# 帮道 MVP 本地启动

## 当前仓库

- 后端：`backend`，来自 `dromara/RuoYi-Vue-Plus` 的 `5.X` 分支
- 管理端前端：`frontend`，来自 `CrazyLionCat/plus-ui` 的 `5.X` 分支
- 用户侧前端：`mobile-uni`，uni-app Vue3 H5 + App-Plus 工程；旧 `mobile` 仅保留为 MVP 演示兜底

## 本地入口与依赖端口

- 管理端前端：`https://wygj-admin.localhost/`
- uni-app 用户侧：`https://wygj-mobile-uni.localhost/h5/`
- 后端：`https://wygj-api.localhost/`
- 固定端口仅用于显式 fallback：`PORTLESS=0 ./scripts/dev.sh` 时后端回退 `http://127.0.0.1:8080/`，旧移动端回退 `http://127.0.0.1:5174/h5/user`
- 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`

## portless 本地入口

本机开发测试优先用 portless 访问稳定域名，避免继续记固定端口：

- uni-app 用户侧：`https://wygj-mobile-uni.localhost/h5/`
- 管理端：`https://wygj-admin.localhost/`
- 后端 API：`https://wygj-api.localhost`

从根目录一次性启动本地依赖、后端、管理端和 uni-app 用户侧：

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

`./scripts/dev.sh` 默认通过 portless 启动后端、管理端和 `mobile-uni`，并由 Docker 启动 MySQL/Redis/MinIO/Qdrant。管理端 Vite 代理读取 `frontend/.env.development` 的 `VITE_APP_PROXY_TARGET=https://wygj-api.localhost`，`mobile-uni` Vite 代理默认指向 `https://wygj-api.localhost`，都不依赖固定 `8080`。如需单独启动后端，可执行：

```bash
portless run --name wygj-api ./scripts/dev-backend.sh
```

本地启动默认关闭管理端图形验证码；需要专门验证验证码链路时设置 `AIHR_DEV_CAPTCHA_ENABLED=true`。生产启动不使用该开发开关，验证码保持开启。

重复启动或切换分支时优先使用 `./scripts/dev.sh restart`，停止使用 `./scripts/dev.sh stop`。脚本会递归终止 portless 包装进程及其 Java/Vite 子进程，避免旧后端脱离后继续占用 MySQL 连接池；进程树回归可用 `bash scripts/tests/process-tree.test.sh` 验证。

也可以只让 portless 按根目录 `portless.json` 启动前端工程：

```bash
portless
```

旧 `mobile/` 只在显式 `PORTLESS=0 ./scripts/dev.sh` 时作为固定端口兜底启动；后端开发测试优先看 `wygj-api.localhost`，管理端开发测试优先看 `wygj-admin.localhost`，新用户侧开发测试优先看 `wygj-mobile-uni.localhost`。

原生 Android/iOS 资源使用 `npm --prefix mobile-uni run build:app` 构建；它不生成签名 APK/IPA，也不适用本文件的 H5 `rsync` 发布流程。自定义基座、协议链接、签名和真机门禁见 [MOBILE_APP_PACKAGING.md](MOBILE_APP_PACKAGING.md)。

Qdrant 默认本地无需配置；远端或自定义 collection 可用 `AIHR_QDRANT_URL`、`AIHR_QDRANT_COLLECTION`、`AIHR_QDRANT_API_KEY` 覆盖。服务端资料导入根目录可用 `AIHR_IMPORT_ROOT` 或 `-Daihr.import.root` 覆盖。组织人员同步可用 `AIHR_ORG_SYNC_BASE_URL` 指向外部开放平台 `/api/open/v1` 前缀，并配置 `AIHR_ORG_SYNC_ACCESS_TOKEN` 或 `AIHR_ORG_SYNC_CLIENT_ID`/`AIHR_ORG_SYNC_CLIENT_SECRET`；业务请求会用 client secret 生成 HMAC-SHA256 hex 签名。移动端手机号登录的短信模板 ID、阿里云 AccessKey、Secret 和短信签名都通过环境变量注入；本地放根目录 `.env.local`，`scripts/dev-backend.sh` 会自动加载。若开放平台凭证放在 `backend/.env`，启动脚本也会加载该文件，并把 `client_id`/`client_secret` 映射为组织同步实际读取的 `AIHR_ORG_SYNC_CLIENT_ID`/`AIHR_ORG_SYNC_CLIENT_SECRET`。

