docs: define ask-master conversation memory plan

AGENTS.md

@@ -46,7 +46,7 @@
 ## 当前业务边界
 
 - 管理端业务路由集中在 `frontend/src/router/index.ts`，覆盖首页、AI 面试、训练运营、问题榜、案例、知识空间、SOP、资料处理、系统配置、组织权限和成长激励；侧栏过滤在 `frontend/src/layout/components/Sidebar/index.vue`，不要恢复若依默认全量菜单。
-- 用户侧只改 `mobile-uni/src/pages/*`；员工、候选人、主管首页分别为 `/pages/user/today/index`、`/pages/candidate/index/index`、`/pages/supervisor/index/index`，旧 `/h5/user|candidate|supervisor|employee|admin` 只做兼容重定向。底栏固定「今日/练/问/我」；SOP 搜索/总结卡复用 `/api/knowledge/search` 和 `/api/knowledge/summary-card`，失败不兜假数据。
+- 用户侧只改 `mobile-uni/src/pages/*`；员工、候选人、主管首页分别为 `/pages/user/today/index`、`/pages/candidate/index/index`、`/pages/supervisor/index/index`，旧 `/h5/user|candidate|supervisor|employee|admin` 只做兼容重定向。底栏固定「今日/练/问/我」；问师傅文字和现场附件查询复用 `/api/knowledge/query`、`/api/knowledge/query-media`，总结卡复用 `/api/knowledge/summary-card`，失败不兜假数据。
 - 不要把三端概括成全模态：员工对练/每日题和问师傅支持文字/语音，问师傅图片/视频只用于本次分析，案例传音频；候选面试支持文字/语音，资料可传文档/图片但图片不参与评分；主管写文字复盘/指派并回听录音。员工对练图像/视频情境、服务录像回放和方言正式验收仍未完成；语音继续复用 `services/speech.ts` 与 `/api/ai/asr`。
 - 问题榜奖励只记积分/学习学分，不得擅自增加现金、提现、预算或税务语义；选最佳答案和考试提交必须保持请求幂等。
 - 全网 AI 与企业问师傅必须分入口、分来源和分免责声明；提供方仅允许公网 HTTPS，修改地址/密钥后必须连接测试成功才能启用，未配置时明确不可用且不生成假答案。

README.md

@@ -18,7 +18,7 @@
 - 正式试点：管理端可按起止日期导出正式试点 CSV，严格门禁只统计唯一映射到在职组织的训练、校准和 SOP 评审。组织身份同步和至少 20 名手机号映射门槛已具备；下一步仍需选定真实试点窗口，产生员工训练、人工校准和 SOP 评审样本后重跑严格门禁，详见 [演示与试点验收](docs/DEMO_ACCEPTANCE.md)。
 - 侧栏：只展示当前 AIHR 业务菜单；过滤名单在 `frontend/src/layout/components/Sidebar/index.vue`，不要恢复若依默认全量菜单。
 - 本地短信：真实阿里云短信参数放根目录 `.env.local`，由 `scripts/dev-backend.sh` 自动加载；不要把密钥写入 `application-dev.yml`。dev 未配短信时验证码固定 `123456`（`aihr.sms.dev-fixed-code`，prod 强制失效）。
-- 生产基线（2026-07-18）：`32fa376d` 已发布，管理端/H5/后端产物哈希一致，21 个迁移完成，目标 schema `34/34`、新增表排序规则兼容 `18/18`；服务、公开 HTTP 和关键页面已验证。正式 OTP 写链路、真机能力和严格试点仍未验收，详见 [BRD 功能审查记录](docs/BRD_IMPLEMENTATION_AUDIT.md)。
+- 生产状态属于易变事实，不在总入口固定某次提交或迁移数量；发布前后按 [BRD 功能审查记录](docs/BRD_IMPLEMENTATION_AUDIT.md)、[生产迁移 Runbook](docs/BRD_PRODUCTION_MIGRATION_RUNBOOK.md) 和正式预检结果确认。正式 OTP 写链路、真机能力和严格试点仍需独立验收。
 
 ## 快速启动
 
