156 lines
5.6 KiB
Markdown
156 lines
5.6 KiB
Markdown
# 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 # 数据库种子脚本
|
||
```
|
||
|
||
## 构建和运行
|
||
|
||
### 构建
|
||
```bash
|
||
GOPROXY=https://goproxy.cn,direct go build -ldflags "-X main.version=$(git describe --tags)" ./cmd/main.go
|
||
```
|
||
|
||
### 运行
|
||
```bash
|
||
# 开发模式
|
||
go run cmd/main.go
|
||
|
||
# Docker
|
||
docker build -t gochat .
|
||
docker run -p 8080:8080 gochat
|
||
```
|
||
|
||
### 测试
|
||
```bash
|
||
# 全量测试
|
||
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/
|
||
```
|
||
|
||
### 编译验证
|
||
```bash
|
||
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 ✅ |