diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..e84f532 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,62 @@ +name: Bug Report +description: 报告一个可复现的缺陷、回归或运行异常 +title: "[Bug] " +labels: + - bug +body: + - type: textarea + id: summary + attributes: + label: 问题描述 + description: 简洁说明问题是什么，影响了什么。 + placeholder: 描述实际发生的问题。 + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: 复现步骤 + description: 用最短路径说明如何稳定复现。 + placeholder: | + 1. 执行 ... + 2. 调用 ... + 3. 观察 ... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: 预期结果 + placeholder: 描述本来应该发生的行为。 + validations: + required: true + + - type: textarea + id: actual + attributes: + label: 实际结果 + placeholder: 描述实际发生的行为、错误码、异常输出。 + validations: + required: true + + - type: textarea + id: env + attributes: + label: 环境信息 + description: 尽量包含分支、提交号、配置模式、数据库模式、平台适配模式。 + placeholder: | + commit: ... + env: development/test/production + postgres: enabled/disabled + adapter: sub2api/newapi/off + validations: + required: true + + - type: textarea + id: logs + attributes: + label: 日志 / 截图 / 失败输出 + description: 粘贴最关键的片段，不要只说“报错了”。 + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..024318a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Platform callback runbook + url: https://github.com/phamnazage-jpg/ai-customer-service/blob/main/docs/RUNBOOK_PLATFORM_CALLBACKS.md + about: 先看 callback 排障与重放说明，再决定是否提 issue。 + - name: Config contract baseline + url: https://github.com/phamnazage-jpg/ai-customer-service/blob/main/docs/CONFIG_CONTRACT_BASELINE.md + about: 配置、环境变量和运行参数以这里为准。 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..a7472e2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,63 @@ +name: Feature Request +description: 提出新的功能、适配增强、运维能力或产品需求 +title: "[Feature] " +labels: + - enhancement +body: + - type: textarea + id: background + attributes: + label: 背景与目标 + description: 说明为什么需要这个能力，它解决什么问题。 + placeholder: 描述业务背景、技术背景或当前痛点。 + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: 建议方案 + description: 说明你希望系统怎么表现，尽量写清边界。 + placeholder: 描述期望的接口、配置、行为或交付结果。 + validations: + required: true + + - type: textarea + id: scope + attributes: + label: 范围与非目标 + description: 说明这次应该做什么，不应该顺手做什么。 + placeholder: | + In scope: + - ... + Out of scope: + - ... + + - type: textarea + id: acceptance + attributes: + label: 验收标准 + description: 给出可验证的完成标准。 + placeholder: | + 1. ... + 2. ... + 3. ... + validations: + required: true + + - type: dropdown + id: area + attributes: + label: 影响范围 + options: + - Webhook ingress + - Dialog / ticket flow + - Sub2API adapter + - NewAPI adapter + - Callback delivery + - PostgreSQL / schema + - Docs / runbook + - QA / verification + - Other + validations: + required: true diff --git a/README.md b/README.md new file mode 100644 index 0000000..7e604a6 --- /dev/null +++ b/README.md @@ -0,0 +1,146 @@ +# 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 +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](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` +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/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 +- 变更配置契约时，必须同步更新： + - `docs/CONFIG_CONTRACT_BASELINE.md` + - `test/QA_GATE_STATUS.md` + - 相关 runbook / plan 文档 +- 不要把“测试通过”直接写成“可生产上线”，门禁口径必须区分代码级、预生产级和灰度放量级 + +## 提问题 + +请优先使用仓库内置 issue 模板： + +- Bug Report +- Feature Request + +提交问题前建议附上： + +- 运行环境 +- 复现步骤 +- 预期结果 / 实际结果 +- 相关日志或失败命令