# P2C — GoChat 路径与API设计文档

> 版本: v1.1 | 更新日期: 2026-07-09
> 参照: Chatwoot config/routes.rb (327路由) + M1-M12需求文档
> 技术选型: Gin 框架 + RESTful API + WebSocket
> 状态：设计文档，路由已实际落地。当前 972 条注册路由，以 router.go 和 docs/parity/route-parity.md 为权威。

---

## 1. API 总体设计原则

### 1.1 与 Chatwoot 对比

| 特性 | Chatwoot (Rails) | GoChat (Gin) |
|---|---|---|
| 路由数量 | 327 | ~150（精简合并） |
| 命名空间 | 多层namespace嵌套 | 两层分组 /api/v1/:module |
| 响应格式 | 无envelope | `{data: {}, meta: {}}` |
| 分页 | page/per_page | offset/limit |
| 认证 | HTTP headers | Authorization: Bearer |
| 版本 | 硬编码v1 | 路径版本 /api/v1/ |
| 请求方法 | PATCH+PUT | PATCH only |
| 状态码 | 混用 | 严格RESTful |

### 1.2 简化策略

1. **合并冗余路由** — Chatwoot有大量one-off action路由（如 `post :assign`, `post :toggle_status`），GoChat统一为PATCH/PUT更新
2. **去除PATCH/PUT双定义** — Rails习惯同时定义PATCH和PUT，GoChat只用PATCH
3. **统一分页参数** — page/per_page → offset/limit
4. **统一响应格式** — 所有API返回 `{data, meta}` envelope
5. **子资源扁平化** — 如 `/accounts/:id/inboxes` → `/inboxes?account_id=X`（简化路由）
6. **企业版标注** — 🔒标记企业版API端点

---

## 2. 认证与授权 API

### 2.1 Auth 路由

```
POST   /api/v1/auth/login                    # 登录（email+password）
POST   /api/v1/auth/register                 # 注册
POST   /api/v1/auth/refresh                  # Token刷新
POST   /api/v1/auth/logout                   # 登出
POST   /api/v1/auth/switch_account           # 切换账户 🔒
POST   /api/v1/auth/reset_password           # 密码重置请求
PATCH  /api/v1/auth/reset_password/confirm    # 确认密码重置
POST   /api/v1/auth/confirm_email            # 验证邮箱

# OAuth
GET    /api/v1/auth/google/callback           # Google OAuth回调
GET    /api/v1/auth/:provider/callback        # 通用OAuth回调 🔒

# SAML 🔒
GET    /api/v1/auth/saml/:account_id/login    # SAML SP发起登录
POST   /api/v1/auth/saml/:account_id/callback # SAML IdP回调
GET    /api/v1/auth/saml/:account_id/logout   # SAML SLO
GET    /api/v1/auth/saml/:account_id/metadata # SAML SP Metadata

# MFA 🔒
POST   /api/v1/auth/mfa/enable                # 启用TOTP
POST   /api/v1/auth/mfa/verify                # 验证TOTP
DELETE /api/v1/auth/mfa/disable               # 禁用TOTP
```

**对比Chatwoot**: DeviseTokenAuth生成 ~15路由 → GoChat精简为~15但更语义化；OAuth合并多个provider回调为统一格式

---

## 3. 核心业务 API

### 3.1 Accounts

