docs(repo): add readme and issue templates

2026-05-06 11:11:08 +08:00
parent dbf88bea07
commit 5b3c38b3ed
4 changed files with 279 additions and 0 deletions
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ 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
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ 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: 配置、环境变量和运行参数以这里为准。
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ 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
--- a/README.md
+++ 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
+
+提交问题前建议附上：
+
+- 运行环境
+- 复现步骤
+- 预期结果 / 实际结果
+- 相关日志或失败命令