736 lines
30 KiB
Markdown
736 lines
30 KiB
Markdown
# 宠小它智能预约助手：产品与技术方案 v0.1
|
||
|
||
> 日期：2026-08-02<br>
|
||
> 状态：**Draft / 待产品、架构、数据与隐私评审；尚未实现**<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 仍以基础预约和真实门店试点为先**
|
||
|
||
## 1. 结论
|
||
|
||
建议将该能力定义为 **「可执行的智能预约助手」**，而不是泛化客服聊天机器。
|
||
|
||
它负责把宠主的自然语言转换为结构化预约草稿，通过现有 Petstore 预约域查询真实宠物、门店服务和可约时段，最后由用户明确确认后才创建 `Appointment`。
|
||
|
||
**核心原则：模型负责「听懂人话」，Petstore 预约域负责「决定什么能约」。**
|
||
|
||
普通预约表单必须保留，智能助手是另一种输入方式，不是唯一入口，也不改变 `Appointment` 的 `new -> doing -> done/cancel` 履约状态机。
|
||
|
||
## 2. 产品机会与首发场景
|
||
|
||
### 2.1 要解决的问题
|
||
|
||
现有预约表单的门店、宠物、服务、日期、时段和备注结构是正确的，但对老客复约仍存在重复操作：
|
||
|
||
- 宠主心里通常已经有一句完整需求，例如「周六下午给球球再洗一次」；
|
||
- 门店、宠物和上次服务往往已有历史事实，但宠主需要重新选择；
|
||
- 「周六下午」「三点以后」「和上次一样」等意图需要先被理解，再转换为精确号源。
|
||
|
||
### 2.2 入口优先级
|
||
|
||
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>
|
||
> **助手**：展示确认卡，不自动提交。
|
||
|
||
确认卡至少展示：
|
||
|
||
- 门店名称；
|
||
- 宠物名称和类型；
|
||
- 服务项目和预计时长；
|
||
- 绝对日期、开始时间和预计结束时间；
|
||
- 宠主提供的备注；
|
||
- 「修改」「确认预约」和「普通预约」操作。
|
||
|
||
### 4.2 澄清规则
|
||
|
||
- 一次优先询问一个高价值缺失项，避免连续追问已知信息。
|
||
- 同名宠物或多只宠物时，必须让宠主选择，不用模型置信度自动判断。
|
||
- 「和上次一样」只能从归属当前 customer 的已有预约中解析。
|
||
- 「周六」「明天」等相对时间需按门店时区转换，确认卡必须展示绝对日期。
|
||
- 「下午」「晚一点」只形成搜索约束，不直接变成最终号源。
|
||
- 候选号源默认给出 3 个；少于 3 个时全部展示，无号源时建议下一个有号源日期。
|
||
|
||
### 4.3 登录与中断恢复
|
||
|
||
- 普通预约仍保持「提交时登录 + guest 草稿恢复」的现有口径。
|
||
- 智能助手 MVP 在创建服务端会话前要求 customer 登录，因为它需要读取归属宠物和历史事实。
|
||
- 客户端可在登录前保存入口来源和非敏感意图，但不得在未登录状态调用宠物或历史数据工具。
|
||
- 会话过期后可将已解析的非敏感草稿回填到普通表单，不能自动续约或提交。
|
||
|
||
## 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` | 结束智能会话 | 否 |
|
||
|
||
## 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[用户明确确认]
|
||
L --> M[AppointmentService 最终复核与创建]
|
||
```
|
||
|
||
### 6.1 模型可以做的事
|
||
|
||
- 识别意图：创建预约、修改草稿、结束会话或切换表单；
|
||
- 提取非权威文本约束：宠物称呼、服务需求、相对日期、时间偏好、备注；
|
||
- 根据状态机的下一动作生成简短、可理解的回复。
|
||
|
||
建议将模型输出限制为 JSON Schema：
|
||
|
||
```json
|
||
{
|
||
"intent": "book | modify | end | fallback",
|
||
"draftPatch": {
|
||
"petQuery": "球球",
|
||
"serviceQuery": "洗澡",
|
||
"dateExpression": "本周六",
|
||
"timeWindow": { "start": "15:00", "end": null },
|
||
"remark": null
|
||
},
|
||
"ambiguities": [],
|
||
"nextAction": "ask | resolve_context | search_slots | show_confirmation | fallback"
|
||
}
|
||
```
|
||
|
||
`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 | 忽略历史预填并继续收集 |
|
||
|
||
白名单中不包含写工具。最终创建由确认 endpoint 在模型调用之外完成。
|
||
|
||
## 7. 预约草稿与数据模型提案
|
||
|
||
### 7.1 `BookingDraft`
|
||
|
||
| 字段 | 来源 | 是否业务权威 | 规则 |
|
||
|---|---|---|---|
|
||
| `customerUserId` | `CurrentUserContext` | 是 | 不接受客户端或模型传入 |
|
||
| `storeId` | 已验证入口或用户选择 | 是 | 一次会话只有一个目标门店 |
|
||
| `petId` | 归属宠物解析 | 是 | 必须属于当前 customer |
|
||
| `serviceTypeId` | 门店服务解析 | 是 | 必须属于当前门店 |
|
||
| `dateConstraint` | 模型提取 + 时区解析 | 否 | 用于搜索，不直接提交 |
|
||
| `timeWindow` | 模型提取 | 否 | 只是偏好约束 |
|
||
| `appointmentTime` | 真实号源选择 | 是 | 必须是精确的未来时间 |
|
||
| `remark` | 宠主原意摘要 | 否 | 限长、可编辑，不生成医疗结论 |
|
||
| `sourceAppointmentId` | 已验证复约入口 | 是 | 可空，必须归属当前 customer |
|
||
| `draftVersion` | 服务端 | 是 | 每次草稿变更递增，确认时防旧版提交 |
|
||
|
||
确认时不直接信任草稿中的展示快照。后端需重新加载 Pet、ServiceType、Store 和容量事实，再由现有预约域生成 `petName`、`petType`、`serviceType`和 `durationMinutes` 快照。
|
||
|
||
### 7.2 候选会话表
|
||
|
||
建议新增 `t_booking_agent_session`，不将对话状态塞入 `t_appointment`。
|
||
|
||
| 字段 | 语义 |
|
||
|---|---|
|
||
| `session_id` | 不可预测会话 ID，主键 |
|
||
| `customer_user_id` | 从登录上下文派生 |
|
||
| `store_id` | 会话数据范围 |
|
||
| `source_appointment_id` | 复约上下文，可空 |
|
||
| `status` | 仅使用第 5 节对话状态 |
|
||
| `draft_json` | 最小结构化草稿，不存原始语音 |
|
||
| `draft_version` | 乐观版本号 |
|
||
| `entry_source` | `home` / `appointment_history` / `report_history` / `pet_profile` |
|
||
| `input_modality` | `text` / `voice` / `mixed` |
|
||
| `appointment_id` | 成功后关联的真实预约，可空 |
|
||
| `expires_at` | 会话过期时间 |
|
||
| `create_time` / `update_time` | 审计时间 |
|
||
|
||
数据建议：
|
||
|
||
- 以 `(customer_user_id, status, expires_at)` 建立查询索引；
|
||
- `appointment_id` 为可空唯一关联；
|
||
- 确认时对 session 行加悲观锁；如已是 `booked`，重复请求直接返回同一 `Appointment`；
|
||
- MVP 会话默认 30 分钟过期，过期不等于删除预约；
|
||
- 不新增 `t_booking_agent_turn` 原文表；模型每轮以当前草稿和当次输入工作，避免默认持久化完整对话。
|
||
|
||
该表、索引、过期清理和迁移顺序均是 **待 Data Model 评审的提案**，不代表当前生产库已存在。
|
||
|
||
### 7.3 预约来源与事件
|
||
|
||
不改变现有 `BusinessEvent.source=customer/admin`的操作人语义。建议在 `appointment_created` 的 `metadata_json` 增加独立维度：
|
||
|
||
```json
|
||
{
|
||
"bookingOrigin": "customer",
|
||
"bookingChannel": "agent_voice",
|
||
"agentSessionId": "<opaque-session-id>"
|
||
}
|
||
```
|
||
|
||
`bookingChannel` 候选值：`form`、`agent_text`、`agent_voice`、`admin`、`follow_up`。不建议 MVP 为此修改 `Appointment` 主表；先以已持久化 `BusinessEvent` 作为统计事实。
|
||
|
||
候选新事件：
|
||
|
||
- `booking_agent_started`；
|
||
- `booking_agent_draft_ready`；
|
||
- `booking_agent_fallback`；
|
||
- `booking_agent_confirmed`。
|
||
|
||
这些事件只用于漏斗和运行分析；只有真实创建成功的 `appointment_created` 才计为预约。编码前需将候选对象、动作、事件和规则同步到 `docs/ontology/` 及 `graph/ontology.jsonl`。
|
||
|
||
## 8. API 契约草案
|
||
|
||
本节是评审草案，尚未实现。响应沿用当前 `{ code, message, bizCode, data }` 业务外壳，所有 endpoint 都要求 customer session token。
|
||
|
||
### 8.1 创建会话
|
||
|
||
`POST /api/booking-agent/sessions`
|
||
|
||
```json
|
||
{
|
||
"entrySource": "home",
|
||
"storeId": 1,
|
||
"sourceAppointmentId": null
|
||
}
|
||
```
|
||
|
||
规则：
|
||
|
||
- 不接受 `customerUserId`，必须从 `CurrentUserContext` 派生；
|
||
- `sourceAppointmentId` 非空时必须归属当前 customer；
|
||
- `storeId` 与源预约冲突时拒绝，不静默覆盖；
|
||
- 返回 `sessionId`、`status`、`draft`、`assistantMessage`、`expiresAt` 和 `draftVersion`。
|
||
|
||
### 8.2 提交文字或语音转写结果
|
||
|
||
`POST /api/booking-agent/sessions/{sessionId}/messages`
|
||
|
||
```json
|
||
{
|
||
"inputType": "text",
|
||
"text": "周六下午给球球洗澡，三点以后都行"
|
||
}
|
||
```
|
||
|
||
建议响应 `data`：
|
||
|
||
```json
|
||
{
|
||
"sessionId": "<opaque-session-id>",
|
||
"status": "proposing",
|
||
"assistantMessage": "本周六有 3 个符合的时段",
|
||
"draft": {},
|
||
"slotOptions": [
|
||
{ "startTime": "2026-08-08T15:00:00", "endTime": "2026-08-08T16:00:00" }
|
||
],
|
||
"quickReplies": ["15:00", "16:30", "17:00", "换一天"],
|
||
"confirmable": false,
|
||
"draftVersion": 2
|
||
}
|
||
```
|
||
|
||
客户端只展示可理解错误，不展示模型原始输出、提示词、堆栈或供应商错误。
|
||
|
||
### 8.3 语音转写
|
||
|
||
`POST /api/booking-agent/transcriptions`
|
||
|
||
- `multipart/form-data`，仅接受允许的音频 MIME 和扩展名；
|
||
- 建议 MVP 单段不超过 60 秒、5 MB，具体值由技术验证后冻结；
|
||
- 后端代理调用语音服务，不向客户端下发供应商密钥；
|
||
- 语音只用于当次转写，不进入通用报告媒体存储，不持久化原始录音；
|
||
- 返回可编辑 `text` 和脱敏 `requestId`，宠主可修改识别结果再发送。
|
||
|
||
### 8.4 确认预约
|
||
|
||
`POST /api/booking-agent/sessions/{sessionId}/confirm`
|
||
|
||
```json
|
||
{
|
||
"draftVersion": 3
|
||
}
|
||
```
|
||
|
||
确认 endpoint 必须：
|
||
|
||
1. 从 session token 重新派生 customer；
|
||
2. 对 `t_booking_agent_session` 行加锁；
|
||
3. 校验 `draftVersion`、会话状态和过期时间；
|
||
4. 重新校验宠物归属、门店服务和号源；
|
||
5. 调用现有 `AppointmentService.createBooking`，保留门店行锁和连续容量桶判定；
|
||
6. 记录 `appointment_created` 及助手漏斗事件；
|
||
7. 将 session 更新为 `booked` 并关联 `appointmentId`。
|
||
|
||
并发或重试时，同一 session 只能创建一个预约；后续重复确认返回已创建的同一预约。
|
||
|
||
### 8.5 返回草稿到普通表单
|
||
|
||
`POST /api/booking-agent/sessions/{sessionId}/fallback`
|
||
|
||
返回经后端验证的可回填字段，客户端导航到现有 `CustAppointmentCreate`。不返回供应商上下文、提示词、置信度或内部调试字段。
|
||
|
||
### 8.6 业务码草案
|
||
|
||
| `bizCode` | 用户语义 | 前端处理 |
|
||
|---|---|---|
|
||
| `AGENT_SESSION_NOT_FOUND` | 会话不存在或不属于当前宠主 | 返回预约入口 |
|
||
| `AGENT_SESSION_EXPIRED` | 会话已过期 | 新建会话或切表单 |
|
||
| `AGENT_INPUT_INVALID` | 输入为空或超限 | 允许重新输入 |
|
||
| `AGENT_UNAVAILABLE` | 模型超时或输出校验失败 | 保留草稿并切表单 |
|
||
| `ASR_UNAVAILABLE` | 语音转写失败 | 重试或改用文字 |
|
||
| `DRAFT_VERSION_CONFLICT` | 确认的不是最新草稿 | 刷新确认卡 |
|
||
| `PET_CUSTOMER_MISMATCH` | 宠物归属校验失败 | 重新选宠物 |
|
||
| `SERVICE_TYPE_INVALID` | 服务不属于门店或已下线 | 重新选服务 |
|
||
| `CAPACITY_FULL` | 确认时号源已变化 | 立即查询新候选时段 |
|
||
|
||
## 9. 语音与模型集成边界
|
||
|
||
### 9.1 供应商适配
|
||
|
||
语音转写和语言模型分别通过后端适配器接入，业务服务不依赖某一厂商 SDK 的对话状态。
|
||
|
||
生产配置至少包括：
|
||
|
||
- 模型和语音能力总开关；
|
||
- 供应商 endpoint、模型名称和超时；
|
||
- 服务端密钥环境变量；
|
||
- 单用户和单门店频率限制；
|
||
- 单轮输入长度、语音大小和时长限制；
|
||
- 模型失败时的降级开关和成本上限。
|
||
|
||
密钥不写入代码、文档、提示词、日志或前端产物。上线前应纳入 production configuration preflight。
|
||
|
||
### 9.2 超时与降级
|
||
|
||
- 语音失败：保留本地输入状态，提供「重新说」和「改用文字」。
|
||
- 模型失败：不自动重复多次调用；保留已验证草稿并导向普通表单。
|
||
- 工具查询失败：展示业务错误，不让模型根据记忆补齐结果。
|
||
- 最终号源冲突：会话进入 `needs_reselection`，不创建失败预约或假成功记录。
|
||
|
||
## 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. 异常场景与产品反应
|
||
|
||
| 场景 | 产品反应 | 业务约束 |
|
||
|---|---|---|
|
||
| 找不到宠物 | 请宠主选择已有宠物或转普通表单 | 助手不自动建档 |
|
||
| 匹配到多只宠物 | 展示选择芯片 | 不用置信度代替选择 |
|
||
| 服务表达模糊 | 展示门店真实服务选项 | 不创造服务名称 |
|
||
| 当日无号 | 给出下一个有号日期 | 不承诺排队或准点履约 |
|
||
| 语音识别失败 | 重新说或改用文字 | 不提交空文本 |
|
||
| 模型超时/无效输出 | 保留草稿并转普通表单 | 不用模型记忆猜测 |
|
||
| 确认时号源已满 | 立即推荐新时段 | 不产生超容量预约 |
|
||
| 重复点击确认 | 返回同一预约成功页 | 会话行锁 + `appointment_id` 幂等 |
|
||
| 会话过期 | 新建会话或回填普通表单 | 不自动提交旧草稿 |
|
||
|
||
## 12. 分阶段交付
|
||
|
||
### M0：草稿助手（首发建议）
|
||
|
||
- 老客从首页、历史预约或登录后报告记录进入；
|
||
- 支持文字和语音转写；
|
||
- 解析宠物、服务和时间偏好，查询真实号源；
|
||
- 生成确认卡，但「继续」只把草稿回填到现有 `CustAppointmentCreate`；
|
||
- 最终仍由现有表单提交，不新增智能层写入路径；
|
||
- 先在 1 家试点门店对老客开放，不影响 RC6 基线验证。
|
||
|
||
### M1：受控确认创建
|
||
|
||
- 增加 session 表、确认 endpoint、行锁和幂等返回；
|
||
- 确认时重新校验权限、宠物归属、服务和容量；
|
||
- 补齐助手漏斗事件和 `bookingChannel`；
|
||
- 通过硬性安全验收后，再允许确认卡直接创建预约。
|
||
|
||
### M2：个性化复约与对照实验
|
||
|
||
- 支持「和上次一样」和宠物档案入口；
|
||
- 在一家门店做智能助手与普通表单的小流量对照；
|
||
- 将最终履约率、取消率和复约率与 `bookingChannel` 关联；
|
||
- 只有在真实使用证明更快或更高转化后，才扩大门店范围。
|
||
|
||
## 13. MVP 验收与试点门槛
|
||
|
||
### 13.1 硬性门禁
|
||
|
||
- [ ] 未点击「确认预约」前不创建 `Appointment`。
|
||
- [ ] 助手不会返回门店不存在的服务或后端未返回的号源。
|
||
- [ ] 确认时复核服务时长、连续容量桶和门店锁，不产生超卖。
|
||
- [ ] 同一 session 并发或重复确认只有一个 `Appointment`。
|
||
- [ ] A customer 不能查询或选择 B customer 的宠物、历史预约或 session。
|
||
- [ ] 不将手机号、完整 `report_token`、session token 或密钥发送给模型或写入日志。
|
||
- [ ] 原始语音转写后立即释放，不出现在通用上传目录或报告媒体中。
|
||
- [ ] 模型、语音或工具失败时能保留已验证草稿并切换普通表单。
|
||
- [ ] `Appointment.status` 仍只有 `new`、`doing`、`done`、`cancel`。
|
||
- [ ] 助手生成的真实预约有 `appointment_created` 事件和可统计 `bookingChannel`。
|
||
|
||
### 13.2 价值验证建议
|
||
|
||
首批 20 个真实 session 用于发现语料和交互问题，不立即下商业化结论。稳定后可对 20～50 个老客 session 使用以下建议门槛：
|
||
|
||
- 助手启动到真实预约成功率 ≥ 70%；
|
||
- 成功 session 的宠主中位消息轮次 ≤ 4；
|
||
- 切换普通表单的比例 ≤ 25%；
|
||
- 进入确认卡后修改门店/宠物/服务/时间的 session 比例 ≤ 20%；
|
||
- 越权、超容量、重复预约和敏感数据泄漏事故 = 0。
|
||
|
||
上述价值门槛是试点假设，应在首批真实数据后与普通表单基线一起复核；不得用演示会话、测试预约或未履约预约代替真实样本。
|
||
|
||
## 14. 开发前待冻结决策
|
||
|
||
| ID | 决策 | 建议默认 | 责任人 |
|
||
|---|---|---|---|
|
||
| D1 | 首发入口 | 登录后历史预约/报告记录，其次首页 | 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 | MVP 30 分钟，编码前由 Data Model 冻结 | Data Model |
|
||
| D7 | 助手对话风格 | 简短、一次一个关键问题，不模拟人格客服 | Product Design |
|
||
| D8 | 试点启动时机 | RC6 基础链路已用真实门店跑通并建立普通表单基线后 | 主控 PM |
|
||
|
||
## 15. 实施任务队列草案
|
||
|
||
以下任务默认为 `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
|
||
```
|
||
|
||
## 16. 开发与验证清单
|
||
|
||
实现时至少需要：
|
||
|
||
1. 更新 `docs/ontology/objects.md`、`actions.md`、`events.md`、`rules.md`、`relations.md` 和 `graph/ontology.jsonl`；
|
||
2. 后端覆盖模型无效输出、跨 customer/跨店、宠物归属、服务下线、号源冲突、重复确认和 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` 已持久化 | 增加独立 `bookingChannel` 和助手漏斗事件 |
|
||
|
||
本方案是对现有预约入口的语义化扩展，不建立第二套预约、容量或身份系统。
|