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