156 lines
4.8 KiB
Markdown
156 lines
4.8 KiB
Markdown
# AI Customer Service
|
||
|
||
AI customer service service focused on secure webhook ingress, dialog routing, handoff ticket flow, auditability, and platform adapter delivery.
|
||
|
||
当前仓库已经从 monorepo 独立拆出，适合作为单独服务持续演进，不再与 `立交桥` 主仓共享日常开发节奏。
|
||
|
||
## 当前状态
|
||
|
||
- 已具备最小客服主链：`webhook -> session -> intent -> reply/handoff -> ticket -> audit`
|
||
- 已具备 PostgreSQL 持久化、migration、health、HMAC webhook 安全校验
|
||
- 已具备 `Sub2API` 第一版平台适配：
|
||
- 平台入口
|
||
- 平台事件 outbox
|
||
- callback worker
|
||
- retry / dead letter
|
||
- integration / e2e 覆盖
|
||
- `NewAPI` 当前仍是同构占位 profile，返回 `501 profile not implemented`
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- Go `1.22+`
|
||
- PostgreSQL
|
||
- 可选：本地测试库 `host=localhost port=5434 user=ai_cs password=ai_cs_secret dbname=ai_customer_service sslmode=disable`
|
||
|
||
### 本地运行
|
||
|
||
最小内存模式：
|
||
|
||
```bash
|
||
AI_CS_RUNTIME_ENV=test \
|
||
go run ./cmd/ai-customer-service
|
||
```
|
||
|
||
PostgreSQL 模式：
|
||
|
||
```bash
|
||
AI_CS_RUNTIME_ENV=development \
|
||
AI_CS_POSTGRES_ENABLED=true \
|
||
AI_CS_POSTGRES_DSN="host=localhost port=5434 user=ai_cs password=ai_cs_secret dbname=ai_customer_service sslmode=disable" \
|
||
AI_CS_POSTGRES_MIGRATION_DIR="./db/migration" \
|
||
go run ./cmd/ai-customer-service
|
||
```
|
||
|
||
平台适配层示例配置：
|
||
|
||
```bash
|
||
cp .env.platform-adapters.example .env.platform-adapters.local
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
make test
|
||
make run
|
||
go test ./... -count=1 -p 1
|
||
go test -race ./... -p 1
|
||
go vet ./...
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
| 路径 | 说明 |
|
||
|---|---|
|
||
| `cmd/ai-customer-service` | 服务启动入口 |
|
||
| `internal/app` | 应用装配、server、worker 启动 |
|
||
| `internal/http` | 路由、handler、中间件 |
|
||
| `internal/service/dialog` | 主对话链路 |
|
||
| `internal/platformadapter` | 平台入口适配器 |
|
||
| `internal/service/platformevents` | 平台事件构建 |
|
||
| `internal/service/platformdelivery` | callback signer / worker |
|
||
| `internal/store/postgres` | PostgreSQL 持久化实现 |
|
||
| `db/migration` | schema migration |
|
||
| `docs/` | runbook、review、上线门禁、验证记录 |
|
||
| `prd/` | 产品范围、SLA、流程约束 |
|
||
| `test/` | integration / e2e 测试 |
|
||
|
||
## 核心接口
|
||
|
||
基础 webhook：
|
||
|
||
- `POST /api/v1/customer-service/webhook`
|
||
- `POST /api/v1/customer-service/webhook/{channel}`
|
||
|
||
平台入口：
|
||
|
||
- `POST /api/v1/customer-service/platforms/sub2api/webhook`
|
||
- 后续预留：`POST /api/v1/customer-service/platforms/newapi/webhook`
|
||
|
||
健康检查：
|
||
|
||
- `GET /actuator/health`
|
||
- `GET /actuator/health/live`
|
||
- `GET /actuator/health/ready`
|
||
|
||
## 配置
|
||
|
||
真实配置契约以这里为准：
|
||
|
||
- [docs/CONFIG_CONTRACT_BASELINE.md](docs/CONFIG_CONTRACT_BASELINE.md)
|
||
- [.env.platform-adapters.example](.env.platform-adapters.example)
|
||
|
||
如果要做平台联调，先看：
|
||
|
||
- [docs/SUB2API_MINIMAL_WEBHOOK_MAPPING.md](docs/SUB2API_MINIMAL_WEBHOOK_MAPPING.md)
|
||
- [docs/RUNBOOK_PLATFORM_CALLBACKS.md](docs/RUNBOOK_PLATFORM_CALLBACKS.md)
|
||
|
||
## 发布与验证
|
||
|
||
当前推荐的验证顺序：
|
||
|
||
1. `go test ./... -count=1 -p 1`
|
||
2. `go test -race ./... -p 1`
|
||
3. `go vet ./...`
|
||
4. `bash -n scripts/verify_preprod_gate_b.sh`
|
||
5. `bash -n scripts/verify_gate_c_rollback.sh`
|
||
|
||
灰度与回滚相关文档：
|
||
|
||
- [docs/GRAY_LAUNCH_CHECKLIST.md](docs/GRAY_LAUNCH_CHECKLIST.md)
|
||
- [docs/PREPROD_VERIFICATION_RECORD.md](docs/PREPROD_VERIFICATION_RECORD.md)
|
||
- [docs/ROLLBACK_DRILL_RECORD.md](docs/ROLLBACK_DRILL_RECORD.md)
|
||
|
||
## 协作约定
|
||
|
||
- 提交使用 Conventional Commits
|
||
- 仓库审阅归属见 [.github/CODEOWNERS](.github/CODEOWNERS)
|
||
- PR 会自动执行基础 CI：
|
||
GitHub 执行 `go test ./... -count=1`、`go test -race ./...`、`go vet ./...`、Gate 脚本语法检查；
|
||
Gitea/TKSea 因共享测试库约束，执行 `go test ./... -count=1 -p 1`、`go test -race ./... -p 1`、`go vet ./...`、Gate 脚本语法检查
|
||
- GitHub 使用 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)，Gitea/TKSea 使用 [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml)
|
||
- `workflow` 名称和 `verify` job 名称属于受保护契约。当前分支保护依赖这两个状态上下文：
|
||
`CI / verify (push)`、`CI / verify (pull_request)`；不要随意改名
|
||
- 本地默认共享 PostgreSQL 测试库，所以本地验证命令统一使用 `-p 1` 串行执行，避免跨包并发污染测试表
|
||
- 变更配置契约时，必须同步更新：
|
||
- `docs/CONFIG_CONTRACT_BASELINE.md`
|
||
- `test/QA_GATE_STATUS.md`
|
||
- 相关 runbook / plan 文档
|
||
- 不要把“测试通过”直接写成“可生产上线”，门禁口径必须区分代码级、预生产级和灰度放量级
|
||
- 贡献方式和 PR 校验要求见 [CONTRIBUTING.md](CONTRIBUTING.md)
|
||
|
||
## 提问题
|
||
|
||
请优先使用仓库内置 issue 模板：
|
||
|
||
- Bug Report
|
||
- Feature Request
|
||
|
||
提交问题前建议附上：
|
||
|
||
- 运行环境
|
||
- 复现步骤
|
||
- 预期结果 / 实际结果
|
||
- 相关日志或失败命令
|