```
GET    /api/v1/accounts                       # 列表（当前用户所属）
POST   /api/v1/accounts                       # 创建
GET    /api/v1/accounts/:id                   # 详情
PATCH  /api/v1/accounts/:id                   # 更新
DELETE /api/v1/accounts/:id                   # 删除

# Account Settings
PATCH  /api/v1/accounts/:id/settings          # 更新设置
GET    /api/v1/accounts/:id/branding          # 获取品牌 🔒
PATCH  /api/v1/accounts/:id/branding          # 更新品牌 🔒

# Account Users
GET    /api/v1/accounts/:id/users             # 成员列表
POST   /api/v1/accounts/:id/users             # 邀请成员
PATCH  /api/v1/accounts/:id/users/:uid        # 更新角色/状态
DELETE /api/v1/accounts/:id/users/:uid        # 移除成员
POST   /api/v1/accounts/:id/users/bulk_action # 批量操作 🔒

# Custom Roles 🔒
GET    /api/v1/accounts/:id/custom_roles
POST   /api/v1/accounts/:id/custom_roles
PATCH  /api/v1/accounts/:id/custom_roles/:rid
DELETE /api/v1/accounts/:id/custom_roles/:rid

# SAML Settings 🔒
GET    /api/v1/accounts/:id/saml_settings
POST   /api/v1/accounts/:id/saml_settings
PATCH  /api/v1/accounts/:id/saml_settings
DELETE /api/v1/accounts/:id/saml_settings

# Feature Flags
GET    /api/v1/accounts/:id/features          # 获取功能开关列表
PATCH  /api/v1/accounts/:id/features/:name    # 开启/关闭功能 🔒
```

### 3.2 Inboxes & Channels

```
GET    /api/v1/inboxes                        # 列表
POST   /api/v1/inboxes                        # 创建
GET    /api/v1/inboxes/:id                    # 详情
PATCH  /api/v1/inboxes/:id                    # 更新
DELETE /api/v1/inboxes/:id                    # 删除

# Inbox Members (Agent绑定)
GET    /api/v1/inboxes/:id/members            # 列表
POST   /api/v1/inboxes/:id/members            # 绑定
DELETE /api/v1/inboxes/:id/members/:uid        # 解绑

# Channel特定API — 创建时按channel_type分发
POST   /api/v1/inboxes/web_widget             # 创建WebWidget Inbox
POST   /api/v1/inboxes/telegram               # 创建Telegram Inbox
POST   /api/v1/inboxes/facebook               # 创建Facebook Inbox 🔒
POST   /api/v1/inboxes/whatsapp               # 创建WhatsApp Inbox 🔒
POST   /api/v1/inboxes/email                  # 创建Email Inbox
POST   /api/v1/inboxes/twilio_sms             # 创建Twilio SMS Inbox 🔒
POST   /api/v1/inboxes/api                    # 创建API Inbox
POST   /api/v1/inboxes/line                   # 创建Line Inbox 🔒
POST   /api/v1/inboxes/instagram              # 创建Instagram Inbox 🔒
POST   /api/v1/inboxes/sms                    # 创建SMS Inbox 🔒
POST   /api/v1/inboxes/tiktok                 # 创建TikTok Inbox 🔒

# Channel更新
PATCH  /api/v1/inboxes/:id/web_widget         # 更新WebWidget配置
PATCH  /api/v1/inboxes/:id/telegram           # 更新Telegram配置
PATCH  /api/v1/inboxes/:id/email              # 更新Email配置
PATCH  /api/v1/inboxes/:id/facebook           # 更新Facebook配置 🔒
PATCH  /api/v1/inboxes/:id/whatsapp           # 更新WhatsApp配置 🔒

# AgentBot
GET    /api/v1/agent_bots                     # 列表
POST   /api/v1/agent_bots                     # 创建
PATCH  /api/v1/agent_bots/:id                 # 更新
DELETE /api/v1/agent_bots/:id                 # 删除

# Inbox Assignment/Capacity 🔒
GET    /api/v1/inboxes/:id/assignment_policy
PATCH  /api/v1/inboxes/:id/assignment_policy
GET    /api/v1/inboxes/:id/capacity_limits
PATCH  /api/v1/inboxes/:id/capacity_limits

# Working Hours 🔒
GET    /api/v1/inboxes/:id/working_hours
PATCH  /api/v1/inboxes/:id/working_hours
```

**对比Chatwoot**: 原路由约40个（含Channels子控制器）→ 合并为 ~30个；Channel创建从多命名空间合并为统一 /inboxes/:type

### 3.3 Conversations

