Files
ssw-platform/HANDOFF.md
T
admin 0d5c43570d feat(face-b): 系统日志 + 审批常用语 + 单据规则落地(面 B 批次 5,+21 端点)
- 新表三张(官方 DDL 逐字):base_sys_log(30 列) / base_common_words / base_bill_rule,tables 29→32
- 登录即落日志:auth.rs::login_handler 写 f_type=1,Log 页与个人中心「登录日志」共用同一 log_page
- 单据规则带单号生成器:时间/随机/UUID 三分支 + 跨天归零 + 回写 f_this_number/f_output_number
- DictionaryData/All 从恒空改为真读字典,seed 灌 businessType 13 行
- 回归 tests/batch5_it.rs(6 条);cargo test --workspace 508 passed
2026-11-01 08:05:14 +08:00

453 lines
31 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-11-01(面 B 批次 5 收尾)。**开工先读这一页**(尤其 §0-bis 缺口全景),再读 `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 装完。
---
## 0-bis. 📊 缺口全景(2026-10-31 05:00 全量摸底,看这里决定下一步)
用 `/tmp/fe-scan/scan.py` 扫前端 `src/api/**`(741 条端点定义,先解 `enum Api` 再解析
模板串),跟后端 `routes.rs` 做差集。**只看本仓该有的 6 个前缀**:
| 前缀 | 已覆盖 | 缺口 | 缺口主要是什么 |
|---|---|---|---|
| `permission` | 54 | 62 | 个人设置 `Users/Current/*`(14)、`Standing`(6)、`PermissionGroup`(6)、`Action`(3)、导入导出 |
| `system` | 29 | 208 | **大半是本仓没这个模块**:printDev(15)/Dataset(16)/DataModel(11)/DataInterface(10)/InterfaceOauth(9)/DataSource(5)/PortalManage(4)/BusinessCategory(5)/Area(6)/BillRule(6)… |
| `oauth` | 3 | 11 | 扫码登录、锁屏、验证码证书 |
| `message` | 0 | 53 | 消息中心(本仓无表) |
| `file` | 0 | 32 | 文件/网盘(本仓无表) |
| `extend` | 0 | 53 | 示例模块 + 邮件 + 甘特图(本仓无表) |
| **合计** | **86** | **419** | |
🔴 **判断**:419 里约 **250 条属于「本仓没这个模块」**,真做也只是恒空 stub。
剩下的真价值集中在 `permission` 那 62 条。所以**下一轮按这个顺序做**:
1. `permission/Users/Current/*` 个人设置(14 条,个人中心要用)—— ✅ 批次 1(实际 23 条)
2. `permission/Standing` / `PermissionGroup` / `Action`(15 条)—— ✅ 批次 2(实际 21 条)
3. ~~`system/System` + `system/SysConfig`(17 条,系统配置页)~~ —— ✅ 批次 3(实际 25 条)
4. ~~`message`(53) / 低代码模块 ⇒ 批量恒空 stub~~
✅ **批次 4 做完(实际 19 条)**——新表 `base_business_category` / `base_message` /
`base_notice`;业务分类(官方 38 行种子)+ 站内消息(列表/已读/回执/删除)+
公告(增删改查 + **发布即逐收件人落消息**)。
⚠️ 只做了 `api/system/message.ts` 那 14 条(消息记录页 / 公告管理页用的),
`api/msgCenter/*`(发送配置/账号配置/供应商/模板/监控/敏感词 —— 共 36 条)
是「消息中心运维后台」,本仓没这个产品 ⇒ **仍待定**(见下条)。
**被最多页面共用的接口**(`python3 scripts/fe-page-deps.py` 的实测排序,按这个做收益最高):
`DataModel/{}/Tables`(12 页) / `visualdev/OnlineDev/{}/Config`(10) / `ai/AiSupplier/Selector`(10) /
`BusinessCategory/treeList`(9 ✅批次4) / `Log`(9) / `workflow/operator/List`(9) /
`Dataset/{}/Actions/InfoByIds`(9) / `BasicDataType`(9) / `extend/TableExample` 四个(9) / `Tag/selector`(8 ✅批次3)。
~~**下一个(批次 5)建议**:`system/Log`(5) + `system/CommonWords`(6) + `system/BillRule`(8)~~
✅ **批次 5 做完(实际 21 条)**——新表 `base_sys_log` / `base_common_words` / `base_bill_rule`;
登录即落日志(`Log` 页与个人中心「登录日志」同一份数据)、审批常用语 CRUD + 使用计数、
单据规则 CRUD + **单号生成器**(时间/随机/UUID 三分支 + 跨天归零 + 回写流水)。
顺手把 `DictionaryData/All` 从「恒空」改成真读字典 + 灌 `businessType` 13 行种子。
详见 §1「批次 5」小节。
**下一个(批次 6)建议**:`DataModel/{}/Tables`(12 页共用,最高优先) +
`extend`/`systemData` 那几个恒空 stub;`visualdev/OnlineDev/{}/Config`(10) 属低代码域,后置。
**2026-11-01 实测**(`python3 scripts/fe-gap.py`):合计 **215 / 900**(23.9%);
`permission` 111/137(81.0%)、`system` **84/196(42.9%,批次 4 47→66、批次 5 66→84)**;
剩下体量最大的仍是 `workFlow`(104) / `onlineDev`(101) / `systemData`(91) / `aiCenter`(75) /
`extend`(64) / `msgCenter`(50) —— **基本都属于「本仓没这个模块」**。
---
## 1. 一句话现状(2026-11-01 批次 5 收尾)
**📌 当前数字(以此为准,下面各批的「当时数字」仅存档)**:
- 契约端点 **249 条**(面 A 28 + 面 B **219** + 两面共用 2);`tables` → **32**。
- `cargo test --offline --workspace` = **508 passed / 0 failed**。
- 十二道闸门全绿;`check-contract` `PASS=10 FAIL=0`,官方端点覆盖 **238/245**
(implemented 225 / partial 13 / absent 7)。
- `python3 scripts/fe-gap.py`:合计 **215 / 900(23.9%)**,`permission` 111/137(81.0%)、
`system` **84/196(42.9%)**。
**✅ 后端已拆成 workspace 多 crate,业务包可独立编译;八道闸门全绿;空载内存 7 MB。**
- 新增 `crates/sspf-contract`(契约层,无 axum)、`crates/sspf-sdk`(业务包唯一依赖)、
`packs/asset`(样板业务包,只依赖 sdk,能 `cargo test -p sspf-pack-asset` 独立跑)。
- `rust-toolchain.toml` 全仓锁 **1.95.0**(L3 动态库 ABI 一致性强依赖;本机代理限速装不上 1.99)。
- 新增两道闸门:`scripts/check-arch.sh`(AR1–AR5 + MEM1–MEM2,带 `--self-test`)、
`scripts/mem-budget.sh`(空载内存实测,用 `vmmap`,**本机沙箱禁 ps/top**)。
- 内核 `platform/{envelope,entity,menu,ids}.rs` 已改为 re-export 契约层 ⇒ 引用路径零变化。
- `cargo test --workspace` = **240 条**(不是 221/230 了,拆 crate 后数字会变,别写死)。
- 长期架构与路线看 **`PLAN.md`**(尤其判断 ⑥ 内存约束、判断 ⑦ 执行器、§4.5 动态库 ABI)。
**前端侧(未变):✅ 浏览器里真跑起来了,用户管理页可渲染、列表/新增/编辑/删除全部可用。**
- 登录 `admin/123456` → 进 `/home` → `/permission/user` 正常渲染,左侧分组树 + 右侧表格有数据,
**整页零非 200 请求**(fetch/XHR 双钩子实测 `[]`)。
- 机构管理 `/permission/organize` 也正常渲染(空状态,零报错)。
**第二波(04:00–05:00)当时的数字(已过期,仅存档):**
- 契约端点 **207 条**(面 B **177** 条);`tables` → **26**(新增 `base_group`、
`base_position`、`base_dictionary_type`、`base_dictionary_data`、`base_user_extra`、
`base_sign_img`、`base_standing`、`base_permission_group`、`base_action`)。
- 六闸全绿:`check-module 114` / `check-boundary 11` / `check-contract 10` /
`check-citations 4` / `perm-smoke 43` / `perm-smoke-jnpf 23`,`cargo test` **230 全过**。
- 官方端点台账覆盖 **165/172**(implemented 160 / partial 5 / absent 7)。
- 浏览器实测 5 个页面**零非 200**:用户管理、机构管理、角色管理、菜单管理、岗位。
菜单管理页能正常显示树(系统管理 → 用户/角色/机构/菜单管理)。
### 批次 2(2026-10-31 08:00–09:00)做了什么
`permission/Standing`(8) + `permission/PermissionGroup`(8) + `permission/Action`(5) = **21 条面 B 端点**,
新增官方表 `base_standing`(15 列) / `base_permission_group`(16 列) / `base_action`(15 列)。
**官方 DDL 逐字对齐**(行号已核对 `JNPF-PostgreSQL.sql`):
`base_action`:1 / `base_permission_group`:3278 / `base_standing`:4071。
🔴 **官方陷阱已照抄**:`base_action.f_enabled_mark` 是 **VARCHAR(11)**(不是 INTEGER)⇒
投影用 `COALESCE(f_enabled_mark,'0')`,**不加 integer CAST**。
🔴 **官方语义已对齐**:
- `base_standing.f_is_system`:**1=系统身份 / 2=自定义** ⇒ 新建默认写 **2**,投影归一化成 `isSystem` 0/1。
- `base_action.f_type`:**1=自定义** ⇒ 新建强制写 1(前端 `record.type == 1 ? '自定义' : '系统'`)。
- `PermissionGroupController.list` 会用 `userService.getFullNameByIds` 把 `f_permission_member`
的 **id 串换成用户名串** ⇒ 本仓用子查询 `string_agg(...)` 做同样的替换。
### 🔴 本轮踩到并解决的 4 个真 bug(都有回归测试 + 反自证)
| # | 症状 | 根因 | 修法 |
|---|---|---|---|
| ① | `GET /PermissionGroup/PermissionMember/{id}` → 500 / `data:null` | `f_id = ANY($1::text[])` ⇒ pglite-rs 把 `$1::text[]` 当成 PG 数组类型 `_text` | 改 `ANY(string_to_array($1::text, ','))`(**函数在 SQL 里做** ⇒ 参数仍是 text) |
| ② | `DELETE /PermissionGroup/{id}` → 500 `42P18` | 软删 `base_authorize` 的 SQL 带了 `$1` 但 WHERE/赋值里**没用到** ⇒ PG 拒「无法确定 $1 类型」 | 把 `f_delete_user_id = $1::text` 写进 SET(既是审计列,也用掉参数) |
| ③ | `DELETE /Standing/{id}` 后**关联残留**(静默) | 软删关联的**占位符与参数顺序错位**(SQL `$1`=item_type、`$2`=item_id,参数传 `[account, id]`) | `rel = [item_type, id, account]` + SQL 改 `$1/$2/$3` 对齐 |
| ④ | 权限组列表 `permissionMember` 返**uuid 串** | 漏了官方的 `getFullNameByIds` 替换 | 子查询 `string_agg` 换成人名串 |
回归测试:`src/backend/tests/batch2_it.rs`(**4 条**,每个钉一个 bug)。
**反自证全部做过**:逐个把修复回退 ⇒ 测试精确复现原始报错(`cannot convert between String and _text` /
`42P18` / 关联残留 n=1 / uuid 串)⇒ 恢复后 4 条全过。
### 批次 3(2026-10-31 21:40–22:10)—— 应用中心 + 系统配置
**31 条面 B 端点**:`/api/system/System`(13:列表/详情/新建/改/删/复制/置顶/偏好/开发者授权×3/Selector/userAuthList)
+ `/api/system/SysConfig`(8:参数读写/第三方配置读写/管理员列表/设置/企业微信·钉钉连通性测试)
+ `/api/system/SynThirdInfo`(4:同步/统计/清空/失败清单)
+ `/api/system/Tag`(6:列表/详情/新建/改/删/selector —— 应用中心页一进来就拉 `selector?enCode=AppTags`)。
- 新表三张(官方 DDL 逐字):`base_system_top`(置顶按 `f_user_id + f_type` 记账)、
`base_sys_config`(`f_category + f_key → f_value` 的键值表)、`base_tag`(标签)。
- 🔴 **老库补表**:`Db::ensure_schema` 原先见到 `base_user` 就早退 ⇒ 后加的表在老库上
**永远不存在**。现在会按 `schema.sql` 逐表探 `to_regclass`,缺哪张补哪张
(DDL 仍以 `schema.sql` 为唯一真源,不另写迁移脚本);单独测试见
`tests/schema_upgrade_it.rs`。
- 🔴 **尺子自身的 bug 修了**:`check-contract-scan.py` 判面 B 守卫时只认模块名
`jnpf` 与函数 `require_login_jnpf` —— 文件早已改名 `face_b.rs` / `require_login_face_b`
⇒ 整片面 B 的 CC6 守卫检查**静默失效**(只打 warning)。两个名字都认之后恢复生效。
- 复制应用**只复制应用行**(菜单/表单资源不复制)⇒ `[OFFICIAL]` 记 `partial`;
应用授权的 `devUsers` 存 `f_user_id` 逗号串、不写 `base_authorize` ⇒ 也记 `partial`。
- 企业微信/钉钉连通性测试**恒业务失败**(未接 SDK)—— 刻意不假装成功。
### 批次 4(2026-10-31)—— 消息业务分类 + 站内消息 + 公告
**19 条面 B 端点**:`/api/system/BusinessCategory`(7:树/详/增/改/删/`treeList`/`selector`)
+ `/api/message`(5:列表/全部已读/读消息/删记录/回执)
+ `/api/message/Notice`(7:列表/增/详/改/删/发布/回执人列表)。
- 新表三张(官方 DDL 逐字):`base_business_category` / `base_message` / `base_notice`;
tables 26 → 29。
- 🔴 **业务分类是平台字典,不是用户数据**:官方初始库灌 89 行(一级 + 二级 + 三级)。
本仓在 `platform/seed.rs::BUSINESS_CATEGORIES` 灌 **38 行**(5 个一级 + 33 个二级),
**id 沿用官方雪花 id**(`f_category` 存的就是这些 id 串,改 id 官方历史消息就错位)。
三级是「消息事件」粒度(`flow_todo_remind` 之类),没有消息行时展示不到 ⇒ 暂不灌。
- 🔴 **`base_message` 一行 = 一个收件人**(`f_user_id` 是收件人,发件人在 `f_creator_user_id`)
⇒ 所有查询必须带 `f_user_id = 当前用户`,漏了就是串号。
- 🔴 **公告发布是全链路的唯一消息来源**:`PUT /Notice/{id}/Actions/Release` 置
`f_enabled_mark=1` 后**逐收件人插 `base_message`**(收件人为空 ⇒ 全体启用用户),
`f_category` 拼「公告一级 id,公告提醒二级 id」⇒ 消息记录页按二级页签过滤、
按一级 `enCode` 显示类型名,两者同时成立。不落这一步,消息记录页永远是空的。
- 🔴 **`ReadInfo` 会写库**(`f_is_read` 0⇒1),且 `f_is_read=2`(已回执)时不回退 ——
前端「点开就变已读」全靠它,别当纯查询。
- 🔴 **用户标签要按 `f_id` 与 `f_account` 双键查**:本仓写 `f_creator_user_id` 存的是**账号**
(`seed.rs` 的 `ADMIN_ACCOUNT`),官方历史数据里是 **id** ⇒ 只查一种另一种永远显示空。
- 已知 `partial`:`POST /message/Notice/List` 的**时间区间过滤未做**
(`releaseTime`/`creatorTime`/`expirationTime` 三个区间参数接受但忽略);
分类删除是**软删**(官方物理删,本仓偏保守)。
- 回归测试 `tests/batch4_it.rs`(**3 条**):分类树/裁剪/两段式 selector/判重、
发布扩散、读+回执+删除(含「已回执不回退」与「只删自己的」)。
### 批次 5(2026-11-01)—— 系统日志 + 审批常用语 + 单据规则
**21 条面 B 端点**:`/api/system/Log`(6:列表/详情/删一条/按类型清空/清登录日志/模块名)
+ `/api/system/CommonWords`(7:列表/selector/详/增/改/删/使用计数)
+ `/api/system/BillRule`(10:列表/selector/详/增/改/启停/删/导出/导入/生成单号)。
- 新表三张(官方 DDL 逐字):`base_sys_log`(30 列)/ `base_common_words` / `base_bill_rule`;tables 29 → **32**。
- 🔴 **登录日志此前根本不存在**:`self_system_log`(个人中心「登录日志」)是手写的恒空分页。
本轮在 `auth.rs::login_handler` 里落一行 `f_type=1`(成功 `f_login_mark=1`、失败 `=0` 且 `f_description` 存失败原因),
**失败只打 stderr 绝不冒泡**(日志写坏了不能把登录搞挂)⇒ `Log?category=1` 与 `Users/Current/SystemLog`
共用同一个 `log_page(.., 1, Some(uid))`,两处同时变真。
- 🔴 **`DELETE /Log/{type}` 的 `{type}` 是分类号不是 id**(官方 `deleteLoginLog` 就是删 `f_type=1` 全部)。
实现成「删某一条」的话,管理员点「一键清空」会静默什么都不做。路由上 `/Log/{id}` 的 GET(详情)与 DELETE(清空)
共用同一段名 `{id}`(matchit 不允许同位置两个参数名),handler 内部按分类号解析。
- 🔴 **`to_char` 的占位符不能照搬官方**:PG 的 `HH` 是 12 小时制、毫秒叫 `MS` 不叫 `SSS`
⇒ 单独写 `to_char_pattern()` 把小写官方格式映射成 PG 格式,否则会生成「下午 03 点」的错号。
- 🔴 **改单据规则时只有四个条件变了才清流水**(前缀/后缀**长度**、位数、日期格式)——
照抄官方这段判断,不然「改个描述」也会把 `f_this_number` 清掉,已发出的号就重号了。
- 🔴 **`f_this_number` / `f_output_number` 只由 `BillNumber` 回写**,不在 `*_WRITE_FIELDS` 里(14 列不含这两个);
规则被发过号(`f_output_number` 非空)就**禁删**(`400 单据已经被使用,不允许被删除`)。
- 🔴 **常用语判重按 `文本 + 类型` 同档**(公共/个人各一套),且 `CommonWordsController` 官方**一个
`@SaCheckPermission` 都没有** ⇒ 故意不挂 `guard()`,只做 `require_login_face_b`。
- 已知 `partial`:`DELETE /Log/{id}` 的 `dataInterfaceId` 收窄未做;`BillRule` 的 `Export`/`Import`
恒业务失败(本仓没有文件服务,**刻意不假装成功**)。
- 顺手修:`GET /api/system/DictionaryData/All` 原先**恒空**(`businessType` 之类下拉全空且不报错)
⇒ 改为真读两张字典表 + `seed.rs` 灌 `businessType` 13 行(`isTree=0`)。
- 回归测试 `tests/batch5_it.rs`(**6 条**):登录落日志双读者一致、三条删除路径语义不同、
常用语 CRUD + 计数、单号时间格式 + 跨天归零、规则守卫、随机/UUID 分支。
### 🔴 上一批(第一批)踩到并解决的 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 # 改代码后
# 🔴 **尺子跑的是 release 产物** ⇒ 跑尺子前必须 `cargo build --release`
RUSTC_WRAPPER=sccache cargo build --release --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":32,...}
```
拿 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 —— 菜单管理 / 角色授权~~ ✅ **2026-10-31 05:00 做完**
| 批次 | 端点 | 备注 |
|---|---|---|
| 岗位 `Position` | 12 条 | 新表 `base_position`(官方 23 列逐字)。CRUD + Selector/SelectorTree/Condition/SelectedList/DutyPosition/DutyUser |
| 角色 `Role` | 6 条 | `base_role` 已有。CRUD + Selector + RoleCondition |
| 菜单 `Menu` | 13 条 | `base_module` 已有。CRUD + 四种 Selector + Export/权限组 |
| 字典 `DictionaryType`/`Data` | 14 条 | 新表 2 张。分类 CRUD + 数据 CRUD + 两种下拉 |
| 用户选人 / 授权 / 关系 | 16 条 | `Users/Selector`、`getUserList`、`getSelected*`、`getAllPermission`、`Authorize`、`Authority/{kind}/{id}`、`RoleRelation/*`、`UserRelation/*` |
### P4 —— 剩下的(按 §0-bis 的全景表,从上往下做)
1. ~~`permission/Users/Current/*` 个人设置 14 条(BaseInfo/改密码/主题/语言/头像/签名/saas)~~
✅ **批次 1 做完(实际 23 条)**——新表 `base_user_extra` / `base_sign_img`
2. ~~`permission/Standing`(6) / `PermissionGroup`(6) / `Action`(3)~~
✅ **批次 2 做完(实际 21 条)**——新表 `base_standing` / `base_permission_group` / `base_action`
3. ~~`system/System`(11) + `system/SysConfig`(6) 系统配置页~~ ← **下一个**
✅ **批次 3 做完(实际 31 条,含 Tag)**——新表 `base_system_top` / `base_sys_config`;
应用中心 CRUD + 置顶 + 应用授权 + 系统参数/第三方配置键值表 + 管理员设置 + 同步统计。
4. ~~`message`(53) 里的 `api/system/message.ts` 那 14 条~~
✅ **批次 4 做完(实际 19 条,含 BusinessCategory)**——新表 `base_business_category` /
`base_message` / `base_notice`。`api/msgCenter/*`(36 条运维后台)仍未定。
5. ~~`system/Log`(5) + `system/CommonWords`(6) + `system/BillRule`(8)~~
✅ **批次 5 做完(实际 21 条)**——新表 `base_sys_log` / `base_common_words` / `base_bill_rule`;
登录落日志 + 常用语 CRUD + 单据规则与单号生成器。
6. `DataModel/{}/Tables`(12 页共用) / `extend`(53) / `systemData`(91) / `file`(32) / 低代码模块
⇒ **下一个**(`file` / `extend` / 低代码多半是恒空 stub,见 §0-bis 的判断)
**实现模板(照抄就行)**:`ORGANIZE_WRITE_FIELDS` / `POSITION_WRITE_FIELDS` 那一套
—— 列白名单 + `now()` 不占参数位 + 只 SET body 里出现的键 + 读回不选 `f_password`。
`docs/contract.md` 三处登记必须同步,否则 CC10 / CIT2 会红。
---
## 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
# 🔴 **尺子跑的是 release 产物** ⇒ 跑尺子前必须先 build --release
RUSTC_WRAPPER=sccache cargo build --release --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` 确认没暴涨。
### 批次 2 新增的坑
- 🔴 **PG 数组参数一律不能写 `$N::text[]`**:pglite-rs 0.2.7 会把它当成 PG 数组类型 `_text`,
而本仓参数**一律按 text 绑定**(`Option<String>`)⇒ 协议错
`cannot convert between the Rust type String and the Postgres type _text`。
⇒ 改成 `= ANY(string_to_array($N::text, ','))`(**函数在 SQL 里做**)。
- 🔴 **PG 会拒「SQL 里有 $N 但没用它」**:`42P18: could not determine data type of parameter $1`。
⇒ 凡是留了 `$N` 的软删 SQL,都要把对应列写进 SET(`f_delete_user_id = $N::text`)。
- 🔴 **占位符顺序必须与参数追加顺序逐字对齐**(不是「大致对上」)⇒ 写完对着读一遍。
- 🔴 **`base_action.f_enabled_mark` 是 VARCHAR(11)**(官方 DDL 陷阱)⇒ 别按整数 CAST。
- 🔴 **`base_standing.f_is_system` 是 1=系统 / 2=自定义** ⇒ 新建写 **2**,不是 1。
- 🔴 **官方 `list` 端点常有「id 串换人名串」的后处理**(`getFullNameByIds`)⇒ 抄控制器别只抄模型。
- 🔴 **Bash 里写多层嵌套引号的 curl + python 验证脚本很容易引号不闭合**(`bash -n` 报
`unexpected EOF` 但**定位不到行**)⇒ **直接用 Python 写验证器**(`urllib` + `ProxyHandler({})`
绕过本机代理),别跟 bash 引号较劲。
- 🔴 **尺子用的是 `target/release/ssw-platform`**,不是 debug 产物 ⇒ 改完代码跑尺子前
**必须 `cargo build --release`**,否则尺子跑的是旧二进制(表现为「刚修好的端点还是 405」)。
---
## 6. 收工前(每一轮都要做)
1. 追加 `.workbuddy/memory/YYYY-MM-DD.md`:结论 / 坑 / 数字(闸门通过数)
2. 更新本文件 §1 现状、§2 现场、§3 待办(划掉做完的)
3. 若还有未完成项,**确认下一次定时任务存在**(`automation_update` list 可查),没有就新建