# GoChat 技术架构设计文档

> 版本: v2.0 | 日期: 2026-05-25 | 作者: CTO
> 项目定位: Go 语言 1:1 重写 Chatwoot（开源多渠道客服平台）
> 技术栈: Go 1.24 + Gin + GORM + PostgreSQL + Redis + WebSocket

---

## 1. 项目概况

| 指标 | 数值 |
|------|------|
| Go 源码文件 | 418 |
| 测试文件 | 104 |
| 测试代码行 | 33,711 |
| 总代码行 | 90,422 |
| 数据库表 | 33 |
| API 路由 | 106 |
| Go 包 | 42 |
| 内部模块 | 26 |

GoChat 是一个开源企业级多渠道客服平台，以 Go 语言重写 Chatwoot 核心功能。系统采用单体架构 + 模块化设计，按业务域分包（domain-driven），通过接口解耦各模块，渠道通过插件接口注册以保证扩展性。

---

## 2. 项目目录结构

```
gochat/
├── cmd/                           # 应用入口
│   ├── gochat/                    # 主HTTP服务器入口
│   │   └── main.go               # Gin server 启动
│   ├── migrate/                   # 数据库迁移独立工具
│   │   └── main.go
│   └── test_debug/                # 测试调试辅助工具
│
├── configs/                        # Viper 配置文件
│   ├── default.yaml               # 默认配置基线
│   ├── development.yaml           # 开发环境覆盖
│   ├── production.yaml            # 生产环境覆盖
│   └── test.yaml                  # 测试环境覆盖
│
├── internal/                       # 核心业务代码（Go不可外部引用）
│   ├── app/                        # 应用生命周期
│   │   ├── app.go                 # App 结构体（持有所有依赖）
│   │   ├── bootstrap.go           # 依赖注入编排（12步启动序列）
│   │   ├── database.go            # PostgreSQL 连接池管理
│   │   ├── redis.go               # Redis 连接 + PubSub
│   │   ├── shutdown.go            # graceful shutdown 信号处理
│   │
│   ├── config/                     # 配置管理
│   │   ├── config.go              # Config 结构体（Server/DB/Redis/JWT/Captain/OAuth/SAML/Push/Webhook）
│   │   ├── reloader.go            # fsnotify 热加载（11字段无需重启）
│   │
│   ├── auth/                       # 认证授权
│   │   ├── jwt.go                 # JWT 签发/验证（access + refresh 双令牌）
│   │   ├── refresh_store.go       # Refresh Token Redis 存储
│   │   ├── oauth.go               # OAuth2 (Google/GitHub) 回调处理
│   │   ├── mfa.go                 # TOTP MFA 启用/验证/禁用
│   │   ├── saml.go                # SAML 2.0 SP 发起/IdP 回调
│   │   ├── permission.go          # RBAC 权限矩阵（角色→权限映射）
│   │   ├── policy.go              # Pundit-style 策略引擎
│   │   ├── platform_auth.go       # Platform API Key 认证
│   │   ├── webhook_registry.go    # Webhook Token 注册表
│   │
│   ├── middleware/                  # Gin 中间件链
│   │   ├── auth.go                # AuthMiddleware (JWT Bearer)
│   │   ├── cors.go                # CORS (通配符子域名支持)
│   │   ├── ratelimit.go           # 速率限制 (Redis滑动窗口)
│   │   ├── account_scope.go       # AccountScope (账号上下文注入)
│   │   ├── super_admin.go         # SuperAdmin (超级管理员守卫)
│   │   ├── security_headers.go    # 安全响应头
│   │   ├── webhook_auth.go        # WebhookAuth (渠道回调认证)
│   │   ├── recovery.go            # panic 恢复
│   │   ├── request_logger.go      # 结构化请求日志
│   │
│   ├── model/                      # GORM 数据模型层
│   │   ├── base.go                # BaseModel (ID/CreatedAt/UpdatedAt/DeletedAt)
│   │   ├── account.go             # Account 模型
│   │   ├── user.go                # User + AccountUser 模型
│   │   ├── contact.go             # Contact + ContactInbox 模型
│   │   ├── inbox.go               # Inbox + InboxMember 模型
│   │   ├── conversation.go        # Conversation 模型
│   │   ├── message.go             # Message + Attachment 模型
│   │   ├── notification.go        # Notification + NotificationPreference 模型
│   │   ├── platform_app.go        # PlatformApp 模型
│   │   ├── captain.go             # Captain Assistant/Document/Scenario/CustomTool/Response
│   │   ├── copilot.go             # Copilot Thread/Message 模型
│   │   ├── team.go                # Team + TeamMember 模型
│   │   ├── reporting.go           # ReportingEvent/Rollup 模型
│   │   ├── dashboard_app.go       # DashboardApp 模型
│   │   ├── portal.go              # Portal (Help Center) 模型
│   │   ├── category.go            # Category 模型
│   │   ├── article.go             # Article 模型
│   │   ├── folder.go              # Folder 模型
│   │   ├── channel.go             # Channel 配置子类型模型
│   │
│   ├── repository/                  # 数据访问层（21+ Repo）
│   │   ├── account_repo.go        # Account CRUD + 软删除
│   │   ├── user_repo.go           # User CRUD + 关联查询
│   │   ├── contact_repo.go        # Contact CRUD + 搜索
│   │   ├── contact_inbox_repo.go  # ContactInbox 关联
│   │   ├── conversation_repo.go   # Conversation CRUD + 状态/标签/优先级
│   │   ├── inbox_repo.go          # Inbox CRUD + 成员管理
│   │   ├── inbox_member_repo.go   # InboxMember 座席分配
│   │   ├── message_repo.go        # Message CRUD + 附件
│   │   ├── notification_repo.go   # Notification CRUD + 未读计数
│   │   ├── notification_pref_repo.go  # 通知偏好设置
│   │   ├── push_token_repo.go     # Push 设备令牌
│   │   ├── webhook_sub_repo.go    # Webhook 事件订阅
│   │   ├── team_repo.go           # Team CRUD
│   │   ├── team_member_repo.go    # TeamMember CRUD
│   │   ├── captain_*_repo.go      # Captain 6 repos
│   │   ├── copilot_*_repo.go      # Copilot 2 repos
│   │   ├── reporting_*_repo.go    # Reporting 2 repos
│   │   ├── dashboard_app_repo.go  # DashboardApp CRUD
│   │   ├── platform_app_repo.go   # PlatformApp CRUD + API Key
│   │   ├── portal_*_repo.go       # Help Center 5 repos
│   │
│   ├── service/                     # 业务逻辑层
│   │   ├── auth_service.go        # 登录/注册/刷新/切换账号
│   │   ├── account_service.go     # Account 管理 + 成员增删
│   │   ├── contact_service.go     # Contact 管理 + 搜索
│   │   ├── conversation_service.go # Conversation CRUD + 状态流转 + Agent分配
│   │   ├── inbox_service.go       # Inbox CRUD + 渠道配置
│   │   ├── inbox_member_service.go # 座席分配/移除
│   │   ├── message_service.go     # 消息收发 + 附件处理
│   │   ├── notification_service.go # 通知管理 + 未读计数
│   │   ├── notification_delivery_service.go # 通知推送管道(Push/Webhook/Email)
│   │   ├── push_subscription_service.go # Push 设令牌管理
│   │   ├── push_delivery_service.go  # Web Push 发送 (VAPID)
│   │   ├── webhook_subscription_service.go # Webhook 订阅管理
│   │   ├── webhook_delivery_service.go    # Webhook 事件投递 + 签名
│   │   ├── profile_service.go     # 用户个人信息更新
│   │   ├── team_service.go        # Team CRUD + 成员管理
│   │   ├── captain_*_service.go   # Captain AI 5 services
│   │   ├── copilot_service.go     # Copilot Thread + AI建议/摘要/翻译
│   │   ├── analytics_service.go   # 报表聚合 + 指标计算
│   │   ├── dashboard_app_service.go # 自定义Dashboard + Widget管理
│   │   ├── platform_app_service.go # Platform App 管理 + API Key
│   │   ├── portal_*_service.go    # Help Center 5 services
│   │   ├── autoassignment/         # 智能分配服务
│   │   │   ├── service.go         # RoundRobin + 负载均衡分配
│   │   │   ├── rate_limiter.go    # 分配速率限制
│   │   │   ├── listener.go        # EventBus 事件监听
│   │
│   ├── automation/                   # 自动化引擎
│   │   ├── model.go               # AutomationRule + Macro + CsatSurvey 模型
│   │   ├── service.go              # AutomationRuleService
│   │   ├── action_service.go       # 规则动作执行引擎
│   │   ├── condition_filter.go     # 条件过滤器
│   │   ├── condition_validator.go  # 条件验证器
│   │   ├── macro_service.go        # Macro CRUD + 执行
│   │   ├── csat_survey_service.go  # CSAT 满意度调查
│   │   ├── *_listener.go           # 多个EventBus监听器
│   │
│   ├── channel/                      # 渠道抽象层
│   │   ├── provider.go             # Provider 接口定义（注册表模式）
│   │   ├── dispatcher.go           # 事件分发器（注册Listener）
│   │   ├── broker.go               # 消息中转器（进出分流）
│   │   ├── incoming.go             # IncomingMessageHandler 接口
│   │   ├── outgoing.go             # OutgoingMessageHandler 接口
│   │   ├── lifecycle.go            # 渠道生命周期管理
│   │   ├── config.go               # 渠道配置结构
│   │   ├── event.go                # 渠道事件类型定义
│   │   ├── listener.go             # Listener 接口
│   │   ├── facebook/               # Facebook + Instagram 渠道
│   │   │   ├── provider.go         # FacebookProvider (Meta API)
│   │   │   ├── instagram_provider.go # InstagramProvider
│   │   │   ├── listener.go         # FacebookEventListener + InstagramEventListener
│   │   │   ├── service.go          # FacebookService (消息/媒体处理)
│   │   │   ├── repository.go       # FacebookRepository (DB访问)
│   │   │   ├── pipeline.go         # 消息处理管道
│   │   │   ├── media.go            # 媒体下载/上传
│   │   │   ├── user_mapping.go     # FB用户→Contact映射
│   │   │   ├── webhook_handler.go  # HTTP webhook 处理
│   │   │   ├── types.go            # FB消息/事件类型
│   │   ├── telegram/               # Telegram 渠道
│   │   │   ├── provider.go         # TelegramProvider (Bot API)
│   │   │   ├── webhook_handler.go  # Telegram webhook HTTP处理
│   │   │   ├── service.go          # TelegramService
│   │   │   ├── repository.go       # TelegramRepository
│   │   │   ├── pipeline.go         # 消息处理管道
│   │   │   ├── types.go            # TG消息/事件类型
│   │   ├── whatsapp/               # WhatsApp 渠道
│   │   │   ├── provider.go         # WhatsAppProvider (Business API)
│   │   │   ├── service.go          # WhatsAppService
│   │   │   ├── repository.go       # WhatsAppRepository
│   │   │   ├── pipeline.go         # 消息处理管道
│   │   │   ├── types.go            # WA消息/事件类型
│   │   ├── email/                  # Email 渠道
│   │   │   ├── imap_listener.go    # IMAP 收信监听
│   │   │   ├── smtp_sender.go      # SMTP 发信
│   │   │   ├── service.go          # EmailService
│   │   │   ├── repository.go       # EmailRepository
│   │   │   ├── pipeline.go         # 邮件处理管道
│   │   │   ├── webhook_handler.go  # Email webhook HTTP处理
│   │   │   ├── types.go            # Email消息类型
│   │   │   ├── provider/           # Provider 注册桥接
│   │   │   │   ├── facebook.go     # FB Provider → channel.Register
│   │   │   │   ├── telegram.go     # TG Provider → channel.Register
│   │   │   │   ├── whatsapp.go     # WA Provider → channel.Register
│   │   │   │   ├── email.go        # Email Provider → channel.Register
│   │   │   │   ├── web_widget.go   # WebWidget Provider → channel.Register
│   │
│   ├── handler/                      # HTTP 处理层
│   │   ├── api/v1/                 # API v1 Handlers (49文件)
│   │   │   ├── auth_handler.go     # Auth: login/register/refresh/logout
│   │   │   ├── mfa_handler.go      # MFA: enable/verify/disable
│   │   │   ├── saml_handler.go     # SAML: SP发起/IdP回调/metadata
│   │   │   ├── account_handler.go  # Account CRUD + 成员 + 设置
│   │   │   ├── contact_handler.go  # Contact CRUD + 搜索
│   │   │   ├── conversation_handler.go # Conversation CRUD + 状态/标签/优先级
│   │   │   ├── inbox_handler.go    # Inbox CRUD
│   │   │   ├── inbox_member_handler.go # 座席分配
│   │   │   ├── message_handler.go  # Message CRUD + retry
│   │   │   ├── profile_handler.go  # Profile GET/PUT/avatar
│   │   │   ├── notification_handler.go # 通知管理
│   │   │   ├── platform_app_handler.go # Platform App CRUD + API Key
│   │   │   ├── team_handler.go     # Team CRUD + 成员
│   │   │   ├── captain_*_handler.go # Captain AI 4 handlers
│   │   │   ├── copilot_handler.go  # Copilot Thread + AI动作
│   │   │   ├── analytics_handler.go # 报表/指标
│   │   │   ├── live_report_handler.go # 实时报表
│   │   │   ├── dashboard_app_handler.go # Dashboard + Widget
│   │   │   ├── portal_handler.go   # Help Center Portal
│   │   │   ├── category_handler.go # Help Center 分类
│   │   │   ├── article_handler.go  # Help Center 文章
│   │   │   ├── folder_handler.go   # Help Center 文件夹
│   │   │   ├── portal_member_handler.go # Portal 成员
│   │   │   ├── automation_rule_handler.go # 自动化规则
│   │   │   ├── macro_handler.go    # Macro CRUD + execute
│   │   │   ├── csat_survey_handler.go # CSAT 满意度调查
│   │   │   ├── push_subscription_handler.go # Push 设备管理
│   │   │   ├── webhook_subscription_handler.go # Webhook 管理
│   │   │   ├── web_widget_handler.go # WebWidget 配置/CRUD
│   │   │   ├── *_routes.go         # 各模块路由注册函数
│   │   ├── webhook/                # 渠道 Webhook Handler
│   │   │   ├── facebook_webhook_handler.go # FB/IG webhook
│   │   │   ├── telegram_webhook_handler.go # TG webhook
│   │   ├── ws/                     # WebSocket Handler
│   │   │   ├── handler.go          # WS升级 + 消息分发
│   │
│   ├── router/                       # 路由注册中心
│   │   ├── router.go               # RegisterRoutes（106路由注册）
│   │
│   ├── ws/                           # WebSocket 核心层
│   │   ├── hub.go                   # Hub (连接池管理 + 广播)
│   │   ├── auth.go                  # WSAuthenticator (JWT + pubsub_token)
│   │   ├── broadcast.go             # 事件广播分发
│   │   ├── presence.go              # 在线状态追踪
│   │   ├── typing.go                # 输入状态推送
│   │   ├── heartbeat.go             # 心跳保活
│   │   ├── event_types.go           # WS事件类型定义
│   │
│   ├── pubsub/                       # 事件总线
│   │   ├── pubsub.go               # PubSub 接口定义
│   │   ├── redis_pubsub.go         # Redis Pub/Sub (watermill-redisstream)
│   │   ├── event_bus.go            # EventBus (topic发布/订阅)
│   │
│   ├── llm/                          # LLM Provider层
│   │   ├── provider.go             # LLMProvider 接口
│   │   ├── openai_provider.go      # OpenAI/volcengine/Ollama 统一适配
│   │
│   ├── dispatch/                     # 事件分发
│   │   ├── dispatcher.go           # Dispatcher (事件→Listener路由)
│   │   ├── event.go                # 事件类型定义
│   │   ├── listener_registry.go    # Listener 注册表
│   │
│   ├── worker/                       # 后台任务
│   │   ├── worker.go               # Worker池 (goroutine并发)
│   │
│   ├── security/                     # 安全模块
│   │   ├── encryption.go           # 加密/解密
│   │   ├── jwt_security.go         # JWT 安全检查
│   │   ├── sql_safety.go           # SQL 注入防护
│   │   ├── ssrf_protection.go      # SSRF 防护
│   │   ├── webhook_signing.go      # Webhook HMAC签名
│   │
│   ├── database/                     # 数据库管理
│   │   ├── migrate.go              # golang-migrate 迁移执行
│   │
│   ├── autoassignment/               # 智能分配
│   ├── campaign/                     # 营销活动
│   ├── canned/                       # 快捷回复
│   ├── csat/                         # CSAT 模型
│   ├── goimap_stub/                  # IMAP 客户端桩
│   ├── pgvector_stub/                # pgvector 桩
│   ├── database/                     # DB 迁移管理
│
├── pkg/                              # 可外部引用的公共工具包
│   ├── crypto/                       # bcrypt Hash/Check
│   ├── logger/                       # zap 结构化日志封装
│   ├── pagination/                   # offset/limit 分页器
│   ├── response/                     # {data, meta} 统一响应格式
│   ├── validator/                    # go-playground/validator/v10 自定义规则
│   ├── testutil/                     # 测试辅助工具
│
├── migrations/                        # SQL 迁移文件（golang-migrate）
│   ├── 000001_init_schema.up.sql     # 核心表（22表）
│   ├── 000002_add_captain_ai_tables.up.sql # Captain AI 表（8表）
│   ├── 000003_add_rate_limit_state.up.sql  # Rate Limit 表（1表）
│   ├── 000004_add_saml_config_tables.up.sql # SAML 表（2表）
│   ├── 000005_add_dashboard_apps_table.up.sql # Dashboard App 表（1表）
│   + 对应 down.sql 回滚文件
│
├── deploy/                            # 部署配置
│   ├── k8s/                          # Kubernetes manifests
│   ├── docker/                       # Docker 相关
│
├── tests/                             # 测试目录
│   ├── e2e/                          # 端到端测试
│   │   ├── auth_e2e_test.go         # 认证流程
│   │   ├── account_e2e_test.go      # Account CRUD
│   │   ├── conversation_e2e_test.go # 会话流程
│   │   ├── crm_e2e_test.go          # CRM 流程
│   │   ├── rbac_e2e_test.go         # RBAC 流程
│   │   ├── dashboard_app_e2e_test.go # Dashboard 流程
│   │   ├── channel_incoming_e2e_test.go # 渠道流入
│   │   ├── middleware_e2e_test.go   # 中间件测试
│   ├── helpers/                      # 测试辅助
│   │   ├── pg_helper.go             # PostgreSQL 测试连接
│
├── scripts/                           # 脚本
│   ├── coverage/                     # 覆盖率报告
│
├── docker-compose.yml                 # 主 compose
├── docker-compose.dev.yml             # 开发 compose
├── docker-compose.prod.yml            # 生产 compose
├── docker-compose.test.yml            # 测试 compose
├── Dockerfile                         # 生产镜像构建
├── Dockerfile.dev                     # 开发镜像
├── .env.example                       # 环境变量模板
├── Makefile                           # 构建/测试/迁移命令
├── go.mod                             # Go 模块定义
├── go.sum                             # 依赖锁定
├── .air.toml                          # Air 热重载配置
```