组织同步写入前先运行只读预检：`node scripts/verify-demo-questions.mjs --org-dry-run`。dry-run 不检查或变更本地快照表结构，也不写数据库；输出只包含人数、手机号覆盖、脱敏数、疑似乱码数和警告，不输出员工姓名。2026-07-15 当前开放平台数据已满足写入条件：3417 名员工中 3392 人可手机号映射，疑似乱码为 0；仍有 25 人手机号不可用，确认后可用 `allowPartialReplace=true` 覆盖写入。

正式试点预检必须指定当前批次租户和时间窗，例如：`AIHR_PILOT_TENANT_ID=000000 AIHR_PILOT_START_DATE=2026-07-07 AIHR_PILOT_END_DATE=2026-07-10 AIHR_PILOT_STRICT=true ./scripts/demo-check.sh`。脚本只接受安全租户编号和 `YYYY-MM-DD` 日期，只统计目标租户窗口内完成的训练、校准和 SOP 评审；人员先按唯一手机号映射到在职组织快照，完训口径为每人至少 10 次已完成对练。

服务端正式试点 CSV 也必须显式指定同一批次日期；当前管理端不展示个人训练或试点导出入口。可用受角色保护的真实 API 验证其日期拒绝、CSV 契约和正式身份范围：`node scripts/verify-demo-questions.mjs --pilot-export --start-date=2026-07-07 --end-date=2026-07-10`。

本地 `.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
AIHR_SMS_DEV_FIXED_CODE=123456
# prod 默认 false；试点期仅在明确接受固定码风险时与上一项同时开启
AIHR_SMS_PROD_FIXED_CODE_ENABLED=false
AIHR_ORG_SYNC_BASE_URL=https://wuye.meihe.cc/api/open/v1
AIHR_ORG_SYNC_ACCESS_TOKEN=
AIHR_ORG_SYNC_CLIENT_ID=
AIHR_ORG_SYNC_CLIENT_SECRET=
AIHR_ORG_SYNC_SIGNING_SECRET=
# 若放在 backend/.env，也可沿用开放平台字段名：
# client_id=dn_xxxxxx
# client_secret=dns_xxxxxx
# 试点成本闸门：超预算时改 false，chat/asr/tts/vision 会停止外发并走现有兜底
AIHR_AI_RUNTIME_ENABLED=true
AIHR_AI_CHAT_ENABLED=true
AIHR_AI_SPEECH_ENABLED=true
```

全网检索访问密钥使用数据库表 `aihr_web_ai_secret` 中自动生成的主密钥加密，不依赖环境变量，也不通过通用参数接口回显。数据库迁移、备份和恢复必须同时保留该表；丢失或修改主密钥后需要重新保存提供方密钥。全网检索提供方只接受公网 HTTPS 地址，且每次修改地址或密钥后都必须重新连接测试，测试成功后才能启用。

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

## 启动步骤

在项目根目录执行：

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

`./scripts/dev.sh` 默认通过 portless 暴露后端、管理端和当前 `mobile-uni` 用户侧。若要显式使用旧端口调试，可执行 `PORTLESS=0 ./scripts/dev.sh`，后端入口为 `http://127.0.0.1:8080/`，管理端入口为 `http://127.0.0.1:5173/`，旧移动端兜底入口为 `http://127.0.0.1:5174/h5/user`。

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

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

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

## 默认登录

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

## 品牌资源