```
GET    /api/v1/conversations                  # 列表（支持filter/status/assignee等）
GET    /api/v1/conversations/:id              # 详情
PATCH  /api/v1/conversations/:id              # 更新（状态/标签/优先级等）
POST   /api/v1/conversations/:id/assign       # 分配给agent/team 🔒
POST   /api/v1/conversations/:id/unassign     # 取消分配
POST   /api/v1/conversations/:id/toggle_status  # 切换状态
POST   /api/v1/conversations/:id/toggle_priority # 切换优先级 🔒
POST   /api/v1/conversations/:id/mute         # 静音
POST   /api/v1/conversations/:id/unmute       # 取消静音
POST   /api/v1/conversations/:id/snooze       # snooze 🔒
POST   /api/v1/conversations/:id/assign_label # 分配标签
POST   /api/v1/conversations/:id/unassign_label # 取消标签

# Messages
GET    /api/v1/conversations/:id/messages     # 消息列表
POST   /api/v1/conversations/:id/messages     # 发送消息
PATCH  /api/v1/conversations/:id/messages/:mid # 更新消息
DELETE /api/v1/conversations/:id/messages/:mid # 删除消息 🔒

# 消息特殊操作
POST   /api/v1/conversations/:id/messages/:mid/translate # 翻译 🔒
POST   /api/v1/conversations/:id/messages/:mid/retry     # 重试发送

# Participants
GET    /api/v1/conversations/:id/participants # 列表
POST   /api/v1/conversations/:id/participants # 添加
DELETE /api/v1/conversations/:id/participants/:uid # 移除

# Unread
GET    /api/v1/conversations/:id/unread_count # 未读数
POST   /api/v1/conversations/:id/update_last_seen # 更新已读

# Typing
POST   /api/v1/conversations/:id/typing       # 打字状态（WebSocket）

# Attachments
POST   /api/v1/conversations/:id/messages/:mid/attachments # 上传附件
DELETE /api/v1/conversations/:id/messages/:mid/attachments/:aid # 删除 🔒

# Direct Upload (大文件)
POST   /api/v1/attachments/direct_upload       # 直传Blob签名URL 🔒

# Draft
GET    /api/v1/conversations/:id/draft         # 获取草稿
POST   /api/v1/conversations/:id/draft         # 保存草稿
DELETE /api/v1/conversations/:id/draft         # 删除草稿
```

**对比**: Chatwoot约50个对话路由 → 精简为 ~30个；toggle_status/toggle_priority合并到PATCH更新

### 3.4 Contacts

```
GET    /api/v1/contacts                       # 列表（filter/search/sort）
POST   /api/v1/contacts                       # 创建
GET    /api/v1/contacts/:id                   # 详情
PATCH  /api/v1/contacts/:id                   # 更新
DELETE /api/v1/contacts/:id                   # 删除
POST   /api/v1/contacts/:id/merge             # 合并 🔒
POST   /api/v1/contacts/search                # 搜索

# Contact Conversations
GET    /api/v1/contacts/:id/conversations     # 对话列表

# Contact Notes
GET    /api/v1/contacts/:id/notes             # 笔记列表
POST   /api/v1/contacts/:id/notes             # 新增笔记
PATCH  /api/v1/contacts/:id/notes/:nid        # 更新
DELETE /api/v1/contacts/:id/notes/:nid        # 删除 🔒

# Contact Labels
GET    /api/v1/contacts/:id/labels             # 标签列表
POST   /api/v1/contacts/:id/labels             # 添加标签
DELETE /api/v1/contacts/:id/labels/:name       # 移除标签

# Custom Attributes
GET    /api/v1/custom_attribute_definitions    # 自定义属性定义列表
POST   /api/v1/custom_attribute_definitions    # 创建
PATCH  /api/v1/custom_attribute_definitions/:id # 更新
DELETE /api/v1/custom_attribute_definitions/:id # 删除

# Custom Filters
GET    /api/v1/custom_filters                  # 过滤器列表
POST   /api/v1/custom_filters                  # 创建
PATCH  /api/v1/custom_filters/:id              # 更新
DELETE /api/v1/custom_filters/:id              # 删除

# Companies 🔒
GET    /api/v1/companies                       # 组织列表
POST   /api/v1/companies                       # 创建
GET    /api/v1/companies/:id                   # 详情
PATCH  /api/v1/companies/:id                   # 更新
DELETE /api/v1/companies/:id                   # 删除
GET    /api/v1/companies/:id/contacts          # 组织成员
```

