docs: define booking agent m0 implementation

2026-08-02 14:26:35 +08:00 · 2026-08-02 14:26:35 +08:00 · 031d2db36e
commit 031d2db36e
parent bde3d1d6d0
3 changed files with 741 additions and 15 deletions
--- a/宠小它智能预约助手-产品与技术方案-v0.1.md
+++ b/宠小它智能预约助手-产品与技术方案-v0.1.md
@ -11,6 +11,11 @@
 > Access / Privacy Review Required：`Yes`<br>
 > RC 边界：**不纳入 `phase2-pilot-rc6`；当前 RC 仍以基础预约和真实门店试点为先**

+**配套文档**
+
+- [模型与语音供应商选型](./智能预约助手-模型与语音供应商选型-2026-08-02.md)
+- [M0 编码任务 brief](./智能预约助手-M0编码任务brief-2026-08-02.md)
+
 ## 1. 结论

 建议将该能力定义为 **「可执行的智能预约助手」**，而不是泛化客服聊天机器。
@ -88,7 +93,7 @@
 - 服务项目和预计时长；
 - 绝对日期、开始时间和预计结束时间；
 - 宠主提供的备注；
- 「修改」「确认预约」和「普通预约」操作。
+- 「修改」「带入普通预约」和「普通预约」操作。M1 通过写路径安全评审后，才将主操作改为「确认预约」。

 ### 4.2 澄清规则

@ -138,6 +143,8 @@ stateDiagram-v2
 | `needs_reselection` | 确认时号源已变化 | 否 |
 | `fallback` / `expired` / `cancelled` | 结束智能会话 | 否 |

+M0 只实现 `collecting`、`proposing`、`confirmable`、`fallback`、`expired` 和 `cancelled`。用户在 `confirmable` 点击「带入普通预约」时离开助手，由现有表单完成提交；`submitting`、`booked` 和 `needs_reselection` 是 M1 状态，M0 不实现。
+
 ## 6. 系统架构与权威边界

 ```mermaid
@ -225,7 +232,7 @@ flowchart LR

 ### 7.2 候选会话表

-建议新增 `t_booking_agent_session`，不将对话状态塞入 `t_appointment`。
+长期建议新增 `t_booking_agent_session`，不将对话状态塞入 `t_appointment`。下表是覆盖 M1 直接确认能力的完整候选形态；M0 实际字段以配套编码 brief 为准。

 | 字段 | 语义 |
 |---|---|
@ -236,17 +243,17 @@ flowchart LR
 | `status` | 仅使用第 5 节对话状态 |
 | `draft_json` | 最小结构化草稿，不存原始语音 |
 | `draft_version` | 乐观版本号 |
-| `entry_source` | `home` / `appointment_history` / `report_history` / `pet_profile` |
+| `entry_source` | `appointment_create` / `home` / `appointment_history` / `report_history` / `pet_profile` |
 | `input_modality` | `text` / `voice` / `mixed` |
-| `appointment_id` | 成功后关联的真实预约，可空 |
+| `appointment_id` | M1 成功后关联的真实预约，可空；M0 不增加 |
 | `expires_at` | 会话过期时间 |
 | `create_time` / `update_time` | 审计时间 |

 数据建议：

 - 以 `(customer_user_id, status, expires_at)` 建立查询索引；
- `appointment_id` 为可空唯一关联；
- 确认时对 session 行加悲观锁；如已是 `booked`，重复请求直接返回同一 `Appointment`；
+- M1 增加 `appointment_id` 可空唯一关联；
+- M1 确认时对 session 行加悲观锁；如已是 `booked`，重复请求直接返回同一 `Appointment`；
 - MVP 会话默认 30 分钟过期，过期不等于删除预约；
 - 不新增 `t_booking_agent_turn` 原文表；模型每轮以当前草稿和当次输入工作，避免默认持久化完整对话。

@ -264,14 +271,14 @@ flowchart LR
 }
 ```

-`bookingChannel` 候选值：`form`、`agent_text`、`agent_voice`、`admin`、`follow_up`。不建议 MVP 为此修改 `Appointment` 主表；先以已持久化 `BusinessEvent` 作为统计事实。
+`bookingChannel` 候选值：`form`、`agent_draft`、`agent_text`、`agent_voice`、`admin`、`follow_up`。`agent_draft` 只表示智能助手提供了已验证草稿；`agent_text` 和 `agent_voice` 保留给 M1 对话内直接创建路径。初始 M0 不修改 `appointment_created` 事件，如需归因表单提交，必须另行评审服务端验证的一次性草稿交接，不接受客户端自由上报渠道。不建议 MVP 为此修改 `Appointment` 主表。

 候选新事件：

 - `booking_agent_started`；
 - `booking_agent_draft_ready`；
 - `booking_agent_fallback`；
- `booking_agent_confirmed`。
+- `booking_agent_confirmed`（M1）。

 这些事件只用于漏斗和运行分析；只有真实创建成功的 `appointment_created` 才计为预约。编码前需将候选对象、动作、事件和规则同步到 `docs/ontology/` 及 `graph/ontology.jsonl`。

@ -333,12 +340,12 @@ flowchart LR
 `POST /api/booking-agent/transcriptions`

 - `multipart/form-data`，仅接受允许的音频 MIME 和扩展名；
- 建议 MVP 单段不超过 60 秒、5 MB，具体值由技术验证后冻结；
+- M0 单段不超过 60 秒、3 MB，与供应商选型和编码 brief 保持一致；
 - 后端代理调用语音服务，不向客户端下发供应商密钥；
 - 语音只用于当次转写，不进入通用报告媒体存储，不持久化原始录音；
 - 返回可编辑 `text` 和脱敏 `requestId`，宠主可修改识别结果再发送。

