# 物业AI人力资源系统 MVP 本地启动

## 当前仓库

- 后端：`backend`，来自 `dromara/RuoYi-Vue-Plus` 的 `5.X` 分支
- 管理端前端：`frontend`，来自 `CrazyLionCat/plus-ui` 的 `5.X` 分支
- 移动端前端：`mobile`，独立 Vue/Vite 工程

## 本地端口

- 管理端前端：`http://127.0.0.1:5173/`
- 移动端前端：`http://127.0.0.1:5174/h5/user`
- 后端：`http://127.0.0.1:8080/`
- MySQL：`127.0.0.1:13306`，数据库 `ry-vue`，账号 `root/root`
- Redis：`127.0.0.1:16379`，密码 `ruoyi123`
- MinIO API：`http://127.0.0.1:9000`，Console：`http://127.0.0.1:9001`，账号 `ruoyi / ruoyi123`，默认 bucket `ruoyi`
- Qdrant REST：`http://127.0.0.1:6333`，默认 collection `aihr_knowledge`
- 服务端资料导入根目录：`./.data/import`

Qdrant 默认本地无需配置；远端或自定义 collection 可用 `AIHR_QDRANT_URL`、`AIHR_QDRANT_COLLECTION`、`AIHR_QDRANT_API_KEY` 覆盖。服务端资料导入根目录可用 `AIHR_IMPORT_ROOT` 或 `-Daihr.import.root` 覆盖。组织人员同步可用 `AIHR_ORG_SYNC_BASE_URL` 指向外部开放平台 `/open/v1` 前缀，并配置 `AIHR_ORG_SYNC_ACCESS_TOKEN` 或 `AIHR_ORG_SYNC_CLIENT_ID`/`AIHR_ORG_SYNC_CLIENT_SECRET`；如外部要求 HMAC 签名，再配置 `AIHR_ORG_SYNC_SIGNING_SECRET`。移动端手机号登录的短信模板 ID、阿里云 AccessKey、Secret 和短信签名都通过环境变量注入；本地放根目录 `.env.local`，`scripts/dev-backend.sh` 会自动加载。

本地 `.env.local` 示例：

```bash
AIHR_SMS_LOGIN_TEMPLATE_ID=SMS_xxxxxx
ALIYUN_SMS_ACCESS_KEY_ID=xxx
ALIYUN_SMS_ACCESS_KEY_SECRET=xxx
ALIYUN_SMS_SIGN_NAME=物业AI助手
# 演示兜底：非空则不真发短信，验证码固定为该值；dev 默认 123456，prod profile 代码级强制失效
AIHR_SMS_DEV_FIXED_CODE=123456
AIHR_ORG_SYNC_BASE_URL=https://hr.example.com/open/v1
AIHR_ORG_SYNC_ACCESS_TOKEN=
AIHR_ORG_SYNC_CLIENT_ID=
AIHR_ORG_SYNC_CLIENT_SECRET=
AIHR_ORG_SYNC_SIGNING_SECRET=
# 试点成本闸门：超预算时改 false，chat/asr/tts 会走现有文本兜底
AIHR_AI_RUNTIME_ENABLED=true
AIHR_AI_CHAT_ENABLED=true
AIHR_AI_SPEECH_ENABLED=true
```

`application-dev.yml` 只保留占位和默认值，不提交真实短信密钥。dev 环境不配阿里云短信也能登录移动端：验证码固定 `123456`。

## 启动步骤

在项目根目录执行：

```bash
./scripts/dev.sh
```

首次启动或需要重建本地 `ry-vue` MVP 数据库时执行：

```bash
./scripts/dev.sh --reset
```

`--reset` 会删除并重建本地 MVP 数据库，只用于本地开发环境。

## 默认登录

- 租户：`000000`
- 管理员：`admin / admin123`
- 测试账号：`test / 666666`、`test1 / 666666`

## 品牌资源

- 页面标题：`物业AI人力资源系统`
- 侧栏 Logo：`frontend/src/assets/logo/logo.png`

## 已验证的基础链路

