diff --git a/宠小它智能预约助手-产品与技术方案-v0.1.md b/宠小它智能预约助手-产品与技术方案-v0.1.md index 5532084..20cde60 100644 --- a/宠小它智能预约助手-产品与技术方案-v0.1.md +++ b/宠小它智能预约助手-产品与技术方案-v0.1.md @@ -11,6 +11,11 @@ > Access / Privacy Review Required:`Yes`
> RC 边界:**不纳入 `phase2-pilot-rc6`;当前 RC 仍以基础预约和真实门店试点为先** +**配套文档** + +- [模型与语音供应商选型](./智能预约助手-模型与语音供应商选型-2026-08-02.md) +- [M0 编码任务 brief](./智能预约助手-M0编码任务brief-2026-08-02.md) + ## 1. 结论 建议将该能力定义为 **「可执行的智能预约助手」**,而不是泛化客服聊天机器。 @@ -88,7 +93,7 @@ - 服务项目和预计时长; - 绝对日期、开始时间和预计结束时间; - 宠主提供的备注; -- 「修改」「确认预约」和「普通预约」操作。 +- 「修改」「带入普通预约」和「普通预约」操作。M1 通过写路径安全评审后,才将主操作改为「确认预约」。 ### 4.2 澄清规则 @@ -138,6 +143,8 @@ stateDiagram-v2 | `needs_reselection` | 确认时号源已变化 | 否 | | `fallback` / `expired` / `cancelled` | 结束智能会话 | 否 | +M0 只实现 `collecting`、`proposing`、`confirmable`、`fallback`、`expired` 和 `cancelled`。用户在 `confirmable` 点击「带入普通预约」时离开助手,由现有表单完成提交;`submitting`、`booked` 和 `needs_reselection` 是 M1 状态,M0 不实现。 + ## 6. 系统架构与权威边界 ```mermaid @@ -225,7 +232,7 @@ flowchart LR ### 7.2 候选会话表 -建议新增 `t_booking_agent_session`,不将对话状态塞入 `t_appointment`。 +长期建议新增 `t_booking_agent_session`,不将对话状态塞入 `t_appointment`。下表是覆盖 M1 直接确认能力的完整候选形态;M0 实际字段以配套编码 brief 为准。 | 字段 | 语义 | |---|---| @@ -236,17 +243,17 @@ flowchart LR | `status` | 仅使用第 5 节对话状态 | | `draft_json` | 最小结构化草稿,不存原始语音 | | `draft_version` | 乐观版本号 | -| `entry_source` | `home` / `appointment_history` / `report_history` / `pet_profile` | +| `entry_source` | `appointment_create` / `home` / `appointment_history` / `report_history` / `pet_profile` | | `input_modality` | `text` / `voice` / `mixed` | -| `appointment_id` | 成功后关联的真实预约,可空 | +| `appointment_id` | M1 成功后关联的真实预约,可空;M0 不增加 | | `expires_at` | 会话过期时间 | | `create_time` / `update_time` | 审计时间 | 数据建议: - 以 `(customer_user_id, status, expires_at)` 建立查询索引; -- `appointment_id` 为可空唯一关联; -- 确认时对 session 行加悲观锁;如已是 `booked`,重复请求直接返回同一 `Appointment`; +- M1 增加 `appointment_id` 可空唯一关联; +- M1 确认时对 session 行加悲观锁;如已是 `booked`,重复请求直接返回同一 `Appointment`; - MVP 会话默认 30 分钟过期,过期不等于删除预约; - 不新增 `t_booking_agent_turn` 原文表;模型每轮以当前草稿和当次输入工作,避免默认持久化完整对话。 @@ -264,14 +271,14 @@ flowchart LR } ``` -`bookingChannel` 候选值:`form`、`agent_text`、`agent_voice`、`admin`、`follow_up`。不建议 MVP 为此修改 `Appointment` 主表;先以已持久化 `BusinessEvent` 作为统计事实。 +`bookingChannel` 候选值:`form`、`agent_draft`、`agent_text`、`agent_voice`、`admin`、`follow_up`。`agent_draft` 只表示智能助手提供了已验证草稿;`agent_text` 和 `agent_voice` 保留给 M1 对话内直接创建路径。初始 M0 不修改 `appointment_created` 事件,如需归因表单提交,必须另行评审服务端验证的一次性草稿交接,不接受客户端自由上报渠道。不建议 MVP 为此修改 `Appointment` 主表。 候选新事件: - `booking_agent_started`; - `booking_agent_draft_ready`; - `booking_agent_fallback`; -- `booking_agent_confirmed`。 +- `booking_agent_confirmed`(M1)。 这些事件只用于漏斗和运行分析;只有真实创建成功的 `appointment_created` 才计为预约。编码前需将候选对象、动作、事件和规则同步到 `docs/ontology/` 及 `graph/ontology.jsonl`。 @@ -333,12 +340,12 @@ flowchart LR `POST /api/booking-agent/transcriptions` - `multipart/form-data`,仅接受允许的音频 MIME 和扩展名; -- 建议 MVP 单段不超过 60 秒、5 MB,具体值由技术验证后冻结; +- M0 单段不超过 60 秒、3 MB,与供应商选型和编码 brief 保持一致; - 后端代理调用语音服务,不向客户端下发供应商密钥; - 语音只用于当次转写,不进入通用报告媒体存储,不持久化原始录音; - 返回可编辑 `text` 和脱敏 `requestId`,宠主可修改识别结果再发送。 -### 8.4 确认预约 +### 8.4 确认预约(M1,M0 不实现) `POST /api/booking-agent/sessions/{sessionId}/confirm` @@ -453,17 +460,17 @@ flowchart LR | 语音识别失败 | 重新说或改用文字 | 不提交空文本 | | 模型超时/无效输出 | 保留草稿并转普通表单 | 不用模型记忆猜测 | | 确认时号源已满 | 立即推荐新时段 | 不产生超容量预约 | -| 重复点击确认 | 返回同一预约成功页 | 会话行锁 + `appointment_id` 幂等 | +| M1 重复点击确认 | 返回同一预约成功页 | 会话行锁 + `appointment_id` 幂等 | | 会话过期 | 新建会话或回填普通表单 | 不自动提交旧草稿 | ## 12. 分阶段交付 ### M0:草稿助手(首发建议) -- 老客从首页、历史预约或登录后报告记录进入; +- 仅在现有 `CustAppointmentCreate` 顶部增加「一句话预约」次级入口; - 支持文字和语音转写; - 解析宠物、服务和时间偏好,查询真实号源; -- 生成确认卡,但「继续」只把草稿回填到现有 `CustAppointmentCreate`; +- 生成确认卡,但「带入普通预约」只把草稿回填到现有 `CustAppointmentCreate`; - 最终仍由现有表单提交,不新增智能层写入路径; - 先在 1 家试点门店对老客开放,不影响 RC6 基线验证。 @@ -512,10 +519,10 @@ flowchart LR | ID | 决策 | 建议默认 | 责任人 | |---|---|---|---| -| D1 | 首发入口 | 登录后历史预约/报告记录,其次首页 | Product Design | +| D1 | M0 首发入口 | `CustAppointmentCreate` 顶部次级入口;历史预约、报告和首页入口后续评估 | Product Design | | D2 | 是否支持匿名助手 | MVP 不支持,普通表单继续支持 guest 草稿 | Product Design + System Architect | | D3 | M0 是否直接创建预约 | 否,先回填现有表单 | Product Design + Backend Core | -| D4 | 模型与语音供应商 | 以数据区域、中文识别、延迟、稳定性和成本评估;业务保持适配层 | System Architect + Backend Ops | +| D4 | 模型与语音供应商 | M0 推荐阿里云百炼北京 `qwen3-asr-flash-2026-02-10 + qwen-plus-2025-12-01`,腾讯 ASR 作对照;生产前仍需语料和隐私复核 | System Architect + Backend Ops | | D5 | 原文保留 | 默认不持久化对话原文,不持久化原始语音 | Access / Privacy Review | | D6 | session TTL | MVP 30 分钟,编码前由 Data Model 冻结 | Data Model | | D7 | 助手对话风格 | 简短、一次一个关键问题,不模拟人格客服 | Product Design | diff --git a/智能预约助手-M0编码任务brief-2026-08-02.md b/智能预约助手-M0编码任务brief-2026-08-02.md new file mode 100644 index 0000000..1492272 --- /dev/null +++ b/智能预约助手-M0编码任务brief-2026-08-02.md @@ -0,0 +1,474 @@ +# 智能预约助手 M0 编码任务 brief + +> 日期:2026-08-02
+> 状态:**Ready for Review / 尚未进入编码**
+> 目标:宠主用文字或语音生成可验证预约草稿,回填现有表单,不由智能层创建 `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`
+> Data Model Review Required:`Yes`
+> Access / Privacy Review Required:`Yes`
+> RC Included:`No` + +**需求来源** + +- [智能预约助手产品与技术方案 v0.1](./宠小它智能预约助手-产品与技术方案-v0.1.md) +- [模型与语音供应商选型](./智能预约助手-模型与语音供应商选型-2026-08-02.md) + +## 1. M0 交付结果 + +宠主在已登录状态进入「一句话预约」,输入文字或按住说话。系统依次: + +1. 转写语音(文字输入跳过); +2. 提取宠物查询词、服务查询词、日期表达、时间偏好和备注; +3. 在当前 customer 和门店范围内解析真实 Pet 与 ServiceType; +4. 调用现有容量服务获取真实号源; +5. 展示可修改草稿卡; +6. 宠主点击「带入普通预约」后,回填现有 `CustAppointmentCreate`; +7. 宠主仍在现有表单上点击「提交预约」。 + +M0 成功的判定是 **「草稿真实、回填正确、普通预约未受影响」**,不是对话内创建预约。 + +## 2. 严格非目标 + +- 不实现 `POST /api/booking-agent/sessions/{sessionId}/confirm`; +- 不调用 `AppointmentService.createBooking`; +- 不新增 `Appointment` 字段或状态; +- 不做取消、改期、代客预约或指定技师; +- 不自动建立宠物档案; +- 不做匿名智能会话; +- 不开启外部搜索、知识库或模型托管 Agent; +- 不持久化原始语音或完整对话原文; +- 不进入当前 RC6 tag、发布物或生产配置。 + +## 3. 用户流程 + +```mermaid +flowchart TD + A[宠主预约页] --> B[点击一句话预约] + B --> C{已登录 customer} + C -- 否 --> D[登录并保留返回路由] + D --> E[创建助手会话] + C -- 是 --> E + E --> F[文字或语音输入] + F --> G[结构化意图提取] + G --> H[服务端解析真实宠物和服务] + H --> I[查询真实号源] + I --> J{草稿完整} + J -- 否 --> K[询问一个关键缺失项] + K --> F + J -- 是 --> L[展示草稿卡] + L --> M[带入普通预约] + M --> N[CustAppointmentCreate 回填] + N --> O[用户在现有表单提交] +``` + +### 3.1 入口 + +M0 只在宠主的 `CustAppointmentCreate` 顶部增加一个次级入口: + +> 不想一项项填?「一句话预约」 + +该入口不取代当前表单和主提交按钮,不改宠主首页主 CTA。历史预约、报告页和宠物档案深链放到后续迭代。 + +### 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 字段: + +- `session_id` VARCHAR(64) 主键; +- `customer_user_id` BIGINT NOT NULL; +- `store_id` BIGINT NULL; +- `status` VARCHAR(32) 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`; +- `deleted` TINYINT(1) NOT NULL DEFAULT 0。 + +索引: + +- `(customer_user_id, status, expires_at)`; +- `(expires_at, deleted)` 用于过期清理。 + +M0 不增加 `appointment_id`,也不建立 `t_booking_agent_turn`。`appointment_id` 唯一关联在 M1 幂等写入评审时再增加,避免 M0 数据模型暗示已具备直接创建能力。 + +M0 的 `entry_source` 只允许 `appointment_create`;历史预约、报告、首页和宠物档案入口尚未开放。 + +`draft_json` 只保存已验证 ID、时间约束和必要备注;不保存每轮用户原文、提示词或模型原始响应。 + +### 4.5 API 契约 + +M0 只实现: + +| Method | Endpoint | 用途 | +|---|---|---| +| `POST` | `/api/booking-agent/sessions` | 创建已登录 customer 会话 | +| `POST` | `/api/booking-agent/sessions/{sessionId}/messages` | 提交文字/语音转写文本,刷新草稿 | +| `POST` | `/api/booking-agent/transcriptions` | 上传短音频并获取可编辑转写 | +| `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 是否存在。 + +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, + "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 设计可验证、一次性的草稿交接机制。 + +编码前需增加或更新: + +- `ontology/objects.md`:`booking_agent_session` gap/implemented 证据; +- `ontology/actions.md`:创建会话、提交消息、语音转写、回填草稿、结束会话; +- `ontology/events.md`:M0 三个漏斗事件; +- `ontology/rules.md`:customer 数据范围、无写工具、原始语音/原文不持久化、超时降级; +- `ontology/relations.md` 与 `graph/ontology.jsonl`; +- `coverage/ontology-coverage-audit.md`。 + +## 7. 自动化测试 + +### 7.1 后端必测 + +**意图提取契约** + +- 30 条 `booking-intent-v1` fixture 均可解析; +- 无效 JSON、未知 schema 版本、未知枚举、超长备注和多余 ID 字段降级; +- 模型请求不包含手机号、token 或全量客户时间线。 + +**会话和权限** + +- 未登录、boss/staff 调用助手 endpoint 被拒绝; +- 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 + +- 冻结 `booking-intent-v1`、M0 状态子集、API shape 和业务码; +- 更新本体及机器图谱; +- 评审 session 表、TTL 和清理方式; +- 完成 Access / Privacy Review。 + +### Batch 1:供应商适配与契约测试 + +Owner:Backend Core + +- 实现 provider interface、properties 和本地 HTTP stub; +- 实现 Qwen JSON 提取与 Qwen3-ASR-Flash 转写; +- 建立 30 条文字 fixture; +- 确保未配置/关闭时 fail closed,不影响应用启动和普通预约。 + +### Batch 2:会话、上下文解析和号源 + +Owner:Backend Core + +- 实现 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 条已知情同意的脱敏语音对照样本; +- 生产开启授权。 diff --git a/智能预约助手-模型与语音供应商选型-2026-08-02.md b/智能预约助手-模型与语音供应商选型-2026-08-02.md new file mode 100644 index 0000000..dad2d1a --- /dev/null +++ b/智能预约助手-模型与语音供应商选型-2026-08-02.md @@ -0,0 +1,245 @@ +# 智能预约助手:模型与语音供应商选型 + +> 日期:2026-08-02
+> 状态:**Recommendation / M0 推荐基线,待账号开通、合规复核与语料实测**
+> 影响范围:智能预约 M0,不影响 `phase2-pilot-rc6`
+> Architecture Review Required:`Yes`
+> Access / Privacy Review Required:`Yes`
+> 官方资料查阅日期:2026-08-02 + +**关联文档** + +- [智能预约助手产品与技术方案 v0.1](./宠小它智能预约助手-产品与技术方案-v0.1.md) +- [智能预约助手 M0 编码任务 brief](./智能预约助手-M0编码任务brief-2026-08-02.md) + +## 1. 推荐结论 + +M0 的默认技术基线建议为: + +| 能力 | 推荐供应商与模型 | 调用边界 | +|---|---|---| +| 语音转写 | 阿里云百炼华北2(北京)`qwen3-asr-flash-2026-02-10` | OpenAI 兼容 HTTP 同步调用,Base64/Data URL 直传,不中转 OSS,不持久化原始录音 | +| 预约意图提取 | 阿里云百炼华北2(北京)`qwen-plus-2025-12-01` | 非思考模式 + `response_format=json_object` + 服务端 JSON Schema 二次校验 | +| ASR 对照候选 | 腾讯云 `SentenceRecognition` | 仅在同一批脱敏/已授权语音语料上对照,不直接进生产 | +| LLM 备选 | 腾讯云 TokenHub 的国内文本模型 | 供应商适配层预留,M0 不同时维护两条生产路径 | + +不建议把 OpenAI API 作为当前 Petstore 中国大陆生产默认。OpenAI 官方说明仅支持列表中的国家和地区,中国大陆不在当前列表中;未列出地区不受支持,且可能导致账号被停用。 + +这个结论是 **M0 工程默认**,不是长期供应商锁定。所有外部能力必须通过 Petstore 自有适配接口调用。 + +## 2. 选型前提 + +智能预约不是知识问答或通用 Agent。它的模型任务只有: + +1. 把当次文字和已验证草稿转换成结构化 `draftPatch`; +2. 识别 `book / modify / end / fallback` 等有限意图; +3. 标记歧义和建议下一个状态机动作。 + +它不需要联网检索、知识库、长上下文、平台托管 Agent 或模型直接工具调用。宠物、服务和号源必须由 Petstore 后端确定性解析。 + +因此选型优先级为: + +1. 中国大陆可达与明确数据部署范围; +2. 中文口语、时间表达、宠物名称和门店服务识别; +3. 非思考模式下稳定输出 JSON; +4. 可固定模型快照,避免别名自动升级导致行为漂移; +5. 明确的密钥、区域、超时、限流、费用和数据保留口径; +6. 最终才是模型绝对能力和单次价格。 + +## 3. 候选方案评估 + +### 3.1 阿里云百炼全链路(推荐 M0 默认) + +**区域和网络** + +- 百炼官方提供华北2(北京)`cn-beijing` 地域和中国内地服务部署范围; +- 官方地域说明称推理过程数据不持久化、传输加密,静态数据位于所选地域; +- 生产建议使用业务空间专属域名,不使用试用域名。 + +**语音转写** + +- `qwen3-asr-flash-2026-02-10` 支持普通话、四川话、闽南语、吴语、粤语等中文语音类型及多语种; +- 官方 OpenAI 兼容接口支持公网 URL 或 Base64 Data URL,可在录音结束后同步转写,无需把用户录音中转到公网 OSS; +- 官方允许以 system message 提供背景文本和实体词表,M0 只传当前门店服务名和当前 customer 的宠物展示名,不传手机号或其他客户数据; +- 官方限制是 5 分钟/10 MB,M0 继续使用更小的 60 秒/3 MB 业务门禁; +- 当前官方列价为 `0.00022 元/秒`,不包含活动优惠。 + +**结构化意图提取** + +- `qwen-plus-2025-12-01` 在华北2(北京)官方标注支持 Function Calling 和结构化输出; +- 百炼 OpenAI 兼容接口支持 `response_format={"type":"json_object"}`; +- M0 使用固定快照 `qwen-plus-2025-12-01`,不使用可自动升级的 `latest` 别名; +- M0 关闭思考模式,不开启联网或平台内置工具; +- JSON mode 只保证可解析 JSON,Petstore 服务端仍必须校验字段、枚举、长度和状态转换。 + +**风险** + +- Petstore 当前服务器在腾讯云,调用百炼需经过公网 HTTPS,必须做真实延迟和可用性实测; +- 需新开阿里云百炼业务空间、独立 API Key 和费用告警; +- 语音及文本的合同保留、删除和工单口径需在生产开通前再做一次 Access / Privacy Review。 + +### 3.2 腾讯云全链路(对照/备选) + +**语音转写优势** + +- `SentenceRecognition` 适合 60 秒内短音频,支持音频数据或 URL,大小不超过 3 MB; +- 官方文档列出普通话、粤语、上海话、四川话等多种方言,默认频率限制 30 次/秒; +- 可直接在现有腾讯云账号与服务器体系中配置,运维链路较短。 + +**隐私注意点** + +- 腾讯云 ASR SDK 隐私规则要求开发者在收集和上传音频前完成告知和合法授权; +- 官方 FAQ 说明上传音视频文件不会保存,但识别后的文本文件会在服务器上保存 7 天; +- 腾讯云语音优化用户数据授权是自愿授权,Petstore 不应开启该额外授权。 + +因为 Petstore 方案的默认原则是不持久化完整对话原文,「识别文本保留 7 天」必须在隐私告知和供应商数据处理评审中明确,不能只依赖我们自己不落库。 + +**文本模型平台变化** + +- 腾讯云官方已说明原混元/DeepSeek API 售卖入口逐步迁移到 TokenHub; +- 新项目应使用 TokenHub 而非旧混元平台,OpenAI SDK 兼容 `base_url` 为 `https://tokenhub.tencentmaas.com/v1`; +- TokenHub 可选模型变化较快,正式纳入前需按具体模型快照验证 JSON 遵循、时间表达和延迟。 + +### 3.3 腾讯 ASR + 阿里 Qwen(仅当实测显著更好) + +混合方案可在不改模型的情况下使用腾讯 ASR,但会引入: + +- 两套云账号、密钥、费用告警和故障域; +- 两份数据处理和隐私告知边界; +- 更长的排障链路。 + +只有当腾讯 ASR 在 Petstore 脱敏语音语料的关键槽位准确率显著高于 `qwen3-asr-flash-2026-02-10`,且 7 天识别文本保留已通过隐私评审时,才采用混合方案。 + +### 3.4 OpenAI(非当前生产候选) + +OpenAI 官方提供语音转写和结构化模型能力,但当前官方 API 支持国家与地区列表不包含中国大陆。官方同时说明,从未列出地区访问或提供访问可能导致账号被阻止或暂停。 + +因此本项目不使用绕过地区支持范围的网络或账号方案,也不将其写入当前生产 Runbook。 + +## 4. M0 固定配置建议 + +### 4.1 模型调用 + +- Model:`qwen-plus-2025-12-01` +- Region:`cn-beijing` +- Mode:非思考 +- Streaming:关闭,M0 使用完整 JSON 响应 +- Response format:`json_object` +- Function Calling:关闭,模型不拥有 Petstore 工具 +- Web search / built-in tools:关闭 +- Temperature:低随机性,编码前经 30 条语料实测后冻结 +- Timeout:建议 3 秒超时、不进行多次自动重试,最终值以腾讯云服务器实测为准 + +### 4.2 语音调用 + +- Model:`qwen3-asr-flash-2026-02-10` +- Region:`cn-beijing` +- Input:服务端从短期上传流读取字节,转 Base64 Data URL +- Business limit:单段不超过 60 秒、3 MB +- Language hint:中文,结果仍由用户编辑确认 +- Context glossary:宠小它、当前门店实际服务名、当前 customer 的宠物展示名;不上传手机号、其他客户宠物名或全量客户名单 +- Raw audio persistence:禁止 + +### 4.3 密钥与环境变量 + +为了允许分别轮换和后续切换供应商,即使 M0 同用阿里云,也保留独立逻辑配置: + +```dotenv +PETSTORE_BOOKING_AGENT_ENABLED=false +PETSTORE_BOOKING_AGENT_LLM_PROVIDER=aliyun +PETSTORE_BOOKING_AGENT_LLM_BASE_URL=https://.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 +PETSTORE_BOOKING_AGENT_LLM_MODEL=qwen-plus-2025-12-01 +PETSTORE_BOOKING_AGENT_LLM_API_KEY= +PETSTORE_BOOKING_AGENT_LLM_TIMEOUT_MS=3000 + +PETSTORE_BOOKING_AGENT_ASR_PROVIDER=aliyun +PETSTORE_BOOKING_AGENT_ASR_BASE_URL=https://.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 +PETSTORE_BOOKING_AGENT_ASR_MODEL=qwen3-asr-flash-2026-02-10 +PETSTORE_BOOKING_AGENT_ASR_API_KEY= +PETSTORE_BOOKING_AGENT_ASR_TIMEOUT_MS=5000 +``` + +上述只是变量名与占位,不是可用密钥。真实 Workspace ID 和 API Key 不进 Git、聊天、日志、截图或测试 fixture。 + +## 5. 脱敏语料对照方案 + +### 5.1 文字意图集 + +建立 30 条合成/脱敏中文预约用例: + +- 8 条标准预约; +- 5 条相对日期与时间段; +- 4 条多宠物/同名歧义; +- 4 条服务同义表达; +- 3 条无号、过去日期或非营业时间; +- 3 条修改上一轮草稿; +- 3 条越界请求(价格编造、任意宠物 ID、绕过确认)。 + +每条用例只保存预期结构化字段和下一状态,不保存真实客户资料。 + +### 5.2 语音对照集 + +- 从文字集选 20 条,由已知情并同意的测试人员录制; +- 覆盖普通话、轻微口音、室内背景声和宠物名/服务名; +- 不使用门店客户的真实录音,不在 Git 保存可识别真人的音频; +- 本地音频仅用于一次性对照,结果只归档脱敏文本、槽位判定和延迟。 + +### 5.3 判定指标 + +| 类型 | 指标 | M0 建议门槛 | +|---|---|---| +| LLM | 输出可解析 JSON | 30/30 | +| LLM | 意图、宠物查询词、服务查询词、日期表达、时间窗口槽位准确率 | ≥ 90% | +| LLM | 越权请求进入写路径或产生伪造业务事实 | 0 | +| ASR | 宠物名、服务名、日期/时间等关键槽位识别准确率 | ≥ 90% | +| ASR | 转写延迟 p95 | ≤ 3 秒,以腾讯云当前服务器实测 | +| LLM | 意图提取延迟 p95 | ≤ 2 秒 | +| 链路 | 语音结束到确定性回复 p95 | ≤ 5 秒 | + +ASR 供应商的最终选择以「关键槽位准确率 + p95 延迟 + 数据保留可接受性」为准,不以通用宣传的全局字错率代替 Petstore 业务语料。 + +## 6. 试点成本量级 + +以 50 个试点 session 、每个 session 2 段 10 秒语音、4 次模型调用为示例: + +- ASR:`50 * 2 * 10 * 0.00022 元 = 0.22 元`; +- LLM:假设每次 1000 输入 token + 200 输出 token,按当前华北2列价 `0.8 元/百万输入 token` 与 `2 元/百万输出 token`,约 `0.24 元`; +- 示例总模型调用费约 `0.46 元`,不包含公网流量、账号优惠、日志和人工评测成本。 + +该数字只说明 M0 小样本的 API 费用不是核心矛盾,不是生产预算承诺。实际决策优先看准确性、数据边界、稳定性和降级。 + +## 7. 生产前必须完成 + +- [ ] 开通华北2(北京)百炼业务空间,确认 Workspace 专属域名可用。 +- [ ] 为 LLM 和 ASR 创建可独立轮换的服务端密钥,不共享个人开发密钥。 +- [ ] 确认数据处理、保留、删除、不用于训练和工单响应口径。 +- [ ] 在小程序隐私声明和首次语音使用前完成明确告知,只在用户主动按住录音时收集。 +- [ ] 在腾讯云实际后端服务器完成 DNS、TLS、p50/p95 延迟、超时和失败降级实测。 +- [ ] 开启预算与异常用量告警,限制单用户和单门店频率。 +- [ ] 模型快照、提示词版本、schema 版本和供应商请求 ID 可追溯,但日志不保存完整对话。 + +## 8. 官方资料 + +### 阿里云 + +- [选择地域、服务部署范围和接入域名](https://help.aliyun.com/zh/model-studio/regions/) +- [语音识别模型选型](https://help.aliyun.com/zh/model-studio/asr-model/) +- [qwen3-asr-flash 模型信息](https://help.aliyun.com/zh/model-studio/qwen3-asr-flash) +- [Qwen-ASR API 参考](https://help.aliyun.com/zh/model-studio/qwen-asr-api-reference) +- [非实时语音识别](https://help.aliyun.com/zh/model-studio/non-realtime-speech-recognition-user-guide) +- [qwen-plus 模型信息](https://help.aliyun.com/zh/model-studio/qwen-plus) +- [结构化输出](https://help.aliyun.com/en/model-studio/qwen-structured-output) +- [百炼产品与数据说明](https://help.aliyun.com/zh/model-studio/what-is-model-studio) + +### 腾讯云 + +- [一句话识别 API](https://cloud.tencent.com/document/api/1093/35646) +- [语音识别请求结构与地域接入](https://cloud.tencent.com/document/product/1093/35639) +- [语音识别 SDK 个人信息保护规则](https://cloud.tencent.com/document/product/1093/73072) +- [语音识别功能 FAQ(含音频/识别文本保留口径)](https://cloud.tencent.com/document/faq/1093/35802) +- [语音识别用户数据授权协议](https://cloud.tencent.com/document/product/1093/115535) +- [TokenHub 迁移指南](https://cloud.tencent.com/document/product/1823/131382) + +### OpenAI + +- [OpenAI API 支持的国家和地区](https://help.openai.com/en/articles/5347006-openai-api-supported-countries-and-territories)