cf46b27610
P0-1 (limits.go): Allow()方法改为全程使用写锁保护counters map读写，避免RLock写入时的data race P0-2 (ticket_workflow.go+ticket_handler.go): Assign/Resolve/Close操作先查询ticket存在性和状态，返回明确的CS_TICKET_4001/CS_TKT_4002/CS_TICKET_4092/CS_TICKET_4093错误码，handler根据错误前缀路由HTTP状态码 P1-1 (ticket_store.go): 移除GetStats中3处手动rows.Close()，只保留defer Close()
117 lines
5.1 KiB
Markdown
117 lines
5.1 KiB
Markdown
# 生产一期范围与门禁定义
|
||
|
||
> 版本：v1.0 | 状态：已生效
|
||
> 关联：PRODUCTION_EXECUTION_PLAN.md、PRODUCTION_PHASE1_STATUS.md、tech/INTERFACE.md
|
||
|
||
---
|
||
|
||
## 1. 生产一期目标定位
|
||
|
||
生产一期是 ai-customer-service 从原型验证到生产可用的第一步。目标不是功能完备，而是**入口安全、闭环真实、运维可控**，在有限范围内做到生产级别质量。
|
||
|
||
---
|
||
|
||
## 2. 已落地能力（生产一期基线）
|
||
|
||
以下能力已在代码中实现并通过验证：
|
||
|
||
| 能力 | 代码位置 | 说明 |
|
||
|------|----------|------|
|
||
| webhook HMAC 签名校验 | `internal/http/handlers/webhook_security.go` | HMAC-SHA256，skew 校验 |
|
||
| 时间戳防重放 | `internal/http/handlers/webhook_security.go` | skew window 内有效 |
|
||
| 消息幂等去重 | `internal/store/postgres/dedup_store.go` | `(channel, message_id)` 去重 |
|
||
| 工单创建 | `internal/service/dialog/service.go` | 退款/敏感意图触发转人工 |
|
||
| 工单持久化 | `internal/store/postgres/ticket_store.go` | PostgreSQL |
|
||
| 工单列表/分配/解决 | `internal/http/handlers/ticket_handler.go` | `GET /tickets`、`POST /assign`、`POST /resolve` |
|
||
| 审计日志持久化 | `internal/store/postgres/audit_store.go` | 写入 `cs_audit_logs`，fail-closed |
|
||
| 健康检查 | `internal/http/handlers/health_handler.go` | `/live`、`/ready`（含 PostgreSQL 依赖检查） |
|
||
| 请求体大小限制 | `internal/platform/httpx/limits.go` | 全局 BodyLimit 配置 |
|
||
| JSON Schema 校验 | `internal/http/handlers/webhook_handler.go` | 最小字段必填与 unknown field 拒绝 |
|
||
| graceful shutdown | `internal/app/app.go` | 优雅停机 |
|
||
|
||
---
|
||
|
||
## 3. 生产一期明确排除范围
|
||
|
||
以下能力**不在生产一期范围内**，不作为阶段完成的阻塞项：
|
||
|
||
- 人工回复用户链路（人工客服 → 用户消息推送）
|
||
- 排队位置查询
|
||
- webhook 速率限制
|
||
- metrics / tracing / SLO 监控面板
|
||
- 知识库 CRUD / 发布 / 审核
|
||
- WebSocket 实时会话
|
||
- 多租户隔离
|
||
- 外部系统（NewAPI/Sub2API）深度集成
|
||
|
||
---
|
||
|
||
## 4. 剩余 P0 缺口（门禁必须项）
|
||
|
||
在以下 P0 缺口**全部收口**前，不得将项目状态汇报为"生产一期完成"：
|
||
|
||
### P0-1：工单状态流转审计
|
||
- **当前状态**：✅ 已落地，`TicketWorkflowStore` 在 Assign/Resolve/Close 时均调用 `writeAudit`
|
||
- **代码位置**：`internal/store/postgres/ticket_workflow.go`
|
||
- **记录内容**：before_state（隐式）/ after_state（显式）、actor_id、source_ip、action（assign/resolve/close）
|
||
|
||
### P0-2：安全拒绝事件审计
|
||
- **当前状态**：✅ 已落地，`WebhookSecurity.auditReject` 在签名缺失/无效/过期/body 读取失败时均写入审计
|
||
- **代码位置**：`internal/http/handlers/webhook_security.go`
|
||
- **记录内容**：Type=`webhook_security_rejected`，Action=`security_reject`，error_code、path、timestamp 等信息
|
||
|
||
### P0-3：工单关闭语义明确
|
||
- **当前状态**：只有 resolve，没有 close 语义
|
||
- **要求**：工单关闭语义明确为 resolve=已解决关闭，或补充 close 接口
|
||
- **代码位置**：`internal/http/handlers/ticket_handler.go`
|
||
|
||
### P0-4：Webhook 路由对齐
|
||
- **当前状态**：已落地统一入口 `/api/v1/customer-service/webhook`
|
||
- **INTERFACE.md 定义**：`/api/v1/customer-service/webhook/{channel}`（按渠道独立入口）
|
||
- **当前方案**：统一入口通过 Query/Body 中的 `channel` 字段识别渠道，与 INTERFACE 定义兼容，无需路由拆分
|
||
- **说明**：生产一期采用统一入口简化运维；如后续渠道量增加，可扩展为 `/webhook/{channel}` 路径
|
||
|
||
---
|
||
|
||
## 5. 门禁检查表
|
||
|
||
### Gate A：允许进入生产底座实现
|
||
- [x] 生产一期范围文档已建立（本文档）
|
||
- [x] PM / TechLead / QA 对范围达成一致
|
||
- [ ] TechLead 生产架构方案已冻结
|
||
|
||
### Gate B：允许联调前
|
||
- [x] webhook 签名、防重放、幂等、鉴权、审计 fail-closed 已具备
|
||
- [x] P0-1（工单状态流转审计）已落地
|
||
- [x] P0-2（安全拒绝事件审计）已落地
|
||
- [x] P0-3（工单关闭语义）已明确：resolve=已解决关闭，另有独立 close 接口支持
|
||
- [x] P0-4（Webhook 路由）已对齐：统一入口兼容 INTERFACE 定义
|
||
- [ ] OpenAPI 与实现一致（无漂移）
|
||
- [x] readiness 健康检查可真实阻断坏实例
|
||
- [ ] 关键失败路径自动化测试存在
|
||
|
||
### Gate C：允许灰度前
|
||
- [ ] P1 缺口（速率限制、人工回复链路、排队位置查询、metrics/tracing）明确完成或推迟计划
|
||
- [ ] 灰度/回滚 Runbook 已完成并演练
|
||
- [ ] 工单闭环真实可用
|
||
- [ ] 监控告警上线
|
||
|
||
---
|
||
|
||
## 6. 范围变更策略
|
||
|
||
任何范围变更（如新增功能、调低优先级）必须：
|
||
1. PM 提出书面变更申请
|
||
2. TechLead 评估技术影响
|
||
3. 三方（PM/TechLead/QA）签字确认
|
||
4. 更新本文档版本号
|
||
|
||
---
|
||
|
||
## 7. 当前版本状态
|
||
|
||
- **本文档版本**：v1.1
|
||
- **生效日期**：2026-04-30
|
||
- **更新内容**：P0-1（工单状态流转审计）、P0-2（安全拒绝事件审计）、P0-4（Webhook 路由对齐）已确认落地，更新门禁检查表状态
|
||
- **下次审查**：灰度前最终检查
|