### 3.5 Teams

```
GET    /api/v1/teams                           # 列表
POST   /api/v1/teams                           # 创建
GET    /api/v1/teams/:id                       # 详情
PATCH  /api/v1/teams/:id                       # 更新
DELETE /api/v1/teams/:id                       # 删除

# Team Members
GET    /api/v1/teams/:id/members               # 成员列表
POST   /api/v1/teams/:id/members               # 添加成员
DELETE /api/v1/teams/:id/members/:uid           # 移除成员

# Assignment Policies 🔒
GET    /api/v1/teams/:id/assignment_policy      # 获取分配策略
PATCH  /api/v1/teams/:id/assignment_policy      # 更新分配策略
```

### 3.6 Automation & Templates

```
# Automation Rules
GET    /api/v1/automation_rules                # 列表
POST   /api/v1/automation_rules                # 创建
PATCH  /api/v1/automation_rules/:id            # 更新
DELETE /api/v1/automation_rules/:id            # 删除
POST   /api/v1/automation_rules/:id/clone      # 克隆 🔒

# Macros 🔒
GET    /api/v1/macros                           # 列表
POST   /api/v1/macros                           # 创建
PATCH  /api/v1/macros/:id                       # 更新
DELETE /api/v1/macros/:id                       # 删除
POST   /api/v1/conversations/:id/macros/:mid/execute # 执行宏

# Canned Responses
GET    /api/v1/canned_responses                # 列表
POST   /api/v1/canned_responses                # 创建
PATCH  /api/v1/canned_responses/:id            # 更新
DELETE /api/v1/canned_responses/:id            # 删除
```

### 3.7 Reporting & CSAT

```
# Reports
GET    /api/v1/reports                          # 报告数据（按type/metric/date）
GET    /api/v1/reports/summary                  # 汇总报告
GET    /api/v1/reports/timeseries               # 时间序列
GET    /api/v1/reports/agents                   # 坐席报告
GET    /api/v1/reports/inboxes                  # Inbox报告
GET    /api/v1/reports/teams                    # 团队报告 🔒
GET    /api/v1/reports/labels                   # 标签报告 🔒

# CSAT
GET    /api/v1/csat_responses                   # CSAT响应列表
POST   /api/v1/csat_responses                   # 提交CSAT（public API）

# CSAT Templates 🔒 (WhatsApp/Twilio)
GET    /api/v1/inboxes/:id/csat_templates       # CSAT模板列表
POST   /api/v1/inboxes/:id/csat_templates       # 创建CSAT模板
PATCH  /api/v1/inboxes/:id/csat_templates/:tid  # 更新

# Campaigns
GET    /api/v1/campaigns                        # 列表
POST   /api/v1/campaigns                        # 创建
GET    /api/v1/campaigns/:id                    # 详情
PATCH  /api/v1/campaigns/:id                    # 更新
DELETE /api/v1/campaigns/:id                    # 删除
```

### 3.8 Notifications

```
GET    /api/v1/notifications                    # 通知列表
PATCH  /api/v1/notifications/:id                # 标记已读
POST   /api/v1/notifications/read_all           # 全部已读
DELETE /api/v1/notifications/:id                # 删除

# Notification Settings
GET    /api/v1/notification_settings            # 设置列表
PATCH  /api/v1/notification_settings/:id        # 更新设置

# Notification Subscriptions
GET    /api/v1/notification_subscriptions        # 订阅列表
POST   /api/v1/notification_subscriptions        # 创建订阅
DELETE /api/v1/notification_subscriptions/:id    # 删除订阅

# Webhooks
GET    /api/v1/webhooks                         # 刘表
POST   /api/v1/webhooks                         # 创建
PATCH  /api/v1/webhooks/:id                     # 更新
DELETE /api/v1/webhooks/:id                     # 删除

# Integration Hooks
GET    /api/v1/integration_hooks                 # 列表
POST   /api/v1/integration_hooks                 # 创建
PATCH  /api/v1/integration_hooks/:id             # 更新
DELETE /api/v1/integration_hooks/:id             # 删除
DELETE /api/v1/integration_hooks/:id/process     # 删除process 🔒
```