---

## 3. 模块划分

### 3.1 分层架构总览

GoChat 采用 **四层分层架构**，各层职责明确，通过接口解耦：

```
┌──────────────────────────────────────────────────────┐
│                    Handler (HTTP层)                    │
│  Gin Handler → 参数校验 → 调用Service → 统一响应格式     │
├──────────────────────────────────────────────────────┤
│                    Service (业务层)                     │
│  业务逻辑编排 → 跨Repo事务 → EventBus事件发布            │
├──────────────────────────────────────────────────────┤
│                    Repository (数据层)                  │
│  GORM查询封装 → 软删除 → 分页 → 条件过滤                │
├──────────────────────────────────────────────────────┤
│                    Model (模型层)                       │
│  GORM结构体 → 表映射 → 关联定义 → 验证标签               │
├──────────────────────────────────────────────────────┤
│                    Database (基础设施)                  │
│  PostgreSQL连接池 → Redis PubSub → Migrations           │
└──────────────────────────────────────────────────────┘
```

### 3.2 模块分组与职责

| 分组 | 模块 | 职责 | 关键文件 |
|------|------|------|---------|
| **应用生命周期** | app | 启动编排、graceful shutdown | bootstrap.go, app.go, shutdown.go |
| **配置管理** | config | Viper多环境叠加、热加载 | config.go, reloader.go |
| **认证授权** | auth | JWT、OAuth、MFA、SAML、RBAC | jwt.go, oauth.go, mfa.go, saml.go, permission.go |
| **HTTP中间件** | middleware | Auth、CORS、RateLimit、AccountScope、SecurityHeaders | auth.go, cors.go, ratelimit.go |
| **数据模型** | model | GORM结构体定义、表映射 | base.go, account.go, user.go, conversation.go |
| **数据访问** | repository | CRUD封装、软删除、分页 | 21+ repo文件 |
| **业务逻辑** | service | 业务编排、事务、事件发布 | 20+ service文件 |
| **HTTP处理** | handler/api/v1 | 参数校验、响应格式化 | 49 handler文件 |
| **路由注册** | router | 路由编排、中间件分组 | router.go |
| **渠道抽象** | channel | Provider接口、Dispatcher、进/出消息 | provider.go, dispatcher.go |
| **渠道实现** | channel/facebook,telegram,whatsapp,email | 各渠道Provider+Service+Repo+Pipeline | 各子包 |
| **WebSocket** | ws | Hub、认证、广播、状态、输入 | hub.go, auth.go, broadcast.go |
| **事件总线** | pubsub | Redis Pub/Sub + EventBus | pubsub.go, redis_pubsub.go, event_bus.go |
| **LLM集成** | llm | OpenAI/Ollama/volcengine统一适配 | provider.go, openai_provider.go |
| **自动化引擎** | automation | 规则CRUD+执行、Macro、CSAT | service.go, action_service.go |
| **智能分配** | autoassignment | RoundRobin+负载均衡分配 | service.go, round_robin.go |
| **报表分析** | reporting | ReportingEvent聚合 | model.go, service.go |
| **后台任务** | worker | goroutine并发池 | worker.go |
| **安全防护** | security | 加密、SQL注入防护、SSRF防护、Webhook签名 | encryption.go, sql_safety.go |
| **数据库管理** | database | golang-migrate迁移执行 | migrate.go |