- 页面标题：`帮道`
- 侧栏 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`。2026-07-15 生产已完成该配置和覆盖同步，线上快照为 3417 名员工。
- 组织同步生产默认关闭 `aihr.org-sync.store-display-fields`，不把外部姓名/部门写入或返回组织人员展示快照；开发环境显式打开该开关仅用于 Demo。项目范围、岗位和外部主体 ID仍用于权限与身份映射。
- 本地组织 seed 带演示手机号；从 `aihr_org_snapshot` 按角色查询测试账号，分别验证员工端岗位识别和主管端项目范围，不在文档保存具体号码
- SOP 知识库支持 `.txt/.md/.markdown/.pdf/.doc/.docx/.xls/.xlsx/.ppt/.pptx` 上传到 MinIO 后解析入库，接口为 `POST /api/knowledge/doc/upload`，单文件上限 100MB；管理端上传请求单独放宽到 180s，PDF 解析/归类/向量化较慢时不要改全局 axios 超时。
- 资料处理中心异步接口支持 `.zip` 和视频单文件 ≤500MB；生产 Spring/Undertow multipart 配置必须保持 `max-file-size=500MB`、`max-request-size=520MB`（源文件 `backend/ruoyi-admin/src/main/resources/application-prod.yml`，线上外置 `/opt/wygj/config/application-prod.yml`），修改后重启 `wygj-aihr.service`。非视频/ZIP 文件仍由队列限制为 100MB；ZIP 最多 1000 个子文件、解压总量 ≤2GB，不支持嵌套 ZIP。
- 视频（`.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 打包，并通过 portless 暴露为 `https://wygj-api.localhost/`
- AIHR 真跑测试必须显式关闭父 POM 的默认跳测：`mvn -f backend/pom.xml -pl ruoyi-modules/ruoyi-aihr -am -DskipTests=false test`；普通 `mvn ... test` 只适合编译/打包检查。
- 前端依赖已安装，Vite 已通过 portless 暴露为 `https://wygj-admin.localhost/`
- 当前用户侧由 `./scripts/dev.sh` 通过 portless 启动 `mobile-uni`，入口 `https://wygj-mobile-uni.localhost/h5/`；旧移动端兜底仅在 `PORTLESS=0` 调试时启动到 `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`，服务端会强制当前 APP 身份和 `mode=mobile`，完成后才会改变主管端完训人数、“待复盘对练”计数、复盘列表、复盘详情、员工训练历史和能力画像。管理端训练看板的同一路径只允许 `superadmin/hr_operator` 做服务端绑定的 `mode=preview` 运营预览；预览不会冒用员工身份，也不计入上述统计、复盘或试点。
- 移动端候选人端“开始面试/面试练习”已复用 `/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 https://wygj-api.localhost/api/knowledge/doc/vector-index-status -H "Authorization: Bearer $TOKEN"
```

## 线上管理端静态发布

线上根站由 Caddy 从服务器 `/opt/wygj/www` 提供；同一目录下的 `/h5` 是移动端静态资源。只改管理端静态资源时无需重启后端，但必须先备份整个目录，并且同步根目录时不能使用 `--delete`，以免删除移动端资源。

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

发布后以管理员真实会话回归受影响页面；如需核对指定资源，可比较本地构建文件和远端对应文件的 SHA-256。该流程不发布后端、不迁移数据库，也不覆盖 `/opt/wygj/www/h5`。

## 线上移动端静态发布

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

```bash
npm --prefix mobile-uni run build:h5
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-uni/dist/build/h5/ YCWY:/opt/wygj/www/h5/
curl -k -s https://peilian.njzhmj.top/h5/ | sed -n '1,20p'
```

发布前先运行只读产物检查，记录 commit、管理端/H5/后端 hash；它不会连接 SSH、同步文件或重启服务：

```bash
./scripts/release-preflight.sh
RELEASE_REMOTE_URL=https://peilian.njzhmj.top ./scripts/release-preflight.sh
# 发布后核验线上主资源是否与当前本地产物一致
RELEASE_REMOTE_URL=https://peilian.njzhmj.top RELEASE_VERIFY_REMOTE_MATCH=true ./scripts/release-preflight.sh
# 同时通过 SSH 校验线上后端 jar；默认使用本机 SSH alias YCWY；比较 ruoyi-aihr 模块内容，避免 ZIP 打包时间戳造成误报
RELEASE_REMOTE_URL=https://peilian.njzhmj.top RELEASE_VERIFY_REMOTE_MATCH=true RELEASE_VERIFY_REMOTE_BACKEND=true ./scripts/release-preflight.sh
# 发布后同时核对线上静态资源、后端包和必需表（schema 检查为只读）
RELEASE_REMOTE_URL=https://peilian.njzhmj.top RELEASE_VERIFY_REMOTE_MATCH=true RELEASE_VERIFY_REMOTE_BACKEND=true RELEASE_VERIFY_REMOTE_SCHEMA=true ./scripts/release-preflight.sh
```

