prop-ai-hr/AGENTS.md

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。

发布口径

• 线上移动端 H5：https://peilian.njzhmj.top/h5/user，Caddy 服务 /opt/wygj/www/h5。
• 只发布移动端静态资源时，用 VITE_BASE=/h5/ npm --prefix mobile run build 后备份远端 /opt/wygj/www/h5，再 rsync -az --delete mobile/dist/ YCWY:/opt/wygj/www/h5/；前端静态修复不需要重启后端。

品牌入口

• 页面标题在 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，但移动端不要把主管端等同后台系统管理员。员工端首页是「师傅区→今日安排→我的地图→我的成长摘要」（视觉基准 docs/feedback/2026070423/design/ + REVIEW.md 修正项，修正项优先于图面）；师傅四状态(idle/listening/thinking/speaking)只从 sopRecording/sopLoading/sopSpeaking 推导，不要新造状态源；员工端底部 tab 钉死「今日/练/问/我」（visibleTabs 强制,不跟随后端 home 旧文案），整页互斥切换（isHomeTab + activeUserPanel/activeSupervisorPanel 条件），不要把面板改回插入首页长页面的叠加渲染；未实现入口进「建设中」整页（openBuildingPage），不留无反应按钮。查 SOP 全屏层（sopPanel）调 /api/knowledge/search（category='sop' 全库），关闭后回到进入前 tab；「生成总结卡」按需调 /api/knowledge/summary-card，失败明确报错可重试,不兜假数据。
• 移动端首页接口：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）。移动端 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。
• 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