### 3.3 公共工具包 (pkg/)

| 包 | 职责 |
|---|------|
| crypto | bcrypt Hash/Check 封装 |
| logger | zap 结构化日志（级别/格式/输出配置） |
| pagination | offset/limit 分页器 + 元数据计算 |
| response | `{data, meta}` 统一JSON响应格式 |
| validator | go-playground/validator/v10 自定义验证规则 |
| testutil | 测试辅助（DB setup/teardown、mock helper） |

### 3.4 模块依赖关系图

```
                cmd/gochat/main.go
                       │
                       ▼
                app.Bootstrap()
                       │
         ┌─────────────┼─────────────┐
         │             │             │
         ▼             ▼             ▼
      config         database       redis
         │             │             │
         └─────────────┼─────────────┘
                       │
                       ▼
              auth (JWT/OAuth/MFA/SAML)
                       │
         ┌─────────────┼─────────────┐
         │             │             │
         ▼             ▼             ▼
    repository      service      middleware
         │             │             │
         ▼             ▼             │
      model          handler ────────┤
                       │             │
                       ▼             ▼
                   router ──→ Gin Engine
                       │
         ┌─────────────┼─────────────┐
         │             │             │
         ▼             ▼             ▼
      channel        ws/Hub       pubsub
    (providers)    (WebSocket)   (EventBus)
         │             │             │
         ▼             ▼             ▼
   FB/TG/WA/Email   broadcast    Redis stream
```

