692 lines
32 KiB
Markdown
692 lines
32 KiB
Markdown
# 宠小它智能预约助手：产品与技术方案 v0.1
|
||
|
||
> 日期：2026-08-02<br>
|
||
> 状态：**M0 产品/架构/数据契约已冻结；尚未实现；真实供应商与生产隐私评审未完成**<br>
|
||
> 目标用户：`customer` 宠主<br>
|
||
> Workstream：`Core Booking Flow`<br>
|
||
> 建议 Owner：`Product Design` + `Customer Experience FE` + `Backend Core`<br>
|
||
> Paired QA：`Core Flow QA`<br>
|
||
> Architecture Review Required：`Yes`<br>
|
||
> Data Model Review Required：`Yes`<br>
|
||
> Access / Privacy Review Required：`Yes`<br>
|
||
> RC 边界：**不纳入 `phase2-pilot-rc6`；当前 RC 仍以基础预约和真实门店试点为先**
|
||
|
||
**配套文档**
|
||
|
||
- [模型与语音供应商选型](./智能预约助手-模型与语音供应商选型-2026-08-02.md)
|
||
- [M0 编码任务 brief](./智能预约助手-M0编码任务brief-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. 结论
|
||
|
||
建议将该能力定义为 **「可执行的智能预约助手」**，而不是泛化客服聊天机器。
|
||
|
||
它负责把宠主的自然语言转换为结构化预约草稿，通过现有 Petstore 预约域查询真实宠物、门店服务和可约时段。M0 只将草稿带入现有表单，仍由用户在普通表单中提交；对话内直接创建 `Appointment` 是 M1 候选能力。
|
||
|
||
**核心原则：模型负责「听懂人话」，Petstore 预约域负责「决定什么能约」。**
|
||
|
||
普通预约表单必须保留，智能助手是另一种输入方式，不是唯一入口，也不改变 `Appointment` 的 `new -> doing -> done/cancel` 履约状态机。
|
||
|
||
## 2. 产品机会与首发场景
|
||
|
||
### 2.1 要解决的问题
|
||
|
||
现有预约表单的门店、宠物、服务、日期、时段和备注结构是正确的，但对老客复约仍存在重复操作：
|
||
|
||
- 宠主心里通常已经有一句完整需求，例如「周六下午给球球再洗一次」；
|
||
- 门店、宠物和上次服务往往已有历史事实，但宠主需要重新选择；
|
||
- 「周六下午」「三点以后」「和上次一样」等意图需要先被理解，再转换为精确号源。
|
||
|
||
### 2.2 入口优先级
|
||
|
||
下列为长期入口价值排序。M0 已冻结为仅从 `CustAppointmentCreate` 顶部次级入口进入，且必须先用现有控件选定门店。
|
||
|
||
1. **服务报告或历史预约：「跟助手约下次」**
|
||
上下文最完整，可在登录与归属校验后预填门店、宠物和上次服务。
|
||
2. **宠主首页：「一句话预约」**
|
||
适合有明确需求的老客，与「普通预约」并列。
|
||
3. **宠物档案：「给 TA 约服务」**
|
||
预填宠物，只询问门店、服务和时间。
|
||
|
||
首发不建议在公开报告页直接开始匿名助手会话。若从公开报告进入，应先完成 customer 登录，再由后端校验源预约是否归属当前宠主；不得把完整 `report_token` 存入会话、日志或模型上下文。
|
||
|
||
### 2.3 核心假设
|
||
|
||
- 对已有宠物和服务历史的宠主，对话式复约比重新填六个字段更省力。
|
||
- 语音的核心价值是快速表达时间偏好和宠物备注，不是为了模拟真人客服。
|
||
- 「可修改的确认卡 + 明确确认」能在便捷性和业务确定性之间取得平衡。
|
||
|
||
## 3. 范围与非目标
|
||
|
||
### 3.1 MVP 范围
|
||
|
||
- 仅面向已登录 `customer`；
|
||
- 支持文字与语音转写两种输入；
|
||
- 仅使用当前 customer 可访问的宠物档案；
|
||
- 仅使用目标门店真实在售服务和现有可约时段；
|
||
- 识别精确日期、相对日期、星期和时间段偏好；
|
||
- 生成可编辑的预约确认卡；
|
||
- 提供「改时间」「换服务」「切换到普通预约」；
|
||
- 记录助手漏斗事件，最终创建仍由现有预约域完成。
|
||
|
||
### 3.2 明确不做
|
||
|
||
- 不做泛化门店客服、开放问答或外部网络检索；
|
||
- 不允许模型自行生成服务、价格、门店承诺或可约时段；
|
||
- 不使用智能助手创建或修改宠物档案；
|
||
- 不做取消、改期或改服务等已有预约变更；
|
||
- 不做技师指定，直到技师排班和技能模型真实落地；
|
||
- 不提供宠物医疗建议，不将行为或健康备注转化为医疗结论；
|
||
- 不引入订单、支付、储值、套餐或跨店组织能力；
|
||
- 不替换普通预约表单。
|
||
|
||
## 4. 用户体验
|
||
|
||
### 4.1 标准对话
|
||
|
||
> **宠主语音**：「周六下午给球球洗澡，三点以后都行。」<br>
|
||
> **助手**：「球球预约精洗护理，预计 60 分钟。本周六 15:00、16:30 和 17:00 可约，你选哪个？」<br>
|
||
> **宠主**：「三点。」<br>
|
||
> **助手**：展示确认卡，不自动提交。
|
||
|
||
确认卡至少展示：
|
||
|
||
- 门店名称；
|
||
- 宠物名称和类型；
|
||
- 服务项目和预计时长；
|
||
- 绝对日期、开始时间和预计结束时间；
|
||
- 宠主提供的备注；
|
||
- 「修改」「带入普通预约」和「普通预约」操作。M1 通过写路径安全评审后，才将主操作改为「确认预约」。
|
||
|
||
### 4.2 澄清规则
|
||
|
||
- 一次优先询问一个高价值缺失项，避免连续追问已知信息。
|
||
- 同名宠物或多只宠物时，必须让宠主选择，不用模型置信度自动判断。
|
||
- 「和上次一样」只能从归属当前 customer 的已有预约中解析。
|
||
- 「周六」「明天」等相对时间需按门店时区转换，确认卡必须展示绝对日期。
|
||
- 「下午」「晚一点」只形成搜索约束，不直接变成最终号源。
|
||
- 候选号源默认给出 3 个；少于 3 个时全部展示，无号源时建议下一个有号源日期。
|
||
|
||
### 4.3 登录与中断恢复
|
||
|
||
- 普通预约仍保持「提交时登录 + guest 草稿恢复」的现有口径。
|
||
- 智能助手 MVP 在创建服务端会话前要求 customer 登录，因为它需要读取归属宠物和历史事实。
|
||
- M0 在创建会话前还要求已选定有效门店；对话不负责选店，session 创建后不允许切店。
|
||
- 客户端可在登录前保存入口来源和非敏感意图，但不得在未登录状态调用宠物或历史数据工具。
|
||
- 会话过期后可将已解析的非敏感草稿回填到普通表单，不能自动续约或提交。
|
||
|
||
## 5. 会话状态机
|
||
|
||
智能会话状态与 `Appointment.status` 完全分离，不得为了对话流程新增预约状态。
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> collecting
|
||
collecting --> proposing: 门店宠物服务和时间约束齐备
|
||
proposing --> collecting: 需要补充或修改
|
||
proposing --> confirmable: 选定真实可约时段
|
||
confirmable --> collecting: 用户修改草稿
|
||
confirmable --> submitting: 用户点击确认预约
|
||
submitting --> booked: 权限和容量复核通过
|
||
submitting --> needs_reselection: 号源已变化
|
||
needs_reselection --> proposing: 重新查询号源
|
||
collecting --> fallback: 模型不可用或用户选择表单
|
||
proposing --> fallback
|
||
confirmable --> fallback
|
||
collecting --> cancelled: 用户结束
|
||
collecting --> expired: 会话过期
|
||
```
|
||
|
||
| 状态 | 语义 | 允许写 `Appointment` |
|
||
|---|---|---|
|
||
| `collecting` | 收集和解析需求 | 否 |
|
||
| `proposing` | 查询真实号源并给出候选 | 否 |
|
||
| `confirmable` | 草稿完整，等待明确确认 | 否 |
|
||
| `submitting` | 加锁会话并复核预约规则 | 仅可调用预约域服务 |
|
||
| `booked` | 已关联真实 `Appointment` | 已写入 |
|
||
| `needs_reselection` | 确认时号源已变化 | 否 |
|
||
| `fallback` / `expired` / `cancelled` | 结束智能会话 | 否 |
|
||
|
||
M0 只实现 `collecting`、`proposing`、`confirmable`、`fallback`、`expired` 和 `cancelled`。用户在 `confirmable` 点击「带入普通预约」时离开助手，由现有表单完成提交；`submitting`、`booked` 和 `needs_reselection` 是 M1 状态，M0 不实现。
|
||
|
||
## 6. 系统架构与权威边界
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[宠主文字] --> D[会话编排器]
|
||
B[宠主语音] --> C[语音转写适配器]
|
||
C --> D
|
||
D --> E[模型：意图与约束提取]
|
||
E --> F[结构化输出校验]
|
||
F --> G[确定性预约状态机]
|
||
G --> H[宠物与归属查询]
|
||
G --> I[门店服务查询]
|
||
G --> J[真实可约时段查询]
|
||
H --> K[确认卡]
|
||
I --> K
|
||
J --> K
|
||
K --> L[M0 带入普通预约]
|
||
L --> M[CustAppointmentCreate 回填]
|
||
M --> N[现有预约域复核与创建]
|
||
K -. M1 另立 ADR 后 .-> O[对话内受控确认]
|
||
```
|
||
|
||
### 6.1 模型可以做的事
|
||
|
||
- 识别意图：创建预约、修改草稿、结束会话或切换表单；
|
||
- 提取非权威文本约束：宠物称呼、服务需求、相对日期、时间偏好、备注；
|
||
- 根据状态机的下一动作生成简短、可理解的回复。
|
||
|
||
模型输出必须通过冻结的 [`booking-intent-v1`](./contracts/booking-intent-v1.schema.json) JSON Schema：
|
||
|
||
```json
|
||
{
|
||
"schemaVersion": "booking-intent-v1",
|
||
"intent": "book",
|
||
"petQuery": "球球",
|
||
"serviceQuery": "洗澡",
|
||
"dateExpression": "本周六",
|
||
"timeWindow": { "start": "15:00", "end": null },
|
||
"remark": null,
|
||
"clearFields": [],
|
||
"ambiguities": [],
|
||
"nextAction": "resolve_context"
|
||
}
|
||
```
|
||
|
||
`petQuery` 和 `serviceQuery` 只是搜索文本，不是业务 ID。所有 ID 必须由后端在当前登录上下文和门店数据范围中解析；未知字段和越界枚举直接拒绝，不从残缺输出猜测。
|
||
|
||
### 6.2 模型不可以做的事
|
||
|
||
- 不直接访问数据库或任意 HTTP 地址；
|
||
- 不传入 `customerUserId`、`storeId` 或 `petId` 作为权限事实；
|
||
- 不直接调用 `AppointmentService.createBooking`；
|
||
- 不决定最终号源，不绕过服务时长、连续容量桶和门店锁；
|
||
- 不修改 `Appointment.status`；
|
||
- 不获取手机号、完整 `report_token`、员工内部信息或与预约无关的客户时间线。
|
||
|
||
### 6.3 内部工具白名单
|
||
|
||
| 工具 | 权限 | 返回的最小数据 | 失败处理 |
|
||
|---|---|---|---|
|
||
| `load_booking_context` | 只读 | 已验证的入口门店、源预约摘要 | 要求选门店或切换表单 |
|
||
| `list_customer_pets` | 只读 | `petId`、展示名、类型 | 无档案时切换普通表单 |
|
||
| `list_store_services` | 只读 | `serviceTypeId`、名称、时长 | 给出真实服务选项 |
|
||
| `search_available_slots` | 只读 | 开始/结束时间、可约性 | 换日期或切换表单 |
|
||
| `resolve_previous_booking` | 只读 | 归属校验后的门店/宠物/服务 ID | 忽略历史预填并继续收集 |
|
||
|
||
白名单中不包含写工具。M0 由普通表单在助手之外完成最终创建；M1 如增加确认 endpoint，也必须在模型调用之外进入预约域。
|
||
|
||
## 7. 预约草稿与数据模型提案
|
||
|
||
### 7.1 `BookingDraft`
|
||
|
||
| 字段 | 来源 | 是否业务权威 | 规则 |
|
||
|---|---|---|---|
|
||
| `customerUserId` | `CurrentUserContext` | 是 | 不接受客户端或模型传入 |
|
||
| `storeId` | 已验证入口或用户选择 | 是 | 一次会话只有一个目标门店 |
|
||
| `petId` | 归属宠物解析 | 是 | 必须属于当前 customer |
|
||
| `serviceTypeId` | 门店服务解析 | 是 | 必须属于当前门店 |
|
||
| `dateConstraint` | 模型提取 + 时区解析 | 否 | 用于搜索，不直接提交 |
|
||
| `timeWindow` | 模型提取 | 否 | 只是偏好约束 |
|
||
| `appointmentTime` | 真实号源选择 | 是 | 必须是精确的未来时间 |
|
||
| `remark` | 宠主原意摘要 | 否 | 限长、可编辑，不生成医疗结论 |
|
||
| `draftVersion` | 服务端 | 是 | 每次草稿变更递增，确认时防旧版提交 |
|
||
|
||
确认时不直接信任草稿中的展示快照。后端需重新加载 Pet、ServiceType、Store 和容量事实，再由现有预约域生成 `petName`、`petType`、`serviceType`和 `durationMinutes` 快照。
|
||
|
||
### 7.2 候选会话表
|
||
|
||
新增 `t_booking_agent_session`，不将对话状态塞入 `t_appointment`。M0 字段已由 ADR 冻结：
|
||
|
||
| 字段 | 语义 |
|
||
|---|---|
|
||
| `id` | BIGINT 自增内部主键 |
|
||
| `session_id` | VARCHAR(36) 唯一外部 UUID，不暴露内部主键 |
|
||
| `customer_user_id` | 从登录上下文派生 |
|
||
| `store_id` | NOT NULL，会话固定数据范围 |
|
||
| `status` | M0 六个状态之一 |
|
||
| `draft_json` | 最小结构化草稿，不存原始语音 |
|
||
| `draft_version` | 乐观版本号 |
|
||
| `entry_source` | M0 固定 `appointment_create` |
|
||
| `input_modality` | `text` / `voice` / `mixed` |
|
||
| `expires_at` | 创建后 30 分钟，不滑动续期 |
|
||
| `create_time` / `update_time` | 审计时间 |
|
||
|
||
数据建议：
|
||
|
||
- 以 `(customer_user_id, status, expires_at)` 建立查询索引；
|
||
- 以 `(status, expires_at)` 支持过期标记和清理；
|
||
- 会话过期 24 小时后物理删除，M0 不增加 `deleted`；
|
||
- M0 不增加 `source_appointment_id` 或 `appointment_id`；
|
||
- 不新增 `t_booking_agent_turn` 原文表；模型每轮以当前草稿和当次输入工作，避免默认持久化完整对话。
|
||
|
||
上述是 **M0 已评审契约**，不代表当前生产库已存在；迁移实现 diff 仍必须经 Data Model Review。
|
||
|
||
### 7.3 预约来源与事件
|
||
|
||
不改变现有 `BusinessEvent.source=customer/admin`的操作人语义。长期可在 `appointment_created` 的 `metadata_json` 评审独立维度：
|
||
|
||
```json
|
||
{
|
||
"bookingOrigin": "customer",
|
||
"bookingChannel": "agent_voice",
|
||
"agentSessionId": "<opaque-session-id>"
|
||
}
|
||
```
|
||
|
||
`bookingChannel` 候选值：`form`、`agent_draft`、`agent_text`、`agent_voice`、`admin`、`follow_up`。`agent_draft` 只表示智能助手提供了已验证草稿；`agent_text` 和 `agent_voice` 保留给 M1 对话内直接创建路径。初始 M0 不修改 `appointment_created` 事件，如需归因表单提交，必须另行评审服务端验证的一次性草稿交接，不接受客户端自由上报渠道。不建议 MVP 为此修改 `Appointment` 主表。
|
||
|
||
冻结的 M0 新事件：
|
||
|
||
- `booking_agent_started`；
|
||
- `booking_agent_draft_ready`；
|
||
- `booking_agent_fallback`。
|
||
|
||
这些事件只用于漏斗和运行分析；只有真实创建成功的 `appointment_created` 才计为预约。M0 不增加 `booking_agent_confirmed`，不修改现有 `appointment_created`。
|
||
|
||
## 8. M0 API 冻结契约
|
||
|
||
契约已冻结、尚未实现。唯一机读权威是 [M0 OpenAPI](./contracts/booking-agent-m0.openapi.yaml)；响应沿用当前 `{ code, message, bizCode, data }` 外壳，除鉴权拦截的 HTTP 401 外，客户端以 body `code` 为业务结果。本功能不顺带重构全局响应语义。
|
||
|
||
### 8.1 Endpoint
|
||
|
||
| Method | Endpoint | M0 语义 |
|
||
|---|---|---|
|
||
| `POST` | `/api/booking-agent/sessions` | 以已选 `storeId` 创建 customer 会话；`entrySource` 由服务端固定 |
|
||
| `POST` | `/api/booking-agent/sessions/{sessionId}/messages` | 携带 `draftVersion`、`inputType` 和文本更新草稿 |
|
||
| `POST` | `/api/booking-agent/sessions/{sessionId}/transcriptions` | 在本人 session 下转写不超过 60 秒/3 MB 的短音频，仅返回可编辑文本 |
|
||
| `POST` | `/api/booking-agent/sessions/{sessionId}/fallback` | 携带 `draftVersion`，返回服务端验证的一次性回填草稿 |
|
||
| `DELETE` | `/api/booking-agent/sessions/{sessionId}` | 将本人非终态会话标记为 `cancelled` |
|
||
|
||
所有 endpoint 只允许已登录 `customer`；session 每次用 `sessionId + current.userId` 查询，他人 session 和不存在 session 统一为 `SESSION_NOT_FOUND`。创建后 `storeId` 固定，消息和 fallback 必须进行草稿版本检查。
|
||
|
||
M0 不注册 `/confirm`，不调用 `AppointmentService.createBooking`；M1 必须新立 ADR 审查写路径、行锁、幂等和事件归因。
|
||
|
||
### 8.2 业务码
|
||
|
||
| 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 会话响应，不用异常码表达。
|
||
|
||
## 9. 语音与模型集成边界
|
||
|
||
### 9.1 供应商适配
|
||
|
||
语音转写和语言模型分别通过后端适配器接入，业务服务不依赖某一厂商 SDK 的对话状态。
|
||
|
||
生产配置至少包括：
|
||
|
||
- 模型和语音能力总开关；
|
||
- 供应商 endpoint、模型名称和超时；
|
||
- 服务端密钥环境变量；
|
||
- 单用户和单门店频率限制；
|
||
- 单轮输入长度、语音大小和时长限制；
|
||
- 模型失败时的降级开关和成本上限。
|
||
|
||
密钥不写入代码、文档、提示词、日志或前端产物。上线前应纳入 production configuration preflight。
|
||
|
||
### 9.2 超时与降级
|
||
|
||
- 语音失败：保留本地输入状态，提供「重新说」和「改用文字」。
|
||
- 模型失败：不自动重复多次调用；保留已验证草稿并导向普通表单。
|
||
- 工具查询失败：展示业务错误，不让模型根据记忆补齐结果。
|
||
- M1 最终号源冲突：会话进入 `needs_reselection`，不创建失败预约或假成功记录。M0 只查询候选号源并回填表单。
|
||
|
||
## 10. 安全、隐私与可观测性
|
||
|
||
### 10.1 身份与数据范围
|
||
|
||
- 所有助手 endpoint 要求 customer 登录；不允许 boss/staff 借该入口传入任意 customer ID。
|
||
- session 每次读写都校验 `customer_user_id == CurrentUserContext.userId`。
|
||
- Pet 必须属于当前 customer，ServiceType 必须属于 session 门店。
|
||
- 模型工具调用只使用服务端已验证 ID，不使用模型或客户端宣称的身份 ID。
|
||
|
||
### 10.2 最小化数据
|
||
|
||
- 不向模型提供手机号、完整 `report_token`、密钥、会话 token、员工信息或全量客户时间线。
|
||
- 只提供当次预约必需的宠物展示名、类型、门店服务名和时间约束。
|
||
- 原始录音不落通用文件存储，转写完成或失败后立即释放。
|
||
- 默认不持久化完整用户对话原文；运行日志只保留脱敏 request ID、结果码、耗时、输入长度区间和模型版本。
|
||
|
||
### 10.3 提示词注入与输出安全
|
||
|
||
- 用户文本始终作为数据，不作为系统指令拼接到工具权限中。
|
||
- 模型只能返回约束 JSON Schema；未通过 schema 和枚举校验时直接降级。
|
||
- 工具名称和参数在服务端白名单中，不允许模型发起任意请求。
|
||
- 客户端不展示模型思考过程、系统提示词、工具调用原文或内部异常。
|
||
|
||
### 10.4 观测指标
|
||
|
||
| 指标 | 口径 |
|
||
|---|---|
|
||
| 助手启动数 | `booking_agent_started` 去重 session |
|
||
| 草稿完成率 | `draft_ready / started` |
|
||
| 助手预约成功率 | 有 `appointment_created` 的 agent session / started |
|
||
| 中位对话轮次 | 成功 session 的 customer message 数中位数 |
|
||
| 确认前修改率 | 进入 `confirmable` 后又修改草稿的 session / confirmable |
|
||
| 表单降级率 | `booking_agent_fallback / started` |
|
||
| 语音识别修改率 | 宠主编辑转写结果的 voice session / voice session |
|
||
| 最终号源冲突率 | `CAPACITY_FULL / confirm` |
|
||
| 重复预约事故 | 同一 session 关联多个 Appointment，期望恒为 0 |
|
||
| 越权或数据泄漏事故 | 任意跨 customer/跨店读写，期望恒为 0 |
|
||
|
||
## 11. 异常场景与产品反应
|
||
|
||
| 场景 | 产品反应 | 业务约束 |
|
||
|---|---|---|
|
||
| 找不到宠物 | 请宠主选择已有宠物或转普通表单 | 助手不自动建档 |
|
||
| 匹配到多只宠物 | 展示选择芯片 | 不用置信度代替选择 |
|
||
| 服务表达模糊 | 展示门店真实服务选项 | 不创造服务名称 |
|
||
| 当日无号 | 给出下一个有号日期 | 不承诺排队或准点履约 |
|
||
| 语音识别失败 | 重新说或改用文字 | 不提交空文本 |
|
||
| 模型超时/无效输出 | 保留草稿并转普通表单 | 不用模型记忆猜测 |
|
||
| 确认时号源已满 | 立即推荐新时段 | 不产生超容量预约 |
|
||
| M1 重复点击确认 | 返回同一预约成功页 | 会话行锁 + `appointment_id` 幂等 |
|
||
| 会话过期 | 新建会话或回填普通表单 | 不自动提交旧草稿 |
|
||
|
||
## 12. 分阶段交付
|
||
|
||
### M0：草稿助手（首发建议）
|
||
|
||
- 仅在现有 `CustAppointmentCreate` 顶部增加「一句话预约」次级入口；
|
||
- 支持文字和语音转写；
|
||
- 解析宠物、服务和时间偏好，查询真实号源；
|
||
- 生成确认卡，但「带入普通预约」只把草稿回填到现有 `CustAppointmentCreate`；
|
||
- 最终仍由现有表单提交，不新增智能层写入路径；
|
||
- 先在 1 家试点门店对老客开放，不影响 RC6 基线验证。
|
||
|
||
### M1：受控确认创建
|
||
|
||
- 在 M0 session 表上增加 `appointment_id`、确认 endpoint、行锁和幂等返回；
|
||
- 确认时重新校验权限、宠物归属、服务和容量；
|
||
- 补齐助手漏斗事件和 `bookingChannel`；
|
||
- 通过硬性安全验收后，再允许确认卡直接创建预约。
|
||
|
||
### M2：个性化复约与对照实验
|
||
|
||
- 支持「和上次一样」和宠物档案入口；
|
||
- 在一家门店做智能助手与普通表单的小流量对照；
|
||
- 将最终履约率、取消率和复约率与 `bookingChannel` 关联；
|
||
- 只有在真实使用证明更快或更高转化后，才扩大门店范围。
|
||
|
||
## 13. MVP 验收与试点门槛
|
||
|
||
### 13.1 硬性门禁
|
||
|
||
- [ ] M0 不存在助手 `/confirm` endpoint，不调用预约写服务。
|
||
- [ ] 助手不会返回门店不存在的服务或后端未返回的号源。
|
||
- [ ] 草稿只使用当前 customer 的宠物、session 门店服务和后端真实号源。
|
||
- [ ] 门店在会话前选定，session 创建后不能跨店更改。
|
||
- [ ] A customer 不能查询或选择 B customer 的宠物、历史预约或 session。
|
||
- [ ] 不将手机号、完整 `report_token`、session token 或密钥发送给模型或写入日志。
|
||
- [ ] 原始语音转写后立即释放，不出现在通用上传目录或报告媒体中。
|
||
- [ ] 模型、语音或工具失败时能保留已验证草稿并切换普通表单。
|
||
- [ ] `Appointment.status` 仍只有 `new`、`doing`、`done`、`cancel`。
|
||
- [ ] 仅记录 M0 三个漏斗事件，不修改 `appointment_created` 事件语义。
|
||
|
||
### 13.2 价值验证建议
|
||
|
||
首批 M0 先观察 `draft_ready / started`、`fallback / started`、语音转写修改率和普通表单回填成功率。下列「助手到真实预约」指标只能在有可验证的服务端草稿归因后使用，不接受客户端自由上报。
|
||
|
||
首批 20 个真实 session 用于发现语料和交互问题，不立即下商业化结论。稳定后可对 20～50 个老客 session 使用以下建议门槛：
|
||
|
||
- 助手启动到真实预约成功率 ≥ 70%；
|
||
- 成功 session 的宠主中位消息轮次 ≤ 4；
|
||
- 切换普通表单的比例 ≤ 25%；
|
||
- 进入确认卡后修改门店/宠物/服务/时间的 session 比例 ≤ 20%；
|
||
- 越权、超容量、重复预约和敏感数据泄漏事故 = 0。
|
||
|
||
上述价值门槛是试点假设，应在首批真实数据后与普通表单基线一起复核；不得用演示会话、测试预约或未履约预约代替真实样本。
|
||
|
||
## 14. M0 已冻结决策与生产前缺口
|
||
|
||
| ID | 决策 | 建议默认 | 责任人 |
|
||
|---|---|---|---|
|
||
| D1 | M0 首发入口 | `CustAppointmentCreate` 顶部次级入口；先选门店，再登录/创建 session | Product Design |
|
||
| D2 | 是否支持匿名助手 | MVP 不支持，普通表单继续支持 guest 草稿 | Product Design + System Architect |
|
||
| D3 | M0 是否直接创建预约 | 否，先回填现有表单 | Product Design + Backend Core |
|
||
| D4 | 模型与语音供应商 | 开发适配目标已选；生产开启仍受语料对照、数据区域和隐私复核阻塞 | System Architect + Backend Ops |
|
||
| D5 | 原文保留 | 默认不持久化对话原文，不持久化原始语音 | Access / Privacy Review |
|
||
| D6 | session TTL | 创建后固定 30 分钟，不滑动续期；过期 24 小时后物理删除 | Data Model |
|
||
| D7 | 助手对话风格 | 简短、一次一个关键问题，不模拟人格客服 | Product Design |
|
||
| D8 | 试点启动时机 | RC6 基础链路已用真实门店跑通并建立普通表单基线后 | 主控 PM |
|
||
|
||
## 15. 实施任务队列
|
||
|
||
当前可执行状态、owner、锁、依赖和验收口径只以 [M0 执行队列](./智能预约助手-M0执行队列-2026-08-02.md) 为准。其中 Batch 1–3 已具备开发边界；真实供应商和生产开启仍为 `Blocked`。
|
||
|
||
<details>
|
||
<summary>已被独立执行队列取代的历史草案（仅供审计，不执行）</summary>
|
||
|
||
以下 BA-01～BA-07 是契约冻结前的原始 Backlog，不再表示当前任务状态。
|
||
|
||
### BA-01 冻结智能预约产品与交互契约
|
||
|
||
```yaml
|
||
Task Name: 冻结智能预约产品与交互契约
|
||
Role: Product Design
|
||
Owner Agent: Product Design
|
||
Paired QA: Core Flow QA
|
||
Workstream: Core Booking Flow
|
||
Track: Product
|
||
Status: Backlog
|
||
Priority: P1
|
||
Repo/Path: docs/宠小它智能预约助手-产品与技术方案-v0.1.md
|
||
Service Lock: docs:booking-agent
|
||
Depends On: RC6 真实预约基线可用
|
||
Acceptance: 入口、登录、对话、确认卡、降级文案和 M0/M1 边界通过评审
|
||
RC Included: No
|
||
Due Date: TBD
|
||
Output Link: 本文档定稿版
|
||
Blocker Owner: 主控 PM
|
||
Commit / RC: Not Frozen
|
||
Architecture Review Required: Yes
|
||
Data Model Review Required: Yes
|
||
Access / Privacy Review Required: Yes
|
||
```
|
||
|
||
### BA-02 评审会话表、过期与幂等模型
|
||
|
||
```yaml
|
||
Task Name: 评审智能预约会话数据模型
|
||
Role: Data Model
|
||
Owner Agent: Data Model
|
||
Paired QA: Core Flow QA
|
||
Workstream: Architecture
|
||
Track: Review
|
||
Status: Backlog
|
||
Priority: P1
|
||
Repo/Path: docs/ontology; backend/src/main/java/com/petstore/entity; backend/db/migrations
|
||
Service Lock: data-model:booking-agent-session
|
||
Depends On: BA-01
|
||
Acceptance: 冻结 session 字段、索引、行锁、幂等、TTL、清理和迁移/回滚口径
|
||
RC Included: No
|
||
Due Date: TBD
|
||
Output Link: TBD
|
||
Blocker Owner: Data Model
|
||
Commit / RC: Not Frozen
|
||
Architecture Review Required: Yes
|
||
Data Model Review Required: Yes
|
||
Access / Privacy Review Required: Yes
|
||
```
|
||
|
||
### BA-03 实现智能预约会话、解析与只读工具后端
|
||
|
||
```yaml
|
||
Task Name: 实现智能预约会话解析与只读工具后端
|
||
Role: Backend Core
|
||
Owner Agent: Backend Core
|
||
Paired QA: Core Flow QA
|
||
Workstream: Core Booking Flow
|
||
Track: Coding
|
||
Status: Backlog
|
||
Priority: P1
|
||
Repo/Path: backend/src/main/java/com/petstore; backend/db/migrations; docs/ontology
|
||
Service Lock: backend:booking-agent-session+read-tools
|
||
Depends On: BA-01, BA-02
|
||
Acceptance: 会话状态、结构化输出校验、只读工具、宠物/门店数据范围、真实号源和表单回填契约有自动化测试，不包含 Appointment 写工具
|
||
RC Included: No
|
||
Due Date: TBD
|
||
Output Link: TBD
|
||
Blocker Owner: Backend Core
|
||
Commit / RC: Not Frozen
|
||
Architecture Review Required: Yes
|
||
Data Model Review Required: Yes
|
||
Access / Privacy Review Required: Yes
|
||
```
|
||
|
||
### BA-04 接入宠主文字语音、确认卡与表单降级
|
||
|
||
```yaml
|
||
Task Name: 接入宠主文字语音与预约确认卡
|
||
Role: Customer Experience Frontend
|
||
Owner Agent: Customer Experience FE
|
||
Paired QA: Core Flow QA
|
||
Workstream: Core Booking Flow
|
||
Track: Coding
|
||
Status: Backlog
|
||
Priority: P1
|
||
Repo/Path: frontend/src/pages/appointment; frontend/src/api; frontend/src/utils; frontend/pages.json
|
||
Service Lock: frontend:customer-booking-agent+shared-api
|
||
Depends On: BA-01, BA-03
|
||
Acceptance: H5/小程序支持文字和语音转写、草稿修改、绝对日期确认、防重提交和回填普通表单
|
||
RC Included: No
|
||
Due Date: TBD
|
||
Output Link: TBD
|
||
Blocker Owner: Customer Experience FE
|
||
Commit / RC: Not Frozen
|
||
Architecture Review Required: Yes
|
||
Data Model Review Required: No
|
||
Access / Privacy Review Required: Yes
|
||
```
|
||
|
||
### BA-05 实现受控确认与幂等预约创建
|
||
|
||
```yaml
|
||
Task Name: 实现智能助手受控确认与幂等预约创建
|
||
Role: Backend Core
|
||
Owner Agent: Backend Core
|
||
Paired QA: Core Flow QA
|
||
Workstream: Core Booking Flow
|
||
Track: Coding
|
||
Status: Backlog
|
||
Priority: P1
|
||
Repo/Path: backend/src/main/java/com/petstore; backend/db/migrations; docs/ontology
|
||
Service Lock: backend:booking-agent-confirm+appointment-create
|
||
Depends On: BA-01, BA-02, BA-03
|
||
Acceptance: 用户明确确认后才进入写路径；确认时复核身份、草稿版本、宠物、服务和容量；同一 session 并发/重试只返回同一 Appointment；事件可追溯
|
||
RC Included: No
|
||
Due Date: TBD
|
||
Output Link: TBD
|
||
Blocker Owner: Backend Core
|
||
Commit / RC: Not Frozen
|
||
Architecture Review Required: Yes
|
||
Data Model Review Required: Yes
|
||
Access / Privacy Review Required: Yes
|
||
```
|
||
|
||
### BA-06 配置模型、语音与生产降级边界
|
||
|
||
```yaml
|
||
Task Name: 配置智能预约模型语音与生产降级边界
|
||
Role: Backend Ops
|
||
Owner Agent: Backend Ops
|
||
Paired QA: Core Flow QA
|
||
Workstream: Release
|
||
Track: Ops
|
||
Status: Backlog
|
||
Priority: P1
|
||
Repo/Path: backend/deploy; production environment; docs/production runbook
|
||
Service Lock: ops:booking-agent-provider-config
|
||
Depends On: BA-03, BA-05
|
||
Acceptance: 密钥仅存环境、preflight 拒绝缺失/弱配置、超时降级可验证、日志无密钥/原始语音/完整对话
|
||
RC Included: No
|
||
Due Date: TBD
|
||
Output Link: TBD
|
||
Blocker Owner: Backend Ops
|
||
Commit / RC: Not Frozen
|
||
Architecture Review Required: Yes
|
||
Data Model Review Required: No
|
||
Access / Privacy Review Required: Yes
|
||
```
|
||
|
||
### BA-07 完成智能预约三类门禁与真实试点评估
|
||
|
||
```yaml
|
||
Task Name: 完成智能预约安全功能与价值验收
|
||
Role: Core Flow QA
|
||
Owner Agent: Core Flow QA
|
||
Paired QA: Backend Core / Customer Experience FE
|
||
Workstream: Core Booking Flow
|
||
Track: QA
|
||
Status: Backlog
|
||
Priority: P1
|
||
Repo/Path: docs/qa-reports; backend tests; frontend smoke
|
||
Service Lock: qa:booking-agent
|
||
Depends On: BA-03, BA-04, BA-05, BA-06
|
||
Acceptance: 确定性、权限/隐私、并发/幂等硬门禁全通过，并归档 20～50 个真实老客 session 指标
|
||
RC Included: No
|
||
Due Date: TBD
|
||
Output Link: TBD
|
||
Blocker Owner: Core Flow QA
|
||
Commit / RC: Not Frozen
|
||
Architecture Review Required: Yes
|
||
Data Model Review Required: Yes
|
||
Access / Privacy Review Required: Yes
|
||
```
|
||
|
||
</details>
|
||
|
||
## 16. 开发与验证清单
|
||
|
||
实现时至少需要：
|
||
|
||
1. 更新 `docs/ontology/objects.md`、`actions.md`、`events.md`、`rules.md`、`relations.md` 和 `graph/ontology.jsonl`；
|
||
2. 后端覆盖模型无效输出、跨 customer/跨店、宠物归属、服务下线、无号源、`draftVersion` 冲突、session 过期和「不存在助手写路径」；
|
||
3. 前端覆盖语音失败、模型失败、空输入、草稿修改、无号源、提交 loading 和普通表单降级；
|
||
4. 生产前检查供应商密钥、允许数据区域、超时、频控、日志脱敏和降级开关；
|
||
5. 以普通预约为基线，不用智能助手取代现有真实门店试点指标。
|
||
|
||
建议实现后必跑：
|
||
|
||
```bash
|
||
cd /Users/apple/_src/petstore/backend && mvn test
|
||
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/docs diff --check
|
||
```
|
||
|
||
## 17. 与现有实现的关系
|
||
|
||
| 现有能力 | 当前事实 | 智能层如何复用 |
|
||
|---|---|---|
|
||
| 宠主预约表单 | `frontend/src/pages/appointment/CustAppointmentCreate.vue` 已存在 | M0 回填草稿和最终提交的降级路径 |
|
||
| 宠物列表 | 宠主可查询自己的 Pet | 只在 customer 归属范围内解析 `petId` |
|
||
| 门店服务 | 服务项目具有名称和 `durationMinutes` | 智能助手只从真实列表中匹配 |
|
||
| 可约时段 | `/api/appointment/available-slots` 按时长和容量返回 | 可复用领域服务，不由模型计算 |
|
||
| 预约创建 | `AppointmentService.createBooking` 复核宠物、服务、时间和容量 | M1 确认 endpoint 的唯一写入权威 |
|
||
| 业务事件 | `appointment_created` 已持久化 | M0 只增加三个助手漏斗事件；`bookingChannel` 与直接创建归因留待 M1 评审 |
|
||
|
||
本方案是对现有预约入口的语义化扩展，不建立第二套预约、容量或身份系统。
|