first commit

2026-06-04 15:42:28 +08:00
commit 4db6efb3a7
1 changed files with 191 additions and 0 deletions
@@ -0,0 +1,191 @@
+# GoChat
+
+> 开源企业级即时通讯平台，参考 Chatwoot 架构，Go 语言实现。
+
+## 项目概览
+
+| 指标 | 数值 |
+|------|------|
+| Go 源码文件 | 299 |
+| 测试文件 | 83 |
+| 测试用例 | 141+ |
+| API 路由 | 106 |
+| Go 包 | 42 |
+| 安全模块 | 14 |
+
+## 架构
+
+GoChat 采用 **分层架构** + **模块化设计**：
+
+```
+cmd/                    # 入口（migrate, server）
+internal/
+  app/                  # 应用启动、graceful shutdown
+  auth/                 # JWT认证、Refresh Token、TOTP
+  autoassignment/       # 智能分配
+  channel/provider/     # 渠道抽象层（Telegram/WebWidget/Email）
+  config/               # Viper多环境热加载配置
+  handler/api/v1/       # HTTP Handler（Gin，104+路由）
+  llm/                  # CaptainAI LLM Provider（OpenAI/Ollama/volcengine）
+  middleware/           # Auth/CORS/RateLimiting/AccountScope/InputValidation
+  model/                # GORM 数据模型（Base/Account/User/Contact/Inbox等）
+  pubsub/               # Redis Pub/Sub
+  repository/           # 数据访问层（21 repo）
+  service/              # 业务逻辑层
+  ws/                   # WebSocket Hub（/cable）
+pkg/
+  crypto/               # bcrypt Hash/Check
+  validation/           # go-playground/validator/v10 自定义规则
+tests/
+  e2e/                  # 端到端测试（Auth/AccountCRUD/CRM）
+```
+
+## 快速开始
+
+### 前置依赖
+
+- Go 1.25+
+- PostgreSQL 16（带 pgvector）
+- Redis 7+
+- Docker（可选）
+
+### 本地开发
+
+```bash
+# 克隆项目
+git clone https://github.com/gochat/gochat.git
+cd gochat
+
+# 安装依赖
+go mod download
+
+# 配置环境
+cp .env.example .env
+# 编辑 .env 配置数据库、Redis、JWT等
+
+# 运行服务
+go run cmd/server/main.go
+
+# 运行测试（SQLite模式，无需PG）
+GOCHAT_TEST_DB=sqlite go test ./internal/... ./pkg/... ./cmd/...
+
+# 运行测试（PG模式）
+go test -v -race ./...
+
+# 运行e2e测试
+go test -v ./tests/e2e/...
+```
+
+### Docker 部署
+
+```bash
+# 构建镜像
+docker build -t gochat/gochat:latest .
+
+# 使用 docker-compose
+docker compose up -d
+```
+
+## 环境配置
+
+GoChat 使用 **Viper 多环境叠加**机制：
+
+- `configs/default.yaml` — 默认配置
+- `configs/production.yaml` — 生产覆盖
+- `configs/development.yaml` — 开发覆盖
+- `.env` — 本地覆盖（最高优先级）
+- 11 个字段支持 **热加载**（无需重启）
+
+详见 [PHASE2_P0_ENV_CONFIG.md](docs/PHASE2_P0_ENV_CONFIG.md)
+
+## API 路由
+
+核心 API 路由106个，覆盖 Chatwoot API 97%+：
+
+| 模块 | 路由前缀 | 说明 |
+|------|----------|------|
+| Auth | `/api/v1/auth/` | 登录、注册、刷新、TOTP |
+| Accounts | `/api/v1/accounts/` | 企业账号 CRUD |
+| Contacts | `/api/v1/accounts/:id/contacts/` | 客户联系人 CRM |
+| Inboxes | `/api/v1/accounts/:id/inboxes/` | 渠道收件箱 |
+| Conversations | `/api/v1/accounts/:id/conversations/` | 会话管理 |
+| Messages | `/api/v1/accounts/:id/conversations/:conversation_id/messages/` | 消息 |
+| CaptainAI | `/api/v1/accounts/:id/captain/` | AI助手、文档、场景 |
+| Reports | `/api/v1/accounts/:id/reports/` | 报表统计 |
+| Teams | `/api/v1/accounts/:id/teams/` | 团队管理 |
+| WebWidget | `/api/v1/accounts/:id/inboxes/:inbox_id/web_widget/` | 网页客服 |
+| Telegram | `/api/v1/accounts/:id/telegram/` | Telegram渠道 |
+| WebSocket | `/cable` | 实时消息推送 |
+| Health | `/health` | 健康检查 |
+
+详见 [API_COVERAGE_REPORT.md](docs/API_COVERAGE_REPORT.md)
+
+## 测试策略
+
+| 层级 | 工具 | 覆盖 |
+|------|------|------|
+| 单元测试 | Go test + testify | Service/Repository/Model/Auth/Config |
+| 集成测试 | Go test + GORM | Service↔Repository↔DB |
+| E2E测试 | httptest + Gin | Handler↔Service↔DB 全链路 |
+| 安全测试 | golangci-lint + gosec + govulncheck | 代码安全扫描 |
+| 性能测试 | Go benchmark | Service/crypto基准 |
+| DB双模式 | PG + SQLite | `GOCHAT_TEST_DB` 自动切换 |
+
+PG-only功能（vector搜索等）使用 `skipIfSQLite` 自动跳过。
+
+## 安全
+
+- **Rate Limiting**: per-IP 令牌桶（golang.org/x/time/rate）
+- **输入验证**: go-playground/validator/v10 + 4自定义规则
+- **SQL注入防护**: GORM参数化查询
+- **CORS**: 生产白名单配置
+- **JWT**: RS256签名 + Refresh Token Rotation
+- **TOTP**: 双因子认证
+- **Password**: bcrypt hash
+
+详见 [SECURITY_AUDIT_REPORT.md](docs/SECURITY_AUDIT_REPORT.md)
+
+## CI/CD
+
+GitHub Actions 5阶段流水线：
+
+1. **Test & Lint**: lint + vet + 单元/集成/e2e/benchmark（PG+SQLite矩阵）
+2. **Security Scan**: gosec + govulncheck + Trivy
+3. **Build**: Docker多平台镜像 + GHCR推送
+4. **Helm Validate**: K8s Helm chart lint + kubeconform
+5. **Deploy**: Staging（develop分支）+ Production（release分支）
+
+详见 [.github/workflows/ci.yml](.github/workflows/ci.yml)
+
+## 技术栈
+
+| 组件 | 技术 |
+|------|------|
+| 语言 | Go 1.25 |
+| HTTP框架 | Gin v1.10 |
+| ORM | GORM v2 |
+| 数据库 | PostgreSQL 16 + pgvector |
+| 缓存 | Redis 7 |
+| 认证 | JWT (RS256) + bcrypt + TOTP |
+| 配置 | Viper + .env |
+| WebSocket | Gorilla WebSocket |
+| 验证 | go-playground/validator/v10 |
+| 限流 | golang.org/x/time/rate |
+| LLM | OpenAI / Ollama / volcengine |
+| 容器 | Docker + Buildx |
+| K8s | Helm chart |
+
+## 文档
+
+- [架构设计](docs/architecture/) — 架构总览、对比分析
+- [API覆盖报告](docs/API_COVERAGE_REPORT.md) — 106路由 vs Chatwoot
+- [安全审计](docs/SECURITY_AUDIT_REPORT.md) — 14安全模块
+- [性能基准](docs/PERFORMANCE_BENCHMARK.md) — benchmark数据
+- [集成验证](docs/INTEGRATION_VERIFICATION_REPORT.md) — 模块集成测试
+- [环境配置](docs/PHASE2_P0_ENV_CONFIG.md) — Viper热加载
+- [交接文档](docs/HANDOVER_DOCUMENT.md) — 项目交接
+- [阶段计划](docs/PHASE2_PLAN.md) — Phase 2规划
+
+## License
+
+MIT