ai-customer-service/README.md

# 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

提交问题前建议附上：

- 运行环境
- 复现步骤
- 预期结果 / 实际结果
- 相关日志或失败命令