-### 8.4 确认预约
+### 8.4 确认预约（M1，M0 不实现）

 `POST /api/booking-agent/sessions/{sessionId}/confirm`

@ -453,17 +460,17 @@ flowchart LR
 | 语音识别失败 | 重新说或改用文字 | 不提交空文本 |
 | 模型超时/无效输出 | 保留草稿并转普通表单 | 不用模型记忆猜测 |
 | 确认时号源已满 | 立即推荐新时段 | 不产生超容量预约 |
-| 重复点击确认 | 返回同一预约成功页 | 会话行锁 + `appointment_id` 幂等 |
+| M1 重复点击确认 | 返回同一预约成功页 | 会话行锁 + `appointment_id` 幂等 |
 | 会话过期 | 新建会话或回填普通表单 | 不自动提交旧草稿 |

 ## 12. 分阶段交付

 ### M0：草稿助手（首发建议）

- 老客从首页、历史预约或登录后报告记录进入；
+- 仅在现有 `CustAppointmentCreate` 顶部增加「一句话预约」次级入口；
 - 支持文字和语音转写；
 - 解析宠物、服务和时间偏好，查询真实号源；
- 生成确认卡，但「继续」只把草稿回填到现有 `CustAppointmentCreate`；
+- 生成确认卡，但「带入普通预约」只把草稿回填到现有 `CustAppointmentCreate`；
 - 最终仍由现有表单提交，不新增智能层写入路径；
 - 先在 1 家试点门店对老客开放，不影响 RC6 基线验证。

@ -512,10 +519,10 @@ flowchart LR

 | ID | 决策 | 建议默认 | 责任人 |
 |---|---|---|---|
-| D1 | 首发入口 | 登录后历史预约/报告记录，其次首页 | Product Design |
+| D1 | M0 首发入口 | `CustAppointmentCreate` 顶部次级入口；历史预约、报告和首页入口后续评估 | Product Design |
 | D2 | 是否支持匿名助手 | MVP 不支持，普通表单继续支持 guest 草稿 | Product Design + System Architect |
 | D3 | M0 是否直接创建预约 | 否，先回填现有表单 | Product Design + Backend Core |
-| D4 | 模型与语音供应商 | 以数据区域、中文识别、延迟、稳定性和成本评估；业务保持适配层 | System Architect + Backend Ops |
+| D4 | 模型与语音供应商 | M0 推荐阿里云百炼北京 `qwen3-asr-flash-2026-02-10 + qwen-plus-2025-12-01`，腾讯 ASR 作对照；生产前仍需语料和隐私复核 | System Architect + Backend Ops |
 | D5 | 原文保留 | 默认不持久化对话原文，不持久化原始语音 | Access / Privacy Review |
 | D6 | session TTL | MVP 30 分钟，编码前由 Data Model 冻结 | Data Model |
 | D7 | 助手对话风格 | 简短、一次一个关键问题，不模拟人格客服 | Product Design |
