Files
ssw-jnpf-lite-rust/HANDOFF.md
T
adminandClaude Code 8edcd3507d feat: 前端逐字复制(仅代理端口改 30010)+ run.sh + check-module.sh + 文档
前端:从 ssw-jnpf-lite-react/src/frontend 逐字复制(package-lock.json 一并复制),
唯一改动 = vite.config.ts 的代理目标 30000 → 30010(含紧邻注释行的端口);
src/api/request.ts 的注释与 axios timeout: 30000 逐字节保留。

脚本:run.sh(install/build/dev/backend/frontend/stop/logs,退出码 0/1/2,
kill_ports 只清 30010 与 5173);scripts/check-module.sh(9 接触点静态自检,
纯静态零 node 依赖)。

文档:README.md、docs/runbook.md、.env.example;CLAUDE.md 逐条核对并与代码同步,
HANDOFF.md §0 状态表与 §9 交接话术改为交付态。

Co-Authored-By: Claude Code <[email protected]>
2026-10-26 03:26:22 +08:00

436 lines
30 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.md —— tds-lite-rs 交接文档
> **给下一个会话的你**:本文件 + `CLAUDE.md` 两份读完就能直接开工,**不需要**重新推导任何设计。
> 目标:把「JNPF 兼容契约的 Rust 实现」从零写到**验收全绿**。
---
## 0. 当前状态
**v1 已完成,验收四门全绿**(每一条 ✅ 都有实际执行输出,见 §9 与各任务报告)。
| 项 | 状态 |
|---|---|
| 目录 `~/Desktop/workspace/tdc-lite-rs/` | ✅ 已建并已 commit(`main` 分支) |
| `CLAUDE.md` | ✅ 已写;**已逐条核对并与代码同步**(Task 12) |
| `HANDOFF.md`(本文件) | ✅ 已写并已同步(§0 状态表 / §9 交接话术,Task 12) |
| 代码 | ✅ 后端已实现(`src/backend/`,Rust 2021 + axum 0.8 + pglite-rs 0.2,**10 张表**、**27 条路由**) |
| 前端 | ✅ 已逐字复制(`src/frontend/`;**唯一改动 = vite 代理端口 `30000 → 30010`**,其余文件逐字节相同) |
| 脚本 | ✅ `scripts/perm-smoke.sh`(**32 条断言**)+ `scripts/check-module.sh`(9 接触点静态自检,**55 条 ✅**) |
| 工程脚本 | ✅ `run.sh`(`install`/`build`/`dev`/`backend`/`frontend`/`stop`/`logs`,退出码 0/1/2) |
| 文档 | ✅ `README.md` / `docs/runbook.md` / `.env.example` |
| 验收四门 | ✅ 全绿(编译 **0 error 0 warning** · 单测 **177 passed / 0 failed** · 冒烟 **PASS=32 FAIL=0** · 前端**浏览器**手验全过) |
**读法**:`CLAUDE.md`(红线与坑位,日常改代码必读)→ §9(怎么起 / 怎么复现验收)。
§3(设计)与 §5(实施顺序 step 0–12)已**完结**,留作背景与决策记录,**不要再照着实施一遍**。
---
## 1. 决策记录(本轮问答全过程,含被推翻的方案)
> 保留被推翻的方案,是为了避免下个会话"重新考虑"已经讨论过的问题。
| # | 问题 | 决定 | 理由 |
|---|---|---|---|
| 1 | Rust 版做成什么形态? | **先做真实项目,验证后再抽技能** | 技能是模板;没跑通的模板没有价值 |
| 2 | v1 做多大? | **全量契约对齐**(auth + 5 组 `base_*` + 四源权限 + 两段种子 + 3 业务模块 + 冒烟) | 迁移价值全在权限与数据模型这两块,缺一块就不成立 |
| 3 | 落在哪个仓? | **独立仓** `tds-lite-rs` | ~~原方案:tdc-rs 开分支~~(已被 #4 推翻) |
| 4 | 运行时拓扑? | **先不碰 tdc-rs,独立仓做** | tdc-rs 已占 `:30000` 且已有自己的 `/api/oauth/Login`(JSON 账号库),两套同路径不同语义会打架 |
| 5 | 目录名? | **`tds-lite-rs`**(用户指定) | ~~原方案:`ssw-jnpf-lite-rust`~~ |
| 6 | 数据库? | **pglite-rs 0.2**(进程内原生 PG) | 沿用 tdc-rs 已验证的形态;零服务零 Docker |
| 7 | 后端端口? | **`:30010`**(前端 vite `:5173`) | 避开 tdc-rs 的 `:30000` |
| 8 | 前端怎么办? | **逐字复制** react 技能的前端,**零改动** | 前端零改 = 契约真的对齐了(改了就说明后端在迁就前端) |
| 9 | 业务实体怎么实现? | **spec 驱动 CRUD 引擎**;5 组 `base_*` 走**显式 handler** | 业务模块语义简单可声明化;`base_*` 的语义(一维授权数组 / 用户↔角色 / 机构树防环)塞不进通用引擎 |
| 10 | 冒烟脚本的 node 依赖? | Rust 二进制加 `--enc <明文>` 模式,脚本**自证 cipher**,不依赖 node | 去掉 node 依赖 = 冒烟可在任何装了 Rust 的机器上跑 |
| 11 | 抽技能的时机? | **验收门全绿之后**再抽 | 目录结构现在就和 react 技能对齐(`src/backend` + `src/frontend` + `scripts/` + `run.sh`),届时 1:1 复制即可 |
**关键约束**:`tdc-rs` **只读**。本仓不 import 它的代码、不共享数据目录、不共享端口。
可以**读**它的 `src/cipher.rs` / `src/db.rs` / `src/envelope.rs` 作工程手法参考。
---
## 2. 目标与非目标
**目标(v1 做完的样子)**:
1. 用 **Rust** 起一个**单二进制、零外部服务**的后端,行为与 `ssw-jnpf-lite-react`(NestJS)**逐条一致**。
2. 前端**一行不改**就能跑通(直接复用 react 技能的 `src/frontend`)。
3. `base_*` 表结构与官方 DDL **逐字一致** ⇒ 迁 JNPF 时**导数据即可**(`--data-only`)。
4. 权限闭环(登录 → 菜单树 → 建用户 → 授权 → 收窄 → 403)**有自动化冒烟钉住**。
5. 跑通之后,1:1 复制成技能(`ssw-jnpf-lite-rust`)。
**非目标(明确不做)**:低代码引擎 / 多租户 / 按钮·列·表单·数据范围级授权 /
Redis+Sa-Token / 分页 / `secretkey` 的官方双层 md5 算法。理由见 `CLAUDE.md`「明确不在 v1 范围」。
---
## 3. 设计(已定稿)
### 3.1 落点与边界
```
tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
├── Cargo.toml ← 【workspace 根】members=["src/backend"] + [profile.release]
├── src/backend/ ← 名字保留是为了将来抽技能时目录与 react 版对齐
│ ├── src/*.rs ← 14 个模块(见 §3.3)
│ ├── db/schema.sql ← 10 张表完整 DDL
│ └── data/ ← 运行期(gitignore)
├── src/frontend/ ← react 技能前端逐字复制(零改)
├── scripts/{perm-smoke.sh,check-module.sh}
├── run.sh ← install/build/dev/stop/logs
└── .env.example
```
**端口**:后端 `30010`(`PORT` 可覆盖)· 前端 `5173`(vite)· vite proxy `/api` → `http://127.0.0.1:30010`。
**数据库**:`pglite-rs`,默认落盘 `src/backend/data/lite.pg`;`PGLITE_DIR=memory://` ⇒ 纯内存。
### 3.2 契约逐字对齐表(对着 react 技能源码抄)
| 契约点 | 精确口径 | react 源码位置 |
|---|---|---|
| 统一返回 | `{code,msg,data}`;成功 `code=200,msg='成功'`;失败 `data=null` | `src/backend/src/common/action-result.ts` |
| HTTP 状态 | 业务失败/鉴权失败 **HTTP 200**;**未知路由 HTTP 404**(body 仍是 ActionResult) | `common/action-result.filter.ts` |
| 错误码 | 未登录 `600` · 无菜单权限 `403` · 业务失败 `400`(msg 透传) | 同上 + 各 controller |
| 登录 | `POST /api/oauth/Login`,form-urlencoded `account`/`password`(密文 hex)/`grant_type=password` | `auth/auth.controller.ts:19` |
| 登录失败文案 | 缺参 → `400 '缺少 account / password'`;grant_type 不支持 → `400`;口令错 → `400 '账号或密码错误'` | `auth/auth.controller.ts` |
| 登录成功体 | `{token, expiresIn:7200, tokenTypeName:'bearer'}` | `auth/auth.service.ts` |
| CurrentUser | `GET /api/oauth/CurrentUser` → `{userInfo:{userId,userAccount,userName,isAdministrator}, menuList}` | `auth/auth.controller.ts:34` |
| cipher | `md5(明文)` → AES-256-ECB-PKCS7(key=`md5("EY8WePvjM5GGwQzn")` 的 32 ASCII 字节)→ hex | `common/cipher.ts` |
| 检验向量 | `encryptPassword('123456')` = `d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b` | `common/cipher.ts` 注释 |
| 口令比对 | 库内存 `md5(明文)` 小写 hex;登录解出 `md5(明文)` ⇒ **大小写不敏感**比较 | `auth/auth.service.ts` |
| 权限四源 | 直授 + 角色 + 组织 + 岗位;**管理员短路在 SQL 之前**;**菜单未映射 ⇒ 放行** | `sys/permission.service.ts` |
| 菜单树 | `parentId||'0'` 为根;按 `sortCode` 升序;节点 `{id,fullName,urlAddress,icon,parentId,children}` | `sys/permission.service.ts:toTree` |
| 授权写入 | `PUT /api/permission/Authority/Data/{objectId}`,body `{objectType:'role'(小写), module:[...]}`(**一维**) | `sys/authorize.controller.ts:39` |
| 授权读取 | `GET /api/permission/Authority/RoleModules?roleId=` → `string[]` | `sys/authorize.controller.ts:52` |
| 角色授权写 | 旧行**软删**(`delete_mark=1`)后插新行 | `sys/sys.service.ts:saveRoleModules` |
| 用户↔角色 | `setUserRoles` = 先 `delete` 旧 `base_role_relation` 行再插新行 | `sys/sys.service.ts` |
| 用户列表 | 去掉 `password`,追加 `roleIds` / `roleNames` | `sys/sys.service.ts:listUsers` |
| 账号唯一 | 应用层保证,**只比 `delete_mark=0`**(官方 DDL 无 UNIQUE) | `sys/sys.service.ts:saveUser` |
| 机构删除 | 有子机构 ⇒ `400 '该机构下还有子机构,先删除子机构'` | `sys/sys.service.ts:deleteOrganize` |
| 业务 List | 软删过滤 + `creatorTime DESC` | `shop/product.service.ts` |
| 业务 Save | 无 id ⇒ 新 36 位 UUID + `creatorUserId='admin'` + `creatorTime=now` + `deleteMark=0`;有 id ⇒ 覆盖更新 | `shop/product.service.ts` |
| 业务 Delete | **软删**(`f_delete_mark=1`) | `shop/product.service.ts` |
| numeric 列 | JSON **字符串**(`"9.90"`) | `shop/product.entity.ts` + TypeORM numeric→string |
| int 列 | JSON 数字 | `books/book.entity.ts` |
| 端点命名 | `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}` | 各 controller |
**种子里必须逐字保留的常量**(`sys/seed.service.ts` 的字面量数组):
- 角色:`role_admin`/enCode `admin`/管理员/sort 1;`role_user`/enCode `user`/使用者/sort 2
- 菜单(`f_type`:1=目录 2=页面):
| id | fullName | urlAddress | parentId | type | icon | sortCode |
|---|---|---|---|---|---|---|
| `m_sys` | 系统管理 | `system` | `0` | 1 | setting | 1 |
| `m_user` | 用户管理 | `system/User` | `m_sys` | 2 | — | 2 |
| `m_role` | 角色管理 | `system/Role` | `m_sys` | 2 | — | 3 |
| `m_org` | 机构管理 | `system/Organize` | `m_sys` | 2 | — | 4 |
| `m_menu` | 菜单管理 | `system/Module` | `m_sys` | 2 | — | 5 |
| `m_demo` | Demo 示例 | `demo-item` | `0` | 2 | app | 6 |
| `m_product` | 产品管理 | `shop/Product` | `0` | 2 | app | 7 |
| `m_book` | 图书超市 | `books/Book` | `0` | 2 | app | 8 |
> ⚠️ `perm-smoke.sh` 在 react 版里是**从 `seed.service.ts` 的字面量动态算期望菜单树**的。
> Rust 版没有那个文件 ⇒ **两种做法二选一**:
> (a) 把上表搬进冒烟脚本作为字面量;或 (b) 后端暴露一个只读端点/二进制子命令打印期望树。
> **推荐 (a)**:脚本自包含、离线可跑。菜单增删时同步改脚本(这是**刻意的耦合**,不是缺陷)。
**两段式种子**(`sys/seed.service.ts`):
- `ensureBase`(**每次启动都跑**,幂等):按 `enCode` 补内置角色、按 `urlAddress` 补内置菜单、
补齐 admin 角色对内置菜单的授权(取库里**真实行 id**)。
**只补缺项**:不覆盖已改值;**同 urlAddress 已有行(含软删)不复活**。
- `firstSeed`(**仅 users==0 时跑一次**):`admin/123456`(`f_is_administrator=1`, `f_organize_id='0'`)
+ 一条 `base_role_relation`(`object_type='user'`, `object_id='admin'`, `role_id='role_admin'`)。
角色/菜单/授权行已由 `ensureBase` 建出,**不重复写**。
### 3.3 后端模块划分
| 模块 | 职责 | 备注 |
|---|---|---|
| `main.rs` | 启动装配:开库 → 起 schema → seed → 建路由 → 挂中间件 → 监听 | `with_state` 必须是最后一步 |
| `config.rs` | `PORT` / `PGLITE_DIR` / 静态目录 / 种子开关 | 环境变量 |
| `db.rs` | pglite 封装:`query_json()` / `query_rows()` / `exec()` / `ensure_schema()` / `valid_table()` | 单 backend ⇒ 进程级 `db_lock` |
| `cipher.rs` | `md5_hex()` / `encrypt_password()` / `decrypt_to_md5()` | **逐字对齐 `cipher.ts`** + 上游向量单测 |
| `envelope.rs` | `ActionResult{code,msg,data}` + `ok/fail/fail_code` | 业务失败恒 HTTP 200 |
| `ids.rs` | `new_uuid()` → 36 位 UUID v4 | **不是** tdc-rs 的雪花 |
| `session.rs` | 内存 token 表(`lite-` 前缀 + 32 hex) | 进程重启即失效 |
| `auth.rs` | 登录 / CurrentUser / `require_login()` / `require_module()` | 守卫返回 `ActionResult`(600 / 403) |
| `permission.rs` | `resolve_user_module_ids()` 四源合并 / `has_module()` 管理员短路+未映射放行 / `build_menu_list()` | **四源 + 两条放行路径都要有测试** |
| `seed.rs` | `ensure_base()` + `first_seed()` | 幂等 + 只补缺项 |
| `sys.rs` | 5 组 `base_*` 的显式 handler 语义 | 用户/角色/机构/菜单/授权 |
| `crud.rs` | spec 驱动的通用 CRUD(List/Save/Delete) | 业务实体用 |
| `entities.rs` | 业务实体 spec 表(表名 / 列 / 类型 / 数值列 / 守卫菜单 key) | 加业务模块 = 加一条 spec |
| `routes.rs` | 路由装配 | |
### 3.4 三个关键取舍
1. **业务实体走 spec 引擎,`base_*` 走显式 handler。**
理由:业务模块语义同构(列表/保存/软删/守卫),声明化后"加一个模块 = 加一条 spec";
而 `base_*` 的语义(一维授权数组、用户↔角色关系、机构树防环、账号唯一性)**塞不进通用引擎**,
硬塞会得到一个既不懂 JNPF 又难懂的框架。
2. **numeric 列在 SQL 投影里就 cast 成 text。**
理由:`row_to_json` 直接给数字 ⇒ serde_json 解析成 f64 ⇒ 回显 `9.9` ⇒ 契约破。
在投影层 `f_price::text AS price` 才是"一次解决、处处一致"。
3. **HTTP 状态语义**刻意**不同于** `tdc-rs`(那边是 401/403 裸 body,这边是 200 + code 600/403)。
理由:react 前端的拦截器只认 `body.code`;两边同时跑时更不能混形状,否则冒烟脚本得写两套。
### 3.5 前端
- **逐字复制** `ssw-jnpf-lite-react/src/frontend` → `src/frontend`(`package.json` / `vite.config.ts` / `src/**`)。
- **唯一允许的改动**:vite 的 proxy 目标端口 `30000 → 30010`(以及 `baseURL` 仍是 `/api`,不变)。
- 前端 `utils/cipher.ts` **保持不变**(它是浏览器侧算法;后端 Rust 侧必须与它**逐字节等价**——由上游向量钉住)。
- 路由 path(`App.tsx`):`/login` `/demo-item` `/shop/Product` `/books/Book`
`/system/User` `/system/Role` `/system/Organize` `/system/Module`
⇒ **去掉前导斜杠**就是 `base_module.f_url_address` ⇒ 也是后端守卫的 module key。**三处一字不差。**
### 3.6 目录/文件对照(react 技能 → 本仓)
| react 技能 | 本仓 |
|---|---|
| `src/backend/src/common/cipher.ts` | `src/backend/src/cipher.rs` |
| `src/backend/src/common/action-result.ts` + `.filter.ts` | `src/backend/src/envelope.rs` |
| `src/backend/src/auth/*` | `src/backend/src/auth.rs` |
| `src/backend/src/sys/permission.service.ts` | `src/backend/src/permission.rs` |
| `src/backend/src/sys/seed.service.ts` | `src/backend/src/seed.rs` |
| `src/backend/src/sys/sys.service.ts` | `src/backend/src/sys.rs` |
| `src/backend/src/{demo,shop,books}/*` | `src/backend/src/entities.rs` + `crud.rs` |
| `src/backend/db/schema.sql` | `src/backend/db/schema.sql`(**本仓要写全 10 张表**) |
| `src/frontend/**` | `src/frontend/**`(逐字复制) |
| `scripts/perm-smoke.sh` | `scripts/perm-smoke.sh`(移植,cipher 改用 `--enc`) |
| `scripts/check-module.sh` | `scripts/check-module.sh`(移植,grep 模式按 Rust 调整) |
| `run.sh` | `run.sh`(改成 cargo 版本) |
---
## 4. 四道验收门("做完"的唯一判据)
| 门 | 命令 | 通过标准 |
|---|---|---|
| ① 编译 | `cargo build --release` | 0 error 0 warning;release 配置照 tdc-rs(`opt-level=2` / `lto="thin"` / `strip="symbols"` / `panic="abort"` / `codegen-units=16`) |
| ② 单测 | `cargo test` | 覆盖:cipher 上游向量 · 信封形状(200/400/600/403)· 四源合并 · 管理员短路 · 未映射放行 · 种子幂等(跑两次结果一致 + 不复活软删行)· CRUD 往返(36 位 UUID / numeric→`"9.90"` / int→`100`)· 账号重复返 400 而非 500 |
| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **22+ 条断言全绿**(FAIL=0),与 react 版断言集**逐条对应**(见 §5 步骤 11 的清单) |
| ④ 前端手验 | `cd src/frontend && npm run dev` | 浏览器 `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
**外加**:`scripts/check-module.sh`(9 接触点静态自检)的 Rust 版移植,作为"加模块后立刻跑"的前置闸门。
---
## 5. 建议实施顺序(step 0–12)
> 每步都带**完成判据**。做完一步先跑该步的判据,再进下一步。
| step | 内容 | 完成判据 |
|---|---|---|
| **0** | 建 **cargo workspace**(根 `Cargo.toml`:`[workspace] members=["src/backend"]` + `[profile.release]`)+ 成员 crate(依赖照 tdc-rs:axum 0.8 / tokio / tower-http 0.6 / serde / serde_json / serde_urlencoded 0.7 / rand 0.8 / hex 0.4 / aes 0.8 / ecb 0.1 / md-5 0.10 / uuid v4 / pglite-rs 0.2 / chrono 0.4) | 根目录 `cargo build` 通过(哪怕是空 main) |
| **1** | `src/cipher.rs` + 单测 | 上游向量**逐字节**相等;`md5_hex` 与 `decrypt_to_md5` 往返一致 |
| **2** | `src/envelope.rs` + 单测 | 业务失败 HTTP 200 + `code=400`;`code=600/403` 同形 |
| **3** | `src/db.rs` + `src/config.rs` + `db/schema.sql`(10 张表) | 进程能开库并建表;`query_json()` 能取回 JSON |
| **4** | `src/ids.rs` + `src/session.rs` | UUID 36 位带连字符;token 登录后可查回 |
| **5** | `src/seed.rs`(`ensure_base` + `first_seed`) | 空库启动 ⇒ admin/123456 + 2 角色 + 8 菜单 + admin 授权;**再启动一次库内容不变** |
| **6** | `src/permission.rs` + 单测 | 四源合并各源单独可注入;管理员短路**不查 SQL**(可用「无授权记录的管理员仍放行」验证);未映射菜单放行 |
| **7** | `src/auth.rs` + `/api/oauth/*` | 登录返 `{token,expiresIn:7200,tokenTypeName:'bearer'}`;CurrentUser 返 `{userInfo,menuList}`;无 token ⇒ `code=600` |
| **8** | `src/sys.rs` + `/api/ssw/sys/*` + `/api/permission/Authority/*` | 5 组 CRUD 语义对齐;**重复账号返 `code=400` + msg `'账号已存在:xxx'`**(不是 500);授权写 `objectType='role'` 小写 + 一维数组 |
| **9** | `src/entities.rs` + `src/crud.rs` + 3 个业务模块端点 | demo/shop/books 三个模块端点可用;numeric 往返 `"9.90"`;未授权非管理员访问 shop/books ⇒ `code=403` |
| **10** | `src/routes.rs` + `main.rs` 装配 + 404/405 兜底 | 未知路由 **HTTP 404** + `code=404`;405 返回 JSON;`with_state` 在链尾 |
| **11** | `scripts/perm-smoke.sh` 移植(**逐条对应 react 版**) | 22+ 断言全绿 |
| **12** | 前端复制 + `run.sh` + `.env.example` + 文档 | 门④ 手验全过;`run.sh install/build/dev/stop/logs` 可用 |
**step 11 的断言清单**(照 react 版 `scripts/perm-smoke.sh` 逐条移植):
1. 无 token 访问 `User/List` ⇒ `code=600`
2. 加密登录 ⇒ `code=200`;3. 拿到 token(非空)
4. `CurrentUser` ⇒ `code=200`
5. 菜单树与种子表**逐字相等**(推荐做法:把 §3.2 的菜单表搬进脚本作字面量)
6. 建用户 ⇒ `code=200`
7. **重复账号** ⇒ HTTP **200**(不是 500)且 `code=400` 且 msg `'账号已存在:smoke_user'`
8. 写授权(一维数组)⇒ `code=200`;9. 写授权(二维兼容)⇒ `code=200`
10. 非管理员登录 ⇒ `code=200`
11. 非管理员菜单**已收窄**(字符串比对)
12. 非管理员访问 `User/List` ⇒ `code=403`
13. 已授权业务(demo)⇒ `code=200`
14. 未知路由 ⇒ **HTTP 404**(不被吞掉)
15. admin 短路 ⇒ Product 列表 `code=200`
16. Product 新建 ⇒ `code=200`;17. 主键 **36 位**;18. numeric 往返 **`"9.90"`**
19. Product 无 token ⇒ `code=600`;20. 未授权非管理员 ⇒ `code=403`
(react 版共 22+ 条,上表是主干;移植时以 react 脚本为准逐条对齐,**一条不落**。)
**另外**:`scripts/check-module.sh`(9 接触点静态自检)移植为 Rust 版——
把「grep TS 文件里的字符串」换成「grep Rust 源 + 检查 spec 注册」,保持同样的 ❌ 判定与退出码约定
(0 全过 / 1 有 ❌ / 2 用法错)。
**脚本退出码约定**(三个入口一致,照抄 react 技能):
| 入口 | 0 | 1 | 2 |
|---|---|---|---|
| `run.sh` | 执行成功 | 运行期失败 | 用法错 |
| `scripts/check-module.sh` | 接触点全过 | 有 ❌ 项 | 用法错 |
| `scripts/perm-smoke.sh` | 全绿(FAIL=0) | 有断言失败 | 前置错误(后端不可达) |
---
## 6. 必读参考文件(绝对路径)
### 契约真源(react 技能,**只读**)
```
~/Desktop/workspace/skills/ssw-jnpf-lite-react/
├── src/backend/src/common/cipher.ts ← cipher 算法 + 检验向量
├── src/backend/src/common/action-result.ts ← {code,msg,data}
├── src/backend/src/common/action-result.filter.ts ← HTTP 状态映射(200/404 的来源)
├── src/backend/src/auth/auth.controller.ts ← 登录 / CurrentUser 端点与文案
├── src/backend/src/auth/auth.service.ts ← 口令比对、token 生成
├── src/backend/src/sys/permission.service.ts ← 四源合并 + 管理员短路 + 未映射放行 + 菜单树
├── src/backend/src/sys/seed.service.ts ← roles/menus 字面量 + 两段式种子
├── src/backend/src/sys/sys.service.ts ← 5 组 base_* CRUD 语义
├── src/backend/src/sys/authorize.controller.ts ← 授权写/读 + 一维 module 归一化
├── src/backend/src/sys/base-*.entity.ts ← 7 张表的列 ↔ JSON 键映射
├── src/backend/src/{demo,shop,books}/* ← 业务模块参照实现
├── src/frontend/src/api/{request,auth,sys,product,book}.ts ← 前端实际调用的端点
├── src/frontend/src/App.tsx ← 前端路由 path(= urlAddress)
├── src/frontend/src/utils/cipher.ts ← 浏览器侧 cipher(后端必须等价)
├── scripts/perm-smoke.sh ← 断言集(逐条移植)
├── scripts/check-module.sh ← 9 接触点静态自检
└── run.sh ← 脚本骨架(改成 cargo 版)
```
### 官方 JNPF(数据模型真源,**只读**)
```
~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql
base_authorize :812
base_module :2209
base_organize :3178
base_role :3686
base_role_relation :3729
base_user :4479
base_user_relation :4707
(另有 base_module_{authorize,button,column,data,form,link,scheme,use_num}、
base_organize_administrator、base_user_{device,extra,old_password} —— v1 不做)
同目录还有 jnpf_db_init.sql(base_user 的 INSERT 可二次确证列名)等 9 个 init 文件
```
### 工程手法参考(tdc-rs,**只读**、不共享代码)
```
~/Desktop/workspace/tdc-rs/src/cipher.rs ← cipher 的 Rust 版逐字实现 + 坑位注释
~/Desktop/workspace/tdc-rs/src/envelope.rs ← 信封形状
~/Desktop/workspace/tdc-rs/src/db.rs ← pglite 封装 / query_json / valid_table
~/Desktop/workspace/tdc-rs/src/main.rs ← resolve_project_dir / 404 兜底 / with_state 收口
~/Desktop/workspace/tdc-rs/src/routes/mw.rs ← 405 JSON 兜底中间件
~/Desktop/workspace/tdc-rs/Cargo.toml ← release 配置
```
---
## 7. 风险与坑(开工前先知道)
| 风险 | 表现 | 处置 |
|---|---|---|
| **pglite 单实例独占数据目录** | 第二个进程起不来(`postmaster.pid` 锁) | 换数据目录/端口;集成测试串行或各用独立目录 |
| **pglite 体积** | debug 二进制 ~35 MB(内嵌 PG 引擎) | 与 tdc-rs 同量级,可接受 |
| **cipher 的 ASCII-hex key 坑** | 一旦当 16 字节摘要用 ⇒ AES-128 ⇒ 登录全挂 | 单测钉死上游向量(步骤 1) |
| **numeric 变 9.9** | 前端金额显示错、冒烟第 18 条红 | 投影层 `::text`(步骤 9) |
| **`base_role_relation` 无 `f_user_id`** | 角色授权不生效 | 建表时逐字照官方 DDL(步骤 3) |
| **npm 装 esbuild 被拦** | vite 起不来 / 端口 000 且报错不指根因 | `npm install-scripts approve esbuild` 后在 `src/frontend` 重跑 `npm install` |
| **前端端口** | macOS 上 `localhost:5173` 失败 | 用 `127.0.0.1:5173`(vite 模板固定 bind IPv4) |
| **冒烟脚本依赖 node** | 换机器跑不了 | Rust 侧 `--enc` 自证(步骤 11) |
| **权限"看起来生效"其实没测到** | 返回了数据 ≠ 权限生效(管理员短路/菜单没映射/未清缓存/异常降级放行,**四条路径全是放行**) | 必须以「**菜单收窄 + 403 拦截**」为判据 |
---
## 8. 开放问题(开工时按需裁决,不阻塞)
1. **`git` 首个 commit 何时做** —— 目录已 `git init` 但**未 commit**。建议步骤 0 结束就 commit 一次骨架。
2. ~~**Cargo workspace 还是单 crate**~~ —— ✅ **已定:workspace**。
根 `Cargo.toml` = `[workspace] members = ["src/backend"] resolver = "2"` + `[workspace.dependencies]` +
`[profile.release]`(**release profile 只在 workspace 根生效**,别写到成员里);
`src/backend/Cargo.toml` = 成员 crate(crate 名 `tds-lite-rs`,`src/main.rs` 在 `src/backend/src/main.rs`)。
理由:保持目录与 react 版对齐 ⇒ 抽技能时 1:1 复制。
3. **`--enc` 子命令的参数形式** —— 建议 `./tds-lite-rs --enc 123456`(打印 hex 到 stdout,退出码 0);
未知参数按 `--help` 处理。
4. **是否需要 `/api/health`** —— react 版没有。**建议加**(`{ok, tables, version}`),便于冒烟探活,但**不是契约**。
5. **抽技能的目标目录名** —— 建议 `ssw-jnpf-lite-rust`,落在 `~/Desktop/workspace/skills/`,
与 `ssw-jnpf-lite-react` 并列。**验收全绿后再做。**
---
## 9. 交接话术(交付态:这个仓是什么、怎么跑、怎么复现验收)
> 读 `CLAUDE.md` + `HANDOFF.md`(本文件)。**设计已定稿且已实现完毕,不要重新设计、不要重写。**
### 一句话
`tds-lite-rs` = **JNPF 兼容契约的 Rust 实现**(单二进制、零外部服务:Rust 2021 + axum 0.8 +
pglite-rs 0.2 进程内原生 PostgreSQL;10 张表、27 条路由)。
**状态:v1 已完成,四道验收门全绿**(见 §0)。
### 怎么起
```bash
cd ~/Desktop/workspace/tdc-lite-rs
bash run.sh install # 一次性:cargo fetch + npm --prefix src/frontend install
bash run.sh build # 一次性:cargo build --release + vite build
bash run.sh dev # 日常:后台起后端(30010) + 前端(5173)
```
- 前端:**http://127.0.0.1:5173**(vite dev server,`/api` 代理到后端)
- 后端:**http://127.0.0.1:30010**
- 账号:**`admin` / `123456`**(首次启动自动种子)
- `bash run.sh logs` 看日志(`.logs/backend.log`、`.logs/frontend.log`);`bash run.sh stop` 停(幂等)
- 🔴 `run.sh` 的 `kill_ports` 是 `kill -9` ⇒ 只清 **30010 / 5173**,**绝不碰兄弟项目 `tdc-rs` 的端口**
- 🔴 打 localhost 用 curl **必须**加 `--noproxy '*'`(本机 curl 走系统代理)
### 怎么复现验收(四门,逐字命令 + 通过标准)
| 门 | 命令 | 通过标准 |
|---|---|---|
| ① 编译 | `cargo build --release` | **0 error 0 warning** |
| ② 单测 | `cargo test` | **177 passed / 0 failed**(8 个测试目标:63+6+19+24+3+18+7+37) |
| ③ 冒烟 | `bash scripts/perm-smoke.sh`(后端先起在 `:30010`) | **PASS=32 FAIL=0**,退出码 0 |
| ④ 前端手验 | `bash run.sh dev` ⇒ 浏览器开 `http://127.0.0.1:5173` | `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → 3 个业务页可用 → 退出再登录 |
外加前置闸门:`bash scripts/check-module.sh`(9 接触点静态自检,纯静态、零 node 依赖;
期望 `PASS=55 FAIL=0`;无参 ⇒ 查全部三个业务模块)。
> 门④ 的浏览器手验清单(逐条):
> 1. `admin/123456` 登录 ⇒ Dashboard 出现「功能菜单」;
> 2. 菜单树 = 系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市;
> 3. 4 个管理页(用户/角色/机构/菜单)从菜单按钮进入,页面标题正确,且**可增删改**;
> 4. 3 个业务页(DemoItem / Product / Book)可达、可增删;
> 5. 退出 ⇒ 回登录页 ⇒ 再登录 ⇒ 仍正常。
>
> ⚠️ 已知:**react 版 Dashboard 只渲染「目录的子项」**(`node.children`)⇒
> Demo 示例 / 产品管理 / 图书超市是**顶层页面型菜单**(`parentId='0'`,无子项)⇒
> **Dashboard 里没有按钮**,只能按 URL 直达(`/demo-item`、`/shop/Product`、`/books/Book`)。
> 这是**参照物原样行为**(前端逐字复制 ⇒ 本仓未改),**不是本仓的 bug**。
### 已知限制(分支级)
摘自 ledger(`.superpowers/sdd/tds-lite-rs-v1/progress.md`)的「分支级已知限制清单」:
- **(k)** release 二进制**没有** catch-all 的自动化覆盖(触发 panic 的端点是 `#[cfg(test)]` 专属;
catch-all 中间件代码在测试构建与 release 构建里**逐字相同**,且 release profile **无** `panic = "abort"` ⇒ 行为等价)。
- **(l)** `Path<String>` 遇**畸形百分号编码** ⇒ axum 默认返**纯文本 400(非信封)**(handler 签名由契约 §S17 定死,改它要动 `sys.rs`)。
- **(m)** 冒烟脚本**每次跑**会往库里留一行 `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user`
(react 同款行为;契约 §13 未要求清理 ⇒ 不改)。
- **(n)** 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file`(观感,判据不受影响)。
- **(o)** 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的**前置提示文案**不同
(`code=无` vs `code=ERR`),退出码都是 2。
本任务(Task 12)另记两条**已观察、未改**的观察(留给最终整体评审裁决):
- **react 版 Dashboard 只渲染「目录的子项」** ⇒ 3 个顶层业务页在菜单里**没有入口按钮**(只能按 URL 直达)。
前端是**逐字复制** ⇒ 改它会破「除代理端口外一字不改」的硬约束 ⇒ **不改**,只记档。
- `src/frontend/vite.config.ts` 的注释仍写着「转发到 **NestJS** 后端(30010)」——
本仓后端是 **Rust**。该注释行属于「代理目标行 + 紧邻注释行」两行允许改动范围,
但 brief 只授权把端口 `30000 → 30010` ⇒ 框架名**逐字保留**,**不「顺手修好」**(最终评审按 Minor 记)。
### 下一步(按 plan)
验收四门全绿 ⇒ **下一步是把本仓 1:1 复制成技能 `ssw-jnpf-lite-rust`**,
落在 `~/Desktop/workspace/skills/`,与 `ssw-jnpf-lite-react` 并列
(技能资产形态 = 本仓 1:1 复制;目录结构已刻意与 react 版对齐)。