Files
ssw-platform/HANDOFF.md
T
sukyboor 9771fa844d init: 尚数网平台 JNPF 7.0 兼容后端(多应用 + 面 A/面 B 双契约)
- axum 0.8 + pglite:12 张表,多应用按 App-Code 头解析 f_system_id 隔离
- 面 A(ssw/react 形状)+ 面 B(官方 JNPF 形状,Vue-Version: 3)双契约并存
- 业务模块 asset/DataResource;面 B 用户 CRUD 9 条已落地
- 六道闸门 + 两把运行时尺子(perm-smoke 43 / perm-smoke-jnpf 23)
- scripts/:前端接口清单、页面依赖反查、运行时探针
2026-10-30 22:08:31 +08:00

138 lines
6.9 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.
# HANDOFF —— 交给下一个 session 的现场交接
> 更新于 2026-10-30 21:30。**开工先读这一页**,再读 `CLAUDE.md`(硬约定),
> 最后看 `.workbuddy/memory/` 最近一天的日志(踩过的坑)。
> 无人值守时不要问用户,选最保守可行的方案继续,并把决策写回本文件。
---
## 1. 一句话现状
Rust 后端(axum + pglite)已能跑,**面 A**(ssw/react 形状)与**面 B**(官方 JNPF 形状,
`Vue-Version: 3`)双契约并存;面 B 的 `Users` 一族 9 条已实现。前端 monorepo 依赖正在安装,
**页面还没渲染过一次**——这是当前最大的未知风险。
---
## 2. 运行中的现场(断了就按这里重启)
### 后端(端口 30000)
```bash
cd ~/Desktop/workspace/ssw-platform
RUSTC_WRAPPER=sccache cargo build --manifest-path src/backend/Cargo.toml # 改代码后
PORT=30000 ./target/debug/ssw-platform & # 后台起
curl -s http://127.0.0.1:30000/api/health # 期望 {"ok":true,"tables":12,...}
```
拿 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`)
🔴 **这个目录在项目工作区之外,跑 pnpm 必须退出沙箱**(否则每个文件操作被 broker 拦一遍,
0.15 包/s,末尾还会 `ERR_PNPM_CODEBUDDY_BROKER_DENY`)。cargo/文本读写不受影响。
```bash
cd ~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework
pnpm install --prefer-offline --reporter=append-only # 断了就续装(缓存命中率很高)
pnpm -r run stub --if-present # 用 --ignore-scripts 装过 ⇒ 必须补
pnpm dev:main # vite, 3000, /dev → 30000
```
- 成功标志:`node_modules/.modules.yaml` 存在 + 2169 个包 `added`
- 打开 `http://localhost:3000/`(根路径 App-Code 为空 ⇒ 后端回退主系统,已支持)
- 登录:`admin` / `123456`(登录框会自己加密,无需手填密文)
---
## 3. 待办(按优先级,做完一条划一条)
### P0 —— 用户管理页剩余接口(`scripts/probe-page.py` 实测的 8 条缺路由)
| 端点 | 备注 |
|---|---|
| `GET /api/permission/Group` | 左侧用户分组树;**需要新表 `base_user_group`** |
| `GET|POST|PUT|DELETE /api/permission/Group/{id}` | 分组 CRUD |
| `POST /api/permission/Group/{id}/Actions/AddUser` / `DeleteUser` | 分组加/移成员 |
| `POST /api/permission/Users/{id}/SetPosition` + `POST /api/permission/Users/SetPositionBatch` | 设岗位(后者当前 405 ⇒ 同路径要补 POST) |
| `GET /api/permission/Users/{id}/SelectorByUserPosId` | 按岗位选人 |
| `GET /api/system/System/getDevUser` | 开发账号下拉 |
| `DELETE /api/permission/socials/{id}` | 第三方账号解绑 |
| `POST /api/permission/Users/workHandover` | 离职交接(写接口,探针默认跳过) |
### P1 —— 让页面真跑起来(比补接口更重要,先验证再补)
1. 装完依赖 → `pnpm -r run stub` → `pnpm dev:main`
2. `aix snapshot` 拿 `@eN` 再点,别猜 selector(见 `~/.agents/skills/aix/SKILL.md`)
3. 登录后进「用户管理」,逐个修控制台/网络的 4xx、5xx
4. 把「页面能渲染 + 列表有数据」做成可复现步骤,写回本文件
### P2 —— 机构管理 `Organize` CRUD + `Selector`
几乎所有权限页面的公共前置。参照 `platform/sys.rs` 里面 A 的 `org_*` 实现。
### P3 —— 菜单管理 / 角色授权(时间够再做)
---
## 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。
---
## 6. 收工前(每一轮都要做)
1. 追加 `.workbuddy/memory/YYYY-MM-DD.md`:结论 / 坑 / 数字(闸门通过数)
2. 更新本文件 §1 现状、§2 现场、§3 待办(划掉做完的)
3. 若还有未完成项,**确认下一次定时任务存在**(`automation_update` list 可查),没有就新建