`RELEASE_VERIFY_REMOTE_BACKEND=true` 必须与 `RELEASE_VERIFY_REMOTE_MATCH=true` 同时使用；预检会同时打印整包 jar SHA-256 和 `ruoyi-aihr` 模块内容 SHA-256，实际匹配以模块内容 hash 为准。远端后端默认核对 `/opt/wygj/app/ruoyi-admin.jar`，如发布路径不同可通过 `RELEASE_REMOTE_BACKEND_PATH` 覆盖；路径必须是安全的绝对路径。开启远端后端或 schema 核验时，预检还会只读检查 `wygj-aihr.service` 及其 `EnvironmentFile` 的有效配置，`AIHR_PRACTICE_RUNTIME_SCHEMA_BOOTSTRAP` 必须为 `false` 或未设置；无法读取引用的环境文件会失败关闭，而不会把本机环境变量当作线上证据。

带 `RELEASE_REMOTE_URL` 时，预检同时校验租户接口 JSON 的业务 `code=200`；HTTP 200 但业务返回 401/405 会判定失败。

发布时必须保留 preflight 输出、远端备份目录和发布后浏览器回归结果；回滚优先使用对应备份目录恢复，再重启后端服务，不能直接覆盖当前线上目录而不留证据。

## 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 逐条解析入库；支持多文件和 ZIP，暂存目录默认 `./.data/staging`（`aihr.upload.staging` 覆盖）。
- uni-app 员工端：进入 `https://wygj-mobile-uni.localhost/h5/#/pages/user/today/index`，手机号登录（dev 验证码固定 `123456`）。今日页进入问师傅、练习、案例素材和个人页；练习页应能完成开始练习、提交回应、结束评分、每日三题提交，个人页同步训练历史和成长证据包。每日三题正式按组织快照 `hire_date` 判断入职三个月窗口；本地 Demo 若快照尚无该字段，仅由 `dev/local` profile 且 `application-dev.yml` 的 `aihr.practice.allow-legacy-daily-drill-fallback=true` 启用训练次数回退，生产 profile 即使误传环境变量也强制关闭。
- 工作助手确认式统一采集：`/h5/#/pages/user/sop/index` 一级入口只保留“工作助手 / 查全网”，既有文字、ASR、媒体、数据工具和 30 分钟/最近 6 轮短会话链保持不变；显式“记一下/帮我记/保存一下”返回 `DRAFT` 确认卡，位置缺失只作可选提示。确认后写 `aihr_assistant_capture`：`PRIVATE/NOT_REQUIRED` 仅本人可见，`COMPANY/PENDING` 只表示待流转；旧项目记录继续使用 `aihr_service_memory/version`。`/h5/#/pages/user/assistant/memories` 展示待确认候选和本人已确认记录；不依赖新的 Qdrant collection，提醒默认关闭。
- 上一条只验证当前已部署的确认式采集；项目名称下拉、项目化会话、原始来源绑定、今日工作成果和主管按日汇总仍属[后续迭代](工作助手与今日工作成果迭代计划-20260721.md)，不得在本地回归结果中写成已完成。
- 移动端登录后若组织快照接口返回 `401/403`，只降级为手动岗位确认，不应清除手机号登录态；岗位确认页仍需允许员工选择“生活顾问”后继续进入业务页。
- uni-app 主管端：进入 `https://wygj-mobile-uni.localhost/h5/#/pages/supervisor/index/index`，应看到团队概览、团队画像、团队预警、指派专项、待复盘和复盘详情；从团队画像派专项后，最近专项应立即回读新记录。
- uni-app 候选人端：进入 `https://wygj-mobile-uni.localhost/h5/#/pages/candidate/index/index`，手机号登录（dev 验证码固定 `123456`）→ “开始面试/面试练习”完成答题评分；“补充资料”选择 PDF/Word/图片后上传，应看到资料状态。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
bash scripts/tests/aihr-schema-migrations.test.sh
node --test mobile-uni/tests/personal-assistant.test.mjs
API_BASE=https://wygj-api.localhost ./scripts/personal-assistant-smoke.sh
# 登录后只读核验：TOKEN=<mobile-access-token> API_BASE=https://wygj-api.localhost ./scripts/personal-assistant-smoke.sh
```

工作助手记忆本地人工回归至少覆盖：登录后说“帮我记一下三栋 3203 需要保洁服务”，即使缺少单元也应看到 `DRAFT` 卡；“暂不保存”不产生正式记录；“仅自己保存”后只由本人召回；“提交公司处理”只显示 `PENDING`，不得显示已送达；同一会话重复描述更新原卡，“另外记一条”才新建；双击确认不得重复写入。再用另一账号验证个人记录不可见，并验证按精确房号查询不会混入同楼栋其他房号。

完整演示脚本与录屏兜底见 [DEMO_ACCEPTANCE.md](DEMO_ACCEPTANCE.md)。
# 个人 AI 助理本地验证

个人知识使用独立 Qdrant collection，默认 `aihr_personal_knowledge`，payload 强制包含 `tenant_id`、`owner_user_id`、`item_id` 与 `captured_at`。对象存储固定使用 `personal-minio` 配置和私有 bucket `ruoyi-personal`，不修改企业资料使用的默认 `minio/ruoyi`。MySQL 表和专用 OSS 配置由 `backend/script/sql/aihr_personal_knowledge_mysql8.sql` 初始化；旧开发库先运行 `COMPOSE_PROJECT_NAME=wygj ./scripts/reset-dev-db.sh`。

企业范围问答另外依赖 `aihr_org_snapshot` 与 `aihr_knowledge_acl`。reset 会给企业 SOP `1001/1002/1003` 写入“一线生活顾问”POSITION ACL；本地物业管家 seed 账号由服务端按固定别名映射到生活顾问后获得 allowlist。普通新注册手机号没有组织快照，企业范围必须返回无权限。不要用手工手机号、客户端岗位参数或 TENANT ACL 绕过该默认拒绝；开放组织系统只负责刷新阶段二快照，北森实时组织/任职仍属阶段三。

空间与处理配额通过 `aihr.personal.*` 配置覆盖，包括空间字节配额、资料数量、单文件大小、抓取字节/超时、worker 与 cleanup 批量大小。不要把个人 collection 改回企业 `aihr_knowledge`。

启动依赖与后端后运行真实隔离 smoke：

```bash
./scripts/dev.sh
./scripts/personal-assistant-smoke.sh
```

脚本每次生成唯一 smoke 手机号与 run marker，通过开发短信登录创建 A/B，并真实采集 TEXT、由 macOS `cupsfilter` 生成的可检索 PDF、公开网页 `https://example.com/`。它会验证三类资料 READY/检索/引用、owner 隔离、私有 OSS 匿名 403、SSRF、幂等删除，以及 MySQL/MinIO/Qdrant 零残留；退出时按本次临时用户清理其全部个人会话/消息，并按 user/item/OSS/job ID 与 run marker 回查清理。公开网页可用 `AIHR_PERSONAL_SMOKE_PUBLIC_URL` 覆盖，页面检索词可用 `AIHR_PERSONAL_SMOKE_PUBLIC_QUERY` 覆盖；客户端只检查 URL 语法，不预先跟随重定向，DNS、逐跳 SSRF 校验和最终 READY 状态以后端为准，公网不可达会明确失败。需要为重定向目标做精确断言时可设置 `AIHR_PERSONAL_SMOKE_EXPECTED_PUBLIC_URL`。脚本不会输出 token。`./scripts/personal-assistant-smoke.sh --signal-self-test` 可单独验证 INT/TERM 分别返回 130/143。

个人网页采集默认从 `/etc/resolv.conf` 读取最多 4 个 DNS resolver，并使用有 socket deadline 的原生 UDP 查询；如运行环境的 resolver 配置不可用，可通过 `AIHR_PERSONAL_DNS_SERVERS=223.5.5.5,1.1.1.1` 显式覆盖。配置项只接受数字 IP，不会递归解析 DNS 服务器名称。