@@ -52,6 +52,7 @@
 | [本地运行手册](docs/DEV_SETUP.md) | 端口、账号、启动和基础验证 |
 | [MVP 演示与验收清单](docs/DEMO_ACCEPTANCE.md) | MVP 演示脚本、录屏兜底和验收口径 |
 | [后端 API 对接指南](docs/API_INTEGRATION.md) | 后端模块落点、正式试点 CSV、移动端训练/复盘、候选资料上传/审核和 SOP 上传解析接口 |
+| [问师傅多轮会话与原始资料交付设计](docs/20260718/问师傅多轮会话与原始资料交付设计.md) | 当前单轮 RAG 缺口、短期会话、指代改写、意图路由、原文件/视频安全交付及验收边界 |
 | [BRD 功能审查记录](docs/BRD_IMPLEMENTATION_AUDIT.md) | 现阶段结论、三端输入匹配矩阵、权限、迁移、线上资源和未完成项证据 |
 | [BRD 生产迁移 Runbook](docs/BRD_PRODUCTION_MIGRATION_RUNBOOK.md) | 生产 schema/内置内容迁移、只读预检、发布和回滚边界 |
 | [ruoyi-ai 能力分片迁移计划](docs/RUOYI_AI_INCREMENTAL_MIGRATION.md) | 知识库、模型能力、文档解析、RAG、chat 的渐进迁移边界 |

docs/20260718/问师傅多轮会话与原始资料交付设计.md