---

## 4. 数据库设计

### 4.1 技术选型

- **主数据库**: PostgreSQL 16 (带 pgvector 扩展，用于 Captain AI 向量搜索)
- **缓存层**: Redis 7+ (Pub/Sub + Rate Limit + Refresh Token + Session)
- **ORM**: GORM v2 (模型定义 + AutoMigrate + 软删除)
- **迁移工具**: golang-migrate (版本化SQL迁移)
- **测试模式**: SQLite (单元测试无需PG) / PostgreSQL (e2e测试)

### 4.2 数据库表总览 (33表)

#### 核心基础表 (M1 — 初始化)

| 表名 | 用途 | 关键字段 |
|------|------|---------|
| accounts | 多租户账户 | name, locale, timezone, status, feature_flags(JSON) |
| users | 用户 | email(唯一), password_hash, role, provider, totp_secret |
| account_users | 用户-账号关联 | user_id, account_id, role, custom_role_id |
| custom_roles | 自定义角色 | account_id, name, permissions(JSONB) |
| contacts | 客户联系人 | account_id, name, email, phone_number, identifier |
| inboxes | 收件箱/渠道入口 | account_id, channel_type, channel_id, enable_auto_assignment |
| contact_inboxes | 联系人-收件箱关联 | contact_id, inbox_id, source_id, pubsub_token |
| inbox_members | 座席分配 | inbox_id, user_id, role, availability_status |
| conversations | 会话 | account_id, inbox_id, contact_id, assignee_id, status, priority, uuid |
| messages | 消息 | conversation_id(FK), account_id(FK), sender_id, content, message_type |
| attachments | 附件 | message_id, file_type, file_url, file_size, metadata(JSONB) |
| notifications | 通知 | account_id, user_id, notification_type, primary_actor, read_at |
| notification_preferences | 通知偏好 | user_id, channel, event_type, enabled, preferences(JSONB) |

#### 渠道配置表 (M1)

| 表名 | 用途 |
|------|------|
| channels | 渠道配置基表 (account_id, inbox_id, type) |
| channel_telegrams | Telegram Bot 配置 (bot_token, bot_name) |
| channel_web_widgets | Web Widget 配置 (website_url, welcome_title, welcome_text) |
| channel_facebook_pages | Facebook Page 配置 (page_id, access_token) |
| channel_whatsapps | WhatsApp Business 配置 (phone_number, business_id) |

#### 平台管理表 (M2-M4)

| 表名 | 用途 | 关键字段 |
|------|------|---------|
| platform_apps | 平台应用管理 | name, api_key, account_id, type, status |
| reporting_events | 事件上报 | account_id, inbox_id, user_id, name, event_start/end_time |
| reporting_events_rollups | 报表聚合 | dimension, dimension_value, metric_name, period |
| rate_limit_states | 速率限制状态 | Redis-backed, DB持久化 |

#### 认证安全表 (M2-M4)

| 表名 | 用途 | 关键字段 |
|------|------|---------|
| saml_configs | SAML 配置 | account_id, idp_url, certificate, sp_entity_id |
| saml_sessions | SAML 会话 | session_id, name_id, account_id, expires_at |

#### Captain AI 表 (M10)

| 表名 | 用途 | 关键字段 |
|------|------|---------|
| captain_assistants | AI 助手 | account_id, name, config(JSONB), guardrails(JSONB), status |
| captain_documents | AI 文档 | assistant_id, external_link, content, content_fingerprint, status |
| captain_assistant_responses | AI 响应记录 | assistant_id, conversation_id, response_text, source |
| captain_scenarios | AI 场景 | assistant_id, name, trigger_conditions(JSONB), actions(JSONB) |
| captain_custom_tools | AI 自定义工具 | account_id, name, tool_config(JSONB) |
| captain_inboxes | 助手-收件箱绑定 | assistant_id, inbox_id |

#### Copilot 表 (M10)

| 表名 | 用途 | 关键字段 |
|------|------|---------|
| copilot_threads | Copilot 会话线程 | account_id, user_id, status |
| copilot_messages | Copilot 消息 | thread_id, role, content, metadata(JSONB) |

#### Dashboard 表 (M11)

| 表名 | 用途 | 关键字段 |
|------|------|---------|
| dashboard_apps | 自定义仪表板 | account_id, name, config(JSONB), widgets(JSONB数组) |

### 4.3 关键设计决策

1. **软删除统一**: 所有表支持 `deleted_at` (GORM软删除)，所有查询自动过滤已删除记录
2. **JSONB广泛使用**: feature_flags, permissions, config, metadata, guardrails 等灵活字段用 JSONB
3. **外键约束**: messages 引用 conversations/accounts/inboxes (数据一致性保证)
4. **索引策略**: 每张表都有 `deleted_at` 索引 + 业务字段条件索引 (`WHERE deleted_at IS NULL`)
5. **时间戳统一**: 所有表使用 `created_at/updated_at/deleted_at` (TIMESTAMP WITH TIME ZONE)
6. **UUID公开标识**: conversations 有 uuid 字段，用于公开API（避免内部ID泄露）
7. **向量搜索**: captain_documents 未来通过 pgvector 支持语义搜索 (当前用 stub)

### 4.4 ER 关系图（核心实体）

