docs: reconcile production release contracts

AGENTS.md

@@ -11,6 +11,7 @@
 - `mobile-uni/` 是当前用户侧工程，承载员工端、候选人端、主管端，使用 uni-app Vue3 H5，后续便于转换 H5/APP/小程序；旧 `mobile/` 仅保留为 MVP 演示兜底，不再承载新增功能。
 - 本项目自己的本地编排放在根目录：`docker-compose.dev.yml`、`scripts/`；运行说明在 `docs/DEV_SETUP.md`。
 - 除非确实要接业务模块，不要改上游框架默认配置；本地端口和开关优先放根目录脚本里覆盖。
+- 新增或变更 AIHR DDL 时，所有 `aihr_*`.`tenant_id` 必须显式使用与框架 `sys_oss.tenant_id` 相同的 `utf8mb4_general_ci`；跨模块连接不能靠吞错或永久 `binary` 兼容掩盖排序规则漂移。
 
 ## 本地运行
 
@@ -41,6 +42,7 @@
 
 - 线上移动端 H5：`https://peilian.njzhmj.top/h5/`，Caddy 服务 `/opt/wygj/www/h5`。
 - 只发布移动端静态资源时，用 `npm --prefix mobile-uni run build:h5` 后备份远端 `/opt/wygj/www/h5`，再 `rsync -az --delete mobile-uni/dist/build/h5/ YCWY:/opt/wygj/www/h5/`；前端静态修复不需要重启后端。
+- 后端或含后端发布完成后，必须按 `docs/BRD_PRODUCTION_MIGRATION_RUNBOOK.md` 运行远端 schema + 后端内容核验；仅后端发布可显式设置 `RELEASE_VERIFY_REMOTE_STATIC=false`，不得省略 schema 门禁。
 
 ## 品牌入口
 
@@ -67,11 +69,11 @@
 - 对练语音走 `POST /api/ai/asr`（≤5MB multipart）和 `POST /api/ai/tts`（文本≤300字，返回 base64 dataURL）；模型走 `aihr_model_config` 的 `asr`/`tts` 类目（`category` 全集：chat/vector/rerank/asr/tts/vision）。移动端 `getUserMedia/MediaRecorder` 不可用或麦克风权限失败时，用隐藏 `audio/*` file input 选择/录制音频后继续走同一 ASR 接口，不要退回只有文字输入。multipart 头部的 filename/contentType 已做 CRLF 清洗，新增外发 HTTP 时同样注意。
 - 后端业务代码不要塞进上游 `ruoyi-demo`；自有 API 放在 `backend/ruoyi-modules/ruoyi-aihr`，再接入 `ruoyi-admin`。
 - AI 面试页、三角色对练页、案例沉淀页、SOP 知识库页和移动端三端首页已是 API 优先 + 本地 fallback；SOP 知识库优先查 `aihr_knowledge_fragment` 的 MySQL Fulltext，vector 模型和 Qdrant 可用时混合召回，`category=rerank` 模型启用时融合后语义重排（失败保持 RRF 顺序）；支持 `.txt/.md/.markdown/.pdf/.doc/.docx/.xls/.xlsx/.ppt/.pptx`、图片 `.jpg/.jpeg/.png/.gif/.webp/.bmp` 及视频 `.mp4/.mov/.avi/.mkv/.webm/.m4v` 上传解析入库。
-- 浏览器批量上传走异步队列 `POST /api/knowledge/doc/upload-async`（暂存目录 `aihr.upload.staging` 默认 `./.data/staging`，队列表 `aihr_knowledge_upload_item`，单文件重试）；同步接口 `POST /api/knowledge/doc/upload` 只留给 SOP 页单文件即时预览，**不要把重加工逻辑加回同步请求线程**。视频（≤500MB/≤60分钟）只走异步队列，依赖服务器安装 ffmpeg/ffprobe。
+- 浏览器批量上传走异步队列 `POST /api/knowledge/doc/upload-async`（暂存目录 `aihr.upload.staging` 默认 `./.data/staging`，队列表 `aihr_knowledge_upload_item`，单文件重试）；ZIP 文件名按 UTF-8 解码并兼容 GBK，必须保留 Zip Slip、条目数/解压量、嵌套 ZIP、同名文件和失败清理保护。同步接口 `POST /api/knowledge/doc/upload` 只留给 SOP 页单文件即时预览，**不要把重加工逻辑加回同步请求线程**。视频（≤500MB/≤60分钟）只走异步队列，依赖服务器安装 ffmpeg/ffprobe。
 - SOP 上传接口是 `POST /api/knowledge/doc/upload`，表单字段为 `file` 和 `category`；当前限制 100MB 内，支持 txt/md/PDF/Word/Excel/PPT 及图片，先写 MinIO/`sys_oss` 再绑定 `aihr_knowledge_attach.oss_id`，同一知识库同名文件会替换旧 fragment。若数据库启用 `category=vector` 的模型配置，会同步调用 OpenAI-compatible `/embeddings`，写入 `embedding_json` 并尽力 upsert 到 Qdrant；配置缺失或外部 embedding 失败才用 `local-hash-v1` 兜底，Qdrant 不可用时保留 MySQL Fulltext/seed fallback。管理端 `uploadKnowledgeDoc` 单接口 timeout 是 180s；遇到约 50s `Broken pipe` 先查浏览器客户端超时，不要改全局 axios。
 - 图片视觉 OCR：上传图片时经 `visionRuntime()` 找启用模型（优先 `aihr_model_config.category='vision'`，无则回退 `category='chat'`），把图片编码成 base64 data URL 调 OpenAI-compatible `/chat/completions` 提取文字再切分入库；无可用视觉模型或 OCR 无结果时按「待处理」落库（0 片段），不算失败。视频关键帧用带画面描述的 FRAME_PROMPT（文字+一句场景描述），改 prompt 时别退回纯 OCR。不依赖 Tesseract。
 - 向量库状态接口是 `GET /api/knowledge/doc/vector-index-status`，重建接口是 `POST /api/knowledge/doc/rebuild-vector-index`；外部 embedding 成功但 Qdrant collection 维度不一致时不要静默降级，走状态提示和重建。
