306 lines
15 KiB
Markdown
306 lines
15 KiB
Markdown
# 架构决策：智能预约助手 M0 契约与数据模型
|
||
|
||
> 日期：2026-08-02<br>
|
||
> 状态：**Accepted / Batch 2 implemented — petstore-backend `3c00065`**<br>
|
||
> Workstream：`Core Booking Flow`<br>
|
||
> Track：`Architecture`<br>
|
||
> Priority：`P0`（独立试验流，不高于 RC6 真实门店基线）<br>
|
||
> Owner Agent：`System Architect`<br>
|
||
> Paired QA：`Core Flow QA`<br>
|
||
> Service Lock：`docs:booking-agent-m0-contract+ontology`<br>
|
||
> Architecture Review Required：`Yes — completed by this ADR`<br>
|
||
> Data Model Review Required：`Yes — proposal and implementation diff completed`<br>
|
||
> Access / Privacy Review Required：`Yes — development boundary accepted; live provider and production review pending`<br>
|
||
> RC Included：`No`
|
||
|
||
**关联资产**
|
||
|
||
- [产品与技术方案](./宠小它智能预约助手-产品与技术方案-v0.1.md)
|
||
- [M0 编码任务 brief](./智能预约助手-M0编码任务brief-2026-08-02.md)
|
||
- [M0 执行队列](./智能预约助手-M0执行队列-2026-08-02.md)
|
||
- [`booking-intent-v1` JSON Schema](./contracts/booking-intent-v1.schema.json)
|
||
- [M0 OpenAPI 契约](./contracts/booking-agent-m0.openapi.yaml)
|
||
- [模型与语音供应商选型](./智能预约助手-模型与语音供应商选型-2026-08-02.md)
|
||
|
||
## 1. 决策结论
|
||
|
||
M0 冻结为 **「已登录 customer 在已选门店范围内，用文字或语音生成已验证预约草稿，再回填现有普通预约表单」**。
|
||
|
||
冻结边界：
|
||
|
||
1. 门店不是模型槽位。宠主必须先在 `CustAppointmentCreate` 选定门店，创建会话时只提交 `storeId`，服务端验证门店存在。
|
||
2. 模型只输出通过 `booking-intent-v1` 校验的非权威文本约束，不输出或决定业务 ID、价格、服务事实、号源或预约状态。
|
||
3. 宠物、服务、日期时间和号源全部由 Petstore 后端在 `current.userId + session.storeId` 范围内重新解析。
|
||
4. M0 没有 `/confirm` endpoint，不调用 `AppointmentService.createBooking`，不修改 `Appointment` 表或状态机。
|
||
5. 「带入普通预约」只返回一次页面级回填数据；最终仍由现有 `/api/appointment/create` 提交。
|
||
6. 原始语音、当轮用户原文、模型请求/响应和完整对话不落库、不进业务事件、不进日志。
|
||
7. 功能开关默认关闭，不进入 `phase2-pilot-rc6`。
|
||
|
||
## 2. 为什么先选门店
|
||
|
||
原方案允许助手在对话内收集门店，但会同时引入门店名称歧义、地理推荐、跨店服务匹配和无门店 `BusinessEvent` 等问题。当前产品仍是单店 SaaS 试点，不需要把门店发现变成 Agent 能力。
|
||
|
||
M0 的次级入口仍位于 `CustAppointmentCreate`，行为调整为：
|
||
|
||
1. 未登录：先登录并返回原预约页；
|
||
2. 未选门店：先使用现有门店选择控件；
|
||
3. 已选有效门店：创建智能会话；
|
||
4. 会话内只解析该门店的服务与容量。
|
||
|
||
这样可以让每个 session 和漏斗事件都有明确 `storeId`，并阻止模型扩大门店数据范围。
|
||
|
||
## 3. `booking-intent-v1` 冻结
|
||
|
||
模型输出以 [`contracts/booking-intent-v1.schema.json`](./contracts/booking-intent-v1.schema.json) 为唯一机器契约。
|
||
|
||
### 3.1 字段语义
|
||
|
||
| 字段 | 语义 | 是否业务权威 |
|
||
|---|---|---|
|
||
| `schemaVersion` | 固定 `booking-intent-v1` | 是，仅契约版本 |
|
||
| `intent` | `book / modify / end / fallback` | 否，状态机重新判定 |
|
||
| `petQuery` | 宠物展示名搜索词 | 否 |
|
||
| `serviceQuery` | 服务名称/同义表达搜索词 | 否 |
|
||
| `dateExpression` | 用户日期表达 | 否 |
|
||
| `timeWindow` | `HH:mm` 起止偏好 | 否 |
|
||
| `remark` | 用户希望带入预约的短备注 | 否，可编辑且限 200 字 |
|
||
| `clearFields` | 用户明确要求清空的草稿字段 | 否，服务端只允许白名单字段 |
|
||
| `ambiguities` | 模型观察到的歧义类型 | 否，服务端重新确认 |
|
||
| `nextAction` | 下一步建议 | 否，编排器可忽略 |
|
||
|
||
### 3.2 强校验顺序
|
||
|
||
1. 响应体必须是单个 JSON object，不接受 Markdown fence 或前后说明文字；
|
||
2. JSON Schema 校验通过，未知字段拒绝；
|
||
3. 文本 trim、控制字符过滤和长度校验；
|
||
4. 输出出现任意 ID、价格、手机号、号源或预约状态字段时整个响应降级；
|
||
5. 服务端时间解析、归属解析和号源查询成功后才更新 `BookingDraft`；
|
||
6. 失败不尝试从残缺 JSON 猜字段，返回 `AGENT_UNAVAILABLE` 并保留旧草稿。
|
||
|
||
### 3.3 时间口径
|
||
|
||
- 时区固定 `Asia/Shanghai`；
|
||
- 支持绝对日期、今天/明天/后天、本周 X/下周 X、精确时间、上午/下午、X 点以前/以后；
|
||
- 「过几天」「最近」「周末都行」等表达不得猜成绝对日期，必须返回日期选择项；
|
||
- `appointmentTime` 只有在现有容量服务返回真实 slot 后才能写入草稿；
|
||
- 对外时间字符串统一为 `yyyy-MM-dd'T'HH:mm:ss`，语义为 `Asia/Shanghai` 本地时间。
|
||
|
||
## 4. M0 会话状态机
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> collecting: create session
|
||
collecting --> collecting: 信息仍不足
|
||
collecting --> proposing: 可搜索真实号源
|
||
proposing --> collecting: 修改条件或需要澄清
|
||
proposing --> confirmable: 选择真实 slot
|
||
confirmable --> collecting: 用户修改草稿
|
||
collecting --> fallback: 用户回填表单或 LLM 降级
|
||
proposing --> fallback: 用户回填表单或 LLM 降级
|
||
confirmable --> fallback: 带入普通预约
|
||
collecting --> cancelled: 用户结束
|
||
proposing --> cancelled: 用户结束
|
||
confirmable --> cancelled: 用户结束
|
||
collecting --> expired: TTL 到期
|
||
proposing --> expired: TTL 到期
|
||
confirmable --> expired: TTL 到期
|
||
```
|
||
|
||
不允许的状态：`submitting`、`booked`、`needs_reselection`。终态 `fallback / expired / cancelled` 不接受新消息或转写。
|
||
|
||
每次消息请求必须带客户端当前 `draftVersion`。服务端只在版本相等时更新，成功后加一；版本冲突返回 `DRAFT_VERSION_CONFLICT`，不得静默覆盖。
|
||
|
||
## 5. API 冻结
|
||
|
||
唯一契约是 [`contracts/booking-agent-m0.openapi.yaml`](./contracts/booking-agent-m0.openapi.yaml)。M0 只注册五个 endpoint：
|
||
|
||
| Method | Endpoint | 结果 |
|
||
|---|---|---|
|
||
| `POST` | `/api/booking-agent/sessions` | 在已选 `storeId` 下创建 customer 会话 |
|
||
| `POST` | `/api/booking-agent/sessions/{sessionId}/messages` | 提交当轮已确认文字并刷新草稿 |
|
||
| `POST` | `/api/booking-agent/sessions/{sessionId}/transcriptions` | 转写短音频，文字返回输入框，不自动发送 |
|
||
| `POST` | `/api/booking-agent/sessions/{sessionId}/fallback` | 返回已验证的部分/完整草稿并结束会话 |
|
||
| `DELETE` | `/api/booking-agent/sessions/{sessionId}` | 结束本人会话 |
|
||
|
||
### 5.1 身份与资源隐藏
|
||
|
||
- 所有 endpoint 都必须经过 `AuthInterceptor`；
|
||
- controller 再要求 `current.role == customer`，boss/staff 返回 `FORBIDDEN`；
|
||
- session 每次以 `sessionId + current.userId` 查询；不存在和他人 session 统一返回 `SESSION_NOT_FOUND`；
|
||
- `storeId` 只在创建时接收并验证，后续从 session 读取；
|
||
- 音频转写 endpoint 必须挂在 session 下，客户端不得上传宠物/服务词表。
|
||
|
||
### 5.2 响应语义
|
||
|
||
沿用 `{ code, message?, bizCode?, data? }`。当前前端以 body `code` 判断业务结果；除 `AuthInterceptor` 的 HTTP 401 外，M0 不借机重构全局 HTTP status 行为。
|
||
|
||
草稿中的 `storeId / petId / serviceTypeId / appointmentTime` 是经过后端重新解析的事实；客户端回填后，现有预约创建服务仍会重新执行最终权限、服务和容量校验。
|
||
|
||
### 5.3 业务码
|
||
|
||
| body code | bizCode | 语义 |
|
||
|---|---|---|
|
||
| 401 | `UNAUTHENTICATED` | session token 缺失或失效 |
|
||
| 403 | `FORBIDDEN` | 非 customer 调用 |
|
||
| 503 | `AGENT_DISABLED` | 功能开关关闭 |
|
||
| 404 | `STORE_NOT_FOUND` | 创建时目标门店无效 |
|
||
| 404 | `SESSION_NOT_FOUND` | session 不存在或不属于当前 customer |
|
||
| 410 | `SESSION_EXPIRED` | 会话 TTL 到期 |
|
||
| 409 | `SESSION_TERMINAL` | 会话已 fallback/cancelled |
|
||
| 409 | `DRAFT_VERSION_CONFLICT` | 客户端草稿版本过旧 |
|
||
| 400 | `INVALID_INPUT` | 空文本、超长或请求结构无效 |
|
||
| 400 | `INVALID_AUDIO` | 空音频、格式/MIME/文件头不匹配或时长非法 |
|
||
| 413 | `AUDIO_TOO_LARGE` | 超过 3 MB |
|
||
| 429 | `RATE_LIMITED` | customer 请求频率超限 |
|
||
| 503 | `AGENT_UNAVAILABLE` | LLM 超时、无效 JSON/schema 或外部失败 |
|
||
| 503 | `ASR_UNAVAILABLE` | ASR 超时或外部失败 |
|
||
|
||
宠物/服务歧义、无号源和未选时段是正常 `200` 会话响应，不用异常码表达。
|
||
|
||
## 6. 数据模型冻结
|
||
|
||
已实现迁移：`backend/db/migrations/20260802_create_booking_agent_session.sql`（petstore-backend `3c00065`）。
|
||
|
||
### 6.1 `t_booking_agent_session`
|
||
|
||
| 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `id` | BIGINT | 自增主键，只在后端和 `BusinessEvent.aggregate_id` 使用 |
|
||
| `session_id` | VARCHAR(36) | UUID，唯一，对客户端暴露 |
|
||
| `customer_user_id` | BIGINT | 必须是创建会话的 customer |
|
||
| `store_id` | BIGINT | M0 必填；创建时验证存在，后续不接受覆盖 |
|
||
| `status` | VARCHAR(24) | 仅六个 M0 状态 |
|
||
| `draft_json` | TEXT | 最小已验证草稿，不存当轮原文/模型响应 |
|
||
| `draft_version` | INT | 初始 0，每次成功草稿更新加一 |
|
||
| `entry_source` | VARCHAR(32) | M0 固定 `appointment_create` |
|
||
| `input_modality` | VARCHAR(16) | `text / voice / mixed`，首次成功消息后派生 |
|
||
| `expires_at` | DATETIME | 创建时固定 `now + 30min`，M0 不滑动续期 |
|
||
| `create_time / update_time` | DATETIME | 服务端时间 |
|
||
|
||
索引：
|
||
|
||
- `UNIQUE uk_booking_agent_session_public_id (session_id)`；
|
||
- `INDEX idx_booking_agent_customer_status_expire (customer_user_id, status, expires_at)`；
|
||
- `INDEX idx_booking_agent_status_expire (status, expires_at)`。
|
||
|
||
不增加：
|
||
|
||
- `appointment_id`；
|
||
- `t_booking_agent_turn`；
|
||
- 原始语音/转写/提示词/模型响应列；
|
||
- `deleted`。会话是短期对象，使用明确终态并按 TTL 物理清理。
|
||
|
||
### 6.2 TTL 与清理
|
||
|
||
1. 会话固定 30 分钟有效，不因消息滑动延长；
|
||
2. endpoint 发现过期时返回 `SESSION_EXPIRED`，并以幂等方式标记 `expired`；
|
||
3. 每小时清理任务将到期活动会话标记 `expired`；
|
||
4. `expires_at` 早于当前时间 24 小时的 session 物理删除；
|
||
5. 清理失败记录数量和错误类别，不记录 `draft_json`；
|
||
6. `BusinessEvent` 是独立低敏事实，不随短期 session 删除。
|
||
|
||
## 7. 业务事件冻结
|
||
|
||
M0 只新增三个首次漏斗事实：
|
||
|
||
| 事件 | 触发 | 幂等键 | metadata 白名单 |
|
||
|---|---|---|---|
|
||
| `booking_agent_started` | session 创建成功 | `booking_agent_started:{sessionDbId}` | `entrySource` |
|
||
| `booking_agent_draft_ready` | session 首次进入 `confirmable` | `booking_agent_draft_ready:{sessionDbId}` | `inputModality` |
|
||
| `booking_agent_fallback` | 用户回填表单或 LLM 降级 | `booking_agent_fallback:{sessionDbId}` | `reason=user/llm_unavailable` |
|
||
|
||
事件使用：
|
||
|
||
- `storeId=session.storeId`；
|
||
- `aggregateType=booking_agent_session`；
|
||
- `aggregateId=session.id`；
|
||
- `actorUserId=session.customerUserId`、`actorRole=customer`、`source=customer`；
|
||
- 已有 `StoreCustomer` 时可关联，不能只为启动助手创建客户主档。
|
||
|
||
禁止把输入原文、转写文本、备注、宠物名、服务名、供应商 request ID 或错误原文写入 metadata。
|
||
|
||
M0 不写 `booking_agent_confirmed`，也不修改现有 `appointment_created` metadata。精确联结「助手草稿 -> 表单创建」需要另行设计服务端一次性交接机制。
|
||
|
||
## 8. 外部调用与隐私门禁
|
||
|
||
### 8.1 语音
|
||
|
||
- 单段不超过 60 秒、3 MB；客户端预检，服务端按字节、文件头、MIME 和解析时长复核；
|
||
- ASR 使用 `qwen3-asr-flash-2026-02-10` Base64 Data URL，不中转 OSS；
|
||
- 上下文只包含当前门店服务名和当前 customer 的宠物展示名；
|
||
- 返回转写后立即释放音频字节，不缓存、不写文件、不返回供应商 request ID；
|
||
- 转写必须由用户编辑/确认后才能调用 messages。
|
||
|
||
### 8.2 LLM
|
||
|
||
- 使用固定 `qwen-plus-2025-12-01`、非思考、非流式、无工具、无联网；
|
||
- LLM 超时 3 秒，ASR 超时 5 秒；不做多次自动重试；
|
||
- 请求只包含当次文字、最小草稿和枚举说明，不包含手机号、token、客户时间线或其他门店数据；
|
||
- API Key、Workspace ID 和 Authorization header 不进 Git、测试 fixture、聊天、截图或日志。
|
||
|
||
### 8.3 频率门禁
|
||
|
||
M0 默认每个 customer：
|
||
|
||
- 10 分钟内最多创建 5 个 session；
|
||
- 10 分钟内最多提交 30 条 message；
|
||
- 10 分钟内最多转写 10 段音频。
|
||
|
||
超限返回 `RATE_LIMITED`，普通预约继续可用。当前单实例可先使用进程内限流；进入多实例前必须切换共享限流状态。
|
||
|
||
## 9. Review 结论
|
||
|
||
### Architecture Review
|
||
|
||
**通过，可进入实现。** 条件是严格保留五个 endpoint、无 `/confirm`、门店先选、普通表单独立可用、feature flag 默认关闭。
|
||
|
||
### Data Model Review
|
||
|
||
**通过提案，可由 Backend Core 实现迁移。** 相比原 brief 的修订：
|
||
|
||
- 使用 `id BIGINT` 内部主键 + `session_id UUID` 外部唯一键；
|
||
- `store_id` 从可空改为 M0 必填；
|
||
- 去掉 `deleted` 和 `appointment_id`；
|
||
- 增加固定 TTL、物理清理和 `draft_version` 并发规则。
|
||
|
||
**实现 diff 复核通过。** `BookingAgentSession` JPA、迁移与 mapper 保持上述冻结字段和三个索引；六态与 `input_modality` 有数据库 `CHECK`，owner 查询持悲观锁，未增加 `appointment_id`、`deleted`、turn 表或原文列。迁移测试、版本/TTL/清理测试均已落地。
|
||
|
||
### Access / Privacy Review
|
||
|
||
**开发边界通过，真实供应商 smoke 与生产开启未通过。** 不需要真实密钥即可实现接口、stub、状态机和测试；真实调用前仍需完成供应商数据处理确认、小程序隐私告知、费用告警和已知情语音样本评测。
|
||
|
||
## 10. 后果与风险
|
||
|
||
正向结果：
|
||
|
||
- M0 不增加第二条预约写路径，模型失败不会污染 `Appointment`；
|
||
- session 可短期恢复结构化草稿，又不形成对话原文数据库；
|
||
- OpenAPI、JSON Schema 和本体可以直接驱动测试与 review；
|
||
- 后续 M1 必须另立 ADR 才能新增 confirm/appointment 关联。
|
||
|
||
已知限制：
|
||
|
||
- 门店必须先选，无法用一句话同时完成「找店 + 预约」；
|
||
- M0 不精确统计回填后最终创建转化；
|
||
- 进程内限流只适用于当前单实例；
|
||
- 供应商效果仍需真实语料验证，当前推荐不是生产准入结论。
|
||
|
||
## 11. 实现门禁
|
||
|
||
编码 PR 必须同时满足：
|
||
|
||
- 引用本 ADR、OpenAPI、JSON Schema 和对应 `ontologyRefs`；
|
||
- provider 单测只访问本地 HTTP stub；
|
||
- 后端测试证明整个 M0 不调用 `AppointmentMapper.save`；
|
||
- 未配置密钥或 feature flag 关闭时应用正常启动、普通预约正常；
|
||
- 本体从 `documented` 更新为 `anchored` 只能与代码和测试同一批完成；
|
||
- 真实供应商 smoke、生产配置和 RC 纳入必须重新授权。
|
||
|
||
## 12. Batch 2 实现证据
|
||
|
||
- Backend：`3c00065 feat: add booking agent session orchestration`；
|
||
- 五个 endpoint、JPA 会话、迁移、owner/store 数据边界、版本与 TTL 已实现；
|
||
- 本体 `BookingAgentSession`、五个动作、三个事件、五条规则和十条关系已从 `documented` 更新为 `anchored`；
|
||
- 后端全量测试 292 项通过，本体端点 73/73、JPA 实体 17/17，无漂移；
|
||
- 功能开关仍默认关闭，真实供应商 smoke、Batch 3 前端和生产开启仍未完成。
|