```
Account ──1:N──→ User (via account_users)
Account ──1:N──→ Inbox
Account ──1:N──→ Contact
Account ──1:N──→ Conversation
Account ──1:N──→ Notification
Account ──1:N──→ CaptainAssistant
Account ──1:N──→ DashboardApp
Account ──1:N──→ PlatformApp

Inbox ──1:N──→ InboxMember (User)
Inbox ──1:N──→ Conversation
Inbox ──1:1──→ Channel (polymorphic: telegram/web_widget/facebook/whatsapp)

Contact ──1:N──→ ContactInbox ──→ Inbox
Contact ──1:N──→ Conversation

Conversation ──1:N──→ Message
Conversation ──1:N──→ Attachment (via Message)
Conversation ──1:1──→ Assignee (User)

CaptainAssistant ──1:N──→ CaptainDocument
CaptainAssistant ──1:N──→ CaptainScenario
CaptainAssistant ──1:N──→ CaptainInbox ──→ Inbox
CaptainAssistant ──1:N──→ CaptainAssistantResponse

CopilotThread ──1:N──→ CopilotMessage
```

---

## 5. API 路由设计

### 5.1 路由总体结构

GoChat API 基于 Gin 框架，采用 RESTful 设计，路由分组如下：

```
/health                          → 健康检查（无认证）
/api/v1/auth/*                   → 认证路由（公开）
/api/v1/saml/*                   → SAML 路由（公开）
/api/v1 (AuthRequired)           → 主API路由（认证后）
  /profile                       → 用户信息
  /notifications                 → 通知管理
  /push_subscriptions            → Push 设备
  /accounts/:id/webhooks         → Webhook 管理
  /accounts (AccountScope)       → 账号级资源
    /accounts/:id/inboxes/*      → 收件箱 + WebWidget配置
    /accounts/:id/conversations/* → 会话 + 消息
    /accounts/:id/contacts/*     → 联系人
    /accounts/:id/teams/*        → 团队
    /accounts/:id/platform_apps/* → 平台应用
    /accounts/:id/captain/*      → Captain AI + Copilot
    /accounts/:id/reports/*      → 报表
    /accounts/:id/live_reports/* → 实时报表
    /accounts/:id/dashboard_apps/* → 自定义仪表板
    /accounts/:id/portals/*      → Help Center
    /accounts/:id/automation_rules/* → 自动化规则
    /accounts/:id/macros/*       → Macro
    /accounts/:id/csats/*        → CSAT 满意度
/platform/api/v1 (SuperAdmin)    → 平台管理路由
/widget (CORS, 无认证)           → Widget API
/public/api/v1 (CORS, 无认证)    → 公开 CSAT 调查
/webhooks (WebhookAuth)          → 渠道回调
  /webhooks/facebook/:inbox_id   → FB/IG webhook
  /webhooks/telegram/:bot_token  → TG webhook
/ws                              → WebSocket 主端点
/cable                           → WebSocket ActionCable兼容端点
```

### 5.2 中间件链

```
全局中间件（所有路由）:
  Recovery → RequestLogger → RateLimit → CORS → SecurityHeaders

路由组中间件:
  AuthMiddleware      → /api/v1, /platform/api/v1
  AccountScope        → /accounts 子路由
  SuperAdmin          → /platform/api/v1
  CORS                → /widget, /public/api/v1
  WebhookAuth         → /webhooks
```

### 5.3 详细路由列表

#### 认证路由 (公开)

| 方法 | 路径 | 说明 |
|------|------|------|
| 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 | 确认密码重置 |
| GET | /api/v1/auth/google/callback | Google OAuth回调 |
| GET | /api/v1/auth/github/callback | GitHub OAuth回调 |

#### MFA路由 (需认证)

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/auth/mfa/enable | 启用TOTP |
| POST | /api/v1/auth/mfa/verify | 验证TOTP |
| POST | /api/v1/auth/mfa/disable | 禁用TOTP |

#### 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 |

#### Profile路由 (认证, 无账号作用域)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/profile | 获取用户信息 |
| PUT | /api/v1/profile | 更新用户信息 |
| PUT | /api/v1/profile/avatar | 更新头像 |

#### Notification路由 (认证, 用户级)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/notifications | 通知列表 |
| GET | /api/v1/notifications/unread_count | 未读数 |
| POST | /api/v1/notifications/read_all | 全部标读 |
| POST | /api/v1/notifications/:id/read | 标读 |
| PUT | /api/v1/notifications/:id | 更新 |
| DELETE | /api/v1/notifications/:id | 删除 |
| GET | /api/v1/accounts/:id/notification_settings | 通知设置 |
| PUT | /api/v1/accounts/:id/notification_settings | 更新设置 |

#### Push/Webhook Subscription路由

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/push_subscriptions | 注册Push设备 |
| GET | /api/v1/push_subscriptions | 列出Push设备 |
| DELETE | /api/v1/push_subscriptions/:id | 删除Push设备 |
| GET | /api/v1/accounts/:id/webhooks | Webhook列表 |
| POST | /api/v1/accounts/:id/webhooks | 创建Webhook |
| GET | /api/v1/accounts/:id/webhooks/:webhook_id | Webhook详情 |
| PUT | /api/v1/accounts/:id/webhooks/:webhook_id | 更新Webhook |
| DELETE | /api/v1/accounts/:id/webhooks/:webhook_id | 删除Webhook |

#### Account路由 (AccountScope)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/ | 账号列表 |
| POST | /api/v1/accounts/ | 创建账号 |
| GET | /api/v1/accounts/:id | 账号详情 |
| PUT | /api/v1/accounts/:id | 更新账号 |
| DELETE | /api/v1/accounts/:id | 删除账号 |
| PUT | /api/v1/accounts/:id/settings | 更新设置 |
| GET | /api/v1/accounts/:id/users | 成员列表 |
| POST | /api/v1/accounts/:id/users | 添加成员 |
| DELETE | /api/v1/accounts/:id/users/:user_id | 移除成员 |

#### Inbox路由 (账号级)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/inboxes/ | 收件箱列表 |
| POST | /api/v1/accounts/:id/inboxes/ | 创建收件箱 |
| GET | /api/v1/accounts/:id/inboxes/:inbox_id | 收件箱详情 |
| PUT | /api/v1/accounts/:id/inboxes/:inbox_id | 更新 |
| DELETE | /api/v1/accounts/:id/inboxes/:inbox_id | 删除 |
| POST | /api/v1/accounts/:id/inboxes/web_widget | 创建Widget收件箱 |
| GET | /api/v1/accounts/:id/inboxes/:inbox_id/web_widget_config | Widget配置 |
| PUT | /api/v1/accounts/:id/inboxes/:inbox_id/web_widget_config | 更新Widget配置 |
| DELETE | /api/v1/accounts/:id/inboxes/:inbox_id/web_widget | 删除Widget |

#### InboxMember路由 (座席分配)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/inboxes/:inbox_id/members | 成员列表 |
| POST | /api/v1/accounts/:id/inboxes/:inbox_id/members | 添加成员 |
| PATCH | /api/v1/accounts/:id/inboxes/:inbox_id/members/:user_id | 更新成员 |
| DELETE | /api/v1/accounts/:id/inboxes/:inbox_id/members/:user_id | 移除成员 |

#### Conversation路由 (账号级)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/conversations/ | 会话列表 |
| POST | /api/v1/accounts/:id/conversations/ | 创建会话 |
| GET | /api/v1/accounts/:id/conversations/search | 搜索会话 |
| POST | /api/v1/accounts/:id/conversations/filter | 过滤会话 |
| GET | /api/v1/accounts/:id/conversations/:id | 会话详情 |
| PATCH | /api/v1/accounts/:id/conversations/:id | 更新会话 |
| DELETE | /api/v1/accounts/:id/conversations/:id | 删除会话 |
| POST | /api/v1/accounts/:id/conversations/:id/assign | 分配Agent |
| POST | /api/v1/accounts/:id/conversations/:id/toggle_status | 切换状态 |
| PATCH | /api/v1/accounts/:id/conversations/:id/labels | 更新标签 |
| POST | /api/v1/accounts/:id/conversations/:id/mute | 静音 |
| POST | /api/v1/accounts/:id/conversations/:id/unmute | 取消静音 |
| PATCH | /api/v1/accounts/:id/conversations/:id/priority | 更新优先级 |

