malei 4815387c23 docs: record booking agent provider completion

2026-08-02 16:51:24 +08:00

19 KiB

Raw Blame History

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

日期：2026-08-02
状态：Batch 1 已完成 / Batch 2 待实施
目标：宠主用文字或语音生成可验证预约草稿，回填现有表单，不由智能层创建 Appointment
Workstream：Core Booking Flow
Owner Agent：Backend Core + Customer Experience FE
Paired QA：Core Flow QA
Service Lock：backend:booking-agent-session+read-tools + frontend:customer-booking-agent+shared-api
Architecture Review Required：Yes — completed by M0 ADR
Data Model Review Required：Yes — proposal completed; implementation diff requires review
Access / Privacy Review Required：Yes — development boundary completed; live provider/production pending
RC Included：No

需求来源

1. M0 交付结果

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

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

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

2. 严格非目标

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

3. 用户流程

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 包与组件

建议新增：

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：

{
  "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 建议写入文件

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 只保存一次性回填对象：

{
  "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 证据增加：

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。

实现时必须在同一批把真实代码/测试路径补入，并将对应条目从 documented 更新为 anchored；不得提前宣称已实现。

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：会话、上下文解析和号源