# 智能预约助手 M0 编码任务 brief

> 日期：2026-08-02<br>
> 状态：**Batch 2 已完成 / Batch 3 待实施**<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>
> Architecture Review Required：`Yes — completed by M0 ADR`<br>
> Data Model Review Required：`Yes — proposal completed; implementation diff requires review`<br>
> Access / Privacy Review Required：`Yes — development boundary completed; live provider/production pending`<br>
> RC Included：`No`

**需求来源**

- [智能预约助手产品与技术方案 v0.1](./宠小它智能预约助手-产品与技术方案-v0.1.md)
- [模型与语音供应商选型](./智能预约助手-模型与语音供应商选型-2026-08-02.md)
- [M0 契约与数据模型 ADR](./架构决策-智能预约助手M0契约与数据模型-2026-08-02.md)
- [`booking-intent-v1` JSON Schema](./contracts/booking-intent-v1.schema.json)
- [M0 OpenAPI 契约](./contracts/booking-agent-m0.openapi.yaml)
- [M0 执行队列](./智能预约助手-M0执行队列-2026-08-02.md)

## 1. M0 交付结果

宠主在普通预约页先选定门店，并在已登录状态进入「一句话预约」。系统依次：

1. 使用已选 `storeId` 创建会话；
2. 转写语音（文字输入跳过）；
3. 提取宠物查询词、服务查询词、日期表达、时间偏好和备注；
4. 在当前 customer 和 session 门店范围内解析真实 Pet 与 ServiceType；
5. 调用现有容量服务获取真实号源；
6. 展示可修改草稿卡；
7. 宠主点击「带入普通预约」后，回填现有 `CustAppointmentCreate`；
8. 宠主仍在现有表单上点击「提交预约」。

M0 成功的判定是 **「草稿真实、回填正确、普通预约未受影响」**，不是对话内创建预约。

## 2. 严格非目标

- 不实现 `POST /api/booking-agent/sessions/{sessionId}/confirm`；
- 不调用 `AppointmentService.createBooking`；
- 不新增 `Appointment` 字段或状态；
- 不做取消、改期、代客预约或指定技师；
- 不自动建立宠物档案；
- 不做匿名智能会话；
- 不开启外部搜索、知识库或模型托管 Agent；
- 不持久化原始语音或完整对话原文；
- 不进入当前 RC6 tag、发布物或生产配置。

## 3. 用户流程

```mermaid
flowchart TD
    A[宠主预约页] --> B[点击一句话预约]
    B --> C{已选有效门店}
    C -- 否 --> D[使用现有控件选择门店]
    D --> E{已登录 customer}
    C -- 是 --> E
    E -- 否 --> F[登录并保留返回路由和门店]
    F --> G[创建助手会话]
    E -- 是 --> G
    G --> H[文字或语音输入]
    H --> I[结构化意图提取]
    I --> J[服务端解析真实宠物和服务]
    J --> K[查询真实号源]
    K --> L{草稿完整}
    L -- 否 --> M[询问一个关键缺失项]
    M --> H
    L -- 是 --> N[展示草稿卡]
    N --> O[带入普通预约]
    O --> P[CustAppointmentCreate 回填]
    P --> Q[用户在现有表单提交]
```

### 3.1 入口

M0 只在宠主的 `CustAppointmentCreate` 顶部增加一个次级入口：

> 不想一项项填？「一句话预约」

该入口不取代当前表单和主提交按钮，不改宠主首页主 CTA。历史预约、报告页和宠物档案深链放到后续迭代。

M0 不在对话内选择门店。未选门店时先使用现有表单控件；创建 session 后 `storeId` 固定，切店需结束会话并重新创建。

### 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 字段：