#### Message路由 (嵌套在Conversation下)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/conversations/:conv_id/messages/ | 消息列表 |
| POST | /api/v1/accounts/:id/conversations/:conv_id/messages/ | 创建消息 |
| GET | /api/v1/accounts/:id/conversations/:conv_id/messages/:id | 消息详情 |
| PATCH | /api/v1/accounts/:id/conversations/:conv_id/messages/:id | 更新消息 |
| DELETE | /api/v1/accounts/:id/conversations/:conv_id/messages/:id | 删除消息 |
| POST | /api/v1/accounts/:id/conversations/:conv_id/messages/:id/retry | 重试 |

#### Contact路由 (账号级)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/contacts/ | 联系人列表 |
| POST | /api/v1/accounts/:id/contacts/ | 创建联系人 |
| GET | /api/v1/accounts/:id/contacts/search | 搜索联系人 |
| GET | /api/v1/accounts/:id/contacts/:contact_id | 联系人详情 |
| PUT | /api/v1/accounts/:id/contacts/:contact_id | 更新联系人 |
| DELETE | /api/v1/accounts/:id/contacts/:contact_id | 删除联系人 |

#### Team路由 (账号级)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/teams/ | 团队列表 |
| POST | /api/v1/accounts/:id/teams/ | 创建团队 |
| GET | /api/v1/accounts/:id/teams/:id | 团队详情 |
| PUT | /api/v1/accounts/:id/teams/:id | 更新团队 |
| DELETE | /api/v1/accounts/:id/teams/:id | 删除团队 |
| POST | /api/v1/accounts/:id/teams/:id/members | 添加成员 |
| DELETE | /api/v1/accounts/:id/teams/:id/members/:user_id | 移除成员 |
| GET | /api/v1/accounts/:id/teams/:id/members | 成员列表 |

#### Captain AI路由 (账号级)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/captain/assistants/ | 助手列表 |
| POST | /api/v1/accounts/:id/captain/assistants/ | 创建助手 |
| GET | /api/v1/accounts/:id/captain/assistants/:id | 助手详情 |
| PUT | /api/v1/accounts/:id/captain/assistants/:id | 更新助手 |
| DELETE | /api/v1/accounts/:id/captain/assistants/:id | 删除助手 |
| POST | /api/v1/accounts/:id/captain/assistants/:id/inboxes | 绑定收件箱 |
| DELETE | /api/v1/accounts/:id/captain/assistants/:id/inboxes/:inbox_id | 解绑收件箱 |
| GET | /api/v1/accounts/:id/captain/assistants/:asst_id/documents/ | 文档列表 |
| POST | /api/v1/accounts/:id/captain/assistants/:asst_id/documents/ | 创建文档 |
| GET | /api/v1/accounts/:id/captain/assistants/:asst_id/documents/:id | 文档详情 |
| DELETE | /api/v1/accounts/:id/captain/assistants/:asst_id/documents/:id | 删除文档 |
| GET | /api/v1/accounts/:id/captain/assistants/:asst_id/scenarios/ | 场景列表 |
| POST | /api/v1/accounts/:id/captain/assistants/:asst_id/scenarios/ | 创建场景 |
| GET | /api/v1/accounts/:id/captain/assistants/:asst_id/scenarios/:id | 场景详情 |
| PUT | /api/v1/accounts/:id/captain/assistants/:asst_id/scenarios/:id | 更新场景 |
| DELETE | /api/v1/accounts/:id/captain/assistants/:asst_id/scenarios/:id | 删除场景 |
| GET | /api/v1/accounts/:id/captain/custom_tools/ | 自定义工具列表 |
| POST | /api/v1/accounts/:id/captain/custom_tools/ | 创建工具 |
| GET | /api/v1/accounts/:id/captain/custom_tools/:id | 工具详情 |
| PUT | /api/v1/accounts/:id/captain/custom_tools/:id | 更新工具 |
| DELETE | /api/v1/accounts/:id/captain/custom_tools/:id | 删除工具 |

#### Copilot路由 (账号级)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/captain/copilot_threads/ | 线程列表 |
| POST | /api/v1/accounts/:id/captain/copilot_threads/ | 创建线程 |
| GET | /api/v1/accounts/:id/captain/copilot_threads/:id | 线程详情 |
| DELETE | /api/v1/accounts/:id/captain/copilot_threads/:id | 删除线程 |
| POST | /api/v1/accounts/:id/captain/copilot_threads/:id/messages | 发送消息 |
| POST | /api/v1/accounts/:id/captain/copilot/suggest_replies | AI建议回复 |
| POST | /api/v1/accounts/:id/captain/copilot/summarize | AI会话摘要 |
| POST | /api/v1/accounts/:id/captain/copilot/translate | AI翻译 |

#### Analytics路由 (账号级)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/reports/summary | 报表总览 |
| GET | /api/v1/accounts/:id/reports/agents | Agent指标 |
| GET | /api/v1/accounts/:id/reports/inboxes | Inbox指标 |
| GET | /api/v1/accounts/:id/reports/labels | 标签指标 |
| GET | /api/v1/accounts/:id/reports/teams | 团队指标 |
| GET | /api/v1/accounts/:id/reports/conversations | 会话流量 |
| GET | /api/v1/accounts/:id/reports/conversation_traffic | 会话流量 |

#### Live Report路由

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/live_reports/conversation_metrics | 实时会话指标 |

#### Dashboard App路由

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/dashboard_apps/ | Dashboard列表 |
| POST | /api/v1/accounts/:id/dashboard_apps/ | 创建Dashboard |
| GET | /api/v1/accounts/:id/dashboard_apps/search | 搜索Dashboard |
| GET | /api/v1/accounts/:id/dashboard_apps/:id | Dashboard详情 |
| PUT | /api/v1/accounts/:id/dashboard_apps/:id | 更新Dashboard |
| PATCH | /api/v1/accounts/:id/dashboard_apps/:id | Patch更新 |
| DELETE | /api/v1/accounts/:id/dashboard_apps/:id | 删除Dashboard |
| GET | /api/v1/accounts/:id/dashboard_apps/:id/widgets | Widget列表 |
| POST | /api/v1/accounts/:id/dashboard_apps/:id/widgets | 添加Widget |
| PUT | /api/v1/accounts/:id/dashboard_apps/:id/widgets/:idx | 更新Widget |
| DELETE | /api/v1/accounts/:id/dashboard_apps/:id/widgets/:idx | 删除Widget |

