gochat/docs/HANDOVER_DOCUMENT.md

GoChat 项目交接文档

项目简介

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

• 仓库位置: ~/Workspace/gochat/
• Module: github.com/gochat/gochat
• 语言: Go 1.22+
• 代码量: 32,228 行源代码 + 8,746 行测试代码

项目结构

gochat/
├── cmd/main.go                   # 入口程序
├── internal/
│   ├── app/bootstrap.go          # DI编排（核心入口）
│   ├── router/router.go          # 104路由注册
│   ├── handler/api/v1/           # 15个handler（HTTP层）
│   ├── service/                  # 业务逻辑层
│   ├── repository/               # 数据访问层（GORM）
│   ├── model/                    # 28个领域模型
│   ├── auth/                     # JWT+RBAC+MFA+OAuth+SAML
│   ├── channel/provider/         # Telegram/WebWidget/API渠道
│   ├── llm/                      # Captain/Copilot AI
│   ├── middleware/                # 11个中间件（安全+限流+XSS+上传）
│   ├── security/                 # 加密+Webhook签名+SQL安全+SSRF
│   ├── ws/                       # WebSocket hub
│   ├── pubsub/                   # Watermill事件驱动
│   ├── config/                   # 配置管理
│   └── reporting/                # 报表+指标
├── pkg/crypto/                   # JWT+加密工具
├── tests/e2e/                    # E2E测试套件（9个测试全通过）
├── configs/                      # 配置文件
├── docs/                         # 项目文档（P15产出）
├── Dockerfile                    # Docker构建
├── .env.example                  # 环境变量示例
└── seed.sh                       # 数据库种子脚本

构建和运行

构建

GOPROXY=https://goproxy.cn,direct go build -ldflags "-X main.version=$(git describe --tags)" ./cmd/main.go

运行

# 开发模式
go run cmd/main.go

# Docker
docker build -t gochat .
docker run -p 8080:8080 gochat

测试

# 全量测试
GOPROXY=https://goproxy.cn,direct go test ./...

# E2E测试
go test -v ./tests/e2e/

# 性能基准
go test -bench=. -benchmem ./internal/repository/ ./internal/auth/

# 覆盖率
go test -cover ./internal/model/ ./internal/auth/ ./pkg/crypto/

编译验证

go build ./...   # 编译检查
go vet ./...     # 代码规范检查

阶段完成状态

阶段	内容	状态
P1	核心框架搭建（Gin+GORM+config）	✅ 完成
P2	用户认证体系（JWT+bcrypt+RBAC）	✅ 完成
P3	基础数据模型（Account/User/Contact）	✅ 完成
P4	对话+消息核心	✅ 完成
P5	渠道抽象层（Provider接口+工厂）	✅ 完成
P6	API+认证完善（REST endpoints）	✅ 完成
P7	WebWidget渠道	✅ 完成
P7	Telegram渠道	✅ 完成
P8	Notification系统	✅ 完成
P9	WebSocket实时通信	✅ 完成
P10	Captain AI（8repo+5handler+LLM）	✅ 完成
P11	报表系统（3model+3repo+2service+3handler）	✅ 完成
P12	Docker部署（Dockerfile+health+graceful shutdown）	✅ 完成
P13	测试完善（e2e全通过+RBAC修复）	✅ 完成
P14	安全加固（14个安全模块1851行）	✅ 完成
P15	架构评审+集成验证+文档	✅ 完成

关键设计约定

约定	说明
Module path	github.com/gochat/gochat
Handler依赖	Service 接口（不依赖 app.App）
Service依赖	Repo 接口（不依赖 app.DB()）
Logger格式	applogger.L().Errorf("msg: %v", err)
RefreshTokenStore	NewRefreshTokenStore(client *redis.Client, cfg *config.JWTConfig)
Handler构造	NewAccountHandler(&service.AccountService{})（取指针）
LLM路径	internal/llm/（不是 internal/service/llm/）
EnableAutoAssignment	默认 false
GORM Update	无记录时 Error=nil，需检查 RowsAffected
JWT Claims	JSON 数字=float64，需 uint(claims["user_id"].(float64))
GOPROXY	https://goproxy.cn,direct（所有 go 命令必须使用）

文档清单

文档	路径
架构评审	docs/ARCHITECTURE_REVIEW.md
API覆盖报告	docs/API_COVERAGE_REPORT.md
性能基准	docs/PERFORMANCE_BENCHMARK.md
安全审计	docs/SECURITY_AUDIT_REPORT.md
集成验证	docs/INTEGRATION_VERIFICATION_REPORT.md
阶段二规划	docs/PHASE2_PLAN.md
项目交接	docs/HANDOVER_DOCUMENT.md

安全模块清单

• JWT安全（HMAC-SHA256 + Redis refresh token）
• SSRF防护（私有IP检测 + URL验证）
• Rate Limiting（IP+路径限流）
• MFA（TOTP 二步验证）
• OAuth2 + SAML（企业认证）
• 文件上传安全（MIME验证+大小限制+ZIP防护）
• XSS防护（bluemonday HTML净化）
• 安全头部（CSP/HSTS/X-Frame-Options等，已集成到bootstrap）
• 数据加密（AES-256-GCM）
• Webhook签名（HMAC-SHA256+防重放）
• SQL注入防护（GORM参数化+安全审计）
• RBAC权限矩阵（管理员/super_admin fast path）

下一步行动

详见 docs/PHASE2_PLAN.md：

1. P0: PostgreSQL迁移 + Redis集成 + Service测试覆盖率提升
2. P1: Agent Availability + Email/Meta渠道 + Swagger文档
3. P2: 索引优化 + 缓存层 + 连接池
4. P3: Prometheus + CI/CD + Kubernetes + OpenTelemetry

---

交接日期: 2026-05-23 项目状态: 阶段一（P1-P15）全部完成 ✅ 全量验证: build ✅ | vet ✅ | unit ✅ | e2e ✅ | benchmark ✅