@@ -0,0 +1,131 @@
+# 问师傅多轮会话与原始资料交付设计
+
+> 状态：实施基线，尚未代表代码完成、生产发布或业务验收。
+>
+> 目标：让“问·数字师傅”能理解本次连续对话中的指代，并在当前授权范围内交付命中的原文件或操作视频。
+
+## 1. 当前事实与问题
+
+`mobile-uni/src/pages/user/sop/index.vue` 会在页面内展示消息列表，但每次文字查询只向 `POST /api/knowledge/query` 发送当前 `queryText`；附件查询同样只向 `POST /api/knowledge/query-media` 发送当前问题和本次附件。页面刷新、重新进入或服务端生成答案时都没有可用的对话上下文。
+
+因此当前能力是“微信式界面 + 单轮无状态 RAG”，不是多轮智能会话。典型失败包括：
+
+- 用户先问“自动扶梯困人怎么办”，再说“把这个 SOP 原文件给我”，第二句无法确定“这个”指什么；
+- 用户说“有没有操作视频”，系统仍按普通知识问答检索，可能返回另一份语义相近但无关的 SOP；
+- 命中文档后只有引用片段，缺少经过再次授权校验的原文件或视频入口。
+
+## 2. 第一版目标与非目标
+
+第一版完成：
+
+1. 内部登录用户拥有 30 分钟不活跃过期的短期会话；页面可显式“新对话”。
+2. 使用现有 chat 模型把追问改写为可独立检索的问题，并输出 `QA`、`FILE`、`VIDEO`、`DATA_TOOL` 四类意图。
+3. 改写后的问题继续走现有租户、调用应用、主体授权交集和 RAG 链路。
+4. 文件/视频只从当前命中且仍有权限的知识附件中返回；下载时再次校验权限。
+5. 模型、会话表或附件不可用时明确降级，不编造上下文、链接或文件。
+
+第一版不做：
+
+- 跨天长期记忆、用户画像记忆或对话向量库；
+- 对外 API_TOKEN 调用端的有状态会话；
+- 自动执行任意数据库查询、自然语言转 SQL；
+- 把用户上传的本次图片/视频自动写入共享知识库；
+- 仅凭语义相似度把未命中的文件伪装成“原文件”。
+
+## 3. 会话数据
+
+新增单表 `aihr_knowledge_conversation`，只保存一个会话的压缩 JSON，不拆消息表：
+
+| 字段 | 作用 |
+|---|---|
+| `tenant_id`、`app_id`、`user_id` | 会话隔离键，全部由服务端身份解析 |
+| `conversation_id` | 客户端持有的随机会话 ID |
+| `version` | 乐观并发版本 |
+| `context_json` | 最近最多 6 轮的脱敏问题、截断答案、引用标题/文档 ID |
+| `expires_time` | 30 分钟不活跃过期时间 |
+| `create_time`、`update_time` | 审计时间 |
+
+约束：单个用户问题最多 600 字、单个答案最多 800 字、送入模型的会话上下文最多 6000 字；过期记录惰性清理。唯一键为 `tenant_id + app_id + user_id + conversation_id`。客户端不能传租户、应用或用户身份。
+
+## 4. 查询契约
+
+内部 `POST /api/knowledge/query` 和 `POST /api/knowledge/query-media` 增加可选字段：
+
+```json
+{
+  "conversationId": "01J...",
+  "contextVersion": 3
+}
+```
+
+响应在现有字段上增加：
+
+```json
+{
+  "conversationId": "01J...",
+  "contextVersion": 4,
+  "intent": "FILE",
+  "rewrittenQuery": "自动扶梯困人应急操作 SOP 原文件",
+  "resources": [
+    {
+      "attachmentId": 123,
+      "title": "自动扶梯困人应急操作 SOP.pdf",
+      "type": "FILE",
+      "contentUrl": "/api/knowledge/resources/123/content"
+    }
+  ]
+}
+```
+
+旧客户端不传会话字段时继续按无状态查询处理。外部 `POST /api/open/knowledge/query` 保持无状态，并忽略或拒绝会话字段。
+
+## 5. 处理流程
+
+```text
+内部登录与应用解析
+  → 计算租户 + 应用 + 主体的有效知识空间
+  → 读取本人未过期会话并校验 contextVersion
+  → 现有 chat 模型 temperature=0 输出 rewrittenQuery + intent
+  → QA/FILE/VIDEO：在有效空间内执行现有混合检索
+  → DATA_TOOL：只执行既有白名单工具及角色/项目范围校验
+  → FILE/VIDEO：把命中 docId 映射为当前空间的附件资源
+  → 返回答案、引用、资源和新 contextVersion
+  → 脱敏截断后更新最近 6 轮会话
+```
+
+模型输出必须使用固定 JSON 契约。JSON 解析失败或模型不可用时，以原问题检索，并用关键词规则只做保守意图判断；不能从历史上下文猜测缺失主体。
+
+## 6. 原文件和视频安全
+
+新增认证接口 `GET /api/knowledge/resources/{attachmentId}/content`。每次下载必须重新计算当前租户、调用应用、用户/角色与知识空间授权，并确认附件仍属于有效空间，然后才通过现有 OSS 服务流式返回内容。
+
+响应只暴露业务附件 ID、标题、类型和受控接口地址，不暴露 `ossId`、对象存储 key、原始 OSS URL 或服务器路径。权限被撤销、文件被解绑或附件不存在时立即拒绝；对话中曾经命中过不能覆盖下载时的实时授权。
+
+视频意图只返回视频类型附件；没有视频时明确回答“当前授权资料中未找到相关视频”，不把 PDF、图片或用户本次上传的视频替代成知识库操作视频。
+
+## 7. 并发与降级
+
+- 客户端提交旧 `contextVersion` 时返回冲突，避免两个请求互相覆盖上下文。
+- 会话不存在或过期时，从空上下文继续当前问题，并返回新的版本。
+- 会话持久化失败时保留当前单轮 RAG 能力，同时不声称已理解前文。
+- RAG 无证据时沿用 `noEvidence=true`；文件/视频意图无附件时返回空 `resources` 和明确说明。
+- 原始资料接口失败不回退到公开 URL、跨空间附件或模型生成链接。
+
+## 8. 移动端交互
+
+问师傅页维护当前 `conversationId/contextVersion`，消息仍只作当前页面展示。顶部提供“新对话”，清空页面消息和会话标识。答案卡增加原文件/视频资源卡，点击时复用现有鉴权文件下载能力；页面卸载或资源替换时释放本地 blob URL。
+
+需要验证文字和语音追问、模型失败、会话过期、并发冲突、无文件、无视频、授权撤销、重新登录和超大字号。微信式外观不再作为“有记忆”的完成证据。
+
+## 9. 验收用例
+
+最小连续对话：
+
+1. “自动扶梯困人怎么办？”返回有依据的 SOP 答案和引用。
+2. “把这个 SOP 原文件给我。”`rewrittenQuery` 指向同一主题，只返回当前授权附件。
+3. “有操作视频吗？”只返回同一主题的视频；不存在时明确无视频。
+4. 点击资料可下载；撤销空间授权后，同一链接立即拒绝。
+
+安全与回归还需覆盖：跨用户/跨租户会话不可读、旧版本冲突、30 分钟过期、模型关闭、OSS 缺失、视频类型过滤、外部 API 保持无状态、旧客户端单轮查询不回退。
+
+完成结论分为：代码实现、自动化测试、本地 HTTP、移动端视觉与交互、生产部署、生产真实多轮、正式业务验收；这些层级不得互相替代。

