Files

Your Name cf46b27610 fix: P0-1 RateLimiter并发写安全 + P0-2工单操作错误码区分 + P1 rows.Close修复

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

2026-05-01 20:56:25 +08:00

5.1 KiB

Raw Permalink Blame History

生产一期范围与门禁定义

版本：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：允许进入生产底座实现

生产一期范围文档已建立（本文档）
PM / TechLead / QA 对范围达成一致
TechLead 生产架构方案已冻结

Gate B：允许联调前

webhook 签名、防重放、幂等、鉴权、审计 fail-closed 已具备
P0-1（工单状态流转审计）已落地
P0-2（安全拒绝事件审计）已落地
P0-3（工单关闭语义）已明确：resolve=已解决关闭，另有独立 close 接口支持
P0-4（Webhook 路由）已对齐：统一入口兼容 INTERFACE 定义
OpenAPI 与实现一致（无漂移）
readiness 健康检查可真实阻断坏实例
关键失败路径自动化测试存在

Gate C：允许灰度前

P1 缺口（速率限制、人工回复链路、排队位置查询、metrics/tracing）明确完成或推迟计划
灰度/回滚 Runbook 已完成并演练
工单闭环真实可用
监控告警上线

6. 范围变更策略

任何范围变更（如新增功能、调低优先级）必须：

PM 提出书面变更申请
TechLead 评估技术影响
三方（PM/TechLead/QA）签字确认
更新本文档版本号

7. 当前版本状态

本文档版本：v1.1
生效日期：2026-04-30
更新内容：P0-1（工单状态流转审计）、P0-2（安全拒绝事件审计）、P0-4（Webhook 路由对齐）已确认落地，更新门禁检查表状态
下次审查：灰度前最终检查

5.1 KiB Raw Permalink Blame History Unescape Escape