# GoChat

> 开源企业级即时通讯平台，参考 Chatwoot 架构，Go 语言实现。

## 项目概览

| 指标 | 数值 |
|------|------|
| Go 源码文件 | 299 |
| 测试文件 | 83 |
| 测试用例 | 141+ |
| API 路由 | 106 |
| Go 包 | 42 |
| 安全模块 | 14 |

## 架构

GoChat 采用 **分层架构** + **模块化设计**：

```
backend/                # Go 后端（单仓库 monorepo 子目录）
  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 自定义规则
  configs/              # 多环境配置（config.yaml + config.{env}.yaml）
  migrations/           # SQL 迁移文件
  docs/                 # Swagger/OpenAPI 生成代码
  scripts/              # 迁移、种子、健康检查等脚本
  tests/
    e2e/                # 端到端测试（Auth/AccountCRUD/CRM）
deploy/                 # 部署相关
  docker/               # Dockerfile + docker-compose（dev/prod/test）
  quickstart/           # 本地/UAT 一键启动 Compose 栈
  fluentd/              # 日志收集配置
docs/                   # 项目文档（架构、需求、计划、报告）
```

## 快速开始

### 前置依赖

- Go 1.25+
- PostgreSQL 16（带 pgvector）
- Redis 7+
- Docker（可选）

### 本地开发

```bash
# 克隆项目
git clone https://github.com/gochat/gochat.git
cd gochat

# 安装依赖（在 backend/ 下）
cd backend
go mod download

# 配置环境（从仓库根目录复制）
cp ../.env.example ../.env
# 编辑 .env 配置数据库、Redis、JWT等

# 运行服务
go run cmd/gochat/main.go serve

# 运行测试（SQLite模式，无需PG）
GOCHAT_TEST_DB=sqlite go test ./internal/... ./pkg/... ./cmd/...

# 运行测试（PG模式）
go test -v -race ./...

# 运行e2e测试
go test -v ./tests/e2e/...
```

### Docker 部署

```bash
# 本地/UAT 快速启动：GoChat + PostgreSQL/pgvector + Redis + Meilisearch + Mailhog
cd deploy/quickstart
cp .env.example .env
docker compose up -d --build

# 可选：初始化演示账号和业务数据
docker compose --profile seed run --rm seed
```

详见 [deploy/quickstart/README.md](deploy/quickstart/README.md)。

## 环境配置

GoChat 使用 **Viper 多环境叠加**机制：

- `backend/configs/config.yaml` — 默认配置
- `backend/configs/config.prod.yaml` — 生产覆盖
- `backend/configs/config.dev.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