### 3.9 Knowledge Base / Help Center

```
# Portals
GET    /api/v1/portals                          # 列表
POST   /api/v1/portals                          # 创建
GET    /api/v1/portals/:id                      # 详情
PATCH  /api/v1/portals/:id                      # 更新
DELETE /api/v1/portals/:id                      # 删除

# Portal Members
GET    /api/v1/portals/:id/members              # 成员列表
POST   /api/v1/portals/:id/members              # 添加成员
DELETE /api/v1/portals/:id/members/:uid          # 移除成员

# Categories
GET    /api/v1/portals/:id/categories           # 列表
POST   /api/v1/portals/:id/categories           # 创建
GET    /api/v1/portals/:id/categories/:cid       # 详情
PATCH  /api/v1/portals/:id/categories/:cid       # 更新
DELETE /api/v1/portals/:id/categories/:cid       # 删除

# Articles
GET    /api/v1/portals/:id/articles             # 列表
POST   /api/v1/portals/:id/articles             # 创建
GET    /api/v1/portals/:id/articles/:aid         # 详情
PATCH  /api/v1/portals/:id/articles/:aid         # 更新
DELETE /api/v1/portals/:id/articles/:aid         # 删除

# Article Search (public)
GET    /public/v1/portals/:slug/articles/search  # 公开搜索
GET    /public/v1/portals/:slug/articles/:slug   # 公开查看文章
GET    /public/v1/portals/:slug/categories/:slug # 公开查看分类

# Folders 🔒
GET    /api/v1/portals/:id/folders               # 列表
POST   /api/v1/portals/:id/folders               # 创建
```

### 3.10 Captain AI & Copilot 🔒

```
# Captain Assistants
GET    /api/v1/captain/assistants               # 列表
POST   /api/v1/captain/assistants               # 创建
GET    /api/v1/captain/assistants/:id           # 详情
PATCH  /api/v1/captain/assistants/:id           # 更新
DELETE /api/v1/captain/assistants/:id           # 删除

# Captain Documents
GET    /api/v1/captain/assistants/:id/documents # 文档列表
POST   /api/v1/captain/assistants/:id/documents # 上传文档
PATCH  /api/v1/captain/assistants/:id/documents/:did # 更新
DELETE /api/v1/captain/assistants/:id/documents/:did # 删除

# Captain Scenarios
GET    /api/v1/captain/assistants/:id/scenarios # 场景列表
POST   /api/v1/captain/assistants/:id/scenarios # 创建场景
PATCH  /api/v1/captain/assistants/:id/scenarios/:sid # 更新
DELETE /api/v1/captain/assistants/:id/scenarios/:sid # 删除

# Captain Inboxes
POST   /api/v1/captain/assistants/:id/inboxes   # 绑定Inbox
DELETE /api/v1/captain/assistants/:id/inboxes/:iid # 解绑

# Captain Playground (测试)
POST   /api/v1/captain/assistants/:id/playground # 对话测试

# Captain Custom Tools 🔒
GET    /api/v1/captain/custom_tools              # 自定义工具列表
POST   /api/v1/captain/custom_tools              # 创建
PATCH  /api/v1/captain/custom_tools/:id          # 更新
DELETE /api/v1/captain/custom_tools/:id          # 删除

# Copilot
GET    /api/v1/copilot/threads                   # Copilot线程列表
POST   /api/v1/copilot/threads                   # 创建线程
GET    /api/v1/copilot/threads/:id/messages      # 线程消息列表
POST   /api/v1/copilot/threads/:id/messages      # 发送消息
POST   /api/v1/copilot/suggest_reply             # 建议回复
POST   /api/v1/copilot/summarize                 # 摘要对话
POST   /api/v1/copilot/rewrite                   # 重写消息
```

