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

本地运行

最小内存模式：

AI_CS_RUNTIME_ENV=test \
go run ./cmd/ai-customer-service

PostgreSQL 模式：

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

平台适配层示例配置：

cp .env.platform-adapters.example .env.platform-adapters.local

常用命令

make test
make run
go test ./... -count=1
go test -race ./...
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
• .env.platform-adapters.example

如果要做平台联调，先看：

• docs/SUB2API_MINIMAL_WEBHOOK_MAPPING.md
• docs/RUNBOOK_PLATFORM_CALLBACKS.md

发布与验证

当前推荐的验证顺序：

1. go test ./... -count=1
2. go test -race ./...
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/PREPROD_VERIFICATION_RECORD.md
• docs/ROLLBACK_DRILL_RECORD.md

协作约定

• 提交使用 Conventional Commits
• 仓库审阅归属见 .github/CODEOWNERS
• PR 会自动执行基础 CI： go test ./... -count=1、go test -race ./...、go vet ./...、Gate 脚本语法检查
• GitHub 使用 .github/workflows/ci.yml，Gitea/TKSea 使用 .gitea/workflows/ci.yml
• 变更配置契约时，必须同步更新：
  • docs/CONFIG_CONTRACT_BASELINE.md
  • test/QA_GATE_STATUS.md
  • 相关 runbook / plan 文档
• 不要把“测试通过”直接写成“可生产上线”，门禁口径必须区分代码级、预生产级和灰度放量级
• 贡献方式和 PR 校验要求见 CONTRIBUTING.md

提问题

请优先使用仓库内置 issue 模板：

• Bug Report
• Feature Request

提交问题前建议附上：

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