feat: complete aihr mvp mobile workflow

2026-07-03 16:43:37 +08:00
parent 0126b0c661
commit f869d66c90
46 changed files with 5879 additions and 219 deletions
@@ -1,13 +1,14 @@
 # 物业行业 AI 人力资源系统 · 开发规格(Tech Spec)

-> 版本:v1.3 ｜ 日期:2026-07-02
+> 版本:v1.4 ｜ 日期:2026-07-03
 > 定位:**开发层唯一依据**。回答"怎么建"——工程结构、数据表、API 契约、Prompt 规格、集成适配。
 > v1.1 变更:数据模型对齐《手册》卷1 第9章 HR 主干,补 3 张 backbone 表(职位职责/雇员绩效/雇用终止),新增附录 D 对照表。
 > v1.2 变更:第 6 章按 Codex 设计评审重写——状态机补异常/终止态、COACH_CHECK 工程化、评分引擎分层(P0 单 LLM / P1 融合)、澄清"单场对练评分 vs 跨期能力画像"两套评分、Prompt 加固 + RAG 硬约束、新增 6.5 P0/P1 切分。
 > v1.3 变更:Qdrant 作为一期向量索引层落地;SOP 知识库检索升级为 MySQL Fulltext + Qdrant RRF 融合,MySQL/MinIO 仍是事实源。
-> 配套:需求见[《物业AI人力资源系统业务需求文档BRD》](物业AI人力资源系统业务需求文档BRD.md);执行计划见[《AI人力资源系统一期Demo作战清单》](AI人力资源系统一期Demo作战清单.md)。
-> **优先级图例**:`P0`=2026-07-05 Demo 必需 · `P1`=一期必需 · `P2`=二期/推迟。
-> 决策基线:若依基座 / 集中式前后端分离 / 本地登录 / 公有大模型API / 一期RAG / 组织人员外部同步(Demo用快照) / 数据范围以项目为主体。
+> v1.4 变更:移动端拆为独立 `mobile/` Vue/Vite Web/H5 工程,承载员工端、候选人端、主管端;后台管理端继续在 `frontend/`。
+> 配套:需求见[《物业AI人力资源系统业务需求文档BRD》](物业AI人力资源系统业务需求文档BRD.md);执行计划见[《AI人力资源系统一期MVP版作战清单》](AI人力资源系统一期MVP版作战清单.md)。
+> **优先级图例**:`P0`=2026-07-05 MVP 演示必需 · `P1`=一期必需 · `P2`=二期/推迟。
+> 决策基线:若依基座 / 集中式前后端分离 / 本地登录 / 公有大模型API / 一期RAG / 组织人员外部同步(MVP 用快照) / 数据范围以项目为主体。

 ---

@@ -18,7 +19,8 @@
 | 层 | 选型 |
 |---|---|
 | 后端 | Java + Spring Boot 4(若依 RuoYi 后端) |
-| 前端 | Vue(若依前端,前后端分离) |
+| 管理端前端 | Vue + plus-ui(若依前端,前后端分离) |
+| 移动端前端 | 独立 `mobile/` Vue/Vite Web/H5;小程序技术栈后续再定 |
 | 数据库 | MySQL(主数据/事务)+ MinIO(原始文件)+ Qdrant(向量索引) |
 | 检索 | MySQL Fulltext + Qdrant 混合 RAG(一期);知识图谱 Neo4j(P2) |
 | 大模型 | 公有大模型 API(对话/出题/评分/案例整理) |
@@ -31,19 +33,18 @@
 backend/
  ruoyi-admin/            # 启动入口
  ruoyi-system/           # 复用:用户/角色/菜单/数据权限