### 3.11 Enterprise 🔒

```
# SLA Policies 🔒
GET    /api/v1/sla_policies                     # 列表
POST   /api/v1/sla_policies                     # 创建
GET    /api/v1/sla_policies/:id                 # 详情
PATCH  /api/v1/sla_policies/:id                 # 更新
DELETE /api/v1/sla_policies/:id                 # 删除

# Audit Log 🔒
GET    /api/v1/audits                           # 审计日志列表
GET    /api/v1/audits/:id                       # 详情

# Agent Capacity 🔒
GET    /api/v1/agent_capacity_policies           # 容量策略列表
POST   /api/v1/agent_capacity_policies           # 创建
PATCH  /api/v1/agent_capacity_policies/:id       # 更新
DELETE /api/v1/agent_capacity_policies/:id       # 删除

# Calls 🔒
POST   /api/v1/conversations/:id/calls/initiate  # 发起通话
PATCH  /api/v1/conversations/:id/calls/:cid       # 更新通话状态
```

### 3.12 Platform & Integration

```
# Profile (当前用户)
GET    /api/v1/profile                          # 获取Profile
PATCH  /api/v1/profile                          # 更新Profile
POST   /api/v1/profile/avatar                   # 上传头像
DELETE /api/v1/profile/avatar                   # 删除头像

# Platform Apps 🔒
GET    /api/v1/platform_apps                    # 列表
POST   /api/v1/platform_apps                    # 创建
GET    /api/v1/platform_apps/:id                # 详情
PATCH  /api/v1/platform_apps/:id                # 更新
DELETE /api/v1/platform_apps/:id                # 删除

# Access Tokens
POST   /api/v1/access_tokens                    # 创建token
DELETE /api/v1/access_tokens/:id                # 删除token

# Data Import 🔒
POST   /api/v1/data_imports                     # 创建导入
GET    /api/v1/data_imports/:id                 # 导入状态

# Installation Config (SuperAdmin)
GET    /api/v1/installation_configs             # 配置列表 🔒
PATCH  /api/v1/installation_configs/:id         # 更新配置 🔒

# Dashboard Apps 🔒
GET    /api/v1/dashboard_apps                   # 列表
POST   /api/v1/dashboard_apps                   # 创建
PATCH  /api/v1/dashboard_apps/:id               # 更新
DELETE /api/v1/dashboard_apps/:id               # 删除
```

---

## 4. Webhook 回调路由（渠道入站）

这些路由由各渠道平台回调，**不需要JWT认证**：

```
# Web Widget
POST   /web_widget/:website_token/inbound       # WebWidget消息入站

# Telegram
POST   /telegram/:bot_token/webhook              # Telegram Bot回调

# Facebook
POST   /facebook/:page_id/webhook               # Facebook Page回调
GET    /facebook/:page_id/webhook                # Facebook验证回调

# WhatsApp
POST   /whatsapp/:phone_number/webhook          # WhatsApp Cloud API回调
POST   /whatsapp/:phone_number/callback         # 360dialog回调

# Twilio
POST   /twilio/:phone_number/webhook            # Twilio SMS/WhatsApp回调

# Email
# IMAP polling (内部定时任务，无API路由)

# Instagram 🔒
POST   /instagram/:account_id/webhook           # Instagram回调
GET    /instagram/:account_id/webhook            # Instagram验证

# Line 🔒
POST   /line/:channel_id/webhook                # Line回调

# SMS 🔒
POST   /sms/:phone_number/webhook               # SMS Bandwidth回调

# TikTok 🔒
POST   /tiktok/:account_id/webhook              # TikTok回调
```

---

## 5. Public API (无认证)