docs/API_INTEGRATION.md

@@ -13,7 +13,7 @@
 | 对练语音 | `POST /api/ai/asr`（multipart 字段 `file`，≤5MB）、`POST /api/ai/tts`（JSON `{text≤300字, voice?, voiceProfile?:{role,voice?,speed?,emotion?}}`，旧 `voice` 兼容；成功返回 `ossId`，客户端播放地址为受控的内联 `data:audio/*`，不返回原始 OSS URL）、`GET /api/aihr/mobile/oss/{ossId}` | 走 OpenAI-compatible audio 接口；生产 SiliconFlow CosyVoice2 按角色映射老师傅/业主/面试官音色，业主对练再按已有情绪分切换平静/严肃/强烈语气和语速，设备语音降级同步调整语速与音高；模型管理需启用 `category=asr/tts` 配置；移动端优先用浏览器录音，`getUserMedia/MediaRecorder` 不可用或麦克风权限失败时，用 `audio/*` file input 选择/录制音频后继续调同一 ASR 接口；ASR/TTS 未配置或失败返回 fail，前端降级设备语音或文本；训练/每日题录音只通过 `audioOssId` 走受保护下载，历史客户端传入的 HTTP `audioUrl` 不再回显；TTS 成功音频仍写入 `sys_oss` 留痕，同时用内联 data URL 保持旧客户端可播放；音频下载按员工本人或主管项目范围授权，系统管理端保持后台访问 |
 | 案例沉淀 `/knowledge/cases` | `GET /api/knowledge/case/capabilities`、`POST /api/knowledge/case/upload`、`/organize`、`/curate`、`GET /records`、`GET /records/{caseId}`、`POST /records/{caseId}/review`、`GET /records/{caseId}/media` | `/capabilities` 返回服务端判定的案例提交/查看能力，移动端不再向普通员工展示无权提交的素材表单；`/upload` 改为 multipart 真实语音上传并走 ASR，服务端只接受 MP3/WAV/M4A/WebM/OGG/AAC/FLAC，成功后原始音频写入 `sys_oss`，案例记录只保存 `mediaOssId` 供受保护媒体接口读取，不向客户端回传原始 `mediaUrl`；`/organize` 用真实转写调 chat 模型整理案例，未配置模型时按真实 transcript 本地结构化，并从背景外的真实摘要项提取学习点；APP 用户的项目范围从 `aihr_org_snapshot` 登录身份解析，上传、整理、入库、列表和详情均按项目范围校验，未完成正式组织映射时安全拒绝，不接受前端伪造项目范围；员工列表/详情只返回 `已入库` 案例，管理端系统用户保留全局运营视图；移动端和管理端案例详情通过受保护媒体接口回放原始音频，主管/项目负责人可提交脱敏点评；预渲染视频样片仍待正式媒体资产接入 |
 | 案例媒体安全 | `GET /api/knowledge/case/records/{caseId}/media` | 案例详情只返回 `mediaOssId`，不返回原始 `sys_oss.url`；媒体下载会重复执行登录、后台角色或 APP 项目范围校验，再由服务端流式读取 OSS。管理端与 `mobile-uni` 通过鉴权 blob/temp 文件播放，关闭详情页时释放本地对象 URL |