-  hr-recruit/             # 选:招聘面试
-  hr-onboard/             # 用:上岗/SOP/培训
-  hr-train/               # 育:对练/每日一练/训练营/错题/师徒
-  hr-competency/          # 留:能力评估/认证/Rubric/激励
-  hr-knowledge/           # 知识库/案例库/RAG
-  hr-ai/                  # AI 适配层:大模型/ASR/TTS/Prompt 模板/评分引擎
-  hr-sync/                # 组织人员同步适配层
+  ruoyi-modules/ruoyi-aihr/ # AI HR 自有业务 API、seed fallback、知识库/RAG/模型配置
+  script/sql/aihr_knowledge_mysql8.sql
+  script/sql/aihr_model_mysql8.sql
 frontend/
-  src/views/{recruit,onboard,train,competency,knowledge,ai-practice,dashboard,admin}
+  src/views/{index,recruit,train,knowledge,system/model} # 管理端 MVP 页面
+mobile/
+  src/App.vue             # 员工端/候选人端/主管端 H5 首页
 ```

- 复用若依 `ruoyi-system` 的用户/角色/菜单/数据权限;业务模块按选用育留 + 支撑拆分。
- AI 能力集中在 `hr-ai`,对上层暴露统一接口(对话/评分/转写/生成),便于切换厂商与兜底。
+- 复用若依 `ruoyi-system` 的用户/角色/菜单/数据权限;自有后端 API 集中在 `ruoyi-aihr`,不要塞回上游 `ruoyi-demo`。
+- 管理端 `frontend/` 不承载 `/h5/*`;移动端通过 `5174` 独立启动,路由为 `/h5/user`、`/h5/candidate`、`/h5/supervisor`。
+- AI 能力先在 `ruoyi-aihr` 内提供统一接口(对话/评分/转写/生成),便于切换厂商与兜底;后续可按模块拆分。
 - 可借助已有的 "codex 若依组件生成 skill" 批量生成 CRUD 骨架。

 ---
@@ -147,7 +148,7 @@ frontend/
 | `aihr_knowledge_fragment`(知识片段) | id, knowledge_id, doc_id, idx, content, embedding_json, embedding_model, embedding_time, FULLTEXT(content) | P0 已落，txt/md/PDF/Word/Excel/PPT 可解析入库，可写 embedding；Qdrant 只存向量索引和最小 payload |
 | `case`(案例主表,脱敏) | id, title, raw_audio_url, transcript, ai_summary, curated(是否入选), project_ext_org_id, status | P0 |
 | `case_tag`(多维标签) | id, case_id, dim(业务类型/紧急/业主画像/情绪/渠道), value | P1 |
-| `case_video`(案例视频/样片) | id, case_id, video_url, is_sample | P1(Demo样片) |
+| `case_video`(案例视频/样片) | id, case_id, video_url, is_sample | P1(MVP样片) |

 ### 3.8 M8/M9 治理 · 版本 · 集成日志

@@ -171,13 +172,14 @@ frontend/
 | `/recruit/interview` | **AI 面试(英雄路径A:出题→作答→打分)** | P0跑通 |
 | `/recruit/candidates` | 候选人列表 | P1 |
 | `/train/practice` | **三角色对练(英雄路径核心)** | P0跑通 |
+| `/h5/user` | 员工端首页，手机号登录后可“开始训练”并同步主管待复盘计数 | P0跑通 |
 | `/train/daily` | 每日一练 | P1 |
 | `/train/camp` | 专项训练营 | P1 |
 | `/train/mistakes` | 错题本 | P1 |
 | `/knowledge/sop` | SOP 库(住宅类检索→引用→训练题) | P0跑通 |
 | `/knowledge/cases` | **案例库(英雄路径B:语音上传→整理)** | P0跑通 |
 | `/knowledge/processing` | 资料处理(解析状态、处理链路、浏览器/服务端导入) | P1已提前落地 |
-| `/system/model` | 模型配置(供应商 Key/Base URL/模型启停/测试) | P1已提前落地 |
+| `/system/model` | 模型配置(供应商 Key/Base URL/模型启停/测试、向量库状态与重建) | P1已提前落地 |
 | `/competency/radar` | 能力雷达图 | P1 |
 | `/competency/cert` | 认证/激励 | P1 |
 | `/onboard/tasks` | 上岗培训任务 | P1 |
@@ -188,7 +190,7 @@ frontend/
 ## 5. API 契约

 > 统一响应信封:`{ code, msg, data }`(若依风格)。以下英雄路径详写,其余按 CRUD 惯例。
-> 当前本地 Demo 先用 API + fallback 跑通 `/recruit/interview`、`/train/practice`、`/knowledge/cases`、`/knowledge/sop` 页面流;SOP 知识库已接 `aihr_knowledge_fragment` MySQL Fulltext 检索、Qdrant 向量召回、txt/md/PDF/Word/Excel/PPT 上传解析和 embedding 写入。
+> 当前本地 MVP 先用 API + fallback 跑通 `/recruit/interview`、`/train/practice`、`/knowledge/cases`、`/knowledge/sop` 页面流;SOP 知识库已接 `aihr_knowledge_fragment` MySQL Fulltext 检索、Qdrant 向量召回、txt/md/PDF/Word/Excel/PPT 上传解析和 embedding 写入。
 > API 对接顺序见 `docs/API_INTEGRATION.md`;面试、对练、案例仍以 seed service 为主，SOP/模型配置已建最小表。

 ### 5.1 英雄路径 A:AI 面试(P0)
@@ -223,6 +225,8 @@ POST /api/train/practice/finish
  resp: { score:{ compliance, emotion, communication, marketing }, mentorRewrite, aiComment, trustCurve }  // 考官评分
 ```

+移动端员工训练闭环复用同一组三角色对练接口。员工端请求必须带手机号登录返回的 `Authorization` 与 `clientid`，`start` 传 `mode=mobile`；`finish` 后写入 `aihr_practice_session`，并刷新 `/api/aihr/mobile/home/supervisor` 的完训人数与“待复盘对练”计数。员工端训练历史查 `GET /api/aihr/mobile/practice/history`，主管端复盘列表查 `GET /api/aihr/mobile/practice/reviews`，复盘详情查 `GET /api/aihr/mobile/practice/reviews/{id}`，标记已复盘用 `POST /api/aihr/mobile/practice/reviews/{id}/reviewed`，能力画像查 `GET /api/aihr/mobile/profile`。当前只落 session 汇总表，并用 `dialogue_json` 保存本场话术；不拆 `practice_turn/practice_score`，需要逐轮复盘明细、人工点评留痕或多次复盘记录时再拆表。
+
 ### 5.3 英雄路径 B:案例语音上传→整理(P0)

 ```
@@ -242,12 +246,13 @@ POST /api/ai/score       req:{ rubricId, dialogue }        resp:{ dimensions, co

 ### 5.5 支撑接口

- 同步:`POST /api/sync/pull`(拉取组织人员,Demo 可读快照文件)
+- 同步:`POST /api/sync/pull`(拉取组织人员,MVP 可读快照文件)
 - 知识检索(RAG):`POST /api/knowledge/search` → `{ queryText, category, answer, reference, docs[], snippets[], training[], records[] }`
 - 知识上传解析:`POST /api/knowledge/doc/upload` → `multipart/form-data { file, category }`，支持 `.txt/.md/.markdown/.pdf/.doc/.docx/.xls/.xlsx/.ppt/.pptx`、100MB 内；先落 `sys_oss` 并绑定 `aihr_knowledge_attach.oss_id`，返回 `{ docId, ossId, fileName, category, fragments, snippets[] }`
- 服务端目录导入:`POST /api/knowledge/doc/import-local-task` → `{ directory, category, limit }`，只允许读取 `AIHR_IMPORT_ROOT` / `aihr.import.root` 下的相对目录，写入后台导入任务并逐文件复用上传解析链路；`GET /api/knowledge/doc/import-tasks` 返回最近任务进度；`POST /api/knowledge/doc/import-local` 保留同步调试。
- 资料处理状态:`GET /api/knowledge/processing/overview` → 聚合附件状态、片段数、向量化状态、分类、处理链路和最近事件。
+- 服务端目录导入:`POST /api/knowledge/doc/import-local-task` → `{ directory, category, limit }`，只允许读取 `AIHR_IMPORT_ROOT` / `aihr.import.root` 下的相对目录，写入后台导入任务并逐文件复用上传解析链路；`GET /api/knowledge/doc/import-tasks` 返回任务进度列表；`POST /api/knowledge/doc/import-local` 保留同步调试。
+- 资料处理状态:`GET /api/knowledge/processing/overview` → 聚合附件状态、片段数、向量化状态、分类、处理链路和事件列表。
 - 片段向量化:同一上传接口在 `category=vector` 模型配置可用时调用 OpenAI-compatible `/embeddings`，写入 `embedding_json/embedding_model/embedding_time`，并尽力 upsert 到 Qdrant；未配置或 Qdrant 不可用不阻塞上传。
+- 向量库状态与重建:`GET /api/knowledge/doc/vector-index-status` 返回当前 vector 模型维度、Qdrant collection 维度、点数和片段向量数；`POST /api/knowledge/doc/rebuild-vector-index` 清空旧 embedding、删除 collection，并按当前 vector 模型重建。外部 embedding 成功但 Qdrant 维度不一致时不降级为本地 hash。
 - 混合检索:`POST /api/knowledge/search` 先查 MySQL Fulltext，同时在 vector 模型和 Qdrant 可用时生成 query embedding 走 Qdrant，最后按 RRF 融合并回 MySQL hydrate 片段；Qdrant 不存正文事实源。
 - Rubric 配置:`/api/competency/rubric/**` CRUD

@@ -306,7 +311,7 @@ INIT → WAITING_INPUT → PROCESSING → WAITING_INPUT(loop) → FINISHED
 - **单场对练评分(每场一次)**:4 维 —— 合规与完整度、情感应变力、沟通有效性、营销敏感性;外加**导师润色版**(不是评分维度,是话术重写对比)。
 - **能力画像(跨期加权,BRD 4.5)**:5 维加权 —— 任务完成度40% / 话术规范性25% / 情绪管理20% / 响应时效10% / 增值转化5%。**由多场对练评分聚合而来,不是同一层。**

-**P0(2026-07-05 Demo):单 LLM 考官一次性出结构化分**
+**P0(2026-07-05 MVP 演示):单 LLM 考官一次性出结构化分**
 - 输入 `dialogue + rubric + sop_points + persona`,输出固定 JSON;**不做多模型融合**。
 - **防漂移**:固定模型 + `temperature=0` + 固定 `prompt_version`;首次评分后**缓存 `practice_score`,刷新不重算**;分数用**档位锚点 60/75/90** 减少小数漂移。
 - **可验收的可解释**:JSON 必带证据 —— `evidence_turn_ids`、`hit_sop_point_ids`、`missed_sop_point_ids`、`rewrite_before/after`;无证据的理由不展示。
@@ -315,7 +320,7 @@ INIT → WAITING_INPUT → PROCESSING → WAITING_INPUT(loop) → FINISHED
 **P1(一期):再拆多模型融合**
 - SOP 关键点覆盖检测 + 语义相似 + 情感/语音特征融合;Rubric 后台可配置 + 版本 + 启停;一致率校准集 + 人工评审流程。

-**一致率验收口径**:`≥70%` 指**分档一致**(非原始分一致),档位建议 `<60 / 60–74 / 75–89 / ≥90`,用 ≥20 段样本对人工基准评估——**是一期目标,不是 2026-07-05 Demo 目标**;2026-07-05 只验端到端 + 结构化输出。
+**一致率验收口径**:`≥70%` 指**分档一致**(非原始分一致),档位建议 `<60 / 60–74 / 75–89 / ≥90`,用 ≥20 段样本对人工基准评估——**是一期目标,不是 2026-07-05 MVP 演示目标**;2026-07-05 只验端到端 + 结构化输出。

 ### 6.4 Prompt 规格(实际入 `hr-ai` 模板库,均需后端兜底)

@@ -328,17 +333,17 @@ INIT → WAITING_INPUT → PROCESSING → WAITING_INPUT(loop) → FINISHED

 ### 6.5 三角色 P0 / P1 最小切分

- **P0(2026-07-05 Demo 必须)**:1 场景 × 1 人设 × 1 套 SOP × 1 套 rubric;**文本端到端先跑通**,语音作为外层 ASR/TTS,失败降级文本;`/start /turn /finish` 三接口闭环;每轮轻量 checker + 客户回应;`/finish` 单 LLM 出结构化分;固定 max_turns + 手动结束 + 评分缓存展示。
+- **P0(2026-07-05 MVP 演示必须)**:1 场景 × 1 人设 × 1 套 SOP × 1 套 rubric;**文本端到端先跑通**,语音作为外层 ASR/TTS,失败降级文本;`/start /turn /finish` 三接口闭环;每轮轻量 checker + 客户回应;`/finish` 单 LLM 出结构化分;固定 max_turns + 手动结束 + 评分缓存展示。
 - **P1(一期)**:Rubric 后台配置与版本;SOP 覆盖/语义/情绪融合;一致率校准集 + 人工评审;多场景/多 persona/动态难度/错题本/能力画像沉淀;LLM 调用日志/成本/prompt 版本/失败重试。

 ---

 ## 7. 集成适配层

-| 集成 | 接口/做法 | Demo 兜底 | 优先级 |
+| 集成 | 接口/做法 | MVP 兜底 | 优先级 |
 |---|---|---|---|
 | 组织人员同步 | `hr-sync` 拉取采购系统 API → 写 `sync_*` | 读静态快照文件 | P0 |
-| 登录/SSO | 一期本地账号(若依) | — | P0(SSO=P2) |
+| 登录/SSO | 管理端用若依本地账号；移动端用手机号短信登录，验证码通过后自动注册 `app_user` | SSO 不做 | P0(SSO=P2) |
 | 权限映射 | `role_perm_mapping` 规则引擎 | 手工配置 | P0 |
 | 大模型 | `hr-ai/chat` 封装公有 API | — | P0 |
 | ASR/TTS | `hr-ai/asr,tts` 封装第三方(方言) | 1 家 1 条路径 | P0 |
@@ -349,7 +354,7 @@ INIT → WAITING_INPUT → PROCESSING → WAITING_INPUT(loop) → FINISHED

 ## 8. 权限与数据范围

- 认证:若依本地账号(一期);SSO 预留 `hr-sync` 对接点(P2)。
+- 认证:管理端使用若依本地账号；移动端使用短信验证码登录，不存在的手机号自动注册 `app_user`；SSO 预留 `hr-sync` 对接点(P2)。
 - 授权:`role_perm_mapping` 把外部岗位/组织映射到本地 `role_code`。
 - **数据范围以项目为主体**:所有业务查询套若依数据权限,按 `party_role.scope_project_ext_org_id` 过滤;主管只见本项目数据。

@@ -366,7 +371,7 @@ INIT → WAITING_INPUT → PROCESSING → WAITING_INPUT(loop) → FINISHED

 ## 10. 实现优先级与里程碑(对齐 MVP 切割线 / 施工单)

-### 10.1 P0(2026-07-05 Demo 必需)
+### 10.1 P0(2026-07-05 MVP 演示必需)

 - 工程骨架 + 本地登录 + 数据权限(M1/M2)
 - AI 适配层:chat / asr / tts / score(M9)
@@ -382,7 +387,7 @@ INIT → WAITING_INPUT → PROCESSING → WAITING_INPUT(loop) → FINISHED

 ### 10.3 P2(二期)

- 知识图谱(Neo4j)、独立 APP、玉溪 Agent 化、企微/钉钉深度集成、SSO、实时同步、多项目类型(公建/景区)。
+- 知识图谱(Neo4j)、原生 APP、玉溪 Agent 化、企微/钉钉深度集成、SSO、实时同步、多项目类型(公建/景区)。

 ---