#### Help Center (Portal)路由

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/portals/ | Portal列表 |
| POST | /api/v1/accounts/:id/portals/ | 创建Portal |
| GET | /api/v1/accounts/:id/portals/:portal_id | Portal详情 |
| PUT | /api/v1/accounts/:id/portals/:portal_id | 更新Portal |
| DELETE | /api/v1/accounts/:id/portals/:portal_id | 删除Portal |
| POST | /api/v1/accounts/:id/portals/:portal_id/archive | 归档Portal |
| DELETE | /api/v1/accounts/:id/portals/:portal_id/logo | 删除Logo |
| GET | /api/v1/accounts/:id/portals/:portal_id/categories/ | 分类列表 |
| POST | /api/v1/accounts/:id/portals/:portal_id/categories/ | 创建分类 |
| GET | /api/v1/accounts/:id/portals/:portal_id/categories/:cat_id | 分类详情 |
| PUT | /api/v1/accounts/:id/portals/:portal_id/categories/:cat_id | 更新分类 |
| DELETE | /api/v1/accounts/:id/portals/:portal_id/categories/:cat_id | 删除分类 |
| POST | /api/v1/accounts/:id/portals/:portal_id/categories/reorder | 分类排序 |
| GET | /api/v1/accounts/:id/portals/:portal_id/articles/ | 文章列表 |
| POST | /api/v1/accounts/:id/portals/:portal_id/articles/ | 创建文章 |
| GET | /api/v1/accounts/:id/portals/:portal_id/articles/search | 搜索文章 |
| GET | /api/v1/accounts/:id/portals/:portal_id/articles/status_counts | 状态统计 |
| POST | /api/v1/accounts/:id/portals/:portal_id/articles/reorder | 文章排序 |
| POST | /api/v1/accounts/:id/portals/:portal_id/articles/bulk_update_status | 批量更新状态 |
| POST | /api/v1/accounts/:id/portals/:portal_id/articles/bulk_delete | 批量删除 |
| GET | /api/v1/accounts/:id/portals/:portal_id/articles/:art_id | 文章详情 |
| GET | /api/v1/accounts/:id/portals/:portal_id/articles/:art_id/edit | 编辑视图 |
| PUT | /api/v1/accounts/:id/portals/:portal_id/articles/:art_id | 更新文章 |
| DELETE | /api/v1/accounts/:id/portals/:portal_id/articles/:art_id | 删除文章 |
| GET | /api/v1/accounts/:id/portals/:portal_id/categories/:cat_id/articles | 分类下文章 |
| GET | /api/v1/accounts/:id/portals/:portal_id/folders/ | 文件夹列表 |
| POST | /api/v1/accounts/:id/portals/:portal_id/folders/ | 创建文件夹 |
| GET | /api/v1/accounts/:id/portals/:portal_id/folders/:folder_id | 文件夹详情 |
| PUT | /api/v1/accounts/:id/portals/:portal_id/folders/:folder_id | 更新文件夹 |
| DELETE | /api/v1/accounts/:id/portals/:portal_id/folders/:folder_id | 删除文件夹 |
| GET | /api/v1/accounts/:id/portals/:portal_id/members/ | 成员列表 |
| POST | /api/v1/accounts/:id/portals/:portal_id/members/ | 创建成员 |
| GET | /api/v1/accounts/:id/portals/:portal_id/members/:member_id | 成员详情 |
| PUT | /api/v1/accounts/:id/portals/:portal_id/members/:member_id | 更新成员 |
| DELETE | /api/v1/accounts/:id/portals/:portal_id/members/:member_id | 删除成员 |

#### Automation Rule路由

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/automation_rules/ | 规则列表 |
| POST | /api/v1/accounts/:id/automation_rules/ | 创建规则 |
| GET | /api/v1/accounts/:id/automation_rules/:id | 规则详情 |
| PUT | /api/v1/accounts/:id/automation_rules/:id | 更新规则 |
| DELETE | /api/v1/accounts/:id/automation_rules/:id | 删除规则 |
| POST | /api/v1/accounts/:id/automation_rules/:id/clone | 克隆规则 |

#### Macro路由

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/macros/ | Macro列表 |
| POST | /api/v1/accounts/:id/macros/ | 创建Macro |
| GET | /api/v1/accounts/:id/macros/:id | Macro详情 |
| PUT | /api/v1/accounts/:id/macros/:id | 更新Macro |
| DELETE | /api/v1/accounts/:id/macros/:id | 删除Macro |
| POST | /api/v1/accounts/:id/macros/:id/execute | 执行Macro |

#### CSAT路由

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/csats/ | CSAT列表 |
| GET | /api/v1/accounts/:id/csats/metrics | CSAT指标 |
| POST | /api/v1/accounts/:id/csats/:id/update_review_notes | 更新审阅笔记 |

#### Platform App路由 (账号级)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/accounts/:id/platform_apps/ | 应用列表 |
| POST | /api/v1/accounts/:id/platform_apps/ | 创建应用 |
| GET | /api/v1/accounts/:id/platform_apps/search | 搜索应用 |
| GET | /api/v1/accounts/:id/platform_apps/:id | 应用详情 |
| PUT | /api/v1/accounts/:id/platform_apps/:id | 更新应用 |
| DELETE | /api/v1/accounts/:id/platform_apps/:id | 删除应用 |
| POST | /api/v1/accounts/:id/platform_apps/:id/regenerate_api_key | 重生API Key |

#### Platform API路由 (超级管理员)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /platform/api/v1/apps | 应用列表 |
| POST | /platform/api/v1/apps | 创建应用 |
| GET | /platform/api/v1/apps/search | 搜索应用 |
| GET | /platform/api/v1/apps/:id | 应用详情 |
| PUT | /platform/api/v1/apps/:id | 更新应用 |
| DELETE | /platform/api/v1/apps/:id | 删除应用 |
| POST | /platform/api/v1/apps/:id/regenerate_api_key | 重生API Key |

#### Widget路由 (公开, CORS)

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /widget/init | Widget初始化 |
| POST | /widget/contact | Widget创建联系人 |
| GET | /widget/conversations | Widget会话列表 |
| POST | /widget/messages | Widget发送消息 |
| GET | /widget/cable_token | 获取Cable令牌 |

#### 公开CSAT路由 (无认证, CORS)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /public/api/v1/conversations/:uuid/csats | 获取CSAT调查 |
| POST | /public/api/v1/conversations/:uuid/csats | 提交CSAT评分 |

#### Webhook回调路由 (渠道认证)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /webhooks/facebook/:inbox_id | FB webhook验证 |
| POST | /webhooks/facebook/:inbox_id | FB webhook回调 |
| POST | /webhooks/telegram/:bot_token | TG webhook回调 |
| ANY | /webhooks/:channel_type/:identifier | 其他渠道(占位) |

#### WebSocket路由

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /ws | WebSocket 主端点 (JWT/pubsub_token认证) |
| GET | /cable | ActionCable兼容端点 |

#### 健康检查

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /health | 服务健康检查 (uptime, version, commit) |

### 5.4 统一响应格式

所有API响应遵循 `{data, meta}` envelope 格式：

```json
// 成功 - 单条
{"data": { ... }, "meta": {}}

// 成功 - 列表
{"data": [ ... ], "meta": {"page": 1, "per_page": 25, "total": 100}}

// 错误
{"error": {"code": "UNAUTHORIZED", "message": "Invalid token"}}
```

---

## 6. 依赖注入与启动序列

### 6.1 Bootstrap 12步序列

```
Step 1:  LoadWithEnv(env)         → 加载配置（Viper多环境叠加）
Step 2:  Validate(cfg)            → 校验配置完整性
Step 3:  InitLogger               → zap结构化日志初始化
Step 4:  NewDatabase              → PostgreSQL连接池
Step 4b: RunMigrations            → golang-migrate执行（可选）
Step 5:  NewRedisClient           → Redis连接
Step 5b: NewRedisPubSub           → Redis Pub/Sub (watermill)
Step 6:  Wire Auth Infrastructure → JWT + OAuth + MFA + SAML + RefreshStore + WebhookRegistry
Step 7:  Wire Repositories        → 21+ Repo实例化（构造函数注入*gorm.DB）
Step 8:  Wire Services            → 20+ Service实例化（注入Repo+依赖）
Step 9:  Wire Handlers            → 49 Handler实例化（注入Service）
Step 10: Setup Gin Router         → 中间件链 + 路由注册
Step 11: Create WebSocket Hub     → WS Hub + WSAuthenticator
Step 12: Setup Config Reloader    → fsnotify热加载（11字段）
```

