# GoChat Architecture Review

## 项目概览

GoChat 是 Chatwoot 的 1:1 Go 语言重写，旨在提供高性能、可扩展的全功能客服平台。

| 指标 | 数值 |
|------|------|
| 源代码行数 | 32,228 |
| 测试代码行数 | 8,746 |
| 源文件数 | 209 |
| 测试文件数 | 30 |
| API路由数 | 104 |
| 模型结构体 | 28 |
| Handler方法 | ~150 |

## 分层架构

```
cmd/main.go                  ← 入口
internal/app/bootstrap.go    ← DI 编排（repos→services→handlers→router）
internal/router/router.go    ← 104 路由注册
internal/handler/api/v1/     ← HTTP 处理层（15个handler文件）
internal/service/            ← 业务逻辑层（DI via 接口）
internal/repository/         ← 数据访问层（GORM + BaseRepository泛型）
internal/model/              ← 领域模型（28 个 struct）
internal/auth/               ← 认证+RBAC+MFA+SAML+OAuth
internal/channel/provider/   ← 渠道抽象（Telegram/WebWidget/API）
internal/llm/                ← AI集成（Captain/Copilot）
internal/middleware/         ← 11 个中间件（安全/限流/XSS/上传等）
internal/security/           ← 加密/Webhook签名/SQL安全
internal/ws/                 ← WebSocket hub + authenticator
internal/pubsub/             ← Watermill 事件驱动
internal/reporting/          ← 报表+指标注册
pkg/crypto/                  ← JWT + 加密工具
```

### 模块代码量分布

| 模块 | 行数 | 占比 |
|------|------|------|
| channel (Telegram/WebWidget/API) | 6,448 | 20.0% |
| handler (HTTP) | 5,044 | 15.6% |
| service (业务逻辑) | 4,426 | 13.8% |
| auth (认证/RBAC/MFA) | 1,691 | 5.2% |
| middleware (安全中间件) | 1,879 | 5.8% |
| security (加密/签名) | 1,570 | 4.9% |
| ws (WebSocket) | 1,221 | 3.8% |
| repository (数据访问) | 1,820 | 5.6% |
| model (领域模型) | 1,392 | 4.3% |
| reporting (报表) | 477 | 1.5% |
| llm (AI) | 579 | 1.8% |
| config | 243 | 0.7% |
| pubsub | 239 | 0.7% |

## 关键设计决策

### 1. 依赖注入（DI）
- Bootstrap 函数按顺序编排：repos → services → handlers → router
- Services 依赖 repo **接口**（不直接依赖 app.DB）
- Handlers 依赖 service **接口**（不依赖 app.App struct）
- ✅ 优点：可测试、松耦合
- ⚠️ 缺点：无 DI 容器，手动编排复杂度随模块增长

### 2. 泛型 BaseRepository
- `BaseRepository[T any]` 提供通用 CRUD
- 具体 Repo 通过组合 BaseRepository + 自定义方法实现
- ✅ 减少重复代码
- ⚠️ 泛型错误处理需要关注 RowsAffected 检查

### 3. 渠道抽象（Channel Provider）
- `ChannelProvider` 接口：`SendMessage/ReceiveMessage/ValidateWebhookToken`
- Provider 工厂模式：`GetProvider(channelType)`
- 支持 Telegram、WebWidget、API Channel
- ✅ 新渠道只需实现接口 + 注册工厂

### 4. Watermill PubSub
- 替代 Chatwoot 的 Sidekiq/asynq
- 内存实现（可扩展到 Redis/NATS）
- 事件：message.created, conversation.updated, notification.created 等
- ✅ Go 生态标准选择，可插拔

### 5. 安全层
- JWT + RefreshToken + MFA (TOTP) + SAML + OAuth
- RBAC: PermissionMatrix → PolicyContext.Can(action, resource)
- SSRF 防护、Rate Limiting、XSS、上传安全、加密
- Webhook HMAC-SHA256 签名验证 + 防重放

### 6. AI 集成（Captain/Copilot）
- LLM provider 接口：`Generate/Stream/Embed`
- 多提供商支持（OpenAI/Anthropic/本地模型）
- Captain: assistant + scenario + document + custom_tool
- Copilot: message suggestion + thread analysis

## 循环依赖检查

```bash
# Go 模块依赖拓扑无循环
go build ./... → PASS
go vet ./... → PASS
```

各包 import 关系：
- handler → service → repository → model（单向）
- auth → config, crypto
- middleware → auth, config
- channel → model, pubsub, service（事件发布）
- ws → auth, crypto
- security → 独立（无外部依赖）

✅ **无循环依赖**，依赖方向全部单向向下。

## 分层合规性评估

| 规则 | 状态 | 说明 |
|------|------|------|
| Handler 不依赖 DB | ✅ | 仅注入 Service 接口 |
| Service 不依赖 app.App | ✅ | 仅注入 Repo 接口 |
| Repo 不依赖 Service | ✅ | 仅依赖 GORM + model |
| Model 独立无业务逻辑 | ✅ | 纯数据结构 + GORM hooks |
| 跨层通过接口通信 | ✅ | 全部 DI via 接口 |

## 改进建议

### 高优先级
1. **引入 DI 容器**（wire/dig）— 减少 bootstrap 手动编排复杂度
2. **Service 层测试覆盖率**（0.2%→50%）— 关键业务逻辑需要验证
3. **Repository 层测试覆盖率**（6.3%→40%）— 数据访问层需保证正确性

### 中优先级
4. **PubSub 扩展到 Redis/NATS** — 生产环境需要持久化消息队列
5. **配置热加载** — 当前配置只在启动时加载
6. **API 文档生成**（Swagger/OpenAPI）— 104 个路由需要自动文档

### 低优先级
7. **性能优化** — Conversation List (468μs) 和 Message List (440μs) 有优化空间
8. **结构化日志** — applogger 当前简化版，生产需要 JSON 结构化