```
# CSAT Survey
POST   /public/v1/csat/:conversation_uuid       # 提交CSAT评分

# Help Center Portal
GET    /public/v1/portals/:slug                  # Portal首页
GET    /public/v1/portals/:slug/categories       # 分类列表
GET    /public/v1/portals/:slug/categories/:slug # 分类详情
GET    /public/v1/portals/:slug/articles         # 文章列表
GET    /public/v1/portals/:slug/articles/:slug   # 文章详情
GET    /public/v1/portals/:slug/articles/search  # 文章搜索

# Web Widget Embed
GET    /widget/:website_token                    # Widget配置（JS嵌入）
POST   /widget/:website_token/contact            # Widget联系人创建
GET    /widget/:website_token/conversation       # Widget对话获取
POST   /widget/:website_token/conversation/messages # Widget消息发送
```

---

## 6. WebSocket 端点

```
GET    /cable                                   # WebSocket连接（JWT认证）
  - 订阅: account:{id}                           # 账户级事件
  - 订阅: conversation:{id}                      # 对话级事件
  - 订阅: inbox:{id}                             # Inbox级事件
  - 订阅: user:{id}                              # 用户级事件
  - 订阅: copilot:{user_id}:{conv_id}            # Copilot事件 🔒
```

**对比Chatwoot**: ActionCable多Channel订阅 → GoChat简化为topic订阅模型

---

## 7. 统一响应格式

### 7.1 单资源

```json
{
  "data": {
    "id": 1,
    "name": "Acme Inc",
    ...
  }
}
```

### 7.2 列表（含分页）

```json
{
  "data": [
    {"id": 1, "name": "..."},
    {"id": 2, "name": "..."}
  ],
  "meta": {
    "count": 42,
    "offset": 0,
    "limit": 25,
    "total": 150
  }
}
```

### 7.3 错误

```json
{
  "error": "unauthorized",
  "message": "You are not authorized to perform this action",
  "code": 403
}
```

---

## 8. 分页与过滤统一设计

### 8.1 分页参数

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| offset | int | 0 | 偏移量 |
| limit | int | 25 | 每页数量(max=100) |

### 8.2 过滤参数

| 参数 | 适用资源 | 说明 |
|---|---|---|
| status | conversations | open/resolved/pending/snoozed |
| assignee_id | conversations | 按坐席过滤 |
| team_id | conversations | 按团队过滤 |
| inbox_id | conversations,contacts | 按Inbox过滤 |
| label | conversations | 按标签过滤 |
| sort | conversations,contacts | created_at/last_message_at |
| q | contacts,articles | 搜索关键词 |
| type | inboxes | 渠道类型过滤 |

### 8.3 日期范围

所有报告API支持 `since` + `until` 参数（ISO8601格式）

---

## 9. 路由数量对比

| 模块 | Chatwoot路由 | GoChat路由 | 简化比例 |
|---|---|---|---|
| Auth | ~15 | 15 | 1:1 |
| Accounts | ~25 | ~20 | -20% |
| Inboxes/Channels | ~40 | ~30 | -25% |
| Conversations | ~50 | ~30 | -40% |
| Contacts | ~25 | ~20 | -20% |
| Teams | ~10 | 8 | -20% |
| Automation | ~15 | 10 | -33% |
| Reporting | ~20 | 15 | -25% |
| Notifications | ~15 | 12 | -20% |
| Knowledge Base | ~20 | 15 | -25% |
| Captain 🔒 | ~20 | 15 | -25% |
| Enterprise 🔒 | ~15 | 10 | -33% |
| Platform | ~15 | 10 | -33% |
| Public | ~15 | 10 | -33% |
| Webhooks | ~15 | 12 | -20% |
| **合计** | **~327** | **~150** | **-54%** |

主要简化来源：
1. PATCH+PUT合并为PATCH（-30路由）
2. one-off action路由合并到PATCH更新（-40路由）
3. 子资源扁平化（-20路由）
4. 冗余索引/show路由合并（-20路由）

---

> 🔒 = 企业版API端点
> **P2架构设计全部完成！**