Files
ssw-platform/docs/README-project.md
T
admin a27389d0d0 docs: 补《编译膨胀问题及处理》—— target/ 58G 的根因、处置与规矩
新增 docs/build-bloat.md,记录 2026-11-03 这次磁盘膨胀的完整处置:

- 现象:target/ 58G(deps 45G + incremental 12G + release 820M),磁盘 87%
- 根因:cargo 默认传 -C incremental=…,而 sccache 遇 incremental 直接拒缓存
  (server 端日志 CannotCache(incremental))⇒ 8.4G 缓存全是废的,每轮从零重编
- 处置:根 Cargo.toml 加 [profile.dev] incremental = false + cargo clean
- 结果:58G → 1.2G;清空后重建 63s → 14.14s(缓存命中,命中率 86.71%);
  磁盘 87% → 75%(跑完测试后 76%)
- 定位方法论:发现 sccache 命中率异常时看 server 端日志
  (SCCACHE_LOG=debug + SCCACHE_ERROR_LOG),client 端统计只说「没命中」
- 区分表:哪些是编译中间产物(该清)、哪些不是(node_modules / pglite 数据,
  按既定约定不动)
- 沉淀 6 条规矩(清前 pgrep、用 cargo clean 而非 rm -rf、sccache 缓存不在项目内、
  改 profile 要重新体检 target 体积等)

索引同步:docs/README-project.md(链接区 + 目录树)、README.md(目录树)。

验证:check-citations 4/4、check-naming 3/0/1、check-arch 20/20、
check-boundary 12/12、check-contract 10/10、check-module 123/123 全绿。
2026-11-03 23:11:26 +08:00

