# 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）
frontend/               # Chatwoot Vue 3 前端（已从 Rails 解耦，独立 Vite SPA）
  app/javascript/       # Vue SPA 源码（dashboard/widget/sdk/portal/superadmin）
  index.html            # 静态入口（注入 window.chatwootConfig）
  vite.config.ts        # 标准 Vite 配置（dev server 代理 API 到 GoChat 后端）
  package.json          # @gochat/frontend（pnpm + Vite + Vue 3）
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)。

### 前端开发

前端已从 Chatwoot 的 Rails 耦合中解耦，现为独立的 Vite + Vue 3 SPA，直连 GoChat 后端。

```bash
# 仓库根目录统一启动
pnpm install              # 安装所有 workspace 依赖
pnpm dev:backend          # 启动 Go 后端（air 热重载，端口 3000）
pnpm dev:frontend         # 启动 Vite dev server（端口 3036，API 代理到 :3000）
pnpm dev                  # 同时启动前后端

# 单独构建前端
pnpm build:frontend       # 生产构建 → frontend/dist/

# 校验前端可重复交付基线
pnpm verify:frontend:delivery # frozen install + 构建产物检查 + 生产依赖 high/critical 漏洞扫描
```

前端交付以仓库提交的 `pnpm-lock.yaml` 为准；依赖变更必须同步提交 lockfile，交付前运行上述校验。
无锁重新解析会随 semver、peer 和可选平台依赖变化，不作为完整依赖图一致性目标。

Vite dev server 会将 `/api`、`/platform`、`/cable`、`/health` 代理到 GoChat 后端
（默认 `http://127.0.0.1:3000`，可通过 `VITE_API_HOST` 环境变量覆盖）。

## 环境配置

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

- `backend/configs/config.yaml` — 默认配置
- `backend/configs/config.production.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 全链路 |
| 性能测试 | 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)

## 技术栈

| 组件 | 技术 |
|------|------|
| 语言 | 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 |
| 部署 | Docker Compose |

## 文档

- [架构设计](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