### 6.2 App 结构体（持有全部依赖）

```go
type App struct {
    config   *config.Config
    reloader *config.ConfigReloader
    db       *gorm.DB
    pubsub   pubsub.PubSub
    engine   *gin.Engine
    wsHub    *ws.Hub
}
```

---

## 7. 技术选型与关键依赖

| 依赖 | 版本 | 用途 |
|------|------|------|
| Gin | v1.10 | HTTP 框架 |
| GORM | v1.30 | ORM (PostgreSQL + SQLite + MySQL驱动) |
| golang-migrate | v4.19 | 版本化SQL迁移 |
| watermill + redisstream | v1.5/v1.4 | Redis Pub/Sub 事件总线 |
| go-redis | v9.12 | Redis客户端 |
| gorilla/websocket | v1.5 | WebSocket |
| golang-jwt | v5.2 | JWT签发/验证 |
| go-playground/validator | v10.20 | 参数校验 |
| spf13/viper | v1.19 | 配置管理 |
| go-playground/bluemonday | v1.0 | HTML安全过滤 |
| go-resty | v2.16 | HTTP客户端(渠道API调用) |
| pgvector-go | v0.4 | 向量搜索(Captain AI) |
| gorm.io/datatypes | v1.2 | JSONB类型支持 |
| emersion/go-imap | v1.2 | IMAP邮件收取 |
| fsnotify | v1.7 | 配置文件热加载 |
| miniredis | v2.38 | Redis测试mock |
| uber/zap | v1.23 | 结构化日志 |
| golang.org/x/crypto | v0.45 | bcrypt + argon2 |
| golang.org/x/oauth2 | v0.30 | OAuth2客户端 |

---

## 8. 渠道抽象层设计

### 8.1 Provider 接口

```go
type Provider interface {
    Name() string                           // "facebook", "telegram", etc.
    ProcessIncoming(ctx, event) (Message, error) // 进站消息处理
    ProcessOutgoing(ctx, message) error           // 出站消息发送
    ValidateWebhook(ctx, request) error           // Webhook验签
}
```

### 8.2 渠道注册表模式

- 全局 `channel.Register(provider)` 注册各Provider
- `channel.Dispatcher` 分发事件到对应Listener
- 每个渠道实现: Provider + Listener + Service + Repository + Pipeline + Types

### 8.3 已实现渠道

| 渠道 | Provider | Listener | Webhook | 状态 |
|------|---------|---------|---------|------|
| Facebook/Instagram | FacebookProvider + InstagramProvider | FBEventListener + IGEventListener | facebook_webhook_handler | 已实现 |
| Telegram | TelegramProvider | (via webhook) | telegram_webhook_handler | 已实现 |
| WhatsApp | WhatsAppProvider | (pending) | (pending) | 基础结构 |
| Email | EmailProvider (IMAP+SMTP) | IMAPListener | email_webhook_handler | 已实现 |
| Web Widget | WebWidgetProvider | (via HTTP) | (内部路由) | 已实现 |

---

## 9. WebSocket 实时通信

### 9.1 双端点设计

- `/ws` — 主WebSocket端点
- `/cable` — ActionCable兼容端点（Chatwoot迁移兼容）

### 9.2 认证方式

- JWT Bearer Token (query param或首条消息)
- pubsub_token (ContactInbox级认证)

### 9.3 功能模块

| 模块 | 职责 |
|------|------|
| Hub | 连接池管理 + 消息广播 |
| WSAuthenticator | JWT + pubsub_token 双认证 |
| Broadcast | EventBus → WS事件分发 |
| Presence | 在线/离线状态追踪 |
| Typing | 输入状态实时推送 |
| Heartbeat | 心跳保活 (ping/pong) |

---

## 10. 安全架构

| 安全措施 | 实现 |
|---------|------|
| JWT认证 | Access Token (短期) + Refresh Token (Redis存储, 长期) |
| MFA (TOTP) | 启用/验证/禁用三步流程 |
| SAML 2.0 | SP发起 + IdP回调 + SLO |
| RBAC | 角色→权限矩阵 (agent/admin/super_admin + custom_roles) |
| Rate Limiting | Redis滑动窗口 (per-IP + per-user) |
| SQL注入防护 | GORM参数化查询 + sql_safety检查 |
| SSRF防护 | URL白名单 + 内网IP过滤 |
| Webhook签名 | HMAC-SHA256 签名验证 |
| HTML安全 | bluemonday HTML过滤 |
| 安全响应头 | X-Frame-Options, CSP, HSTS, X-Content-Type-Options |
| 密码存储 | bcrypt + argon2id |

---

## 11. 测试架构

| 测试层级 | 工具 | 覆盖范围 |
|---------|------|---------|
| 单元测试 | Go testing + testify | Service/Repository/Auth/Middleware/Model (83文件, 141+用例) |
| E2E测试 | Go testing + PG helper | Auth/Account/Conversation/CRM/RBAC/Dashboard/Channel/Middleware |
| 测试DB | SQLite (单元) + PostgreSQL (e2e) | 独立DB, 无副作用 |
| Redis Mock | miniredis | Auth/RateLimit/PubSub测试 |
| Benchmark | Go benchmark | JWT签发/验证性能 |

---

## 12. 部署架构

### 12.1 Docker Compose 模式

```
docker-compose.yml       → 主compose (app + postgres + redis)
docker-compose.dev.yml   → 开发 (热重载 + debug端口)
docker-compose.prod.yml  → 生产 (健康检查 + 资源限制)
docker-compose.test.yml  → 测试 (独立PG + 覆盖率)
```

### 12.2 Kubernetes 部署

```
deploy/k8s/              → Deployment + Service + ConfigMap + Secret manifests
```

### 12.3 环境配置优先级

```
.env (最高) → configs/production.yaml → configs/default.yaml → 程序默认值
```

### 12.4 热加载字段（11个，无需重启）

- Log Level, CORS origins, Rate Limit thresholds, JWT expiry, Worker concurrency 等

---

## 13. 与 Chatwoot 的架构差异总结

| 维度 | Chatwoot (Ruby/Rails) | GoChat (Go/Gin) |
|------|---------------------|-----------------|
| 代码组织 | MVC按技术层分层 | 按业务域分包 (domain-driven) |
| 依赖注入 | Rails自动加载 | 手动DI + 构造函数注入 |
| 实时推送 | ActionCable | Redis Pub/Sub + WebSocket Hub |
| 异步任务 | Sidekiq (Ruby进程) | Goroutine + Worker池 |
| DB迁移 | ActiveRecord Migration | golang-migrate (SQL文件) |
| 配置管理 | InstallationConfig表 + ENV | Viper配置层 + fsnotify热加载 |
| 中间件 | Rails before_action | Gin显式中间件链 |
| 权限校验 | Pundit Policy类 | 中间件 + 内联权限函数 |
| 多态关联 | polymorphic (owner_type+owner_id) | 独立关联表 + JSON字段 |
| 事件分发 | Dispatcher + Listener | EventBus接口 + Redis Pub/Sub |
| 路由数量 | 327 | ~106 (精简合并) |
| 表数量 | 87 | 33 (精简+合并) |