155 lines
10 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.
# ssw-jnpf-lite-rust
**JNPF 兼容契约的 Rust 实现** —— 单二进制、零外部服务(进程内原生 PostgreSQL)。
它的存在意义只有一条:**让「用 Rust 写业务」和「迁回官方 JNPF(Java)」之间是机械翻译,而不是重写。**
为此本仓的**数据模型(`base_*` 表名/列名/语义)与 HTTP 契约**从第一天起就锁死成官方 JNPF 的形状。
本仓是**双面后端**:**同一进程**同时提供
**面 A**(ssw/react 契约,27 条路由,冻结)与 **面 B**(官方 JNPF 契约,5 条路由 + 2 条共用路由按 `Vue-Version: 3` 分流),
共用同一套 `base_*` 表 / cipher / seed,但**权限判据不同**(面 A 按菜单路径 / 面 B 按 `f_en_code` 点权限)。
⇒ 既是「Rust ⇒ 官方 JNPF」的**可移植性验证床**,也是「官方 JNPF / React 版 ⇒ 打到本框架跑」的**对照靶场**。
- 📘 **契约唯一真源**:[`docs/contract.md`](contract.md) —— 与本文件冲突时以契约为准。
- 🧭 **agent 指引**:[`CLAUDE.md`](../CLAUDE.md)(红线 / 踩坑 / 端点全表)· [`HANDOFF.md`](../HANDOFF.md)(交接)。
- 🛠 **怎么起 / 怎么冒烟 / 常见故障**:[`docs/runbook.md`](runbook.md)。
- 💾 **编译膨胀问题及处理**:[`docs/build-bloat.md`](build-bloat.md)(`target/` 58G → 1.2G 的根因、处置与规矩)。
- 🧾 **实施期裁决(98 条「什么—为什么—代价」)**:[`docs/decisions.md`](decisions.md)
· **分支级已知限制**:[`docs/known-limitations.md`](known-limitations.md)。
---
## 快速开始
```bash
# 一次性:装依赖(cargo fetch + npm install)+ 构建(cargo build --release + vite build)
bash run.sh install
bash run.sh build
# 日常:后台起后端(30010) + 前端(5173),日志在 .logs/,PID 在 .run/
bash run.sh dev
# 前端 http://127.0.0.1:5173 后端 http://127.0.0.1:30010
# 账号 admin / 123456
# (**后端与前端都就绪**才算成功;任一没就绪 ⇒ 退出码 1 并打印对应日志尾部)
bash run.sh stop # 停(幂等)
bash run.sh logs # 看日志尾部
```
| 端口 | 谁 | 说明 |
|---|---|---|
| `30010` | 后端(Rust) | **硬约定**:`run.sh` 的端口不许改 —— `PORT` ≠ 30010 时 `run.sh dev` / `run.sh backend` 报错退出 2(要换端口请**直接跑二进制**)。**后端二进制本身**吃 `PORT`(非法值回落 30010)。默认**只监听 `127.0.0.1`**;`BIND_ADDR=0.0.0.0` 才对外暴露 |
| `5173` | 前端(vite dev) | `strictPort: true` ⇒ 端口被占直接报错,不自动换端口 |
---
## 目录
```
ssw-jnpf-lite-rust/
├── Cargo.toml # cargo workspace 根(成员 = src/backend)+ release profile
├── run.sh # install / build / dev / backend / frontend / stop / logs
├── .env.example # PORT / BIND_ADDR / PGLITE_DIR(PGLITE_DIR 只能写绝对路径或 memory://)
├── src/backend/ # Rust 后端(axum 0.8 + pglite-rs 0.2,10 张表,32 条路由 = 面 A 27 + 面 B 5)
├── src/frontend/ # react 技能前端**逐字复制**(只改 vite 代理端口 30000 → 30010)
├── scripts/perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖)—— 面 A 尺子
├── scripts/perm-smoke-jnpf.sh # 官方 JNPF 形状冒烟(18 条断言)—— 面 B 尺子(**已全绿 18/18**)
├── scripts/smoke_backend.sh # 两把尺子的「隔离后端」自启动助手(默认自起 ⇒ CI 可跑)
├── scripts/check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端)
└── docs/ # contract.md(契约)· runbook.md(运维)· decisions.md(裁决)· known-limitations.md(已知限制)
# build-bloat.md(编译膨胀问题及处理)
# JNPF_SOURCE_AUDIT.md(官方源码逐行核对)· JNPF_COMPAT_SURFACE.md(面 B 规格)· MIGRATION.md(迁移指南)· ddl/
```
---
## 它做了什么(v1 = 全量契约对齐)
- **登录 / `CurrentUser`**:`POST /api/oauth/Login`(form-urlencoded,密文 hex)⇒ `{token, expiresIn:7200, tokenTypeName:'bearer'}`;
`GET /api/oauth/CurrentUser` ⇒ `{userInfo, menuList}`。
- **5 组 `base_*` 管理 CRUD**:用户 / 角色 / 机构 / 菜单 / 授权。
- **统一授权**:`PUT /api/permission/Authority/Data/{objectId}`(body `{objectType:'role', module:[...]}`,**小写 + 一维数组**)。
- **四源权限合并**:用户直授 + 角色 + 组织 + 岗位;**管理员在任何 SQL 之前短路放行**;**菜单未映射 ⇒ 放行**。
- **两段式种子**:`ensure_base`(每次启动补内置角色/菜单/授权)+ `first_seed`(仅首次建 `admin/123456`)。
- **3 个业务模块**(spec 驱动 CRUD 引擎):`demo/DemoItem` · `shop/Product` · `books/Book`。
### 契约红线(摘要,完整版见 `CLAUDE.md`)
1. **业务失败一律 HTTP 200 + `{code,msg,data}`**;成败只看 body 的 `code`。
唯一例外:**未知路由 = HTTP 404**(body 仍是信封)。鉴权失败也是 200(`600` 未登录 / `403` 无菜单权限)。
2. **`base_*` 表名/列名逐字对齐官方 JNPF DDL**(含两个「故意不修正」的陷阱,见 `CLAUDE.md`)。
3. **numeric 列必须是 JSON 字符串**(`"9.90"`,不是 `9.9`);int 列保持数字。
4. **口令不得外泄**:库里存 `md5(明文)`,对外响应手工挑字段(用户列表去掉 `password`)。
5. **schema DDL 绝不可从 HTTP 下载**。
---
## 验收门
| 门 | 命令 | 通过标准 |
|---|---|---|
| ① 编译 | `cargo build --release` | 0 error **0 warning** |
| ② 单测 | `cargo test` | 全绿(当前 **197 passed / 0 failed**) |
| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **PASS=32 FAIL=0**(🔴 **后端不用先起** —— `:30010` 不通 ⇒ 尺子自起隔离实例,跑完即删) |
| ③' 冒烟(面 B) | `bash scripts/perm-smoke-jnpf.sh` | **PASS=18 FAIL=0 SKIP=0**(**已达标**;同样默认自起隔离实例) |
| ④ 前端手验 | `bash run.sh dev` | `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
外加:`bash scripts/check-module.sh`(9 接触点静态自检)—— 加业务模块后立刻跑的前置闸门。
### 第二把尺子(面 B:官方 JNPF 形状)
```bash
bash scripts/perm-smoke-jnpf.sh # 18 条断言,打印「面 B 覆盖 N/18」
```
**面 B = 官方 JNPF 契约面**(官方形状的端点 / 响应 / 码表),规格见 `../JNPF_COMPAT_SURFACE.md`。
✅ **已落地**(`src/backend/src/platform/jnpf.rs`,S1–S6 全完成)⇒ 当前报 **`PASS=18 FAIL=0 SKIP=0`(面 B 覆盖 18/18)**。
面 B 的判别头是 **`Vue-Version: 3`**(官方前端必发,本仓前端**唯一不发**的一头 ⇒ 零歧义)。
面 A 27 条路由**冻结**、面 B 5 条新增 ⇒ **同一进程**同时提供两套契约。
> 本机 curl 走系统代理 ⇒ 打 localhost **必须**加 `--noproxy '*'`。
---
## 三个参照物(各司其职,别混)
| 参照物 | 地位 |
|---|---|
| 官方 JNPF 源码 + DDL(`~/Desktop/workspace/jnpf/`) | **数据模型真源**(`base_*` 表名/列名) |
| `ssw-jnpf-lite-react` 技能(`~/Desktop/workspace/skills/ssw-jnpf-lite-react/`) | **行为真源**(NestJS 版把契约跑起来了);本仓前端是它的**逐字复制** |
| `tdc-rs` 兄弟项目(`~/Desktop/workspace/tdc-rs/`) | **只抄工程手法**;不共享代码 / 端口 / 数据目录 |
---
## 已知限制(分支级)
- **面 B 的 10 条已知偏差**(B1–B10,逐条见 `../JNPF_COMPAT_SURFACE.md` §8 与 `docs/known-limitations.md` §H):
授权读 `list` 返空数组 · `sysConfigInfo` 返 `{}` · `currentSystemId` 固定 ·
**无按钮/列/表单/数据级权限** · 三个业务菜单的 `f_en_code` 是自拟占位 ·
`permissionList` 粒度 = 每菜单一条(`modelId` = 菜单 id)· `Organize/AsyncList` 未分页。
- **口令存储缺官方 `secretkey` 一步**:本仓存 `md5(明文)`,官方存 `md5(md5(明文)+secretkey)`。
迁官方时**一次性换算**即可,**不需要明文**(见 `../MIGRATION.md` §7)。
- **两套权限判据并存**:面 A 按菜单路径(`f_url_address`)、面 B 按点权限编码(`f_en_code`)。
⇒ 同一用户可能**面 A 通、面 B 拒**(这是设计,不是 bug);种子菜单已补 `f_en_code`(8 条),
业务菜单的 `f_en_code` 仍是自拟值,迁官方前须换成官方真实编码。
- **release 二进制没有 catch-all 的自动化覆盖**:触发 panic 的端点是 `#[cfg(test)]` 专属;
catch-all 中间件代码在测试构建与 release 构建里逐字相同,且 release profile **无** `panic = "abort"` ⇒ 行为等价。
- **`Path<String>` 遇畸形百分号编码** ⇒ **实测 axum 0.8.9 接受该转义**:`PUT /api/permission/Authority/Data/%zz`
返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**(信封,正常)⇒ **不存在**「返非信封 400」这种破口。
- **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**):
登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**
(进程不重启就永不过期);契约未覆盖 TTL ⇒ 不改。
- **冒烟脚本每次跑会往库里留一行** `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user`(react 同款行为,契约未要求清理)。
🔴 **但只在「复用外部后端」时**:尺子**默认自起隔离实例**(临时数据目录)⇒ 跑完即删、**不留脏数据**、
两把尺子**互不污染**、**CI 可跑**;显式给了 `B` 才打外部库。
- 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file`(观感,判据不受影响)。
- 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的前置提示文案不同(退出码都是 2)。
---
## 技术栈
Rust 2021 · axum 0.8 · tokio · pglite-rs 0.2(进程内原生 PostgreSQL,零服务/零 Docker/零 WASM)·
aes 0.8 + ecb 0.1 + md-5 0.10 · React 18 + Vite 5(逐字复用)