niuniu/ai-customer-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b796653a9333699450b10eb46e8fa523aaf93e7e
ai-customer-service/docs/PRODUCTION_LAUNCH.md

226 lines
8.0 KiB
Markdown
Raw Normal View History

docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
# AI-Customer-Service 生产上线文档
> 版本：v1.0 | 日期：2026-05-01
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
> 状态：⚠️ 代码级主链已通过验证，但预生产与灰度门禁尚未闭环
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
> 代码基准：`3e9022a`（`upload/ai-customer-service` 分支）
---
## 1. 项目概述
**项目名**：ai-customer-service（立交桥智能客服系统）
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
**一句话**：当前交付物是面向生产一期的客服后端最小闭环服务，覆盖 webhook、会话、转人工工单、审计与健康检查。
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
**当前已验证能力**：
- 统一 Webhook 入口与按路径覆写 channel 的入口
- 基于规则的意图识别与静态 FAQ 回复
- 自动转人工工单最小闭环（创建→分配→解决→关闭）
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
- 审计日志持久化
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
- PostgreSQL 持久化、健康检查、优雅停机
**当前未完成但属于后续目标能力**：
- 真实 LLM 意图识别与多供应商 failover
- 真实 RAG 检索与知识库运营
- 完整多渠道适配器产品化
- 运营后台 UI 与完整 RBAC
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
---
## 2. 技术架构
**技术栈**：Go 1.22 + PostgreSQL + HTTP/REST
**二进制**：`cmd/ai-customer-service`
**模块结构**：
```
internal/
├── app/ # 应用入口、graceful shutdown
├── config/ # 配置加载（环境变量驱动）
├── domain/ # 领域模型（ticket、session、intent、message、audit）
├── http/
│ ├── router.go # HTTP 路由注册
│ └── handlers/ # HTTP Handler（webhook/session/ticket/health/stats）
├── platform/
│ ├── httpx/ # HTTP 扩展（BodyLimit、速率限制）
│ ├── logging/ # 结构化日志（slog）
│ └── health/ # 健康检查探针
└── service/
├── dialog/ # 对话引擎（Process 主流程）
├── intent/ # 意图识别
├── handoff/ # 转人工
└── reply/ # 回复生成
store/
├── memory/ # 内存存储（测试/开发用）
└── postgres/ # PostgreSQL 持久化（生产用）
```
---
## 3. API 接口清单
### 3.1 Webhook（外部消息入口）
| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| POST | `/api/v1/customer-service/webhook` | 统一 Webhook 入口 | ✅ 已实现 |
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
| POST | `/api/v1/customer-service/webhook/{channel}` | 按路径指定 channel 的 Webhook 入口 | ✅ 已实现 |
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
**安全特性**：HMAC-SHA256 签名校验 + 时间戳防重放 + BodyLimit 512KB + 速率限制（滑动窗口 10 req/s/IP）
### 3.2 会话管理
| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| POST | `/sessions/{id}/handoff` | 手动转人工 | ✅ 已实现 |
| POST | `/sessions/{id}/feedback` | 用户反馈提交 | ✅ 已实现 |
### 3.3 工单管理
| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| GET | `/tickets` | 工单列表（分页） | ✅ 已实现 |
| GET | `/tickets/{id}` | 工单详情 | ✅ 已实现 |
| POST | `/tickets/{id}/assign` | 工单分配（agent_id） | ✅ 已实现 |
| POST | `/tickets/{id}/resolve` | 工单解决 | ✅ 已实现 |
| POST | `/tickets/{id}/close` | 工单关闭 | ✅ 已实现（audit 已接入） |
### 3.4 运营与健康
| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| GET | `/actuator/health` | 综合健康检查 | ✅ 已实现 |
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
| GET | `/actuator/health/live` | Liveness 探针 | ✅ 已实现 |
| GET | `/actuator/health/ready` | Readiness 探针（含 DB 依赖检查） | ✅ 已实现 |
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
| GET | `/tickets/stats` | 工单统计（open/assigned/resolved） | ✅ 已实现 |
---
## 4. 质量验证结果
### 4.1 测试覆盖率（Phase 2 目标达成）
| 包 | 覆盖率 | Phase 2 目标 | 状态 |
|----|--------|-------------|------|
| internal/http/handlers | **87.1%** | >85% | ✅ |
| internal/service/dialog | **88.5%** | >85% | ✅ |
| internal/platform/httpx | **84.3%** | >70% | ✅ |
| internal/config | **82.4%** | >70% | ✅ |
| internal/app | **73.8%** | >70% | ✅ |
| internal/store/postgres | **62.0%** | >60% | ✅ |
| internal/store/memory | **88.3%** | >85% | ✅ |
| internal/platform/logging | **100%** | — | ✅ |
| internal/service/intent | **100%** | — | ✅ |
| internal/service/handoff | **100%** | — | ✅ |
| internal/platform/health | **100%** | — | ✅ |
| **整体覆盖率** | **77.4%** | >70% | ✅ |
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
### 4.2 当前门禁结论
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
| 门禁层级 | 状态 | 说明 |
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
|---------|------|------|
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
| 代码级门禁 | ✅ 通过 | `go test ./...`、`go test -race ./...`、`go build ./...` 通过 |
| 预生产门禁 | ⚠️ 未闭环 | 真实环境 DB/migration/webhook/audit/ticket 入库验证仍需证据化 |
| 灰度门禁 | ❌ 未通过 | 鉴权、最小监控、灰度阈值、回滚演练未闭环 |
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
**当前解释口径**：仓库内测试通过，只能证明现有实现稳定，不等于“PRD 功能已完成”或“可直接灰度发布”。
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
### 4.3 安全审计
| 检查项 | 结果 |
|--------|------|
| 硬编码密钥/Token | ✅ 未发现 |
| SQL 注入 | ✅ 参数化查询，无拼接 |
| Audit 写入失败 | ✅ P0 标准：只 log，不阻流 |
| Context 超时 | ✅ 有限 timeout 上下文 |
| 数据竞争 | ✅ gorace 无警告 |
### 4.4 死代码修复记录
**问题**：`auditTicketChange`（ticket_handler.go:104）定义但从未调用，导致 Assign/Resolve/Close 状态变更缺少 handler 层审计。
**修复**：将 `auditTicketChange` 接入 Assign/Resolve/Close 成功后调用，新增 `actorID` 参数。
**Commit**：`3e9022a`
---
## 5. 部署指南
### 5.1 构建 Docker 镜像
```bash
# 项目根目录执行
docker build -t ai-customer-service:v1.0.0 .
# 或使用 Makefile
make test # 运行测试
make run # 本地运行（go run）
```
### 5.2 环境变量配置
| 变量 | 说明 | 示例 |
|------|------|------|
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
| `AI_CS_RUNTIME_ENV` | 运行环境 | `production` |
| `AI_CS_ADDR` | HTTP 监听地址 | `:8080` |
| `AI_CS_POSTGRES_ENABLED` | 是否启用 PostgreSQL store | `true` |
| `AI_CS_POSTGRES_DSN` | PostgreSQL 连接串 | `postgres://ai_cs:***@localhost:5432/ai_customer_service?sslmode=disable` |
| `AI_CS_POSTGRES_MIGRATION_DIR` | migration 目录 | `db/migration` |
| `AI_CS_WEBHOOK_SECRET` | Webhook HMAC 密钥 | — |
| `AI_CS_WEBHOOK_TIMESTAMP_HEADER` | 时间戳请求头 | `X-CS-Timestamp` |
| `AI_CS_WEBHOOK_SIGNATURE_HEADER` | 签名请求头 | `X-CS-Signature` |
| `AI_CS_WEBHOOK_MAX_SKEW_SECONDS` | 最大时钟偏差（秒） | `300` |
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
### 5.3 数据库初始化
```bash
# 执行 migration（项目 db/ 目录）
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
psql "$AI_CS_POSTGRES_DSN" -f db/migration/0001_init.up.sql
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
```
### 5.4 健康检查
```bash
# Readiness（含 DB 依赖检查）
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
curl http://localhost:8080/actuator/health/ready
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
# Liveness
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
curl http://localhost:8080/actuator/health/live
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
# 综合健康
curl http://localhost:8080/actuator/health
```
---
## 6. 仓库分布
| Remote | 仓库地址 | 分支 | 最新 Commit |
|--------|---------|------|------------|
| GitHub | `https://github.com/phamnazage-jpg/lijiaoqiao` | `upload/ai-customer-service` | `3e9022a` ✅ |
| Gitea | `http://localhost:3000/shenyi/lijiaoqiao` | `upload/ai-customer-service` | `3e9022a` ✅ |
| TKSea | `https://tksea.top/niuniu/lijiaoqiao` | `upload/ai-customer-service` | `3e9022a` ✅ |
**三端已同步。**
---
## 7. 已知限制（P1 后续迭代）
以下功能在本版本未实现，如需请在 P1 中补充：
| 功能 | 优先级 | 说明 |
|------|--------|------|
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
| 真实多渠道适配器产品化 | P1 | 当前只有统一 webhook 模型与路径覆写 channel |
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
| 人工回复用户链路 | P1 | 只有工单创建，无回复闭环 |
| 排队位置查询 | P1 | 无此 API |
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
| 真实 LLM / RAG | P1 | 当前为规则识别 + 静态 FAQ |
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
| 安全拒绝事件审计（签名失败/非法 body） | P0 | 此类事件暂未写审计 |
| metrics / tracing / SLO | P1 | 暂无可观测基础设施 |
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
| 灰度/回滚 Runbook | P1 | 需完成演练与证据化验证 |
docs: 新增生产上线文档 PRODUCTION_LAUNCH.md 包含：项目概述、技术架构、API 清单、质量验证结果、部署指南、仓库分布、已知限制
2026-05-01 16:51:16 +08:00
---
## 8. 关键联系人
- **项目负责人**：小龙团队（Hermes Review 完成）
- **代码基准**：`3e9022a`
fix(audit): use uuid.New() for ticket workflow audit IDs Fixes 'invalid input syntax for type uuid' error when writing ticket workflow audit logs. The audit Event.ID field was using fmt.Sprintf with nanoseconds ('wf-%d') which doesn't match PostgreSQL's uuid type. Also adds uuid import to ticket_workflow.go. Verified: full chain webhook→assign→resolve→close produces 3 audit logs correctly, no more 'invalid uuid' errors in logs.
2026-05-04 13:44:39 +08:00
- **Phase 2 覆盖率目标**：✅ 已达成（77.4% > 70%）
Reference in New Issue Copy Permalink