-- 资料处理接口是 `GET /api/knowledge/processing/overview`，直接聚合 `aihr_knowledge_attach`、`aihr_knowledge_fragment` 和 `sys_oss.ext1`；`POST /api/knowledge/doc/import-local` 保留同步导入，`POST /api/knowledge/doc/import-local-task` + `GET /api/knowledge/doc/import-tasks` 用于页面启动后台目录导入和轮询进度，`POST /api/knowledge/doc/import-tasks/{id}/cancel` 取消运行中任务。目录只能是 `aihr.import.root` 下的相对路径，逐文件复用上传解析链路；大批量资料优先走服务端导入任务，不走浏览器单次上传。
+- 资料处理接口 `GET /api/knowledge/processing/overview` 直接聚合 `aihr_knowledge_attach`、`aihr_knowledge_fragment` 和 `sys_oss.ext1`；查询异常必须向上暴露并记录，不能转换成“0 份资料”的假成功。目录导入只能读取 `aihr.import.root` 下的相对路径并复用上传链路，接口契约见 `docs/API_INTEGRATION.md`。
 - seed service 阶段已完成；后续按 `docs/RUOYI_AI_INCREMENTAL_MIGRATION.md` 分片迁移 `ruoyi-ai` 的知识库、文档解析、RAG、chat 能力。
 - 迁移时不要整包搬 `ruoyi-chat`；优先在 `ruoyi-aihr` 内吸收必要表、service、loader 和检索接口，并保留 seed fallback。
 - 已落地的演示流不要退回静态壳：AI 面试、三角色对练、案例沉淀已是真模型优先（未配置/失败回退本地兜底），SOP 知识库、移动端三端首页保留 fallback——改造时降级链必须保留。
@@ -79,16 +81,5 @@
 
 ## 业务文档
 
-- 总入口：`README.md`
-- 文档索引：`docs/README.md`
-- Figma 设计资产清单：`docs/FIGMA_DESIGN_INVENTORY.md`；页面实现应复用既有变量与组件，以清单中的正式画板为视觉基准，不按单页自由发挥。
-- MVP 演示与验收：`docs/DEMO_ACCEPTANCE.md`
-- 阶段交付归档：`docs/archive/2026-07-mvp-delivery/`
-- 分阶段总纲：`docs/银城员工端APP分阶段实施总纲.md`
-- AI 陪练二期推进（阶段一执行）：`docs/AI陪练二期开发推进计划.md`
-- 数字师傅产品定案（2026-07-08 学练问报/问题榜/学分）：`docs/20260708/数字师傅学练问报整合方案.md`
-- AI 陪练缺口修订：`docs/AI陪练功能优化与缺口分析(修订).md`
-- 后端 API 对接：`docs/API_INTEGRATION.md`
-- 对外会议版口径：`docs/AI人力资源系统项目规划方案与AI接口说明.md`
-- 业务需求：`docs/物业AI人力资源系统业务需求文档BRD.md`
-- 开发规格：`docs/物业AI人力资源系统开发规格TechSpec.md`
+- 总入口和完整索引是 `README.md`、`docs/README.md`；归档和原始纪要不作为施工入口。
+- 页面以 `docs/FIGMA_DESIGN_INVENTORY.md` 为基准；发布、API、验收分别以对应 Runbook、`docs/API_INTEGRATION.md`、`docs/DEMO_ACCEPTANCE.md` 为准。