Files
ssw-jnpf-lite-rust/HANDOFF.md
T
adminandClaude 0aed12a102 docs: 契约规格 + 实施计划 + 官方 base_* DDL 原文
- docs/contract.md: 唯一规格来源(信封/cipher/端点/权限/种子/验收门)
- docs/ddl/base_ddl_raw.sql: 从官方 JNPF dump 逐字提取的 7 张 base_* DDL
- CLAUDE.md / HANDOFF.md: 项目级 agent 指引与交接文档

Co-Authored-By: Claude <[email protected]>
2026-10-25 17:05:00 +08:00

361 lines
25 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. 当前状态
| 项 | 状态 |
|---|---|
| 目录 `~/Desktop/workspace/tds-lite-rs/` | ✅ 已建(`git init` 已做,**未 commit**) |
| `CLAUDE.md` | ✅ 已写(项目级 agent 指引:红线 / 坑位 / 端点全表 / 数据模型) |
| `HANDOFF.md`(本文件) | ✅ 已写 |
| 代码 | ⬜ **零行**。`src/` `scripts/` `Cargo.toml` `schema.sql` 都还没有 |
| 前端 | ⬜ 还没复制(`ssw-jnpf-lite-react/src/frontend` → 本仓 `src/frontend`) |
| 设计 | ✅ 已定稿(见 §3),**不要再重新设计** |
**开工前先读**:`CLAUDE.md`(红线与坑位)→ 本文件 §3(设计)→ §5(实施顺序)。
§4 的四道验收门是"什么算做完"的唯一判据。
---
## 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`(本文件)。设计已定稿,**不要重新设计**。
> 从 **step 0** 开始按 §5 顺序实施,每步先跑该步的完成判据。
> 参照物:`ssw-jnpf-lite-react`(契约真源,只读)、`jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql`(数据模型真源,只读)、
> `tdc-rs`(工程手法参考,只读,**不改**)。四道验收门见 §4,全部绿了才算完成。