--- a/智能预约助手-M0编码任务brief-2026-08-02.md
+++ b/智能预约助手-M0编码任务brief-2026-08-02.md
@ -0,0 +1,474 @@
+# 智能预约助手 M0 编码任务 brief
+
+> 日期：2026-08-02<br>
+> 状态：**Ready for Review / 尚未进入编码**<br>
+> 目标：宠主用文字或语音生成可验证预约草稿，回填现有表单，不由智能层创建 `Appointment`<br>
+> Workstream：`Core Booking Flow`<br>
+> Owner Agent：`Backend Core` + `Customer Experience FE`<br>
+> Paired QA：`Core Flow QA`<br>
+> Service Lock：`backend:booking-agent-session+read-tools` + `frontend:customer-booking-agent+shared-api`<br>
+> Data Model Review Required：`Yes`<br>
+> Access / Privacy Review Required：`Yes`<br>
+> RC Included：`No`
+
+**需求来源**
+
+- [智能预约助手产品与技术方案 v0.1](./宠小它智能预约助手-产品与技术方案-v0.1.md)
+- [模型与语音供应商选型](./智能预约助手-模型与语音供应商选型-2026-08-02.md)
+
+## 1. M0 交付结果
+
+宠主在已登录状态进入「一句话预约」，输入文字或按住说话。系统依次：
+
+1. 转写语音（文字输入跳过）；
+2. 提取宠物查询词、服务查询词、日期表达、时间偏好和备注；
+3. 在当前 customer 和门店范围内解析真实 Pet 与 ServiceType；
+4. 调用现有容量服务获取真实号源；
+5. 展示可修改草稿卡；
+6. 宠主点击「带入普通预约」后，回填现有 `CustAppointmentCreate`；
+7. 宠主仍在现有表单上点击「提交预约」。
+
+M0 成功的判定是 **「草稿真实、回填正确、普通预约未受影响」**，不是对话内创建预约。
+
+## 2. 严格非目标
+
+- 不实现 `POST /api/booking-agent/sessions/{sessionId}/confirm`；
+- 不调用 `AppointmentService.createBooking`；
+- 不新增 `Appointment` 字段或状态；
+- 不做取消、改期、代客预约或指定技师；
+- 不自动建立宠物档案；
+- 不做匿名智能会话；
+- 不开启外部搜索、知识库或模型托管 Agent；
+- 不持久化原始语音或完整对话原文；
+- 不进入当前 RC6 tag、发布物或生产配置。
+
+## 3. 用户流程
+
+```mermaid
+flowchart TD
+    A[宠主预约页] --> B[点击一句话预约]
+    B --> C{已登录 customer}
+    C -- 否 --> D[登录并保留返回路由]
+    D --> E[创建助手会话]
+    C -- 是 --> E
+    E --> F[文字或语音输入]
+    F --> G[结构化意图提取]
+    G --> H[服务端解析真实宠物和服务]
+    H --> I[查询真实号源]
+    I --> J{草稿完整}
+    J -- 否 --> K[询问一个关键缺失项]
+    K --> F
+    J -- 是 --> L[展示草稿卡]
+    L --> M[带入普通预约]
+    M --> N[CustAppointmentCreate 回填]
+    N --> O[用户在现有表单提交]
+```
+
+### 3.1 入口
+
+M0 只在宠主的 `CustAppointmentCreate` 顶部增加一个次级入口：
+
+> 不想一项项填？「一句话预约」
+
+该入口不取代当前表单和主提交按钮，不改宠主首页主 CTA。历史预约、报告页和宠物档案深链放到后续迭代。
+
+### 3.2 对话风格
+
+- 回复简短，一次只问一个关键缺失项；
+- 宠物、服务和号源使用固定模板回复，不由模型自由生成业务事实；
+- 可选项使用芯片/卡片，不要求宠主重复说已知内容；
+- 对话页固定保留「普通预约」退出口。
+
+### 3.3 可支持的时间表达
+
+M0 确定性解析只承诺：
+
+- 绝对日期；
+- 「今天 / 明天 / 后天」；
+- 「本周 X / 下周 X」；
+- 精确时间、「上午 / 下午」和「X 点以后 / 以前」。
+
+「过几天」「最近」「周末都行」等不能稳定转换的表达保留为歧义，请宠主选择日期。确认卡和回填草稿始终使用 `Asia/Shanghai` 下的绝对日期时间。
+
+## 4. 后端设计
+
+### 4.1 包与组件
+
+建议新增：
+
+```text
+backend/src/main/java/com/petstore/bookingagent/
+  api/
+    BookingAgentController.java
+    BookingAgentDtos.java
+  config/
+    BookingAgentProperties.java
+  domain/
+    BookingAgentSession.java
+    BookingAgentStatus.java
+    BookingDraft.java
+    BookingIntentPatch.java
+  mapper/
+    BookingAgentSessionMapper.java
+  provider/
+    BookingIntentExtractor.java
+    SpeechTranscriber.java
+    ProviderException.java
+    aliyun/
+      QwenBookingIntentExtractor.java
+      Qwen3AsrSpeechTranscriber.java
+  service/
+    BookingAgentService.java
+    BookingAgentContextResolver.java
+    BookingAgentReplyRenderer.java
+    BookingTimeConstraintResolver.java
+```
+
+注：项目现有微信出站调用使用 JDK `HttpClient`。M0 供应商适配也优先使用可注入、有固定 connect/request timeout 的 JDK `HttpClient`，不为两个 HTTPS endpoint 引入重型 Agent SDK。
+
+### 4.2 责任边界
+
+| 组件 | 责任 | 禁止 |
+|---|---|---|
+| `BookingAgentController` | 登录上下文、输入大小、响应映射 | 不在 controller 解析时间或调用预约写服务 |
+| `BookingIntentExtractor` | 当前输入 + 最小草稿 -> `BookingIntentPatch` | 不访问数据库、不调工具 |
+| `BookingAgentContextResolver` | 解析当前 customer 的 Pet 和目标门店 ServiceType | 不信任模型传入 ID |
+| `BookingTimeConstraintResolver` | 相对日期/时间窗 -> 绝对搜索条件 | 不猜测未支持表达 |
+| `BookingAgentService` | 状态转换、上下文解析、号源查询、草稿版本 | 不调用 `createBooking` |
+| `BookingAgentReplyRenderer` | 按确定数据渲染中文模板 | 不使用模型生成宠物/服务/号源事实 |
+| `SpeechTranscriber` | 短音频 -> 文本 | 不保存原始音频 |
+
+### 4.3 M0 会话状态
+
+M0 只允许：
+
+- `collecting`；
+- `proposing`；
+- `confirmable`；
+- `fallback`；
+- `expired`；
+- `cancelled`。
+
+`submitting`、`booked` 和 `needs_reselection` 属于 M1，M0 的 service 不得转入这三个状态。
+
+### 4.4 数据表
+
+新增迁移提案：
+
+`backend/db/migrations/20260802_create_booking_agent_session.sql`
+
+M0 字段：
+
+- `session_id` VARCHAR(64) 主键；
+- `customer_user_id` BIGINT NOT NULL；
+- `store_id` BIGINT NULL；
+- `status` VARCHAR(32) NOT NULL；
+- `draft_json` TEXT NOT NULL；
+- `draft_version` INT NOT NULL；
+- `entry_source` VARCHAR(32) NOT NULL；
+- `input_modality` VARCHAR(16) NULL；
+- `expires_at` DATETIME NOT NULL；
+- `create_time` / `update_time`；
+- `deleted` TINYINT(1) NOT NULL DEFAULT 0。
+
+索引：
+
+- `(customer_user_id, status, expires_at)`；
+- `(expires_at, deleted)` 用于过期清理。
+
+M0 不增加 `appointment_id`，也不建立 `t_booking_agent_turn`。`appointment_id` 唯一关联在 M1 幂等写入评审时再增加，避免 M0 数据模型暗示已具备直接创建能力。
+
+M0 的 `entry_source` 只允许 `appointment_create`；历史预约、报告、首页和宠物档案入口尚未开放。
+
+`draft_json` 只保存已验证 ID、时间约束和必要备注；不保存每轮用户原文、提示词或模型原始响应。
+
+### 4.5 API 契约
+
+M0 只实现：
+
+| Method | Endpoint | 用途 |
+|---|---|---|
+| `POST` | `/api/booking-agent/sessions` | 创建已登录 customer 会话 |
+| `POST` | `/api/booking-agent/sessions/{sessionId}/messages` | 提交文字/语音转写文本，刷新草稿 |
+| `POST` | `/api/booking-agent/transcriptions` | 上传短音频并获取可编辑转写 |
+| `POST` | `/api/booking-agent/sessions/{sessionId}/fallback` | 返回可回填普通表单的已验证草稿 |
+| `DELETE` | `/api/booking-agent/sessions/{sessionId}` | 将本人会话标记为 `cancelled` |
+
+所有 endpoint 都要求 `CurrentUserContext.require()` 且 role 为 `customer`。每次读写 session 都以 `sessionId + current.userId` 查询；他人 session 和不存在 session 均返回统一 404 语义，避免泄漏 session 是否存在。
+
+M0 绝对不注册 `/confirm` endpoint。
+
+### 4.6 模型输出强校验
+
+`BookingIntentPatch` 建议为固定 record/DTO：
+
+```json
+{
+  "schemaVersion": "booking-intent-v1",
+  "intent": "book",
+  "petQuery": "球球",
+  "serviceQuery": "洗澡",
+  "dateExpression": "本周六",
+  "timeWindow": {
+    "start": "15:00",
+    "end": null
+  },
+  "remark": null,
+  "ambiguities": [],
+  "nextAction": "resolve_context"
+}
+```
+
+校验规则：
+
+- 未知字段拒绝或明确忽略，不得进业务实体；
+- `schemaVersion`、`intent` 和 `nextAction` 为枚举；
+- 文本字段 trim、限长；
+- 模型输出 ID、价格、号源或预约状态字段时整个响应降级；
+- JSON 解析、schema 或枚举校验失败统一映射 `AGENT_UNAVAILABLE`，不展示模型原始输出。
+
+### 4.7 出站日志
+
+允许记录：
+
+- 脱敏 request ID；
+- provider/model/schema/prompt 版本；
+- 请求字符数或音频时长区间；
+- 耗时、HTTP 大类、结果码和降级类型。
+
+禁止记录：
+
+- API Key 或 Authorization header；
+- 用户原文、原始音频、Base64；
+- 完整模型请求/响应；
+- 手机号、session token、`report_token`、私密媒体 URL。
+
+## 5. 前端设计
+
+### 5.1 建议写入文件
+
+```text
+frontend/src/pages/appointment/BookingAgent.vue                 # 新页面
+frontend/src/pages/appointment/CustAppointmentCreate.vue        # 次级入口 + 回填
+frontend/src/api/index.js                                       # 统一 API 封装
+frontend/src/utils/bookingAgentDraft.js                         # 短期草稿交接
+frontend/src/pages.json                                         # 路由
+```
+
+`frontend/src/api/index.js` 为共享契约入口，写入前由 Customer Experience FE 持有 `shared-api` 锁并通知 Backend Core。
+
+### 5.2 页面元素
+
+- 顶部标题：「一句话预约」；
+- 简短说明：「告诉我宠物、服务和想来的时间」；
+- 消息区：只在当前页内保留消息用于展示，不持久化到 Storage；
+- 文字输入框；
+- 按住说话按钮，上传前显示隐私说明；
+- 转写结果先回到可编辑输入框，宠主确认后再发送意图请求；
+- 宠物/服务/时段选择芯片；
+- 草稿卡；
+- 主操作「带入普通预约」；
+- 次操作「普通预约」和「结束对话」。
+
+### 5.3 语音适配
+
+- 小程序录音格式、权限和真机行为必须先做小程序实测，不在文档中假定 H5 和 mp-weixin 的录音细节完全相同；
+- 客户端在上传前检查时长和大小，后端再做一次权威检查；
+- 音频上传完成后立即释放本地临时路径引用；
+- 权限拒绝时显示「可以直接打字预约」，不反复强请求录音权限；
+- H5 无可用录音能力时只显示文字输入，不阻断 M0 主链路。
+
+### 5.4 草稿回填
+
+`bookingAgentDraft.js` 只保存一次性回填对象：
+
+```json
+{
+  "source": "booking-agent-m0",
+  "storeId": 1,
+  "petId": 2,
+  "petName": "球球",
+  "petType": "狗",
+  "serviceType": "精洗护理",
+  "appointmentTime": "2026-08-08T15:00:00",
+  "remark": "怕吹风机"
+}
+```
+
+该对象不包含 customer ID、token、手机号、模型原文或供应商 request ID。`CustAppointmentCreate` 成功消费后立即删除；店/宠物/服务不再有效时按普通表单错误处理，不静默提交。
+
+## 6. 业务事件与本体
+
+M0 候选事件：
+
+- `booking_agent_started`；
+- `booking_agent_draft_ready`；
+- `booking_agent_fallback`。
+
+M0 不记录 `booking_agent_confirmed`，也不修改现有 `appointment_created` metadata，因为助手没有直接确认写入，而客户端的 `source` 字符串不能当作服务端归因事实。如后续需要精确联结「助手草稿 -> 表单创建」，另立 brief 设计可验证、一次性的草稿交接机制。
+
+编码前需增加或更新：
+
+- `ontology/objects.md`：`booking_agent_session` gap/implemented 证据；
+- `ontology/actions.md`：创建会话、提交消息、语音转写、回填草稿、结束会话；
+- `ontology/events.md`：M0 三个漏斗事件；
+- `ontology/rules.md`：customer 数据范围、无写工具、原始语音/原文不持久化、超时降级；
+- `ontology/relations.md` 与 `graph/ontology.jsonl`；
+- `coverage/ontology-coverage-audit.md`。
+
+## 7. 自动化测试
+
+### 7.1 后端必测
+
+**意图提取契约**
+
+- 30 条 `booking-intent-v1` fixture 均可解析；
+- 无效 JSON、未知 schema 版本、未知枚举、超长备注和多余 ID 字段降级；
+- 模型请求不包含手机号、token 或全量客户时间线。
+
+**会话和权限**
+
+- 未登录、boss/staff 调用助手 endpoint 被拒绝；
+- A customer 无法查询、修改或结束 B customer session；
+- session 过期后不再接收消息；
+- M0 不存在 `/confirm` endpoint；
+- 全套 M0 测试不会调用 `AppointmentMapper.save`。
+
+**预约事实**
+
+- 宠物名唯一时解析到归属 Pet，多宠物/同名返回歧义选项；
+- 服务必须属于当前门店；
+- 只返回 `available-slots` 真实可约候选；
+- 过去日期、非营业时间和无号日期不生成 `appointmentTime`；
+- 相对日期在固定 Clock + `Asia/Shanghai` 下可重复测试。
+
+**语音和日志**
+
+- 空音频、错误 MIME、超 60 秒、超 3 MB 被拒绝；
+- ASR 超时/失败映射 `ASR_UNAVAILABLE`；
+- 测试日志不出现音频 Base64、API Key、Authorization 或用户原文。
+
+供应商单元测试使用本地 HTTP stub，CI 不访问真实云 API。真实供应商 smoke 必须显式启用、使用本地密钥存储且不作为普通 `mvn test` 的一部分。
+
+### 7.2 前端必测/手工 smoke
+
+- customer 能进入，boss/staff 不展示入口；
+- 未登录进入时先登录，返回后进助手；
+- 文字输入、发送 loading、网络失败和重试可理解；
+- 语音权限拒绝可切换文字；
+- 转写可编辑，不自动继续提交；
+- 多宠物、多服务、多号源可点选；
+- 「带入普通预约」的门店、宠物、服务、时间和备注正确；
+- 回填数据消费后从 Storage 删除；
+- 对话失败或退出不影响普通表单；
+- H5 和 mp-weixin 构建通过，小程序真机录音路径单独验收。
+
+## 8. 实施顺序
+
+### Batch 0：本体、数据与契约冻结
+
+Owner：System Architect + Data Model + Product Design
+
+- 冻结 `booking-intent-v1`、M0 状态子集、API shape 和业务码；
+- 更新本体及机器图谱；
+- 评审 session 表、TTL 和清理方式；
+- 完成 Access / Privacy Review。
+
+### Batch 1：供应商适配与契约测试
+
+Owner：Backend Core
+
+- 实现 provider interface、properties 和本地 HTTP stub；
+- 实现 Qwen JSON 提取与 Qwen3-ASR-Flash 转写；
+- 建立 30 条文字 fixture；
+- 确保未配置/关闭时 fail closed，不影响应用启动和普通预约。
+
+### Batch 2：会话、上下文解析和号源
+
+Owner：Backend Core
+
+- 实现 session 实体、迁移、mapper 和 service；
+- 复用 Pet、ServiceType、Store 和 BookingCapacity 领域服务；
+- 实现确定性回复模板和 fallback DTO；
+- 完成权限、过期、时间和无写路径测试。
+
+### Batch 3：宠主对话页与回填
+
+Owner：Customer Experience FE
+
+- 实现 BookingAgent 页、文字链路、选择芯片和草稿卡；
+- 实现语音转写及隐私告知；
+- 实现一次性草稿回填；
+- 完成 H5/mp-weixin 构建和小程序真机 smoke。
+
+### Batch 4：对照、QA 与禁用默认
+
+Owner：Core Flow QA + Backend Ops
+
+- 跑 20 条已授权语音对照，归档关键槽位和延迟；
+- 检查日志、错误映射、限流和降级；
+- 默认保持 `PETSTORE_BOOKING_AGENT_ENABLED=false`；
+- 不进生产，等待 RC6 真实门店基线和用户明确变更授权。
+
+## 9. Definition of Done
+
+- [ ] 对话入口仅 customer 可见，所有后端 endpoint 仅 customer 可用。
+- [ ] 文字和语音转写都能产生 `booking-intent-v1`。
+- [ ] 模型不能产生或传入业务 ID、服务事实和号源事实。
+- [ ] 宠物、服务、时段全部由后端在当前数据范围重新解析。
+- [ ] 任何模型/ASR/网络失败都能切换普通表单。
+- [ ] 不存在助手 `/confirm` endpoint，不调用预约写服务。
+- [ ] 回填草稿消费后删除，并且不包含敏感字段。
+- [ ] 原始语音、对话原文、密钥、token 和私密 URL 不落库、不进日志、不进 Git。
+- [ ] 后端全测、H5/mp-weixin 构建和本体校验通过。
+- [ ] 功能开关默认关闭，普通预约回归通过。
+- [ ] 语料对照达到选型文档的准确率、延迟和安全门槛。
+
+## 10. 必跑验证
+
+```bash
+cd /Users/apple/_src/petstore/backend && mvn test
+cd /Users/apple/_src/petstore/backend && mvn -DskipTests package
+cd /Users/apple/_src/petstore/frontend && npm run build:h5
+cd /Users/apple/_src/petstore/frontend && npm run build:mp-weixin
+cd /Users/apple/_src/petstore && python3 docs/graph/validate_ontology.py docs
+cd /Users/apple/_src/petstore && python3 docs/graph/audit_drift.py
+git -C /Users/apple/_src/petstore/backend diff --check
+git -C /Users/apple/_src/petstore/frontend diff --check
+git -C /Users/apple/_src/petstore/docs diff --check
+```
+
+另行归档：
+
+- 30 条文字契约结果；
+- 20 条语音关键槽位准确率、p50/p95 延迟；
+- 错误/降级截图或低敏日志证据；
+- H5 和 mp-weixin 构建摘要；
+- 小程序真机录音权限、上传、转写和回填 smoke。
+
+## 11. 发布与回滚
+
+M0 完成也不等于生产开启。发布前必须再获得：
+
+- 百炼业务空间、费用与数据边界审核；
+- 小程序隐私告知与语音权限验收；
+- 一家真实门店的小流量范围和回滚负责人；
+- 主控 PM 对新 RC 和变更窗口的明确授权。
+
+回滚优先级：
+
+1. 关闭 `PETSTORE_BOOKING_AGENT_ENABLED`，隐藏入口；
+2. 保留惰性 session 表，不执行破坏性回滚；
+3. 普通 `CustAppointmentCreate` 仍可独立使用；
+4. 语音/模型供应商故障时不影响预约、报告和回访主链路。
+
+## 12. 外部输入与阻塞
+
+不需要真实密钥也可完成 provider interface、状态机、本地 stub 和大部分前后端开发。以下项目只阻塞真实供应商 smoke 和上线：
+
+- 阿里云百炼华北2（北京）Workspace ID；
+- 服务端 LLM/ASR API Key；
+- 账单和异常费用告警负责人；
+- 语音数据处理和小程序隐私告知确认；
+- 20 条已知情同意的脱敏语音对照样本；
+- 生产开启授权。
--- a/智能预约助手-模型与语音供应商选型-2026-08-02.md
+++ b/智能预约助手-模型与语音供应商选型-2026-08-02.md
@ -0,0 +1,245 @@
+# 智能预约助手：模型与语音供应商选型
+
+> 日期：2026-08-02<br>
+> 状态：**Recommendation / M0 推荐基线，待账号开通、合规复核与语料实测**<br>
+> 影响范围：智能预约 M0，不影响 `phase2-pilot-rc6`<br>
+> Architecture Review Required：`Yes`<br>
+> Access / Privacy Review Required：`Yes`<br>
+> 官方资料查阅日期：2026-08-02
+
+**关联文档**
+
+- [智能预约助手产品与技术方案 v0.1](./宠小它智能预约助手-产品与技术方案-v0.1.md)
+- [智能预约助手 M0 编码任务 brief](./智能预约助手-M0编码任务brief-2026-08-02.md)
+
+## 1. 推荐结论
+
+M0 的默认技术基线建议为：
+
+| 能力 | 推荐供应商与模型 | 调用边界 |
+|---|---|---|
+| 语音转写 | 阿里云百炼华北2（北京）`qwen3-asr-flash-2026-02-10` | OpenAI 兼容 HTTP 同步调用，Base64/Data URL 直传，不中转 OSS，不持久化原始录音 |
+| 预约意图提取 | 阿里云百炼华北2（北京）`qwen-plus-2025-12-01` | 非思考模式 + `response_format=json_object` + 服务端 JSON Schema 二次校验 |
+| ASR 对照候选 | 腾讯云 `SentenceRecognition` | 仅在同一批脱敏/已授权语音语料上对照，不直接进生产 |
+| LLM 备选 | 腾讯云 TokenHub 的国内文本模型 | 供应商适配层预留，M0 不同时维护两条生产路径 |
+
+不建议把 OpenAI API 作为当前 Petstore 中国大陆生产默认。OpenAI 官方说明仅支持列表中的国家和地区，中国大陆不在当前列表中；未列出地区不受支持，且可能导致账号被停用。
+
+这个结论是 **M0 工程默认**，不是长期供应商锁定。所有外部能力必须通过 Petstore 自有适配接口调用。
+
+## 2. 选型前提
+
+智能预约不是知识问答或通用 Agent。它的模型任务只有：
+
+1. 把当次文字和已验证草稿转换成结构化 `draftPatch`；
+2. 识别 `book / modify / end / fallback` 等有限意图；
+3. 标记歧义和建议下一个状态机动作。
+
+它不需要联网检索、知识库、长上下文、平台托管 Agent 或模型直接工具调用。宠物、服务和号源必须由 Petstore 后端确定性解析。
+
+因此选型优先级为：
+
+1. 中国大陆可达与明确数据部署范围；
+2. 中文口语、时间表达、宠物名称和门店服务识别；
+3. 非思考模式下稳定输出 JSON；
+4. 可固定模型快照，避免别名自动升级导致行为漂移；
+5. 明确的密钥、区域、超时、限流、费用和数据保留口径；
+6. 最终才是模型绝对能力和单次价格。
+
+## 3. 候选方案评估
+
+### 3.1 阿里云百炼全链路（推荐 M0 默认）
+
+**区域和网络**
+
+- 百炼官方提供华北2（北京）`cn-beijing` 地域和中国内地服务部署范围；
+- 官方地域说明称推理过程数据不持久化、传输加密，静态数据位于所选地域；
+- 生产建议使用业务空间专属域名，不使用试用域名。
+
+**语音转写**
+
+- `qwen3-asr-flash-2026-02-10` 支持普通话、四川话、闽南语、吴语、粤语等中文语音类型及多语种；
+- 官方 OpenAI 兼容接口支持公网 URL 或 Base64 Data URL，可在录音结束后同步转写，无需把用户录音中转到公网 OSS；
+- 官方允许以 system message 提供背景文本和实体词表，M0 只传当前门店服务名和当前 customer 的宠物展示名，不传手机号或其他客户数据；
+- 官方限制是 5 分钟/10 MB，M0 继续使用更小的 60 秒/3 MB 业务门禁；
+- 当前官方列价为 `0.00022 元/秒`，不包含活动优惠。
+
+**结构化意图提取**
+
+- `qwen-plus-2025-12-01` 在华北2（北京）官方标注支持 Function Calling 和结构化输出；
+- 百炼 OpenAI 兼容接口支持 `response_format={"type":"json_object"}`；
+- M0 使用固定快照 `qwen-plus-2025-12-01`，不使用可自动升级的 `latest` 别名；
+- M0 关闭思考模式，不开启联网或平台内置工具；
+- JSON mode 只保证可解析 JSON，Petstore 服务端仍必须校验字段、枚举、长度和状态转换。
+
+**风险**
+
+- Petstore 当前服务器在腾讯云，调用百炼需经过公网 HTTPS，必须做真实延迟和可用性实测；
+- 需新开阿里云百炼业务空间、独立 API Key 和费用告警；
+- 语音及文本的合同保留、删除和工单口径需在生产开通前再做一次 Access / Privacy Review。
+
+### 3.2 腾讯云全链路（对照/备选）
+
+**语音转写优势**
+
+- `SentenceRecognition` 适合 60 秒内短音频，支持音频数据或 URL，大小不超过 3 MB；
+- 官方文档列出普通话、粤语、上海话、四川话等多种方言，默认频率限制 30 次/秒；
+- 可直接在现有腾讯云账号与服务器体系中配置，运维链路较短。
+
+**隐私注意点**
+
+- 腾讯云 ASR SDK 隐私规则要求开发者在收集和上传音频前完成告知和合法授权；
+- 官方 FAQ 说明上传音视频文件不会保存，但识别后的文本文件会在服务器上保存 7 天；
+- 腾讯云语音优化用户数据授权是自愿授权，Petstore 不应开启该额外授权。
+
+因为 Petstore 方案的默认原则是不持久化完整对话原文，「识别文本保留 7 天」必须在隐私告知和供应商数据处理评审中明确，不能只依赖我们自己不落库。
+
+**文本模型平台变化**
+
+- 腾讯云官方已说明原混元/DeepSeek API 售卖入口逐步迁移到 TokenHub；
+- 新项目应使用 TokenHub 而非旧混元平台，OpenAI SDK 兼容 `base_url` 为 `https://tokenhub.tencentmaas.com/v1`；
+- TokenHub 可选模型变化较快，正式纳入前需按具体模型快照验证 JSON 遵循、时间表达和延迟。
+
+### 3.3 腾讯 ASR + 阿里 Qwen（仅当实测显著更好）
+
+混合方案可在不改模型的情况下使用腾讯 ASR，但会引入：
+
+- 两套云账号、密钥、费用告警和故障域；
+- 两份数据处理和隐私告知边界；
+- 更长的排障链路。
+
+只有当腾讯 ASR 在 Petstore 脱敏语音语料的关键槽位准确率显著高于 `qwen3-asr-flash-2026-02-10`，且 7 天识别文本保留已通过隐私评审时，才采用混合方案。
+
+### 3.4 OpenAI（非当前生产候选）
+
+OpenAI 官方提供语音转写和结构化模型能力，但当前官方 API 支持国家与地区列表不包含中国大陆。官方同时说明，从未列出地区访问或提供访问可能导致账号被阻止或暂停。
+
+因此本项目不使用绕过地区支持范围的网络或账号方案，也不将其写入当前生产 Runbook。
+
+## 4. M0 固定配置建议
+
+### 4.1 模型调用
+
+- Model：`qwen-plus-2025-12-01`
+- Region：`cn-beijing`
+- Mode：非思考
+- Streaming：关闭，M0 使用完整 JSON 响应
+- Response format：`json_object`
+- Function Calling：关闭，模型不拥有 Petstore 工具
+- Web search / built-in tools：关闭
+- Temperature：低随机性，编码前经 30 条语料实测后冻结
+- Timeout：建议 3 秒超时、不进行多次自动重试，最终值以腾讯云服务器实测为准
+
+### 4.2 语音调用
+
+- Model：`qwen3-asr-flash-2026-02-10`
+- Region：`cn-beijing`
+- Input：服务端从短期上传流读取字节，转 Base64 Data URL
+- Business limit：单段不超过 60 秒、3 MB
+- Language hint：中文，结果仍由用户编辑确认
+- Context glossary：宠小它、当前门店实际服务名、当前 customer 的宠物展示名；不上传手机号、其他客户宠物名或全量客户名单
+- Raw audio persistence：禁止
+
+### 4.3 密钥与环境变量
+
+为了允许分别轮换和后续切换供应商，即使 M0 同用阿里云，也保留独立逻辑配置：
+
+```dotenv
+PETSTORE_BOOKING_AGENT_ENABLED=false
+PETSTORE_BOOKING_AGENT_LLM_PROVIDER=aliyun
+PETSTORE_BOOKING_AGENT_LLM_BASE_URL=https://<workspace-id>.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
+PETSTORE_BOOKING_AGENT_LLM_MODEL=qwen-plus-2025-12-01
+PETSTORE_BOOKING_AGENT_LLM_API_KEY=<from-secret-store>
+PETSTORE_BOOKING_AGENT_LLM_TIMEOUT_MS=3000
+
+PETSTORE_BOOKING_AGENT_ASR_PROVIDER=aliyun
+PETSTORE_BOOKING_AGENT_ASR_BASE_URL=https://<workspace-id>.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
+PETSTORE_BOOKING_AGENT_ASR_MODEL=qwen3-asr-flash-2026-02-10
+PETSTORE_BOOKING_AGENT_ASR_API_KEY=<from-secret-store>
+PETSTORE_BOOKING_AGENT_ASR_TIMEOUT_MS=5000
+```
+
+上述只是变量名与占位，不是可用密钥。真实 Workspace ID 和 API Key 不进 Git、聊天、日志、截图或测试 fixture。
+
+## 5. 脱敏语料对照方案
+
+### 5.1 文字意图集
+
+建立 30 条合成/脱敏中文预约用例：
+
+- 8 条标准预约；
+- 5 条相对日期与时间段；
+- 4 条多宠物/同名歧义；
+- 4 条服务同义表达；
+- 3 条无号、过去日期或非营业时间；
+- 3 条修改上一轮草稿；
+- 3 条越界请求（价格编造、任意宠物 ID、绕过确认）。
+
+每条用例只保存预期结构化字段和下一状态，不保存真实客户资料。
+
+### 5.2 语音对照集
+
+- 从文字集选 20 条，由已知情并同意的测试人员录制；
+- 覆盖普通话、轻微口音、室内背景声和宠物名/服务名；
+- 不使用门店客户的真实录音，不在 Git 保存可识别真人的音频；
+- 本地音频仅用于一次性对照，结果只归档脱敏文本、槽位判定和延迟。
+
+### 5.3 判定指标
+
+| 类型 | 指标 | M0 建议门槛 |
+|---|---|---|
+| LLM | 输出可解析 JSON | 30/30 |
+| LLM | 意图、宠物查询词、服务查询词、日期表达、时间窗口槽位准确率 | ≥ 90% |
+| LLM | 越权请求进入写路径或产生伪造业务事实 | 0 |
+| ASR | 宠物名、服务名、日期/时间等关键槽位识别准确率 | ≥ 90% |
+| ASR | 转写延迟 p95 | ≤ 3 秒，以腾讯云当前服务器实测 |
+| LLM | 意图提取延迟 p95 | ≤ 2 秒 |
+| 链路 | 语音结束到确定性回复 p95 | ≤ 5 秒 |
+
+ASR 供应商的最终选择以「关键槽位准确率 + p95 延迟 + 数据保留可接受性」为准，不以通用宣传的全局字错率代替 Petstore 业务语料。
+
+## 6. 试点成本量级
+
+以 50 个试点 session 、每个 session 2 段 10 秒语音、4 次模型调用为示例：
+
+- ASR：`50 * 2 * 10 * 0.00022 元 = 0.22 元`；
+- LLM：假设每次 1000 输入 token + 200 输出 token，按当前华北2列价 `0.8 元/百万输入 token` 与 `2 元/百万输出 token`，约 `0.24 元`；
+- 示例总模型调用费约 `0.46 元`，不包含公网流量、账号优惠、日志和人工评测成本。
+
+该数字只说明 M0 小样本的 API 费用不是核心矛盾，不是生产预算承诺。实际决策优先看准确性、数据边界、稳定性和降级。
+
+## 7. 生产前必须完成
+
+- [ ] 开通华北2（北京）百炼业务空间，确认 Workspace 专属域名可用。
+- [ ] 为 LLM 和 ASR 创建可独立轮换的服务端密钥，不共享个人开发密钥。
+- [ ] 确认数据处理、保留、删除、不用于训练和工单响应口径。
+- [ ] 在小程序隐私声明和首次语音使用前完成明确告知，只在用户主动按住录音时收集。
+- [ ] 在腾讯云实际后端服务器完成 DNS、TLS、p50/p95 延迟、超时和失败降级实测。
+- [ ] 开启预算与异常用量告警，限制单用户和单门店频率。
+- [ ] 模型快照、提示词版本、schema 版本和供应商请求 ID 可追溯，但日志不保存完整对话。
+
+## 8. 官方资料
+
+### 阿里云
+
+- [选择地域、服务部署范围和接入域名](https://help.aliyun.com/zh/model-studio/regions/)
+- [语音识别模型选型](https://help.aliyun.com/zh/model-studio/asr-model/)
+- [qwen3-asr-flash 模型信息](https://help.aliyun.com/zh/model-studio/qwen3-asr-flash)
+- [Qwen-ASR API 参考](https://help.aliyun.com/zh/model-studio/qwen-asr-api-reference)
+- [非实时语音识别](https://help.aliyun.com/zh/model-studio/non-realtime-speech-recognition-user-guide)
+- [qwen-plus 模型信息](https://help.aliyun.com/zh/model-studio/qwen-plus)
+- [结构化输出](https://help.aliyun.com/en/model-studio/qwen-structured-output)
+- [百炼产品与数据说明](https://help.aliyun.com/zh/model-studio/what-is-model-studio)
+
+### 腾讯云
+
+- [一句话识别 API](https://cloud.tencent.com/document/api/1093/35646)
+- [语音识别请求结构与地域接入](https://cloud.tencent.com/document/product/1093/35639)
+- [语音识别 SDK 个人信息保护规则](https://cloud.tencent.com/document/product/1093/73072)
+- [语音识别功能 FAQ（含音频/识别文本保留口径）](https://cloud.tencent.com/document/faq/1093/35802)
+- [语音识别用户数据授权协议](https://cloud.tencent.com/document/product/1093/115535)
+- [TokenHub 迁移指南](https://cloud.tencent.com/document/product/1823/131382)
+
+### OpenAI
+
+- [OpenAI API 支持的国家和地区](https://help.openai.com/en/articles/5347006-openai-api-supported-countries-and-territories)