-| SOP知识库 `/knowledge/sop` | `POST /api/knowledge/search`、`POST /api/knowledge/answer-feedback`、`GET /api/knowledge/position-sop`、`GET /api/aihr/mobile/onboard/tasks`、`POST /api/aihr/mobile/onboard/tasks/{id}/complete`、`GET /api/aihr/mobile/qualification`、`POST /api/knowledge/doc/upload` | 已接入 MySQL Fulltext + Qdrant 混合召回、岗位学习适配摘要、OSS-first 文档上传、txt/md/PDF/Word/Excel/PPT 解析和 embedding 写入，失败回退 seed；搜索返回 `reviewId` 与 `promptVersion`，员工反馈回传并保存该评审批次，SOP 人工评审记录同时保留答案生成提示词版本，管理端可继续复核；员工学习页按当前 APP 身份读取正式岗前/入职任务，员工只能将本人处于“待完成/进行中”的任务确认完成，服务端按组织快照/手机号归属更新 `status/completed_time`，不接受前端身份参数；资格证据无正式数据时明确返回 `NOT_CONFIGURED`，不以 AI 分数代替上岗资格；`position-sop` 仍保留一期生活顾问学习导航语义 |
+| 问师傅与 SOP 知识库 `/pages/user/sop/index`、`/knowledge/sop` | `POST /api/knowledge/query`、`POST /api/knowledge/query-media`、`POST /api/knowledge/answer-feedback`、`GET /api/knowledge/position-sop`、`GET /api/aihr/mobile/onboard/tasks`、`POST /api/aihr/mobile/onboard/tasks/{id}/complete`、`GET /api/aihr/mobile/qualification`、`POST /api/knowledge/doc/upload` | 当前文字/现场附件查询已走统一知识空间授权和 MySQL Fulltext + Qdrant 混合召回；搜索返回 `reviewId` 与 `promptVersion`，员工反馈回传并保存该评审批次。现状仍是每次只提交当前问题的单轮 RAG，页面消息列表不等于服务端对话记忆；多轮指代、意图路由和原文件/视频交付按 [专项设计](20260718/问师傅多轮会话与原始资料交付设计.md) 实施。员工学习页按当前 APP 身份读取正式岗前/入职任务，资格证据无正式数据时明确返回 `NOT_CONFIGURED`；`position-sop` 保留一期生活顾问学习导航语义 |
 | 资料处理 `/knowledge/processing` | `GET /api/knowledge/processing/overview`、`POST /api/knowledge/doc/upload-async`、`GET /api/knowledge/doc/upload-items`、`POST /api/knowledge/doc/upload-items/{id}/retry` | 已接入解析任务状态聚合；页面只保留“批量导入”，接口暂存+入队即秒回，后台 worker（并发 2）逐条解析/归类/向量化；ZIP 在 worker 内安全解压后把支持的子文件继续入同一批次队列，页面按批次轮询进度、失败可单文件重试；不提供浏览器目录选择或服务端目录导入入口 |
 | 组织人员同步 | `POST /api/aihr/org/sync` | 从开放组织同步系统的 `/api/open/v1/sync/snapshot` 拉取 `company/department/employee` 快照，分页参数使用 `limit`；员工手机号只落 `person_phone` 用于移动端身份映射，不在组织列表响应暴露；岗位识别 `position/job_title/post/job_name/role/title` 等字段。`dryRun` 必须显式传入 `true`（预检）或 `false`（写入），省略或传 `null` 直接拒绝，避免空请求意外写库；默认 `replaceExisting=true`，写入前必须先用 `{"dryRun":true}`；dry-run 不访问本地快照表、不执行 DDL/写库，返回 `phoneLinked/maskedPhone/suspectText/warnings` 且 `syncedCount=0`。非 dry-run 覆盖写入遇到员工被跳过、手机号不完整、脱敏手机号或疑似乱码时默认拒绝，只有确认 dry-run 结果后显式传 `allowPartialReplace=true` 才允许覆盖；重复 `ext_party_id` 始终拒绝写入，因为数据库唯一键会折叠重复身份；`replaceExisting=false` 不触发不完整快照覆盖闸门，但仍拒绝重复身份。2026-07-15 线上已用 `/api/open/v1` 前缀完成配置、dry-run 和覆盖同步：开放平台返回公司 17、部门 963、员工 3417；生产 `aihr_org_snapshot` 为 3417 行，`phoneLinked=3392`、`maskedPhone=25`、`suspectText=0`，在职 2943、离职 474。当前剩余 25 人手机号不可用属于上游数据质量问题；功能发布不再被组织同步能力阻塞 |
 | 移动端手机号登录 | `GET /resource/sms/code`、`POST /auth/mobile/sms-login` | 已复用 sms4j 阿里云配置 `config1` 和 RuoYi `sms` 授权策略；短信发送成功后才写 Redis 验证码；手机号不存在时自动注册 `app_user`；`aihr.sms.dev-fixed-code` 非空时不真发短信、验证码固定（dev 默认 `123456`）。prod 默认关闭，试点期只有同时设置 `AIHR_SMS_DEV_FIXED_CODE` 与 `AIHR_SMS_PROD_FIXED_CODE_ENABLED=true` 才启用固定码。 |