- MySQL、Redis 与 MinIO 容器健康检查通过
- Qdrant 容器随本地开发编排启动，供 SOP 知识库向量召回使用
- `ry_vue_5.X.sql`、`ry_job.sql`、`ry_workflow.sql` 已导入
- `aihr_knowledge_mysql8.sql`、`aihr_model_mysql8.sql` 已导入；本地库含住宅 SOP seed 片段与模型配置表
- `aihr_practice_mysql8.sql` 已导入；移动端员工训练记录落 `aihr_practice_session`，用于训练历史、主管待复盘列表和能力画像聚合
- `aihr_interview_result_mysql8.sql` 已纳入 reset 脚本；AI 面试评分完成后结果落 `aihr_interview_result`
- `aihr_candidate_material_mysql8.sql` 已纳入；候选人端补充资料文件写 `sys_oss`/MinIO，关系落 `aihr_candidate_material`
- `aihr_org_snapshot_mysql8.sql` 已纳入 reset 脚本；组织人员本地 seed（2 个住宅项目 22 人，项目经理/主管/一线三层）支撑演示，外部开放组织系统配置完成后用 `POST /api/aihr/org/sync` 拉取 `company/department/employee` 快照并覆盖本地 `aihr_org_snapshot`
- SOP 知识库支持 `.txt/.md/.markdown/.pdf/.doc/.docx/.xls/.xlsx/.ppt/.pptx` 上传到 MinIO 后解析入库，接口为 `POST /api/knowledge/doc/upload`，单文件上限 100MB；管理端上传请求单独放宽到 180s，PDF 解析/归类/向量化较慢时不要改全局 axios 超时
- 视频（`.mp4/.mov/.avi/.mkv/.webm/.m4v`，≤500MB、≤60 分钟）只走资料处理中心批量导入（异步队列）：ffmpeg 抽音轨分段调 asr 转写 + 抽关键帧调 vision 提取画面文字，合并后归类切片入库，片段带 `[mm:ss]` 时间戳；**依赖服务器安装 ffmpeg/ffprobe**（macOS `brew install ffmpeg`，Linux `apt install ffmpeg`）
- 服务端目录导入接口为 `POST /api/knowledge/doc/import-local-task`，只读取导入根目录下的相对目录，后台逐文件复用同一上传解析链路；`POST /api/knowledge/doc/import-tasks/{id}/cancel` 可取消运行中任务；`POST /api/knowledge/doc/import-local` 保留为同步调试接口。
- 启用 `aihr_model_config.category='vector'` 的模型配置后，上传会同步写入片段 embedding，并尽力 upsert 到 Qdrant；模型配置页可查看 Qdrant 维度、点数和片段向量数，并在维度不一致时重建索引；未配置或 Qdrant 不可用时只走 MySQL Fulltext/seed fallback，不影响检索。
- 后端 `ruoyi-admin` 已完成 Maven 打包并启动在 `8080`
- 前端依赖已安装，Vite 已启动在 `5173`
- 移动端依赖已安装，Vite 已启动在 `5174`
- 移动端手机号登录页已接 `/resource/sms/code` 与 `/auth/mobile/sms-login`；未配置真实 `ALIYUN_SMS_ACCESS_KEY_ID`、`ALIYUN_SMS_ACCESS_KEY_SECRET`、`ALIYUN_SMS_SIGN_NAME`、`AIHR_SMS_LOGIN_TEMPLATE_ID` 时不会发送阿里云短信；手机号不存在时会自动注册为 `app_user`
- 移动端员工端“开始训练”已复用 `/api/train/practice/start`、`/turn`、`/finish`；移动端请求需带登录返回的 `Authorization` 与 `clientid`；完成后主管端完训人数、“待复盘对练”计数、复盘列表、复盘详情、员工训练历史和能力画像会变化
- 移动端候选人端“开始面试/面试练习”已复用 `/api/recruit/interview/start`、`/answer`、`/finish`；“补充资料”需带移动端 `Authorization` 与 `clientid`，上传后写 `sys_oss` 和 `aihr_candidate_material`，管理端 `/recruit/interview` 可审核为 `已通过/已驳回`
- `/dev-api/auth/tenant/list` 与 `/dev-api/auth/code` 已通过前端代理返回 `200`
- `000000 / admin / admin123` 已通过真实加密登录接口返回 `access_token`

Qdrant 单独检查：

```bash
curl -fsS http://127.0.0.1:6333/
```

登录后可检查向量索引状态：

```bash
TOKEN=<登录后 access_token>
curl -fsS http://127.0.0.1:8080/api/knowledge/doc/vector-index-status -H "Authorization: Bearer $TOKEN"
```

## 线上移动端静态发布

线上 `peilian.njzhmj.top` 由 Caddy 服务，`/h5*` 映射到服务器 `/opt/wygj/www/h5`，并 fallback 到 `/h5/index.html`。只改移动端静态资源时无需重启后端。

```bash
VITE_BASE=/h5/ npm --prefix mobile run build
ssh YCWY 'ts=$(date +%Y%m%d%H%M%S); mkdir -p /opt/wygj/backups; cp -a /opt/wygj/www/h5 /opt/wygj/backups/h5-$ts; echo /opt/wygj/backups/h5-$ts'
rsync -az --delete mobile/dist/ YCWY:/opt/wygj/www/h5/
curl -k -s https://peilian.njzhmj.top/h5/supervisor | sed -n '1,20p'
```

## MVP 页面验证

登录后侧栏应只展示以下入口：

