niuniu/ai-customer-service

Fork 0

Files

Your Name 67922c589a

CI / verify (push) Successful in 45s

Details

docs(ci): document protected status contexts

2026-05-06 12:46:22 +08:00

4.8 KiB

Raw Permalink Blame History

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 -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

配置

真实配置契约以这里为准：

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

发布与验证

当前推荐的验证顺序：

go test ./... -count=1 -p 1
go test -race ./... -p 1
go vet ./...
bash -n scripts/verify_preprod_gate_b.sh
bash -n scripts/verify_gate_c_rollback.sh

灰度与回滚相关文档：

协作约定

提交使用 Conventional Commits
仓库审阅归属见 .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，Gitea/TKSea 使用 .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

提问题

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

Bug Report
Feature Request

提交问题前建议附上：

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

4.8 KiB Raw Permalink Blame History Unescape Escape