admin/prop-ai-hr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c47a9bb075edd13fd6831126bcdfe388d1b06535
prop-ai-hr/AGENTS.md
T
admin c47a9bb075 docs: sync mobile scenario home, tab navigation and sop panel 
员工端五情境区、底部 tab 整页互斥切换、死按钮 toast、查SOP面板同步
进 DEMO_ACCEPTANCE 演示口径、DEV_SETUP 验证步骤、README 概览;
AGENTS 补规则:不要把面板改回首页叠加渲染、未实现入口必须走 toast。
2026-07-04 14:56:32 +08:00

80 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AGENTS.md
## 项目定位
这是“物业AI人力资源系统”一期 MVP 版工程。目标是用 RuoYi-Vue-Plus + plus-ui 跑通本地账号登录、可演示业务路径和 AI HR 的最小英雄路径。
## 工程边界
- `backend/` 是 `dromara/RuoYi-Vue-Plus` 的 `5.X` 分支检出。
- `frontend/` 是 `CrazyLionCat/plus-ui` 的 `5.X` 分支检出，只承载管理端。
- `mobile/` 是独立移动端工程，承载员工端、候选人端、主管端；当前是 Vue/Vite H5，三端首页按 `docs/prototypes/*端-首页.png` 实现，后续确定小程序技术栈后再迁移到 uni-app/Taro。
- 本项目自己的本地编排放在根目录：`docker-compose.dev.yml`、`scripts/`；运行说明在 `docs/DEV_SETUP.md`。
- 除非确实要接业务模块，不要改上游框架默认配置；本地端口和开关优先放根目录脚本里覆盖。
## 本地运行
- MySQL：`127.0.0.1:13306`，库 `ry-vue`，账号 `root/root`。
- Redis：`127.0.0.1:16379`，密码 `ruoyi123`。
- MinIO：API `127.0.0.1:9000`，Console `127.0.0.1:9001`，账号 `ruoyi / ruoyi123`，bucket `ruoyi`。
- Qdrant：REST `127.0.0.1:6333`，默认 collection `aihr_knowledge`；可用 `AIHR_QDRANT_URL`、`AIHR_QDRANT_COLLECTION`、`AIHR_QDRANT_API_KEY` 覆盖。
- 资料导入根目录：默认 `./.data/import`，由 `scripts/dev-backend.sh` 传入 `aihr.import.root`；也可用 `AIHR_IMPORT_ROOT` 覆盖。
- 本地私密配置：根目录 `.env.local` 已被 `.gitignore` 忽略，`scripts/dev-backend.sh` 会自动加载；阿里云短信密钥只放这里或外部环境变量，不写入 `application-*.yml`。
- 后端：`./scripts/dev-backend.sh`，端口 `8080`。
- 管理端前端：`./scripts/dev-frontend.sh`，端口 `5173`。
- 移动端前端：`./scripts/dev-mobile.sh`，端口 `5174`。
- 重置数据：`./scripts/reset-dev-db.sh`，会删除并重建本地 `ry-vue`。
导入 SQL 必须带 `--default-character-set=utf8mb4`，否则中文昵称可能按错误字符集导入并触发字段长度问题。
## 验证口径
- 前端首页：`http://127.0.0.1:5173/`
- 移动端首页：`http://127.0.0.1:5174/h5/user`
- 租户接口：`http://127.0.0.1:5173/dev-api/auth/tenant/list`
- 验证码接口：`http://127.0.0.1:5173/dev-api/auth/code`
- 默认登录：租户 `000000`，管理员 `admin / admin123`。
## 品牌入口
- 页面标题在 `frontend/.env.development` 与 `frontend/.env.production`。
- 侧栏 logo 在 `frontend/src/assets/logo/logo.png`。
## MVP 管理端前端边界
- 首页：`frontend/src/views/index.vue`，路由 `/index`。
- AI 面试：`frontend/src/views/recruit/interview.vue`，路由 `/recruit/interview`。
- 三角色对练：`frontend/src/views/train/practice.vue`，路由 `/train/practice`。
- 案例沉淀：`frontend/src/views/knowledge/cases.vue`，路由 `/knowledge/cases`。
- SOP 知识库：`frontend/src/views/knowledge/sop.vue`，路由 `/knowledge/sop`。
- 资料处理：`frontend/src/views/knowledge/processing.vue`，路由 `/knowledge/processing`。
- 模型配置：`frontend/src/views/system/model/index.vue`，路由 `/system/model`。
- MVP 阶段侧栏只保留“首页 / AI面试 / 三角色对练 / 案例沉淀 / SOP知识库 / 资料处理 / 系统设置-模型配置”。过滤逻辑在 `frontend/src/layout/components/Sidebar/index.vue`，不要在未明确要求时恢复若依默认全量菜单。
- 移动端三端首页：`mobile/src/App.vue`，路由 `/h5/user`、`/h5/candidate`、`/h5/supervisor`，分别对应用户/员工端、候选人端、主管端；兼容 `/h5/employee`、`/h5/admin`，但移动端不要把主管端等同后台系统管理员。员工端首页是「学/复盘/用/报/成长」五个情境区；底部 tab 是整页互斥切换（isHomeTab + activeUserPanel/activeSupervisorPanel 条件），**不要把面板改回插入首页长页面的叠加渲染**；未实现入口必须走 `tap()` 的「建设中」toast，不留无反应按钮。查 SOP 全屏层（sopPanel）调 `/api/knowledge/search`（category='sop' 全库），关闭后回到进入前 tab。
- 移动端首页接口：`GET /api/aihr/mobile/home/{role}`，当前 `@SaIgnore` 公开只读 seed，用于 H5 首屏 API 优先 + 本地 fallback；后续确定小程序登录后再接移动端 token，不复用管理后台登录态。
- 移动端手机号登录：验证码发送走 `GET /resource/sms/code?phonenumber=...`，登录走 `POST /auth/mobile/sms-login`；短信发送复用 `sms.blends.config1` 阿里云配置。手机号不存在时自动注册 `app_user`，备注为“移动端短信自动注册”。模板 ID 用 `AIHR_SMS_LOGIN_TEMPLATE_ID`，AccessKey/Secret/签名用 `ALIYUN_SMS_ACCESS_KEY_ID`、`ALIYUN_SMS_ACCESS_KEY_SECRET`、`ALIYUN_SMS_SIGN_NAME`，本地放 `.env.local`。dev 兜底：`aihr.sms.dev-fixed-code` 非空则验证码固定（dev 默认 `123456`）、不真发短信；prod profile 代码级强制失效，不要移除该闸门。
- 移动端员工训练闭环：员工端首页“开始训练”复用 `POST /api/train/practice/start`、`/turn`、`/finish`，请求必须带移动端登录返回的 `Authorization` 与 `clientid`；`mode=mobile` 完成后写入 `aihr_practice_session`，并更新主管端首页完训率、“待复盘对练”、员工训练历史和能力画像。主管端复盘详情查 `GET /api/aihr/mobile/practice/reviews/{id}`，标记复盘用 `POST /api/aihr/mobile/practice/reviews/{id}/reviewed`。
- 移动端候选人闭环：候选人端“开始面试/面试练习”复用 `POST /api/recruit/interview/start`、`/answer`、`/finish`；“补充资料”走认证接口 `POST /api/aihr/mobile/candidate/materials`（multipart `file` + `candidateId/candidateName/materialType`）和 `GET /api/aihr/mobile/candidate/materials`，文件先写 `sys_oss`/MinIO，再写 `aihr_candidate_material` 状态 `待审核`。HR 审核复用管理端 `/recruit/interview` 页，接口为 `GET /api/aihr/hr/candidate/materials` 和 `POST /api/aihr/hr/candidate/materials/{id}/review`，状态只用 `待审核/已通过/已驳回`。上传接口不要放进 class-level `@SaIgnore` 的 `AihrMobileController`。
- 当前业务页已跑通可演示闭环；后端 API 对接先看 `docs/API_INTEGRATION.md`。三角色对练 `/turn`/`/finish` 已接真 LLM（`AihrPracticeLlmService`，评分 temperature=0 结构化输出），seed 剧本是剧情锚点与兜底，改对练逻辑时必须保留"未配置/失败回退 seed"的降级链，不要让演示依赖外部 API。
- 对练语音走 `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）。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。
- 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` 下的相对路径，逐文件复用上传解析链路；大批量资料优先走服务端导入任务，不走浏览器单次上传。
- seed service 阶段已完成；后续按 `docs/RUOYI_AI_INCREMENTAL_MIGRATION.md` 分片迁移 `ruoyi-ai` 的知识库、文档解析、RAG、chat 能力。
- 迁移时不要整包搬 `ruoyi-chat`；优先在 `ruoyi-aihr` 内吸收必要表、service、loader 和检索接口，并保留 seed fallback。
- 已落地的演示流不要退回静态壳：AI 面试、三角色对练、案例沉淀已是真模型优先（未配置/失败回退本地兜底），SOP 知识库、移动端三端首页保留 fallback——改造时降级链必须保留。
- 本项目 AI 表前缀用 `aihr_*`：知识库是 `aihr_knowledge_info/attach/fragment`，上传队列是 `aihr_knowledge_upload_item`，导入任务是 `aihr_knowledge_import_task`，模型配置是 `aihr_model_provider/config`，移动端训练记录是 `aihr_practice_session`，候选人补充资料是 `aihr_candidate_material`，组织人员快照是 `aihr_org_snapshot`（Demo 静态数据，生产走外部同步）。
## 业务文档
- 总入口：`README.md`
- 文档索引：`docs/README.md`
- MVP 范围和止损线：`docs/AI人力资源系统一期MVP版作战清单.md`
- 后端 API 对接：`docs/API_INTEGRATION.md`
- 业务需求：`docs/物业AI人力资源系统业务需求文档BRD.md`
- 开发规格：`docs/物业AI人力资源系统开发规格TechSpec.md`
Reference in New Issue View Git Blame Copy Permalink