- `id` BIGINT 自增主键；
- `session_id` VARCHAR(36) 唯一外部 UUID；
- `customer_user_id` BIGINT NOT NULL；
- `store_id` BIGINT NOT NULL；
- `status` VARCHAR(24) 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`。

索引：

- `UNIQUE (session_id)`；
- `(customer_user_id, status, expires_at)`；
- `(status, expires_at)` 用于过期和物理清理。

M0 不增加 `appointment_id`，也不建立 `t_booking_agent_turn`。`appointment_id` 唯一关联在 M1 幂等写入评审时再增加，避免 M0 数据模型暗示已具备直接创建能力。

M0 的 `entry_source` 只允许 `appointment_create`；历史预约、报告、首页和宠物档案入口尚未开放。

`draft_json` 只保存已验证 ID、时间约束和必要备注；不保存每轮用户原文、提示词或模型原始响应。

TTL 固定为创建后 30 分钟，不滑动续期；过期 24 小时后物理删除。M0 不增加 `deleted`，详细迁移和清理口径以 ADR 为准。

### 4.5 API 契约

M0 只实现：

| Method | Endpoint | 用途 |
|---|---|---|
| `POST` | `/api/booking-agent/sessions` | 创建已登录 customer 会话 |
| `POST` | `/api/booking-agent/sessions/{sessionId}/messages` | 提交文字/语音转写文本，刷新草稿 |
| `POST` | `/api/booking-agent/sessions/{sessionId}/transcriptions` | 在本人 session 下上传短音频并获取可编辑转写 |
| `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 是否存在。

创建 session 时 `storeId` 必填并验证存在；之后不再接受客户端传门店。消息和 fallback 请求必须携带当前 `draftVersion`，版本不一致返回 `DRAFT_VERSION_CONFLICT`。

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,
  "clearFields": [],
  "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 设计可验证、一次性的草稿交接机制。

Batch 0 已按 `documented` 证据增加以下设计条目；Batch 2 已用真实代码和测试将对应条目全部更新为 `anchored`：

- `ontology/objects.md`：`booking_agent_session` 最初的 `documented` 模型条目；
- `ontology/actions.md`：创建会话、提交消息、语音转写、回填草稿、结束会话；
- `ontology/events.md`：M0 三个漏斗事件；
- `ontology/rules.md`：customer 数据范围、无写工具、原始语音/原文不持久化、超时降级；
- `ontology/relations.md` 与 `graph/ontology.jsonl`；
- `coverage/ontology-coverage-audit.md`。

Batch 2 已在同一批补入真实代码/测试路径，并将对应条目从 `documented` 更新为 `anchored`；Batch 3 前端仍不得提前宣称已实现。

## 7. 自动化测试

### 7.1 后端必测

**意图提取契约**

- 30 条 `booking-intent-v1` fixture 均可解析；
- 无效 JSON、未知 schema 版本、未知枚举、超长备注和多余 ID 字段降级；
- 模型请求不包含手机号、token 或全量客户时间线。

**会话和权限**

- 未登录、boss/staff 调用助手 endpoint 被拒绝；
- 创建 session 缺少/伪造门店被拒绝，创建后不能跨店覆盖；
- 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

状态：**Completed — 2026-08-02**

- 冻结 `booking-intent-v1`、M0 状态子集、API shape 和业务码；
- 更新本体及机器图谱；
- 评审 session 表、TTL 和清理方式；
- 完成开发态 Access / Privacy Review；真实 provider 与生产复核仍在 Batch 4。

### Batch 1：供应商适配与契约测试

Owner：Backend Core

状态：**Completed — 2026-08-02（petstore-backend `77c6d69`）**

- 实现 provider interface、properties 和本地 HTTP stub；
- 实现 Qwen JSON 提取与 Qwen3-ASR-Flash 转写；
- 建立 30 条文字 fixture；
- 确保未配置/关闭时 fail closed，不影响应用启动和普通预约。

### Batch 2：会话、上下文解析和号源

Owner：Backend Core

状态：**Completed — 2026-08-02（petstore-backend `3c00065`）**

- 实现 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 条已知情同意的脱敏语音对照样本；
- 生产开启授权。