docs/BACKLOG.md

@@ -122,6 +122,10 @@
 
 ## Future Enhancements
 
+### 问师傅短期多轮与资料交付
+
+当前页面只有微信式消息外观，服务端查询仍是单轮 RAG。短期会话、指代改写、问答/原文件/视频/数据工具意图路由和受控资料下载已进入实施，完整范围与安全边界见 [问师傅多轮会话与原始资料交付设计](20260718/问师傅多轮会话与原始资料交付设计.md)。完成后从活动待办移除，并把最终契约同步到 `API_INTEGRATION.md`。
+
 ### Model Classification Version Governance
 
 Current behavior:

docs/README.md

@@ -14,6 +14,7 @@
 | [FIGMA需求覆盖与版本偏差审计-20260717.md](FIGMA需求覆盖与版本偏差审计-20260717.md) | 旧版功能、已确认需求、Figma 实际画板与当前实现的四方对照，以及防止遗漏旧功能和误拉后续阶段的事实源规则 |
 | [DEMO_ACCEPTANCE.md](DEMO_ACCEPTANCE.md) | 一期 MVP 演示脚本、录屏兜底、MVP 演示流验收清单 |
 | [API_INTEGRATION.md](API_INTEGRATION.md) | 后端 API 对接顺序、正式试点 CSV、移动端训练记录/复盘详情、候选资料上传/审核、SOP 上传解析接口 |
+| [20260718/问师傅多轮会话与原始资料交付设计.md](20260718/问师傅多轮会话与原始资料交付设计.md) | 问师傅从单轮 RAG 升级为短期多轮问答、指代改写、意图路由和受控原文件/视频交付的实施基线 |
 | [KNOWLEDGE_PLATFORM_RUNBOOK.md](KNOWLEDGE_PLATFORM_RUNBOOK.md) | 银城/美途知识空间初始化、授权、令牌、内容迁移、监控验证和安全回滚手册 |
 | [RUOYI_AI_INCREMENTAL_MIGRATION.md](RUOYI_AI_INCREMENTAL_MIGRATION.md) | 从 `ageerle/ruoyi-ai` 分片迁移知识库、模型能力、文档解析、Qdrant/RAG 和 chat 的执行边界 |
 | [superpowers/specs/2026-07-16-multi-tenant-knowledge-platform-design.md](superpowers/specs/2026-07-16-multi-tenant-knowledge-platform-design.md) | 银城/美途独立租户、多知识空间、多调用应用统一问答、授权交集、受控数据工具和安全验收的完整需求方案 |