From bde3d1d6d0e6394bfb8c5463733e8581bae4c5dd Mon Sep 17 00:00:00 2001 From: malei <> Date: Sun, 2 Aug 2026 14:02:15 +0800 Subject: [PATCH] docs: propose conversational booking assistant --- 产品全方位优化说明-v1.md | 1 + 产品设计文档.md | 1 + 宠小它智能预约助手-产品与技术方案-v0.1.md | 735 ++++++++++++++++++++++ 3 files changed, 737 insertions(+) create mode 100644 宠小它智能预约助手-产品与技术方案-v0.1.md diff --git a/产品全方位优化说明-v1.md b/产品全方位优化说明-v1.md index b22a43b..3160681 100644 --- a/产品全方位优化说明-v1.md +++ b/产品全方位优化说明-v1.md @@ -12,6 +12,7 @@ | [产品改进建议](./产品改进建议.md) | 中长期方向库 | | [本期主线-下一步产品优化点](./本期主线-下一步产品优化点.md) | 报告传播 + 成片 + 留资 + 绑定切片 | | [宠主端预约体验优化-产品说明](./宠主端预约体验优化-产品说明.md) | C 端预约入口与表单 | +| [智能预约助手产品与技术方案 v0.1](./宠小它智能预约助手-产品与技术方案-v0.1.md) | 待评审的对话式预约扩展；不属于当前 RC6 已实现能力 | | [前端 UI 规范](./前端UI规范.md) | 视觉与组件基线（已与 `global.css` 对齐主色与 token） | | [洗美报告短视频成片方案](./洗美报告短视频成片方案.md) | 成片边界与工程契约 | | [**P0 研发落地清单**](./P0-研发落地清单.md) | **发给研发的 P0 任务与验收表** | diff --git a/产品设计文档.md b/产品设计文档.md index 652dfdf..4887bf4 100644 --- a/产品设计文档.md +++ b/产品设计文档.md @@ -14,6 +14,7 @@ - [洗美报告短视频成片方案](./洗美报告短视频成片方案.md) — **本期迭代主方案**：过程短视频与自动成片（与 §5.3 服务报告延伸能力对应；时长与编排以专文「与工程实现同步」为准） - [产品改进建议](./产品改进建议.md) — 中长期方向库；**§〇** 为本期重点说明 - [产品全方位优化说明 v1](./产品全方位优化说明-v1.md) — 定位/IA/交互/UI/商业化/小程序体验汇总与排期切片（**与专文互补**，冲突以评审更新为准） +- [智能预约助手产品与技术方案 v0.1](./宠小它智能预约助手-产品与技术方案-v0.1.md) — **待评审、未实现**：宠主通过文字/语音生成受控预约草稿，分 M0 表单回填与 M1 明确确认创建 - [**P0 研发落地清单**](./P0-研发落地清单.md) — **本期必做**：后端状态机、Tab 筛选、发送报告话术、H5 隐私提示、宠主路径、埋点最小集等（**可直接拆 issue**） --- diff --git a/宠小它智能预约助手-产品与技术方案-v0.1.md b/宠小它智能预约助手-产品与技术方案-v0.1.md new file mode 100644 index 0000000..5532084 --- /dev/null +++ b/宠小它智能预约助手-产品与技术方案-v0.1.md @@ -0,0 +1,735 @@ +# 宠小它智能预约助手：产品与技术方案 v0.1 + +> 日期：2026-08-02
+> 状态：**Draft / 待产品、架构、数据与隐私评审；尚未实现**
+> 目标用户：`customer` 宠主
+> Workstream：`Core Booking Flow`
+> 建议 Owner：`Product Design` + `Customer Experience FE` + `Backend Core`
+> Paired QA：`Core Flow QA`
+> Architecture Review Required：`Yes`
+> Data Model Review Required：`Yes`
+> Access / Privacy Review Required：`Yes`
+> 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 标准对话 + +> **宠主语音**：「周六下午给球球洗澡，三点以后都行。」
+> **助手**：「球球预约精洗护理，预计 60 分钟。本周六 15:00、16:30 和 17:00 可约，你选哪个？」
+> **宠主**：「三点。」
+> **助手**：展示确认卡，不自动提交。 + +确认卡至少展示： + +- 门店名称； +- 宠物名称和类型； +- 服务项目和预计时长； +- 绝对日期、开始时间和预计结束时间； +- 宠主提供的备注； +- 「修改」「确认预约」和「普通预约」操作。 + +### 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": "" +} +``` + +`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": "", + "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` 和助手漏斗事件 | + +本方案是对现有预约入口的语义化扩展，不建立第二套预约、容量或身份系统。