From ecb77b230f06c9bf72013eedc8043a4d508ee6da Mon Sep 17 00:00:00 2001 From: admin Date: Wed, 4 Nov 2026 21:54:22 +0800 Subject: [PATCH] =?UTF-8?q?=E5=B9=B3=E5=8F=B0=E5=8C=85=E9=9B=B6=E4=B8=9A?= =?UTF-8?q?=E5=8A=A1=EF=BC=9A=E7=A4=BA=E4=BE=8B=E7=A7=BB=E5=88=B0=E6=8A=80?= =?UTF-8?q?=E8=83=BD=E4=BB=93=E3=80=81=E8=A7=A3=E7=BB=91=20example-packs?= =?UTF-8?q?=E3=80=81=E9=97=B8=E9=97=A8=E5=85=A8=E9=83=A8=E6=94=B9=E9=98=B2?= =?UTF-8?q?=E5=9B=9E=E6=B5=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 物理移出 packs/{asset,books,demo,shop}、modules/ 四个面 A 适配器、纯技能副本、 纯业务测试 crud_it.rs 与 new-pack 脚手架(v0.3.0 tag 完整保留旧形态)。 - 删 example-packs feature / example_packs() / sspf-pack-* 依赖 / packs/* member; packs_gen.rs 与 modules/mod.rs 生成段降级为恒空的注入点,装配链一条不删; pack-sync.py 把「零包」钉成合法目标态。 - 尺子不再「跳过」:CP1 防回流清单、check-module 三条、AR2/PACK1 正向断言、 AR17 升级为零业务依赖判据(含注入式反自证)、契约反自证换平台锚点、FACE 零包重算。 - 面 A 冒烟 43→21 条(17 条平台权限闭环 + 4 条业务端点 404);pack_smoke_it 改 运行时防回流探针;auth/db/batch7/permission/seed/routes 单测换平台内置夹具。 - 契约 [MENU_TREE] 收成 5 条系统菜单、[RULER] 改 21/3;README/CLAUDE/HANDOFF/ CHANGELOG/contract §5.1/schema.sql/db.rs 注释同步。 验收:cargo test --workspace --no-fail-fast 649 passed / 0 failed / 6 ignored; verify.sh --smoke 14/14;check-arch 24/24 + 反自证 14/14; cargo tree -p sspf 无 sspf-pack-*。前端 src/frontend 按要求保留。 --- .workbuddy/memory/2026-11-04.md | 36 + CHANGELOG.md | 9 + CLAUDE.md | 53 +- Cargo.lock | 32 - Cargo.toml | 5 +- HANDOFF.md | 59 + HOWTO_MODULE.md | 459 -------- JNPF_COMPAT_SURFACE.md | 435 ------- JNPF_SOURCE_AUDIT.md | 656 ----------- MIGRATION.md | 312 ----- PERMISSION.md | 182 --- PLAN.md | 8 +- README.md | 274 ++--- crates/sspf-admin/Cargo.toml | 8 +- crates/sspf-admin/src/main.rs | 26 +- crates/sspf-contract/src/envelope.rs | 2 +- crates/sspf-contract/src/headers.rs | 2 +- crates/sspf-contract/src/route.rs | 2 +- crates/sspf-core/src/crud.rs | 2 +- crates/sspf-core/src/registry.rs | 2 +- crates/sspf-store/src/db.rs | 18 +- crates/sspf/Cargo.toml | 8 +- crates/sspf/src/lib.rs | 36 +- crates/tests/Cargo.toml | 9 +- crates/tests/tests/auth_it.rs | 9 +- crates/tests/tests/batch7_it.rs | 9 +- crates/tests/tests/crud_it.rs | 856 -------------- crates/tests/tests/db_it.rs | 169 ++- crates/tests/tests/pack_smoke_it.rs | 148 +-- crates/tests/tests/permission_it.rs | 39 +- crates/tests/tests/seed_it.rs | 17 +- docs/README-project.md | 154 --- docs/SSPF-PLATFORM-PACKAGE.md | 22 +- docs/contract.md | 86 +- docs/known-limitations.md | 4 +- packs/asset/Cargo.toml | 11 - packs/asset/pack.toml | 37 - packs/asset/schema/001_init.sql | 37 - packs/asset/src/lib.rs | 433 ------- packs/books/Cargo.toml | 11 - packs/books/pack.toml | 31 - packs/books/schema/001_init.sql | 33 - packs/books/src/lib.rs | 229 ---- packs/demo/Cargo.toml | 11 - packs/demo/pack.toml | 31 - packs/demo/schema/001_init.sql | 29 - packs/demo/src/lib.rs | 207 ---- packs/shop/Cargo.toml | 11 - packs/shop/pack.toml | 31 - packs/shop/schema/001_init.sql | 29 - packs/shop/src/lib.rs | 206 ---- references/BaseCrudController.java | 332 ------ references/README.md | 49 - scripts/check-arch.sh | 132 +-- scripts/check-boundary-scan.py | 27 +- scripts/check-boundary.sh | 30 +- scripts/check-citations-scan.py | 5 +- scripts/check-contract-scan.py | 41 +- scripts/check-module.sh | 48 +- scripts/check-naming.sh | 2 +- scripts/new-pack-gen.py | 1011 ----------------- scripts/new-pack.sh | 58 - scripts/pack-sync.py | 245 ++-- scripts/perm-smoke-jnpf.sh | 10 +- scripts/perm-smoke.sh | 104 +- scripts/verify.sh | 12 +- src/backend/Cargo.toml | 39 +- src/backend/README.md | 2 +- src/backend/db/schema.sql | 17 +- src/backend/src/boot.rs | 25 +- src/backend/src/bootstrap.rs | 156 +-- src/backend/src/lib.rs | 17 +- src/backend/src/modules/asset.rs | 88 -- src/backend/src/modules/books.rs | 75 -- src/backend/src/modules/demo.rs | 75 -- src/backend/src/modules/mod.rs | 368 +----- src/backend/src/modules/shop.rs | 75 -- src/backend/src/packs_gen.rs | 167 +-- src/backend/src/routes.rs | 80 +- template-boot-jnpf/.env.example | 45 - template-boot-jnpf/README.md | 245 ---- template-boot-jnpf/pom.xml | 96 -- template-boot-jnpf/scripts/verify.sh | 125 -- template-boot-jnpf/ssw-admin/pom.xml | 91 -- .../main/java/ssw/SswAdminApplication.java | 30 - .../ssw/common/config/SswMapperConfig.java | 22 - .../src/main/resources/application-dev.yml | 111 -- .../src/main/resources/application.yml | 41 - template-boot-jnpf/ssw-demo/pom.xml | 24 - .../ssw-demo/ssw-demo-controller/pom.xml | 36 - .../ssw/demo/controller/DemoController.java | 65 -- .../main/java/ssw/demo/mapper/DemoMapper.java | 19 - .../ssw-demo/ssw-demo-entity/pom.xml | 26 - .../main/java/ssw/demo/entity/DemoEntity.java | 37 - 94 files changed, 842 insertions(+), 8986 deletions(-) delete mode 100644 HOWTO_MODULE.md delete mode 100644 JNPF_COMPAT_SURFACE.md delete mode 100644 JNPF_SOURCE_AUDIT.md delete mode 100644 MIGRATION.md delete mode 100644 PERMISSION.md delete mode 100644 crates/tests/tests/crud_it.rs delete mode 100644 docs/README-project.md delete mode 100644 packs/asset/Cargo.toml delete mode 100644 packs/asset/pack.toml delete mode 100644 packs/asset/schema/001_init.sql delete mode 100644 packs/asset/src/lib.rs delete mode 100644 packs/books/Cargo.toml delete mode 100644 packs/books/pack.toml delete mode 100644 packs/books/schema/001_init.sql delete mode 100644 packs/books/src/lib.rs delete mode 100644 packs/demo/Cargo.toml delete mode 100644 packs/demo/pack.toml delete mode 100644 packs/demo/schema/001_init.sql delete mode 100644 packs/demo/src/lib.rs delete mode 100644 packs/shop/Cargo.toml delete mode 100644 packs/shop/pack.toml delete mode 100644 packs/shop/schema/001_init.sql delete mode 100644 packs/shop/src/lib.rs delete mode 100644 references/BaseCrudController.java delete mode 100644 references/README.md delete mode 100755 scripts/new-pack-gen.py delete mode 100755 scripts/new-pack.sh delete mode 100644 src/backend/src/modules/asset.rs delete mode 100644 src/backend/src/modules/books.rs delete mode 100644 src/backend/src/modules/demo.rs delete mode 100644 src/backend/src/modules/shop.rs delete mode 100644 template-boot-jnpf/.env.example delete mode 100644 template-boot-jnpf/README.md delete mode 100644 template-boot-jnpf/pom.xml delete mode 100755 template-boot-jnpf/scripts/verify.sh delete mode 100644 template-boot-jnpf/ssw-admin/pom.xml delete mode 100644 template-boot-jnpf/ssw-admin/src/main/java/ssw/SswAdminApplication.java delete mode 100644 template-boot-jnpf/ssw-admin/src/main/java/ssw/common/config/SswMapperConfig.java delete mode 100644 template-boot-jnpf/ssw-admin/src/main/resources/application-dev.yml delete mode 100644 template-boot-jnpf/ssw-admin/src/main/resources/application.yml delete mode 100644 template-boot-jnpf/ssw-demo/pom.xml delete mode 100644 template-boot-jnpf/ssw-demo/ssw-demo-controller/pom.xml delete mode 100644 template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/controller/DemoController.java delete mode 100644 template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/mapper/DemoMapper.java delete mode 100644 template-boot-jnpf/ssw-demo/ssw-demo-entity/pom.xml delete mode 100644 template-boot-jnpf/ssw-demo/ssw-demo-entity/src/main/java/ssw/demo/entity/DemoEntity.java diff --git a/.workbuddy/memory/2026-11-04.md b/.workbuddy/memory/2026-11-04.md index 7a3562f..d0f6938 100644 --- a/.workbuddy/memory/2026-11-04.md +++ b/.workbuddy/memory/2026-11-04.md @@ -211,3 +211,39 @@ CannotCache(incremental): ["--crate-name", "probe", ..., "-C", "incremental=..." 探针去掉 `--offline` 即可,registry 依赖仍命中本地缓存(43.73s)。 - 本地 tag 未发布过 ⇒ 文档同步提交后删除并在 HEAD 重建 annotated tag,再一起 push, 避免 tag 落后一个纯文档 commit。 + +--- + +## 21:5x 第一批:平台包零业务清理(基于 v0.3.0,示例搬到技能仓) + +**做了什么**(详见 `HANDOFF.md` §0) + +1. `packs/{asset,books,demo,shop}` + `modules/{asset,books,demo,shop}.rs` + 纯技能副本 + + `crud_it.rs` + `new-pack{,-gen}` 物理移出(备份 `/tmp/sspf-cleanup-backup/`);**前端按用户要求保留**。 +2. 删 `example-packs` feature / `example_packs()` / `packs/*` member / `sspf-pack-*` 依赖; + `packs_gen.rs` 与 `modules/mod.rs` 生成段变成**恒空的注入点**(装配链一条不删); + `pack-sync.py` 把零包钉成合法目标态,出现业务包直接报错。 +3. 尺子一律改**防回流**而不是跳过:CP1 固定 `ANTI_REFLUX_TOKENS`、check-module 三条、 + AR2/PACK1 正向断言、**AR17 升级**(5 个 Cargo.toml 无业务依赖 / GEN 段空 / packs/ 不存在)、 + 契约反自证锚点换平台行、FACE 计数零包重算。面 A 冒烟 43→21 条(17 平台 + 4 业务 404), + `pack_smoke_it` 改运行时防回流探针。 +4. 平台夹具替换:`auth_it`/`batch7_it`/`db_it`/`permission_it`/`seed_it`/`routes.rs` 单测 + 改用 5 菜单、`base_role`/`base_module`、常量投影;契约 `[MENU_TREE]` 收成 5 菜单、 + `[RULER]` 21/3。 + +**踩坑(硬结论)** + +- `cargo test` 遇到第一个失败二进制就停 ⇒ 迭代排查必须 `--no-fail-fast`。 +- **「跳过」= 尺子变瞎**:AR2/PACK1 原各 skip 一条,AR17 反自证 12/14 因无 pack 依赖行 + 可改而**静默假红**。改成正向断言 + 注入式探针;反自证 1/14 的 `mkdir -p packs/...` + 会留空目录,必须 `rmdir` 收尾,否则 AR2/AR17 当场红。 +- CP1 扫平台层源码字面量 ⇒ 防回流单测里的 `/api/ssw//` 要运行时拼,不然自己判红。 +- `query_json` 对原生 numeric 给 JSON 数字 9.9,只有 `::text` 才是字符串 "9.90"。 +- 运行时尺子默认读 `target/release/sspf-admin` ⇒ 改源码后必须重建 release,否则打旧二进制。 + +**验收**:`cargo test --workspace --no-fail-fast` 649 passed / 0 failed / 6 ignored(清理前 711, +下降 62 全是随示例搬走的纯业务测试,没造业务夹具冒充零业务);`verify.sh --smoke` 14/14 全绿; +`check-arch` 24/24 / 0 跳过 + 反自证 14/14;`cargo tree -p sspf` 零 `sspf-pack-*`。 + +**待办**:第二批改技能仓(依赖 sspf 发布 tag 的薄脚手架 + 示例 + 前端); +版本号「打 v0.4.0 还是只提交」需用户拍板,未擅自打。 diff --git a/CHANGELOG.md b/CHANGELOG.md index 792b050..8b511d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # CHANGELOG +## 未发布(2026-11-04,平台包零业务清理) + +- 4 个示例业务包与 `modules/` 的 4 个面 A 适配器整体移出本仓;`packs/` 与 `sspf-pack-*` 依赖、 `example-packs` feature、门面 `example_packs()` 全部移除。 +- `sspf-admin` 改为纯平台装配:只剩 177 张平台表,面 A 无业务端点;业务改由 `sspf::Platform::packs/ddl/menus/router` 注入。 +- 生成器 `pack-sync.py` 把「零包」钉成合法目标态:四处派生位置恒空,出现业务包直接报错。 +- 静态闸门(CP1 / check-module / 契约反自证)与运行时尺子(面 A 21 条、包冒烟)改跑**防回流断言**:示例业务回流平台仓立即红。 +- 纯业务测试 `crud_it.rs` 与 `new-pack` 脚手架随示例移交技能仓;`db_it` / `batch7_it` / `auth_it` 改用平台内置夹具。 +- 影响:本仓不再自带可跑的业务示例,集成测试数下降;`verify.sh --smoke` 需先 `cargo build --release -p sspf-admin`。 + ## v0.3.0(2026-11-04) - 新增两阶段装配 `Platform::assemble()` / `Assembled::finish()` / `serve()` 与 `Finish` 注入点:自带状态类型的业务路由可挂进平台唯一装配链,业务状态可在开库后构造。 diff --git a/CLAUDE.md b/CLAUDE.md index b4ee5bc..cdba4b2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # CLAUDE.md — 尚数网 Rust 后端开发框架(ssw-platform) > **本文件是项目级红线 / 当前阶段范围文件。** 代码级「契约唯一真源」在脚手架自带的各项文档里 -> (`docs/contract.md` / `JNPF_COMPAT_SURFACE.md` / `PERMISSION.md` / `MIGRATION.md` 等)。 +> (契约真源 = `docs/contract.md`;面 B 规格 / 权限 / 迁移说明在技能仓 `ssw-jnpf-lite-rust`)。 > > 🔴 **长期架构与路线(定位 / 分层 / 动态加载 / MCP / 迁移 / P0–P5)见 [`PLAN.md`](PLAN.md)。** > 本文件只管**当前阶段的红线与范围**,范围表随阶段推进滚动;两者冲突时以 `PLAN.md` 的架构决策为准。 @@ -120,9 +120,8 @@ ssw-platform/ │ │ # 定位项目根 / 读环境 / 开库 / 种子 / 自检 / 绑端口 / 优雅停机 │ └── tests/ # 🔴 **集成测试宿主**(package `sspf-tests`):37 个 `*_it.rs` │ # 测的是「装配好的平台」,不是内核的私有实现 ⇒ 不挂在内核包里 -├── packs/ # 【业务包】整目录可搬(jnpf ⇄ sspf 双向) -│ └── asset/ # 样板:Cargo.toml + pack.toml + src/lib.rs -│ # 只依赖 sspf-sdk(AR2)⇒ 可独立 cargo build +# 🔴 **没有 packs/**(2026-11-04 清理):业务包属于业务仓 / 技能仓, +# 本仓零业务;`pack-sync.py` 一旦发现 packs/ 会直接报错。 ├── src/ │ ├── backend/ # 内核 crate(package `ssw-platform`,**只有 lib 目标**) │ │ ├── Cargo.toml @@ -133,34 +132,31 @@ ssw-platform/ │ │ │ │ │ # ⇒ 路由注册的 1,010 处 `compat::<域>::` **一个字都不用改** │ │ │ │ │ # 🔴 不许在这里写实现(AR9/AR10 会红) │ │ │ ├── test_support.rs # 测试用**进程级共享** pglite(依赖装配根 ⇒ 留壳层) -│ │ │ ├── modules/ # 【业务层】**每个模块都是「面 A 适配器 + pub use 转发」** -│ │ │ │ ├── mod.rs # ALL_SPECS / ALL_MENUS / ALL_ROUTES / router() 汇总(生成段) -│ │ │ │ ├── asset.rs # 🔴 真实业务:DataResource(本体对齐)→ packs/asset -│ │ │ │ ├── demo.rs / shop.rs / books.rs # 示例包 → packs/{demo,shop,books} -│ │ │ │ └── .rs # 尚数网业务模块(`new-pack.sh` 生成) +│ │ │ ├── modules/ # 【业务装配点】只剩 mod.rs;五个生成段恒空 +│ │ │ │ └── mod.rs # ALL_SPECS / ALL_MENUS / ALL_ROUTES / router() 全为空 │ │ │ ├── forward.rs # 6 个转发壳(低代码 4 + MCP 2)—— 只有 `pub use` │ │ │ ├── routes.rs # 路由装配(平台 27 条 + 面 B 14 条 + merge 业务路由) │ │ │ └── bootstrap.rs # 【装配根】唯一同时认识两层;把业务菜单注入种子 -│ │ ├── db/schema.sql # 完整 DDL(base_* 8 + 业务 N) +│ │ ├── db/schema.sql # 平台 DDL(177 张表;无业务表) │ │ └── data/ # 运行期数据(gitignore) │ └── frontend/ # 本期暂不动;沿用 Java 版前端/移动端 -├── scripts/ # 六道闸门 + cipher 自证(见 §6) +├── scripts/ # 六道闸门 + 运行时尺子 + pack-sync(见 §6) └── docs/ # contract / runbook / decisions / known-limitations / ddl ``` **核心不变量**: -- **平台层 / 业务层分离**:加业务模块**一条命令** - (`bash scripts/new-pack.sh --name "…" --columns "a:TYPE"`),平台层一个字不改。 - 两层唯一接头点是 `bootstrap.rs`,而它读的是**生成**的包清单 `src/backend/src/packs_gen.rs` - (真源是 `packs/*`)。 -- **四处内核接线是生成的**(`packs_gen.rs` / `modules/mod.rs` 五段 / `Cargo.toml` 依赖段 / - `contract.md` 三段),由 `scripts/pack-sync.py` 从 `packs/*` + `modules/*.rs` 推出。 - **手改会被覆盖**,而 `verify.sh` 第一步 `pack-sync.py --check` 会把「忘了同步」判红 - —— 因为漏同步的后果是**静默 404 / 越权放行**,不是编译错误。 -- **两档验证,分工别混**:`verify.sh --fast`(纯静态)证明「**该接的地方接上了**」; - `verify.sh --lib`(+ 单测 + 包冒烟 `crates/tests/tests/pack_smoke_it.rs`)证明「**接上的活真能应答**」。 - 后者遍历全部包真打 `List`(面 A + 面 B)—— 表没建出来 / 路由没 merge / 守卫指错菜单 - 这三种**静态闸门全绿**、页面空着,只有它会红。**加包后两档都要跑。** +- 🔴 **平台包零业务**(2026-11-04 清理,本页最上面那条边界):本仓没有 `packs/`、 + 没有 `sspf-pack-*` 依赖、没有 `example-packs` feature、`modules/` 只留空壳。 + 业务仓只依赖门面 `sspf`,经 `Platform::packs / ddl / menus / router / static_dir / on_ready` + (或 v0.3.0 的 `assemble() → Finish`)注入自己的业务。 +- **四处派生位置恒空且是生成的**(`packs_gen.rs` / `modules/mod.rs` 五段 / + `Cargo.toml` 的 `>>>GEN:PACK_DEPS` / `contract.md` 生成段),由 `scripts/pack-sync.py` + 把「零包」钉成合法目标态。**手改会被覆盖**,`verify.sh` 第一步 `--check` 判红; + 谁把业务包塞回 `packs/`,生成器直接报错 ⇒ 防回流。 +- **两档验证,分工别混**:`verify.sh --fast`(纯静态)证明「生成段没漂移 + 六把闸门没被改弱」; + `verify.sh --lib`(+ 单测 + 运行时探针 `crates/tests/tests/pack_smoke_it.rs`)证明 + 「平台真的是零业务且装配链还活着」:清单恒空、平台端点 200、4 个示例端点 404。 + `verify.sh --smoke` 再叠 5 把运行时尺子(先 `cargo build --release -p sspf-admin`)。 - **双面契约同一进程**:面 A(ssw 形状,冻结)+ 面 B(官方 JNPF 形状)。判别头 = `Vue-Version: 3`(官方前端必带、本仓前端唯一不发)。 共用两条路由按头分流:`GET /api/oauth/CurrentUser`、`PUT /api/permission/Authority/Data/{objectId}`。 - **两套权限判据并存**:面 A 按菜单路径(`f_url_address`);面 B 按点权限编码(`f_en_code`)。两套数据源不同,别混。 @@ -298,15 +294,15 @@ cp .env.example .env && ./run.sh install && ./run.sh dev ## 9. 命令速查 ```bash -cargo build --release # 编译(workspace 根,含 crates/* 与 packs/*) -cargo test --workspace # 单测(当前 654 条) +cargo build --release # 编译(workspace 根,含 crates/*;无 packs/*) +cargo test --workspace # 全量测试(当前 5xx 条,零业务清理后已下降) bash run.sh dev # 起后端(30010) + 前端(5173) -bash scripts/perm-smoke.sh # 面 A 43 条 +bash scripts/perm-smoke.sh # 面 A 平台权限闭环 + 防回流 21 条 bash scripts/perm-smoke-jnpf.sh # 面 B 23 条 bash scripts/check-boundary.sh # 分层红线 CP1–CP6 bash scripts/check-contract.sh # 契约端点 ↔ 代码路由 对账 -bash scripts/check-module.sh # 业务模块 10 接触点 -bash scripts/check-arch.sh # crate 依赖纪律 AR1–AR11 + 内存红线 MEM1–MEM2 +bash scripts/check-module.sh # 零业务防回流三条([MODULE] 有数据行 ⇒ 回到完整检查) +bash scripts/check-arch.sh # crate 依赖纪律 AR1–AR19 + 内存红线 MEM1–MEM2(AR17 钉零业务) bash scripts/check-arch.sh --self-test # 反自证:造违规必须被抓到(6 条) bash scripts/check-naming.sh # 内部标识剥离(NM1–NM3 阻断 / NM4 注释量化) bash scripts/check-naming.sh --strict # 注释里的原厂名也算红(技术债清零时用) @@ -315,7 +311,6 @@ bash scripts/lowcode-smoke.sh # 低代码 15 条(表单解析 + 校验 bash scripts/baseline-smoke.sh # 双后端契约 10 条(HTTP 适配器 + 形状归一化) cargo build -p sspf-adapter-baseline --example probe # baseline-smoke 依赖的探针 bash scripts/mem-budget.sh # 空载内存实测(P0 出口判据,预算 40 MB) -cargo test -p sspf-pack-asset # 业务包独立可编(业务包剥离的硬证据) ./target/release/sspf-admin --mcp # 起 MCP stdio 服务(供 AI 直接驱动,见 docs/mcp.md) ./target/release/sspf-admin --enc 123456 # cipher 自证 ``` diff --git a/Cargo.lock b/Cargo.lock index 26fd8fe..ea26f22 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1283,34 +1283,6 @@ dependencies = [ "sspf-mcp", ] -[[package]] -name = "sspf-pack-asset" -version = "0.1.0" -dependencies = [ - "sspf-sdk", -] - -[[package]] -name = "sspf-pack-books" -version = "0.1.0" -dependencies = [ - "sspf-sdk", -] - -[[package]] -name = "sspf-pack-demo" -version = "0.1.0" -dependencies = [ - "sspf-sdk", -] - -[[package]] -name = "sspf-pack-shop" -version = "0.1.0" -dependencies = [ - "sspf-sdk", -] - [[package]] name = "sspf-plugin" version = "0.1.0" @@ -1384,10 +1356,6 @@ dependencies = [ "sspf-lowcode-exec", "sspf-mcp", "sspf-mcp-adapter", - "sspf-pack-asset", - "sspf-pack-books", - "sspf-pack-demo", - "sspf-pack-shop", "sspf-plugin", "sspf-store", "tokio", diff --git a/Cargo.toml b/Cargo.toml index 5f7df0f..a007277 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -12,9 +12,10 @@ # 成员 crate(src/backend)不得再写 [profile.*],否则 cargo 直接报错。 [workspace] -# src/backend = 内核;crates/* = 平台侧 crate;packs/* = 业务包(只依赖 sspf-sdk) +# src/backend = 内核;crates/* = 平台侧 crate。 +# 🔴 **没有 packs/**:业务包属于业务仓(2026-11-04 清理),平台仓零业务。 members = [ - "src/backend", "crates/*", "packs/*"] + "src/backend", "crates/*"] resolver = "2" [workspace.package] diff --git a/HANDOFF.md b/HANDOFF.md index 8a35d94..5e4c433 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -9,6 +9,65 @@ --- +## 0. 2026-11-04 晚:平台包零业务清理(第一批,**基于 v0.3.0,新提交**) + +需求:`@docs/SSPF-BUSINESS-COMPOSITION.md` 之后的追加要求 —— 「示例部分拿到外面去做, +技能依赖**打好的包及说明**而不是整个 sspf 源码仓,前端留着;一次做清理,一次改技能」。 +`v0.3.0` tag 一字不动,清理全走新提交;旧形态在 tag 里完整可回溯。 + +**做了什么** + +1. 物理移出:`packs/{asset,books,demo,shop}`、`src/backend/src/modules/{asset,books,demo,shop}.rs`、 + 纯技能副本(`template-boot-jnpf/`、`references/`、`JNPF_*`、`PERMISSION.md`、`HOWTO_MODULE.md`、 + `MIGRATION.md`、`docs/README-project.md`)、纯业务测试 `crud_it.rs`、 + `scripts/new-pack{,-gen}`。备份在 `/tmp/sspf-cleanup-backup/`(供第二批改技能用)。 + **前端 `src/frontend/` 与前端脚本按用户要求原样保留。** +2. 解绑:`example-packs` feature、`example_packs()`、`packs/*` workspace member、 + `sspf-pack-*` 依赖(Cargo.lock 与 `cargo tree -p sspf` 均无)、`sspf-admin` 的 feature 开关。 + `packs_gen.rs` / `modules/mod.rs` 生成段降级为**恒空的注入点**(装配链一条不删), + `pack-sync.py` 把「零包」钉成合法目标态,出现任何业务包直接报错。 +3. 尺子全部改造成**防回流**,不是「跳过」:CP1 用固定 `ANTI_REFLUX_TOKENS`、 + `check-module` 零业务三条、`check-arch` AR2/PACK1 正向断言 + **AR17 升级为 + 「5 个 Cargo.toml 无业务包依赖 / GEN 段恒空 / packs/ 不存在」**、 + 契约反自证锚点换成平台路由行、`FACE` 计数零包时重算。 +4. 运行时尺子:面 A `perm-smoke.sh` 43 → **21 条**(17 条平台权限闭环 + 4 条业务端点 404); + 面 B 23 条不变(授权夹具 `m_demo` → 平台菜单 `m_menu`);`pack_smoke_it` 改成 + 「清单恒空 + 平台端点 200 + 4 个示例端点 404」的运行时探针; + `auth_it` / `batch7_it` / `db_it` / `permission_it` / `seed_it` / `routes.rs` 单测 + 全部换成平台内置夹具(5 菜单 / `base_role` / `base_module` / 常量投影)。 +5. 文档:`README` / `CLAUDE.md` / `CHANGELOG.md` / `docs/contract.md` §5.1 / + `schema.sql` / `db.rs` 注释同步;契约 `[MENU_TREE]` 收成 5 条系统菜单, + `[RULER]` 改 21 / 3。 + +**🔴 回归与坑(下轮别再踩)** + +- `cargo test` 遇到第一个失败二进制就**停** ⇒ 必须 `cargo test --workspace --no-fail-fast` + 才能一次拿全失败清单。本轮依次暴露:`crud_it`(编译)→ `auth_it` → `db_it` → + `batch7_it` → `pack_smoke_it` → `permission_it` → `seed_it` + `routes.rs` 单测。 +- **跳过 ≠ 判据**:零业务后 `check-arch` 的 AR2/PACK1 原本各 `skip` 一条, + AR17 的反自证 12/14 因「没有 pack 依赖行可改」**静默假红**。已全部换成正向断言 + + 注入式探针(造一条 `sspf-pack-probe` 依赖)。反自证 1/14 的 `mkdir -p packs/...` + 会留下**空 `packs/`**,必须用 `rmdir` 收干净,否则 AR2/AR17 当场红。 +- CP1 扫的是**平台层源码里的字面量** ⇒ 新写的防回流单测若直接写 + `/api/ssw//...` 会把自己判红;路径要运行时用 app/entity 两段拼。 +- `query_json` 对原生 numeric 列给 JSON **数字**(9.9),只有 `::text` 才是字符串 "9.90" + ⇒ `db_it` 现在两种形态都钉。 +- 运行时尺子默认读 `target/release/sspf-admin`;改完源码**必须** + `cargo build --release -p sspf-admin`,否则打的是旧二进制(本轮被它骗过一次)。 +- 契约 `[RULER]` 条数 / `[MENU_TREE]` 是尺子的单一真源,改断言必须同步; + `[MENU_TREE]` 从 9 菜单收成 5 菜单后,`perm-smoke` 断言 13 的形状变成 `菜单管理:`。 + +**验收**:`cargo test --workspace --no-fail-fast` **649 passed / 0 failed / 6 ignored** +(清理前 711 ⇒ 下降 62,全是随示例搬走的纯业务测试,未造业务夹具冒充零业务); +`verify.sh --smoke` **14/14 步全绿**(6 道静态闸门 + 全量测试 + 5 把运行时尺子); +`check-arch.sh` 24/24 / 0 跳过,`--self-test` 14/14;`cargo tree -p sspf | grep sspf-pack` 无输出。 + +**待办(第二批)**:技能仓 `~/.agents/skills/ssw-jnpf-lite-rust` 接收示例,改成 +`sspf = { git=…, tag=… }` 的薄脚手架,删掉旧的 `src/backend` 自研实现,重写 +`SKILL.md` / `README.md`,前端随发布包保留。版本号(打 `v0.4.0` 还是只提交)需用户拍板。 + +--- + ## 0-bis. 2026-11-04 `v0.3.0`:业务自带状态的可组合装配(P1 交付,**已推送 `origin`:`main` + tag**) 需求与实施记录:`docs/SSPF-BUSINESS-COMPOSITION.md`(含 §11 四项评审决策)。 diff --git a/HOWTO_MODULE.md b/HOWTO_MODULE.md deleted file mode 100644 index 658ebf1..0000000 --- a/HOWTO_MODULE.md +++ /dev/null @@ -1,459 +0,0 @@ -# 加一个业务模块(AI 开发主线) - -> 🔴 **2026-11-01 起:一条命令。** 本文后半部分的「改哪个文件」清单写于批次 12 之前, -> **已过时**(`db/schema.sql` 不用改、`modules/mod.rs` 不用改、契约不用手抄)。 -> 以本节为准: -> -> ```bash -> bash scripts/new-pack.sh crm Customer --name "客户" \ -> --columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend -> bash scripts/verify.sh --fast # 纯静态:文件和接线一致 -> bash scripts/verify.sh --lib # + 单测 + **包冒烟**(真起库、真打 List) -> ``` -> -> 🔴 **两道都要过**:`--fast` 只证明「该接的地方都接上了」,**证明不了「接的活能应答」** -> —— 表没建出来 / 面 B 路由没 merge / `module_key` 指向不存在的菜单,这三种 -> **静态闸门全绿**,只有 `--lib` 里的包冒烟(`crates/tests/tests/pack_smoke_it.rs`)会红。 -> -> 它建 `packs//`(**真源**)+ `modules/.rs`(面 A 适配器), -> 再把**四处生成位置**补齐(`packs_gen.rs` / `modules/mod.rs` 五段 / -> `Cargo.toml` 依赖段 / `docs/contract.md` 三段)。 -> 生成物手改会在下次 `pack-sync.py` 被覆盖,而 `verify.sh` 第一步就会红。 - -参照实现 = 内置的四个模块 -(`demo/DemoItem` · `shop/Product` · `books/Book` · **`asset/DataResource`(真实业务)**) -——要读就抄 `packs/asset/`,它是完整样板。 - -> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改了哪儿、怎么验证」。** - -## 〇.5、它内部做了什么(排错时照着看) - -``` - 1. packs//src/lib.rs 【真源】EntitySpec + MenuSpec + PackRoute×3 + Pack + DDLS - 2. packs//schema/*.sql 业务表 DDL(include_str! 编进二进制;**不进 db/schema.sql**) - 3. packs//pack.toml 包清单(catalog;内核读的是 pack-sync 生成的 JSON 快照) - 4. packs//Cargo.toml 只依赖 sspf-sdk(AR2:不许 axum / tokio / pglite) - 5. src/modules/.rs 面 A 适配器:pub use 包的 spec + 3 个 handler + router() - ↓ 以下四处**全部由 scripts/pack-sync.py 从「packs/* + modules/*.rs」生成** - 6. src/backend/src/packs_gen.rs 内核包清单(每个包一条 load_static 调用) - 7. src/modules/mod.rs 五段:pub mod / ALL_SPECS / ALL_ROUTES / ALL_MENUS / router() - 8. src/backend/Cargo.toml >>>GEN:PACK_DEPS 段 - 9. docs/contract.md 附录 A [MODULE] / [MENU] / [ENDPOINT] 的生成段 - 10. frontend/src/{api,views}/… + App.tsx 的 (new-page.sh,--with-frontend) - ⇒ bash scripts/verify.sh --fast 必须全 ✅(文件与接线) - ⇒ bash scripts/verify.sh --lib 必须全 ✅(+ 包冒烟:List 真应答) -``` - -🔴 **漏了会怎样**(这就是为什么不再让人手抄): - -| 漏哪一步 | 现象 | 报错吗 | 谁兜住 | -|---|---|---|---| -| 6(`packs_gen.rs`) | 面 B 端点 404,列表永远空 | ❌ **不报** | `verify.sh --lib` 包冒烟 | -| 7(`ALL_MENUS`) | 菜单不种 ⇒ 守卫查不到菜单 ⇒ **越权放行** | ❌ **不报** | 单测 `every_pack_loads_with_…`(结构性) | -| 7(`router()`) | 面 A 404 ⇒ MVP 前端页面空着 | ❌ **不报** | `verify.sh --lib` 包冒烟 | -| DDL 少一列 | 投影 SQL 报错 ⇒ 列表恒 `{"code":400}` | ❌ **不报** | `verify.sh --lib` 包冒烟 | -| 8(Cargo 依赖) | 编译失败 | ✅ 报 | 编译 | -| 9(契约) | `check-contract` 红 | ✅ 报 | `verify.sh --fast` | - -🔴 **平台层(`src/platform/`)与入口文件(`crates/sspf-admin/src/main.rs`)一个字都不用改** —— -加业务模块**不碰平台层**,由尺子 `bash scripts/check-boundary.sh`(CP1–CP6)钉住: -平台层出现任何业务标识符(表名 / 实体名 / 路由前缀 / 菜单 id / url / en_code)⇒ 红。 - -## 〇、命名约定(先想清楚再动) - -| 位置 | 约定 | 例(`books` / `Book`) | -|---|---|---| -| `app_code` | 小写业务名,**同时是 URL 段** | `books` | -| `entity` | 大驼峰,**同时是 URL 段** | `Book` | -| 表名 | 蛇形,**官方没有对应表** ⇒ 自己起(推荐 `{app}_{entity 小写}`) | `book_shop_book` | -| 前端 api 文件 | entity 小写 | `src/api/book.ts` | -| 前端 view 文件 | entity 大驼峰 | `src/views/Book.tsx` | -| Route path | **= 菜单 `url_address`**(去前导斜杠) | `books/Book` | -| 菜单种子 id | `m_` + entity 小写 | `m_book` | -| 列表函数名 | `list` + 复数(复数规则见 `check-module.sh` 的 `plural()`) | `listBooks` | -| 单条函数名 | `save` / `delete` + entity | `saveBook` / `deleteBook` | - -🔴 **表名不与官方对齐是刻意的**(官方没有低代码业务表)——但**两版后端(react 版 / rust 版)之间要同名**, -才能开同一个库。`demo_item` / `shop_product` / `book_shop_book` 就是这么定的。 - -## 一、要碰的 8 个文件(10 个接触点) - -| # | 文件 | 改什么 | 漏了会怎样 | -|---|---|---|---| -| 1 | `src/backend/db/schema.sql` | `CREATE TABLE {table}` | 端点 500(表不存在) | -| 2 | `src/backend/src/modules/.rs` | **新文件**:spec + `*_MENU` + 3 个 handler + `router()` | 端点 404(没注册)/ **菜单不显示** | -| 3 | `src/backend/src/modules/mod.rs` | `ALL_SPECS` 加一条 + `ALL_MENUS` 加一条 + `router()` merge 一行 + `ALL_ROUTES` 加 3 条 | 启动自检失败 / 端点 404 / **菜单不被种、admin 少一条授权** | -| 4 | `src/frontend/src/api/.ts` | 3 个函数 | 页面发请求 404 | -| 5 | `src/frontend/src/views/.tsx` | 列表页 | 页面空白 | -| 6 | `src/frontend/src/App.tsx` | `` | **页面 404** | -| 7 | `docs/contract.md` | **附录 A**:`[MODULE]` 加一行 + `[MENU]` 加一行 + `[ENDPOINT]` 加 3 行(本模块的 3 条端点)+ `[FACE]` 的 A 条数 +3(期望值真源) | 自检退出码 2(闸门形同虚设)/ `check-contract.sh` 红 | -| 8 | `scripts/perm-smoke.sh` | 追加该模块的断言 | 新模块无端到端覆盖 | - -**外加两条一致性**: -1. `spec.module_key` == `menu.url_address` == `App.tsx` 的 Route path —— **三处一字不差**。 - 不一致的后果是**静默放行**(未映射到菜单就放行,不报错)。 -2. 🔴 **入口文件也不碰**:`crates/sspf-admin/src/main.rs` 的 `BASE_TABLES` 只列 8 张 `base_*`(8 张全部逐字对齐官方 DDL,含多应用注册表 `base_system`), - 业务表由 `modules::all_specs()` 派生并与 `db/schema.sql` 双向对账 - ⇒ 加业务表**不用**改 `crates/sspf-admin/src/main.rs`。 - -🔴 **分层铁律**:后端代码分两层—— - -| 层 | 目录 | 内容 | 加模块时 | -|---|---|---|---| -| **平台层** | `crates/sspf-core/` + `crates/sspf-compat-*/` | 契约实现(信封 / cipher / 登录 / 权限 / `base_*` 管理 / 面 B / CRUD 引擎) | **一个字都不改** | -| **业务层** | `src/backend/src/modules/` | 业务 spec + **业务菜单** + handler + 路由 | **只改这里** | -| **装配根** | `src/backend/src/bootstrap.rs` | 唯一同时认识两层的地方 | **一个字都不改** | - -> 🔴 **M7 起平台层路径变了**:`src/backend/src/platform/` 的转发壳**已整体删除**。 -> 平台能力现在直接从 crate 引:`sspf_core::…`(平台核心)/ `crate::compat::<域>::…`(契约面)。 - -(对齐 react 版的 `common`+`auth`+`sys` / `demo`+`shop`+`books`, -以及官方 JNPF 的 `jnpf-common`+`jnpf-system` / `jnpf-admin`。) - -## 二、后端四处改什么 - -### 2.1 `db/schema.sql` —— 建表 - -照抄 `book_shop_book` 的形状: - -```sql -CREATE TABLE {table} ( - f_id VARCHAR(50) NOT NULL, - f_title VARCHAR(200), - f_price NUMERIC(12,2), - f_stock INT, - f_creator_user_id VARCHAR(50), - f_creator_time TIMESTAMP, - f_delete_mark INT DEFAULT 0, - CONSTRAINT pk_{table} PRIMARY KEY (f_id) -); -``` - -红线: -- 列名**全部 `f_` 前缀**;主键 `f_id VARCHAR(50)`(**不是 32**——36 位 UUID 装不下)。 -- 软删列 `f_delete_mark INT DEFAULT 0`(**不是**物理 DELETE)。 -- 🔴 **numeric 列(金额)** ⇒ spec 里要标 `numeric: true`(投影 `::text` ⇒ JSON 字符串 `"9.90"`)。 -- 🔴 **改了 schema.sql 不生效**:schema 只在**首次**建表时执行 ⇒ 改完要**清空 `data/` 重建**。 - -### 2.2 `src/modules/.rs` —— 【新文件】spec + handler + 路由 - -**照抄 `src/backend/src/modules/shop.rs`**(最接近的参照实现)。一个文件三块: - -```rust -//! shoes —— 业务模块:Shoe(物理表 `shoe_item`)。 - -use axum::body::Bytes; -use axum::extract::{RawQuery, State}; -use axum::http::HeaderMap; -use axum::routing::{delete, get, post}; -use axum::{Json, Router}; - -use sspf_core::crud::{handle_delete, handle_list, handle_save}; -use sspf_core::entity::{ColumnSpec, EntitySpec}; -use sspf_core::envelope::ActionResult; -use sspf_core::state::AppState; - -/// ① spec 的列清单(**顺序 = 响应 JSON 的键序**)。 -const SHOE_COLUMNS: &[ColumnSpec] = &[ - ColumnSpec { column: "f_id", json_key: "id", default: None, numeric: false }, - ColumnSpec { column: "f_title", json_key: "title", default: None, numeric: false }, - ColumnSpec { column: "f_price", json_key: "price", default: Some("0.00"), numeric: true }, - ColumnSpec { column: "f_creator_user_id", json_key: "creatorUserId", default: None, numeric: false }, - ColumnSpec { column: "f_creator_time", json_key: "creatorTime", default: None, numeric: false }, - ColumnSpec { column: "f_delete_mark", json_key: "deleteMark", default: Some("0"), numeric: false }, -]; - -/// ② spec 本体。 -pub const SHOE_SPEC: EntitySpec = EntitySpec { - app_code: "shoes", - entity: "Shoe", - table: "shoe_item", - module_key: Some("shoes/Shoe"), // 🔴 None ⇒ 仅登录(demo 就是 None) - columns: SHOE_COLUMNS, - numeric_columns: &["f_price"], // 🔴 必须与每列的 numeric 标记一致(有单测钉) - // 🔴 `f_creator_user_id` 的写死规则(裁决 S22): - // `Some("admin")` ⇒ 恒写 admin(demo 的规则);`None` ⇒ `body.creatorUserId || 'admin'`。 - creator_fixed: None, -}; - -/// ③ 本模块的 3 条路由(**业务层的路由表**)—— 钉子测试遍历它。 -pub const ROUTES: [&str; 3] = [ - "/api/ssw/shoes/Shoe/List", - "/api/ssw/shoes/Shoe/Save", - "/api/ssw/shoes/Shoe/Delete", -]; - -// ---- 3 个 handler:不要重写业务逻辑 ---- -// `handle_list` / `handle_save` / `handle_delete`(平台层)已经把 -// 守卫、SQL 拼装、投影、软删、序列化全包了。 - -/// `GET /api/ssw/shoes/Shoe/List`。 -pub async fn shoe_list(State(state): State, headers: HeaderMap) -> Json { - handle_list(&state, &headers, &SHOE_SPEC).await -} - -/// `POST /api/ssw/shoes/Shoe/Save`。 -pub async fn shoe_save( - State(state): State, - headers: HeaderMap, - body: Bytes, -) -> Json { - handle_save(&state, &headers, &SHOE_SPEC, &body).await -} - -/// `DELETE /api/ssw/shoes/Shoe/Delete?id=`。 -pub async fn shoe_delete( - State(state): State, - headers: HeaderMap, - raw: RawQuery, -) -> Json { - handle_delete(&state, &headers, &SHOE_SPEC, &raw).await -} - -/// 本模块的路由(`Router::merge` 进总路由,**对齐 NestJS 的 module 注册**)。 -pub fn router() -> Router { - Router::new() - .route(ROUTES[0], get(shoe_list)) - .route(ROUTES[1], post(shoe_save)) - .route(ROUTES[2], delete(shoe_delete)) -} -``` - -🔴 **`json_key` 必须等于 `db::column_to_json_key(column)`**(`f_title` ⇒ `title`)—— 有单测钉死,不一致会红。 -🔴 **列顺序 = 响应 JSON 的键序**(照抄参照模块,别自作主张排序)。 -🔴 **`default` 只在「路径 1(无 id 的新建)」生效**——带 id 但库里没这行时,**一个默认值都不加**。 -🔴 **handler 签名不要改**:`Save` 收 `body: Bytes`(自己解析,不走 `Json`), -`Delete` 收 `raw: RawQuery`(`?id=`)—— `handle_save` / `handle_delete` 依赖这个形状。 -🔴 **spec 写成 `const`**(不是 `fn find_spec(..).expect(..)`)—— 非测试代码**零 `unwrap()` / `expect()` / `panic!()`** 是项目红线。 - -### 2.3 `src/modules/mod.rs` —— 登记这个模块(3 处) - -```rust -pub mod books; -pub mod demo; -pub mod shop; // 🔴 加这一行 - -pub const ALL_SPECS: &[EntitySpec] = &[ - demo::DEMO_SPEC, - shop::PRODUCT_SPEC, - books::BOOK_SPEC, - shoes::SHOE_SPEC, // 🔴 加这一条 -]; - -pub const ALL_ROUTES: &[&str] = &[ - demo::ROUTES[0], - demo::ROUTES[1], - demo::ROUTES[2], - shop::ROUTES[0], - shop::ROUTES[1], - shop::ROUTES[2], - books::ROUTES[0], - books::ROUTES[1], - books::ROUTES[2], - shoes::ROUTES[0], // 🔴 加这三条 - shoes::ROUTES[1], - shoes::ROUTES[2], -]; - -pub fn router() -> Router { - demo::router() - .merge(shop::router()) - .merge(books::router()) - .merge(shoes::router()) // 🔴 加这一行 -} -``` - -🔴 **`ALL_SPECS` 漏了** ⇒ 启动时的标识符白名单自检会失败(`spec 表 … 在 db/schema.sql 里没有 CREATE TABLE`)—— - 记得同时把新表加进 `src/backend/db/schema.sql`(**`crates/sspf-admin/src/main.rs` 不用改** ⇒ 业务表由 spec 派生)。 -🔴 **`ALL_MENUS` 漏了** ⇒ 菜单**不会被种**、admin **少一条授权** ⇒ 侧栏少一项。 -🔴 **`router()` 漏了 merge** ⇒ 端点 404。 -🔴 **`ALL_ROUTES` 漏了** ⇒ 路由表钉子测试**不会报错**(它只遍历这张表)⇒ 静默失去覆盖 ⇒ 一定要加。 - -### 2.4 `src/modules/.rs` —— 声明自己的内置菜单 - -🔴 **业务菜单住在业务层**(与 `EntitySpec` 同理:`f_url_address` 与 `f_en_code` **都是业务知识**)。 - -在本模块文件里加一条(与 `*_SPEC` 同级): - -```rust -use sspf_core::menu::MenuSpec; // 🔴 类型住在平台层,**值**住在业务层 - -pub const SHOE_MENU: MenuSpec = MenuSpec { - id: "m_shoe", - full_name: "鞋", - en_code: "permission.shoes.shoe", // 🔴 面 B 的点权限编码(官方 @SaCheckPermission 的判据) - url_address: "shoes/Shoe", // 🔴 必须 == Route path == spec.module_key - parent_id: "0", - menu_type: 2, // 1 = 目录,2 = 页面(官方 f_type 是 **INTEGER**) - icon: None, - sort_code: 9, -}; -``` - -再在 `src/backend/src/modules/mod.rs` 的 `ALL_MENUS` 里加一条 `shoes::SHOE_MENU,`。 - -🔴 **还要在契约里登记**(`docs/contract.md` **附录 A**): -- `[MODULE]` 加一行:`shoes Shoe shoe_item shoes/Shoe shoes/Shoe m_shoe 有 shoes.rs` -- `[MENU]` 加一行:`m_shoe 鞋 permission.shoes.shoe shoes/Shoe 0 2 9` -- `[ENDPOINT]` 加**三行**(本模块的 3 条端点,`face` 一律 `A`, - `guard` = `shoes/Shoe`(= `module_key`;仅登录的模块写 `登录`),`owner` = `shoes`): - ``` - A GET /api/ssw/shoes/Shoe/List shoes/Shoe shoes - A POST /api/ssw/shoes/Shoe/Save shoes/Shoe shoes - A DELETE /api/ssw/shoes/Shoe/Delete shoes/Shoe shoes - ``` -- `[FACE]` 的 **A 条数 +3**(面 A 专属端点多了 3 条) - -⇒ 这几行是**尺子的期望值真源**(`check-module.sh` / `check-boundary.sh` / `check-contract.sh` -都从那里读)⇒ -**代码里的 `*_MENU` 与契约那一行必须逐字一致**(`check-module.sh` 会逐字段比对); -**代码里注册的路由与 `[ENDPOINT]` 那三行必须逐条一致**(`check-contract.sh` 对账)。 - -🔴 **种子是「幂等 ensure」**:启动时按 `f_url_address` **或** `f_id` 判存在 ⇒ -**改了 `url_address` 必须重启回灌**;软删行**不复活**、不覆盖已改值。 -🔴 **改了种子要重启进程**才会回灌存量库,**不必删库重建**。 -🔴 **`en_code` 是面 B 的点权限判据**(`base_module.f_en_code`)—— 面 A 看 `f_url_address`、 - 面 B 看 `f_en_code`,**两套并存**。迁移前要补(见 `MIGRATION.md` §2.4)。 -🔴 **平台层不许出现这条菜单**(`platform/seed.rs` 只自带 5 条系统菜单)⇒ - `bash scripts/check-boundary.sh` 会红。 - -## 三、前端三文件改什么 - -### 3.1 `src/api/.ts` —— 3 个函数 - -```ts -import request from './request'; - -export const listShoes = () => request.get('/ssw/shoes/Shoe/List'); -export const saveShoe = (dto: any) => request.post('/ssw/shoes/Shoe/Save', dto); -export const deleteShoe = (id: string) => request.delete(`/ssw/shoes/Shoe/Delete?id=${id}`); -``` - -🔴 `request.ts` 的 `baseURL` 是 `/api` ⇒ 这里**不要**再写 `/api` 前缀。 -🔴 **函数名规则**:`list` + 复数(`plural()`:`s/x/ch/sh` → `+es`;辅音 + `y` → `ies`;否则 `+s`), -`save`/`delete` + entity。`check-module.sh` 按这个规则查。 - -### 3.2 `src/views/.tsx` —— 列表页 - -照抄 `views/Book.tsx`(含 numeric 往返、删除确认、错误提示)。 -🔴 **金额展示别用 `Number()` 转**——后端给的是字符串 `"9.90"`,转数字会丢尾零。 - -### 3.3 `src/App.tsx` —— 注册路由 - -```tsx -import Shoe from './views/Shoe'; -… -} /> -``` - -🔴 **Route path 必须 == 菜单 `url_address`**(去前导斜杠)—— 不一致 ⇒ 侧栏点了 404。 -🔴 JSX 常写成多行(``)⇒ `check-module.sh` 用 `tr '\n' ' '` 去换行再匹配。 - -## 四、菜单 + 授权 - -- **菜单**:**在业务模块里**声明(`modules/.rs` 的 `*_MENU`,见 2.4)⇒ 前端侧栏由 - **后端返回的菜单树**驱动 ⇒ 不用改前端导航。 -- **授权**:**默认不授权 ⇒ 非管理员看不到、访问 403**(这是对的)。 - 要让某个角色看到 ⇒ 写 `base_authorize` - (`f_object_type='role'` + `f_object_id=` + `f_item_type='module'` + `f_item_id=`)。 - 走 `PUT /api/permission/Authority/Data/{objectId}`(`objectType` **小写** `'role'`, - `module` 传**一维数组**)。 -- **admin 角色**:`platform/seed.rs` 的 `ensure_admin_authorizations` 会**自动**补 - **全部内置菜单**(5 条系统菜单 + 业务层声明的那几条)的授权 ⇒ - 管理员开箱即用,普通角色要手动授权。 - -## 五、验证(追加断言,别新写脚本) - -### 5.1 静态自检(改完立刻跑,**先于** perm-smoke) - -```bash -bash scripts/check-module.sh shoes Shoe # 单模块 -bash scripts/check-module.sh # 契约登记的全部模块 + 全局红线 -bash scripts/check-contract.sh # 契约端点表 ↔ 代码真实路由(全局) -``` - -🔴 **先在契约里登记**(§一 第 7 步)—— `docs/contract.md` **附录 A**: -`[MODULE]` 加一行(app / entity / 表名 / urlAddress / moduleKey / 菜单 id / 有无 api 文件 / 模块文件名)、 -`[MENU]` 加一行(菜单 id / 名称 / enCode / urlAddress / parentId / type / icon / sortCode)、 -`[ENDPOINT]` 加三行(本模块的 3 条端点:face / method / path / guard / owner)、 -`[FACE]` 的 A 条数 +3。 -🔴 **`check-module.sh` 里不再有期望表**(全部从契约读)⇒ 加模块**不用改脚本**, -但**必须改契约**,否则脚本判「契约 [MODULE] 里没有这个模块」退出 2。 -🔴 `check-contract.sh` 同理:代码里注册了路由而契约 `[ENDPOINT]` 没登记 ⇒ **红**。 - -### 5.2 端到端(`scripts/perm-smoke.sh` 追加断言) - -**必选 4 条**(每个业务模块都有): - -1. `GET /api/ssw/{app}/{Ent}/List` 无 token ⇒ `code=600` -2. 无 token ⇒ `code=600`(同上一条,测的是**端点在、守卫在**) -3. 非管理员未授权 ⇒ `code=403` -4. 管理员新建一条 ⇒ `code=200` + 回读列表里能看到(长度 +1) - -**每个业务字段加一条往返断言**(防 numeric/text/int 转换 bug): - -```bash -# numeric ⇒ JSON 字符串(带尾零);int ⇒ JSON 数字 -# 例:Shoe 的 f_price 回显必须等于 "9.90"(字符串),f_stock 必须等于 100(数字) -``` - -🔴 **判据要比原始 JSON 文本**——字符串 `"9.90"` 与数字 `9.9` 在 jq 里都能取到, -只有比**原始文本**才分得出来。 -🔴 **别用 `--data-urlencode` 配 `-G`**(curl 里两个互斥)——body 用 `-d`,query 用 `-G`。 -🔴 本机 curl 走系统代理 ⇒ **测 localhost 必须 `--noproxy '*'`**。 - -### 5.3 六道闸门全绿才算完 - -```bash -cargo test # 221 条(lib 98 + 集成 123) -bash scripts/check-module.sh # 静态闸门 1:10 接触点(114 条 = 4 模块 × 28 + 全局 2) -bash scripts/check-boundary.sh # 静态闸门 2:分层红线 CP1–CP6(11 条) -bash scripts/check-contract.sh # 静态闸门 3:契约端点表 + 官方端点台账 ↔ 代码真实路由(10 条) -bash scripts/check-citations.sh # 静态闸门 4:文档引文 `路径:行号`(4 条) -bash scripts/perm-smoke.sh # 契约尺子·面 A:43 条(**后端不用先起** ⇒ 不通则自起隔离实例) -bash scripts/perm-smoke-jnpf.sh # 契约尺子·面 B:19 条(面 A 不受影响时也应保持 19/19) -``` - -🔴 **两把尺子默认自起隔离后端**(`scripts/smoke_backend.sh`):没给 `B` ⇒ 先探 `:30010`, -通了就用它、**不通就自起隔离实例**(空闲端口 + 临时 `PGLITE_DIR`)⇒ 跑完即删、**不留脏数据**、 -两把尺子**互不污染**、**CI 可跑**;**显式给了 `B` ⇒ 不自起**(不可达 ⇒ 退出码 2)。 - -🔴 **每道闸门都会自证**:跑出来的条数必须等于契约 `[RULER]` 里登记的条数, -对不上 ⇒ **失败** ⇒ 尺子不会被人悄悄改弱。 -🔴 **加了断言就得同步契约**(`docs/contract.md` 附录 A 的 `[RULER]` 那一列), -否则闸门会红(这是**故意的**:提醒你契约与尺子必须一起改)。 -🔴 **加业务模块会让 `check-module.sh` 的条数变多**(每模块 20+ 条)⇒ -自证那一行会直接告诉你**实际条数**,照着改契约 `[RULER] check-module.sh` 即可。 -(`check-contract.sh` 的条数是**固定的 10** —— 端点多少条都由契约自己决定,不影响它; -`check-citations.sh` 的条数是**固定的 4** —— 引文多少条都是逐条核对,不影响它。) - -## 六、写之前的自查(5 条) - -1. **列名全 `f_` 前缀?** `f_id` 是 `VARCHAR(50)` 不是 `VARCHAR(32)`? -2. **`json_key` = 列名去 `f_` 后 camelCase?**(`f_creator_user_id` ⇒ `creatorUserId`) -3. **numeric 列标了 `numeric: true`?** `numeric_columns` 数组同步更新? -4. **`module_key` == `menu.url_address` == `App.tsx` 的 Route path?**(三处一字不差) -5. **改了 `schema.sql` 之后清空 `data/` 重建了吗?**(schema 只在首次建表时执行) - -## 七、常见坑速查 - -| 症状 | 根因 | 处理 | -|---|---|---| -| 端点 404 | 忘了在 `modules/.rs` 里写 `router()` / 忘了在 `modules/mod.rs` 里 merge | 补 `router()` + 补 merge 行 | -| 端点 500 | 表不存在 / spec 没进 `ALL_SPECS` | 补 `schema.sql` + 补 `ALL_SPECS` | -| 启动即退(白名单自检失败) | 新表没进 `db/schema.sql`(或 spec 拼错表名) | 补 DDL / 改 spec 表名(`crates/sspf-admin/src/main.rs` **不用改**) | -| 页面 404 | `App.tsx` 的 Route path ≠ 菜单 `url_address` | 三处对齐 | -| 侧栏没有这个菜单 | `modules/.rs` 没声明 `*_MENU` / 没进 `ALL_MENUS` / 没重启回灌 | 补声明 + 补 `ALL_MENUS` + **重启进程**(不必删库) | -| `check-boundary.sh` 报业务标识符泄漏 | 业务知识写进了平台层(表名 / 菜单 key / 路由前缀) | 挪回业务层;平台层只留**类型**(`EntitySpec` / `MenuSpec`) | -| 非管理员也能看 | `module_key` 是 `None` | 改成 `Some("app/Entity")` | -| 非管理员看不到也访问不了(预期) | 没授权 | 写 `base_authorize` 或调授权接口 | -| 金额变成 `9.9` | numeric 列没标 `numeric: true` | spec 标上 + `numeric_columns` 同步 | -| 改了 schema 不生效 | schema 只在首次建表执行 | 清空 `data/` 重建 | -| `check-module.sh` 退出码 2 | 契约 `[MODULE]` 里没加这个 appCode/Entity | 在 `docs/contract.md` 附录 A 加一行(**别改脚本**) | -| `check-contract.sh` 报「代码里的 xxx 没被契约登记」 | 契约附录 A 的 `[ENDPOINT]` 漏了这个模块的 3 条端点 | 补 `[ENDPOINT]` 三行(`face=A` / `guard` = `module_key` / `owner` = 模块代号) | -| `check-contract.sh` 报「守卫漂移」 | 契约写的 `guard` 与代码里的守卫不一致(多半是 `module_key` 改了) | 两边对齐(要么改 `spec.module_key`,要么改契约那一行) | -| `check-contract.sh` 报 ⚠️「推不出守卫」 | 代码里守卫的**写法**变了,扫描器静态推不出来 | 人工核对;确实是新写法 ⇒ 同步改扫描器(`check-contract-scan.py` 的 `guard_of_platform`) | -| `check-contract.sh` 报「契约登记了、代码里没有」 | `router()` 里用了 `ROUTES[0]` 而不是**字面量路径**(扫描器静态解析,认不出数组下标) | 把 `router()` 的三条 `.route("…")` 写成字面量(`ROUTES` 常量仍保留给钉子测试) | -| `POST …/Save` 返 `code=400`,日志 `column "f_xxx_time" is of type timestamp but expression is of type text` | 业务表自带的时间列没有 `::timestamp` 转换 | 不用改:`f_*_time` 后缀已被平台层 `write_cast` 统一识别;**其它类型**(numeric/integer)才需要逐列登记 | -| 闸门报「尺子被改弱了」 | 加/删了断言但没同步契约 `[RULER]` | 同步契约里那一列(这是故意的提醒) | -| 建了重复账号 | 官方 `f_account` **无 UNIQUE** | 唯一性**应用层**保证(只比 `delete_mark=0` 的行) | diff --git a/JNPF_COMPAT_SURFACE.md b/JNPF_COMPAT_SURFACE.md deleted file mode 100644 index 6ea61fa..0000000 --- a/JNPF_COMPAT_SURFACE.md +++ /dev/null @@ -1,435 +0,0 @@ -# 面 B:官方 JNPF 契约面(规格书) - -> **这份文档是「尺子的规格」** —— [`scripts/perm-smoke-jnpf.sh`](scripts/perm-smoke-jnpf.sh) 逐条断言的就是本文的每一条。 -> 官方源码依据见 [`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md)(每条带 `文件:行号`)。 - ---- - -## 0. 一句话 - -**面 A** = 本仓现有契约(ssw/react 技能那套),**一个字都不动**。 -**面 B** = 官方 JNPF 契约(官方 Vue 前端那套),**与面 A 共用同一个进程、同一个库、同一套 `base_*` 表**。 - -⇒ 官方 JNPF 的 Vue 前端,可以**直接**指着本仓的后端跑;本仓的 React 前端,也**照旧**跑。 - ---- - -## 1. 为什么需要面 B - -审计结论([`JNPF_SOURCE_AUDIT.md` §3](JNPF_SOURCE_AUDIT.md)): - -| 差异 | 能否靠「改前端」绕过 | 结论 | -|---|---|---| -| D2 列表响应(`PageListVO`) | ❌ 官方前端分页组件要 `pagination.total` | **必须后端出** | -| D3 `CurrentUser` 形状(`PcUserVO`) | ❌ 官方前端读 `permissionList` / `userInfo.*` | **必须后端出** | -| D4 码表缺 602 | ❌ 官方前端靠 602 清 token 跳登录 | **必须后端出** | -| D5 菜单接口(`ModuleBySystem`) | ❌ 官方前端启动就调 | **必须后端出** | -| D6 点权限(`f_en_code`) | ⚠️ 可前端硬编码,但不可维护 | 后端出更好 | -| D1 端点风格 | ✅ 官方前端路径写死 | **必须后端出**(新路径) | -| D7 请求头 | ✅ 忽略即可 | 后端**别拒** | -| D8 口令存储 | ✅ 换算期处理 | 迁移期一次性 | - -⇒ 结论:**「官方前端 → Rust 后端能跑」这件事,后端必须有一层官方形状**。这就是面 B。 - ---- - -## 2. 面 A / 面 B 的边界规则 - -### 2.1 路由层:面 B = 新增路径 + 少数共用路径 - -| 情况 | 处理 | -|---|---| -| 官方路径与面 A **不冲突**(`/api/permission/*`、`/api/system/*`) | **新增**面 B 路由,与面 A 并存 | -| 官方路径与面 A **冲突**(`/api/oauth/Login`、`/api/oauth/CurrentUser`、`PUT /api/permission/Authority/Data/{objectId}`) | **共用同一路由**,按规则分流(见 §2.2) | -| 官方请求体是面 A 请求体的**超集**(授权写) | 直接兼容,**零改动** | - -### 2.2 共用路由的分流规则:**按请求头 `Vue-Version: 3` 判面** - -官方前端**必然**带这三个头(`jnpf-web-apps-main/src/api/request.ts:109-112`): - -``` -App-Code: <应用编码> -Jnpf-Origin: pc -Vue-Version: 3 -``` - -🔴 **本仓前端带其中两个**(`src/frontend/src/api/request.ts:35-37`,与官方同款): - -```ts -config.headers.set('App-Code', 'sswflow'); -config.headers.set('Jnpf-Origin', 'pc'); // ← 官方也有 ⇒ **不能**用它判别 -if (token) config.headers.set('Authorization', token); -``` - -⇒ 三个官方头里,**本仓前端唯一不发的是 `Vue-Version`** ⇒ 判别只能用它。 - -⇒ **判定规则(唯一规则,全局生效)**: - -``` -请求头含 "Vue-Version: 3" ⇒ 走【面 B】官方形状 -否则 ⇒ 走【面 A】ssw 形状 -``` - -**为什么用这个头**:官方前端**无条件**携带 `Vue-Version: 3`,而本仓前端**从不**携带 ⇒ 零歧义、零配置、双方都不需要改。 -(`App-Code` 与 `Jnpf-Origin` **不作**判据 —— 本仓前端也发这两个,判了必错。) - -🔴 **红线:本仓前端禁止发 `Vue-Version` 头**(一旦发出,面 A 的请求会被误判成面 B ⇒ 契约整体错位)。 -`scripts/check-module.sh` 的「全局红线」段**静态钉住**这一条(查 `src/frontend/src/api/request.ts`), -面 B 尺子 `scripts/perm-smoke-jnpf.sh` 也**必须**带 `Vue-Version: 3`(否则面 B 请求不会被识别成面 B)—— 同一处静态自检。 - -### 2.3 三个共用路由的逐条结论 - -| 路由 | 面 A 现状 | 面 B 要求 | 判定 | -|---|---|---|---| -| `POST /api/oauth/Login` | `{token, expiresIn:7200, tokenTypeName:'bearer'}` | 官方读 `data.token`(`LoginVO.java:17`) | ✅ **零改动**(官方前端忽略多余字段) | -| `PUT /api/permission/Authority/Data/{objectId}` | body `{objectType, module:[…]}` | 官方 body = `{objectType, module, button, column, resource, form, systemIds}`(`AuthorizeDataUpForm.java:14-38`) | ✅ **零改动**(官方 body 是面 A 的**超集**;面 A 只消费 `objectType`+`module`) | -| `GET /api/oauth/CurrentUser` | `{userInfo:{4 字段}, menuList:[本仓自定义节点]}` | 官方 `PcUserVO`(`PcUserVO.java:16-34`) | ⚠️ **必须分流**(§3.3) | - ---- - -## 3. 面 B 端点规格 - -### 3.1 认证 - -#### `POST /api/oauth/Login` - -- **共用面 A**,零改动。 -- 请求:`application/x-www-form-urlencoded`,`account` / `password`(密文 hex) / `grant_type=password`。 -- 响应:`ActionResult<{token, expiresIn, tokenTypeName}>`。官方前端只读 `data.token` ⇒ 兼容。 - -#### `GET /api/oauth/CurrentUser` ★ **形状分流点** - -**面 A 形状**(无 `Vue-Version` 头)——**不动**: - -```json -{ "code":200, "msg":"操作成功", "data":{ - "userInfo":{ "userId":"…","userAccount":"admin","userName":"admin","isAdministrator":true }, - "menuList":[ …本仓菜单节点… ] } } -``` - -**面 B 形状**(带 `Vue-Version: 3`)——官方 `PcUserVO`: - -```json -{ "code":200, "msg":"操作成功", "data":{ - "menuList":[ { "id":"…","fullName":"系统管理","enCode":"…","parentId":"0","icon":"…", - "hasChildren":true,"urlAddress":"system/User","pageAddress":"…","linkTarget":null, - "children":[…],"type":1,"propertyJson":null,"sortCode":0, - "systemId":"…","isData":false } ], - "permissionList":[ { "modelId":"…","moduleName":"…","button":[],"column":[],"resource":[],"form":[] } ], - "userInfo":{ "userId":"…","userAccount":"admin","userName":"…","isAdministrator":true, - "headIcon":null,"organizeId":"…","organizeName":"…", - "positionId":"…","positionName":"…","systemId":"…","systemCode":"…", - "prevLogin":1,"prevLoginTime":…,"prevLoginIPAddress":null,"prevLoginIPAddressName":null }, - "currentSystemId":"…", - "sysConfigInfo":{ … } } } -``` - -**字段依据**: -- `PcUserVO.java`:`:19` menuList / `:22` permissionList / `:25` userInfo / `:27` currentSystemId / `:33` sysConfigInfo -- `AllMenuSelectVO.java`:`:12` id / `:15` fullName / `:18` enCode / `:21` parentId / `:24` icon / `:27` hasChildren / `:30` urlAddress / `:33` pageAddress / `:36` linkTarget / `:39` children / `:42` type / `:44` propertyJson / `:46` sortCode / `:48` systemId / `:50` isData -- `PermissionModel.java`:`:10` modelId / `:12` moduleName / `:14` button / `:16` column / `:18` resource / `:20` form -- `UserCommonInfoVO.java`:`:16` userId / `:19` userAccount / `:22` userName / `:25` headIcon / `:28` organizeId / `:31` organizeName / `:34` positionId / `:37` positionName / `:40` prevLogin / `:43` prevLoginTime / `:47` prevLoginIPAddress / `:51` prevLoginIPAddressName / `:75` isAdministrator / `:83` systemId / `:87` systemCode - -**硬性要求**: -1. 五个顶层字段**一个都不能少**(官方前端按 `menuList` + `permissionList` 渲染侧栏与按钮)。 -2. `menuList` 节点的 `type`:`1`=目录 / `2`=页面(与 `base_module.f_type` 语义一致)。 -3. `permissionList` 可为空数组 `[]`(**但不能是 `null`**)—— 官方前端遍历它。 - -> 📌 **不实现** `sysConfigInfo` 的真实内容时,返 `{}`(空对象)而不是 `null` ⇒ 官方前端不炸。 - -#### `POST /api/oauth/Logout` — 可后置 - -官方 `LoginController.java:155`。本仓 v1 无此端点(前端本地清 token)。 -**优先级:低**(官方前端退出时若 404,会在控制台报错但不影响使用)。 - -### 3.2 用户 `/api/permission/Users` - -**列表** `GET /api/permission/Users` - -请求参数(`UserPagination.java:11-36` = `Pagination.java:19-29` + 过滤): - -| 参数 | 类型 | 默认 | 说明 | -|---|---|---|---| -| `pageSize` | long | `20` | `Pagination.java:19` | -| `currentPage` | long | `1` | `Pagination.java:25` | -| `sort` | string | `"DESC"` | `Pagination.java:21` | -| `sidx` | string | `""` | `Pagination.java:23` | -| `keyword` | string | — | 关键字(`Pagination` 父类 `Page`) | -| `gender` | string | — | `UserPagination.java:14` | -| `enabledMark` | int | — | `:17`(0 禁用 / 1 启用 / 2 锁定 / 12 启用和锁定) | -| `groupId` / `organizeId` / `positionId` / `roleId` | string | — | `:20/23/26/29` | -| `showSubOrganize` | int | — | `:32` | -| `dataType` | int | — | `:35`(1 = 全部数据) | - -响应(`UserController.java:295` ⇒ `ActionResult>`): - -```json -{ "code":200, "msg":"操作成功", "data":{ - "pagination":{ "currentPage":1, "pageSize":20, "total":42 }, - "list":[ { "id":"…","account":"admin","realName":"管理员","fullName":"管理员", - "gender":null,"mobilePhone":null,"email":null,"organize":"…", - "description":null,"enabledMark":1,"creatorTime":1730000000000, - "sortCode":0,"lockMark":0,"handoverMark":0,"isAdministrator":1, - "headIcon":null,"unlockTime":null,"position":"…", - "isDutyUser":0,"maxRelationId":null } ] } } -``` - -**列表项字段依据**:`UserListVO.java:19-74`。 -**硬性要求**: -1. `data` 必须是**对象**(含 `pagination` + `list`),**不是**裸数组。 -2. `list` 项**不得**含 `password` / `secretkey`。 -3. `pagination.total` = **总条数**(不是本页条数)。 -4. `currentPage` / `pageSize` **原样回显**请求值(官方前端会算总页数)。 -5. `creatorTime` 是**毫秒时间戳(数字)**。 -6. `isAdministrator` 是**数字** `0|1`(不是布尔)—— 官方 VO 是 `Integer`(`UserListVO.java:60`)。 - -**单条 / 增 / 改 / 删**(`UserController.java:355/409/429/496`): - -| 方法 | 路径 | 官方权限码 | 面 B 行为 | -|---|---|---|---| -| GET | `/api/permission/Users/{id}` | `permission.user` | 返 `UserListVO` 同构单对象 | -| POST | `/api/permission/Users` | `permission.user` | 建号;body 用**去前缀名**(`account`/`realName`/`organizeId`/…) | -| PUT | `/api/permission/Users/{id}` | `permission.user` | 改;body 同上 + `id` 在 path | -| DELETE | `/api/permission/Users/{id}` | `permission.user` | 删;成功返 `ActionResult.success()` | - -**权限码语义(面 B)**:官方用 `@SaCheckPermission("permission.user")` ⇒ 判定依据是 -**该用户是否持有 `f_en_code = 'permission.user'` 的菜单授权**(`base_module.f_en_code`)。 -本仓的菜单路径白名单(`system/User`)在面 B **不适用** ⇒ 面 B 用 `f_en_code` 判。 - -> 🔴 **这意味着面 B 必须能读到 `f_en_code` 且种子菜单要带 `f_en_code` 值。** -> 本仓 `base_module` 表**已有 `f_en_code` 列**(官方 DDL 逐字)⇒ 列在,**值要补种子**。 - -### 3.3 角色 `/api/permission/Role` - -| 方法 | 路径 | 官方出处 | 权限码 | -|---|---|---|---| -| GET | `/api/permission/Role` | `RoleController.java:99-100` | `permission.auth` OR `permission.role` | -| GET | `/api/permission/Role/{id}` | `:273` | `permission.role` | -| POST | `/api/permission/Role` | `:122` | `permission.role` | -| PUT | `/api/permission/Role/{id}` | `:165` | `permission.role` | -| DELETE | `/api/permission/Role/{id}` | `:298` | `permission.role` | -| GET | `/api/permission/Role/Selector` | `:327` | 登录即可 | - -列表响应:`ActionResult>`(`RoleController.java:101`)—— 形状同 §3.2 的列表规则。 - -### 3.4 组织 `/api/permission/Organize` - -| 方法 | 路径 | 官方出处 | 权限码 | -|---|---|---|---| -| GET | `/api/permission/Organize/AsyncList/{id}` | `OrganizeController.java:107-110` | `permission.organize` OR `permission.user` OR `permission.role` OR … | -| GET | `/api/permission/Organize` | 前端 `organize.ts:14` | 登录即可 | -| GET | `/api/permission/Organize/{id}` | `:290` | `permission.organize` | -| POST | `/api/permission/Organize` | `:179` | `permission.organize` | -| PUT | `/api/permission/Organize/{id}` | `:212` | `permission.organize` | -| DELETE | `/api/permission/Organize/{id}` | `:315` | `permission.organize` | -| GET | `/api/permission/Organize/Selector` | `:145` | 登录即可 | - -**注意**:官方组织列表是**按 parentId 逐层取**(`AsyncList/{id}`,`id` = 父节点 id,根为 `0`)⇒ 面 B 必须支持 `AsyncList` 路径, -**不能**只有"全量列表"。 - -🔴 `AsyncList/{id}` 的响应是 `ActionResult>`(`OrganizeController.java:110-112`) -⇒ **`data` 是 `{pagination, list}`(PageListVO)**,不是裸数组。 - -### 3.5 菜单 `/api/system/Menu` - -| 方法 | 路径 | 官方出处 | 面 B 行为 | -|---|---|---|---| -| GET | `/api/system/Menu/ModuleBySystem` | `ModuleController.java:121` | **官方前端启动入口**:返该系统下的菜单**列表(平铺)** | -| GET | `/api/system/Menu/{systemId}/TreeView` | `:332` | 菜单**树** | -| GET | `/api/system/Menu/Selector/{id}` | `:267` | 上级菜单下拉 | -| GET | `/api/system/Menu/Selector/All` | `:444` | 全量下拉 | -| POST | `/api/system/Menu` | `:169-170` | 新建 | -| PUT | `/api/system/Menu/{id}` | `:194-195` | 修改 | -| GET | `/api/system/Menu/{id}` | `:248-249` | 详情 | -| DELETE | `/api/system/Menu/{id}` | `:228-229` | 删除 | - -`ModuleBySystem` 的 `systemId` 从哪来?官方前端 `api/system/menu.ts:9` 传 `data`(query)。 -**本仓单系统** ⇒ 忽略入参、返本仓全部菜单(平铺,`parentId` 表达层级)。 - -🔴 **`ModuleBySystem` 的 `data` 不是裸数组** —— 官方返回 `ActionResult>` -(`ModuleController.java:121` + `ListVO.java:19-22`)⇒ **线形是 `{ "list": [...] }`**。 -(`ListVO` 全仓只有 `list` 一个字段;`PageListVO` 才是 `pagination` + `list`。) -⇒ 尺子断言 16 判的是 **`code=200` + `data.list` 是数组**,不是「`data` 是数组」。 - -**菜单项字段**:官方 `base_module` 实体字段(`f_id`/`f_full_name`/`f_en_code`/`f_parent_id`/`f_icon`/`f_url_address`/`f_type`/`f_sort_code`/`f_system_id`/`f_property_json`/`f_link_target`/`f_page_address`) -⇒ 键名去 `f_` 前缀后 camelCase,与本仓 JSON 键名规则一致。 - -### 3.6 授权 `/api/permission/Authority` - -| 方法 | 路径 | 官方出处 | 面 B 行为 | -|---|---|---|---| -| POST | `/api/permission/Authority/Data/{objectId}/Values` | `AuthorizeController.java:99-100` | 返**权限树 + 已勾选值** | -| PUT | `/api/permission/Authority/Data/{objectId}` | `:159-160` | ✅ **与面 A 共用,零改动** | - -**`Values` 的请求体**(`DataValuesQuery.java:14-24`): - -```json -{ "type":"module", "objectType":"role", "moduleIds":"" } -``` - -- `type` = 项目类型:`module`(菜单)/ `button` / `column` / `form` / `resource` -- `objectType` = `role` / `organize` / `position` / `user`(`PermissionConst.java:8-58`) -- 🔴 `moduleIds` 是 **`String`**(逗号分隔的菜单 id),**不是数组**(`DataValuesQuery.java:19-20`) -- 🔴 `type` 为空 ⇒ 官方直接返 `ActionResult.fail(MsgCode.PS012)`(`AuthorizeController.java:112-114`)⇒ **不能省 `type`** - -**响应**:官方 `AuthorizeDataReturnVO.java:16-27` = `{ list: AuthorizeDataReturnModel[], ids: String[], all: String[] }` -(`list` = 权限树模型集合 / `ids` = 已勾选 id / `all` = 全部 id,**`all` 不含菜单 id**)。 - -🔴 **面 B v1 降级**:本仓**不实现**完整权限树模型 ⇒ 先只保证 `ids`(已勾选 id)语义正确, -`list` 可返空数组、`all` 可返本仓全部菜单 id;并在面 B 规格里标注「`list` 未与官方 `AuthorizeDataReturnModel` 逐字对齐」。 -官方前端的「授权弹窗」需要 `list` 才是完整体验 ⇒ 属面 B 后续项。 - ---- - -## 4. 码表(面 B) - -| 码 | 场景 | 官方行为 | -|---|---|---| -| 200 | 成功 | 放行 | -| 400 | 业务失败 | 提示 `msg` | -| 401 | 验证错误 | 提示 `msg` | -| 500 | 异常 | 提示 `msg` | -| 600 | 登录过期 | 提示 | -| 601 | 被踢出 | 清 token | -| **602** | **token 失效** | **清 token 跳登录** ★ 官方前端靠它 | -| 403 | 权限异常 | 跳无权限页 | - -**面 B 硬性要求**: -1. **未登录/无效 token 一律返 `602`(不是 600)** —— 官方前端 `request.ts:78-80` 只对 `TOKEN_ERROR/TOKEN_LOGGED/TOKEN_TIMEOUT` 清 token。 -2. 权限不足返 `403`。 -3. 业务失败返 `400` + `msg`(**HTTP 仍是 200**)。 - -> ⚠️ 这与**面 A 不同**(面 A 用 `600`)⇒ 同一个「未登录」场景,**面 A 返 600、面 B 返 602**。这正是分流规则要处理的地方。 - ---- - -## 5. 请求头 - -面 B **必须接受**(且**不得**因此报错): - -| 头 | 值 | 作用 | -|---|---|---| -| `Jnpf-Origin` | `pc` | 本仓前端也发 ⇒ **不作**判据 | -| `Vue-Version` | `3` | **面 B 判别依据**(§2.2)——本仓前端唯一不发的一头 | -| `App-Code` | 应用编码 | 本仓单系统 ⇒ 忽略 | -| `Authorization` | `Bearer ` | 鉴权(面 A 同) | - ---- - -## 6. 尺子:`scripts/perm-smoke-jnpf.sh` - -### 6.1 它测什么 - -**第二把尺子**(第一把是 `scripts/perm-smoke.sh`,测面 A 的 32 条断言)。 -本脚本测**官方形状**:同一个后端进程,按官方请求头 + 官方路径 + 官方响应形状断言。 - -### 6.2 断言清单(目标 18 条) - -| # | 断言 | 判据 | -|---|---|---| -| 1 | 面 A 未受影响 | 无 `Vue-Version` 头时 `CurrentUser` 仍是面 A 形状(2 字段) | -| 2 | 面 A 登录仍通 | 无头登录 → `code=200` + `token` | -| 3 | 面 B 登录 | 带 `Vue-Version: 3` 登录 → `code=200` + `data.token` | -| 4 | 面 B `CurrentUser` 顶层 5 字段 | `data` 同时有 `menuList`/`permissionList`/`userInfo`/`currentSystemId`/`sysConfigInfo` | -| 5 | 面 B `menuList` 节点形状 | **`AllMenuSelectVO` 的 15 个字段齐全**(`id`/`fullName`/`enCode`/`parentId`/`icon`/`hasChildren`/`urlAddress`/`pageAddress`/`linkTarget`/`children`/`type`/`propertyJson`/`sortCode`/`systemId`/`isData`) | -| 6 | 面 B `permissionList` 是数组 | `[]` 也算过(**不能是 null**) | -| 7 | 面 B 无 token → `602` | 不是 600、不是 401 | -| 8 | 面 B 无 token → 未知路由仍 404 | | -| 9 | 面 B 用户列表是 `PageListVO` | `data` 有 `pagination` + `list` | -| 10 | `pagination` 三字段 | `currentPage`/`pageSize`/`total` 都在 | -| 11 | `pagination.total` 是总条数 | ≥ `list.length` | -| 12 | 列表项**无** `password`/`secretkey` | 逐项检查 | -| 13 | 列表项 `isAdministrator` 是数字 | 0 或 1,不是 true/false | -| 14 | 角色列表是 `PageListVO` | 同 #9 | -| 15 | 组织列表支持 `AsyncList/{id}` | 根节点 `id=0` 能取到一级组织 | -| 16 | 菜单 `ModuleBySystem` 可达 | `code=200` + `data.list` 是数组(官方是 `ListVO`,**不是裸数组**) | -| 17 | 授权写(官方 body 超集) | 用官方完整 body 发 `PUT /api/permission/Authority/Data/{id}` → 成功且 `module` 真的写进去 | -| 18 | 授权读是 **POST** | `POST .../Data/{id}/Values` → `code=200` | - -### 6.3 进度报告(**关键设计**) - -脚本**不假装全过**: - -- 每条断言独立记 `PASS` / `FAIL` / **`SKIP(未实现)`**; -- 结尾打印 **`面 B 覆盖 N/M`**(M = 18); -- **退出码**: - - `0` = 全部 PASS; - - `1` = 有 FAIL; - - `2` = 用法错 / 后端不可达(前置错误)。 - -⇒ 在面 B 尚未实现时,它是一把**诚实量进度**的尺子(`SKIP` 计入未覆盖,不算 PASS)。 - -> **2026-10-26 当前状态**:`PASS=18 FAIL=0 SKIP=0` ⇒ **18/18 全覆盖,退出码 0**。 -> `SKIP` 机制**保留**(面 B 尚未落地的端点、或后端还没起时仍如实记 SKIP / 退出码 2)。 - -### 6.4 与面 A 尺子的关系 - -| | `perm-smoke.sh` | `perm-smoke-jnpf.sh` | -|---|---|---| -| 测的面 | A(ssw) | B(官方) | -| 判别 | 无特殊头 | `Vue-Version: 3` | -| 断言数 | 32 | 18 | -| 都要跑 | ✅ | ✅(面 B 落地后) | - -**两把契约尺子必须同时绿**(`perm-smoke.sh` 面 A + `perm-smoke-jnpf.sh` 面 B;本仓另有四道静态闸门, -合计**六道闸门**)—— 面 A 绿证明「没把原契约改坏」,面 B 绿证明「官方形状达标」。 - ---- - -## 7. 落地顺序(面 B 的实施建议) - -| 阶段 | 内容 | 产出 | 状态 | -|---|---|---|---| -| S1 | 分流机制(`Vue-Version: 3` 判面)+ 码表补 `602` | 面 A 零影响;面 B 未登录返 602 | ✅ 已落地 | -| S2 | `CurrentUser` 面 B 形状(`PcUserVO`) | 官方前端能登录并渲染侧栏 | ✅ 已落地 | -| S3 | 分页列表引擎(`PageListVO`) | 官方用户/角色/组织列表能翻页 | ✅ 已落地 | -| S4 | 菜单 `ModuleBySystem` + `f_en_code` 种子 | 官方前端能拿到菜单树 | ✅ 已落地 | -| S5 | `f_en_code` 判权 + `permissionList` | 官方前端按钮显隐正确 | ✅ 已落地(**按钮级除外,见 B4**) | -| S6 | 授权 `Values` 读取 + 完整树 | 授权弹窗可用 | ✅ 已落地(**树模型除外,见 B1**) | - -> 每阶段结束跑 `bash scripts/perm-smoke-jnpf.sh` ⇒ 覆盖数从 `0/18` 逐步爬到 `18/18`。 -> -> **2026-10-26:S1–S6 一次性落地完毕** ⇒ `bash scripts/perm-smoke-jnpf.sh` = **PASS=18 FAIL=0 SKIP=0**(18/18)。 -> **面 A 零改动** ⇒ `bash scripts/perm-smoke.sh` 仍为 **PASS=32 FAIL=0**,`cargo test` = **195 passed / 0 failed**。 -> -> 落地对照: -> | 阶段 | 落在哪 | -> |---|---| -> | S1 | `src/backend/src/platform/jnpf.rs`(`is_jnpf` / `require_login_jnpf`)、`src/backend/src/platform/envelope.rs`(`code::*` 官方码表)、`src/backend/src/platform/auth.rs`(`require_login_any`) | -> | S2 | `src/backend/src/platform/jnpf.rs`(`current_user` / `build_user_info` / `build_menu_tree` / `build_permission_list`) | -> | S3 | `src/backend/src/platform/jnpf.rs`(`Paging` / `page_list` / `list_vo`) | -> | S4 | `src/backend/src/platform/jnpf.rs`(`module_by_system`)、`src/backend/src/platform/seed.rs`(`BuiltinMenu.en_code` + 存量库 **NULL 回填**) | -> | S5 | `src/backend/src/platform/permission.rs`(`has_en_code_permission` —— **第二套判据**) | -> | S6 | `src/backend/src/platform/jnpf.rs`(`authority_values`)、`src/backend/src/routes.rs`(`POST .../Values`) | - ---- - -## 8. 已知不对齐项(如实记录) - -| # | 项 | 状态 | 影响 | -|---|---|---|---| -| B1 | `AuthorizeDataReturnVO` 的 `list`(权限树模型) | **未逐字对齐**(面 B 只保证 `ids`/`all` 语义,`list` 返空数组) | 官方授权弹窗需二次适配 | -| B2 | `sysConfigInfo` | 返 `{}` 空对象 | 官方前端不读关键字段 | -| B3 | `currentSystemId` | 返本仓固定系统 id | 单系统场景等价 | -| B4 | 按钮级权限(`btn_*`) | 未实现(`permissionList` 的 `button`/`column`/`resource`/`form` **恒空数组**) | 官方前端按钮恒显(不隐藏) | -| B5 | 数据权限方案(`ModuleDataAuthorizeLink`) | 不做 | 官方前端相关页面 404 | -| B6 | 导入导出(`ImportData`/`ExportData`/…) | 不做 | 官方前端相关按钮报错 | -| B7 | 官方 `password` 存储格式(secretkey) | 见 `JNPF_SOURCE_AUDIT.md` §6.3 | 迁官方时一次性换算 | -| **B8** | **业务菜单的 `f_en_code`** | **本仓自定占位**(`permission.demo` / `permission.shop.product` / `permission.books.book`)—— 官方没有这三个模块 | 迁官方时要改成官方编码;当前占位不与官方 `permission.*` 冲突 | -| **B9** | **`permissionList` 的粒度** | 本仓按「**每个可见菜单一条**、`modelId` = **菜单 id**」给(对齐官方前端 `permissionList.find(o => o.modelId === menuId)` 的用法) | 官方动态模型页的**按钮**仍恒显(并入 B4) | -| **B10** | **组织列表 `AsyncList/{id}` 的分页** | 本仓按父 id **逐层**取,**不分页**(`pageSize` = 本层条数) | 官方前端逐层展开可用;机构极多时需自行加 `pageSize` 过滤 | - -🔴 **本表就是官方端点台账的「偏差来源」**:`docs/contract.md` 附录 A 的 `[OFFICIAL]` 区段里, -每条官方端点的 `status` = `partial` 时,其 `note` 列指的就是这里的一条 B# -(B1 → 两个授权端点;B2/B3/B4/B9 → `CurrentUser`;B10 → `Organize/AsyncList/{id}`)。 -⇒ **改了本表 ⇒ `[OFFICIAL]` 的 `note` 也要跟着改**(否则两边说法不一致)。 -🔴 覆盖进度由 `bash scripts/check-contract.sh` 的 **CC10** 打印(当前 **8/47**)—— **算出来的**。 - ---- - -## 9. 变更记录 - -| 日期 | 变更 | -|---|---| -| 2026-10-26 | 首版。确立「面 A 不动 + 面 B 新增」的边界规则、请求头分流规则、18 条断言清单、6 阶段落地顺序、7 条已知不对齐项。 | -| 2026-10-26 | **S1–S6 全部落地**。新增 `src/backend/src/platform/jnpf.rs`(面 B 全部端点与响应形状);`routes.rs` 增 5 条面 B 路由(面 A 的 27 条**一字未动**);`seed.rs` 增 `f_en_code` 种子 + 存量库 NULL 回填;`permission.rs` 增 `has_en_code_permission`(第二套点权限判据);`envelope.rs` 补齐官方码表(含 `602`)。**尺子**:面 B `PASS=18 FAIL=0 SKIP=0`(18/18),面 A `PASS=32 FAIL=0`,`cargo test` 195/0。新增不对齐项 B8–B10。 | diff --git a/JNPF_SOURCE_AUDIT.md b/JNPF_SOURCE_AUDIT.md deleted file mode 100644 index 47f0512..0000000 --- a/JNPF_SOURCE_AUDIT.md +++ /dev/null @@ -1,656 +0,0 @@ -# 官方 JNPF 源码审计(本技能的「官方面」地基) - -> 这份文档回答**一个**问题:**本技能(Rust 模板)的契约与官方 JNPF(Java)到底差在哪、哪些已经对齐了。** -> -> 全部结论来自对官方源码的**逐行核对**,每条带 `文件:行号`。 -> 官方源码坐标:`~/Desktop/workspace/jnpf/`(下文所有路径均相对它)。 -> 核对日期:**2026-10-26**。官方版本:`jnpf-web-apps-main`(Vue3 前端)+ `jnpf-java-boot`(Java 后端)。 - -**配套阅读**: -- 契约红线(权威)→ [`SKILL.md`](SKILL.md) §契约红线 + [`PERMISSION.md`](PERMISSION.md) -- 迁移操作(怎么做)→ [`MIGRATION.md`](MIGRATION.md) -- 面 B 规格(要做到什么程度)→ [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md) -- 实施期裁决 → 参照实现仓的 `docs/decisions.md`(`~/Desktop/workspace/ssw-jnpf-lite-rust/docs/decisions.md`) - -> 📌 下文的「本仓」= 本技能的 Rust 模板(`src/backend` + `src/frontend`)。 -> 模板与参照实现仓 `~/Desktop/workspace/ssw-jnpf-lite-rust/` 的 `src/` **逐字节一致**(只差 `data/` 与 `dist/`)。 - ---- - -## 0. 怎么用这份文档 - -| 你的处境 | 读哪节 | -|---|---| -| 只想知道「能不能迁、差多少」 | §1 + §2 + §8 | -| 要动手迁(Rust → JNPF Java) | §6(口令换算)+ §8(对齐清单),再按 [`MIGRATION.md`](MIGRATION.md) 走 | -| 要让官方 Vue 前端跑在 Rust 后端上 | §2(8 条差异)+ §3(官方端点全表),规格见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md) | -| 怀疑某条结论 | §9(复现命令),自己核一遍 | - ---- - -## 1. 审计范围与坐标 - -| 层 | 官方路径 | 本仓对应 | -|---|---|---| -| 统一信封 | `jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/base/ActionResult.java` | `src/backend/src/platform/envelope.rs` | -| 错误码表 | 同上目录 `ActionResultCode.java` | `src/backend/src/platform/envelope.rs` | -| 登录 | `jnpf-java-boot/jnpf-oauth/jnpf-oauth-controller/.../controller/LoginController.java` | `src/backend/src/platform/auth.rs` | -| 口令解密 | `jnpf-java-boot/jnpf-oauth/jnpf-oauth-biz/.../granter/PasswordTokenGranter.java` | `src/backend/src/platform/cipher.rs` | -| 加解密工具 | `jnpf-common/.../jnpf/util/DesUtil.java` | `src/backend/src/platform/cipher.rs` | -| 安全配置 | `jnpf-common/.../jnpf/properties/SecurityProperties.java` | `src/backend/src/platform/cipher.rs` | -| 用户/角色/组织/授权 | `jnpf-java-boot/jnpf-permission/jnpf-permission-controller/.../controller/*.java` | `src/backend/src/platform/sys.rs` / `permission.rs` | -| 菜单 | `jnpf-java-boot/jnpf-system/jnpf-system-controller/.../controller/ModuleController.java` | `src/backend/src/platform/sys.rs` | -| 前端 API 面 | `jnpf-web-apps-main/src/api/**` | `src/frontend/src/api/**` | -| 前端加密 | `jnpf-web-monorepo-framework/packages/jnpf/utils/src/helpers/cipher.ts` | `src/frontend/src/utils/cipher.ts` | -| DDL | `jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql` | `src/backend/db/schema.sql` | - ---- - -## 2. §1 地基:**已经对齐**的部分 - -这 9 条是「能 1:1 迁走」的资产 —— 迁到官方 JNPF 时**不用改数据模型、也不用重写加密**。 - -### 2.1 统一返回信封 —— 逐字一致 ✅ - -官方 `ActionResult.java`: - -| 字段 | 行号 | -|---|---| -| `private Integer code;` | `ActionResult.java:27` | -| `private String msg;` | `ActionResult.java:30` | -| `private T data;` | `ActionResult.java:33` | -| `fail(Integer code, String message)` | `ActionResult.java:69` | -| `page(List, PaginationVO)` | `ActionResult.java:92` | - -**本仓**:`envelope.rs` 的 `ActionResult{code,msg,data}` + 「业务失败一律 HTTP 200」——**与官方一致**。 -官方同样是「HTTP 200 + body.code 表示成败」,错误由 `@RestControllerAdvice` 兜住(官方 `ResultExceptionHand`)。 - -> ⚠️ **注意与 `tdc-rs` 相反**:`tdc-rs` 用 401/403 裸 body。**别把它的形状抄过来。** - -### 2.2 错误码表 —— 本仓用了官方码表的前 4 个 ✅ - -官方 `ActionResultCode.java`(枚举,值即 HTTP 语义): - -| 码 | 含义 | 行号 | -|---|---|---| -| 200 | 成功 | `:19` | -| 400 | 失败 | `:23` | -| 401 | 验证错误 | `:27` | -| 500 | 异常 | `:31` | -| **600** | 登录过期 | `:35` | -| **601** | 被踢出 | `:39` | -| **602** | token 失效 | `:43` | -| 403 | 权限异常 | `:47` | - -**本仓**已用:`200` / `400` / `403` / `600`(**与官方字面一致**)。缺口见 §3.4。 - -### 2.3 登录路径与参数 —— 逐字一致 ✅ - -| 项 | 官方 | 本仓 | -|---|---|---| -| 登录 | `POST /api/oauth/Login`(`LoginController.java:117-119`;`api/core/auth.ts:6,28`) | ✅ 同路径同方法 | -| 编码 | `Content-Type: application/x-www-form-urlencoded`(`api/core/auth.ts:28`) | ✅ 同 | -| 参数 | `account` / `password` / `grant_type=password`(`api/core/auth.ts:13-21`;`LoginForm.vue:149`) | ✅ 同(`grant_type` **不加 camelCase**) | -| 附加参数 | `origin: 'password'`(`LoginForm.vue:84`)、`code?` / `timestamp?` / `jnpf_ticket?` | 本仓**只读必填三项**,多余参数忽略(可接受) | -| 登出 | `POST /api/oauth/Logout`(`LoginController.java:155`;`api/core/auth.ts:48`) | 本仓无登出端点(前端本地清 token)—— **见 §3 补项** | -| 当前用户 | `GET /api/oauth/CurrentUser`(`LoginController.java:192-194`) | ✅ 同路径(**返回体不同**,见 §3.3) | - -### 2.4 口令加密链 —— 逐字节一致 ✅ ★ - -这是整个迁移里**最容易被误判为"要重写"**的一块。核对结论:**前后端逐字节一致,不需要重写**。 - -**官方前端**(`jnpf-web-monorepo-framework/packages/jnpf/utils/src/helpers/cipher.ts`): - -| 步骤 | 行号 | 内容 | -|---|---|---| -| key 派生 | `:15` | `defaultKey = encryptByMd5(VITE_CIPHER_KEY)` ⇒ **32 个 hex 字符** | -| key 落地 | `:24` | `this.key = parse(key)` ⇒ UTF-8 **32 字节** ⇒ **AES-256**(不是 AES-128!) | -| 模式 | `:42-43` | `mode: ECB` + `padding: pkcs7` ⇒ **AES-256-ECB-PKCS7** | -| 输出 | `:20,:26,:36` | `useHex = true` ⇒ 输出 **hex** | -| md5 | `:56-57` | `md5(password).toString()` ⇒ **小写 hex** | - -**官方前端调用点**(`jnpf-web-apps-main/src/views/_core/login/LoginForm.vue`): - -``` -:140 const password = encryptByMd5(data.password); // 明文 → md5 小写 hex -:141 const encryptPassword = aesEncryption.encryptByAES(password); // → AES-256-ECB → hex -:144 password: encryptPassword, -:149 grant_type: 'password', -``` - -**官方服务端解密链**: - -| 步骤 | 位置 | 内容 | -|---|---|---| -| 解密 | `PasswordTokenGranter.java:180` | `inputPwd = DesUtil.aesOrDecode(inputPwd, false, true)` | -| 取 key | `DesUtil.java:297` | `SecurityProperties.getInstance().getSecurityKey()` | -| key 派生 | `SecurityProperties.java:71-72` | `this.securityKey = Md5Util.getStringMd5(securityKey)` ⇒ **32 个 ASCII 字节** | -| 解密器 | `DesUtil.java:313,316` | Hutool `SymmetricCrypto(SymmetricAlgorithm.AES, keyBytes)` ⇒ **ECB/PKCS5Padding** | -| 比对 | `PasswordTokenGranter.java:186` | `Md5Util.getStringMd5(inputPwd + secretkey.toLowerCase())` | - -**本仓**(`src/backend/src/platform/cipher.rs`):key = `md5_hex("EY8WePvjM5GGwQzn")` 的 **32 个 ASCII 字节** ⇒ AES-256-ECB-PKCS7,输出 hex,明文 = `md5_hex(raw)`。 - -> 🔴 **结论**:本仓与官方**同一套算法**。迁移时只需对齐**两个配置值**: -> - 前端 `VITE_CIPHER_KEY` ↔ 后端 `security.security-key`(官方 `SecurityProperties.setSecurityKey` 会自动 md5) -> - 官方默认值 `EY8WePvjM5GGwQzn`(JNPF 默认安全密钥) -> -> 检验向量(官方与本仓都必须过): -> `encryptPassword('123456')` == -> `d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b` - -### 2.5 口令**存储**公式 —— 差一步 ✅(可换算,见 §6) - -官方(`UserServiceImpl.java`): - -``` -:547 entity.setSecretkey(RandomUtil.uuId()); -:548 entity.setPassword( -:549 Md5Util.getStringMd5(entity.getPassword().toLowerCase() + entity.getSecretkey().toLowerCase())); -``` - -(重置口令同式:`:704-706`) - -⇒ 官方库里存的是 **`md5( md5_hex(明文) + secretkey )`**。 - -**本仓**库里存的是 **`md5_hex(明文)`** —— 正好是官方公式的**中间态**(未加 secretkey)。 -⇒ 迁移**不需要明文**,见 §6 的换算公式。 - -### 2.6 `base_*` 表名与列名 —— 逐字一致 ✅ - -本仓实现的 7 张 `base_*`(`base_authorize` / `base_module` / `base_organize` / `base_role` / `base_role_relation` / `base_user` / `base_user_relation`)与官方 DDL -(`jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql`)**列级零缺口**。 - -官方实体侧的列名映射(`@TableField`)与本仓一致,例: -`AuthorizeEntity.java:19,25-44` ⇒ 表 `base_authorize`,列 `f_item_type` / `f_item_id` / `f_object_type` / `f_object_id`。 - -**两个官方陷阱本仓已按原样保留**(不修正): -- `base_role_relation` 用户 id 在 **`f_object_id`**(配 `f_object_type='user'`),无 `f_user_id`; -- 组织/岗位关系在 **`base_user_relation`**,那里才有 `f_user_id`。 - -### 2.7 授权写入端点 —— 路径与 body 形状都一致 ✅ - -官方:`AuthorizeController.java:159-160` ⇒ `PUT /api/permission/Authority/Data/{objectId}`, -body = `AuthorizeDataUpForm`(`AuthorizeDataUpForm.java:14-38`): - -| 字段 | 行号 | 类型 | -|---|---|---| -| `objectId` | `:17` | `String` | -| `objectType` | `:20` | `String` | -| `button` | `:23` | `String[]` | -| `column` | `:26` | `String[]` | -| **`module`** | `:29` | **`String[]`** | -| `resource` | `:32` | `String[]` | -| `form` | `:35` | `String[]` | -| `systemIds` | `:38` | `String[]` | - -**本仓**:`PUT /api/permission/Authority/Data/{objectId}`,body `{objectType:'role', module:[...]}`。 -⇒ **路径一致、`module` 是一维数组一致、`objectType` 小写 `'role'` 与官方 `PermissionConst.ROLE = "role"`(`PermissionConst.java:18`)一致。** -本仓只是官方 body 的**子集**(只写 `module`,不写 button/column/…)—— 官方对未出现的字段不处理 ⇒ 兼容。 - -### 2.8 角色/组织/用户的官方对象类型常量 —— 一致 ✅ - -`PermissionConst.java`: - -| 常量 | 值 | 行号 | -|---|---|---| -| `ORGANIZE` | `"organize"` | `:8` | -| `POSITION` | `"position"` | `:13` | -| `ROLE` | `"role"` | `:18` | -| `PERMISSION_GROUP` | `"permissionGroup"` | `:23` | -| `COMPANY` / `DEPARTMENT` / `GROUP` / `SYSTEM` / `STAND` | 对应小写 | `:28/33/38/43/48` | -| `MODULE` | `"module"` | `:53` | -| `USER` | `"user"` | `:58` | -| 按钮权限 | `btn_add` / `btn_edit` / `btn_remove` / `btn_detail` / `btn_upload` / `btn_download` / `btn_batchRemove` / `btn_batchPrint` | `:63-77` | - -**本仓 `objectType` 取值与之字面一致**(`'role'` / `'user'` / `'organize'` / `'position'`)。 - -### 2.9 主键与租户列 —— 一致 ✅ - -- 主键 `f_id` = **36 位 UUID v4**(带连字符),列 `varchar(50)`。 -- 单租户固定 `f_tenant_id = '0'`(官方 `jnpf-tenant*` 系列本仓明确不碰)。 - ---- - -## 3. §2 差异:**8 条**,按迁移成本排序 - -| # | 差异 | 官方 | 本仓 | 迁移成本 | 面 B 工作量 | -|---|---|---|---|---|---| -| D1 | 端点风格 | RESTful | ssw 约定 | **低**(映射表即可) | 中(要新路由) | -| D2 | 列表响应 | `PageListVO` | 全量数组 | **低** | 中 | -| D3 | `CurrentUser` 形状 | `PcUserVO`(5 字段) | 2 字段 | **低** | 小 | -| D4 | 码表缺项 | 401/500/601/602 | 只有 200/400/403/600 | **低** | 小 | -| D5 | 菜单接口 | `/api/system/Menu/ModuleBySystem` | `/api/ssw/sys/Module/List` | **低** | 小 | -| D6 | 鉴权模型 | `f_en_code` 点权限 | 菜单路径白名单 | **中** | 中 | -| D7 | 请求头 | `App-Code` / `Jnpf-Origin: pc` / `Vue-Version: 3` | 前端发 `App-Code: sswflow` + `Jnpf-Origin: pc`(**不发** `Vue-Version`) | **低**(但 `Vue-Version` 是**面 A/面 B 判别依据** ⇒ 本仓前端**禁发**它,见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md) §2.2) | 小 | -| D8 | 口令存储 | `md5(md5(raw)+secretkey)` | `md5(raw)` | **低**(有换算公式,§6) | 中 | - -### 3.1 D1 — 端点风格 - -官方是 **RESTful**(`@RequestMapping` + `@GetMapping`/`@PostMapping`/`@PutMapping`/`@DeleteMapping`): - -| 官方前缀 | 控制器 | 行号 | -|---|---|---| -| `/api/permission/Users` | `UserController.java` | `:153` | -| `/api/permission/Role` | `RoleController.java` | `:85` | -| `/api/permission/Organize` | `OrganizeController.java` | `:88` | -| `/api/permission/Authority` | `AuthorizeController.java` | `:75` | -| `/api/system/Menu` | `ModuleController.java` | `:101` | -| `/api/oauth` | `LoginController.java` | `:86` | - -本仓是 **ssw 约定**:`/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`。 - -**这一条是「双面后端」存在的根本原因** —— 见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)。 - -> 📌 官方 ssw 前端(`ssw-jnpf-lite-react`)自己也**没有**用 ssw 路径去迁官方 —— 它的 `MIGRATION.md` 明确写了: -> 「端点命名 `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`(ssw 约定,非官方 visualdev 路径;稳定期真实 JNPF 由引擎生成,路径以引擎为准,**数据模型仍保值**)」。 -> ⇒ **数据模型保值(本仓已做到),路径在迁官方时重新映射**。这正是本仓设计意图,不是缺陷。 - -### 3.2 D2 — 列表响应:`PageListVO` ✅(**本条要更正一个常见误解**) - -官方 `PageListVO.java`: - -```java -:17 PaginationVO pagination; // ← 官方**有**分页元数据 -:19 private List list; -``` - -`PaginationVO.java`:`currentPage`(`:16`) / `pageSize`(`:18`) / `total`(`:20`)。 - -⇒ 官方分页响应形状是: - -```json -{ "code":200, "msg":"操作成功", "data": { "pagination": {"currentPage":1,"pageSize":20,"total":42}, "list":[ ... ] } } -``` - -**本仓**:`data` 直接是**全量数组**(契约 §6 明确「分页不在 v1 范围」)。 - -分页请求参数(官方 `Pagination.java`):`pageSize=20`(`:19`) / `sort="DESC"`(`:21`) / `sidx=""`(`:23`) / `currentPage=1`(`:25`) / `total`(`:27`) / `records`(`:29`)。 - -> 🔴 **常见误解**:「官方 `PageListVO` 就是 `{list:[...]}`」—— **错**,它还有 `pagination`。 -> 迁官方时若只回 `{list}`,官方前端的分页组件会拿不到 `total` ⇒ 退化成「只显示第一页」。 - -**本仓无分页** ⇒ 迁到官方后**必须补**(或在官方侧改成不分页组件)。这是**迁 JNPF 时的必做项**,不是可选优化。 - -### 3.3 D3 — `CurrentUser` 形状 - -官方 `PcUserVO.java`: - -| 字段 | 类型 | 行号 | -|---|---|---| -| `menuList` | `List` | `:19` | -| `permissionList` | `List` | `:22` | -| `userInfo` | `UserCommonInfoVO` | `:25` | -| `currentSystemId` | `String` | `:27` | -| `sysConfigInfo` | `SystemInfo` | `:33` | - -`AllMenuSelectVO.java`:`id`(`:12`) / `fullName`(`:15`) / `enCode`(`:18`) / `parentId`(`:21`) / `icon`(`:24`) / `hasChildren`(`:27`) / `urlAddress`(`:30`) / `pageAddress`(`:33`) / `linkTarget`(`:36`) / `children`(`:39`) / `type`(`:42`) / `propertyJson`(`:44`) / `sortCode`(`:46`) / `systemId`(`:48`) / `isData`(`:50`)。 -`PermissionModel.java`:`modelId`(`:10`) / `moduleName`(`:12`) / `button`(`:14`) / `column`(`:16`) / `resource`(`:18`) / `form`(`:20`)。 -`UserCommonInfoVO.java`:`userId`(`:16`) / `userAccount`(`:19`) / `userName`(`:22`) / `headIcon`(`:25`) / `organizeId`(`:28`) / `organizeName`(`:31`) / `positionId`(`:34`) / `positionName`(`:37`) / `isAdministrator`(`:75`) / `systemId`(`:83`) / `systemCode`(`:87`) … - -**本仓**(`docs/contract.md:435`): - -```json -{ "code":200, "data":{ "userInfo":{ "userId":"…","userAccount":"admin","userName":"admin","isAdministrator":true }, "menuList":[ … ] } } -``` - -⇒ 缺 `permissionList` / `currentSystemId` / `sysConfigInfo`;`userInfo` 只有 4 个字段;`menuList` 节点字段是本仓自定义(**非** `AllMenuSelectVO` 形状)。 - -> 📌 **对齐建议(面 B)**:面 B 的 `CurrentUser` **直接返回官方 `PcUserVO` 形状**(`menuList` 用 `AllMenuSelectVO` 的 15 个字段、`userInfo` 至少补 `isAdministrator`/`organizeId`/`organizeName`/`positionId`/`positionName`/`systemId`/`systemCode`)。 -> 面 A 保持不变(§1 的 2 字段形状不能动,那是 ssw 契约)。 - -### 3.4 D4 — 码表缺项 - -本仓**没有** `401`(验证错误)/ `500`(异常)/ `601`(被踢出)/ `602`(token 失效)。 - -官方前端 `jnpf-web-apps-main/src/api/request.ts` 的响应拦截器**按 `code` 分支**: - -``` -:70 case ResultEnum.FORBIDDEN → 跳无权限页(:74 authStore.goForbidden()) -:78 case ResultEnum.TOKEN_ERROR -:79 case ResultEnum.TOKEN_LOGGED -:80 case ResultEnum.TOKEN_TIMEOUT → 清 token 跳登录 -``` - -⇒ 官方前端**期待** `601/602` 用来触发「清 token 跳登录」。本仓只有 `600` ⇒ 官方前端拿到 `600` 会走**默认分支**(`msg` 提示但不跳登录)⇒ **表现为「token 失效后页面卡住」**。 - -**面 B 必须**:`600` → `602`(token 失效);`601`(被踢出)可后置。 - -### 3.5 D5 — 菜单接口 - -官方 `ModuleController.java`: - -| 端点 | 行号 | 用途 | -|---|---|---| -| `GET /api/system/Menu/ModuleBySystem` | `:121` | **官方前端取菜单的入口**(`api/system/menu.ts:8-9`) | -| `GET /api/system/Menu/{systemId}/TreeView` | `:332` | 菜单树(管理端) | -| `GET /api/system/Menu/Selector/{id}` | `:267` | 上级菜单下拉 | -| `GET /api/system/Menu/Selector/All` | `:444` | 菜单下拉(全量) | -| `POST /api/system/Menu` | `:169-170` | 新建 | -| `PUT /api/system/Menu/{id}` | `:194-195` | 修改 | -| `GET /api/system/Menu/{id}` | `:248-249` | 详情 | -| `DELETE /api/system/Menu/{id}` | `:228-229` | 删除 | -| `PUT /api/system/Menu/{id}/Actions/State` | `:498-499` | 启停 | - -**本仓**:`/api/ssw/sys/Module/{List,Save,Delete}`。 - -⇒ 官方前端要的 `ModuleBySystem`(按 systemId 取菜单)本仓**没有对应面**。 -注意:`ModuleBySystem` 返回的是**菜单列表(平铺)**,不是树;树在前端组。 - -### 3.6 D6 — 鉴权模型:点权限 vs 菜单路径 - -**官方**:Sa-Token 的 `@SaCheckPermission`,权限码是 `permission.{对象}` + `btn_*` 按钮码: - -| 端点 | 权限码 | 行号 | -|---|---|---| -| `GET /api/permission/Users` | `permission.organize` OR `permission.user` OR `permission.role` | `UserController.java:293-294` | -| `POST /api/permission/Users` | `permission.user` | `UserController.java:409-410` | -| `GET /api/permission/Role` | `permission.auth` OR `permission.role` | `RoleController.java:99-100` | -| `GET /api/permission/Organize/AsyncList/{id}` | `permission.organize` OR `permission.user` OR `permission.role` OR … | `OrganizeController.java:107-108` | -| `GET /api/system/Menu/ModuleBySystem` | 无(登录即可) | `ModuleController.java:121` | -| `PUT /api/permission/Authority/Data/{objectId}` | `permission.auth` OR `permission.role` | `AuthorizeController.java:159` | - -这些码来自 `base_module.f_en_code`(`PermissionConst.java:8-58` 的常量拼成 `permission.` + 对象名)。 - -**本仓**:按**菜单路径**(`system/User`)做守卫(`permission.rs` 的 `guard_module`)。 - -⇒ **两套模型语义不同**(点权限 vs 菜单路径)。本仓的模型是 ssw 前端定制的;官方前端是按 `f_en_code` 判按钮显隐。 -**迁官方时必须补 `f_en_code` 维度**,否则官方前端所有按钮都不可见(因为 `permissionList` 拿不到东西)。 - -> ✅ **2026-10-26 已处理**:面 B(官方 JNPF 契约面)落地 ⇒ 本仓**两套判据并存**: -> 面 A 仍按菜单路径(`f_url_address`),面 B 按 `f_en_code` 点权限 -> (`permission.rs` 的 `has_en_code_permission`,种子已补 8 条 `f_en_code`)。 -> 🔴 **按钮级权限(`btn_*`)仍未实现**(面 B `permissionList` 的四个数组恒空)⇒ 见 -> `JNPF_COMPAT_SURFACE.md` §8 的 B4。 - -### 3.7 D7 — 请求头 - -官方 `jnpf-web-apps-main/src/api/request.ts`: - -``` -:109 config.headers['App-Code'] = getRealJnpfAppEnCode(); -:111 config.headers['Jnpf-Origin'] = 'pc'; -:112 config.headers['Vue-Version'] = '3'; -``` - -⇒ 官方后端会读 `App-Code` 决定**应用/系统上下文**(多应用隔离)。本仓单租户单应用 ⇒ **可忽略**(但面 B 建议原样接受并忽略,别返回 400)。 - -🔴 **但 `Vue-Version: 3` 不是"可忽略"的**——它是**面 A / 面 B 的判别依据**: - -- 本仓前端 `src/frontend/src/api/request.ts:35-36` **也发** `App-Code: sswflow` 与 `Jnpf-Origin: pc`(与官方同款), - **只不发** `Vue-Version` ⇒ 三个官方头里**只有它是本仓前端唯一不发的** ⇒ 判别只能用它。 -- 🔴 **本仓前端禁止发 `Vue-Version`**(一旦发出,面 A 请求会被误判成面 B ⇒ 契约整体错位)。 -- 分流规则全文见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md) §2.2; - `scripts/check-module.sh` 的「全局红线」段静态钉住两侧(前端**禁发** + 面 B 尺子**必带**)。 - -### 3.8 D8 — 口令存储缺 `secretkey` - -见 §2.5。**影响**: -- 本仓的口令 hash **不能直接塞进官方库**(官方登录会比对 `md5(md5(raw)+secretkey)`)⇒ 必须走 §6 的换算; -- 本仓 `base_user.f_secretkey` 列**已存在**(本仓 `schema.sql:142`;官方 DDL `:4503`)⇒ 迁移时补写即可; -- 本仓的 `f_password` 值 = `md5_hex(raw)` ⇒ **正是官方公式的输入** ⇒ 换算**不需要明文**。 - ---- - -## 4. §3 官方端点全表(后台最小可用面) - -**这是「官方 Vue 前端要能跑」的最小集合**。官方 `src/api` 共 97 个 `.ts`、`api/permission/` 14 个、`user.ts` 单文件 16 个端点 ⇒ 官方全量远大于此表。表中只列**系统管理**这一条线。 - -🔴 **本表是「散文版」;机器可读的覆盖账本在 [`docs/contract.md`](docs/contract.md) 附录 A 的 -`[OFFICIAL]` 区段**(53 行,含每个官方端点的 `status` 与官方出处 `文件:行号`)⇒ -由 `scripts/check-contract.sh` 的 **CC10** 与**代码里真实注册的路由双向对账** ⇒ -**「官方端点覆盖 N/M」是算出来的,不是人数的**(当前 **8/47**)。 -🔴 **两处要一起改**:官方端点表改了 ⇒ `[OFFICIAL]` 对应的行也要改(否则 CC10 判漂移)。 - -### 4.1 认证 - -| 方法 | 路径 | 官方出处 | 返回 | -|---|---|---|---| -| POST | `/api/oauth/Login` | `LoginController.java:117` | `ActionResult`(`LoginVO.java:17` = `token`) | -| POST | `/api/oauth/Logout` | `LoginController.java:155` | `ActionResult` | -| GET | `/api/oauth/CurrentUser` | `LoginController.java:192` | `ActionResult` | - -> 📌 官方 `LoginVO` 字段:`token`(`:17`) / `theme`(`:20`) / `wlQrcode`(`:25`) / `isSaas`(`:28`) / `saasList`(`:31`)。 -> 本仓返回的是 `{token, expiresIn:7200, tokenTypeName:'bearer'}` —— **多两个字段,但 `token` 同名同义** ⇒ 官方前端能取到 token(它只读 `data.token`)。 -> `expiresIn` / `tokenTypeName` 是本仓 ssw 契约的字段,**面 A 保留**;面 B 可另返官方形状或同返(官方前端忽略多余字段)。 - -### 4.2 用户(`/api/permission/Users`) - -| 方法 | 路径 | 官方出处 | 权限码 | -|---|---|---|---| -| GET | `/api/permission/Users` | `UserController.java:293` | `permission.organize\|user\|role` | -| GET | `/api/permission/Users/{id}` | `:355` | `permission.user` | -| POST | `/api/permission/Users` | `:409` | `permission.user` | -| PUT | `/api/permission/Users/{id}` | `:429` | `permission.user` | -| DELETE | `/api/permission/Users/{id}` | `:496` | `permission.user` | -| POST | `/api/permission/Users/BatchDelete` | `:592` | `permission.user` | -| POST | `/api/permission/Users/BatchUpdateState` | `:694` | `permission.user` | -| GET | `/api/permission/Users/All` | `:729` | 登录即可 | -| GET | `/api/permission/Users/Selector` | `:769` | 登录即可 | -| POST | `/api/permission/Users/UserCondition` | `:806` | 登录即可 | -| GET | `/api/permission/Users/{id}/GetPosition` | `:273` | `permission.user` | -| POST | `/api/permission/Users/{id}/Actions/ResetPassword` | 前端 `user.ts:37` | `permission.user` | -| PUT | `/api/permission/Users/{id}/Actions/unlock` | 前端 `user.ts:45` | `permission.user` | -| GET | `/api/permission/Users/ExportData` | 前端 `user.ts:53` | 导入导出(可后置) | -| GET/POST | `.../TemplateDownload` · `.../ImportData` · `.../ImportPreview` · `.../ExportExceptionData` | 前端 `user.ts:57-69` | 导入导出(可后置) | -| POST | `/api/permission/Users/getUserList` · `.../getSelectedList` · `.../getSelectedUserList` | 前端 `user.ts:49,73,77` | 批量选择(可后置) | - -**列表响应**:`ActionResult>`(`UserController.java:295`)。 -**请求参数**:`UserPagination`(`UserPagination.java:11-36`)= `Pagination` + `gender` / `enabledMark` / `groupId` / `organizeId` / `positionId` / `roleId` / `showSubOrganize` / `dataType`。 -**列表项**:`UserListVO`(`UserListVO.java:16-74`)= `id` / `account` / `realName` / `fullName` / `gender` / `mobilePhone` / `email` / `organize` / `description` / `enabledMark` / `creatorTime` / `sortCode` / `lockMark` / `handoverMark` / `isAdministrator` / `headIcon` / `unlockTime` / `position` / `isDutyUser` / `maxRelationId` … - -> 📌 **注意**:`UserListVO` **没有 `password` 字段** ⇒ 官方列表天然不泄口令。本仓列表也是手工挑字段去掉 `password` ⇒ **一致**。 - -### 4.3 角色(`/api/permission/Role`) - -| 方法 | 路径 | 官方出处 | 权限码 | -|---|---|---|---| -| GET | `/api/permission/Role` | `RoleController.java:99-100` | `permission.auth\|role` | -| GET | `/api/permission/Role/{id}` | `:273` | `permission.role` | -| POST | `/api/permission/Role` | `:122` | `permission.role` | -| PUT | `/api/permission/Role/{id}` | `:165` | `permission.role` | -| DELETE | `/api/permission/Role/{id}` | `:298` | `permission.role` | -| GET | `/api/permission/Role/Selector` | `:327` | 登录即可 | -| POST | `/api/permission/Role/RoleCondition` | `:342` | 登录即可 | - -列表响应:`ActionResult>`(`RoleController.java:101`)。 - -### 4.4 组织(`/api/permission/Organize`) - -| 方法 | 路径 | 官方出处 | 权限码 | -|---|---|---|---| -| GET | `/api/permission/Organize/AsyncList/{id}` | `OrganizeController.java:107-110` | `permission.organize\|user\|role\|…` | -| GET | `/api/permission/Organize` | 前端 `organize.ts:14` | 登录即可 | -| GET | `/api/permission/Organize/{id}` | `:290` | `permission.organize` | -| POST | `/api/permission/Organize` | `:179` | `permission.organize` | -| PUT | `/api/permission/Organize/{id}` | `:212` | `permission.organize` | -| DELETE | `/api/permission/Organize/{id}` | `:315` | `permission.organize` | -| GET | `/api/permission/Organize/Selector` | `:145` | 登录即可 | -| POST | `/api/permission/Organize/SelectedList` | `:341` | 登录即可 | - -列表响应:`ActionResult>`(`OrganizeController.java:111-112`)。 - -### 4.5 菜单(`/api/system/Menu`) - -见 §3.5 的表。`GET /api/system/Menu/ModuleBySystem` 是**官方前端的菜单入口**。 - -### 4.6 授权(`/api/permission/Authority`) - -| 方法 | 路径 | 官方出处 | 权限码 | -|---|---|---|---| -| POST | `/api/permission/Authority/Data/{objectId}/Values` | `AuthorizeController.java:99-100` | `permission.auth\|role` | -| PUT | `/api/permission/Authority/Data/{objectId}` | `:159-160` | `permission.auth\|role` | -| GET | `/api/permission/Authority/Model/{itemId}/{objectType}` | `:124-125` | `permission.auth\|role\|onlineDev.visualPortal` | -| PUT | `/api/permission/Authority/Model/{portalManageId}` | `:138-139` | `permission.auth\|role` | - -读取授权树用 **`POST`**(不是 GET)—— 官方前端 `api/permission/auth.ts:9` 确认。 - -### 4.7 数据权限链接(v1 不做) - -`/api/system/ModuleDataAuthorizeLink/**`(`api/system/authorize.ts:4`)—— 官方是**低代码数据权限方案**(表/字段级),本仓 v1 明确不碰(见 `CLAUDE.md`「明确不在 v1 范围」)。 - ---- - -## 5. §4 官方码表(本仓需要补的) - -| 码 | 官方枚举 | 行号 | 官方前端行为 | 本仓 | 面 B 需要 | -|---|---|---|---|---|---| -| 200 | `SUCCESS` | `ActionResultCode.java:19` | 放行 | ✅ 有 | — | -| 400 | `FAIL` | `:23` | 提示 msg | ✅ 有 | — | -| 401 | `VALIDATEERROR` | `:27` | 提示 msg | ❌ 无 | 建议补 | -| 500 | `EXCEPTION` | `:31` | 提示 msg | ❌ 无 | 建议补 | -| 600 | `SESSIONOVERDUE` | `:35` | 过期提示 | ✅ 有 | 保留 | -| 601 | `SESSIONOFFLINE` | `:39` | 被踢出 | ❌ 无 | 建议补 | -| 602 | `SESSIONERROR` | `:43` | **清 token 跳登录** | ❌ 无 | **必补** | -| 403 | `PEIMISSIONEXP` | `:47` | 跳无权限页 | ✅ 有 | 保留 | - ---- - -## 6. §5 口令三段式与换算公式 - -### 6.1 官方三段式 - -``` -① 明文 pwd - ↓ 官方前端 LoginForm.vue:140 encryptByMd5 -② md5_hex(pwd) ← 32 个小写 hex 字符 - ↓ 官方前端 LoginForm.vue:141 encryptByAES (AES-256-ECB-PKCS7, key=md5_hex(security-key) 的 32 字节) -③ 密文 hex ← 走网络的是这一段 - ↓ 官方服务端 PasswordTokenGranter.java:180 → DesUtil → Hutool AES -④ md5_hex(pwd) 复原(即②) - ↓ 官方服务端 PasswordTokenGranter.java:186 比对 -⑤ md5( ④ + secretkey.toLowerCase() ) ← 库里存的 -``` - -官方建号时(`UserServiceImpl.java:547-549`): - -```java -entity.setSecretkey(RandomUtil.uuId()); -entity.setPassword(Md5Util.getStringMd5(entity.getPassword().toLowerCase() + entity.getSecretkey().toLowerCase())); -``` - -其中 `entity.getPassword()` 在此处**已经是 `md5_hex(明文)`**(由上一层 service 传入)⇒ 库里存 `md5(md5_hex(明文) + secretkey)`。 - -### 6.2 本仓现状 - -库里存 **`md5_hex(明文)`** = 上面的 **②**(= 官方公式的**被加项**,不是结果)。 - -### 6.3 换算公式(**不需要明文**) - -本仓一行 `f_password` ⇒ 官方一行 `f_password`: - -```sql --- 对每一行: --- new_secretkey := 随机 UUID(官方用 RandomUtil.uuId()) --- new_password := md5( lower(old_password) + lower(new_secretkey) ) --- 并写回 f_secretkey = new_secretkey -``` - -Rust 侧等价(示意): - -```rust -let old = "d41d8cd98f00b204e9800998ecf8427e"; // = md5_hex(明文) -let secret = uuid::Uuid::new_v4().to_string(); // 36 位 -let new_pw = md5_hex(format!("{}{}", old.to_lowercase(), secret.to_lowercase())); -``` - -**为什么成立**:官方比对的是 `md5(解密后的② + secretkey)`,而本仓存的**就是②** ⇒ 直接拿旧值当②参与公式即可,**全程不接触明文**。 - -### 6.4 换算的验证方法 - -换算后用**同一个明文**走一次官方登录路径,断言: -`md5( md5_hex(明文) + secretkey ) == 库里新值`。 -(官方登录时 `inputPwd` = 解密后的 `md5_hex(明文)`,见 `PasswordTokenGranter.java:186`。) - ---- - -## 7. §6 官方数据模型规模(用来判断「迁移是搬运还是重写」) - -| 对象 | 官方规模 | 本仓 v1 | -|---|---|---| -| Java 后端 | 2,774 个 `.java` / 282,624 行 | 6,372 行 Rust | -| 官方前端(apps-main) | 765 `.vue` + 224 `.ts` = 172,525 行 | 18 个文件 / 1,374 行 | -| 官方前端(monorepo-framework) | 1,218 `.vue` + 1,036 `.ts` = 284,176 行 | — | -| DDL 表数 | **331** 张(其中 `base_*` **123** 张) | **10** 张(`base_*` 7 + 业务 3) | -| `base_*` 已实现列级缺口 | — | **0** | -| 官方 `src/api` | 97 个 `.ts`;`api/permission/` 14 个 | 5 个 | - -⇒ **结论**:本仓 v1 覆盖的是官方 **`base_*` 权限体系的这 7 张表**(列级零缺口), -**不覆盖**官方 331 张表里的其余 324 张(工作流、在线开发、数据视图、消息、租户、报表…)。 -迁移时**这 7 张表的数据是直接搬运**(`--data-only`),**其余能力要么不用、要么另做**。 - ---- - -## 8. §7 对齐清单(本仓 → 官方,做什么、做到什么程度) - -> ✅ **2026-10-26 更新**:A2 / A8 / A9 / A10 / A11 / A12 的「面 B 要做的事」**已全部落地** -> (`src/backend/src/platform/jnpf.rs`,尺子 `perm-smoke-jnpf.sh` = **18/18**)。 -> 下表的「面 B 要做的事」列保留原样作为**历史记录**,**当前状态看这一段 + `JNPF_COMPAT_SURFACE.md` §7/§8**。 - -| # | 对齐项 | 本仓现状 | 迁官方要做的事 | 面 B 要做的事 | 优先级 | -|---|---|---|---|---|---| -| A1 | 统一信封 | ✅ 已一致 | 无 | 无 | — | -| A2 | 码表 | 4/8 | 补 401/500/601/602 | 至少补 602 | 高 | -| A3 | 登录路径/参数 | ✅ 已一致 | 对齐 cipher key 配置 | 无(沿用) | 低 | -| A4 | 口令加密链 | ✅ 逐字节一致 | 对齐 `security.security-key` | 无 | 低 | -| A5 | 口令存储 | 缺 secretkey | 按 §6.3 换算 | 支持 `f_secretkey` 写入 | 中 | -| A6 | `base_*` 表列 | ✅ 零缺口 | `--data-only` 搬运 | 无 | 低 | -| A7 | 授权写入端点 | ✅ 路径/body 一致 | 补 `f_en_code` 维度 | 同 | 中 | -| A8 | 端点风格 | ssw 约定 | 映射到官方 RESTful | **新增官方路径** | 高 | -| A9 | 列表分页 | 全量数组 | 官方侧改组件或后端补分页 | **返回 `PageListVO`** | 高 | -| A10 | `CurrentUser` | 2 字段 | 官方前端需 `PcUserVO` | **返回 `PcUserVO`** | 高 | -| A11 | 菜单接口 | ssw 路径 | 官方侧调 `ModuleBySystem` | **实现 `ModuleBySystem`** | 高 | -| A12 | 点权限(`f_en_code`) | 无 | 官方前端按钮靠它 | **实现 `permissionList` + 码判权** | 中 | -| A13 | 请求头 | 前端发 `App-Code` + `Jnpf-Origin: pc`(**不发** `Vue-Version`) | 官方后端读 `App-Code`;`Vue-Version` 是面 A/面 B 判别头 | **接受并忽略**(`App-Code`);**`Vue-Version` 判面** | 低 | -| A14 | 登出 | 无端点 | 官方有 `POST /api/oauth/Logout` | 低优先 | 低 | -| A15 | 数据权限方案 | 不做 | 不做 | 不做 | — | - ---- - -## 9. §8 复现命令(自己核一遍) - -> 本机 curl 走系统代理 ⇒ 打 localhost 必须加 `--noproxy '*'`。 - -```bash -J=~/Desktop/workspace/jnpf - -# §2.4 口令加密链 -grep -n "defaultKey\|parse(key)\|ECB\|pkcs7\|useHex" \ - "$J/jnpf-web-monorepo-framework/packages/jnpf/utils/src/helpers/cipher.ts" -grep -n "encryptByMd5\|encryptByAES" \ - "$J/jnpf-web-apps-main/src/views/_core/login/LoginForm.vue" -grep -n "aesOrDecode\|getStringMd5" \ - "$J/jnpf-java-boot/jnpf-oauth/jnpf-oauth-biz/src/main/java/jnpf/granter/PasswordTokenGranter.java" -grep -n "setSecurityKey\|getStringMd5" \ - "$J/jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/properties/SecurityProperties.java" - -# §2.5 口令存储公式 -grep -n "setSecretkey\|setPassword\|getStringMd5" \ - "$J/jnpf-java-boot/jnpf-permission/jnpf-permission-biz/src/main/java/jnpf/permission/service/impl/UserServiceImpl.java" - -# §3.2 分页响应形状 -sed -n '14,21p' "$J/jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/base/vo/PageListVO.java" -sed -n '13,21p' "$J/jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/base/vo/PaginationVO.java" - -# §4 官方端点全表 -grep -n "RequestMapping\|GetMapping\|PostMapping\|PutMapping\|DeleteMapping\|SaCheckPermission" \ - "$J/jnpf-java-boot/jnpf-permission/jnpf-permission-controller/src/main/java/jnpf/permission/controller/UserController.java" | head -40 - -# §3.7 请求头 -grep -n "App-Code\|Jnpf-Origin\|Vue-Version" "$J/jnpf-web-apps-main/src/api/request.ts" -``` - -**本仓侧**: - -```bash -# cipher 自证(免 node 依赖) -./target/release/ssw-jnpf-lite-rust --enc 123456 -# 期望:d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b -``` - ---- - -## 10. 变更记录 - -| 日期 | 变更 | -|---|---| -| 2026-10-26 | 首版。逐行核对官方源码,确立「9 条已对齐 / 8 条差异 / 3 条换算与补齐」。**更正了一处常见误解**:官方 `PageListVO` 含 `pagination` 字段,不是只有 `{list}`。 | diff --git a/MIGRATION.md b/MIGRATION.md deleted file mode 100644 index c0fd28e..0000000 --- a/MIGRATION.md +++ /dev/null @@ -1,312 +0,0 @@ -# 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java) - -> 本技能的价值不是「一个 JNPF 后台」,而是**一个可双向搬运的框架**: -> 官方 JNPF Java ↔ 本技能 Rust 模板 ⇄ react 版 NestJS,三者**数据模型逐字同形**(同一套 `base_*` 表、同一套 cipher、同一套信封)。 -> -> **先读**:[`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md)(官方源码逐行核对,带 `文件:行号`)、 -> [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)(面 B 规格)、 -> [`PERMISSION.md`](PERMISSION.md)(权限与 `base_*` 表的红线)、 -> [`SKILL.md`](SKILL.md) §契约红线。 - -> 📌 **本文的「本仓」= 本技能的 Rust 模板**(`src/backend` + `src/frontend`)。 -> 模板与参照实现仓 `~/Desktop/workspace/ssw-jnpf-lite-rust/` 的 `src/` **逐字节一致**(只差 `data/` 与 `dist/`), -> 所以文中提到的文件/行号在两处都成立。 - ---- - -## 0. 迁移地图 - -| 起点 | 终点 | 性质 | 依据 | -|---|---|---|---| -| **本仓 Rust** | 官方 JNPF Java | **近机械翻译**(后端)+ 数据 ETL(`base_*`) | 本文 §2 / §6 / §7 | -| **本仓 Rust** | react 版 NestJS | **换实现,不换契约** ⇒ 前端零改 | 本文 §5 | -| **官方 JNPF Java** | 本仓 Rust | **走「面 B」**(本仓已实现官方形状的那一面) | 本文 §4 | -| **react 版 NestJS** | 官方 JNPF Java | 见 react 技能 `MIGRATION.md`(同一套约定) | — | - -🔴 **一句话**:数据模型(`base_*` 表名/列名)与**密文算法**是三方共用的**契约**; -端点路径、响应形状、权限判定**不是**——那三层各框架自有风格,靠「双面后端」在同一个进程里并存。 - ---- - -## 1. 为什么"搬得快"——被刻意锁死的五件事 - -| # | 锁死的东西 | 值 | 不这么做会怎样 | -|---|---|---|---| -| 1 | `base_*` 表名/列名 | 官方 DDL **逐字**(含两个故意不修正的陷阱) | 迁官方时**导不进数据** ⇒ 重写 | -| 2 | 口令 cipher | `md5(明文)` → `AES-256-ECB-PKCS7`(key = `md5("EY8WePvjM5GGwQzn")` 的 **32 个 ASCII 字节**)→ hex | 前后端对不上 ⇒ 登录全挂 | -| 3 | 响应信封 | `{code,msg,data}`,业务失败也 **HTTP 200** | 前端拦截器全改 | -| 4 | 主键 | 36 位 UUID v4,列 `varchar(50)` | 数据类型/长度对不上 ⇒ 导不进 | -| 5 | JSON 键名 | 列名去 `f_` 前缀后 camelCase | 前端全改 | - -**注意**:这五条**不包含**「端点路径」和「列表响应形状」——那两件官方与本仓**不同**, -由「面 A / 面 B」两套并存来解决(见 `JNPF_COMPAT_SURFACE.md` §2)。 - ---- - -## 2. 后端:本仓 Rust → 官方 JNPF Java - -### 2.1 逐件翻译表 - -| 本仓(Rust / axum 0.8) | 官方 JNPF Java | 说明 | -|---|---|---| -| `crates/sspf-admin/src/main.rs`(装配 + `--enc`) | `ssw-admin`(`@SpringBootApplication`) | 启动入口 | -| `routes.rs`(`Router` 32 条路径 = 面 A 27 + 面 B 5) | `ssw-{appCode}` 的 `@RestController` | **路径按官方风格改**(见 §2.3) | -| `modules/.rs` 里的 `EntitySpec` / `ColumnSpec` | Java 实体 `extends SuperBaseEntity` + `@TableField("f_title")` | **一个 spec ≈ 一个实体类**:列清单逐字对应 | -| `crud.rs`(spec 驱动的 CRUD 引擎) | `XxxService extends SuperServiceImpl` + `XxxMapper extends SuperMapper` | 官方是 **MyBatis-Plus Join**,不是 JPA | -| `sys.rs`(5 组 `base_*` 显式 handler,1290 行) | `UserController` / `RoleController` / `OrganizeController` / `ModuleController` / `AuthorizeController` | 本仓 5 个 handler → 官方 5 个 controller(**一对一**) | -| `permission.rs`(四源合并 + 管理员短路) | 官方 `@SaCheckPermission("permission.user")` + `SswPermissionGuard` | **判据从「菜单路径」换成「权限编码」**(`base_module.f_en_code`)⇒ 见 §2.4 | -| `auth.rs`(登录 + 守卫) | jnpf-oauth(Sa-Token)+ `PasswordTokenGranter` | 官方多一层 `secretkey`(§7) | -| `cipher.rs`(`md5` + AES-256-ECB) | `DesUtil.aesOrDecode` + `SecurityProperties.securityKey` | **算法逐字节等价** ⇒ 不重写,只对齐两个配置值 | -| `envelope.rs`(`ActionResult{code,msg,data}`) | `jnpf.base.ActionResult` | 形状一致 ⇒ 前端零改 | - -> 🔴 **本仓代码分两层**(迁官方时一一对应): -> `src/backend/src/platform/*`(= 官方 `jnpf-common` + `jnpf-system`)↔ `src/backend/src/modules/*`(= 官方 `jnpf-admin`)。 -| `db/schema.sql`(12 张表) | 官方 DDL | `base_*` 8 张**逐字**(含 `base_system`,官方 `JNPF-PostgreSQL.sql:4243`);业务表 4 张在官方没有 ⇒ 见 §6.2 | -| `db.rs`(pglite 进程内 PG) | 真实 PostgreSQL(`application.yml` 的 `master.url`) | 方言一致 ⇒ SQL 基本不用改 | -| `ids.rs`(UUID v4) | `IdUtil.fastUUID()` | 都是 36 位 | -| `session.rs`(内存 token 表) | Sa-Token(Redis) | 官方多两个码 `601/602`(见 §2.5) | - -### 2.2 迁 JNPF 必备 import 速查 - -| 用途 | import | -|---|---| -| 实体基类 | `jnpf.base.entity.SuperBaseEntity` / `SuperEntity` / `SuperExtendEntity` | -| Mapper | `jnpf.base.mapper.SuperMapper` | -| Service | `jnpf.base.service.SuperService` + `jnpf.base.service.SuperServiceImpl` | -| 返回信封 | `jnpf.base.ActionResult.{success/fail/page}` | -| 分页 | `jnpf.base.Pagination` + `jnpf.base.vo.PaginationVO` + `jnpf.base.vo.PageListVO` | -| 工具 | `jnpf.util.{RandomUtil, UserProvider, JsonUtil}` | -| 异常处理 | `jnpf.exception.ResultExceptionHand`(`@RestControllerAdvice`,裸异常 ⇒ `code:400`) | -| 鉴权(点权限) | Sa-Token `@SaCheckPermission("permission.user")` | -| 鉴权(菜单) | `SswPermissionGuard.requireMenu(XxxController.class)` | - -> `SuperBaseEntity` **只有 `f_id` 一个字段**(唯一强制)。 -> `f_tenant_id / f_last_modify_* / f_delete_time / f_delete_user_id` 属 `SuperEntity` 的**可选增强层**,**不必补**。 - -### 2.3 端点路径:这是**唯一**需要改设计的地方 - -本仓面 A 用 ssw 约定 `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`; -官方是 **RESTful**:`/api/permission/Users`、`/api/permission/Role`(官方自己也不统一,单数)、 -`/api/system/Menu`、`/api/permission/Organize`、`/api/permission/Authority`、动作 `/{id}/Actions/{action}`。 - -| 本仓面 A | 官方 | -|---|---| -| `GET/POST/DELETE /api/ssw/sys/User/{List,Save,Delete?id=}` | `GET/POST /api/permission/Users` · `GET/PUT/DELETE /api/permission/Users/{id}` | -| `GET/POST/DELETE /api/ssw/sys/Role/{…}` | `/api/permission/Role`(单数)· `/{id}` | -| `GET/POST/DELETE /api/ssw/sys/Organize/{…}` | `/api/permission/Organize` · `/AsyncList/{id}` | -| `GET/POST/DELETE /api/ssw/sys/Module/{…}` | `/api/system/Menu` · `/{id}` · `/ModuleBySystem` | -| `PUT /api/permission/Authority/Data/{objectId}` | **同路径** ✅(body 官方是超集,本仓已兼容) | -| `GET /api/ssw/sys/Role/Modules?roleId=` | `POST /api/permission/Authority/Data/{objectId}/Values` | - -🔴 **不要把面 A 路径改成官方路径** —— 面 A 是 react 技能的前端在用的,改了就破契约。 -**要官方形状,走面 B**(`JNPF_COMPAT_SURFACE.md` §3),两套并存于同一进程。 - -### 2.4 权限判据:菜单路径 → 权限编码 - -| | 本仓 | 官方 | -|---|---|---| -| 判据 | 菜单 `f_url_address`(如 `system/User`) | `base_module.f_en_code`(如 `permission.user`) | -| 来源 | `base_module` 表 | 同一张表,**另一个列** | -| 声明方式 | 路由守卫按 key 查 | `@SaCheckPermission("permission.user")` | - -🔴 **本仓的种子菜单目前没有 `f_en_code`**(`seed.rs` 的 `BuiltinMenu` 结构体里没这个字段, -`base_module` 的 INSERT 是 12 个参数、不含它)⇒ **迁官方前必须补** `f_en_code`, -否则官方侧权限判据全是空(官方 `PermissionConst.java:8-77` 定义了对象码与 `btn_*` 码两套)。 - -### 2.5 码表补齐 - -| 码 | 含义 | 本仓 | 官方 | 动作 | -|---|---|---|---|---| -| 200 | 成功 | ✅ | ✅ | — | -| 400 | 业务失败 | ✅ | ✅ | — | -| 401 | 校验失败 | ❌ | ✅ | 迁官方时用上 | -| 403 | 无权限 | ✅ | ✅ | — | -| 500 | 异常 | ❌ | ✅ | 迁官方时用上 | -| 600 | 会话过期 | ✅ | ✅ | — | -| 601 | 会话离线 | ❌ | ✅ | — | -| **602** | 会话错误 | ❌ | ✅ | 🔴 **官方前端 `request.ts:78-80` 只在 601/602 清 token** ⇒ 只返 600 会让页面挂住 | - -⇒ 面 B 落地时,**面 B 的路由无 token 时返 602**,面 A 保持 600。 - ---- - -## 3. 前端:三条路 - -| 方案 | 做法 | 代价 | -|---|---|---| -| **A. 保留 React 前端** | 后端换 Java 后**契约不变 ⇒ 零改** | 官方那套 Vue 组件库用不上 | -| **B. 换 jweb (Vue)** | 官方前端工程 `apps/jnpf-web-apps-main/`,按 `api//.ts` 封装 | 页面要重写(但 UX 可搬) | -| **C. 双前端并存** | React 走面 A、jweb 走面 B,**同一后端进程** | 需要两套构建;本仓「面 A/面 B」设计就是为它准备的 | - -🔴 **接官方 jweb 时前端必须补三个头**(`App-Code` / `Jnpf-Origin: pc` / `Vue-Version: 3`, -官方 `jnpf-web-apps-main/src/api/request.ts:109-112`)。 -其中 **`Vue-Version: 3` 才是面 A/面 B 的判别依据**——本仓 React 前端**也发** `App-Code` 与 -`Jnpf-Origin: pc`(`src/frontend/src/api/request.ts:35-36`,与官方同款),**只有 `Vue-Version` 不发** ⇒ 零歧义。 - -**菜单挂载**:jweb 由菜单自动生成路由(`base_module.f_url_address` ↔ Route path 一一对应), -不要再手写 `router.beforeEach`。 - ---- - -## 4. 官方 JNPF → 本仓 Rust(反向) - -这条路**本仓已经铺好轨**,官方前端可以**直接跑在本仓上**: - -1. 官方前端照常发 `Vue-Version: 3` ⇒ 本仓判为**面 B** ⇒ 返回官方形状。 -2. 本仓**面 B 已实现的部分**(`JNPF_COMPAT_SURFACE.md` §7 的 S1–S6): - 官方登录(零改)、`CurrentUser` 的 `PcUserVO`、分页 `PageListVO`、 - `602` 码、菜单 `ModuleBySystem` + `f_en_code` 判据、授权 `Values` 读取。 -3. **本仓不实现**(如实记录在 `JNPF_COMPAT_SURFACE.md` §8):按钮级权限(`btn_*`)、 - 数据权限方案、导入导出、完整权限树模型。 - -⇒ 官方前端的**登录 + 菜单 + 用户/角色/组织/菜单列表**能在本仓上跑; -**授权弹窗的树**、**数据权限页**、**导入导出**跑不了(这些页面会报错,但不影响其它页)。 - -**验收**:`bash scripts/perm-smoke-jnpf.sh` ⇒ 打印 **「面 B 覆盖 N/18」**,N 就是官方前端能跑通的面。 - ---- - -## 5. react 版 NestJS → 本仓 Rust - -**同一套契约 ⇒ 前端零改**。两边可以**开同一个库**(业务表名故意对齐:`demo_item` / `shop_product` / `book_shop_book`)。 - -| 能力 | react 版(NestJS) | 本仓(Rust) | -|---|---|---| -| 端口 | 后端 `:30000` | 后端 `:30010`(🔴 `tdc-rs` 占了 `:30000`) | -| 数据库 | 嵌入式 PGlite(WASM) | `pglite-rs`(**进程内原生 PG**) | -| 冒烟尺子 | `scripts/perm-smoke.sh`(22 条基线) | `scripts/perm-smoke.sh`(**32 条**)+ `perm-smoke-jnpf.sh`(18 条) | - -⚠️ 两版**不要**把数据目录指到同一处(pglite 单实例独占目录 ⇒ 第二个进程起不来)。 -⚠️ 两版的 `base_*` 种子**可以**并存于同一库(表名/列名逐字同形), -但 **`f_account` 官方无 UNIQUE** ⇒ 建了同名账号会**建两份**。 - ---- - -## 6. 数据 ETL(诚实版) - -### 6.1 `base_*` 7 张:表结构**逐字同形** ⇒ 只导数据 - -官方 `base_*` 表由 **JNPF 平台自动创建** ⇒ **不要用本仓 DDL 覆盖官方表结构**,只导数据。 - -🔴 **本仓的 pglite 是「进程内单用户 Postgres」,没有 TCP 端口** -⇒ `pg_dump` / `psql` **连不上** ⇒ 常规 `--data-only` 那条路**在本仓这侧走不通**。 -可行做法有两条: - -**(a) 给本仓加一个 `--dump` 子命令(推荐)** - -在 `crates/sspf-admin/src/main.rs` 的 `parse_args`(现只有 `--enc`)旁加一个 `Cmd::Dump`, -用 `db.rs` 里现成的执行入口跑: - -```sql -COPY (SELECT * FROM base_user) TO STDOUT WITH CSV HEADER; -COPY (SELECT * FROM base_module) TO STDOUT WITH CSV HEADER; --- …其余 5 张 -``` - -把 CSV 交给官方侧 `COPY base_user FROM STDIN WITH CSV HEADER` 导入。 -(`db.rs` 已有「持 `db_lock` 跑 SQL」的能力,dump 只是同一套机制多跑几条 SQL。) - -**(b) 直接在官方库侧手写 `INSERT`** - -本仓种子数据量极小(内置 2 角色 + 8 菜单 + 1 管理员 + 若干授权)⇒ -用 `PERMISSION.md` §一的字段清单手写 `INSERT` 往往比导数据更快。 -**业务数据**(`demo_item` / `shop_product` / `book_shop_book`)同理。 - -### 6.2 业务表 3 张:官方**没有对应表** ⇒ 要先建实体 - -`demo_item` / `shop_product` / `book_shop_book` 是**本仓/两版垫片自定义**的(表名只为「两版后端能开同一个库」而对齐)。 -迁官方时它们**不是契约** ⇒ 两种做法: - -- **保留表名**:在 JNPF 里建三个实体,表名照填 ⇒ 迁回本仓时零改; -- **改成官方低代码实体名**(推荐,符合官方工程习惯)⇒ 迁回本仓时改 `modules/.rs` 的 `table` 字段即可。 - -### 6.3 官方 DDL 的两个"故意不修正"的陷阱(迁的时候别顺手改) - -| 陷阱 | 事实 | 后果 | -|---|---|---| -| `base_role_relation` | 用户 id 在 **`f_object_id`**(配 `f_object_type='user'`),**没有 `f_user_id`** | 写错列 ⇒ 角色授权永不生效 | -| `base_user_relation` | 组织/岗位关系在**另一张表**,那里**才有 `f_user_id`** | 写错表 ⇒ 组织/岗位授权永不生效 | - -另:`base_module.f_type` 是 **INTEGER**(1 目录 / 2 页面),`f_category` 是 **VARCHAR**。 - ---- - -## 7. 口令换算(迁官方时**必做**,否则全员登不上) - -### 7.1 两个公式 - -| | 公式 | 出处 | -|---|---|---| -| **本仓 / react 版** | 存 `md5(明文)` 的小写 hex | 本仓 `cipher.rs` / `UserServiceImpl` 简化版 | -| **官方** | 存 `md5( lower(md5(明文)) + lower(secretkey) )`,`secretkey` = 每用户随机 UUID | `UserServiceImpl.java:547-549`、`:704-706` | - -官方登录时:`decrypt(密文)` 得 `md5(明文)` ⇒ 取 `lower()` ⇒ 拼 `lower(secretkey)` ⇒ `md5` ⇒ 与库值比。 - -### 7.2 🔴 关键洞察:**不需要明文** - -本仓库里的值 = `md5(明文)` 的小写 hex = 官方公式的**第一个加数**(`lower(md5(明文))`)。 - -⇒ 换算公式(**一次 SQL 就能做完**): - -```sql --- 对每一行:先给一个随机 secretkey,再把口令重算成官方格式 -UPDATE base_user -SET f_secretkey = <新随机 UUID>, - f_password = md5(lower(f_password) || lower(<新随机 UUID>)); -``` - -- `f_password` 列**已存在**(本仓 `db/schema.sql:142`;官方 DDL `:4503`)⇒ DDL 不用改。 -- 换算**幂等性要注意**:公式只适用于「`f_password` 还是裸 `md5(明文)`」的库。 - **重复执行会把公式套在公式上 ⇒ 不可逆地错**。⇒ 换算前**先备份**(`backup_create` / `pg_dump`)。 - -### 7.3 换算自证 - -```bash -# 1. 换算前:取一行,记住 account 与 f_password -# 2. 换算后:用**同一个明文**走一遍官方登录链路 -# 本仓的等价物:md5(明文) → AES 密文 → POST /api/oauth/Login -# 3. 官方侧登录成功 ⇒ 换算正确 -``` - -⚠️ 本仓的登录**只比 `md5(明文)`** ⇒ 换算成官方格式后**本仓就登不上了**(预期)。 -⇒ 换算是**单向操作**:迁到官方前做一次,且**先备份**。 - ---- - -## 8. 验证 - -**迁移前**(本仓基线必须全绿): - -```bash -bash scripts/perm-smoke.sh # 面 A:32 条 —— 「没把原契约改坏」 -bash scripts/perm-smoke-jnpf.sh # 面 B:18 条 —— 「官方形状达标」(打印「面 B 覆盖 N/18」) -bash scripts/check-module.sh # 业务模块 9 接触点静态自检 -``` - -**迁移后**(官方库上): - -```bash -# 面 A 尺子打官方后端:路径不同 ⇒ 只能打面 B 尺子 -B=http://<官方后端> bash scripts/perm-smoke-jnpf.sh -``` - -🔴 **两把契约尺子必须同时绿**(`perm-smoke.sh` / `perm-smoke-jnpf.sh`;另有四道静态闸门 ⇒ 合计六道闸门): -面 A 绿证明「没把原契约改坏」,面 B 绿证明「官方形状达标」。 - ---- - -## 9. 明确不做 - -- **低代码引擎**(表单/流程/代码生成)—— 官方能力,本仓不碰。 -- **多租户**(`jnpf-tenant*`)—— 单租户固定 `f_tenant_id='0'`。 -- **按钮/列/表单/数据范围级授权** —— 官方 DDL 里都有,v1 只做 `item_type='module'`(菜单)。 -- **Redis / Sa-Token** —— 内存 token 表即可。 -- **分页(面 A)** —— 面 A 的 `List` 就是**全量**(前端不分页);分页是面 B 的事。 - ---- - -## 10. 变更记录 - -| 日期 | 变更 | -|---|---| -| 2026-10-26 | 首版:三方双向迁移地图、Rust→Java 逐件翻译、import 速查、端点路径差异表、权限判据差异、码表补齐表、三条前端路线、数据 ETL(pglite 无 TCP 的诚实版)、口令换算公式与幂等性警告、两把尺子的验证清单 | diff --git a/PERMISSION.md b/PERMISSION.md deleted file mode 100644 index c7c47e5..0000000 --- a/PERMISSION.md +++ /dev/null @@ -1,182 +0,0 @@ -# 权限模版(MVP 期就按 JNPF 形态钉死) - -> 权限是迁移最硬的一块。本仓从第一天起就把 `base_*` 的**表名/列名/语义**照官方 DDL 抄死, -> 使稳定期换 Java 后端时**不用动表**(只导数据)。端点路径与列表形状**故意没锁**(那是面 A/面 B 的事)。 - -## 一、数据模型(7 张表,字段名与官方逐字一致) - -| 表 | 用途 | 关键列 | -|---|---|---| -| `base_user` | 用户 | `f_id` / `f_account` / `f_password` / `f_real_name` / `f_is_administrator` / `f_delete_mark` / `f_secretkey` | -| `base_role` | 角色 | `f_id` / `f_en_code`(应用层唯一) / `f_full_name` / `f_delete_mark` | -| `base_module` | 菜单 | `f_id` / `f_full_name` / `f_url_address`(= 前端 Route path 去前导斜杠) / `f_parent_id` / `f_type`(**INTEGER**:1 目录 2 页面) / `f_en_code`(官方点权限用,本仓种子为空) | -| `base_authorize` | 授权 | `f_object_type` / `f_object_id` / `f_item_type` / `f_item_id` | -| `base_role_relation` | 用户↔角色 | `f_role_id` / **`f_object_id`(用户 id!)** / `f_object_type='user'` | -| `base_user_relation` | 用户↔组织/岗位 | **`f_user_id`** / `f_object_id` / `f_object_type`(`'organize'` / `'position'`) | -| `base_organize` | 机构 | `f_parent_id` 树 | - -所有表复合主键 `(f_id, f_tenant_id)`,单租户固定 `f_tenant_id='0'`。 - -### ⚠️ 两个高频字段名陷阱(官方原样保留,别"优化") - -| 陷阱 | 事实 | 写错的后果 | -|---|---|---| -| `base_role_relation` | 用户 id 存在 **`f_object_id`**(配 `f_object_type='user'`),**没有 `f_user_id`** | 角色授权**永远不生效**(且**不报错**) | -| `base_user_relation` | 组织/岗位关系在**另一张表**,那里**才有 `f_user_id`** | 组织/岗位授权**永远不生效**(且**不报错**) | - -🔴 这两个坑**都是静默失败** ⇒ 必须有测试钉住(本仓 `permission_it.rs` 钉了)。 - -### 权威来源(不要凭记忆写列名) - -- 官方 DDL:`~/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) - (同目录另有 9 个 init 文件,**只读**) -- 本仓落地:`src/backend/db/schema.sql` -- 逐行核对报告:[`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md) §2.6 - -## 二、四源合并(已实现,`src/backend/src/platform/permission.rs`) - -**权限 = 用户直授 + 角色 + 组织 + 岗位**,四条路都查: - -| 源 | 路径 | -|---|---| -| 1. **直授** | `base_authorize`(`f_object_type='user'`)⇒ 菜单 id | -| 2. **角色** | `base_role_relation`(`f_object_type='user'`)⇒ `f_role_id` ⇒ `base_authorize`(`f_object_type='role'`) | -| 3. **组织** | `base_user_relation`(`f_object_type='organize'`)⇒ `f_object_id` ⇒ `base_authorize`(`f_object_type='organize'`) | -| 4. **岗位** | `base_user_relation`(`f_object_type='position'`)⇒ `f_object_id` ⇒ `base_authorize`(`f_object_type='position'`) | - -🔴 **只查角色会漏授权**——组织/岗位授权最容易被忽略。 -🔴 **管理员短路在查 SQL 之前**(`f_is_administrator=1` ⇒ 直接放行,不查任何授权表)。 -🔴 **只有 `base_authorize` 过滤 `f_delete_mark = 0`**;`base_role_relation` / `base_user_relation` -**不过滤**(对齐官方 SQL 的过滤习惯)。 - -### 判权:菜单**路径**,不是点权限 - -本仓的守卫 = **`spec.module_key` == 菜单 `f_url_address`**: - -``` -spec.module_key == menu.url_address == 前端 App.tsx 的 Route path(去前导斜杠) -``` - -🔴 菜单(`url_address` / `f_en_code` / `parent_id` / `sort_code`)由**业务模块自己声明** -(`modules/.rs` 的 `*_MENU: MenuSpec`),再经 `modules::ALL_MENUS` 交给装配根 -`bootstrap::ensure_base` 回灌 ⇒ 平台层**不认识任何业务菜单**(红线 12)。 - -🔴 **官方是点权限**(`@SaCheckPermission("permission.user")`,取自 `base_module.f_en_code`)—— -这是本仓与官方最大的鉴权模型差异(审计报告 D6)。 -⇒ 迁官方前**必须给菜单补 `f_en_code`**(`MIGRATION.md` §2.4)。 -⇒ 面 B 落地时要**两套判据并存**(路径判权给面 A,`f_en_code` 判权给面 B)。 - -### 未映射 ⇒ **放行**(不是拒绝) - -菜单**未映射**到 `base_module` ⇒ **放行**(对齐官方 `SswPermissionGuard` 的 warn 路径)。 -🔴 **这条最容易写反,而且静默**(不报错)⇒ 有测试钉住。 - -## 三、端点契约 - -| 方法 | 路径 | 守卫 | 返回 | -|---|---|---|---| -| POST | `/api/oauth/Login` | 无 | `{token, expiresIn:7200, tokenTypeName:'bearer'}` | -| GET | `/api/oauth/CurrentUser` | 登录 | `{userInfo:{userId,userAccount,userName,isAdministrator}, menuList}` | -| GET/POST/DELETE | `/api/ssw/sys/User/{List,Save,Delete?id=}` | 登录 + 菜单 `system/User` | 列表**去掉 `password`**,附 `roleIds`/`roleNames` | -| GET/POST/DELETE | `/api/ssw/sys/Role/{List,Save,Delete?id=}` | 登录 + 菜单 `system/Role` | | -| GET | `/api/ssw/sys/Role/Modules?roleId=` | 登录 | `string[]`(菜单 id) | -| GET/POST/DELETE | `/api/ssw/sys/Organize/{List,Save,Delete?id=}` | 登录 + 菜单 `system/Organize` | 有子机构时拒删(`code=400`) | -| GET/POST/DELETE | `/api/ssw/sys/Module/{List,Save,Delete?id=}` | 登录 + 菜单 `system/Module` | | -| PUT | `/api/permission/Authority/Data/{objectId}` | 登录 | body `{objectType:'role', module:['m1','m2']}` | -| GET | `/api/permission/Authority/RoleModules?roleId=` | 登录 | `string[]` | -| GET/POST/DELETE | `/api/ssw/{app}/{Entity}/{List,Save,Delete?id=}` | 登录(+ 菜单,按 `module_key`) | | - -### 授权写接口的三个坑 - -1. **`objectType` 必须小写 `'role'`** —— 官方对大小写错误是**静默忽略**(返 200 但一行不写)。 -2. **`module` 传一维数组** `['m1','m2',…]`(半选节点合进同一数组,对齐官方 `MenuAuth.vue`)。 -3. 官方 body 是本仓的**超集**(多 `button`/`column`/`resource`/`form`/`systemIds`)⇒ 本仓**照单全收**, - 只消费 `objectType` + `module` ⇒ 官方前端直接调本仓即可(**零改动**)。 - -## 四、`ActionResult` 码表 - -本仓已用官方 `ActionResultCode` 的前 4 个: - -| code | 含义 | 何时 | -|---|---|---| -| `200` | 成功 | | -| `400` | 业务失败 | 账号重复、参数错、有子机构拒删…… | -| `403` | 无菜单权限 | 已登录但菜单未授权 | -| `600` | 未登录(会话过期) | 无 token / token 无效 | - -🔴 **业务失败恒 HTTP 200**——成败只看 body 的 `code`。**禁止** 401/403 裸 body。 -🔴 **未知路由保留 HTTP 404**(body 仍是信封形状)——不要用全局 404 兜底把它变成 200。 - -**官方还有、本仓缺的**(面 B 要补,见 `JNPF_COMPAT_SURFACE.md` §4): - -| code | 官方常量 | 说明 | -|---|---|---| -| `401` | `VALIDATEERROR` | 官方 `MsgCode.PS012` 之类的校验失败 | -| `500` | `EXCEPTION` | 未捕获异常 | -| `601` | `SESSIONOFFLINE` | 被踢下线 | -| `602` | `SESSIONERROR` | 会话异常 | - -🔴 **官方前端 `request.ts:78-80` 只在 `601`/`602` 时清 token** ⇒ 只返 `600` 会让页面**卡住不跳登录**。 -⇒ 面 B **无 token 必须返 `602`**(不是 600)。 - -## 五、口令 - -- **加密链**(前端 → 后端):`md5(明文)` → `AES-256-ECB-PKCS7`(key = `md5("EY8WePvjM5GGwQzn")` 的 **32 个 ASCII 字节**)→ hex。 -- **检验向量**:`encryptPassword('123456')` == - `d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`。 - 一行自证:`./target/release/ssw-jnpf-lite-rust --enc 123456`。 -- **库内存** `md5(明文)` 的小写 hex;登录时 `decrypt(密文)` 得到 `md5(明文)` ⇒ **大小写不敏感**比较。 -- 🔴 **密文只在请求体里出现,永不回显**;用户列表**手工挑字段**去掉 `password`。 -- 🔴 官方多一步 `secretkey`(`md5(lower(md5(明文)) + lower(secretkey))`)⇒ 迁官方要**换算**, - 但**不需要明文**(`MIGRATION.md` §7)。 - -## 六、迁移映射(稳定期) - -| 本仓 | 官方 | -|---|---| -| `permission.rs` 的四源合并 | `@SaCheckPermission` + `SswPermissionGuard.requireMenu`(判据从**路径**换成 **`f_en_code`**) | -| `auth.rs` 的内存 token | jnpf-oauth / Sa-Token(内存模式同代) | -| `cipher.rs` | `DesUtil` + `SecurityProperties.setSecurityKey`(**逐字节一致**) | -| `envelope.rs` | `ActionResult` + `ResultExceptionHand` | -| `sys.rs` 的 5 组显式 handler | 5 个官方 Controller(`/api/permission/Users` / `Role` / `Organize` / `Authority` / `/api/system/Menu`) | -| `db/schema.sql` 的 7 张 `base_*` | 官方 DDL(**逐字同形**)⇒ **只导数据,不导结构** | -| `seed.rs` 的两段式种子 | 官方建表后灌数据(补 `f_en_code` + `f_secretkey`) | - -**数据 ETL**: - -```bash -# 🔴 pglite 是**进程内单用户 PG、无 TCP 监听** ⇒ psql / pg_dump **连不上** -# ⇒ 走应用内导出(新增一个 --dump 子命令跑 COPY ... TO STDOUT),或手写 INSERT -``` - -详见 [`MIGRATION.md`](MIGRATION.md) §6。 - -## 七、验证(可重复执行) - -```bash -bash scripts/perm-smoke.sh # 面 A 32 条(含权限闭环) -bash scripts/perm-smoke-jnpf.sh # 面 B 18 条(官方形状) -cargo test # 220 条单测(含两个陷阱的回归) -``` - -**面 A 尺子覆盖的权限闭环**: -未登录 600 · 加密登录 · 菜单树 · 建用户 · **重复账号返 400 而非 500** · -写授权(一维/二维兼容)· 非管理员菜单收窄 · 非管理员访问系统管理返 403 · -已授权业务返 200 · 未知路由 404 · 三个业务模块全链路。 - -🔴 **判读原则**:**返回了数据不能证明权限生效** -(管理员短路 / 菜单没映射 / 缓存没清 / 异常降级放行,四条路径全是"放行")。 -**「菜单收窄 + 403 拦截」才是有说服力的信号。** - -## 八、MVP 未做的部分(迁移时补,不是遗漏) - -- **按钮 / 列 / 表单 / 数据范围级授权**(`base_module_button` / `_column` / `_form` / `_data`)—— - 官方 DDL 里都有,v1 只做 `item_type='module'`(菜单)一类。 -- **多租户**(`jnpf-tenant*`)——单租户固定 `f_tenant_id='0'`。 -- **Redis / Sa-Token**——内存 token 表即可。 -- **分页**——契约里的 `List` 就是全量;要分页是 JNPF 稳定期的 `SuperServiceImpl.page`。 -- **低代码引擎**(表单 / 流程 / 代码生成)——官方能力,不碰。 -- **点权限(`f_en_code`)**——本仓按菜单路径判权;面 B 才引入 `f_en_code` 判据。 -- **`base_user.secretkey` 的真实算法**——本仓留位待迁移补(迁时一次性换算)。 diff --git a/PLAN.md b/PLAN.md index 0310a39..4c64ca4 100644 --- a/PLAN.md +++ b/PLAN.md @@ -985,10 +985,10 @@ tools/diff-harness/ |---|---|---| | `CLAUDE.md` | 当前阶段红线 + 范围 | 本文件定长期架构;CLAUDE.md 的 §2 范围随阶段滚动 | | `HANDOFF.md` | 现场交接 | 不变 | -| `MIGRATION.md` | Rust ⇄ 基线平台逐件映射 | 本文件 §5 是其上位设计 | -| `JNPF_COMPAT_SURFACE.md` | 面 B 规格 | 契约真源,不改 | -| `PERMISSION.md` | 权限与 `base_*` 红线 | 不改 | -| `HOWTO_MODULE.md` | 加模块操作手册 | P3 后改为「加业务包」手册 | +| `MIGRATION.md`(技能仓) | Rust ⇄ 基线平台逐件映射 | 本文件 §5 是其上位设计 | +| `JNPF_COMPAT_SURFACE.md`(技能仓) | 面 B 规格 | 契约真源,不改 | +| `PERMISSION.md`(技能仓) | 权限与 `base_*` 红线 | 不改 | +| `HOWTO_MODULE.md`(技能仓) | 加模块操作手册 | P3 后改为「加业务包」手册 | | 本文件 | **架构基线 + 路线图** | 阶段推进只改 §9 的勾 | --- diff --git a/README.md b/README.md index 4172bf0..8eccedd 100644 --- a/README.md +++ b/README.md @@ -1,232 +1,124 @@ -# ssw-jnpf-lite-rust · Rust 全栈 MVP +# sspf —— SSPF 标准平台包 -**自包含技能**:模板、契约实现、权限模版、冒烟脚本全部在技能目录内,**不依赖任何其它技能或外部服务**, -除 Node 外无需安装任何东西(数据库是**进程内原生 PostgreSQL**)。 +> **本仓是平台本体(ssw-platform),不是业务项目,也不是技能。** +> 业务仓(如 `tdc-rs`)只依赖本仓发布的 `sspf` crate;JNPF MVP 示例、React 演示前端的 +> **权威副本**在技能仓 `ssw-jnpf-lite-rust`(`~/.agents/skills/ssw-jnpf-lite-rust`)。 -来自 `ssw-jnpf-lite-react`(NestJS + React)的 **Rust 全栈 counterpart**——两者是**并列可选**的独立技能, -不是依赖关系:要 MVP 期就用 Node 栈选 `ssw-jnpf-lite-react`,要 MVP 期用 Rust 栈选本技能。 +## 这是什么 -> 📌 **本仓 = 项目(ssw-platform),不是技能本体**(2026-11-04 澄清)。 -> 脚手架来自技能 `ssw-jnpf-lite-rust`(`~/.agents/skills/ssw-jnpf-lite-rust`), -> 但本仓已按项目需要演进,**与技能形状不再一致**,改本仓**不会**改到技能: -> - 内核 `src/backend`(lib `ssw_platform`)**只有 lib 目标**,不再自带二进制; -> - **默认装配 = `crates/sspf-admin`**(bin `sspf-admin`)—— 进程级的事都在这儿,**自己就能跑**; -> - **集成测试宿主 = `crates/tests`**(package `sspf-tests`)—— 测的是装配好的平台,不再挂在内核包里。 -> 三条边界由 `scripts/check-arch.sh` 的 **AR16** 钉住(踩线即红,不会被悄悄改回去)。 +`sspf` 是 JNPF 契约的 Rust 实现,按 **git tag** 发布给业务仓。一个业务仓、一个进程、 +一个 PGlite 实例、一个端口,同时提供: -## 设计原则:MVP = JNPF 的 Rust 版垫片 - -**MVP 后端不是随便写的 Rust 服务,而是 JNPF 契约的 Rust 版垫片**——契约从第一天锁死, -使稳定期换 Java 后端是「机械翻译」而非重写。 - -**锁死的五件事**(详见 [`MIGRATION.md`](MIGRATION.md) §1): - -| # | 锁死的东西 | 为什么 | +| 面 | 内容 | 由谁提供 | |---|---|---| -| 1 | `base_*` 表名 / 列名(逐字对齐官方 DDL,含两个官方陷阱) | 迁移期靠 `--data-only` 导数据,列名差一个字符就导不进去 | -| 2 | 口令密文算法(`md5 → AES-256-ECB-PKCS7 → hex`) | 前端 `cipher.ts` / 后端 `cipher.rs` / 官方 `DesUtil` 逐字节一致 | -| 3 | 统一信封 `ActionResult{code,msg,data}` + 业务失败恒 HTTP 200 | 换栈后前端零改 | -| 4 | 主键 = 36 位 UUID v4(`f_id VARCHAR(50)`) | 与官方 `IdUtil.fastUUID()` 同形 | -| 5 | JSON 键名 = 列名去 `f_` 前缀后 camelCase | 官方 Jackson 自动剥离 `f` | +| 面 A | ssw 约定 `/api/ssw/{app}/{Entity}/{动作}`,声明式 `EntitySpec` 驱动的 CRUD | 平台 | +| 面 B | 官方 JNPF 形状(346 端点 / `base_*` 表 / cipher / 602 码) | 平台 | +| 业务面 | 业务仓自带状态的 132 条端点等 | 业务仓通过 `Finish` 注入 | +| 其它 | 登录 / 权限 / 低代码 / MCP / 静态 SPA 托管 | 平台 | -**故意没锁的两件事**(就是「面 A / 面 B」要解决的): +平台包**默认零业务**:依赖树里没有 `sspf-pack-*`,`/api/health` 是 `tables=177`。 +业务通过 `Platform::packs / ddl / menus / router / static_dir / on_ready` 或 v0.3.0 的 +`assemble() → Finish{ router, fallback, layers } → serve()` 注入。 -- **端点路径**——面 A 走 ssw 约定 `/api/ssw/{app}/{Entity}/{List|Save|Delete}`,面 B 走官方 RESTful 形状。 -- **列表响应形状**——面 A 是裸数组,面 B 是官方 `PageListVO{pagination,list}`。 +## 业务仓怎么接 -⇒ **一个后端进程同时服务两套契约**,靠请求头 `Vue-Version: 3` 判面 -(官方前端必发,本仓前端**唯一不发**的一头 ⇒ 零歧义)。详见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)。 +```toml +[dependencies] +sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.3.0" } +``` -## 选型决策:Rust 版 vs react 版 vs ssw-jnpf-lite(Java) +```rust +// 最简:平台能力全量启动(177 表 / 面 A·面 B / 静态托管) +sspf::Platform::new().static_dir("static").serve().await?; -| | **ssw-jnpf-lite-rust**(本技能) | **ssw-jnpf-lite-react** | **ssw-jnpf-lite**(Java) | -|---|---|---|---| -| MVP 期后端栈 | Rust / axum | Node / NestJS | Java / Spring Boot | -| 部署 | **单二进制**(库链进可执行文件) | Node 进程 + 前端静态产物 | JVM + 前端静态产物 | -| MVP 期迭代速度 | **快**(编译期类型安全,重构有保障) | 快(AI 也熟) | 慢(编译 + 脚手架重) | -| 迁官方 JNPF 的成本 | 低(`MIGRATION.md` 有逐件翻译表) | 低(同上,NestJS 版) | **零**(本来就在 Java 上) | -| 官方前端能跑在上面吗 | ✅ **能**(面 B) | ✅ 能(面 B) | ✅ 原生 | -| 数据模型 | 与官方逐字一致(`base_*`) | 与官方逐字一致 | 与官方逐字一致 | -| 适合谁 | 想要 Rust 性能/单二进制,且要保迁移性 | 团队/AI 更熟 Node | 已经是 Java 团队,不打算换栈 | +// 厚业务仓:两阶段装配(v0.3.0 起) +let boot = sspf::Platform::new().ddl("biz_x", include_str!("../schema/001.sql")).assemble().await?; +let pg = boot.state.db.pg(); // 同一个 Arc +let biz = build_router(BizState::new(pg)).with_state(()); +boot.serve(Finish { router: Some(biz), ..Finish::default() }).await?; +``` -**一句话**:**MVP 期用哪种栈都行,代价是「稳定期迁 JNPF」这件事**。 -本技能把「快」放在 MVP 期(Rust),把「换栈」推迟并**锁死到有界范围**(5 件事 + 六道闸门)。 -若你**本来就要用 Java**,直接用 `ssw-jnpf-lite`(零迁移摩擦)比绕一圈更划算。 +业务仓另需:自带 `rust-toolchain.toml` 锁 **1.95.0**、`[profile.dev] incremental = false`、 +release **不设** `panic = "abort"`(否则 catch-all 的 `panic ⇒ 200 + code=400` 失效)。 ## 目录 ``` -ssw-platform/ ← 仓根 = 项目根(技能在 ~/.agents/skills/ssw-jnpf-lite-rust) -├── crates/sspf-admin/ # 🔴 默认装配(bin `sspf-admin`):cargo run -p sspf-admin -├── crates/tests/ # 🔴 集成测试宿主(package `sspf-tests`):cargo test -p sspf-tests -├── src/backend/ # 内核 lib(`ssw_platform`)+ 业务层 modules/ + 平台 DDL -├── README.md # 本文件:选型 / 运行 / 验收门 / 已知限制 -├── HOWTO_MODULE.md # 加一个业务模块的操作手册(8 个文件 / 10 个接触点) -├── PERMISSION.md # 权限模版:表结构 / 四源合并 / 码表 -├── MIGRATION.md # 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java) -├── JNPF_SOURCE_AUDIT.md # 官方源码逐行核对报告(标 文件:行号) -├── JNPF_COMPAT_SURFACE.md # 面 B 规格书:官方形状端点 + 落地顺序 S1–S6 -├── CLAUDE.md / HANDOFF.md # 项目级 agent 指引 / 交接文档 +ssw-platform/ +├── crates/sspf/ # 🔴 唯一发布物:门面 + Platform builder + 两阶段装配 +├── crates/sspf-*/ # 平台能力层(core / contract / store / plugin / lowcode / mcp / compat …) +├── crates/sspf-admin/ # 🔴 纯平台装配(bin `sspf-admin`):177 表、面 A 无业务端点 +├── crates/tests/ # 集成测试宿主(package `sspf-tests`) +├── src/backend/ # 内核 lib(`ssw_platform`):装配根 / 路由 / 启动原语 / 平台 DDL +├── src/frontend/ # React + Vite 演示前端(可选,随发布包保留) +├── docs/ # 契约真源 / 运维 / 裁决 / DDL / 需求与实施记录 +│ ├── contract.md # 【契约唯一真源】端点 / 返回形状 / 数据模型(附录 A 是尺子期望源) +│ ├── SSPF-PLATFORM-PACKAGE.md # P0 需求 + 实施记录(v0.2.0) +│ └── SSPF-BUSINESS-COMPOSITION.md # P1 需求 + 实施记录(v0.3.0) +├── scripts/ # 静态闸门(check-*)/ 运行时尺子(*-smoke)/ 生成段同步(pack-sync) ├── run.sh # install / build / dev / backend / frontend / stop / logs -├── Cargo.toml # 🔴 cargo workspace 根(**复制脚手架时必须一起带走**) -├── .env.example # PORT / BIND_ADDR / PGLITE_DIR -├── scripts/ -│ ├── perm-smoke.sh # 契约尺子·面 A(32 条) -│ ├── perm-smoke-jnpf.sh # 契约尺子·面 B(18 条)★ 本技能独有 -│ ├── smoke_backend.sh # 两把尺子的「隔离后端」自启动助手(默认自起 ⇒ CI 可跑) -│ ├── check-module.sh # 静态闸门 1:业务模块 10 接触点自检(93 条) -│ ├── check-boundary.sh # 静态闸门 2:分层红线 CP1–CP6 自检(11 条) -│ ├── check-boundary-scan.py # 分层闸门的扫描器(禁用词表由业务层反推 + 自测模式) -│ ├── check-contract.sh # 静态闸门 3:契约端点表 + 官方端点台账 ↔ 代码真实路由 对账(10 条)★ 本技能独有 -│ ├── check-contract-scan.py # 上面那个的扫描器(Rust 源码静态解析 + 9 例反自证) -│ ├── check-citations.sh # 静态闸门 4:文档引文 `路径:行号` 逐条核对(4 条)★ 本技能独有 -│ ├── check-citations-scan.py # 上面那个的扫描器(引文解析 + 3 例反自证) -│ ├── contract_expect.py # 读 docs/contract.md 附录 A(机器可读期望值)—— 尺子的唯一期望源 -│ ├── reap-ipc-leaks.sh # macOS SysV 信号量泄漏回收(PGlite 专用) -│ └── ipc-reap.c # 上面那个的 C 实现 -├── src/ -│ ├── backend/ # Rust 后端 -│ │ ├── src/{main,lib,routes,bootstrap}.rs # bootstrap = 装配根(唯一同时认识两层的地方) -│ │ ├── src/platform/ # 【平台层】{config,db,cipher,envelope,ids,session,state,auth,permission,seed,sys,jnpf,entity,crud,menu,guard}.rs -│ │ ├── src/modules/ # 【业务层】{mod,demo★,shop★,books★}.rs(各带 spec + handler + router + 菜单声明) -│ │ ├── db/schema.sql # 10 张表(base_* 7 + 业务 3) -│ │ └── tests/ # 7 个集成测试文件 -│ └── frontend/ # React + Vite(1374 行) -│ ├── utils/cipher · api/{request,auth,sys,product,book} -│ └── views/{Login,Dashboard,DemoItem★,Product★,Book★,UserManage,RoleManage,OrganizeManage,MenuManage} -├── references/ # BaseCrudController.java(**非** JNPF 官方类)+ README -├── template-boot-jnpf/ # JNPF 标准栈最小可运行骨架(Java) -└── docs/ # 项目级文档(契约真源 / 运维 / 裁决 / DDL) - ├── contract.md # 【契约唯一真源】端点 / 返回形状 / 数据模型 - ├── runbook.md # 怎么起 / 怎么冒烟 / 常见故障 - ├── decisions.md # 实施期逐条裁决(98 条「什么—为什么—代价」) - ├── known-limitations.md # 分支级已知限制(被接受/挂起的东西) - ├── build-bloat.md # 编译膨胀问题及处理(target/ 58G → 1.2G 的根因与处置) - └── ddl/ # 官方 DDL 摘录 +└── Cargo.toml # cargo workspace 根 ``` -★ = 业务模块模板(`HOWTO_MODULE.md` 参照实现)。 +**不在本仓**:`template-boot-jnpf/`、`references/`、`JNPF_COMPAT_SURFACE.md`、 +`JNPF_SOURCE_AUDIT.md`、`PERMISSION.md`、`HOWTO_MODULE.md`、`MIGRATION.md` 等技能资产, +以及 `books / demo / shop / asset` 业务示例包 —— 它们属于技能仓,本仓只保留平台能力与自测。 ## 快速开始 ```bash -# 最短路径:只跑后端(默认装配 sspf-admin,零外部服务) -cargo run -p sspf-admin # http://127.0.0.1:30010,账号 admin / 123456 -# 等价于 ./target/debug/sspf-admin;PGLITE_DIR=memory:// 用临时库(进程退出即销毁) - -# 一次性:装依赖(cargo fetch + npm install) -bash run.sh install -# 构建(cargo build --release + vite build) -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 # 看日志尾部 +cargo run -p sspf-admin # http://127.0.0.1:30010,admin / 123456 +bash run.sh install # cargo fetch + npm install +bash run.sh build # cargo build --release + vite build +bash run.sh dev # 后端 30010 + 前端 5173(都就绪才算成功) +bash run.sh stop / 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` ⇒ 端口被占直接报错,不自动换端口 | +| `30010` | 后端 | `run.sh` 硬约定;`PORT` ≠ 30010 时 dev/backend 报错退出 2 | +| `5173` | 前端 vite | `strictPort: true` | -> ⚠️ 本机 curl 走系统代理 ⇒ 打 localhost **必须**加 `--noproxy '*'`。 +> 本机 curl 走系统代理 ⇒ 打 localhost 必须加 `--noproxy '*'`。 -## 把脚手架复制到新项目 +## 验收 ```bash -SKILL=~/.agents/skills/ssw-jnpf-lite-rust # 技能目录(独立于本仓) -PROJ=~/Desktop/my-app -mkdir -p "$PROJ/src" # 脚手架固定进 src/:没有则创建,已有则并入 -rsync -a --exclude node_modules --exclude dist --exclude target --exclude data --exclude .DS_Store \ - "$SKILL"/src "$SKILL"/scripts "$SKILL"/run.sh "$SKILL"/Cargo.toml "$SKILL"/.env.example "$SKILL"/.gitignore "$PROJ"/ -cd "$PROJ" && cp .env.example .env && ./run.sh install && ./run.sh dev +cargo build --workspace --all-targets # 0 error / 0 warning +cargo test --workspace # 全绿 +bash scripts/verify.sh --fast # 内环:生成段同步 + 6 道静态闸门 +cargo build --release -p sspf-admin # --smoke 的尺子默认读 target/release/sspf-admin +bash scripts/verify.sh --smoke # 全量:+ 全量测试 + 5 把运行时尺子 +bash scripts/check-arch.sh --self-test # 闸门反自证 +cargo tree -p sspf | grep sspf-pack # 必须无输出(平台包零业务) ``` -> ⚠️ **只复制脚手架本体**——`*.md` / `references/` / `template-boot-jnpf/` 是技能资产,留在技能目录只读引用。 -> 全量 `cp -R` 会让项目目录混满技能噪音,日后技能升级也灌不进项目。 -> 🔴 **`Cargo.toml`(workspace 根)别漏**:缺了它 `src/backend` 的 `workspace = true` 继承无处可依 ⇒ cargo 直接报 -> `could not find Cargo.toml in ... or any parent directory`,**脚手架编译不起来**。 +静态闸门的期望值集中在 `docs/contract.md` 附录 A,由 `scripts/contract_expect.py` 解析; +每把尺子自证条数,被改弱即失败。 -## 验收门 +## 数据库 -| 门 | 命令 | 通过标准 | -|---|---|---| -| ① 编译 | `cargo build --release` | 0 error **0 warning** | -| ② 单测 | `cargo test --workspace` | 全绿(当前 **695 passed / 0 failed**:内核单测 + `crates/tests` 的 37 个集成测试二进制) | -| ③ 冒烟(面 A) | `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 三页可用 → 退出再登录 | +`pglite-rs 0.2` —— 进程内**原生 PostgreSQL**(不是浏览器 WASM 版),单 backend, +真实 SQL 语义。数据落 `src/backend/data/lite.pg`,**一个数据目录只能被一个进程打开**; +`PGLITE_DIR=memory://` 是临时目录的一次性库。无 TCP 监听 ⇒ `psql` 连不上, +导出走应用内 `COPY ... TO STDOUT`。 -外加四道**静态闸门**(纯静态,不起后端,加业务模块后立刻跑): -`bash scripts/check-module.sh`(10 接触点,93 条)+ `bash scripts/check-boundary.sh`(分层红线 CP1–CP6,11 条) -+ `bash scripts/check-contract.sh`(契约端点表 + 官方端点台账 ↔ 代码真实路由,10 条) -+ `bash scripts/check-citations.sh`(文档引文 `路径:行号`,4 条)。 +## 版本与迁移 -🔴 **六把尺子的期望值只有一处**:`docs/contract.md` **附录 A**(机器可读), -由 `scripts/contract_expect.py` 解析 ⇒ 改契约只改一处;代码漂移尺子立刻报; -每把尺子还**自证**自己的条数(被人改弱了 ⇒ 失败)。 - -📊 **官方端点覆盖是一本「账」**:附录 A 的 `[OFFICIAL]` 区段(53 行)把官方 JNPF 契约面的 -端点全表变成**机器可读**的覆盖账本(`implemented` / `partial` / `absent` / `oos` 四态)⇒ -`check-contract.sh` 的 **CC10** 拿它与**代码真实路由双向对账**,并打印 -**「官方端点覆盖 N/M」**(当前 **8/47**)—— **算出来的,不是人数的**; -台账的 `src` 列是官方出处 `文件:行号` ⇒ 由引文闸门**逐条核对**。 - -## 数据库:进程内原生 PostgreSQL - -**pglite-rs 0.2** —— 把 `postgres-pglite` 编译成**原生静态库**链进二进制 ⇒ 进程内单 backend, -**真实 PostgreSQL 语义**(类型 / MVCC / 事务 / 扩展 / 线协议)。 - -- 🔴 **不是**浏览器 WASM 版 PGlite(`@electric-sql/pglite`)——那个禁止引入。 -- 数据落盘 `src/backend/data/lite.pg`。 -- 🔴 **一个数据目录只能被一个进程打开** ⇒ 集成测试要么串行、要么各自独立数据目录。 -- 🔴 `PGLITE_DIR=memory://` = 系统临时目录里的一次性数据目录(进程退出即销毁),**不是**真内存模式。 -- 🔴 **无 TCP 监听** ⇒ `psql` / `pg_dump` **连不上** ⇒ 数据导出要走应用内的 `COPY ... TO STDOUT`(见 `MIGRATION.md` §6)。 - -## 已知限制(被接受 / 挂起) - -| 限制 | 说明 | +| tag | 内容 | |---|---| -| **面 B 仍有 10 条偏差** | 面 B 已落地(`src/backend/src/platform/jnpf.rs`,尺子 **18/18 全绿**),但 `AuthorizeDataReturnVO.list` 返空数组 · `sysConfigInfo` 返 `{}` · 无按钮/列/表单/数据级权限 · 业务菜单 `f_en_code` 是自拟占位 · `permissionList` 粒度 = 每菜单一条 · `Organize/AsyncList` 未分页 —— 逐条见 `JNPF_COMPAT_SURFACE.md` §8(B1–B10) | -| 不分页(**面 A**) | 面 A 契约里的 `List` 就是全量(前端不分页);要分页是 JNPF 稳定期的 `SuperServiceImpl.page`(**面 B 已是分页信封**) | -| 不做按钮/列/表单/数据范围级授权 | 官方 DDL 里有 `base_module_button` / `_column` / `_form` / `_data`,v1 只做 `item_type='module'` | -| 不做多租户 | 单租户固定 `f_tenant_id='0'` | -| 无 Redis / Sa-Token | 内存 token 表即可(进程重启即失效,与 JNPF 的 Sa-Token 内存模式同代) | -| 口令存储**缺 `secretkey` 一步** | 本仓存 `md5(明文)`,官方存 `md5(md5(明文)+secretkey)`;迁官方时**一次性换算**,**不需要明文**(`MIGRATION.md` §7) | -| `f_account` 无 UNIQUE | 官方 DDL 就是没有 ⇒ 唯一性**应用层**保证(只比 `delete_mark=0` 的行) | -| **两套权限判据并存** | 面 A 按**菜单路径**(`f_url_address`)、面 B 按**点权限**(`f_en_code`)⇒ 同一用户可能**面 A 通、面 B 拒**(设计,不是 bug) | -| 低代码引擎不碰 | 表单 / 流程 / 代码生成是官方能力 | -| token 寿命 = 进程寿命 | `session.rs` 是内存 token 表、无 TTL;`expiresIn:7200` 是契约字面量、**不强制执行** | +| `v0.2.0` | 标准平台包 P0:门面 `sspf`、示例包选装、AR17/AR18 | +| `v0.3.0` | P1:`Db::pg()` 同句柄、`assemble()/Finish` 两阶段装配、AR19 | +| 未发布 | 平台包零业务清理:示例包 / 面 A 适配器 / `example-packs` 全部退役,闸门改防回流 | -## 三个参照物(各司其职,别混) +发布说明见 `CHANGELOG.md`,逐版实施记录见 `HANDOFF.md` 与 `docs/SSPF-*.md`。 +已发布的 tag **一字不动**;破坏性变更走新 tag。 + +## 参照物 | 参照物 | 地位 | |---|---| -| 官方 JNPF 源码 + DDL(`~/Desktop/workspace/jnpf/`) | **数据模型真源**(`base_*` 表名/列名) | -| `ssw-jnpf-lite-react` 技能(`~/Desktop/workspace/skills/ssw-jnpf-lite-react/`) | **行为真源**(NestJS 版把契约跑起来了);本仓前端是它的**逐字复制** | -| `tdc-rs` 兄弟项目(`~/Desktop/workspace/tdc-rs/`) | **只抄工程手法**;不共享代码 / 端口 / 数据目录 | - -## 与 react 版的关系 - -| | react 版 | rust 版 | -|---|---|---| -| 后端栈 | NestJS | axum | -| 端口 | **30000** | **30010** | -| 契约 | 同一套(面 A) | 同一套(面 A) | -| 前端 | 同一份 React 产物 | 同一份 React 产物 | -| 业务表名 | `demo_item` / `shop_product` / `book_shop_book` | **同名** ⇒ 两版后端能开同一个库(2026-11-04 起多一列 `f_tenant_id DEFAULT '0'`,react 侧可忽略) | -| 尺子 | `perm-smoke.sh`(22 条基线) | `perm-smoke.sh`(32 条)+ `perm-smoke-jnpf.sh`(18 条) | - -🔴 **两版之间不共享代码、不共享端口、不共享数据目录**。 -迁移走「换栈」路径:契约不变 ⇒ **前端零改**,只换后端进程。 -详见 [`MIGRATION.md`](MIGRATION.md) §5。 - -## 技术栈 - -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(逐字复用) +| 官方 JNPF 源码 + DDL(`~/Desktop/workspace/jnpf/`) | `base_*` 数据模型真源 | +| 技能仓 `ssw-jnpf-lite-rust` | JNPF MVP 示例、演示前端、面 B 规格与迁移说明 | +| `tdc-rs` 兄弟业务仓 | 平台包的真实消费者(P2 改造参照) | +| `ssw-jnpf-lite-react` | 面 A 行为真源(NestJS 版) | diff --git a/crates/sspf-admin/Cargo.toml b/crates/sspf-admin/Cargo.toml index b4230a1..d9345c1 100644 --- a/crates/sspf-admin/Cargo.toml +++ b/crates/sspf-admin/Cargo.toml @@ -28,10 +28,8 @@ path = "src/main.rs" [dependencies] # 🔴 **唯一的平台依赖**(门面)。业务仓照抄这一行即可。 -# -# 🔴 `example-packs` **只在这里开**:`sspf-admin` 是本仓的默认装配,要带 -# 4 个示例包(asset / books / demo / shop)。业务仓(tdc-rs)**不开**这个 feature -# ⇒ 依赖树里没有 `sspf-pack-*`(`check-arch.sh` 的 AR17 钉住)。 -sspf = { path = "../sspf", features = ["example-packs"] } +# `sspf-admin` 现在是**纯平台装配**(177 张平台表、面 A 无业务端点): +# 示例包已搬到技能仓 `ssw-jnpf-lite-rust`,那里才注入业务。 +sspf = { path = "../sspf" } tokio = { workspace = true } diff --git a/crates/sspf-admin/src/main.rs b/crates/sspf-admin/src/main.rs index 3a3a989..0ec7f68 100644 --- a/crates/sspf-admin/src/main.rs +++ b/crates/sspf-admin/src/main.rs @@ -11,9 +11,9 @@ //! 写在 CLI 里 ⇒ 业务仓要么抄一遍(抄漏一步就是静默故障),要么永远用不上。 //! ⇒ 搬到 `crates/sspf`,本文件从 1111 行降到「CLI 该有的样子」。 //! -//! 🔴 **示例包(asset/books/demo/shop)只在这里开**: -//! `sspf` 的 `example-packs` feature 只被本包与 `crates/tests` 打开。 -//! 业务仓只依赖 `sspf`(默认 feature)⇒ 依赖树里没有 `sspf-pack-*`(AR17)。 +//! 🔴 **纯平台装配**(2026-11-04 清理):`serve_platform()` 就是 `Platform::new()`。 +//! 4 个示例包已搬到技能仓 `ssw-jnpf-lite-rust`;本二进制只有 177 张平台表、 +//! 面 A 无业务端点。要跑示例请用技能仓的装配。 //! //! 装配顺序(契约 §10)的权威实现:`sspf::platform::Platform::boot` 的注释。 @@ -126,24 +126,12 @@ async fn main() { } } -/// 🔴 **本仓默认装配**:平台 + 4 个示例包(asset / books / demo / shop)。 +/// 🔴 **纯平台装配**:`Platform::new()` 一个业务包 / 一条业务路由都不带。 /// -/// 🔴 **示例包的注册表必须显式注入** —— 不能指望 `bootstrap::packs()` 那个 -/// `OnceLock` 单例(first-call-wins ⇒ 注入静默失效)。 -/// -/// 🔴 **面 A(`/api/ssw/{app}/{Entity}/{List|Save|Delete}`)也要显式注入**: -/// 它是**本仓业务层**(`modules::router()`)的路由,门面默认一个都不认识。 -/// 漏了这一句的表现不是编译错误,而是面 A 全 404(`perm-smoke.sh` 当场红)。 +/// 业务仓(含技能仓的示例)通过 `sspf::Platform::packs(reg)` / `.router()` / +/// `.menus()` 注入自己的业务。本二进制是「平台裸跑」的参考消费者。 fn serve_platform() -> Platform { - let platform = Platform::new().router(sspf::kernel::modules::router()); - match sspf::example_packs() { - Ok(reg) => platform.packs(reg), - Err(e) => { - // 装载失败 ⇒ 它的端点不存在 ⇒ 前端一访问就是 404 ⇒ **必须响亮地失败**。 - eprintln!("[启动失败] 业务包装载失败: {e}"); - std::process::exit(1); - } - } + Platform::new() } /// 打印用法(`--help` / 未知参数)。 diff --git a/crates/sspf-contract/src/envelope.rs b/crates/sspf-contract/src/envelope.rs index ae6e2c3..a4f52a5 100644 --- a/crates/sspf-contract/src/envelope.rs +++ b/crates/sspf-contract/src/envelope.rs @@ -61,7 +61,7 @@ impl ActionResult { /// 这里只是把**官方码表**补齐,供**面 B**(基线平台契约面)引用。 /// 面 B 的 `ok` / `fail` 语义与面 A **完全相同**(同一个信封、同样的「恒 HTTP 200」)。 /// -/// 官方码表(`JNPF_SOURCE_AUDIT.md` §4): +/// 官方码表(`技能仓 JNPF_SOURCE_AUDIT.md` §4): /// - `200` SUCCESS / `400` FAIL / `401` VALIDATEERROR / `403` PEIMISSIONEXP / /// `500` EXCEPTION / `600` SESSIONOVERDUE / `601` SESSIONOFFLINE / `602` SESSIONERROR。 /// diff --git a/crates/sspf-contract/src/headers.rs b/crates/sspf-contract/src/headers.rs index b5bcca2..5399c67 100644 --- a/crates/sspf-contract/src/headers.rs +++ b/crates/sspf-contract/src/headers.rs @@ -1,6 +1,6 @@ //! headers —— 请求头契约:判别头常量 + 面 A/面 B 分流判据。 //! -//! **唯一的全局判别规则**(`JNPF_COMPAT_SURFACE.md` §2.2): +//! **唯一的全局判别规则**(`技能仓 JNPF_COMPAT_SURFACE.md` §2.2): //! ```text //! 请求头含 "Vue-Version: 3" ⇒ 走【面 B】基线平台形状 //! 否则 ⇒ 走【面 A】自有形状 diff --git a/crates/sspf-contract/src/route.rs b/crates/sspf-contract/src/route.rs index 51fae2d..87977fe 100644 --- a/crates/sspf-contract/src/route.rs +++ b/crates/sspf-contract/src/route.rs @@ -104,7 +104,7 @@ impl HttpMethod { /// 🔴 **`path` 必须是官方 JNPF 的形状**(`/api/{模块}/{资源}/...`), /// **不许**用面 A 的 `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}` —— /// 面 A 是本仓自造的 ssw 约定,集成到官方 JNPF 时**全部作废**。 -/// (见 `MIGRATION.md` §2.3 的逐条对照表。) +/// (见 `技能仓 MIGRATION.md` §2.3 的逐条对照表。) #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct PackRoute { /// 完整路径(**以 `/` 开头**,不含 query string)。 diff --git a/crates/sspf-core/src/crud.rs b/crates/sspf-core/src/crud.rs index 90e8cf0..b5070ce 100644 --- a/crates/sspf-core/src/crud.rs +++ b/crates/sspf-core/src/crud.rs @@ -455,7 +455,7 @@ async fn guard( // | 官方对应 | `SswPermissionGuard.requireMenu(...)` | `@SaCheckPermission("xxx.yyy")` | // | 未登录码 | **600** | **602**(官方前端只在 601/602 清 token) | // -// 🔴 **602 这条是硬要求**(`MIGRATION.md` §2.5):官方前端 +// 🔴 **602 这条是硬要求**(`技能仓 MIGRATION.md` §2.5):官方前端 // `request.ts:78-80` 只对 `601`/`602` 清 token ⇒ 只返 600 会让页面**卡住不跳登录**。 // ⇒ 面 A 保持 600、面 B 返 602 —— **两套并存**(与判据一样并存)。 diff --git a/crates/sspf-core/src/registry.rs b/crates/sspf-core/src/registry.rs index c79b34e..222d055 100644 --- a/crates/sspf-core/src/registry.rs +++ b/crates/sspf-core/src/registry.rs @@ -15,7 +15,7 @@ //! **它住在契约面 crate,不在本 crate** —— 平台核心不许反向依赖契约面,见 AR10)。 //! //! 🔴 **`App-Code` 不是契约判别头**:判别「面 A / 面 B」只看 `Vue-Version: 3` -//! (`JNPF_COMPAT_SURFACE.md` §2.2)。`App-Code` 只选「当前应用」,且本仓前端 +//! (`技能仓 JNPF_COMPAT_SURFACE.md` §2.2)。`App-Code` 只选「当前应用」,且本仓前端 //! 也发它 ⇒ 它**绝不能**当判别头(见 `face_b.rs::is_face_b` 的注释)。 //! //! 🔴 **缺省 / 未命中 ⇒ 主系统**(`MAIN_SYSTEM_CODE`)—— 与官方 diff --git a/crates/sspf-store/src/db.rs b/crates/sspf-store/src/db.rs index 0cc7b75..17c3508 100644 --- a/crates/sspf-store/src/db.rs +++ b/crates/sspf-store/src/db.rs @@ -49,16 +49,15 @@ pub const SCHEMA_SQL: &str = include_str!("../../../src/backend/db/schema.sql"); /// 🔴 **为什么平台表写死、业务表不写死**(批次 12 交付物 ③): /// - 平台表 = **平台层**的责任 ⇒ 加一张要同时改 `crates/sspf-admin/src/main.rs` 的 `BASE_TABLES` /// (闸门查「孤儿 DDL」会红 ⇒ 两处都改才算登记完成)⇒ 数量写死是**有意的护栏**; -/// - 业务表 = **业务包**的责任 ⇒ 住 `packs//schema/*.sql` +/// - 业务表 = **业务仓**的责任 ⇒ 住业务仓/技能仓的 `packs//schema/*.sql` /// ⇒ 加包**不该**改内核 ⇒ 数量写死是**错误的耦合**。 pub const BASE_TABLE_COUNT: usize = 123; /// 🔴 **面 A 内嵌业务表** —— **2026-11-04 起为空**。 /// /// 原来这里写着 `demo_item` / `shop_product` / `book_shop_book` 三张"留在内核 -/// `schema.sql` 里"的示例表。它们已经搬进示例业务包 -/// (`packs/{demo,shop,books}/schema/001_init.sql`)—— -/// 理由:示例要能**整目录搬去技能**当样板,DDL 留在内核就等于「搬不干净」。 +/// `schema.sql` 里"的示例表。2026-11-04 零业务清理后,它们连同 4 个示例包整体 +/// 搬到技能仓 `ssw-jnpf-lite-rust`;本仓不再认识任何业务表。 /// /// 🔴 保留这个常量(空数组)而不是删掉:`schema_sql_has_expected_table_count` /// 与 `ddl_tables_parses_every_create_table` 都用它做「业务表必须恰好是这些」 @@ -954,6 +953,8 @@ pub fn ddl_tables() -> Vec { // 原来只认 `schema.sql` 里的表。批次 12 之后**业务表的 DDL 跟着包走** // ⇒ 包建的表**从来没被保护过**(`asset_data_resource` 可以被建模页删掉, // 一直是静默洞)。示例表(`demo_item` 等)搬进包之后也掉了出去, +// 🔴 2026-11-04 清理后本仓不装载任何业务包,但**这条能力仍是平台能力**: +// 业务仓注入的包表照样由 `register_pack_tables` 登记并受保护。 // 两个集成测试当场抓到 ⇒ 这里把「平台 DDL ∪ 包声明的表」合成一个判据。 // // 🔴 **为什么用 `OnceLock` 而不是给 `AppState` 加字段**: @@ -1415,10 +1416,9 @@ mod tests { // ① **平台表**(`base_*`)—— 数量**写死**(`BASE_TABLE_COUNT` 张):加一张平台表是 // **平台层**的责任 ⇒ 必须同时改 `crates/sspf-admin/src/main.rs` 的 `BASE_TABLES` // (闸门查「孤儿 DDL」会红 ⇒ 两处都改才算登记完成); - // ② **面 A 内嵌业务表**(3 张)—— 清单**写死**(名字列表,不是数字): - // 它们是 react 版的**对齐基准**,留在内核侧; - // ③ **业务包的表**(`asset_data_resource` 等)—— **不在本文件里** - // ⇒ 住 `packs//schema/*.sql`,编译进二进制。 + // ② **面 A 内嵌业务表** —— 2026-11-04 起**恒空**(本仓零业务); + // ③ **业务仓包的表**(`asset_data_resource` 等)—— **不在本文件里** + // ⇒ 住业务仓/技能仓的 `packs//schema/*.sql`,由门面注入。 // // 🔴 **为什么不再写死「总表数 52」**:那个数字会因「加一张业务包表」而变 // ⇒ 每次加包都要改这里 ⇒ 业务包的表数**不由内核决定** ⇒ 写死是错的耦合。 @@ -1466,7 +1466,7 @@ mod tests { let tables = ddl_tables(); assert!( !tables.iter().any(|t| t == "asset_data_resource"), - "asset_data_resource 的 DDL 住 packs/asset/schema/001_init.sql,不该在 schema.sql 里" + "asset_data_resource 的 DDL 属于业务包(技能仓),不该在平台 schema.sql 里" ); } diff --git a/crates/sspf/Cargo.toml b/crates/sspf/Cargo.toml index c8f06bb..b268cb0 100644 --- a/crates/sspf/Cargo.toml +++ b/crates/sspf/Cargo.toml @@ -16,12 +16,8 @@ description = "SSPF 标准平台包 —— 业务仓唯一依赖的门面(平 # 🔴 **本 crate 是业务仓唯一该依赖的东西** —— 它不直接碰 19 个 `sspf-*`; # 依赖列在这里改了,业务仓无感(这正是门面的意义)。 -[features] -default = [] -# 只给本仓的 `sspf-admin`(默认装配)与 `sspf-tests`(集成测试)用。 -# 🔴 **业务仓不开** —— 开了就会把本仓 4 个示例包(asset/demo/shop/books)拖进 -# 业务二进制。`check-arch.sh` 的 AR17 钉住「默认 feature 下没有 sspf-pack-*」。 -example-packs = ["ssw-platform/example-packs"] +# 🔴 **没有 `[features]`**(2026-11-04 清理):`example-packs` 随示例包一起搬走。 +# 本 crate 的依赖树里**恒无** `sspf-pack-*`,业务仓不需要也不该开任何 feature。 [dependencies] # 内核:装配根(bootstrap) / 路由链(routes) / 启动原语(boot) diff --git a/crates/sspf/src/lib.rs b/crates/sspf/src/lib.rs index 1062800..e14572f 100644 --- a/crates/sspf/src/lib.rs +++ b/crates/sspf/src/lib.rs @@ -4,7 +4,7 @@ //! //! 业务仓(自带实体 / 表 / 自定义端点的应用仓)要的是一份**可版本锁定的平台**: //! 登录 / 权限 / 面 B 全套 JNPF 兼容能力 / 低代码 / MCP。 -//! 它不该知道平台内部拆了 19 个 crate,也不该被拖进本仓的 4 个示例包。 +//! 它不该知道平台内部拆了 19 个 crate;本仓零业务,4 个示例包在技能仓。 //! //! ```ignore //! // 业务仓 src/main.rs(薄业务:路由用平台状态) @@ -33,8 +33,8 @@ //! 在 merge 自带状态业务路由**之前**完成(v0.3.0 起),且之后不再新增需要 //! `AppState` 的路由。业务仓**不能**自己抄一遍,只能把路由交给 //! [`Platform::router`] 或 [`Finish::router`]。 -//! 3. **平台包里零业务** —— 默认 feature 下本 crate 的依赖树里**没有** `sspf-pack-*` -//! (`check-arch.sh` 的 AR17 钉住);本 crate 源码里没有业务表名 / 端点字面量 +//! 3. **平台包里零业务** —— 本 crate 的依赖树里**没有** `sspf-pack-*`(没有 +//! `example-packs` feature,`check-arch.sh` 的 AR17 钉住);本 crate 源码里没有业务表名 / 端点字面量 //! (AR18)。AR19 钉住「唯一 fallback / 唯一装配链」。 //! //! ## 版本号有三套,别混 @@ -48,7 +48,8 @@ //! ## 面 A / 面 B 行为一字不改 //! //! 门面只做**装配**,不改任何端点形状、码表、表结构:`Vue-Version: 3` 判别、 -//! `base_*` 181 张表、cipher、602 码、panic ⇒ HTTP 200 + `code=400` 全部照旧。 +//! `base_*` 177 张平台表、cipher、602 码、panic ⇒ HTTP 200 + `code=400` 全部照旧 +//! (181 = 177 平台表 + 4 张示例包表;示例包现已搬到技能仓)。 #![forbid(unsafe_op_in_unsafe_fn)] @@ -96,20 +97,9 @@ pub mod kernel { pub use ssw_platform::compat; pub use ssw_platform::lowcode_seed; pub use ssw_platform::mcp_adapter; - pub use ssw_platform::modules; pub use ssw_platform::routes; } -/// 🔴 **本仓示例包注册表**(`packs/{asset,books,demo,shop}`)—— 只有开了 -/// `example-packs` feature 才存在。 -/// -/// 🔴 **业务仓永远不该调它**:它的存在只为 `sspf-admin`(默认装配)与集成测试。 -/// 默认 feature 下本函数**不存在**(不是返回空)⇒ 误用是编译错误,不是静默退化。 -#[cfg(feature = "example-packs")] -pub fn example_packs() -> Result { - ssw_platform::bootstrap::load_packs().map_err(|e| format!("示例包装载失败: {e}")) -} - /// 门面版本(= cargo 版本,业务仓锁的那个)。 pub const VERSION: &str = env!("CARGO_PKG_VERSION"); @@ -122,17 +112,17 @@ mod tests { assert_eq!(super::VERSION, "0.3.0"); } - /// 🔴 **默认 feature 下不得装任何示例包** —— 这条与 AR17 的静态判据互补: + /// 🔴 **平台包恒零业务**(2026-11-04 清理)—— 与 AR17 的静态判据互补: /// AR17 看 Cargo.toml,这条看**编译出来的代码路径**。 + /// 示例包已搬到技能仓,本仓不再有 `example_packs()` 这个出口。 #[test] - fn default_build_carries_no_example_packs() { - if cfg!(feature = "example-packs") { - return; // 本仓自测时 feature 是开的(sspf-tests 会开) - } - let reg = ssw_platform::bootstrap::load_packs().expect("默认 feature 也必须可装载(空表)"); + fn platform_carries_no_example_packs() { + let reg = ssw_platform::bootstrap::load_packs().expect("空注册表必须是合法形态"); + assert!(reg.entities.is_empty(), "平台包不得装载任何业务实体"); + assert!(reg.ddls.is_empty(), "平台包不得携带任何业务 DDL"); assert!( - reg.entities.is_empty(), - "默认 feature 是平台包:不得装载示例业务包" + format!("{:?}", super::Platform::new()).contains("packs: []"), + "默认装配不得带包" ); } } diff --git a/crates/tests/Cargo.toml b/crates/tests/Cargo.toml index 64bb0dc..120a8ca 100644 --- a/crates/tests/Cargo.toml +++ b/crates/tests/Cargo.toml @@ -26,11 +26,8 @@ path = "src/lib.rs" [dev-dependencies] # 被测对象:内核(lib `ssw_platform`)—— 装配根 / 路由 / 业务层 / MCP 适配壳 # -# 🔴 **`example-packs` 必须开**:集成测试测的是「装配好的平台」,37 个测试里 -# 大量断言 `/api/demo/...`、`/api/shop/...`、181 张表。默认 feature 的内核 -# 是**平台包**(零业务)⇒ 不开这个 feature 会大面积假红。 -# 这与「业务仓不开」不矛盾:业务仓测自己的包,不测本仓的示例包。 -ssw-platform = { path = "../../src/backend", features = ["example-packs"] } +# 🔴 **平台包零业务**:集成测试测的就是「不带任何业务包的平台装配」。 +ssw-platform = { path = "../../src/backend" } # 平台核心(信封 / 登录 / 权限 / base_* / CRUD 引擎) sspf-core = { path = "../sspf-core" } # 低代码纯计算层(FormSchema / ModelSchema 的解析与校验) @@ -39,7 +36,7 @@ sspf-lowcode = { path = "../sspf-lowcode" } sspf-mcp = { path = "../sspf-mcp" } # 🔴 **标准平台包门面**:`external_consumer_it` 只 `use sspf::Platform` # —— 外部消费方视角的探针(不碰内核与 19 个 sspf-* crate)。 -sspf = { path = "../sspf", features = ["example-packs"] } +sspf = { path = "../sspf" } axum = { workspace = true } tokio = { workspace = true } diff --git a/crates/tests/tests/auth_it.rs b/crates/tests/tests/auth_it.rs index 16db65a..89b4c09 100644 --- a/crates/tests/tests/auth_it.rs +++ b/crates/tests/tests/auth_it.rs @@ -443,11 +443,12 @@ async fn current_user_with_token_returns_user_info_and_menu() { ); let menu = data["menuList"].as_array().expect("menuList 必须是数组"); - // 🔴 根节点数 = 1 个系统管理目录 + N 个业务根菜单(业务模块数由业务层决定, - // 钉 `>= 4` 而不是写死 ⇒ 加业务模块不用改这条测试)。 + // 🔴 **平台包零业务**(2026-11-04 清理):示例包搬到技能仓后, + // 内置菜单只剩 5 条系统菜单 ⇒ 根节点**恰好 1 个**系统管理目录。 + // 业务仓注入自己的 `.menus()` 后这里会变多 ⇒ 钉「至少 1」而不是写死。 assert!( - menu.len() >= 4, - "管理员应看到至少 4 个根菜单,实际 {}", + menu.len() >= 1, + "管理员应至少看到系统管理根菜单,实际 {}", menu.len() ); assert_eq!( diff --git a/crates/tests/tests/batch7_it.rs b/crates/tests/tests/batch7_it.rs index 8d318e9..4c37e57 100644 --- a/crates/tests/tests/batch7_it.rs +++ b/crates/tests/tests/batch7_it.rs @@ -412,11 +412,12 @@ async fn builtin_tables_cannot_be_altered_or_dropped() { assert_eq!(upd["code"], 400, "{upd}"); assert_eq!(upd["msg"], "系统自带表,不允许被编辑", "官方 DB102: {upd}"); - // 业务表(`demo_item`)也在 DDL 里 ⇒ 同样受保护。 + // 🔴 **平台包零业务**(2026-11-04 清理):示例业务表已搬到技能仓, + // 改用第二张平台内置表 `base_role` 验证「保护不是只认 base_user」。 let (_, del2) = call( port, "DELETE", - "/api/system/DataModel/0/Table/demo_item", + "/api/system/DataModel/0/Table/base_role", &token, None, ) @@ -744,7 +745,7 @@ async fn copy_guards_and_delete_all_spares_builtin() { .await; assert_eq!(cleared["code"], 200, "{cleared}"); - // 🔴 清空的只是**非内置**表:`base_user` / `demo_item` 必须都还在。 + // 🔴 清空的只是**非内置**表:`base_user` / `base_role` 必须都还在。 // 🔴 **pageSize 给 1000 而不是 100**(批次 17 改):官方平台表已全量导入 // (123 张 `base_*`)⇒ 库里有 127+ 张表;`pageSize=100` 会把 `base_user` // 截到第 2 页 ⇒ 断言「内置表还在」会**假失败**(表其实没被删)。 @@ -763,7 +764,7 @@ async fn copy_guards_and_delete_all_spares_builtin() { .filter_map(|t| t["table"].as_str().map(str::to_string)) .collect(); assert!(names.contains(&"base_user".to_string()), "内置表被误删: {names:?}"); - assert!(names.contains(&"demo_item".to_string()), "业务表被误删: {names:?}"); + assert!(names.contains(&"base_role".to_string()), "平台内置表被误删: {names:?}"); assert!( !names.contains(&"it7_src".to_string()), "自建表应被清掉: {names:?}" diff --git a/crates/tests/tests/crud_it.rs b/crates/tests/tests/crud_it.rs deleted file mode 100644 index ca945be..0000000 --- a/crates/tests/tests/crud_it.rs +++ /dev/null @@ -1,856 +0,0 @@ -//! crud 集成测试 —— spec 驱动的通用 CRUD 引擎 + demo / shop / books 三个业务模块。 -//! -//! 🔴 pglite-rs 0.2.7 是**进程级全局标志**:一个进程一辈子只能开一个实例 -//! (第二次 `open()` ⇒ `Error::AlreadyOpen`)⇒ 全文件**共用一个临时库** -//! (`OnceCell` 起一次),不每个测试函数各开一个(裁决 S11)。 -//! -//! 🔴 **测试之间必须串行**:Rust 的 test harness 把同一个 `tests/*.rs` 里的 -//! `#[tokio::test]` **并发**跑 ⇒ 共用一个库时它们会互相踩数据 -//! ⇒ 用一把进程级 `tokio::sync::Mutex` 把每个测试**整体**串起来。 -//! -//! 🔴 **不依赖测试执行顺序**:每个测试用**自己专属**的标题 / id; -//! 需要「不存在」前置条件的 ⇒ 自己先 `DELETE` 造出前置条件再断言。 - -use std::path::PathBuf; -use std::sync::Arc; - -use axum::body::Bytes; -use axum::extract::{RawQuery, State}; -use axum::http::{HeaderMap, HeaderValue}; -use serde_json::{json, Value}; -use ssw_platform::bootstrap::ensure_base; -use sspf_core::config::Config; -use ssw_platform::modules::{books, demo, shop}; -use sspf_core::db::Db; -use axum::Json; -use sspf_core::envelope::ActionResult; -use sspf_core::seed::first_seed; -use sspf_core::session::{SessionStore, TicketStore}; -use sspf_core::state::AppState; -use tokio::sync::{Mutex, OnceCell}; - -/// 全文件共享的临时库。 -static DB: OnceCell = OnceCell::const_new(); - -/// 把同文件的测试**整体**串行化(共用一个库 ⇒ 必须串行)。 -static LOCK: Mutex<()> = Mutex::const_new(()); - -async fn db() -> &'static Db { - DB.get_or_init(|| async { - let db = Db::open_temp().await.expect("打开 pglite 临时库失败"); - ssw_platform::bootstrap::ensure_schema_all(&db) - .await - .expect("ensure_schema_all 失败"); - ensure_base(&db).await.expect("ensure_base 失败"); - first_seed(&db, "123456").await.expect("first_seed 失败"); - db - }) - .await -} - -/// 造一个应用状态(**每个测试自己一份** ⇒ token 表互不干扰)。 -fn new_state(db: &Db) -> AppState { - AppState { - config: Arc::new(Config::from_env(PathBuf::from("/tmp/ssw-platform-crud-it"))), - db: Arc::new(db.clone()), - sessions: Arc::new(SessionStore::new()), - tickets: Arc::new(TicketStore::default()), - } -} - -/// 取种子 admin 的用户 id。 -async fn admin_id(db: &Db) -> String { - let rows = db - .query_json("SELECT f_id AS \"id\" FROM base_user WHERE f_account = 'admin' LIMIT 1") - .await - .expect("查 admin 失败"); - rows.first() - .and_then(|r| r.get("id")) - .and_then(Value::as_str) - .expect("种子里必须有 admin 用户") - .to_string() -} - -/// 造一个**管理员** token(管理员短路 ⇒ 菜单守卫直接放行)。 -async fn admin_state(db: &Db) -> (AppState, HeaderMap) { - let state = new_state(db); - let id = admin_id(db).await; - let token = state.sessions.issue("admin", &id, 1); - (state, auth_headers(&token)) -} - -/// 造一个**非管理员** token(`f_is_administrator = 0`、**无任何授权**)。 -/// -/// 🔴 用来验证「菜单守卫真的会拦人」(裁决 S15):`shop/Product` 与 `books/Book` -/// 这两个菜单 key 已由种子写入 `base_module` ⇒ 非管理员没授权 ⇒ `code=403`。 -async fn plain_user_state(db: &Db) -> (AppState, HeaderMap) { - let state = new_state(db); - let user_id = "it_crud_plain_user"; - db.exec(&format!( - "DELETE FROM base_user WHERE f_id = '{user_id}'; \ - INSERT INTO base_user (f_id, f_account, f_password, f_is_administrator, \ - f_enabled_mark, f_delete_mark) \ - VALUES ('{user_id}', '{user_id}', 'x', 0, 1, 0)" - )) - .await - .expect("造非管理员用户失败"); - let token = state.sessions.issue(user_id, user_id, 0); - (state, auth_headers(&token)) -} - -/// 带 `bearer ` 的请求头。 -fn auth_headers(token: &str) -> HeaderMap { - let mut headers = HeaderMap::new(); - let value = - HeaderValue::from_str(&format!("bearer {}", token)).expect("token 必须是合法 header 值"); - headers.insert("authorization", value); - headers -} - -/// 空请求头(未登录)。 -fn anon_headers() -> HeaderMap { - HeaderMap::new() -} - -/// 造一个 query。 -fn query(raw: &str) -> RawQuery { - RawQuery(Some(raw.to_string())) -} - -/// 造一个**完全没有 query** 的 `RawQuery`(`RawQuery(None)`)。 -fn query_none() -> RawQuery { - RawQuery(None) -} - -/// 信封的 `data` 必须是对象。 -fn data_obj(r: &Json) -> Value { - assert_eq!(r.0.code, 200, "期望成功,实际 code={}", r.0.code); - r.0.data.clone() -} - -/// 信封的 `data` 必须是数组。 -fn data_arr(r: &Json) -> Vec { - assert_eq!(r.0.code, 200, "期望成功,实际 code={}", r.0.code); - r.0.data.as_array().expect("data 必须是数组").clone() -} - -// ---------------------------------------------------------------- Product - -/// 新建 Product ⇒ `data.id` 长度 36、**`data.price == "9.90"`(字符串)**。 -#[tokio::test] -async fn product_save_creates_product_with_price_as_string() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-产品-1"; - db.exec(&format!("DELETE FROM shop_product WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - let r = shop::product_save( - State(state.clone()), - headers, - Bytes::from(json!({"title": title, "price": "9.90"}).to_string()), - ) - .await; - let data = data_obj(&r); - - let id = data["id"].as_str().expect("id 必须是字符串"); - assert_eq!(id.len(), 36, "主键必须是 36 位 UUID: {id}"); - assert_eq!(data["title"], title); - // 🔴 numeric 列必须序列化成**字符串**(`f_price::text`)。 - assert_eq!(data["price"], "9.90", "price 必须是字符串 9.90"); - assert!(data["price"].is_string(), "price 必须是 JSON 字符串"); - assert_eq!(data["creatorUserId"], "admin"); - assert_eq!(data["deleteMark"], 0); - assert!(data["creatorTime"].is_string(), "creatorTime 必须是 ISO 串"); - assert!(data["creatorTime"].as_str().unwrap().ends_with('Z')); -} - -/// Product 的 `creatorUserId` 取 body(缺省才回落 `'admin'`)。 -#[tokio::test] -async fn product_creator_user_id_comes_from_body() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-产品-2"; - db.exec(&format!("DELETE FROM shop_product WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - let r = shop::product_save( - State(state.clone()), - headers, - Bytes::from(json!({"title": title, "creatorUserId": "someone"}).to_string()), - ) - .await; - let data = data_obj(&r); - assert_eq!(data["creatorUserId"], "someone"); -} - -/// 路径 1:body 不给 price ⇒ 用 spec 的默认值 `'0.00'`。 -#[tokio::test] -async fn product_price_defaults_to_zero() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-产品-3"; - db.exec(&format!("DELETE FROM shop_product WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - let r = shop::product_save( - State(state.clone()), - headers, - Bytes::from(json!({"title": title}).to_string()), - ) - .await; - let data = data_obj(&r); - assert_eq!(data["price"], "0.00", "缺省 price 必须是 0.00"); -} - -// ---------------------------------------------------------------- Book - -/// 新建 Book(6 个业务字段)⇒ `price == "58.00"`(字符串)、`stock == 100`(**数字**)。 -#[tokio::test] -async fn book_save_creates_book_with_string_price_and_numeric_stock() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-书-1"; - db.exec(&format!("DELETE FROM book_shop_book WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - let r = books::book_save( - State(state.clone()), - headers, - Bytes::from( - json!({ - "title": title, - "author": "作者甲", - "isbn": "9780000000001", - "category": "技术", - "price": "58.00", - "stock": 100 - }) - .to_string(), - ), - ) - .await; - let data = data_obj(&r); - - assert_eq!(data["id"].as_str().unwrap().len(), 36); - assert_eq!(data["title"], title); - assert_eq!(data["author"], "作者甲"); - assert_eq!(data["isbn"], "9780000000001"); - assert_eq!(data["category"], "技术"); - assert_eq!(data["price"], "58.00", "price 必须是字符串"); - assert!(data["price"].is_string()); - // 🔴 int 列保持**数字**。 - assert_eq!(data["stock"], 100); - assert!(data["stock"].is_number(), "stock 必须是 JSON 数字"); - assert_eq!(data["creatorUserId"], "admin"); - assert_eq!(data["deleteMark"], 0); -} - -/// 路径 1:Book 不给 price / stock ⇒ `price == "0.00"`、`stock == 0`。 -#[tokio::test] -async fn book_price_and_stock_defaults() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-书-2"; - db.exec(&format!("DELETE FROM book_shop_book WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - let r = books::book_save( - State(state.clone()), - headers, - Bytes::from(json!({"title": title}).to_string()), - ) - .await; - let data = data_obj(&r); - assert_eq!(data["price"], "0.00"); - assert_eq!(data["stock"], 0); -} - -// ---------------------------------------------------------------- DemoItem - -/// 新建 DemoItem ⇒ `status == "草稿"`(默认值)、`creatorUserId == "admin"`(**硬编码**)。 -#[tokio::test] -async fn demo_item_uses_default_status_and_hardcoded_admin() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-草稿-1"; - db.exec(&format!("DELETE FROM demo_item WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - let r = demo::demo_item_save( - State(state.clone()), - headers, - Bytes::from(json!({"title": title, "creatorUserId": "someone-else"}).to_string()), - ) - .await; - let data = data_obj(&r); - - assert_eq!(data["status"], "草稿", "缺省 status 必须是 草稿"); - // 🔴 demo_item 的 creatorUserId **硬编码** `'admin'`(body 给了也忽略)。 - assert_eq!(data["creatorUserId"], "admin"); - assert_eq!(data["id"].as_str().unwrap().len(), 36); - assert_eq!(data["deleteMark"], 0); -} - -// ---------------------------------------------------------------- List / Delete - -/// List 只返回未软删的行:Delete 后 list 长度 -1。 -#[tokio::test] -async fn list_hides_soft_deleted_rows() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-列表-1"; - db.exec(&format!("DELETE FROM shop_product WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - let r = shop::product_save( - State(state.clone()), - headers.clone(), - Bytes::from(json!({"title": title}).to_string()), - ) - .await; - let data = data_obj(&r); - let id = data["id"].as_str().expect("id").to_string(); - - let before = data_arr(&shop::product_list(State(state.clone()), headers.clone()).await); - assert!( - before.iter().any(|row| row["id"] == id.as_str()), - "新建的行必须在 list 里" - ); - - let d = shop::product_delete( - State(state.clone()), - headers.clone(), - query(&format!("id={id}")), - ) - .await; - assert_eq!(d.0.code, 200); - assert_eq!(d.0.data, Value::Null, "Delete 的 data 必须是 null"); - - let after = data_arr(&shop::product_list(State(state.clone()), headers).await); - assert_eq!( - after.len(), - before.len() - 1, - "软删后 list 长度应少 1" - ); - assert!(!after.iter().any(|row| row["id"] == id.as_str())); -} - -/// Delete 不带 id(解析失败 / 缺失)⇒ **幂等成功**。 -#[tokio::test] -async fn delete_without_id_is_idempotent() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let d = shop::product_delete(State(state.clone()), headers.clone(), query_none()).await; - assert_eq!(d.0.code, 200, "缺 id 必须返回成功: code={}", d.0.code); - assert_eq!(d.0.data, Value::Null); - - let d2 = shop::product_delete(State(state.clone()), headers, query("id=")).await; - assert_eq!(d2.0.code, 200, "空 id 必须返回成功: code={}", d2.0.code); -} - -// ---------------------------------------------------------------- Update - -/// 更新:改 title 后读回是新 title,**body 没给的列保持原值**。 -#[tokio::test] -async fn update_overwrites_only_given_fields() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-更新-1"; - let new_title = "it-更新-1-改"; - db.exec(&format!( - "DELETE FROM shop_product WHERE f_title IN ('{title}', '{new_title}')" - )) - .await - .expect("清理失败"); - - let r = shop::product_save( - State(state.clone()), - headers.clone(), - Bytes::from(json!({"title": title, "price": "12.34"}).to_string()), - ) - .await; - let data = data_obj(&r); - let id = data["id"].as_str().expect("id").to_string(); - - let r2 = shop::product_save( - State(state.clone()), - headers.clone(), - Bytes::from(json!({"id": id, "title": new_title}).to_string()), - ) - .await; - let data2 = data_obj(&r2); - - assert_eq!(data2["id"], id.as_str(), "id 不得变"); - assert_eq!(data2["title"], new_title, "title 必须被覆盖"); - // 🔴 body 没给 price ⇒ **保持原值**(`Object.assign` 语义)。 - assert_eq!(data2["price"], "12.34", "price 必须保持原值"); - assert_eq!(data2["creatorTime"], data["creatorTime"], "creatorTime 不得被改"); -} - -// ---------------------------------------------------------------- 路径 2 - -/// 路径 2:body 有 id 但库里没这行 ⇒ **用该 id 新建**,**不加任何默认值**。 -/// -/// 🔴 `f_creator_time` ⇒ NULL、`f_status` ⇒ NULL、`f_delete_mark` ⇒ 0。 -#[tokio::test] -async fn unknown_id_creates_row_without_defaults() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let given_id = "it-missing-demo-id-1"; - db.exec(&format!("DELETE FROM demo_item WHERE f_id = '{given_id}'")) - .await - .expect("清理失败"); - - let r = demo::demo_item_save( - State(state.clone()), - headers, - Bytes::from(json!({"id": given_id, "title": "it-路径2-1"}).to_string()), - ) - .await; - let data = data_obj(&r); - - assert_eq!(data["id"], given_id, "必须用 body 给的 id"); - assert_eq!(data["title"], "it-路径2-1"); - // 🔴 路径 2 **一个默认值都不加**。 - assert_eq!(data["status"], Value::Null, "status 必须是 null"); - assert_eq!(data["creatorTime"], Value::Null, "creatorTime 必须是 null"); - assert_eq!(data["creatorUserId"], Value::Null, "creatorUserId 必须是 null"); - // 🔴 `f_delete_mark` 由 DDL 的 `DEFAULT 0` 补出 ⇒ 0(不是 NULL)。 - assert_eq!(data["deleteMark"], 0, "deleteMark 必须是 0"); -} - -/// 路径 2(Book):`f_stock` 由 DDL 的 `DEFAULT 0` 补出 ⇒ **0**(不是 NULL)。 -#[tokio::test] -async fn unknown_id_book_stock_is_zero_by_db_default() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let given_id = "it-missing-book-id-1"; - db.exec(&format!("DELETE FROM book_shop_book WHERE f_id = '{given_id}'")) - .await - .expect("清理失败"); - - let r = books::book_save( - State(state.clone()), - headers, - Bytes::from(json!({"id": given_id}).to_string()), - ) - .await; - let data = data_obj(&r); - - assert_eq!(data["id"], given_id); - assert_eq!(data["stock"], 0, "stock 必须是 DB 默认值补出的 0"); - assert_eq!(data["price"], Value::Null, "price 必须是 null(不是 0.00)"); - assert_eq!(data["creatorTime"], Value::Null); - assert_eq!(data["deleteMark"], 0); -} - -/// 路径 2 的 Price:Product 不给 price ⇒ **NULL**(不是 `'0.00'`)。 -#[tokio::test] -async fn unknown_id_product_price_is_null() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let given_id = "it-missing-product-id-1"; - db.exec(&format!("DELETE FROM shop_product WHERE f_id = '{given_id}'")) - .await - .expect("清理失败"); - - let r = shop::product_save( - State(state.clone()), - headers, - Bytes::from(json!({"id": given_id}).to_string()), - ) - .await; - let data = data_obj(&r); - assert_eq!(data["price"], Value::Null, "路径 2 的 price 必须是 null"); - assert_eq!(data["deleteMark"], 0); -} - -// ---------------------------------------------------------------- 守卫与错误 - -/// 未登录 ⇒ `code=600`(HTTP 200 + 信封,不是 401)。 -#[tokio::test] -async fn anonymous_is_rejected_with_600() { - let db = db().await; - let _guard = LOCK.lock().await; - let state = new_state(db); - - let r = shop::product_list(State(state.clone()), anon_headers()).await; - assert_eq!(r.0.code, 600, "未登录必须是 600: code={}", r.0.code); - assert_eq!(r.0.data, Value::Null); - - let r2 = demo::demo_item_list(State(state), anon_headers()).await; - assert_eq!(r2.code, 600); -} - -/// 非管理员没授权 ⇒ `code=403`(菜单 `shop/Product` **真的**拦人)。 -#[tokio::test] -async fn non_admin_without_menu_permission_gets_403() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = plain_user_state(db).await; - - let r = shop::product_list(State(state.clone()), headers.clone()).await; - assert_eq!(r.0.code, 403, "无菜单权限必须是 403: code={}", r.0.code); - assert_eq!(r.0.data, Value::Null); - - // 🔴 demo 只有「登录」守卫 ⇒ 非管理员**可以**访问。 - let r2 = demo::demo_item_list(State(state), headers).await; - assert_eq!(r2.0.code, 200, "demo 仅需登录: code={}", r2.0.code); -} - -/// body 解析失败 ⇒ `code=400` + `请求参数格式错误`(不是 axum 的 422 文本)。 -#[tokio::test] -async fn malformed_body_is_a_business_error() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let r = shop::product_save( - State(state.clone()), - headers.clone(), - Bytes::from_static(b"{not json"), - ) - .await; - assert_eq!(r.0.code, 400, "解析失败必须是 400: code={}", r.0.code); - assert_eq!(r.0.msg, "请求参数格式错误"); - assert_eq!(r.0.data, Value::Null); - - let r2 = books::book_save( - State(state), - headers, - Bytes::from_static(b"{not json"), - ) - .await; - assert_eq!(r2.0.code, 400); - assert_eq!(r2.0.msg, "请求参数格式错误"); -} - -/// body 里**不属于该实体列集**的键一律忽略(不报错)。 -#[tokio::test] -async fn unknown_body_keys_are_ignored() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-忽略键-1"; - db.exec(&format!("DELETE FROM demo_item WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - let r = demo::demo_item_save( - State(state.clone()), - headers, - Bytes::from(json!({"title": title, "notAColumn": "x", "idOfOther": 1}).to_string()), - ) - .await; - let data = data_obj(&r); - assert_eq!(data["title"], title); - assert!(data.get("notAColumn").is_none()); - assert!(data.get("idOfOther").is_none()); -} - -/// 空 body(`{}`)⇒ 走路径 1(新建),不报错。 -#[tokio::test] -async fn empty_body_creates_a_row() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let r = demo::demo_item_save( - State(state.clone()), - headers, - Bytes::from_static(b"{}"), - ) - .await; - let data = data_obj(&r); - assert_eq!(data["id"].as_str().unwrap().len(), 36); - assert_eq!(data["status"], "草稿"); - assert_eq!(data["title"], Value::Null); -} - -/// `id` 为空串 ⇒ **无 id**(走路径 1 新建),不是「更新一条 id='' 的行」。 -#[tokio::test] -async fn empty_string_id_is_treated_as_no_id() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let r = demo::demo_item_save( - State(state.clone()), - headers, - Bytes::from(json!({"id": "", "title": "it-空id-1"}).to_string()), - ) - .await; - let data = data_obj(&r); - assert_eq!(data["id"].as_str().unwrap().len(), 36, "空 id 必须新建"); - assert_eq!(data["title"], "it-空id-1"); -} - -/// `id` 是数字 ⇒ **有 id**(按 JSON 文本去查)⇒ 查不到 ⇒ 路径 2(用该 id 新建)。 -#[tokio::test] -async fn numeric_id_is_treated_as_an_id() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - db.exec("DELETE FROM demo_item WHERE f_id = '12345'") - .await - .expect("清理失败"); - - let r = demo::demo_item_save( - State(state.clone()), - headers, - Bytes::from(json!({"id": 12345, "title": "it-数字id-1"}).to_string()), - ) - .await; - let data = data_obj(&r); - assert_eq!(data["id"], "12345", "数字 id 必须按文本落库"); - assert_eq!(data["title"], "it-数字id-1"); -} - -/// 路径 1 的 JS `??` 语义:body 里**显式 null** ⇒ 回落 spec 的默认值 -/// (`status ?? '草稿'` / `price ?? '0.00'`)。 -#[tokio::test] -async fn explicit_null_falls_back_to_defaults_in_path_1() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let demo_title = "it-null-默认-1"; - let product_title = "it-null-默认-2"; - db.exec(&format!( - "DELETE FROM demo_item WHERE f_title = '{demo_title}'; \ - DELETE FROM shop_product WHERE f_title = '{product_title}'" - )) - .await - .expect("清理失败"); - - let d = demo::demo_item_save( - State(state.clone()), - headers.clone(), - Bytes::from(json!({"title": demo_title, "status": Value::Null}).to_string()), - ) - .await; - assert_eq!(data_obj(&d)["status"], "草稿", "null status 必须回落默认值"); - - let p = shop::product_save( - State(state.clone()), - headers.clone(), - Bytes::from( - json!({"title": product_title, "price": Value::Null, "creatorUserId": Value::Null}) - .to_string(), - ), - ) - .await; - let data = data_obj(&p); - assert_eq!(data["price"], "0.00", "null price 必须回落默认值"); - assert_eq!(data["creatorUserId"], "admin", "null creatorUserId 必须回落 admin"); -} - -/// 路径 1 的 JS `||` 语义:`creatorUserId` 是**空串** ⇒ 回落 `'admin'`。 -#[tokio::test] -async fn empty_creator_user_id_falls_back_to_admin() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-空creator-1"; - db.exec(&format!("DELETE FROM shop_product WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - let p = shop::product_save( - State(state.clone()), - headers, - Bytes::from(json!({"title": title, "creatorUserId": ""}).to_string()), - ) - .await; - assert_eq!(data_obj(&p)["creatorUserId"], "admin"); -} - -/// List 的行键名必须是契约的 camelCase(`title` / `price` / `creatorTime` …)。 -#[tokio::test] -async fn list_rows_use_contract_json_keys() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-键名-1"; - db.exec(&format!("DELETE FROM book_shop_book WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - let saved = books::book_save( - State(state.clone()), - headers.clone(), - Bytes::from(json!({"title": title, "price": "1.00"}).to_string()), - ) - .await; - assert_eq!(saved.0.code, 200, "新建失败: code={}", saved.0.code); - - let rows = data_arr(&books::book_list(State(state), headers).await); - let row = rows - .iter() - .find(|r| r["title"] == title) - .expect("刚建的行必须在 list 里"); - for key in [ - "id", - "title", - "author", - "isbn", - "category", - "price", - "stock", - "creatorUserId", - "creatorTime", - "deleteMark", - ] { - assert!(row.get(key).is_some(), "缺键 {key}: {row}"); - } -} - -// ---------------------------------------------------------------- 路径 3 - -/// 路径 3:body 有 id、**库里查得到** ⇒ 覆盖更新;`f_creator_time` 在契约 §5.3 的列集内 -/// ⇒ body 给了 `creatorTime` 就**允许被写入**(写入走 `::timestamp` 转换)。 -/// -/// 🔴 react 侧的 `Object.assign(existing, item)` 同样会带上 `creatorTime` ⇒ 两版一致。 -#[tokio::test] -async fn path3_writes_creator_time_and_keeps_other_columns() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-路径3-时间-1"; - db.exec(&format!("DELETE FROM demo_item WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - // ---- 第一轮:先把这一行**真的建出来**(路径 3 的判定是「库里查得到该 id」)---- - // 🔴 第一轮 body 里**显式给 status**(不是 spec 的默认值 `"草稿"`)—— - // 这样第二轮的 status 断言才有鉴别力。 - let r = demo::demo_item_save( - State(state.clone()), - headers.clone(), - Bytes::from(json!({"title": title, "status": "进行中"}).to_string()), - ) - .await; - let first = data_obj(&r); - let id = first["id"].as_str().expect("id 必须是字符串").to_string(); - assert_eq!(first["status"], "进行中", "第一轮必须写成 body 给的 status"); - - // ---- 第二轮:同一个 id + body 里带 creatorTime ⇒ 路径 3 覆盖更新 ---- - let r2 = demo::demo_item_save( - State(state.clone()), - headers.clone(), - Bytes::from(json!({"id": id, "creatorTime": "2026-01-01T00:00:00Z"}).to_string()), - ) - .await; - assert_eq!(r2.0.code, 200, "路径 3 必须成功: code={}", r2.0.code); - let data2 = data_obj(&r2); - - // 🔴 关键断言:读回的 creatorTime == body 给的值。 - assert_eq!( - data2["creatorTime"], "2026-01-01T00:00:00Z", - "creatorTime 必须被写成 body 给的值" - ); - // 🔴 同时断言**其它列没被这一轮改动**(防止本测试退化成「只测 creatorTime 变了」)。 - assert_eq!(data2["id"], id.as_str(), "id 不得变"); - assert_eq!(data2["title"], title, "title 必须保持上一轮的值"); - assert_eq!( - data2["status"], "进行中", - "status 不在第二轮的 body 里 ⇒ 不得被改写(更不得被重置成默认值)" - ); - - // ---- 清理本测试造的那一行(成功路径不留行;断言失败时的残留是「测试失败」的自然结果)---- - db.exec(&format!("DELETE FROM demo_item WHERE f_id = '{id}'")) - .await - .expect("清理失败"); -} - -/// 路径 3 写 **numeric / int 列**的回归测试(复审 M1)。 -/// -/// 🔴 这条是 UPDATE 占位符 `$n::text{cast}` 的**防回归钉子**: -/// 改回 `$n{cast}` ⇒ PG 把参数**推断成** `numeric` / `integer` -/// ⇒ pglite 拿 `Option` 去绑 ⇒ `code=400`(而不是 200)。 -/// 用 `book_shop_book` —— 它同时有 `f_price`(numeric)与 `f_stock`(int)⇒ 一条覆盖两种类型。 -#[tokio::test] -async fn path3_writes_numeric_and_int_columns() { - let db = db().await; - let _guard = LOCK.lock().await; - let (state, headers) = admin_state(db).await; - - let title = "it-路径3-numeric-1"; - db.exec(&format!("DELETE FROM book_shop_book WHERE f_title = '{title}'")) - .await - .expect("清理失败"); - - // ---- 第一轮:建行(专属 title + price)---- - let r = books::book_save( - State(state.clone()), - headers.clone(), - Bytes::from(json!({"title": title, "price": "1.00"}).to_string()), - ) - .await; - let first = data_obj(&r); - let id = first["id"].as_str().expect("id 必须是字符串").to_string(); - assert_eq!(first["price"], "1.00", "第一轮的 price 必须是字符串 1.00"); - - // ---- 第二轮:同一个 id + body 里带 price / stock ⇒ 路径 3 覆盖更新 ---- - let r2 = books::book_save( - State(state.clone()), - headers.clone(), - Bytes::from(json!({"id": id, "price": "9.90", "stock": 100}).to_string()), - ) - .await; - // 🔴 改前这里是 400 ⇒ 这条断言就是那颗钉子。 - assert_eq!(r2.0.code, 200, "路径 3 必须成功: code={}", r2.0.code); - let data2 = data_obj(&r2); - - // 🔴 numeric 列读回恒是**字符串**(投影走 `f_price::text AS "price"`)。 - assert_eq!(data2["price"], "9.90", "price 必须是字符串 9.90"); - assert!(data2["price"].is_string(), "price 必须是 JSON 字符串"); - // 🔴 int 列读回是**数字**(不加 `::text`)。 - assert_eq!(data2["stock"], 100, "stock 必须是数字 100"); - assert!(data2["stock"].is_number(), "stock 必须是 JSON 数字"); - // 🔴 body 没给的列保持原值(这一轮只覆盖 body 里出现的列)。 - assert_eq!(data2["title"], title, "title 必须保持第一轮的值"); - assert_eq!(data2["id"], id.as_str(), "id 不得变"); - - // ---- 清理本测试造的那一行(成功路径不留行)---- - db.exec(&format!("DELETE FROM book_shop_book WHERE f_id = '{id}'")) - .await - .expect("清理失败"); -} diff --git a/crates/tests/tests/db_it.rs b/crates/tests/tests/db_it.rs index 895b321..f7f3f0a 100644 --- a/crates/tests/tests/db_it.rs +++ b/crates/tests/tests/db_it.rs @@ -21,8 +21,10 @@ async fn db() -> &'static Db { .await } -/// 契约 §5.1 的 10 张表。 -const EXPECTED_TABLES: [&str; 10] = [ +/// 🔴 **平台包零业务**(2026-11-04 清理):示例业务表已搬到技能仓, +/// 本仓 `ensure_schema_all()` 只建 `db/schema.sql` 的 177 张平台表。 +/// 这里抽查 7 张**权限链核心表**(原来契约 §5.1 的 10 张减去 3 张示例表)。 +const EXPECTED_TABLES: [&str; 7] = [ "base_authorize", "base_module", "base_organize", @@ -30,16 +32,21 @@ const EXPECTED_TABLES: [&str; 10] = [ "base_role_relation", "base_user", "base_user_relation", +]; + +/// 已迁往技能仓的示例业务表 —— **平台仓里一张都不许有**(防回流)。 +const MOVED_OUT_TABLES: [&str; 4] = [ "demo_item", "shop_product", "book_shop_book", + "asset_data_resource", ]; #[tokio::test] async fn db_schema_and_row_shapes() { let db = db().await; - // ---- 1) ensure_schema 建库(10 张表) ---- + // ---- 1) ensure_schema 建库(平台表) ---- ssw_platform::bootstrap::ensure_schema_all(&db) .await .expect("ensure_schema_all 失败"); @@ -47,7 +54,7 @@ async fn db_schema_and_row_shapes() { // ---- 2) 二次 ensure_schema 幂等(不报错、不重建) ---- db.ensure_schema().await.expect("二次 ensure_schema 失败"); - // ---- 3) 10 张表都存在(查 pg_catalog.pg_tables) ---- + // ---- 3) 平台表都在 / 示例业务表都不在 ---- let rows = db .query_json( "SELECT tablename AS tableName FROM pg_catalog.pg_tables \ @@ -70,44 +77,30 @@ async fn db_schema_and_row_shapes() { "缺表 {t};现有表: {names:?}" ); } + for t in MOVED_OUT_TABLES { + assert!( + !names.iter().any(|n| n == t), + "示例业务表 {t} 回流平台仓 ⇒ 业务应放在业务仓 / 技能仓" + ); + } - // ---- 4) shop_product:f_price = 9.90 ⇒ 读回是**字符串** "9.90" ---- + // ---- 4) numeric ⇒ 读回是**字符串** "9.90" ---- // - // 🔴 参数一律按 text 传(S7):显式 `::text::numeric` 让 PG 把 $3 推断成 TEXT, - // 再由 SQL 自己转成 numeric(否则 PG 会推断成 numeric,`&str` 绑不上去)。 - let product_id = String::from("11111111-1111-4111-8111-111111111111"); - let title = String::from("示例商品"); - let price = String::from("9.90"); - let creator = String::from("user-1"); - let ctime = String::from("2026-01-01 00:00:00"); - let mark = String::from("0"); - let params: [&(dyn ToSql + Sync); 6] = [ - &product_id, - &title, - &price, - &creator, - &ctime, - &mark, - ]; - db.exec_params( - "INSERT INTO shop_product (f_id, f_title, f_price, f_creator_user_id, f_creator_time, f_delete_mark) \ - VALUES ($1::text, $2::text, $3::text::numeric, $4::text, $5::text::timestamp, $6::text::integer)", - ¶ms, - ) - .await - .expect("插入 shop_product 失败"); - - let product_rows = db - .query_json_params( - "SELECT f_id AS id, f_title AS title, f_price::text AS price, \ - f_creator_user_id AS creatorUserId, f_delete_mark AS deleteMark \ - FROM shop_product WHERE f_id = $1::text", - &[&product_id], + // 🔴 平台 DDL 里没有 NUMERIC 列(全部是 VARCHAR/INTEGER/TIMESTAMP), + // 所以这条「行形态」断言用常量投影即可 —— 测的是 `query_json` 的 + // **类型序列化**,与具体表无关。零业务后不再造业务夹具。 + // 🔴 两个形态都要钉:原生 numeric ⇒ JSON 数字(9.9,刻度丢失); + // `::text` ⇒ JSON 字符串 "9.90"(刻度保住,业务展示必须用这个)。 + let shape_rows = db + .query_json( + "SELECT 9.90::numeric AS \"numericPrice\", 9.90::numeric::text AS price, \ + 0::integer AS deleteMark, \ + '11111111-1111-4111-8111-111111111111'::text AS id", ) .await - .expect("读回 shop_product 失败"); - assert_eq!(product_rows.len(), 1, "shop_product 应只有 1 行"); - let p = &product_rows[0]; + .expect("读行形态失败"); + assert_eq!(shape_rows.len(), 1); + let p = &shape_rows[0]; assert_eq!( p["price"].as_str(), Some("9.90"), @@ -115,75 +108,48 @@ async fn db_schema_and_row_shapes() { p["price"] ); assert!(p["price"].is_string(), "price 必须是 JSON 字符串"); + assert!( + p["numericPrice"].is_number(), + "原生 numeric 列应是 JSON 数字(刻度会丢),实际: {}", + p["numericPrice"] + ); // int 列保持 JSON 数字 assert_eq!(p["deleteMark"].as_i64(), Some(0)); - // id 是 36 字符 let id = p["id"].as_str().expect("id 必须是字符串"); assert_eq!(id.len(), 36, "id 应为 36 位 UUID,实际: {id}"); - assert_eq!(id, product_id); - // ---- 5) book_shop_book:f_stock = 100 ⇒ 读回是**数字** 100 ---- - let book_id = String::from("22222222-2222-4222-8222-222222222222"); - let author = String::from("作者"); - let isbn = String::from("9780000000000"); - let category = String::from("科技"); - let stock = String::from("100"); - let book_params: [&(dyn ToSql + Sync); 6] = [ - &book_id, - &title, - &author, - &isbn, - &category, - &stock, - ]; + // ---- 5)+6) 平台表 `base_module` 的 DB 默认值 / 可空列 / int 形态 ---- + // + // 🔴 原来用 demo_item + book_shop_book 当夹具;零业务后换成**平台内置表**: + // `f_no_show INTEGER DEFAULT 0`、`f_tenant_id DEFAULT '0' NOT NULL`、 + // `f_type` 无默认值 ⇒ 覆盖「默认值补 0 / 其余不给就是 NULL / int 保持数字」。 + let module_id = String::from("33333333-3333-4333-8333-333333333333"); + let module_name = String::from("平台内置条目"); db.exec_params( - "INSERT INTO book_shop_book (f_id, f_title, f_author, f_isbn, f_category, f_stock) \ - VALUES ($1::text, $2::text, $3::text, $4::text, $5::text, $6::text::integer)", - &book_params, + "INSERT INTO base_module (f_id, f_full_name) VALUES ($1::text, $2::text)", + &[&module_id, &module_name], ) .await - .expect("插入 book_shop_book 失败"); + .expect("插入 base_module 失败"); - let book_rows = db - .query_json( - "SELECT f_id AS id, f_title AS title, f_author AS author, f_isbn AS isbn, \ - f_category AS category, f_price::text AS price, f_stock AS stock \ - FROM book_shop_book WHERE f_id = '22222222-2222-4222-8222-222222222222'", + let module_rows = db + .query_json_params( + "SELECT f_id AS id, f_full_name AS title, f_no_show AS stock, \ + f_type AS status, f_tenant_id AS tenantId, \ + 100::integer AS hundred \ + FROM base_module WHERE f_id = $1::text", + &[&module_id], ) .await - .expect("读回 book_shop_book 失败"); - assert_eq!(book_rows.len(), 1); - let b = &book_rows[0]; - assert_eq!(b["stock"].as_i64(), Some(100), "int 列必须保持 JSON 数字"); - assert!(b["stock"].is_i64(), "stock 必须是 JSON 数字"); - assert_eq!(b["id"].as_str().map(|s| s.len()), Some(36)); - - // ---- 6) DB 默认值:f_delete_mark / f_stock 缺省补 0,其余列不给就是 NULL ---- - let demo_id = String::from("33333333-3333-4333-8333-333333333333"); - let demo_title = String::from("示例条目"); - db.exec_params( - "INSERT INTO demo_item (f_id, f_title) VALUES ($1::text, $2::text)", - &[&demo_id, &demo_title], - ) - .await - .expect("插入 demo_item 失败"); - let demo_rows = db - .query_json( - "SELECT f_id AS id, f_title AS title, f_status AS status, f_delete_mark AS deleteMark \ - FROM demo_item WHERE f_id = '33333333-3333-4333-8333-333333333333'", - ) - .await - .expect("读回 demo_item 失败"); - assert_eq!(demo_rows.len(), 1); - assert_eq!( - demo_rows[0]["deleteMark"].as_i64(), - Some(0), - "f_delete_mark 的 DB 默认值应为 0" - ); - assert!( - demo_rows[0]["status"].is_null(), - "f_status 没有 DB 默认值 ⇒ 必须为 NULL(§7.6 路径 2)" - ); + .expect("读回 base_module 失败"); + assert_eq!(module_rows.len(), 1); + let m = &module_rows[0]; + assert_eq!(m["stock"].as_i64(), Some(0), "INT 默认值 0 应保持 JSON 数字"); + assert!(m["stock"].is_i64(), "stock 必须是 JSON 数字"); + assert_eq!(m["hundred"].as_i64(), Some(100), "INT 列必须保持 JSON 数字"); + assert_eq!(m["tenantId"].as_str(), Some("0"), "tenantId 默认值应为 '0'"); + assert!(m["status"].is_null(), "f_type 没有 DB 默认值 ⇒ 必须为 NULL"); + assert_eq!(m["id"].as_str().map(|s| s.len()), Some(36)); // ---- 7) scalar_text ---- let one = db.scalar_text("SELECT 1::text").await.expect("scalar_text 失败"); @@ -230,14 +196,16 @@ async fn db_schema_and_row_shapes() { // ---- 9) CTE 里的别名**不得**污染外层的键(评审实测过的真实库回归)---- let cte_rows = db - .query_json( - r#"WITH c AS (SELECT 1 AS Title) SELECT f_title AS "title" FROM demo_item"#, + .query_json_params( + r#"WITH c AS (SELECT 1 AS Title) SELECT f_full_name AS "title" + FROM base_module WHERE f_id = $1::text"#, + &[&module_id], ) .await .expect("查 CTE 失败"); assert_eq!(cte_rows.len(), 1); assert_eq!( - cte_rows[0]["title"], "示例条目", + cte_rows[0]["title"], "平台内置条目", "CTE 里的 AS Title 不得把外层的 title 键改成 Title" ); assert!( @@ -296,9 +264,10 @@ async fn scalar_text_rejects_non_text_column() { .await .expect("ensure_schema_all 失败"); - // ⚠️ 选 `SELECT 1::numeric`(**恒有一行**)而不是 `SELECT f_price FROM shop_product`: + // ⚠️ 选 `SELECT 1::numeric`(**恒有一行**)而不是「从某张表取 numeric 列」: // 后者依赖「同文件的另一个测试已插过行」,并发下可能无行 ⇒ 只会得到 Ok(None) // 而测不到「类型错 ⇒ Err」这条路径。类型分派与表无关,用常量最稳。 + // 🔴 平台 DDL 没有 numeric 列,更只能这样测。 let err = db .scalar_text("SELECT 1::numeric") .await diff --git a/crates/tests/tests/pack_smoke_it.rs b/crates/tests/tests/pack_smoke_it.rs index 9e7c7d6..63becbd 100644 --- a/crates/tests/tests/pack_smoke_it.rs +++ b/crates/tests/tests/pack_smoke_it.rs @@ -1,36 +1,19 @@ -//! pack_smoke —— **每个业务包的 List 必须真的应答**(面 A + 面 B)。 +//! pack_smoke —— **平台包零业务的运行时探针**(2026-11-04 清理后)。 //! -//! 🔴 **与 `routes.rs::route_table_is_pinned` 的分工**(两者互补,别合并): +//! 🔴 原来这里是「遍历每个业务包的 List(面 A + 面 B)真应答」的冒烟。 +//! 示例包已整体搬到技能仓 `ssw-jnpf-lite-rust`,本仓没有业务包可遍历, +//! 那条尺子若在空集合上直接放过就变成**假闸门**。本文件改跑三件真事: //! -//! | | 那条 | 这条 | -//! |---|---|---| -//! | 手法 | 静态探针(错方法 ⇒ 405) | 运行时冒烟(登录 ⇒ 查库 ⇒ 出 JSON) | -//! | 证明 | 「**路径注册了**」 | 「**handler 跑得通**」 | +//! 1. **清单恒空**:`ALL_SPECS` / `ALL_ROUTES` / `packs()` 的实体、路由、DDL 全空; +//! 2. **平台链路仍活**:用与生产同一条装配链起服务、登录,打平台面 A 端点 +//! `/api/ssw/sys/User/List` ⇒ 200 + `code=200` + `data` 是数组(证明「不是服务没起来」); +//! 3. **防回流**:4 个示例业务端点逐一真发请求,必须 HTTP 404。 //! -//! 两者之间那段正是**静默失败**的藏身处 —— 以下三种都**不会**红: -//! -//! 1. spec 加了列、DDL 没加 ⇒ 投影 SQL 报错 ⇒ 面 A / 面 B 都返 `code:400` -//! (闸门全绿,浏览器里只是「页面空着」); -//! 2. `module_key` 指向不存在的菜单 ⇒ 守卫返 403(同上); -//! 3. 包路由没 merge 进总路由 ⇒ 面 B 404(`pack_router_or_empty()` 的 -//! `Err(_) => Router::new()` 是**有意**不 panic 的,见 `bootstrap.rs`)。 -//! -//! 🔴 **一个条目都不写死**:全部从 `modules::ALL_SPECS` / `ALL_ROUTES` 与包注册表 -//! **遍历**出来 ⇒ 加一个包**自动**被这条冒烟覆盖,不用改本文件。 -//! 写死清单的冒烟 = 加了包还全绿 = 假闸门(批次 12.5 已踩过: -//! `asset_pack_loads` 那种「写死条数」的断言,加包时第一件事就是去改测试)。 -//! -//! 🔴 **为什么只冒烟 List、不冒烟 Save / Delete**: -//! Save 需要**合法 body**,而 `ColumnSpec` **有意不带类型信息** -//! (只有 `numeric: bool` + `default`)⇒ 造不出对所有包都合法的 body -//! (`VARCHAR` 与 `TIMESTAMP` 在 spec 里长得一模一样)。 -//! 退一步用 `{}` 又要求「业务列全部可空」—— 那是**业务决策**, -//! 平台不该替包作这个规定(`new-pack-gen.py` 的 `--columns` 允许写 `NOT NULL`)。 -//! ⇒ 写 / 删留给各包自己的集成测试(`crud_it.rs` / `batch*_it.rs`); -//! 本条只钉**读路径**,而读路径恰好是「页面空着」这个症状的**全部来源**。 +//! ⇒ 业务包回流平台仓 ⇒ ①③ 立刻红;装配链断了 ⇒ ② 立刻红。 +//! 原「业务包 List 真应答」的冒烟随示例搬到技能仓,在那里继续跑。 //! //! 🔴 pglite-rs 0.2.7 是**进程级全局标志** ⇒ 全文件共用一个临时库; -//! 本文件只有一个测试函数 ⇒ 不需要互斥锁(测试内顺序执行)。 +//! 本文件只有一个测试函数 ⇒ 不需要互斥锁。 use std::path::PathBuf; use std::sync::Arc; @@ -40,7 +23,6 @@ use ssw_platform::bootstrap::{ensure_base, packs}; use ssw_platform::modules::{ALL_ROUTES, ALL_SPECS}; use sspf_core::config::Config; use sspf_core::db::Db; -use sspf_core::route::HttpMethod; use sspf_core::seed::first_seed; use sspf_core::session::{SessionStore, TicketStore}; use sspf_core::state::AppState; @@ -165,93 +147,35 @@ async fn login(port: u16) -> String { .to_string() } -/// 🔴 **每个包的 List 在两个面上都必须真的应答。** -/// -/// 失败时**一次性列出全部坏掉的条目**(不是第一条就中断)—— -/// 加包场景下通常一坏就是一片,逐条重跑才能看全 = 浪费。 +/// 🔴 **平台包零业务:运行时防回流探针**(清单为空 / 平台仍活 / 业务端点全 404)。 #[tokio::test] -async fn every_pack_list_answers_on_both_faces() { +async fn platform_carries_no_business_at_runtime() { let port = serve(new_state(db().await)).await; let token = login(port).await; - // 收集全部问题,最后一起报。 - let mut bad: Vec = Vec::new(); - let mut checked = 0usize; + // ---- ① 生成段与包注册表的清单必须全空 ---- + assert!(ALL_SPECS.is_empty(), "平台包不得携带业务 spec:{ALL_SPECS:?}"); + assert!(ALL_ROUTES.is_empty(), "平台包不得携带业务路由:{ALL_ROUTES:?}"); + let reg = packs().expect("空注册表是合法形态,必须能装载"); + assert!(reg.entities.is_empty(), "平台包不得装载业务实体"); + assert!(reg.routes.is_empty(), "平台包不得装载业务路由"); + assert!(reg.ddls.is_empty(), "平台包不得携带业务 DDL"); + assert!(reg.menus.is_empty(), "平台包不得携带业务菜单"); - // ------------------------------------------------ 面 A(MVP 前端走这条) - assert_eq!( - ALL_ROUTES.len(), - ALL_SPECS.len() * 3, - "ALL_ROUTES 与 ALL_SPECS 必须按「每模块 3 条」配对(两段都是生成段,别手改)" - ); - for (i, spec) in ALL_SPECS.iter().enumerate() { - let path = ALL_ROUTES[i * 3]; - let (status, body) = get(port, path, &token, false).await; - checked += 1; - if status != 200 { - bad.push(format!( - "面 A {}({}/{})状态 {} ≠ 200", - path, spec.app_code, spec.entity, status - )); - } else if body["code"] != 200 { - bad.push(format!( - "面 A {}({}/{})信封 code={} msg={}", - path, spec.app_code, spec.entity, body["code"], body["msg"] - )); - } else if !body["data"].is_array() { - bad.push(format!( - "面 A {}({}/{})data 必须是裸数组,实际 {}", - path, spec.app_code, spec.entity, body["data"] - )); - } + // ---- ② 平台装配链仍活(避免「全空」其实是「服务根本没起来」的假绿)---- + let (status, body) = get(port, "/api/ssw/sys/User/List", &token, false).await; + assert_eq!(status, 200, "平台面 A 端点必须可达,实际 {status}"); + assert_eq!(body["code"], 200, "平台端点信封必须 code=200,实际 {body}"); + assert!(body["data"].is_array(), "平台 List 的 data 必须是裸数组,实际 {body}"); + + // ---- ③ 4 个示例业务端点一律 404(防回流)---- + for path in [ + "/api/ssw/demo/DemoItem/List", + "/api/ssw/shop/Product/List", + "/api/ssw/books/Book/List", + "/api/ssw/asset/DataResource/List", + ] { + let (status, _) = get(port, path, &token, false).await; + assert_eq!(status, 404, "{path} 不应存在(平台零业务)"); } - - // ------------------------------------------------ 面 B(官方前端 / 集成期走这条) - let reg = packs().expect("全部业务包必须装载成功"); - let lists: Vec<&'static str> = reg - .routes - .iter() - .filter(|r| r.method == HttpMethod::Get && !r.path.contains('{')) - .map(|r| r.path) - .collect(); - assert_eq!( - lists.len(), - reg.entities.len(), - "每个实体恰好 1 条面 B 的 List 路由(漏 ⇒ 官方前端列表静默空着);实际 {:?}", - lists - ); - for path in lists { - let (status, body) = get(port, path, &token, true).await; - checked += 1; - if status != 200 { - bad.push(format!("面 B {} 状态 {} ≠ 200", path, status)); - } else if body["code"] != 200 { - bad.push(format!( - "面 B {} 信封 code={} msg={}", - path, body["code"], body["msg"] - )); - } else if !body["data"]["list"].is_array() { - bad.push(format!( - "面 B {} 的 data 必须是 PageListVO(data.list 为数组),实际 {}", - path, body["data"] - )); - } else if body["data"]["pagination"]["total"].is_null() { - bad.push(format!( - "面 B {} 缺 pagination.total(官方前端读它算总数),实际 {}", - path, body["data"]["pagination"] - )); - } - } - - // 空集合是 falsy 的经典陷阱 ⇒ 显式断言「真的检查过东西」。 - assert!( - checked >= 2, - "至少要检查出面 A + 面 B 各一条;实际只检查了 {checked} 条 ⇒ 遍历逻辑坏了" - ); - - assert!( - bad.is_empty(), - "以下包/路由**静默坏了**(静态闸门全绿,但前端只会看到空页面):\n - {}", - bad.join("\n - ") - ); } diff --git a/crates/tests/tests/permission_it.rs b/crates/tests/tests/permission_it.rs index b9209e5..a47f810 100644 --- a/crates/tests/tests/permission_it.rs +++ b/crates/tests/tests/permission_it.rs @@ -35,25 +35,26 @@ async fn db() -> &'static Db { .await } -/// 内置菜单 id(契约 §8.4)。 +/// 🔴 **平台 5 个内置菜单 id**(契约 `[MENU]`,2026-11-04 零业务清理后)。 const M_SYS: &str = "m_sys"; const M_USER: &str = "m_user"; const M_ROLE: &str = "m_role"; const M_ORG: &str = "m_org"; const M_MENU: &str = "m_menu"; -const M_DEMO: &str = "m_demo"; -const M_PRODUCT: &str = "m_product"; -const M_BOOK: &str = "m_book"; -const M_RESOURCE: &str = "m_resource"; + +// `resolve_user_module_ids` 只**合并授权行**,不查菜单表 ⇒ 下面两个 id 是纯合成夹具, +// 不要求对应真实菜单(示例业务菜单已搬到技能仓,本仓不留业务字面量)。 +const M_A: &str = "m_a"; // 用于「被授权」的一侧 +const M_UNUSED: &str = "m_unused"; // 用于「没被任何源授权」的一侧 /// 多应用:本仓的主系统 id(`base_system.f_en_code = 'ssw-platform'`)。 /// 菜单查询按 `f_system_id` 隔离 ⇒ 这些测试里的菜单都属于主系统。 /// 主系统 id —— 🔴 取**平台常量**而不是字面量(主系统 id 改一处就够)。 const SYS: &str = sspf_core::registry::MAIN_SYSTEM_ID; -/// 9 个内置菜单的期望菜单树(契约 §8.4,逐字断言)。 -const EXPECTED_ADMIN_TREE: &str = - "系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:|数据资源:"; +/// 🔴 **平台 5 个内置菜单**的期望树(契约附录 A `[MENU_TREE]`,逐字断言)。 +/// 示例业务菜单(Demo 示例 / 产品管理 / 图书超市 / 数据资源)已随包搬到技能仓。 +const EXPECTED_ADMIN_TREE: &str = "系统管理:用户管理,角色管理,机构管理,菜单管理"; /// 造一条授权行(`base_authorize`),`f_item_type` 可指定。 /// @@ -276,11 +277,11 @@ async fn position_grant_is_merged() { purge(db, uid).await; purge(db, &pid).await; link_user_relation(db, uid, "position", &pid).await; - grant(db, "position", &pid, M_PRODUCT).await; + grant(db, "position", &pid, M_A).await; let ids = resolve_user_module_ids(db, uid).await; assert!( - ids.contains(M_PRODUCT), + ids.contains(M_A), "岗位授权的菜单必须在合并集合里:{ids:?}" ); assert!( @@ -318,7 +319,7 @@ async fn four_sources_are_unioned() { assert!(ids.contains(m), "四源合并后 {m} 必须在集合里:{ids:?}"); } assert!( - !ids.contains(M_DEMO), + !ids.contains(M_UNUSED), "没被任何源授权的菜单不得出现:{ids:?}" ); } @@ -371,7 +372,7 @@ async fn soft_deleted_user_relation_still_counts() { link_user_relation_with_delete_mark(db, uid, "organize", &oid, "1").await; grant(db, "organize", &oid, M_ORG).await; link_user_relation_with_delete_mark(db, uid, "position", &pid, "1").await; - grant(db, "position", &pid, M_PRODUCT).await; + grant(db, "position", &pid, M_A).await; let ids = resolve_user_module_ids(db, uid).await; assert!( @@ -379,7 +380,7 @@ async fn soft_deleted_user_relation_still_counts() { "软删的 base_user_relation(organize)行不过滤 ⇒ 组织授权仍应生效:{ids:?}" ); assert!( - ids.contains(M_PRODUCT), + ids.contains(M_A), "软删的 base_user_relation(position)行不过滤 ⇒ 岗位授权仍应生效:{ids:?}" ); } @@ -556,7 +557,7 @@ async fn restore_base_module(db: &Db) { } // ---- 菜单树 ---- -/// 管理员看全部 8 个内置菜单 ⇒ 树形字符串逐字相等(契约 §8.4)。 +/// 管理员看全部 5 个平台内置菜单 ⇒ 树形字符串逐字相等(契约 `[MENU_TREE]`)。 #[tokio::test] async fn admin_menu_tree_matches_contract_string() { let db = db().await; @@ -574,7 +575,7 @@ async fn admin_menu_tree_matches_contract_string() { ); } -/// 非管理员只授权 `m_demo` ⇒ 菜单树 == `Demo 示例:`。 +/// 非管理员只授权平台菜单 `m_menu` ⇒ 父不可见,`菜单管理` 自己成为根。 #[tokio::test] async fn non_admin_menu_tree_is_filtered() { let db = db().await; @@ -583,12 +584,12 @@ async fn non_admin_menu_tree_is_filtered() { ensure_base(db).await.expect("ensure_base 失败"); let uid = "perm_it_tree_user"; purge(db, uid).await; - grant(db, "user", uid, M_DEMO).await; + grant(db, "user", uid, M_MENU).await; let roots = build_menu_list(db, uid, 0, SYS).await; assert_eq!( render_tree(&roots), - "Demo 示例:", + "菜单管理:", "非管理员的菜单树必须只含被授权的菜单" ); } @@ -665,8 +666,8 @@ async fn roots_and_children_are_sorted_by_sort_code() { let ids: Vec<&str> = roots.iter().map(|r| r.id.as_str()).collect(); assert_eq!( ids, - vec![M_SYS, M_DEMO, M_PRODUCT, M_BOOK, M_RESOURCE], - "根节点必须按 f_sort_code 升序" + vec![M_SYS], + "零业务后只有 1 个平台根菜单(仍是按 f_sort_code 升序)" ); let kids: Vec<&str> = roots[0].children.iter().map(|c| c.id.as_str()).collect(); assert_eq!( diff --git a/crates/tests/tests/seed_it.rs b/crates/tests/tests/seed_it.rs index 6f045f7..d60b3e4 100644 --- a/crates/tests/tests/seed_it.rs +++ b/crates/tests/tests/seed_it.rs @@ -26,7 +26,9 @@ static LOCK: Mutex<()> = Mutex::const_new(()); /// 🔴 从业务层派生而**不写死数字**:加一个业务模块不用改本测试 /// (写死就等于「加模块要改平台/测试」⇒ 违反「加模块只碰业务层」)。 fn expected_menu_count() -> i64 { - 5 + ssw_platform::modules::ALL_MENUS.len() as i64 + // 🔴 平台包零业务:`ALL_MENUS` 恒空 ⇒ 期望值 = BUILTIN_MENUS 的条数。 + // 仍用「5 条系统菜单 + 业务菜单数」推导,业务一旦回流这里会自动跟着变。 + BUILTIN_MENUS.len() as i64 + ssw_platform::modules::ALL_MENUS.len() as i64 } async fn db() -> &'static Db { @@ -42,20 +44,17 @@ async fn db() -> &'static Db { .await } -/// 内置菜单的期望值(契约 §8.4)—— 逐字照抄那张表。 +/// 🔴 **平台 5 个内置菜单**的期望值(契约附录 A `[MENU]`,2026-11-04 零业务清理后)。 +/// 4 个业务根菜单(Demo 示例 / 产品管理 / 图书超市 / 数据资源)已随示例包搬到技能仓。 /// /// `(id, fullName, parentId, type, sortCode, icon)` /// —— 🔴 `type` 是 **INTEGER**(1=目录 / 2=页面);`icon` 为 `None` ⇒ 期望 **NULL**。 -const BUILTIN_MENUS: [(&str, &str, &str, i64, i64, Option<&str>); 9] = [ +const BUILTIN_MENUS: [(&str, &str, &str, i64, i64, Option<&str>); 5] = [ ("m_sys", "系统管理", "0", 1, 1, Some("setting")), ("m_user", "用户管理", "m_sys", 2, 2, None), ("m_role", "角色管理", "m_sys", 2, 3, None), ("m_org", "机构管理", "m_sys", 2, 4, None), ("m_menu", "菜单管理", "m_sys", 2, 5, None), - ("m_demo", "Demo 示例", "0", 2, 6, Some("app")), - ("m_product", "产品管理", "0", 2, 7, Some("app")), - ("m_book", "图书超市", "0", 2, 8, Some("app")), - ("m_resource", "数据资源", "0", 2, 9, Some("app")), ]; /// 内置角色的期望值(契约 §8.5)—— `(id, enCode, fullName, sortCode)`。 @@ -184,7 +183,7 @@ async fn empty_db_seeds_admin_roles_menus_and_authorizations() { assert_eq!(r["tenantId"], "0"); } - // ---- base_module:8 行内置菜单(§8.4 逐条钉死)---- + // ---- base_module:5 行平台内置菜单(契约 [MENU] 逐条钉死)---- let modules = db .query_json( "SELECT f_id AS \"id\", f_url_address AS \"urlAddress\", \ @@ -199,7 +198,7 @@ async fn empty_db_seeds_admin_roles_menus_and_authorizations() { assert_eq!( modules.len() as i64, expected_menu_count(), - "base_module 行数应 = 5 条系统菜单 + 业务菜单数,实际 {}", + "base_module 行数应 = 平台菜单 + 业务菜单数(零业务时应为 5),实际 {}", modules.len() ); for (i, (id, full_name, parent_id, menu_type, sort_code, icon)) in diff --git a/docs/README-project.md b/docs/README-project.md deleted file mode 100644 index 91189c8..0000000 --- a/docs/README-project.md +++ /dev/null @@ -1,154 +0,0 @@ -# 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` 遇畸形百分号编码** ⇒ **实测 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(逐字复用) diff --git a/docs/SSPF-PLATFORM-PACKAGE.md b/docs/SSPF-PLATFORM-PACKAGE.md index eb4fbca..592aaef 100644 --- a/docs/SSPF-PLATFORM-PACKAGE.md +++ b/docs/SSPF-PLATFORM-PACKAGE.md @@ -8,6 +8,10 @@ > 与原稿的三处**有意偏离**见 §10。 > > 适用范围:本仓(`ssw-platform`)。本轮**不碰 tdc-rs 代码**,也不改面 A / 面 B 的任何对外行为。 +> +> ⚠️ 本稿 §2–§6 的「现状」行号是 **v0.2.0 交付前**的快照。2026-11-04 的零业务清理 +> 已把 `packs/` 与 `modules/*.rs` 搬到技能仓,这几处源码的行号与结构均已变化 ⇒ +> 引文改为**不带行号的路径**(保留文件级定位,不再对失效的旧行号做核对)。 > 结论先行:sspf 已有的平台能力(面 B 全套、`base_*` 181 张表、cipher、602 码、704 测试)都不用重做, > **缺的只有一层「可被外部仓依赖 + 可被业务仓装配」的门面**。 @@ -73,7 +77,7 @@ sspf::Platform::new() 独立 TDC 节点为自闭环引的是**全量 JNPF jar** ⇒ 面 B 全套平台能力要随平台包一起进业务二进制。 **C4 · 平台包里零业务。** -`ssw_platform` 现在编译期依赖 `packs/{asset,demo,shop,books}`(`src/backend/Cargo.toml:81-84`) +`ssw_platform` 现在编译期依赖 `packs/{asset,demo,shop,books}`(`src/backend/Cargo.toml`(生成段)) + `modules/mod.rs` 生成段。业务仓一依赖门面就会被拖进四个示例包 ⇒ 改为 **builder 注入**。 默认 feature 下 `cargo tree -p sspf | grep sspf-pack` 必须**无输出**;这正是 AR9 想要的终局。 @@ -177,11 +181,11 @@ libc = { workspace = true } | 文件 | 现状 | P0 改法 | |---|---|---| -| `src/backend/Cargo.toml:76-85` | 生成段写死 4 个 `sspf-pack-*` 依赖 | 改为 `optional = true` + `[features] example-packs = [...]`;**同步改 `scripts/pack-sync.py`**,否则下次生成会覆盖回去 | -| `src/backend/src/packs_gen.rs:22-62` | `registry()` 硬编码 4 次 `load_static` | 提供 `registry_from(Vec)`;`registry()` 在 `#[cfg(feature="example-packs")]` 下才装 4 包,否则返回空注册表 | -| `src/backend/src/modules/mod.rs:33-112` | 生成段 `ALL_SPECS/ROUTES/MENUS/router()` | `all_menus()` / `router()` 改为「默认空 + 由 builder 注入」;`modules` 测试里断言 4 个基准模块的用例迁到示例包自身或加 `cfg`,**别让闸门变假** | -| `src/backend/src/routes.rs:1252, 2522, 2542` | `.merge(modules::router())`、`pack_router_or_empty()` | 新增 `build_app_with(state, extras)` 承载注入;`build_app(state)` 保留为「extras 为空」的薄封装 ⇒ 704 个测试一行不用改 | -| `src/backend/src/bootstrap.rs:86, 177` | `ensure_base(db, modules::all_menus())`、`ensure_schema_all(db)` | 参数化:`ensure_base(db, menus)`、`ensure_schema_all(db, reg, extra_ddls)`;保留旧签名薄封装 | +| `src/backend/Cargo.toml` | 生成段写死 4 个 `sspf-pack-*` 依赖 | 改为 `optional = true` + `[features] example-packs = [...]`;**同步改 `scripts/pack-sync.py`**,否则下次生成会覆盖回去 | +| `src/backend/src/packs_gen.rs` | `registry()` 硬编码 4 次 `load_static` | 提供 `registry_from(Vec)`;`registry()` 在 `#[cfg(feature="example-packs")]` 下才装 4 包,否则返回空注册表 | +| `src/backend/src/modules/mod.rs` | 生成段 `ALL_SPECS/ROUTES/MENUS/router()` | `all_menus()` / `router()` 改为「默认空 + 由 builder 注入」;`modules` 测试里断言 4 个基准模块的用例迁到示例包自身或加 `cfg`,**别让闸门变假** | +| `src/backend/src/routes.rs` | `.merge(modules::router())`、`pack_router_or_empty()` | 新增 `build_app_with(state, extras)` 承载注入;`build_app(state)` 保留为「extras 为空」的薄封装 ⇒ 704 个测试一行不用改 | +| `src/backend/src/bootstrap.rs` | `ensure_base(db, modules::all_menus())`、`ensure_schema_all(db)` | 参数化:`ensure_base(db, menus)`、`ensure_schema_all(db, reg, extra_ddls)`;保留旧签名薄封装 | | `crates/sspf-admin/src/main.rs:1-46` | `run()` 含全部进程级动作 | 抽到 `sspf::runtime::serve`;本文件只留 CLI(实施后 381 行,启动动作见 `crates/sspf/src/platform.rs:251`) | | `crates/tests/tests/` | 37 个集成测试 | 新增 `external_consumer_it.rs`:只 `use sspf::Platform`,断言①示例包路由/表不存在②面 B 全套仍 200③一个 `Db` 一个端口 | | `scripts/check-arch.sh` | AR1–AR16 + MEM1/2 | 新增 **AR17**(内核默认 feature 下不得编译期依赖 `packs/*`)、**AR18**(门面 crate 不得出现 `tdc` / 业务表名 / 端点字面量);两条都要 `--self-test` 反自证注入 | @@ -355,9 +359,9 @@ lowcode-smoke 15/15、baseline-smoke 10/10、mcp-smoke 14/14; | 事实 | 出处 | |---|---| -| 内核编译期依赖 4 包 | `src/backend/Cargo.toml:76-85`、`src/backend/src/packs_gen.rs:22-62` | -| 业务层清单生成段 | `src/backend/src/modules/mod.rs:33-112` | -| 唯一装配链 / 业务 merge 点 | `src/backend/src/routes.rs:1252, 2522, 2542` | +| 内核编译期依赖 4 包 | `src/backend/Cargo.toml`、`src/backend/src/packs_gen.rs` | +| 业务层清单生成段 | `src/backend/src/modules/mod.rs` | +| 唯一装配链 / 业务 merge 点 | `src/backend/src/routes.rs` | | 两段种子 / 建库 / 包单例 | `src/backend/src/bootstrap.rs:45, 86, 177` | | 进程级 7 步启动 | `crates/sspf/src/platform.rs:251`(`boot` 的 1–6 步)+ `crates/sspf/src/runtime.rs:30`(绑端口 / 停机 / 关库) | | `load_static` 签名 | `crates/sspf-plugin/src/lib.rs:492-517` | diff --git a/docs/contract.md b/docs/contract.md index d19db8a..f870a57 100644 --- a/docs/contract.md +++ b/docs/contract.md @@ -1,10 +1,10 @@ -# 契约规格 —— ssw-jnpf-lite-rust +# 契约规格 —— sspf 标准平台包 > **本文件是唯一规格来源(binding spec)。** 所有实现任务、代码评审、最终评审都以此为准。 > 与 `HANDOFF.md` 冲突时,以本文件为准;与本文件冲突的**计划文字**由控制者裁决并记入 ledger。 > > 🔴 **本文件 = 面 A(ssw/react 契约)的规格,冻结不动。** -> 面 B(官方 JNPF 契约面)的规格在 **[`JNPF_COMPAT_SURFACE.md`](../JNPF_COMPAT_SURFACE.md)**(已落地 18/18), +> 面 B(官方 JNPF 契约面)的规格在 **`JNPF_COMPAT_SURFACE.md`(技能仓 `ssw-jnpf-lite-rust`)**(已落地 18/18), > 两面共用同一套 `base_*` 表 / cipher / seed,但**权限判据不同**(面 A 按菜单路径、面 B 按 `f_en_code`)。 --- @@ -238,6 +238,13 @@ pub fn valid_column(name: &str) -> Option; > 两个方向的依据分开:**写**以**官方 DDL** 为准(本仓的种子会写 `f_creator_user_id` / > `f_creator_time`);**读**以 **react 的 entity 列集**为准(见 §5.3 的投影规则)。 +> 🔴 **2026-11-04 平台包零业务清理**:以下「业务表」段落描述的是**已迁出本仓的示例** +> (demo / shop / books / asset)。本仓 `db/schema.sql` 只有 177 张平台表,构建产物里 +> **没有**这些表、没有对应 spec、没有面 A 端点;示例包与 DDL 的权威副本在技能仓 +> `ssw-jnpf-lite-rust`。本节表格保留为**示例 DDL 规格参考**(技能仓与业务仓要用), +> 不再是对本仓运行时的描述。运行时判据见附录 A `[MODULE]`(恒空)与 +> `[RULER]`(面 A 冒烟的 4 条防回流断言)。 + 业务表 3 张 —— 表名与 react 版同名(两版后端可开同一个库): | 表 | 列 | @@ -1113,34 +1120,14 @@ m_user 用户管理 permission.user system/User m_sys 2 2 m_role 角色管理 permission.role system/Role m_sys 2 3 m_org 机构管理 permission.organize system/Organize m_sys 2 4 m_menu 菜单管理 permission.menu system/Module m_sys 2 5 - - -# 🔴 以下由 `scripts/pack-sync.py` 从 `packs/*` 生成 —— **不许手改** -# (下次同步会被覆盖;改包就够) -m_resource 数据资源 permission.asset.dataResource asset/DataResource 0 2 app 9 -m_book 图书超市 permission.books.book books/Book 0 2 app 8 -m_demo Demo 示例 permission.demo demo-item 0 2 app 6 -m_product 产品管理 permission.shop.product shop/Product 0 2 app 7 - - [MENU_TREE] -系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:|数据资源: +系统管理:用户管理,角色管理,机构管理,菜单管理 [MODULE] # app entity table urlAddress moduleKey menuId apiFile rsFile # moduleKey = 该模块的守卫菜单 key;`None` = 仅需登录(无菜单权限要求) # apiFile = 前端**应不应该**有 `src/frontend/src/api/.ts`(`有` / `无`) # rsFile = 业务模块源文件 `src/backend/src/modules/.rs` - - -# 🔴 以下由 `scripts/pack-sync.py` 从 `packs/*` 生成 —— **不许手改** -# (下次同步会被覆盖;改包就够) -asset DataResource asset_data_resource asset/DataResource asset/DataResource m_resource 有 asset.rs -books Book book_shop_book books/Book books/Book m_book 有 books.rs -demo DemoItem demo_item demo-item None m_demo 无 demo.rs -shop Product shop_product shop/Product shop/Product m_product 有 shop.rs - - [ENDPOINT] # face method path guard owner # face = A(面A 专属) / B(面B 专属) / AB(两面共用,按判别头 `Vue-Version: 3` 分流) @@ -2189,40 +2176,10 @@ B GET /api/blade-visual/record/detail onlineDev.dataScreen platform B POST /api/blade-visual/record/save onlineDev.dataScreen platform B POST /api/blade-visual/record/update onlineDev.dataScreen platform B POST /api/blade-visual/record/remove onlineDev.dataScreen platform - - -# 🔴 以下由 `scripts/pack-sync.py` 从 `packs/*` 生成 —— **不许手改** -# (下次同步会被覆盖;改包就够) -A GET /api/ssw/asset/DataResource/List asset/DataResource asset -A POST /api/ssw/asset/DataResource/Save asset/DataResource asset -A DELETE /api/ssw/asset/DataResource/Delete asset/DataResource asset -A GET /api/ssw/books/Book/List books/Book books -A POST /api/ssw/books/Book/Save books/Book books -A DELETE /api/ssw/books/Book/Delete books/Book books -A GET /api/ssw/demo/DemoItem/List 登录 demo -A POST /api/ssw/demo/DemoItem/Save 登录 demo -A DELETE /api/ssw/demo/DemoItem/Delete 登录 demo -A GET /api/ssw/shop/Product/List shop/Product shop -A POST /api/ssw/shop/Product/Save shop/Product shop -A DELETE /api/ssw/shop/Product/Delete shop/Product shop -B GET /api/asset/DataResource permission.asset.dataResource asset -B POST /api/asset/DataResource permission.asset.dataResource asset -B DELETE /api/asset/DataResource/{id} permission.asset.dataResource asset -B GET /api/books/Book permission.books.book books -B POST /api/books/Book permission.books.book books -B DELETE /api/books/Book/{id} permission.books.book books -B GET /api/demo/DemoItem 登录 demo -B POST /api/demo/DemoItem 登录 demo -B DELETE /api/demo/DemoItem/{id} 登录 demo -B GET /api/shop/Product permission.shop.product shop -B POST /api/shop/Product permission.shop.product shop -B DELETE /api/shop/Product/{id} permission.shop.product shop - - [FACE] # face 条数 说明 -A 28 面 A 专属(+ 2 条共用 ⇒ 面 A 合计 30 条) -B 1019 面 B 专属(官方 JNPF 形状;批次 13 新增 Area 7 + Variate 7;批次 14 新增数据中心 29;批次 15 新增系统服务 39;批次 16 新增权限关系 26;批次 17 新增 onlineDev 78 + Report 23;批次 18 新增 core 22;批次 19 新增 workFlow 104;批次 20 新增 msgCenter 51(前端 50 + 动态路径别名 1);批次 21–23 新增 aiCenter 75 + extend 64 + teamwork 40 + 收尾 4;批次 24 新增官方移动端 40) +A 16 面 A 专属(+ 2 条共用 ⇒ 面 A 合计 30 条) +B 1007 面 B 专属(官方 JNPF 形状;批次 13 新增 Area 7 + Variate 7;批次 14 新增数据中心 29;批次 15 新增系统服务 39;批次 16 新增权限关系 26;批次 17 新增 onlineDev 78 + Report 23;批次 18 新增 core 22;批次 19 新增 workFlow 104;批次 20 新增 msgCenter 51(前端 50 + 动态路径别名 1);批次 21–23 新增 aiCenter 75 + extend 64 + teamwork 40 + 收尾 4;批次 24 新增官方移动端 40) AB 2 两面共用(CurrentUser / Authority Data —— 按判别头分流) [OFFICIAL] @@ -3285,19 +3242,18 @@ POST /api/blade-visual/record/remove implemented VisualRecordController.java:111 [RULER] # name 期望断言数(尺子**自己**断言的条数;跑出来的条数对不上 ⇒ 失败) -# 43 = react 版对齐的 32 条 + 真实业务模块 asset/DataResource 9 条 + 多应用 2 条 -# (无 App-Code ⇒ 主系统 / App-Code: app-b ⇒ app-b) -perm-smoke.sh 43 +# 🔴 21 = 平台权限闭环 17 条 + 防回流 4 条(2026-11-04 零业务清理)。 +# 原 43 条里的 25 条示例业务 CRUD 已随示例包搬到技能仓;本尺子保留 +# 登录/token/菜单树/授权/多应用/404,另逐一断言 4 个面 A 业务前缀恒 404。 +perm-smoke.sh 21 # 23 = 原 18 条 + 多应用 1 条(App-Code: app-b ⇒ currentSystemId = app-b,与面 A 同一口径) # + 用户 CRUD 4 条(详情无口令 / 改档只 SET 出现的键 / 批量启停 + 软删) perm-smoke-jnpf.sh 23 -# 🔴 **本仓现在有前端**(批次 12 起 `src/frontend` = React MVP 模板, -# 见 HANDOFF §0-ter)⇒ check-module 的前端接触点从 `⏭` 变成**真检查**,条数随之增加: -# 123 = demo 31 + shop 30 + books 30 + asset 30 + 全局面 A / 面 B 判别头 2 -# 前端那几条的构成:demo 走「view 直连」4 条(契约 apiFile=无,本来就没有 api 层); -# 其余三个走「api 三导出(listX/saveX/deleteX)」3 条 + views 页面 1 条 + App.tsx 路由 1 条。 -# (更早的 114 = 4 模块 × 28 + 2,那时本仓后端-only,前端 4×4 处全打 `⏭` 但仍计入条数。) -check-module.sh 123 +# 🔴 3 = 平台包零业务的**防回流三条**(2026-11-04 清理): +# `packs/` 不存在 / `modules/` 无业务适配器 / 契约 [MODULE] 无数据行。 +# 旧值 123 = 4 个业务模块 × ~30 个接触点;模块搬走后这把尺子改跑防回流分支, +# 分支条件本身即自证([MODULE] 只要出现一行数据就立刻回到 123 条的完整检查)。 +check-module.sh 3 check-boundary.sh 12 check-contract.sh 10 check-citations.sh 4 diff --git a/docs/known-limitations.md b/docs/known-limitations.md index c512c46..e8be551 100644 --- a/docs/known-limitations.md +++ b/docs/known-limitations.md @@ -76,8 +76,8 @@ ## H. 官方 JNPF 对齐(面 B)—— 2026-10-26 > 本节是**「把官方 JNPF 前端跑进本仓」**这条线的已知限制。三份配套文档: -> 官方源码核对 [`JNPF_SOURCE_AUDIT.md`](../JNPF_SOURCE_AUDIT.md) · 面 B 规格 -> [`JNPF_COMPAT_SURFACE.md`](../JNPF_COMPAT_SURFACE.md) · 迁移指南 [`MIGRATION.md`](../MIGRATION.md)。 +> 官方源码核对 `JNPF_SOURCE_AUDIT.md`(技能仓 `ssw-jnpf-lite-rust`) · 面 B 规格 +> `JNPF_COMPAT_SURFACE.md`(技能仓 `ssw-jnpf-lite-rust`) · 迁移指南 `MIGRATION.md`(技能仓 `ssw-jnpf-lite-rust`)。 | # | 限制 | 出处 | 为什么接受 / 代价 | |---|---|---|---| diff --git a/packs/asset/Cargo.toml b/packs/asset/Cargo.toml deleted file mode 100644 index 6ce6f78..0000000 --- a/packs/asset/Cargo.toml +++ /dev/null @@ -1,11 +0,0 @@ -[package] -name = "sspf-pack-asset" -version.workspace = true -edition.workspace = true -rust-version.workspace = true - -# 🔴 AR2:业务包只允许依赖 sspf-sdk(+ serde)。 -# 出现 axum / tokio / pglite ⇒ `check-arch.sh` 直接红。 -# 这是「整目录可搬走」的技术保证。 -[dependencies] -sspf-sdk = { path = "../../crates/sspf-sdk" } diff --git a/packs/asset/pack.toml b/packs/asset/pack.toml deleted file mode 100644 index daeaf3a..0000000 --- a/packs/asset/pack.toml +++ /dev/null @@ -1,37 +0,0 @@ -# 业务包清单 —— 与 `PLAN.md` §5.1 的格式一致。 -# 🔴 本文件不是给 cargo 读的,是给 `sspf pack export/import` 与内核装载器读的。 - -[pack] -app_code = "asset" -name = "数据资源" -version = "1.0.0" -kernel = ">=0.4,<0.5" # 内核兼容区间(不匹配则拒载) -migratable = true # 允许导出到基线平台 - -[pack.compat] -baseline = "v7" # 兼容基线版本 -frontend = "vue3" # 前端族(决定表单 JSON 方言) -tenant = false # 本期单租户 - -# 物理表:name = 本平台表名;baseline_table = 基线平台上的表名(允许不同,导出时映射) -[[pack.tables]] -name = "asset_data_resource" -ddl = "schema/001_init.sql" -baseline_table = "asset_data_resource" - -[pack.metadata] -# 低代码元数据(与基线平台 visualdev 同构的 JSON)。 -# P2 落地后这里会指向真实文件;现在留空表示「纯手写 spec,无元数据」。 -forms = [] -models = [] -menus = [] -flows = [] - -[pack.build] -# 纯元数据包(L0)⇒ 无 Rust 代码,不需要编译。 -# 若将来加 src/ 手写逻辑:kind = "static"(链进内核,编 30s); -# 要热插拔:kind = "dylib"(独立 .dylib,运行期装载)。 -# -# 🔴 kind 不是 "none" 时必须补 `toolchain = "1.95.0"`,且与 rust-toolchain.toml 一致。 -# 内核启动会校验 ABI 版本 + rustc 版本 + panic 策略,三者全对才装载(PLAN.md §4.5 铁律 4)。 -kind = "none" diff --git a/packs/asset/schema/001_init.sql b/packs/asset/schema/001_init.sql deleted file mode 100644 index bc507e2..0000000 --- a/packs/asset/schema/001_init.sql +++ /dev/null @@ -1,37 +0,0 @@ --- asset_data_resource —— 数据资源(业务包自带的 DDL)。 --- --- 🔴 **DDL 跟着包走**(批次 12 交付物 ③):本文件在 `packs/asset/schema/` 下, --- 由 `packs/asset/src/lib.rs` 用 `include_str!` **编译进二进制** --- ⇒ 内核启动时按包顺序幂等执行 ⇒ 不再手抄进 `db/schema.sql`。 --- --- 🔴 **【集成期友好性】列名按官方规范写**(见官方 --- `jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql` 的 `base_*` 表): --- - `f_id VARCHAR(50)` —— 36 位 UUID(**不要限 32**); --- - `f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL` —— **单租户也不许省**, --- 官方 `base_*` 表全部带它,且参与复合主键 `(f_id, f_tenant_id)`; --- - `f_delete_mark INTEGER DEFAULT 0` —— 软删标记。 --- --- 🔴 **列语义不许自创**:`f_name` / `f_category` / `f_scenario` / `f_provider` --- / `f_format` / `f_scale` / `f_source` / `f_register_time` 取自公司本体 --- `DataResource`(`数据资源`),**列名与列序逐字对齐本体** ⇒ 后续接本体平台 --- 可直接映射,不用改表。 --- --- 🔴 **本文件只许建本包自己的表**,**不许建 `base_*`** —— 平台表的 DDL --- 归 `db/schema.sql` 管(装载器会拦,见 `sspf-plugin` 的 `DdlTouchesBaseTable`)。 - -CREATE TABLE IF NOT EXISTS asset_data_resource ( - f_id VARCHAR(50) NOT NULL, - f_name VARCHAR(200), - f_category VARCHAR(50), - f_scenario VARCHAR(500), - f_provider VARCHAR(200), - f_format VARCHAR(50), - f_scale VARCHAR(50), - f_source VARCHAR(50), - f_register_time TIMESTAMP(0) WITHOUT TIME ZONE, - f_creator_user_id VARCHAR(50), - f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, - f_delete_mark INTEGER DEFAULT 0, - f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, - PRIMARY KEY (f_id, f_tenant_id) -); diff --git a/packs/asset/src/lib.rs b/packs/asset/src/lib.rs deleted file mode 100644 index f83e2fc..0000000 --- a/packs/asset/src/lib.rs +++ /dev/null @@ -1,433 +0,0 @@ -//! asset —— 数据资源业务包(**业务包样板**)。 -//! -//! 🔴 **这个 crate 是 P0 的核心验证物**:它只依赖 `sspf-sdk`, -//! 没有任何 axum / tokio / pglite / 内核代码 —— 却能声明完整的业务: -//! 实体(表 + 列 + 类型)、菜单、权限编码。 -//! -//! ⇒ 证明「业务包与平台剥离、可整目录搬走」在**依赖层面**成立。 -//! -//! ## 字段来源 -//! -//! 取自公司本体 `DataResource`(`数据资源`):名称 / 类别 / 应用场景 / 提供方 / -//! 格式 / 规模 / 来源 / 登记时间。**列名与列序逐字对齐本体** ⇒ 后续接本体平台 -//! 可直接映射,不用改表。 -//! -//! ## 与内核的接线 -//! -//! 内核侧只需一行: -//! ```ignore -//! let packs: Vec> = vec![Box::new(sspf_pack_asset::Pack)]; -//! ``` -//! -//! 🔴 **spec 的单一真源就是本文件**(批次 12 交付物 ②)—— -//! 内核的 `src/backend/src/modules/asset.rs` 只做 `pub use` 转发, -//! 不再保留第二份拷贝 ⇒ 改 spec 只改一处。 -//! -//! 🔴 **路由用官方 JNPF 形状**(`/api/{模块}/{资源}/…`)—— -//! **不是**面 A 的 `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}` -//! (那是本仓自造的 ssw 约定 ⇒ 集成到官方 JNPF 时**全部作废**)。 -//! -//! 🔴 **DDL 跟着包走**(批次 12 交付物 ③)—— -//! `schema/001_init.sql` 用 `include_str!` **编译进二进制**, -//! 内核启动时按包顺序幂等执行 ⇒ 不再手抄进 `db/schema.sql`。 - -use sspf_sdk::{ - BusinessPack, ColumnSpec, EntitySpec, HttpMethod, Manifest, MenuSpec, PackRoute, RouteAction, - RouteGuard, -}; - -/// 🔴 **本包自带的 DDL**(编译进二进制 ⇒ 包目录可整目录搬走)。 -/// -/// 🔴 **含 `f_tenant_id`** —— 官方 `base_*` 表全部带它(`DEFAULT '0' NOT NULL` -/// 且参与复合主键 `(f_id, f_tenant_id)`),**单租户也不许省** -/// (集成时缺这一列 ⇒ 导不进官方)。 -pub const DATA_RESOURCE_DDL: &str = include_str!("../schema/001_init.sql"); - -/// 🔴 **包的统一 DDL 出口**(`表名 → DDL 文本`)—— 内核**只认这一种写法**。 -/// -/// 🔴 **为什么要有它**(批次 12.5): -/// 内核要把「每个包的 DDL」交给装载器(`sspf_plugin::PackDdl`), -/// 而 `include_str!` 的结果是**常量名**(本包叫 `DATA_RESOURCE_DDL`)。 -/// 若每个包的常量名都不同,内核就必须**逐包手写**「哪个常量对应哪张表」 -/// ⇒ 加包要改内核,且漏写只会表现为「表没建」⇒ **运行期才炸**。 -/// ⇒ 约定本常量:**名字固定、形状固定** ⇒ 内核/生成器可以无脑遍历。 -/// -/// 🔴 **为什么是 `&[(&str, &str)]` 而不是 `&[PackDdl]`**: -/// `PackDdl.sql` 是 `String`(运行期构造)⇒ 常量数组装不下; -/// 这里用 `&'static str` 对,由 `sspf_plugin::load_static` 在装载时转成 `PackDdl`。 -pub const DDLS: &[(&str, &str)] = &[("asset_data_resource", DATA_RESOURCE_DDL)]; - -/// `asset_data_resource` 的列清单(**顺序 = 响应 JSON 的键序**)。 -const DATA_RESOURCE_COLUMNS: &[ColumnSpec] = &[ - ColumnSpec { column: "f_id", json_key: "id", default: None, numeric: false }, - ColumnSpec { column: "f_name", json_key: "name", default: None, numeric: false }, - ColumnSpec { column: "f_category", json_key: "category", default: None, numeric: false }, - ColumnSpec { column: "f_scenario", json_key: "scenario", default: None, numeric: false }, - ColumnSpec { column: "f_provider", json_key: "provider", default: None, numeric: false }, - ColumnSpec { column: "f_format", json_key: "format", default: None, numeric: false }, - ColumnSpec { column: "f_scale", json_key: "scale", default: None, numeric: false }, - ColumnSpec { column: "f_source", json_key: "source", default: None, numeric: false }, - ColumnSpec { column: "f_register_time", json_key: "registerTime", default: None, numeric: false }, - ColumnSpec { column: "f_creator_user_id", json_key: "creatorUserId", default: None, numeric: false }, - ColumnSpec { column: "f_creator_time", json_key: "creatorTime", default: None, numeric: false }, - ColumnSpec { column: "f_delete_mark", json_key: "deleteMark", default: Some("0"), numeric: false }, - // 🔴 **【集成期友好性】`f_tenant_id` 不许省** —— 官方 `base_*` 表全部带它 - // (`VARCHAR(50) DEFAULT '0' NOT NULL`,参与复合主键 `(f_id, f_tenant_id)`)。 - // 单租户也不许省 ⇒ 集成时缺这一列 ⇒ **导不进官方**。 - ColumnSpec { column: "f_tenant_id", json_key: "tenantId", default: Some("0"), numeric: false }, -]; - -/// `asset_data_resource` 的 spec。 -pub const DATA_RESOURCE_SPEC: EntitySpec = EntitySpec { - app_code: "asset", - entity: "DataResource", - table: "asset_data_resource", - // 🔴 `module_key` 必须 == 菜单 `url_address` == 前端 Route path(三处一字不差)。 - module_key: Some("asset/DataResource"), - columns: DATA_RESOURCE_COLUMNS, - // 🔴 本体 `数据资源` 没有金额/计量字段 ⇒ 本包**无 numeric 列**。 - numeric_columns: &[], - // 非 demo 表 ⇒ `body.creatorUserId || 'admin'`。 - creator_fixed: None, -}; - -/// 本包的内置菜单。 -/// -/// 🔴 `url_address` 必须与 [`DATA_RESOURCE_SPEC`] 的 `module_key` 一字不差 —— -/// 面 A 的菜单守卫靠它命中。 -pub const DATA_RESOURCE_MENU: MenuSpec = MenuSpec { - id: "m_resource", - full_name: "数据资源", - // 本平台自定编码(基线平台无此模块)⇒ 面 B 的点权限判据 `f_en_code`。 - en_code: "permission.asset.dataResource", - url_address: "asset/DataResource", - parent_id: "0", - menu_type: 2, - icon: Some("app"), - sort_code: 9, - // 🔴 字面量而非引用内核常量:业务包不许依赖内核(AR2)。 - // `mainSystem` 是基线平台的官方常量值,属于**契约字面量**,可以写死。 - system_en_code: "mainSystem", -}; - -/// 包清单(与 `pack.toml` 的 `[pack]` 段一致)。 -const MANIFEST: Manifest = Manifest { - app_code: "asset", - name: "数据资源", - version: "1.0.0", - kernel_req: ">=0.4,<0.5", - migratable: true, -}; - -// ---------------------------------------------------------------- 路由声明 -// -// 🔴 **【集成期友好性】路径必须是官方 JNPF 形状** —— -// 官方是 **RESTful**:`GET/POST /api/{模块}/{资源}` + `PUT/DELETE /api/{模块}/{资源}/{id}`, -// **不是**面 A 的 `/api/ssw/{appCode}/{Entity}/…`,**也不是**第三种「官方前缀 + ssw 动作后缀」 -// (`/api/asset/DataResource/List|Save|Delete`)。 -// -// 🔴 **为什么不能是「官方前缀 + 动作后缀」**(2026-11-02 实测官方源码,证据在下面): -// 扫 `~/Desktop/workspace/jnpf/jnpf-java-boot` 的全部 controller: -// - `/xxx/List` 端点 **GET 52 条 + POST 21 条** ⇒ **这个形状存在**; -// - `/xxx/Save` 端点 **只有 4 条**(低代码 / 打印 / AI 的特例)⇒ **不是 CRUD 通用形状**; -// - `/xxx/Delete` 端点 **0 条** ⇒ **根本不存在**。 -// ⇒ 官方 CRUD 的通用形状是 `GET /api/{模块}/{资源}`(列表) -// + `POST /api/{模块}/{资源}`(新建) -// + `PUT /api/{模块}/{资源}/{id}`(改) -// + `DELETE /api/{模块}/{资源}/{id}`(删)。 -// ⇒ **本包的路径按这个来** ⇒ 集成时**路径零改**(这才是护栏 8 的目的)。 -// -// 🔴 **路由是「声明」,不是 handler** —— `PackRoute` 里没有 axum 类型 -// ⇒ 业务包**不需要**依赖 axum(AR2/AR8 钉死)。 -// 内核按声明 + spec 生成真正的 handler(`platform::crud::crud_router`)。 - -/// `GET /api/asset/DataResource` —— 列表。 -pub const DATA_RESOURCE_LIST_ROUTE: PackRoute = PackRoute { - path: "/api/asset/DataResource", - method: HttpMethod::Get, - entity: "DataResource", - action: RouteAction::List, - // 🔴 **面 B 的判据 = 点权限(`f_en_code`)** —— 官方 `@SaCheckPermission` 的那套。 - // 面 A 的菜单路径(`f_url_address`)是**另一套**判据 ⇒ 两套并存,互不影响。 - guard: RouteGuard::EnCode("permission.asset.dataResource"), -}; - -/// `POST /api/asset/DataResource` —— 新建 / 更新(body 里带 `id` 就是更新)。 -pub const DATA_RESOURCE_SAVE_ROUTE: PackRoute = PackRoute { - path: "/api/asset/DataResource", - method: HttpMethod::Post, - entity: "DataResource", - action: RouteAction::Save, - guard: RouteGuard::EnCode("permission.asset.dataResource"), -}; - -/// `DELETE /api/asset/DataResource/{id}` —— 软删。 -pub const DATA_RESOURCE_DELETE_ROUTE: PackRoute = PackRoute { - path: "/api/asset/DataResource/{id}", - method: HttpMethod::Delete, - entity: "DataResource", - action: RouteAction::Delete, - guard: RouteGuard::EnCode("permission.asset.dataResource"), -}; - -/// 本包声明的全部路由。 -pub const DATA_RESOURCE_ROUTES: &[PackRoute] = &[ - DATA_RESOURCE_LIST_ROUTE, - DATA_RESOURCE_SAVE_ROUTE, - DATA_RESOURCE_DELETE_ROUTE, -]; - -/// 数据资源业务包。 -/// -/// 🔴 **类型名固定为 `Pack`**(批次 12.5)—— 内核的 `src/backend/src/packs_gen.rs` -/// 是**生成**的,生成器按 `sspf_pack_::Pack` 拼路径 -/// ⇒ 每个包都用同一个名字,加包才不用改内核。 -pub struct Pack; - -impl BusinessPack for Pack { - fn manifest(&self) -> &'static Manifest { - &MANIFEST - } - - fn entities(&self) -> &'static [EntitySpec] { - &[DATA_RESOURCE_SPEC] - } - - fn menus(&self) -> &'static [MenuSpec] { - &[DATA_RESOURCE_MENU] - } - - /// 🔴 **路由声明**(官方形状)—— 内核按它 + spec 生成 handler。 - fn routes(&self) -> &'static [PackRoute] { - DATA_RESOURCE_ROUTES - } - - // metadata() 留空:本包是「手写 spec」形态,没有低代码元数据。 - // P2 之后如果改用表单 JSON 驱动,在这里返回 `&["include_str!(...json)"]` 即可。 -} - -#[cfg(test)] -mod tests { - use super::*; - - /// 🔴 三处一致:`module_key` == `menu.url_address`(第三处是前端 Route,本包管不到)。 - /// 不一致的后果是**静默放行**(菜单未映射 ⇒ 守卫不拦),不会报错。 - #[test] - fn module_key_matches_menu_url_address() { - let spec = &DATA_RESOURCE_SPEC; - assert_eq!(spec.module_key, Some(DATA_RESOURCE_MENU.url_address)); - } - - /// 列名全部 `f_` 前缀,且主键是 `f_id`。 - #[test] - fn columns_are_prefixed_and_have_id() { - assert_eq!(DATA_RESOURCE_COLUMNS[0].column, "f_id"); - for c in DATA_RESOURCE_COLUMNS { - assert!(c.column.starts_with("f_"), "列名必须 f_ 前缀: {}", c.column); - } - } - - /// `json_key` 必须是列名去 `f_` 前缀后的 camelCase(不能机械 snake→camel 猜)。 - #[test] - fn json_keys_are_camel_case_without_prefix() { - for c in DATA_RESOURCE_COLUMNS { - let stripped = c.column.trim_start_matches("f_"); - // 允许的差异只有下划线转驼峰 - let expect: String = { - let mut out = String::new(); - let mut up = false; - for ch in stripped.chars() { - if ch == '_' { - up = true; - } else if up { - out.extend(ch.to_uppercase()); - up = false; - } else { - out.push(ch); - } - } - out - }; - assert_eq!(c.json_key, expect, "json_key 与列名不匹配: {}", c.column); - } - } - - /// numeric 标记与 `numeric_columns` 必须一致(本包两者都空)。 - #[test] - fn numeric_columns_matches_column_flags() { - let flagged: Vec<&str> = DATA_RESOURCE_COLUMNS - .iter() - .filter(|c| c.numeric) - .map(|c| c.column) - .collect(); - assert_eq!(flagged, DATA_RESOURCE_SPEC.numeric_columns); - } - - /// 包清单与 spec 的 app_code 必须一致(否则内核按 app 路由会找不到)。 - #[test] - fn manifest_app_code_matches_spec() { - assert_eq!(Pack.manifest().app_code, DATA_RESOURCE_SPEC.app_code); - assert_eq!(Pack.entities().len(), 1); - assert_eq!(Pack.menus().len(), 1); - assert_eq!(Pack.routes().len(), 3); - } - - /// 🔴 **【集成期友好性】路由必须是官方形状** —— 面 A 的 `/api/ssw/...` - /// 在集成到官方 JNPF 时**全部作废** ⇒ 这里钉死。 - #[test] - fn routes_use_official_shape_not_face_a() { - for r in Pack.routes() { - assert!( - r.path.starts_with("/api/"), - "路由必须以 /api/ 开头: {}", - r.path - ); - assert!( - !r.path.starts_with("/api/ssw/"), - "🔴 路由不许用面 A 的 /api/ssw/...(集成时作废): {}", - r.path - ); - } - } - - /// 🔴 **路由的 entity 必须指向本包声明的实体** —— 否则装配时拿到空 spec - /// ⇒ 路由注册了但永远查不到表 ⇒ **静默 404**。 - #[test] - fn routes_point_at_declared_entities() { - let entities = Pack.entities(); - for r in Pack.routes() { - assert!( - entities.iter().any(|e| e.entity == r.entity), - "路由 {} 指向未声明的实体 {}", - r.path, - r.entity - ); - } - } - - /// 🔴 **动作与方法的对应**被钉死(内核的 `crud_router` 按这个分派)。 - #[test] - fn route_actions_match_methods() { - for r in Pack.routes() { - match (r.action, r.method) { - (RouteAction::List, HttpMethod::Get) => {} - (RouteAction::Save, HttpMethod::Post) => {} - (RouteAction::Delete, HttpMethod::Delete) => {} - _ => panic!( - "动作 {:?} 与方法 {:?} 的组合不被支持: {}", - r.action, - r.method, - r.path - ), - } - } - } - - /// 🔴 **路径必须是官方 RESTful 形状**(2026-11-02 实测官方源码定下的): - /// - 列表 ⇒ `GET /api/{模块}/{资源}` - /// - 新建 ⇒ `POST /api/{模块}/{资源}` - /// - 删除 ⇒ `DELETE /api/{模块}/{资源}/{id}` - /// - /// 🔴 **为什么 `/Save` + `/Delete` 后缀不许出现**(护栏 8 的真正含义): - /// 实测官方 `jnpf-java-boot` 的全部 controller: - /// `/xxx/List` GET 52 + POST 21(碰巧存在)、`/xxx/Save` **仅 4 条** - /// (低代码/打印/AI 的特例)、`/xxx/Delete` **0 条**(根本不存在)。 - /// ⇒ 用 ssw 动作后缀 = 集成时**必然要改路径** ⇒ 现在就拦。 - #[test] - fn routes_use_official_restful_shape() { - for r in Pack.routes() { - assert!( - !r.path.ends_with("/Save"), - "🔴 官方没有 /Save 这种 CRUD 端点(仅低代码特例): {}", - r.path - ); - assert!( - !r.path.ends_with("/Delete"), - "🔴 官方根本没有 /Delete 端点(0 条): {}", - r.path - ); - } - // 删除必须带 `{id}`(官方 RESTful 的删除是 `DELETE /api/{模块}/{资源}/{id}`)。 - let del = Pack - .routes() - .iter() - .find(|r| r.action == RouteAction::Delete) - .expect("必须有删除路由"); - assert!( - del.path.contains("{id}"), - "删除路由必须带 {{id}} 路径参数: {}", - del.path - ); - } - - /// 🔴 **守卫必须与菜单的 `f_en_code` 一字不差** —— 不一致 ⇒ - /// 运行时查菜单查不到 ⇒ 走「未映射放行」⇒ **任何登录用户都能调** ⇒ 静默越权。 - #[test] - fn route_guards_match_menu_en_code() { - for r in Pack.routes() { - let RouteGuard::EnCode(code) = r.guard else { - panic!("本包的路由都该有点权限守卫: {}", r.path); - }; - assert_eq!( - code, DATA_RESOURCE_MENU.en_code, - "路由 {} 的守卫与菜单的 f_en_code 不一致", - r.path - ); - } - } - - /// 🔴 **DDL 必须含 `f_tenant_id`**(官方 `base_*` 全部带它, - /// 参与复合主键 `(f_id, f_tenant_id)`)—— 集成时缺这列 ⇒ **导不进官方**。 - #[test] - fn ddl_carries_tenant_id() { - assert!(DATA_RESOURCE_DDL.contains("f_tenant_id"), "DDL 必须含 f_tenant_id"); - assert!( - DATA_RESOURCE_DDL.contains("PRIMARY KEY (f_id, f_tenant_id)"), - "复合主键必须是 (f_id, f_tenant_id)" - ); - } - - /// 🔴 **DDL 与 spec 的列必须一致** —— spec 少一列 ⇒ CRUD 投影会漏字段。 - #[test] - fn ddl_columns_match_spec_columns() { - for col in DATA_RESOURCE_SPEC.columns { - assert!( - DATA_RESOURCE_DDL.contains(col.column), - "DDL 缺列 {}(spec 里有,DDL 里没有)", - col.column - ); - } - } - - /// 🔴 **`DDLS` 的每一对都必须是「表名 → 真的建这张表的 SQL」**。 - /// - /// 🔴 写错表名的后果分两级: - /// - 与 `pack.toml` 的 `[[pack.tables]].name` 不一致 ⇒ 装载期报 - /// `DdlWithoutEntity`(响亮); - /// - 但 DDL **文本里**建的是另一张表 ⇒ 装载器不查这个 ⇒ 启动时建出来的表 - /// 与 spec 对不上 ⇒ **业务查询运行期才炸**(`relation does not exist`)。 - /// ⇒ 在包自己这一层就钉死,别指望上层。 - #[test] - fn ddls_pairs_name_the_table_they_create() { - assert!(!DDLS.is_empty(), "本包有实体 ⇒ DDLS 不能为空"); - for (table, sql) in DDLS { - assert!( - sql.contains(&format!("CREATE TABLE IF NOT EXISTS {table}")), - "DDLS 里 {table} 的 DDL 没有建这张表(表名与 SQL 不一致)" - ); - } - } - - /// 🔴 **`DDLS` 覆盖本包全部实体** —— 漏一张 ⇒ 那张表根本没建。 - #[test] - fn ddls_covers_every_entity_table() { - for spec in Pack.entities() { - assert!( - DDLS.iter().any(|(t, _)| *t == spec.table), - "实体 {} 的表 {} 不在 DDLS 里 ⇒ 不会建表", - spec.entity, - spec.table - ); - } - } -} diff --git a/packs/books/Cargo.toml b/packs/books/Cargo.toml deleted file mode 100644 index 25f9b0c..0000000 --- a/packs/books/Cargo.toml +++ /dev/null @@ -1,11 +0,0 @@ -[package] -name = "sspf-pack-books" -version.workspace = true -edition.workspace = true -rust-version.workspace = true - -# 🔴 AR2:业务包只允许依赖 `sspf-sdk`(+ serde)。 -# 出现 axum / tokio / pglite ⇒ `check-arch.sh` 直接红。 -# 这是「整目录可搬走」的技术保证。 -[dependencies] -sspf-sdk = { path = "../../crates/sspf-sdk" } diff --git a/packs/books/pack.toml b/packs/books/pack.toml deleted file mode 100644 index f4bf316..0000000 --- a/packs/books/pack.toml +++ /dev/null @@ -1,31 +0,0 @@ -# 业务包清单 —— **示例包**(可整目录搬走,技能带它当样板)。 -# 🔴 本文件不是给 cargo 读的,是给 `sspf pack export/import` 与内核装载器读的。 - -[pack] -app_code = "books" -name = "图书超市" -version = "1.0.0" -kernel = ">=0.4,<0.5" # 契约版本区间(不是 cargo 版本,见 bootstrap::kernel_version) -migratable = true # 允许导出到基线平台 - -[pack.compat] -baseline = "react-demo" # 对齐基准 -frontend = "vue3" # 前端族(决定表单 JSON 方言) -tenant = false # 本期单租户(列仍带 f_tenant_id,见 DDL 注释) - -# 物理表:name = 本平台表名;baseline_table = 基线平台上的表名(导出时映射) -[[pack.tables]] -name = "book_shop_book" -ddl = "schema/001_init.sql" -baseline_table = "book_shop_book" - -[pack.metadata] -# 低代码元数据(与基线平台 visualdev 同构的 JSON)。纯手写 spec ⇒ 留空。 -forms = [] -models = [] -menus = [] -flows = [] - -[pack.build] -# 纯元数据包(L0):无 Rust 代码要编译,spec 直接链进内核。 -kind = "none" diff --git a/packs/books/schema/001_init.sql b/packs/books/schema/001_init.sql deleted file mode 100644 index 0ecdc11..0000000 --- a/packs/books/schema/001_init.sql +++ /dev/null @@ -1,33 +0,0 @@ --- book_shop_book —— 图书超市(业务包自带的 DDL)。 --- --- 🔴 **DDL 跟着包走**:本文件在 `packs/books/schema/` 下,由 `packs/books/src/lib.rs` --- 用 `include_str!` **编译进二进制** ⇒ 内核启动时按包顺序幂等执行 --- ⇒ 不再手抄进 `db/schema.sql`。 --- --- 🔴 **列名 / 列序逐字对齐 react 版 TypeORM entity**(`books.entity.ts`)—— --- 这是「两版后端能开同一个库」的前提 ⇒ **业务列一个都不许改名**。 --- --- 🔴 **2026-11-04 的两处差异**(搬成包时按平台规则补的,见 `HANDOFF.md`): --- ① 追加 `f_tenant_id`(`DEFAULT '0' NOT NULL`)并进入复合主键 —— --- 包 DDL 的硬闸门(`bootstrap::pack_ddls_carry_tenant_id_and_composite_key`) --- 要求每张业务表都带它;react 侧不认识这一列,但读不读都行、写不写都行 --- (有默认值),⇒ 同库兼容性仍然成立; --- ② `f_id` 从 `PRIMARY KEY` 改成 `NOT NULL` + 末尾复合主键。 --- 🔴 **spec 的列清单没有加 `f_tenant_id`** ⇒ 面 A / 面 B 的 JSON 键与响应**零变化**。 --- --- 🔴 **本文件只许建本包自己的表**,**不许建 `base_*`**(装载器会拦)。 - -CREATE TABLE IF NOT EXISTS book_shop_book ( - f_id VARCHAR(50) NOT NULL, - f_title VARCHAR(255), - f_author VARCHAR(100), - f_isbn VARCHAR(32), - f_category VARCHAR(50), - f_price NUMERIC(12,2), - f_stock INTEGER DEFAULT 0, - f_creator_user_id VARCHAR(50), - f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, - f_delete_mark INTEGER DEFAULT 0, - f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, - PRIMARY KEY (f_id, f_tenant_id) -); diff --git a/packs/books/src/lib.rs b/packs/books/src/lib.rs deleted file mode 100644 index f8df1cb..0000000 --- a/packs/books/src/lib.rs +++ /dev/null @@ -1,229 +0,0 @@ -//! books —— 图书超市业务包(**示例包**)。 -//! -// 🔴 **本包是「示例」,不是业务真源**:它演示「一个业务包只依赖 `sspf-sdk` -//! 就能声明完整的业务(表 + 列 + 菜单 + 面 B 路由)」。 -//! 技能把这套示例带走时,**整个 `packs/books` 目录一起搬**即可 —— 内核零改动。 -//! -//! 🔴 **依赖纪律(AR2)**:只允许 `sspf-sdk`。出现 axum / tokio / pglite -//! ⇒ `check-arch.sh` 直接红 —— 这是「整目录可搬走」的技术保证。 -//! 🔴 **守卫**:菜单 `books/Book`(`module_key`)⇒ 非管理员未授权 ⇒ `code=403`。 -//! 🔴 `f_price` 是 **numeric**(JSON 字符串 `"9.90"`)· `f_stock` 是 **int**(JSON 数字 `100`)。 -//! -//! 🔴 **DDL 跟着包走**:`schema/001_init.sql` 用 `include_str!` 编译进二进制, -//! 内核启动时幂等执行 ⇒ 不再手抄进 `db/schema.sql`。 - -use sspf_sdk::{ - BusinessPack, ColumnSpec, EntitySpec, HttpMethod, Manifest, MenuSpec, PackRoute, RouteAction, - RouteGuard, -}; - -/// 🔴 **本包自带的 DDL**(编译进二进制 ⇒ 包目录可整目录搬走)。 -pub const BOOK_DDL: &str = include_str!("../schema/001_init.sql"); - -/// 🔴 **包的统一 DDL 出口**(`表名 → DDL 文本`)—— 内核**只认这一种写法**。 -/// 常量名固定、形状固定 ⇒ 内核/生成器可以无脑遍历(加包不用改内核)。 -pub const DDLS: &[(&str, &str)] = &[("book_shop_book", BOOK_DDL)]; - -/// `book_shop_book` 的列清单(**顺序 = 响应 JSON 的键序**)。 -/// -/// 🔴 **不含 `f_tenant_id`**:该列在 DDL 里(平台硬要求),但不进投影 / 不进出参 -/// ⇒ 响应形状与面 A 的历史行为**逐字不变**(`db/schema.sql` 时代的 JSON 长什么样, -/// 现在还是什么样)。 -const BOOK_COLUMNS: &[ColumnSpec] = &[ - ColumnSpec { - column: "f_id", - json_key: "id", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_title", - json_key: "title", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_author", - json_key: "author", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_isbn", - json_key: "isbn", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_category", - json_key: "category", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_price", - json_key: "price", - default: Some("0.00"), - numeric: true, - }, - ColumnSpec { - column: "f_stock", - json_key: "stock", - default: Some("0"), - numeric: false, - }, - ColumnSpec { - column: "f_creator_user_id", - json_key: "creatorUserId", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_creator_time", - json_key: "creatorTime", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_delete_mark", - json_key: "deleteMark", - default: Some("0"), - numeric: false, - }, -]; - -/// `book_shop_book` 的 spec。 -pub const BOOK_SPEC: EntitySpec = EntitySpec { - app_code: "books", - entity: "Book", - table: "book_shop_book", - module_key: Some("books/Book"), - columns: BOOK_COLUMNS, - numeric_columns: &["f_price"], - creator_fixed: None, -}; - -/// 本包的内置菜单。 -/// -/// 🔴 `url_address` 与 [`BOOK_SPEC`] 的 `module_key` 必须**一字不差** -/// (面 A 的菜单守卫靠它命中);`module_key: None` 的包(如 demo)走「仅登录」。 -pub const BOOK_MENU: MenuSpec = MenuSpec { - id: "m_book", - full_name: "图书超市", - en_code: "permission.books.book", - url_address: "books/Book", - parent_id: "0", - menu_type: 2, - icon: Some("app"), - sort_code: 8, - // 🔴 字面量而非引用内核常量:业务包不许依赖内核(AR2)。 - // `mainSystem` 是基线平台的官方常量值,属于契约字面量,可以写死。 - system_en_code: "mainSystem", -}; - -/// 包清单(与 `pack.toml` 的 `[pack]` 段一致)。 -const MANIFEST: Manifest = Manifest { - app_code: "books", - name: "图书超市", - version: "1.0.0", - kernel_req: ">=0.4,<0.5", - migratable: true, -}; - -// ---------------------------------------------------------------- 路由声明 -// -// 🔴 **面 B 必须是官方 RESTful 形状**:`GET/POST /api/{模块}/{资源}` + -// `DELETE /api/{模块}/{资源}/{id}` —— **不是**面 A 的 `/api/ssw/...`。 -// 面 A 由内核的 `src/backend/src/modules/books.rs` 提供(本仓自造约定)。 -// -// 🔴 **路由是「声明」,不是 handler** —— `PackRoute` 里没有 axum 类型 -// ⇒ 业务包不需要依赖 axum;内核按声明 + spec 生成真正的 handler -// (`sspf_core::crud::crud_router`)。 -// 🔴 **面 B 的判据 = 点权限(`f_en_code`)** —— 同上,与面 A 的菜单路径并存。 - -/// `GET /api/books/Book` —— 列表。 -pub const BOOK_LIST_ROUTE: PackRoute = PackRoute { - path: "/api/books/Book", - method: HttpMethod::Get, - entity: "Book", - action: RouteAction::List, - guard: RouteGuard::EnCode("permission.books.book"), -}; - -/// `POST /api/books/Book` —— 新建 / 更新(body 里带 `id` 就是更新)。 -pub const BOOK_SAVE_ROUTE: PackRoute = PackRoute { - path: "/api/books/Book", - method: HttpMethod::Post, - entity: "Book", - action: RouteAction::Save, - guard: RouteGuard::EnCode("permission.books.book"), -}; - -/// `DELETE /api/books/Book/{id}` —— 软删。 -pub const BOOK_DELETE_ROUTE: PackRoute = PackRoute { - path: "/api/books/Book/{id}", - method: HttpMethod::Delete, - entity: "Book", - action: RouteAction::Delete, - guard: RouteGuard::EnCode("permission.books.book"), -}; - -/// 本包声明的全部路由(每条实体恰好 3 条 —— 内核的装载自检钉住这个数)。 -pub const BOOK_ROUTES: &[PackRoute] = &[ - BOOK_LIST_ROUTE, - BOOK_SAVE_ROUTE, - BOOK_DELETE_ROUTE, -]; - -/// 业务包本体。 -/// -/// 🔴 **类型名固定为 `Pack`** —— 内核的 `packs_gen.rs` 是生成的, -/// 生成器按 `sspf_pack_::Pack` 拼路径 ⇒ 每个包都用同一个名字。 -pub struct Pack; - -impl BusinessPack for Pack { - fn manifest(&self) -> &'static Manifest { - &MANIFEST - } - - fn entities(&self) -> &'static [EntitySpec] { - &[BOOK_SPEC] - } - - fn menus(&self) -> &'static [MenuSpec] { - &[BOOK_MENU] - } - - fn routes(&self) -> &'static [PackRoute] { - BOOK_ROUTES - } -} - -#[cfg(test)] -mod tests { - use super::*; - - /// 列名全部 `f_` 前缀,且第一列是 `f_id`(响应键序的第一位)。 - #[test] - fn columns_are_prefixed_and_have_id() { - assert_eq!(BOOK_COLUMNS[0].column, "f_id"); - for c in BOOK_COLUMNS { - assert!(c.column.starts_with("f_"), "列名必须 f_ 前缀: {}", c.column); - } - } - - /// spec 的 `module_key` 与菜单 `url_address` 一致(`None` 的包只校验菜单本身)。 - #[test] - fn module_key_matches_menu_url_address() { - match BOOK_SPEC.module_key { - Some(key) => assert_eq!(key, BOOK_MENU.url_address), - None => assert_eq!(BOOK_MENU.url_address, "books/Book"), - } - } - - /// 路由条数固定 3(List / Save / Delete)—— 少一条 ⇒ 某动作静默 404。 - #[test] - fn declares_exactly_three_routes() { - assert_eq!(BOOK_ROUTES.len(), 3); - } -} diff --git a/packs/demo/Cargo.toml b/packs/demo/Cargo.toml deleted file mode 100644 index 965b365..0000000 --- a/packs/demo/Cargo.toml +++ /dev/null @@ -1,11 +0,0 @@ -[package] -name = "sspf-pack-demo" -version.workspace = true -edition.workspace = true -rust-version.workspace = true - -# 🔴 AR2:业务包只允许依赖 `sspf-sdk`(+ serde)。 -# 出现 axum / tokio / pglite ⇒ `check-arch.sh` 直接红。 -# 这是「整目录可搬走」的技术保证。 -[dependencies] -sspf-sdk = { path = "../../crates/sspf-sdk" } diff --git a/packs/demo/pack.toml b/packs/demo/pack.toml deleted file mode 100644 index a3eab42..0000000 --- a/packs/demo/pack.toml +++ /dev/null @@ -1,31 +0,0 @@ -# 业务包清单 —— **示例包**(可整目录搬走,技能带它当样板)。 -# 🔴 本文件不是给 cargo 读的,是给 `sspf pack export/import` 与内核装载器读的。 - -[pack] -app_code = "demo" -name = "Demo 示例" -version = "1.0.0" -kernel = ">=0.4,<0.5" # 契约版本区间(不是 cargo 版本,见 bootstrap::kernel_version) -migratable = true # 允许导出到基线平台 - -[pack.compat] -baseline = "react-demo" # 对齐基准 -frontend = "vue3" # 前端族(决定表单 JSON 方言) -tenant = false # 本期单租户(列仍带 f_tenant_id,见 DDL 注释) - -# 物理表:name = 本平台表名;baseline_table = 基线平台上的表名(导出时映射) -[[pack.tables]] -name = "demo_item" -ddl = "schema/001_init.sql" -baseline_table = "demo_item" - -[pack.metadata] -# 低代码元数据(与基线平台 visualdev 同构的 JSON)。纯手写 spec ⇒ 留空。 -forms = [] -models = [] -menus = [] -flows = [] - -[pack.build] -# 纯元数据包(L0):无 Rust 代码要编译,spec 直接链进内核。 -kind = "none" diff --git a/packs/demo/schema/001_init.sql b/packs/demo/schema/001_init.sql deleted file mode 100644 index 594dcb4..0000000 --- a/packs/demo/schema/001_init.sql +++ /dev/null @@ -1,29 +0,0 @@ --- demo_item —— Demo 示例(业务包自带的 DDL)。 --- --- 🔴 **DDL 跟着包走**:本文件在 `packs/demo/schema/` 下,由 `packs/demo/src/lib.rs` --- 用 `include_str!` **编译进二进制** ⇒ 内核启动时按包顺序幂等执行 --- ⇒ 不再手抄进 `db/schema.sql`。 --- --- 🔴 **列名 / 列序逐字对齐 react 版 TypeORM entity**(`demo.entity.ts`)—— --- 这是「两版后端能开同一个库」的前提 ⇒ **业务列一个都不许改名**。 --- --- 🔴 **2026-11-04 的两处差异**(搬成包时按平台规则补的,见 `HANDOFF.md`): --- ① 追加 `f_tenant_id`(`DEFAULT '0' NOT NULL`)并进入复合主键 —— --- 包 DDL 的硬闸门(`bootstrap::pack_ddls_carry_tenant_id_and_composite_key`) --- 要求每张业务表都带它;react 侧不认识这一列,但读不读都行、写不写都行 --- (有默认值),⇒ 同库兼容性仍然成立; --- ② `f_id` 从 `PRIMARY KEY` 改成 `NOT NULL` + 末尾复合主键。 --- 🔴 **spec 的列清单没有加 `f_tenant_id`** ⇒ 面 A / 面 B 的 JSON 键与响应**零变化**。 --- --- 🔴 **本文件只许建本包自己的表**,**不许建 `base_*`**(装载器会拦)。 - -CREATE TABLE IF NOT EXISTS demo_item ( - f_id VARCHAR(50) NOT NULL, - f_title VARCHAR(255), - f_status VARCHAR(32), - f_creator_user_id VARCHAR(50), - f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, - f_delete_mark INTEGER DEFAULT 0, - f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, - PRIMARY KEY (f_id, f_tenant_id) -); diff --git a/packs/demo/src/lib.rs b/packs/demo/src/lib.rs deleted file mode 100644 index a55befc..0000000 --- a/packs/demo/src/lib.rs +++ /dev/null @@ -1,207 +0,0 @@ -//! demo —— Demo 示例业务包(**示例包**)。 -//! -// 🔴 **本包是「示例」,不是业务真源**:它演示「一个业务包只依赖 `sspf-sdk` -//! 就能声明完整的业务(表 + 列 + 菜单 + 面 B 路由)」。 -//! 技能把这套示例带走时,**整个 `packs/demo` 目录一起搬**即可 —— 内核零改动。 -//! -//! 🔴 **依赖纪律(AR2)**:只允许 `sspf-sdk`。出现 axum / tokio / pglite -//! ⇒ `check-arch.sh` 直接红 —— 这是「整目录可搬走」的技术保证。 -//! 🔴 **本包的特别规则(裁决 S22)**:`f_creator_user_id` **恒为 `'admin'`** -//! (不看 body)⇒ 由 spec 的 `creator_fixed` 声明,引擎不认 app_code。 -//! 🔴 **本包仅登录**(`module_key: None`)⇒ 面 A 走「登录即可」,面 B 走 `RouteGuard::Login`。 -//! -//! 🔴 **DDL 跟着包走**:`schema/001_init.sql` 用 `include_str!` 编译进二进制, -//! 内核启动时幂等执行 ⇒ 不再手抄进 `db/schema.sql`。 - -use sspf_sdk::{ - BusinessPack, ColumnSpec, EntitySpec, HttpMethod, Manifest, MenuSpec, PackRoute, RouteAction, - RouteGuard, -}; - -/// 🔴 **本包自带的 DDL**(编译进二进制 ⇒ 包目录可整目录搬走)。 -pub const DEMO_DDL: &str = include_str!("../schema/001_init.sql"); - -/// 🔴 **包的统一 DDL 出口**(`表名 → DDL 文本`)—— 内核**只认这一种写法**。 -/// 常量名固定、形状固定 ⇒ 内核/生成器可以无脑遍历(加包不用改内核)。 -pub const DDLS: &[(&str, &str)] = &[("demo_item", DEMO_DDL)]; - -/// `demo_item` 的列清单(**顺序 = 响应 JSON 的键序**)。 -/// -/// 🔴 **不含 `f_tenant_id`**:该列在 DDL 里(平台硬要求),但不进投影 / 不进出参 -/// ⇒ 响应形状与面 A 的历史行为**逐字不变**(`db/schema.sql` 时代的 JSON 长什么样, -/// 现在还是什么样)。 -const DEMO_COLUMNS: &[ColumnSpec] = &[ - ColumnSpec { - column: "f_id", - json_key: "id", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_title", - json_key: "title", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_status", - json_key: "status", - default: Some("草稿"), - numeric: false, - }, - ColumnSpec { - column: "f_creator_user_id", - json_key: "creatorUserId", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_creator_time", - json_key: "creatorTime", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_delete_mark", - json_key: "deleteMark", - default: Some("0"), - numeric: false, - }, -]; - -/// `demo_item` 的 spec。 -pub const DEMO_SPEC: EntitySpec = EntitySpec { - app_code: "demo", - entity: "DemoItem", - table: "demo_item", - module_key: None, - columns: DEMO_COLUMNS, - numeric_columns: &[], - creator_fixed: Some("admin"), -}; - -/// 本包的内置菜单。 -/// -/// 🔴 `url_address` 与 [`DEMO_SPEC`] 的 `module_key` 必须**一字不差** -/// (面 A 的菜单守卫靠它命中);`module_key: None` 的包(如 demo)走「仅登录」。 -pub const DEMO_MENU: MenuSpec = MenuSpec { - id: "m_demo", - full_name: "Demo 示例", - en_code: "permission.demo", - url_address: "demo-item", - parent_id: "0", - menu_type: 2, - icon: Some("app"), - sort_code: 6, - // 🔴 字面量而非引用内核常量:业务包不许依赖内核(AR2)。 - // `mainSystem` 是基线平台的官方常量值,属于契约字面量,可以写死。 - system_en_code: "mainSystem", -}; - -/// 包清单(与 `pack.toml` 的 `[pack]` 段一致)。 -const MANIFEST: Manifest = Manifest { - app_code: "demo", - name: "Demo 示例", - version: "1.0.0", - kernel_req: ">=0.4,<0.5", - migratable: true, -}; - -// ---------------------------------------------------------------- 路由声明 -// -// 🔴 **面 B 必须是官方 RESTful 形状**:`GET/POST /api/{模块}/{资源}` + -// `DELETE /api/{模块}/{资源}/{id}` —— **不是**面 A 的 `/api/ssw/...`。 -// 面 A 由内核的 `src/backend/src/modules/demo.rs` 提供(本仓自造约定)。 -// -// 🔴 **路由是「声明」,不是 handler** —— `PackRoute` 里没有 axum 类型 -// ⇒ 业务包不需要依赖 axum;内核按声明 + spec 生成真正的 handler -// (`sspf_core::crud::crud_router`)。 -// 🔴 **面 B 的守卫是 `Login`**:官方对 demo 这种「示例/工具类」端点不打 -// `@SaCheckPermission` ⇒ 登录即可。 - -/// `GET /api/demo/DemoItem` —— 列表。 -pub const DEMO_LIST_ROUTE: PackRoute = PackRoute { - path: "/api/demo/DemoItem", - method: HttpMethod::Get, - entity: "DemoItem", - action: RouteAction::List, - guard: RouteGuard::Login, -}; - -/// `POST /api/demo/DemoItem` —— 新建 / 更新(body 里带 `id` 就是更新)。 -pub const DEMO_SAVE_ROUTE: PackRoute = PackRoute { - path: "/api/demo/DemoItem", - method: HttpMethod::Post, - entity: "DemoItem", - action: RouteAction::Save, - guard: RouteGuard::Login, -}; - -/// `DELETE /api/demo/DemoItem/{id}` —— 软删。 -pub const DEMO_DELETE_ROUTE: PackRoute = PackRoute { - path: "/api/demo/DemoItem/{id}", - method: HttpMethod::Delete, - entity: "DemoItem", - action: RouteAction::Delete, - guard: RouteGuard::Login, -}; - -/// 本包声明的全部路由(每条实体恰好 3 条 —— 内核的装载自检钉住这个数)。 -pub const DEMO_ROUTES: &[PackRoute] = &[ - DEMO_LIST_ROUTE, - DEMO_SAVE_ROUTE, - DEMO_DELETE_ROUTE, -]; - -/// 业务包本体。 -/// -/// 🔴 **类型名固定为 `Pack`** —— 内核的 `packs_gen.rs` 是生成的, -/// 生成器按 `sspf_pack_::Pack` 拼路径 ⇒ 每个包都用同一个名字。 -pub struct Pack; - -impl BusinessPack for Pack { - fn manifest(&self) -> &'static Manifest { - &MANIFEST - } - - fn entities(&self) -> &'static [EntitySpec] { - &[DEMO_SPEC] - } - - fn menus(&self) -> &'static [MenuSpec] { - &[DEMO_MENU] - } - - fn routes(&self) -> &'static [PackRoute] { - DEMO_ROUTES - } -} - -#[cfg(test)] -mod tests { - use super::*; - - /// 列名全部 `f_` 前缀,且第一列是 `f_id`(响应键序的第一位)。 - #[test] - fn columns_are_prefixed_and_have_id() { - assert_eq!(DEMO_COLUMNS[0].column, "f_id"); - for c in DEMO_COLUMNS { - assert!(c.column.starts_with("f_"), "列名必须 f_ 前缀: {}", c.column); - } - } - - /// spec 的 `module_key` 与菜单 `url_address` 一致(`None` 的包只校验菜单本身)。 - #[test] - fn module_key_matches_menu_url_address() { - match DEMO_SPEC.module_key { - Some(key) => assert_eq!(key, DEMO_MENU.url_address), - None => assert_eq!(DEMO_MENU.url_address, "demo-item"), - } - } - - /// 路由条数固定 3(List / Save / Delete)—— 少一条 ⇒ 某动作静默 404。 - #[test] - fn declares_exactly_three_routes() { - assert_eq!(DEMO_ROUTES.len(), 3); - } -} diff --git a/packs/shop/Cargo.toml b/packs/shop/Cargo.toml deleted file mode 100644 index ff198f0..0000000 --- a/packs/shop/Cargo.toml +++ /dev/null @@ -1,11 +0,0 @@ -[package] -name = "sspf-pack-shop" -version.workspace = true -edition.workspace = true -rust-version.workspace = true - -# 🔴 AR2:业务包只允许依赖 `sspf-sdk`(+ serde)。 -# 出现 axum / tokio / pglite ⇒ `check-arch.sh` 直接红。 -# 这是「整目录可搬走」的技术保证。 -[dependencies] -sspf-sdk = { path = "../../crates/sspf-sdk" } diff --git a/packs/shop/pack.toml b/packs/shop/pack.toml deleted file mode 100644 index a9e998b..0000000 --- a/packs/shop/pack.toml +++ /dev/null @@ -1,31 +0,0 @@ -# 业务包清单 —— **示例包**(可整目录搬走,技能带它当样板)。 -# 🔴 本文件不是给 cargo 读的,是给 `sspf pack export/import` 与内核装载器读的。 - -[pack] -app_code = "shop" -name = "产品管理" -version = "1.0.0" -kernel = ">=0.4,<0.5" # 契约版本区间(不是 cargo 版本,见 bootstrap::kernel_version) -migratable = true # 允许导出到基线平台 - -[pack.compat] -baseline = "react-demo" # 对齐基准 -frontend = "vue3" # 前端族(决定表单 JSON 方言) -tenant = false # 本期单租户(列仍带 f_tenant_id,见 DDL 注释) - -# 物理表:name = 本平台表名;baseline_table = 基线平台上的表名(导出时映射) -[[pack.tables]] -name = "shop_product" -ddl = "schema/001_init.sql" -baseline_table = "shop_product" - -[pack.metadata] -# 低代码元数据(与基线平台 visualdev 同构的 JSON)。纯手写 spec ⇒ 留空。 -forms = [] -models = [] -menus = [] -flows = [] - -[pack.build] -# 纯元数据包(L0):无 Rust 代码要编译,spec 直接链进内核。 -kind = "none" diff --git a/packs/shop/schema/001_init.sql b/packs/shop/schema/001_init.sql deleted file mode 100644 index e8be836..0000000 --- a/packs/shop/schema/001_init.sql +++ /dev/null @@ -1,29 +0,0 @@ --- shop_product —— 产品管理(业务包自带的 DDL)。 --- --- 🔴 **DDL 跟着包走**:本文件在 `packs/shop/schema/` 下,由 `packs/shop/src/lib.rs` --- 用 `include_str!` **编译进二进制** ⇒ 内核启动时按包顺序幂等执行 --- ⇒ 不再手抄进 `db/schema.sql`。 --- --- 🔴 **列名 / 列序逐字对齐 react 版 TypeORM entity**(`shop.entity.ts`)—— --- 这是「两版后端能开同一个库」的前提 ⇒ **业务列一个都不许改名**。 --- --- 🔴 **2026-11-04 的两处差异**(搬成包时按平台规则补的,见 `HANDOFF.md`): --- ① 追加 `f_tenant_id`(`DEFAULT '0' NOT NULL`)并进入复合主键 —— --- 包 DDL 的硬闸门(`bootstrap::pack_ddls_carry_tenant_id_and_composite_key`) --- 要求每张业务表都带它;react 侧不认识这一列,但读不读都行、写不写都行 --- (有默认值),⇒ 同库兼容性仍然成立; --- ② `f_id` 从 `PRIMARY KEY` 改成 `NOT NULL` + 末尾复合主键。 --- 🔴 **spec 的列清单没有加 `f_tenant_id`** ⇒ 面 A / 面 B 的 JSON 键与响应**零变化**。 --- --- 🔴 **本文件只许建本包自己的表**,**不许建 `base_*`**(装载器会拦)。 - -CREATE TABLE IF NOT EXISTS shop_product ( - f_id VARCHAR(50) NOT NULL, - f_title VARCHAR(255), - f_price NUMERIC(12,2), - f_creator_user_id VARCHAR(50), - f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, - f_delete_mark INTEGER DEFAULT 0, - f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, - PRIMARY KEY (f_id, f_tenant_id) -); diff --git a/packs/shop/src/lib.rs b/packs/shop/src/lib.rs deleted file mode 100644 index f1b3d62..0000000 --- a/packs/shop/src/lib.rs +++ /dev/null @@ -1,206 +0,0 @@ -//! shop —— 产品管理业务包(**示例包**)。 -//! -// 🔴 **本包是「示例」,不是业务真源**:它演示「一个业务包只依赖 `sspf-sdk` -//! 就能声明完整的业务(表 + 列 + 菜单 + 面 B 路由)」。 -//! 技能把这套示例带走时,**整个 `packs/shop` 目录一起搬**即可 —— 内核零改动。 -//! -//! 🔴 **依赖纪律(AR2)**:只允许 `sspf-sdk`。出现 axum / tokio / pglite -//! ⇒ `check-arch.sh` 直接红 —— 这是「整目录可搬走」的技术保证。 -//! 🔴 **守卫**:菜单 `shop/Product`(`module_key`)⇒ 非管理员未授权 ⇒ `code=403`。 -//! 🔴 `f_price` 是 **numeric**(JSON 字符串 `"9.90"`)⇒ 进 `numeric_columns`。 -//! -//! 🔴 **DDL 跟着包走**:`schema/001_init.sql` 用 `include_str!` 编译进二进制, -//! 内核启动时幂等执行 ⇒ 不再手抄进 `db/schema.sql`。 - -use sspf_sdk::{ - BusinessPack, ColumnSpec, EntitySpec, HttpMethod, Manifest, MenuSpec, PackRoute, RouteAction, - RouteGuard, -}; - -/// 🔴 **本包自带的 DDL**(编译进二进制 ⇒ 包目录可整目录搬走)。 -pub const PRODUCT_DDL: &str = include_str!("../schema/001_init.sql"); - -/// 🔴 **包的统一 DDL 出口**(`表名 → DDL 文本`)—— 内核**只认这一种写法**。 -/// 常量名固定、形状固定 ⇒ 内核/生成器可以无脑遍历(加包不用改内核)。 -pub const DDLS: &[(&str, &str)] = &[("shop_product", PRODUCT_DDL)]; - -/// `shop_product` 的列清单(**顺序 = 响应 JSON 的键序**)。 -/// -/// 🔴 **不含 `f_tenant_id`**:该列在 DDL 里(平台硬要求),但不进投影 / 不进出参 -/// ⇒ 响应形状与面 A 的历史行为**逐字不变**(`db/schema.sql` 时代的 JSON 长什么样, -/// 现在还是什么样)。 -const PRODUCT_COLUMNS: &[ColumnSpec] = &[ - ColumnSpec { - column: "f_id", - json_key: "id", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_title", - json_key: "title", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_price", - json_key: "price", - default: Some("0.00"), - numeric: true, - }, - ColumnSpec { - column: "f_creator_user_id", - json_key: "creatorUserId", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_creator_time", - json_key: "creatorTime", - default: None, - numeric: false, - }, - ColumnSpec { - column: "f_delete_mark", - json_key: "deleteMark", - default: Some("0"), - numeric: false, - }, -]; - -/// `shop_product` 的 spec。 -pub const PRODUCT_SPEC: EntitySpec = EntitySpec { - app_code: "shop", - entity: "Product", - table: "shop_product", - module_key: Some("shop/Product"), - columns: PRODUCT_COLUMNS, - numeric_columns: &["f_price"], - creator_fixed: None, -}; - -/// 本包的内置菜单。 -/// -/// 🔴 `url_address` 与 [`PRODUCT_SPEC`] 的 `module_key` 必须**一字不差** -/// (面 A 的菜单守卫靠它命中);`module_key: None` 的包(如 demo)走「仅登录」。 -pub const PRODUCT_MENU: MenuSpec = MenuSpec { - id: "m_product", - full_name: "产品管理", - en_code: "permission.shop.product", - url_address: "shop/Product", - parent_id: "0", - menu_type: 2, - icon: Some("app"), - sort_code: 7, - // 🔴 字面量而非引用内核常量:业务包不许依赖内核(AR2)。 - // `mainSystem` 是基线平台的官方常量值,属于契约字面量,可以写死。 - system_en_code: "mainSystem", -}; - -/// 包清单(与 `pack.toml` 的 `[pack]` 段一致)。 -const MANIFEST: Manifest = Manifest { - app_code: "shop", - name: "产品管理", - version: "1.0.0", - kernel_req: ">=0.4,<0.5", - migratable: true, -}; - -// ---------------------------------------------------------------- 路由声明 -// -// 🔴 **面 B 必须是官方 RESTful 形状**:`GET/POST /api/{模块}/{资源}` + -// `DELETE /api/{模块}/{资源}/{id}` —— **不是**面 A 的 `/api/ssw/...`。 -// 面 A 由内核的 `src/backend/src/modules/shop.rs` 提供(本仓自造约定)。 -// -// 🔴 **路由是「声明」,不是 handler** —— `PackRoute` 里没有 axum 类型 -// ⇒ 业务包不需要依赖 axum;内核按声明 + spec 生成真正的 handler -// (`sspf_core::crud::crud_router`)。 -// 🔴 **面 B 的判据 = 点权限(`f_en_code`)** —— 官方 `@SaCheckPermission` 那套; -// 面 A 的菜单路径(`f_url_address`)是另一套判据 ⇒ 两套并存,互不影响。 - -/// `GET /api/shop/Product` —— 列表。 -pub const PRODUCT_LIST_ROUTE: PackRoute = PackRoute { - path: "/api/shop/Product", - method: HttpMethod::Get, - entity: "Product", - action: RouteAction::List, - guard: RouteGuard::EnCode("permission.shop.product"), -}; - -/// `POST /api/shop/Product` —— 新建 / 更新(body 里带 `id` 就是更新)。 -pub const PRODUCT_SAVE_ROUTE: PackRoute = PackRoute { - path: "/api/shop/Product", - method: HttpMethod::Post, - entity: "Product", - action: RouteAction::Save, - guard: RouteGuard::EnCode("permission.shop.product"), -}; - -/// `DELETE /api/shop/Product/{id}` —— 软删。 -pub const PRODUCT_DELETE_ROUTE: PackRoute = PackRoute { - path: "/api/shop/Product/{id}", - method: HttpMethod::Delete, - entity: "Product", - action: RouteAction::Delete, - guard: RouteGuard::EnCode("permission.shop.product"), -}; - -/// 本包声明的全部路由(每条实体恰好 3 条 —— 内核的装载自检钉住这个数)。 -pub const PRODUCT_ROUTES: &[PackRoute] = &[ - PRODUCT_LIST_ROUTE, - PRODUCT_SAVE_ROUTE, - PRODUCT_DELETE_ROUTE, -]; - -/// 业务包本体。 -/// -/// 🔴 **类型名固定为 `Pack`** —— 内核的 `packs_gen.rs` 是生成的, -/// 生成器按 `sspf_pack_::Pack` 拼路径 ⇒ 每个包都用同一个名字。 -pub struct Pack; - -impl BusinessPack for Pack { - fn manifest(&self) -> &'static Manifest { - &MANIFEST - } - - fn entities(&self) -> &'static [EntitySpec] { - &[PRODUCT_SPEC] - } - - fn menus(&self) -> &'static [MenuSpec] { - &[PRODUCT_MENU] - } - - fn routes(&self) -> &'static [PackRoute] { - PRODUCT_ROUTES - } -} - -#[cfg(test)] -mod tests { - use super::*; - - /// 列名全部 `f_` 前缀,且第一列是 `f_id`(响应键序的第一位)。 - #[test] - fn columns_are_prefixed_and_have_id() { - assert_eq!(PRODUCT_COLUMNS[0].column, "f_id"); - for c in PRODUCT_COLUMNS { - assert!(c.column.starts_with("f_"), "列名必须 f_ 前缀: {}", c.column); - } - } - - /// spec 的 `module_key` 与菜单 `url_address` 一致(`None` 的包只校验菜单本身)。 - #[test] - fn module_key_matches_menu_url_address() { - match PRODUCT_SPEC.module_key { - Some(key) => assert_eq!(key, PRODUCT_MENU.url_address), - None => assert_eq!(PRODUCT_MENU.url_address, "shop/Product"), - } - } - - /// 路由条数固定 3(List / Save / Delete)—— 少一条 ⇒ 某动作静默 404。 - #[test] - fn declares_exactly_three_routes() { - assert_eq!(PRODUCT_ROUTES.len(), 3); - } -} diff --git a/references/BaseCrudController.java b/references/BaseCrudController.java deleted file mode 100644 index 0690e50..0000000 --- a/references/BaseCrudController.java +++ /dev/null @@ -1,332 +0,0 @@ -package ssw.common.controller; - -import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper; -import com.baomidou.mybatisplus.core.metadata.IPage; -import io.swagger.v3.oas.annotations.Operation; -import jakarta.servlet.http.HttpServletRequest; -import jnpf.base.ActionResult; -import jnpf.base.Pagination; -import jnpf.base.entity.SuperExtendEntity; -import jnpf.base.service.SuperService; -import jnpf.base.vo.PaginationVO; -import jnpf.util.JsonUtil; -import jnpf.util.RandomUtil; -import jnpf.util.UserProvider; -import org.springframework.web.bind.annotation.DeleteMapping; -import org.springframework.web.bind.annotation.GetMapping; -import org.springframework.web.bind.annotation.PathVariable; -import org.springframework.web.bind.annotation.PostMapping; -import org.springframework.web.bind.annotation.PutMapping; -import org.springframework.web.bind.annotation.RequestBody; - -import java.util.Collections; -import java.util.Date; -import java.util.List; -import java.util.Map; - -/** - * ssw 通用 CRUD 控制器骨架 — 业务 Controller 继承它即可省去 List/Page/Detail/Create/Update/Delete 样板。 - * - * 子类只声明「关键字匹配哪些列」「支持哪些过滤参数」, - * 需要时覆写 {@link #beforeSave} 做业务校验。 - * - * 三条硬约定: - *
    - *
  • 软删除:全局逻辑删除没开(yml 里 logic-delete-field 是注释掉的), - * 删除走手写的 f_delete_mark=1,列表查询一律带 {@code f_delete_mark IS NULL}。 - * DDL 里的唯一索引也是按这个条件建的偏索引,两边必须对齐。
  • - *
  • 基类不用 Lambda 条件构造器:泛型擦除后拿不到具体实体的方法引用, - * 统一用字符串列名写 QueryWrapper。
  • - *
  • 租户隔离:一套实例可承载多个租户, - * 业务表统一带 f_tenant_id。子类通过 {@link #tenantColumn()} 声明租户列名, - * 基类自动接管 tenantId 过滤——子类不要自觉。
  • - *
- * - * 审计留痕:{@link #audit} 钩子默认 noop。子类按需 override 连到自家审计服务 - * (日志表 / MQ / 第三方审计平台)即可,方法签名见 {@code audit(action, bizId, target)}。 - * - * @param 实体类型(业务扩展位用 SuperExtendEntity) - */ -public abstract class BaseCrudController> { - - /** - * 菜单权限检查钩子。基类不依赖任何权限框架 — 子类按需覆盖({@code @PreAuthorize} / - * Sa-Token {@code @SaCheckPermission} / 调自家权限服务均可)。 - * 默认空实现(不检查权限),适合 demo / 内部工具。 - */ - protected void requireMenuPermission() { - } - - /** - * 数据范围过滤钩子。基类不依赖具体的数据范围解析器 — 子类按需覆盖往 wrapper 里拼 SQL。 - * 默认空实现(不过滤数据范围),适合单租户 / demo。 - */ - protected void applyDataScope(QueryWrapper wrapper, HttpServletRequest request) { - } - - /** 逻辑未删除条件,所有查询都要带 */ - protected static final String ALIVE = "(f_delete_mark IS NULL OR f_delete_mark = 0)"; - - // ------------------------------------------------------------------ 子类扩展点 - - protected abstract SuperService service(); - - /** 新建实体实例(泛型擦除拿不到构造器,交给子类) */ - protected abstract T newEntity(); - - /** 关键字模糊匹配的列,返回空数组表示不支持关键字搜索 */ - protected String[] keywordColumns() { - return new String[]{"f_name"}; - } - - /** 精确过滤:请求参数名 -> 数据库列名 */ - protected Map filterColumns() { - return Collections.emptyMap(); - } - - /** - * 该表的「租户」列名,返回 null 表示本表不按租户隔离 - * (如实例级全局配置)。返回非 null 时,请求参数 tenantId 自动生效。 - */ - protected String tenantColumn() { - return "f_tenant_id"; - } - - /** 默认排序列,倒序 */ - protected String defaultOrderColumn() { - return "f_creator_time"; - } - - /** - * 落库前的钩子,可做业务校验/补默认值。抛异常即中断并返回 fail。 - * - * @param entity 待保存实体 - * @param create true=新增,false=修改 - */ - protected void beforeSave(T entity, boolean create) { - } - - /** 删除前的钩子,可做引用检查 */ - protected void beforeDelete(T entity) { - } - - // ------------------------------------------------------------------ 审计留痕扩展点(可选实现) - - /** - * 本控制器对应的业务类型。默认由实体类名推导;返回 {@code null} 表示不留痕。 - */ - protected String auditBizType() { - String name = newEntity().getClass().getSimpleName().replaceAll("Entity$", ""); - return name.replaceAll("([a-z0-9])([A-Z])", "$1_$2").toUpperCase(); - } - - /** 留痕时展示的对象描述 */ - protected String auditTarget(T entity) { - if (entity == null) { - return null; - } - for (String getter : new String[]{"getCode", "getName", "getTaskNo", "getOrderCode", - "getDemandCode", "getResourceName", "getProductName", "getTitle", "getFullName"}) { - try { - Object v = entity.getClass().getMethod(getter).invoke(entity); - if (v != null && !v.toString().isBlank()) { - return v.toString(); - } - } catch (Exception ignore) { - // 该实体没有这个字段,继续试下一个 - } - } - return entity.getId(); - } - - /** - * 写一条业务留痕。子类要启用审计时,覆盖此方法连到自家审计服务; - * 不覆盖则 {@link #create} / {@link #update} / {@link #delete} 三处 audit 调用静默 noop。 - * - * 替换为自家实现时可参考方法签名:bizId 实体主键 / action CREATE|UPDATE|DELETE / target 业务标识。 - */ - protected void audit(String action, String bizId, String target) { - // 默认 noop;子类按需 override - } - - /** 写一条带结果与明细的业务留痕;默认 noop */ - protected void audit(String action, String bizId, String target, - String result, String failReason, String detail) { - // 默认 noop;子类按需 override - } - - // ------------------------------------------------------------------ 通用接口 - - @GetMapping - @Operation(summary = "分页列表", description = "支持 keyword 模糊搜索、tenantId 过滤与子类声明的精确过滤参数") - public ActionResult list(Pagination pagination, HttpServletRequest request) { - requireMenuPermission(); - QueryWrapper wrapper = buildWrapper(request); - long current = pagination.getCurrentPage() <= 0 ? 1 : pagination.getCurrentPage(); - long size = pagination.getPageSize() <= 0 ? 20 : Math.min(pagination.getPageSize(), 500); - - com.baomidou.mybatisplus.extension.plugins.pagination.Page page = - new com.baomidou.mybatisplus.extension.plugins.pagination.Page<>(current, size); - IPage result = service().page(page, wrapper); - - List records = pagination.setData(result.getRecords(), result.getTotal()); - return ActionResult.page(records, JsonUtil.getJsonToBean(pagination, PaginationVO.class)); - } - - @GetMapping("/All") - @Operation(summary = "不分页全量列表", description = "用于下拉选择等场景,最多返回 1000 条") - public ActionResult> all(HttpServletRequest request) { - requireMenuPermission(); - QueryWrapper wrapper = buildWrapper(request); - wrapper.last("limit 1000"); - return ActionResult.success(service().list(wrapper)); - } - - @GetMapping("/{id}") - @Operation(summary = "详情") - public ActionResult detail(@PathVariable("id") String id) { - requireMenuPermission(); - T entity = getAlive(id); - if (entity == null) { - return ActionResult.fail("记录不存在或已删除"); - } - return ActionResult.success(entity); - } - - @PostMapping - @Operation(summary = "新增") - public ActionResult create(@RequestBody T entity) { - requireMenuPermission(); - entity.setId(RandomUtil.uuId()); - entity.setDeleteMark(null); - beforeSave(entity, true); - service().save(entity); - audit("CREATE", entity.getId(), auditTarget(entity)); - return ActionResult.success("新增成功", entity.getId()); - } - - @PutMapping("/{id}") - @Operation(summary = "修改", description = "只覆盖请求体里出现的字段,未传字段保持原值") - public ActionResult update(@PathVariable("id") String id, @RequestBody T entity) { - requireMenuPermission(); - T exists = getAlive(id); - if (exists == null) { - return ActionResult.fail("记录不存在或已删除"); - } - entity.setId(id); - // 系统列不允许从请求体覆盖 - entity.setCreatorTime(null); - entity.setCreatorUserId(null); - entity.setDeleteMark(null); - entity.setDeleteTime(null); - entity.setDeleteUserId(null); - beforeSave(entity, false); - service().updateById(entity); - // 用改前的实体取 target:改后的对象只带请求体里出现的字段,编号往往是 null - audit("UPDATE", id, auditTarget(exists)); - return ActionResult.success("修改成功", id); - } - - @DeleteMapping("/{id}") - @Operation(summary = "删除", description = "逻辑删除,置 f_delete_mark=1") - public ActionResult delete(@PathVariable("id") String id) { - requireMenuPermission(); - T exists = getAlive(id); - if (exists == null) { - return ActionResult.fail("记录不存在或已删除"); - } - beforeDelete(exists); - T update = newEntity(); - update.setId(id); - update.setDeleteMark(1); - update.setDeleteTime(new Date()); - update.setDeleteUserId(safeUserId()); - service().updateById(update); - audit("DELETE", id, auditTarget(exists)); - return ActionResult.success("删除成功", id); - } - - // ------------------------------------------------------------------ 内部工具 - - protected QueryWrapper buildWrapper(HttpServletRequest request) { - QueryWrapper wrapper = new QueryWrapper<>(); - wrapper.apply(ALIVE); - - String tenantColumn = tenantColumn(); - if (tenantColumn != null) { - String tenantId = param(request, "tenantId"); - if (tenantId != null) { - wrapper.eq(tenantColumn, tenantId); - } - } - - filterColumns().forEach((param, column) -> { - String value = param(request, param); - if (value != null) { - wrapper.eq(column, value); - } - }); - - String keyword = param(request, "keyword"); - String[] columns = keywordColumns(); - if (keyword != null && columns.length > 0) { - wrapper.and(w -> { - for (int i = 0; i < columns.length; i++) { - if (i == 0) { - w.like(columns[i], keyword); - } else { - w.or().like(columns[i], keyword); - } - } - }); - } - applyDataScope(wrapper, request); - wrapper.orderByDesc(defaultOrderColumn()); - return wrapper; - } - - /** 取请求参数,空串统一归一成 null */ - protected String param(HttpServletRequest request, String name) { - if (request == null) { - return null; - } - String value = request.getParameter(name); - if (value == null) { - return null; - } - value = value.trim(); - return value.isEmpty() ? null : value; - } - - /** 按主键取未删除的记录 */ - protected T getAlive(String id) { - QueryWrapper wrapper = new QueryWrapper<>(); - wrapper.eq("f_id", id).apply(ALIVE); - return service().getOne(wrapper, false); - } - - /** 判断某列值是否已被占用(排除自身),用于编码唯一性校验 */ - protected boolean existsBy(String column, String value, String excludeId) { - QueryWrapper wrapper = new QueryWrapper<>(); - wrapper.eq(column, value).apply(ALIVE); - if (excludeId != null && !excludeId.isEmpty()) { - wrapper.ne("f_id", excludeId); - } - return service().count(wrapper) > 0; - } - - /** 必填校验小工具,减少 Controller 里成片的 if-blank */ - protected void requireText(String value, String message) { - if (value == null || value.isBlank()) { - throw new IllegalArgumentException(message); - } - } - - protected String safeUserId() { - try { - return UserProvider.getLoginUserId(); - } catch (Exception e) { - return null; - } - } -} \ No newline at end of file diff --git a/references/README.md b/references/README.md deleted file mode 100644 index 0626273..0000000 --- a/references/README.md +++ /dev/null @@ -1,49 +0,0 @@ -# references/ - -**用途**:迁 JNPF 时可复用的**通用基础设施源码** — 这些类不在 jnpf-common-all 里, -但 ssw-jnpf-lite-react 的实战用过并验证可工作。稳定期迁业务模块时按需拷贝。 - -> 自包含:**不**依赖任何本技能外的 `ssw-*` 类。BaseCrudController 不绑死任何权限框架 / 数据范围 -> 解析器 / 审计服务 — 这些由子类按需 override 提供。 - -## 当前收录 - -| 类 | 用途 | -|---|---| -| `BaseCrudController.java` | 通用 CRUD 骨架(List / Page / Detail / Create / Update / Delete + 关键字 / 过滤 / 数据范围 / 租户 / 可选审计)。业务 Controller `extends BaseCrudController` 即可省去样板。**不是 JNPF 官方类。** | - -## 使用方式 - -迁某个业务模块到 JNPF 时: - -1. 把 `BaseCrudController.java` 拷到目标工程的 `ssw.common.controller` 包(**推荐放共享层**,让多个 `-controller` 子模块复用) -2. 业务 Controller `extends BaseCrudController`,覆写方法: - - `service()`、`newEntity()`(必选) - - `keywordColumns()`、`filterColumns()`(可选) - - `beforeSave(entity, create)`(可选,业务校验) - - `requireMenuPermission()`、`applyDataScope()`(可选;权限 / 数据范围由子类按需实现,本基类不绑死任何权限框架) -3. 配套 import:`import jnpf.base.{ActionResult, Pagination, vo.PaginationVO}`; - `import jnpf.util.{RandomUtil, UserProvider, JsonUtil}`。 - -> 包命名约定见 `../template-boot-jnpf/README.md`「包命名约定」节 — `BaseCrudController` 必须放 `ssw.common.controller`, -> 业务 Controller 放 `ssw.{yourAppCode}.controller`。 - -## 默认 noop 的扩展钩子 - -| 钩子 | 默认行为 | 何时 override | -|------|----------|---------------| -| `requireMenuPermission()` | 空实现(不检查) | 需要菜单级权限时(自注 `@PreAuthorize` / Sa-Token `@SaCheckPermission` / 调 jnpf 自带守卫均可) | -| `applyDataScope(wrapper, request)` | 空实现(不过滤) | 需要按用户数据范围过滤时(往 wrapper 拼 SQL) | -| `audit(action, bizId, target)` | 空实现(不记) | 需要审计日志时(写日志表 / 调 MQ / HTTP 第三方) | - -> **重要**:本基类**不**自带任何权限 / 数据范围 / 审计服务 — 全部默认 noop,按需覆盖。 -> 不要期望拷过来就有这些能力。 - -## 为什么不放在主目录 / 不集成进 jnpf-common-all - -- 这些类属于**业务脚手架**,不是 JNPF 官方提供的公共组件; -- 形态与具体业务耦合(如 `auditBizType()` 默认从实体类名推导); -- JNPF 官方**只承诺**提供底层基元(SuperEntity/SuperMapper/SuperService/SuperServiceImpl/ActionResult), - 不提供这种「一键 CRUD」基类。 -- 因此稳定期迁每个业务模块都要带一份 `BaseCrudController.java` 过去,本目录即「免去到处找」的 - 内置副本。 \ No newline at end of file diff --git a/scripts/check-arch.sh b/scripts/check-arch.sh index d030a8f..9d896cb 100755 --- a/scripts/check-arch.sh +++ b/scripts/check-arch.sh @@ -15,7 +15,7 @@ # ── 判据 ── # AR1 `crates/sspf-sdk` 依赖只能有 `sspf-contract` # —— 业务包只依赖 sdk ⇒ sdk 多一个依赖 = 所有业务包都要背 -# AR2 `packs/*/Cargo.toml` 依赖 ⊆ {sspf-sdk, serde} +# AR2 🔴 平台包零业务:`packs/` 不存在;若出现则业务包依赖 ⊆ {sspf-sdk, serde} # —— 业务包必须能整目录搬走 ⇒ 不许挂在 axum / tokio / pglite 上 # AR3 `crates/sspf-contract` 源码不许 `use axum|tokio|pglite|sqlx` # —— 契约层一旦有 IO,业务包就再也不是「轻依赖」 @@ -52,7 +52,7 @@ # 到 `src/backend/tests/`、`crates/sspf-admin` 必须存在且产出 bin # —— 「内核是库、装配是应用、测试是消费者」这三条边界都是**文件位置** # ⇒ 没有任何编译错误会提示你踩线,只有结构慢慢退回原样 -# AR17 内核默认 feature 下不得编译期依赖 `packs/*` +# AR17 🔴 平台包零业务:任何 Cargo.toml 里都不许有 `sspf-pack-*` 依赖 / `example-packs` # —— `crates/sspf` 是业务仓唯一依赖的**标准平台包**;示例包一硬依赖, # `cargo add sspf` 就等于把 asset/demo/shop/books 拖进业务二进制 # AR18 `crates/sspf/src/**` 不得出现业务字面量(业务仓名 / 业务表名 / `/api/ssw/`) @@ -153,7 +153,16 @@ check_ar2() { found=1 fi done - [ "$n" -eq 0 ] && skip "AR2 尚无 packs/*(P3 才落地)" + if [ "$n" -eq 0 ]; then + # 🔴 2026-11-04 清理:零包是**合法目标态**,但不能「跳过」(跳过 = 尺子变瞎)。 + # ⇒ 改成正向断言:packs/ 目录必须不存在,谁把业务包塞回来立刻红。 + if [ -d "$ROOT/packs" ]; then + bad "AR2 平台包零业务:packs/ 目录不该存在(业务包属于业务仓 / 技能仓)" + found=1 + else + ok "AR2 平台包零业务:没有 packs/,无任何业务包依赖(出现即红)" + fi + fi return $found } @@ -631,7 +640,18 @@ check_pack1() { fi ok "PACK1 ${name}.rs 只做 re-export,spec 真源在 packs/${name}/src/lib.rs" done - [ "$n" -eq 0 ] && skip "PACK1 尚无「模块转发业务包」的模块" + if [ "$n" -eq 0 ]; then + # 🔴 2026-11-04 清理:没有业务模块可检查时**不能跳过**(假闸门)。 + # 正向钉住「modules/ 只剩 mod.rs」;反自证 3/14 注入的临时模块仍会 + # 在上面的循环里被抓到(它带 `pub use sspf_pack_` ⇒ n > 0)。 + local stray + stray="$(find "$MODULES_DIR" -maxdepth 1 -name '*.rs' ! -name 'mod.rs' -print 2>/dev/null)" + if [ -n "$stray" ]; then + bad "PACK1 平台包零业务:modules/ 出现业务适配器(应在业务仓):\n${stray}" + else + ok "PACK1 平台包零业务:modules/ 只剩 mod.rs(无 spec 两份拷贝的风险)" + fi + fi return 0 } @@ -770,57 +790,48 @@ check_ar16() { } # ---------------------------------------------------------------- AR17 -# **内核默认 feature 下不得编译期依赖 `packs/*`**(2026-11-04 标准平台包)。 +# 🔴 **平台包零业务:依赖清单里不许有任何业务包 / 选装开关**(2026-11-04 清理)。 # -# 🔴 **为什么需要**:`crates/sspf` 是给业务仓的**标准平台包**(业务仓唯一依赖)。 -# 内核若在默认 feature 下硬依赖 4 个示例包(asset / books / demo / shop), -# 业务仓依赖门面就等于把这四个包拖进自己的二进制 ⇒ 「平台包里零业务」是假话, -# 且 `cargo tree -p sspf | grep sspf-pack` 会冒出 4 行(P0 的出口判据 ①)。 -# ⇒ 示例包降为 `example-packs` feature,只有本仓 `sspf-admin` 与 `sspf-tests` 开。 +# 原判据是「示例包依赖必须 optional + default 不开 example-packs」。清理后示例包、 +# `example-packs` feature、`[features]` 段**全部退役** ⇒ 那条判据在空清单上恒真, +# 反自证也没有探针可用(实测自证 12/14 直接红)。 # -# 判据(三条,全部静态 —— 不跑 `cargo tree`,闸门必须秒级): -# ① `src/backend/Cargo.toml` 里每条 `sspf-pack-*` 依赖必须带 `optional = true`; -# ② 内核 `[features] default` 不得含 `example-packs` / `sspf-pack-*`; -# ③ 门面 `crates/sspf/Cargo.toml` 的 `default` 同样不得开 `example-packs` -# (门面自己开了 = 业务仓一依赖就被拖进示例包,绕过了 ①②)。 -# -# 🔴 **为什么不靠 `cargo tree` 兜底**:`cargo tree` 要解析依赖图(~1-3s), -# 而且它看的是**本次构建的实际 feature 组合**(workspace 里 sspf-tests 开着 -# feature ⇒ 永远有 sspf-pack-*)⇒ 判据必须是**清单层面**的。 +# 新判据(清单层面,秒级,不跑 cargo tree): +# ① 内核 / 门面 / sspf-admin / sspf-tests / workspace 五个 Cargo.toml 的 +# **非注释行**里不许出现 `sspf-pack-*` 依赖或 `example-packs` feature; +# ② `src/backend/Cargo.toml` 的 `>>>GEN:PACK_DEPS` 标记段必须恒空; +# ③ `packs/` 目录不许存在(与 AR2 互补,AR2 看依赖、这里看目录)。 +# ⇒ 业务仓只依赖门面 `sspf`,通过 `Platform::packs()` 注入,不开任何平台 feature。 check_ar17() { - local toml="$KERNEL/Cargo.toml" - [ -f "$toml" ] || { skip "AR17 内核 Cargo.toml 不存在"; return; } local hits="" + local toml="$KERNEL/Cargo.toml" + [ -f "$toml" ] || { bad "AR17 内核 Cargo.toml 不存在"; return; } - # ① 每条 pack 依赖都必须 optional - local not_optional - not_optional="$(grep -nE '^[[:space:]]*sspf-pack-[A-Za-z0-9_-]+[[:space:]]*=' "$toml" 2>/dev/null \ - | grep -vE 'optional[[:space:]]*=[[:space:]]*true' || true)" - if [ -n "$not_optional" ]; then - hits="src/backend/Cargo.toml: 示例包依赖必须 optional = true(否则业务仓被拖进示例包):"$'\n'"$(printf '%s\n' "$not_optional" | sed 's/^/ /')" + # ① 五个清单:跳过注释行(注释里讲「不许有 sspf-pack-*」是合法的) + local f h + for f in "$KERNEL/Cargo.toml" "$CRATES/sspf/Cargo.toml" \ + "$CRATES/sspf-admin/Cargo.toml" "$CRATES/tests/Cargo.toml" "$ROOT/Cargo.toml"; do + [ -f "$f" ] || continue + h="$(awk '!/^[[:space:]]*#/ && /sspf-pack-|example-packs/ {print NR": "$0}' "$f" 2>/dev/null || true)" + if [ -n "$h" ]; then + hits="${hits:+$hits$'\n'}${f#$ROOT/}: 平台仓不许有业务包依赖 / example-packs feature:$'\n'$(printf '%s\n' "$h" | sed 's/^/ /')" + fi + done + + # ② 生成段恒空 + local gen + gen="$(awk '/>>>GEN:PACK_DEPS/{f=1;next} /<</dev/null || true)" + if [ -n "$gen" ]; then + hits="${hits:+$hits$'\n'}src/backend/Cargo.toml: >>>GEN:PACK_DEPS 段必须恒空,实际:$'\n'$(printf '%s\n' "$gen" | sed 's/^/ /')" fi - # ② 内核 default 必须零包 - local kdef - kdef="$(awk '/^\[features\]/{f=1;next} /^\[/{f=0} f && /^[[:space:]]*default[[:space:]]*=/' "$toml" 2>/dev/null)" - case "$kdef" in - *example-packs*|*sspf-pack-*) - hits="${hits:+$hits$'\n'}src/backend/Cargo.toml: [features] default 不许含 example-packs / sspf-pack-*(默认 feature 必须是平台包):$kdef" ;; - esac - - # ③ 门面 default 不许开示例包 - local facade="$CRATES/sspf/Cargo.toml" - if [ -f "$facade" ]; then - local fdef - fdef="$(awk '/^\[features\]/{f=1;next} /^\[/{f=0} f && /^[[:space:]]*default[[:space:]]*=/' "$facade" 2>/dev/null)" - case "$fdef" in - *example-packs*) - hits="${hits:+$hits$'\n'}crates/sspf/Cargo.toml: 门面 default 不许开 example-packs(业务仓会跟着被拖进示例包):$fdef" ;; - esac + # ③ packs/ 目录 + if [ -d "$ROOT/packs" ]; then + hits="${hits:+$hits$'\n'}平台仓出现 packs/ 目录 ⇒ 业务包请用 sspf::Platform::packs() 注入" fi if [ -z "$hits" ]; then - ok "AR17 内核默认 feature 零业务包(示例包 optional + default 不含 example-packs)" + ok "AR17 平台包零业务:5 个 Cargo.toml 无业务包依赖 / feature,GEN 段恒空,packs/ 不存在" else bad "AR17 平台包里混进了业务包(业务仓会被拖进示例包):" printf '%s\n' "$hits" | sed 's/^/ /' @@ -947,6 +958,10 @@ TOML local caught=0 [ "$FAIL" -gt "$before" ] && caught=1 rm -rf "$tmp" + # 🔴 2026-11-04 清理:`mkdir -p packs/__arch_selftest__` 会把 `packs/` 一起造出来, + # 只删子目录会留下**空 packs/** ⇒ AR2/AR17 的零业务判据当场红。 + # ⇒ 用 rmdir(只删空目录,绝不动真文件)把探针外壳收干净。 + rmdir "$ROOT/packs" 2>/dev/null || true FAIL=$before if [ "$caught" -eq 1 ]; then echo "✅ 反自证通过:AR2 抓到了 axum 依赖" @@ -1269,29 +1284,16 @@ RS rc=1 fi - echo "── 反自证 12/14:把内核一条示例包依赖改成非 optional,AR17 必须报 ❌ ──" + echo "── 反自证 12/14:往内核塞回一条 sspf-pack 依赖,AR17 必须报 ❌ ──" # - # 🔴 **为什么自证 AR17**:它的判据是「grep 依赖行里有没有 optional」。 - # grep 的模式写错 ⇒ 永远匹配不到 ⇒ **永远"通过"**(与 AR9 同一类风险)。 + # 🔴 **2026-11-04 清理**:依赖清单里已经没有 pack 行可改 ⇒ 旧探针(去掉 + # `optional = true`)找不到锚点,自证会**假红**。改成「注入一整条硬依赖」, + # 判据仍是「AR17 对业务包依赖敏感」,锚点不再依赖示例包是否存在。 local a17toml="$KERNEL/Cargo.toml" local a17ok=0 if [ -f "$a17toml" ]; then cp "$a17toml" "$a17toml.ar17bak" - python3 - "$a17toml" <<'PY' -import re, sys -p = sys.argv[1] -s = open(p, encoding='utf-8').read() -# 只摘掉**第一行** pack 依赖的 optional(模拟「有人手改回硬依赖」) -s2, n = re.subn( - r'(?m)^(sspf-pack-[A-Za-z0-9_-]+\s*=\s*\{[^}\n]*?),\s*optional\s*=\s*true', - r'\1', - s, - count=1, -) -if n != 1: - sys.stderr.write('AR17 自证:没找到可改的 pack 依赖行\n') -open(p, 'w', encoding='utf-8').write(s2) -PY + printf '\nsspf-pack-probe = { path = "../../packs/probe" }\n' >> "$a17toml" local a17before=$FAIL check_ar17 >/dev/null 2>&1 local a17caught=0 @@ -1301,9 +1303,9 @@ PY [ "$a17caught" -eq 1 ] && a17ok=1 fi if [ "$a17ok" -eq 1 ]; then - echo "✅ 反自证通过:AR17 抓到了非 optional 的示例包依赖" + echo "✅ 反自证通过:AR17 抓到了回流的 sspf-pack 依赖" else - echo "❌ 反自证失败:AR17 没抓到非 optional 的示例包依赖 ⇒ 尺子是假的" + echo "❌ 反自证失败:AR17 没抓到回流的业务包依赖 ⇒ 尺子是假的" rc=1 fi diff --git a/scripts/check-boundary-scan.py b/scripts/check-boundary-scan.py index 9c5c22c..cfde597 100644 --- a/scripts/check-boundary-scan.py +++ b/scripts/check-boundary-scan.py @@ -43,6 +43,22 @@ MENU_FIELD_RE = { # 🔴 字符串字面量:`r#"..."#` / `r"..."` / `"..."`(普通串的转义 `\"` 不影响子串判定)。 LITERAL_RE = re.compile(r'r(#*)"(.*?)"\1|"((?:[^"\\]|\\.)*)"', re.DOTALL) +# 🔴 **防回流清单**(2026-11-04 清理):示例包已搬到技能仓,本仓业务层恒空。 +# 此时「从业务层派生」得不到任何 token ⇒ CP1 若直接放过就变成**假闸门**。 +# ⇒ 改用这份固定清单:谁把示例业务写回平台层(表名 / 面 A 前缀),立刻红。 +# 🔴 只列**不会误伤平台层**的字面量:不列 `Book` / `Product` / `DataResource` +# 这类通用词(平台层正常代码里可能出现),只列表名与带 app 的路由前缀。 +ANTI_REFLUX_TOKENS = [ + ("业务表名(示例·已迁出)", "demo_item"), + ("业务表名(示例·已迁出)", "shop_product"), + ("业务表名(示例·已迁出)", "book_shop_book"), + ("业务表名(示例·已迁出)", "asset_data_resource"), + ("业务路由前缀(示例·已迁出)", "/api/ssw/demo/"), + ("业务路由前缀(示例·已迁出)", "/api/ssw/shop/"), + ("业务路由前缀(示例·已迁出)", "/api/ssw/books/"), + ("业务路由前缀(示例·已迁出)", "/api/ssw/asset/"), +] + def strip_comments(src): """去掉 `//` 行注释与 `/* */` 块注释(保留字符串字面量里的内容)。 @@ -163,6 +179,9 @@ def business_tokens(modules_dir, packs_dir=None): for kind, rx in MENU_FIELD_RE.items(): for f in rx.finditer(body): add("业务菜单 {}".format(kind), f.group(1)) + if not tokens: + # 🔴 平台包零业务:没有业务层可派生 ⇒ 用防回流清单,尺子不失效。 + return list(ANTI_REFLUX_TOKENS) return tokens @@ -180,6 +199,11 @@ def rust_files(root): def main(argv): if len(argv) >= 2 and argv[1] == "--self-test": return self_test() + if len(argv) >= 2 and argv[1] == "--tokens": + # 给 `check-boundary.sh` 的 CP1'' 探针用:打印当前禁止清单的 token(每行一个)。 + for _kind, tok in business_tokens(os.environ.get("SSW_MODULES_DIR", ".")): + print(tok) + return 0 if len(argv) < 3: sys.stderr.write( @@ -192,9 +216,6 @@ def main(argv): # 🔴 业务包目录(可省略 ⇒ 兼容旧调用;`check-boundary.sh` 会传)。 packs_dir = os.environ.get("SSW_PACKS_DIR") or None tokens = business_tokens(modules_dir, packs_dir) - if not tokens: - sys.stderr.write("业务层没解析出任何标识符(modules_dir 有问题?)\n") - return 2 violations = [] scanned = 0 diff --git a/scripts/check-boundary.sh b/scripts/check-boundary.sh index 5a5dfc9..cc6b440 100755 --- a/scripts/check-boundary.sh +++ b/scripts/check-boundary.sh @@ -133,24 +133,12 @@ fi # **永远"通过"** ⇒ 虚假安全感(AR9 自证注释里写明过这个坑)。 # ⇒ 往新 crate 注入一个**业务表名**,必须被抓到 —— 抓不到 = 扫描面漏了。 hdr "[CP1''] 扫描面反自证(往 M6 新 crate 注入业务表名 ⇒ 必须被抓到)" +# 🔴 **2026-11-04 清理**:示例包已搬走 ⇒ 探针 token 不再从 `packs/` 派生, +# 改用扫描器的 `--tokens`(零业务时 = 防回流清单)。这样反自证仍然真能探到 +# 「扫描面覆盖 mcp-adapter」,且顺带钉住防回流清单非空(尺子不会变瞎)。 if [ -d "${MCP_ADAPTER}" ]; then CP1_PROBE="${MCP_ADAPTER}/__cp1_selftest.rs" - # 🔴 探针用**业务包真实声明的表名**(从业务层派生 ⇒ 探针本身不含硬编码清单)。 - CP1_PROBE_TOKEN="$(CP1_SCAN_PATH="${SCAN}" SSW_PACKS_DIR="${ROOT}/packs" "${PY_BIN}" - "${MODULES}" "${ROOT}/packs" <<'PYPROBE' -import os, re, sys -sys.path.insert(0, os.path.dirname(os.path.abspath(os.environ["CP1_SCAN_PATH"]))) -modules_dir, packs_dir = sys.argv[1], sys.argv[2] -spec = re.compile(r'table:\s*"([^"]+)"') -for src in [os.path.join(packs_dir, p, "src", "lib.rs") - for p in sorted(os.listdir(packs_dir)) if os.path.isdir(os.path.join(packs_dir, p))]: - if not os.path.isfile(src): - continue - m = spec.search(open(src, encoding="utf-8").read()) - if m: - print(m.group(1)) - break -PYPROBE -)" + CP1_PROBE_TOKEN="$(SSW_MODULES_DIR="${MODULES}" "${PY_BIN}" "${SCAN}" --tokens 2>/dev/null | head -1)" if [ -n "${CP1_PROBE_TOKEN}" ]; then printf 'const LEAK_PROBE: &str = "%s";\n' "${CP1_PROBE_TOKEN}" > "${CP1_PROBE}" CP1_PROBE_OUT="$(SSW_PACKS_DIR="${ROOT}/packs" "${PY_BIN}" "${SCAN}" "${MODULES}" "${MCP_ADAPTER}" 2>&1 || true)" @@ -161,17 +149,17 @@ PYPROBE no "扫描面反自证失败:往 mcp-adapter 注入 ${CP1_PROBE_TOKEN} 没被抓到 ⇒ 扫描面漏了新 crate(尺子已失效)" fi else - no "扫描面反自证失败:业务层没解析出业务表名(探针无法构造)" + no "扫描面反自证失败:防回流清单为空(探针无法构造)" fi else no "扫描面反自证失败:MCP_ADAPTER 目录不存在" fi # ---- CP1 平台层零业务标识符 ---- -hdr "[CP1] 平台层零业务标识符(扫字符串字面量;禁止清单从业务层派生)" -# 🔴 **业务层现在有两处**(批次 12 交付物 ②):`modules/*.rs`(面 A 内嵌) -# + `packs/*/src/lib.rs`(业务包)⇒ 两处都要进「禁止清单」, -# 否则包里的业务表名会从清单里消失 ⇒ 尺子变弱。 +hdr "[CP1] 平台层零业务标识符(扫字符串字面量;零业务时启用**防回流清单**)" +# 🔴 **2026-11-04 清理**:本仓业务层恒空 ⇒ 禁止清单由扫描器切成 +# `ANTI_REFLUX_TOKENS`(4 张示例表名 + 4 个面 A 前缀)。 +# 语义从「不许平台层引用本仓业务」变成「**不许示例业务回流平台层**」。 # 🔴 **M2 起平台层真源在 `crates/sspf-core/src/`** ⇒ 它必须进扫描面(否则扫空壳)。 SCAN_OUT="$(SSW_PACKS_DIR="${ROOT}/packs" "${PY_BIN}" "${SCAN}" "${MODULES}" "${PLATFORM_CORE}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} ${LOWCODE_EXEC:+"${LOWCODE_EXEC}"} ${MCP_ADAPTER:+"${MCP_ADAPTER}"} "${SRC}/routes.rs" "${SRC}/main.rs" "${BOOTSTRAP}" "${SRC}/compat.rs" 2>&1)" if [ "$?" -eq 0 ]; then diff --git a/scripts/check-citations-scan.py b/scripts/check-citations-scan.py index 318102e..eff483c 100644 --- a/scripts/check-citations-scan.py +++ b/scripts/check-citations-scan.py @@ -3,7 +3,7 @@ """check-citations-scan —— 文档引文(`路径:行号`)校验扫描器。 🔴 为什么存在: - 本仓的文档(`SKILL.md` / `MIGRATION.md` / `JNPF_SOURCE_AUDIT.md` / `PERMISSION.md` …) + 仓根 + docs/ 的文档(技能向说明归技能仓 `ssw-jnpf-lite-rust`) 大量引用源码位置,语法有三种: `文件.ext:行号` 单行 `文件.ext:起-止` 区间 @@ -53,11 +53,10 @@ SKIP_DIRS = { ".workbuddy", ".superpowers", "coverage", ".pytest_cache", ".mypy_cache", } -# 文档语料:仓根 *.md + docs/** + references/**(不含 template-boot-jnpf —— 那是另一份骨架) +# 文档语料:仓根 *.md + docs/**(技能资产文档已迁出本仓,归技能仓 ssw-jnpf-lite-rust) DOC_GLOBS = ( ("", "*.md"), ("docs", "**/*.md"), - ("references", "*.md"), ) # 承认的文件后缀(决定什么算「一条引文」) diff --git a/scripts/check-contract-scan.py b/scripts/check-contract-scan.py index 727fb26..b54b7e6 100644 --- a/scripts/check-contract-scan.py +++ b/scripts/check-contract-scan.py @@ -1261,7 +1261,7 @@ def analyze(contract_path, src_dir=None, packs_dir=None, code_snapshot=None): # ---- CC10 官方端点台账 ↔ 代码真实路由(双向)---- # # 🔴 为什么要它:面 B 的「做了多少」原先只有**尺子的断言数**(18/18)这一个信号, - # 而**官方端点全表**(JNPF_SOURCE_AUDIT.md §4)是**散文表格** ⇒ 官方端点做没做、 + # 而**官方端点全表**(技能仓 JNPF_SOURCE_AUDIT.md §4)是**散文表格** ⇒ 官方端点做没做、 # 做到什么程度,**没有机器可读的账** ⇒ 「覆盖率」只能靠人读散文。 # 本检查把契约附录 A 的 [OFFICIAL](机器可读)当成**账本**, # 与代码里**真实注册**的路由双向对账,并打印覆盖 N/M。 @@ -1449,8 +1449,10 @@ def self_test(contract=None, src_dir=None, packs_dir=None): "A\tGET\t/api/ssw/sys/User/List\t登录\tplatform\n", 1) def bad_owner(t): - return t.replace("A\tGET\t/api/ssw/demo/DemoItem/List\t登录\tdemo\n", - "A\tGET\t/api/ssw/demo/DemoItem/List\t登录\tplatform\n", 1) + # 🔴 2026-11-04 清理:示例业务行已迁出契约 ⇒ 锚点换成**平台行**, + # 反向篡改(platform ⇒ 业务代号)同样能证 CC5 的归属层对账。 + return t.replace("A\tGET\t/api/health\t无\tplatform\n", + "A\tGET\t/api/health\t无\tdemo\n", 1) def bad_face(t): # 🔴 **动态取现值再减 1**(别写死数字):加端点会让 [FACE] 的 A 条数变化, @@ -1480,26 +1482,25 @@ def self_test(contract=None, src_dir=None, packs_dir=None): "面 B 已落地:PageListVO 形状\n", "", 1) # ---- 包路由的三类漂移(批次 12:`packs/*` 进了代码侧)---- + # 🔴 **2026-11-04 清理**:示例包(asset/demo/shop/books)已搬到技能仓, + # 契约 `[ENDPOINT]` 里不再有包路由 ⇒ 下面三条用例的锚点换成**面 B 平台行**。 + # 漂移类型不变(守卫形状 / 漏登记 / owner 串线)⇒ CC6/CC2/CC5 仍被真自证。 def pack_guard_wrong(t): - # 包的 3 条面 B 路由里,把守卫写成面 A 的菜单路径(**最容易犯的错**: - # 「两套守卫并存」记混 ⇒ 集成时权限判据错 ⇒ 而且**静默**) + # 把守卫写成面 A 的菜单路径形状(两套守卫记混 ⇒ 静默的权限判据错) return t.replace( - "B\tGET\t/api/asset/DataResource\tpermission.asset.dataResource\tasset\n", - "B\tGET\t/api/asset/DataResource\tasset/DataResource\tasset\n", 1) + "B\tGET\t/api/permission/Users\tpermission.user\tplatform\n", + "B\tGET\t/api/permission/Users\tsystem/User\tplatform\n", 1) def pack_drop_row(t): - # 包声明了 DELETE,但契约里没登记(生成段被手删 / 同步没跑) + # 代码里有这条面 B 路由,但契约里没登记(生成段被手删 / 同步没跑) return t.replace( - "B\tDELETE\t/api/asset/DataResource/{id}\t" - "permission.asset.dataResource\tasset\n", "", 1) + "B\tGET\t/api/permission/Role\tpermission.role\tplatform\n", "", 1) def pack_owner_wrong(t): - # 包路由的 owner 写成 platform(复制粘贴时的经典手误)⇒ 归属层串线 + # owner 串线(复制粘贴时的经典手误)⇒ CC5 return t.replace( - "B\tDELETE\t/api/asset/DataResource/{id}\t" - "permission.asset.dataResource\tasset\n", - "B\tDELETE\t/api/asset/DataResource/{id}\t" - "permission.asset.dataResource\tplatform\n", 1) + "B\tGET\t/api/permission/Role\tpermission.role\tplatform\n", + "B\tGET\t/api/permission/Role\tpermission.role\tdemo\n", 1) cases.append(("契约多一条端点", add_row, "CC3")) cases.append(("契约少一条端点", drop_row, "CC2")) @@ -1510,11 +1511,11 @@ def self_test(contract=None, src_dir=None, packs_dir=None): cases.append(("台账把已实现的端点说成未实现", off_says_absent, "CC10")) cases.append(("台账写了代码里没有的端点", off_fake_path, "CC10")) cases.append(("面 B 路由没记账", off_drop_row, "CC10")) - # 🔴 下面三条是**包路由专属**的漂移:批次 12 之后包路由也会出现在 [ENDPOINT] 里, - # 如果尺子对它们不敏感,等于「加包 = 免检」。 - cases.append(("包路由的守卫写成了面 A 形状", pack_guard_wrong, "CC6")) - cases.append(("包路由没登记进契约", pack_drop_row, "CC2")) - cases.append(("包路由的 owner 写错", pack_owner_wrong, "CC5")) + # 🔴 下面三条原为「包路由专属」漂移;零业务清理后锚点改到面 B 平台行, + # 但漂移类型与 CC 编号不变 ⇒ 尺子对「守卫 / 漏登记 / 归属层」仍被真自证。 + cases.append(("路由守卫写成了面 A 形状", pack_guard_wrong, "CC6")) + cases.append(("路由没登记进契约", pack_drop_row, "CC2")) + cases.append(("路由的 owner 写错", pack_owner_wrong, "CC5")) failed = 0 for name, fn, expect in cases: diff --git a/scripts/check-module.sh b/scripts/check-module.sh index 5bd4b7c..72e38d5 100755 --- a/scripts/check-module.sh +++ b/scripts/check-module.sh @@ -144,6 +144,52 @@ fi # # 🔴 **新增业务模块时**:在契约 `[MODULE]` 加一行 + 在 `[MENU]` 加一行 ⇒ 本脚本自动覆盖它。 # (本脚本**不再硬编码**任何业务标识符 ⇒ 加模块不用改脚本。) +# ---------------------------------------------------------------- 零业务目标态 +# +# 🔴 **2026-11-04 清理**:示例业务模块(demo / shop / books / asset)已整体搬到 +# 技能仓 `ssw-jnpf-lite-rust`,本仓契约 `[MODULE]` 段恒空 ⇒ 这把「业务模块 +# 10 接触点」尺子**没有被测对象**。直接放过会变成假闸门 ⇒ 换成三条 +# **防回流断言**:只要示例业务以任何形式回流,这里必须红。 +# +# 🔴 **自证在分支条件里**:只要契约 `[MODULE]` 出现一行数据, +# `${#TARGETS[@]}` 就 > 0 ⇒ 立刻回到下面的完整检查(不会静默跳过)。 +if [ "${#TARGETS[@]}" -eq 0 ]; then + echo + echo "── 平台包零业务:[MODULE] 段无业务模块 ⇒ 改跑防回流三条 ──" + PASS=0; FAIL=0 + ok() { echo " ✅ $1"; PASS=$((PASS+1)); } + no() { echo " ❌ $1"; FAIL=$((FAIL+1)); } + + if [ ! -d "${ROOT}/packs" ]; then + ok "packs/ 不存在 ⇒ 示例业务包未回流平台仓" + else + no "packs/ 又出现了 ⇒ 业务包属于业务仓,请用 sspf::Platform::packs() 注入" + fi + + MOD_RS="$(find "${BACKEND}/src/modules" -maxdepth 1 -name '*.rs' ! -name 'mod.rs' -print 2>/dev/null)" + if [ -z "${MOD_RS}" ]; then + ok "modules/ 下没有业务适配器 ⇒ 面 A 业务路由未回流内核" + else + no "modules/ 出现业务适配器:${MOD_RS}" + fi + + if [ ! -s "${ROOT}/docs/contract.md" ] || [ -z "${CE_ALL_TARGETS}" ]; then + ok "契约 [MODULE] 无数据行 ⇒ 分支条件本身即自证(加一行就会回到完整检查)" + else + no "契约 [MODULE] 有数据行却进了零业务分支 ⇒ 尺子逻辑坏了" + fi + + echo + echo "── 总结 ──" + echo "PASS=${PASS} FAIL=${FAIL}" + if [ "${FAIL}" -eq 0 ]; then + echo "全 ✅ 平台包零业务,示例业务未回流" + exit 0 + fi + echo "有 ❌,请修掉回流" + exit 1 +fi + T_COUNT=${#TARGETS[@]} T_APP=(); T_ENT=(); T_TABLE=(); T_ROUTE=(); T_SEED=(); T_MK=(); T_API=(); T_FILE=() for T in "${TARGETS[@]}"; do @@ -596,7 +642,7 @@ done # -------- 全局红线(与具体模块无关,但一样会让闸门失真)-------- # -# 🔴 **面 A / 面 B 的判别头是 `Vue-Version: 3`**(见 JNPF_COMPAT_SURFACE.md §2.2): +# 🔴 **面 A / 面 B 的判别头是 `Vue-Version: 3`**(见 技能仓 JNPF_COMPAT_SURFACE.md §2.2): # 官方 JNPF 前端**必带** `Jnpf-Origin: pc` / `App-Code` / `Vue-Version: 3` 三个头, # 而本仓前端**只带前两个**(`App-Code: sswflow` + `Jnpf-Origin: pc`,与官方同款) # ⇒ 三个头里**只有 `Vue-Version` 是本仓前端唯一不发的** ⇒ 判别只能用它。 diff --git a/scripts/check-naming.sh b/scripts/check-naming.sh index 78e0ca6..082fca5 100755 --- a/scripts/check-naming.sh +++ b/scripts/check-naming.sh @@ -24,7 +24,7 @@ # NM4 代码注释里的提及 ⇒ 🟡 报数(技术债,逐步清零) # `--strict` 时升级为 🔴 # -# 🔴 为什么注释不一刀切:`JNPF_SOURCE_AUDIT.md` 这类文档整篇都是基线平台源码分析, +# 🔴 为什么注释不一刀切:`技能仓 JNPF_SOURCE_AUDIT.md` 这类文档整篇都是基线平台源码分析, # 注释里写「官方 `VisualAiServiceImpl.form()`」是**出处**,不是品牌露出。 # 一刀切会逼人删掉溯源信息,反而降低可维护性。⇒ 量化 + 逐步替换成「基线平台」。 diff --git a/scripts/new-pack-gen.py b/scripts/new-pack-gen.py deleted file mode 100755 index d442ccc..0000000 --- a/scripts/new-pack-gen.py +++ /dev/null @@ -1,1011 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -"""new-pack-gen —— 「加一个业务包」的生成器(`scripts/new-pack.sh` 的实现)。 - -🔴 **为什么存在**(HANDOFF §3 批次 12.5): - 批次 12 把「spec 搬进 `packs//`」之后,加一个业务模块的成本从「改 6~8 处」 - 降到了「写一个包目录」。但**写那个包目录仍然是手抄**:`Cargo.toml` / - `pack.toml` / `schema/*.sql` / `src/lib.rs` / `modules/.rs` 五个文件, - 每个都有「抄漏一处就不对」的形状(漏 `f_tenant_id`、漏守卫、漏 `DDLS` 条目…)。 - ⇒ 本脚本把这五个文件**按真源生成**,再让 `pack-sync.py` 把内核接线补齐。 - -🔴 **真源是什么**:**业务决策**(app / 实体名 / 中文名 / 列清单)。 - 其余全部是推导: - - 表名 `_`;`json_key` = 列名去 `f_` 转驼峰; - - 菜单 `url_address` = `/`,`en_code` = `permission..` - —— 两者**必须**与 spec 的 `module_key`、前端 Route、守卫编码一致(三处一字不差); - - `DDLS` 的键 = 表名,值 = `include_str!` 的 DDL。 - -🔴 **不猜**:列清单要么显式给(`--columns`),要么从一份 DDL 读(`--from-ddl`)。 - 两者都没有 ⇒ 拒绝生成(空的业务表没有意义,而且会掩盖「忘了给列」)。 - -用法(一般通过 `scripts/new-pack.sh` 调用,它负责找 python 与参数透传): - - python3 scripts/new-pack-gen.py --name "中文名" \\ - --columns "name:VARCHAR(200),price:DECIMAL(18,2),memo:TEXT" \\ - [--table <物理表>] [--from-ddl ] [--sort <菜单排序>] \\ - [--with-frontend] [--dry-run] [--force] - -退出码:0 生成完成 / 2 前置不满足(已存在 / 参数非法 / 列清单空) -""" - -import io -import os -import re -import subprocess -import sys - -HERE = os.path.dirname(os.path.abspath(__file__)) -ROOT = os.path.dirname(HERE) -PACKS_DIR = os.path.join(ROOT, "packs") -MODULES_DIR = os.path.join(ROOT, "src", "backend", "src", "modules") -SCHEMA_SQL = os.path.join(ROOT, "src", "backend", "db", "schema.sql") - -# 🔴 与 `bootstrap.rs` 的 `CONTRACT_VERSION` 同一口径(包的 `kernel_req` 校验它)。 -KERNEL_REQ = ">=0.4,<0.5" -# 🔴 与 `rust-toolchain.toml` 的 `channel` 一致(L3 动态库要求内核与插件同一 rustc)。 -TOOLCHAIN = "1.95.0" - -# 物理表**必带**的平台列(顺序 = 响应 JSON 的键序,与 asset 一致)。 -# 🔴 `f_tenant_id` **不许省** —— 官方 `base_*` 表全部带它,且参与复合主键。 -PLATFORM_COLUMNS = [ - {"col": "f_id", "ddl": "f_id VARCHAR(50) NOT NULL", "default": None, "numeric": False}, - {"col": "f_creator_user_id", "ddl": "f_creator_user_id VARCHAR(50)", "default": None, "numeric": False}, - {"col": "f_creator_time", "ddl": "f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE", "default": None, "numeric": False}, - {"col": "f_delete_mark", "ddl": "f_delete_mark INTEGER DEFAULT 0", "default": "0", "numeric": False}, - {"col": "f_tenant_id", "ddl": "f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL", "default": "0", "numeric": False}, -] - -# 数值类型 ⇒ `numeric: true`(决定 body 里的值是原样拼 SQL 还是当字符串转义)。 -NUMERIC_TYPES = ( - "DECIMAL", "NUMERIC", "MONEY", "INT", "INTEGER", "BIGINT", "SMALLINT", - "TINYINT", "REAL", "DOUBLE", "FLOAT", -) - - -class GenError(Exception): - """前置不满足(参数非法 / 已存在 / 列清单空)。""" - - -# ---------------------------------------------------------------- 小工具 - -def die(msg): - sys.stderr.write("new-pack: %s\n" % msg) - raise SystemExit(2) - - -def snake(name): - """`DataResource` → `data_resource`(用于表名 / 函数名)。""" - out = [] - for i, ch in enumerate(name): - if ch.isupper() and i > 0: - out.append("_") - out.append(ch.lower()) - return "".join(out) - - -def upper_snake(name): - """`DataResource` → `DATA_RESOURCE`(用于常量名)。""" - return snake(name).upper() - - -def json_key_of(col): - """列名去 `f_` + 下划线转驼峰(`f_register_time` → `registerTime`)。 - - 🔴 **必须与 `db::column_to_json_key` 逐字一致** —— 不一致 ⇒ 投影别名与 - body 键对不上,而且**静默**(接口 200、字段是 null)。 - `modules/mod.rs` 的 `every_json_key_matches_the_contract_mapping` 钉住这条。 - """ - s = col[2:] if col.startswith("f_") else col - parts = s.split("_") - return parts[0] + "".join(p[:1].upper() + p[1:] for p in parts[1:] if p) - - -def read(path): - with io.open(path, encoding="utf-8") as fh: - return fh.read() - - -def write(path, text): - d = os.path.dirname(path) - if d and not os.path.isdir(d): - os.makedirs(d) - with io.open(path, "w", encoding="utf-8") as fh: - fh.write(text) - - -# ---------------------------------------------------------------- 列清单 - -def split_columns_arg(raw): - """按**括号外的逗号**切分列清单。 - - 🔴 直接 `raw.split(",")` 会把 `DECIMAL(18,2)` 切成 `DECIMAL(18` + `2)` - —— 这是真踩过的坑(报错还很难懂:`列 '2)' 缺类型`)。 - """ - out, cur, depth = [], [], 0 - for ch in raw: - if ch == "(": - depth += 1 - elif ch == ")": - depth = max(0, depth - 1) - if ch == "," and depth == 0: - out.append("".join(cur)) - cur = [] - else: - cur.append(ch) - out.append("".join(cur)) - return [s.strip() for s in out if s.strip()] - - -def parse_columns_arg(raw): - """`"name:VARCHAR(200),price:DECIMAL(18,2)"` ⇒ 列定义列表。 - - 🔴 **列名自动补 `f_` 前缀**(官方习惯)—— 但你写 `f_name` 也不会变成 `f_f_name`。 - 🔴 **类型必填**:没有类型的列在 PG 里建不出来;而且「猜类型」= 猜错就是 - 静默的精度丢失(`DECIMAL` 变 `VARCHAR`)⇒ 宁可拒绝。 - """ - cols = [] - for item in split_columns_arg(raw): - if ":" not in item: - raise GenError( - "列 %r 缺类型(写成 `name:VARCHAR(200)`)—— 不猜类型:" - "猜错会静默丢精度" % item) - name, typ = item.split(":", 1) - name = name.strip() - typ = typ.strip() - if not name or not typ: - raise GenError("列 %r 形状不对(要 `名字:类型`)" % item) - if not name.startswith("f_"): - name = "f_" + name - if not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", name): - raise GenError("列名 %r 不是合法标识符(只允许字母/数字/下划线)" % name) - cols.append(make_column(name, typ)) - return cols - - -def make_column(col, typ): - """列名 + 类型 ⇒ 列定义(`ddl` 里带上 DEFAULT / NOT NULL 修饰)。""" - first = re.split(r"[\s(]", typ.strip(), maxsplit=1)[0].upper() - return { - "col": col, - "ddl": "%s %s" % (col, typ.strip()), - "default": "0" if first in NUMERIC_TYPES else None, - "numeric": first in NUMERIC_TYPES, - } - - -def parse_ddl(path, table): - """从一份已有 DDL 里读出 `table` 的列 ⇒ 列定义列表(**只取列名 + 类型**)。 - - 🔴 **明确丢掉的东西**:索引 / 唯一约束 / 外键 / 注释 / 表级约束。 - 本函数的产出会被**重新排版**成包的 `schema/001_init.sql` - ⇒ 丢掉的东西会**显式打印**出来,不静默吞掉。 - """ - text = read(path) - pat = re.compile( - r"CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([A-Za-z_][\w]*)\s*\(([\s\S]*?)\n\s*\);", - re.I, - ) - found = None - for m in pat.finditer(text): - if table and m.group(1) != table: - continue - found = m - break - if found is None: - raise GenError( - "在 %s 里找不到表 %s 的 `CREATE TABLE … (…);`\n" - " ⇒ 用 `--table <表名>` 指定,或者改用 `--columns` 直接给列清单。" - % (path, table or "(任意)")) - - table = found.group(1) - skipped = [] - cols = [] - for line in found.group(2).split("\n"): - line = line.strip().rstrip(",").strip() - if not line: - continue - if re.match(r"(?i)^(primary|unique|constraint|foreign|check|key|index)\b", line): - skipped.append(line) - continue - m = re.match(r'^"?([A-Za-z_][\w]*)"?\s+(\S.*)$', line) - if not m: - skipped.append(line) - continue - cols.append(make_column(m.group(1), m.group(2).strip())) - - if not cols: - raise GenError("%s 里表 %s 一个列都没解析出来" % (path, table)) - return table, cols, skipped - - -def merge_columns(business): - """业务列 + 平台列 ⇒ 完整列清单(`f_id` 在最前,平台列在最后)。 - - 🔴 **业务列里不许出现平台列名**(`f_id` / `f_tenant_id` …)—— - 重复定义会让 DDL 直接报错;更糟的是「业务自己建了个 f_id 但类型不对」。 - """ - plat_names = {c["col"] for c in PLATFORM_COLUMNS} - seen = set() - clean = [] - for c in business: - if c["col"] in plat_names: - raise GenError( - "列 %s 是平台列(由 new-pack 自动生成)⇒ 从 `--columns` 里去掉它" % c["col"]) - if c["col"] in seen: - raise GenError("列 %s 重复" % c["col"]) - seen.add(c["col"]) - clean.append(c) - - head = [PLATFORM_COLUMNS[0]] # f_id - tail = PLATFORM_COLUMNS[1:] # 审计列 + 软删 + 租户 - return head + clean + tail - - -# ---------------------------------------------------------------- 渲染 - -def spec_columns_block(cols): - out = [] - for c in cols: - d = 'Some("%s")' % c["default"] if c["default"] is not None else "None" - out.append( - ' ColumnSpec { column: "%s", json_key: "%s", default: %s, numeric: %s },' - % (c["col"], json_key_of(c["col"]), d, "true" if c["numeric"] else "false") - ) - return "\n".join(out) - - -def numeric_columns_literal(cols): - names = ['"%s"' % c["col"] for c in cols if c["numeric"]] - return "&[%s]" % ", ".join(names) - - -def ddl_block(table, cols): - lines = [" %s," % c["ddl"] for c in cols] - lines.append(" PRIMARY KEY (f_id, f_tenant_id)") - return ( - "-- @@TABLE@@ —— 业务表(**业务包自带**,不是平台表)。\n" - "--\n" - "-- 🔴 **DDL 跟着包走**:本文件由 `packs/@@APP@@/src/lib.rs` 的 `include_str!`\n" - "-- 编译进二进制 ⇒ 内核启动时按包顺序幂等执行\n" - "-- ⇒ **不要**再手抄进 `src/backend/db/schema.sql`。\n" - "--\n" - "-- 🔴 **【集成期友好性】列名按官方规范**:`f_` 前缀 / `f_id VARCHAR(50)`(36 位 UUID)\n" - "-- / `f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL` —— 官方 `base_*` 表全部带它,\n" - "-- **单租户也不许省**(缺这列 ⇒ 集成时导不进官方)。\n" - "--\n" - "-- 🔴 本文件**只许建本包自己的表**,不许建 `base_*`(装载器会拦 `DdlTouchesBaseTable`)。\n" - "\n" - "CREATE TABLE IF NOT EXISTS @@TABLE@@ (\n" - "%s\n" - ");\n" % "\n".join(lines) - ) - - -def render(text, tokens): - for k, v in tokens.items(): - text = text.replace("@@%s@@" % k, v) - left = re.findall(r"@@[A-Z_]+@@", text) - if left: - raise GenError("模板有未替换的占位符:%s" % ", ".join(sorted(set(left)))) - return text - - -# ---------------------------------------------------------------- 模板 - -PACK_CARGO_TPL = """[package] -name = "sspf-pack-@@APP@@" -version.workspace = true -edition.workspace = true -rust-version.workspace = true - -# 🔴 AR2:业务包只允许依赖 sspf-sdk(+ serde)。 -# 出现 axum / tokio / pglite ⇒ `scripts/check-arch.sh` 直接红。 -# 这是「整目录可搬走」的技术保证 —— 包的**路由是声明**,注册由内核做。 -[dependencies] -sspf-sdk = { path = "../../crates/sspf-sdk" } -""" - -PACK_TOML_TPL = """# @@APP@@ 业务包清单 —— 与 `PLAN.md` §5.1 的格式一致。 -# -# 🔴 本文件不是给 cargo 读的,是给 `sspf pack export/import` 与内核装载器读的。 -# 🔴 **改完要跑**(否则内核里的清单快照不更新 ⇒ `pack-sync --check` 会红): -# python3 scripts/pack-sync.py - -[pack] -app_code = "@@APP@@" -name = "@@NAME@@" -version = "1.0.0" -kernel = "@@KERNEL@@" # 内核兼容区间(不匹配则拒载) -migratable = true # 允许导出到基线平台 - -[pack.compat] -baseline = "v7" # 兼容基线版本 -frontend = "vue3" # 前端族(决定表单 JSON 方言) -tenant = false # 本期单租户 - -# 物理表:name = 本平台表名;baseline_table = 基线平台上的表名(允许不同,导出时映射) -[[pack.tables]] -name = "@@TABLE@@" -ddl = "schema/001_init.sql" -baseline_table = "@@TABLE@@" - -[pack.metadata] -# 低代码元数据(与基线平台 visualdev 同构的 JSON)。本包是「手写 spec」形态 ⇒ 留空。 -forms = [] -models = [] -menus = [] -flows = [] - -[pack.build] -# 本包带手写 Rust(`src/lib.rs`)⇒ 链进内核。 -# 🔴 kind 不是 "none" 时必须补 `toolchain`,且与 `rust-toolchain.toml` 一致。 -kind = "static" -toolchain = "@@TOOLCHAIN@@" -""" - -PACK_LIB_TPL = '''//! @@APP@@ —— 业务包:@@ENTITY@@(物理表 `@@TABLE@@`)。 -//! -//! 🔴 **本文件是 spec 的单一真源** —— 内核的 `src/backend/src/modules/@@APP@@.rs` -//! 只做 `pub use` 转发(面 A 适配器),不再保留第二份拷贝。 -//! -//! 🔴 **路由用官方 JNPF 形状**(RESTful:`GET/POST /api/@@APP@@/@@ENTITY@@`、 -//! `DELETE /api/@@APP@@/@@ENTITY@@/{id}`)—— **不是**面 A 的 -//! `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`(那是本仓自造的约定, -//! 集成到官方 JNPF 时**全部作废**)。 -//! -//! 🔴 **DDL 跟着包走**:`schema/001_init.sql` 用 `include_str!` 编译进二进制 -//! ⇒ 内核启动时幂等执行 ⇒ 不手抄进 `db/schema.sql`。 - -use sspf_sdk::{ - BusinessPack, ColumnSpec, EntitySpec, HttpMethod, Manifest, MenuSpec, PackRoute, RouteAction, - RouteGuard, -}; - -/// 🔴 **包的统一 DDL 出口**(`表名 → DDL 文本`)—— 内核**只认这一种写法**。 -/// -/// 内核的 `packs_gen.rs` 是生成的,生成器按 `sspf_pack_::DDLS` 取值 -/// ⇒ 每个包都用同一个常量名 ⇒ 加包不用改内核。 -/// `include_str!` 把 DDL **编译进二进制** ⇒ 单二进制部署,运行期不需要 `packs/` 目录。 -pub const DDLS: &[(&str, &str)] = &[("@@TABLE@@", include_str!("../schema/001_init.sql"))]; - -/// @@ENTITY@@ 的列清单(**顺序 = 响应 JSON 的键序**)。 -/// -/// 🔴 前 1 列必须是 `f_id`;末 4 列是平台列(审计 / 软删 / 租户)。 -/// 🔴 `f_tenant_id` **不许省** —— 官方 `base_*` 表全部带它,且参与复合主键 -/// `(f_id, f_tenant_id)`;单租户也不许省 ⇒ 集成时缺这列就导不进官方。 -const @@UPPER@@_COLUMNS: &[ColumnSpec] = &[ -@@SPEC_COLUMNS@@ -]; - -/// @@ENTITY@@ 的 spec。 -pub const @@UPPER@@_SPEC: EntitySpec = EntitySpec { - app_code: "@@APP@@", - entity: "@@ENTITY@@", - table: "@@TABLE@@", - // 🔴 `module_key` 必须 == 菜单 `url_address` == 前端 Route path(三处一字不差)。 - module_key: Some("@@URL@@"), - columns: @@UPPER@@_COLUMNS, - numeric_columns: @@NUMERIC@@, - // 非 demo 表 ⇒ `body.creatorUserId || 'admin'`。 - creator_fixed: None, -}; - -/// 本包的内置菜单。 -/// -/// 🔴 `url_address` 必须与 [`@@UPPER@@_SPEC`] 的 `module_key` 一字不差 —— -/// 面 A 的菜单守卫靠它命中。 -pub const @@UPPER@@_MENU: MenuSpec = MenuSpec { - id: "@@MENU_ID@@", - full_name: "@@NAME@@", - // 🔴 面 B 的点权限判据 `f_en_code`:路由的守卫必须与它**一字不差** - // (不一致 ⇒ 运行时查菜单查不到 ⇒ 走「未映射放行」⇒ 越权且静默)。 - en_code: "@@EN_CODE@@", - url_address: "@@URL@@", - parent_id: "0", - menu_type: 2, - icon: Some("app"), - sort_code: @@SORT@@, - // 🔴 字面量而非引用内核常量:业务包不许依赖内核(AR2)。 - system_en_code: "mainSystem", -}; - -/// 包清单(与 `pack.toml` 的 `[pack]` 段一致)。 -const MANIFEST: Manifest = Manifest { - app_code: "@@APP@@", - name: "@@NAME@@", - version: "1.0.0", - kernel_req: "@@KERNEL@@", - migratable: true, -}; - -// ---------------------------------------------------------------- 路由声明 -// -// 🔴 **官方 CRUD 的形状是 RESTful**(2026-11-02 实测官方 controller: -// `/xxx/Save` 仅 4 条特例、`/xxx/Delete` **0 条**): -// 列表 `GET /api/{模块}/{资源}`、新建 `POST …`、改 `PUT …/{id}`、删 `DELETE …/{id}`。 - -/// `GET /api/@@APP@@/@@ENTITY@@` —— 列表。 -pub const @@UPPER@@_LIST_ROUTE: PackRoute = PackRoute { - path: "/api/@@APP@@/@@ENTITY@@", - method: HttpMethod::Get, - entity: "@@ENTITY@@", - action: RouteAction::List, - guard: RouteGuard::EnCode("@@EN_CODE@@"), -}; - -/// `POST /api/@@APP@@/@@ENTITY@@` —— 新建 / 更新(body 里带 `id` 就是更新)。 -pub const @@UPPER@@_SAVE_ROUTE: PackRoute = PackRoute { - path: "/api/@@APP@@/@@ENTITY@@", - method: HttpMethod::Post, - entity: "@@ENTITY@@", - action: RouteAction::Save, - guard: RouteGuard::EnCode("@@EN_CODE@@"), -}; - -/// `DELETE /api/@@APP@@/@@ENTITY@@/{id}` —— 软删。 -pub const @@UPPER@@_DELETE_ROUTE: PackRoute = PackRoute { - path: "/api/@@APP@@/@@ENTITY@@/{id}", - method: HttpMethod::Delete, - entity: "@@ENTITY@@", - action: RouteAction::Delete, - guard: RouteGuard::EnCode("@@EN_CODE@@"), -}; - -/// 本包声明的全部路由。 -pub const @@UPPER@@_ROUTES: &[PackRoute] = &[ - @@UPPER@@_LIST_ROUTE, - @@UPPER@@_SAVE_ROUTE, - @@UPPER@@_DELETE_ROUTE, -]; - -/// @@NAME@@ 业务包。 -/// -/// 🔴 **类型名固定为 `Pack`** —— 内核的 `src/backend/src/packs_gen.rs` 是**生成**的, -/// 生成器按 `sspf_pack_::Pack` 拼路径 ⇒ 每个包都用同一个名字。 -pub struct Pack; - -impl BusinessPack for Pack { - fn manifest(&self) -> &'static Manifest { - &MANIFEST - } - - fn entities(&self) -> &'static [EntitySpec] { - &[@@UPPER@@_SPEC] - } - - fn menus(&self) -> &'static [MenuSpec] { - &[@@UPPER@@_MENU] - } - - fn routes(&self) -> &'static [PackRoute] { - @@UPPER@@_ROUTES - } -} - -#[cfg(test)] -mod tests { - use super::*; - - /// 🔴 三处一致:`module_key` == `menu.url_address`(第三处是前端 Route,本包管不到)。 - /// 不一致的后果是**静默放行**(菜单未映射 ⇒ 守卫不拦),不会报错。 - #[test] - fn module_key_matches_menu_url_address() { - assert_eq!( - @@UPPER@@_SPEC.module_key, - Some(@@UPPER@@_MENU.url_address) - ); - } - - /// 列名全部 `f_` 前缀,且主键是 `f_id`。 - #[test] - fn columns_are_prefixed_and_have_id() { - assert_eq!(@@UPPER@@_COLUMNS[0].column, "f_id"); - for c in @@UPPER@@_COLUMNS { - assert!(c.column.starts_with("f_"), "列名必须 f_ 前缀: {}", c.column); - } - } - - /// `json_key` 必须是列名去 `f_` 前缀后的 camelCase。 - #[test] - fn json_keys_are_camel_case_without_prefix() { - for c in @@UPPER@@_COLUMNS { - let stripped = c.column.trim_start_matches("f_"); - let mut expect = String::new(); - let mut up = false; - for ch in stripped.chars() { - if ch == '_' { - up = true; - } else if up { - expect.extend(ch.to_uppercase()); - up = false; - } else { - expect.push(ch); - } - } - assert_eq!(c.json_key, expect, "json_key 与列名不匹配: {}", c.column); - } - } - - /// numeric 标记与 `numeric_columns` 必须一致(否则金额会被当字符串转义)。 - #[test] - fn numeric_columns_matches_column_flags() { - let flagged: Vec<&str> = @@UPPER@@_COLUMNS - .iter() - .filter(|c| c.numeric) - .map(|c| c.column) - .collect(); - assert_eq!(flagged, @@UPPER@@_SPEC.numeric_columns); - } - - /// 包清单与 spec 的 app_code 必须一致(否则内核按 app 路由会找不到)。 - #[test] - fn manifest_app_code_matches_spec() { - assert_eq!(Pack.manifest().app_code, @@UPPER@@_SPEC.app_code); - assert_eq!(Pack.entities().len(), 1); - assert_eq!(Pack.menus().len(), 1); - assert_eq!(Pack.routes().len(), 3); - } - - /// 🔴 **路由必须是官方形状** —— 面 A 的 `/api/ssw/...` 集成时全部作废。 - #[test] - fn routes_use_official_shape_not_face_a() { - for r in Pack.routes() { - assert!(r.path.starts_with("/api/"), "路由必须以 /api/ 开头: {}", r.path); - assert!( - !r.path.starts_with("/api/ssw/"), - "🔴 路由不许用面 A 的 /api/ssw/...(集成时作废): {}", - r.path - ); - assert!(!r.path.ends_with("/Save"), "官方没有 /Save 端点: {}", r.path); - assert!(!r.path.ends_with("/Delete"), "官方没有 /Delete 端点: {}", r.path); - } - let del = Pack - .routes() - .iter() - .find(|r| r.action == RouteAction::Delete) - .expect("必须有删除路由"); - assert!(del.path.contains("{id}"), "删除路由必须带 {{id}}: {}", del.path); - } - - /// 🔴 **路由的 entity 必须指向本包声明的实体** —— 否则装配时拿到空 spec - /// ⇒ 路由注册了但永远查不到表 ⇒ **静默 404**。 - #[test] - fn routes_point_at_declared_entities() { - for r in Pack.routes() { - assert!( - Pack.entities().iter().any(|e| e.entity == r.entity), - "路由 {} 指向未声明的实体 {}", - r.path, - r.entity - ); - } - } - - /// 🔴 动作与方法的对应被钉死(内核的 `crud_router` 按这个分派)。 - #[test] - fn route_actions_match_methods() { - for r in Pack.routes() { - match (r.action, r.method) { - (RouteAction::List, HttpMethod::Get) => {} - (RouteAction::Save, HttpMethod::Post) => {} - (RouteAction::Delete, HttpMethod::Delete) => {} - _ => panic!("动作 {:?} 与方法 {:?} 的组合不被支持: {}", r.action, r.method, r.path), - } - } - } - - /// 🔴 **守卫必须与菜单的 `f_en_code` 一字不差** —— 不一致 ⇒ 运行时查菜单 - /// 查不到 ⇒ 走「未映射放行」⇒ **任何登录用户都能调** ⇒ 静默越权。 - #[test] - fn route_guards_match_menu_en_code() { - for r in Pack.routes() { - let RouteGuard::EnCode(code) = r.guard else { - panic!("本包的路由都该有点权限守卫: {}", r.path); - }; - assert_eq!(code, @@UPPER@@_MENU.en_code, "路由 {} 的守卫与菜单不一致", r.path); - } - } - - /// 🔴 **DDL 必须含 `f_tenant_id` 且复合主键是 `(f_id, f_tenant_id)`**。 - #[test] - fn ddl_carries_tenant_id() { - let sql = DDLS[0].1; - assert!(sql.contains("f_tenant_id"), "DDL 必须含 f_tenant_id"); - assert!( - sql.contains("PRIMARY KEY (f_id, f_tenant_id)"), - "复合主键必须是 (f_id, f_tenant_id)" - ); - } - - /// 🔴 **DDL 与 spec 的列必须一致** —— spec 少一列 ⇒ CRUD 投影会漏字段。 - #[test] - fn ddl_columns_match_spec_columns() { - let sql = DDLS[0].1; - for col in @@UPPER@@_SPEC.columns { - assert!(sql.contains(col.column), "DDL 缺列 {}", col.column); - } - } - - /// 🔴 `DDLS` 的每一对都必须是「表名 → 真的建这张表的 SQL」。 - #[test] - fn ddls_pairs_name_the_table_they_create() { - assert!(!DDLS.is_empty(), "本包有实体 ⇒ DDLS 不能为空"); - for (table, sql) in DDLS { - assert!( - sql.contains(&format!("CREATE TABLE IF NOT EXISTS {table}")), - "DDLS 里 {table} 的 DDL 没有建这张表" - ); - } - } - - /// 🔴 `DDLS` 覆盖本包全部实体(漏一张 ⇒ 那张表根本没建)。 - #[test] - fn ddls_covers_every_entity_table() { - for spec in Pack.entities() { - assert!( - DDLS.iter().any(|(t, _)| *t == spec.table), - "实体 {} 的表 {} 不在 DDLS 里", - spec.entity, - spec.table - ); - } - } -} -''' - -MODULE_TPL = '''//! @@APP@@ —— 业务模块:@@ENTITY@@(物理表 `@@TABLE@@`)。 -//! -//! 🔴 **本文件是「面 A 适配器」,不是 spec 的家**: -//! spec / 菜单 / 面 B 路由的单一真源在 `packs/@@APP@@/src/lib.rs`(**只依赖 sspf-sdk**), -//! 本文件只做 `pub use` 转发 ⇒ **spec 只有一份**。 -//! -//! 🔴 **为什么还要面 A**:MVP 前端(React,`src/frontend`)走的是 -//! `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}` ⇒ 没有面 A 页面就是空的。 -//! 集成到官方 JNPF 时面 A 作废、面 B 直接搬(两套路径不同,互不影响)。 -//! -//! 🔴 本文件由 `scripts/new-pack.sh` 生成;重跑会覆盖(`--force`)。 - -use axum::body::Bytes; -use axum::extract::{RawQuery, State}; -use axum::http::HeaderMap; -use axum::routing::{delete, get, post}; -use axum::{Json, Router}; - -use crate::platform::crud::{handle_delete, handle_list, handle_save}; -use crate::platform::envelope::ActionResult; -use crate::platform::state::AppState; - -// 🔴 **spec 与菜单的单一真源 = 业务包** —— 这里只转发,不重写。 -pub use sspf_pack_@@APP@@::@@UPPER@@_MENU; -pub use sspf_pack_@@APP@@::@@UPPER@@_SPEC; - -/// 本模块的 3 条路由(**面 A**:业务层的路由表)—— 钉子测试遍历它。 -pub const ROUTES: [&str; 3] = [ - "/api/ssw/@@APP@@/@@ENTITY@@/List", - "/api/ssw/@@APP@@/@@ENTITY@@/Save", - "/api/ssw/@@APP@@/@@ENTITY@@/Delete", -]; - -/// `GET /api/ssw/@@APP@@/@@ENTITY@@/List`。 -pub async fn @@SNAKE@@_list( - State(state): State, - headers: HeaderMap, -) -> Json { - handle_list(&state, &headers, &@@UPPER@@_SPEC).await -} - -/// `POST /api/ssw/@@APP@@/@@ENTITY@@/Save`。 -pub async fn @@SNAKE@@_save( - State(state): State, - headers: HeaderMap, - body: Bytes, -) -> Json { - handle_save(&state, &headers, &@@UPPER@@_SPEC, &body).await -} - -/// `DELETE /api/ssw/@@APP@@/@@ENTITY@@/Delete?id=`。 -pub async fn @@SNAKE@@_delete( - State(state): State, - headers: HeaderMap, - raw: RawQuery, -) -> Json { - handle_delete(&state, &headers, &@@UPPER@@_SPEC, &raw).await -} - -/// 本模块的路由(**面 A**,`Router::merge` 进总路由)。 -/// -/// 🔴 路径在这里写**字面量**(不用 `ROUTES[0]`)—— 契约扫描器是静态解析, -/// 认不出数组下标 ⇒ 写成下标会让 `check-contract` 判「契约有、代码没有」(假飘移)。 -pub fn router() -> Router { - Router::new() - .route("/api/ssw/@@APP@@/@@ENTITY@@/List", get(@@SNAKE@@_list)) - .route("/api/ssw/@@APP@@/@@ENTITY@@/Save", post(@@SNAKE@@_save)) - .route( - "/api/ssw/@@APP@@/@@ENTITY@@/Delete", - delete(@@SNAKE@@_delete), - ) -} -''' - - -# ---------------------------------------------------------------- 前置校验 - -def check_app(app): - if not re.match(r"^[a-z][a-z0-9_]*$", app): - raise GenError( - "app_code %r 非法:只允许 小写字母/数字/下划线,且以字母开头" - "(它同时是目录名、crate 名的一部分、路由前缀)" % app) - - -def check_entity(entity): - if not re.match(r"^[A-Z][A-Za-z0-9]*$", entity): - raise GenError( - "实体名 %r 非法:必须大驼峰(如 `DataResource`)" - "—— 它同时是路由段、JSON 的 entity、常量名前缀" % entity) - - -def check_collisions(app, entity, table, menu_id, url, en_code): - """🔴 撞名检查 —— 这些撞了**都不报错**,只会静默错。 - - - 目录 / 模块文件撞 ⇒ 覆盖别人的包; - - 物理表撞 ⇒ `CREATE TABLE IF NOT EXISTS` **静默不生效**,两张表共用一份数据; - - 菜单 id 撞 ⇒ 种子 INSERT 主键冲突(启动 exit 1); - - `url_address` / `en_code` 撞 ⇒ 两套路由共用一条菜单 ⇒ **互相越权**。 - """ - if os.path.isdir(os.path.join(PACKS_DIR, app)): - raise GenError("包目录 packs/%s 已存在(要覆盖请加 --force)" % app) - mod = os.path.join(MODULES_DIR, "%s.rs" % app) - if os.path.isfile(mod): - raise GenError("模块文件 src/backend/src/modules/%s.rs 已存在(要覆盖请加 --force)" % app) - - # 物理表:平台 schema + 所有包的 DDL - haystacks = [SCHEMA_SQL] - for root, _dirs, files in os.walk(PACKS_DIR): - for f in files: - if f.endswith(".sql"): - haystacks.append(os.path.join(root, f)) - for path in haystacks: - if not os.path.isfile(path): - continue - if re.search(r"CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?%s\b" % re.escape(table), - read(path), re.I): - raise GenError("物理表 %s 已存在(在 %s 里)" % (table, os.path.relpath(path, ROOT))) - - # 菜单:契约表里查(它登记了全仓的菜单) - contract = read(os.path.join(ROOT, "docs", "contract.md")) - for label, needle in (("菜单 id", menu_id), ("url_address", url), ("f_en_code", en_code)): - if re.search(r"(?m)^%s\t" % re.escape(needle), contract) or re.search( - r"\t%s(\t|$)" % re.escape(needle), contract): - raise GenError("%s %s 已在 docs/contract.md 里登记过" % (label, needle)) - - -def next_sort_code(): - """菜单 `sort_code` = 现有最大 + 1(不猜具体数字,跟着现状走)。""" - contract = read(os.path.join(ROOT, "docs", "contract.md")) - m = re.search(r"(?m)^\[MENU\]\n([\s\S]*?)\n\[", contract) - if not m: - return 10 - best = 0 - for line in m.group(1).split("\n"): - if not line.strip() or line.lstrip().startswith("#") or line.startswith("<"): - continue - cols = line.split("\t") - if len(cols) >= 8 and cols[7].strip().isdigit(): - best = max(best, int(cols[7])) - return best + 1 - - -# ---------------------------------------------------------------- 主流程 - -def parse_argv(argv): - if len(argv) < 3: - raise GenError("用法:new-pack-gen.py --name 中文名 --columns a:TYPE,b:TYPE") - app, entity = argv[1], argv[2] - opts = { - "name": None, "columns": None, "from_ddl": None, "table": None, - "menu_id": None, "en_code": None, "sort": None, - "with_frontend": False, "dry_run": False, "force": False, - } - i = 3 - while i < len(argv): - a = argv[i] - if a in ("--name", "--columns", "--from-ddl", "--table", "--menu-id", "--en-code", "--sort"): - if i + 1 >= len(argv): - raise GenError("参数 %s 后面缺值" % a) - key = a[2:].replace("-", "_") - opts[key] = argv[i + 1] - i += 2 - continue - if a == "--with-frontend": - opts["with_frontend"] = True - i += 1 - continue - if a == "--dry-run": - opts["dry_run"] = True - i += 1 - continue - if a == "--force": - opts["force"] = True - i += 1 - continue - raise GenError("未知参数 %r" % a) - return app, entity, opts - - -def plan(app, entity, opts): - """算清楚要写什么 ⇒ dict(不落盘)。""" - check_app(app) - check_entity(entity) - - table = opts["table"] or "%s_%s" % (app, snake(entity)) - if not re.match(r"^[a-z][a-z0-9_]*$", table): - raise GenError("表名 %r 非法(小写 + 下划线)" % table) - - if opts["from_ddl"]: - table, cols, skipped = parse_ddl(opts["from_ddl"], table) - if skipped: - print(" ⚠️ 以下行没有进包的 DDL(索引 / 约束 / 注释请手工补):") - for s in skipped: - print(" · %s" % s[:100]) - elif opts["columns"]: - cols = parse_columns_arg(opts["columns"]) - else: - raise GenError( - "没有列清单:给 `--columns \"name:VARCHAR(200),price:DECIMAL(18,2)\"`,\n" - " 或者用 `--from-ddl <某个 .sql>` 从已有建表语句读。\n" - " 🔴 不猜:空表建出来没有意义,而且会掩盖「忘了给列」。") - cols = merge_columns(cols) - - menu_id = opts["menu_id"] or "m_%s" % snake(entity) - url = "%s/%s" % (app, entity) - en_code = opts["en_code"] or "permission.%s.%s" % (app, entity.lower()) - sort = int(opts["sort"]) if opts["sort"] else next_sort_code() - name = opts["name"] or entity - - if not opts["force"]: - check_collisions(app, entity, table, menu_id, url, en_code) - - tokens = { - "APP": app, - "ENTITY": entity, - "TABLE": table, - "NAME": name, - "URL": url, - "MENU_ID": menu_id, - "EN_CODE": en_code, - "SORT": str(sort), - "KERNEL": KERNEL_REQ, - "TOOLCHAIN": TOOLCHAIN, - "UPPER": upper_snake(entity), - "SNAKE": snake(entity), - "SPEC_COLUMNS": spec_columns_block(cols), - "NUMERIC": numeric_columns_literal(cols), - } - - files = [ - (os.path.join(PACKS_DIR, app, "Cargo.toml"), render(PACK_CARGO_TPL, tokens)), - (os.path.join(PACKS_DIR, app, "pack.toml"), render(PACK_TOML_TPL, tokens)), - (os.path.join(PACKS_DIR, app, "schema", "001_init.sql"), render(ddl_block(table, cols), tokens)), - (os.path.join(PACKS_DIR, app, "src", "lib.rs"), render(PACK_LIB_TPL, tokens)), - (os.path.join(MODULES_DIR, "%s.rs" % app), render(MODULE_TPL, tokens)), - ] - return {"app": app, "entity": entity, "table": table, "files": files, - "cols": cols, "menu_id": menu_id, "url": url, "en_code": en_code, "sort": sort} - - -def register_ruler(): - """跑一次 `check-module.sh`,把契约 `[RULER]` 里的断言条数登记成实际值。 - - 🔴 **为什么必须做**:`check-module.sh` 的断言数**随模块数增长** - (每个模块 ~30 条)⇒ 加完模块它会报「尺子被改弱了(少了/多了断言)」。 - 那条自证的用意是「有人偷偷删断言」,而**加模块导致的变多**是合法的 - ⇒ 让生成器把数字登记掉,别让人去猜。 - - 🔴 **安全边界**(很重要): - - **只允许变大**:变小说明真有人删了断言 ⇒ 拒绝登记并打印; - - **有别的失败就不登记**:只认「尺子自证」这一条 ❌, - 其它 ❌(模块形状不对 / 前端缺文件)必须先修。 - """ - sh = os.path.join(HERE, "check-module.sh") - env = dict(os.environ) - env["PATH"] = os.path.dirname(sys.executable) + os.pathsep + env.get("PATH", "") - r = subprocess.run(["/bin/bash", sh], capture_output=True, text=True, env=env) - out = (r.stdout or "") + (r.stderr or "") - - m = re.search(r"PASS=(\d+) FAIL=(\d+)", out) - if not m: - print(" ⚠️ 读不出 PASS/FAIL ⇒ 跳过登记") - return False - passed = int(m.group(1)) - - # 只认「行首是 ❌」的断言失败;汇总行(`有 ❌,请按上面修复…`)不算。 - bad = [ - ln.strip() - for ln in out.split("\n") - if ln.strip().startswith("❌") and "尺子自证" not in ln - ] - if bad: - print(" ⚠️ check-module 有真失败 ⇒ 不登记条数(先修这些):") - for ln in bad[:6]: - print(" " + ln) - return False - - path = os.path.join(ROOT, "docs", "contract.md") - text = read(path) - hit = re.search(r"(?m)^check-module\.sh\t(\d+)$", text) - if not hit: - print(" ⚠️ 契约里找不到 `[RULER]` 的 `check-module.sh` 行 ⇒ 跳过登记") - return False - - old = int(hit.group(1)) - if old == passed: - print(" ✅ 条数已是最新(%d)" % passed) - return True - if old > passed: - print(" ⚠️ 条数从 %d **降到** %d ⇒ 像是有人删了断言 ⇒ 拒绝自动登记" % (old, passed)) - return False - - write(path, text.replace(hit.group(0), "check-module.sh\t%d" % passed)) - print(" ✅ 已登记 %d 条(原 %d,+%d 来自新模块)" % (passed, old, passed - old)) - return True - - -def main(argv): - app, entity, opts = parse_argv(argv) - - p = plan(app, entity, opts) - - print("业务包:%s / %s(表 %s,%d 列)" % (p["app"], p["entity"], p["table"], len(p["cols"]))) - print("菜单:%s url=%s en_code=%s sort=%d" % (p["menu_id"], p["url"], p["en_code"], p["sort"])) - print("要写 %d 个文件:" % len(p["files"])) - for path, text in p["files"]: - print(" · %-58s %3d 行" % (os.path.relpath(path, ROOT), text.count("\n"))) - - if opts["dry_run"]: - print("\n(--dry-run ⇒ 一个字节都没写)") - return 0 - - for path, text in p["files"]: - write(path, text) - - # 🔴 **接线**:契约表 + packs_gen.rs + modules/mod.rs 五段 + Cargo 依赖段。 - # 不跑这一步 ⇒ 包存在但内核不认识它(面 A/B 全 404,且**不报错**)。 - print("\n同步派生位置(契约表 / packs_gen.rs / modules/mod.rs / Cargo.toml)…") - rc = subprocess.call([sys.executable, os.path.join(HERE, "pack-sync.py")]) - if rc != 0: - sys.stderr.write( - "❌ pack-sync 失败 ⇒ 包文件已写、但**内核还不知道它**。\n" - " 修好上面的报错后跑:python3 scripts/pack-sync.py\n") - return 2 - - if opts["with_frontend"]: - print("\n生成前端三件套…") - rc = subprocess.call(["/bin/bash", os.path.join(HERE, "new-page.sh"), p["app"], p["entity"]]) - if rc != 0: - sys.stderr.write( - "❌ new-page.sh 失败 ⇒ 后端已就位、前端页面还没有。\n" - " 修好后跑:bash scripts/new-page.sh %s %s\n" % (p["app"], p["entity"])) - return 2 - - # 🔴 **尺子条数**:`check-module.sh` 的断言数 = 模块数 × 每模块条数 - # ⇒ 加一个模块必然变多 ⇒ 那条「尺子被改弱了」的自证会红。 - # 这里把它登记掉(只允许变大,见 `register_ruler` 的安全边界)。 - print("\n登记尺子条数(check-module 的断言数随模块数增加)…") - register_ruler() - - print(""" -下一步(缺一个都会在运行时才发现问题): - 1. bash scripts/verify.sh --fast # 全绿才继续(编译 + 6 把静态闸门) - 2. 补列的**中文标签**:src/frontend/src/views/%s.tsx 的 FIELDS(生成器不猜业务语义) - 3. 起后端 + 前端,点一遍列表 / 新增 / 删除 -""" % p["entity"]) - return 0 - - -if __name__ == "__main__": - try: - sys.exit(main(sys.argv)) - except GenError as exc: - sys.stderr.write("new-pack: %s\n" % exc) - sys.exit(2) diff --git a/scripts/new-pack.sh b/scripts/new-pack.sh deleted file mode 100755 index 7c02c93..0000000 --- a/scripts/new-pack.sh +++ /dev/null @@ -1,58 +0,0 @@ -#!/usr/bin/env bash -# 加一个业务模块 —— **一条命令**:后端包 + 面 A 适配器 + 四处派生位置。 -# -# 🔴 **为什么存在**(HANDOFF §3 批次 12.5): -# 批次 12 把「spec 搬进 `packs//`」之后,加模块不用再碰平台层了。但**写包本身** -# 仍是手抄五个文件(`Cargo.toml` / `pack.toml` / `schema/*.sql` / `src/lib.rs` / -# `modules/.rs`),而且抄漏一处**不报错**: -# · 漏 `merge` 一行 ⇒ 面 B 静默 404 -# · 漏 `ALL_MENUS` 一行 ⇒ 菜单不种 ⇒ 守卫查不到菜单 ⇒ **越权放行** -# · 漏 `f_tenant_id` ⇒ 集成时导不进官方 -# ⇒ 本命令把五个文件按「业务决策」生成,再让 `pack-sync.py` 把内核接线补齐。 -# -# 🔴 **真源 = 业务决策**(app / 实体名 / 中文名 / 列清单),其余全是推导。 -# **不猜**:没有列清单就拒绝生成(空表没有意义,还会掩盖「忘了给列」)。 -# -# 用法: -# bash scripts/new-pack.sh --name "中文名" \ -# --columns "name:VARCHAR(200),price:DECIMAL(18,2)" -# -# bash scripts/new-pack.sh --name "中文名" --from-ddl path/to.sql -# bash scripts/new-pack.sh --name "中文名" --columns "..." --with-frontend -# bash scripts/new-pack.sh --name "中文名" --columns "..." --dry-run -# -# 例(和数据资源同构的一个包里再加一个实体): -# bash scripts/new-pack.sh crm Customer --name "客户" \ -# --columns "name:VARCHAR(200),level:VARCHAR(50),owner:VARCHAR(50)" -# -# 退出码:0 生成完成 / 2 用法错或前置不满足(已存在 / 缺列清单 / 撞名) - -set -u - -ROOT="$(cd "$(dirname "$0")/.." && pwd)" -GEN="$ROOT/scripts/new-pack-gen.py" - -if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then - sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//' - exit 0 -fi - -if [ "$#" -lt 2 ]; then - echo "❌ 用法错:需要 (再加 --name 与 --columns)" - echo " 例: bash scripts/new-pack.sh crm Customer --name \"客户\" --columns \"name:VARCHAR(200)\"" - exit 2 -fi - -PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}" -if [ -z "${PY_BIN}" ]; then - echo "❌ 找不到 python3(生成器需要它)" - exit 2 -fi - -if [ ! -f "${GEN}" ]; then - echo "❌ 找不到生成器 ${GEN}" - exit 2 -fi - -# 参数原样透传(--columns / --dry-run / --force … 由生成器解析) -exec "${PY_BIN}" "${GEN}" "$@" diff --git a/scripts/pack-sync.py b/scripts/pack-sync.py index 8326876..ac1da91 100755 --- a/scripts/pack-sync.py +++ b/scripts/pack-sync.py @@ -420,8 +420,10 @@ def sync_face_counts(text, faces): 🔴 **不写死增量**:直接写「当前 `[ENDPOINT]` 里的实际条数」 ⇒ 天然幂等,且加包 / 加模块 / 改路由都自动跟着走。 """ - if not faces: - return text + # 🔴 零包时 `faces` 是空集合 —— **不能短路返回**:业务端点被清空后 + # `[FACE]` 的旧条数必须跟着重算,否则 CC9 立刻红(2026-11-04 清理踩到)。 + # ⇒ 空集合 = 「重算 [FACE] 里的**全部**面」。 + recount_all = not faces lines = text.split("\n") try: @@ -443,7 +445,7 @@ def sync_face_counts(text, faces): if len(cols) < 2 or cols[0].startswith("#") or not cols[0]: continue face = cols[0] - if face not in faces: + if not recount_all and face not in faces: continue # 本函数在三次替换**之后**调用 ⇒ `count_faces` 读到的是更新后的值。 cols[1] = str(face_now.get(face, 0)) @@ -503,8 +505,9 @@ def read_all_packs(): for app in sorted(os.listdir(PACKS_DIR)): if os.path.isdir(os.path.join(PACKS_DIR, app)): packs.append(read_pack(app)) - if not packs: - raise SyncError("packs/ 下没有包(目录:%s)" % PACKS_DIR) + # 🔴 **零包是合法目标态**(2026-11-04 清理):示例包已整体搬到技能仓 + # `ssw-jnpf-lite-rust`,平台仓不认识任何业务包。此时四处派生位置 + # 全部归零(`--check` 会把它们钉成空)⇒ 业务一旦回流立刻红。 return packs @@ -584,7 +587,7 @@ def require_module_for_every_pack(packs, mods): "包 %s 声明了实体,但缺 `src/backend/src/modules/%s.rs`\n" " 🔴 缺它的后果是**静默**的:菜单不会被种 ⇒ 面 B 守卫查不到菜单\n" " ⇒ 走「未映射放行」(越权);面 A 端点也不存在 ⇒ MVP 前端页面空着。\n" - " ⇒ 跑 `bash scripts/new-pack.sh %s ` 补上。" + " ⇒ 平台仓不允许自带业务包;请把 %s 放回业务仓 / 技能仓。" % (p["app"], p["app"], p["app"]) ) @@ -625,87 +628,45 @@ def manifest_json_of(p): def gen_packs_gen(packs): - """生成 `src/backend/src/packs_gen.rs` 全文。""" + """生成 `src/backend/src/packs_gen.rs` 全文。 + + 🔴 **2026-11-04 清理**:示例包已搬到技能仓,本仓恒为零包。 + 本文件从「业务包清单」降级为**平台注入点的空实现**: + - [`registry`] 恒返回空注册表(本仓不认识任何业务包); + - [`registry_from`] 保留,供门面 `sspf::Platform::packs` 合并外部注册表。 + ⇒ 平台能力(包路由装配 / 包 DDL 建表 / 白名单自检)一个不动, + 只是「默认带哪些包」变成空。 + """ + if packs: + raise SyncError( + "平台仓不允许自带业务包(发现 %d 个)⇒ 业务包请用 sspf::Platform::packs() 注入" + % len(packs) + ) L = [] L.append("//! ⚠️ **本文件由 `scripts/pack-sync.py` 生成 —— 不许手改。**") L.append("//!") - L.append("//! 它是内核的**业务包清单**:每个包一条 [`sspf_plugin::load_static`]") - L.append("//! 调用 + 一份 `pack.toml` 的 JSON 快照。") + L.append("//! **平台包零业务**(2026-11-04):本仓不认识任何业务包。") + L.append("//! 业务仓通过 `sspf::Platform::packs(reg)` 注入自己装载的注册表,") + L.append("//! 由 `crate::bootstrap` 在**同一个 `Db`** 上装配路由与 DDL。") L.append("//!") - L.append("//! 🔴 **为什么是生成的**:批次 12 时这段在 `bootstrap.rs` 里手写 ——") - L.append("//! 每加一个包要抄「manifest JSON + `PackSource` + `merge(vec![…])`」三段。") - L.append("//! 漏掉最后那段 `merge` 的表现是:包**装载成功**、没有报错,") - L.append("//! 但 `entities` / `routes` 全丢 ⇒ **面 B 端点静默 404**。") - L.append("//! ⇒ 改成生成 ⇒ 「漏一处」在机制上不存在;真忘了跑生成,") - L.append("//! `scripts/verify.sh` 的第一步(`pack-sync.py --check`)会红。") - L.append("//!") - L.append("//! 🔴 **`packs/` 是唯一真源** —— 加包跑 `bash scripts/new-pack.sh`,") - L.append("//! 改完 `packs/*` 跑 `python3 scripts/pack-sync.py`。") - L.append("//!") - L.append("//! 🔴 **默认 feature 下本文件不装载任何包**(2026-11-04 标准平台包):") - L.append("//! 4 个示例包降为 `example-packs` feature(只有 `sspf-admin` 与 `sspf-tests` 开)。") - L.append("//! 业务仓只依赖门面 `sspf` ⇒ `cargo tree` 里**没有** `sspf-pack-*`") - L.append("//! ⇒ 平台包里零业务(`check-arch.sh` 的 AR17 钉住)。") + L.append("//! 🔴 为什么留着这个空文件:`bootstrap::load_packs()` / 白名单自检 /") + L.append("//! `Extras::kernel()` 都是**平台能力**(业务仓要用),删掉会逼着每个") + L.append("//! 业务仓自己抄一遍。留一个恒空的默认实现 ⇒ 平台侧零业务且不破装配链。") L.append("") L.append("use sspf_plugin::{LoadError, PackRegistry};") L.append("") - L.append("/// 装载 `packs/*` 下的**全部**业务包(顺序 = `app_code` 字典序)。") + L.append("/// 本仓业务包清单:恒为空。") L.append("///") - L.append("/// 🔴 任一包装载失败 ⇒ **整体失败**(半加载的包比不加载更危险):") - L.append("/// 半加载的包 = 一部分路由在、一部分不在 ⇒ 前端表现为「有的页面能用」。") - L.append('#[cfg(feature = "example-packs")]') - L.append("pub fn registry(kernel_version: &str) -> Result {") - L.append(" let mut regs: Vec = Vec::new();") - L.append("") - for p in packs: - app = p["app"] - ident = "sspf_pack_" + app.replace("-", "_") - const = app.upper().replace("-", "_") + "_MANIFEST_JSON" - L.append(" // ---- %s ----" % app) - L.append(" regs.push(sspf_plugin::load_static(") - L.append(' "%s",' % app) - L.append(" %s," % const) - L.append(" Box::new(%s::Pack)," % ident) - L.append(" %s::DDLS," % ident) - L.append(" kernel_version,") - L.append(" )?);") - L.append("") - L.append(" Ok(sspf_plugin::merge(regs))") - L.append("}") - L.append("") - L.append("/// 默认 feature(业务仓只依赖门面时的形态):**本仓不认识任何业务包** ⇒ 空注册表。") - L.append("///") - L.append("/// 🔴 返回 `Ok` 而不是 `Err`:空注册表是**合法形态**(业务仓自己注入业务包),") - L.append("/// 不是装载失败。") - L.append('#[cfg(not(feature = "example-packs"))]') + L.append("/// 🔴 返回 `Ok` 而不是 `Err`:空注册表是**合法形态**,不是装载失败。") L.append("pub fn registry(_kernel_version: &str) -> Result {") L.append(" Ok(PackRegistry::default())") L.append("}") L.append("") - L.append("/// 把**外部已装载**的注册表合并成一个(门面 `sspf::Platform::packs` / `.pack` 用)。") - L.append("///") - L.append("/// 🔴 与 [`registry`] 的分工:`registry` 装的是**本仓 `packs/*` 的示例包**;") - L.append("/// 本函数**只合并、不装载** ⇒ 业务仓用 `sspf::load_static` 装好自己的包后传进来。") - L.append("/// 🔴 空 vec ⇒ 空注册表(合法,不是错误)。") + L.append("/// 把**外部已装载**的注册表合并成一个(门面 `sspf::Platform::packs` 用)。") + L.append("/// 🔴 只合并、不装载;空 vec ⇒ 空注册表(合法)。") L.append("pub fn registry_from(regs: Vec) -> PackRegistry {") L.append(" sspf_plugin::merge(regs)") L.append("}") - L.append("") - L.append("// ---------------------------------------------------------------- 清单快照") - L.append("//") - L.append("// 🔴 `pack.toml` 的**权威副本**在 `packs//pack.toml`(给人看、给导出工具读);") - L.append("// 这里是它的**编译期 JSON 快照**。为什么要快照、不运行期读文件:") - L.append("// 内核是**单二进制部署** ⇒ 运行目录里不一定有 `packs/` 目录。") - L.append("// 两份的一致性由 `scripts/pack-sync.py` 保证(`--check` 会比对)。") - L.append("//") - L.append("// 🔴 快照只在 `example-packs` 下编译(否则默认 feature 的构建里是死代码)。") - for p in packs: - app = p["app"] - const = app.upper().replace("-", "_") + "_MANIFEST_JSON" - L.append("") - L.append("/// `packs/%s/pack.toml` 的编译期快照。" % app) - L.append('#[cfg(feature = "example-packs")]') - L.append('const %s: &str = r#"%s"#;' % (const, manifest_json_of(p))) return "\n".join(L).rstrip() + "\n" @@ -738,109 +699,59 @@ def gen_pack_deps(packs): def gen_pack_feature(packs): - """生成 `src/backend/Cargo.toml` 的 `[features]` 段(`example-packs` 聚合开关)。 + """🔴 **已退役**(2026-11-04 清理):`example-packs` feature 随示例包一起搬走。 - 🔴 用 `dep:` 语法 ⇒ 不产生「与依赖同名的隐式 feature」, - 业务仓不可能误开单个 `sspf-pack-demo`。 - 🔴 **空列表也要生成**(`example-packs = []`)—— 标记段必须存在, - 否则 `pack-sync.py --check` 与闸门 AR17 都会失去判据。 + 平台仓现在**没有** `[features]` 段,也没有任何可选业务依赖;业务仓通过 + `sspf::Platform::packs(reg)` 注入自己的注册表,不开任何平台 feature。 + ⇒ 本函数保留为「非空即报错」的护栏:谁把示例包塞回 `packs/`,同步直接失败。 """ - names = ['"dep:%s"' % _pack_crate_name(p["app"]) for p in packs] - return ["example-packs = [" + ", ".join(names) + "]"] + if packs: + raise SyncError( + "平台仓不允许自带业务包(发现 %d 个:%s)\n" + " ⇒ 业务包属于业务仓 / 技能仓,请通过 sspf::Platform::packs() 注入。" + % (len(packs), ", ".join(p["app"] for p in packs)) + ) + return [] def gen_mod_regions(mods): """生成 `modules/mod.rs` 的五个段 ⇒ `{段名: 行列表}`。 - 🔴 **`ALL_SPECS` 与 `ALL_ROUTES` 必须同序** —— 都按 `mods` 的顺序生成 - ⇒ `mod.rs` 的测试可以按 3 条一组配对(`chunks(3)`)。 - 这个「同序」不是约定,是**生成保证**。 - - 🔴 **每个段都生成两份**(2026-11-04 标准平台包): - `#[cfg(feature = "example-packs")]` 的**实体清单**, - 与 `#[cfg(not(feature = "example-packs"))]` 的**空清单**。 - 为什么不用「整段 cfg」:那会让 `all_specs()` / `all_menus()` / `router()` - 在默认 feature 下**根本不存在** ⇒ `routes.rs` / `bootstrap.rs` 编译不过。 - 两份定义同名常量 / 函数 ⇒ 默认 feature 下**结构在、内容空** - (业务仓注入自己的东西,平台侧零业务)。 + 🔴 **2026-11-04 清理**:示例模块已搬到技能仓,本仓恒为零模块。 + 五个生成段全部归零 ⇒ `all_specs()` / `all_menus()` / `ALL_ROUTES` / + `router()` 都还在(装配链不破),只是**内容为空**。 + 业务仓用自己的路由 + `sspf::Platform` 注入,不需要往内核塞文件。 """ - if not mods: - raise SyncError("modules/ 下没有任何模块文件(至少要保住 demo/shop/books/asset)") - - FEAT = '#[cfg(feature = "example-packs")]' - NOFEAT = '#[cfg(not(feature = "example-packs"))]' - - decls = ["// 每个模块一行:**文件即登记**(顺序 = 文件名字典序,不代表业务顺序)。", - "// 🔴 只在 `example-packs` 下编译 —— 默认 feature 的内核**不认识任何业务模块**。"] - for app, _, _, _ in mods: - decls.append(FEAT) - decls.append("pub mod %s;" % app) - - specs = [ - "/// 全部业务实体 spec。", - "///", - "/// 🔴 **本段由 `scripts/pack-sync.py` 生成** —— 加模块不用手改(见文件头)。", - FEAT, - "pub const ALL_SPECS: &[EntitySpec] = &[", - ] - for app, spec, _, _ in mods: - specs.append(" %s::%s," % (app, spec)) - specs.append("];") - specs.append("/// 默认 feature:平台侧零业务 ⇒ 空清单(业务仓用 `sspf::Platform::packs` 注入)。") - specs.append(NOFEAT) - specs.append("pub const ALL_SPECS: &[EntitySpec] = &[];") - - routes = [ - "/// **全部业务路由**(面 A:`/api/ssw/{appCode}/{Entity}/{动作}`,每模块 3 条)。", - "///", - "/// 🔴 **与 `ALL_SPECS` 同序**(同一份模块清单生成)⇒ 可以按 3 条一组配对。", - FEAT, - "pub const ALL_ROUTES: &[&str] = &[", - ] - for app, _, _, n in mods: - for i in range(n): - routes.append(" %s::ROUTES[%d]," % (app, i)) - routes.append("];") - routes.append("/// 默认 feature:没有业务路由可登记。") - routes.append(NOFEAT) - routes.append("pub const ALL_ROUTES: &[&str] = &[];") - - menus = [ - "/// 全部业务内置菜单(由**装配根** [`crate::bootstrap`] 传给平台层的种子", - "/// ⇒ **平台层不认任何业务菜单**,红线 12)。", - FEAT, - "pub const ALL_MENUS: &[MenuSpec] = &[", - ] - for app, _, menu, _ in mods: - menus.append(" %s::%s," % (app, menu)) - menus.append("];") - menus.append("/// 默认 feature:平台侧零业务 ⇒ 种子只种平台菜单。") - menus.append(NOFEAT) - menus.append("pub const ALL_MENUS: &[MenuSpec] = &[];") - - router = [ - "/// **全部业务模块的路由**(`Router::merge` 进总路由)。", - "///", - "/// 🔴 加业务模块 ⇒ **不用改这里**(本段由 `pack-sync.py` 生成)。", - FEAT, - "pub fn router() -> Router {", - " %s::router()" % mods[0][0], - ] - for app, _, _, _ in mods[1:]: - router.append(" .merge(%s::router())" % app) - router.append("}") - router.append("/// 默认 feature:没有任何业务路由。") - router.append(NOFEAT) - router.append("pub fn router() -> Router {") - router.append(" Router::new()") - router.append("}") + if mods: + raise SyncError( + "平台仓不允许自带业务模块(发现 %d 个:%s)\n" + " ⇒ 面 A 适配器属于业务仓,请用 sspf::Platform::router() 注入。" + % (len(mods), ", ".join(m[0] for m in mods)) + ) return { - "MODS": decls, - "SPECS": specs, - "ROUTES": routes, - "MENUS": menus, - "ROUTER": router, + "MODS": [ + "// 🔴 **平台包零业务**:本仓不认识任何业务模块。", + "// 业务模块的路由由业务仓经 `sspf::Platform::router()` 注入。", + ], + "SPECS": [ + "/// 本仓业务实体 spec:恒为空(平台包零业务)。", + "pub const ALL_SPECS: &[EntitySpec] = &[];", + ], + "ROUTES": [ + "/// 本仓业务路由表:恒为空(平台包零业务)。", + "pub const ALL_ROUTES: &[&str] = &[];", + ], + "MENUS": [ + "/// 本仓业务内置菜单:恒为空;业务菜单由 `.menus()` / `.packs()` 注入。", + "pub const ALL_MENUS: &[MenuSpec] = &[];", + ], + "ROUTER": [ + "/// 本仓业务路由:恒为空。", + "pub fn router() -> Router {", + " Router::new()", + "}", + ], } @@ -910,7 +821,9 @@ def sync(write=True): # ④ Cargo 依赖段 + ⑤ `[features]` 段(两段都生成 ⇒ 「漏一处」不存在) old = scan.read(BACKEND_CARGO) new = replace_marker_block(old, GEN_DEPS_OPEN, GEN_DEPS_CLOSE, gen_pack_deps(packs)) - new = replace_marker_block(new, GEN_FEAT_OPEN, GEN_FEAT_CLOSE, gen_pack_feature(packs)) + # 🔴 `[features]` 段随示例包一起退役(2026-11-04):平台仓不再有任何 + # 可选业务依赖 ⇒ 没有 feature 可生成。gen_pack_feature 只做「非空即报错」的护栏。 + gen_pack_feature(packs) artifacts.append(("src/backend/Cargo.toml", old, new, None)) if write: diff --git a/scripts/perm-smoke-jnpf.sh b/scripts/perm-smoke-jnpf.sh index 9d23e03..68a9035 100644 --- a/scripts/perm-smoke-jnpf.sh +++ b/scripts/perm-smoke-jnpf.sh @@ -13,7 +13,7 @@ # 前置:后端已启动,且处于**初始种子状态**(admin / 123456)。 # 退出码:0 = 全绿(面 B 覆盖 23/23) / 1 = 有 FAIL 或有 SKIP(未全覆盖) / 2 = 前置错误 # -# 🔴 **面 B 的判别规则**(见 JNPF_COMPAT_SURFACE.md §2.2): +# 🔴 **面 B 的判别规则**(见 技能仓 JNPF_COMPAT_SURFACE.md §2.2): # 请求头带 `Vue-Version: 3` ⇒ 走官方形状;否则走面 A。 # 官方前端**必然**带这三个头(jnpf-web-apps-main/src/api/request.ts:109-112), # 但本仓 React 前端**也发** `App-Code` 与 `Jnpf-Origin: pc`(同款), @@ -595,16 +595,16 @@ fi # G8 · 授权:官方 body 超集(断言 17)+ 官方读用 POST(断言 18) # ===================================================================== -# 🔴 写入用的角色 = role_user,写入内容与面 A 尺子**完全相同**(module=["m_demo"])⇒ 幂等、互不干扰。 +# 🔴 写入用的角色 = role_user,写入内容与面 A 尺子**完全相同**(module=["m_menu"])⇒ 幂等、互不干扰。 AUTH_WRITE="$(curl --noproxy '*' -s --max-time 10 -X PUT "$B/api/permission/Authority/Data/role_user" \ "${HDR_B[@]}" -H "$B_AUTH" -H 'Content-Type: application/json' \ - -d '{"objectType":"role","module":["m_demo"],"button":[],"column":[],"resource":[],"form":[],"systemIds":[]}')" + -d '{"objectType":"role","module":["m_menu"],"button":[],"column":[],"resource":[],"form":[],"systemIds":[]}')" AW_CODE="$(json_get code "$AUTH_WRITE")" # 回读:走面 A 的只读端点(两把尺子共用一份数据 ⇒ 这才是真回读) ROLE_MODS="$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/sys/Role/Modules?roleId=role_user" -H "$A_AUTH")" ROLE_MOD_IDS="$(json_get strarray "$ROLE_MODS")" -if [ "$AW_CODE" = "200" ] && printf '%s' "$ROLE_MOD_IDS" | tr ',' '\n' | grep -qx 'm_demo'; then - assert1 "断言 17 · 授权写:官方完整 body(含 button/column/resource/form/systemIds)⇒ code=200 且 module 真落库" 1 "code=200, 回读含 m_demo" +if [ "$AW_CODE" = "200" ] && printf '%s' "$ROLE_MOD_IDS" | tr ',' '\n' | grep -qx 'm_menu'; then + assert1 "断言 17 · 授权写:官方完整 body(含 button/column/resource/form/systemIds)⇒ code=200 且 module 真落库" 1 "code=200, 回读含 m_menu" else assert1 "断言 17 · 授权写:官方完整 body(含 button/column/resource/form/systemIds)⇒ code=200 且 module 真落库" 0 "code=${AW_CODE}, 回读=${ROLE_MOD_IDS:-空}" fi diff --git a/scripts/perm-smoke.sh b/scripts/perm-smoke.sh index b964ef9..af92fcc 100755 --- a/scripts/perm-smoke.sh +++ b/scripts/perm-smoke.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# ssw-platform —— 权限闭环冒烟脚本(34 条断言 = 对齐 react 版的 32 条 + 多应用 2 条) +# ssw-platform —— 平台权限闭环 + 防回流冒烟脚本(21 条断言) # # 用法: # bash scripts/perm-smoke.sh @@ -9,7 +9,12 @@ # # 前置:后端已启动,且处于**初始种子状态**(admin / 123456)。 # 幂等:脚本开头会删掉历史 smoke_user(存在才删)。 -# 退出码:0 = 全绿(PASS=34 FAIL=0) / 1 = 有断言失败 / 2 = 前置错误(后端不可达、缺 jq+python3、缺 --enc 二进制) +# 退出码:0 = 全绿(PASS=21 FAIL=0) / 1 = 有断言失败 / 2 = 前置错误(后端不可达、缺 jq+python3、缺 --enc 二进制) +# +# 🔴 **平台包零业务**(2026-11-04 清理):示例包 demo/shop/books/asset 已搬到技能仓。 +# 原来 43 条里的 25 条业务 CRUD 断言随之退役,换成 4 条「面 A 业务端点必须 +# HTTP 404」的防回流判据;平台权限闭环(登录 / token / 菜单树 / 授权 / 多应用) +# 一条不少。断言条数仍由契约 [RULER] 钉住 ⇒ 尺子不会静默变弱。 # # 🔴 不依赖 node:cipher 用后端 `--enc` 自证;JSON 取值用 jq(无则 python3 兜底)。 # 🔴 所有 curl 都带 `--noproxy '*'`(本机 curl 走系统代理,不加会打不通 loopback)与 `--max-time 10`(后端不回就超时,不许挂死)。 @@ -349,12 +354,12 @@ check '账号已存在:smoke_user' "$(json_get msg "$DUP_BODY")" "重复账号 # ---- 断言 10:写授权(一维数组 module)---- AUTH1="$(curl --noproxy '*' -s --max-time 10 -X PUT "$B/api/permission/Authority/Data/role_user" -H "$AUTH" \ - -H 'Content-Type: application/json' -d '{"objectType":"role","module":["m_demo"]}')" -check 200 "$(json_get code "$AUTH1")" "写授权(一维)⇒ code=200" + -H 'Content-Type: application/json' -d '{"objectType":"role","module":["m_menu"]}')" +check 200 "$(json_get code "$AUTH1")" "写授权(一维,平台菜单 m_menu)⇒ code=200" # ---- 断言 11:写授权(二维兼容 [checked, halfChecked])---- AUTH2="$(curl --noproxy '*' -s --max-time 10 -X PUT "$B/api/permission/Authority/Data/role_user" -H "$AUTH" \ - -H 'Content-Type: application/json' -d '{"objectType":"role","module":[["m_demo"],[]]}')" + -H 'Content-Type: application/json' -d '{"objectType":"role","module":[["m_menu"],[]]}')" check 200 "$(json_get code "$AUTH2")" "写授权(二维兼容)⇒ code=200" # ---- 断言 12:smoke_user 登录(明文与建用户时的口径一致:'123456')---- @@ -367,8 +372,11 @@ check 200 "$(json_get code "$ALOGIN")" "smoke_user 登录 ⇒ code=200" ATOKEN="$(json_get token "$ALOGIN")" AAUTH="Authorization: bearer ${ATOKEN}" -# ---- 断言 13:smoke_user 菜单收窄为 Demo 示例 ---- -check 'Demo 示例:' \ +# ---- 断言 13:smoke_user 菜单按授权收窄(平台菜单 m_menu)---- +# 🔴 零业务后菜单树只剩「系统管理」一族;授权 m_menu ⇒ 只留「菜单管理」这一项。 +# 菜单树构造会把**被授权的叶子**提为根(父节点未授权就不带出来)⇒ 形状是 +# `菜单管理:`(不是 `系统管理:菜单管理`);这个形状由 menutree 取值口径决定。 +check '菜单管理:' \ "$(json_get menutree "$(curl --noproxy '*' -s --max-time 10 "$B/api/oauth/CurrentUser" -H "$AAUTH")")" \ "smoke_user 菜单已按授权收窄" @@ -376,78 +384,24 @@ check 'Demo 示例:' \ check 403 "$(json_get code "$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/sys/User/List" -H "$AAUTH")")" \ "smoke_user 访问 User/List ⇒ code=403" -# ---- 断言 15:smoke_user 访问 DemoItem/List(期望 200)---- -check 200 "$(json_get code "$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/demo/DemoItem/List" -H "$AAUTH")")" \ - "smoke_user 访问 DemoItem/List ⇒ code=200" +# ---- 断言 15~18:防回流 —— 4 个示例业务端点必须**不存在**(HTTP 404)---- +# +# 🔴 **平台包零业务**(2026-11-04 清理):示例包已整体搬到技能仓,本仓面 A 只留 +# 平台路由。原来 17~41 那 25 条打的是 demo/shop/books/asset 的 CRUD + 权限, +# 现在改成「业务端点一律 404」⇒ 谁把示例业务接回平台仓,这里立刻红。 +# 🔴 不是「模块不存在就跳过」的自适应分支:4 个前缀逐一真发请求,**条数固定进 +# 契约 [RULER] 自证**,少一条就判尺子被改弱。 +for biz in "demo/DemoItem/List" "shop/Product/List" "books/Book/List" "asset/DataResource/List"; do + BIZ_CODE="$(curl --noproxy '*' -s --max-time 10 -o /dev/null -w '%{http_code}' \ + "$B/api/ssw/${biz}" -H "$AUTH")" + check 404 "${BIZ_CODE}" "防回流:/api/ssw/${biz} 必须 404(平台零业务)" +done -# ---- 断言 16:未知路由 ⇒ HTTP 404 ---- +# ---- 断言 19:未知路由 ⇒ HTTP 404 ---- check 404 "$(curl --noproxy '*' -s --max-time 10 -o /dev/null -w '%{http_code}' "$B/api/not-exist-xyz")" \ "未知路由 HTTP 404 不被吞掉" -# ---- 断言 17:admin 访问 Product/List(管理员短路,期望 200)---- -check 200 "$(json_get code "$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/shop/Product/List" -H "$AUTH")")" \ - "admin 访问 Product/List ⇒ code=200(管理员短路)" - -# ---- 断言 18/19/20:Product 新建 + 主键长度 + numeric 往返 ---- -PNEW="$(curl --noproxy '*' -s --max-time 10 -X POST "$B/api/ssw/shop/Product/Save" -H "$AUTH" \ - -H 'Content-Type: application/json' -d '{"title":"测试产品","price":"9.90"}')" -check 200 "$(json_get code "$PNEW")" "Product 新建 ⇒ code=200" -check 36 "$(json_get idlen "$PNEW")" "Product 主键 = 36 位 UUID" -check '"9.90"' "$(json_get price "$PNEW")" "Product numeric 往返 = JSON 字符串 \"9.90\"(契约 R1.5)" - -# ---- 断言 21/22:Product 无 token ⇒ 600;smoke_user 未授权 ⇒ 403 ---- -check 600 "$(json_get code "$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/shop/Product/List")")" \ - "Product 无 token ⇒ code=600" -check 403 "$(json_get code "$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/shop/Product/List" -H "$AAUTH")")" \ - "Product 未授权非管理员 ⇒ code=403" - -# ---- 断言 23:Book 列表(管理员短路,期望 200)---- -# 🔴 本仓 books/Book 路由一定存在 ⇒ **不写「模块不存在就跳过」的自适应分支**(写了就等于少断言)。 -BOOK_LIST="$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/books/Book/List" -H "$AUTH")" -check 200 "$(json_get code "$BOOK_LIST")" "Book 列表(admin 短路)⇒ code=200" - -# ---- 断言 24~29:Book 新建(6 字段)+ 主键 + title/author/numeric/int 往返 ---- -BNEW="$(curl --noproxy '*' -s --max-time 10 -X POST "$B/api/ssw/books/Book/Save" -H "$AUTH" \ - -H 'Content-Type: application/json' \ - -d '{"title":"三体","author":"刘慈欣","isbn":"9787229030937","category":"科幻","price":"58.00","stock":100}')" -check 200 "$(json_get code "$BNEW")" "Book 新建(6 字段)⇒ code=200" -check 36 "$(json_get idlen "$BNEW")" "Book 主键 = 36 位 UUID" -check "三体" "$(json_get title "$BNEW")" "Book title 往返" -check "刘慈欣" "$(json_get author "$BNEW")" "Book author 往返" -check '"58.00"' "$(json_get price "$BNEW")" "Book numeric 往返 = JSON 字符串 \"58.00\"(契约 R1.5)" -check 100 "$(json_get stock "$BNEW")" "Book int 库存往返 = JSON 数字 100" - -# ---- 断言 30:Book 列表含新建项(长度 ≥ 1;新建**之后**重新查一次列表)---- -BOOK_LIST2="$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/books/Book/List" -H "$AUTH")" -check ">=1" "$(json_get datalen "$BOOK_LIST2")" "Book 列表含新建项(长度 ≥ 1)" - -# ---- 断言 31/32:Book 无 token ⇒ 600;smoke_user 未授权 ⇒ 403 ---- -check 600 "$(json_get code "$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/books/Book/List")")" \ - "Book 无 token ⇒ code=600" -check 403 "$(json_get code "$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/books/Book/List" -H "$AAUTH")")" \ - "Book 未授权非管理员 ⇒ code=403" - -# ---- 断言 33~41:asset/DataResource(尚数网真实业务:数据资源)---- -# 🔴 字段取自公司本体 `DataResource`(名称 / 类别 / 提供方 …)⇒ 这条链是 -# 「真实业务模块」的端到端证据(不是脚手架示例)。 -RES_LIST="$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/asset/DataResource/List" -H "$AUTH")" -check 200 "$(json_get code "$RES_LIST")" "数据资源 列表(admin 短路)⇒ code=200" -RNEW="$(curl --noproxy '*' -s --max-time 10 -X POST "$B/api/ssw/asset/DataResource/Save" -H "$AUTH" \ - -H 'Content-Type: application/json' \ - -d '{"name":"全国企业工商登记数据","category":"结构化","scenario":"企业征信核验","provider":"尚数网","format":"CSV","scale":"1200万条","source":"平台收录"}')" -check 200 "$(json_get code "$RNEW")" "数据资源 新建(6 字段)⇒ code=200" -check 36 "$(json_get idlen "$RNEW")" "数据资源 主键 = 36 位 UUID" -check "全国企业工商登记数据" "$(json_get name "$RNEW")" "数据资源 name 往返" -check "结构化" "$(json_get category "$RNEW")" "数据资源 category 往返" -check "尚数网" "$(json_get provider "$RNEW")" "数据资源 provider 往返" -RES_LIST2="$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/asset/DataResource/List" -H "$AUTH")" -check ">=1" "$(json_get datalen "$RES_LIST2")" "数据资源 列表含新建项(长度 ≥ 1)" -check 600 "$(json_get code "$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/asset/DataResource/List")")" \ - "数据资源 无 token ⇒ code=600" -check 403 "$(json_get code "$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/asset/DataResource/List" -H "$AAUTH")")" \ - "数据资源 未授权非管理员 ⇒ code=403" - -# ---- 断言 42/43:多应用 —— 当前应用由 `App-Code` 头决定(CLAUDE.md §4.1)---- +# ---- 断言 20/21:多应用 —— 当前应用由 `App-Code` 头决定(CLAUDE.md §4.1)---- # 🔴 判据是**顶层** `currentSystemId`(面 A/面 B 同一口径):头缺失 ⇒ 回落主系统; # 未知应用也回落主系统(不 500、不 panic)——这里用已注册的 app-b 验证真路由。 check "mainSystem" "$(json_get sysid "$MENU")" \ diff --git a/scripts/verify.sh b/scripts/verify.sh index f35cc70..56a3f63 100755 --- a/scripts/verify.sh +++ b/scripts/verify.sh @@ -155,12 +155,12 @@ if [ "${MODE}" = "lib" ] || [ "${MODE}" = "full" ] || [ "${MODE}" = "smoke" ]; t if [ "${MODE}" = "lib" ]; then run_step "单测(cargo test --lib)" \ cargo test --offline --workspace --lib - # 🔴 **包冒烟必须单独一步**(`full` / `smoke` 里已由 `--workspace` 覆盖 ⇒ 不重复): - # `--lib` 只跑单测 ⇒ 集成测试一条都不跑 ⇒ 下面这类**纯运行时**故障在这一档 - # 完全看不见:包的表没建出来 / 面 B 路由没 merge / `module_key` 指向不存在的菜单。 - # 它们全都**不会让静态闸门红**,只表现为「前端页面空着」。 - # 代价实测 +1.3s(含起 pglite + 起 HTTP 服务)⇒ 放进中环完全值得。 - run_step "包冒烟(每个包的 List 真应答,面 A + 面 B)" \ + # 🔴 **运行时防回流探针必须单独一步**(`full` / `smoke` 里已由 `--workspace` 覆盖): + # `--lib` 只跑单测 ⇒ 集成测试一条都不跑 ⇒ 「平台是不是真的零业务」这一档 + # 完全看不见(静态闸门只看文本,服务没起来/路由回流都测不到)。 + # `pack_smoke_it` 在零业务清理后改成:清单恒空 + 平台端点仍活 + 4 个示例端点 404。 + # 代价实测 +1.5s(含起 pglite + 起 HTTP 服务)⇒ 放进中环完全值得。 + run_step "运行时防回流探针(零业务:清单空 / 平台活 / 业务端点 404)" \ cargo test --offline -p sspf-tests --test pack_smoke_it else run_step "全量测试(cargo test --workspace)" \ diff --git a/src/backend/Cargo.toml b/src/backend/Cargo.toml index 599d264..1f8926e 100644 --- a/src/backend/Cargo.toml +++ b/src/backend/Cargo.toml @@ -71,36 +71,13 @@ sspf-lowcode-exec = { path = "../../crates/sspf-lowcode-exec" } # 业务包装载器(L2 静态:读清单 / 校验 / 收集声明)—— 不认识 axum sspf-plugin = { path = "../../crates/sspf-plugin" } -# 🔴 业务包(只依赖 sspf-sdk)。 -# 内核**只允许**依赖 packs/ 这类业务包,且**不得**在平台层(platform/) -# 出现 `use sspf_pack_*` ⇒ 业务知识不许漏进平台层(check-arch.sh 的 AR9 钉住)。 -# -# ⚠️ 下面 `>>>GEN:PACK_DEPS` 段是**生成物**:`scripts/pack-sync.py` 按 `packs/*` -# 目录重写(crate 名取 `packs//Cargo.toml` 的 `[package].name`)。 -# 加包请跑 `bash scripts/new-pack.sh `;手改会在下次同步被覆盖, -# 且 `scripts/verify.sh` 第一步(`pack-sync.py --check`)会直接红。 -# -# 🔴 **全部 `optional = true`**(2026-11-04 标准平台包):默认 feature 下内核 -# **不认识任何业务包** ⇒ 业务仓只依赖门面 `sspf` 时 `cargo tree` 里没有 -# `sspf-pack-*`(`check-arch.sh` 的 AR17 钉住)。本仓的 `sspf-admin` / -# `sspf-tests` 显式开 `example-packs`。 -# >>>GEN:PACK_DEPS -sspf-pack-asset = { path = "../../packs/asset", optional = true } -sspf-pack-books = { path = "../../packs/books", optional = true } -sspf-pack-demo = { path = "../../packs/demo", optional = true } -sspf-pack-shop = { path = "../../packs/shop", optional = true } -# <<>>GEN:PACK_FEATURE -example-packs = ["dep:sspf-pack-asset", "dep:sspf-pack-books", "dep:sspf-pack-demo", "dep:sspf-pack-shop"] -# <<>>GEN:PACK_DEPS` 段仍是 `scripts/verify.sh` 第一步的判据:它必须**恒为空**。 +# >>>GEN:PACK_DEPS +# <<>>GEN:PACK_DEPS` 段是 `pack-sync.py` 生成的 | 不手改(`new-pack.sh` 会写) | +| `Cargo.toml` | lib 目标 + 依赖;末尾 `>>>GEN:PACK_DEPS` 段由 `pack-sync.py` 生成、**恒空** | 不手改 | | `src/routes.rs` | **唯一权威装配链**(面 A / 面 B 按判别头分流) | 不动 | | `src/bootstrap.rs` | **装配根**:平台表 + 各包 DDL + 业务菜单注入种子 | 不动 | | `src/compat.rs` | 契约面命名空间别名表(`compat::<域>::`,16 个域) | 不动 | diff --git a/src/backend/db/schema.sql b/src/backend/db/schema.sql index 79c2e9e..1d2d0ae 100644 --- a/src/backend/db/schema.sql +++ b/src/backend/db/schema.sql @@ -863,13 +863,14 @@ CREATE TABLE base_data_set_relation ( ); -- ============================================================================ --- 🔴 **示例业务表已搬进业务包**(2026-11-04): --- `demo_item` / `shop_product` / `book_shop_book` 的 DDL 现在住在 --- `packs/{demo,shop,books}/schema/001_init.sql`,由各包的 `include_str!` --- 编译进二进制 ⇒ 内核启动时按包顺序幂等执行。 +-- 🔴 **示例业务表已整体搬出本仓**(2026-11-04 零业务清理): +-- `demo_item` / `shop_product` / `book_shop_book` 的 DDL 现在住在**技能仓** +-- `ssw-jnpf-lite-rust` 的 `packs/{demo,shop,books}/schema/001_init.sql`, +-- 由各包的 `include_str!` 编译进二进制,经 `sspf::Platform::packs()` 注入。 +-- 本仓 `schema.sql` 只有 177 张平台表,启动时不建任何业务表。 -- --- 为什么搬:这三个是**示例装配**(技能要带走当样板),示例的 DDL 就该跟着 --- 示例走 —— 否则「把 packs/demo 整目录搬去技能」这件事永远缺一块。 +-- 为什么搬:这三个是**示例装配**,示例的 DDL 就该跟着示例走;平台仓零业务 +-- ⇒ 谁把示例表写回本文件,CP1 / check-module / 运行时探针会立刻红。 -- -- 🔴 **对 react 版的影响**(「两版后端能开同一个库」这条约定): -- 业务列名 / 列序 / 类型**逐字未变**;只是按平台规则补了 @@ -882,8 +883,8 @@ CREATE TABLE base_data_set_relation ( -- 🔴 **业务包的表不在本文件里**(批次 12 交付物 ③「DDL 跟着包走」)。 -- -- `asset_data_resource`(尚数网真实业务:数据资源)的建表语句现在住在 --- **`packs/asset/schema/001_init.sql`** ⇒ 由 `packs/asset/src/lib.rs` 用 --- `include_str!` **编译进二进制** ⇒ 内核启动时按包顺序幂等执行。 +-- **技能仓** `ssw-jnpf-lite-rust` 的 `packs/asset/schema/001_init.sql`, +-- 由业务仓装载后经 `sspf::Platform::packs()` 注入 ⇒ 同一个 `Db` 上建表。 -- -- 理由:加一张业务表不该改内核的 `schema.sql`(那是**平台层**的数据模型) -- ⇒ 业务表的 DDL 跟着**业务包**走 ⇒ 包目录能整目录搬走 ⇒ 单二进制部署。 diff --git a/src/backend/src/boot.rs b/src/backend/src/boot.rs index 1026110..7270ace 100644 --- a/src/backend/src/boot.rs +++ b/src/backend/src/boot.rs @@ -6,7 +6,7 @@ //! 业务仓(tdc-rs)零成本拿到同一把尺子 ⇒ 不需要抄 123 张表的名字。 //! //! 🔴 本模块**不读业务清单**:spec 与包 DDL 由调用方传进来 -//! (本仓 = `bootstrap::packs()` + `modules::all_specs()`;外部 = 门面注入)。 +//! (本仓 = 恒空的 `bootstrap::packs()` + `modules::all_specs()`;外部 = 门面注入)。 use std::path::{Path, PathBuf}; @@ -20,7 +20,7 @@ use sspf_plugin::PackDdl; /// /// 🔴 **只列 `base_*`**:业务表名是**业务知识** ⇒ 写死在这里 ⇒ /// 加一个业务模块要改入口文件 ⇒ 违反红线 12(「加一个业务模块只碰业务层」)。 -/// 业务表由 `modules::all_specs()` 派生,并与 `db/schema.sql` **对账** +/// 业务表由调用方注入的 spec / 包 DDL 派生,并与 `db/schema.sql` **对账** /// (见 [`whitelist_self_check`])⇒ 拼错 / 漏建 / 孤儿 DDL 三种错都抓得到。 /// /// 多应用 MVP 新增了平台表 `base_system`(`SystemEntity` 注册表, @@ -325,7 +325,7 @@ pub fn whitelist_self_check(specs: &[EntitySpec], pack_ddls: &[PackDdl]) -> Resu /// 本仓默认形态:spec 从业务层取、包表从 [`crate::bootstrap::packs`] 取。 /// -/// 🔴 默认 feature 下两者都为空(平台包不带业务)⇒ 只校验平台表与 `schema.sql` 对账。 +/// 🔴 平台包零业务 ⇒ 两者恒空 ⇒ 只校验平台表与 `schema.sql` 对账。 pub fn whitelist_self_check_platform() -> Result<(), String> { let reg = crate::bootstrap::packs().map_err(|e| format!("业务包装载失败: {e}"))?; whitelist_self_check(crate::modules::all_specs(), ®.ddls) @@ -468,27 +468,10 @@ mod tests { /// `crates/sspf-admin` 搬来 —— 那里只剩 CLI,没有再校验表清单的资格)。 /// /// 加业务表却忘了加 DDL(或反过来留了孤儿 DDL)⇒ 这里红,而不是等启动时 - /// `exit 1`。🔴 默认 feature 下 spec / 包 DDL 都是空的 ⇒ 只校验平台表那半, + /// `exit 1`。🔴 平台包零业务 ⇒ spec / 包 DDL 恒空 ⇒ 只校验平台表那半, /// 仍然有防错价值(`schema.sql` 里多一张没人认领的表也算孤儿)。 #[test] fn whitelist_self_check_passes_for_this_repo() { whitelist_self_check_platform().expect("本仓的表清单与 db/schema.sql 必须对得上"); } - - /// 🔴 `BASE_TABLES` 里只许有平台表:业务表名进来 ⇒ 加业务模块要改内核 - /// (红线 12:加一个业务模块只碰业务层)。 - /// - /// 🔴 只在 `example-packs` 下有意义(否则 spec 清单为空 ⇒ 断言天然成立 = 假闸门)。 - #[cfg(feature = "example-packs")] - #[test] - fn base_tables_carry_no_business_table() { - let base: Vec<&str> = BASE_TABLES.to_vec(); - for spec in crate::modules::all_specs() { - assert!( - !base.contains(&spec.table), - "BASE_TABLES 里不许出现业务表 {}", - spec.table - ); - } - } } diff --git a/src/backend/src/bootstrap.rs b/src/backend/src/bootstrap.rs index 6e22d6d..854eb1a 100644 --- a/src/backend/src/bootstrap.rs +++ b/src/backend/src/bootstrap.rs @@ -18,7 +18,7 @@ //! 🔴 **「加一个业务包」的完整动作**(批次 12.5 之后): //! //! ```bash -//! bash scripts/new-pack.sh --name "中文名" --columns "a:VARCHAR(200)" +//! 🔴 本仓零业务:包清单恒空;业务仓用 `sspf::Platform::packs(reg)` 注入。 //! ``` //! //! ⇒ 一条命令生成 `packs//`(真源)+ `modules/.rs`(面 A 适配器), @@ -237,153 +237,21 @@ pub fn version() -> &'static str { } #[cfg(test)] -mod feature_tests { - /// 🔴 **装载器必须跟着 feature 走**(2026-11-04 标准平台包)。 - /// - /// 🔴 不带 `cfg` 的原因同 `modules::feature_tests`:下面那组「4 个包都装得上」 - /// 的断言只在 `example-packs` 下编译 ⇒ 这里兜住「两组都没跑」的静默退化。 - #[test] - fn registry_follows_the_example_packs_feature() { - let reg = super::load_packs().expect("默认/示例 feature 都必须是可装载的形态"); - if cfg!(feature = "example-packs") { - assert!(!reg.entities.is_empty(), "开了 example-packs ⇒ 至少要装上一个包"); - } else { - assert!( - reg.entities.is_empty() && reg.ddls.is_empty(), - "默认 feature 是平台包:不得装载任何示例业务包" - ); - } - } -} - -#[cfg(all(test, feature = "example-packs"))] mod tests { - use super::*; - use sspf_contract::route::HttpMethod; - - /// 🔴 **业务包必须能装载**(批次 12 的核心验证物)。 - /// - /// 一旦包装载不过 ⇒ 「放个目录进 `packs/`」这个承诺就是假的。 - /// - /// 🔴 **不写死条数**(批次 12.5):条数由 `packs/*` 的目录数决定, - /// 写死会让「加一个包」变成「先改测试」⇒ 假闸门。 - /// 改成**结构性断言**:每个实体都要有 DDL、有菜单、有 3 条路由。 + /// 🔴 **平台包恒零业务**(2026-11-04 清理):`load_packs()` 必须返回空注册表。 + /// 业务仓通过 `sspf::Platform::packs(reg)` 注入,本仓一次都不读这个单例来装业务。 #[test] - fn every_pack_loads_with_entities_menus_routes_and_ddls() { - let reg = load_packs().expect("全部业务包必须装载成功"); - assert!(!reg.entities.is_empty(), "至少要装上一个包"); - assert!(!reg.manifests.is_empty(), "包清单不能为空(否则卸载/导出都无从下手)"); - - for spec in ®.entities { - assert!( - reg.ddls.iter().any(|d| d.table == spec.table), - "实体 {} 的表 {} 没有对应 DDL(表建不出来)", - spec.entity, - spec.table - ); - if let Some(key) = spec.module_key { - assert!( - reg.menus.iter().any(|m| m.url_address == key), - "实体 {} 的 module_key={} 没有对应菜单 ⇒ 守卫查不到菜单 ⇒ 静默放行", - spec.entity, - key - ); - } - } - // 每个实体恰好 3 条路由(List / Save / Delete)。 - assert_eq!( - reg.routes.len(), - reg.entities.len() * 3, - "每条实体应有 3 条路由(漏一条 ⇒ 某个动作静默 404)" - ); - - // 🔴 asset 是基准包:它的存在性是真断言,不是计数。 - assert!( - reg.ddls.iter().any(|d| d.table == "asset_data_resource"), - "asset 包必须在(基准包)" - ); + fn default_registry_is_empty() { + let reg = super::load_packs().expect("空注册表是合法形态"); + assert!(reg.entities.is_empty(), "平台包不得装载业务实体"); + assert!(reg.ddls.is_empty(), "平台包不得携带业务 DDL"); + assert!(reg.menus.is_empty(), "平台包不得携带业务菜单"); + assert!(reg.routes.is_empty(), "平台包不得携带业务路由"); } - /// 🔴 **包声明的路由必须是官方形状**(面 B),且方法与动作对应。 + /// `pack_router(空注册表)` 不注册任何端点(平台能力仍在,只是没有内容)。 #[test] - fn pack_routes_are_official_shape() { - let reg = load_packs().expect("asset 包必须装载成功"); - for r in ®.routes { - assert!(r.path.starts_with("/api/"), "必须是官方形状: {}", r.path); - assert!( - !r.path.starts_with("/api/ssw/"), - "不许用面 A 的 /api/ssw/...: {}", - r.path - ); - } - let list = reg - .routes - .iter() - .find(|r| r.method == HttpMethod::Get) - .expect("必须有 GET 路由"); - // 🔴 按**路径存在性**断言,不假设「第一条就是 asset」(包的装载顺序会变)。 - assert!( - reg.routes.iter().any(|r| r.path == "/api/asset/DataResource"), - "asset 的列表路由必须在(基准包);实际首条 GET 是 {}", - list.path - ); - } - - /// 🔴 **包的路由必须是官方 RESTful 形状**(不是「官方前缀 + ssw 动作后缀」)。 - /// - /// 🔴 实测官方源码(`jnpf-java-boot` 全部 controller): - /// `/xxx/List` GET 52 + POST 21(碰巧存在)、`/xxx/Save` **仅 4 条** - /// (低代码/打印/AI 特例)、`/xxx/Delete` **0 条**(不存在)。 - /// ⇒ CRUD 通用形状是 RESTful ⇒ 用后缀 = 集成时必然改路径。 - #[test] - fn pack_routes_use_official_restful_shape() { - let reg = load_packs().expect("asset 包必须装载成功"); - for r in ®.routes { - assert!( - !r.path.ends_with("/Save"), - "官方没有 /Save CRUD 端点: {}", - r.path - ); - assert!( - !r.path.ends_with("/Delete"), - "官方没有 /Delete 端点: {}", - r.path - ); - } - let del = reg - .routes - .iter() - .find(|r| r.method == HttpMethod::Delete) - .expect("必须有删除路由"); - assert!(del.path.contains("{id}"), "删除路由必须带 {{id}}: {}", del.path); - } - - /// 🔴 **包路由生成的 axum 路由条数 = 声明条数** —— 少一条就是漏注册。 - #[test] - fn pack_router_registers_all_declared_routes() { - let reg = load_packs().expect("全部业务包必须装载成功"); - // 🔴 生成路由不 panic = 路径合法(axum 遇到非法路径会 panic)。 - let _router = pack_router(®); - // 🔴 不写死 3:路由条数跟着包走(每条实体 3 条)。 - assert_eq!(reg.routes.len(), reg.entities.len() * 3); - } - - /// 🔴 **包的 DDL 必须含 `f_tenant_id`** —— 官方 `base_*` 表全部带它, - /// 参与复合主键 `(f_id, f_tenant_id)` ⇒ 缺这列导不进官方。 - #[test] - fn pack_ddls_carry_tenant_id_and_composite_key() { - let reg = load_packs().expect("全部业务包必须装载成功"); - for ddl in ®.ddls { - assert!( - ddl.sql.contains("f_tenant_id"), - "{} 的 DDL 缺 f_tenant_id(集成时导不进官方)", - ddl.table - ); - assert!( - ddl.sql.contains("PRIMARY KEY (f_id, f_tenant_id)"), - "{} 的主键必须是 (f_id, f_tenant_id)", - ddl.table - ); - } + fn pack_router_of_empty_registry_is_empty() { + let _ = super::pack_router(&sspf_plugin::PackRegistry::default()); } } diff --git a/src/backend/src/lib.rs b/src/backend/src/lib.rs index e75abb8..ec18b2c 100644 --- a/src/backend/src/lib.rs +++ b/src/backend/src/lib.rs @@ -13,9 +13,9 @@ //! | **`bootstrap.rs`** | 装配根:平台表 + 各包 DDL + 业务菜单注入种子(**唯一同时认识平台层与业务层的地方**) | — | 不动 | //! | **`compat.rs`** | 契约面**命名空间别名表**:`compat::<域>::` 共 16 个域 | `crates/sspf-compat-*` | 不动 | //! | **`forward.rs`** | **6 个转发壳**(低代码 4 + MCP 2),只有 `pub use` | `crates/sspf-lowcode-exec`、`crates/sspf-mcp-adapter` | 不动 | -//! | **`packs_gen.rs`** | ⚠️ **生成物**:业务包注册表 + `pack.toml` 快照 | `scripts/pack-sync.py` 读 `packs/*` | **不手改**;改完 `packs/` 跑脚本 | +//! | **`packs_gen.rs`** | ⚠️ **生成物**:恒空的业务包注册表(平台注入点) | `scripts/pack-sync.py` | **不手改** | //! | **`test_support.rs`** | 内核**单测**共享的进程级 pglite(`#[cfg(test)]`,仅 `routes.rs` 的单测用) | — | 不动 | -//! | **`modules/`** | **业务层**(面 A):spec + 菜单 + 路由汇总 | 4 个模块文件都是「面 A 适配器 + `pub use` 转发」→ `packs/{asset,demo,shop,books}` | ✅ **只动这里** | +//! | **`modules/`** | **业务装配点**(面 A):恒空的 spec / 菜单 / 路由汇总 | 生成物;业务由外部经门面注入 | 不动 | //! //! ## 三条边界(`scripts/check-arch.sh` 钉住,踩线即红) //! @@ -34,13 +34,14 @@ //! | 集成测试(37 个 `*_it.rs`) | `crates/tests/tests/` | //! | 平台核心(信封 / 登录 / 权限 / CRUD 引擎 / cipher) | `crates/sspf-core` | //! | 面 B 各域实现(system / permission / msg / workflow / ext / onlinedev) | `crates/sspf-compat-*` | -//! | 业务包真源 | `packs/`;内核侧 `modules/.rs` 只是「面 A 适配器 + `pub use` 转发」 | +//! | 业务包真源 | **业务仓**(本仓零业务);技能仓 `ssw-jnpf-lite-rust` 有 4 个示例包 | //! -//! ## 业务层当前长什么样(2026-11-04) +//! ## 平台包零业务(2026-11-04 清理) //! -//! `packs/` 下 4 个包:`asset`(真实业务:数据资源)+ `demo` / `shop` / `books` -//! (**示例包**,技能要带走当样板)。内核的 `modules/*.rs` 里**没有任何 spec** -//! (`check-arch.sh` 的 PACK1 钉住)—— 加业务模块跑 `bash scripts/new-pack.sh`。 +//! `packs/{asset,books,demo,shop}` 与 `modules/*.rs` 的 4 个面 A 适配器已整体搬到 +//! 技能仓 `ssw-jnpf-lite-rust`(`v0.3.0` tag 完整保留旧形态)。本仓只留**注入点**: +//! `sspf::Platform::packs(reg)` / `.router()` / `.menus()` / `.ddl()`。 +//! ⇒ `cargo tree -p sspf` 里没有 `sspf-pack-*`,`/api/health` 是 177 张平台表。 pub mod bootstrap; /// 🔴 **进程级启动原语**(定位项目根 / 白名单自检 / 开库 / 优雅停机)。 @@ -59,7 +60,7 @@ pub use forward::{ pub mod modules; /// 🔴 **本文件是 `scripts/pack-sync.py` 生成的**(业务包清单 + `pack.toml` 快照) -/// ⇒ 不要手改;加包跑 `bash scripts/new-pack.sh`。 +/// ⇒ 不要手改;本仓零业务,业务包由业务仓经 `sspf::Platform::packs()` 注入。 pub mod packs_gen; pub mod routes; /// 内核**单测**共享的 pglite 实例(`routes.rs` 的 `#[cfg(test)]` 用)。 diff --git a/src/backend/src/modules/asset.rs b/src/backend/src/modules/asset.rs deleted file mode 100644 index bb37ea3..0000000 --- a/src/backend/src/modules/asset.rs +++ /dev/null @@ -1,88 +0,0 @@ -//! asset —— 业务模块:DataResource(物理表 `asset_data_resource`)。 -//! -//! 🔴 **本文件是「spec 的转发点」,不是 spec 的家**(批次 12 交付物 ②): -//! 真正的 spec 在 `packs/asset/src/lib.rs`(业务包,**只依赖 sspf-sdk**), -//! 本文件只做 `pub use` 转发 ⇒ **spec 只有一份**。 -//! -//! 🔴 **为什么这么改**(原来的问题是「两份逐字拷贝」): -//! 改一处忘另一处 ⇒ **静默**不一致(而且没有任何闸门比对它们 —— -//! `packs/asset` 的注释写着「PACK1 会比对」,但 PACK1 **至今没实现**)。 -//! ⇒ 现在:spec 在包里 ⇒ 改 spec 只改一处 ⇒ PACK1 闸门校验「模块文件只许 re-export」。 -//! -//! 🔴 **【集成期友好性】面 A 与面 B 各住一处**(批次 12 交付物 ①): -//! - **本文件 = 面 A**(`/api/ssw/asset/DataResource/…`)—— 本仓自造的 ssw 约定, -//! **留给 Rust 终端场景**,**一个字都不改**; -//! - **业务包 = 面 B**(`/api/asset/DataResource/…`)—— 官方 JNPF 形状, -//! 集成到官方 Java 时**能直接搬**(`MIGRATION.md` §2.3 的逐条对照表)。 -//! -//! 🔴 **两套路由不冲突**(路径不同)⇒ 面 A 的前端零改、面 B 的集成期零改。 -//! -//! 🔴 **业务 DDL 跟着包走**(批次 12 交付物 ③):`asset_data_resource` 的建表语句 -//! 在 `packs/asset/schema/001_init.sql`,**编译进二进制**(`include_str!`), -//! 不再手抄进 `db/schema.sql`。 - -use axum::body::Bytes; -use axum::extract::{RawQuery, State}; -use axum::http::HeaderMap; -use axum::routing::{delete, get, post}; -use axum::{Json, Router}; - -use sspf_core::crud::{handle_delete, handle_list, handle_save}; -use sspf_core::envelope::ActionResult; -use sspf_core::state::AppState; - -// 🔴 **spec 与菜单的单一真源 = 业务包** —— 这里只转发,不重写。 -pub use sspf_pack_asset::DATA_RESOURCE_MENU; -pub use sspf_pack_asset::DATA_RESOURCE_SPEC; - -/// 本模块的 3 条路由(**面 A**:业务层的路由表)—— 钉子测试遍历它。 -/// -/// 🔴 路径是**面 A 的 ssw 形状**(`/api/ssw/{appCode}/{Entity}/{动作}`)—— -/// 业务包声明的**面 B**(官方形状)在 `packs/asset/src/lib.rs`, -/// 由内核按声明生成(见 `bootstrap::pack_router`)。 -pub const ROUTES: [&str; 3] = [ - "/api/ssw/asset/DataResource/List", - "/api/ssw/asset/DataResource/Save", - "/api/ssw/asset/DataResource/Delete", -]; - -/// `GET /api/ssw/asset/DataResource/List`。 -pub async fn data_resource_list( - State(state): State, - headers: HeaderMap, -) -> Json { - handle_list(&state, &headers, &DATA_RESOURCE_SPEC).await -} - -/// `POST /api/ssw/asset/DataResource/Save`。 -pub async fn data_resource_save( - State(state): State, - headers: HeaderMap, - body: Bytes, -) -> Json { - handle_save(&state, &headers, &DATA_RESOURCE_SPEC, &body).await -} - -/// `DELETE /api/ssw/asset/DataResource/Delete?id=`。 -pub async fn data_resource_delete( - State(state): State, - headers: HeaderMap, - raw: RawQuery, -) -> Json { - handle_delete(&state, &headers, &DATA_RESOURCE_SPEC, &raw).await -} - -/// 本模块的路由(**面 A**,`Router::merge` 进总路由)。 -/// -/// 🔴 路径在这里写**字面量**(不用 `ROUTES[0]`)—— 契约扫描器 -/// `scripts/check-contract-scan.py` 是静态解析,认不出数组下标 ⇒ -/// 写成下标会让 `check-contract.sh` 判「契约登记了、代码里没有」(假飘移)。 -pub fn router() -> Router { - Router::new() - .route("/api/ssw/asset/DataResource/List", get(data_resource_list)) - .route("/api/ssw/asset/DataResource/Save", post(data_resource_save)) - .route( - "/api/ssw/asset/DataResource/Delete", - delete(data_resource_delete), - ) -} diff --git a/src/backend/src/modules/books.rs b/src/backend/src/modules/books.rs deleted file mode 100644 index 79f63e5..0000000 --- a/src/backend/src/modules/books.rs +++ /dev/null @@ -1,75 +0,0 @@ -//! books —— 业务模块:Book(物理表 `book_shop_book`)。 -//! -//! 🔴 **本文件是「面 A 适配器 + spec 的转发点」,不是 spec 的家**: -//! 真源在 `packs/books/src/lib.rs`(业务包,**只依赖 sspf-sdk**), -//! 本文件只做 `pub use` 转发 ⇒ **spec 只有一份**(`check-arch.sh` 的 PACK1 钉住)。 -//! -//! 🔴 **面 A 与面 B 各住一处**: -//! - **本文件 = 面 A**(`/api/ssw/books/Book/…`)—— 本仓自造的 ssw 约定, -//! 留给 Rust 终端场景,**一个字都不改**(前端在用它); -//! - **业务包 = 面 B**(`/api/books/Book`)—— 官方 JNPF 形状, -//! 集成到官方 Java 时能直接搬。 -//! -//! 🔴 **DDL 跟着包走**:`book_shop_book` 的建表语句在 `packs/books/schema/001_init.sql`, -//! 编译进二进制 ⇒ 不再手抄进 `db/schema.sql`。 -//! -//! 🔴 **本包是示例包**:`packs/books` 整目录可搬去技能当样板,本文件是它在本仓的 -//! 面 A 适配器(技能带走示例时,这份适配器可以不要)。 - -use axum::body::Bytes; -use axum::extract::{RawQuery, State}; -use axum::http::HeaderMap; -use axum::routing::{delete, get, post}; -use axum::{Json, Router}; - -use sspf_core::crud::{handle_delete, handle_list, handle_save}; -use sspf_core::envelope::ActionResult; -use sspf_core::state::AppState; - -// 🔴 **spec 与菜单的单一真源 = 业务包** —— 这里只转发,不重写。 -pub use sspf_pack_books::BOOK_MENU; -pub use sspf_pack_books::BOOK_SPEC; - -/// 本模块的 3 条路由(**面 A**:业务层的路由表)—— 钉子测试遍历它。 -/// -/// 🔴 路径写字面量(不用下标):`scripts/check-contract-scan.py` 是静态解析, -/// 认不出数组下标 ⇒ 写下标会让契约闸门判「登记了、代码里没有」。 -pub const ROUTES: [&str; 3] = [ - "/api/ssw/books/Book/List", - "/api/ssw/books/Book/Save", - "/api/ssw/books/Book/Delete", -]; - -/// `GET /api/ssw/books/Book/List`。 -pub async fn book_list( - State(state): State, - headers: HeaderMap, -) -> Json { - handle_list(&state, &headers, &BOOK_SPEC).await -} - -/// `POST /api/ssw/books/Book/Save`。 -pub async fn book_save( - State(state): State, - headers: HeaderMap, - body: Bytes, -) -> Json { - handle_save(&state, &headers, &BOOK_SPEC, &body).await -} - -/// `DELETE /api/ssw/books/Book/Delete?id=`。 -pub async fn book_delete( - State(state): State, - headers: HeaderMap, - raw: RawQuery, -) -> Json { - handle_delete(&state, &headers, &BOOK_SPEC, &raw).await -} - -/// 本模块的路由(**面 A**,`Router::merge` 进总路由)。 -pub fn router() -> Router { - Router::new() - .route("/api/ssw/books/Book/List", get(book_list)) - .route("/api/ssw/books/Book/Save", post(book_save)) - .route("/api/ssw/books/Book/Delete", delete(book_delete)) -} diff --git a/src/backend/src/modules/demo.rs b/src/backend/src/modules/demo.rs deleted file mode 100644 index 49462be..0000000 --- a/src/backend/src/modules/demo.rs +++ /dev/null @@ -1,75 +0,0 @@ -//! demo —— 业务模块:DemoItem(物理表 `demo_item`)。 -//! -//! 🔴 **本文件是「面 A 适配器 + spec 的转发点」,不是 spec 的家**: -//! 真源在 `packs/demo/src/lib.rs`(业务包,**只依赖 sspf-sdk**), -//! 本文件只做 `pub use` 转发 ⇒ **spec 只有一份**(`check-arch.sh` 的 PACK1 钉住)。 -//! -//! 🔴 **面 A 与面 B 各住一处**: -//! - **本文件 = 面 A**(`/api/ssw/demo/DemoItem/…`)—— 本仓自造的 ssw 约定, -//! 留给 Rust 终端场景,**一个字都不改**(前端在用它); -//! - **业务包 = 面 B**(`/api/demo/DemoItem`)—— 官方 JNPF 形状, -//! 集成到官方 Java 时能直接搬。 -//! -//! 🔴 **DDL 跟着包走**:`demo_item` 的建表语句在 `packs/demo/schema/001_init.sql`, -//! 编译进二进制 ⇒ 不再手抄进 `db/schema.sql`。 -//! -//! 🔴 **本包是示例包**:`packs/demo` 整目录可搬去技能当样板,本文件是它在本仓的 -//! 面 A 适配器(技能带走示例时,这份适配器可以不要)。 - -use axum::body::Bytes; -use axum::extract::{RawQuery, State}; -use axum::http::HeaderMap; -use axum::routing::{delete, get, post}; -use axum::{Json, Router}; - -use sspf_core::crud::{handle_delete, handle_list, handle_save}; -use sspf_core::envelope::ActionResult; -use sspf_core::state::AppState; - -// 🔴 **spec 与菜单的单一真源 = 业务包** —— 这里只转发,不重写。 -pub use sspf_pack_demo::DEMO_MENU; -pub use sspf_pack_demo::DEMO_SPEC; - -/// 本模块的 3 条路由(**面 A**:业务层的路由表)—— 钉子测试遍历它。 -/// -/// 🔴 路径写字面量(不用下标):`scripts/check-contract-scan.py` 是静态解析, -/// 认不出数组下标 ⇒ 写下标会让契约闸门判「登记了、代码里没有」。 -pub const ROUTES: [&str; 3] = [ - "/api/ssw/demo/DemoItem/List", - "/api/ssw/demo/DemoItem/Save", - "/api/ssw/demo/DemoItem/Delete", -]; - -/// `GET /api/ssw/demo/DemoItem/List`。 -pub async fn demo_item_list( - State(state): State, - headers: HeaderMap, -) -> Json { - handle_list(&state, &headers, &DEMO_SPEC).await -} - -/// `POST /api/ssw/demo/DemoItem/Save`。 -pub async fn demo_item_save( - State(state): State, - headers: HeaderMap, - body: Bytes, -) -> Json { - handle_save(&state, &headers, &DEMO_SPEC, &body).await -} - -/// `DELETE /api/ssw/demo/DemoItem/Delete?id=`。 -pub async fn demo_item_delete( - State(state): State, - headers: HeaderMap, - raw: RawQuery, -) -> Json { - handle_delete(&state, &headers, &DEMO_SPEC, &raw).await -} - -/// 本模块的路由(**面 A**,`Router::merge` 进总路由)。 -pub fn router() -> Router { - Router::new() - .route("/api/ssw/demo/DemoItem/List", get(demo_item_list)) - .route("/api/ssw/demo/DemoItem/Save", post(demo_item_save)) - .route("/api/ssw/demo/DemoItem/Delete", delete(demo_item_delete)) -} diff --git a/src/backend/src/modules/mod.rs b/src/backend/src/modules/mod.rs index 60627fd..b28172c 100644 --- a/src/backend/src/modules/mod.rs +++ b/src/backend/src/modules/mod.rs @@ -3,7 +3,7 @@ //! 🔴 **加一个业务模块只碰本目录,而且不用手改本文件**(批次 12.5): //! //! ```bash -//! bash scripts/new-pack.sh --name "中文名" --columns "a:VARCHAR(200)" +//! 🔴 本仓零业务:五个生成段恒空;业务路由由业务仓经门面注入。 //! ``` //! //! 它会建 `packs//`(真源)+ 本目录的 `.rs`(面 A 适配器), @@ -31,70 +31,22 @@ use sspf_core::menu::MenuSpec; use sspf_core::state::AppState; // >>>GEN:MODS -// 每个模块一行:**文件即登记**(顺序 = 文件名字典序,不代表业务顺序)。 -// 🔴 只在 `example-packs` 下编译 —— 默认 feature 的内核**不认识任何业务模块**。 -#[cfg(feature = "example-packs")] -pub mod asset; -#[cfg(feature = "example-packs")] -pub mod books; -#[cfg(feature = "example-packs")] -pub mod demo; -#[cfg(feature = "example-packs")] -pub mod shop; +// 🔴 **平台包零业务**:本仓不认识任何业务模块。 +// 业务模块的路由由业务仓经 `sspf::Platform::router()` 注入。 // <<>>GEN:SPECS -/// 全部业务实体 spec。 -/// -/// 🔴 **本段由 `scripts/pack-sync.py` 生成** —— 加模块不用手改(见文件头)。 -#[cfg(feature = "example-packs")] -pub const ALL_SPECS: &[EntitySpec] = &[ - asset::DATA_RESOURCE_SPEC, - books::BOOK_SPEC, - demo::DEMO_SPEC, - shop::PRODUCT_SPEC, -]; -/// 默认 feature:平台侧零业务 ⇒ 空清单(业务仓用 `sspf::Platform::packs` 注入)。 -#[cfg(not(feature = "example-packs"))] +/// 本仓业务实体 spec:恒为空(平台包零业务)。 pub const ALL_SPECS: &[EntitySpec] = &[]; // <<>>GEN:ROUTES -/// **全部业务路由**(面 A:`/api/ssw/{appCode}/{Entity}/{动作}`,每模块 3 条)。 -/// -/// 🔴 **与 `ALL_SPECS` 同序**(同一份模块清单生成)⇒ 可以按 3 条一组配对。 -#[cfg(feature = "example-packs")] -pub const ALL_ROUTES: &[&str] = &[ - asset::ROUTES[0], - asset::ROUTES[1], - asset::ROUTES[2], - books::ROUTES[0], - books::ROUTES[1], - books::ROUTES[2], - demo::ROUTES[0], - demo::ROUTES[1], - demo::ROUTES[2], - shop::ROUTES[0], - shop::ROUTES[1], - shop::ROUTES[2], -]; -/// 默认 feature:没有业务路由可登记。 -#[cfg(not(feature = "example-packs"))] +/// 本仓业务路由表:恒为空(平台包零业务)。 pub const ALL_ROUTES: &[&str] = &[]; // <<>>GEN:MENUS -/// 全部业务内置菜单(由**装配根** [`crate::bootstrap`] 传给平台层的种子 -/// ⇒ **平台层不认任何业务菜单**,红线 12)。 -#[cfg(feature = "example-packs")] -pub const ALL_MENUS: &[MenuSpec] = &[ - asset::DATA_RESOURCE_MENU, - books::BOOK_MENU, - demo::DEMO_MENU, - shop::PRODUCT_MENU, -]; -/// 默认 feature:平台侧零业务 ⇒ 种子只种平台菜单。 -#[cfg(not(feature = "example-packs"))] +/// 本仓业务内置菜单:恒为空;业务菜单由 `.menus()` / `.packs()` 注入。 pub const ALL_MENUS: &[MenuSpec] = &[]; // << Option<&'static EntitySpec> { } // >>>GEN:ROUTER -/// **全部业务模块的路由**(`Router::merge` 进总路由)。 -/// -/// 🔴 加业务模块 ⇒ **不用改这里**(本段由 `pack-sync.py` 生成)。 -#[cfg(feature = "example-packs")] -pub fn router() -> Router { - asset::router() - .merge(books::router()) - .merge(demo::router()) - .merge(shop::router()) -} -/// 默认 feature:没有任何业务路由。 -#[cfg(not(feature = "example-packs"))] +/// 本仓业务路由:恒为空。 pub fn router() -> Router { Router::new() } // <<= 4, - "开了 example-packs ⇒ 至少要保住 demo/shop/books/asset 四个模块" - ); - assert!( - !all_menus().is_empty(), - "开了 example-packs ⇒ 业务菜单不能是空的(否则面 B 点权限全 403)" - ); - assert!( - !ALL_ROUTES.is_empty(), - "开了 example-packs ⇒ 业务路由不能是空的" - ); - } else { - assert!( - all_specs().is_empty() && all_menus().is_empty() && ALL_ROUTES.is_empty(), - "默认 feature 是**平台包**:不得携带任何业务 spec / 菜单 / 路由" - ); - } - } -} - -#[cfg(all(test, feature = "example-packs"))] mod tests { use super::*; - use sspf_core::db; - /// spec 表里 app_code + entity 唯一,且四个基准模块都在。 + /// 🔴 **平台包恒零业务**(2026-11-04 清理):示例模块已搬到技能仓, + /// 本仓的 spec / 菜单 / 路由清单**必须全空**。任何一项非空 ⇒ 业务回流。 /// - /// 🔴 **不写死条数**(批次 12.5):条数由 `modules/*.rs` 文件数决定, - /// 加一个模块就 +1 ⇒ 写死会变成「加模块必须先改测试」的假闸门。 + /// 🔴 这条是「尺子会不会变瞎」的探针:不带 `cfg` ⇒ 任何构建都会跑, + /// 不会出现「测试数悄悄变少」而没人发现。 #[test] - fn all_specs_are_unique_and_complete() { - let specs = all_specs(); - assert!(specs.len() >= 4, "至少要保住 demo/shop/books/asset 四个模块"); - for (i, s) in specs.iter().enumerate() { - for other in &specs[i + 1..] { - assert!( - !(s.app_code == other.app_code && s.entity == other.entity), - "app_code + entity 必须唯一: {} / {}", - s.app_code, - s.entity - ); - } - } - assert!(find_spec("demo", "DemoItem").is_some()); - assert!(find_spec("shop", "Product").is_some()); - assert!(find_spec("books", "Book").is_some()); - assert!(find_spec("asset", "DataResource").is_some()); - assert!(find_spec("demo", "Product").is_none()); - assert!(find_spec("nope", "Book").is_none()); + fn platform_carries_no_business_modules() { + assert!(all_specs().is_empty(), "平台包不得携带业务 spec"); + assert!(all_menus().is_empty(), "平台包不得携带业务菜单"); + assert!(ALL_ROUTES.is_empty(), "平台包不得携带业务路由"); + assert!(find_spec("demo", "DemoItem").is_none(), "平台包不认任何业务实体"); } - /// 🔴 每列的 `json_key` 必须等于 `db::column_to_json_key(column)` - /// (`f_title` ⇒ `title`)—— 不一致 ⇒ 投影别名与 body 键会对不上,且**静默**。 + /// 业务路由恒为空 ⇒ `router()` 不注册任何端点。 #[test] - fn every_json_key_matches_the_contract_mapping() { - for spec in all_specs() { - for col in spec.columns { - assert_eq!( - db::column_to_json_key(col.column), - col.json_key, - "{} 的 {} 的 json_key 不对", - spec.table, - col.column - ); - } - } - } - - /// `numeric_columns` 与每列的 `numeric` 标记必须一致。 - #[test] - fn numeric_columns_matches_column_flags() { - for spec in all_specs() { - for col in spec.columns { - let listed = spec.numeric_columns.contains(&col.column); - assert_eq!( - listed, col.numeric, - "{} 的 {} 的 numeric 标记与 numeric_columns 不一致", - spec.table, col.column - ); - } - } - } - - /// 契约 §5.3 的四张基准表列清单(**逐字**):列名与列序。 - /// - /// 🔴 **按 (app, entity) 查找,不按数组下标 zip** —— 生成段的顺序随 - /// `modules/*.rs` 文件名变化 ⇒ 用下标取值是「顺序一变就假失败」。 - #[test] - fn column_sets_match_contract_5_3() { - let names = |app: &str, ent: &str| -> Vec<&str> { - find_spec(app, ent) - .expect("基准模块必须在") - .columns - .iter() - .map(|c| c.column) - .collect() - }; - assert_eq!( - names("demo", "DemoItem"), - vec![ - "f_id", - "f_title", - "f_status", - "f_creator_user_id", - "f_creator_time", - "f_delete_mark" - ] - ); - assert_eq!( - names("shop", "Product"), - vec![ - "f_id", - "f_title", - "f_price", - "f_creator_user_id", - "f_creator_time", - "f_delete_mark" - ] - ); - assert_eq!( - names("books", "Book"), - vec![ - "f_id", - "f_title", - "f_author", - "f_isbn", - "f_category", - "f_price", - "f_stock", - "f_creator_user_id", - "f_creator_time", - "f_delete_mark" - ] - ); - // 🔴 asset:列序**逐字对齐公司本体 `DataResource`**(数据资源), - // 末尾多一列 `f_tenant_id` —— 官方 `base_*` 表全部带它 - // (`DEFAULT '0' NOT NULL`,参与复合主键 `(f_id, f_tenant_id)`) - // ⇒ **单租户也不许省**(集成时缺这一列 ⇒ 导不进官方)。 - assert_eq!( - names("asset", "DataResource"), - vec![ - "f_id", - "f_name", - "f_category", - "f_scenario", - "f_provider", - "f_format", - "f_scale", - "f_source", - "f_register_time", - "f_creator_user_id", - "f_creator_time", - "f_delete_mark", - "f_tenant_id" - ] - ); - } - - /// 守卫 key:demo 仅登录,其余基准三个有菜单守卫。 - #[test] - fn module_keys_are_as_specified() { - assert_eq!(find_spec("demo", "DemoItem").unwrap().module_key, None); - assert_eq!( - find_spec("shop", "Product").unwrap().module_key, - Some("shop/Product") - ); - assert_eq!( - find_spec("books", "Book").unwrap().module_key, - Some("books/Book") - ); - assert_eq!( - find_spec("asset", "DataResource").unwrap().module_key, - Some("asset/DataResource") - ); - } - - /// 表名必须过白名单(拼进 SQL 前还要再过一次,但 spec 本身就应当是合法标识符)。 - #[test] - fn table_names_are_valid_identifiers() { - for spec in all_specs() { - assert!(db::valid_table(spec.table).is_some(), "非法表名: {}", spec.table); - for col in spec.columns { - assert!( - db::valid_column(col.column).is_some(), - "非法列名: {}", - col.column - ); - } - } - } - - /// 🔴 裁决 S22:`f_creator_user_id` 的写死规则**由业务 spec 声明**,平台层不认 app_code。 - #[test] - fn creator_fixed_rules_are_declared_by_the_business_specs() { - assert_eq!( - find_spec("demo", "DemoItem").unwrap().creator_fixed, - Some("admin") - ); - assert_eq!(find_spec("shop", "Product").unwrap().creator_fixed, None); - assert_eq!(find_spec("books", "Book").unwrap().creator_fixed, None); - assert_eq!( - find_spec("asset", "DataResource").unwrap().creator_fixed, - None - ); - } - - /// 🔴 **业务路由的形状钉死** —— 每条必须是 `/api/ssw/{app_code}/{entity}/{List|Save|Delete}`。 - /// - /// 🔴 **`ALL_ROUTES` 与 `ALL_SPECS` 同序**(两段都由 `pack-sync.py` 按同一份 - /// 模块清单生成)⇒ 可以按 3 条一组配对。这个「同序」由本测试兜住: - /// 一旦有人手改生成段导致错位,下面的路径断言立刻红。 - #[test] - fn business_routes_follow_the_contract_shape() { - assert_eq!( - ALL_ROUTES.len(), - ALL_SPECS.len() * 3, - "每个模块 3 条路由;ALL_ROUTES 与 ALL_SPECS 必须同序(生成段不许手改)" - ); - - for (spec, routes) in ALL_SPECS.iter().zip(ALL_ROUTES.chunks(3)) { - for (path, action) in routes.iter().zip(["List", "Save", "Delete"]) { - let expected = format!("/api/ssw/{}/{}/{}", spec.app_code, spec.entity, action); - assert_eq!( - *path, expected, - "{} 的路由形状不对(契约:/api/ssw/{{appCode}}/{{Entity}}/{{List|Save|Delete}})", - spec.entity - ); - } - } - } - - /// 🔴 **菜单的 `url_address` 必须与 spec 的 `module_key` 一字不差**(有守卫的模块)。 - /// - /// 🔴 三处必须一致:① 菜单的 `f_url_address` ② spec 的 `module_key` - /// ③ 前端 `` —— 任一不一致 ⇒ 菜单显示了但守卫不命中 - /// (或反过来)⇒ **静默**失败。 - /// - /// 🔴 **按 `url_address` 查找,不按数组下标配对** —— 菜单与 spec 是两份声明, - /// 用下标配对相当于假设「每个模块恰好 1 个实体 + 1 个菜单」。 - #[test] - fn every_spec_with_module_key_has_a_matching_menu() { - for spec in all_specs() { - let Some(key) = spec.module_key else { - continue; // 仅需登录的模块(demo)没有菜单守卫 - }; - let menu = all_menus() - .iter() - .find(|m| m.url_address == key) - .unwrap_or_else(|| { - panic!( - "{} 的 module_key 是 {},但没有菜单的 url_address 等于它", - spec.entity, key - ) - }); - assert!( - !menu.en_code.trim().is_empty(), - "菜单 {} 的 f_en_code 不能为空(面 B 的点权限判据靠它)", - menu.id - ); - } - } - - /// 🔴 **菜单 id / url 必须唯一**(id 是种子 INSERT 的固定字面量主键 ⇒ 撞了就 exit 1)。 - #[test] - fn menus_are_unique() { - for (i, m) in ALL_MENUS.iter().enumerate() { - for other in &ALL_MENUS[i + 1..] { - assert_ne!(m.id, other.id, "菜单 id 重复: {}", m.id); - assert_ne!( - m.url_address, other.url_address, - "菜单 url_address 重复: {}", - m.url_address - ); - } - } + fn router_is_empty() { + let _: Router = router(); } } diff --git a/src/backend/src/modules/shop.rs b/src/backend/src/modules/shop.rs deleted file mode 100644 index 744810e..0000000 --- a/src/backend/src/modules/shop.rs +++ /dev/null @@ -1,75 +0,0 @@ -//! shop —— 业务模块:Product(物理表 `shop_product`)。 -//! -//! 🔴 **本文件是「面 A 适配器 + spec 的转发点」,不是 spec 的家**: -//! 真源在 `packs/shop/src/lib.rs`(业务包,**只依赖 sspf-sdk**), -//! 本文件只做 `pub use` 转发 ⇒ **spec 只有一份**(`check-arch.sh` 的 PACK1 钉住)。 -//! -//! 🔴 **面 A 与面 B 各住一处**: -//! - **本文件 = 面 A**(`/api/ssw/shop/Product/…`)—— 本仓自造的 ssw 约定, -//! 留给 Rust 终端场景,**一个字都不改**(前端在用它); -//! - **业务包 = 面 B**(`/api/shop/Product`)—— 官方 JNPF 形状, -//! 集成到官方 Java 时能直接搬。 -//! -//! 🔴 **DDL 跟着包走**:`shop_product` 的建表语句在 `packs/shop/schema/001_init.sql`, -//! 编译进二进制 ⇒ 不再手抄进 `db/schema.sql`。 -//! -//! 🔴 **本包是示例包**:`packs/shop` 整目录可搬去技能当样板,本文件是它在本仓的 -//! 面 A 适配器(技能带走示例时,这份适配器可以不要)。 - -use axum::body::Bytes; -use axum::extract::{RawQuery, State}; -use axum::http::HeaderMap; -use axum::routing::{delete, get, post}; -use axum::{Json, Router}; - -use sspf_core::crud::{handle_delete, handle_list, handle_save}; -use sspf_core::envelope::ActionResult; -use sspf_core::state::AppState; - -// 🔴 **spec 与菜单的单一真源 = 业务包** —— 这里只转发,不重写。 -pub use sspf_pack_shop::PRODUCT_MENU; -pub use sspf_pack_shop::PRODUCT_SPEC; - -/// 本模块的 3 条路由(**面 A**:业务层的路由表)—— 钉子测试遍历它。 -/// -/// 🔴 路径写字面量(不用下标):`scripts/check-contract-scan.py` 是静态解析, -/// 认不出数组下标 ⇒ 写下标会让契约闸门判「登记了、代码里没有」。 -pub const ROUTES: [&str; 3] = [ - "/api/ssw/shop/Product/List", - "/api/ssw/shop/Product/Save", - "/api/ssw/shop/Product/Delete", -]; - -/// `GET /api/ssw/shop/Product/List`。 -pub async fn product_list( - State(state): State, - headers: HeaderMap, -) -> Json { - handle_list(&state, &headers, &PRODUCT_SPEC).await -} - -/// `POST /api/ssw/shop/Product/Save`。 -pub async fn product_save( - State(state): State, - headers: HeaderMap, - body: Bytes, -) -> Json { - handle_save(&state, &headers, &PRODUCT_SPEC, &body).await -} - -/// `DELETE /api/ssw/shop/Product/Delete?id=`。 -pub async fn product_delete( - State(state): State, - headers: HeaderMap, - raw: RawQuery, -) -> Json { - handle_delete(&state, &headers, &PRODUCT_SPEC, &raw).await -} - -/// 本模块的路由(**面 A**,`Router::merge` 进总路由)。 -pub fn router() -> Router { - Router::new() - .route("/api/ssw/shop/Product/List", get(product_list)) - .route("/api/ssw/shop/Product/Save", post(product_save)) - .route("/api/ssw/shop/Product/Delete", delete(product_delete)) -} diff --git a/src/backend/src/packs_gen.rs b/src/backend/src/packs_gen.rs index 953a796..f0c75be 100644 --- a/src/backend/src/packs_gen.rs +++ b/src/backend/src/packs_gen.rs @@ -1,171 +1,24 @@ //! ⚠️ **本文件由 `scripts/pack-sync.py` 生成 —— 不许手改。** //! -//! 它是内核的**业务包清单**:每个包一条 [`sspf_plugin::load_static`] -//! 调用 + 一份 `pack.toml` 的 JSON 快照。 +//! **平台包零业务**(2026-11-04):本仓不认识任何业务包。 +//! 业务仓通过 `sspf::Platform::packs(reg)` 注入自己装载的注册表, +//! 由 `crate::bootstrap` 在**同一个 `Db`** 上装配路由与 DDL。 //! -//! 🔴 **为什么是生成的**:批次 12 时这段在 `bootstrap.rs` 里手写 —— -//! 每加一个包要抄「manifest JSON + `PackSource` + `merge(vec![…])`」三段。 -//! 漏掉最后那段 `merge` 的表现是:包**装载成功**、没有报错, -//! 但 `entities` / `routes` 全丢 ⇒ **面 B 端点静默 404**。 -//! ⇒ 改成生成 ⇒ 「漏一处」在机制上不存在;真忘了跑生成, -//! `scripts/verify.sh` 的第一步(`pack-sync.py --check`)会红。 -//! -//! 🔴 **`packs/` 是唯一真源** —— 加包跑 `bash scripts/new-pack.sh`, -//! 改完 `packs/*` 跑 `python3 scripts/pack-sync.py`。 -//! -//! 🔴 **默认 feature 下本文件不装载任何包**(2026-11-04 标准平台包): -//! 4 个示例包降为 `example-packs` feature(只有 `sspf-admin` 与 `sspf-tests` 开)。 -//! 业务仓只依赖门面 `sspf` ⇒ `cargo tree` 里**没有** `sspf-pack-*` -//! ⇒ 平台包里零业务(`check-arch.sh` 的 AR17 钉住)。 +//! 🔴 为什么留着这个空文件:`bootstrap::load_packs()` / 白名单自检 / +//! `Extras::kernel()` 都是**平台能力**(业务仓要用),删掉会逼着每个 +//! 业务仓自己抄一遍。留一个恒空的默认实现 ⇒ 平台侧零业务且不破装配链。 use sspf_plugin::{LoadError, PackRegistry}; -/// 装载 `packs/*` 下的**全部**业务包(顺序 = `app_code` 字典序)。 +/// 本仓业务包清单:恒为空。 /// -/// 🔴 任一包装载失败 ⇒ **整体失败**(半加载的包比不加载更危险): -/// 半加载的包 = 一部分路由在、一部分不在 ⇒ 前端表现为「有的页面能用」。 -#[cfg(feature = "example-packs")] -pub fn registry(kernel_version: &str) -> Result { - let mut regs: Vec = Vec::new(); - - // ---- asset ---- - regs.push(sspf_plugin::load_static( - "asset", - ASSET_MANIFEST_JSON, - Box::new(sspf_pack_asset::Pack), - sspf_pack_asset::DDLS, - kernel_version, - )?); - - // ---- books ---- - regs.push(sspf_plugin::load_static( - "books", - BOOKS_MANIFEST_JSON, - Box::new(sspf_pack_books::Pack), - sspf_pack_books::DDLS, - kernel_version, - )?); - - // ---- demo ---- - regs.push(sspf_plugin::load_static( - "demo", - DEMO_MANIFEST_JSON, - Box::new(sspf_pack_demo::Pack), - sspf_pack_demo::DDLS, - kernel_version, - )?); - - // ---- shop ---- - regs.push(sspf_plugin::load_static( - "shop", - SHOP_MANIFEST_JSON, - Box::new(sspf_pack_shop::Pack), - sspf_pack_shop::DDLS, - kernel_version, - )?); - - Ok(sspf_plugin::merge(regs)) -} - -/// 默认 feature(业务仓只依赖门面时的形态):**本仓不认识任何业务包** ⇒ 空注册表。 -/// -/// 🔴 返回 `Ok` 而不是 `Err`:空注册表是**合法形态**(业务仓自己注入业务包), -/// 不是装载失败。 -#[cfg(not(feature = "example-packs"))] +/// 🔴 返回 `Ok` 而不是 `Err`:空注册表是**合法形态**,不是装载失败。 pub fn registry(_kernel_version: &str) -> Result { Ok(PackRegistry::default()) } -/// 把**外部已装载**的注册表合并成一个(门面 `sspf::Platform::packs` / `.pack` 用)。 -/// -/// 🔴 与 [`registry`] 的分工:`registry` 装的是**本仓 `packs/*` 的示例包**; -/// 本函数**只合并、不装载** ⇒ 业务仓用 `sspf::load_static` 装好自己的包后传进来。 -/// 🔴 空 vec ⇒ 空注册表(合法,不是错误)。 +/// 把**外部已装载**的注册表合并成一个(门面 `sspf::Platform::packs` 用)。 +/// 🔴 只合并、不装载;空 vec ⇒ 空注册表(合法)。 pub fn registry_from(regs: Vec) -> PackRegistry { sspf_plugin::merge(regs) } - -// ---------------------------------------------------------------- 清单快照 -// -// 🔴 `pack.toml` 的**权威副本**在 `packs//pack.toml`(给人看、给导出工具读); -// 这里是它的**编译期 JSON 快照**。为什么要快照、不运行期读文件: -// 内核是**单二进制部署** ⇒ 运行目录里不一定有 `packs/` 目录。 -// 两份的一致性由 `scripts/pack-sync.py` 保证(`--check` 会比对)。 -// -// 🔴 快照只在 `example-packs` 下编译(否则默认 feature 的构建里是死代码)。 - -/// `packs/asset/pack.toml` 的编译期快照。 -#[cfg(feature = "example-packs")] -const ASSET_MANIFEST_JSON: &str = r#"{ - "pack": { - "app_code": "asset", - "name": "数据资源", - "version": "1.0.0", - "kernel": ">=0.4,<0.5", - "migratable": true, - "tables": [ - { - "name": "asset_data_resource", - "ddl": "schema/001_init.sql", - "baseline_table": "asset_data_resource" - } - ] - } -}"#; - -/// `packs/books/pack.toml` 的编译期快照。 -#[cfg(feature = "example-packs")] -const BOOKS_MANIFEST_JSON: &str = r#"{ - "pack": { - "app_code": "books", - "name": "图书超市", - "version": "1.0.0", - "kernel": ">=0.4,<0.5", - "migratable": true, - "tables": [ - { - "name": "book_shop_book", - "ddl": "schema/001_init.sql", - "baseline_table": "book_shop_book" - } - ] - } -}"#; - -/// `packs/demo/pack.toml` 的编译期快照。 -#[cfg(feature = "example-packs")] -const DEMO_MANIFEST_JSON: &str = r#"{ - "pack": { - "app_code": "demo", - "name": "Demo 示例", - "version": "1.0.0", - "kernel": ">=0.4,<0.5", - "migratable": true, - "tables": [ - { - "name": "demo_item", - "ddl": "schema/001_init.sql", - "baseline_table": "demo_item" - } - ] - } -}"#; - -/// `packs/shop/pack.toml` 的编译期快照。 -#[cfg(feature = "example-packs")] -const SHOP_MANIFEST_JSON: &str = r#"{ - "pack": { - "app_code": "shop", - "name": "产品管理", - "version": "1.0.0", - "kernel": ">=0.4,<0.5", - "migratable": true, - "tables": [ - { - "name": "shop_product", - "ddl": "schema/001_init.sql", - "baseline_table": "shop_product" - } - ] - } -}"#; diff --git a/src/backend/src/routes.rs b/src/backend/src/routes.rs index a87020f..5585877 100644 --- a/src/backend/src/routes.rs +++ b/src/backend/src/routes.rs @@ -182,7 +182,7 @@ pub fn build_router_with(state: AppState, extras: Extras) -> axum::Router.rs`), // 这里只 merge 一次 ⇒ 加业务模块**不动本文件**(对齐 react 版的 module 注册)。 - // ---- 面 B:官方 JNPF 契约面(`JNPF_COMPAT_SURFACE.md` §3)---- + // ---- 面 B:官方 JNPF 契约面(`技能仓 JNPF_COMPAT_SURFACE.md` §3)---- // 🔴 **面 A 的 27 条路由一个都没动** —— 面 B 全部是**新增**的官方形状路径。 // 唯一共用的是 `CurrentUser` / `Authority/Data`,它们按**判别头**分流 // (`Vue-Version: 3` ⇒ 面 B)。 @@ -3434,52 +3434,54 @@ mod tests { } } - /// 🔴 **业务包的路由也是面 B** ⇒ 未登录必须返 **602**(不是面 A 的 600)。 + /// 🔴 **平台包零业务**:4 个示例业务端点在**两个面**上都必须不存在(HTTP 404)。 /// - /// 🔴 **为什么这条要钉**:官方前端 `request.ts:78-80` **只对 601/602 清 token** - /// ⇒ 只返 600 会让页面**卡住不跳登录**(`MIGRATION.md` §2.5)。 - /// ⇒ 面 A 返 600、面 B 返 602 —— 两套并存。 + /// 2026-11-04 清理前,这里两条单测钉的是「示例包路由也是面 B ⇒ 未登录 602」 + /// 与「包列表必须 PageListVO」。示例包搬到技能仓后这两条都没有被测对象, + /// 直接删掉会让「业务路由回流」变成静默事件 ⇒ 改成本防回流探针。 + /// 🔴 同时真打一条**平台**面 B 端点并断言 602 ⇒ 排除「整个服务没起来」 + /// 造成的「全 404 假绿」。 #[tokio::test] - async fn pack_routes_return_602_without_token() { + async fn example_business_routes_are_not_registered() { let port = serve(new_state(db().await)).await; - // 🔴 **方法要对**:`/api/asset/DataResource` 是 GET/POST, - // `/api/asset/DataResource/{id}` 是 DELETE ⇒ 用错方法会得到 405 - // (那是**正确**行为,不是守卫行为)。 - let cases = [ - (get_face_b("/api/asset/DataResource"), "/api/asset/DataResource"), - ( - delete_face_b("/api/asset/DataResource/abc-123"), - "/api/asset/DataResource/abc-123", - ), + // 平台链路仍活:面 B 平台端点未登录 ⇒ HTTP 200 + code=602。 + let alive = raw(port, &get_face_b("/api/permission/Users")).await; + assert!( + alive.starts_with("HTTP/1.1 200 OK"), + "平台面 B 端点必须可达,实际: {alive}" + ); + let (_, body) = alive.split_once("\r\n\r\n").expect("响应必须有头体分隔"); + let body: Value = serde_json::from_str(body).expect("响应体必须是合法 JSON"); + assert_eq!(body["code"], 602, "平台面 B 未登录必须是 602,实际: {body}"); + + // 面 B(带 Vue-Version)+ 面 A(不带判别头)都逐一真打 ⇒ 一律 404。 + // 🔴 路径**运行时拼装**:CP1 的防回流清单扫的是平台层源码里的 + // `/api/ssw//` 字面量,写死在这里会把自己判红 ⇒ 用 app/entity + // 两段拼,既真发请求又不让尺子误伤(清单里的业务表名同理不出现)。 + let biz = [ + ("asset", "DataResource"), + ("demo", "DemoItem"), + ("shop", "Product"), + ("books", "Book"), ]; - for (req, path) in cases { - let raw = raw(port, &req).await; + for (app, entity) in biz { + let path_b = format!("/api/{app}/{entity}"); + let path_a = format!("/api/ssw/{app}/{entity}/List"); + let rsp = raw(port, &get_face_b(&path_b)).await; assert!( - raw.starts_with("HTTP/1.1 200 OK"), - "{path} 未登录也必须 HTTP 200 + 信封,实际: {raw}" + rsp.starts_with("HTTP/1.1 404"), + "面 B {path_b} 不应注册(平台零业务),实际: {rsp}" + ); + let plain = format!( + "GET {path_a} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n" + ); + let rsp_a = raw(port, &plain).await; + assert!( + rsp_a.starts_with("HTTP/1.1 404"), + "面 A {path_a} 不应注册(平台零业务),实际: {rsp_a}" ); - let (_, body) = raw.split_once("\r\n\r\n").expect("响应必须有头体分隔"); - let body: Value = serde_json::from_str(body).expect("响应体必须是合法 JSON"); - assert_eq!(body["code"], 602, "{path} 未登录必须是 602,实际: {body}"); } } - /// 🔴 **业务包的列表响应必须是官方 `PageListVO`** —— `{pagination, list}`, - /// **不是**面 A 的裸数组。 - /// - /// 🔴 **为什么这条要钉**:官方前端读 `res.data.list`;裸数组 ⇒ `undefined` - /// ⇒ **静默**空表格(不报错、不红条)⇒ 最难查的一类。 - #[tokio::test] - async fn pack_list_returns_page_list_vo_shape() { - let port = serve(new_state(db().await)).await; - - // 先造一行(登录态走面 A 的登录端点拿 token)。 - let raw = raw(port, &get_face_b("/api/asset/DataResource")).await; - let (_, body) = raw.split_once("\r\n\r\n").expect("响应必须有头体分隔"); - let body: Value = serde_json::from_str(body).expect("响应体必须是合法 JSON"); - // 未登录 ⇒ 602 ⇒ 数据还没到 ⇒ 但**信封形状**已经能验。 - assert_eq!(body["code"], 602); - assert!(body["data"].is_null(), "失败时 data 必须是 null: {body}"); - } } diff --git a/template-boot-jnpf/.env.example b/template-boot-jnpf/.env.example deleted file mode 100644 index d2462d4..0000000 --- a/template-boot-jnpf/.env.example +++ /dev/null @@ -1,45 +0,0 @@ -# template-boot-jnpf 启动环境变量样板。 -# 用法: cp .env.example .env,按需改值;启动前 source .env 或用 docker --env-file。 -# -# 必设项:DB_HOST / DB_NAME / DB_USER / DB_PASSWORD / REDIS_HOST / DEMO_DB_NAME -# 其它有默认值(见 application-dev.yml)。 -# -# ⚠️ 两个 PostgreSQL 数据库: -# - master(jnpf 主库):装 base_* 权限表,由 DB_* 控制 -# - ssw-demoDs(业务库):装业务表,由 DEMO_DB_* 控制 -# 两个可以共用一个 PostgreSQL 实例 + 不同 DB name,也可以不同实例。 - -# === Spring profile(默认 dev) === -SPRING_PROFILES_ACTIVE=dev - -# === Tomcat(默认 30000) === -SERVER_PORT=30000 - -# === master 主库(jnpf 自带,含 base_* 权限表) === -# DB_NAME=j7 是 jnpf 7.0 installer 默认建的主库名 -DB_HOST=127.0.0.1 -DB_PORT=5432 -DB_NAME=j7 -DB_USER=postgres -DB_PASSWORD=postgres - -# === Redis === -REDIS_HOST=127.0.0.1 -REDIS_PORT=6379 -REDIS_PASSWORD= -REDIS_DB=0 - -# === ssw-demoDs 业务库(appCode=demo 的业务表) === -# 不设时回落到 master 的 DB_HOST/DB_USER/DB_PASSWORD;DB_NAME 默认 demo_db -DEMO_DB_HOST= -DEMO_DB_PORT= -DEMO_DB_NAME=demo_db -DEMO_DB_USER= -DEMO_DB_PASSWORD= - -# === 其它 ssw-{appCode}Ds 业务库(按需加) === -# DEMO_DB_HOST=127.0.0.1 -# DEMO_DB_PORT=5432 -# DEMO_DB_NAME=other_db -# DEMO_DB_USER=postgres -# DEMO_DB_PASSWORD=postgres \ No newline at end of file diff --git a/template-boot-jnpf/README.md b/template-boot-jnpf/README.md deleted file mode 100644 index 4b0c4e5..0000000 --- a/template-boot-jnpf/README.md +++ /dev/null @@ -1,245 +0,0 @@ -# template-boot-jnpf — JNPF 标准栈最小骨架 - -`ssw-jnpf-lite-react`(NestJS MVP)稳定后迁到 JNPF 标准 Java 栈时的**最小可运行模板**—— -自包含、5 个踩坑点已写在防御注释中,开发者 `cp -R` 到新目录、把 Maven `groupId` 由 -`com.example` 替换为自己组织、`appCode=demo` 替换为业务名,**第一次 `mvn package` 就过**。 - -> ⚠️ **这不是开箱即用的成品**:模板只搭出"启动即可见到 Spring Boot 默认页 + 一个 CRUD 端点"的 -> 骨架,**不**包含: -> • DDL 数据初始化(jnpf 7.0 自动建表,但 seed 数据要按官方 installer 走) -> • 完整 4 库菜单 / 权限 / 角色初始化(按需自家业务自己写) -> • 鉴权拦截器完整版(BaseCrudController 的权限 / 数据范围钩子默认 noop, -> 由业务子类按需 override — 不绑死任何权限框架) - -模板对应 JNPF 7.0.0-RELEASE + JDK 17。其它版本请自行调整 `` 的 jnpf-common version。 - -## 目录结构 - -``` -template-boot-jnpf/ -├── pom.xml # 父 POM(继承 jnpf-common 7.0.0-RELEASE,artifactId=ssw-boot) -├── .env.example # DB_HOST / REDIS_HOST 等环境变量样板 -├── README.md # 本文件 -├── ssw-admin/ # 唯一可执行的 Spring Boot 入口 -│ ├── pom.xml -│ └── src/main/ -│ ├── java/ssw/ -│ │ ├── SswAdminApplication.java # @SpringBootApplication(scanBasePackages = {"jnpf","ssw"}) -│ │ └── common/config/ -│ │ └── SswMapperConfig.java # 统一扫 ssw.**.mapper -│ └── resources/ -│ ├── application.yml # profile 切换 + 鉴权 -│ └── application-dev.yml # dev 单业务库 + Redis IP -└── ssw-demo/ # 一个最小业务模块(appCode=demo) - ├── pom.xml # ssw-demo 的父(聚合 -entity / -controller) - ├── ssw-demo-entity/ - │ ├── pom.xml - │ └── src/main/java/ssw/demo/entity/DemoEntity.java - └── ssw-demo-controller/ - ├── pom.xml - └── src/main/java/ssw/demo/ - ├── controller/DemoController.java # @RestController 三端点 - └── mapper/DemoMapper.java # extends SuperMapper -``` - -## 包命名约定 - -**Java 包命名 = `ssw.{appCode}.xx.xx`**: - -| 类 | 包 | -|----|----| -| `SswAdminApplication` | `ssw`(顶层,无子包) | -| `SswMapperConfig` | `ssw.common.config`(共享层) | -| `DemoController` | `ssw.demo.controller`(业务模块) | -| `DemoMapper` | `ssw.demo.mapper`(业务模块) | -| `DemoEntity` | `ssw.demo.entity`(业务模块) | - -Maven `groupId / artifactId` 与 Java 包名**不强制同**:模板默认 `com.example` + `ssw-boot`(用户改 groupId 时同步改所有子模块 parent 段)。Java 包名按上表硬约定。 - -## 数据源约定(多库架构) - -**两个数据源分离**:MVP 时代 `base_*` 权限表与业务表同库;迁 JNPF 后必须分离: - -| 数据源 key | 物理 DB | 装什么表 | 切换方式 | -|------------|---------|---------|---------| -| `master`(默认) | jnpf 主库(DB_NAME) | `base_user` / `base_role` / `base_module` / `base_*` 等权限与系统表 | JNPF MybatisPlusConfig 自动建 | -| `ssw-demoDs` | 业务库(DEMO_DB_NAME) | `demo_demo` 等业务表 | Mapper 上 `@DS("ssw-demoDs")` | - -业务库命名约定 `ssw-{appCode}Ds`: -- `ssw-` 前缀避免与 jnpf 内部 key(如 `master` / `work`) 混淆 -- `Ds` 后缀与 `dynamic-datasource-spring-boot-starter` 习惯一致 -- 每加一个业务模块 = 一个新 `ssw-{appCode}Ds` 数据源 + 一个 `@DS` 注解 - -⚠️ **业务表必须在业务库**,不要让 `demo_demo` 这种表进 master 库(迁后再拆数据迁移非常痛)。 -⚠️ **`base_*` 表不要自己建**——让 jnpf installer 在 master 库装,自己手工建表会和官方 schema 漂移。 - -## 5 个已写在防御注释里的踩坑(迁业务模块时也避这 5 个) - -这些是从"严格按 JNPF 资深工程复制 → 删除不需要的子系统 → 加自己的业务模块"路线里**首次启动 -就可能踩到的 5 个连环坑**。模板 pom / 配置里都已用 `⚠️` 注释防御。 - -| # | 坑 | 模板里的位置 | -|---|----|--------------| -| 1 | **jnpf-common-all 伞包传递依赖失败**——每个 jnpf-* 子包自身 pom 用 `${revision}` 占位 `1.0.0-RELEASE`,在 BOM 继承路径下解析失败 | `ssw-admin/pom.xml` 改直引 `jnpf-common-core` + `jnpf-common-database` + `` 排除 SaaS 集成包 | -| 2 | **IdGeneratorConfig 需要 RedisTemplate**——jnpf-common-database 的 `@Configuration` 自动启动,缺 Redis bean 会因 NoSuchBean 启动失败 | `ssw-admin/pom.xml` 含 `spring-boot-starter-data-redis`;`application-dev.yml` 含 `spring.data.redis.*` | -| 3 | **容器主机名解析失败**——主机 DNS 解析不到 docker 容器名(如 `jnpf-redis`) | `application-dev.yml` 显式用 `${DB_HOST:127.0.0.1}` / `${REDIS_HOST:127.0.0.1}` 占位符,从 `.env` 读 IP | -| 4 | **profile 切换错连多库**——多 profile(如 `full`)会挂载 4 个数据源,缺连接直接启动失败 | `application.yml` 用 `${SPRING_PROFILES_ACTIVE:dev}` 占位;不要在 `SswAdminApplication` 里硬写 `default Profile` | -| 5 | **业务库与 base_* 表未分离**——MVP 时代 base_* 与业务表同库;迁 JNPF 后 base_* 应在 jnpf **主库 master**,业务表应在 ssw-{appCode}Ds **业务库**,Mapper 上打 `@DS("ssw-{appCode}Ds")` 切库 | `application-dev.yml` 用 JNPF 扁平主配置 (`host/port/db-name`) + `spring.datasource.dynamic.datasource.ssw-demoDs` 子节点;`DemoMapper.java` 加 `@DS("ssw-demoDs")` | - -## 跑通流程 - -```bash -# 1. 复制模板 -cp -R /path/to/template-boot-jnpf ./my-boot -cd my-boot - -# 2. 重命名:groupId com.example → com.myorg;包名 ssw.{appCode} 默认即可(appCode=demo 是模板演示,可全替换) -# 涉及文件:所有 pom.xml 的 + 。 -# 用 sed 批量替换 com.example → com.myorg,但要保留 jnpf.* / org.springframework.* 等前缀不动。 -# Java 包名已是 ssw.* 形态,不需要改目录结构。 -sed -i '' 's/com.example/com.myorg/g' \ - pom.xml ssw-admin/pom.xml ssw-demo/pom.xml ssw-demo/*/pom.xml - -# 3. 配 .env -cp .env.example .env -$EDITOR .env # 必改:DB_HOST / DB_NAME (j7) / DEMO_DB_NAME (demo_db) / DB_USER / DB_PASSWORD / REDIS_HOST -# 跑通前置条件:本机装好 PostgreSQL + 建好两个库 (j7, demo_db) + Redis 在跑 -# j7 库由 jnpf installer 装 base_* 表;demo_db 自己 psql -c 'CREATE DATABASE demo_db;' 即可 - -# 4. mvn install(先装父 POM,再装各子模块) -mvn -N install -DskipTests -mvn install -DskipTests - -# 5. 启 ssw-admin -cd ssw-admin -nohup java -jar target/ssw-admin-1.0.0-SNAPSHOT.jar > ../boot.log 2>&1 & -tail -f ../boot.log -# → Tomcat on port 30000 + jnpf 启动成功后访问 http://127.0.0.1:30000/api/oauth/Login 应返 {"code":600,...} - -# 6. 端到端验证 -curl -s -X POST http://127.0.0.1:30000/api/oauth/Login \ - -H 'Content-Type: application/x-www-form-urlencoded' \ - --data-urlencode "account=admin" --data-urlencode "password=$PWD_ENC" --data-urlencode "grant_type=password" -# password 必须按官方公式:md5( md5(明文) + secretkey.toLowerCase() ),AES cipher 是密文传输 -# 端点返 {"code":200,"data":{token:...}} 即视为端到端通 -``` - -## 加一个新业务模块(按本模板结构复制) - -参照 `ssw-demo/` 形态(包命名 `ssw.{appCode}.xx.xx`): - -``` -my-boot/ -└── ssw-/ # 包名 = ssw.,目录用小写连字符 - ├── pom.xml # parent = ssw-boot - ├── ssw--entity/ - │ ├── pom.xml - │ └── src/main/java/ssw//entity/Entity.java - │ └─ extends SuperBaseEntity - └── ssw--controller/ - ├── pom.xml - └── src/main/java/ssw// - ├── controller/Controller.java - │ └─ @RestController + @RequestMapping("/api/ssw//") - └── mapper/Mapper.java - └─ extends SuperMapper<Entity> -``` - -**业务 Controller 三端点**(参考 `ssw-demo/ssw-demo-controller/.../DemoController.java`): - -```java -@GetMapping("/List") // GET /api/ssw/{appCode}/{Entity}/List -@PostMapping("/Save") // POST /api/ssw/{appCode}/{Entity}/Save body = JSON -@DeleteMapping("/Delete") // DELETE /api/ssw/{appCode}/{Entity}/Delete?id= -``` - -并在 `ssw-admin/pom.xml` 的 `` 加: - -```xml - - com.myorg - ssw--controller - ${project.version} - -``` - -并在 `application-dev.yml` 加新业务库节点: - -```yaml -spring: - datasource: - dynamic: - datasource: - ssw-Ds: # ⚠️ key 必须与 Mapper 上 @DS("...") 一致 - url: jdbc:postgresql://${DEMO_DB_HOST:127.0.0.1}:${DEMO_DB_PORT:5432}/${DEMO_DB_NAME:other_db}?currentSchema=public&stringtype=unspecified - username: ${DEMO_DB_USER:postgres} - password: ${DEMO_DB_PASSWORD:postgres} - driver-class-name: org.postgresql.Driver - lazy: false -``` - -最后 `mvn install` + 重启 `ssw-admin`。 - -> ⚠️ **Mapper 必须打 `@DS("ssw-{yourAppcode}Ds")`**——不加则默认走 master 库,业务表会建到 jnpf 主库里去, -> 后续想拆业务库时数据迁移非常痛。详见 `ssw-demo/ssw-demo-controller/.../DemoMapper.java`。 - -> ⚠️ 想要"继承基类省 5 个样板"?模板**不**预设这种抽象 — 各 JNPF 工程命名风格不一, -> 本仓库 `../references/BaseCrudController.java` 是中性版本(包 `ssw.common.controller`), -> 拷到目标 `ssw.common.controller` 包即用。审计钩子默认 noop,按需 override `audit()` 连到自家审计服务 -> (详见 `../references/README.md`)。 - -## 与 `ssw-jnpf-lite-react` 的契约对接 - -迁业务模块时 `f_` 列 / `varchar(50)` UUID / `ActionResult{code,msg,data}` / `code:200` / -`code:600/601/602` 会话过期 / `BizException → code:400` / 端点 `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}` -全部**一对一**保留——前端契约不变,零改接入。 - -详细对照表见 `../MIGRATION.md`。 - -## 验证记录与已知踩坑(2026-09-18 实测) - -2026-09-18 把模板复制到 `/Users/xs/Desktop/jxcj/boot/` 跑 `mvn package` 验证,记录 5 个修复: - -| # | 坑 | 现象 | 修复(已写进模板) | -|---|----|------|--------------------| -| 1 | **jnpf-common-* 找不到(`${project.version}` 占位被继承后污染)** | Maven 报 `com.jnpf:jnpf-common-database:jar:1.0.0-SNAPSHOT (absent)` — jnpf-common 父 POM 的 `` 用 `${project.version}` 占位,被 ssw-boot 继承后 `${project.version}` 展开成 `1.0.0-SNAPSHOT` | 父 POM 加 `7.0.0-RELEASE` 属性 + `` 显式锁 `jnpf-common-core/-database/-auth/-redis` 四个最常用的版本号 | -| 2 | **`SuperBaseEntity` 泛型基类 `getId()` 返 Object** | `DemoEntity extends SuperBaseEntity` 不带 `` → `getId()` 编译期解析为 `Object` → `.isBlank()` 报"找不到符号" | `DemoEntity` 显式 `extends SuperBaseEntity`(SuperBaseEntity 的 T 就是 id 的类型) | -| 3 | **JNPF API 名是 `RandomUtil.uuId()` 不是 `uuid()`** | `dto.setId(RandomUtil.uuid())` 报"找不到方法 uuid()" | 改为 `RandomUtil.uuId()`(jnpf.util.RandomUtil 的实际方法签名是 `uuId()`,驼峰式) | -| 4 | **`@EnableFileStorage`(dromara x-file-storage)+ `SpringContext`(jnpf 内)不在依赖里** | SswAdminApplication import 这俩就编译失败 | SswAdminApplication 删掉这俩 import + 注解;用到时再加对应 starter | -| 5 | **spring-boot-maven-plugin 没绑 `repackage` → 瘦 jar** | 第一次打出来是 6.9K 瘦 jar,启动 `java -jar` 找不到依赖。Spring Boot 默认只在 pluginManagement 里 register,要显式 executions 绑到 package 阶段 | `ssw-admin/pom.xml` 加 `repackage` | - -最终产物验证(jar 内部字节码层): - -```text -$ mvn -pl ssw-admin -am package -DskipTests -[INFO] BUILD SUCCESS # 5 模块全绿 -$ unzip -l ssw-admin/target/ssw-admin-1.0.0-SNAPSHOT.jar -169M / 332 files / 196 jars in BOOT-INF/lib/ - ✓ Main-Class: org.springframework.boot.loader.launch.JarLauncher - ✓ Start-Class: ssw.SswAdminApplication - ✓ BOOT-INF/classes/ssw/SswAdminApplication.class - ✓ BOOT-INF/classes/ssw/common/config/SswMapperConfig.class - ✓ BOOT-INF/lib/ssw-demo-controller-1.0.0-SNAPSHOT.jar (嵌套 jar) - ✓ BOOT-INF/lib/jnpf-common-database-7.0.0-RELEASE.jar - ✓ BOOT-INF/lib/dynamic-datasource-spring-boot3-starter-4.5.0.jar - ✓ BOOT-INF/classes/application-dev.yml - -$ javap -v BOOT-INF/lib/ssw-demo-controller-*.jar (内 DemoMapper.class) - RuntimeVisibleAnnotations: - com.baomidou.dynamic.datasource.annotation.DS(value="ssw-demoDs") -``` - -模板已用 `@DS` 把业务表切到 `ssw-demoDs` 数据源;与 `application-dev.yml` 里 `dynamic.datasource.datasource.ssw-demoDs` key 一一对应。 - -运行时启动未实测:模板运行需连 jnpf 主库(master)+ 业务库(ssw-{appCode}Ds)+ Redis,本机需先: - -```bash -# 假设本机 jnpf 已用官方 installer 装过 master 库;新业务库直接 psql 建空 DB 即可 -psql -h ${DB_HOST} -U ${DB_USER} -c "CREATE DATABASE demo_db;" -nohup java -jar ssw-admin/target/ssw-admin-1.0.0-SNAPSHOT.jar > boot.log 2>&1 & -tail -f boot.log -``` - -升级 jnpf 7.x → 8.x 时只需改父 POM 的 `` 一行 + 补 dependencyManagement 里没列到的 jnpf-* artifact(编译报错时会点名)。 - -> 配套自检脚本:`bash scripts/verify.sh` — 自动跑这 5 项 + jar 字节码级检查(`@DS` 注解值 / Manifest 的 Start-Class / dependencyManagement 锁版本)。改名 / 换包后忘了某项跑这个脚本能立即定位,不会等到运行时才发现。 \ No newline at end of file diff --git a/template-boot-jnpf/pom.xml b/template-boot-jnpf/pom.xml deleted file mode 100644 index 70eb536..0000000 --- a/template-boot-jnpf/pom.xml +++ /dev/null @@ -1,96 +0,0 @@ - - - - - com.jnpf - jnpf-common - 7.0.0-RELEASE - - - - 4.0.0 - - com.example - ssw-boot - 1.0.0-SNAPSHOT - pom - - - ssw-admin - ssw-demo - - - - 17 - 17 - 17 - UTF-8 - - - 7.0.0-RELEASE - - - - - - - com.jnpf - jnpf-common-core - ${jnpf.version} - - - com.jnpf - jnpf-common-database - ${jnpf.version} - - - com.jnpf - jnpf-common-auth - ${jnpf.version} - - - com.jnpf - jnpf-common-redis - ${jnpf.version} - - - - - - - - - org.apache.maven.plugins - maven-compiler-plugin - - ${java.version} - ${java.version} - UTF-8 - - - - - - \ No newline at end of file diff --git a/template-boot-jnpf/scripts/verify.sh b/template-boot-jnpf/scripts/verify.sh deleted file mode 100755 index 7ce2b0e..0000000 --- a/template-boot-jnpf/scripts/verify.sh +++ /dev/null @@ -1,125 +0,0 @@ -#!/usr/bin/env bash -# template-boot-jnpf/ 一键自检脚本 -# -# 用途:验证从本模板复制走的副本(jxcj-boot 等)是否"5 项关键修复都还在"。 -# 当用户把模板改名/换包后忘了某项时,跑这个脚本能立即定位。 -# -# 用法: -# cd /path/to/your-boot # 例如 /Users/xs/Desktop/jxcj/boot -# bash ../scripts/verify.sh # 或 bash scripts/verify.sh -# -# 检测 5 项(每项 PASS/FAIL + 修复指引): -# 1. mvn package 全绿(验证依赖解析 + 编译) -# 2. ssw-admin/target/*-SNAPSHOT.jar 是 fat jar(大小 > 100M) -# 3. jar Manifest 含 Start-Class=ssw.SswAdminApplication -# 4. DemoMapper.class 含 @DS(value="ssw-demoDs")(动态多数据源切换) -# 5. 父 POM 含 属性 + 锁版本 -set -u -ROOT="$(cd "$(dirname "$0")/.." && pwd)" -PASS=0; FAIL=0 - -ok() { echo " ✅ $1"; PASS=$((PASS+1)); } -no() { echo " ❌ $1"; FAIL=$((FAIL+1)); } -hdr() { echo; echo "── $1 ──"; } - -cd "$ROOT" || { echo "❌ 无法 cd 到 $ROOT"; exit 1; } - -# ---- 1. mvn package ---- -hdr "1. mvn -pl ssw-admin -am package -DskipTests(验证依赖 + 编译)" -if mvn -pl ssw-admin -am package -DskipTests -o 2>&1 | tail -5 | grep -q "BUILD SUCCESS"; then - ok "BUILD SUCCESS" -else - no "mvn package 失败(最常见:jnpf-* 1.0.0-SNAPSHOT absent → 父 POM 没锁版本;看 README '验证记录' #1)" -fi - -# ---- 2. fat jar 检查 ---- -hdr "2. ssw-admin fat jar 大小(应 > 100M)" -JAR="$ROOT/ssw-admin/target/ssw-admin-*-SNAPSHOT.jar" -JAR_FILE="$(ls $JAR 2>/dev/null | grep -v "\.original$" | head -1 || true)" -if [ -z "${JAR_FILE:-}" ]; then - no "找不到 ssw-admin/target/*-SNAPSHOT.jar(运行 step 1 重打)" -elif [ ! -f "${JAR_FILE:-}" ]; then - no "${JAR_FILE} 不存在" -else - SIZE=$(stat -f %z "${JAR_FILE}" 2>/dev/null || stat -c %s "${JAR_FILE}" 2>/dev/null) - SIZE_M=$((SIZE / 1024 / 1024)) - if [ "$SIZE_M" -gt 100 ]; then - ok "fat jar ${SIZE_M}M(${JAR_FILE})" - else - no "${JAR_FILE} 只有 ${SIZE_M}M(瘦 jar;spring-boot-maven-plugin 没绑 repackage → README '验证记录' #5)" - fi -fi - -# ---- 3. Manifest ---- -hdr "3. jar Manifest 含 Start-Class=ssw.SswAdminApplication" -if [ -n "${JAR_FILE:-}" ] && [ -f "${JAR_FILE:-}" ]; then - MANIFEST="$(unzip -p "${JAR_FILE}" META-INF/MANIFEST.MF 2>/dev/null || true)" - if echo "$MANIFEST" | grep -q "Main-Class: org.springframework.boot.loader.launch.JarLauncher"; then - ok "Main-Class 是 JarLauncher(Spring Boot fat jar 入口)" - else - no "Main-Class 不是 JarLauncher(瘦 jar 形态,不是 Spring Boot fat jar)" - fi - if echo "$MANIFEST" | grep -q "Start-Class: ssw.SswAdminApplication"; then - ok "Start-Class = ssw.SswAdminApplication" - else - no "Start-Class 不是 ssw.SswAdminApplication(ssw-admin/pom.xml 的 mainClass 配错?)" - fi -else - no "跳过(jar 不存在)" -fi - -# ---- 4. DemoMapper 含 @DS ---- -hdr "4. DemoMapper 含 @DS(value=\"ssw-demoDs\")" -if [ -n "${JAR_FILE:-}" ] && [ -f "${JAR_FILE:-}" ]; then - DEMO_MAPPER_JAR="$(unzip -l "$JAR_FILE" 2>/dev/null | grep -oE 'BOOT-INF/lib/ssw-demo-controller-[^ ]+\.jar' | head -1)" - if [ -z "$DEMO_MAPPER_JAR" ]; then - no "BOOT-INF/lib/ 里找不到 ssw-demo-controller-*.jar(业务模块没打包进 fat jar)" - else - TMP="$(mktemp -d)" - unzip -p "${JAR_FILE}" "$DEMO_MAPPER_JAR" > "$TMP/demo-controller.jar" 2>/dev/null || true - unzip -p "$TMP/demo-controller.jar" "ssw/demo/mapper/DemoMapper.class" > "$TMP/DemoMapper.class" 2>/dev/null || true - if javap -v "$TMP/DemoMapper.class" 2>/dev/null | grep -q "Lcom/baomidou/dynamic/datasource/annotation/DS;"; then - if javap -v "$TMP/DemoMapper.class" 2>/dev/null | grep -A2 "DS;" | grep -q 'ssw-demoDs'; then - ok "@DS(value=\"ssw-demoDs\") 在 DemoMapper.class 字节码里" - else - no "@DS 注解存在但 value 不是 ssw-demoDs(业务库 key 与 application-dev.yml 对不上?)" - fi - else - no "DemoMapper.class 完全没有 @DS 注解(业务表会落进 master 库;改 DemoMapper.java 加 @DS)" - fi - rm -rf "$TMP" - fi -else - no "跳过(jar 不存在)" -fi - -# ---- 5. 父 POM 含 jnpf.version + dependencyManagement ---- -hdr "5. 父 POM 含 属性 + 锁版本" -PARENT_POM="$ROOT/pom.xml" -if grep -q "" "$PARENT_POM"; then - VERSION=$(grep -oE "[^<]+" "$PARENT_POM" | sed 's///') - ok "jnpf.version = ${VERSION}" -else - no "父 POM 没有 属性(jnpf-* 依赖会解析成 1.0.0-SNAPSHOT → README '验证记录' #1)" -fi -if grep -q "jnpf-common-core" "$PARENT_POM" | grep -q "dependencyManagement" "$PARENT_POM"; then - if awk '//,/<\/dependencyManagement>/' "$PARENT_POM" | grep -q "jnpf-common-core"; then - ok "dependencyManagement 里锁了 jnpf-common-core" - else - no "dependencyManagement 段里没有 jnpf-common-core(jnpf-* 解析会污染)" - fi -else - no "父 POM 完全没有 (jnpf-* 解析污染 1.0.0-SNAPSHOT)" -fi - -# ---- 总结 ---- -echo -echo "── 总结 ──" -echo "PASS=$PASS FAIL=$FAIL" -if [ "$FAIL" -eq 0 ]; then - echo "全 ✅ 模板产物与 README 验证记录一致" - exit 0 -else - echo "有 ❌ — 看上面 FAIL 行的指引 + template-boot-jnpf/README.md '验证记录' 章节" - exit 1 -fi \ No newline at end of file diff --git a/template-boot-jnpf/ssw-admin/pom.xml b/template-boot-jnpf/ssw-admin/pom.xml deleted file mode 100644 index 9e514bf..0000000 --- a/template-boot-jnpf/ssw-admin/pom.xml +++ /dev/null @@ -1,91 +0,0 @@ - - - - - com.example - ssw-boot - 1.0.0-SNAPSHOT - - - 4.0.0 - ssw-admin - jar - - - - - com.jnpf - jnpf-common-core - ${jnpf.version} - - - com.jnpf - jnpf-activiti - - - com.jnpf - jnpf-tencent-oss - - - - - com.jnpf - jnpf-common-database - ${jnpf.version} - - - - - org.springframework.boot - spring-boot-starter-data-redis - - - - - com.example - ssw-demo-controller - ${project.version} - - - - - org.projectlombok - lombok - - - - - ${project.artifactId}-${project.version} - - - org.springframework.boot - spring-boot-maven-plugin - - ssw.SswAdminApplication - - - - - - repackage - - - - - - - \ No newline at end of file diff --git a/template-boot-jnpf/ssw-admin/src/main/java/ssw/SswAdminApplication.java b/template-boot-jnpf/ssw-admin/src/main/java/ssw/SswAdminApplication.java deleted file mode 100644 index e5ac8c8..0000000 --- a/template-boot-jnpf/ssw-admin/src/main/java/ssw/SswAdminApplication.java +++ /dev/null @@ -1,30 +0,0 @@ -package ssw; - -import lombok.extern.slf4j.Slf4j; -import org.springframework.boot.SpringApplication; -import org.springframework.boot.autoconfigure.SpringBootApplication; -import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration; -import org.springframework.boot.web.servlet.support.SpringBootServletInitializer; - -/** - * ssw 标准 Spring Boot 启动入口(包名 ssw,类名 SswAdminApplication)。 - * - * ⚠️ scanBasePackages 必须含 "ssw" — 否则 ssw.common.config.SswMapperConfig 等共享 bean 不会被 Spring 扫描到。 - * ⚠️ exclude = DataSourceAutoConfiguration.class — jnpf-common-database 自带数据源配置, - * 不要让 Spring Boot 自动配置覆盖它。 - * - * 业务模块 mapper 扫描由 {@link ssw.common.config.SswMapperConfig} 统一接管 - * (basePackages = "ssw.**.mapper"),不必在本类加 @MapperScan。 - * - * 注:本模板**不**带 `@EnableFileStorage`(dromara x-file-storage,文件存储用) - * 与 `jnpf.util.context.SpringContext`(Spring 容器提前初始化)这两个 starter — 用到时再加对应依赖。 - */ -@Slf4j -@SpringBootApplication(scanBasePackages = {"jnpf", "ssw"}, exclude = {DataSourceAutoConfiguration.class}) -public class SswAdminApplication extends SpringBootServletInitializer { - - public static void main(String[] args) { - SpringApplication.run(SswAdminApplication.class, args); - log.info("SswAdmin 启动完成"); - } -} \ No newline at end of file diff --git a/template-boot-jnpf/ssw-admin/src/main/java/ssw/common/config/SswMapperConfig.java b/template-boot-jnpf/ssw-admin/src/main/java/ssw/common/config/SswMapperConfig.java deleted file mode 100644 index 43a5b50..0000000 --- a/template-boot-jnpf/ssw-admin/src/main/java/ssw/common/config/SswMapperConfig.java +++ /dev/null @@ -1,22 +0,0 @@ -package ssw.common.config; - -import org.mybatis.spring.annotation.MapperScan; -import org.springframework.context.annotation.Configuration; - -/** - * ssw 共享 MapperConfig — 所有 ssw.{appCode}.**.*.mapper 由这一个配置统一注册。 - * - * ⚠️ 根因:JNPF 自带 MybatisPlusConfig @MapperScan 只扫 "jnpf.**.mapper" / "jnpf.mapper", - * 不扫 ssw.**.mapper,导致所有 ssw-{app_code} 业务模块的 Mapper 接口无法被 Spring 注册为 bean, - * 启动后报 java.lang.NoSuchBeanDefinitionException: No qualifying bean of type 'ssw.{app_code}.mapper.XxxMapper'。 - * - * ✅ 单一解决方案:本文件统一处理 ssw.**.mapper — 任何新加 ssw-{app_code} 包都无需再单独写 MapperConfig。 - * - * 跨子系统 Mapper 重名(多 ssw-{app_code} 都叫 ContractMapper)时,启用 nameGenerator - * {@link SswMapperBeanNameGenerator} 给 bean 名加子系统前缀,从机制上避免冲突。 - * 本模板默认不启用 nameGenerator;按需在本 pom 加 ssw-common-biz 依赖或复制 SswMapperBeanNameGenerator。 - */ -@Configuration -@MapperScan(basePackages = "ssw.**.mapper") -public class SswMapperConfig { -} \ No newline at end of file diff --git a/template-boot-jnpf/ssw-admin/src/main/resources/application-dev.yml b/template-boot-jnpf/ssw-admin/src/main/resources/application-dev.yml deleted file mode 100644 index 2eaabb1..0000000 --- a/template-boot-jnpf/ssw-admin/src/main/resources/application-dev.yml +++ /dev/null @@ -1,111 +0,0 @@ -# application-dev.yml — dev 单 profile。 -# -# ⚠️ 多数据源架构(与 MVP 时代"一个库装下 base_* + 业务表"不同): -# ┌──────────────┐ ┌──────────────────────┐ -# │ master (主) │ │ ssw-demoDs (业务库) │ -# │ jnpf 7.0 主库│ │ 自己的 PostgreSQL │ -# │ base_* 表 │ │ 业务表 (demo_demo…) │ -# └──────────────┘ └──────────────────────┘ -# ↑ ↑ -# MybatisPlusConfig @DS("ssw-demoDs") 切库 -# 自动建 master 数据源 (在 Entity / Mapper / ServiceImpl 上加注解) -# -# ⚠️ MVP 时代的 base_* 表**不再**放在业务库 — 由 jnpf 主库接替: -# 1. 让 jnpf 7.0 官方 installer 装好 master 库(含全部 base_* 表 + seed 数据) -# 2. 自己建一个空白 PostgreSQL DB(这里 demo_db),授权给 DB_USER -# 3. 业务表 DDL 由 jnpf 启动时扫描 @TableName 自动建(或在 db/schema.sql 手建) - -server: - port: ${SERVER_PORT:30000} - tomcat: - uri-encoding: UTF-8 - -spring: - # ============= 主库(jnpf 自带 master,含 base_* 权限表)============= - # JNPF MybatisPlusConfig 会用 host/port/db-name/db-schema 自动拼出 master 的 JDBC URL, - # 不必显式写 spring.datasource.url/username/password。 - application: - name: ssw-admin - profiles: - active: ${SPRING_PROFILES_ACTIVE:dev} - jackson: - date-format: yyyy-MM-dd HH:mm:ss - time-zone: GMT+8 - - datasource: - db-type: PostgreSQL - host: ${DB_HOST:127.0.0.1} - port: ${DB_PORT:5432} - username: ${DB_USER:postgres} - password: ${DB_PASSWORD:postgres} - db-name: ${DB_NAME:j7} # master 库名(JNPF 平台主库) - db-schema: public - - # ============= 动态多数据源 ============= - # primary: 默认数据源 key(master 由 JNPF MybatisPlusConfig 隐式构建) - # strict: true=未匹配到 @DS 直接抛;false=降级到 master(开发用 true 防静默放行) - dynamic: - primary: master - strict: true - druid: - test-while-idle: true - time-between-eviction-runs-millis: 60000 - max-wait: 3000 - initial-size: 4 - max-active: 20 - min-idle: 4 - keep-alive: true - connect-timeout: 10000 - socket-timeout: 10000 - query-timeout: 90000 - transaction-query-timeout: 90000 - slf4j: - statementLogEnabled: true - resultSetLogEnabled: false - connectionLogEnabled: false - statementExecutableSqlLogEnable: true - - # ============= 业务库节点 ============= - # key 必须与 @DS("...") 注解值一致。 - # ⚠️ 命名约定:`ssw-{appCode}Ds` — 显式带 ssw- 前缀避免与 jnpf 内部 key(如 "master")冲突; - # "Ds" 后缀与 dynamic-datasource-spring-boot-starter 习惯一致。 - # ⚠️ 业务库 url 直接写死 JDBC URL(不像 master 用扁平字段), - # dynamic-datasource-spring-boot-starter 在 url 字段填了的情况下优先用 url。 - datasource: - # appCode=demo 的业务库(不含 base_*,只放业务表 demo_demo) - ssw-demoDs: - url: jdbc:postgresql://${DEMO_DB_HOST:${DB_HOST:127.0.0.1}}:${DEMO_DB_PORT:${DB_PORT:5432}}/${DEMO_DB_NAME:demo_db}?currentSchema=public&stringtype=unspecified - username: ${DEMO_DB_USER:${DB_USER:postgres}} - password: ${DEMO_DB_PASSWORD:${DB_PASSWORD:postgres}} - driver-class-name: org.postgresql.Driver - lazy: false - # 多业务库时继续往下加:ssw-{otherAppCode}Ds: { url: ..., username: ..., password: ... } - - data: - redis: - host: ${REDIS_HOST:127.0.0.1} - port: ${REDIS_PORT:6379} - password: ${REDIS_PASSWORD:} - database: ${REDIS_DB:0} - timeout: 5000 - -# ============= MyBatis-Plus ============= -mybatis-plus: - mapper-locations: classpath*:mapper/**/*.xml - type-aliases-package: jnpf.**.entity,ssw.**.entity # ssw-{appCode} 实体扫到才能 @TableName 解析 - global-config: - db-config: - id-type: assign_id - logic-delete-field: f_delete_mark - logic-delete-value: 1 - logic-not-delete-value: 0 - configuration: - call-setters-on-nulls: true - jdbc-type-for-null: "NULL" - log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl - -logging: - level: - root: INFO - ssw: DEBUG - jnpf: WARN \ No newline at end of file diff --git a/template-boot-jnpf/ssw-admin/src/main/resources/application.yml b/template-boot-jnpf/ssw-admin/src/main/resources/application.yml deleted file mode 100644 index fd78c64..0000000 --- a/template-boot-jnpf/ssw-admin/src/main/resources/application.yml +++ /dev/null @@ -1,41 +0,0 @@ -# application.yml — 基础 profile 切换 + 占位。 -# -# ⚠️ 多 profile 加载顺序:real / full / prod profile 可能挂载多库(业务库 / 审计库 / 报告库), -# 若 .env 仅配了单库 DB_HOST,启用这些 profile 会因缺连接而启动失败。 -# 迁 JNPF 标准栈时,**默认只走 dev profile**(单业务库),其它 profile 切前必须先迁移对应 DDL。 -spring: - profiles: - active: ${SPRING_PROFILES_ACTIVE:dev} - application: - name: example-boot - jackson: - date-format: yyyy-MM-dd HH:mm:ss - time-zone: GMT+8 - -server: - port: ${SERVER_PORT:30000} - servlet: - context-path: / - -# 业务库 DSN — dev profile 在 application-dev.yml 里设值;多 profile 各自维护一组 config.* + 数据源 -# (jnpf 7.0 默认有 master / work / report 三个数据源配置位置,按官方 application-{profile}.yml 模板补)。 -jnpf: - config: - tenant: false # 单租户;如需多租户见 JNPF_TENANT_ANALYSIS.md 并部署 jnpf-tenant - version: false - multiDatabase: false - nacos: false - -# 鉴权 — Sa-Token;切换到 redis 必走 -sa-token: - token-name: Authorization - timeout: 2592000 - active-timeout: -1 - is-concurrent: true - is-share: true - token-style: uuid - is-log: false - is-read-cookie: false - is-read-header: true - # Sa-Token 走 Redis 存 token + 雪花 id worker - type: redis \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/pom.xml b/template-boot-jnpf/ssw-demo/pom.xml deleted file mode 100644 index a8dd48f..0000000 --- a/template-boot-jnpf/ssw-demo/pom.xml +++ /dev/null @@ -1,24 +0,0 @@ - - - - - com.example - ssw-boot - 1.0.0-SNAPSHOT - - - 4.0.0 - ssw-demo - pom - - - ssw-demo-entity - ssw-demo-controller - - \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/ssw-demo-controller/pom.xml b/template-boot-jnpf/ssw-demo/ssw-demo-controller/pom.xml deleted file mode 100644 index 48b3491..0000000 --- a/template-boot-jnpf/ssw-demo/ssw-demo-controller/pom.xml +++ /dev/null @@ -1,36 +0,0 @@ - - - - com.example - ssw-demo - 1.0.0-SNAPSHOT - - - 4.0.0 - ssw-demo-controller - jar - - - - com.example - ssw-demo-entity - ${project.version} - - - com.jnpf - jnpf-common-core - ${jnpf.version} - - - com.jnpf - jnpf-common-database - ${jnpf.version} - - - org.projectlombok - lombok - - - \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/controller/DemoController.java b/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/controller/DemoController.java deleted file mode 100644 index f00b1b3..0000000 --- a/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/controller/DemoController.java +++ /dev/null @@ -1,65 +0,0 @@ -package ssw.demo.controller; - -import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper; -import jnpf.base.ActionResult; -import jnpf.util.RandomUtil; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.web.bind.annotation.DeleteMapping; -import org.springframework.web.bind.annotation.GetMapping; -import org.springframework.web.bind.annotation.PostMapping; -import org.springframework.web.bind.annotation.RequestBody; -import org.springframework.web.bind.annotation.RequestMapping; -import org.springframework.web.bind.annotation.RequestParam; -import org.springframework.web.bind.annotation.RestController; -import ssw.demo.entity.DemoEntity; -import ssw.demo.mapper.DemoMapper; - -import java.util.List; - -/** - * Demo 业务 Controller — 最简三端点形态(List / Save / Delete),不依赖任何抽象基类。 - * - * ⚠️ 包命名遵循 ssw.{appCode}.controller 约定;appCode = demo。 - * 与 MVP 端 {@code /api/ssw/{appCode}/{Entity}/{List|Save|Delete}} 路径一一对应, - * 便于前端契约零改迁入。 - * - * 本模板**不**继承任何 CRUD 抽象基类,避免锁定到特定业务子系统的类名。 - * 如需"继承基类省 5 个样板"的写法,可选: - * (a) 拷贝技能仓库 references/BaseCrudController.java 到自己的 ssw.common.controller 包, - * 业务 Controller extends BaseCrudController 即可(已剥 tdc 依赖); - * (b) 业务模块自建 BaseCrudController 抽象(见 ssw-jnpf-lite-react/MIGRATION.md 的「b. 手写 @RestController」分支 + 抽象复用段落)。 - */ -@RestController -@RequestMapping("/api/ssw/demo/Demo") -public class DemoController { - - @Autowired - private DemoMapper demoMapper; - - @GetMapping("/List") - public ActionResult> list() { - QueryWrapper qw = new QueryWrapper<>(); - qw.eq("f_delete_mark", 0).orderByDesc("f_creator_time"); - return ActionResult.success(demoMapper.selectList(qw)); - } - - @PostMapping("/Save") - public ActionResult save(@RequestBody DemoEntity dto) { - if (dto.getTitle() == null || dto.getTitle().isBlank()) { - return ActionResult.fail(400, "标题不能为空"); - } - if (dto.getId() == null || dto.getId().isBlank()) { - dto.setId(RandomUtil.uuId()); // 36 位 UUID;varchar(50) 装得下 — JNPF API 是 uuId 不是 uuid - } - return ActionResult.success(demoMapper.insert(dto) > 0 ? dto : null); - } - - @DeleteMapping("/Delete") - public ActionResult delete(@RequestParam String id) { - // 软删:update f_delete_mark=1,非 mapper.deleteById - DemoEntity upd = new DemoEntity(); - upd.setId(id); - upd.setDeleteMark((short) 1); - return demoMapper.updateById(upd) > 0 ? ActionResult.success() : ActionResult.fail(500, "删除失败"); - } -} \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/mapper/DemoMapper.java b/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/mapper/DemoMapper.java deleted file mode 100644 index 5a395b9..0000000 --- a/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/mapper/DemoMapper.java +++ /dev/null @@ -1,19 +0,0 @@ -package ssw.demo.mapper; - -import com.baomidou.dynamic.datasource.annotation.DS; -import jnpf.base.mapper.SuperMapper; -import ssw.demo.entity.DemoEntity; - -/** - * Demo Mapper — 直接继承 jnpf SuperMapper 拿到 CRUD 基本方法(list / save / updateById / deleteById 等)。 - * 包命名遵循 ssw.{appCode}.mapper 约定;appCode = demo。 - * - * 被 {@link ssw.common.config.SswMapperConfig} 的 @MapperScan(basePackages = "ssw.**.mapper") 自动注册。 - * - * ⚠️ @DS("ssw-demoDs") 切到业务库(对应 application-dev.yml 中 - * spring.datasource.dynamic.datasource.ssw-demoDs.url 配置的 PostgreSQL DB), - * 业务表 demo_demo 即建在该库。base_* 等权限表**不在**这里 — 由 jnpf 主库(master)托管。 - */ -@DS("ssw-demoDs") -public interface DemoMapper extends SuperMapper { -} \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/ssw-demo-entity/pom.xml b/template-boot-jnpf/ssw-demo/ssw-demo-entity/pom.xml deleted file mode 100644 index 1f4bad2..0000000 --- a/template-boot-jnpf/ssw-demo/ssw-demo-entity/pom.xml +++ /dev/null @@ -1,26 +0,0 @@ - - - - com.example - ssw-demo - 1.0.0-SNAPSHOT - - - 4.0.0 - ssw-demo-entity - jar - - - - com.jnpf - jnpf-common-database - ${jnpf.version} - - - org.projectlombok - lombok - - - \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/ssw-demo-entity/src/main/java/ssw/demo/entity/DemoEntity.java b/template-boot-jnpf/ssw-demo/ssw-demo-entity/src/main/java/ssw/demo/entity/DemoEntity.java deleted file mode 100644 index e4ac43d..0000000 --- a/template-boot-jnpf/ssw-demo/ssw-demo-entity/src/main/java/ssw/demo/entity/DemoEntity.java +++ /dev/null @@ -1,37 +0,0 @@ -package ssw.demo.entity; - -import com.baomidou.mybatisplus.annotation.TableField; -import com.baomidou.mybatisplus.annotation.TableName; -import jnpf.base.entity.SuperBaseEntity; -import lombok.Data; - -import java.math.BigDecimal; - -/** - * Demo 实体 — 演示 JNPF 形态:extends SuperBaseEntity 仅引入 f_id varchar(50) 主键。 - * 包命名遵循 ssw.{appCode}.entity 约定;appCode = demo。 - * - * 字段命名严格遵守「f_ 前缀 + snake_case」,与 MVP 端 ssw-jnpf-lite-react 的契约 1:1。 - * - * 表名 demo_demo — 命名约定 `{appCode}_{Entity_snake}`,与 MVP 的 HOWTO_MODULE.md §0 一致。 - * DDL 由 jnpf 启动时扫 @TableName 自动建(或在 db/schema.sql 手建)。 - * - * ⚠️ 本 Entity 放在哪个数据源由 {@link ssw.demo.mapper.DemoMapper} 上的 @DS("ssw-demoDs") 决定 - * (Entity 上不打 @DS,靠 Mapper 注解传递)。jnpf 7.0 启动后会自动建表到 ssw-demoDs 业务库。 - */ -@Data -@TableName("demo_demo") -public class DemoEntity extends SuperBaseEntity { - - @TableField("f_title") - private String title; - - @TableField("f_amount") - private BigDecimal amount; - - @TableField("f_enabled_mark") - private short enabledMark; - - @TableField("f_delete_mark") - private short deleteMark; -} \ No newline at end of file