rogee/gochat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0dabb8cfa540dcffc34efea481d9f96f265f4e1f
gochat/docs/product/05-design-routing-and-api.md
T
rogee 0dabb8cfa5 docs: 整理文档目录结构 — 清理过时文档、归集功能子目录、统一命名规范 
清理:
- 删除 34 份过时文档（gap reports/QA临时报告/验收报告/阶段性文档）
- 删除 docs/.hermes/skills 第三方 skills 副本（16 文件）
- 删除 skills-lock.json

目录归集:
- 根目录仅保留 README.md 索引
- product/ — 产品与架构设计（PRD + ARCHITECTURE + P2设计文档 + AI/企业路线图）
- tracking/ — Chatwoot parity 开发跟踪
- requirements/ — M01-M12 模块需求
- plans/ — 历史实现计划
- parity/ — 路由 parity 与前端契约
- qa/ — QA 报告与测试计划
- ops/ — 运维部署

命名规范:
- 全小写 kebab-case，禁止全大写文件名
- product/tracking/ops 用 NN- 序号前缀
- requirements 用 MNN- 两位零填充模块号
- plans/qa 用 YYYY-MM-DD- 日期前缀
- requirements M1-M9 零填充为 M01-M09（修复字典序）

同步更新:
- backend/cmd/route_parity/main.go 路径默认值
- backend/scripts/parity_frontend_smoke.sh 报告路径
- 所有 docs 内部交叉引用
- .gitignore 排除编译产物 (backend/gochat, backend/route_parity)
- 新增迁移 000052/000053
- 前端 WS 相关修改
2026-07-09 14:53:27 +08:00

691 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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架构设计全部完成！**
Reference in New Issue View Git Blame Copy Permalink