- 首页：`/index`
- AI面试：`/recruit/interview`
- 三角色对练：`/train/practice`
- 案例沉淀：`/knowledge/cases`
- SOP知识库：`/knowledge/sop`
- 资料处理：`/knowledge/processing`
- 系统设置-模型配置：`/system/model`

若依默认菜单如“系统管理 / 租户管理 / 系统监控 / 系统工具 / 测试菜单”在当前 MVP 阶段应保持隐藏。

## MVP 演示流验证

当前已跑通管理端五个本地演示流和移动端员工训练闭环：

- AI面试：进入 `/recruit/interview`，点击“生成题目” → 输入真实回答或“填满参考回答” → “完成评分”，应看到新增面试记录；配置 chat 模型时题目和评分都来自真实模型，未配置时使用本地 Rubric。
- 三角色对练：进入 `/train/practice`，点击“开始对练” → 完成两轮真实或参考回复 → “结束并评分”，应看到“已完成闭环”“导师改写”和新增对练记录。
- 案例沉淀：进入 `/knowledge/cases`，上传真实语音 → “AI 整理” → “送审” → “入库”，应看到“已完成闭环”和新增案例记录；上传必须先完成 ASR 转写。
- SOP知识库：进入 `/knowledge/sop`，可上传 txt/md/PDF/Word/Excel/PPT 文档入库；点击“检索” → “生成训练题”，应看到“已完成闭环”、命中数据库 SOP 原文片段和训练题；数据库不可用时页面回退 seed。
- 资料处理：进入 `/knowledge/processing`，应看到资料总量、解析任务表、处理链路、规则与风险；可用少量文件验证“批量导入/选择目录/服务端导入”。**批量导入走异步队列**：提交即返回，页面出现“本次批量上传”进度面板（排队/加工中/完成/失败 + 单条重试），后台 worker 并发 2 逐条解析入库；暂存目录默认 `./.data/staging`（`aihr.upload.staging` 覆盖）。服务端导入读取 `./.data/import` 下的相对目录，启动后台任务并在页面显示进度，运行中任务可点“取消”；目录导入的重试粒度是同目录重新导入，批量上传的重试粒度是单文件。
- 移动端员工训练：进入 `http://127.0.0.1:5174/h5/user`，手机号登录（dev 验证码固定 `123456`）。员工端首页为「师傅区(mentor.png 头像+气泡+按住说话/打字问+快捷chips)→今日安排→我的地图四色块→我的成长摘要」（视觉基准 `feedback/2026070423/design/`），底部 tab（今日/练/问/我）整页切换，滚动后师傅头像收缩为右下悬浮球；未实现入口进「建设中」整页。点底部“练”进入 `http://127.0.0.1:5174/h5/user/training`，首屏应先看到场景模拟、开始练习和最近练过，每日三题在下方；点“开始练习”进入 `http://127.0.0.1:5174/h5/user/practice`，两次“填入建议回复 / 提交本轮”后应看到评分、导师改写、训练历史和能力画像；切到主管端后完训人数与“待复盘对练”计数增加，并展示待复盘列表；点进单条可看评分、话术、导师改写，并可标记已复盘。训练页有“语音输入”和“播报”按钮，需启用 asr/tts 模型后生效；iOS/WebView 若无法直接访问麦克风，会切到“选择语音”并用系统录音/音频文件继续走 ASR，否则降级文本。快捷 chip 或「问」打开查 SOP 面板：文本/语音提问 → 轻概要(回答+要点+注意)+依据折叠；点「生成总结卡·约10秒」弹出信息图卡（四步法/异议/话术/提醒+听一遍/开始跟读），需 chat 模型；语音需 asr 模型。
- 移动端候选人：进入 `http://127.0.0.1:5174/h5/candidate`，手机号登录（dev 验证码固定 `123456`）→ “开始面试/面试练习”完成答题评分；“补充资料”选择 PDF/Word/图片后上传，应看到“已提交资料”、`OSS ...`、`待审核`。再进入管理端 `/recruit/interview` 底部“候选资料审核”点“通过/驳回”，候选人端刷新后应显示新状态。Codex 内置浏览器不支持本地文件选择时，用真实 HTTP multipart smoke 代替浏览器文件选择。
- 真 LLM 激活：在 `/system/model` 给供应商填 api_host/api_key 并启用 `category=chat` 模型后，三角色对练的客户回复与评分即为真实 LLM 生成；再启用 `category=asr/tts`（如硅基流动 SenseVoice/CosyVoice2）语音路径生效。未配置时全链路自动回退 seed。

演示前可先跑最小预检：

```bash
./scripts/demo-check.sh
```

完整演示脚本与录屏兜底见 [DEMO_ACCEPTANCE.md](DEMO_ACCEPTANCE.md)。