# HANDOFF —— 交给下一个 session 的现场交接 > 更新于 2026-10-31 03:35。**开工先读这一页**,再读 `CLAUDE.md`(硬约定), > 最后看 `.workbuddy/memory/` 最近一天的日志(踩过的坑)。 > 无人值守时不要问用户,选最保守可行的方案继续,并把决策写回本文件。 --- ## 0. ⚠️ 修正上一版口径(很重要) 上一版说「跑 pnpm 必须 `dangerouslyDisableSandbox`」。**这条不完整**:真正拦住 fs 的是 `NODE_OPTIONS` 里注入的 `node-language-shim.cjs`(brokered-fs),退沙箱它仍在,末尾报 `CODEBUDDY_BROKER_OUTCOME_UNKNOWN — Broker request timed out`。**正确做法见 §2,用 `env -u NODE_OPTIONS pnpm ...`** —— 实测 2169 包 46.5s 装完。 --- ## 1. 一句话现状(2026-10-31 03:30 夜班更新) **✅ 前端已经在浏览器里真跑起来了,用户管理页可渲染、列表/新增/编辑/删除全部可用。** - 登录 `admin/123456` → 进 `/home` → `/permission/user` 正常渲染,左侧分组树 + 右侧表格有数据, **整页零非 200 请求**(fetch/XHR 双钩子实测 `[]`)。 - 机构管理 `/permission/organize` 也正常渲染(空状态,零报错)。 - 面 B 端点从「9 条」涨到 **40 条**;`tables` 12 → **13**(新增 `base_group`)。 - 六闸全绿:`check-module 114` / `check-boundary 11` / `check-contract 10` / `check-citations 4` / `perm-smoke 43` / `perm-smoke-jnpf 23`,`cargo test` **221 全过**。 - 官方端点台账覆盖 **49/72**(implemented 44 / partial 5 / absent 23)。 上一版说「页面从未渲染过一次」——**这个未知已经消除**。 🔴 **本轮踩到并解决的 4 个真 bug**(都是「页面能打开但功能不对」这一类): 1. `CurrentUser` 的 `preferenceJson` 必须是**字符串** `"{}"` —— 给对象会让前端 `handleUpdatePreferences` 抛异常 ⇒ 登录后立刻跳 Logout(表现为「登录无效原地打转」)。 2. 菜单 `urlAddress` 走的是**面 B 路径** `permission/user`,不是面 A 的 `system/User` ⇒ 之前直接访问 `/system/User` 必然 404。 3. `Users` 列表的 `keyword` 压根没进 SQL(搜索框形同虚设)⇒ 已补三列 ILIKE。 4. 空关键词时把 `like` 塞进参数数组 ⇒ PG 报「bind supplies 1 params, statement requires 0」 ⇒ **必须** `if keyword.is_empty() { Vec::new() }`。 --- ## 2. 运行中的现场(断了就按这里重启) ### 后端(端口 30000) ```bash cd ~/Desktop/workspace/ssw-platform RUSTC_WRAPPER=sccache cargo build --manifest-path src/backend/Cargo.toml # 改代码后 nohup env PORT=30000 ./target/debug/ssw-platform > /tmp/ssw-backend.log 2>&1 & # 后台起 curl -s http://127.0.0.1:30000/api/health # 期望 {"ok":true,"tables":13,...}(新增 base_group) ``` 拿 token(面 B): ```bash ENC=$(./target/debug/ssw-platform --enc 123456) curl -s -X POST http://127.0.0.1:30000/api/oauth/Login \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Vue-Version: 3' -H 'App-Code: mainSystem' \ --data-urlencode account=admin --data-urlencode "password=$ENC" # → data.token(lite- 前缀)。Authorization 头是**裸 token,没有 bearer 前缀** ``` ### 前端(`~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework`) 🔴 **必须 `env -u NODE_OPTIONS`**:否则被 brokered-fs shim 逐次拦截(0.15 包/s,末尾 `ERR_PNPM_CODEBUDDY_BROKER_DENY` / `CODEBUDDY_BROKER_OUTCOME_UNKNOWN`)。依赖**已经装好**, 下面第 1 步只在坏了时重跑。 ```bash cd ~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework env -u NODE_OPTIONS pnpm install --prefer-offline --reporter=append-only # 断了才需要重跑,约 47s pnpm -r run stub --if-present # 已由 postinstall 跑过 env -u NODE_OPTIONS nohup pnpm dev:main > /tmp/vite-main.log 2>&1 & # vite, 3000, /dev → 30000 ``` - 成功标志:`node_modules/.modules.yaml` 存在(✅ 已存在)、vite 打印 `ready in ~7s` - 打开 `http://localhost:3000/`(根路径 App-Code 为空 ⇒ 后端回退主系统,已支持) - 登录:`admin` / `123456`(登录框自己加密,不要手填密文) ⚠️ **后台进程会随 turn 结束被回收**(`run_in_background` 起的东西在回复完就没了)。 🔴 **2026-10-31 实测修正**:`run_in_background` **不可靠**(上下文压缩那一轮 vite 就被回收了, 日志里明明 `ready in 5188ms`)。用 **`nohup ... &`** 起,实测能跨 turn 存活: ```bash # 前端 cd ~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework env -u NODE_OPTIONS nohup pnpm dev:main > /tmp/vite-main.log 2>&1 & # 后端 cd ~/Desktop/workspace/ssw-platform nohup env PORT=30000 ./target/debug/ssw-platform > /tmp/ssw-backend.log 2>&1 & ``` 两个都起好后,浏览器会话 `aix --session ssw` 可以直接复用(登录态在 localStorage)。 ⚠️ **后端一重启,token 就失效**(session 是进程内内存表)⇒ 每轮开工必须重新登录拿 token。 ### 代码仓库(本机 Gitea) ```bash cd ~/Desktop/workspace/ssw-platform git status -sb # main...origin/main,工作区应干净 # 推送(凭据只在 xop 注入的环境里存在,脚本不落盘) xop run --secret GU=git_local_user --secret GP=git_local_pass -- bash -c ' export GIT_ASKPASS=/tmp/askpass-ssw.sh GIT_TERMINAL_PROMPT=0 git -c http.proxy= -c https.proxy= push origin main' < /dev/null ``` - 远端:`http://127.0.0.1:13300/ssw/ssw-platform.git`(Gitea 1.26.1,私有,默认分支 main) - `ssw` 是**用户命名空间**不是组织(`/api/v1/orgs/ssw` 返 404),建仓用 `POST /api/v1/user/repos` - `/tmp/askpass-ssw.sh` 若不存在,重建:`case "$1" in *[Uu]sername*) echo "$GU";; *) echo "$GP";; esac` - 🔴 xop 会把输出里等于密钥值的串打码(`ssw` → `ss****【xop禁止将密钥泄漏】`),日志别扭但无害 - 每批做完建议 `git add -A && git commit`(一晚上至少留一个可回滚点) --- ## 3. 待办(按优先级,做完一条划一条) ### ~~P0 —— 用户管理页剩余接口~~ ✅ **2026-10-31 全部做完** | 端点 | 状态 | |---|---| | `GET /api/permission/Group` | ✅ 左侧分组树(ListVO)。**表是官方 `base_group`**(不是 `base_user_group`,官方 DDL `JNPF-PostgreSQL.sql:1758` 只有 `base_group`) | | `GET/POST/PUT/DELETE /api/permission/Group/{id}` | ✅ CRUD 全通,端到端实测(建→详情→改→加成员→移出→删) | | `POST /api/permission/Group/{id}/Actions/AddUser` / `DeleteUser` | ✅ 走 `base_user_relation`(f_object_type='Group'),幂等插 | | `POST /api/permission/Users/{id}/SetPosition` + `/SetPositionBatch` | ✅ 405 已修(单独注册 `/Users/SetPositionBatch`) | | `GET /api/permission/Users/{id}/SelectorByUserPosId` | ✅ | | `GET /api/system/System/getDevUser` | ✅ | | `DELETE /api/permission/socials/{id}` | ✅ 本仓无 `base_socials_users` ⇒ 恒成功 | | `POST /api/permission/Users/workHandover` | ✅ 置 `f_handover_mark=1` | **另外顺手补了 5 条页面级 404**(都是「不补就弹红条」的): `GET /api/system/DictionaryData/All`(恒 `{list:[]}`,**不能是裸数组**)、 `GET /api/system/HomeData`(恒 `[]`,前端读 `res.data.length`)、 `POST /api/system/MenuData/useModuleNum/{id}`(恒成功)、 `GET /api/oauth/getLoginConfig` + `getConfig/{account}`(**登录前调用 ⇒ 无守卫**,恒 `{}`)。 ### ~~P1 —— 让页面真跑起来~~ ✅ **2026-10-31 达成** 可复现步骤(实测有效): 1. `nohup` 起后端 + vite(命令见 §2) 2. `aix open "http://localhost:3000/login" --session ssw` → `aix snapshot` 拿 `@eN` → fill 账号/密码 → click 登录 → 约 9s 后落到 `/home` 3. `aix open "http://localhost:3000/permission/user"` ⇒ 期望:左侧「全部用户」+ 分组节点, 右侧表格有 admin 行,零报错 4. 零非 200 的查法(比看控制台准):进页面前先注入 fetch/XHR 双钩子收集 `window.__net`, 再 filter `x[0]!==200`。**控制台看不到 404 的 details 时就用这招** ### ~~P2 —— 机构管理 `Organize` CRUD + `Selector`~~ ✅ **2026-10-31 做完** `GET/POST /api/permission/Organize`、`GET/PUT/DELETE /api/permission/Organize/{id}`、 `GET /api/permission/Organize/Selector` 共 6 条。 端到端实测:建父 → 建子(`organizeIdTree` = 父树+自己,`orgNameTree` 同理)→ 详情 → 改(只发 `fullName`,`enCode` 不动)→ Selector 2 行 → 删 → 剩 0 行。 ⚠️ 删机构**不级联**(只软删本行)⇒ 已记为已知限制 `(ak)`。 ### P3 —— 菜单管理 / 角色授权(**剩下的就这一块了**) - 菜单:`GET/POST/PUT/DELETE /api/system/Menu/{id}` 一族(面 B 目前只有 `ModuleBySystem`) - 角色:`/api/permission/Role` 已有列表,缺 CRUD + `Selector` + 授权 - 权限:`/api/permission/Authority` 一族(面 B 目前只有 `Data/{objectId}/Values`) - 参考:机构那 6 条是**模板写法**(`ORGANIZE_WRITE_FIELDS` 白名单 + `now()` 不占参数位), 照抄即可,`docs/contract.md` 三处登记记得同步 --- ## 4. 每批实现的固定动作(缺一不可) ```bash cd ~/Desktop/workspace/ssw-platform # 1) 实现 → 编译 RUSTC_WRAPPER=sccache cargo build --manifest-path src/backend/Cargo.toml # 2) 重启后端(老进程先 kill) PORT=30000 ./target/debug/ssw-platform & # 3) 运行时验证(比静态比对权威) python3 scripts/probe-page.py docs/fe/page-user.tsv # 4) 单测 + 六闸 RUSTC_WRAPPER=sccache cargo test --manifest-path src/backend/Cargo.toml for s in check-module check-boundary check-contract check-citations; do bash scripts/$s.sh; done bash scripts/perm-smoke.sh ENC_BIN="$PWD/target/debug/ssw-platform" bash scripts/perm-smoke-jnpf.sh ``` 新增/变更端点必须同步三处,否则闸门必红: 1. `docs/contract.md` 的 `[ENDPOINT]`(面 B 行首列写 `B`)与 `[OFFICIAL]`(`absent → implemented`) 2. `docs/contract.md` 的 `[FACE]` 计数 + `[RULER]` 里 `perm-smoke-jnpf.sh` 的断言数 3. `src/backend/src/routes.rs` 测试里的 `JNPF_REGISTERED`(按**路径**列,同路径多方法算一条) --- ## 5. 必踩的坑(都已踩过一次,别再踩) - 🔴 **一条 `.route()` 只挂一个方法**:`check-contract-scan.py` 只解析每个 `.route()` 的第一个方法, `get(a).post(b)` 会被判成「契约写 POST、代码是 GET」。同路径多次 `.route()` 在 axum 里是合并,不冲突。 - 🔴 **驼峰 ≠ 下划线机械转换**:`ranks` ↔ `f_rank`、`certificatesType` ↔ `f_certificates_type`。 列名只来自白名单常量(如 `USER_WRITE_FIELDS`),别用 `snake_case()` 猜。 - 🔴 `f_creator_time` 写 SQL `now()` 时**不占参数位**:`marks.push("now()")` 而非 `placeholder()`, 否则 `$n` 序号和 `columns` 错位(报 `column is of type timestamp but expression is of type text`)。 - 🔴 写路径只 `SET` **body 里出现过的键**,未出现的列必须保持原值(有断言钉住)。 - 🔴 读回**不选** `f_password` / `f_secretkey`(有断言钉住「详情无 password 键」)。 - 🔴 `{id}` 会吞掉 `Users/` 下未注册的静态 GET 子路径;matchit 静态段优先,所以那些路由 **一旦注册就自动优先匹配**,不需要改详情。 - 🔴 测试共用 `platform/test_support.rs` 的**单例 pglite**(进程内只能开一个实例), 别在测试里 `open_temp`。 - 🔴 `python` 脚本里递归取同目录 `.vue` 时用 `if seen is None:`,**不能写 `seen = seen or set()`** (空 set 是 falsy ⇒ 每层新建 ⇒ 环形 import OOM 被 SIGKILL)。 - 🔴 jq 里 `$d|has(a) or $d|has(b)` 会被 `|` 抢结合 ⇒ 用 `[keys[]|select(.=="a" or .=="b")]|length`。 - 🔴 端口:前端 dev 3000,代理 `/dev` → **30000**,后端绝不能起在 3000。 - 🔴 **npm/pnpm 类命令一律 `env -u NODE_OPTIONS`**(见 §0);cargo 不受影响,不用加。 - 🔴 **后台进程随 turn 结束被回收**:起服务与验证必须同一 turn 内完成。 - 🔴 git 推送别把密码塞 remote URL:用 `GIT_ASKPASS` + `xop run --secret`,并加 `-c http.proxy=`。 - 🔴 `.gitignore` 已挡 `target/`(1.7G) 与 `src/backend/data/`(38M);`git add -A` 前先 `git diff --cached --name-only | wc -l` 确认没暴涨。 --- ## 6. 收工前(每一轮都要做) 1. 追加 `.workbuddy/memory/YYYY-MM-DD.md`:结论 / 坑 / 数字(闸门通过数) 2. 更新本文件 §1 现状、§2 现场、§3 待办(划掉做完的) 3. 若还有未完成项,**确认下一次定时任务存在**(`automation_update` list 可查),没有就新建