From 9771fa844dd3a227f734b782e99d85be69396c20 Mon Sep 17 00:00:00 2001 From: sukyboor Date: Fri, 30 Oct 2026 22:08:31 +0800 Subject: [PATCH] =?UTF-8?q?init:=20=E5=B0=9A=E6=95=B0=E7=BD=91=E5=B9=B3?= =?UTF-8?q?=E5=8F=B0=20JNPF=207.0=20=E5=85=BC=E5=AE=B9=E5=90=8E=E7=AB=AF?= =?UTF-8?q?=EF=BC=88=E5=A4=9A=E5=BA=94=E7=94=A8=20+=20=E9=9D=A2=20A/?= =?UTF-8?q?=E9=9D=A2=20B=20=E5=8F=8C=E5=A5=91=E7=BA=A6=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - axum 0.8 + pglite:12 张表,多应用按 App-Code 头解析 f_system_id 隔离 - 面 A(ssw/react 形状)+ 面 B(官方 JNPF 形状,Vue-Version: 3)双契约并存 - 业务模块 asset/DataResource;面 B 用户 CRUD 9 条已落地 - 六道闸门 + 两把运行时尺子(perm-smoke 43 / perm-smoke-jnpf 23) - scripts/:前端接口清单、页面依赖反查、运行时探针 --- .env.example | 53 + .gitignore | 29 + .workbuddy/memory/2026-10-30.md | 127 ++ CLAUDE.md | 283 +++ Cargo.lock | 1448 +++++++++++++ Cargo.toml | 54 + HANDOFF.md | 137 ++ HOWTO_MODULE.md | 432 ++++ JNPF_COMPAT_SURFACE.md | 435 ++++ JNPF_SOURCE_AUDIT.md | 656 ++++++ MIGRATION.md | 312 +++ PERMISSION.md | 182 ++ README.md | 221 ++ docs/README-project.md | 152 ++ docs/contract.md | 1273 +++++++++++ docs/ddl/base_ddl_raw.sql | 206 ++ docs/decisions.md | 975 +++++++++ docs/fe/endpoints.tsv | 901 ++++++++ docs/fe/gap-permission.tsv | 133 ++ docs/fe/gap-runtime-user.txt | 28 + docs/fe/page-user.tsv | 25 + docs/known-limitations.md | 105 + docs/runbook.md | 420 ++++ references/BaseCrudController.java | 332 +++ references/README.md | 49 + run.sh | 277 +++ scripts/check-boundary-scan.py | 246 +++ scripts/check-boundary.sh | 268 +++ scripts/check-citations-scan.py | 570 +++++ scripts/check-citations.sh | 150 ++ scripts/check-contract-scan.py | 756 +++++++ scripts/check-contract.sh | 168 ++ scripts/check-module.sh | 573 +++++ scripts/contract_expect.py | 227 ++ scripts/fe-api-inventory.py | 316 +++ scripts/fe-gap.py | 164 ++ scripts/fe-page-deps.py | 187 ++ scripts/ipc-reap.c | 123 ++ scripts/perm-smoke-jnpf.sh | 714 +++++++ scripts/perm-smoke.sh | 476 +++++ scripts/probe-page.py | 121 ++ scripts/reap-ipc-leaks.sh | 37 + scripts/smoke_backend.sh | 140 ++ src/backend/Cargo.toml | 36 + src/backend/db/schema.sql | 319 +++ src/backend/src/bootstrap.rs | 29 + src/backend/src/lib.rs | 18 + src/backend/src/main.rs | 502 +++++ src/backend/src/modules/asset.rs | 178 ++ src/backend/src/modules/books.rs | 161 ++ src/backend/src/modules/demo.rs | 145 ++ src/backend/src/modules/mod.rs | 340 +++ src/backend/src/modules/shop.rs | 136 ++ src/backend/src/platform/auth.rs | 274 +++ src/backend/src/platform/cipher.rs | 213 ++ src/backend/src/platform/config.rs | 160 ++ src/backend/src/platform/crud.rs | 615 ++++++ src/backend/src/platform/db.rs | 1093 ++++++++++ src/backend/src/platform/entity.rs | 48 + src/backend/src/platform/envelope.rs | 224 ++ src/backend/src/platform/guard.rs | 344 +++ src/backend/src/platform/ids.rs | 54 + src/backend/src/platform/jnpf.rs | 1550 ++++++++++++++ src/backend/src/platform/menu.rs | 50 + src/backend/src/platform/mod.rs | 36 + src/backend/src/platform/permission.rs | 463 ++++ src/backend/src/platform/seed.rs | 630 ++++++ src/backend/src/platform/session.rs | 181 ++ src/backend/src/platform/state.rs | 36 + src/backend/src/platform/sys.rs | 1295 ++++++++++++ src/backend/src/platform/system.rs | 196 ++ src/backend/src/platform/test_support.rs | 27 + src/backend/src/routes.rs | 787 +++++++ src/backend/tests/auth_it.rs | 554 +++++ src/backend/tests/crud_it.rs | 853 ++++++++ src/backend/tests/db_it.rs | 305 +++ src/backend/tests/guard_it.rs | 166 ++ src/backend/tests/permission_it.rs | 675 ++++++ src/backend/tests/seed_it.rs | 522 +++++ src/backend/tests/sys_it.rs | 1883 +++++++++++++++++ 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 + 95 files changed, 30592 insertions(+) create mode 100644 .env.example create mode 100644 .gitignore create mode 100644 .workbuddy/memory/2026-10-30.md create mode 100644 CLAUDE.md create mode 100644 Cargo.lock create mode 100644 Cargo.toml create mode 100644 HANDOFF.md create mode 100644 HOWTO_MODULE.md create mode 100644 JNPF_COMPAT_SURFACE.md create mode 100644 JNPF_SOURCE_AUDIT.md create mode 100644 MIGRATION.md create mode 100644 PERMISSION.md create mode 100644 README.md create mode 100644 docs/README-project.md create mode 100644 docs/contract.md create mode 100644 docs/ddl/base_ddl_raw.sql create mode 100644 docs/decisions.md create mode 100644 docs/fe/endpoints.tsv create mode 100644 docs/fe/gap-permission.tsv create mode 100644 docs/fe/gap-runtime-user.txt create mode 100644 docs/fe/page-user.tsv create mode 100644 docs/known-limitations.md create mode 100644 docs/runbook.md create mode 100644 references/BaseCrudController.java create mode 100644 references/README.md create mode 100755 run.sh create mode 100644 scripts/check-boundary-scan.py create mode 100755 scripts/check-boundary.sh create mode 100644 scripts/check-citations-scan.py create mode 100644 scripts/check-citations.sh create mode 100644 scripts/check-contract-scan.py create mode 100644 scripts/check-contract.sh create mode 100755 scripts/check-module.sh create mode 100755 scripts/contract_expect.py create mode 100644 scripts/fe-api-inventory.py create mode 100644 scripts/fe-gap.py create mode 100644 scripts/fe-page-deps.py create mode 100644 scripts/ipc-reap.c create mode 100644 scripts/perm-smoke-jnpf.sh create mode 100755 scripts/perm-smoke.sh create mode 100644 scripts/probe-page.py create mode 100755 scripts/reap-ipc-leaks.sh create mode 100644 scripts/smoke_backend.sh create mode 100644 src/backend/Cargo.toml create mode 100644 src/backend/db/schema.sql create mode 100644 src/backend/src/bootstrap.rs create mode 100644 src/backend/src/lib.rs create mode 100644 src/backend/src/main.rs create mode 100644 src/backend/src/modules/asset.rs create mode 100644 src/backend/src/modules/books.rs create mode 100644 src/backend/src/modules/demo.rs create mode 100644 src/backend/src/modules/mod.rs create mode 100644 src/backend/src/modules/shop.rs create mode 100644 src/backend/src/platform/auth.rs create mode 100644 src/backend/src/platform/cipher.rs create mode 100644 src/backend/src/platform/config.rs create mode 100644 src/backend/src/platform/crud.rs create mode 100644 src/backend/src/platform/db.rs create mode 100644 src/backend/src/platform/entity.rs create mode 100644 src/backend/src/platform/envelope.rs create mode 100644 src/backend/src/platform/guard.rs create mode 100644 src/backend/src/platform/ids.rs create mode 100644 src/backend/src/platform/jnpf.rs create mode 100644 src/backend/src/platform/menu.rs create mode 100644 src/backend/src/platform/mod.rs create mode 100644 src/backend/src/platform/permission.rs create mode 100644 src/backend/src/platform/seed.rs create mode 100644 src/backend/src/platform/session.rs create mode 100644 src/backend/src/platform/state.rs create mode 100644 src/backend/src/platform/sys.rs create mode 100644 src/backend/src/platform/system.rs create mode 100644 src/backend/src/platform/test_support.rs create mode 100644 src/backend/src/routes.rs create mode 100644 src/backend/tests/auth_it.rs create mode 100644 src/backend/tests/crud_it.rs create mode 100644 src/backend/tests/db_it.rs create mode 100644 src/backend/tests/guard_it.rs create mode 100644 src/backend/tests/permission_it.rs create mode 100644 src/backend/tests/seed_it.rs create mode 100644 src/backend/tests/sys_it.rs create mode 100644 template-boot-jnpf/.env.example create mode 100644 template-boot-jnpf/README.md create mode 100644 template-boot-jnpf/pom.xml create mode 100755 template-boot-jnpf/scripts/verify.sh create mode 100644 template-boot-jnpf/ssw-admin/pom.xml create mode 100644 template-boot-jnpf/ssw-admin/src/main/java/ssw/SswAdminApplication.java create mode 100644 template-boot-jnpf/ssw-admin/src/main/java/ssw/common/config/SswMapperConfig.java create mode 100644 template-boot-jnpf/ssw-admin/src/main/resources/application-dev.yml create mode 100644 template-boot-jnpf/ssw-admin/src/main/resources/application.yml create mode 100644 template-boot-jnpf/ssw-demo/pom.xml create mode 100644 template-boot-jnpf/ssw-demo/ssw-demo-controller/pom.xml create mode 100644 template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/controller/DemoController.java create mode 100644 template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/mapper/DemoMapper.java create mode 100644 template-boot-jnpf/ssw-demo/ssw-demo-entity/pom.xml create mode 100644 template-boot-jnpf/ssw-demo/ssw-demo-entity/src/main/java/ssw/demo/entity/DemoEntity.java diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..6e5c6d4 --- /dev/null +++ b/.env.example @@ -0,0 +1,53 @@ +# ssw-platform 环境变量样例 +# +# 用法:cp .env.example .env 后按需修改;run.sh 会把 .env 里的变量导出给子进程。 +# 🔴 本文件里的每一项都必须是「**生效的**」值 —— 注释掉才是「不生效」。 + +# 后端监听端口(缺省 30010)。 +# 🔴 不许改成 30010 以外的端口:兄弟项目 tdc-rs 已经占了它自己的后端端口, +# 两套服务必须彻底分开(不共享端口 / 数据目录 / 代码)。 +PORT=30010 + +# 后端监听地址。 +# +# 🔴 **默认只监听本机**(127.0.0.1):本仓的种子口令是 admin/123456、token 永不过期 +# ⇒ 若默认监听所有网卡,局域网内可以直接连上后端 ⇒ 必须朝安全方向默认。 +# 要在容器 / 反代里对外暴露,才把它改成 0.0.0.0。 +# +# 🔴 只接受**字面 IP**(127.0.0.1 / 0.0.0.0 / ::1);写主机名(如 localhost) +# 会被判非法 ⇒ 回落 127.0.0.1。 +BIND_ADDR=127.0.0.1 + +# pglite 数据目录。 +# +# 🔴 **留空** ⇒ 用后端的默认值 `<项目根>/src/backend/data/lite.pg` +# (**绝对路径**,由可执行文件向上定位项目根 ⇒ 与 cwd 无关)。 +# +# 🔴 **不要**在这里写一个**相对**的 PGLITE_DIR:config.rs 对 PGLITE_DIR 是**原样使用** +# (相对路径 ⇒ 相对**当前工作目录**解析)⇒ 换个 cwd 就换一份库,而且**静默**。 +# 真要覆盖,只能写**绝对路径**,例如: +# PGLITE_DIR=/Users/xxx/ssw-platform/src/backend/data/lite.pg +# +# 临时库(进程退出即销毁)—— pglite-rs 0.2.7 没有真内存模式, +# `memory://` 走的是 `PGlite::open_temp()`(系统临时目录里的一次性数据目录)。 +# PGLITE_DIR=memory:// + +# 部署档位(缺省 dev)。 +# +# 🔴 `dev`(缺省)= **一律不判弱口令**(本地开发/演示形态,契约与冒烟脚本零影响)。 +# 🔴 `prod` = **六条弱口令判据逐条生效**,任一违规 ⇒ **拒绝启动**(人话报错 + exit 1): +# ① 键不在本部署清单里 ⇒ 跳过 ② 值为空/空白 ③ 精确等于已知弱值 +# ④ 含已知弱值(反绕过) ⑤ 命中弱标记词(整体词) ⑥ 长度 < 12 +# 另外还会**回读库里的 admin 行** —— 种子口令只对空库生效 ⇒ 库里那个可能是当初 +# 种下的 `123456`,而运维后来才设了 `SEED_ADMIN_PASSWORD` ⇒ 只查配置 = 守卫形同虚设。 +# +# 取值:`dev` / `prod`(`production` 也认;**非法值回落 dev**,朝不误伤本地开发的方向)。 +# SSW_PROFILE=prod + +# 首启 admin 的种子口令(明文;缺省 123456 = 契约 §8.6 逐字要求)。 +# +# 🔴 **只在空库首启时生效**(`base_user` 行数为 0)⇒ 已有库里改它**没用**, +# 要改口令请在管理界面里改(或清库重来)。 +# 🔴 生产档请给一个**强**口令(≥ 12 位、不是已知弱值/弱标记词), +# 否则 `SSW_PROFILE=prod` 会拒绝启动。 +# SEED_ADMIN_PASSWORD=123456 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..dafa5ce --- /dev/null +++ b/.gitignore @@ -0,0 +1,29 @@ +# Rust / cargo +target/ +**/target/ + +# 运行期数据(pglite 数据目录) +src/backend/data/ +src/backend/data.bak-*/ +*.pg/ + +# 前端 +src/frontend/node_modules/ +src/frontend/dist/ +src/frontend/.vite/ + +# SDD 工作区(git-ignored 草稿) +.superpowers/ +.tmp/ + +# Python 字节码缓存(scripts/ 下的扫描器被 import 时会生成) +__pycache__/ +*.pyc + +# 运行期 PID / 日志 +.run/ +.logs/ +*.log + +# macOS +.DS_Store diff --git a/.workbuddy/memory/2026-10-30.md b/.workbuddy/memory/2026-10-30.md new file mode 100644 index 0000000..d5d180c --- /dev/null +++ b/.workbuddy/memory/2026-10-30.md @@ -0,0 +1,127 @@ +# 2026-10-30 + +## ssw-platform 规划(尚数网 Rust 后端) + +- 任务:参考 JNPF v7.0(git-mirror),做 Rust 版尚数网开发框架,先后端;前端/移动端/数据库暂兼容 Java 版;多租户/SSO/微服务暂不迁。 +- 探索结论: + - 脚手架 `ssw-jnpf-lite-rust`(~/Desktop/workspace/skills/ssw-jnpf-lite-rust,三处软链同仓)已交付双面契约后端:面 A(ssw 形状,冻结 27 路由)+ 面 B(官方 JNPF 形状,18/18,按 `Vue-Version: 3` 分流)。共享 base_* schema + 同一把 cipher + seed。六道闸门(4 静态 + 2 契约尺子)。 + - JNPF v7.0 java-boot 模块:jnpf-system/jnpf-permission(迁)、jnpf-admin(部分)、jnpf-oauth(SSO 跳过)、jnpf-tenant(独立仓,跳过)、jnpf-flowable/ai/file/message/scheduletask/extend/app(暂缓)、jnpf-public/common-all(部分)/generater-base/provider(跳过)。 + - DDL 真源:git-mirror `jnpf/7.0-jnpf-database`(`PostgreSQL/JNPF-PostgreSQL.sql`);本地 ~/Desktop/workspace/jnpf 仅有白皮书,无源码。 +- 产出:`/Users/xs/Desktop/workspace/ssw-platform/CLAUDE.md`(规划/红线/模块取舍/兼容策略/路线图/待确认决策)。 +- 待确认:crate 命名、DB 形态(pglite-rs→真实 PG)、Java 版面 B diff、首批业务模块、文件依赖。 +- 下一步:Phase 0 实例化脚手架 → Phase 1 跑六闸门 → Phase 2 Java 前端实连面 B 验证。 + +## 多应用架构 MVP(已落地) + +- 决策(用户确认):当前应用用 **`App-Code` 头**(官方 JNPF 方式)选定;本期 MVP = 注册表 + 路由 + 系统级隔离(不做 `SystemController` CRUD)。与多租户(`f_tenant_id`,仍延期)是两码事。 +- 落点: + - `db/schema.sql` 新增 `base_system`(注册表,`en_code`=App-Code,`id`=systemId,复合 PK `(f_id,f_tenant_id)`)。 + - 新建 `platform/system.rs`:`MAIN_SYSTEM_ID/CODE="ssw-platform"`、`app_code_of(headers)`、`resolve_system(db,app_code)→SystemRef{id,code}`(None/未知/DB错一律回落主系统,绝不 panic)、`resolve_system_id`。 + - `MenuSpec` 加 `system_en_code` 字段;所有菜单查询 `build_menu_list`/`load_menus`/`has_module`/`has_en_code_permission` 全部按 `f_system_id` 隔离;业务菜单填 `MAIN_SYSTEM_CODE`。 + - `seed.rs`:`ensure_systems` 种主系统 + `app-b`(app-b 无菜单,专门验证隔离且不破坏 CP6 平台菜单计数);`first_seed` 经 `bootstrap::ensure_base` 单入口。 + - `auth.rs`/`jnpf.rs` 的 `CurrentUser`/`userInfo` 加 `currentSystemId`/`systemId`/`systemCode`(由 app_code 解析,不再硬编码)。 + - 测试统一走新建 `platform/test_support.rs` 的进程级共享 pglite(pglite 每进程只能开一次,旧 `routes.rs` 模块级 OnceCell 与 `system.rs` 各自 open_temp 会 `AlreadyOpen`/`ReopenUnsupported`)。 + - `main.rs` `BASE_TABLES` 由 7 张扩到 8 张(加 `base_system`),否则启动白名单自检报「孤儿 DDL」。 +- 闸门终态:lib 单测 98 全过;`check-boundary`(11/0)、`check-contract`(10/0)、`perm-smoke`面A(32/0)、`perm-smoke-jnpf`面B(18/0) 全绿。`check-module`(87 vs 契约登记93) 与 `check-citations`(CIT1/CIT2/CIT3) 为**改动前就存在**的文档/契约登记漂移(指向本仓没有的 JNPF 官方源码文件),与多应用无关。 +- 延期项:真正第二个有菜单的应用接入、CLAUDE.md 同步多应用决策与重命名。 + +## 计划推进第二轮(六闸门全绿 + 首个真实业务模块) + +- 计划(用户「列个计划,逐步推」)6 项:① check-module 反映后端-only ② 拉 JNPF 源码修 check-citations ③ CLAUDE.md 同步 ④ 多应用钉进契约尺子 ⑤ 落真实业务模块 ⑥ 总复核归档。①–④ 已完成,⑤⑥ 本轮完成。 +- ①check-module:加 `HAS_FE` 探测(无 `src/frontend` ⇒ 前端 4 处打 `⏭` 且仍计入条数);契约 `[RULER]` 口径 93→86(当时 3 模块)。 +- ②check-citations:从内网 Gitea 浅克隆 `jnpf-database/java-boot/web-apps-main/common/resources` 到 `~/Desktop/workspace/jnpf/`,192 条引文全解析,CIT1/CIT2 绿(CIT3 仍 SKIP:DDL 行号表对账依赖官方 `JNPF-PostgreSQL.sql`)。 +- ③CLAUDE.md:多应用章节、表数、重命名、路线图 Phase 1.5 已同步。 +- ④多应用钉进尺子:面 A 加 2 条(无头⇒主系统 / `App-Code: app-b`⇒app-b),面 B 加 1 条同类断言 ⇒ `[RULER]` 34 / 19。 + - 坑:`currentSystemId` 在**信封 `data` 内**(`.data.currentSystemId`),取值器写到根上会静默得空串 ⇒ 假失败。 +- ⑤首个真实业务模块 `asset/DataResource`(数据资源):字段逐字取自公司本体 `DataResource`(名称/类别/应用场景/提供方/格式/规模/来源/登记时间),物理表 `asset_data_resource`,菜单 `m_resource`(sort 9),路由 `/api/ssw/asset/DataResource/{List,Save,Delete}`。只碰 `modules/asset.rs` + `modules/mod.rs` + `schema.sql` + 契约。 + - 坑 1:`router()` 必须写**字面量路径**(不能用 `ROUTES[0]`)——`check-contract-scan.py` 静态解析认不出数组下标 ⇒ CC2/CC3 假漂移。 + - 坑 2:`crud.rs::write_cast` 原先只硬编码 `f_creator_time` ⇒ 业务时间列 `f_register_time` 报 `column is of type timestamp but expression is of type text`。改成 **`f_*_time` 后缀通用规则**(规律优于枚举,避免「加模块要改平台层」)。 + - 坑 3:`check-contract-scan.py` 的反自证用例 `bad_face` 写死 `A\t25\t` 锚点 ⇒ 改 `[FACE]` 条数后反自证失效。改成**动态取现值再减 1**。 + - 坑 4:`cargo test -p ssw-platform --lib` **不覆盖** `tests/*.rs` 集成测试 ⇒ 多应用改签名后 `permission_it`(14 处)/`auth_it`/`seed_it` 全挂。教训:**交付前必须跑 `cargo test`(无 `--lib`)**。 + - 集成测试去硬编码:`seed_it` 用 `5 + modules::ALL_MENUS.len()` 派生菜单数;`auth_it` 根菜单断言改 `>= 4`;`permission_it` 的 `SYS` 常量 + 9 条菜单树。 +- 闸门终态(本轮):`cargo test` **221**(lib 98 + 集成 123)、check-module **114/114**、check-boundary 11/11、check-contract 10/10、check-citations 4/4、perm-smoke 面A **43/43**、perm-smoke-jnpf 面B **19/19**。 +- 文档同步:契约 `[MODULE]/[MENU]/[MENU_TREE]/[ENDPOINT]×3/[FACE]25→28/[RULER]`、§5.3 列清单加 `asset_data_resource`、§13 断言表 33–43;`HOWTO_MODULE.md` 条数与两个新坑;`CLAUDE.md` 表数 12、条数、Phase 3 状态;`MIGRATION.md` 表数;`docs/runbook.md` 的 `cd` 路径(原指向脚手架目录)。 +- 待办:Phase 2(Java 前端实连面 B);真正第二个「有菜单」的应用;CIT3 的 DDL 行号表仍需官方 dump。 + +## 补:官方源码到手 + 改成「前端驱动」路线(同日) + +- **官方源码来源确定**:公司 GitLab `http://192.168.1.2:8080/platform/jnpf-platform/7.0`(单仓,`main`)。凭据 xop `jnpf_git_user`/`jnpf_git_pass`,用 `GIT_ASKPASS` 脚本**不要**把密码写进 URL。 + - 🔴 **别全量克隆**:.git 已涨到 430M 且仅 0.8MB/s。用 `git clone --depth 1 --filter=blob:none --no-checkout` + `git sparse-checkout set` ⇒ 1.2M 拿树,按需取 blob 共 ~270M。 + - 🔴 `git ls-tree -l`(带 `-l`)会触发**拉 blob**(列大小要读内容);只看结构一律用 `--name-only`。 + - GitLab API v4 **不接受账号密码**(`-u user:pass` → 404 Project Not Found),只能走 git 协议。 +- **官方 DDL 拿到**:`database/PostgreSQL/JNPF-PostgreSQL.sql`(791KB / **13227 行 / 331 张表**)。软链 `~/Desktop/workspace/jnpf/jnpf-database -> 7.0/database` 满足 `check-citations-scan.py:43` 的既有路径 ⇒ **CIT3 从 SKIP 变真校验**(CLAUDE.md §5.1 加 8 条 DDL 行号表)。 +- **三处实现偏差(前端源码/官方常量直接掀出来的,已修)**: + 1. `JnpfConst.MAIN_SYSTEM_CODE = "mainSystem"`(不是自造的 `ssw-platform`);官方种子 `f_id=309228585019769285`/`f_full_name=系统平台`/`f_is_main=1`。前端 `CollectPane.vue`/`CommonPane.vue` 硬比较 `systemCode === 'mainSystem'` ⇒ 常量必须对齐。 + 2. `base_system` 官方 **24 列**(有 `f_is_main`/`f_icon`/`f_portal_id`/`f_app_portal_id`/`f_preference_json`/`f_background_color`/`f_user_id`/`f_authorize_id`/`f_tag_id`/`f_last_modify_user_id`),我自造的少了 10 列还多一个官方没有的 `f_category`。**已逐字对齐**(schema.sql + seed 11 参数)。 + 3. 面 B `CurrentUser`:前端类型 `GetUserInfoModel` 要 **5 个键**(`menuList/permissionList/routerList/sysConfigInfo/userInfo`),我缺 `routerList`;`UserInfo` 声明 **40 个字段**(`roleIds/groupIds/organizeIds/positionIds/organizeList/positionList/standingList` 是非可选数组),我只给了 15 个 ⇒ 已补到 **40 个一个不缺**(`f_role_id`/`f_group_id` 逗号分隔拆数组,`preferenceJson` 必须是字符串)。 + - 附带坑:`resolve_system(None)` 改成**也走 DB 按 `mainSystem` 查**(不再直接返常量),这样部署方把主系统 `f_id` 建成雪花号也能对上 `f_system_id`。 + - 附带坑:schema.sql 注释里写 `CREATE TABLE base_system` 会被 `SCHEMA_SQL.matches("CREATE TABLE ")` 数进去 ⇒ 表数 13≠12 假失败。 +- **前端真实请求契约(`src/api/request.ts` 逐条读出来的)**: + - 头:`Authorization = <裸 token,无 bearer 前缀>`、`App-Code = getRealJnpfAppEnCode()`(从 URL 路径前缀 `/app-xxx/` 解析,可能为空串)、`Accept-Language`、`Jnpf-Origin: pc`、`Vue-Version: 3`。 + - 信封 `{code,msg,data}`,`ResultEnum` = 200/403/**600 超时/601 已注销/602 无效**(我后端已一致)。 + - **登录是 form-urlencoded body**:`RequestClient:91-114` 把「非 GET 且只给 `params`」的 `params` 当 `data`,再 `qs.stringify` ⇒ `POST /api/oauth/Login` body = `account=&password=&grant_type=`。Content-Type 带 `;charset=UTF-8` 后缀也能过。 + - `CurrentUser` 返 `403` 且 `App-Code` 非空 ⇒ 前端跳 `/forbidden`(合法路径,要能复现)。 + - dev 代理:前端 3000,`/dev` → `http://localhost:30000`,`proxy.ts:36` **rewrite 会剥掉 `/dev`** ⇒ 后端直接听 **30000**、路径就是 `/api/...`。 +- **端点权威清单工具**:`scripts/fe-api-inventory.py`(解析 `enum Api{}` + `defHttp.({url})`,含模板串拼接),产出 `docs/fe/endpoints.tsv`。 + - 实测:**900 个端点 / 147 个前缀组**;本仓面 B 只覆盖 **7** 个。 + - `--diff docs/contract.md` 直接出覆盖率矩阵;`--group` 按前缀汇总。 + - 大组:`permission/Users` 49、`file/Document` 25、`workflow/*` 50、`system/Dataset` 18、`system/Menu` 13、`system/System` 14、`system/Dictionary*` 15。 + - 按页面(`views/permission/*` 的 import 反查):用户管理 53、机构管理 40、菜单管理 29+、角色管理 13、角色授权 26。 +- 真机自检(后端 30000 + 前端真实头):登录取到 token、`CurrentUser` 200、6 顶层键、userInfo 40 字段、`systemCode=mainSystem`、菜单 5 根/9 条授权、菜单节点 15 键;裸 token 与空 `App-Code` 都能过。 +- 前端依赖:`pnpm install` 在 `~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework`(vben 风格 turborepo,workspace 里 `packages/business|presets|@core/forward` 是残留 glob,仓库里根本不存在)。 + +## 20:0x 前端依赖安装排查 + 三个新脚本 + +**结论:慢的既不是源也不是缓存,是 pnpm 的「每包落盘」步骤。** +- 生效配置本来就是国内源 `registry.npmmirror.com`(`~/.npmrc` + 前端工程 `.npmrc` 都有), + store 本来就在 `~/.cache/pnpm/store/v10`(`~/Library/pnpm/store/v10` 是软链过去,符合 §2 约定), + 所以「换源」「按约定放 ~/.cache」两条**早在上一轮就已落地**,无需改动。 +- 实测四家镜像取同一个 5.4MB 包:npmmirror 1.04MB/s、腾讯 1.32、华为 0.58、npmjs 0.87 + ⇒ 同一量级,**换源救不了**;8 并发 curl 8 个包 6.6s ⇒ 网络也不是瓶颈。 +- 真瓶颈:`pnpm install` 全程 ~0.15 包/s,磁盘 `iostat` 却基本空转(tps 19~136,MB/s ≤1.8), + 进程大量 FD 挂在 `/` 上 ⇒ 像是被安全软件/文件监控逐次拦截,非磁盘性能问题(dd 1.5GB/s)。 +- `--ignore-scripts` 不改变速率(排除 postinstall 卡死);缓存命中率本身很高: + `resolved 2169 / reused 1879`,只有 290 个包需要下载。 + +**三个新脚本(都进 `scripts/`,驱动「从 web 端逐个 api 突破」)** +- `fe-gap.py`:前端 900 条接口 × 后端真实注册路由 ⇒ 缺口表。**catch-all 与 `routes.rs` + 里「期望路径字符串数组」都不能算实现**(第一版踩了这个坑,把未实现误判成已实现)。 +- `fe-page-deps.py`:`views/**/*.vue` 的 `#/api/*` 具名导入反查 ⇒ **页面 → 接口**。 + 🔴 递归取同目录 `.vue` 时必须 `if seen is None` 而不是 `seen or set()`——空 set 是 falsy, + 会每层新建 set,环形 import 直接 OOM 被 kill(实测 SIGKILL 137)。 +- `probe-page.py`:拿页面接口清单**打真后端**(路径参数填 `__probe__`,集合写接口默认跳过)。 + 静态比对 ≠ 运行时事实,这个才回答「路由真注册了吗」。 + +**运行时缺口(用户管理页,24 条)**:只有 `GET /api/permission/Users` 通,18 条 404、5 条写接口未探。 +明细 `docs/fe/gap-runtime-user.txt`、`docs/fe/page-user.tsv`。 + +## 21:0x 面 B 用户 CRUD 第一批落地(9 条路由) + +**真正的病根找到了:`pnpm install` 慢/失败是 WorkBuddy 沙箱的文件策略**,不是源也不是缓存。 +- 沙箱下:~0.15 包/s,磁盘空转,进程 FD 挂在 `/`(**每个文件操作都被 broker 拦一遍**)。 +- 退出沙箱(`dangerouslyDisableSandbox`):**1.4 包/s,快 10 倍**;跑到尾还报 + `ERR_PNPM_CODEBUDDY_BROKER_DENY — Brokered host rename overwrite refused by file policy` + ⇒ 前端目录在项目工作区**之外**,rename 被策略拒绝。**结论:跨工作区跑包管理器必须退沙箱。** + +**已实现(`platform/jnpf.rs`,9 条)**:`POST /Users`、`GET|PUT|DELETE /Users/{id}`、 +`/Users/BatchDelete`、`/Users/BatchUpdateState`、`/Users/{id}/GetPosition`、 +`/Users/{id}/Actions/ResetPassword`、`/Users/{id}/Actions/unlock`。 +- 写路径三条硬律:列名只来自常量 `USER_WRITE_FIELDS`;读回**不选** `f_password`; + 失败恒 code=400/500。 +- 🔴 **`ranks` ↔ `f_rank`、`certificatesType` ↔ `f_certificates_type`**:官方驼峰与 DDL + 下划线**不是**机械对应,别用下划线转换。 +- 🔴 `f_creator_time` 直接写 SQL `now()`,**不占参数位**(`$$` 序号和 `columns` 必须等长, + 用 `marks.push("now()")` 对齐)。 + +**踩坑** +- `check-contract-scan.py` **只解析每个 `.route()` 的第一个方法** ⇒ `get(a).post(b)` + 会被判成「契约写 POST、代码是 GET」。**一条 `.route()` 只挂一个方法**,同路径多次 + `.route()` 在 axum 里是合并,不冲突。 +- `JNPF_REGISTERED` 按**路径**列(同路径多方法算一条)⇒ 11 条不是 14 条。 +- jq 里 `$d|has(x) or $d|has(y)` 会被 `|` 抢结合 ⇒ 必须 + `[keys[]|select(.=="x" or .=="y")]|length`。 + +**闸门全绿**:cargo test 221、check-contract 10/10、check-boundary 11/11、 +check-module 114/114、check-citations 4/4、perm-smoke 43/43、perm-smoke-jnpf **23/23** +(新增断言 20~23:建档 / 详情无口令 / 改档只 SET 出现的键 / 批量启停+软删)。 +契约 `[ENDPOINT]` 35→44 条、`[FACE]` B 5→14、`[OFFICIAL]` 翻转 9 条 absent→implemented。 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..64d300f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,283 @@ +# CLAUDE.md — 尚数网 Rust 后端开发框架(ssw-platform) + +> **本文件是项目级规划 / agent 红线文件。** 代码级「契约唯一真源」在脚手架自带的各项文档里 +> (`docs/contract.md` / `JNPF_COMPAT_SURFACE.md` / `PERMISSION.md` / `MIGRATION.md` 等), +> 本文件只管 **项目级决策:做什么 / 不做什么 / 为什么 / 验收口径 / 路线图**。 +> 改代码后回头核对本文件是否还成立。 + +--- + +## 0. 一句话定位 + +**尚数网 Rust 后端(ssw-platform)= 用 Rust 重写「尚数网 Java 版后台」,契约与数据库逐字兼容 Java 版(= JNPF v7.0 形状),从而前端 / 移动端 / 库原地不动,只换后端引擎。** + +- 后端先迁(单二进制、好部署、编译期类型安全)。 +- 前端 / 移动端 / 数据库 **本期不动**,靠「双面契约 + 同一套 `base_*` schema + 同一把 cipher + 同一套 seed」做到兼容。 +- 多租户 / SSO / 微服务 **本期不迁**(见 §2.2)。 + +技术底座 = 已验证的 `ssw-jnpf-lite-rust` 脚手架(axum 0.8 + pglite-rs 0.2 进程内 PostgreSQL,零外部服务)。 +本仓库 = 该脚手架的**实例化项目**;脚手架文档即本项目的契约真源,升级从脚手架同步进来。 + +--- + +## 1. 三个参照物(各司其职,别混) + +| 参照物 | 路径 | 地位 | +|---|---|---| +| **JNPF v7.0 官方源码 + DDL** | git-mirror `jnpf/7.0-jnpf-java-boot` + `jnpf/7.0-jnpf-database`(`PostgreSQL/JNPF-PostgreSQL.sql`) | **数据模型真源**:`base_*` 表名/列名/陷阱以官方 DDL 为准 | +| **`ssw-jnpf-lite-rust` 脚手架** | `~/Desktop/workspace/skills/ssw-jnpf-lite-rust/`(三处软链同仓) | **契约/工程真源**:本项目的模板与绑定规范 | +| **尚数网 Java 版(公司 fork)** | 当前生产系统(不在这些 mirror 里) | **兼容目标**:其前端/移动端/库应由本后端无缝接管 | + +🔴 **关键判断**:mirror 里只有上游 JNPF,没有公司 fork。因此「兼容 Java 版」在工程上 += **兼容官方 JNPF v7.0 契约(面 B)+ 同一套 `base_*` schema**。Java 版若对官方有定制, +需要在 Phase 2 拿 Java 版实跑一次面 B diff(见 §8 待确认决策 ③)才能确认覆盖度。 + +--- + +## 2. 范围 + +### 2.1 本期必做(v1,= 脚手架已交付能力) + +- **后端平台层**:登录 / `CurrentUser` / 5 组 `base_*` 管理 CRUD / 统一授权 / 四源权限合并 / 两段式种子。 +- **双面契约**:面 A(ssw/react 形状,冻结)+ 面 B(官方 JNPF 形状,按 `Vue-Version: 3` 分流)。面 B 让 Java 前端/移动端直连。 +- **3 个示例业务模块**(demo / shop / books)—— 作为「加业务模块」的模板,不进生产。 +- **多应用(app)**:`App-Code` 请求头选定当前应用;`base_system` 注册表 + `f_system_id` 系统级隔离(模块/菜单/授权按系统切分)。**本期只做注册表 + 路由 + 隔离**,不做 `SystemController` CRUD。见 §4.1。 +- **数据库**:复用 JNPF v7.0 官方 `base_*` DDL(8 张表,含多应用注册表 `base_system`)+ 业务表;进程内 pglite-rs(真实 PostgreSQL 语义),后续可换真实 PG。 + +### 2.2 本期不做(明确暂缓,别偷跑) + +| 项 | 官方对应 | 原因 | +|---|---|---| +| 多租户 | `7.0-jnpf-java-tenant` / `f_tenant_id` | 单租户固定 `'0'`,暂不切分 | +| SSO / OAuth | `jnpf-oauth`(`jnpf-oauth-api/-biz/-controller/-entity`) | 用内部账号密码会话 token,不做第三方登录 | +| 微服务拆分 | `jnpf-public/jnpf-provider` | 单进程 monolith,不做 RPC/服务注册 | +| 低代码引擎 | `jnpf-flowable` / visualdev / 代码生成 | 官方能力,本期不碰 | +| 文件 / 消息 / AI / 调度 / 扩展 / 应用中心 | `jnpf-file` / `jnpf-message` / `jnpf-ai` / `jnpf-scheduletask` / `jnpf-extend` / `jnpf-app` | 后续按需,不在 v1;注意 Java 前端可能依赖文件上传等,Phase 2 验证时确认 | +| 按钮/列/表单/数据范围级授权 | `base_module_button/_column/_form/_data` | 仅做 `item_type='module'`(菜单)一类 | + +--- + +## 3. JNPF v7.0 模块取舍(java-boot 模块映射) + +`7.0-jnpf-java-boot` 是 Maven 多模块,顶层模块如下(已逐模块判定): + +| java-boot 模块 | 决策 | 映射到本后端 | +|---|---|---| +| `jnpf-system`(`jnpf-system-biz/-controller/-entity`) | ✅ 移植 | 平台层:`base_user`/`base_role`/`base_organize`/`base_module` 管理及面 B 的 `User`/`Role`/`Organize`/`Menu` | +| `jnpf-permission` | ✅ 移植 | 平台层:授权写入 + 面 B `Authority/Data`、`Users`、`Role`、`Organize/AsyncList`、`Menu/ModuleBySystem` | +| `jnpf-admin`(聚合入口 + AOP/filter) | 🟡 部分 | 登录/`CurrentUser`/`AuthFilter` 已映射为面 A/面 B;tenant 过滤、多数据源、sharding 跳过 | +| `jnpf-public/jnpf-common-all` | 🟡 部分 | `base_*` 实体与 DDL 已对齐;其余 common 工具用 Rust 自有实现 | +| `jnpf-public/jnpf-generater-base` | ⛔ 跳过 | 代码生成器(低代码),不在 v1 | +| `jnpf-public/jnpf-provider` | ⛔ 跳过 | RPC/微服务 | +| `jnpf-oauth` | ⛔ 跳过 | SSO(§2.2) | +| `7.0-jnpf-java-tenant`(独立仓) | ⛔ 跳过 | 多租户(§2.2) | +| `jnpf-flowable` | ⛔ 暂不 | 工作流/低代码 | +| `jnpf-ai`(`jnpf-ai-v2/-v3`) | ⏸ 暂缓 | AI 能力后续按需 | +| `jnpf-file` | ⏸ 暂缓 | 文件上传/预览;Phase 2 确认 Java 前端是否依赖 | +| `jnpf-message` / `jnpf-scheduletask` / `jnpf-extend` / `jnpf-app` | ⏸ 暂缓 | 消息/定时/扩展/应用中心 | +| `jnpf-example` / `jnpf-exception` | ⛔ 不迁 | 示例 / 异常处理(Rust 自有) | + +**DDL 真源**:`jnpf/7.0-jnpf-database` 仓的 `PostgreSQL/JNPF-PostgreSQL.sql`(经 git-mirror 取)。 +脚手架已带 `docs/ddl/base_ddl_raw.sql` 与对齐后的 `db/schema.sql`(12 表:8 `base_*` + 4 业务)。 + +--- + +## 4. 架构 + +``` +ssw-platform/ +├── Cargo.toml # workspace 根(members=["src/backend"]);release profile 在此 +├── src/ +│ ├── backend/ +│ │ ├── Cargo.toml +│ │ ├── src/ +│ │ │ ├── main.rs # 启动装配 +│ │ │ ├── lib.rs # pub mod platform / modules / routes +│ │ │ ├── platform/ # 【平台层】契约实现,加业务模块一个字都不改 +│ │ │ │ ├── cipher.rs # md5→AES-256-ECB(key=md5("EY8WePvjM5GGwQzn") 的 32 ASCII 字节)→hex +│ │ │ │ ├── envelope.rs# ActionResult{code,msg,data} +│ │ │ │ ├── auth.rs # 登录 / CurrentUser / 登录守卫(面 A/面 B 共用) +│ │ │ │ ├── jnpf.rs # 【面 B】官方形状:判别头 / PcUserVO / PageListVO / 点权限守卫 +│ │ │ │ ├── permission.rs # 四源合并 + 管理员短路 + 菜单树(全部按 f_system_id 隔离) +│ │ │ │ ├── seed.rs # ensureBase(含 ensure_systems)+ firstSeed +│ │ │ │ ├── system.rs # 【多应用】App-Code 头 → SystemRef{id,code};base_system 注册表 +│ │ │ │ ├── sys.rs # 5 组 base_* 显式 handler +│ │ │ │ ├── crud.rs # spec 驱动通用 CRUD 引擎(不含业务表名/app_code) +│ │ │ │ ├── test_support.rs # 测试用**进程级共享** pglite(pglite 每进程只能开一次) +│ │ │ │ └── ...(config/db/ids/session/state/entity/menu/guard/mod) +│ │ │ ├── modules/ # 【业务层】加业务模块只改这里 +│ │ │ │ ├── mod.rs # ALL_SPECS / ALL_MENUS / ALL_ROUTES / router() 汇总 +│ │ │ │ ├── demo.rs / shop.rs / books.rs # 模板模块(不进生产) +│ │ │ │ ├── asset.rs # 🔴 真实业务:DataResource(数据资源,本体对齐) +│ │ │ │ └── .rs # 尚数网业务模块(Phase 3 起) +│ │ │ ├── routes.rs # 路由装配(平台 27 条 + 面 B 14 条 + merge 业务路由) +│ │ │ └── bootstrap.rs # 【装配根】唯一同时认识两层;把业务菜单注入种子 +│ │ ├── db/schema.sql # 完整 DDL(base_* 8 + 业务 N) +│ │ └── data/ # 运行期数据(gitignore) +│ └── frontend/ # 本期暂不动;沿用 Java 版前端/移动端 +├── scripts/ # 六道闸门 + cipher 自证(见 §6) +└── docs/ # contract / runbook / decisions / known-limitations / ddl +``` + +**核心不变量**: +- **平台层 / 业务层分离**:加业务模块只碰 `src/modules/`(新文件 + `mod.rs` 登记),平台层一个字不改。 + 两层唯一接头点是 `bootstrap.rs`。 +- **双面契约同一进程**:面 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`)。两套数据源不同,别混。 + +### 4.1 多应用(app)模型 —— 本期 MVP + +- **当前应用由 `App-Code` 请求头选定**(官方 JNPF 做法): + `system::app_code_of(&headers)` → `resolve_system(&db, app_code)` → `SystemRef { id, code }`。 + 头缺失 / 未知应用 / 查库失败 **一律回落主系统**(绝不 panic,也不 500)。 +- **注册表 = `base_system`**:`f_en_code` 存 App-Code,`f_id` 即 systemId,`f_full_name` 是显示名,`f_is_main` 标记主系统。 + 列定义与官方 `database/PostgreSQL/JNPF-PostgreSQL.sql:4243` **逐字一致**(24 列)。 + 种子(`ensure_systems`,幂等):主系统 `mainSystem`(= 官方 `JnpfConst.MAIN_SYSTEM_CODE`,`f_is_main=1`;5 条内置菜单 + 全部业务菜单)+ `app-b`(**故意无菜单**,专门用来验证隔离)。 +- **隔离口径**:所有菜单 / 授权查询都带 `f_system_id` + (`build_menu_list` / `load_menus` / `has_module` / `has_en_code_permission`)。 + `MenuSpec.system_en_code` 声明菜单归属哪个应用,种子经 `system_id_of()` 解析成 `f_system_id` 落库。 +- **`CurrentUser` / `userInfo` 的系统字段**(`currentSystemId` / `systemId` / `systemCode`)由 `App-Code` 解析,**不再硬编码**;面 A、面 B 同一口径。 +- 🔴 **多应用 ≠ 多租户**:应用(app:`base_system` + `f_system_id`)是「同一租户下的多个子系统」; + 租户(`f_tenant_id`)是数据隔离维度,本期仍固定 `'0'`(§2.2)。 +- 本期**不做**:`SystemController` 增删改查端点、应用级授权包、前端跨应用切换 UI。 +- 钉住它的测试:`platform::system::tests::registry_resolution_and_menu_isolation` + (默认/未知头 → 主系统;`app-b` → 正确解析;两系统的菜单树互不可见)。 + +--- + +## 5. 契约与数据库「兼容 Java 版」策略(本期核心) + +兼容不靠"重写一套一样的东西",而靠**三件被刻意锁死、三方共用的契约**(Rust ⇄ NestJS ⇄ 官方 Java): + +1. **`base_*` 表名/列名逐字对齐官方 DDL**(含两个故意不修正的官方陷阱: + `base_role_relation` 用户 id 在 `f_object_id`;组织/岗位关系在另一张 `base_user_relation`)。 +2. **口令 cipher**:`md5(明文)` → `AES-256-ECB-PKCS7`(key = `md5("EY8WePvjM5GGwQzn")` 的 32 个 ASCII 字节)→ hex。 + 检验向量:`encryptPassword('123456')` == + `d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`。 +3. **响应信封 + 主键 + JSON 键名**:`{code,msg,data}`(业务失败也 HTTP 200);主键 36 位 UUID v4 `varchar(50)`; + JSON 键名 = 列名去 `f_` 前缀后 camelCase。 + +### 5.1 官方 DDL 行号表(`check-citations.sh` 的 CIT3 对账源) + +官方结构 DDL = `~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql` +(公司 GitLab `platform/jnpf-platform/7.0` 的 `database/PostgreSQL/`,**13227 行 / 331 张表**)。 +本仓只用到下面 8 张 + 4 张业务表;行号漂移(官方增删表)会被 CIT3 当场抓到: + +| 表 | 官方 DDL 行 | 用途 | +|---|---|---| +| `base_authorize` | 812 | 授权(角色/用户/岗位 × 菜单/按钮) | +| `base_module` | 2209 | 菜单/模块(`f_system_id` 多应用隔离就在这张表) | +| `base_organize` | 3178 | 组织机构树 | +| `base_role` | 3686 | 角色 | +| `base_role_relation` | 3729 | 角色—用户关系(**用户 id 在 `f_object_id`**) | +| `base_system` | 4243 | 系统应用(多应用注册表,24 列,`f_is_main` 标主系统) | +| `base_user` | 4479 | 用户 | +| `base_user_relation` | 4707 | 用户—组织/岗位关系 | + +由此得到三条兼容通道: + +- **数据库兼容**:Rust 后端读写与 Java 版**同一套 `base_*` 表**(同连一个 PG,或 `pg_dump --data-only` 迁移)。列名差一个字符就导不进 —— 所以严禁自创表名/列名。 +- **前端/移动端兼容**:Java 前端发官方形状请求(带 `Vue-Version: 3`)→ 命中**面 B** → 返回官方 `PageListVO`/`PcUserVO` 等形状 → 前端零改。 +- **鉴权兼容**:内部账号密码登录链路(同一把 cipher)→ Java 前端登录/CurrentUser 直连 Rust 后端。 + +🔴 **面 B 未登录返 `code=602`**(不是 600):官方前端只对 `601`/`602` 清 token,返 600 会卡死不跳登录页。面 A 仍是 600(冻结)。 + +--- + +## 6. 验收闸门(六道,缺一不可) + +| 类别 | 脚本 | 测什么 | 当前状态 | +|---|---|---|---| +| 静态 | `scripts/check-module.sh` | 业务模块 10 接触点齐不齐(**本仓后端-only ⇒ 前端 4 处打 `⏭`,仍计入条数**) | 114/114 已绿 | +| 静态 | `scripts/check-boundary.sh` | 分层红线 CP1–CP6(平台层不许有业务知识) | 已绿(11/11) | +| 静态 | `scripts/check-contract.sh` | 契约端点表 ↔ 代码真实路由(CC2–CC10,含官方端点台账 CC10) | 已绿(10/10) | +| 静态 | `scripts/check-citations.sh` | 文档引文 `路径:行号` 逐条核对 | 4/4 已绿(192 条引文全解析;CIT3 依赖官方 DDL,缺失则 `⏭`) | +| 契约尺子·面 A | `scripts/perm-smoke.sh` | 43 条(面 A 契约闭环 32 + 真实业务模块 asset 9 + 多应用 `App-Code` 路由 2) | 已绿 | +| 契约尺子·面 B | `scripts/perm-smoke-jnpf.sh` | 23 条(官方形状 18 + 多应用 `App-Code` 路由 1 + 用户 CRUD 4,诚实记 SKIP) | **23/23 已绿** | + +🔴 期望值只有一处:`docs/contract.md` 附录 A(机器可读 `[ENDPOINT]` / `[OFFICIAL]` 等),由 `scripts/contract_expect.py` 解析。 +每把尺子结尾比对「实际断言数 vs 契约登记数」,对不上即失败 —— 尺子不会被悄悄改弱。 +**加任何业务模块 / 改任何契约,六道闸门必须全绿才算完成。** + +cipher 自证(免 node):`./target/release/ssw-platform --enc 123456`。 + +--- + +## 7. 红线(摘要;细则见脚手架文档) + +1. **契约优先于实现**:端点路径/入参/返回形状/错误码与官方/脚手架逐字一致;不确定先读源码,不凭印象。 +2. **业务失败一律 HTTP 200 + `{code,msg,data}`**;唯一例外:未知路由 HTTP 404(body 仍是信封)。**鉴权失败也是 200**(`600`/`403`)。 +3. **`base_*` 表名/列名逐字对齐官方 DDL**,严禁自创(迁移靠 `--data-only`,差一字导不进)。 +4. **四源权限合并 + 管理员短路 + 未映射放行**:管理员在 SQL 前短路;权限 = 直授+角色+组织+岗位;菜单未映射到 `base_module` ⇒ 放行(静默,必须有测试钉住)。 +5. **口令不得外泄**:库内存 `md5(明文)`;响应手工挑字段(去 `password`);密文只在请求体出现。 +6. **平台层 / 业务层分离**:加模块只碰业务层;接线只在 `bootstrap.rs`。由 `check-boundary.sh` 钉死。 +7. **判别头 `Vue-Version: 3`**:本仓前端禁止发该头(发了面 A 误判成面 B);面 B 必带。 +8. **两套权限判据并存别混**:面 A 按菜单路径,面 B 按 `f_en_code`;同一用户两面可能一通一拒,不是 bug。 +9. **暂缓项不偷跑**:tenant / SSO / 微服务 / 低代码 不在本期(§2.2)。 +10. **同一文件多 Edit 必须串行 + 改完 grep 复核**。 + +--- + +## 8. 实施路线图 + +| 阶段 | 目标 | 出口判据 | +|---|---|---| +| **Phase 0 — 实例化** | 把脚手架本体(非技能噪音)rsync 进本仓库根的 `src/` + `scripts/` + `Cargo.toml` + `.env.example` + `.gitignore`;`cp .env.example .env` | 目录齐、可 `./run.sh install` | +| **Phase 1 — 基线门** | 编译 + 跑通六道闸门(默认全绿) | ✅ 已过:`cargo test` 221(lib 98 + 集成 123)、check-module 114/114、check-boundary 11/11、check-contract 10/10、check-citations 4/4、perm-smoke 43/43、perm-smoke-jnpf 23/23 | +| **Phase 1.5 — 多应用 MVP** | `base_system` 注册表 + `App-Code` 路由 + `f_system_id` 隔离(§4.1) | ✅ 已落地:`registry_resolution_and_menu_isolation` 绿;`app-b` 与主系统菜单互不可见 | +| **Phase 2 — 兼容验证** | 用尚数网 Java 前端/移动端实连面 B,跑登录/`CurrentUser`/用户/角色/机构/菜单/授权闭环;与 Java 版做一次面 B diff | Java 前端可登录、菜单/授权行为一致 | +| **Phase 3 — 业务模块** | 按 `HOWTO_MODULE.md` 加尚数网业务模块(只碰 `modules/`) | ✅ 首个已落地:`asset/DataResource`(数据资源,字段对齐公司本体);每模块 check-module + 六闸门全绿 | +| **Phase 4 —(后续)** | 按需补文件/消息/AI;评估 SSO/租户/微服务;稳定后切真实 PG | 按业务优先级排期 | + +Phase 0 复制清单(**不要** `cp -R` 整个技能目录,会灌入技能噪音): +```bash +SKILL=~/Desktop/workspace/skills/ssw-jnpf-lite-rust +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 "$SKILL"/README.md \ + "$SKILL"/HOWTO_MODULE.md "$SKILL"/PERMISSION.md "$SKILL"/MIGRATION.md \ + "$SKILL"/JNPF_COMPAT_SURFACE.md "$SKILL"/JNPF_SOURCE_AUDIT.md \ + "$SKILL"/docs "$PWD"/ +cp .env.example .env && ./run.sh install && ./run.sh dev +``` + +--- + +## 9. 命令速查 + +```bash +cargo build --release # 编译(workspace 根) +cargo test # 单测 +bash run.sh dev # 起后端(30010) + 前端(5173) +bash scripts/perm-smoke.sh # 面 A 43 条 +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 接触点 +./target/release/ssw-platform --enc 123456 # cipher 自证 +``` + +> 本机 curl 走系统代理,测 localhost 必须加 `--noproxy '*'`。 + +--- + +## 10. 待确认决策(开工前或 Phase 2 前定) + +1. ~~**命名**~~ ✅ **已定**:项目 / crate / bin 一律 `ssw-platform`(`Cargo.toml` + 命令速查已改;脚本里的 `ssw-jnpf-lite-rust` 只剩「脚手架参照物」语义)。 +2. **数据库形态**:MVP 用 pglite-rs 进程内(零服务);稳定期是否切真实 PostgreSQL?数据迁移/双写路径? +3. **Java 版实际契约差异**:拿尚数网 Java 版实跑一次面 B diff,确认 `18/18` 是否覆盖 Java 前端**全部必需**端点(mirror 只有上游 JNPF,缺公司 fork 定制)。若有缺口,记 `partial`/`absent` 排期补。 +4. **首批业务模块**:尚数网首批要落哪些业务模块?(demo/shop/books 仅作模板,不进生产) +5. **文件/预览依赖**:Java 前端是否依赖 `jnpf-file` 的文件上传/预览?若依赖,Phase 2 需先补最小文件面 B。 +6. **官方源码位置(`check-citations` 的前置)**:引文校验要读官方源码,默认根 = `~/Desktop/workspace/jnpf`。 + 已就位:`jnpf-java-boot` / `jnpf-web-apps-main` / `jnpf-common`(均从内网 Gitea 浅克隆)。 + **缺**:`jnpf-database`(Gitea 上该 mirror 已 404)⇒ CIT3「DDL 行号表」只能 `⏭`。 + 拿到 `PostgreSQL/JNPF-PostgreSQL.sql` 后放进 `~/Desktop/workspace/jnpf/jnpf-database/` 即可转真校验。 + +--- + +## 11. 记忆约定 + +- 踩坑与长 traceback → `docs/<子系统>/.md`。 +- 工作日志 → `.workbuddy/memory/YYYY-MM-DD.md`。 +- 本文件只留「原则 + 决定 + 一句话摘要」;改代码后回头核对是否还成立。 diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..32db508 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,1448 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "aes" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0" +dependencies = [ + "cfg-if", + "cipher", + "cpufeatures 0.2.17", +] + +[[package]] +name = "android_system_properties" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc" +dependencies = [ + "libc", +] + +[[package]] +name = "atomic-waker" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0" + +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + +[[package]] +name = "axum" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90" +dependencies = [ + "axum-core", + "bytes", + "form_urlencoded", + "futures-util", + "http", + "http-body", + "http-body-util", + "hyper", + "hyper-util", + "itoa", + "matchit", + "memchr", + "mime", + "percent-encoding", + "pin-project-lite", + "serde_core", + "serde_json", + "serde_path_to_error", + "serde_urlencoded", + "sync_wrapper", + "tokio", + "tower", + "tower-layer", + "tower-service", + "tracing", +] + +[[package]] +name = "axum-core" +version = "0.5.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "http-body-util", + "mime", + "pin-project-lite", + "sync_wrapper", + "tower-layer", + "tower-service", + "tracing", +] + +[[package]] +name = "base64" +version = "0.22.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" + +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + +[[package]] +name = "block-buffer" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa" +dependencies = [ + "hybrid-array", +] + +[[package]] +name = "block-padding" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a8894febbff9f758034a5b8e12d87918f56dfc64a8e1fe757d65e29041538d93" +dependencies = [ + "generic-array", +] + +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + +[[package]] +name = "byteorder" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" + +[[package]] +name = "bytes" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" + +[[package]] +name = "cc" +version = "1.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86e055fa6e3e40ad6187ba25b6855eeb635d5271f8e0f0e1e9a5826b8d75bea0" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "chacha20" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06" +dependencies = [ + "cfg-if", + "cpufeatures 0.3.1", + "rand_core 0.10.1", +] + +[[package]] +name = "chrono" +version = "0.4.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327" +dependencies = [ + "iana-time-zone", + "js-sys", + "num-traits", + "wasm-bindgen", + "windows-link", +] + +[[package]] +name = "cipher" +version = "0.4.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad" +dependencies = [ + "crypto-common 0.1.7", + "inout", +] + +[[package]] +name = "cmov" +version = "0.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a" + +[[package]] +name = "const-oid" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c" + +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + +[[package]] +name = "cpufeatures" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +dependencies = [ + "libc", +] + +[[package]] +name = "cpufeatures" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566" +dependencies = [ + "libc", +] + +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "typenum", +] + +[[package]] +name = "crypto-common" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453" +dependencies = [ + "hybrid-array", +] + +[[package]] +name = "ctutils" +version = "0.4.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2376ffd6f96d8a9db59875b4b6b0237d6900b5baf64279714e05493ce64828a" +dependencies = [ + "cmov", +] + +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer 0.10.4", + "crypto-common 0.1.7", +] + +[[package]] +name = "digest" +version = "0.11.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2" +dependencies = [ + "block-buffer 0.12.1", + "const-oid", + "crypto-common 0.2.2", + "ctutils", +] + +[[package]] +name = "ecb" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a8bfa975b1aec2145850fcaa1c6fe269a16578c44705a532ae3edc92b8881c7" +dependencies = [ + "cipher", +] + +[[package]] +name = "errno" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "fallible-iterator" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4443176a9f2c162692bd3d352d745ef9413eec5782a80d8fd6f8a1ac692a07f7" + +[[package]] +name = "filetime" +version = "0.2.29" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c287a33c7f0a620c38e641e7f60827713987b3c0f26e8ddc9462cc69cf75759" +dependencies = [ + "cfg-if", + "libc", +] + +[[package]] +name = "find-msvc-tools" +version = "0.1.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48" + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "futures" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3" +dependencies = [ + "futures-channel", + "futures-core", + "futures-executor", + "futures-io", + "futures-sink", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-channel" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4" +dependencies = [ + "futures-core", + "futures-sink", +] + +[[package]] +name = "futures-core" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" + +[[package]] +name = "futures-executor" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432" +dependencies = [ + "futures-core", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-io" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed" + +[[package]] +name = "futures-macro" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "futures-sink" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d" + +[[package]] +name = "futures-task" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" + +[[package]] +name = "futures-util" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" +dependencies = [ + "futures-channel", + "futures-core", + "futures-io", + "futures-macro", + "futures-sink", + "futures-task", + "memchr", + "pin-project-lite", + "slab", +] + +[[package]] +name = "generic-array" +version = "0.14.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" +dependencies = [ + "typenum", + "version_check", +] + +[[package]] +name = "getrandom" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0" +dependencies = [ + "cfg-if", + "libc", + "wasi", +] + +[[package]] +name = "getrandom" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099" +dependencies = [ + "cfg-if", + "libc", + "r-efi", + "rand_core 0.10.1", +] + +[[package]] +name = "hex" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" + +[[package]] +name = "hmac" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f" +dependencies = [ + "digest 0.11.3", +] + +[[package]] +name = "http" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0" +dependencies = [ + "bytes", + "itoa", +] + +[[package]] +name = "http-body" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c" +dependencies = [ + "bytes", + "http", +] + +[[package]] +name = "http-body-util" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "pin-project-lite", +] + +[[package]] +name = "httparse" +version = "1.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87" + +[[package]] +name = "httpdate" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9" + +[[package]] +name = "hybrid-array" +version = "0.4.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "27f864f10dfb56725ce5ce5472bc52252c8f93a4ab86327122cebf62c5f59a17" +dependencies = [ + "typenum", +] + +[[package]] +name = "hyper" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c" +dependencies = [ + "atomic-waker", + "bytes", + "futures-core", + "http", + "http-body", + "httparse", + "httpdate", + "itoa", + "pin-project-lite", + "smallvec", + "tokio", +] + +[[package]] +name = "hyper-util" +version = "0.1.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ddc03d96684f9226b8a787cdb71488417b53ab5ea8fdb1dac946cb9431cc8bff" +dependencies = [ + "bytes", + "http", + "http-body", + "hyper", + "pin-project-lite", + "tokio", + "tower-service", +] + +[[package]] +name = "iana-time-zone" +version = "0.1.65" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "log", + "wasm-bindgen", + "windows-core", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + +[[package]] +name = "inout" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01" +dependencies = [ + "block-padding", + "generic-array", +] + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "js-sys" +version = "0.3.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a" +dependencies = [ + "cfg-if", + "futures-util", + "wasm-bindgen", +] + +[[package]] +name = "libc" +version = "0.2.191" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" + +[[package]] +name = "linux-raw-sys" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" + +[[package]] +name = "lock_api" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965" +dependencies = [ + "scopeguard", +] + +[[package]] +name = "log" +version = "0.4.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6" + +[[package]] +name = "matchit" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3" + +[[package]] +name = "md-5" +version = "0.10.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf" +dependencies = [ + "cfg-if", + "digest 0.10.7", +] + +[[package]] +name = "md-5" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69b6441f590336821bb897fb28fc622898ccceb1d6cea3fde5ea86b090c4de98" +dependencies = [ + "cfg-if", + "digest 0.11.3", +] + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "mime" +version = "0.3.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a" + +[[package]] +name = "mio" +version = "1.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee" +dependencies = [ + "libc", + "wasi", + "windows-sys", +] + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "parking_lot" +version = "0.12.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a" +dependencies = [ + "lock_api", + "parking_lot_core", +] + +[[package]] +name = "parking_lot_core" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall", + "smallvec", + "windows-link", +] + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "pglite-rs" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce51c5797f88bf0e5f11764118d5392bef6aae38b668947e3b9dcc0dcd42f047" +dependencies = [ + "bytes", + "fallible-iterator", + "futures", + "libc", + "pglite-rs-sys", + "postgres-protocol", + "postgres-types", + "ruzstd", + "tar", + "thiserror", +] + +[[package]] +name = "pglite-rs-lib-aarch64-apple-darwin" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ba22160e74de33d75cb1209da1fbb5816afd3506a9b47df2c81f54066f6bd97" + +[[package]] +name = "pglite-rs-lib-aarch64-unknown-linux-gnu" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d2b934381ed7bbde6400034ec7294cb68ec46fb745b478b38de3913328126f" + +[[package]] +name = "pglite-rs-lib-x86_64-apple-darwin" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "71a8da533f2f9a82700af976acb573495be5bbdedeef90d1133d882c45128e61" + +[[package]] +name = "pglite-rs-lib-x86_64-pc-windows-gnu" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c84ae5eed7dd28f5d9069b62ddd68ff0ea2ee65b989cfb4e9dea227a5dee2896" + +[[package]] +name = "pglite-rs-lib-x86_64-unknown-linux-gnu" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32f15e7c780aba8873afdb1db6b1cd741f2f03ece5a7996cb83f7d7814e64606" + +[[package]] +name = "pglite-rs-sys" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e8c85cdc379a58bef741624ce9c98786818c1decc5c13bd3691a32d125a59d3" +dependencies = [ + "libc", + "pglite-rs-lib-aarch64-apple-darwin", + "pglite-rs-lib-aarch64-unknown-linux-gnu", + "pglite-rs-lib-x86_64-apple-darwin", + "pglite-rs-lib-x86_64-pc-windows-gnu", + "pglite-rs-lib-x86_64-unknown-linux-gnu", + "ruzstd", +] + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "postgres-protocol" +version = "0.6.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08808e3c483c46e999108051c78334f473d5adb59d78bb80a1268c7e6aa6c514" +dependencies = [ + "base64", + "byteorder", + "bytes", + "fallible-iterator", + "hmac", + "md-5 0.11.0", + "memchr", + "rand 0.10.3", + "sha2", + "stringprep", +] + +[[package]] +name = "postgres-types" +version = "0.2.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "851ca9db4932932d69f3ea811b1abe63087a0f740a47692619dd40d4899b68be" +dependencies = [ + "bytes", + "fallible-iterator", + "postgres-protocol", +] + +[[package]] +name = "ppv-lite86" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9" +dependencies = [ + "zerocopy", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" + +[[package]] +name = "rand" +version = "0.8.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e058c7de0b26af77780c769414d6257830bb240f3c38477dbc2c16e5f54d6d4c" +dependencies = [ + "libc", + "rand_chacha", + "rand_core 0.6.4", +] + +[[package]] +name = "rand" +version = "0.10.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65c9fb96cbc91e3478eaae79a69fcd3f1ae4ad052e471fe6732fff548984b4af" +dependencies = [ + "chacha20", + "getrandom 0.4.3", + "rand_core 0.10.1", +] + +[[package]] +name = "rand_chacha" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88" +dependencies = [ + "ppv-lite86", + "rand_core 0.6.4", +] + +[[package]] +name = "rand_core" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c" +dependencies = [ + "getrandom 0.2.17", +] + +[[package]] +name = "rand_core" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69" + +[[package]] +name = "redox_syscall" +version = "0.5.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d" +dependencies = [ + "bitflags", +] + +[[package]] +name = "rustix" +version = "1.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5e76742e5294153d4dde1207dbec5bdd81eef6fabdc0d2118babadabfd858aa" +dependencies = [ + "bitflags", + "errno", + "libc", + "linux-raw-sys", + "windows-sys", +] + +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "ruzstd" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7c1c839d570d835527c9a5e4db7cb2198683a988cb9d7293fc8674e6bd58fc8" +dependencies = [ + "twox-hash", +] + +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "scopeguard" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_path_to_error" +version = "0.1.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457" +dependencies = [ + "itoa", + "serde", + "serde_core", +] + +[[package]] +name = "serde_urlencoded" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd" +dependencies = [ + "form_urlencoded", + "itoa", + "ryu", + "serde", +] + +[[package]] +name = "sha2" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d7069beb7d6ac7b9acd1039986e73443f24234f41074da099d6f994ac9ad19" +dependencies = [ + "cfg-if", + "cpufeatures 0.3.1", + "digest 0.11.3", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "signal-hook-registry" +version = "1.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b" +dependencies = [ + "errno", + "libc", +] + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "smallvec" +version = "1.16.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0d5d4b1981b8bbbb7aed204cae5726d683d5d6ac7e74ec54122ea28f315e7c8" + +[[package]] +name = "socket2" +version = "0.6.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "ssw-platform" +version = "0.1.0" +dependencies = [ + "aes", + "axum", + "chrono", + "ecb", + "hex", + "md-5 0.10.6", + "pglite-rs", + "rand 0.8.8", + "serde", + "serde_json", + "serde_urlencoded", + "tokio", + "uuid", +] + +[[package]] +name = "stringprep" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7b4df3d392d81bd458a8a621b8bffbd2302a12ffe288a9d931670948749463b1" +dependencies = [ + "unicode-bidi", + "unicode-normalization", + "unicode-properties", +] + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "sync_wrapper" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263" + +[[package]] +name = "tar" +version = "0.4.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f6221d9a6003c78398e3b239969f352578258df48c8eb051caadae0015bc840" +dependencies = [ + "filetime", + "libc", + "xattr", +] + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "tinyvec" +version = "1.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee" + +[[package]] +name = "tokio" +version = "1.54.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b52fd3255258d26fac7264ab5a76b53c13367136dc011d3d6ad4f8ed070396a3" +dependencies = [ + "bytes", + "libc", + "mio", + "parking_lot", + "pin-project-lite", + "signal-hook-registry", + "socket2", + "tokio-macros", + "windows-sys", +] + +[[package]] +name = "tokio-macros" +version = "2.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "tower" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4" +dependencies = [ + "futures-core", + "futures-util", + "pin-project-lite", + "sync_wrapper", + "tokio", + "tower-layer", + "tower-service", + "tracing", +] + +[[package]] +name = "tower-layer" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e" + +[[package]] +name = "tower-service" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3" + +[[package]] +name = "tracing" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" +dependencies = [ + "log", + "pin-project-lite", + "tracing-core", +] + +[[package]] +name = "tracing-core" +version = "0.1.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a" +dependencies = [ + "once_cell", +] + +[[package]] +name = "twox-hash" +version = "2.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86a801b3cea342a06d468c8710662aa29e5e05e4f5c0d62f00bbb7f2ad7941c2" + +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + +[[package]] +name = "unicode-bidi" +version = "0.3.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "unicode-normalization" +version = "0.1.26" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "75cd3fb03d5288b3ba9a1ee103ac7e9cbb59f0b03d64f8ddfcc04dd42758a85d" +dependencies = [ + "tinyvec", +] + +[[package]] +name = "unicode-properties" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7df058c713841ad818f1dc5d3fd88063241cc61f49f5fbea4b951e8cf5a8d71d" + +[[package]] +name = "uuid" +version = "1.29.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4a0e2d11620c50695fe12bbbfde96b3477fe606e7284c22d505c12ce51214514" +dependencies = [ + "getrandom 0.4.3", + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "wasm-bindgen" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c" +dependencies = [ + "cfg-if", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 3.0.9", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement", + "windows-interface", + "windows-link", + "windows-result", + "windows-strings", +] + +[[package]] +name = "windows-implement" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-interface" +version = "0.59.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "xattr" +version = "1.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "963d6fab92d5504b971dc8bd90ca743c2575e590bc8071ea5bc571598667ae08" +dependencies = [ + "libc", + "rustix", +] + +[[package]] +name = "zerocopy" +version = "0.8.63" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8" +dependencies = [ + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.8.63" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..6890ed4 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,54 @@ +# ssw-platform —— cargo workspace 根 +# +# 🔴 **本文件是脚手架的一部分,复制到项目根时必须一起带上** +# +# 为什么必须有它:`src/backend/Cargo.toml` 里的 +# `version.workspace = true` / `edition.workspace = true` / `xxx = { workspace = true }` +# 都要求**上层有一个 workspace 根**。缺了它,cargo 直接报 +# `error: could not find Cargo.toml in ... or any parent directory`, +# 脚手架**根本编译不起来**。 +# +# 这里只放「跨成员共享」的配置:成员列表、依赖版本、release profile。 +# 成员 crate(src/backend)不得再写 [profile.*],否则 cargo 直接报错。 + +[workspace] +members = ["src/backend"] +resolver = "2" + +[workspace.package] +version = "0.1.0" +edition = "2021" +# pglite-rs 0.2.7 要求 Rust ≥ 1.85(edition 2024 家族)。本机实测 rustc 1.95.0。 +rust-version = "1.85" + +# 依赖版本集中在此,成员 crate 一律用 `xxx = { workspace = true }` 继承。 +# +# ⚠️ 版本锁死说明(不要随意升级): +# - aes 0.8 + ecb 0.1 属于 cipher **0.4** 家族;aes 0.9 / ecb 0.2 是 cipher 0.5, +# 泛型不通用,混用编译不过。 +# - md-5 0.10 的 crate 名是 `md5`(`use md5::{Digest, Md5};`)。 +# - pglite-rs 0.2 的 **lib 名是 `pglite`**(`use pglite::PGlite;`), +# 且 0.2.7 没有 `memory://` 模式,`PGlite::open()` 只接受路径。 +[workspace.dependencies] +axum = "0.8" +tokio = { version = "1", features = ["full"] } +serde = { version = "1", features = ["derive"] } +serde_json = "1" +serde_urlencoded = "0.7" +aes = "0.8" +ecb = "0.1" +md-5 = "0.10" +rand = "0.8" +uuid = { version = "1", features = ["v4"] } +hex = "0.4" +pglite-rs = "0.2" +chrono = "0.4" + +[profile.release] +opt-level = 2 +lto = "thin" +strip = "symbols" +# 🔴 不要设 `panic = "abort"`:契约 §6.5 要求 panic ⇒ HTTP 200 + code=400, +# 而 abort 下 `catch_unwind` 抓不到 panic(进程直接死 ⇒ 客户端连接重置)。 +# catch-all 中间件依赖默认的 `panic = "unwind"`(Ruling P19)。 +codegen-units = 16 diff --git a/HANDOFF.md b/HANDOFF.md new file mode 100644 index 0000000..53c40e5 --- /dev/null +++ b/HANDOFF.md @@ -0,0 +1,137 @@ +# HANDOFF —— 交给下一个 session 的现场交接 + +> 更新于 2026-10-30 21:30。**开工先读这一页**,再读 `CLAUDE.md`(硬约定), +> 最后看 `.workbuddy/memory/` 最近一天的日志(踩过的坑)。 +> 无人值守时不要问用户,选最保守可行的方案继续,并把决策写回本文件。 + +--- + +## 1. 一句话现状 + +Rust 后端(axum + pglite)已能跑,**面 A**(ssw/react 形状)与**面 B**(官方 JNPF 形状, +`Vue-Version: 3`)双契约并存;面 B 的 `Users` 一族 9 条已实现。前端 monorepo 依赖正在安装, +**页面还没渲染过一次**——这是当前最大的未知风险。 + +--- + +## 2. 运行中的现场(断了就按这里重启) + +### 后端(端口 30000) + +```bash +cd ~/Desktop/workspace/ssw-platform +RUSTC_WRAPPER=sccache cargo build --manifest-path src/backend/Cargo.toml # 改代码后 +PORT=30000 ./target/debug/ssw-platform & # 后台起 +curl -s http://127.0.0.1:30000/api/health # 期望 {"ok":true,"tables":12,...} +``` + +拿 token(面 B): + +```bash +ENC=$(./target/debug/ssw-platform --enc 123456) +curl -s -X POST http://127.0.0.1:30000/api/oauth/Login \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -H 'Vue-Version: 3' -H 'App-Code: mainSystem' \ + --data-urlencode account=admin --data-urlencode "password=$ENC" +# → data.token(lite- 前缀)。Authorization 头是**裸 token,没有 bearer 前缀** +``` + +### 前端(`~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework`) + +🔴 **这个目录在项目工作区之外,跑 pnpm 必须退出沙箱**(否则每个文件操作被 broker 拦一遍, +0.15 包/s,末尾还会 `ERR_PNPM_CODEBUDDY_BROKER_DENY`)。cargo/文本读写不受影响。 + +```bash +cd ~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework +pnpm install --prefer-offline --reporter=append-only # 断了就续装(缓存命中率很高) +pnpm -r run stub --if-present # 用 --ignore-scripts 装过 ⇒ 必须补 +pnpm dev:main # vite, 3000, /dev → 30000 +``` + +- 成功标志:`node_modules/.modules.yaml` 存在 + 2169 个包 `added` +- 打开 `http://localhost:3000/`(根路径 App-Code 为空 ⇒ 后端回退主系统,已支持) +- 登录:`admin` / `123456`(登录框会自己加密,无需手填密文) + +--- + +## 3. 待办(按优先级,做完一条划一条) + +### P0 —— 用户管理页剩余接口(`scripts/probe-page.py` 实测的 8 条缺路由) + +| 端点 | 备注 | +|---|---| +| `GET /api/permission/Group` | 左侧用户分组树;**需要新表 `base_user_group`** | +| `GET|POST|PUT|DELETE /api/permission/Group/{id}` | 分组 CRUD | +| `POST /api/permission/Group/{id}/Actions/AddUser` / `DeleteUser` | 分组加/移成员 | +| `POST /api/permission/Users/{id}/SetPosition` + `POST /api/permission/Users/SetPositionBatch` | 设岗位(后者当前 405 ⇒ 同路径要补 POST) | +| `GET /api/permission/Users/{id}/SelectorByUserPosId` | 按岗位选人 | +| `GET /api/system/System/getDevUser` | 开发账号下拉 | +| `DELETE /api/permission/socials/{id}` | 第三方账号解绑 | +| `POST /api/permission/Users/workHandover` | 离职交接(写接口,探针默认跳过) | + +### P1 —— 让页面真跑起来(比补接口更重要,先验证再补) + +1. 装完依赖 → `pnpm -r run stub` → `pnpm dev:main` +2. `aix snapshot` 拿 `@eN` 再点,别猜 selector(见 `~/.agents/skills/aix/SKILL.md`) +3. 登录后进「用户管理」,逐个修控制台/网络的 4xx、5xx +4. 把「页面能渲染 + 列表有数据」做成可复现步骤,写回本文件 + +### P2 —— 机构管理 `Organize` CRUD + `Selector` + +几乎所有权限页面的公共前置。参照 `platform/sys.rs` 里面 A 的 `org_*` 实现。 + +### P3 —— 菜单管理 / 角色授权(时间够再做) + +--- + +## 4. 每批实现的固定动作(缺一不可) + +```bash +cd ~/Desktop/workspace/ssw-platform +# 1) 实现 → 编译 +RUSTC_WRAPPER=sccache cargo build --manifest-path src/backend/Cargo.toml +# 2) 重启后端(老进程先 kill) +PORT=30000 ./target/debug/ssw-platform & +# 3) 运行时验证(比静态比对权威) +python3 scripts/probe-page.py docs/fe/page-user.tsv +# 4) 单测 + 六闸 +RUSTC_WRAPPER=sccache cargo test --manifest-path src/backend/Cargo.toml +for s in check-module check-boundary check-contract check-citations; do bash scripts/$s.sh; done +bash scripts/perm-smoke.sh +ENC_BIN="$PWD/target/debug/ssw-platform" bash scripts/perm-smoke-jnpf.sh +``` + +新增/变更端点必须同步三处,否则闸门必红: + +1. `docs/contract.md` 的 `[ENDPOINT]`(面 B 行首列写 `B`)与 `[OFFICIAL]`(`absent → implemented`) +2. `docs/contract.md` 的 `[FACE]` 计数 + `[RULER]` 里 `perm-smoke-jnpf.sh` 的断言数 +3. `src/backend/src/routes.rs` 测试里的 `JNPF_REGISTERED`(按**路径**列,同路径多方法算一条) + +--- + +## 5. 必踩的坑(都已踩过一次,别再踩) + +- 🔴 **一条 `.route()` 只挂一个方法**:`check-contract-scan.py` 只解析每个 `.route()` 的第一个方法, + `get(a).post(b)` 会被判成「契约写 POST、代码是 GET」。同路径多次 `.route()` 在 axum 里是合并,不冲突。 +- 🔴 **驼峰 ≠ 下划线机械转换**:`ranks` ↔ `f_rank`、`certificatesType` ↔ `f_certificates_type`。 + 列名只来自白名单常量(如 `USER_WRITE_FIELDS`),别用 `snake_case()` 猜。 +- 🔴 `f_creator_time` 写 SQL `now()` 时**不占参数位**:`marks.push("now()")` 而非 `placeholder()`, + 否则 `$n` 序号和 `columns` 错位(报 `column is of type timestamp but expression is of type text`)。 +- 🔴 写路径只 `SET` **body 里出现过的键**,未出现的列必须保持原值(有断言钉住)。 +- 🔴 读回**不选** `f_password` / `f_secretkey`(有断言钉住「详情无 password 键」)。 +- 🔴 `{id}` 会吞掉 `Users/` 下未注册的静态 GET 子路径;matchit 静态段优先,所以那些路由 + **一旦注册就自动优先匹配**,不需要改详情。 +- 🔴 测试共用 `platform/test_support.rs` 的**单例 pglite**(进程内只能开一个实例), + 别在测试里 `open_temp`。 +- 🔴 `python` 脚本里递归取同目录 `.vue` 时用 `if seen is None:`,**不能写 `seen = seen or set()`** + (空 set 是 falsy ⇒ 每层新建 ⇒ 环形 import OOM 被 SIGKILL)。 +- 🔴 jq 里 `$d|has(a) or $d|has(b)` 会被 `|` 抢结合 ⇒ 用 `[keys[]|select(.=="a" or .=="b")]|length`。 +- 🔴 端口:前端 dev 3000,代理 `/dev` → **30000**,后端绝不能起在 3000。 + +--- + +## 6. 收工前(每一轮都要做) + +1. 追加 `.workbuddy/memory/YYYY-MM-DD.md`:结论 / 坑 / 数字(闸门通过数) +2. 更新本文件 §1 现状、§2 现场、§3 待办(划掉做完的) +3. 若还有未完成项,**确认下一次定时任务存在**(`automation_update` list 可查),没有就新建 diff --git a/HOWTO_MODULE.md b/HOWTO_MODULE.md new file mode 100644 index 0000000..3b9981d --- /dev/null +++ b/HOWTO_MODULE.md @@ -0,0 +1,432 @@ +# 加一个业务模块(AI 开发主线) + +本文件是 **Rust 版**的操作手册。参照实现 = 内置的四个模块 +(`demo/DemoItem` · `shop/Product` · `books/Book` · **`asset/DataResource`(真实业务)**) +——**照抄一个最接近的,别从零想**;要加真实业务模块就抄 `asset.rs`。 + +> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改哪儿、怎么验证」。** + +## 〇.5、一图看完全流程(先看一遍再动) + +``` + 1. db/schema.sql 建表(f_ 前缀 + f_id VARCHAR(50) + 软删列) + 2. src/modules/.rs 【新文件】spec + *MENU + 3 个 handler + 自己的 router() + 3. src/modules/mod.rs 加 spec 进 ALL_SPECS + 加菜单进 ALL_MENUS + 加 router() 进 merge + 加路由进 ALL_ROUTES + 4. frontend/src/api/.ts 3 个函数(list/save/delete) + 5. frontend/src/views/.tsx 列表页 + 6. frontend/src/App.tsx + 7. docs/contract.md 附录 A 加五行:[MODULE] 一行 + [MENU] 一行 + [ENDPOINT] 三行 + (本模块的 3 条端点)+ [FACE] 的 A 条数 +3 + ★ 期望值真源 + ⇒ bash scripts/check-module.sh 必须全 ✅ + ⇒ bash scripts/check-contract.sh 必须全 ✅(端点表 ↔ 代码) + 8. scripts/perm-smoke.sh 追加该模块的断言(别新写脚本) +``` + +**8 个文件 = 上面的 1–8**(其中 `modules/.rs` 与 `modules/mod.rs` 是**业务层**)。 +第 7 步漏了 ⇒ `check-module.sh` 直接判「契约 [MODULE] 里没有这个模块」退出 2; +`[ENDPOINT]` 漏了 ⇒ `check-contract.sh` 判「代码里的路由没被契约登记」红。 + +🔴 **平台层(`src/platform/`)与入口文件(`src/backend/src/main.rs`)一个字都不用改** —— +加业务模块**不碰平台层**。 +(对比 react 版要动 4 个后端文件;本仓**只动 `src/modules/` 下的 2 个文件** + `db/schema.sql`。) +🔴 **内置菜单也住在业务层**(`modules/.rs` 的 `*_MENU: MenuSpec`)⇒ 由装配根 +`bootstrap.rs` 注入平台层的种子 ⇒ 平台层只自带 5 条**系统**菜单。 +🔴 这条分层由尺子钉住:`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. 🔴 **入口文件也不碰**:`main.rs` 的 `BASE_TABLES` 只列 8 张 `base_*`(8 张全部逐字对齐官方 DDL,含多应用注册表 `base_system`), + 业务表由 `modules::all_specs()` 派生并与 `db/schema.sql` 双向对账 + ⇒ 加业务表**不用**改 `main.rs`。 + +🔴 **分层铁律**:后端代码分两层—— + +| 层 | 目录 | 内容 | 加模块时 | +|---|---|---|---| +| **平台层** | `src/backend/src/platform/` | 契约实现(信封 / cipher / 登录 / 权限 / `base_*` 管理 / 面 B / CRUD 引擎) | **一个字都不改** | +| **业务层** | `src/backend/src/modules/` | 业务 spec + **业务菜单** + handler + 路由 | **只改这里** | +| **装配根** | `src/backend/src/bootstrap.rs` | 唯一同时认识两层的地方 | **一个字都不改** | + +(对齐 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 crate::platform::crud::{handle_delete, handle_list, handle_save}; +use crate::platform::entity::{ColumnSpec, EntitySpec}; +use crate::platform::envelope::ActionResult; +use crate::platform::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`(**`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 crate::platform::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 表名(`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 new file mode 100644 index 0000000..6ea61fa --- /dev/null +++ b/JNPF_COMPAT_SURFACE.md @@ -0,0 +1,435 @@ +# 面 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 new file mode 100644 index 0000000..47f0512 --- /dev/null +++ b/JNPF_SOURCE_AUDIT.md @@ -0,0 +1,656 @@ +# 官方 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 new file mode 100644 index 0000000..d690803 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,312 @@ +# 迁移指南(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 | 说明 | +|---|---|---| +| `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` 子命令(推荐)** + +在 `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 new file mode 100644 index 0000000..c7c47e5 --- /dev/null +++ b/PERMISSION.md @@ -0,0 +1,182 @@ +# 权限模版(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/README.md b/README.md new file mode 100644 index 0000000..7a7e1bc --- /dev/null +++ b/README.md @@ -0,0 +1,221 @@ +# ssw-jnpf-lite-rust · Rust 全栈 MVP + +**自包含技能**:模板、契约实现、权限模版、冒烟脚本全部在技能目录内,**不依赖任何其它技能或外部服务**, +除 Node 外无需安装任何东西(数据库是**进程内原生 PostgreSQL**)。 + +来自 `ssw-jnpf-lite-react`(NestJS + React)的 **Rust 全栈 counterpart**——两者是**并列可选**的独立技能, +不是依赖关系:要 MVP 期就用 Node 栈选 `ssw-jnpf-lite-react`,要 MVP 期用 Rust 栈选本技能。 + +> 📌 **本仓 = 技能本体**(不是「技能的项目副本」):仓根就是技能目录(`SKILL.md` 在仓根), +> 三处软链 `~/.agents/skills/` · `~/.claude/skills/` · `~/.workbuddy/skills/` 均指向本仓, +> 所以**改一次仓 = 改一次技能**。 + +## 设计原则: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 / 面 B」要解决的): + +- **端点路径**——面 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)。 + +## 选型决策:Rust 版 vs react 版 vs ssw-jnpf-lite(Java) + +| | **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 团队,不打算换栈 | + +**一句话**:**MVP 期用哪种栈都行,代价是「稳定期迁 JNPF」这件事**。 +本技能把「快」放在 MVP 期(Rust),把「换栈」推迟并**锁死到有界范围**(5 件事 + 六道闸门)。 +若你**本来就要用 Java**,直接用 `ssw-jnpf-lite`(零迁移摩擦)比绕一圈更划算。 + +## 目录 + +``` +ssw-jnpf-lite-rust/ ← 仓根 = 技能根(三处软链指向这里) +├── SKILL.md # 入口:是什么 / 何时用 / 契约红线 / 六道闸门 +├── 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 指引 / 交接文档 +├── 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 # 分支级已知限制(被接受/挂起的东西) + └── ddl/ # 官方 DDL 摘录 +``` + +★ = 业务模块模板(`HOWTO_MODULE.md` 参照实现)。 + +## 快速开始 + +```bash +# 一次性:装依赖(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 # 看日志尾部 +``` + +| 端口 | 谁 | 说明 | +|---|---|---| +| `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` ⇒ 端口被占直接报错,不自动换端口 | + +> ⚠️ 本机 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 +``` + +> ⚠️ **只复制脚手架本体**——`*.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`,**脚手架编译不起来**。 + +## 验收门 + +| 门 | 命令 | 通过标准 | +|---|---|---| +| ① 编译 | `cargo build --release` | 0 error **0 warning** | +| ② 单测 | `cargo test` | 全绿(当前 **220 passed / 0 failed**) | +| ③ 冒烟(面 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 三页可用 → 退出再登录 | + +外加四道**静态闸门**(纯静态,不起后端,加业务模块后立刻跑): +`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)。 + +## 已知限制(被接受 / 挂起) + +| 限制 | 说明 | +|---|---| +| **面 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` 是契约字面量、**不强制执行** | + +## 三个参照物(各司其职,别混) + +| 参照物 | 地位 | +|---|---| +| 官方 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` | **同名** ⇒ 两版后端能开同一个库 | +| 尺子 | `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(逐字复用) diff --git a/docs/README-project.md b/docs/README-project.md new file mode 100644 index 0000000..a3268c8 --- /dev/null +++ b/docs/README-project.md @@ -0,0 +1,152 @@ +# 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)。 +- 🧾 **实施期裁决(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(已知限制) + # 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/contract.md b/docs/contract.md new file mode 100644 index 0000000..b307aa8 --- /dev/null +++ b/docs/contract.md @@ -0,0 +1,1273 @@ +# 契约规格 —— ssw-jnpf-lite-rust + +> **本文件是唯一规格来源(binding spec)。** 所有实现任务、代码评审、最终评审都以此为准。 +> 与 `HANDOFF.md` 冲突时,以本文件为准;与本文件冲突的**计划文字**由控制者裁决并记入 ledger。 +> +> 🔴 **本文件 = 面 A(ssw/react 契约)的规格,冻结不动。** +> 面 B(官方 JNPF 契约面)的规格在 **[`JNPF_COMPAT_SURFACE.md`](../JNPF_COMPAT_SURFACE.md)**(已落地 18/18), +> 两面共用同一套 `base_*` 表 / cipher / seed,但**权限判据不同**(面 A 按菜单路径、面 B 按 `f_en_code`)。 + +--- + +## 0. 术语与参照物 + +| 参照物 | 路径 | 地位 | +|---|---|---| +| 官方 JNPF DDL | `~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql` | **数据模型真源**(`base_*` 表名/列名逐字) | +| `ssw-jnpf-lite-react` | `~/Desktop/workspace/skills/ssw-jnpf-lite-react/` | **行为真源**(NestJS 版把契约跑起来了) | +| `tdc-rs` | `~/Desktop/workspace/tdc-rs/` | **工程手法参考**(只读;不共享代码/端口/数据目录) | + +--- + +## 1. 全局红线(每个任务都必须满足) + +### R1.1 契约优先于实现 +端点路径、入参、返回形状、错误码**逐字**对齐 `ssw-jnpf-lite-react`。不确定时读 react 源码,不凭印象。 + +### R1.2 业务失败一律 HTTP 200 + `{code,msg,data}` +- 成功:`code=200, msg='成功'` +- 业务失败:`code=400`,`data=null`,`msg` 透传业务提示 +- 未登录:`code=600`,`msg='未登录'` +- 无菜单权限:`code=403`,`msg='无菜单权限'` +- 未捕获异常(panic / DB 报错)⇒ 同样 **HTTP 200** + `{code:400,msg:'系统异常,请联系管理员',data:null}` + (对齐 react 的全局 `ActionResultFilter` 兜底分支:真实堆栈只进服务端日志,不外泄) +- **唯一例外**:未知路由 → **HTTP 404**,body 仍是 `{code:404,msg:'接口不存在',data:null}` + (404 是**传输层**例外,不是业务失败;同理 **405 保留 HTTP 405**,见 §6.5) + +### R1.3 `base_*` 表名/列名逐字对齐官方 DDL +不得自创表名/列名。迁移期靠 `--data-only` 导数据,列名差一个字符就导不进去。 + +### R1.4 不得用 `SELECT *` +所有 SELECT **必须显式列出列名**。原因:react 版库(TypeORM `synchronize`)只有 entity 里的列, +官方 DDL 有 30~60 列。显式投影让本仓后端**能开 react 建出来的库**,且响应 JSON 与 react 逐字相同。 + +🔴 **每列还要显式 `AS ""`**(camelCase + **双引号**,见 §4)——`row_to_json` 用**列的输出名**当 JSON 键。 +写成 `AS creator_time` 会得到 `"creator_time"`,react 是 `"creatorTime"` ⇒ 前端读不到字段。 + +🔴🔴 **别名必须加双引号**(2026-10-25 修订,Ruling P23)—— +**PostgreSQL 会把未加双引号的标识符折叠成小写**:`AS realName` 的输出列名是 `realname` +⇒ `row_to_json` 出来的键是 `"realname"`,**不是** `"realName"` ⇒ 前端读不到字段,**且静默**。 +实测:`SELECT row_to_json(q)::text FROM (SELECT 1 AS realName) q` ⇒ `{"realname":1}`; +写成 `AS "realName"` 才是 `{"realName":1}`。 +⇒ **规范写法:`f_real_name AS "realName"`、`f_price::text AS "price"`。** +(`db.rs` 另有一层键归一兜底,见 §5.4 —— 它是**安全网**,不是本规范;规范写法本身不依赖它。) + +### R1.5 numeric 列必须序列化成 JSON 字符串 +`f_price` 回显 `"9.90"`,不是 `9.9`。手段:**在 SQL 投影里就 cast 成 text**(`f_price::text AS price`)。 +`int` 列(`f_delete_mark` / `f_stock` / `f_is_administrator`)**保持数字**。 + +### R1.6 口令不得外泄 +库内存 `md5(明文)` 小写 hex。对外响应**手工挑字段**(用户列表去掉 `password`)。密文只在请求体里出现,永不回显。 + +### R1.7 四源权限合并 + 管理员短路 + 未映射放行 +- 管理员(`f_is_administrator=1`)**在任何 SQL 之前**短路放行; +- 权限 = 用户直授 + 角色 + 组织 + 岗位,**只查角色会漏授权**; +- 菜单**未映射**到 `base_module` ⇒ **放行**(对齐 `SswPermissionGuard` 的 warn 路径),不是拒绝。 + 这条最容易写反且**静默**,必须有测试钉住。 + +### R1.8 前端不直接持有数据库 +一切访问经 `/api/**`。 + +### R1.9 schema DDL 绝不可从 HTTP 下载 +`db/schema.sql` **不在 web root**。后端若托管静态产物,只能托管前端 `dist/`。 + +### R1.10 标识符白名单 +任何拼进 SQL 的表名/列名都要过白名单(`[A-Za-z][A-Za-z0-9_]*`),启动时自检全部拼接点,不过白名单 ⇒ 秒退。 + +### R1.11 同一文件的多个 Edit 必须串行 +并行 Edit 同一文件 = last-writer-wins 静默覆盖。改完必须 grep 复核全部改动点。 + +### R1.12 bash 变量后紧跟中文必须写 `${VAR}` +`"$RC里已有"` 会把中文字节并入变量名,`set -u` 下直接 `unbound variable`。写中文提示的 shell 脚本一律用 `${VAR}` 包裹。 + +--- + +## 2. 统一信封 + +```json +{ "code": 200, "msg": "成功", "data": null } +``` + +- `code`:`int` +- `msg`:`string` +- `data`:任意 JSON(失败时为 `null`) + +**Rust 侧固定形态**(`src/backend/src/platform/envelope.rs`): + +```rust +use axum::Json; +use serde_json::Value; + +#[derive(serde::Serialize)] +pub struct ActionResult { + pub code: i32, + pub msg: String, + pub data: Value, +} + +/// 成功:code=200, msg='成功' +pub fn ok(data: Value) -> Json; +/// 失败:code=, msg=, data=null(**恒 HTTP 200**) +pub fn fail(code: i32, msg: impl Into) -> Json; +``` + +**没有第三种形状。** 禁止 `{"success":false,...}`、禁止 401/403 裸 body(那是 `tdc-rs` 的形状,**不要抄**)。 + +--- + +## 3. cipher(与 `cipher.ts` 逐字节等价) + +```rust +// src/backend/src/platform/cipher.rs +pub fn md5_hex(s: &str) -> String; +pub fn encrypt_password(plain: &str) -> String; // hex 输出 +pub fn decrypt_to_md5(encrypted_hex: &str) -> Option; // 解出 md5(明文);非法 hex ⇒ None +``` + +算法: +1. `key = md5_hex("EY8WePvjM5GGwQzn")` ⇒ **32 个 ASCII 字节**(不是 16 字节摘要!) +2. `src = md5_hex(plaintext)` 的 **32 个 ASCII 字节** +3. `AES-256-ECB-PKCS7`,输出 hex + +🔴 **key 当成 hex 串当 ASCII 用** ⇒ 32 字节 ⇒ AES-256。若当 16 字节摘要用 ⇒ AES-128 ⇒ 登录全挂。 + +**上游检验向量(必须逐字节相等)**: +``` +encrypt_password("123456") +== "d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b" +``` + +**中间值(已用 openssl 独立验算通过,2026-10-25)**: +``` +md5_hex("EY8WePvjM5GGwQzn") = "05b0175907a859751f57a04d5a5ee9ac" ← 32 字符,当 32 个 ASCII 字节用 +md5_hex("123456") = "e10adc3949ba59abbe56e057f20f883e" ← 32 字符,当 32 个 ASCII 字节用 +``` + +🔴 **输出长度**:输入是 32 字节(= 16 的整数倍)⇒ PKCS7 **补满一整块 16 字节** ⇒ +密文 48 字节 ⇒ hex **96 个字符**(不是 64)。 +自查:若你的实现输出 64 个 hex 字符 ⇒ 漏了 PKCS7 填充。 +解密时必须**去掉 PKCS7 填充**;填充非法 ⇒ 返回 `None`。 + +**口令比对**:库内存 `md5(明文)`;登录时 `decrypt_to_md5(密文)` 得到 `md5(明文)` ⇒ **大小写不敏感**比较。 + +🔴 **解密失败(`None`)⇒ 登录端点返回 `400 '账号或密码错误'`,与 react 完全同形。** +react 的 `decryptToMd5` 遇非法 hex / 非法填充返回**空串** ⇒ 与库里的 md5 比对不等 ⇒ 抛 `账号或密码错误`。 +⇒ 本仓的 `None` 必须**映射到同一条消息**,**不要**另造「密文格式错误」之类的新提示。 +(也别再加「解密结果长度必须 == 32」这类额外校验 —— react 没有,额外校验只会让行为与 react 不一致。) + +**依赖版本组合(别混用)**:`aes 0.8` + `ecb 0.1`(cipher 0.4 家族);`md-5 0.10`(crate 名 `md5`,`use md5::{Digest, Md5};`)。 +`aes 0.9`/`ecb 0.2` 是 cipher 0.5 家族,两套泛型不通用。 + +--- + +## 4. JSON 键名映射(列名 ↔ JSON 键) + +**规则**:列名去 `f_` 前缀 → 剩余部分按 `_` 拆 → camelCase。 + +🔴 **投影时别名一律写 `AS ""`(带双引号)** —— PG 会把未加引号的标识符折叠成小写 +(`AS realName` ⇒ 键 `"realname"` ⇒ 前端读不到,**且静默**)。详见 §R1.4。 + +| 列 | JSON 键 | +|---|---| +| `f_id` | `id` | +| `f_tenant_id` | `tenantId` | +| `f_account` | `account` | +| `f_real_name` | `realName` | +| `f_password` | `password` | +| `f_secretkey` | `secretkey` | +| `f_is_administrator` | `isAdministrator` | +| `f_role_id` | `roleId` | +| `f_organize_id` | `organizeId` | +| `f_creator_user_id` | `creatorUserId` | +| `f_creator_time` | `creatorTime` | +| `f_enabled_mark` | `enabledMark` | +| `f_delete_mark` | `deleteMark` | +| `f_full_name` | `fullName` | +| `f_en_code` | `enCode` | +| `f_url_address` | `urlAddress` | +| `f_parent_id` | `parentId` | +| `f_sort_code` | `sortCode` | +| `f_type` | `type` | +| `f_category` | `category` | +| `f_icon` | `icon` | +| `f_object_type` | `objectType` | +| `f_object_id` | `objectId` | +| `f_item_type` | `itemType` | +| `f_item_id` | `itemId` | +| `f_role_id` | `roleId` | +| `f_user_id` | `userId` | +| `f_org_id` | `orgId` | +| `f_title` | `title` | +| `f_status` | `status` | +| `f_price` | `price` | +| `f_stock` | `stock` | +| `f_author` | `author` | +| `f_isbn` | `isbn` | + +**Rust 侧固定形态**(`src/backend/src/platform/db.rs`): +```rust +pub fn column_to_json_key(col: &str) -> String; +pub fn json_key_to_column(key: &str) -> String; // 逆规则 +pub fn valid_table(name: &str) -> Option; +pub fn valid_column(name: &str) -> Option; +``` + +**请求体键名 = JSON 键名**(去前缀名):`title` 不是 `fTitle`,`realName` 不是 `fRealName`。 + +--- + +## 5. 数据库 + +### 5.1 表清单(10 张) + +`base_*` 7 张 —— **官方 DDL 逐字**(源行号见括号): +`base_authorize`(812) · `base_module`(2209) · `base_organize`(3178) · `base_role`(3686) · +`base_role_relation`(3729) · `base_user`(4479) · `base_user_relation`(4707) + +> 官方 DDL 原文已提取到 `.tmp/base_ddl_raw.sql`(**逐字,未改写**)。 +> 复合主键一律 `(f_id, f_tenant_id)`;`f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL`。 +> 除 `f_id` 外**没有**其它 NOT NULL 列 ⇒ 插入只需给业务列 + `f_tenant_id`。 +> 唯一性(`f_account` / `f_en_code`)**无 DB 约束**,应用层保证。 + +> 🔴 **「两版后端可开同一个库」这句话的适用范围 = 下面那 3 张业务表**(本节的措辞如此)。 +> `base_*` 7 张是**官方 DDL 逐字**(本仓的「契约」),而 react 的 `base_*` entity 只是它的**子集** +> (react 的 `base_module` 没有 `f_creator_user_id`;`base_authorize` 没有 `f_creator_time` / +> `f_creator_user_id`;`base_role_relation` 这两列都没有)⇒ **react 后端本来就打不开本仓的库** +> (它的 TypeORM `synchronize: true` 会 `ALTER` 掉官方 DDL 的多余列)。 +> ⇒ 本仓真正复用的是 react 的**前端产物**,**不是** react 的**后端**。 +> 两个方向的依据分开:**写**以**官方 DDL** 为准(本仓的种子会写 `f_creator_user_id` / +> `f_creator_time`);**读**以 **react 的 entity 列集**为准(见 §5.3 的投影规则)。 + +业务表 3 张 —— 表名与 react 版同名(两版后端可开同一个库): + +| 表 | 列 | +|---|---| +| `demo_item` | `f_id` / `f_title` / `f_status` / `f_creator_user_id` / `f_creator_time` / `f_delete_mark` | +| `shop_product` | `f_id` / `f_title` / `f_price numeric(12,2)` / `f_creator_user_id` / `f_creator_time` / `f_delete_mark` | +| `book_shop_book` | `f_id` / `f_title` / `f_author` / `f_isbn` / `f_category` / `f_price numeric(12,2)` / `f_stock int` / `f_creator_user_id` / `f_creator_time` / `f_delete_mark` | + +业务表主键 `f_id VARCHAR(50) PRIMARY KEY`,时间列 `TIMESTAMP(0) WITHOUT TIME ZONE`。 + +🔴 **业务表的列宽与默认值必须逐字对齐 react 的 TypeORM entity** +(`demo-item.entity.ts` / `product.entity.ts` / `book.entity.ts`)—— +这是「两版后端可开同一个库」能成立的**前提**:TypeORM `synchronize` 建的库与我们的 `schema.sql` +必须是同一张表,否则一边 `synchronize` 会 `ALTER` 掉另一边建好的列。 + +| 表 | 逐字 DDL | +|---|---| +| `demo_item` | `f_id VARCHAR(50) PRIMARY KEY` / `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` | +| `shop_product` | `f_id VARCHAR(50) PRIMARY KEY` / `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` | +| `book_shop_book` | `f_id VARCHAR(50) PRIMARY KEY` / `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` | +| `asset_data_resource` | `f_id VARCHAR(50) PRIMARY KEY` / `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` | + +> 🔴 `asset_data_resource` 是**尚数网真实业务表**(不是脚手架示例):列名逐字取自公司本体 +> `DataResource`(`数据资源`)。它**没有 react 版对应表** ⇒ §5.1 那条「两版同库」不适用; +> 但它同样遵守**全部** DDL 红线(`f_` 前缀 / `f_id VARCHAR(50)` / 软删 / 业务列无 DB 默认值)。 + +🔴 **有 DB 默认值的只有两处**:`f_delete_mark`(三张表都有)与 **`book_shop_book.f_stock`**。 +react 的 `book.entity.ts` 上 `stock` 也有 `default: 0` ⇒ TypeORM 建的库同样带这个默认值。 +§7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建)依赖它们补出 `0`。 +其余业务列(`f_title` / `f_status` / `f_price` / `f_author` / `f_isbn` / `f_category` / +`f_creator_user_id` / `f_creator_time`)**不得**有 DB 默认值(§7.6 路径 2 要求"没给就是 NULL")。 + +### 5.2 时间列口径 +官方 DDL 是 `TIMESTAMP(0) WITHOUT TIME ZONE`(秒精度、无时区)。 +**写入一律 UTC 朴素时间**;**读出投影成 JS ISO 串**: + +```sql +to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS creatorTime +``` + +🔴 **投影的 `AS` 别名必须就是 §4 的 JSON 键(camelCase),且必须加双引号** —— +`row_to_json` 用的是**列的输出名**当 JSON 键。别名写成 `AS creator_time` 会得到 `"creator_time"`, +与 react 的 `"creatorTime"` **对不上** ⇒ 前端所有字段读不到。 +**每一列**都要显式 `AS ""`(**带双引号** —— PG 折叠未加引号的标识符,见 §R1.4)。 + +### 5.3 精确列清单(**投影真源**) + +🔴 **SELECT 的列必须逐字取自下表** —— 这是 react 版 entity 的**精确列集**(`~/Desktop/workspace/skills/ssw-jnpf-lite-react/src/backend/src/**/*.entity.ts`), +**不是**官方 DDL 的全列。官方 DDL 有 30~60 列,react entity 只有 8~13 列。 +取下表的列 ⇒ ① 响应 JSON 与 react **逐字相同**;② 本仓后端能打开 react 建出来的库。 + +格式:`列名 → JSON 键`。列顺序 = react entity 的声明顺序。 + +🔴 **投影写法**:每列都写成 `f_xxx AS ""`(**别名 = 右边的 JSON 键,camelCase,且带双引号**)。 +`row_to_json` 用的就是别名当 JSON 键 —— 别名写错 ⇒ 响应键名对不上 react; +**双引号漏了 ⇒ PG 折叠成小写 ⇒ 键名对不上且静默**(见 §R1.4)。 +例:`f_real_name AS "realName"`、`f_is_administrator AS "isAdministrator"`、 +`f_creator_time` ⇒ `to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS "creatorTime"`、 +`f_price` ⇒ `f_price::text AS "price"`(numeric 必须是字符串)。 + +**base_authorize**(9 列) +``` +f_id → id f_tenant_id → tenantId f_object_type → objectType +f_object_id → objectId f_item_type → itemType f_item_id → itemId +f_org_id → orgId f_sort_code → sortCode f_delete_mark → deleteMark +``` +⚠️ react 的 `base_authorize` entity **没有** `f_creator_time` / `f_creator_user_id`(官方 DDL 有)⇒ 投影里**不要**它们。 + +**base_module**(13 列) +``` +f_id → id f_tenant_id → tenantId f_full_name → fullName +f_url_address → urlAddress f_parent_id → parentId f_type → type +f_category → category f_en_code → enCode f_icon → icon +f_sort_code → sortCode f_enabled_mark → enabledMark +f_creator_time → creatorTime f_delete_mark → deleteMark +``` +⚠️ 没有 `f_creator_user_id`。 + +**base_organize**(11 列) +``` +f_id → id f_tenant_id → tenantId f_full_name → fullName +f_parent_id → parentId f_category → category f_en_code → enCode +f_manager_id → managerId f_sort_code → sortCode f_enabled_mark → enabledMark +f_creator_time → creatorTime f_delete_mark → deleteMark +``` +⚠️ 没有 `f_creator_user_id`。 + +**base_role**(11 列) +``` +f_id → id f_tenant_id → tenantId f_full_name → fullName +f_en_code → enCode f_type → type f_description → description +f_enabled_mark → enabledMark f_sort_code → sortCode +f_creator_user_id → creatorUserId f_creator_time → creatorTime +f_delete_mark → deleteMark +``` + +**base_role_relation**(8 列) +``` +f_id → id f_tenant_id → tenantId f_object_type → objectType +f_object_id → objectId f_role_id → roleId f_sort_code → sortCode +f_delete_mark → deleteMark +``` +⚠️ 没有 `f_creator_time` / `f_creator_user_id`。 + +**base_user**(13 列) +``` +f_id → id f_tenant_id → tenantId f_account → account +f_real_name → realName f_password → password f_secretkey → secretkey +f_is_administrator → isAdministrator f_role_id → roleId +f_organize_id → organizeId f_creator_user_id → creatorUserId +f_creator_time → creatorTime f_enabled_mark → enabledMark +f_delete_mark → deleteMark +``` +🔴 **没有 `f_manager_id` / `f_position_id` / `f_gender` / `f_email` 等** —— 官方 DDL 有,react entity 没有 ⇒ 不投影。 + +**base_user_relation**(8 列) +``` +f_id → id f_tenant_id → tenantId f_user_id → userId +f_object_type → objectType f_object_id → objectId +f_sort_code → sortCode f_delete_mark → deleteMark +``` + +**demo_item**(6 列)/ **shop_product**(6 列)/ **book_shop_book**(10 列) +``` +demo_item: f_id → id, f_title → title, f_status → status, + f_creator_user_id → creatorUserId, f_creator_time → creatorTime, + f_delete_mark → deleteMark +shop_product: f_id → id, f_title → title, f_price → price, + f_creator_user_id → creatorUserId, f_creator_time → creatorTime, + f_delete_mark → deleteMark +book_shop_book: f_id → id, f_title → title, f_author → author, f_isbn → isbn, + f_category → category, f_price → price, f_stock → stock, + f_creator_user_id → creatorUserId, f_creator_time → creatorTime, + f_delete_mark → deleteMark +``` + +**已知无害偏离**(记入 ledger,不必对齐): +- `f_sort_code` 是 `BIGINT`,直投影为 JSON **数字**;react 因 `pg` 驱动把 int8 返回成**字符串**。 + 前端只在 `` 里原样渲染(`MenuManage.tsx:75`)⇒ 显示一致。 +- 时间列:react 返回 JS Date ⇒ JSON `"2026-01-01T00:00:00.000Z"`;我们投影 `"2026-01-01T00:00:00Z"`(秒精度)。 + 前端**完全不用** `creatorTime` ⇒ 无影响。 + +### 5.4 pglite 封装(`src/backend/src/platform/db.rs`) +```rust +pub const SCHEMA_SQL: &str = include_str!("../db/schema.sql"); + +pub struct Db { /* PGlite + 进程级 Mutex */ } + +impl Db { + pub async fn open(dir: &Path) -> Result; + pub async fn open_temp() -> Result; + pub async fn ensure_schema(&self) -> Result<(), pglite::Error>; + pub async fn query_json(&self, sql: &str) -> Result, pglite::Error>; + pub async fn query_json_params(&self, sql: &str, params: &[&(dyn pglite::ToSql + Sync)]) + -> Result, pglite::Error>; + pub async fn exec(&self, sql: &str) -> Result<(), pglite::Error>; + pub async fn exec_params(&self, sql: &str, params: &[&(dyn pglite::ToSql + Sync)]) + -> Result<(), pglite::Error>; + pub async fn scalar_text(&self, sql: &str) -> Result, pglite::Error>; +} + +/// 字面量感知 SQL 切分(单引号串 / dollar-quote / 行注释 / 块注释内的 `;` 不切) +pub fn split_sql_statements(sql: &str) -> Vec; +``` + +**序列化手法**(沿用 `tdc-rs`): +```sql +SELECT row_to_json(q)::text AS _row FROM () AS q +``` +⇒ 取单列文本 ⇒ `serde_json::from_str`。**不要另起逐列类型映射分支。** + +🔴 **键归一安全网**(`db.rs` 内建,Ruling P23):`query_json` 返回前会把 JSON 键还原成 camelCase —— +① 内层 SQL 里 `AS <别名>`(**含大写字母**)的别名 ⇒ 按作者原样还原(`AS realName` ⇒ `"realName"`); +② 键以 `f_` 开头 ⇒ 走 `column_to_json_key`(`f_real_name` ⇒ `realName`,与 `tdc-rs` 同思路)。 +已加双引号的别名(`AS "realName"`)PG 原样保留 ⇒ 两条规则都不动它。 +⇒ **两种写法都能出正确键**;但**规范写法是加双引号**(原生 PG 行为,不依赖这层解析)。 +安全网存在的意义是:万一某处漏了双引号,**不会静默产出小写键**。 + +**绑定参数一律按 text 传**(`&str` / `Option<&str>` 都实现了 `ToSql`); +类型转换由 SQL 里的 `CAST` / 列上下文负责(PG 从目标列推断参数类型)。 + +**单 backend 独占**:pglite-rs 每进程只允许一个 `PGlite` 实例 ⇒ 集成测试必须**共用一个实例**, +且各自用独立数据目录的多个测试二进制不能并行跑。 + +### 5.5 schema 初始化 +启动时探测 `base_user` 是否存在;不存在才按 `;` 拆分执行 `schema.sql`(拆分要**字面量感知**)。 + +🔴 **`schema.sql` 只在「`base_user` 不存在」时整体执行一次**,不是「每次启动都跑」。 +- 改了 schema(加列/改类型)⇒ 必须**清空数据目录**(`src/backend/data/`)重建,否则旧库仍是老结构。 +- 7 张 `base_*` 的 `CREATE TABLE` 块与 `docs/ddl/base_ddl_raw.sql` **逐字相同**; + 文件尾部另有 4 条官方索引(`i_ba_foi` / `i_brr_fri` / `i_bu_fa` / `i_bur_fui`), + 官方全部**非唯一** ⇒ 账号唯一性仍由**应用层**保证(不会有 23505)。 +- 4 条索引都带 `IF NOT EXISTS` ⇒ `schema.sql` 重复执行不会报 42P07。 + +--- + +## 6. 端点全表 + +> 🔴 **本节是「人读」版;机器可读版在附录 A 的 `[ENDPOINT]` 区段** +> (列:`face` / `method` / `path` / `guard` / `owner`,一行一条端点,**44** 条; +> 外加 `[FACE]` 区段登记各契约面的条数)。 +> 由 **`scripts/check-contract.sh`** 把它与**代码里真实注册的路由**逐条对账 +> (总数 / 存在性 / 方法 / 归属层 / 守卫,**双向**)⇒ +> 改契约忘了改代码(或反之)**立刻报**。 +> 🔴 **改端点时两处都要改**:本节的散文表 + 附录 A 的 `[ENDPOINT]`。 +> +> 📊 **本仓对「官方 JNPF 契约面」的覆盖**是另一本账:附录 A 的 **`[OFFICIAL]`** 区段 +> (53 行 = 官方端点全表 + 每个端点的 `status` 四态 + 官方出处 `文件:行号`)⇒ +> 由 `check-contract.sh` 的 **CC10** 与代码真实路由**双向**对账 ⇒ +> 打印「官方端点覆盖 N/M」。官方端点全表的人读版在 `JNPF_SOURCE_AUDIT.md` §4。 + +### 6.1 认证 + +| 方法 | 路径 | 守卫 | 说明 | +|---|---|---|---| +| POST | `/api/oauth/Login` | 无 | **form-urlencoded**:`account` / `password`(密文 hex) / `grant_type=password` | +| GET | `/api/oauth/CurrentUser` | 登录 | `{userInfo:{userId,userAccount,userName,isAdministrator}, menuList}` | + +**登录失败文案**(逐字): +- 缺 `account` 或 `password` ⇒ `400 '缺少 account / password'` +- `grant_type` **非空**且 ≠ `password` ⇒ `400 '不支持的 grant_type'` +- 口令错 / 账号不存在 ⇒ `400 '账号或密码错误'` +- **密文非法(非法 hex / 非法 PKCS7 填充 ⇒ `decrypt_to_md5` 返回 `None`)⇒ 同一条 `400 '账号或密码错误'`** + (react 的 `decryptToMd5` 失败返空串 ⇒ 比对不等 ⇒ 同一条消息。**不要**另造提示文案。) + +**实现注记**:axum 0.8.9 的 `Form` **没有** `OptionalFromRequest` ⇒ `Option>` 编译不过。 +⇒ handler 取**原始 body**(`Bytes`),自己 `serde_urlencoded::from_bytes::(&body)`; +**解析失败也走业务信封**(`fail(400, "缺少 account / password")`),不要 axum 默认的 400 文本。 + +**登录成功体**:`{token, expiresIn: 7200, tokenTypeName: 'bearer'}` + +**token 形态**:`lite-` + 32 位小写 hex(`lite-` 前缀 + md5)。进程重启即失效(内存表)。 + +**Authorization 头**:`bearer `(大小写不敏感前缀)。 + +**CurrentUser 的 `userName` = 账号**(react 版 `userName: u.account`,不是 `realName`)。 +`isAdministrator` 是 **JSON 布尔**(`isAdmin === 1`)。 + +### 6.2 系统管理(5 组) + +| 方法 | 路径 | 守卫菜单 key | +|---|---|---| +| GET/POST/DELETE | `/api/ssw/sys/User/{List,Save,Delete?id=}` | `system/User` | +| GET/POST/DELETE | `/api/ssw/sys/Role/{List,Save,Delete?id=}` | `system/Role` | +| GET | `/api/ssw/sys/Role/Modules?roleId=` | **仅登录** | +| GET/POST/DELETE | `/api/ssw/sys/Organize/{List,Save,Delete?id=}` | `system/Organize` | +| GET/POST/DELETE | `/api/ssw/sys/Module/{List,Save,Delete?id=}` | `system/Module` | + +### 6.3 授权 + +| 方法 | 路径 | 守卫 | 说明 | +|---|---|---|---| +| PUT | `/api/permission/Authority/Data/{objectId}` | 仅登录 | body `{objectType:'role', module:['m1','m2']}`(**一维**) | +| GET | `/api/permission/Authority/RoleModules?roleId=` | 仅登录 | 返 `string[]`(菜单 id) | + +**`module` 归一化**(react `normalizeModule`):一维数组直接用;历史二维形态 `[[checked],[halfChecked]]` **展平**后同样落库; +非数组 ⇒ 视作空数组;只保留**非空字符串**元素。 + +⚠️ body 里的 **`objectType` 被完全忽略**(react 只读 `body.module`,落库的 `f_object_type` 硬编码为 `'role'`)⇒ +**不要**因为 body 传了 `'Role'` 就拒绝。详见 §7.5 与 §7.7。 + +### 6.4 业务模块(3 组) + +| 方法 | 路径 | 守卫菜单 key | +|---|---|---| +| GET/POST/DELETE | `/api/ssw/demo/DemoItem/{List,Save,Delete?id=}` | **仅登录**(无菜单守卫) | +| GET/POST/DELETE | `/api/ssw/shop/Product/{List,Save,Delete?id=}` | `shop/Product` | +| GET/POST/DELETE | `/api/ssw/books/Book/{List,Save,Delete?id=}` | `books/Book` | + +### 6.5 其它 +- 未知路由 ⇒ **HTTP 404** + `{code:404,msg:'接口不存在',data:null}` +- 405(路径存在、方法不对)⇒ **HTTP 405** + `{code:405,msg:'方法不被允许',data:null}`,**保留 `Allow` 头** + (react 侧 Express 路由对错误方法其实返 404,但**前端从不发错方法** ⇒ 这条不在契约面上, + 按「传输层状态码保留」处理,别让它掉进 R1.2 的 HTTP 200 规则。) +- 未捕获异常(panic / DB 报错)⇒ **HTTP 200** + `{code:400,msg:'系统异常,请联系管理员',data:null}` + (必须装 catch-all 中间件,**不能**让 axum 的默认 500 空 body 漏出去) +- `GET /api/health` ⇒ `{ok, tables, version}`(**非契约**,探活用) + +--- + +## 7. 各端点语义(逐字对齐 react 版) + +> 本节每一条都**逐字核对过** react 源码 +> (`~/Desktop/workspace/skills/ssw-jnpf-lite-react/src/backend/src/{auth,sys,demo,shop,books}/`)。 +> 括号里的 `react:` 行号是出处。凡与 react 有**故意**偏离的(只有一条:User Save 的 `password`), +> 都标了 🔴 **刻意偏离** 并在 §7.7 记录原因。 + +> 🔴 **全局覆盖规则(§7.1–§7.4 通用)**:后文所有「覆盖 `f_xxx`」默认指 +> **只 SET body 里出现的键**(body 里没出现 ⇒ 该列**不动原值**)—— +> 这就是 react / TypeORM `save` 的 `undefined` 语义(`save` 跳过 `undefined` 的列)。 +> body 里出现了但值为 `null` ⇒ 写 NULL;出现了且值为 `''` ⇒ 写空串。 +> **例外**:凡是本节显式写出兜底表达式的列(`?? 原值` / `|| '0'` / `? 1 : 0`), +> **一律按该表达式求值** —— body 缺该键时取**兜底值**(`?? 原值` ⇒ 原值、 +> `|| '0'` ⇒ `'0'`),**不是**「不动原值」。 +> 🔴 **承重之处**:§7.4 的 `f_url_address` 是 §8.2 权限守卫的比对键。 +> 把它清成 NULL ⇒ 该菜单变成「**未映射**」⇒ 守卫走「未映射放行」 +> ⇒ **任何登录用户都能访问该模块**(静默越权)。⇒ 更新菜单时**绝不可**把 +> `f_url_address` 写成本仓未提供的值。 + +### 7.1 User(`/api/ssw/sys/User/*`) + +- **List** + - `base_user`:`f_delete_mark=0`,`f_creator_time DESC`。 + - 关联:`base_role_relation` 取 `f_object_type='user'` 的**全部**行(**不按 `f_delete_mark` 过滤**), + 再按 `f_object_id == 用户 id` 过滤 ⇒ `roleIds` = 命中行的 `f_role_id` 数组(保持库里顺序)。 + - `roleNames` = `base_role` 中 `f_delete_mark=0` 的行按 id 查 `f_full_name`; + **查不到就跳过**(不是填空串、不是 null)⇒ 数组长度可能小于 `roleIds`。 + - 输出去掉 `password`,追加 `roleIds` / `roleNames`(两个都是**一维** `string[]`)。 +- **Save**(`POST /api/ssw/sys/User/Save`,body 是 JSON) + 1. `account` 为空 ⇒ `400 '账号不能为空'`。 + 2. **查重**(新建和更新**都查**):`base_user` 中 `f_account = AND f_delete_mark = 0`。 + ⚠️ 官方 DDL 对 `f_account` **无 UNIQUE**,唯一性只在应用层。 + 3. **无 `id`** ⇒ 新建: + - `f_id` = 36 位 UUID v4(带连字符),`f_tenant_id='0'`; + - `f_account` = body.account; + - `f_real_name` = body.realName(body 没有 ⇒ NULL); + - `f_password` = `md5(body.password)`;body.password 为空 ⇒ `md5('123456')`; + - `f_is_administrator` = body.isAdministrator **真值 ⇒ 1,否则 0**(缺省即 0,不是「保持原值」); + - `f_organize_id` = body.organizeId || `'0'`; + - `f_creator_user_id` = `'admin'`,`f_creator_time` = now(UTC), + `f_enabled_mark=1`,`f_delete_mark=0`。 + - `f_secretkey` / `f_role_id` 不写(NULL)。 + - 若 `dup` 存在 ⇒ `400 '账号已存在:'`(**HTTP 200,不是 500**)。 + 4. **有 `id`** ⇒ 更新: + - 先按 `f_id = ` 查(**不按 `f_delete_mark` 过滤** ⇒ 软删过的行也算存在), + 查不到 ⇒ `400 '用户不存在'`; + - 若 `dup` 存在**且** `dup.f_id != ` ⇒ `400 '账号已存在:'`; + - 覆盖规则(**只覆盖 body 里出现的键**,`undefined` ⇒ 不动原值): + `f_account`(必覆盖)、`f_real_name`(body 有才覆盖)、 + `f_is_administrator`(**总是**覆盖为 body 真值 ? 1 : 0)、 + `f_organize_id`(**总是**覆盖为 body.organizeId || `'0'`)、 + `f_password`(**body.password 非空才**覆盖为 `md5(body.password)`)。 + - ⚠️ 更新**不**碰 `f_creator_time` / `f_enabled_mark` / `f_delete_mark`。 + 5. `roleIds` 是数组 ⇒ **先硬删**该用户的 `base_role_relation` 旧行 + (`f_object_type='user' AND f_object_id=`),再每个 roleId 插一行 + (`f_id`=UUID v4、`f_tenant_id='0'`、`f_object_type='user'`、`f_object_id=`、 + `f_role_id=`、`f_sort_code=0`、`f_delete_mark=0`)。空数组 ⇒ 只删不插。 + 6. **响应** = 落库后该用户行(**去掉 `password`**)+ `roleIds` + `roleNames`。 + 🔴 **刻意偏离**:react 的 Save 响应**带着 `password` 的 md5 摘要**(可被重新加密成合法登录密文)。 + 本仓按 R1.6 **剥掉 `password`**(List 与 Save 都剥)。前端从不读该字段 ⇒ 无影响。 +- **Delete**(`DELETE /api/ssw/sys/User/Delete?id=`) + - 软删 `base_user`:`f_delete_mark=1`(按 id,**不按 `f_delete_mark` 过滤** ⇒ 幂等); + - 硬删 `base_role_relation`:`f_object_type='user' AND f_object_id=`; + - **不检查用户是否存在** ⇒ 不存在也返回成功。 + +### 7.2 Role(`/api/ssw/sys/Role/*`) + +- **List**:`f_delete_mark=0`,`f_sort_code ASC`。 +- **Save** + 1. `fullName` 为空 ⇒ `400 '角色名称不能为空'`。 + 2. **无 `id`** ⇒ 新建: + - **先查重** `base_role` 中 `f_en_code = AND f_delete_mark = 0`; + 命中 ⇒ `400 '角色编码已存在:'`; + - `f_id`=UUID v4、`f_tenant_id='0'`、`f_full_name`=body.fullName、`f_en_code`=body.enCode、 + `f_type` = body.type ?? `'user'`、`f_description`=body.description、 + `f_enabled_mark=1`、`f_sort_code` = body.sortCode ?? 0、 + `f_creator_user_id='admin'`、`f_creator_time`=now、`f_delete_mark=0`。 + 3. **有 `id`** ⇒ 更新: + - 按 `f_id` 查(**不带 `f_delete_mark` 过滤**),查不到 ⇒ `400 '角色不存在'`; + - 覆盖(**body 有才覆盖**,见本节全局规则):`f_full_name`、`f_en_code`、 + `f_type` = body.type ?? **原值**、`f_description`; + - ⚠️ 更新**不做** `f_en_code` 查重;**不碰** `f_sort_code` / `f_enabled_mark`。 +- **Delete** + - 软删 `base_role`(`f_delete_mark=1`,按 id); + - 软删 `base_authorize`:`f_object_type='role' AND f_object_id=` ⇒ `f_delete_mark=1` + (⚠️ **不带 `f_item_type` 过滤**); + - **硬删** `base_role_relation`:`f_role_id=`(⚠️ **不带 `f_object_type` 过滤**)。 +- **`GET /api/ssw/sys/Role/Modules?roleId=`** + ⇒ `base_authorize` 中 `f_object_type='role' AND f_item_type='module' AND f_object_id= AND f_delete_mark=0` + 的 `f_item_id` 数组(`string[]`)。 + +### 7.3 Organize(`/api/ssw/sys/Organize/*`) + +- **List**:`f_delete_mark=0`,`f_sort_code ASC`。 +- **Save** + 1. `fullName` 为空 ⇒ `400 '机构名称不能为空'`。 + 2. **无 `id`** ⇒ 新建:`f_id`=UUID v4、`f_tenant_id='0'`、`f_full_name`=body.fullName、 + `f_parent_id` = body.parentId || `'0'`、`f_category` = body.category ?? NULL、 + `f_sort_code` = body.sortCode ?? 0、`f_enabled_mark=1`、`f_creator_time`=now、`f_delete_mark=0`。 + ⚠️ **不写 `f_creator_user_id`**(react 的 `base_organize` entity 没有该列)⇒ NULL。 + 3. **有 `id`** ⇒ 更新:按 `f_id` 查(不带 `f_delete_mark` 过滤),查不到 ⇒ `400 '机构不存在'`; + 覆盖(**body 有才覆盖**,见本节全局规则):`f_full_name`、 + `f_parent_id` = body.parentId || `'0'`、`f_category` = body.category ?? **原值**。 + ⚠️ 更新**不碰** `f_sort_code` / `f_enabled_mark`。 +- **Delete** + - 先查子机构:`base_organize` 中 `f_parent_id= AND f_delete_mark=0`; + 非空 ⇒ `400 '该机构下还有子机构,先删除子机构'`; + - 否则软删(`f_delete_mark=1`,按 id)。 + +### 7.4 Module(`/api/ssw/sys/Module/*`) + +- **List**:`f_delete_mark=0`,`f_sort_code ASC`。 +- **Save** + 1. `fullName` 为空 ⇒ `400 '菜单名称不能为空'`。 + 2. **无 `id`** ⇒ 新建:`f_id`=UUID v4、`f_tenant_id='0'`、`f_full_name`=body.fullName、 + `f_url_address`=body.urlAddress、`f_parent_id` = body.parentId || `'0'`、 + `f_type` = body.type ?? **2**(**INTEGER**:1=目录 2=页面)、 + `f_category` = body.category ?? NULL(**VARCHAR 分类**)、 + `f_icon`=body.icon、`f_sort_code` = body.sortCode ?? 0、 + `f_enabled_mark=1`、`f_creator_time`=now、`f_delete_mark=0`。 + ⚠️ **不写 `f_creator_user_id`** ⇒ NULL。 + 3. **有 `id`** ⇒ 更新:按 `f_id` 查(不带 `f_delete_mark` 过滤),查不到 ⇒ `400 '菜单不存在'`; + 覆盖(**body 有才覆盖**,见本节全局规则):`f_full_name`、`f_url_address`、 + `f_parent_id` = body.parentId || `'0'`、`f_type` = body.type ?? **原值**、 + `f_category` = body.category ?? **原值**、`f_icon`、`f_sort_code` = body.sortCode ?? 0。 +- **Delete** + - 软删 `base_module`(`f_delete_mark=1`,按 id); + - 软删 `base_authorize`:`f_item_type='module' AND f_item_id=` ⇒ `f_delete_mark=1` + (⚠️ **不带 `f_object_type` 过滤**)。 + +### 7.5 授权(`/api/permission/Authority/*`) + +- **`PUT /api/permission/Authority/Data/{objectId}`**,body `{objectType, module}`: + 1. **守卫**:未登录 ⇒ `600 '未登录'`。 + 2. **归一化 `module`**(react `normalizeModule`): + - body 里没有 `module` 或不是数组 ⇒ `[]`; + - 若 `module[0]` 是数组 ⇒ **展平一层**(兼容官方前端的 `[checked, halfChecked]` 二维形态); + - 只保留**非空字符串**。 + 3. ⚠️ **body 里的 `objectType` 被完全忽略**(react 只读 `body.module`)⇒ + 落库一律 `f_object_type='role'`、`f_item_type='module'`、`f_object_id=`。 + (不要因为 body 传了 `'Role'` 而拒绝 —— react 不校验,本仓也不校验。) + 4. **先软删**旧行:`base_authorize` 中 `f_object_type='role' AND f_item_type='module' AND f_object_id=` + ⇒ `f_delete_mark=1`(⚠️ **不带 `f_delete_mark` 过滤**)。 + 5. 再**插新行**(每个 moduleId 一行):`f_id`=UUID v4、`f_tenant_id='0'`、 + `f_object_type='role'`、`f_item_type='module'`、`f_item_id`=、 + `f_sort_code=0`、`f_delete_mark=0`。空数组 ⇒ 只软删不插。 + 6. 成功 ⇒ `{code:200,msg:'成功',data:null}`。 +- **`GET /api/permission/Authority/RoleModules?roleId=`** ⇒ 同 §7.2 的 `Role/Modules` + (`string[]`)。未登录 ⇒ `600 '未登录'`。 + +### 7.6 业务模块(spec 引擎,3 组同构) + +- **List**:`f_delete_mark=0`,`f_creator_time DESC`。 +- **Save** —— **三条互不相同的路径**,按 body 里有没有 `id`、以及该 `id` 存不存在分流: + 1. **无 `id`** ⇒ 新建(**只写下列字段,不多写**): + - `demo_item`:`f_id`=UUID v4、`f_title`=body.title、`f_status` = body.status ?? `'草稿'`、 + `f_creator_user_id` = **`'admin'`(硬编码,不取 body)**、`f_creator_time`=now、`f_delete_mark`=0; + - `shop_product`:`f_id`=UUID v4、`f_title`=body.title、`f_price` = body.price ?? `'0.00'`、 + `f_creator_user_id` = body.creatorUserId || `'admin'`、`f_creator_time`=now、`f_delete_mark`=0; + - `book_shop_book`:`f_id`=UUID v4、`f_title`=body.title、`f_author`=body.author、 + `f_isbn`=body.isbn、`f_category`=body.category、`f_price` = body.price ?? `'0.00'`、 + `f_stock` = body.stock ?? 0、`f_creator_user_id` = body.creatorUserId || `'admin'`、 + `f_creator_time`=now、`f_delete_mark`=0。 + 2. **有 `id` 但库里查不到该行** ⇒ **用这个 id 新建**: + - 写入 body 里**该实体的已知列**(§5.3 的列集),**不加任何默认值**: + 没有 `f_creator_time` ⇒ NULL;没有 `f_status` / `f_price` ⇒ NULL; + - `f_delete_mark`:body 没给 ⇒ **0**(业务表该列 DDL 带 `DEFAULT 0`); + - `f_stock`(**仅 `book_shop_book`**):body 没给 ⇒ **0**(该列 DDL 也带 `DEFAULT 0`, + 与 react 的 `book.entity.ts` 一致 ⇒ 两版后端开同一个库时结果相同)。 + 3. **有 `id` 且库里查得到** ⇒ 覆盖更新:**只覆盖 body 里出现的该实体已知列**(`Object.assign` 语义), + body 没出现的列保持原值。 + - 三个模块**共用**一条规则:**body 里不属于该实体列集的键一律忽略**(不建列、不报错)。 + - **响应体 = 落库后重新读回的那一行**(这样 numeric 的 `"9.90"` 由投影 `::text` 保证)。 +- **Delete**(`DELETE .../Delete?id=`):软删 `f_delete_mark=1`(按 id,**不检查是否存在** ⇒ 幂等)。 + +### 7.7 与 react 的唯一刻意偏离 + +| 项 | react 行为 | 本仓行为 | 理由 | +|---|---|---|---| +| User **Save** 响应 | 带 `password` 字段(md5 摘要) | **剥掉 `password`** | R1.6 口令不得外泄。md5 摘要可被前端用 `cipher.ts` 重新加密成**合法登录密文** ⇒ 泄露即等于泄露凭据。前端从不读该字段 ⇒ 无功能影响。List 响应两版都剥。 | + +--- + +## 8. 权限与菜单树 + +### 8.1 四源合并 +`resolve_user_module_ids(userId)` 返回菜单 id 集合,四个来源: +1. **直授**:`base_authorize` 中 `f_object_type='user' AND f_object_id= AND f_item_type='module' AND f_delete_mark=0` ⇒ `f_item_id` +2. **角色**:`base_role_relation` 中 `f_object_type='user' AND f_object_id=` ⇒ 每行的 `f_role_id` + ⇒ 对每个 roleId 取 `base_authorize` 中 `f_object_type='role' AND f_object_id= AND f_item_type='module' AND f_delete_mark=0` ⇒ `f_item_id` +3. **组织**:`base_user_relation` 中 `f_user_id= AND f_object_type='organize'` ⇒ 每行的 `f_object_id` + ⇒ 对每个 objectId 取 `base_authorize` 中 `f_object_type='organize' AND f_object_id= ...` ⇒ `f_item_id` +4. **岗位**:`base_user_relation` 中 `f_user_id= AND f_object_type='position'` ⇒ 同上,`f_object_type='position'` + +### 8.2 菜单守卫 `has_module(userId, isAdmin, moduleKey)` +1. `isAdmin == 1` ⇒ **放行**(不查任何 SQL) +2. 查 `base_module` 中 `f_url_address = moduleKey AND f_delete_mark=0`(取**第一条**); + **查不到 ⇒ 放行**(未映射放行) +3. 查得到 ⇒ 该菜单 `f_id` 是否在四源合并集合里;在 ⇒ 放行,否则 ⇒ `403` +### 8.3 菜单树 `build_menu_list(userId, isAdmin)` +- 取 `base_module` 中 `f_delete_mark=0` 的行,按 `f_sort_code ASC` +- 非管理员:过滤成「id 在四源集合里」的子集 +- 建树:`f_parent_id` 为空或 `'0'` 或父节点不在集合内 ⇒ 该节点是根;否则挂到父节点 `children` +- 节点形状:`{id, fullName, urlAddress, icon, parentId, children}` + (`urlAddress` / `icon` 库里是 NULL ⇒ JSON 里就是 `null`,**不要**省略这两个键; + `parentId` 取 `f_parent_id`,为 NULL/空 ⇒ `'0'`) +- 根按 `f_sort_code` 升序;同层 children 按 `f_sort_code` 升序 + +### 8.4 种子菜单(8 行,`f_tenant_id='0'`,`f_enabled_mark=1`,`f_delete_mark=0`) + +| id | fullName | urlAddress | parentId | type | icon | sortCode | +|---|---|---|---|---|---|---| +| `m_sys` | 系统管理 | `system` | `0` | 1 | `setting` | 1 | +| `m_user` | 用户管理 | `system/User` | `m_sys` | 2 | — | 2 | +| `m_role` | 角色管理 | `system/Role` | `m_sys` | 2 | — | 3 | +| `m_org` | 机构管理 | `system/Organize` | `m_sys` | 2 | — | 4 | +| `m_menu` | 菜单管理 | `system/Module` | `m_sys` | 2 | — | 5 | +| `m_demo` | Demo 示例 | `demo-item` | `0` | 2 | `app` | 6 | +| `m_product` | 产品管理 | `shop/Product` | `0` | 2 | `app` | 7 | +| `m_book` | 图书超市 | `books/Book` | `0` | 2 | `app` | 8 | + +**期望菜单树字符串**(冒烟断言用;值在**附录 A 的 `[MENU_TREE]` 区段**,脚本从那里读): +``` +系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市: +``` + +🔴 **这 8 行的值住在哪(分层红线 12)**: +- 前 5 行(系统管理 + 4 个系统页)= **平台层**的种子,值在 `platform/seed.rs` 的 `BUILTIN_MENUS`; +- 后 3 行(Demo / 产品 / 图书)= **业务层**的菜单,值在各自 `modules/.rs` 的 `*_MENU: MenuSpec`, + 经 `modules::ALL_MENUS` 交给装配根 `src/bootstrap.rs` 回灌。 +⇒ **加一个业务模块只碰 `modules/`**(平台层一个字都不改),但**菜单行数会变** ⇒ +本节表格与 `modules::ALL_MENUS` 必须同步;`scripts/check-boundary.sh` 的 CP4/CP6 静态钉住这两处一致。 + +### 8.5 种子角色(2 行) +| id | enCode | fullName | sortCode | +|---|---|---|---| +| `role_admin` | `admin` | 管理员 | 1 | +| `role_user` | `user` | 使用者 | 2 | + +其它列:`f_tenant_id='0'`、`f_type='user'`、`f_enabled_mark=1`、`f_delete_mark=0`。 + +### 8.6 两段式种子 +**`ensure_base()`(每次启动都跑,幂等)** +- 补内置角色:查 `base_role` 的**全部行**(🔴 **不按 `f_delete_mark` 过滤**), + 凡 `f_en_code` 命中内置清单(`admin` / `user`)的**一律视为已存在** ⇒ 不补、不覆盖。 + 缺的行按 §8.5 的值插入。 +- 补内置菜单:查 `base_module` 的**全部行**(🔴 **含软删行**), + 凡 `f_url_address` 命中内置清单的**一律视为已存在** ⇒ **不复活**软删的菜单。 + 缺的行按 §8.4 的值插入(`f_tenant_id='0'`、`f_enabled_mark=1`、`f_delete_mark=0`)。 +- 补 admin 授权: + - 取 `base_role` 中 `f_en_code='admin'` 的行(🔴 **不按 `f_delete_mark` 过滤**,取到软删行也用它); + - 取 `base_module` 中 `f_delete_mark=0` **且** `f_url_address` 命中内置清单的行(`builtin_live`); + - 查 `base_authorize` 中 `f_object_type='role' AND f_object_id= AND f_item_type='module'` + 的**全部行**(🔴 **不按 `f_delete_mark` 过滤** ⇒ 软删的授权行也算「已授权」⇒ 不补); + - `builtin_live` 里没出现在上述集合中的行 ⇒ 补一条授权 + (`f_id`=UUID v4、`f_tenant_id='0'`、`f_object_type='role'`、`f_object_id=`、 + `f_item_type='module'`、`f_item_id=`、`f_sort_code=0`、`f_delete_mark=0`) +- **只补缺项**:不覆盖已改值(人工改名/调序会被保留) + +**`first_seed()`(仅 `base_user` 行数为 0 时跑一次)** +- 建 `admin` 用户:`f_id`=UUID v4、`f_account='admin'`、`f_real_name='管理员'`、 + `f_password=md5_hex('123456')`、`f_is_administrator=1`、`f_organize_id='0'`、 + `f_creator_user_id='admin'`、`f_creator_time`=now、`f_enabled_mark=1`、`f_delete_mark=0`、`f_tenant_id='0'` +- 建一条 `base_role_relation`:`f_object_type='user'`、🔴 **`f_object_id='admin'`(账号名,不是 UUID!)**、 + `f_role_id='role_admin'`、`f_sort_code=0`、`f_delete_mark=0`、`f_tenant_id='0'`、`f_id`=UUID v4 + (react 源码里就是 `'admin'`,**逐字照抄**;admin 本人是管理员,不靠这条授权吃饭) + +--- + +## 9. Rust 模块接口契约 + +🔴 **代码分两层**(对齐 react 版的 `common`+`auth`+`sys` / `demo`+`shop`+`books`, +以及官方 JNPF 的 `jnpf-common`+`jnpf-system` / `jnpf-admin`): + +| 层 | 目录 | 职责 | 加业务模块 | +|---|---|---|---| +| **平台层** | `src/backend/src/platform/` | 契约实现(信封 / cipher / 登录 / 权限 / `base_*` 管理 / 面 B / CRUD 引擎) | **不动** | +| **业务层** | `src/backend/src/modules/` | 业务 spec + 各自的 handler 与路由 | **只动这里** | + +所有模块由 `src/backend/src/lib.rs` 统一 `pub mod` 导出。 + +```rust +// ---- lib.rs ---- +pub mod modules; // 业务层:demo / shop / books +pub mod platform; // 平台层:契约实现 +pub mod routes; // 路由装配 +``` + +### ids.rs +```rust +pub fn new_uuid() -> String; // 36 位 UUID v4(带连字符) +``` + +### session.rs +```rust +#[derive(Clone)] +pub struct TokenUser { pub user_id: String, pub account: String, pub is_admin: i32 } + +#[derive(Clone, Default)] +pub struct SessionStore { /* Arc>> */ } + +impl SessionStore { + pub fn new() -> Self; + pub fn issue(&self, account: &str, user_id: &str, is_admin: i32) -> String; // "lite-" + 32 hex + pub fn resolve(&self, auth_header: Option<&str>) -> Option; // 去 bearer 前缀(大小写不敏感) +} +``` + +### config.rs +```rust +pub struct Config { + pub port: u16, // 默认 30010,env PORT + pub pg_dir: PathBuf, // env PGLITE_DIR;"memory://" ⇒ open_temp() + pub project_dir: PathBuf, + pub static_dir: Option, // src/frontend/dist 存在才有 +} +impl Config { pub fn from_env(project_dir: PathBuf) -> Config; } +``` + +### auth.rs +```rust +/// 三个字段全是 Option:缺字段也要走业务信封(code=400),不能落到 axum 默认的 400 文本。 +/// `grant_type` 是 snake_case 字面量,**不能**改名为 camelCase。 +#[derive(serde::Deserialize)] +pub struct LoginForm { + pub account: Option, + pub password: Option, + pub grant_type: Option, +} + +pub async fn login(state: &AppState, body: LoginForm) -> Json; +pub async fn current_user(state: &AppState, headers: HeaderMap) -> Json; + +/// 守卫:未登录 ⇒ `fail(600, "未登录")`;无菜单权限 ⇒ `fail(403, "无菜单权限")` +pub async fn require_login(state: &AppState, headers: &HeaderMap) -> Result>; +pub async fn require_module(state: &AppState, headers: &HeaderMap, module_key: &str) + -> Result>; +``` + +### permission.rs +```rust +pub async fn resolve_user_module_ids(db: &Db, user_id: &str) -> HashSet; +pub async fn has_module(db: &Db, user_id: &str, is_admin: i32, module_key: &str) -> bool; +pub async fn build_menu_list(db: &Db, user_id: &str, is_admin: i32) -> Vec; + +#[derive(serde::Serialize)] +pub struct MenuNode { + pub id: String, pub full_name: String, // #[serde(rename="fullName")] + pub url_address: Option, // #[serde(rename="urlAddress")] + pub icon: Option, + pub parent_id: String, // #[serde(rename="parentId")] + pub children: Vec, +} +``` + +### `platform/entity.rs`(业务实体 spec 的**类型**)+ `modules/`(业务 spec 本体) + +🔴 **类型在平台层、spec 在业务层**(加业务模块只碰业务层)。 + +`platform/entity.rs`: +```rust +pub struct EntitySpec { + pub app_code: &'static str, // "demo" / "shop" / "books" + pub entity: &'static str, // "DemoItem" / "Product" / "Book" + pub table: &'static str, // "demo_item" / "shop_product" / "book_shop_book" + pub module_key: Option<&'static str>, // None = 仅登录守卫;Some("shop/Product") + pub columns: &'static [ColumnSpec], + pub numeric_columns: &'static [&'static str], // 需要 ::text 投影的列 + // 🔴 `f_creator_user_id` 的写死值(裁决 S22): + // Some("admin") ⇒ 恒写 admin(demo);None ⇒ `body.creatorUserId || 'admin'`。 + // 平台层**不认 app_code** ⇒ 加新表不必改引擎。 + pub creator_fixed: Option<&'static str>, +} + +pub struct ColumnSpec { + pub column: &'static str, // "f_title" + pub json_key: &'static str, // "title" + pub default: Option<&'static str>, // 新建时的默认值 + pub numeric: bool, // true ⇒ 投影 ::text +} +``` + +`modules/mod.rs`(业务层登记表): +```rust +pub fn all_specs() -> &'static [EntitySpec]; +pub fn find_spec(app_code: &str, entity: &str) -> Option<&'static EntitySpec>; +pub const ALL_ROUTES: &[&str]; // 全部业务路由(业务层的路由表) +pub fn router() -> Router; // 全部业务模块的路由 +``` + +### `platform/crud.rs`(spec 驱动的通用 CRUD 引擎) +```rust +pub(crate) async fn handle_list(state: &AppState, headers: &HeaderMap, spec: &EntitySpec) -> Json; +pub(crate) async fn handle_save(state: &AppState, headers: &HeaderMap, spec: &EntitySpec, body: &Bytes) -> Json; +pub(crate) async fn handle_delete(state: &AppState, headers: &HeaderMap, spec: &EntitySpec, raw: &RawQuery) -> Json; +``` +🔴 **平台层不含任何业务表名 / app_code** ⇒ 加业务表**不用改本文件**。 + +### routes.rs +```rust +pub fn build_router(state: AppState) -> Router; +``` +(`with_state` 由 `main.rs` 在**链尾**调用; +业务路由由 `routes.rs` 的 `.merge(modules::router())` 一次并入 ⇒ **加业务模块不动平台层**。) + +### AppState(`src/backend/src/platform/state.rs`) +```rust +#[derive(Clone)] +pub struct AppState { + pub config: Arc, + pub db: Arc, + pub sessions: Arc, +} +``` + +🔴 **`src/backend/src/lib.rs` 现在只声明三层**:`pub mod platform;` / `pub mod modules;` / `pub mod routes;` +—— 平台层的模块清单在 `platform/mod.rs` 里,业务层的在 `modules/mod.rs` 里。 +(`AppState` 在 `platform/state.rs`。) + +--- + +## 10. 启动装配(main.rs) + +顺序: +1. `resolve_project_dir()` —— 从可执行文件向上找锚点文件(`src/backend/db/schema.sql` + 根 `Cargo.toml`),**与 cwd 解耦** +2. `Config::from_env(project_dir)` +3. **标识符白名单自检**(不过 ⇒ 秒退 exit 1),放在开库**之前** +4. `Db::open` / `Db::open_temp` ⇒ `ensure_schema()` +5. `seed::ensure_base()` ⇒ 若用户数为 0 则 `seed::first_seed()` + 🔴 **种子失败 ⇒ 打印人话错误 + `exit 1`(启动期不变量破了就立刻退出)**, + 与第 3 步的白名单自检同一处置。react 的 `onModuleInit` 是 try/catch + `logger.warn` 后**继续跑**, + 本仓**刻意不同**(react 那边是 NestJS 容器里已挂载的应用,退出不了;本仓是单二进制,退出更干净)。 + 这条**不在 HTTP 契约面上**(服务要么正常起来,要么根本不起来)。 +6. `build_router(state)` + 404 兜底 + 405 改写中间件 + **catch-all(panic/未捕获异常 ⇒ HTTP 200 + `code=400`)** + `with_state(state)`(**链尾**) +7. `TcpListener::bind` ⇒ 绑定失败打印人话 + exit 1(**不 panic**) + +**子命令**:`--enc <明文>` ⇒ 打印 hex 到 stdout,退出码 0(冒烟脚本用它自证 cipher,不依赖 node)。 +`--help` / 未知参数 ⇒ 打印用法,退出码 0 或 2。 + +**`PGLITE_DIR=memory://`** ⇒ `Db::open_temp()`(pglite-rs 0.2.7 **没有**真正的内存模式,`open()` 只接受路径)。 + +--- + +## 11. 验收门(六道,全绿才算完成) + +| 门 | 命令 | 通过标准 | +|---|---|---| +| ① 编译 | `cargo build --release` | 0 error **0 warning**;release profile:根 `Cargo.toml` 写 `opt-level=2` / `lto="thin"` / `strip="symbols"` / `codegen-units=16`;🔴 **不要**写 `panic="abort"`(Ruling P19:abort 下 `catch_unwind` 抓不到 panic,与 §6.5 的「panic ⇒ HTTP 200 + code=400」冲突 ⇒ 必须用默认的 `unwind`) | +| ② 单测 | `cargo test` | 见 §12 | +| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **全部断言全绿**(FAIL=0),断言集与 react 版**逐条对应**;🔴 **后端不用先起** —— 尺子默认自起隔离实例(见下) | +| ④ 前端手验 | `cd src/frontend && npm run dev` | `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → 3 个业务页可用 → 退出再登录 | +| ⑤ 静态闸门 | `bash scripts/check-module.sh` + `bash scripts/check-boundary.sh` + `bash scripts/check-contract.sh` + `bash scripts/check-citations.sh` | 四把尺子全绿(**86** / **11** / **10** / **4** 条断言,FAIL=0)——纯静态,不起后端。🔴 本仓后端-only:check-module 的 10 个前端接触点打 `⏭`(仍计入条数),见附录 A `[RULER]` | + +**脚本退出码约定**(各入口一致): +`run.sh` 0=成功 / 1=运行期失败 / 2=用法错; +`check-module.sh` 0=全过 / 1=有 ❌ / 2=用法错; +`check-boundary.sh` 0=全过 / 1=有 ❌ / 2=用法错; +`check-contract.sh` 0=全过 / 1=有 ❌ / 2=用法错或前置错误(契约读不出来); +`check-citations.sh` 0=全过 / 1=有 ❌ / 2=用法错或前置错误; +`perm-smoke.sh` 0=全绿 / 1=有断言失败 / 2=前置错误(后端不可达且**显式指定了 `B`** ⇒ 不自起)。 + +🔴 **两把契约尺子默认自起隔离后端**(`scripts/smoke_backend.sh`): +没给 `B` ⇒ 先探 `:30010`;**通** ⇒ 用它;**不通** ⇒ 自起隔离实例(空闲端口 + `mktemp -d` 临时 +`PGLITE_DIR`),跑完即删 ⇒ 两把尺子**互不污染**、不留脏数据、**CI 可跑**。 +**显式给了 `B`** ⇒ **不自起**,不可达即退出码 2(尊重外部后端)。 + +🔴 **官方端点覆盖是一本「账」**(附录 A 的 `[OFFICIAL]` 区段,机器可读): +官方 JNPF 契约面的**端点全表**在 `JNPF_SOURCE_AUDIT.md` §4(**散文表格**), +本仓的**覆盖账本**在附录 A `[OFFICIAL]`(**机器可读**)⇒ +`check-contract.sh` 的 **CC10** 与代码真实路由**双向**对账,并打印 +**「官方端点覆盖 N/M」**(N = implemented + partial;M = 再加 absent;`oos` 单列不进分母)。 +状态词表:`implemented`(已落地且形状对齐)/ `partial`(已落地但**形状有偏差**, +偏差逐条记在 `JNPF_COMPAT_SURFACE.md` §8 的 B1–B10)/ `absent`(未实现,可后置)/ +`oos`(v1 明确不做)。🔴 **面 B / 共用的每条路由都必须在账上**(防止"实现了但没记账")。 + +🔴 **尺子的期望值只有一处**:**附录 A**(机器可读)。 +菜单表 / 菜单树 / 业务模块清单 / **端点表(路径 / 方法 / 守卫 / 归属)** / +各尺子的断言条数**都不写在脚本里**, +一律由 `scripts/contract_expect.py` 从附录 A 读 ⇒ +① 改契约只改附录 A 一处;② 代码漂移尺子立刻报;③ 加模块不用改脚本。 +🔴 **每把尺子都自证**:结尾比对「本尺子实际跑了多少条断言」与附录 A `[RULER]` 登记的条数, +对不上 ⇒ **失败** ⇒ 尺子不会被人悄悄改弱(这条是**故意的**:加断言必须同步契约)。 + +--- + +## 12. 单测覆盖清单(门② 必须全过) + +- **cipher**:上游向量逐字节相等;`md5_hex` ↔ `decrypt_to_md5` 往返;非法 hex ⇒ `None` +- **envelope**:业务失败 HTTP **200** + `code=400`;`code=600`/`403` 同形;成功 `code=200`+`msg='成功'` +- **db**:`split_sql_statements` 字面量感知(单引号 / dollar-quote / 注释内的 `;` 不切); + `column_to_json_key` / `json_key_to_column` 互逆;`valid_table` 只收 `[A-Za-z][A-Za-z0-9_]*` +- **ids**:UUID 36 位带连字符、格式合法 +- **session**:登录后可查回;错误 token 查不到;`bearer` 前缀大小写不敏感 +- **permission**:四源合并**各源单独可注入**;管理员短路**不查 SQL**(无授权记录的管理员仍放行);未映射菜单放行 +- **seed**:空库启动 ⇒ admin/123456 + 2 角色 + 8 菜单 + admin 授权;**再启动一次库内容不变**;不复活软删行 +- **CRUD 往返**:36 位 UUID;numeric ⇒ `"9.90"`;int ⇒ `100`;软删过滤生效;账号重复返 **400**(不是 500) + +--- + +## 13. 冒烟断言集(门③,逐条对应 react 版) + +react 版 `scripts/perm-smoke.sh` 实际有 **32 条断言**。移植后一条不落,另加 +**9 条真实业务模块断言**(33–41,asset/DataResource)+ **2 条多应用断言**(42/43)⇒ 本仓共 **43 条**: + +| # | 断言 | 期望 | +|---|---|---| +| 1 | 无 token 访问 `User/List` | `code=600` | +| 2 | admin 加密登录 | `code=200` | +| 3 | token 非空 | 真 | +| 4 | `CurrentUser` | `code=200` | +| 5 | 菜单树 | `系统管理:用户管理,角色管理,机构管理,菜单管理\|Demo 示例:\|产品管理:\|图书超市:` | +| 6 | 新建 `smoke_user` | `code=200` | +| 7 | 重复账号 HTTP 状态 | **200**(不是 500) | +| 8 | 重复账号业务码 | `code=400` | +| 9 | 重复账号 msg | `账号已存在:smoke_user` | +| 10 | 写授权(一维数组) | `code=200` | +| 11 | 写授权(二维兼容) | `code=200` | +| 12 | `smoke_user` 登录 | `code=200` | +| 13 | `smoke_user` 菜单收窄 | `Demo 示例:` | +| 14 | `smoke_user` 访问 `User/List` | `code=403` | +| 15 | `smoke_user` 访问 `DemoItem/List` | `code=200` | +| 16 | 未知路由 | **HTTP 404** | +| 17 | admin 访问 `Product/List` | `code=200`(管理员短路) | +| 18 | Product 新建 | `code=200` | +| 19 | Product 主键长度 | `36` | +| 20 | Product numeric 往返 | `"9.90"` | +| 21 | Product 无 token | `code=600` | +| 22 | Product 未授权非管理员 | `code=403` | +| 23 | Book 列表(admin 短路) | `code=200` | +| 24 | Book 新建(6 字段) | `code=200` | +| 25 | Book 主键长度 | `36` | +| 26 | Book title 往返 | `三体` | +| 27 | Book author 往返 | `刘慈欣` | +| 28 | Book numeric 往返 | `"58.00"` | +| 29 | Book int 库存往返 | `100` | +| 30 | Book 列表含新建项 | 长度 ≥ 1 | +| 31 | Book 无 token | `code=600` | +| 32 | Book 未授权非管理员 | `code=403` | +| 33 | 数据资源列表(admin 短路) | `code=200` | +| 34 | 数据资源新建(6 字段) | `code=200` | +| 35 | 数据资源主键长度 | `36` | +| 36 | 数据资源 `name` 往返 | `全国企业工商登记数据` | +| 37 | 数据资源 `category` 往返 | `结构化` | +| 38 | 数据资源 `provider` 往返 | `尚数网` | +| 39 | 数据资源列表含新建项 | 长度 ≥ 1 | +| 40 | 数据资源无 token | `code=600` | +| 41 | 数据资源未授权非管理员 | `code=403` | +| 42 | 多应用:`CurrentUser` 无 `App-Code` 头 | `data.currentSystemId = "mainSystem"`(官方 `JnpfConst.MAIN_SYSTEM_CODE`,回落主系统) | +| 43 | 多应用:`CurrentUser` 带 `App-Code: app-b` | `data.currentSystemId = "app-b"`(应用路由生效) | + +**脚本不得依赖 node**(react 版依赖 `node` + `crypto-js` + `src/backend/node_modules`,本仓一律不用): +- **cipher 加密** ⇒ 调用后端自证:`./target/release/ssw-platform --enc '<明文>'` 输出 hex(退出码 0)。 + (冒烟脚本自带 `--enc` 的向量自检,**不**假设 node 存在。) +- **JSON 取值** ⇒ `jq`(若已装)或 `python3`(macOS 自带)写的取字段小工具;**不得**用 node。 +- **期望菜单树** ⇒ **从附录 A 的 `[MENU_TREE]` 区段读**(不是写死在脚本里)—— + 值仍是 §8.4 的 `系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:`。 + react 版是从 `src/backend/src/sys/seed.service.ts` 里 grep 菜单数组动态算的 —— + 本仓是 Rust,没有那个文件 ⇒ 直接用字面量(§8.4 的表就是它的来源)。 +- **后端地址** ⇒ `B` 环境变量,默认 **`http://127.0.0.1:30010`**(本仓端口,**不是** react 的 30000)。 +- 所有 curl 都要带 `--noproxy '*'`(本机 curl 走系统代理,不加会打不通 loopback)。 + + +```text +# 契约期望值 —— **唯一真源**。 +# +# 🔴 下面这段是**机器可读**的(`scripts/contract_expect.py` 解析), +# 所有尺子(check-module.sh / check-boundary.sh / check-contract.sh / +# perm-smoke.sh / perm-smoke-jnpf.sh) +# 的**期望值都从这里读** ⇒ +# ① 改契约 ⇒ 改这一处,尺子自动跟着走; +# ② 代码漂移 ⇒ 尺子立刻报「与契约不一致」(不是默默放过)。 +# +# 格式:区段 `[NAME]` + **制表符**分隔的列;`#` 开头是注释行(忽略)。 +# 列名以各区段的表头注释为准。空字段 = 空值(NULL)。 +# +# 区段: +# [MENU] 种子菜单 8 行(id / fullName / enCode / urlAddress / parentId / type / icon / sortCode) +# [MENU_TREE] 期望菜单树字符串(面 A 的 CurrentUser 对账用) +# [MODULE] 业务模块清单(app / entity / table / urlAddress / moduleKey / menuId / apiFile / rsFile) +# [ENDPOINT] **端点表**(face / method / path / guard / owner)—— 由 `scripts/check-contract.sh` +# 与**代码里真实注册的路由**逐条对账(总数 / 存在性 / 方法 / 归属层 / 守卫,双向) +# [FACE] 各契约面的条数(自洽对账用) +# [OFFICIAL] **官方端点台账**(method / path / status / src / note)—— 官方 JNPF 契约面的 +# 覆盖账本;由 `scripts/check-contract.sh` 的 CC10 与代码真实路由**双向**对账 +# [RULER] 各尺子的期望断言条数(尺子自证用) + +[MENU] +# id fullName enCode urlAddress parentId type icon sortCode +m_sys 系统管理 permission system 0 1 setting 1 +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 +m_demo Demo 示例 permission.demo demo-item 0 2 app 6 +m_product 产品管理 permission.shop.product shop/Product 0 2 app 7 +m_book 图书超市 permission.books.book books/Book 0 2 app 8 +m_resource 数据资源 permission.asset.dataResource asset/DataResource 0 2 app 9 + +[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` +demo DemoItem demo_item demo-item None m_demo 无 demo.rs +shop Product shop_product shop/Product shop/Product m_product 有 shop.rs +books Book book_shop_book books/Book books/Book m_book 有 books.rs +asset DataResource asset_data_resource asset/DataResource asset/DataResource m_resource 有 asset.rs + +[ENDPOINT] +# face method path guard owner +# face = A(面A 专属) / B(面B 专属) / AB(两面共用,按判别头 `Vue-Version: 3` 分流) +# guard = 无 / 登录 / 面A 的菜单路径 key / 面B 的点权限编码 `f_en_code` +# owner = platform(平台层) / 业务模块代号(demo|shop|books) ⇒ 路由注册在哪个文件 +# path = 与代码**逐字**一致(axum 0.8 的 `{param}` 花括号语法) +A GET /api/health 无 platform +A POST /api/oauth/Login 无 platform +AB GET /api/oauth/CurrentUser 登录 platform +A GET /api/ssw/sys/User/List system/User platform +A POST /api/ssw/sys/User/Save system/User platform +A DELETE /api/ssw/sys/User/Delete system/User platform +A GET /api/ssw/sys/Role/List system/Role platform +A POST /api/ssw/sys/Role/Save system/Role platform +A DELETE /api/ssw/sys/Role/Delete system/Role platform +A GET /api/ssw/sys/Role/Modules 登录 platform +A GET /api/ssw/sys/Organize/List system/Organize platform +A POST /api/ssw/sys/Organize/Save system/Organize platform +A DELETE /api/ssw/sys/Organize/Delete system/Organize platform +A GET /api/ssw/sys/Module/List system/Module platform +A POST /api/ssw/sys/Module/Save system/Module platform +A DELETE /api/ssw/sys/Module/Delete system/Module platform +AB PUT /api/permission/Authority/Data/{objectId} 登录 platform +A GET /api/permission/Authority/RoleModules 登录 platform +B GET /api/permission/Users permission.user platform +B POST /api/permission/Users permission.user platform +B GET /api/permission/Users/{id} permission.user platform +B PUT /api/permission/Users/{id} permission.user platform +B DELETE /api/permission/Users/{id} permission.user platform +B POST /api/permission/Users/BatchDelete permission.user platform +B POST /api/permission/Users/BatchUpdateState permission.user platform +B GET /api/permission/Users/{id}/GetPosition permission.user platform +B POST /api/permission/Users/{id}/Actions/ResetPassword permission.user platform +B PUT /api/permission/Users/{id}/Actions/unlock permission.user platform +B GET /api/permission/Role permission.role platform +B GET /api/permission/Organize/AsyncList/{id} permission.organize platform +B GET /api/system/Menu/ModuleBySystem permission.menu platform +B POST /api/permission/Authority/Data/{objectId}/Values 登录 platform +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 +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/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 + +[FACE] +# face 条数 说明 +A 28 面 A 专属(+ 2 条共用 ⇒ 面 A 合计 30 条) +B 14 面 B 专属(官方 JNPF 形状) +AB 2 两面共用(CurrentUser / Authority Data —— 按判别头分流) + +[OFFICIAL] +# 官方端点台账 —— 本仓对**官方 JNPF 契约面**的覆盖账本(机器可读) +# method = HTTP 方法;`*` = 端点**一族**(范围声明,不做存在性对账) +# path = 官方路径(axum 0.8 的 `{param}` 花括号语法) +# status = implemented(已落地且形状对齐) / partial(已落地但**形状有偏差**,见 note) +# / absent(未实现,可后置) / oos(v1 明确不做,不进覆盖分母) +# src = 官方出处(`文件:行号` ⇒ 由 `scripts/check-citations.sh` 逐条核对) +# note = 偏差/取舍说明 +# +# 🔴 由 `scripts/check-contract.sh` 的 **CC10** 与代码真实路由**双向**对账: +# implemented/partial 的必须真的注册了;absent/oos 的必须**没有**注册; +# 反向:代码里**面 B / 共用**的每条路由都必须在本台账里**有账**。 +# 覆盖 N/M = (implemented + partial) / (implemented + partial + absent)。 +POST /api/oauth/Login partial LoginController.java:117 路径与入参逐字一致;返回的是面 A 形状(token 同名同义),官方 LoginVO 的 theme/wlQrcode/isSaas/saasList 未返 +POST /api/oauth/Logout absent LoginController.java:155 登出未做(token 是进程内内存表,进程退出即失效) +GET /api/oauth/CurrentUser partial LoginController.java:192 面 B 返 PcUserVO 5 字段;sysConfigInfo 返空对象、currentSystemId 固定、按钮级权限恒空、permissionList 按菜单给 +GET /api/permission/Users implemented UserController.java:293 面 B 已落地:PageListVO 形状、列表项无 password/secretkey、isAdministrator 是数字 +GET /api/permission/Users/{id} implemented UserController.java:355 面 B 已落地:UserInfoVO 形状(Form.vue 的 field 逐字对齐),无 password/secretkey +POST /api/permission/Users implemented UserController.java:409 面 B 已落地:白名单写库 + 账号查重 + 默认口令 md5(123456),返回 `{id}` +PUT /api/permission/Users/{id} implemented UserController.java:429 面 B 已落地:**只 SET body 里出现的键**(未出现的列保持原值) +DELETE /api/permission/Users/{id} implemented UserController.java:496 面 B 已落地:软删(f_delete_mark=1),幂等 +POST /api/permission/Users/BatchDelete implemented UserController.java:592 面 B 已落地:一条 UPDATE … IN ⇒ 原子;空集合返成功 +POST /api/permission/Users/BatchUpdateState implemented UserController.java:694 面 B 已落地:批量改 f_enabled_mark +GET /api/permission/Users/All absent UserController.java:729 全量用户未做 +GET /api/permission/Users/Selector absent UserController.java:769 用户下拉未做 +POST /api/permission/Users/UserCondition absent UserController.java:806 用户条件查询未做 +GET /api/permission/Users/{id}/GetPosition implemented UserController.java:273 面 B 已落地:无 base_position 表 ⇒ 由 f_position_id 反推,包成 `[{id}]` +POST /api/permission/Users/{id}/Actions/ResetPassword implemented user.ts:37 面 B 已落地:body.password ⇒ md5;兼容 newPassword +PUT /api/permission/Users/{id}/Actions/unlock implemented user.ts:45 面 B 已落地:清 f_lock_mark / f_unlock_time / f_log_error_count +GET /api/permission/Users/ExportData oos user.ts:53 导入导出族(官方前端按需)—— v1 明确不做 +GET /api/permission/Users/TemplateDownload oos user.ts:57-69 导入导出族 —— v1 明确不做 +POST /api/permission/Users/ImportData oos user.ts:57-69 导入导出族 —— v1 明确不做 +POST /api/permission/Users/ImportPreview oos user.ts:57-69 导入导出族 —— v1 明确不做 +GET /api/permission/Users/ExportExceptionData oos user.ts:57-69 导入导出族 —— v1 明确不做 +POST /api/permission/Users/getUserList absent user.ts:49 批量选择族(可后置,未列入 v1 范围也未明确排除) +POST /api/permission/Users/getSelectedList absent user.ts:73 批量选择族(可后置) +POST /api/permission/Users/getSelectedUserList absent user.ts:77 批量选择族(可后置) +GET /api/permission/Role implemented RoleController.java:99-100 面 B 已落地:PageListVO 形状 +GET /api/permission/Role/{id} absent RoleController.java:273 角色详情未做 +POST /api/permission/Role absent RoleController.java:122 官方建角色未做 +PUT /api/permission/Role/{id} absent RoleController.java:165 官方改角色未做 +DELETE /api/permission/Role/{id} absent RoleController.java:298 官方删角色未做 +GET /api/permission/Role/Selector absent RoleController.java:327 角色下拉未做 +POST /api/permission/Role/RoleCondition absent RoleController.java:342 角色条件查询未做 +GET /api/permission/Organize/AsyncList/{id} partial OrganizeController.java:107-110 面 B 已落地:按父 id 逐层取,但**不分页**(pageSize = 本层条数) +GET /api/permission/Organize absent organize.ts:14 官方机构列表未做 +GET /api/permission/Organize/{id} absent OrganizeController.java:290 机构详情未做 +POST /api/permission/Organize absent OrganizeController.java:179 官方建机构未做 +PUT /api/permission/Organize/{id} absent OrganizeController.java:212 官方改机构未做 +DELETE /api/permission/Organize/{id} absent OrganizeController.java:315 官方删机构未做 +GET /api/permission/Organize/Selector absent OrganizeController.java:145 机构下拉未做 +POST /api/permission/Organize/SelectedList absent OrganizeController.java:341 机构已选列表未做 +GET /api/system/Menu/ModuleBySystem implemented ModuleController.java:121 面 B 已落地:ListVO 形状(不是裸数组)、节点 15 字段 +GET /api/system/Menu/{systemId}/TreeView absent ModuleController.java:332 管理端菜单树未做 +GET /api/system/Menu/Selector/{id} absent ModuleController.java:267 上级菜单下拉未做 +GET /api/system/Menu/Selector/All absent ModuleController.java:444 菜单下拉全量未做 +POST /api/system/Menu absent ModuleController.java:169-170 官方建菜单未做 +PUT /api/system/Menu/{id} absent ModuleController.java:194-195 官方改菜单未做 +GET /api/system/Menu/{id} absent ModuleController.java:248-249 菜单详情未做 +DELETE /api/system/Menu/{id} absent ModuleController.java:228-229 官方删菜单未做 +PUT /api/system/Menu/{id}/Actions/State absent ModuleController.java:498-499 菜单启停未做 +POST /api/permission/Authority/Data/{objectId}/Values partial AuthorizeController.java:99-100 面 B 已落地:官方完整 body 真落库、读是 POST;但 list(权限树模型)返空数组 +PUT /api/permission/Authority/Data/{objectId} partial AuthorizeController.java:159-160 两面共用(按判别头分流);list(权限树模型)返空数组 +GET /api/permission/Authority/Model/{itemId}/{objectType} absent AuthorizeController.java:124-125 权限树模型读取未做 +PUT /api/permission/Authority/Model/{portalManageId} absent AuthorizeController.java:138-139 权限树模型保存未做 +* /api/system/ModuleDataAuthorizeLink/** oos authorize.ts:4 低代码数据权限方案(表/字段级)—— v1 明确不碰 + +[RULER] +# name 期望断言数(尺子**自己**断言的条数;跑出来的条数对不上 ⇒ 失败) +# 43 = react 版对齐的 32 条 + 真实业务模块 asset/DataResource 9 条 + 多应用 2 条 +# (无 App-Code ⇒ 主系统 / App-Code: app-b ⇒ app-b) +perm-smoke.sh 43 +# 23 = 原 18 条 + 多应用 1 条(App-Code: app-b ⇒ currentSystemId = app-b,与面 A 同一口径) +# + 用户 CRUD 4 条(详情无口令 / 改档只 SET 出现的键 / 批量启停 + 软删) +perm-smoke-jnpf.sh 23 +# 🔴 本仓是**后端-only**(CLAUDE.md §2.2:前端/移动端本期不动,沿用 Java 版)⇒ +# check-module 的「前端接触点」(4 模块 × 4 处 + 全局面 A 判别头)按 N/A 打 `⏭` +# 且**仍计入条数**;114 = 4 模块 × 28 条 + 全局面 B 判别头 1 条 + 全局面 A 判别头 1 条。 +# (脚手架原版口径 93 = 3 模块含真实前端的条数,本仓无 src/frontend,不适用。) +check-module.sh 114 +check-boundary.sh 11 +check-contract.sh 10 +check-citations.sh 4 +``` + diff --git a/docs/ddl/base_ddl_raw.sql b/docs/ddl/base_ddl_raw.sql new file mode 100644 index 0000000..acdf31b --- /dev/null +++ b/docs/ddl/base_ddl_raw.sql @@ -0,0 +1,206 @@ +-- ===== base_authorize ===== (source lines 812-829) +CREATE TABLE base_authorize ( + f_id VARCHAR(50) NOT NULL, + f_item_type VARCHAR(50), + f_item_id VARCHAR(50), + f_object_type VARCHAR(50), + f_object_id VARCHAR(50), + f_sort_code BIGINT, + f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_creator_user_id VARCHAR(50), + f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_last_modify_user_id VARCHAR(50), + f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_delete_user_id VARCHAR(50), + f_delete_mark INTEGER, + f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, + f_org_id VARCHAR(50), + PRIMARY KEY (f_id, f_tenant_id) +); + +-- ===== base_module ===== (source lines 2209-2240) +CREATE TABLE base_module ( + f_id VARCHAR(50) NOT NULL, + f_parent_id VARCHAR(50), + f_type INTEGER, + f_full_name VARCHAR(200), + f_en_code VARCHAR(200), + f_category VARCHAR(50), + f_url_address VARCHAR(500), + f_icon VARCHAR(500), + f_link_target VARCHAR(50), + f_is_button_authorize INTEGER, + f_is_column_authorize INTEGER, + f_is_data_authorize INTEGER, + f_is_form_authorize INTEGER, + f_module_id VARCHAR(50), + f_system_id VARCHAR(50), + f_property_json TEXT, + f_description VARCHAR(500), + f_enabled_mark INTEGER, + f_sort_code BIGINT, + f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_creator_user_id VARCHAR(50), + f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_last_modify_user_id VARCHAR(50), + f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_delete_user_id VARCHAR(50), + f_delete_mark INTEGER, + f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, + f_page_address VARCHAR(500), + f_no_show INTEGER DEFAULT 0, + PRIMARY KEY (f_id, f_tenant_id) +); + +-- ===== base_organize ===== (source lines 3178-3201) +CREATE TABLE base_organize ( + f_id VARCHAR(50) NOT NULL, + f_parent_id VARCHAR(50), + f_category VARCHAR(50), + f_en_code VARCHAR(200), + f_full_name VARCHAR(200), + f_manager_id VARCHAR(50), + f_property_json TEXT, + f_organize_id_tree TEXT, + f_description VARCHAR(500), + f_enabled_mark INTEGER, + f_sort_code BIGINT, + f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_creator_user_id VARCHAR(50), + f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_last_modify_user_id VARCHAR(50), + f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_delete_user_id VARCHAR(50), + f_delete_mark INTEGER, + f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, + f_duty_position VARCHAR(50), + f_org_name_tree TEXT, + PRIMARY KEY (f_id, f_tenant_id) +); + +-- ===== base_role ===== (source lines 3686-3707) +CREATE TABLE base_role ( + f_id VARCHAR(50) NOT NULL, + f_full_name VARCHAR(200), + f_en_code VARCHAR(200), + f_type VARCHAR(50), + f_property_json TEXT, + f_global_mark INTEGER, + f_description VARCHAR(500), + f_enabled_mark INTEGER, + f_sort_code BIGINT, + f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_creator_user_id VARCHAR(50), + f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_last_modify_user_id VARCHAR(50), + f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_delete_user_id VARCHAR(50), + f_delete_mark INTEGER, + f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, + f_is_condition INTEGER, + f_condition_json TEXT, + PRIMARY KEY (f_id, f_tenant_id) +); + +-- ===== base_role_relation ===== (source lines 3729-3744) +CREATE TABLE base_role_relation ( + f_id VARCHAR(50) NOT NULL, + f_role_id VARCHAR(50), + f_object_type VARCHAR(50), + f_object_id VARCHAR(50), + f_sort_code BIGINT, + f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_creator_user_id VARCHAR(50), + f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_last_modify_user_id VARCHAR(50), + f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_delete_user_id VARCHAR(50), + f_delete_mark INTEGER, + f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, + PRIMARY KEY (f_id, f_tenant_id) +); + +-- ===== base_user ===== (source lines 4479-4542) +CREATE TABLE base_user ( + f_id VARCHAR(50) NOT NULL, + f_account VARCHAR(50), + f_real_name VARCHAR(50), + f_quick_query VARCHAR(100), + f_nick_name VARCHAR(50), + f_head_icon TEXT, + f_gender VARCHAR(50), + f_birthday TIMESTAMP(0) WITHOUT TIME ZONE, + f_mobile_phone VARCHAR(20), + f_tele_phone VARCHAR(20), + f_landline VARCHAR(50), + f_email VARCHAR(50), + f_nation VARCHAR(50), + f_native_place VARCHAR(50), + f_entry_date TIMESTAMP(0) WITHOUT TIME ZONE, + f_certificates_type VARCHAR(50), + f_certificates_number VARCHAR(50), + f_education VARCHAR(50), + f_urgent_contacts VARCHAR(50), + f_urgent_tele_phone VARCHAR(50), + f_postal_address VARCHAR(500), + f_signature VARCHAR(500), + f_password VARCHAR(50), + f_secretkey VARCHAR(50), + f_first_log_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_first_log_ip VARCHAR(50), + f_prev_log_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_prev_log_ip VARCHAR(50), + f_last_log_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_last_log_ip VARCHAR(50), + f_log_success_count INTEGER, + f_log_error_count INTEGER, + f_change_password_date TIMESTAMP(0) WITHOUT TIME ZONE, + f_language VARCHAR(50), + f_theme VARCHAR(50), + f_is_administrator INTEGER, + f_manager_id VARCHAR(50), + f_organize_id VARCHAR(50), + f_position_id VARCHAR(50), + f_role_id TEXT, + f_portal_id TEXT, + f_lock_mark INTEGER, + f_unlock_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_group_id VARCHAR(50), + f_handover_mark INTEGER, + f_app_system_id VARCHAR(50), + f_description VARCHAR(500), + f_enabled_mark INTEGER, + f_sort_code BIGINT, + f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_creator_user_id VARCHAR(50), + f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_last_modify_user_id VARCHAR(50), + f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_delete_user_id VARCHAR(50), + f_delete_mark INTEGER, + f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, + f_handover_userid VARCHAR(100), + f_rank VARCHAR(50), + f_standing VARCHAR(50), + f_app_standing VARCHAR(50), + PRIMARY KEY (f_id, f_tenant_id) +); + +-- ===== base_user_relation ===== (source lines 4707-4722) +CREATE TABLE base_user_relation ( + f_id VARCHAR(50) NOT NULL, + f_user_id VARCHAR(50), + f_object_type VARCHAR(50), + f_object_id VARCHAR(50), + f_sort_code BIGINT, + f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_creator_user_id VARCHAR(50), + f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_last_modify_user_id VARCHAR(50), + f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE, + f_delete_user_id VARCHAR(50), + f_delete_mark INTEGER, + f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL, + PRIMARY KEY (f_id, f_tenant_id) +); + diff --git a/docs/decisions.md b/docs/decisions.md new file mode 100644 index 0000000..7c477bc --- /dev/null +++ b/docs/decisions.md @@ -0,0 +1,975 @@ +# 决策记录(ssw-jnpf-lite-rust · 分支级) + +> 本文件是 **`ssw-jnpf-lite-rust` 从零实现全过程中控制器(controller)逐条作出的裁决**, +> 格式统一为「**裁决了什么 — 为什么 — 判错了的代价**」。 +> 它是**代码之外的「为什么」**:`docs/contract.md` 说什么必须成立,本文件说**为什么这样实现**、 +> **哪些分歧被有意留下**、**哪些判断是带风险的**。 + +🔴 **来源**:SDD 过程 ledger(`.superpowers/sdd/ssw-jnpf-lite-rust-v1/progress.md`)—— 那份 ledger 是 +**git-ignored 的过程草稿**,交付时已清理;本文件是它的**受版本控制的正本**(只保留裁决正文, +不含逐条验证输出与任务流水)。 + +**编号**: +- `P##` = 逐任务实施期的裁决(Plan 阶段起的第 P 批); +- `F##` = **最终整体评审**(Final review)的裁决 —— 那一轮把 15 条评审发现压成 11 条裁决 + + 后续修复轮追加的 F11/F12。 + +**配套阅读**: +- 契约(权威)→ [`docs/contract.md`](contract.md) +- 交接文档(设计 / 四门 / 风险)→ [`../HANDOFF.md`](../HANDOFF.md) +- 分支级已知限制(被「接受/挂起」的东西)→ [`known-limitations.md`](known-limitations.md) + +--- + +**Ruling F1(I-2 的机制陈述被推翻,但加固照做)** —— +评审的因果链(npm 只向直接子进程发信号 ⇒ SIGTERM 到不了 vite)**实测不成立**: +`kill -TERM ` ⇒ npm 与 vite 双双死、5173 被释放。 +但 runbook 承诺的「不会在 5173 上留残进程」应当**无条件**为真 ⇒ 失败分支补 `kill_ports 5173`。 +**代价**:一行;`kill -9` 只作用于**本仓自己的 5173**(`kill_ports` 的端口清单硬约定)。 + +**Ruling F2(M-10 不是契约缺陷)** —— +契约全文对「原子/事务/atomic」**零提及** ⇒ 契约只要求「单次调用原子」。 +M-10 是 known-limitation (b)(「`Db` 没有跨调用持锁的公开接口 ⇒ 多步写不是单一事务」, +P59/P71 已裁决)的**具体实例**,不是新缺陷 ⇒ 不改代码,把具体场景写进 (b) 的代价栏。 +**代价**:`user_save` 步骤 2 失败 ⇒ 用户行已提交、角色关系没写 ⇒ 响应 `code=400` 而库里已有该用户。 + +**Ruling F3(M-6 只能改文档)** —— +契约 §6.1(line 448)**逐字定死** `{token, expiresIn: 7200, tokenTypeName:'bearer'}` ⇒ 代码不许改。 +`session.rs` 无 TTL ⇒ token 实际寿命 = **进程寿命**;`expiresIn: 7200` 是**继承自 JNPF/Sa-Token 的语义**、非强制值。 +⇒ 改文档 + known-limitations 新增一行。**代价**:文档要如实说明「7200 不会真的到期」。 + +**Ruling F4(M-1 的三处文档断言是假的)** —— +`%zz` 实测 ⇒ HTTP 200 + 正常信封 ⇒ known-limitations (l) 的「纯文本 400」**不存在**。 +⇒ **就地改写**该行(先例:(u) 就是这么处理的:标「已推翻」+ 给实测),并同步 `README.md` / `HANDOFF.md`。 +**代价**:无(去掉一条不存在的限制)。 + +**Ruling F5(I-3:默认绑 `127.0.0.1`,`BIND_ADDR` 可覆盖)** —— +全部文档写的都是 `http://127.0.0.1:30010`,代码却绑 `0.0.0.0` ⇒ **文档与代码不符**; +且「admin/123456 + 口令永不过期 + 全网卡监听」= 局域网可直连的弱口令服务 ⇒ 默认改回 `127.0.0.1`, +新增 env `BIND_ADDR`(非法值回落 `127.0.0.1`,**朝安全方向**回落)。 +**代价**:容器/反代场景要显式 `BIND_ADDR=0.0.0.0`(写进 `.env.example`)。 + +**Ruling F6(M-8:413 归一为信封,传输状态码保留)** —— +契约 §2「没有第三种形状」管的是**信封**;§6.5 对 404/405 采取「**传输状态码保留 + body 归一为信封**」, +且**未覆盖 413** ⇒ 照 405 的先例:**HTTP 413 + `{code:413,msg:'请求体过大',data:null}`**。 +🔴 `msg` 是**本仓自定**(契约未规定 413 的文案)⇒ 记在此处,契约不因此改动。 + +**Ruling F7(M-9:优雅停机)** —— +`run.sh stop` 发 SIGTERM → 1s → SIGKILL;后端**忽略 SIGTERM** ⇒ **每一次 stop 都是 SIGKILL 掉嵌入式 PG** +(下次启动要 crash recovery,数据目录还留 `postmaster.pid`)。 +⇒ 装 SIGTERM/SIGINT 处理 → `axum::serve(...).with_graceful_shutdown(...)` → 退出前调 pglite 的 +`PGlite::shutdown(&self)`(pglite-rs 0.2.7 `src/db.rs:444` 确有此方法)。 +**代价**:`main.rs`/`db.rs` 多 ~20 行;tokio 的 `signal` feature 已在 `features=["full"]` 里 ⇒ **不新增依赖**。 + +**Ruling F8(M-7 挂起)** —— +口令比对非常量时间**不是契约缺陷**、也**不是文档与代码不符**;HTTP 上对 md5-hex 比对的计时攻击收益可忽略; +而这轮要在**最后一道门**上动**最敏感的文件**(`auth.rs` 的登录路径)⇒ 风险 > 收益。 +⇒ 挂起,记为 known-limitations 新行(写清代价与将来要改的形状)。 +**代价**:留下一个理论上的计时侧信道(实际不可利用)。 + +**Ruling F9(M-11 / M-12 已覆盖)** —— 分别落在 (f) / (e) 内 ⇒ 不新增行,只把具体例子补进去。 + +**Ruling F10(契约在分支内被改过 13 次这件事本身要记档)** —— +评审说「契约从未被修改」**不准确**:`git log --oneline -- docs/contract.md | wc -l` = **14** +(初次提交 `0aed12a` 之后 13 次修订:`6b8c30e 4a7805a c927632 1db2f0a 0de161d f44b300 28de290 +349aeef 0fef2fb aa45da8 a77d8c1 15469ea c055e1b`)。 +评审自己核过其中一次(`c055e1b` 把 DB 报错的措辞**朝 react 参照物**修正)⇒ 修订都是**收紧**而非放松。 +⇒ 合规判据是**最终的 §编号正文**;这一点记在此处,让轨迹可见。**代价**:无。 + +**Ruling P1 — 官方 DDL 可逐字使用。** 官方 JNPF dump 里 7 张 `base_*` 表除 `f_id`/`f_tenant_id` 外**没有其它 NOT NULL 列**, +整份 dump **零 UNIQUE 约束** ⇒ 直接逐字入库,不改列名/类型/约束。 +代价:若实现时发现某列有隐式 NOT NULL,插入会报 23502 —— 表现为运行期错误,不是契约错误。 + +**Ruling P2 — 禁止 `SELECT *`,全部显式列投影。** 官方 DDL 有 30~60 列,react 版库(TypeORM `synchronize`)只有 entity 的列。 +显式投影让本仓后端**能开 react 建出来的库**("两版后端可开同一个库"要成立就必须这样), +且响应 JSON 与 react 逐字相同。代价:每个查询要多写列名;新增列要同步改 spec。 + +**Ruling P3 — `PGLITE_DIR=memory://` ⇒ `PGlite::open_temp()`。** pglite-rs 0.2.7 **没有**内存模式, +`PGlite::open()` 只接受路径。项目 `CLAUDE.md` 里"纯内存"那句与现实不符 ⇒ 实现按 `open_temp()` 落地, +并**在 `CLAUDE.md` 里更正那句话**(Task 12 一并改)。代价:`open_temp()` 是临时目录,不是纯内存,进程退出即丢。 + +**Ruling P4 — 拆 `src/lib.rs` + `src/main.rs`。** lib 供集成测试 `use ssw_jnpf_lite_rust::…`; +bin 是薄壳(`fn main() { ssw_jnpf_lite_rust::run() }`)。计划文字只提了 `main.rs` ⇒ 按此裁决加 `lib.rs`。 +代价:多一个文件。不影响 HTTP 契约。 + +**Ruling P5 — `resolve_project_dir()` 锚点改为 `src/backend/db/schema.sql` + 根 `Cargo.toml`。** +计划文字提到 `static/` 锚点,但本仓**没有** `static/`(前端跑 Vite `:5173`)⇒ 锚点无效。 +代价:无。锚点文件换成了真实存在的两个。 + +**Ruling P6 — 时间列:存 UTC 朴素、读出投影 ISO `...Z`。** 官方 DDL 是 `TIMESTAMP(0) WITHOUT TIME ZONE`(秒精度), +react entity 声明的是 `timestamptz`。用 `TIMESTAMP(0)` 口径 + `to_char(...)||'Z'` 投影, +与 react 的 ISO 串(`2026-01-01T00:00:00.000Z`)**不完全相同**(无毫秒)。 +冒烟断言不依赖时间格式 ⇒ 可接受。代价:与 react 的时间串差一个毫秒位。 + +**Ruling P7 — 业务表不加 `f_tenant_id`。** react 版 3 张业务表 entity 没有该列 ⇒ 加了会让 +"两版后端开同一个库"的 INSERT 报列不存在。`base_*` 全部保留 `f_tenant_id`(官方 DDL 有)。 +代价:业务表与 `base_*` 口径不一致 —— 这是刻意的(对齐 react)。 + +**Ruling P8 — `base_authorize` / `base_role_relation` / `base_user_relation` 允许插入时 +`f_creator_time` 等官方列留空。** 官方 DDL 这些列可空 ⇒ 不必全填。省事且不违反契约。 + +**Ruling P9 — User Save 的响应剥掉 `password`(唯一一处与 react 刻意偏离)。** +react 的 `saveUser` 直接返回 TypeORM 的 saved entity,**带着 `password` 列的 md5 摘要**。 +该摘要可被前端 `cipher.ts` 重新加密成**合法登录密文** ⇒ 响应里出现它等于泄露凭据。 +R1.6(口令不得外泄)**优先于**与 react 的逐字一致 ⇒ 本仓 List 与 Save **都**剥。 +代价:与 react 的 Save 响应少一个字段;前端 `UserManage` 从不读 `password` ⇒ 无功能影响。 +(已写进 `docs/contract.md` §7.7 偏离表。) + +**Ruling P10 — 授权端点**忽略 body 里的 `objectType`,一律写 `f_object_type='role'`。 +react 的 `AuthorizeController.save` **只读 `body.module`**,从不读 `body.objectType`; +落库的 `objectType` 是 `saveRoleModules` 里**硬编码**的 `'role'`。 +原计划文字说"objectType 必须小写,否则写不进去" —— 对 react **不成立**(它根本不看这个字段)。 +本仓按 react 实际行为实现:忽略该字段、不校验大小写。 +代价:与 JNPF 官方语义(官方会静默忽略大写)**恰好一致**,无需额外校验。 + +**Ruling P11 — §7 整节按 react 源码逐字重写(2026-10-25)。** +读完 `sys.service.ts` / `auth.service.ts` / `authorize.controller.ts` / 三个业务 service 后, +发现原 §7 有 9 处与源码不符,全部修正(记录在 `docs/contract.md` §7 的各条括号里): +User 更新也查重 / User 更新**总是**覆盖 `isAdministrator` 与 `organizeId` / +Role 更新**不**查重**不**碰 `sortCode`·`enabledMark` / Role 删除**不**带 `f_item_type` 过滤 / +Module 删除**不**带 `f_object_type` 过滤 / Organize·Module **不写** `f_creator_user_id` / +业务模块保存有**三条**路径(无 id / 有 id 但行不存在 / 有 id 且存在)/ +`roleNames` 查不到就**跳过**(数组可能比 `roleIds` 短)。 + +**Ruling P12 — 业务表只有 `f_delete_mark` 带 DB 默认值 `DEFAULT 0`。** +react entity 上 `deleteMark` 有 `default: 0`;§7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建) +靠这个默认值补出 `0`,其余列"body 没给 ⇒ NULL" ⇒ **其它业务列一律不得有默认值**。 +🔴 **本条已被 P18 部分推翻**:`book_shop_book.f_stock` 在 react 的 entity 上**也有** `default: 0`, +⇒ 它也带 DB 默认值。P12 当时只看了 `deleteMark` 就推广到全部列,属推理漏洞(已由 P18 修正)。 + +**Ruling P13 — 未捕获异常(panic / DB 报错)也走业务信封:HTTP 200 + `code=400` + `msg='系统异常,请联系管理员'`。** +react 的全局 `ActionResultFilter` 兜底分支就是这个形状(真实堆栈只进服务端日志,不外泄)。 +Rust 侧若放任 axum 默认的 **HTTP 500 空 body**,前端 `request.ts` 的错误分支只会拿到 +"Request failed with status code 500",**丢掉了 `msg`** ⇒ 与 react 行为不一致。 +⇒ 必须在链尾装 catch-all 中间件(§6.5 / §10 第 6 步)。 +同时把 **405 的 HTTP 状态定死为 405**(保留 `Allow` 头)—— +react 侧 Express 路由对错误方法返 404,但前端从不发错方法 ⇒ 不在契约面上; +定成 405 是「传输层状态码保留」,比掉进 R1.2 的 HTTP 200 规则更清楚。 +代价:多一个中间件;契约面(前端实际会发的请求)零影响。 + +**Ruling P14 — `src/backend/src/lib.rs` 的唯一 owner 是 Task 4。** +Task 0 评审发现「`lib.rs` 声明完毕不再改」与「§9 要求 `AppState` 落在 `lib.rs`(或新 `state.rs`)」有潜在冲突: +两条路都会逼后续任务改 `lib.rs`,两个任务并行改就撞 CLAUDE.md 红线 8(同文件并行 Edit = last-writer-wins)。 +裁决:`AppState` 放**独立 `src/backend/src/state.rs`**;`lib.rs` 只加**一行** `pub mod state;`, +由 **Task 4(ids + session)** 一次性落地 —— 它是 `AppState` 三个依赖(`Config`/`Db` 来自 Task 3、 +`SessionStore` 来自 Task 4)里最后就位的。Task 1/2/3 **一律不许碰 `lib.rs`**;Task 5+ 只读不写。 +代价:多一个文件(`state.rs`);换来 `lib.rs` 全程只有一个写入者。 + +**Ruling P15 — `decrypt_to_md5` 返回 `None` ⇒ 登录端点回 `400 '账号或密码错误'`(与 react 同形)。** +react 的 `decryptToMd5` 遇非法 hex / 非法填充返回**空串** ⇒ 与库里 md5 比对不等 ⇒ 抛 `账号或密码错误`。 +⇒ 本仓的 `None` 必须映射到**同一条消息**,不另造「密文格式错误」。 +同时**不加**「解密结果长度必须 == 32」的额外校验(react 没有,加了只会与 react 不一致)。 +Task 1 实现者的 concern①/② 就按这条关掉。 + +**Ruling P16 — 种子失败 ⇒ 打印人话错误 + `exit 1`(启动期 fail-fast),不学 react 的「warn 后继续跑」。** +react 的 `SeedService.onModuleInit` 是 try/catch + `logger.warn`(因为它是 NestJS 容器里已挂载的应用,退不出去)。 +本仓是**单二进制**:种子失败 ⇒ 没有 admin 用户 ⇒ 整个应用 100% 不可用 ⇒ 半死不活地跑着只会让人对着 403 猜。 +与 §10 第 3 步「白名单自检不过 ⇒ 秒退」同一处置。 +这条**不在 HTTP 契约面上**(服务要么正常起来,要么根本不起来)⇒ 不影响与 react 的契约对齐。 + +**Ruling P17 — `ensure_base()` 的三处「不过滤软删」必须逐字照抄 react。** +读 `seed.service.ts` 源码后发现 react 的三处查询**都不带 `deleteMark` 条件**: +① 判「内置角色已存在」查 `base_role` 全部行(软删的 `admin` 角色也算存在 ⇒ 不补); +② 判「内置菜单已存在」查 `base_module` 全部行(软删的也不复活); +③ 判「admin 角色已授权」查 `base_authorize` 全部行(软删的授权行也算已授权 ⇒ 不补)。 +另:`f_object_id='admin'`(**账号名,不是 UUID**)也照抄。 +⇒ 规格 §8.6 已按源码逐字重写。 + +**Ruling P18 — 业务表 DDL 逐字对齐 react 的 TypeORM entity(2026-10-25,Task 3 派发前发现)。** +读 react 的三个 business entity 源码,发现计划的业务表 DDL 有 3 处与 react 不一致: +① `demo_item.f_status` react 是 **varchar(32)**,计划写 50; +② `book_shop_book.f_isbn` react 是 **varchar(32)**,计划写 50; +③ `book_shop_book.f_stock` react 的 entity 上有 **`default: 0`**(⇒ TypeORM 建的库带 `DEFAULT 0`), + 计划却写「业务表只有 `f_delete_mark` 有 DB 默认值」⇒ 计划自己的 P12 推理漏了 stock。 +③ 是**真契约分歧**:§7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建)在 react 里 `f_stock` 得 **0**, + 按计划实现会得 **NULL** ⇒ 响应不同。 +裁决:业务表 DDL **逐字照抄 react entity**(列宽 + 默认值都照抄)—— +理由是「两版后端可开同一个库」要求两张表是**同一张表**,否则 react 的 `synchronize` 会 `ALTER` 掉我们建的列。 +⇒ 规格 §5.1 已补业务表逐字 DDL 表;§7.6 路径 2 已把 `f_stock` 改成「没给 ⇒ 0」。 +代价:`f_status` / `f_isbn` 收窄到 32 —— react 的库本来就是 32,收窄零风险。 + +**Ruling P19 — 去掉 release 的 `panic = "abort"`,改 `unwind`;catch-all 中间件自己手写,不引新依赖。** +发现 P13(panic ⇒ HTTP 200 + `code=400`)与 Task 0 在根 `Cargo.toml` 里定的 +`[profile.release] panic = "abort"` **直接冲突**: +`panic = "abort"` 下 `std::panic::catch_unwind` **抓不到 panic**(进程直接 abort), +⇒ panic 时客户端拿到的是**连接重置**(连 HTTP 500 都没有),比 axum 默认还差。 +而 react 侧 Node 抛异常**不会**终止进程(NestJS 全局 filter 接住)⇒ 与 react 对齐必须是「接住」不是「崩掉」。 +裁决: +① 根 `Cargo.toml` 去掉 `panic = "abort"`(回到默认 `unwind`); +② catch-all 中间件**手写**(约 25 行,`Pin>` + `std::panic::catch_unwind`,**无需 `unsafe`**) + ⇒ **不引 `tower` / `tower-http` / `futures`**(CLAUDE.md 的依赖集由 Task 0 锁死,加依赖要动根 Cargo.toml 重跑全量编译); +③ 「DB 报错」那条路**不走 panic 捕获** —— handler 返回 `Result`,`Err` 在**类型层**映射成 + `fail(400, "系统异常,请联系管理员")`(普通 `match`,零依赖)。 +代价:release 二进制略大(unwind 表 + 栈回溯信息);换来 panic 不再杀进程。 +落地:Task 10 brief 已写明中间件骨架。 + +**Ruling S11 — 集成测试**全文件共用一个 `Db` 实例**(pglite 进程级单实例约束)。** +pglite-rs 0.2.7 的 `OPEN` / `BOOTED` 是**进程级全局标志**:第二次 `open()` ⇒ `Error::AlreadyOpen`, +关掉再开 ⇒ `Error::ReopenUnsupported`。 +Rust test harness 把**同一个 `tests/*.rs` 里的所有 `#[tokio::test]` 放进同一个进程** +⇒ 原 brief 里「每个测试各开一个临时库 / 用不同子目录隔离」的做法**必然在第二个测试炸**。 +裁决: +① 每个 `tests/*.rs` 用一个 `tokio::sync::OnceCell` 起一次 `Db::open_temp()`,全文件共享; +② `cargo test` 每个 `tests/*.rs` 是**独立二进制 = 独立进程** ⇒ `seed_it.rs` / `sys_it.rs` / `crud_it.rs` + 各自一个库,**互不干扰** ✅(这正好把三组集成测试的库隔离开); +③ 测试间数据隔离靠**专属账号/编码/名称** + 需要干净前置条件时**自己先 `DELETE`**, + **不依赖测试执行顺序**。 +落地:Task 5 / 8 / 9 brief 已追加 S11 段。 + +**Ruling P20 — 承认两处「畸形密文」角落与 react 不同,不追平(2026-10-25,核对 react `cipher.ts` 时发现)。** +react 的 `decryptToMd5` 有两处**宽容**行为,本仓是**严格**的: +① `CryptoJS.enc.Hex.parse` 会**静默剔除**非 hex 字符 ⇒ `zz<合法密文>` 仍能解出; + Rust `hex::decode` 直接失败。 +② `CryptoJS.pad.Pkcs7.unpad` **不校验** padding(只看末字节数值就裁掉), + 且 `enc.Utf8.stringify` 遇非法 UTF-8 会 **throw `Malformed UTF-8 data`** + ⇒ react 控制器 catch 后回 `fail(400, "Malformed UTF-8 data")`。 +本仓:`hex::decode` 失败 / PKCS7 严格解包失败 / 非 UTF-8 ⇒ `decrypt_to_md5` 返回 `None` +⇒ 按 P15 回 `fail(400, "账号或密码错误")`。 +**观测差异只在畸形密文上**:`code` 都是 400、HTTP 都是 200,**只有 msg 不同**。 +正常路径(合法密文 / 错口令)**完全一致** ✅ —— 冒烟 32 条断言不涉及此路径。 +裁决:**不追平**。理由:react 的宽容是「意外」,不是契约;严格更安全。 +代价:若将来有客户端发畸形密文,msg 会与 react 不同(前端不依赖该 msg,只看 code)。 + +**Ruling P21** — 修复轮 R1 只动 `src/backend/src/cipher.rs`(加测试 + debug_assert)与报告措辞,**不改算法**。 +理由:评审明确「代码是对的,理由是伪造的」;改算法会危及「上游向量逐字节相等」这条硬约束。 +**代价**:P20 的两处畸形密文文案分歧**继续存在**(react 抛 "Malformed UTF-8 data"、 +本仓返 `None` ⇒ 登录端点文案 "账号或密码错误")—— 已由 P20 记录为有意分歧, +HTTP 状态与 `code` 相同、仅 `msg` 不同、无测试覆盖。 + +**Ruling P22** — 修复轮的提交**只 `git add` 显式路径**(`src/backend/src/cipher.rs`), +不碰 Task 3 实现者正在写的 `config.rs` / `db.rs` / `schema.sql` / `tests/`。 +理由:避免与并发实现者抢 git index(`index.lock` 冲突 ⇒ 对方提交失败)。 +**代价**:无(Task 3 的四个文件在 `d73b161` 后仍是未提交状态,已复核 `git status`)。 + +**Task 1: complete — `a7308af`(+ 修复轮 R1 `d73b161` / `08c2665`)** — cipher 三函数 + 11 条单测 +(含「PKCS7 填充不合法 ⇒ `None`」严格性钉住、上游向量双向断言);评审修复轮复审结论 +**All findings addressed, no new Critical/Important breakage**。 + +**Ruling P23** — 规格投影别名改为**带双引号**:`f_xxx AS ""`。 +修订 `docs/contract.md` §R1.4 / §4 / §5.2 / §5.3(提交 `0fef2fb`,独立提交,规格不漂移)。 +理由:加引号是**原生 PG 行为**(不依赖任何文本解析);未加引号依赖「谁来还原大小写」。 +**代价**:下游 5 个任务的 SQL 别名要加引号(多两个字符);已写进 Task 6–10 brief 的 **S12** 段。 + +**Ruling P24** — 保留 `db.rs` 的**键归一安全网**(别名还原 + `f_*`→camelCase), +但规格写明它是**安全网**、不是规范路径;规范写法(加引号)本身不依赖它。 +理由:防漏 —— 万一某处漏了引号,**不会静默产出小写键**;`db_it.rs:213-222` 已钉住两种写法都出 `realName`。 +**代价**:多一层 SQL 文本解析(`collect_alias_map`)在热路径上;已由实现者的单测覆盖 +(字符串/注释/dollar-quote 跳过、只收含大写的别名、已加引号的别名不收)。 + +**Ruling P25** — Task 3 的 concern②(业务表时间列 `TIMESTAMP(0)` vs react 的 TypeORM 默认精度 6) +按**已知无害偏离**处理,不改 DDL:契约 §5.1 已写死 `TIMESTAMP(0)`;列名/类型族不变, +两版后端开同一个库无碍;前端不用 `creatorTime`。concern③(`pub use pglite;`)是集成测试写带参 +SQL 的必要出口,**保留**。concern④(`split_sql_statements` 丢弃注释内容)规格未要求保留注释, +**接受**。concern⑤(未起 HTTP 服务)—— 装配链属 Task 10 的验收范围。 + +**Ruling P26** — 键归一安全网改为**作用域受限**扫描(原 `collect_alias_map` → `collect_alias_info`)。 +理由:评审实测两条**静默错值** —— `WITH c AS (SELECT 1 AS Title) SELECT f_title AS "title" FROM demo_item` +把契约键 `title` 静默改成 `Title`;`SELECT CAST(1 AS NUMERIC) AS "numeric"` 把 `numeric` 改成 `NUMERIC`。 +根因是「扫整条 SQL 的别名」与「拿结果对象的键查全局表」跨作用域混用 —— 安全网反而制造了 +§R1.4 要消灭的静默失败。改法:**只扫外层 SELECT 的投影列表**(第一个深度 0 的 `SELECT` → 第一个深度 0 的 `FROM`)、 +**只认相对深度 0 的 `AS`**(⇒ `CAST(x AS TYPE)`、CTE、子查询里的 `AS` 都不登记)、 +双引号别名进 `quoted` 集且**归一时优先于一切还原**、同名不同写法**放弃还原**。 +**代价**:多一层括号深度跟踪;`AS realName`(未加引号)这条兼容路径仍在(P24 的安全网保留), +但它现在**只对外层投影列表生效** —— 内层/子查询里的未加引号别名不再被还原(契约不依赖它)。 + +**Ruling P27** — `scalar_text` 按**列类型 OID 分派**;非文本/整数/布尔类型**返回 `Err`**(不猜)。 +理由:评审实测 `scalar_text("SELECT count(*) FROM base_user")` 返回 8 个 NUL(`String::from_sql` +不校验列类型、pglite 走 extended protocol 拿的是二进制格式)⇒ 下游 count/exists 判断会**静默判错**。 +分派:TEXT/VARCHAR/BPCHAR/NAME/UNKNOWN ⇒ 原样;INT2/INT4/INT8 ⇒ 十进制字符串;BOOL ⇒ `true`/`false`; +其余(numeric/timestamp/json…)⇒ `Err`,错误信息提示写 `::text`。 +**公开签名不变** ⇒ 下游 Task 6/8/9 不用改代码。**代价**:调用方写 `SELECT count(*)` 不加 `::text` +拿到的是**响亮的错误**而不是错的字符串 —— 这是有意的(宁可报错也不要静默判错)。 + +**Ruling P28** — `split_sql_statements` 遇到注释时往结果里推**一个空格**(原来什么都不推)。 +理由:评审实测 `SELECT 1/*x*/FROM t` 被切成 `SELECT 1FROM t`(token 粘连、语义变了)。 +当前 `schema.sql` 的注释都是整行 ⇒ 现在无害,但这是 `pub fn` ⇒ 下游可能踩。 +**代价**:无(切出的语句多一个空格,SQL 语义不变)。 + +**Ruling P29** — `exec`(simple protocol,可多语句、整批隐式事务)与 +`exec_params`(extended protocol,**只能单语句**)的能力不对等 ⇒ **只补 doc 注释,不改实现**。 +理由:brief 的 S1 明文要求 `exec_params` 建在 `query(sql, params)` 之上;改实现就得放弃参数。 +**代价**:调用方需自己知道 `exec_params` 不接受多语句(已写进 doc)。 + +**Ruling P30** — `Db::open` 与 `config::pg_is_temp()` 各判一次 `memory://` ⇒ **不改**。 +理由:评审自己确认「不是 bug」,两处都判是双重保险;改它要动 `config.rs`, +而本轮修复范围只给 `db.rs` + `db_it.rs`。**代价**:无。 + +**Task 3: 修复轮 R1 已派给实现者 `a5cdd71d7d46fd631`**(规格: +`.superpowers/sdd/ssw-jnpf-lite-rust-v1/task-3-fix-r1.md`)。 +BASE = `0fef2fb`。本轮**只许**改 `src/backend/src/db.rs` + `src/backend/tests/db_it.rs` +(`lib.rs` 是 Task 4 的专属写入文件,Task 4 马上派工 ⇒ 本轮不许碰,否则撞车)。 + +**Ruling P31 — 观察 O1/O2 均为「按规格实现的预期取舍」,不改代码。** +— 理由:契约 §5.3 的规范写法是带双引号的 camelCase 键,安全网只是防漏; + 两种契约写法(双引号别名 / 直接投影 `f_*`)复审实测均正确 ⇒ 契约未破。 +— 若错了的代价:将来若出现「子查询定义别名 + 外层裸选」的 SQL,返回的键会全小写、 + 前端读不到字段且不报错(静默失败);届时改 `collect_alias_info` 的扫描范围即可, + 成本 = 一次局部修改 + 一条回归测试。 + +**Ruling P32 — 观察 O3(`AliasInfo` 可见性)不处理。** +— 理由:它不是缺陷,也不影响任何调用方(`collect_alias_info` 与字段都是 crate 内部使用); + 现在动它属于纯噪音改动,会污染后续任务的 diff。— 若错了的代价:几乎为零。 + +**Ruling P33 — 键归一安全网的作用域(供 Task 5~10 引用):** +安全网**只认外层 SELECT 投影列表里相对深度 0 的 `AS`**; +CTE / 子查询 / `CAST(x AS TYPE)` 里的 `AS` 不登记。 +⇒ 本仓 SQL 一律按契约写法 `f_xxx AS ""`(双引号);安全网不是规范路径。 +(已写进 task-6..10 brief 的 S13。) + +**Ruling P36 — brief S11 关于 `Config` 不可克隆的说法是笔误,已更正为「`Config` 是 `Clone`, +但契约 §9 仍写死 `Arc` ⇒ 照契约用 `Arc`」。** +— 理由:核对 `src/backend/src/platform/config.rs:41` = `#[derive(Clone, Debug)]`。 + 契约的 `Arc` 仍然成立(`AppState` 要 `Clone`,`Arc` 是最省 clone 的写法)。 +— 若错了的代价:几乎为零(`Arc` 与 `Config` 在行为上等价,只是 clone 成本不同)。 + +**Ruling P37 — brief 里 UUID 下标断言自相矛盾,按**真实 v4 布局**钉住。** +brief 原写「第 15 个字符是 `'-'`」「第 14 个字符是 `'4'`」——两句都反了: +真实 `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx` 的 1-based 连字符在 9/14/19/24, +版本号 `4` 在第 15 位,变体位在第 20 位(8/9/a/b)。 +实现者按真实布局写测试并在测试的 doc 注释里记下 brief 的错 ⇒ **行为正确**。 +(已把 brief 改对,避免以后再被同一句话误导。) +— 若错了的代价:几乎为零(若按 brief 原样写测试,则该测试必失败 ⇒ 反而更早暴露)。 + +**Ruling P38 — 观察「variant nibble 未断言」不改。** +— 理由:`new_uuid()` = `Uuid::new_v4().to_string()`,**variant 位由 `uuid` crate 按 RFC-4122 保证** + (8/9/a/b)⇒ 断言的是构造器的契约,不是本仓实现的契约;评审的 2000 样本探针实测全部正确。 +— 条件:若将来 `new_uuid` 改为手搓 UUID ⇒ **必须**补 variant 位断言。 +— 若错了的代价:几乎为零(uuid crate 不可能产出非 v4 的 v4 UUID)。 + +**Ruling P39 — 观察「`issue` 在写锁中毒时仍返回 token」不改。** +— 理由:触发前提是 `HashMap::insert` 期间 panic(OOM 之类)⇒ 进程本就不健康; + 且 `resolve` 用 `.ok()?` ⇒ 中毒只导致 `resolve` 返回 `None`,**不会 panic 传播、不杀请求**。 + 契约面(登录成功/未登录)无差别。 +— 若错了的代价:几乎为零。 + +**Ruling P40 — 观察「session 表无 TTL / 无容量上限」v1 不实现 TTL。** +— 理由:契约 §6.1 逐字写死「token 形态 = `lite-`+32 hex;**进程重启即失效(内存表)**」, + `expiresIn: 7200` 是**响应字面量**;项目 CLAUDE.md 也明确认可「内存 token 表」形态 + (与 JNPF 的 Sa-Token 内存模式同代)。 + 实现 TTL 会引入「token 提前失效 ⇒ 冒烟脚本随机失败」的新失败模式, + 换来的收益是防一个 v1 规模下**不可观测**的内存增长。 +— 条件:v2 面向真实用户时补「TTL + 容量上限」。 +— 若错了的代价:低(长跑进程里 token 表单调增长;每条 ~50 字节,登录量级下无感)。 + +**Ruling P41 — 观察「`trim()` 放宽了接受范围」不改。** +— 理由:只**放宽**不收紧(`' bearer '` 现在能解析),token 本身仍要精确匹配 ⇒ 无安全副作用。 +— 若错了的代价:几乎为零。 + +**Ruling P42 — 契约 §7.2/§7.3/§7.4 的「覆盖」语义 = 「只 SET body 里出现的键」(react 的 `undefined` 语义)。** +— 理由:契约 §7.1 明确写了全局规则「**只覆盖 body 里出现的键,`undefined` ⇒ 不动原值**」, + §7.2/§7.3/§7.4 只是**没重复**这句全局规则,不是要改成「总是覆盖」。 + react 的行为真源(`sys.service.ts`)也一致:`Object.assign(ex, {urlAddress: dto.urlAddress})` + ⇒ `undefined` ⇒ TypeORM `save` 跳过该列 ⇒ 原值不动。 +— 承重之处:菜单的 `f_url_address` 是**权限守卫的比对键**(§8.2)。 + 若一次 Module 更新把它清成 NULL ⇒ 该菜单变成「**未映射**」⇒ 守卫走「未映射放行」 + ⇒ **任何登录用户都能访问该模块**(静默越权)。 + 「只 SET body 里出现的键」这条通用规则正是防这个的。 +— 已写进 task-8-brief 的 **S16**(含逐字段兜底表:`f_type`/`f_category` 用 `?? 原值`, + `f_sort_code` 用 `?? 0`,`f_parent_id` 用 `|| '0'`,`f_is_administrator` 用「真值?1:0」, + `f_organize_id` 用 `|| '0'`,`f_password` 非空才覆盖;`f_url_address`/`f_icon`/`f_en_code`/`f_description` 缺省不动)。 +— 待办:**把这条全局规则回写进 `docs/contract.md` §7.2/§7.3/§7.4**(Task 5 提交落地后、派 Task 6 之前做, + 免得在实现者运行时动工作区)。 +— 若错了的代价:菜单 `f_url_address` 被清空 ⇒ 越权窗口(中高)。 + +**Ruling P43 — 冒烟断言按契约 §13 的 32 条实现(react 脚本实际只有 31 个 `check`)。** +— 理由:逐个数过 react 的 `scripts/perm-smoke.sh`:它的「smoke_user 登录」那一步**只提取 token、没有 `check`**, + 实际 `check` 调用数 = 31;而契约 §13 的表把「`smoke_user` 登录 ⇒ `code=200`」**列为第 12 条** ⇒ 表里 32 行。 + 契约(binding authority)与 react(行为真源)在此**不是冲突而是粒度差** ⇒ 取更严的契约口径。 +— 好处:登录失败会**立刻**定位,而不是让后面 8 条连环假失败(噪音大、难定位)。 +— 已写进 task-11-brief 的 S13(含 react JS 表达式 → jq 表达式的**逐条翻译表**、 + `$ROOT` 定位 `--enc` 二进制、`mktemp` 临时目录、第 9 条 msg 的**全角冒号**、第 5/13 条的 `|` 用单引号)。 +— 若错了的代价:几乎为零(多断言一条登录成功;真失败时反而更好定位)。 + +**Ruling P44 — `permission.rs` 里的 DB 报错必须「拒」,不得当成「未映射放行」。** +— 理由:契约 §9 把 `resolve_user_module_ids` / `has_module` / `build_menu_list` 的签名定成 + **不带 `Result`**(`HashSet` / `bool` / `Vec`)⇒ DB 报错**没法往外传**, + 只能在模块内部消解。而 `has_module` 第 2 步的语义是「查 `base_module` 查不到 ⇒ **未映射放行** ⇒ true」, + 「**查不到**」与「**查询失败**」极易被写成同一分支(`if !found { return true }`)。 + 写成同一分支 ⇒ DB 一挂,全站模块守卫**全部放行** ⇒ **静默全站越权**。 +— 裁定:DB 报错 ⇒ `has_module` 返回 `false`(拒)、`resolve_user_module_ids` 返回空集、 + `build_menu_list` 返回空 `Vec`,并在 `eprintln!` 里记一行(不打印口令/token/密文)。 + 「查不到」与「查询失败」**必须分成两条路径**。 +— 已写进 task-6-brief 的 **S15**。 +— 若错了的代价:DB 故障时全站越权(高)。 + +**Ruling P45 — 🔴 修:固定字面量 id 的 INSERT 必须与「存在性判定」对齐,否则改一次名就永久起不来。** +— 缺陷(Important,reviewer 指 `seed.rs:212-252` / `seed.rs:264-309`): + 存在性按 `f_en_code` / `f_url_address` 判,但 INSERT 用**固定字面量 id**(`role_admin` / `m_user` …)。 + `base_module` / `base_role` 的 PK 是 `(f_id, f_tenant_id)` ⇒ 只要用户通过 UI 改过内置菜单的 + `urlAddress`(契约 §7.4 允许)或内置角色的 `enCode`(§7.2 允许), + 下次启动就会「查不到 ⇒ INSERT 固定 id」⇒ **主键冲突** ⇒ 种子失败 ⇒ 进程 `exit 1` ⇒ + **此后每次启动都失败,且因为服务起不来,用户无法通过 UI 改回去** ⇒ 只能手工改库。 + react 不会这样:它的 `save({id:'m_user', …})` 是**按主键 upsert**。 +— 裁定:存在性判定改成 **「`f_en_code`/`f_url_address` 命中清单 **或** `f_id` = 固定字面量」** ⇒ + 已有行一律不碰(保住「只补缺项、绝不覆盖已改值」),且**永不再 INSERT 撞主键**。 + (备选 `ON CONFLICT (f_id, f_tenant_id) DO NOTHING` 也可,但「OR f_id」语义更准: + 撞主键的那一行本来就**不该被覆盖**。) +— 这条同时暴露了**契约本身的一处缺口**:§8.6 同时规定了「固定 id」与「按 en_code/url 判存在」, + 两者在「人工改名」之后就会打架。⇒ 本仓以「两条都算存在」消解。 +— 若错了的代价:改一次名 ⇒ 后端**永久起不来**(高)。 + +**Ruling P46 — 不修(Minor 2 的 `base_role_relation` 多填两列):按契约 §8.6 逐字删掉。** +— 契约 §8.6 对 `base_role_relation` 那行**逐字列了 7 个业务字段**(`f_object_type`/`f_object_id`/ + `f_role_id`/`f_sort_code`/`f_delete_mark`/`f_tenant_id`/`f_id`),**没有** `f_creator_user_id`/ + `f_creator_time`;react 的 `roleRelRepo.save` 也不写。Ruling P34 的「统一约定」明确只覆盖 + **角色行 / 菜单行**,没覆盖这条关联行。⇒ **删掉这两个字段**(本仓 DDL 允许 NULL,不影响任何逻辑)。 +— 若错了的代价:两列审计字段为 NULL(极低)。 + +**Ruling P47 — 评审的 ⚠️#2(react 的 `base_*` entity 是官方 DDL 的**子集** ⇒ 本仓种子往 +`base_module`/`base_authorize` 写 `f_creator_user_id` 在 react 建的库上会「列不存在」)**不属于本任务缺陷**。** +— 理由:契约 §5.1 把「两版后端可开同一个库」这句话**挂在三张业务表上** + (原文:「**业务表**的列宽与默认值必须逐字对齐 react 的 TypeORM entity —— 这是『两版后端可开同一个库』 + 能成立的**前提**」)。`base_*` 7 张是**官方 DDL 逐字**(本仓的「契约」), + react 的 entity 只是它的**子集**(react 的 `base_module` 无 `f_creator_user_id`、 + `base_authorize` 无 `f_creator_time`/`f_creator_user_id`)⇒ **react 后端本来就打不开本仓的库** + (它的 `synchronize: true` 会 `ALTER` 掉官方 DDL 的多余列)。 + 契约 §5.3 已经把这件事处理过了(「⚠️ react 的 `base_authorize` entity 没有 `f_creator_time`/ + `f_creator_user_id` ⇒ **投影里不要它们**」)—— 那是**读**的方向;**写**的方向以官方 DDL 为准。 + ⇒ 本仓真正的复用对象是 react 的**前端**,不是 react 的**后端**。 +— 处置:记为**项目级边界**(写进 `docs/contract.md` §5.1 的注解 + `CLAUDE.md` 的措辞), + 不算 Task 5 的缺陷、不改代码。 +— 若错了的代价:拿 react 后端指过来会 `ALTER` 官方 DDL(但那是 react 侧的行为,本仓管不了)。 + +**Ruling P48 — 「改掉内置角色 `f_en_code` ⇒ 不再补 admin 授权行」是契约行为,不是缺陷。** +— `ensure_admin_authorizations` 仍按 `f_en_code='admin'` 找 admin 角色(契约 §8.6 逐字)。 + 用户把内置 admin 角色的 `f_en_code` 改掉后,`ensure_base` 不会补授权行 + —— 但**不报错、不撞主键**(R1 的核心诉求已满足),且 admin 本人是 `f_is_administrator=1` + ⇒ 走管理员短路,菜单不受影响。 +— 为什么不加「或 `f_id='role_admin'`」:那会在「用户另建一个 `en_code='admin'` 的角色」时 + 出现**两个候选**,可能把授权挂到 `role_admin` 上 ⇒ 与 §8.6 的语义冲突 + (契约说 admin 角色 = `f_en_code='admin'` 的那一行,且 `f_en_code` 无 UNIQUE ⇒ 取 `ORDER BY f_id LIMIT 1`)。 +— `first_seed` 的 `f_role_id='role_admin'` 仍是字面量(§8.6 明文);该 id 恒存在 + (`ensure_base` 先行补齐;用户改名时行还在、硬删时会被重建)⇒ **不会悬空**。 +— 若错了的代价:改过内置 admin 角色编码后,该角色的非管理员成员失去菜单授权(低)。 + +**Ruling P49 — `MAX_TREE_DEPTH = 32` 保留(不改代码),只补一行注释说明它是「防御性上限」。** +— 契约 §8.3 对层数**无**规定,react 的 `toTree` 也没有层数概念 ⇒ 不是「偏离契约」,是防御性上限。 +— 控制器已逐行核对 `build_tree` / `build_node`:**环**(A.parent=B、B.parent=A)靠 + `by_parent.remove()` 的**消费式取值**本来就终止(环成员互为子、无根 ⇒ 输出空; + 挂在根下的环走一圈后 `remove()` 取空)⇒ 封顶**不是**防环的唯一手段。 +— 但**极深的链**(>1000 层)会让递归爆栈 ⇒ SIGSEGV ⇒ 整个进程死掉。 + 而 react 在环场景下更糟:它造出**循环引用**的对象图 ⇒ JSON 序列化抛 + 「Converting circular structure to JSON」⇒ 500。⇒ **截断严格优于 react 的行为**。 +— 截断只在「菜单嵌套 > 32 层」时生效(UI 逐级建菜单,现实中不可达)。 +— 若错了的代价:>32 层的菜单子树被静默丢弃(极低)。 + +**Ruling P50 — `has_module` 里 `LIMIT 1` 不加 `ORDER BY`,保持与 react 一致。** +— 契约写的是「取第一条」;react 的 `findOne` 同样不确定 ⇒ 加 `ORDER BY` 反而是**偏离**。 + `f_url_address` 无 UNIQUE 是**官方 DDL 的既定事实**,重复 url 属应用层该防的事,不在本任务范围。 + +**Ruling P51 — `grant_type` 空串:按 react 的 falsy 语义放行,并**修订契约措辞**(实现不动)。** +— 契约 §6.1 原文「`grant_type` **存在且** ≠ `password` ⇒ 400」,字面读会把空串判成 400。 +— 行为真源(react `auth.controller.ts`)是 `if (grantType && grantType !== 'password')` + ⇒ JS 空串 **falsy** ⇒ 空串放行;全局约束第 1 条要求逐字对齐 react。 +— 且前端恒发 `grant_type=password`(`auth.ts:11`)⇒ 退化输入,影响面为零。 +— ⇒ 裁决:`auth.rs` 的判定逻辑**保持**(`!grant_type.is_empty() && grant_type != "password"`), + **修订 `docs/contract.md:439`** 为「**非空**且 ≠ `password`」,并同步 `auth.rs` 的 doc 注释。 +— 若错了的代价:一个退化输入的 400/放行差异;无现实影响。 + +**Ruling P52 — 登录的 DB 报错 ⇒ `系统异常,请联系管理员`(**推翻**实现者报告 §5.3 与评审的意见)。** +— 契约 §R1.2(`docs/contract.md:28`)与 §6.5(`:493`)**逐字规定**: + 「未捕获异常(panic / **DB 报错**)⇒ HTTP 200 + `{code:400,msg:'系统异常,请联系管理员',data:null}`」。 +— 实现者与评审都判成「规格没规定 ⇒ 取不泄露信息的安全文案」⇒ **规格其实规定了**,两人都漏读 §R1.2。 +— react 那边把 `e.message` 回给客户端(泄露 PG 原文);本仓刻意不抄,但契约给的通用文案同样不泄露。 +— ⇒ 裁决:改成 `fail(400, "系统异常,请联系管理员")`(HTTP 200 不变),保留 `eprintln!`; + 补一条 DROP `base_user` 的测试钉住它。 +— 若错了的代价:DB 故障时客户端看到「系统异常」而非「账号或密码错误」——这正是契约要的可区分性; + 用户不会误以为口令错而反复重试。 + +**Ruling P53 — `LoginForm` 去掉 `Debug` / `Default` / `Clone`(只留 `serde::Deserialize`)。** +— `Debug` 派生的结构体里装着**口令密文** ⇒ 一次 `{:?}` 就是一次泄漏(评审 Minor)。 +— `Default` / `Clone` 全仓零使用点(`auth_it.rs` 用结构体字面量)。 +— 若错了的代价:将来真要用时编译期会报(加回即可)。 + +**Ruling P54 — 口令哈希的 JSON 键改名:`f_password AS "password"` ⇒ `AS "storedPassword"`。** +— 那个 `Value` 里有一个**键名叫 `password`** 的字段 ⇒ 一次误打日志就是哈希泄漏(评审 Minor)。 +— 只改这一列的别名与对应的一处读取点;`id` / `account` / `isAdministrator` 三个别名一字不动。 +— 若错了的代价:无(该键不进响应体)。 + +**Ruling P55 — `cipher.rs::encrypt_password` 的两处 `.expect()` 必须去掉(**控制器自查发现,评审未报**)。** +— 项目红线「非测试代码零 `unwrap`/`expect`/`panic!`」;`cipher.rs:60/63` 是**全仓仅剩**的两处 + (`cipher.rs:158/181`、`envelope.rs:118+`、`session.rs:124+` 全在 `#[cfg(test)] mod tests` 里)。 +— key 构造换成 `KeyInit::new(&GenericArray)`(不可失败;`new_from_slice` 内部就是 + `Self::new(Key::from_slice(key))` ⇒ **完全等价**);填充的 `Err` 用 `match` fail-closed + (**绝不回显明文**);上游检验向量必须一字不变(测试钉住)。 +— 若错了的代价:零。 + +**Ruling P56 — 补两条测试钉子(解析失败分支 / 校验顺序优先级)。** +— 这两条分支此前**没有测试钉住**:把 `login_from_bytes` 的 `Err(_)` 分支删掉、 + 或把校验顺序 1 与 2 调换,现有 16 条测试**照样全绿** ⇒ 契约被静默改掉也没人发现。 +— ⇒ 用**重复键**(`account=a&account=b`)触发 serde 的 duplicate field 错误; + 用「缺 password + `grant_type=foo`」钉住顺序(必须得到 `缺少 account / password`)。 + +**Ruling P57 — 契约文本的修改必须回到 `docs/contract.md`,不能只写进任务报告。** +— 评审明确指出:`grant_type=""` 的分歧「应在 `docs/contract.md` 里对账,而不只是写进任务报告 —— + 否则契约仍是权威,却读起来像 `""` ⇒ 400」。 +— 契约是**约束真源**,任务报告只是记录 ⇒ 分歧必须在契约里消除。 + +**Ruling P58 — 保留 `cipher.rs::encrypt_password` 里既有的 `debug_assert_eq!(src.len(), 32, ...)`(不删)。** +— 实现者提出的**非阻塞**关切:该断言在 debug 构建下会 panic。 +— 控制器判定**保留**:① MD5 摘要恒为 16 字节 ⇒ hex 恒 32 个 ASCII 字符 ⇒ 这是**编译期常量级**的不变式; + ② `debug_assert!` 正是陈述这类不变式的惯用法(release 下被编译掉,debug 下会响亮地炸); + ③ 红线「非测试代码零 `unwrap`/`expect`/`panic!`」针对的是**运行时可能失败**的路径, + 而这条断言恒真;④ 它既不是 `unwrap` 也不是 `expect` 也不是 `panic!`。 +— 若错了的代价:几乎为零(最坏是 debug 构建多一次恒真断言开销)。 + +**Ruling P59 — 多步写操作的原子性口径。** +— `Db` 的每个公开方法**各自**持进程级 `Mutex`(`db.rs` 内部实现);**没有**跨多次调用 + 公开持锁的接口 ⇒ `db.rs` 自己的 S3 注释(「一次业务操作跨多条 query 必须由本层进程级 + Mutex 兜住」)目前**无接口可实现** ⇒ **已知缺口**,交给最终整体评审。 +— 本任务口径:能写成**一条**语句的多步写(授权写入的「软删旧行+插新行」;User Save 的 + 「删旧 role_relation+插新行」)⇒ 用 **data-modifying CTE** 合成一条 SQL + (PG 的数据修改型 CTE 无论是否被引用都执行且只执行一次 ⇒ 一条语句 = 一个隐式事务 = 原子), + 值全部走绑定参数;确实需要多步的 ⇒ 顺序多次参数化调用(与 `permission.rs` 既有模式一致)。 +— **不要**改 `db.rs`(Task 8 改动面只有 `sys.rs` + `tests/sys_it.rs`)。 +— 若错了的代价:并发下可能读到「软删已完成、插入未完成」的中间态(方向是**少权限**,非越权)。 + +**Ruling P60 — Task 8 的 handler 签名(Task 10 装配要用,现在定死)。** +— 统一形状:`State` + `HeaderMap` +(Save/Authority 用 `Bytes` 原始 body; + Delete/Modules 用 `RawQuery`)+ 返回 `Json`。 +— 🔴 **body 用 `Bytes` 自己解析**(`serde_json::from_slice`):axum 的 `Json` 解析失败会返回 + **422 + 非信封 body** ⇒ 契约破(与 Task 7 `login_handler` 同一个坑)。 +— 🔴 **query 用 `RawQuery` 自己解析**(`serde_urlencoded::from_str`):axum 的 `Query` 解析失败 + 会返回 **400 + 非信封 body** ⇒ 契约破。解析失败 ⇒ 视作「参数缺失」⇒ 走既有业务文案。 +— 若错了的代价:Task 10 装配时签名对不上,要返工改 `sys.rs` + `routes.rs`(小)。 + +**Ruling P61 — 非法 JSON body 的文案(契约未覆盖,控制器裁决)。** +— body 解析失败 ⇒ `fail(400, "请求参数格式错误")`(**HTTP 200** + 信封)。 +— 理由:契约 §R1.2 要求业务失败一律走 `{code,msg,data}`;axum 默认的 422 文本**不是**信封 ⇒ 破。 +— 若错了的代价:文案不在契约清单里(契约未列此场景)⇒ 极小;改起来是一行。 + +**Ruling P62 — Delete 端点在「`id` 参数缺失 / id 不存在」时返回成功(实现者 concern 1)。** +— 契约 §7.1 明确:User Delete「软删 `base_user`(按 id,**不按 `f_delete_mark` 过滤** ⇒ 幂等)」 + +「**不检查用户是否存在** ⇒ 不存在也返回成功」;Role Delete / Module Delete 未要求存在性检查; + Organize Delete 先查子机构(无子机构即软删,不存在也是软删 0 行)。 +— ⇒ 「id 不存在」在契约下就是**成功**;「`id` 参数**缺失**」契约未单列,取**同一读法**(幂等成功) + 是与契约最一致的选择。 +— 🔴 **安全前置条件**:`id` 缺失时**绝不能**退化成「无 WHERE 条件的全表更新」⇒ + 实现必须是 `WHERE f_id = $1::text`(绑定空串 ⇒ 匹配 0 行)。已核对 `sys.rs` 的 4 个 delete + handler 均为 `WHERE f_id = $1::text` 绑定参数 ⇒ 无误伤风险。**维持现状,不改。** +— 理由:改成 `400 '用户不存在'` 反而**违反**契约 §7.1 的显式条款。 +— 若错了的代价:契约 §7.1 若被改写,4 个 delete handler 各一行(极小)。 + +**Ruling P63 — `roleIds` 的非字符串元素 / `f_type`·`f_sortCode` 的不可解析值(实现者 concern 2)。** +— `roleIds` 非字符串元素:契约 §7.1 第 5 条说「每个 roleId 插一行」,未规定非字符串元素的行为; + react 原样落库 ⇒ 会在 `f_role_id`(varchar)里写入非 id 串 ⇒ 污染授权数据。 + 控制器判定:**丢弃非字符串元素**是更安全的一侧(不污染),且契约未禁止 ⇒ **维持现状**。 +— `f_type` / `f_sortCode` 不可解析值回落「原值 / 0」:契约 §7.2/§7.4 说 `f_type` = body.type ?? **原值**、 + `f_sort_code` = body.sortCode ?? 0 ⇒ 「值不可解析」时回落默认与契约的「缺省」语义一致; + 另一条路是让 DB 报类型错 ⇒ 变成「系统异常」⇒ **违反** §R1.2 的语义分层。⇒ **维持现状。** +— 若错了的代价:极小(契约未覆盖非字符串 roleId 的精确行为)。 + +**Ruling P64 — `write_user_roles` 不得吞掉 DB 错误(唯一阻塞项)。** +— 契约 §7.1 第 5 条把「先硬删旧行再插新行」列为 User Save 的**必经步骤**; + 原实现 `sys.rs:547-549` 只 `eprintln!` 后返回 `()`,调用点忽略返回值 + ⇒ 角色写失败仍回 `{code:200,msg:'成功'}` ⇒ **契约要求的写入没生效却报成功**。 +— 修法:`write_user_roles` 返回 `Result<(), pglite::Error>`;两个调用点映射 + `db_error(e, "用户角色关联写入")` ⇒ HTTP 200 + `fail(400, "系统异常,请联系管理员")`。 +— 若错了的代价:与契约 §R1.2 的「DB 报错 ⇒ 400」不一致(吞错)。 + +**Ruling P65 — body 里 `id` 存在但非字符串 ⇒ 走更新分支(不是新建)。** +— 契约 §7.1 第 4 条写的是「**有 `id`** ⇒ 更新」;react 的 `if (dto.id)` 对数字 `123` 是 truthy + ⇒ 行为真源也走更新分支。原实现 `as_str()` 得 `None` ⇒ 被当成「无 id」⇒ **静默多插一行**。 +— 修法:新增 `body_id(&obj)`(`None`/`Null`/空串 ⇒ 无 id;其余 ⇒ 按 JSON 文本当 id)。 +— 若错了的代价:域外输入下多插一行(静默数据污染)。 + +**Ruling P66 — `roleIds` 原始数组非空但全非法 ⇒ 不动已有关系行。** +— P63 只裁定「丢弃非字符串元素」,**没考虑先删后插的放大效应**: + `roleIds:[123]` ⇒ 旧行已硬删 + 过滤后为空 ⇒ 用户的**全部**角色授权被清空。 +— 修法:原始数组**非空**且过滤后为空 ⇒ 早退,**不动**关系行; + 原始数组本身就是 `[]` ⇒ 仍按契约 §7.1 第 5 条「空数组 ⇒ 只删不插」。 +— 若错了的代价:一次畸形输入清空用户的角色授权。 + +**不要求改的 Minor(已裁决,记此备最终整体评审复查)**: + +- **P67 — `or_zero` 把非字符串 `organizeId`/`parentId` 写成 `'0'`** ⇒ **不改**。 + 契约只规定默认值 `'0'`、未规定入参类型;本仓 id 全是 UUID 字符串 ⇒ 数字型是**域外输入**; + 前端恒传字符串。记为已知偏离。 + +- **P68 — `sys.rs` 单文件 1273 行承载 5 组** ⇒ **不改**。 + 计划与 brief 的目录结构明确要求「`sys.rs` = 5 组 `base_*` 显式 handler」,拆文件会与计划冲突。 + ⇒ 留给**最终整体评审**裁决。 + +- **P69 — `user_role_map` 每次加载整张 `base_role_relation` + `base_role`** ⇒ **不改**。 + v1 规模(几十行)完全够用,优化留到稳定期。 + +**R=1 范围复审(sonnet `a51282a746faf814a`)结论:PASS。** +必改 1–5 全部 ADDRESSED;New Breakage: None;未要求改的 4 个 Minor 一律未动。 + +**Ruling P70 — `body_id` 对 `0` / `false` 这类 JS falsy 的非字符串 id 判为「有 id」⇒ 不改。** +— 契约对 `id` 的取值域就是 36 位 UUID 字符串 ⇒ 数字/布尔是**域外输入**; + 与 P67(`or_zero` 域外输入不处理)同一口径 ⇒ 记录备查,不阻塞。 + +**Ruling P71 — 新建路径角色写入失败可能残留「有用户、无角色关系」的半成品 ⇒ 不改。** +— 这是 Ruling P59 的**已知缺口**(`Db` 没有跨调用持锁的公开接口)的具体表现 + ⇒ 统一交给**最终整体评审**裁决;本任务**不改 `db.rs`**。 + +**修复轮 R=2(唯一补洞项)**:补 2 条测试,钉住 R=1 必改 3 引入的**早退分支** +(原始 `roleIds` 非空但全非法 ⇒ 关系行**不动**)与其**相邻**的契约分支 +(原始 `roleIds` 就是 `[]` ⇒ 只删不插 ⇒ **清空**授权)—— 两条长得极像、结果相反、**都没有测试**。 +清单见 `.superpowers/sdd/ssw-jnpf-lite-rust-v1/task-8-fix2.md`。 + +**Ruling P72 — react 前端的 `30000` 实际有 3 处(不是 2 处);`request.ts:5` 的端口注释保持逐字节不变。** +— 控制器 2026-10-26 实测全目录 grep(排除 `node_modules`/`package-lock.json`): + `vite.config.ts:11`(注释)/ `vite.config.ts:12`(代理目标)/ `request.ts:5`(文档注释,**也是端口**)/ + `request.ts:31`(axios **超时毫秒**)。原 Task 12 brief 的 S13① 只列了 2 处 ⇒ 表述不准确。 +— 为什么:plan 明文「逐字复制、唯一允许的改动 = `vite.config.ts` 的代理目标」, + 且 Task 12 的 diff 门判据是「`diff -r` 的**全部**差异只允许出现在 `vite.config.ts`」 + ⇒ 改 `request.ts:5` 会让 diff 门失败。 +— 代价:`request.ts:5` 在改完后**描述的是旧端口 30000**(纯注释、无功能影响)⇒ 记为**已知陈旧注释**, + 最终整体评审按 Minor 处理;🔴 **禁止**在 Task 12 顺手"修好"它。 +— 已同步修正 `.superpowers/sdd/ssw-jnpf-lite-rust-v1/task-12-brief.md` 的 S13①(三处清单 + 处理列 + 理由)。 + +**Task 9 评审(opus)结论:✅ Spec compliant / Approved(Critical 0 / Important 0 / Minor 6)。** +逐条核对契约 §7.6 三条路径 + §5.3 三套列集 + `??`/`||` 语义 + `module_key` 守卫 + 9 个 handler 签名 +⇒ **全部逐字落地且有测试钉住**;三份文件严格在 allowlist 内;零 `unwrap/expect/panic!`;SQL 全参数化。 + +**5 条 concern 的裁定(评审者比对 `docs/contract.md` + react 真源后确认实现正确)**: +- Concern 1(`??` vs `||`):**合规**。契约 §7.6 明文写出两套表达式;§7.1–§7.4 的 + 「null ⇒ 写 NULL」规则**自带作用域标注**「(§7.1–§7.4 通用)」⇒ **不治理 §7.6**。 +- Concern 2(路径 2/3 存在性判定不过滤 `f_delete_mark`):**合规**。契约分流条件是 + 「库里查不到该行」;react `findOne({where:{id}})` 同样不过滤 ⇒ 一致。 +- Concern 3(路径 3 允许写 `f_creator_time`):**合规**(在 §5.3 列集内 ⇒ 可写), + 但**该分支无测试** ⇒ 列为必改 2。 +- Concern 4(`save` 非单事务):按 S16 口径**不是本任务缺陷** ⇒ 归 P59 已知缺口。 +- Concern 5(clippy):「`permission.rs` 已有同类告警」**属实**,但计数需修正 —— + 实跑 `cargo clippy --all-targets`:`doc_lazy_continuation` **共 6 条** + (**本任务新引入 4 条**:`crud.rs:5-6` / `entity.rs:5-6`;既有 2 条:`permission.rs:18-19`)。 + ⇒ 另发现**既有**告警:`sys.rs` 3 条(`question_mark` / `unnecessary_first_then_check` / + `vec_init_then_push`)+ `tests/seed_it.rs` 1 条(`type_complexity`)⇒ 共 6 条待清。 + 🔴 **根因已定位**:`crud.rs:4` / `entity.rs:4` 的**行首是 `+`** ⇒ markdown 当成无序列表标记 + ⇒ 后两行变成该列表项的惰性续行 ⇒ clippy 告警(`permission.rs` 同机制:`:17` 行首是 `-`)。 + +**Ruling P73 — `write_cast` 的硬编码 cast 表与 spec 的 `numeric` 脱钩 ⇒ 本轮只补一致性测试,不重构。** +— 风险真实存在:将来新增一个 numeric 列时,投影会正确加 `::text`、写入却不会加 `::numeric` + ⇒ PG 报类型错 ⇒ 只在运行时变成「系统异常」信封,编译期/启动期无提示。 +— 但重构 `write_cast` 为「由 `col.numeric` 推导」会改**写入口的类型转换**(生产逻辑)⇒ + 超出「告警 + 测试 + 注释」这一轮的范围,且 v1 只有三张固定 spec ⇒ 本轮**只补一条一致性测试** + (遍历三张 spec,断言每个 `numeric: true` 的列都落在 `::numeric` 分支)把这条不变量**钉住**。 +— 代价:若将来新增 numeric 列而**忘了同步 cast 表**,新测试会失败(这是我们要的), + 但重构本身被推迟 ⇒ 留给**最终整体评审**。 + +**Ruling P74 — 0 字节 body ⇒ `fail(400,"请求参数格式错误")`,**不**跟随 react 的 `{}` ⇒ 有意偏离。** +— react 侧 express body-parser 对空 body 给 `{}` ⇒ 建行;本仓 JSON 解析失败 ⇒ 400。 +— 契约未覆盖 0 字节 body,但通用规则「非法 JSON ⇒ 请求参数格式错误」优先 ⇒ 0 字节 body 不是合法 JSON。 +— 处置:**写进 `crud.rs` 模块文档**说明这是有意偏离(不静默埋着),不改逻辑。 + +**Ruling P75 — 本轮消掉本任务新引入的 4 条 clippy 告警;其余 6 条留给最终整体评审的修复轮。** +— `permission.rs` ×2、`sys.rs` ×3、`tests/seed_it.rs` ×1 全是**既有/其它任务遗留**, + 改它们会越出本任务的文件白名单(`crud.rs` / `entities.rs` / `crud_it.rs`)。 +— 🔴 记为**最终整体评审的必清项**(全是机械改动:`?` 运算符 / `!rows.is_empty()` / `vec![]` / + 列表续行缩进 / type alias)。 + +**修复轮 R=1(in flight)**:清单见 `.superpowers/sdd/ssw-jnpf-lite-rust-v1/task-9-fix1.md` +—— 必改 1 消 4 条 clippy;必改 2 补「路径 3 写 `f_creator_time`」测试; +必改 3 补「numeric 列 ↔ `write_cast` 一致性」测试(须自证 load-bearing); +必改 4 两条文档说明(P74 / `numeric_columns` 权威来源)。 +明确不改:Minor 6(性能)、Concern 4(P59 已知缺口)、`permission.rs`/`sys.rs`/`seed_it.rs` 的既有告警。 + +**Task 10 预备裁决(在派单前补齐 brief 的两处缺口)** + +**Ruling P76 — `build_router` 的签名 + 三层兜底的挂法(契约 §9 与 §10 有表面冲突)。** +— 冲突:§9 写 `pub fn build_router(state: AppState) -> Router;` 且括注「`with_state` 由 `main.rs` 在链尾调用」; + §10 第 6 步又写「`build_router(state)` + … + `with_state(state)`(链尾)」。 + `-> Router`(=`Router<()>`)与「main 再调 `with_state`」**在类型上不能同时字面成立**。 +— 裁决:`routes::build_router(state: AppState) -> axum::Router`, + 内部以 `.with_state(state)`(`S2` 显式落在 `AppState`)**让契约的 `state` 参数有去处**、 + 同时**不**终结状态;`main.rs` 链尾**唯一一次** `.with_state(state)` 把类型落成 `Router<()>`。 +— 🔴 兜底挂法:`.fallback(not_found_handler())` **必须写在两个 `.layer(...)` 之前** —— + `Router::layer` 只包住**调用它时已存在**的 fallback ⇒ 先 layer 后 fallback ⇒ 404 兜底 + 既不过 405 改写、panic 也不被 catch_all 接住。 + 正确链:`build_router → .fallback(404) → .layer(405) → .layer(catch_all) → .with_state(state)`。 +— 代价:`build_router` 里那一句 `.with_state(state)` 语义上是 no-op(链尾会覆盖), + 纯粹是为了让契约 §9 的 `state` 参数不产生 `unused_variables` warning ⇒ **已在 brief 里注明**, + 避免最终评审误判为多余代码。 + +**Ruling P77 — 标识符白名单自检的口径(契约 §10 第 3 步只说"自检",没说自检什么)。** +— 自检函数放 `main.rs`(私有),在 `Db::open` **之前**;不过 ⇒ 打印人话 + `exit 1`。 +— 检查对象只有**两类**:① `entities::all_specs()` 里每张 spec 的 `table`(过 `db::valid_table`) + 与每个 `col.column`(过 `db::valid_column`);② **10 张表的字面量清单**(7 张 `base_*` + 3 张业务表) + 逐个过 `db::valid_table`,且**每张 spec 的 `table` 必须在这张清单里**(抓"拼错但仍是合法标识符")。 +— 🔴 **明确不查**:`sys.rs` 的 4 组投影列常量(`USER_COLUMNS` 等)——它们是**源码里的字面量常量**、 + 不是运行时输入,真写错编译期就炸 ⇒ 启动自检对它们无防错价值 ⇒ **本任务不需要改 `sys.rs`**。 +— 代价:自检是**兜底 tripwire**、不是完备证明 ⇒ 记为已知简化,最终整体评审可见。 + +**Ruling P78 — 接受 R=1 实现者主动报告的「越界改动」(`crud.rs` 的 UPDATE 占位符加 `::text`)。** +— 越界点:`update_existing` 的占位符从 `$n{cast}` 改成 `$n::text{cast}`; + 实现者称不改的话,裁决书「必改 2」(路径 3 写 `f_creator_time` 且 `code==200`)**不可达** + (PG 对 `SET f_creator_time = $1::timestamp` 把 `$1` **推断成 timestamp**, + 而 pglite 一律按 text 编码 `Option` ⇒ 协议层类型错 ⇒ 400 系统异常)。 +— 复审(独立在 `/tmp` 副本复现)确认: + ① **必要**:改回原形 ⇒ 路径 3 写 timestamp / numeric / int **全部** `code=400`; + ② **安全**:改后参数恒为 text、转换在服务端做;与 `insert_new` 的 `$i::text{cast}` **逐字同构**; + timestamp → `"2026-01-01T00:00:00Z"` ✅、numeric `"9.90"` → `"9.90"` ✅、int `42` → `42` ✅、 + JSON 数字 `9.9` → `"9.90"`(numeric(12,2) scale)✅、**NULL → NULL** ✅、 + 非法值 `"abc"` → 仍是 `code=400 系统异常,请联系管理员`(与路径 1 同口径同文案)✅; + ③ **契约可观测行为有变化,但方向是「违约 → 守约」**:改前路径 3 写 numeric/int/timestamp + **100% 失败**(不存在可回归的旧行为);返回值形状 / 错误文案 / 列集 / 路径分流 / handler 签名全未变; + ④ **最小**:一个 format 串 + 一个 token + 5 行注释;把 `::text` 塞进 `write_cast` 需连带改 `insert_new` + (改动更大);合并两个函数属「顺手重构」⇒ 否决。 +— 裁决:**接受,不判违规**;但这条改动**改了对外可观测行为** ⇒ 必须有回归测试钉住 + ⇒ 开了 R=2 补「路径 3 写 numeric / int 列」的测试(复审 M1)。 +— 代价:改动的"正当性"依赖上面那份复现实验;⇒ 复审 M2(INSERT/UPDATE 两处各自手写占位符、 + 建议抽共享 helper)**留给最终整体评审的修复轮**(本轮禁重构)。 + +**Ruling P79 — Task 10 **不**实现静态托管(后端不读文件系统来响应请求)。** +— 计划 §610 与契约 §68 都把静态托管写成**可选**(「后端**若**托管静态产物,只能托管前端 `dist/`」)。 +— 事实:前端由 **vite dev server(:5173)** 托管、`/api` 代理到 `:30010`(Task 12 的 `run.sh`); + 契约的 4 条验收门**没有任何一条**要求后端托管前端产物(门④就是 `http://127.0.0.1:5173` 手验)。 +— 裁决:Task 10 **不**加静态文件服务;`config.static_dir`(`/src/frontend/dist`)**故意不使用**。 + 「DDL 绝不可从 HTTP 下载」这条红线由「后端根本不读文件系统来响应请求」**天然**满足, + 并**另加一条守卫测试**:`GET /db/schema.sql` / `GET /src/backend/db/schema.sql` ⇒ HTTP 404 + 信封。 +— 理由:静态服务会引入路径穿越 / content-type 猜测 / SPA fallback 三类**新风险**, + 而**没有任何验收门依赖它** ⇒ 不在 v1 引入。 +— 代价:后端**不能**单独托管已构建的前端("单二进制跑全栈"不成立)⇒ 若最终整体评审认为这是硬伤, + 再开一轮加静态服务(届时须自带路径穿越守卫)。 + +**Ruling P80 — Task 10 的 brief 内部有三处自相矛盾,控制器统一收敛(控制器已改 brief)。** +— 矛盾①:「catch-all 中间件」段写「handler 一律返回 `Result, pglite::Error>`」, + 与 S14③(`pglite::Error` **没有** `IntoResponse` ⇒ 编译不过)及**实际的 27 个 handler 签名** + (全部返回 `Json`)冲突。 + ⇒ 收敛为:**catch-all 只管 panic**;DB 报错**已**在 handler 内部由 `db_error(e, ctx)` + (`sys.rs:79` / `crud.rs:63`)映射成 `fail(400, "系统异常,请联系管理员")`(HTTP 200 + code=400), + **不改任何 handler 的返回类型**。 +— 矛盾②:「catch-all 的位置」段与 S16 里的顺序写 `→ .layer(404兜底)`, + 与 S25 的 `.fallback(404)` 冲突。 + ⇒ 收敛为 S25 的链:`build_router → .fallback(404) → .layer(405) → .layer(catch_all) → .with_state(state)`。 + **控制器已核 axum 0.8.9 源码**(`axum-0.8.9/src/routing/mod.rs`): + `Router::fallback(h)` 同时写 `catch_all_fallback` 与 `fallback_router`;`Router::layer(l)` 把 `l` + **同时**包到 `path_router` / `fallback_router` / `catch_all_fallback` 三处;官方文档原话 + 「the middleware is only applied to existing routes. So you have to first add your routes + (and / or fallback) and then call `layer` afterwards.」⇒ `.fallback()` 必须在两个 `.layer()` **之前**。 + `Router::layer` 的实现是逐条 `route.layer(l)` ⇒ **后挂的在外层**(后进先出)。 +— 矛盾③:S15 写「查询参数用 `axum::extract::Query` 取」, + 与 S17(`Query` 解析失败 ⇒ **400 + 非信封 body** ⇒ 契约破;handler 签名里已经是 `RawQuery`)冲突。 + ⇒ 收敛为:**路由注册时完全不用管 query**(handler 收 `RawQuery` 并在内部自己解析)。 +— 代价:brief 变长、且「以 S25 / S17 为准」这类**交叉引用**读起来略绕 ⇒ 若实现者漏读, + 会在复审时被退回;这正是**任务级评审**要抓的东西,故保留。 + +## 2026-10-26 追加:后端分层(平台层 / 业务层) + +**Ruling P81 — 后端平铺改两层目录:`src/platform/`(契约实现)+ `src/modules/`(业务模块)。** +— 动机:react 版后端本来就是两段(`common`+`auth`+`sys` / `demo`+`shop`+`books`), + 官方 JNPF 同样是两段(`jnpf-common`+`jnpf-system` / `jnpf-admin`); + 本仓当时是平铺(`src/{config,db,cipher,…,entities}.rs`)⇒ 加业务模块要动平台文件, + 形态与参照物不一致。 +— 裁决:按用户口径**只分目录层**(不动 `db/schema.sql` 的业务表 DDL、不动前端、不动契约)。 + 平台层 = `config · db · cipher · envelope · ids · session · state · auth · permission · seed · + sys · jnpf · entity · crud`;业务层 = `mod.rs` + `demo.rs` / `shop.rs` / `books.rs`, + 每个业务模块自带 **spec 表 + 3 条路由 + 自己的 `router()`**。 +— 连带两条**独立**裁决(否则「加模块不动平台」只是口号): + ① **业务路由清单搬到业务层**(`modules/.rs::ROUTES` ⇒ `modules::ALL_ROUTES`), + 平台层的钉子测试遍历它 ⇒ 原来「每加一模块要改 `routes.rs` 路由表」的口子被堵死。 + ② **平台层最后一个业务知识泄漏清掉**:S22 的 `f_creator_user_id` 规则原先在引擎里写死 + `app_code == "demo"` ⇒ 改成**业务 spec 自己声明**(`EntitySpec.creator_fixed`),引擎只读声明。 +— 理由:平台层必须**可插拔**——契约(信封 / 权限 / 密文 / 两面分流)跨项目不变, + 业务层随项目变。分层边界画在「业务表名 / app_code 出现在哪个层」这条线上,是可静态检查的 + (`check-module.sh` 的反向断言),比靠注释约定可靠。 +— 代价:① 平台层与业务层的**边界靠约定**(`entity.rs` 的 `EntitySpec` 是唯一跨界的数据结构), + 将来若要加第二种业务形态(如带树形的实体),得先扩 `EntitySpec`;② `check-module.sh` 从 + 「9 接触点」升到 **69 条断言**(新增反向断言 + 业务层登记断言),维护成本上升。 +— 历史裁决(P14 / P21 / P22 等)**保留原路径写法**——它们记的是「为什么这么实现」, + 不是「文件在哪」;文件路径以本文与 `HOWTO_MODULE.md` 的现状描述为准。 + +## 2026-10-27 追加:分层边界可执行化 + 生产档守卫 + macOS 资源回收 + +> 背景:把兄弟项目 `tdc-rs` 的**机制**(尺子 / 台账 / 守卫 / 引文校验)逐条搬过来, +> 但**只搬机制、不搬内容** —— `tdc-rs` 的实体名 / `tdc_` 表前缀 / `/api/ssw/tdc/` 路由前缀 / +> 数值-JSON 规则 / 内部 token 分级**一律不引入**,因为那些是**那一个业务应用**的知识, +> 搬过来就污染本仓的通用骨架。每一条新机制都在**本仓自己的契约/行为真源**上重新推导。 + +**Ruling P82 — 业务菜单由业务层声明,平台层只留「类型」,中间加一个装配根 `src/bootstrap.rs`。** +— 动机:P81 之后平台层已经不含业务表名,但**业务菜单**仍住在 `platform/seed.rs` + ⇒ 加一个业务模块必须改平台层 ⇒ 「加模块只碰业务层」这条红线**没兑现**。 + 难点在于:平台层要种菜单(那是契约行为),又不能知道菜单是哪个业务的 ⇒ 单靠分层拆不开。 +— 裁决:拆成三块。① `platform/menu.rs` 只定义 **`MenuSpec` 这个类型**(字段全是平台语义 + 的通用属性:`id` / `full_name` / `en_code` / `url_address` / `parent_id` / `menu_type` / + `icon` / `sort_code`),**不含任何具体菜单**;② 每个业务模块在 `modules/.rs` 声明 + `pub const _MENU: MenuSpec = …`,登记进 `modules::ALL_MENUS`; + ③ 新增 `src/bootstrap.rs` 作**装配根**(composition root)—— + `bootstrap::ensure_base(db) = platform::seed::ensure_base(db, modules::all_menus())`。 + `platform::seed` 从「自带 8 个菜单常量」改成「自带 5 个系统菜单 + 接收外部菜单参数」。 +— 理由:**装配根是唯一允许同时认识两层的文件**,这是经典的 composition root 模式 + (依赖倒置的落点)。平台层依旧可插拔,业务层不反向依赖平台层的 seed 细节。 +— 代价:多一个文件(`bootstrap.rs`)和一层间接;`seed::ensure_base` 的签名从 + `(db)` 变成 `(db, extra_menus)` ⇒ **平台层测试要传 `&[]`**,未来若再加第二种菜单来源 + (如从配置文件读),`ensure_base` 的参数会变复杂。 + +**Ruling P83 — 分层红线从「注释约定」升级成「可执行闸门」,且禁用词表由业务层自己反推。** +— 动机:P81 的分层边界「是可静态检查的(`check-module.sh` 的反向断言)」—— + 但那只检查**已知的三个业务模块**;换一个 app_code 就漏检。且检查写在**脚本里**, + 脚本里的期望值也可能与代码漂移。 +— 裁决:新增 `scripts/check-boundary.sh`(CP1–CP6)+ `scripts/check-boundary-scan.py`。 + 扫描器的**禁用词表不是手写的**,而是从 `modules/*.rs`(跳�� `mod.rs`)里 + **反推**出:表名、实体名、`/api/ssw//` 路由前缀、菜单 id、`en_code`、`url_address` + ⇒ **加一个业务模块,禁用词表自动变严**(不写新规则也能拦住新泄漏)。 + 扫描器只认**字符串字面量**,注释里的提及**不算**(否则文档化讨论会误报)。 + CP1 还额外扫 `routes.rs` / `main.rs` / `bootstrap.rs`(它们也是平台侧文件)。 +— 附带一条**防自证**约定:扫描器带 `--self-test` 模式 —— 造一棵假的 + `modules/` + `platform/` 树,断言**恰好**抓到 1 处泄漏(字面量里的泄漏被抓到, + 注释里的提及不误报)⇒ 扫描器不会悄悄退化成「永远通过」的空壳。 +— 代价:① 禁用词表由业务层反推 ⇒ **业务层改名会同步改禁用词表**, + 旧名字不再被禁(这是**特性**:模块改完名,旧名泄漏反而抓不到——但旧名已无人使用, + 危害有限);② 平台层里哪怕是**测试夹具**里的业务字面量也会被报出来 + ⇒ 本仓把 `platform/db.rs` 的测试夹具表名从 `demo_item` 改成中性的 `t_item` + (🔴 注意:**只改测试夹具**,不动任何真实业务表名)。 + +**Ruling P84 — `main.rs` 的 `EXPECTED_TABLES` 硬编码 10 张表 ⇒ 改为「DDL 对账」。** +— 动机:P83 之后,「加业务模块要改 `main.rs`」这个口子**又活过来了** + (白名单自检要核对表名)。入口文件是**平台侧**文件,它一旦知道业务表名,分层就漏了。 +— 裁决:把硬编码的 10 张表拆成 `BASE_TABLES`(7 张 `base_*`,平台侧)+ **对账**: + ① `db::ddl_tables()` 解析 `schema.sql` 里所有 `CREATE TABLE `; + ② DDL 里的每张表**必须**要么在 `BASE_TABLES` 里、要么有对应的业务 spec + ⇒ 否则**孤儿 DDL**(建了表但没 spec)报错; + ③ 每张 spec 表**必须**在 DDL 里有 `CREATE TABLE` ⇒ 否则**漏建表**报错。 +— 理由:这比原来的硬编码**更强**(多抓两类错)而不是更弱,且入口文件**再也不需要** + 为业务模块而改 ⇒ 红线 12 完整兑现。 +— 代价:多一个 `db::ddl_tables()`(用 `include_str!` 读 DDL 文本 + 正则解析); + DDL 写法的自由度高了一点(解析器认的是「行首 `CREATE TABLE `」这一种写法)。 + +**Ruling P85 — 弱口令不靠「文档里写一句」⇒ 加**部署档位**守卫(`SSW_PROFILE=prod`)。** +— 动机:本仓的种子口令是 `admin/123456`(契约 §8.6 逐字要求)、token 永不过期、 + 默认只监听 `127.0.0.1` ⇒ 本地开发形态是安全的,但**部署到生产**时同一份配置就是弱口令暴露。 + 契约不能改(`123456` 是契约的一部分),所以只能在**部署档位**上分叉。 +— 裁决:新增 `platform/guard.rs`(纯函数、无 IO ⇒ 好测)与两个环境变量: + `SSW_PROFILE`(`dev` 缺省 / `prod`;**非法值回落 dev**,朝不误伤本地开发的方向)、 + `SEED_ADMIN_PASSWORD`(缺省 `123456`,**只在空库首启时生效**)。 + `prod` 档下六条判据逐条生效:① 键不在本部署清单里 ⇒ 跳过 + ② 值为空/空白 ③ 精确等于已知弱值 ④ 含已知弱值(反绕过)⑤ 命中弱标记词(整体词) + ⑥ 长度 < 12 ⇒ 任一违规**拒绝启动**(人话报错 + exit 1)。 + 🔴 **额外做一次 DB 级回读**:种子口令只对空库生效 ⇒ 库里那个 admin 可能是当初种下的 + `123456`,而运维后来才设了 `SEED_ADMIN_PASSWORD` ⇒ **只查配置 = 守卫形同虚设** ⇒ 必须回读库。 +— 🔴 **刻意排除 `CIPHER_KEY`**:cipher 的 key 是 `md5_hex("EY8WePvjM5GGwQzn")`, + **协议共享**(前端 `cipher.ts` 与后端逐字节等价)⇒ 它不是「可轮换的弱密钥」, + 当成弱密钥去判 ⇒ 整个系统开不了机。**协议常量 ≠ 部署密钥**,这条判据必须写死。 +— 代价:多两个环境变量 + 一条启动前置检查;`prod` 档下第一次起必须先设一个强口令 + (否则报错退出,这是**故意的**)。 + +**Ruling P86 — macOS 的 SysV 信号量泄漏自建回收器(`scripts/ipc-reap.c` + `reap-ipc-leaks.sh`)。** +— 动机:macOS(XNU) 的 SysV 信号量集**在创建进程退出后不回收**(与 Linux 不同), + 且 macOS **不带 `ipcrm` / `ipcs`**。本仓每个测试文件一个 `Db::open_temp()` + ⇒ 7 个测试文件 ⇒ 每轮 `cargo test` 漏 7 个 `nsems=20` 的 set ⇒ 累积到 + `kern.sysv.semmns`(87381)上限后,**任何新的 PostgreSQL 实例都起不来** + (`semget: No space left on device`)。 +— 裁决:自写 C 回收器。回收口径**刻意保守**(宁可漏回收也不误伤活进程): + ① 只回收 `nsems == 20`(= PGlite/postgres-pglite 的指纹); + ② 只回收创建者 uid == 当前用户的 set(不碰 root / 其他用户); + ③ 只回收「最近一次操作时间」距今超过 `--min-idle` 秒的 set + (活着的 PostgreSQL 会持续 `semop` ⇒ otime 是新的 ⇒ 不会误删)。 + 默认 `--min-idle 3600`(1 小时),`--dry-run` 只报不删。 +— 代价:多一个 C 源文件(需 `cc`,即 Xcode Command Line Tools); + 判据③的「1 小时」是经验值(宁可漏,不误伤);`free_capacity()` 靠二分探测, + 每次运行会新建并立刻释放一个 set ⇒ 净中性。 + +**Ruling P87 — 契约端点表下沉成「机器可读」段落(附录 A `[ENDPOINT]` / `[FACE]`)。** +— 动机:契约的「端点全表」一直是给人看的人话表格,而尺子的期望值另写在脚本里 + ⇒ **同一件事两处**,改端点只改脚本不改契约 ⇒ 契约慢慢退化成"过期文档"。 + 本仓的其它期望值(菜单 / 业务模块)早已下沉到附录 A(`[MENU]` / `[MODULE]`), + 端点表是**最后一块没下沉的**。 +— 裁决:把 §6 端点全表在附录 A 落成 `[ENDPOINT]` 段(列:face / method / path / guard / owner), + 另加 `[FACE]` 段记三面条数(A 25 / B 5 / AB 2)。 + `scripts/contract_expect.py` 新增 `endpoint` / `endpoints` / `face` 三个子命令读它。 +— 🔴 **face 是必要的新维度**:面 A 专属 25 + 面 B 专属 5 + 两面共用 2 = 32, + 而"面 A 27 条"= 25 + 2(共用算进面 A)⇒ **不记面就必然有人对不上数**。 + `[FACE]` 段自带的 `条数` 列就是让这个口径**写在契约里**而不是各自记。 +— 代价:契约文档里同一批端点出现两次(人话表 + 机器表)⇒ **改端点必须两处同改** + (`HOWTO_MODULE.md` §2.4 已写死这条),换来"尺子期望值只有一处"这个更值钱的性质。 + +**Ruling P88 — 加第三道静态闸门 `check-contract.sh`:契约端点表 ↔ 代码真实路由「双向」对账。** +— 动机:已有的闸门都查不出"**契约里写了一条、代码里没实现**"或"**代码多了一条、契约没登记**"—— + 前者要人读文档、后者要人读源码,两者都不在任何尺子的射程内; + 而"文档与实现漂移"恰恰是本仓这种"契约优先"项目最容易出的错。 +— 裁决:新增 `scripts/check-contract.sh` + `scripts/check-contract-scan.py` + (纯静态,不起后端、不连库)。扫描器用**掩码解析**读 Rust 源码: + 先把注释/字符串字面量挖空但**保留字节偏移**,在掩码文本上找结构、 + 在原文同偏移处取字面量 ⇒ 注释里写的 `.route(` 不会被误当成真路由。 + 检查项 CC2–CC9:端点总数 / 契约→代码(存在 + 方法一致)/ 代码→契约(无未登记)/ + 归属层(platform vs 业务层)/ 守卫 / 钉子测试覆盖 / 业务路由三处一致 / 面计数自洽。 +— 代价:多一个 Python 扫描器要跟着路由写法演进;**只认 axum 的 `.route(` 写法** + (本仓唯一写法),换写法必须改扫描器——这是"静态对账"换来的确定性的代价。 + +**Ruling P89 — 静态闸门必须自带「反自证」(`--self-test`),且"推不出"判 WARN 不判失败。** +— 动机:一条只会在"代码碰巧对"时才绿的闸门等于没有闸门—— + **尺子本身要能证明自己抓得住错**。另外静态推导有天然盲区:守卫写法一变就推不出来, + 若把它判成失败 ⇒ 闸门天天误报 ⇒ 团队习惯性忽略 ⇒ 闸门名存实亡。 +— 裁决:① `--self-test` 模式**注入六种已知漂移**(契约多一条 / 少一条 / 方法写错 / + 守卫写错 / 归属层写错 / 面计数写错)到契约副本,断言每种都被抓到; + **同时先断言真契约零漂移**——两向都过才算自证成立。 + ② 推不出守卫 ⇒ 报 `WARN`(**不计失败**)⇒ 闸门只在"确知不一致"时红。 +— 🔴 **自证本身不计入 PASS/FAIL**:CC1' 只表现为 ✅/❌,不参与 9 条断言的计数 + ⇒ 尺子不能用"自己多认一条"来给自己加分。 +— 代价:自证要维护一份"漂移注入"样板(每种漂移一段),新增检查类型时须同步补注入用例。 + +**Ruling P90 — 文档里的「路径:行号」会**静默漂移** ⇒ 加第四道静态闸门 `check-citations.sh`。** +— 动机:本仓的文档(`SKILL` / `README` / `MIGRATION` / `JNPF_SOURCE_AUDIT` / `PERMISSION` …) + 大量引用源码位置(**百余条**全限定引文 + **84 处**续行行号;**条数随文档改动而变** ⇒ + 以 `check-citations.sh` 的输出为准,这里不钉死数字)。行号是**会漂移**的: + 源码改一行 ⇒ 上游行号整体位移 ⇒ 文档里的引用**静默指向别的行**—— + **不报错**,只是悄悄说错话(这比"链接 404"更坏:404 会被人看见)。 + P0-1 的契约↔代码对账管的是**端点**,管不到**行号**。 +— 裁决:新增 `scripts/check-citations.sh` + `scripts/check-citations-scan.py`(纯静态)。 + 三条判据:CIT1 引文**可解析** / CIT2 引文**行号有效** / CIT3 **DDL 行号表**对账 + (`CLAUDE.md` 写的建表行号 ↔ 官方 DDL 那一行真的有 `CREATE TABLE`)。 + 引文行号支持四种写法:`N` / `N-M` / `N/M`(多个散行)/ `N+`(及以后)。 + 解析三级:精确 ⇒ 相对路径**后缀** ⇒ **基名**(官方源码文档里 `ActionResult.java:27` 这种)。 + 参照根四处:本仓 / 官方 JNPF 源码 / react 姊妹技能 / **cargo registry** + (引文指到依赖源码时,如 `pglite-rs 0.2.7` 的 `src/db.rs:444`)。 +— 🔴 **三条「不判失败」的口径是刻意的**(不然闸门天天误报 ⇒ 被人忽略 ⇒ 闸门名存实亡): + ① **外部参照根缺失 ⇒ 判「跳过」**(官方源码 / react 技能 / cargo registry 不在本机时, + 只校验本仓内的引文);② **无路径的续行行号**(`:NNN`)**只报不判失败**—— + 那是本仓表格的约定,且**相邻两行可能指不同文件** ⇒ 机械继承必然误报 ⇒ + 改用「上文 40 行内点名的文件里**任意一个**行数够」的**弱判据**;③ 行号越界才是硬失败。 +— 代价:多一个 Python 扫描器;**文档改行号后必须同步改**(这是本闸门的全部意义); + 弱判据意味着**个别**续行行号漂移抓不到(能抓到"没有任何点名的文件够长"这一档)。 + +**Ruling P91 — 契约尺子**默认自起隔离后端**;显式给了 `B` 才不自起。** +— 动机:两把契约尺子原先都要求「后端已经在 `:30010` 起着」⇒ 三个具体问题: + ① **两把尺子互相踩** —— 面 A 尺子改了库里的角色/菜单授权 ⇒ 面 B 尺子的前置状态被污染 + ⇒ 面 B 的结论**依赖面 A 跑没跑、跑的顺序** ⇒ 尺子不可独立复现; + ② **跑完留脏数据** —— 每次跑都往 `src/backend/data/lite.pg` 里多一行 `smoke_user` / + `shop_product` / `book_shop_book`(`known-limitations` (n))⇒ 重复跑让这两张表无界增长; + ③ **CI 里没法跑** —— 没人替你起后端 ⇒ 闸门形同虚设。 +— 裁决:把「起后端」收进尺子自己(新文件 `scripts/smoke_backend.sh`,被两把尺子 `source`, + **不独立可执行**),口径三条: + ① **没给 `B`** ⇒ 先探 `:30010`:**通** ⇒ 就用它(保留「跑开发中的后端」这个习惯,不逼用户改习惯); + **不通** ⇒ **自起隔离实例** —— 空闲端口(`python3` 真 bind 一下拿端口,退化时扫 `30110-30199`) + + `mktemp -d` 临时 `PGLITE_DIR`(**绝对路径**,契约要求); + ② **显式给了 `B`** ⇒ **不自起**(尊重外部后端)⇒ 不可达即**退出码 2**; + ③ 退出时尺子 `trap` 先 `TERM` 后端(等 6s 再兜底 `KILL`)再删临时目录 ⇒ 库里的痕迹**随临时目录一起消失**。 + ⇒ 断言可重复、两把尺子互不污染、CI 可跑。 +— 🔴 **刻意不做的事**:**不**在尺子里把外部后端「顶掉」(不许抢 30010、不许 kill 用户的进程)—— + 显式 `B` 不可达就**报错退出**,而不是自作主张换端口打空气; + **不**把「自起」做成默认的**唯一**路径(那会逼用户放弃「打开发中后端」的习惯)。 +— 代价:① 多了 `scripts/smoke_backend.sh` 一个文件(尺子不再自包含 ⇒ 拷贝尺子时**必须一起带走**); + ② 自起路径要等后端就绪(最多 40s,冷启动含建 10 张表)⇒ 尺子比原来慢一点; + ③ **端口是动态的** ⇒ 依赖固定端口 30010 的外部脚本会拿不到(显式 `B` 可绕)。 + +**Ruling P92 — 官方端点覆盖要有一本**机器可读的账**(`[OFFICIAL]` 台账 + CC10 双向对账)。** +— 动机:面 B 的「做了多少」原先只有**尺子的断言数**(`面 B 覆盖 18/18`)这一个信号, + 而**官方端点全表**(`JNPF_SOURCE_AUDIT.md` §4)是**散文表格** ⇒ + 「官方端点做了没、做到什么程度」**只能靠人读散文** ⇒ 既不可机器核对,也没法当进度条。 + 另一个隐患:**散文表格与代码各说各话** —— 台账说做了、代码里没注册(或反过来)没人发现。 +— 裁决:在 `docs/contract.md` 附录 A 新增 **`[OFFICIAL]`** 区段(机器可读,53 行), + 每行 = `method` / `path` / `status` / `src`(官方出处 `文件:行号`)/ `note`(偏差说明)。 + 状态词表**穷举四态**: + `implemented`(已落地且形状对齐)/ `partial`(已落地但**形状有偏差**,偏差逐条指向 + `JNPF_COMPAT_SURFACE.md` §8 的 B1–B10)/ `absent`(未实现,可后置)/ + `oos`(v1 明确不做:导入导出族、数据权限链接 —— **不进覆盖分母**)。 + `scripts/check-contract-scan.py` 加 **CC10**,与**代码真实路由双向**对账: + ① 说 `implemented/partial` 的必须**真的注册了**;说 `absent/oos` 的必须**没有**注册; + ② 反向:**面 B / 共用**的每条路由都必须在台账上**有账**(防"实现了但没记账"); + ③ 打印**「官方端点覆盖 N/M」**(N = implemented+partial,M = 再加 absent)—— + 与面 B 尺子的「覆盖 N/18」同一路数:**诚实量进度**。 + 台账的 `src` 列是官方出处 `文件:行号` ⇒ 由**引文闸门(P90)逐条核对** + ⇒ 台账里的官方出处**不是抄来的,是验过的**(现 198 条引文全中)。 +— 🔴 **刻意做的三件事**: + ① **台账与散文表格并存**(§4 仍是人读的)⇒ 代价是**同一批官方端点写两处**, + 两处都用 `🔴` 互相指路(§4 指 `[OFFICIAL]`;`[OFFICIAL]` 的 `src` 指 §4 的行号); + ② **CC10 挂在 `check-contract.sh` 而不是新开第七道闸门** —— 它的性质与 CC2–CC9 完全同源 + (都是「台账 ↔ 代码」),合在一起只多一条断言(9 → 10),闸门总数仍是**六道**; + ③ **`partial` 单列成一态** —— 硬塞进 `implemented` 会让覆盖数虚高, + 硬塞进 `absent` 又会让人以为"没做" ⇒ 官方形状的**偏差**必须**看得见**。 +— 代价:① 官方端点表写两处(改端点 ⇒ 两处都改,CC10 会红); + ② **覆盖 N/M 是个会动的数**(官方端点表一变,分母就变)⇒ 文档里**不钉死具体数字**的地方 + 只能写"以尺子输出为准";③ 台账的 `src` 列与引文闸门**耦合** ⇒ 官方源码换了文件/行号 ⇒ + 引文闸门会红(这是**故意的**:出处漂移了就该报)。 diff --git a/docs/fe/endpoints.tsv b/docs/fe/endpoints.tsv new file mode 100644 index 0000000..636770f --- /dev/null +++ b/docs/fe/endpoints.tsv @@ -0,0 +1,901 @@ +METHOD PATH FUNC WHERE +GET /api/Report getReportList api/onlineDev/report.ts:14 +POST /api/Report createReport api/onlineDev/report.ts:18 +POST /api/Report/Data getData api/onlineDev/report.ts:46 +DELETE /api/Report/Info/{param} delVersion api/onlineDev/report.ts:62 +GET /api/Report/Info/{param} getVersionInfo api/onlineDev/report.ts:54 +POST /api/Report/Info/{param} copyVersion api/onlineDev/report.ts:66 +POST /api/Report/Save saveVersion api/onlineDev/report.ts:50 +GET /api/Report/Selector getReportSelector api/onlineDev/report.ts:78 +GET /api/Report/Version/{param} getVersionList api/onlineDev/report.ts:58 +POST /api/Report/data/ImportExcel uploadFileExcel api/onlineDev/report.ts:90 +POST /api/Report/data/downImg uploadImg api/onlineDev/report.ts:86 +POST /api/Report/data/upload/file uploadFileImage api/onlineDev/report.ts:82 +POST /api/Report/data/{param}/DownExcel exportFileExcel api/onlineDev/report.ts:94 +GET /api/Report/data/{param}/getQueryList getPreviewQueryList api/onlineDev/report.ts:106 +POST /api/Report/data/{param}/preview getPreviewDesign api/onlineDev/report.ts:70 +POST /api/Report/data/{param}/previewTemplate getPreviewTemplate api/onlineDev/report.ts:74 +DELETE /api/Report/{param} delReport api/onlineDev/report.ts:30 +GET /api/Report/{param} getReportInfo api/onlineDev/report.ts:26 +PUT /api/Report/{param} updateReport api/onlineDev/report.ts:22 +POST /api/Report/{param}/Actions/Copy copy api/onlineDev/report.ts:34 +GET /api/Report/{param}/Actions/Export exportData api/onlineDev/report.ts:42 +POST /api/Report/{param}/Actions/Module createMenu api/onlineDev/report.ts:102 +GET /api/Report/{param}/getReleaseMenu getReleaseMenu api/onlineDev/report.ts:98 +GET /api/ai/Agent getAgentList api/aiCenter/aiAgent.ts:9 +POST /api/ai/Agent create api/aiCenter/aiAgent.ts:17 +DELETE /api/ai/Agent/Info/{param} delVersion api/aiCenter/aiAgent.ts:49 +GET /api/ai/Agent/Info/{param} getVersionInfo api/aiCenter/aiAgent.ts:41 +POST /api/ai/Agent/Info/{param} copyVersion api/aiCenter/aiAgent.ts:53 +POST /api/ai/Agent/Save saveVersion api/aiCenter/aiAgent.ts:37 +GET /api/ai/Agent/Selector getAgentSelector api/aiCenter/aiAgent.ts:13 +GET /api/ai/Agent/Version/{param} getVersionList api/aiCenter/aiAgent.ts:45 +DELETE /api/ai/Agent/{param} delAgent api/aiCenter/aiAgent.ts:29 +GET /api/ai/Agent/{param} getInfo api/aiCenter/aiAgent.ts:25 +PUT /api/ai/Agent/{param} update api/aiCenter/aiAgent.ts:21 +POST /api/ai/Agent/{param}/Actions/Copy copyAgent api/aiCenter/aiAgent.ts:33 +GET /api/ai/AiSupplier getAiSupplierList api/aiCenter/aiModel.ts:9 +POST /api/ai/AiSupplier create api/aiCenter/aiModel.ts:17 +GET /api/ai/AiSupplier/Selector getAiSupplierSelector api/aiCenter/aiModel.ts:13 +POST /api/ai/AiSupplier/checkAi checkAi api/aiCenter/aiModel.ts:33 +DELETE /api/ai/AiSupplier/{param} delAiSupplier api/aiCenter/aiModel.ts:29 +GET /api/ai/AiSupplier/{param} getInfo api/aiCenter/aiModel.ts:25 +PUT /api/ai/AiSupplier/{param} update api/aiCenter/aiModel.ts:21 +GET /api/ai/Chat/Close/{param} stopChat api/aiCenter/aiChat.ts:23 +POST /api/ai/Chat/Optimize optimize api/aiCenter/aiChat.ts:47 +POST /api/ai/Chat/Send sendChat api/aiCenter/aiChat.ts:9 +POST /api/ai/Chat/Translate sendTranslate api/aiCenter/aiChat.ts:19 +DELETE /api/ai/Chat/history/cleanAll deleteAllHistory api/aiCenter/aiChat.ts:43 +DELETE /api/ai/Chat/history/delete/{param} deleteHistory api/aiCenter/aiChat.ts:39 +GET /api/ai/Chat/history/get/{param} getHistoryInfoList api/aiCenter/aiChat.ts:31 +GET /api/ai/Chat/history/list getHistoryList api/aiCenter/aiChat.ts:27 +PUT /api/ai/Chat/history/update/{param} updateHistory api/aiCenter/aiChat.ts:35 +GET /api/ai/Document getAiDocumentList api/aiCenter/aiDocument.ts:9 +POST /api/ai/Document create api/aiCenter/aiDocument.ts:13 +DELETE /api/ai/Document/{param} delAiDocument api/aiCenter/aiDocument.ts:25 +GET /api/ai/Document/{param} getInfo api/aiCenter/aiDocument.ts:21 +PUT /api/ai/Document/{param} update api/aiCenter/aiDocument.ts:17 +GET /api/ai/Document/{param}/getText getText api/aiCenter/aiDocument.ts:37 +POST /api/ai/Document/{param}/section documentSection api/aiCenter/aiDocument.ts:29 +POST /api/ai/Document/{param}/study documentStudy api/aiCenter/aiDocument.ts:33 +GET /api/ai/Knowledge getKnowledgeList api/aiCenter/aiKnowledge.ts:9 +POST /api/ai/Knowledge create api/aiCenter/aiKnowledge.ts:21 +GET /api/ai/Knowledge/Relation/{param} getRelationAgentList api/aiCenter/aiKnowledge.ts:41 +GET /api/ai/Knowledge/Selector getKnowledgeSelector api/aiCenter/aiKnowledge.ts:13 +POST /api/ai/Knowledge/getListByIds getKnowledgeListByIds api/aiCenter/aiKnowledge.ts:17 +DELETE /api/ai/Knowledge/{param} delKnowledge api/aiCenter/aiKnowledge.ts:33 +GET /api/ai/Knowledge/{param} getInfo api/aiCenter/aiKnowledge.ts:29 +PUT /api/ai/Knowledge/{param} update api/aiCenter/aiKnowledge.ts:25 +POST /api/ai/Knowledge/{param}/Test recallTest api/aiCenter/aiKnowledge.ts:37 +GET /api/ai/Mcp getMcpList api/aiCenter/aiMcp.ts:9 +POST /api/ai/Mcp create api/aiCenter/aiMcp.ts:21 +GET /api/ai/Mcp/Selector getMcpSelector api/aiCenter/aiMcp.ts:13 +GET /api/ai/Mcp/Sync/{param} syncMcp api/aiCenter/aiMcp.ts:37 +POST /api/ai/Mcp/getListByIds getMcpListByIds api/aiCenter/aiMcp.ts:17 +DELETE /api/ai/Mcp/{param} delMcp api/aiCenter/aiMcp.ts:33 +GET /api/ai/Mcp/{param} getInfo api/aiCenter/aiMcp.ts:29 +PUT /api/ai/Mcp/{param} update api/aiCenter/aiMcp.ts:25 +GET /api/ai/Model getModelConfigList api/aiCenter/aiModelConfig.ts:9 +GET /api/ai/Model/{param} getInfo api/aiCenter/aiModelConfig.ts:17 +PUT /api/ai/Model/{param} update api/aiCenter/aiModelConfig.ts:13 +GET /api/ai/Prompt getPromptList api/aiCenter/aiPrompt.ts:9 +POST /api/ai/Prompt create api/aiCenter/aiPrompt.ts:13 +DELETE /api/ai/Prompt/{param} delPrompt api/aiCenter/aiPrompt.ts:25 +GET /api/ai/Prompt/{param} getInfo api/aiCenter/aiPrompt.ts:21 +PUT /api/ai/Prompt/{param} update api/aiCenter/aiPrompt.ts:17 +GET /api/ai/Serve getAgentServiceList api/aiCenter/aiAgentService.ts:9 +POST /api/ai/Serve create api/aiCenter/aiAgentService.ts:17 +GET /api/ai/Serve/Selector getAgentServiceSelector api/aiCenter/aiAgentService.ts:13 +DELETE /api/ai/Serve/{param} delAgentService api/aiCenter/aiAgentService.ts:29 +GET /api/ai/Serve/{param} getInfo api/aiCenter/aiAgentService.ts:25 +PUT /api/ai/Serve/{param} update api/aiCenter/aiAgentService.ts:21 +GET /api/ai/Skills getAiSkillsList api/aiCenter/aiSkills.ts:9 +POST /api/ai/Skills/getListByIds getAiSkillsListByIds api/aiCenter/aiSkills.ts:13 +GET /api/ai/Skills/{param} getInfo api/aiCenter/aiSkills.ts:17 +GET /api/ai/Tool getAiToolList api/aiCenter/aiTool.ts:9 +POST /api/ai/Tool/getListByIds getAiToolListByIds api/aiCenter/aiTool.ts:13 +GET /api/ai/Tool/{param} getInfo api/aiCenter/aiTool.ts:17 +POST /api/ai/visualdev getAiFormInfo api/aiCenter/aiChat.ts:52 +POST /api/ai/workflow getAiFlowInfo api/aiCenter/aiChat.ts:56 +GET /api/blade-visual/visual/Selector getDataVSelector api/onlineDev/dataV.ts:9 +GET /api/extend/BigData getBigDataList api/extend/bigData.ts:9 +POST /api/extend/BigData createBigData api/extend/bigData.ts:13 +GET /api/extend/CrmOrder getOrderList api/extend/order.ts:9 +GET /api/extend/CrmOrder/Customer getCustomerList api/extend/order.ts:25 +GET /api/extend/CrmOrder/Goods getGoodsList api/extend/order.ts:29 +GET /api/extend/CrmOrder/OrderEntry/{param}/Items getOrderEntryList api/extend/order.ts:17 +DELETE /api/extend/CrmOrder/{param} delOrder api/extend/order.ts:13 +GET /api/extend/CrmOrder/{param}/CollectionPlan getOrderPlanList api/extend/order.ts:21 +GET /api/extend/DocumentPreview getDocumentPreviewList api/extend/documentPreview.ts:9 +GET /api/extend/DocumentPreview/{param}/Preview previewFile api/extend/documentPreview.ts:13 +GET /api/extend/Email getEmailList api/extend/email.ts:9 +POST /api/extend/Email saveSent api/extend/email.ts:25 +POST /api/extend/Email/Actions/SaveDraft saveDraft api/extend/email.ts:29 +GET /api/extend/Email/Config getConfigInfo api/extend/email.ts:13 +PUT /api/extend/Email/Config saveConfig api/extend/email.ts:17 +POST /api/extend/Email/Config/Actions/CheckMail checkMail api/extend/email.ts:21 +POST /api/extend/Email/Receive receive api/extend/email.ts:57 +DELETE /api/extend/Email/{param} delEmail api/extend/email.ts:37 +GET /api/extend/Email/{param} getEmailInfo api/extend/email.ts:33 +PUT /api/extend/Email/{param}/Actions/Read setRead api/extend/email.ts:41 +PUT /api/extend/Email/{param}/Actions/Star setStar api/extend/email.ts:49 +PUT /api/extend/Email/{param}/Actions/Unread setUnread api/extend/email.ts:45 +PUT /api/extend/Email/{param}/Actions/Unstar setUnStar api/extend/email.ts:53 +GET /api/extend/Employee getEmployeeList api/extend/employee.ts:9 +GET /api/extend/Employee/ExportData exportExcel api/extend/employee.ts:17 +POST /api/extend/Employee/ImportData importData api/extend/employee.ts:25 +GET /api/extend/Employee/ImportPreview importPreview api/extend/employee.ts:29 +GET /api/extend/Employee/TemplateDownload templateDownload api/extend/employee.ts:21 +DELETE /api/extend/Employee/{param} delEmployee api/extend/employee.ts:13 +GET /api/extend/ProjectGantt getProjectList api/extend/projectGantt.ts:9 +POST /api/extend/ProjectGantt createProject api/extend/projectGantt.ts:13 +POST /api/extend/ProjectGantt/Task createTask api/extend/projectGantt.ts:41 +GET /api/extend/ProjectGantt/Task/{param} getTaskInfo api/extend/projectGantt.ts:37 +PUT /api/extend/ProjectGantt/Task/{param} updateTask api/extend/projectGantt.ts:45 +DELETE /api/extend/ProjectGantt/{param} delProject api/extend/projectGantt.ts:21 +GET /api/extend/ProjectGantt/{param} getInfo api/extend/projectGantt.ts:25 +PUT /api/extend/ProjectGantt/{param} updateProject api/extend/projectGantt.ts:17 +GET /api/extend/ProjectGantt/{param}/Task getTaskList api/extend/projectGantt.ts:29 +GET /api/extend/ProjectGantt/{param}/Task/Selector/{param} getTaskSelector api/extend/projectGantt.ts:33 +GET /api/extend/TableExample getTableList api/extend/table.ts:29 +POST /api/extend/TableExample createTable api/extend/table.ts:13 +GET /api/extend/TableExample/All getTableListAll api/extend/table.ts:33 +GET /api/extend/TableExample/CityList/{param} getCityList api/extend/table.ts:9 +GET /api/extend/TableExample/ControlSample/{param} getTableListByType api/extend/table.ts:61 +GET /api/extend/TableExample/IndustryList getIndustryList api/extend/table.ts:21 +PUT /api/extend/TableExample/UpdateSign/{param} updateSign api/extend/table.ts:57 +DELETE /api/extend/TableExample/{param} delTable api/extend/table.ts:17 +GET /api/extend/TableExample/{param} getInfo api/extend/table.ts:25 +PUT /api/extend/TableExample/{param} updateTable api/extend/table.ts:53 +GET /api/extend/TableExample/{param}/Actions/Postil getPostilList api/extend/table.ts:41 +PUT /api/extend/TableExample/{param}/Actions/RowsEdit updateTableRow api/extend/table.ts:37 +POST /api/extend/TableExample/{param}/Postil sendPostil api/extend/table.ts:45 +DELETE /api/extend/TableExample/{param}/Postil/{param} delPostil api/extend/table.ts:49 +GET /api/extend/saleOrder/Classify getProductClassify api/extend/saleOrder.ts:33 +GET /api/extend/saleOrder/Customer getCustomer api/extend/saleOrder.ts:29 +GET /api/extend/saleOrder/Goods getGoodsList api/extend/saleOrder.ts:37 +GET /api/extend/saleOrder/Goods/Selector getGoodsSelector api/extend/saleOrder.ts:49 +GET /api/extend/saleOrder/Goods/getGoodList getGoodsListByType api/extend/saleOrder.ts:41 +GET /api/extend/saleOrder/Product getOrderList api/extend/saleOrder.ts:9 +POST /api/extend/saleOrder/Product createOrder api/extend/saleOrder.ts:17 +GET /api/extend/saleOrder/Product/ProductEntry/{param} getProductEntry api/extend/saleOrder.ts:45 +DELETE /api/extend/saleOrder/Product/{param} delOrder api/extend/saleOrder.ts:25 +GET /api/extend/saleOrder/Product/{param} getInfo api/extend/saleOrder.ts:13 +PUT /api/extend/saleOrder/Product/{param} updateOrder api/extend/saleOrder.ts:21 +GET /api/file/Document getAllList api/teamwork/document.ts:11 +POST /api/file/Document create api/teamwork/document.ts:19 +POST /api/file/Document/Actions/CancelShare shareCancel api/teamwork/document.ts:55 +POST /api/file/Document/Actions/Copy/{param} copyTo api/teamwork/document.ts:51 +PUT /api/file/Document/Actions/MoveTo/{param} moveTo api/teamwork/document.ts:47 +POST /api/file/Document/Actions/Share createShare api/teamwork/document.ts:59 +POST /api/file/Document/Actions/ShareAdjustment/{param} createSingleShare api/teamwork/document.ts:63 +POST /api/file/Document/BatchDelete batchDeleteDocument api/teamwork/document.ts:31 +GET /api/file/Document/Detail getDetail api/teamwork/document.ts:43 +POST /api/file/Document/FolderTree getFolderTree api/teamwork/document.ts:35 +POST /api/file/Document/PackDownload download api/teamwork/document.ts:95 +GET /api/file/Document/Share getShareOutList api/teamwork/document.ts:67 +GET /api/file/Document/ShareTome getShareTomeList api/teamwork/document.ts:75 +GET /api/file/Document/ShareUser/{param} getShareUserList api/teamwork/document.ts:79 +GET /api/file/Document/Trash getTrashList api/teamwork/document.ts:83 +POST /api/file/Document/Trash trashDelete api/teamwork/document.ts:87 +POST /api/file/Document/Trash/Actions/Recovery trashRecovery api/teamwork/document.ts:91 +POST /api/file/Document/UploadBlob uploadBlob api/teamwork/document.ts:103 +GET /api/file/Document/getIcon getIconList api/teamwork/document.ts:107 +GET /api/file/Document/list getImgDocList api/teamwork/document.ts:15 +POST /api/file/Document/merge documentMerge api/teamwork/document.ts:99 +GET /api/file/Document/recent getRecentList api/teamwork/document.ts:71 +PUT /api/file/Document/tag setTag api/teamwork/document.ts:23 +GET /api/file/Document/{param} getInfo api/teamwork/document.ts:39 +PUT /api/file/Document/{param} update api/teamwork/document.ts:27 +GET /api/file/DocumentSpace getSpaceList api/teamwork/documentSpace.ts:9 +POST /api/file/DocumentSpace createSpace api/teamwork/documentSpace.ts:25 +POST /api/file/DocumentSpace/MoveOut moveOut api/teamwork/documentSpace.ts:41 +POST /api/file/DocumentSpace/Release release api/teamwork/documentSpace.ts:37 +GET /api/file/DocumentSpace/Selector getSpaceSelector api/teamwork/documentSpace.ts:17 +GET /api/file/DocumentSpace/getDocumentList getSpaceDocumentList api/teamwork/documentSpace.ts:13 +DELETE /api/file/DocumentSpace/{param} delSpace api/teamwork/documentSpace.ts:21 +GET /api/file/DocumentSpace/{param} getSpaceInfo api/teamwork/documentSpace.ts:33 +PUT /api/file/DocumentSpace/{param} updateSpace api/teamwork/documentSpace.ts:29 +GET /api/file/Download/{param}/{param} getDownloadUrl api/core/common.ts:13 +POST /api/file/PackDownload/{param} getPackDownloadUrl api/core/common.ts:17 +GET /api/file/Uploader/Preview previewFile api/core/common.ts:21 +POST /api/file/merge chunkMerge api/core/common.ts:25 +GET /api/flowForm/Form getFormList api/workFlow/formDesign.ts:9 +POST /api/flowForm/Form create api/workFlow/formDesign.ts:13 +PUT /api/flowForm/Form update api/workFlow/formDesign.ts:17 +POST /api/flowForm/Form/Release/{param} release api/workFlow/formDesign.ts:29 +GET /api/flowForm/Form/getFormById/{param} getFlowByFormId api/workFlow/formDesign.ts:49 +GET /api/flowForm/Form/select getFormSelect api/workFlow/formDesign.ts:45 +DELETE /api/flowForm/Form/{param} delForm api/workFlow/formDesign.ts:25 +GET /api/flowForm/Form/{param} getInfo api/workFlow/formDesign.ts:21 +GET /api/flowForm/Form/{param}/Actions/Copy copy api/workFlow/formDesign.ts:33 +GET /api/flowForm/Form/{param}/Actions/Export exportData api/workFlow/formDesign.ts:37 +GET /api/flowForm/Form/{param}/getField getFormField api/workFlow/formDesign.ts:41 +GET /api/message getMessageList api/system/message.ts:35 +GET /api/message/Account getConfigList api/msgCenter/accountConfig.ts:9 +POST /api/message/Account create api/msgCenter/accountConfig.ts:13 +PUT /api/message/Account/setdefault updateDefaultConfig api/msgCenter/accountConfig.ts:37 +DELETE /api/message/Account/{param} delConfig api/msgCenter/accountConfig.ts:25 +GET /api/message/Account/{param} getInfo api/msgCenter/accountConfig.ts:21 +POST /api/message/Account/{param} testConfig api/msgCenter/accountConfig.ts:33 +PUT /api/message/Account/{param} update api/msgCenter/accountConfig.ts:17 +POST /api/message/Account/{param}/Actions/Copy copy api/msgCenter/accountConfig.ts:29 +POST /api/message/Actions/ReadAll readAllMsg api/system/message.ts:39 +GET /api/message/Monitor getMsgMonitorList api/msgCenter/msgMonitor.ts:9 +GET /api/message/Monitor/Info getMsgAuditList api/msgCenter/msgMonitor.ts:29 +DELETE /api/message/Monitor/batchRemove delMsgMonitor api/msgCenter/msgMonitor.ts:17 +GET /api/message/Monitor/detail/{param} getInfo api/msgCenter/msgMonitor.ts:13 +DELETE /api/message/Monitor/empty emptyMsgMonitor api/msgCenter/msgMonitor.ts:21 +GET /api/message/Monitor/{param}/RecordList getSendRecordList api/msgCenter/msgMonitor.ts:25 +POST /api/message/Monitor/{param}/Retry retry api/msgCenter/msgMonitor.ts:33 +POST /api/message/Notice create api/system/message.ts:14 +POST /api/message/Notice/List getNoticeList api/system/message.ts:10 +DELETE /api/message/Notice/{param} delNotice api/system/message.ts:26 +GET /api/message/Notice/{param} getInfo api/system/message.ts:22 +PUT /api/message/Notice/{param} update api/system/message.ts:18 +PUT /api/message/Notice/{param}/Actions/Release release api/system/message.ts:30 +GET /api/message/Notice/{param}/ReplyUserList getReceiptList api/system/message.ts:68 +GET /api/message/ReadInfo/{param} readInfo api/system/message.ts:43 +GET /api/message/Receive getReceiveList api/msgCenter/receiveConfig.ts:9 +POST /api/message/Receive saveReceive api/msgCenter/receiveConfig.ts:14 +DELETE /api/message/Record delMsgRecord api/system/message.ts:47 +POST /api/message/Reply/{param} confirmReceipt api/system/message.ts:64 +GET /api/message/Send getSendConfigList api/msgCenter/sendConfig.ts:9 +POST /api/message/Send create api/msgCenter/sendConfig.ts:13 +GET /api/message/Send/getSendConfigList getSendConfigSelect api/msgCenter/sendConfig.ts:41 +POST /api/message/Send/getTestConfig/{param} getTestSendConfig api/msgCenter/sendConfig.ts:33 +POST /api/message/Send/testSendConfig testSendConfig api/msgCenter/sendConfig.ts:37 +DELETE /api/message/Send/{param} delSendConfig api/msgCenter/sendConfig.ts:25 +GET /api/message/Send/{param} getInfo api/msgCenter/sendConfig.ts:21 +PUT /api/message/Send/{param} update api/msgCenter/sendConfig.ts:17 +POST /api/message/Send/{param}/Actions/Copy copy api/msgCenter/sendConfig.ts:29 +GET /api/message/Sensitive getList api/msgCenter/msgSecurity.ts:9 +POST /api/message/Sensitive create api/msgCenter/msgSecurity.ts:21 +DELETE /api/message/Sensitive/{param} deleteSecurity api/msgCenter/msgSecurity.ts:25 +GET /api/message/Sensitive/{param} getInfo api/msgCenter/msgSecurity.ts:13 +PUT /api/message/Sensitive/{param} update api/msgCenter/msgSecurity.ts:17 +GET /api/message/Supplier getSupplierList api/msgCenter/supplier.ts:9 +POST /api/message/Supplier create api/msgCenter/supplier.ts:13 +GET /api/message/Supplier/Selector getSupplierSelector api/msgCenter/supplier.ts:17 +POST /api/message/Supplier/SyncTemplate syncSupplierTemplate api/msgCenter/supplier.ts:41 +GET /api/message/Supplier/TemplateList getSupplierTemplatelist api/msgCenter/supplier.ts:33 +POST /api/message/Supplier/TestConnect testConnectSupplier api/msgCenter/supplier.ts:45 +DELETE /api/message/Supplier/{param} delSupplier api/msgCenter/supplier.ts:29 +GET /api/message/Supplier/{param} getSupplierInfo api/msgCenter/supplier.ts:21 +PUT /api/message/Supplier/{param} update api/msgCenter/supplier.ts:25 +POST /api/message/Supplier/{param}/Actions/Copy copySupplier api/msgCenter/supplier.ts:37 +PUT /api/message/Supplier/{param}/Actions/State updateSupplierState api/msgCenter/supplier.ts:49 +GET /api/message/Supplier/{param}/VariableList getVariableList api/msgCenter/supplier.ts:53 +GET /api/message/Template getMsgTemplateList api/msgCenter/msgTemplate.ts:9 +POST /api/message/Template create api/msgCenter/msgTemplate.ts:13 +POST /api/message/Template/testSendMail testMsgTemplate api/msgCenter/msgTemplate.ts:33 +DELETE /api/message/Template/{param} delMsgTemplate api/msgCenter/msgTemplate.ts:25 +GET /api/message/Template/{param} getInfo api/msgCenter/msgTemplate.ts:21 +PUT /api/message/Template/{param} update api/msgCenter/msgTemplate.ts:17 +POST /api/message/Template/{param}/Actions/Copy copy api/msgCenter/msgTemplate.ts:29 +GET /api/message/imreply getIMReply api/system/message.ts:52 +DELETE /api/message/imreply/deleteChatRecord/{param} deleteChatRecord api/system/message.ts:56 +DELETE /api/message/imreply/relocation/{param} removeChatRecord api/system/message.ts:60 +GET /api/oauth/CurrentUser isBackend api/core/user.ts:15 +POST /api/oauth/LockScreen unlockApi api/core/user.ts:19 +POST /api/oauth/Login loginApi api/core/auth.ts:28 +POST /api/oauth/Login/saas headers api/core/auth.ts:34 +POST /api/oauth/Login/socials socialsLogin api/core/user.ts:43 +POST /api/oauth/Logout logoutApi api/core/auth.ts:48 +POST /api/oauth/apply/saas applySaasApi api/core/auth.ts:42 +GET /api/oauth/codeCertificate getCodeCertificate api/core/user.ts:47 +GET /api/oauth/codeCertificateStatus/{param} getCodeCertificateStatus api/core/user.ts:51 +GET /api/oauth/getConfig/{param} getConfig api/core/user.ts:23 +GET /api/oauth/getLoginConfig getLoginConfig api/core/user.ts:31 +GET /api/oauth/getTicket getTicket api/core/user.ts:35 +GET /api/oauth/getTicketStatus/{param} getTicketStatus api/core/user.ts:39 +GET /api/oauth/mobilecode/saas getTenantMobileCode api/core/auth.ts:38 +GET /api/oauth/setCodeCertificateStatus/{param}/{param} setCodeCertificateStatus api/core/user.ts:55 +POST /api/oauth/updatePasswordMessage updatePasswordMessage api/core/user.ts:27 +GET /api/permission/Action getActionList api/permission/action.ts:9 +POST /api/permission/Action create api/permission/action.ts:13 +DELETE /api/permission/Action/{param} delAction api/permission/action.ts:25 +GET /api/permission/Action/{param} getInfo api/permission/action.ts:21 +PUT /api/permission/Action/{param} update api/permission/action.ts:17 +PUT /api/permission/Authority/Data/{param} updateAuthList api/permission/auth.ts:13 +POST /api/permission/Authority/Data/{param}/Values getAuthValues api/permission/auth.ts:9 +GET /api/permission/Authority/{param}/{param} getCommonAuthValues api/permission/auth.ts:17 +POST /api/permission/Authority/{param}/{param} updateCommonAuthList api/permission/auth.ts:21 +GET /api/permission/Group getGroupList api/permission/group.ts:9 +POST /api/permission/Group create api/permission/group.ts:17 +POST /api/permission/Group/GroupCondition getGroupByCondition api/permission/group.ts:33 +GET /api/permission/Group/Selector getGroupSelector api/permission/group.ts:13 +DELETE /api/permission/Group/{param} delGroup api/permission/group.ts:29 +GET /api/permission/Group/{param} getInfo api/permission/group.ts:25 +PUT /api/permission/Group/{param} update api/permission/group.ts:21 +POST /api/permission/Group/{param}/Actions/AddUser addGroupUser api/permission/group.ts:37 +POST /api/permission/Group/{param}/Actions/DeleteUser removeGroupUser api/permission/group.ts:41 +GET /api/permission/Organize getOrganizeList api/permission/organize.ts:14 +POST /api/permission/Organize create api/permission/organize.ts:18 +GET /api/permission/Organize/AsyncList/{param} getOrganizeSyncList api/permission/organize.ts:10 +GET /api/permission/Organize/AsyncPosList getOrgAndPosSelector api/permission/organize.ts:68 +GET /api/permission/Organize/ExportData exportExcel api/permission/organize.ts:34 +POST /api/permission/Organize/ExportExceptionData exportExceptionData api/permission/organize.ts:50 +POST /api/permission/Organize/ImportData importData api/permission/organize.ts:42 +GET /api/permission/Organize/ImportPreview importPreview api/permission/organize.ts:46 +POST /api/permission/Organize/OrganizeCondition getOrgByOrganizeCondition api/permission/organize.ts:63 +POST /api/permission/Organize/SelectedList getOrgSelectedList api/permission/organize.ts:59 +GET /api/permission/Organize/Selector getOrganizeSelector api/permission/organize.ts:55 +GET /api/permission/Organize/TemplateDownload templateDownload api/permission/organize.ts:38 +DELETE /api/permission/Organize/{param} delOrganize api/permission/organize.ts:30 +GET /api/permission/Organize/{param} getInfo api/permission/organize.ts:26 +PUT /api/permission/Organize/{param} update api/permission/organize.ts:22 +GET /api/permission/PermissionGroup getList api/permission/authGroup.ts:9 +POST /api/permission/PermissionGroup create api/permission/authGroup.ts:25 +GET /api/permission/PermissionGroup/PermissionMember/{param} getPermissionMember api/permission/authGroup.ts:33 +POST /api/permission/PermissionGroup/PermissionMember/{param} savePermissionMember api/permission/authGroup.ts:37 +DELETE /api/permission/PermissionGroup/{param} del api/permission/authGroup.ts:17 +GET /api/permission/PermissionGroup/{param} getInfo api/permission/authGroup.ts:13 +PUT /api/permission/PermissionGroup/{param} update api/permission/authGroup.ts:21 +POST /api/permission/PermissionGroup/{param}/Actions/Copy copy api/permission/authGroup.ts:29 +GET /api/permission/Position getPositionList api/permission/position.ts:9 +POST /api/permission/Position create api/permission/position.ts:13 +GET /api/permission/Position/ExportData exportExcel api/permission/position.ts:53 +POST /api/permission/Position/ExportExceptionData exportExceptionData api/permission/position.ts:69 +POST /api/permission/Position/ImportData importData api/permission/position.ts:61 +GET /api/permission/Position/ImportPreview importPreview api/permission/position.ts:65 +POST /api/permission/Position/PositionCondition getPositionByCondition api/permission/position.ts:37 +POST /api/permission/Position/SelectedList getPositionSelectedList api/permission/position.ts:49 +GET /api/permission/Position/Selector getPositionSelector api/permission/position.ts:45 +GET /api/permission/Position/SelectorTree getPositionSelectorTree api/permission/position.ts:41 +GET /api/permission/Position/TemplateDownload templateDownload api/permission/position.ts:57 +DELETE /api/permission/Position/{param} delPosition api/permission/position.ts:25 +GET /api/permission/Position/{param} getInfo api/permission/position.ts:21 +PUT /api/permission/Position/{param} update api/permission/position.ts:17 +POST /api/permission/Position/{param}/Actions/DutyPosition setDutyPosition api/permission/position.ts:29 +POST /api/permission/Position/{param}/Actions/DutyUser setDutyUser api/permission/position.ts:33 +GET /api/permission/Role getRoleList api/permission/role.ts:9 +POST /api/permission/Role create api/permission/role.ts:17 +POST /api/permission/Role/RoleCondition getRoleByCondition api/permission/role.ts:33 +GET /api/permission/Role/Selector getRoleSelector api/permission/role.ts:13 +DELETE /api/permission/Role/{param} delRole api/permission/role.ts:29 +GET /api/permission/Role/{param} getInfo api/permission/role.ts:25 +PUT /api/permission/Role/{param} update api/permission/role.ts:21 +GET /api/permission/RoleRelation getRoleRelationList api/permission/roleRelation.ts:9 +POST /api/permission/RoleRelation addRoleRelation api/permission/roleRelation.ts:13 +POST /api/permission/RoleRelation/addRoles addRoles api/permission/roleRelation.ts:21 +POST /api/permission/RoleRelation/delete removeRoleRelation api/permission/roleRelation.ts:17 +POST /api/permission/RoleRelation/deleteRoles removeRoles api/permission/roleRelation.ts:25 +GET /api/permission/RoleRelation/roleList getRoleList api/permission/roleRelation.ts:29 +GET /api/permission/Standing getIdentityList api/permission/identity.ts:9 +POST /api/permission/Standing create api/permission/identity.ts:13 +GET /api/permission/Standing/list getIdentityRelation api/permission/identity.ts:29 +DELETE /api/permission/Standing/{param} delIdentity api/permission/identity.ts:25 +GET /api/permission/Standing/{param} getInfo api/permission/identity.ts:21 +PUT /api/permission/Standing/{param} update api/permission/identity.ts:17 +POST /api/permission/Standing/{param}/Actions/AddObject addIdentityRelation api/permission/identity.ts:33 +POST /api/permission/Standing/{param}/Actions/DeleteObject removeIdentityRelation api/permission/identity.ts:37 +POST /api/permission/UserRelation addUserRelation api/permission/userRelation.ts:13 +POST /api/permission/UserRelation/delete removeUserRelation api/permission/userRelation.ts:17 +GET /api/permission/UserRelation/userList getUserRelation api/permission/userRelation.ts:9 +GET /api/permission/Users getUserList api/permission/user.ts:9 +POST /api/permission/Users createUser api/permission/user.ts:17 +GET /api/permission/Users/Authorize getAuthList api/permission/user.ts:113 +POST /api/permission/Users/BatchDelete batchDelete api/permission/user.ts:33 +POST /api/permission/Users/BatchUpdateState batchUpdateState api/permission/user.ts:41 +POST /api/permission/Users/Current/Actions/ModifyPassword updatePassword api/permission/userSetting.ts:21 +PUT /api/permission/Users/Current/Avatar updateAvatar api/permission/userSetting.ts:9 +GET /api/permission/Users/Current/BaseInfo getUserSettingInfo api/permission/userSetting.ts:13 +PUT /api/permission/Users/Current/BaseInfo updateUserInfo api/permission/userSetting.ts:17 +GET /api/permission/Users/Current/SignImg getSignList api/permission/userSetting.ts:57 +POST /api/permission/Users/Current/SignImg createSign api/permission/userSetting.ts:61 +GET /api/permission/Users/Current/Subordinate/{param} getSubordinate api/permission/userSetting.ts:33 +PUT /api/permission/Users/Current/SystemLanguage updateLanguage api/permission/userSetting.ts:29 +GET /api/permission/Users/Current/SystemLog getLogList api/permission/userSetting.ts:37 +PUT /api/permission/Users/Current/SystemTheme updateTheme api/permission/userSetting.ts:25 +GET /api/permission/Users/Current/getAppSecret getAppSecret api/permission/userSetting.ts:93 +GET /api/permission/Users/Current/getUserOrganizes getUserOrganizes api/permission/userSetting.ts:41 +GET /api/permission/Users/Current/getUserPositions getUserPositions api/permission/userSetting.ts:45 +GET /api/permission/Users/Current/getUserRoles getUserRoles api/permission/userSetting.ts:49 +PUT /api/permission/Users/Current/major setMajor api/permission/userSetting.ts:53 +GET /api/permission/Users/Current/saasList getSaasList api/permission/userSetting.ts:81 +GET /api/permission/Users/Current/saasTenantName/{param} getCompanyName api/permission/userSetting.ts:89 +GET /api/permission/Users/Current/saasinfo getSaasInfo api/permission/userSetting.ts:85 +POST /api/permission/Users/Current/saasjoin joinSaas api/permission/userSetting.ts:73 +PUT /api/permission/Users/Current/saveAppSecret createAppSecret api/permission/userSetting.ts:97 +DELETE /api/permission/Users/Current/{param}/SignImg deleteSign api/permission/userSetting.ts:65 +PUT /api/permission/Users/Current/{param}/SignImg updateDefaultSign api/permission/userSetting.ts:69 +DELETE /api/permission/Users/Current/{param}/saas exitSaas api/permission/userSetting.ts:77 +GET /api/permission/Users/ExportData exportExcel api/permission/user.ts:53 +POST /api/permission/Users/ExportExceptionData exportExceptionData api/permission/user.ts:69 +POST /api/permission/Users/ImportData importData api/permission/user.ts:61 +GET /api/permission/Users/ImportPreview importPreview api/permission/user.ts:65 +GET /api/permission/Users/ReceiveUserList getReceiveUserList api/permission/user.ts:89 +GET /api/permission/Users/Selector getUserSelector api/permission/user.ts:13 +POST /api/permission/Users/SetPositionBatch batchSetUserPosition api/permission/user.ts:105 +GET /api/permission/Users/TemplateDownload templateDownload api/permission/user.ts:57 +GET /api/permission/Users/getAllPermission getAuthGroup api/permission/user.ts:109 +POST /api/permission/Users/getSelectedList getSelectedList api/permission/user.ts:73 +POST /api/permission/Users/getSelectedUserList getSelectedUserList api/permission/user.ts:77 +POST /api/permission/Users/getUserList getUserInfoList api/permission/user.ts:49 +GET /api/permission/Users/getWorkByUser getWorkByUser api/permission/user.ts:81 +POST /api/permission/Users/workHandover workHandover api/permission/user.ts:85 +DELETE /api/permission/Users/{param} delUser api/permission/user.ts:29 +GET /api/permission/Users/{param} getUserInfo api/permission/user.ts:25 +PUT /api/permission/Users/{param} updateUser api/permission/user.ts:21 +POST /api/permission/Users/{param}/Actions/ResetPassword resetUserPassword api/permission/user.ts:37 +PUT /api/permission/Users/{param}/Actions/unlock unlockUser api/permission/user.ts:45 +GET /api/permission/Users/{param}/GetPosition getUserPosition api/permission/user.ts:97 +GET /api/permission/Users/{param}/SelectorByUserPosId getSamePosUser api/permission/user.ts:93 +POST /api/permission/Users/{param}/SetPosition setUserPosition api/permission/user.ts:101 +GET /api/permission/socials getSocialsUserList api/permission/socialsUser.ts:9 +GET /api/permission/socials/render/{param} socialsBind api/permission/socialsUser.ts:17 +DELETE /api/permission/socials/{param} deleteSocials api/permission/socialsUser.ts:21 +GET /api/scheduletask getTaskList api/system/task.ts:9 +POST /api/scheduletask create api/system/task.ts:13 +GET /api/scheduletask/Info/{param} getInfo api/system/task.ts:21 +GET /api/scheduletask/TaskMethods getTaskMethodsList api/system/task.ts:33 +DELETE /api/scheduletask/{param} delTask api/system/task.ts:25 +PUT /api/scheduletask/{param} update api/system/task.ts:17 +GET /api/scheduletask/{param}/TaskLog getTaskLogList api/system/task.ts:29 +POST /api/system/AdvancedQuery create api/system/advancedQuery.ts:13 +DELETE /api/system/AdvancedQuery/{param} delAdvancedQuery api/system/advancedQuery.ts:25 +GET /api/system/AdvancedQuery/{param} getInfo api/system/advancedQuery.ts:21 +PUT /api/system/AdvancedQuery/{param} update api/system/advancedQuery.ts:17 +GET /api/system/AdvancedQuery/{param}/List getAdvancedQueryList api/system/advancedQuery.ts:9 +POST /api/system/Area createArea api/system/area.ts:21 +POST /api/system/Area/GetAreaByIds getAreaByIds api/system/area.ts:17 +DELETE /api/system/Area/{param} delArea api/system/area.ts:33 +GET /api/system/Area/{param} getAreaList api/system/area.ts:9 +PUT /api/system/Area/{param} updateArea api/system/area.ts:25 +GET /api/system/Area/{param}/Info getAreaInfo api/system/area.ts:29 +GET /api/system/Area/{param}/Selector/{param} getAreaSelector api/system/area.ts:13 +GET /api/system/BaseLang getBaseLangList api/system/baseLang.ts:9 +POST /api/system/BaseLang create api/system/baseLang.ts:13 +POST /api/system/BaseLang/ImportData importData api/system/baseLang.ts:37 +GET /api/system/BaseLang/LangJson getLangJson api/system/baseLang.ts:29 +GET /api/system/BaseLang/TemplateDownload templateDownload api/system/baseLang.ts:33 +DELETE /api/system/BaseLang/{param} delBaseLang api/system/baseLang.ts:25 +GET /api/system/BaseLang/{param} getInfo api/system/baseLang.ts:21 +PUT /api/system/BaseLang/{param} update api/system/baseLang.ts:17 +GET /api/system/BasicDataType getBasicDataTypeList api/systemData/basicDataType.ts:9 +POST /api/system/BasicDataType create api/systemData/basicDataType.ts:13 +DELETE /api/system/BasicDataType/{param} delBasicDataType api/systemData/basicDataType.ts:25 +GET /api/system/BasicDataType/{param} getInfo api/systemData/basicDataType.ts:21 +PUT /api/system/BasicDataType/{param} update api/systemData/basicDataType.ts:17 +GET /api/system/BillRule getBillRuleList api/system/billRule.ts:9 +POST /api/system/BillRule createBillRule api/system/billRule.ts:17 +GET /api/system/BillRule/BillNumber/{param} getBillNumber api/system/billRule.ts:33 +GET /api/system/BillRule/Selector getBillRuleSelector api/system/billRule.ts:13 +DELETE /api/system/BillRule/{param} delBillRule api/system/billRule.ts:29 +GET /api/system/BillRule/{param} getBillRuleInfo api/system/billRule.ts:25 +PUT /api/system/BillRule/{param} updateBillRule api/system/billRule.ts:21 +GET /api/system/BillRule/{param}/Actions/Export exportTpl api/system/billRule.ts:37 +GET /api/system/BusinessCategory getCategoryList api/system/businessCategory.ts:9 +POST /api/system/BusinessCategory create api/system/businessCategory.ts:13 +GET /api/system/BusinessCategory/selector getCategorySelector api/system/businessCategory.ts:33 +GET /api/system/BusinessCategory/treeList getCategoryTree api/system/businessCategory.ts:29 +DELETE /api/system/BusinessCategory/{param} delCategory api/system/businessCategory.ts:21 +GET /api/system/BusinessCategory/{param} getCategoryInfo api/system/businessCategory.ts:25 +PUT /api/system/BusinessCategory/{param} update api/system/businessCategory.ts:17 +GET /api/system/CacheManage getCacheList api/system/cache.ts:9 +POST /api/system/CacheManage/Actions/ClearAll delAllCache api/system/cache.ts:21 +DELETE /api/system/CacheManage/{param} delCache api/system/cache.ts:17 +GET /api/system/CacheManage/{param} getInfo api/system/cache.ts:13 +GET /api/system/CommonFields getCommonFieldsList api/systemData/commonFields.ts:9 +POST /api/system/CommonFields createCommonFields api/systemData/commonFields.ts:13 +DELETE /api/system/CommonFields/{param} delCommonFields api/systemData/commonFields.ts:25 +GET /api/system/CommonFields/{param} getCommonFieldsInfo api/systemData/commonFields.ts:21 +PUT /api/system/CommonFields/{param} updateCommonFields api/systemData/commonFields.ts:17 +GET /api/system/CommonWords getCommonWordsList api/system/commonWords.ts:9 +POST /api/system/CommonWords create api/system/commonWords.ts:17 +GET /api/system/CommonWords/Selector getCommonWordsSelector api/system/commonWords.ts:13 +DELETE /api/system/CommonWords/{param} delCommonWords api/system/commonWords.ts:29 +GET /api/system/CommonWords/{param} getInfo api/system/commonWords.ts:25 +PUT /api/system/CommonWords/{param} update api/system/commonWords.ts:21 +GET /api/system/DataBase getDataBaseList api/systemData/database.ts:10 +POST /api/system/DataBase create api/systemData/database.ts:14 +DELETE /api/system/DataBase/{param} delDataBase api/systemData/database.ts:26 +GET /api/system/DataBase/{param} getInfo api/systemData/database.ts:22 +PUT /api/system/DataBase/{param} update api/systemData/database.ts:18 +GET /api/system/DataInterface getList api/systemData/dataService.ts:9 +POST /api/system/DataInterface create api/systemData/dataService.ts:17 +GET /api/system/DataInterface/GetParam/{param} getDataServiceParam api/systemData/dataService.ts:53 +GET /api/system/DataInterface/getList getDataServiceList api/systemData/dataService.ts:13 +DELETE /api/system/DataInterface/{param} delDataService api/systemData/dataService.ts:29 +GET /api/system/DataInterface/{param} getInfo api/systemData/dataService.ts:25 +PUT /api/system/DataInterface/{param} update api/systemData/dataService.ts:21 +POST /api/system/DataInterface/{param}/Actions/Copy copy api/systemData/dataService.ts:33 +GET /api/system/DataInterface/{param}/Actions/Export exportData api/systemData/dataService.ts:37 +POST /api/system/DataInterface/{param}/Actions/Preview getDataServiceRes api/systemData/dataService.ts:49 +GET /api/system/DataInterface/{param}/get getDataServiceInfo api/systemData/dataService.ts:41 +POST /api/system/DataInterface/{param}/save save api/systemData/dataService.ts:45 +GET /api/system/DataInterfaceVariate/Selector getVariateSelector api/systemData/variate.ts:9 +POST /api/system/DataModel/{param}/Table createDataModel api/systemData/dataModel.ts:23 +PUT /api/system/DataModel/{param}/Table updateDataModel api/systemData/dataModel.ts:27 +DELETE /api/system/DataModel/{param}/Table/{param} delDataModel api/systemData/dataModel.ts:35 +GET /api/system/DataModel/{param}/Table/{param} getDataModelInfo api/systemData/dataModel.ts:31 +POST /api/system/DataModel/{param}/Table/{param}/Actions/Copy copy api/systemData/dataModel.ts:51 +GET /api/system/DataModel/{param}/Table/{param}/Actions/Export exportTable api/systemData/dataModel.ts:47 +GET /api/system/DataModel/{param}/Table/{param}/Preview previewDataModel api/systemData/dataModel.ts:19 +GET /api/system/DataModel/{param}/TableAll getDataModelListAll api/systemData/dataModel.ts:15 +GET /api/system/DataModel/{param}/Tables getDataModelList api/systemData/dataModel.ts:11 +GET /api/system/DataModel/{param}/Tables/{param}/Fields getDataModelFieldList api/systemData/dataModel.ts:39 +PUT /api/system/DataModel/{param}/addFields addTableFields api/systemData/dataModel.ts:43 +GET /api/system/DataSource getDataSourceList api/systemData/dataSource.ts:10 +POST /api/system/DataSource createDataSource api/systemData/dataSource.ts:19 +POST /api/system/DataSource/Actions/Test testDbConnection api/systemData/dataSource.ts:35 +GET /api/system/DataSource/Selector data api/systemData/dataSource.ts:15 +DELETE /api/system/DataSource/{param} delDataSource api/systemData/dataSource.ts:31 +GET /api/system/DataSource/{param} getDataSourceInfo api/systemData/dataSource.ts:27 +PUT /api/system/DataSource/{param} updateDataSource api/systemData/dataSource.ts:23 +POST /api/system/DataSync dataSync api/systemData/dataSource.ts:39 +POST /api/system/DataSync/Actions/Execute execute api/systemData/dataSource.ts:43 +POST /api/system/DataSync/Actions/batchExecute batchExecute api/systemData/dataSource.ts:47 +POST /api/system/DataSync/Actions/checkDbLink checkDbLink api/systemData/dataSource.ts:51 +GET /api/system/DataTypeMapping getDataTypeMappingList api/systemData/dataTypeMapping.ts:9 +POST /api/system/DataTypeMapping create api/systemData/dataTypeMapping.ts:13 +GET /api/system/DataTypeMapping/getKeyList getKeyList api/systemData/dataTypeMapping.ts:29 +DELETE /api/system/DataTypeMapping/{param} delDataTypeMapping api/systemData/dataTypeMapping.ts:25 +GET /api/system/DataTypeMapping/{param} getInfo api/systemData/dataTypeMapping.ts:21 +PUT /api/system/DataTypeMapping/{param} update api/systemData/dataTypeMapping.ts:17 +GET /api/system/DataTypeRelation getDataTypeRelationList api/systemData/database.ts:31 +POST /api/system/DataTypeRelation createDataTypeRelation api/systemData/database.ts:35 +DELETE /api/system/DataTypeRelation/{param} delDataTypeRelation api/systemData/database.ts:47 +GET /api/system/DataTypeRelation/{param} getDataTypeRelationInfo api/systemData/database.ts:43 +PUT /api/system/DataTypeRelation/{param} updateDataTypeRelation api/systemData/database.ts:39 +GET /api/system/Dataset getDatasetList api/systemData/dataset.ts:9 +POST /api/system/Dataset create api/systemData/dataset.ts:13 +GET /api/system/Dataset/GetParam/{param} getDatasetParam api/systemData/dataset.ts:33 +GET /api/system/Dataset/Selector getDatasetSelector api/systemData/dataset.ts:77 +POST /api/system/Dataset/fields getFields api/systemData/dataset.ts:81 +GET /api/system/Dataset/getList getDatasetSelectorList api/systemData/dataset.ts:65 +POST /api/system/Dataset/previewSql getPreviewSql api/systemData/dataset.ts:57 +DELETE /api/system/Dataset/{param} delDataset api/systemData/dataset.ts:25 +GET /api/system/Dataset/{param} getInfo api/systemData/dataset.ts:21 +PUT /api/system/Dataset/{param} update api/systemData/dataset.ts:17 +POST /api/system/Dataset/{param}/Actions/Copy copy api/systemData/dataset.ts:45 +GET /api/system/Dataset/{param}/Actions/Export exportData api/systemData/dataset.ts:37 +POST /api/system/Dataset/{param}/Actions/InfoByIds getDatasetDataInfoByIds api/systemData/dataset.ts:73 +POST /api/system/Dataset/{param}/Actions/List getDatasetDataSelect api/systemData/dataset.ts:69 +POST /api/system/Dataset/{param}/Actions/Preview getDatasetRes api/systemData/dataset.ts:29 +POST /api/system/Dataset/{param}/Actions/getRes getPreviewRes api/systemData/dataset.ts:61 +GET /api/system/Dataset/{param}/get getDatasetInfo api/systemData/dataset.ts:49 +POST /api/system/Dataset/{param}/save save api/systemData/dataset.ts:53 +GET /api/system/DatasetLog/{param} getDataSetLog api/systemData/dataset.ts:41 +POST /api/system/DictionaryData createDictionaryData api/systemData/dictionary.ts:51 +GET /api/system/DictionaryData/All getDictionaryAll api/systemData/dictionary.ts:39 +DELETE /api/system/DictionaryData/{param} delDictionaryData api/systemData/dictionary.ts:63 +GET /api/system/DictionaryData/{param} getDictionaryDataList api/systemData/dictionary.ts:35 +PUT /api/system/DictionaryData/{param} updateDictionaryData api/systemData/dictionary.ts:55 +GET /api/system/DictionaryData/{param}/Actions/Export exportData api/systemData/dictionary.ts:67 +GET /api/system/DictionaryData/{param}/Data/Selector getDictionaryDataSelector api/systemData/dictionary.ts:47 +GET /api/system/DictionaryData/{param}/Info getDictionaryDataInfo api/systemData/dictionary.ts:59 +GET /api/system/DictionaryData/{param}/Selector/{param} getDictionaryDataTypeSelector api/systemData/dictionary.ts:43 +GET /api/system/DictionaryType getDictionaryType api/systemData/dictionary.ts:10 +POST /api/system/DictionaryType createDictionaryType api/systemData/dictionary.ts:18 +GET /api/system/DictionaryType/Selector/{param} getDictionaryTypeSelector api/systemData/dictionary.ts:14 +DELETE /api/system/DictionaryType/{param} delDictionaryType api/systemData/dictionary.ts:30 +GET /api/system/DictionaryType/{param} getDictionaryTypeInfo api/systemData/dictionary.ts:26 +PUT /api/system/DictionaryType/{param} updateDictionaryType api/systemData/dictionary.ts:22 +GET /api/system/HomeData getHomeData api/system/homeData.ts:9 +GET /api/system/HomeData/mySystem getMySystem api/system/homeData.ts:13 +GET /api/system/InterfaceOauth getInterfaceOauthList api/systemData/openApi.ts:9 +POST /api/system/InterfaceOauth create api/systemData/openApi.ts:13 +POST /api/system/InterfaceOauth/SaveUserList saveUserList api/systemData/openApi.ts:45 +GET /api/system/InterfaceOauth/dataInterfaceLog/{param} getLogList api/systemData/openApi.ts:41 +GET /api/system/InterfaceOauth/getAppId getAppId api/systemData/openApi.ts:29 +POST /api/system/InterfaceOauth/getInterfaceList getInterfaceList api/systemData/openApi.ts:37 +GET /api/system/InterfaceOauth/interfaceSelector getInterfaceSelector api/systemData/openApi.ts:49 +POST /api/system/InterfaceOauth/saveInterfaceList saveInterfaceList api/systemData/openApi.ts:33 +DELETE /api/system/InterfaceOauth/{param} delInterfaceOauth api/systemData/openApi.ts:21 +GET /api/system/InterfaceOauth/{param} getInfo api/systemData/openApi.ts:25 +PUT /api/system/InterfaceOauth/{param} update api/systemData/openApi.ts:17 +GET /api/system/Kit getKitList api/system/kit.ts:9 +POST /api/system/Kit create api/system/kit.ts:17 +GET /api/system/Kit/Selector getKitSelector api/system/kit.ts:13 +DELETE /api/system/Kit/{param} delKit api/system/kit.ts:29 +GET /api/system/Kit/{param} getInfo api/system/kit.ts:25 +PUT /api/system/Kit/{param} update api/system/kit.ts:21 +POST /api/system/Kit/{param}/Actions/Copy copy api/system/kit.ts:33 +GET /api/system/Kit/{param}/Actions/Export exportTpl api/system/kit.ts:37 +GET /api/system/Location/around getMapAroundList api/core/common.ts:45 +GET /api/system/Location/inputtips getInputTips api/core/common.ts:53 +GET /api/system/Location/text getMapTextList api/core/common.ts:49 +DELETE /api/system/Log delLog api/system/log.ts:13 +GET /api/system/Log getLogList api/system/log.ts:9 +DELETE /api/system/Log/deleteLoginLog batchDelLoginLog api/system/log.ts:25 +GET /api/system/Log/{param} getInfo api/system/log.ts:21 +DELETE /api/system/Log/{param}${interfaceId batchDelLog api/system/log.ts:17 +POST /api/system/Menu create api/system/menu.ts:21 +GET /api/system/Menu/ModuleBySystem getMenuList api/system/menu.ts:9 +GET /api/system/Menu/Selector/${ getMenuSelector api/system/menu.ts:13 +GET /api/system/Menu/Selector/All getSelectorAll api/system/menu.ts:17 +GET /api/system/Menu/Selector/Form getMenuSelectorForm api/system/menu.ts:53 +GET /api/system/Menu/Selector/Page getMenuListFormType api/system/menu.ts:61 +GET /api/system/Menu/SelectorFilter/{param} getMenuSelectorFilter api/system/menu.ts:49 +GET /api/system/Menu/getPermission/{param}/{param} getMenuPermissionInfo api/system/menu.ts:45 +GET /api/system/Menu/getPermissionGroup/{param} getMenuPermissionGroup api/system/menu.ts:41 +GET /api/system/Menu/getSystemMenu getMenuSelectorFormTree api/system/menu.ts:57 +DELETE /api/system/Menu/{param} delMenu api/system/menu.ts:33 +GET /api/system/Menu/{param} getInfo api/system/menu.ts:29 +PUT /api/system/Menu/{param} update api/system/menu.ts:25 +GET /api/system/Menu/{param}/Actions/Export exportMenu api/system/menu.ts:37 +GET /api/system/MenuData getCollectMenuList api/system/collectMenu.ts:9 +POST /api/system/MenuData/useModuleNum/{param} addCommonMenu api/system/collectMenu.ts:21 +DELETE /api/system/MenuData/{param} deLCollectMenu api/system/collectMenu.ts:17 +POST /api/system/MenuData/{param} createCollectMenu api/system/collectMenu.ts:13 +POST /api/system/ModuleButton create api/system/buttonAuthorize.ts:17 +POST /api/system/ModuleButton/selectActions/{param} selectActions api/system/buttonAuthorize.ts:33 +DELETE /api/system/ModuleButton/{param} del api/system/buttonAuthorize.ts:29 +GET /api/system/ModuleButton/{param} getInfo api/system/buttonAuthorize.ts:25 +PUT /api/system/ModuleButton/{param} update api/system/buttonAuthorize.ts:21 +GET /api/system/ModuleButton/{param}/List getButtonAuthorizeList api/system/buttonAuthorize.ts:9 +GET /api/system/ModuleButton/{param}/Selector getButtonAuthorizeSelector api/system/buttonAuthorize.ts:13 +POST /api/system/ModuleColumn create api/system/columnAuthorize.ts:13 +POST /api/system/ModuleColumn/Actions/Batch batchCreate api/system/columnAuthorize.ts:17 +DELETE /api/system/ModuleColumn/{param} del api/system/columnAuthorize.ts:29 +GET /api/system/ModuleColumn/{param} getInfo api/system/columnAuthorize.ts:25 +PUT /api/system/ModuleColumn/{param} update api/system/columnAuthorize.ts:21 +GET /api/system/ModuleColumn/{param}/Fields getColumnAuthorizeList api/system/columnAuthorize.ts:9 +GET /api/system/ModuleDataAuthorizeLink/getInfo/{param}/{param} getInfo api/system/authorize.ts:21 +GET /api/system/ModuleDataAuthorizeLink/getVisualTables/{param}/{param} getVisualTables api/system/authorize.ts:9 +POST /api/system/ModuleDataAuthorizeLink/saveLinkData update api/system/authorize.ts:17 +GET /api/system/ModuleDataAuthorizeLink/{param}/Tables/{param}/Fields/{param}/{param} getTableInfoByTableName api/system/authorize.ts:13 +POST /api/system/ModuleDataAuthorizeScheme create api/system/dataAuthorize.ts:13 +DELETE /api/system/ModuleDataAuthorizeScheme/{param} del api/system/dataAuthorize.ts:25 +GET /api/system/ModuleDataAuthorizeScheme/{param} getInfo api/system/dataAuthorize.ts:21 +PUT /api/system/ModuleDataAuthorizeScheme/{param} update api/system/dataAuthorize.ts:17 +GET /api/system/ModuleDataAuthorizeScheme/{param}/List getDataAuthorizeList api/system/dataAuthorize.ts:9 +POST /api/system/ModuleForm create api/system/formAuthorize.ts:13 +POST /api/system/ModuleForm/Actions/Batch batchCreate api/system/formAuthorize.ts:17 +DELETE /api/system/ModuleForm/{param} del api/system/formAuthorize.ts:29 +GET /api/system/ModuleForm/{param} getInfo api/system/formAuthorize.ts:25 +PUT /api/system/ModuleForm/{param} update api/system/formAuthorize.ts:21 +GET /api/system/ModuleForm/{param}/Fields getFormAuthorizeList api/system/formAuthorize.ts:9 +GET /api/system/Monitor getSysMonitor api/system/monitor.ts:9 +DELETE /api/system/OnlineUser batchDelOnlineUser api/permission/onlineUser.ts:13 +GET /api/system/OnlineUser getOnlineUser api/permission/onlineUser.ts:9 +DELETE /api/system/OnlineUser/{param} deleteOnlineUser api/permission/onlineUser.ts:17 +POST /api/system/PortalManage createPortalManage api/onlineDev/portal.ts:92 +GET /api/system/PortalManage/list/{param} getPortalManageList api/onlineDev/portal.ts:80 +DELETE /api/system/PortalManage/{param} delPortalManage api/onlineDev/portal.ts:100 +GET /api/system/PortalManage/{param} getPortalManageInfo api/onlineDev/portal.ts:88 +PUT /api/system/PortalManage/{param} updatePortalManage api/onlineDev/portal.ts:96 +GET /api/system/Schedule getScheduleList api/teamwork/schedule.ts:9 +POST /api/system/Schedule createSchedule api/teamwork/schedule.ts:13 +GET /api/system/Schedule/detail getScheduleDetail api/teamwork/schedule.ts:29 +GET /api/system/Schedule/{param} getScheduleInfo api/teamwork/schedule.ts:25 +DELETE /api/system/Schedule/{param}/{param} delSchedule api/teamwork/schedule.ts:21 +PUT /api/system/Schedule/{param}/{param} updateSchedule api/teamwork/schedule.ts:17 +GET /api/system/Signature getSignatureList api/system/signature.ts:9 +POST /api/system/Signature create api/system/signature.ts:17 +POST /api/system/Signature/ListByIds getSignatureListByIds api/system/signature.ts:33 +GET /api/system/Signature/Selector getSignatureSelector api/system/signature.ts:13 +DELETE /api/system/Signature/{param} delSignature api/system/signature.ts:29 +GET /api/system/Signature/{param} getInfo api/system/signature.ts:25 +PUT /api/system/Signature/{param} update api/system/signature.ts:21 +POST /api/system/SynThirdInfo synThirdInfo api/system/sysConfig.ts:34 +GET /api/system/SynThirdInfo/clearAllSyn clearAllSyn api/system/sysConfig.ts:44 +GET /api/system/SynThirdInfo/getHandleNum getHandleNum api/system/sysConfig.ts:56 +GET /api/system/SynThirdInfo/getSynThirdTotal/{param} getSynData api/system/sysConfig.ts:39 +GET /api/system/SysConfig getSysConfig api/system/sysConfig.ts:10 +PUT /api/system/SysConfig update api/system/sysConfig.ts:14 +GET /api/system/SysConfig/getAdminList getAdminList api/system/sysConfig.ts:26 +PUT /api/system/SysConfig/setAdminList setAdminList api/system/sysConfig.ts:30 +GET /api/system/SysConfig/socials getSocialsConfig api/system/sysConfig.ts:48 +PUT /api/system/SysConfig/socials updateSocialsConfig api/system/sysConfig.ts:52 +POST /api/system/SysConfig/testDingTalkConnect testDing api/system/sysConfig.ts:22 +POST /api/system/SysConfig/{param}/testQyWebChatConnect testQy api/system/sysConfig.ts:18 +GET /api/system/System getSystemList api/system/system.ts:9 +POST /api/system/System create api/system/system.ts:17 +GET /api/system/System/Selector getSystemSelector api/system/system.ts:57 +POST /api/system/System/actionTop setPin api/system/system.ts:65 +POST /api/system/System/changeAppAuthorization changeAppAuth api/system/system.ts:49 +GET /api/system/System/getAppAuthorization/{param} getAppAuth api/system/system.ts:41 +GET /api/system/System/getDevUser getDevUser api/system/system.ts:53 +POST /api/system/System/saveAppAuthorization saveAppAuth api/system/system.ts:45 +GET /api/system/System/userAuthList getAuthSystemList api/system/system.ts:13 +DELETE /api/system/System/{param} delSystem api/system/system.ts:29 +GET /api/system/System/{param} getInfo api/system/system.ts:25 +PUT /api/system/System/{param} update api/system/system.ts:21 +POST /api/system/System/{param}/Actions/Copy copySystem api/system/system.ts:33 +GET /api/system/System/{param}/Actions/Export exportSystem api/system/system.ts:37 +GET /api/system/Tag getTagList api/system/tag.ts:9 +POST /api/system/Tag create api/system/tag.ts:17 +GET /api/system/Tag/selector getTagSelector api/system/tag.ts:33 +DELETE /api/system/Tag/{param} delTag api/system/tag.ts:25 +GET /api/system/Tag/{param} getTagInfo api/system/tag.ts:13 +PUT /api/system/Tag/{param} update api/system/tag.ts:21 +GET /api/system/Tag/{param}/Actions/Export exportTag api/system/tag.ts:29 +GET /api/system/Variate getVariableList api/system/variate.ts:9 +POST /api/system/Variate createVariable api/system/variate.ts:13 +GET /api/system/Variate/selector getVariableSelector api/system/variate.ts:29 +GET /api/system/Variate/sysfunccategory getSysFuncCategoryList api/system/variate.ts:37 +GET /api/system/Variate/sysfunctree getSysFuncTree api/system/variate.ts:45 +GET /api/system/Variate/sysvariate getSysVariableList api/system/variate.ts:33 +DELETE /api/system/Variate/{param} delVariable api/system/variate.ts:25 +GET /api/system/Variate/{param} getVariable api/system/variate.ts:21 +PUT /api/system/Variate/{param} updateVariable api/system/variate.ts:17 +GET /api/system/Variate/{param}/sysfunc getSysFunctionList api/system/variate.ts:41 +GET /api/system/atlas getAtlas api/onlineDev/portal.ts:56 +GET /api/system/atlas/geojson getMapData api/onlineDev/portal.ts:60 +GET /api/system/printDev getPrintDevList api/system/printDev.ts:9 +POST /api/system/printDev createPrintDev api/system/printDev.ts:25 +POST /api/system/printDev/BatchData getBatchData api/system/printDev.ts:53 +DELETE /api/system/printDev/Info/{param} delVersion api/system/printDev.ts:69 +GET /api/system/printDev/Info/{param} getVersionInfo api/system/printDev.ts:61 +POST /api/system/printDev/Info/{param} copyVersion api/system/printDev.ts:73 +POST /api/system/printDev/Save saveVersion api/system/printDev.ts:57 +GET /api/system/printDev/Selector getPrintDevSelector api/system/printDev.ts:13 +GET /api/system/printDev/Version/{param} getVersionList api/system/printDev.ts:65 +GET /api/system/printDev/WorkSelector getPrintWorkSelector api/system/printDev.ts:17 +POST /api/system/printDev/getListOptions getPrintDevByIds api/system/printDev.ts:21 +DELETE /api/system/printDev/{param} delPrintDev api/system/printDev.ts:37 +GET /api/system/printDev/{param} getPrintDevInfo api/system/printDev.ts:33 +PUT /api/system/printDev/{param} updatePrintDev api/system/printDev.ts:29 +POST /api/system/printDev/{param}/Actions/Copy copy api/system/printDev.ts:41 +GET /api/system/printDev/{param}/Actions/Export exportData api/system/printDev.ts:45 +GET /api/system/printDev/{param}/Actions/Preview getPreviewInfo api/system/printDev.ts:49 +GET /api/visualdev/Base getVisualDevList api/onlineDev/visualDev.ts:15 +POST /api/visualdev/Base create api/onlineDev/visualDev.ts:23 +GET /api/visualdev/Base/Selector getVisualDevSelector api/onlineDev/visualDev.ts:63 +GET /api/visualdev/Base/getColumnList getColumnList api/onlineDev/visualDev.ts:67 +GET /api/visualdev/Base/getListBySystem getListBySystem api/onlineDev/visualDev.ts:175 +GET /api/visualdev/Base/list getVisualDevFormList api/onlineDev/visualDev.ts:19 +DELETE /api/visualdev/Base/{param} delVisualDev api/onlineDev/visualDev.ts:35 +GET /api/visualdev/Base/{param} getInfo api/onlineDev/visualDev.ts:31 +PUT /api/visualdev/Base/{param} update api/onlineDev/visualDev.ts:27 +POST /api/visualdev/Base/{param}/Actions/Copy copy api/onlineDev/visualDev.ts:39 +POST /api/visualdev/Base/{param}/Actions/Module createMenu api/onlineDev/visualDev.ts:51 +POST /api/visualdev/Base/{param}/Actions/Release release api/onlineDev/visualDev.ts:43 +GET /api/visualdev/Base/{param}/FieldDataSelect getFieldDataSelect api/onlineDev/visualDev.ts:59 +GET /api/visualdev/Base/{param}/FormDataFields getFormDataFields api/onlineDev/visualDev.ts:55 +GET /api/visualdev/Base/{param}/getReleaseMenu getReleaseMenu api/onlineDev/visualDev.ts:47 +GET /api/visualdev/Dashboard/Email getEmailList api/onlineDev/portal.ts:72 +POST /api/visualdev/Dashboard/Notice getNoticeList api/onlineDev/portal.ts:68 +POST /api/visualdev/Generater/{param}/Actions/CodePreview codePreview api/onlineDev/visualDev.ts:76 +POST /api/visualdev/Generater/{param}/Actions/DownloadCode downloadCode api/onlineDev/visualDev.ts:72 +GET /api/visualdev/Generater/{param}/Alias/Info getAliasInfo api/onlineDev/visualDev.ts:80 +POST /api/visualdev/Generater/{param}/Alias/Save saveAlias api/onlineDev/visualDev.ts:84 +GET /api/visualdev/OnlineDev/Config getConfigDataByMenuId api/onlineDev/visualDev.ts:93 +POST /api/visualdev/OnlineDev/RelationQuery getRelationQueryList api/onlineDev/visualDev.ts:149 +POST /api/visualdev/OnlineDev/batchDelete/{param} batchDelete api/onlineDev/visualDev.ts:125 +POST /api/visualdev/OnlineDev/{param} createModel api/onlineDev/visualDev.ts:105 +POST /api/visualdev/OnlineDev/{param}/Actions/Export exportData api/onlineDev/visualDev.ts:141 +POST /api/visualdev/OnlineDev/{param}/Actions/ExportData exportModel api/onlineDev/visualDev.ts:133 +GET /api/visualdev/OnlineDev/{param}/Config getConfigData api/onlineDev/visualDev.ts:89 +POST /api/visualdev/OnlineDev/{param}/DataChange getDataChange api/onlineDev/visualDev.ts:129 +GET /api/visualdev/OnlineDev/{param}/FormData getFormData api/onlineDev/visualDev.ts:97 +POST /api/visualdev/OnlineDev/{param}/List getModelList api/onlineDev/visualDev.ts:101 +GET /api/visualdev/OnlineDev/{param}/Template getTemplate api/onlineDev/visualDev.ts:137 +POST /api/visualdev/OnlineDev/{param}/actionLaunchFlow launchFlow api/onlineDev/visualDev.ts:145 +DELETE /api/visualdev/OnlineDev/{param}/{param} delModel api/onlineDev/visualDev.ts:121 +GET /api/visualdev/OnlineDev/{param}/{param} getModelInfo api/onlineDev/visualDev.ts:113 +PUT /api/visualdev/OnlineDev/{param}/{param} updateModel api/onlineDev/visualDev.ts:109 +GET /api/visualdev/OnlineLog getDataLogList api/onlineDev/visualDev.ts:117 +GET /api/visualdev/Portal getPortalList api/onlineDev/portal.ts:12 +POST /api/visualdev/Portal createPortal api/onlineDev/portal.ts:28 +PUT /api/visualdev/Portal/Actions/release/{param} release api/onlineDev/portal.ts:76 +PUT /api/visualdev/Portal/Custom/Save/{param} UpdateCustomPortal api/onlineDev/portal.ts:64 +GET /api/visualdev/Portal/Selector getPortalSelector api/onlineDev/portal.ts:40 +GET /api/visualdev/Portal/Selector/Menu getHomePortalList api/onlineDev/portal.ts:44 +GET /api/visualdev/Portal/manage/Selector/{param} getPortalManageSelector api/onlineDev/portal.ts:84 +GET /api/visualdev/Portal/systemFilter/{param} getSystemListFilter api/onlineDev/portal.ts:104 +DELETE /api/visualdev/Portal/{param} delPortal api/onlineDev/portal.ts:20 +GET /api/visualdev/Portal/{param} getInfo api/onlineDev/portal.ts:16 +PUT /api/visualdev/Portal/{param} updatePortal api/onlineDev/portal.ts:24 +POST /api/visualdev/Portal/{param}/Actions/Copy copyPortal api/onlineDev/portal.ts:32 +POST /api/visualdev/Portal/{param}/Actions/Export exportPortal api/onlineDev/portal.ts:36 +PUT /api/visualdev/Portal/{param}/Actions/SetDefault setDefaultPortal api/onlineDev/portal.ts:48 +GET /api/visualdev/Portal/{param}/auth getAuthPortal api/onlineDev/portal.ts:52 +PUT /api/visualdev/ShortLink updateShortLink api/onlineDev/shortLink.ts:13 +POST /api/visualdev/ShortLink/checkPwd checkPwd api/onlineDev/shortLink.ts:21 +GET /api/visualdev/ShortLink/getConfig/{param}${encryption getConfig api/onlineDev/shortLink.ts:17 +GET /api/visualdev/ShortLink/{param} getShortLinkInfo api/onlineDev/shortLink.ts:9 +POST /api/visualdev/ShortLink/{param}${encryption createModel api/onlineDev/shortLink.ts:33 +GET /api/visualdev/ShortLink/{param}/Config${encryption getConfigData api/onlineDev/shortLink.ts:25 +POST /api/visualdev/ShortLink/{param}/ListLink${data.encryption getModelList api/onlineDev/shortLink.ts:29 +GET /api/visualdev/ShortLink/{param}/{param}/DataChange${encryption getDataChange api/onlineDev/shortLink.ts:37 +POST /api/visualdev/ocr getOcrData api/onlineDev/visualDev.ts:196 +GET /api/visualdev/personal getViewList api/onlineDev/visualDev.ts:154 +POST /api/visualdev/personal createView api/onlineDev/visualDev.ts:162 +DELETE /api/visualdev/personal/{param} delView api/onlineDev/visualDev.ts:158 +PUT /api/visualdev/personal/{param} updateView api/onlineDev/visualDev.ts:166 +PUT /api/visualdev/personal/{param}/setDefault setDefaultView api/onlineDev/visualDev.ts:170 +GET /api/visualdev/share getShareList api/onlineDev/visualDev.ts:179 +POST /api/visualdev/share/SelectedList getShareInfo api/onlineDev/visualDev.ts:183 +GET /api/visualdev/share/Selector getShareSelector api/onlineDev/visualDev.ts:191 +POST /api/visualdev/share/save saveShare api/onlineDev/visualDev.ts:187 +GET /api/workflow/Hooks/getParams/{param} getWebhookParams api/workFlow/template.ts:127 +GET /api/workflow/Hooks/getUrl getWebhookUrl api/workFlow/template.ts:123 +GET /api/workflow/Hooks/{param}/start/{param} webhookStart api/workFlow/template.ts:131 +GET /api/workflow/comment getCommentList api/workFlow/template.ts:110 +POST /api/workflow/comment createComment api/workFlow/template.ts:114 +DELETE /api/workflow/comment/{param} delComment api/workFlow/template.ts:118 +GET /api/workflow/delegate getFlowDelegateList api/workFlow/flowDelegate.ts:9 +POST /api/workflow/delegate create api/workFlow/flowDelegate.ts:13 +GET /api/workflow/delegate/Info/{param} getFlowDelegateInfo api/workFlow/flowDelegate.ts:37 +POST /api/workflow/delegate/Notarize/{param} notarize api/workFlow/flowDelegate.ts:41 +PUT /api/workflow/delegate/Stop/{param} stop api/workFlow/flowDelegate.ts:33 +GET /api/workflow/delegate/UserList getDelegateUser api/workFlow/flowDelegate.ts:29 +DELETE /api/workflow/delegate/{param} del api/workFlow/flowDelegate.ts:25 +GET /api/workflow/delegate/{param} getInfo api/workFlow/flowDelegate.ts:21 +PUT /api/workflow/delegate/{param} update api/workFlow/flowDelegate.ts:17 +DELETE /api/workflow/monitor delMonitorList api/workFlow/flowMonitor.ts:13 +GET /api/workflow/monitor getFlowMonitorList api/workFlow/flowMonitor.ts:9 +POST /api/workflow/monitor/Activate/{param} resurgence api/workFlow/flowMonitor.ts:29 +GET /api/workflow/monitor/AnySubFlow/{param} getPauseType api/workFlow/flowMonitor.ts:33 +POST /api/workflow/monitor/Assign/{param} assign api/workFlow/flowMonitor.ts:25 +POST /api/workflow/monitor/Cancel/{param} cancel api/workFlow/flowMonitor.ts:21 +GET /api/workflow/monitor/FlowTodo getFlowTodoList api/workFlow/flowMonitor.ts:49 +POST /api/workflow/monitor/FlowTodoCount getFlowTodoCount api/workFlow/flowMonitor.ts:45 +POST /api/workflow/monitor/Pause/{param} pause api/workFlow/flowMonitor.ts:37 +POST /api/workflow/monitor/Reboot/{param} reboot api/workFlow/flowMonitor.ts:41 +GET /api/workflow/monitor/{param}/EventLog getLogList api/workFlow/flowMonitor.ts:17 +POST /api/workflow/operator/AddSign/{param} freeApprover api/workFlow/task.ts:164 +POST /api/workflow/operator/AddSignUserIdList/{param} getFreeApproverUserList api/workFlow/task.ts:100 +POST /api/workflow/operator/Assist/{param} assist api/workFlow/task.ts:124 +POST /api/workflow/operator/AssistSave/{param} saveAssist api/workFlow/task.ts:112 +POST /api/workflow/operator/Audit/{param} audit api/workFlow/task.ts:96 +GET /api/workflow/operator/BatchCandidate getBatchCandidate api/workFlow/task.ts:132 +GET /api/workflow/operator/BatchFlowSelector getBatchFlowSelector api/workFlow/task.ts:136 +GET /api/workflow/operator/BatchNode getBatchNode api/workFlow/task.ts:148 +GET /api/workflow/operator/BatchNodeSelector/{param} getBatchNodeSelector api/workFlow/task.ts:144 +POST /api/workflow/operator/BatchOperation batchOperation api/workFlow/task.ts:128 +GET /api/workflow/operator/BatchVersionSelector/{param} getBatchVersionSelector api/workFlow/task.ts:140 +POST /api/workflow/operator/CandidateNode/{param} getCandidates api/workFlow/task.ts:68 +POST /api/workflow/operator/CandidateUser/{param} getCandidateUser api/workFlow/task.ts:64 +GET /api/workflow/operator/CirculateList getCirculateList api/workFlow/task.ts:180 +GET /api/workflow/operator/List/{param} getFlowBeforeList api/workFlow/task.ts:72 +POST /api/workflow/operator/Recall/{param} auditRecall api/workFlow/task.ts:116 +GET /api/workflow/operator/RecordList getRecordList api/workFlow/task.ts:168 +POST /api/workflow/operator/ReduceApprover/{param} reduceApprover api/workFlow/task.ts:104 +POST /api/workflow/operator/SaveAudit/{param} saveAudit api/workFlow/task.ts:108 +POST /api/workflow/operator/SendBack/{param} back api/workFlow/task.ts:156 +GET /api/workflow/operator/SendBackNodeList/{param} getBackNodeCodeList api/workFlow/task.ts:160 +POST /api/workflow/operator/Sign batchSign api/workFlow/task.ts:76 +POST /api/workflow/operator/Transact batchHandle api/workFlow/task.ts:88 +POST /api/workflow/operator/Transfer/{param} transfer api/workFlow/task.ts:120 +GET /api/workflow/operator/{param}/Info checkInfo api/workFlow/task.ts:152 +GET /api/workflow/task getFlowLaunchList api/workFlow/task.ts:16 +POST /api/workflow/task create api/workFlow/task.ts:27 +GET /api/workflow/task/Hooks/Retry/{param} retryOutside api/workFlow/task.ts:176 +POST /api/workflow/task/Press/{param} press api/workFlow/task.ts:47 +PUT /api/workflow/task/Recall/{param} launchRecall api/workFlow/task.ts:39 +PUT /api/workflow/task/Revoke/{param} revoke api/workFlow/task.ts:43 +GET /api/workflow/task/SubFlowInfo getSubFlowInfo api/workFlow/task.ts:59 +GET /api/workflow/task/TaskUserList/{param} getTaskUserList api/workFlow/task.ts:55 +GET /api/workflow/task/ViewStartForm/{param} getStartFormInfo api/workFlow/task.ts:172 +DELETE /api/workflow/task/{param} delFlowLaunch api/workFlow/task.ts:35 +GET /api/workflow/task/{param} newId api/workFlow/task.ts:23 +PUT /api/workflow/task/{param} update api/workFlow/task.ts:31 +GET /api/workflow/task/{param}/EventLog getLogList api/workFlow/task.ts:51 +GET /api/workflow/template getList api/workFlow/template.ts:11 +POST /api/workflow/template create api/workFlow/template.ts:19 +POST /api/workflow/template/GetFlowList getFlowEngineListByIds api/workFlow/template.ts:87 +DELETE /api/workflow/template/Info/{param} delVersion api/workFlow/template.ts:59 +GET /api/workflow/template/Info/{param} getFlowInfo api/workFlow/template.ts:51 +POST /api/workflow/template/Info/{param} copyVersion api/workFlow/template.ts:63 +POST /api/workflow/template/Save saveFlow api/workFlow/template.ts:47 +GET /api/workflow/template/Selector getFlowSelector api/workFlow/template.ts:67 +POST /api/workflow/template/SetCommonFlow/{param} setCollectFlow api/workFlow/template.ts:95 +GET /api/workflow/template/StartForm/{param} getFlowStartFormInfo api/workFlow/template.ts:75 +GET /api/workflow/template/StartFormId/{param} getFlowStartFormId api/workFlow/template.ts:79 +GET /api/workflow/template/TreeList getTreeList api/workFlow/template.ts:83 +GET /api/workflow/template/Version/{param} getVersionList api/workFlow/template.ts:55 +GET /api/workflow/template/getCommonFlowList getCollectFlowList api/workFlow/template.ts:91 +DELETE /api/workflow/template/{param} delFlow api/workFlow/template.ts:31 +GET /api/workflow/template/{param} getInfo api/workFlow/template.ts:27 +PUT /api/workflow/template/{param} update api/workFlow/template.ts:23 +POST /api/workflow/template/{param}/Actions/Copy copy api/workFlow/template.ts:35 +GET /api/workflow/template/{param}/Actions/Export exportData api/workFlow/template.ts:39 +GET /api/workflow/template/{param}/DecisionParameter getDecisionParameter api/workFlow/template.ts:106 +GET /api/workflow/template/{param}/FlowList getFlowList api/workFlow/template.ts:15 +GET /api/workflow/template/{param}/FormInfo getFlowFormInfo api/workFlow/template.ts:71 +GET /api/workflow/template/{param}/SubFlowUserList getSubFlowUserList api/workFlow/template.ts:99 +PUT /api/workflow/template/{param}/UpDownShelf upDownShelf api/workFlow/template.ts:103 +PUT /api/workflow/template/{param}/UpdateType changeType api/workFlow/template.ts:43 +DELETE /api/workflow/trigger/task delTaskMonitor api/workFlow/trigger.ts:17 +GET /api/workflow/trigger/task getTaskMonitorList api/workFlow/trigger.ts:13 +GET /api/workflow/trigger/task/List getTaskLogList api/workFlow/trigger.ts:9 +POST /api/workflow/trigger/task/Retry/{param} retryTask api/workFlow/trigger.ts:21 +POST /api/{param}/ImportData importData api/core/common.ts:37 +POST /api/{param}/ImportExceptionData getImportExceptionData api/core/common.ts:41 +GET /api/{param}/ImportPreview getImportPreview api/core/common.ts:33 +GET /api/{param}/TemplateDownload getTemplateDownload api/core/common.ts:29 diff --git a/docs/fe/gap-permission.tsv b/docs/fe/gap-permission.tsv new file mode 100644 index 0000000..32fbda2 --- /dev/null +++ b/docs/fe/gap-permission.tsv @@ -0,0 +1,133 @@ +MODULE METHOD PATH FUNC WHERE IMPL +permission GET /api/permission/Action getActionList api/permission/action.ts:9 N +permission POST /api/permission/Action create api/permission/action.ts:13 N +permission DELETE /api/permission/Action/{param} delAction api/permission/action.ts:25 N +permission GET /api/permission/Action/{param} getInfo api/permission/action.ts:21 N +permission PUT /api/permission/Action/{param} update api/permission/action.ts:17 N +permission GET /api/permission/Authority/{param}/{param} getCommonAuthValues api/permission/auth.ts:17 N +permission POST /api/permission/Authority/{param}/{param} updateCommonAuthList api/permission/auth.ts:21 N +permission GET /api/permission/Group getGroupList api/permission/group.ts:9 N +permission POST /api/permission/Group create api/permission/group.ts:17 N +permission POST /api/permission/Group/GroupCondition getGroupByCondition api/permission/group.ts:33 N +permission GET /api/permission/Group/Selector getGroupSelector api/permission/group.ts:13 N +permission DELETE /api/permission/Group/{param} delGroup api/permission/group.ts:29 N +permission GET /api/permission/Group/{param} getInfo api/permission/group.ts:25 N +permission PUT /api/permission/Group/{param} update api/permission/group.ts:21 N +permission POST /api/permission/Group/{param}/Actions/AddUser addGroupUser api/permission/group.ts:37 N +permission POST /api/permission/Group/{param}/Actions/DeleteUser removeGroupUser api/permission/group.ts:41 N +permission GET /api/permission/Organize getOrganizeList api/permission/organize.ts:14 N +permission POST /api/permission/Organize create api/permission/organize.ts:18 N +permission GET /api/permission/Organize/AsyncPosList getOrgAndPosSelector api/permission/organize.ts:68 N +permission GET /api/permission/Organize/ExportData exportExcel api/permission/organize.ts:34 N +permission POST /api/permission/Organize/ExportExceptionData exportExceptionData api/permission/organize.ts:50 N +permission POST /api/permission/Organize/ImportData importData api/permission/organize.ts:42 N +permission GET /api/permission/Organize/ImportPreview importPreview api/permission/organize.ts:46 N +permission POST /api/permission/Organize/OrganizeCondition getOrgByOrganizeCondition api/permission/organize.ts:63 N +permission POST /api/permission/Organize/SelectedList getOrgSelectedList api/permission/organize.ts:59 N +permission GET /api/permission/Organize/Selector getOrganizeSelector api/permission/organize.ts:55 N +permission GET /api/permission/Organize/TemplateDownload templateDownload api/permission/organize.ts:38 N +permission DELETE /api/permission/Organize/{param} delOrganize api/permission/organize.ts:30 N +permission GET /api/permission/Organize/{param} getInfo api/permission/organize.ts:26 N +permission PUT /api/permission/Organize/{param} update api/permission/organize.ts:22 N +permission GET /api/permission/PermissionGroup getList api/permission/authGroup.ts:9 N +permission POST /api/permission/PermissionGroup create api/permission/authGroup.ts:25 N +permission GET /api/permission/PermissionGroup/PermissionMember/{param} getPermissionMember api/permission/authGroup.ts:33 N +permission POST /api/permission/PermissionGroup/PermissionMember/{param} savePermissionMember api/permission/authGroup.ts:37 N +permission DELETE /api/permission/PermissionGroup/{param} del api/permission/authGroup.ts:17 N +permission GET /api/permission/PermissionGroup/{param} getInfo api/permission/authGroup.ts:13 N +permission PUT /api/permission/PermissionGroup/{param} update api/permission/authGroup.ts:21 N +permission POST /api/permission/PermissionGroup/{param}/Actions/Copy copy api/permission/authGroup.ts:29 N +permission GET /api/permission/Position getPositionList api/permission/position.ts:9 N +permission POST /api/permission/Position create api/permission/position.ts:13 N +permission GET /api/permission/Position/ExportData exportExcel api/permission/position.ts:53 N +permission POST /api/permission/Position/ExportExceptionData exportExceptionData api/permission/position.ts:69 N +permission POST /api/permission/Position/ImportData importData api/permission/position.ts:61 N +permission GET /api/permission/Position/ImportPreview importPreview api/permission/position.ts:65 N +permission POST /api/permission/Position/PositionCondition getPositionByCondition api/permission/position.ts:37 N +permission POST /api/permission/Position/SelectedList getPositionSelectedList api/permission/position.ts:49 N +permission GET /api/permission/Position/Selector getPositionSelector api/permission/position.ts:45 N +permission GET /api/permission/Position/SelectorTree getPositionSelectorTree api/permission/position.ts:41 N +permission GET /api/permission/Position/TemplateDownload templateDownload api/permission/position.ts:57 N +permission DELETE /api/permission/Position/{param} delPosition api/permission/position.ts:25 N +permission GET /api/permission/Position/{param} getInfo api/permission/position.ts:21 N +permission PUT /api/permission/Position/{param} update api/permission/position.ts:17 N +permission POST /api/permission/Position/{param}/Actions/DutyPosition setDutyPosition api/permission/position.ts:29 N +permission POST /api/permission/Position/{param}/Actions/DutyUser setDutyUser api/permission/position.ts:33 N +permission POST /api/permission/Role create api/permission/role.ts:17 N +permission POST /api/permission/Role/RoleCondition getRoleByCondition api/permission/role.ts:33 N +permission GET /api/permission/Role/Selector getRoleSelector api/permission/role.ts:13 N +permission DELETE /api/permission/Role/{param} delRole api/permission/role.ts:29 N +permission GET /api/permission/Role/{param} getInfo api/permission/role.ts:25 N +permission PUT /api/permission/Role/{param} update api/permission/role.ts:21 N +permission GET /api/permission/RoleRelation getRoleRelationList api/permission/roleRelation.ts:9 N +permission POST /api/permission/RoleRelation addRoleRelation api/permission/roleRelation.ts:13 N +permission POST /api/permission/RoleRelation/addRoles addRoles api/permission/roleRelation.ts:21 N +permission POST /api/permission/RoleRelation/delete removeRoleRelation api/permission/roleRelation.ts:17 N +permission POST /api/permission/RoleRelation/deleteRoles removeRoles api/permission/roleRelation.ts:25 N +permission GET /api/permission/RoleRelation/roleList getRoleList api/permission/roleRelation.ts:29 N +permission GET /api/permission/Standing getIdentityList api/permission/identity.ts:9 N +permission POST /api/permission/Standing create api/permission/identity.ts:13 N +permission GET /api/permission/Standing/list getIdentityRelation api/permission/identity.ts:29 N +permission DELETE /api/permission/Standing/{param} delIdentity api/permission/identity.ts:25 N +permission GET /api/permission/Standing/{param} getInfo api/permission/identity.ts:21 N +permission PUT /api/permission/Standing/{param} update api/permission/identity.ts:17 N +permission POST /api/permission/Standing/{param}/Actions/AddObject addIdentityRelation api/permission/identity.ts:33 N +permission POST /api/permission/Standing/{param}/Actions/DeleteObject removeIdentityRelation api/permission/identity.ts:37 N +permission POST /api/permission/UserRelation addUserRelation api/permission/userRelation.ts:13 N +permission POST /api/permission/UserRelation/delete removeUserRelation api/permission/userRelation.ts:17 N +permission GET /api/permission/UserRelation/userList getUserRelation api/permission/userRelation.ts:9 N +permission POST /api/permission/Users createUser api/permission/user.ts:17 N +permission GET /api/permission/Users/Authorize getAuthList api/permission/user.ts:113 N +permission POST /api/permission/Users/BatchDelete batchDelete api/permission/user.ts:33 N +permission POST /api/permission/Users/BatchUpdateState batchUpdateState api/permission/user.ts:41 N +permission POST /api/permission/Users/Current/Actions/ModifyPassword updatePassword api/permission/userSetting.ts:21 N +permission PUT /api/permission/Users/Current/Avatar updateAvatar api/permission/userSetting.ts:9 N +permission GET /api/permission/Users/Current/BaseInfo getUserSettingInfo api/permission/userSetting.ts:13 N +permission PUT /api/permission/Users/Current/BaseInfo updateUserInfo api/permission/userSetting.ts:17 N +permission GET /api/permission/Users/Current/SignImg getSignList api/permission/userSetting.ts:57 N +permission POST /api/permission/Users/Current/SignImg createSign api/permission/userSetting.ts:61 N +permission GET /api/permission/Users/Current/Subordinate/{param} getSubordinate api/permission/userSetting.ts:33 N +permission PUT /api/permission/Users/Current/SystemLanguage updateLanguage api/permission/userSetting.ts:29 N +permission GET /api/permission/Users/Current/SystemLog getLogList api/permission/userSetting.ts:37 N +permission PUT /api/permission/Users/Current/SystemTheme updateTheme api/permission/userSetting.ts:25 N +permission GET /api/permission/Users/Current/getAppSecret getAppSecret api/permission/userSetting.ts:93 N +permission GET /api/permission/Users/Current/getUserOrganizes getUserOrganizes api/permission/userSetting.ts:41 N +permission GET /api/permission/Users/Current/getUserPositions getUserPositions api/permission/userSetting.ts:45 N +permission GET /api/permission/Users/Current/getUserRoles getUserRoles api/permission/userSetting.ts:49 N +permission PUT /api/permission/Users/Current/major setMajor api/permission/userSetting.ts:53 N +permission GET /api/permission/Users/Current/saasList getSaasList api/permission/userSetting.ts:81 N +permission GET /api/permission/Users/Current/saasTenantName/{param} getCompanyName api/permission/userSetting.ts:89 N +permission GET /api/permission/Users/Current/saasinfo getSaasInfo api/permission/userSetting.ts:85 N +permission POST /api/permission/Users/Current/saasjoin joinSaas api/permission/userSetting.ts:73 N +permission PUT /api/permission/Users/Current/saveAppSecret createAppSecret api/permission/userSetting.ts:97 N +permission DELETE /api/permission/Users/Current/{param}/SignImg deleteSign api/permission/userSetting.ts:65 N +permission PUT /api/permission/Users/Current/{param}/SignImg updateDefaultSign api/permission/userSetting.ts:69 N +permission DELETE /api/permission/Users/Current/{param}/saas exitSaas api/permission/userSetting.ts:77 N +permission GET /api/permission/Users/ExportData exportExcel api/permission/user.ts:53 N +permission POST /api/permission/Users/ExportExceptionData exportExceptionData api/permission/user.ts:69 N +permission POST /api/permission/Users/ImportData importData api/permission/user.ts:61 N +permission GET /api/permission/Users/ImportPreview importPreview api/permission/user.ts:65 N +permission GET /api/permission/Users/ReceiveUserList getReceiveUserList api/permission/user.ts:89 N +permission GET /api/permission/Users/Selector getUserSelector api/permission/user.ts:13 N +permission POST /api/permission/Users/SetPositionBatch batchSetUserPosition api/permission/user.ts:105 N +permission GET /api/permission/Users/TemplateDownload templateDownload api/permission/user.ts:57 N +permission GET /api/permission/Users/getAllPermission getAuthGroup api/permission/user.ts:109 N +permission POST /api/permission/Users/getSelectedList getSelectedList api/permission/user.ts:73 N +permission POST /api/permission/Users/getSelectedUserList getSelectedUserList api/permission/user.ts:77 N +permission POST /api/permission/Users/getUserList getUserInfoList api/permission/user.ts:49 N +permission GET /api/permission/Users/getWorkByUser getWorkByUser api/permission/user.ts:81 N +permission POST /api/permission/Users/workHandover workHandover api/permission/user.ts:85 N +permission DELETE /api/permission/Users/{param} delUser api/permission/user.ts:29 N +permission GET /api/permission/Users/{param} getUserInfo api/permission/user.ts:25 N +permission PUT /api/permission/Users/{param} updateUser api/permission/user.ts:21 N +permission POST /api/permission/Users/{param}/Actions/ResetPassword resetUserPassword api/permission/user.ts:37 N +permission PUT /api/permission/Users/{param}/Actions/unlock unlockUser api/permission/user.ts:45 N +permission GET /api/permission/Users/{param}/GetPosition getUserPosition api/permission/user.ts:97 N +permission GET /api/permission/Users/{param}/SelectorByUserPosId getSamePosUser api/permission/user.ts:93 N +permission POST /api/permission/Users/{param}/SetPosition setUserPosition api/permission/user.ts:101 N +permission GET /api/permission/socials getSocialsUserList api/permission/socialsUser.ts:9 N +permission GET /api/permission/socials/render/{param} socialsBind api/permission/socialsUser.ts:17 N +permission DELETE /api/permission/socials/{param} deleteSocials api/permission/socialsUser.ts:21 N +permission DELETE /api/system/OnlineUser batchDelOnlineUser api/permission/onlineUser.ts:13 N +permission GET /api/system/OnlineUser getOnlineUser api/permission/onlineUser.ts:9 N +permission DELETE /api/system/OnlineUser/{param} deleteOnlineUser api/permission/onlineUser.ts:17 N diff --git a/docs/fe/gap-runtime-user.txt b/docs/fe/gap-runtime-user.txt new file mode 100644 index 0000000..9ed007c --- /dev/null +++ b/docs/fe/gap-runtime-user.txt @@ -0,0 +1,28 @@ +METHOD PATH HTTP 判定 说明 +-------------------------------------------------------------------------------------------- +DELETE /api/permission/Group/{param} 404 缺路由 {"code":404,"msg":"接口不存在","data":null} +DELETE /api/permission/Users/{param} 200 通 成功 +DELETE /api/permission/socials/{param} 404 缺路由 {"code":404,"msg":"接口不存在","data":null} +GET /api/permission/Group 404 缺路由 {"code":404,"msg":"接口不存在","data":null} +GET /api/permission/Group/{param} 404 缺路由 {"code":404,"msg":"接口不存在","data":null} +GET /api/permission/Users 200 通 成功 +GET /api/permission/Users/getWorkByUser 200 码400 用户不存在 +GET /api/permission/Users/{param} 200 码400 用户不存在 +GET /api/permission/Users/{param}/GetPosition 200 通 成功 +GET /api/permission/Users/{param}/SelectorByUserPosId 404 缺路由 {"code":404,"msg":"接口不存在","data":null} +GET /api/system/System/getDevUser 404 缺路由 {"code":404,"msg":"接口不存在","data":null} +POST /api/permission/Group - 跳过写 需 --allow-write +POST /api/permission/Group/{param}/Actions/AddUser - 跳过写 需 --allow-write +POST /api/permission/Group/{param}/Actions/DeleteUser - 跳过写 需 --allow-write +POST /api/permission/Users - 跳过写 需 --allow-write +POST /api/permission/Users/BatchDelete 200 通 成功 +POST /api/permission/Users/BatchUpdateState 200 通 成功 +POST /api/permission/Users/SetPositionBatch 405 码405 方法不被允许 +POST /api/permission/Users/workHandover - 跳过写 需 --allow-write +POST /api/permission/Users/{param}/Actions/ResetPassword 200 码400 口令不能为空 +POST /api/permission/Users/{param}/SetPosition 404 缺路由 {"code":404,"msg":"接口不存在","data":null} +PUT /api/permission/Group/{param} 404 缺路由 {"code":404,"msg":"接口不存在","data":null} +PUT /api/permission/Users/{param} 200 码400 用户不存在 +PUT /api/permission/Users/{param}/Actions/unlock 200 通 成功 +-------------------------------------------------------------------------------------------- +码400:4 码405:1 缺路由:8 跳过写:5 通:6 diff --git a/docs/fe/page-user.tsv b/docs/fe/page-user.tsv new file mode 100644 index 0000000..21f484b --- /dev/null +++ b/docs/fe/page-user.tsv @@ -0,0 +1,25 @@ +PAGE METHOD PATH VIA +jnpf-web-apps-main/src/views/permission/user/index.vue DELETE /api/permission/Group/{param} permission/group:delGroup +jnpf-web-apps-main/src/views/permission/user/index.vue DELETE /api/permission/Users/{param} permission/user:delUser +jnpf-web-apps-main/src/views/permission/user/index.vue DELETE /api/permission/socials/{param} permission/socialsUser:deleteSocials +jnpf-web-apps-main/src/views/permission/user/index.vue GET /api/permission/Group permission/group:getGroupList +jnpf-web-apps-main/src/views/permission/user/index.vue GET /api/permission/Group/{param} permission/group:getInfo +jnpf-web-apps-main/src/views/permission/user/index.vue GET /api/permission/Users permission/user:getUserList +jnpf-web-apps-main/src/views/permission/user/index.vue GET /api/permission/Users/getWorkByUser permission/user:getWorkByUser +jnpf-web-apps-main/src/views/permission/user/index.vue GET /api/permission/Users/{param} permission/user:getUserInfo +jnpf-web-apps-main/src/views/permission/user/index.vue GET /api/permission/Users/{param}/GetPosition permission/user:getUserPosition +jnpf-web-apps-main/src/views/permission/user/index.vue GET /api/permission/Users/{param}/SelectorByUserPosId permission/user:getSamePosUser +jnpf-web-apps-main/src/views/permission/user/index.vue GET /api/system/System/getDevUser system/system:getDevUser +jnpf-web-apps-main/src/views/permission/user/index.vue POST /api/permission/Group permission/group:create +jnpf-web-apps-main/src/views/permission/user/index.vue POST /api/permission/Group/{param}/Actions/AddUser permission/group:addGroupUser +jnpf-web-apps-main/src/views/permission/user/index.vue POST /api/permission/Group/{param}/Actions/DeleteUser permission/group:removeGroupUser +jnpf-web-apps-main/src/views/permission/user/index.vue POST /api/permission/Users permission/user:createUser +jnpf-web-apps-main/src/views/permission/user/index.vue POST /api/permission/Users/BatchDelete permission/user:batchDelete +jnpf-web-apps-main/src/views/permission/user/index.vue POST /api/permission/Users/BatchUpdateState permission/user:batchUpdateState +jnpf-web-apps-main/src/views/permission/user/index.vue POST /api/permission/Users/SetPositionBatch permission/user:batchSetUserPosition +jnpf-web-apps-main/src/views/permission/user/index.vue POST /api/permission/Users/workHandover permission/user:workHandover +jnpf-web-apps-main/src/views/permission/user/index.vue POST /api/permission/Users/{param}/Actions/ResetPassword permission/user:resetUserPassword +jnpf-web-apps-main/src/views/permission/user/index.vue POST /api/permission/Users/{param}/SetPosition permission/user:setUserPosition +jnpf-web-apps-main/src/views/permission/user/index.vue PUT /api/permission/Group/{param} permission/group:update +jnpf-web-apps-main/src/views/permission/user/index.vue PUT /api/permission/Users/{param} permission/user:updateUser +jnpf-web-apps-main/src/views/permission/user/index.vue PUT /api/permission/Users/{param}/Actions/unlock permission/user:unlockUser diff --git a/docs/known-limitations.md b/docs/known-limitations.md new file mode 100644 index 0000000..04a41ca --- /dev/null +++ b/docs/known-limitations.md @@ -0,0 +1,105 @@ +# 分支级已知限制清单(ssw-jnpf-lite-rust · 交付态) + +> 本清单是**逐任务评审过程中被明确「接受/挂起」**的条目汇总 —— 不是新发现,是**已裁决**的。 +> 每条都带裁决来源(ledger 的 `Ruling P##` / `Ruling F##` / 任务号)与「代价」。 +> 最终整体评审**不必重新裁决**这些,但可以指出「某条其实该修」。 + +🔴 **本文件是 SDD 工作区(`.superpowers/sdd//`)里那份清单的**受版本控制的正本**—— +工作区是 git-ignored 的过程草稿,会在交付时清掉;本文件才是跟着仓库走的。 + +--- + +## A. 后端实现层 + +| # | 限制 | 出处 | 为什么接受 / 代价 | +|---|---|---|---| +| (a) | `restore_base_module` 用**子串匹配**恢复模块 ⇒ 会误伤 `base_module_ext`、会丢二级索引 | Task 6 遗留 | 契约未要求二级索引;代价:菜单恢复不是精确恢复 | +| (b) | `Db` **没有跨调用持锁的公开接口** ⇒ 业务上的多步写**不是**单一事务 | P59 / P71 | 契约 §6 只要求「单次调用原子」;代价:跨表多写可能部分失败(具体实例见 **(z)**) | +| (c) | Task 7 的「DB 报错」测试会**重复插入** admin 的 `base_role_relation` 行 | Task 7 | 测试夹具问题;不影响生产路径 | +| (d) | `sys.rs` **1290 行单文件** | P68 | 5 组 `base_*` 显式 handler 的必然体量;代价:可读性/可拆分度 | +| (e) | `user_role_map` **整表加载**到内存 | P69 | 数据量小;代价:多用户场景内存随行数线性增长。**M-12 补充的具体例子**(最终整体评审修复轮 R=3):每次列用户都会把**整张** `base_role_relation`(全量用户↔角色关系)+ **整张** `base_role` 拉进内存 ⇒ 用户/角色规模上去后,单次请求的内存占用随行数线性增长 | +| (f) | `or_zero` 对**非字符串**值的处理未逐类型覆盖 | P67 | 契约只对 string 有要求。**M-11 补充的具体例子**(最终整体评审修复轮 R=3):`or_zero` 把「数字 / 布尔 / 对象 / 数组」一律当 `"0"` ⇒ 例如 body 传 `"organizeId": 123`(**数字**而非字符串)会落库成 `"0"` 而不是 `"123"` | +| (g) | `write_cast` 用**硬编码 cast 表**,未直接用 `col.numeric` | P73 | 两条路径已由测试钉住一致;代价:schema 变更时需同步两处 | +| (h) | **6 条既有 clippy 告警**:`sys.rs`×3 / `permission.rs`×2 / `tests/seed_it.rs`×1 | P75 | 全部先于本分支存在;**零新增**;代价:CI 需容忍这 6 条 | +| (i) | `insert_new` 与 `update_existing` 各自构造 `$n::text{cast}` 占位符,**逻辑重复** | Task 8 Minor 2 | 合并属「顺手重构」;代价:一处改了另一处可能漏 | + +## B. 装配与路由层 + +| # | 限制 | 出处 | 为什么接受 / 代价 | +|---|---|---|---| +| (j) | **后端不托管前端静态产物**(无 static 文件服务) | P79 | 契约 §6.8/§10 把静态托管写成**可选**;前端由 vite dev server(`:5173`) 托管、`/api` 代理到 `:30010`;**四条验收门没有一条**要求后端托管前端。**红线「DDL 绝不可从 HTTP 下载」由「后端根本不读文件系统响应请求」天然满足**,并另有守卫测试(`GET /db/schema.sql` ⇒ 404 + 信封)。代价:后端**不能**单独跑全栈 | +| (k) | release 二进制**没有 catch-all 的自动化覆盖** | Task 10 Minor 4 | panic 端点是 `#[cfg(test)]` 专属(守住「非测试代码零 `panic!()`」红线);catch-all 中间件代码在测试构建与 release 构建**逐字相同**,且 release profile **无** `panic = "abort"` ⇒ 行为等价 | +| (l) | ~~`Path` 遇**畸形百分号编码** ⇒ axum 默认返**非信封的 400 响应**~~(该断言**已被推翻**,见右栏) | Task 10 Minor 7 | 🔴 **已推翻**(最终整体评审修复轮 R=3,控制器逐条独立复现):axum 0.8.9 **接受**该转义 —— 实测 `PUT /api/permission/Authority/Data/%zz` 返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**(信封,正常)⇒ **不存在**「返非信封 400」这种破口。原裁决的前提(axum 会吐非信封的 400)**不成立** ⇒ **不改代码** | +| (m) | 标识符白名单自检是**兜底 tripwire、不是完备证明** | P77 | 自检只查 spec 的表/列 + 10 张表字面量清单;**明确不查** `sys.rs` 的 4 组投影列常量(源码字面量常量,写错编译期就炸)。代价:编译期 SQL 拼写错误不在自检覆盖面内 | + +## C. 冒烟脚本层(`scripts/perm-smoke.sh`) + +| # | 限制 | 出处 | 为什么接受 / 代价 | +|---|---|---|---| +| (n) | 每次跑**留一行** `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user` | Task 11 fix R=1 | react 版同款行为;契约 §13 **未要求**清理 ⇒ 不改。代价:重复跑会让这两张表**无界增长**(第 30 条断言的计数因此递增)。🔴 **仅在复用外部后端时**:尺子**默认自起隔离实例**(临时数据目录)⇒ 跑完即删、不留脏数据 | +| (o) | 「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file` | Task 11 fix R=1 | 纯观感;断言 7/8/9 仍正确判失败 | +| (p) | 「空 body 前置失败」时 jq/python 两条路径的**前置提示文案不同**(`code=无` vs `code=ERR`) | Task 11 fix R=1 | 退出码**都是 2**;纯文案不一致 | + +## D. 前端层 + +| # | 限制 | 出处 | 为什么接受 / 代价 | +|---|---|---|---| +| (q) | `src/api/request.ts:5` 的注释仍写「转发到 **30000**」 | Task 12 brief S13① | **刻意留下**:「逐字复制、只改代理目标」是硬约束 ⇒ `diff -r` 的判据是「全部差异只出现在 `vite.config.ts`」。改它会让 diff 门失败。代价:一行**陈旧但无害**的注释 | +| (r) | 前端 `api/*.ts` 的导出名是**自然英语复数**(`listBooks` / `listProducts`) | Task 12 brief S13② | 逐字复制的必然结果;`scripts/check-module.sh` 照抄 react 的 `plural()` 逻辑适配 | +| (ac) | Dashboard 的「功能菜单」**只渲染二级节点**(`node.children.map`)⇒ 顶层菜单(`Demo 示例` / `产品管理` / `图书超市`,种子 `parent_id='0'`)**只出标题、没有按钮**,这三个业务页只能按 URL 直达 | 逐字复制 react 版 `src/frontend/src/views/Dashboard.tsx:46-56` | **刻意留下**:前端是 react 技能的逐字复制(唯一允许的改动 = vite 代理端口)⇒ 改 Dashboard 会让「前端差异只出现在 `vite.config.ts`」的核对门失败。契约 §8.4 只规定菜单树结构、**没规定 Dashboard 按钮粒度** ⇒ 契约未覆盖。代价:三个业务页在 UI 上无侧栏入口(需记 URL / 收藏);门④ 的浏览器自验同样按 URL 直达验的 | + +## E. 已明确「不改」的契约级偏差(**已由测试钉住**) + +| # | 事项 | 出处 | 说明 | +|---|---|---|---| +| (s) | `crud.rs` 的 UPDATE 占位符改成 `$n::text{cast}` | P78(Task 8 R=1) | 改前:写 timestamp/numeric/int **100% 失败**(`code=400`);改后:参数恒为 text、转换在服务端做。**契约可观测行为方向是「违约 → 守约」**;返回值形状/错误文案/列集/路径分流/handler 签名全未变 | +| (t) | 契约 §9 写 `build_router(state) -> Router`,而 `Router<()>` 与「main 再调 `with_state`」**类型上不能同时字面成立** | P76 | 裁决:`build_router(state: AppState) -> Router`(内部 `.with_state(state)` 是**类型层面 no-op**,只为让契约的 `state` 参数有去处),**链尾唯一一次** `with_state(state)` 把类型落成 `Router<()>` | + +## F. 运行脚本层(`run.sh`) + +| # | 限制 | 出处 | 为什么接受 / 代价 | +|---|---|---|---| +| (u) | ~~`pkill -f "vite"` 是死代码~~ | 控制器 2026-10-26 | 🔴 **已推翻**(控制器早先据一次失效探针得出的「macOS `pkill -f` 只匹配 argv[0]」是**错的**):重做实测证明 `pkill -f` 匹配**完整命令行** ⇒ `pkill -f "vite"` **打得中**,但**匹配面过宽**(别的项目的 vite 也中)。⇒ 该条已**从限制清单移出**,改为 Task 12 修复轮 R=1 的**必改项**(收窄模式 / 删掉 vite pkill,交给 `kill_ports`) | +| (v) | `run.sh dev` **就绪失败**时只收**前端**(按 PID 文件),**不收后端** | Task 12 修复轮 R=2 | 已实测的失败场景(后端打不开数据库目录)里**后端自己会退出**(pglite 报错 ⇒ 进程 exit 1)⇒ 只需要收前端。**残留场景**:后端进程活着但 `/api/health` 一直不通(HTTP 层坏了)⇒ 后端会留在后台占着 30010。**为何不改**:① 该场景要求 HTTP 层已经坏了(`kill_ports` 在启动前已清过端口 ⇒ 端口被占不会触发它);② **自愈** —— 下一次 `dev` / `stop` 的 `kill_ports 30010` 会把它收掉;③ 贸然收后端会有「后端只是慢、其实好的」被误杀的副作用。**代价**:极端场景下 `dev` 失败后机器上留一个后端进程 | +| (w) | `run.sh stop` / `run.sh logs` 仍无条件 `mkdir -p "$LOGS" "$RUN"` ⇒ `logs`(**只读** tail)也会造出空的 `.run/` + `.logs/` | Task 12 修复轮 R=2(scoped re-review 新增 Minor) | R=1 必改 5b 的 brief **点名**了 `dev`/`stop`/`logs` 三个分支 ⇒ 实现者照办。**代价**:纯观感(两个空目录,`.gitignore` 已覆盖);`--help` 与无参**不造**目录(原缺陷已消除) | + +## G. 最终整体评审新增(修复轮 R=3,2026-10-26) + +| # | 限制 | 出处 | 为什么接受 / 代价 | +|---|---|---|---| +| (x) | **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**);登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量(`docs/contract.md:448`)、**不会被强制执行** | M-6(最终整体评审) | `expiresIn: 7200` 继承自 JNPF/Sa-Token 的语义;**契约逐字定死**该字面量 ⇒ 改代码即破契约 ⇒ 只如实写清文档。代价:进程不重启时 token 永不过期(与内存 token 表「进程重启即失效」是同一条事实的另一面) | +| (y) | **口令比对不是常量时间**(`auth.rs` 里 `stored.to_lowercase() != plain_md5.to_lowercase()`) | M-7(最终整体评审) | **为何接受**:HTTP 上对 md5-hex 比对的计时攻击收益可忽略;且改动落在**最敏感的登录路径**、收益 < 风险 ⇒ 挂起。代价:留下一个理论上的计时侧信道(**实际不可利用**) | +| (z) | `sys.rs` 的 `user_save` 的「插用户行」与「写角色关系」是**两条独立语句** ⇒ 步骤 2 失败时**用户行已提交、角色关系没写** ⇒ 响应 `code=400` 而库里已有该用户 | M-10(最终整体评审);是 (b)(P59 / P71 裁决)的**具体实例** | 契约**未**要求跨调用原子性(`docs/contract.md` 全文无「原子 / 事务 / atomic」字样)⇒ 不改。代价:极端场景下前端提示「保存失败」但用户其实已建好 | +| (aa) | **停机后第二个 SIGTERM / SIGINT 不再强制终止进程**(首个信号后 tokio 的信号 handler 仍在位) | R=3 scoped re-review Minor 4 | 首个信号后进入优雅停机,收尾**有界**(`postmaster.pid` 轮询上限 3 秒)⇒ 不会挂死。**为何不改**:加「二次信号 ⇒ force-exit」要动刚写好的信号路径,收益仅是省 ≤3 秒等待,风险 > 收益。代价:急停需另发 `SIGKILL` | +| (ab) | 停机路径用 `std::process::exit(0)` 收尾 ⇒ `run()` 的 `Ok` 路径不可达;且 `axum::serve` 以 `Err` 结束时 `?` **提前返回** ⇒ PG **不走**优雅关闭(仍被 SIGKILL 掉) | R=3 scoped re-review Minor 6 | **刻意设计**:pglite 的收尾线程可能卡死 ⇒ 不能让它吊住整个进程。`serve` 异常退出与改动前行为一致(**非回归**)。代价:`serve` 异常退出时 PG 仍要走 crash recovery | + +## 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)。 + +| # | 限制 | 出处 | 为什么接受 / 代价 | +|---|---|---|---| +| (ac) | ~~**面 B 只有规格、没有实现**~~ —— ✅ **2026-10-26 已落地**(S1–S6 一次性做完):`src/backend/src/platform/jnpf.rs` + `routes.rs` 5 条新路由 + `seed.rs` 的 `f_en_code` + `permission.rs` 的第二套判据 | 面 B 规格 §7 | **规格先行**的收益兑现:官方形状的 18 条断言**全部落地** ⇒ `scripts/perm-smoke-jnpf.sh` 从 **`覆盖 5/18`** 走到 **`PASS=18 FAIL=0 SKIP=0`(18/18)**;面 A `perm-smoke.sh` 仍 **`PASS=32 FAIL=0`**(面 A 的 27 条路由**一字未动**) | +| (ad) | **口令存储缺官方 `secretkey` 一步** —— 本仓 `base_user.f_password` 存 `md5(明文)` 的小写 hex;官方存 `md5(lower(md5(明文)) + lower(secretkey))` | `JNPF_SOURCE_AUDIT.md` §2.6 · `MIGRATION.md` §7 | **迁官方时可一次性换算,且不需要明文**(`secretkey` 是每行自带的 ⇒ 库里算得出)。**为何本仓不改**:官方 `secretkey` 的**生成规则**未在本仓建模(每用户一个随机 secret),改了会让本仓与 react 版**不再同形**、破坏"两版可开同一个库"的前提。代价:**现在不能直接把本仓的库丢给官方后端登录**(须先跑一次换算) | +| (ae) | **面 A 的权限判据仍是菜单路径** —— 面 A 守卫 = `spec.module_key == base_module.f_url_address`;**面 B** 另有一套 = `base_module.f_en_code`(`@SaCheckPermission("permission.user")`) | `JNPF_SOURCE_AUDIT.md` D6 · `PERMISSION.md` §二 · 面 B 规格 §3 | ✅ **两套判据已并存**(`has_module` 给面 A / `has_en_code_permission` 给面 B),**互不影响**、各自短路与放行规则同构。**代价**:面 B 的 `f_en_code` 判据**依赖菜单行存在** ⇒ 未映射 ⇒ 放行(与面 A 同一条红线)⇒ 官方点权限**不映射就没有**;且本仓**只做菜单级**(`item_type='module'`),按钮级不做(见 (ag)) | +| (af) | ~~**官方码表有 4 个本仓没有的 code**~~ —— ✅ **2026-10-26 已补齐**(`envelope.rs` 的 `code::*`:含 `401`/`500`/`601`/**`602`**) | `JNPF_SOURCE_AUDIT.md` §4 · 面 B 规格 §4 | 面 A 的码**一个都没改**(`600` 未登录 / `403` 无权限 / `400` 业务失败),**面 B 走 `602`** ⇒ 官方前端 `request.ts:78-80` 只在 `601`/`602` 清 token ⇒ 不会卡住不跳登录 | +| (ag) | **按钮 / 列 / 表单 / 数据级权限不做** —— `permissionList` 的 `button`/`column`/`resource`/`form` **恒空数组** | 面 B 规格 §8 B4 | 官方 DDL 里 `base_module_button` / `_column` / `_form` / `_data` 都有,但 v1 范围只做 `item_type='module'`。**代价**:官方前端**动态模型页的按钮恒显**(不隐藏);官方前端对 `permissionList` 缺项是**容错**的(`list && list.button ? list.button : []`)⇒ 不报错 | +| (ah) | **三个业务菜单的 `f_en_code` 是本仓自定占位** —— `permission.demo` / `permission.shop.product` / `permission.books.book` | 面 B 规格 §8 B8 | 官方没有 demo/shop/books 三个模块。**代价**:迁官方时要改成官方编码;当前占位**不与官方 `permission.*` 冲突**(官方只用到 `permission.user`/`role`/`organize`/`menu` 等) | +| (ai) | **`AuthorizeDataReturnVO.list`(权限树模型)返空数组** —— 只保证 `ids`/`all` 语义正确 | 面 B 规格 §8 B1 | 官方那套树模型(`modelId` + `button`/`column`/`resource`/`form` 子树)本仓不做。**代价**:官方授权弹窗需二次适配(`ids` 可直接用) | +| (aj) | **组织 `AsyncList/{id}` 不分页** —— 按父 id 逐层取,`pageSize` = 本层条数 | 面 B 规格 §8 B10 | 官方前端就是靠这个接口**逐层展开**机构树。**代价**:机构极多时无分页保护(本仓机构表本身很小) | + +### H.1 🔴 一条**判别规则**(不是限制,是红线) + +面 A(本仓 ssw/react 形状)与面 B(官方 JNPF 形状)**共用同一套 `base_*` 表与 cipher**,靠**请求头**分流: + +| 请求头 | 判定 | +|---|---| +| 含 **`Vue-Version: 3`** | ⇒ **面 B**(官方形状) | +| 不含 | ⇒ **面 A**(ssw 形状) | + +🔴 **判别头只能是 `Vue-Version`**:官方前端发 `App-Code` / `Jnpf-Origin: pc` / `Vue-Version: 3` 三个头, +而本仓前端 `src/frontend/src/api/request.ts` **也发**前两个(与官方同款)⇒ **只有 `Vue-Version` 是本仓前端唯一不发的**。 +🔴 **本仓前端禁止发 `Vue-Version`**(发了 ⇒ 面 A 请求被误判成面 B ⇒ 契约整体错位)。 +🔴 `scripts/check-module.sh` 的「全局红线」段**静态钉住两侧**:前端**禁发**该头 + 面 B 尺子**必带**该头。 diff --git a/docs/runbook.md b/docs/runbook.md new file mode 100644 index 0000000..e8bec99 --- /dev/null +++ b/docs/runbook.md @@ -0,0 +1,420 @@ +# runbook —— ssw-jnpf-lite-rust 怎么起、怎么冒烟、坏了怎么办 + +> 契约见 [`contract.md`](contract.md);红线与坑位清单见 [`../CLAUDE.md`](../CLAUDE.md)。 + +--- + +## 0. 前置 + +| 工具 | 版本(本机实测) | 用途 | +|---|---|---| +| Rust | ≥ 1.85(edition 2021;本机实测 rustc 1.95.0) | 后端 | +| Node / npm | node v26.8.1 · npm 11.19.0 | 前端(vite 5) | +| jq | 1.7.1(`/usr/bin/jq`) | 冒烟脚本的 JSON 取值(无则 python3 兜底) | +| python3 | 3.14.5 | 冒烟脚本的 JSON 取值兜底 | + +🔴 **后端与 `scripts/perm-smoke.sh` 零 node 依赖** —— 冒烟脚本用后端自己的 `--enc` 子命令自证 cipher。 +前端用 npm/vite 是它本来的工具链,允许。 + +--- + +## 1. 第一次上手 + +```bash +cd ~/Desktop/workspace/ssw-platform + +bash run.sh install # cargo fetch + npm --prefix src/frontend install +bash run.sh build # cargo build --release + vite build(产出 src/frontend/dist) +``` + +`install` 用的是 `npm install`(**可能更新 `package-lock.json`**)。想严格按 lock 装、不碰 lock,用: + +```bash +npm --prefix src/frontend ci +``` + +> ⚠️ 本机 npm 11 会打印 `install-scripts 2 packages have install scripts not yet covered by allowScripts` +> (`esbuild` / `fsevents`)。**不影响构建** —— vite 用的二进制来自平台包 `@esbuild/darwin-*`。 +> 万一 vite 报「esbuild binary not found」,再执行: +> `npm --prefix src/frontend install-scripts approve esbuild && npm --prefix src/frontend install`。 + +--- + +## 2. 日常启动 + +```bash +bash run.sh dev # 后台起后端(30010) + 前端(5173) +bash run.sh logs # 看 .logs/backend.log + .logs/frontend.log 尾部 +bash run.sh stop # 停(幂等:无进程时也不报错,退出码 0) +``` + +- 前端:**http://127.0.0.1:5173** +- 后端:**http://127.0.0.1:30010** +- 账号:**`admin` / `123456`**(首次启动自动种;密码用浏览器侧 `utils/cipher.ts` 加密后提交) + —— 登录后的 **token 寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**); + 响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**。 +- PID 在 `.run/{backend,frontend}.pid`,日志在 `.logs/{backend,frontend}.log`(两者都在 `.gitignore` 里) + +单起一半: + +```bash +bash run.sh backend # 前台跑后端(Ctrl-C 停) +bash run.sh frontend # 前台跑 vite +``` + +`run.sh` 退出码:**0** 成功 / **1** 运行期失败 / **2** 用法错(无参、未知子命令)。 +`bash run.sh --help` 打印用法并退出 **0**(且**不会**创建 `.run/` `.logs/` 目录 —— 目录只在真正要写日志/PID 的分支里建)。 + +🔴 **端口是本仓硬约定**:后端固定 **30010**、前端固定 **5173**。 +守卫**只对 `dev` / `backend` 生效**(这两个子命令真的会起后端,后端会继承 `PORT` 并真的绑那个端口): +`PORT` 被设成别的值 ⇒ `run.sh dev` / `run.sh backend` **明确报错并退出 2** +(不会去清别的端口、也不会打印错的 URL)。 +其它子命令(`--help` / 无参 / `logs` / `install` / `build` / `stop` / `frontend`)**不碰端口** +⇒ **完全不受 `PORT` 影响**(环境里恰好有个 `PORT` 不会让它们失败)。 +要用别的端口请直接跑二进制:`PORT=xxxx ./target/release/ssw-jnpf-lite-rust`。 +🔴 **后端默认只监听 `127.0.0.1`**(`BIND_ADDR` 可覆盖)—— 本仓的种子口令是 `admin/123456`、 +token 永不过期 ⇒ 默认不监听所有网卡;要在容器 / 反代里对外暴露才设 `BIND_ADDR=0.0.0.0`。 + +🔴 **`run.sh` 的 `kill_ports` 是 `kill -9`** ⇒ 它只会清 **30010** 和 **5173** 两个端口。 +**兄弟项目 `tdc-rs` 的端口不在列表里**(打死它就是破坏兄弟项目)。 + +🔴 **`dev` 会等后端与前端都真的就绪**(后端轮询 `/api/health`,最长 30 秒;前端轮询 vite 根路径,最长 60 秒) +⇒ 任一没真正起来(数据库路径写错 / 依赖没装 / 端口被占 / `npm run dev` 立刻报错退出)时, +**脚本退出码 1** 并打印对应日志尾部(后端失败 ⇒ `.logs/backend.log`;前端失败 ⇒ `.logs/frontend.log`), +**不会**「报成功但其实没有服务」。 +此时**本次刚起的前端进程会被一并收掉**(**PID 文件 SIGTERM → SIGKILL** + **按端口 `kill -9` 兜底**)⇒ +**不会在 5173 上留残进程**(`stop_pid` 依赖 npm 把 SIGTERM 转发给 vite —— 那是 npm 的内部实现细节、 +不是保证 ⇒ 必须有 `kill_ports` 兜底)。 +🔴 前端没就绪时**不收后端**(后端可能只是慢;下一次 `dev` / `stop` 的 `kill_ports 30010` 会自愈), +脚本会明确提示「后端仍在 30010 上运行,要停请执行 `./run.sh stop`」。 + +🔴 **`stop` 的实际停止路径 = PID 文件(SIGTERM → 1s → SIGKILL)+ `kill_ports`(按端口 `kill -9`)**; +`pkill` 只是最后兜底,且模式收窄到**后端本体的完整路径** +(macOS/BSD 的 `pkill -f` 匹配**完整命令行**,宽模式会连「命令行里提到本仓名字」的无关进程一起杀掉)。 +vite 由 `kill_ports 5173` 按**端口**收 ⇒ 不会误杀别的项目的 vite dev server。 +🔴 **后端收到 SIGTERM / SIGINT 会优雅关闭**嵌入式 PostgreSQL(先收完在途请求,再正常关库) +⇒ 不再被 SIGKILL 打断(以前每次停机都是 SIGKILL 掉嵌入式 PG ⇒ 下次启动要 crash recovery、 +数据目录里还留 `postmaster.pid`);`./run.sh stop` 的 1 秒宽限期对优雅停机足够(实测 < 200ms)。 +> ℹ️ 停机瞬间 `.logs/backend.log` 里可能出现**几十行** +> `FATAL: terminating connection because protocol synchronization was lost` —— +> 那是 **pglite-rs 0.2.7 的收尾噪音**(PG 收到 Terminate 后 postmaster 反复拉起后端), +> **无害**:PG 本身是干净关库的(`postmaster.pid` 会被清掉)。 +> 后端会在 PG 干净关库后**立刻**退出(日志尾行 `ssw-jnpf-lite-rust 已停止(嵌入式 PostgreSQL 已优雅关闭)。`)。 + +🔴 **`backend` 子命令用 `exec`** ⇒ **后端自己的退出码原样透传**(后端 panic 时是 **101**,不是 1)。 + +--- + +## 3. 环境变量(`.env`) + +`run.sh` 会把仓库根的 `.env` 导出给子进程(`set -a; . .env; set +a`)。样例见 `.env.example`。 + +| 变量 | 默认 | 说明 | +|---|---|---| +| `PORT` | `30010` | 后端监听端口(**非法值回落 30010**) | +| `BIND_ADDR` | `127.0.0.1` | 后端监听地址 —— 🔴 **默认只监听本机**;要在容器 / 反代里对外暴露才设 `0.0.0.0`(只接受**字面 IP**,主机名会被判非法 ⇒ 回落 127.0.0.1) | +| `PGLITE_DIR` | `<项目根>/src/backend/data/lite.pg` | 数据目录(**绝对路径**,与 cwd 无关) | +| `SSW_PROFILE` | `dev` | 部署档位 —— `dev` = 一律不判弱口令;`prod` = 六条弱口令判据生效,违规**拒绝启动** | +| `SEED_ADMIN_PASSWORD` | `123456` | 首启 admin 的**种子口令**(明文)—— **只在空库首启时生效** | + +🔴 **`PGLITE_DIR` 只能写绝对路径**。`config.rs` 对它是**原样使用** ⇒ 相对路径会相对**当前工作目录**解析 +⇒ 换个 cwd 就换一份库,而且**静默**。要临时库就写 `PGLITE_DIR=memory://` +(pglite-rs 0.2.7 没有真内存模式,走的是系统临时目录里的一次性数据目录,进程退出即销毁)。 + +--- + +## 4. 冒烟与自检 + +### 4.1 权限闭环冒烟(32 条断言) + +```bash +bash scripts/perm-smoke.sh # 期望:PASS=32 FAIL=0,退出码 0(**后端不用先起**,见 4.1.1) +B=http://127.0.0.1:30010 bash scripts/perm-smoke.sh # 打别的地址(**显式指定 ⇒ 不自起**) +JQ_BIN="" bash scripts/perm-smoke.sh # 强制走 python3 兜底路径(两条路径判据一致) +``` + +退出码:**0** 全绿 / **1** 有断言失败 / **2** 前置错误(后端不可达、缺 jq+python3、缺 `--enc` 二进制)。 + +断言覆盖:未登录 `600` → 加密登录 → 菜单树分组 → 建用户 → 重复账号 `400`(不是 500)→ +一维/二维授权写入 → 非管理员菜单收窄 → `403` → 未知路由 `404` → 管理员短路 → +Product/Book 往返(36 位 UUID、numeric 是 JSON 字符串 `"9.90"`、int 是 JSON 数字 `100`)。 + +### 4.1.1 尺子自起隔离后端(**默认行为**) + +两把契约尺子(`perm-smoke.sh` / `perm-smoke-jnpf.sh`)**默认自己把后端起起来**(助手在 +`scripts/smoke_backend.sh`,被两把尺子 `source`)。口径: + +| 情况 | 行为 | +|---|---| +| **没给 `B`** + `:30010` **通** | 就用它(保留「跑开发中的后端」这个习惯) | +| **没给 `B`** + `:30010` **不通** | **自起隔离实例**:空闲端口 + `mktemp -d` 临时数据目录 ⇒ 打印「ℹ️ 已自起隔离后端:…」 | +| **显式给了 `B`** + 不可达 | **不自起**(尊重外部后端)⇒ 前置错误,**退出码 2** | + +为什么:不自起的话 ① 两把尺子**互相踩**(面 A 改了库里的角色/菜单 ⇒ 面 B 的前置状态被污染); +② 跑完**留脏数据**在 `src/backend/data/lite.pg`;③ **CI 里没法跑**(没人替你起后端)。 +⇒ 自起时库里的痕迹**随临时目录一起消失** ⇒ 断言可重复、两把尺子互不污染。 + +🔴 隔离实例的 `PGLITE_DIR` 是**临时目录下的绝对路径**(契约:只接受绝对路径或 `memory://`), +进程退出即销毁;退出时尺子先 `TERM` 后端(等 6s 再兜底 `KILL`)再删临时目录。 + +### 4.2 面 B 冒烟(官方 JNPF 形状,18 条断言) + +```bash +bash scripts/perm-smoke-jnpf.sh # 期望:PASS=18 FAIL=0 SKIP=0,退出码 0(**后端不用先起**,见 4.1.1) +B=http://127.0.0.1:30010 bash scripts/perm-smoke-jnpf.sh # 显式指定 ⇒ 不自起 +``` + +退出码:**0** 全绿 / **1** 有断言失败或未全覆盖 / **2** 前置错误(后端不可达等)。 + +🔴 **它打的是面 B**(官方 JNPF 形状)⇒ 请求必须带判别头 **`Vue-Version: 3`**(脚本自带)。 +断言覆盖:面 A 未受影响 · 两面登录 · 面 B `CurrentUser` 5 字段 · `menuList` 节点 15 字段 · +`permissionList` 是数组 · 未登录 `602` · 未知路由仍 `404` · 用户/角色列表是 `PageListVO` · +列表项无 `password`/`secretkey` 且 `isAdministrator` 是**数字** · `ModuleBySystem` 返 `ListVO` · +授权写(官方完整 body)真落库 · 授权读是 **POST**。 + +### 4.3 业务模块 10 接触点静态自检 + +```bash +bash scripts/check-module.sh # 无参 ⇒ 检查契约登记的全部业务模块(期望 PASS=93) +bash scripts/check-module.sh books Book # 只查一个 +``` + +**纯静态**:不启动后端、不发请求、不依赖 node。 +每个 `appCode/Entity` 查 10 个接触点(后端路由注册 · spec 定义 · 实体表 · 守卫 `module_key` · +前端 api 文件 · 前端页面 · 前端路由 · **菜单声明**(`*_MENU: MenuSpec`,与契约 `[MENU]` 逐字对齐)· +**菜单登记**(`modules/mod.rs` 的 `ALL_MENUS`)· **三处一字不差**), +外加两条契约红线(`f_` 前缀 + `f_id VARCHAR(50)` 主键 · 软删契约)。 + +🔴 **期望值不在脚本里** —— 全部从 `docs/contract.md` **附录 A**(机器可读)读 +(`scripts/contract_expect.py` 解析):菜单表 / 业务模块清单 / 各尺子的断言条数。 +⇒ 改契约只改一处;代码漂移立刻报。 + +🔴 **尺子自证**:脚本结尾会比对「本尺子实际跑了多少条断言」与「契约登记的条数」, +对不上 ⇒ **失败**(防止有人删掉断言把尺子改弱)。 + +退出码:**0** 全过 / **1** 有 ❌ / **2** 用法错(未知参数、app_code/Entity 不在契约清单)。 + +> 🔴 demo 模块**没有** `api/demoitem.ts`(`views/DemoItem.tsx` 直接 `request.get('/ssw/demo/DemoItem/List')`) +> ⇒ 这一条走「view 直连」分支;两种都查不到才算 ❌。 + +### 4.4 分层红线静态自检(平台层 / 业务层不许互相渗透) + +```bash +bash scripts/check-boundary.sh # 期望:PASS=11 FAIL=0,退出码 0 +``` + +**纯静态**(只需要 `python3`,macOS 自带)。把 `CLAUDE.md` 红线 12 +(「加一个业务模块只碰业务层」)变成可执行的尺子: + +| 判据 | 内容 | +|---|---| +| **CP1'** | 扫描器**反自证** —— 造一个明知存在的泄漏,必须被抓到(永远返回「干净」的尺子 = 没有尺子) | +| **CP1** | 平台层**零业务标识符**(业务表名 / 实体名 / 路由前缀 / 菜单 id / url / en_code)—— 只扫**字符串字面量**(注释里的举例允许);禁止清单**从业务层自己派生** ⇒ 加模块时这把尺子自动变严 | +| **CP2** | 平台层**不反向依赖**业务层(`platform/**` 不许 `use crate::modules`) | +| **CP3** | 业务层**不直接调**平台层的种子(接线只在装配根 `bootstrap.rs`) | +| **CP4** | 每个业务模块必须声明 `*_MENU: MenuSpec` ⇒ 且被 `modules/mod.rs` 的 `ALL_MENUS` 收编 ⇒ 且声明的菜单 id 与**契约** `[MODULE]` 一致 | +| **CP5** | `platform::seed::ensure_base` 的调用点**只有** `bootstrap.rs`(应用与测试走同一条路 ⇒ 测到的库 == 上线的库) | +| **CP6** | 平台层自带菜单的**条数**(= 契约菜单数 − 业务模块数)与**id 列表**都与契约逐条一致(业务菜单不许混进 `platform/seed.rs`) | + +退出码:**0** 全过 / **1** 有 ❌ / **2** 用法错(缺 `python3`)。 + +🔴 **期望值不在脚本里** —— 菜单数、业务模块数都从 `docs/contract.md` **附录 A** 读 +⇒ 加一个业务模块只需在契约里加两行,本脚本的期望值自动跟着变。 +🔴 **尺子自证**:结尾比对「实际跑了多少条断言」与「契约登记的条数」,对不上 ⇒ 失败。 + +### 4.5 契约端点表 ↔ 代码真实路由 对账(静态闸门 3) + +```bash +bash scripts/check-contract.sh # 期望:PASS=10 FAIL=0,退出码 0 +``` + +**纯静态**(只需要 `python3`)。把 `docs/contract.md` **附录 A 的 `[ENDPOINT]`** +(机器可读的端点表:face / method / path / guard / owner,一行一条,共 32 行) +与**代码里真实注册的路由**逐条对账 —— **双向**: + +| 判据 | 内容 | +|---|---| +| **CC2** | 端点**总数**一致(契约 N 条 == 代码 N 条) | +| **CC3** | 契约 → 代码:每条端点在代码里存在且**方法**一致 | +| **CC4** | 代码 → 契约:代码里没有契约未登记的端点 | +| **CC5** | **归属层**一致(`platform` / 业务模块代号 `demo|shop|books`) | +| **CC6** | **守卫**一致(面A 菜单 key / 面B 点权限编码 / 登录 / 无)—— **静态推导** | +| **CC7** | 钉子测试的字面量清单(`REGISTERED` / `JNPF_REGISTERED`)与平台层路由**双向覆盖** | +| **CC8** | 业务路由**三处**一致(各模块 `ROUTES` 常量 / `router()` 注册 / `ALL_ROUTES`) | +| **CC9** | 契约面计数**自洽**(`[FACE]` 登记的条数 == `[ENDPOINT]` 里各 face 的实际条数) | +| **CC10** | **官方端点台账**(`[OFFICIAL]`)↔ 代码真实路由**双向**:说 `implemented/partial` 的必须真的注册了,说 `absent/oos` 的必须**没有**注册;反向:**面 B / 共用**的每条路由都必须在台账上有账 | +| **CC1'** | **反自证** —— 注入 9 种已知漂移,必须**每一种**都被抓到 | + +退出码:**0** 全过 / **1** 有 ❌ / **2** 用法错或前置错误(契约读不出来)。 + +#### 官方端点覆盖 N/M(CC10 的副产物) + +尺子会打印一行进度(**不计入** PASS/FAIL): + +``` +📊 CC10-COVER:官方端点覆盖 8/47(implemented 3 / partial 5 / absent 39;oos 6 单列,不进分母) +``` + +N = `implemented` + `partial`(**已落地**的官方端点数); +M = 再加 `absent`(**在范围内**的官方端点总数,官方 JNPF 后台最小可用面这一条线); +`oos`(v1 明确不做:导入导出族、数据权限链接)**单列**,不进分母。 +状态词表见 `docs/contract.md` 附录 A `[OFFICIAL]` 的表头注释; +`partial` 的**具体偏差**逐条记在 `JNPF_COMPAT_SURFACE.md` §8 的 B1–B10。 + +🔴 台账的 `src` 列是官方出处 `文件:行号` ⇒ 由**引文闸门**(`check-citations.sh`)逐条核对 +⇒ 台账里的官方出处**不是抄来的**,是**验过的**。 + +🔴 **守卫对账是静态推导**(`require_module(&state,&headers,CONST)` ⇒ 菜单 key; +`guard(&state,&headers,EN_X)` ⇒ 点权限编码)⇒ 改守卫写法会让扫描器**推不出来** +(报 ⚠️ WARN,**不**判失败,但要人工核对)。 +🔴 **尺子自证**:结尾比对「实际跑了多少条断言」与「契约登记的条数」,对不上 ⇒ 失败。 +🔴 **改端点要改两处**:契约 §6 的散文表 **+** 附录 A 的 `[ENDPOINT]`。 + +### 4.6 文档引文(`路径:行号`)核对(静态闸门 4) + +```bash +bash scripts/check-citations.sh # 期望:PASS=4 FAIL=0,退出码 0 +bash scripts/check-citations.sh --list # 顺带打印每条引文明细 +``` + +**纯静态**(只需要 `python3`)。本仓的文档大量引用源码位置,行号是**会漂移**的: +源码改一行 ⇒ 上游行号整体位移 ⇒ 文档里的引用**静默指向别的行**——不报错,只是悄悄说错话。 +本闸门把每条引文**解析到真实文件**并核对行号: + +| 判据 | 内容 | +|---|---| +| **CIT1** | 引文**可解析**:每条 `路径:行号` 都能定位到真实文件(当前 141 条) | +| **CIT2** | 引文**行号有效**:行号区间落在该文件的行数范围内(`N` / `N-M` / `N/M` / `N+` 四种写法) | +| **CIT3** | **DDL 行号表**对账:`CLAUDE.md` 里写的建表行号 ↔ 官方 DDL 那一行真的有 `CREATE TABLE <表名>`(7 张 `base_*` 表) | +| **CIT1'** | **反自证** —— 注入 3 类坏引用(行号越界 / 文件不存在 / DDL 行号错位),必须**每一种**都被抓到 | + +**解析口径**(三级,先精确后模糊):① `<根>/<路径>` 精确命中 ⇒ ② 相对路径**后缀**命中 +(`db/schema.sql` ⇒ `src/backend/db/schema.sql`)⇒ ③ **基名**命中(官方源码文档里 +`ActionResult.java:27` 这种写法)。参照根共 4 处:本仓 / 官方 JNPF 源码 +(`~/Desktop/workspace/jnpf`)/ react 姊妹技能 / cargo registry(引文指到依赖源码时,如 +`pglite-rs 0.2.7` 的 `src/db.rs:444`)。 + +退出码:**0** 全过 / **1** 有 ❌ / **2** 用法错或前置错误。 + +🔴 **外部参照根缺失 ⇒ 判「跳过」不判失败**(官方源码 / react 技能 / cargo registry 都不在本机时, +本闸门只校验本仓内的引文,条数照旧、状态记 ⏭)。 +🔴 **「无路径的续行行号」(`:NNN`)只报不判失败** —— 那是本仓表格的约定(先写文件名、 +下面只写行号),且**相邻两行可能指不同文件** ⇒ 机械继承会大量误报。 +本闸门用「上文 40 行内点名的文件里**任意一个**行数够」这种**弱判据**核对, +对不上才报「疑似漂移」。 +🔴 **尺子自证**:结尾比对「实际跑了多少条断言」与「契约登记的条数」,对不上 ⇒ 失败。 + +### 4.7 macOS SysV 信号量回收(`cargo test` 跑多了会攒) + +```bash +bash scripts/reap-ipc-leaks.sh # 扫 + 回收本仓的孤儿信号量集 +bash scripts/reap-ipc-leaks.sh --dry-run # 只扫不删 +``` + +🔴 **为什么需要**:pglite 的 `initdb` 会 `semget` 一个 `nsems=20` 的信号量集, +而 macOS(XNU)**不回收**进程退出时留下的信号量集(Linux 有 `ipcrm`,macOS 没有)⇒ +`cargo test` 跑久了会攒到几千个 ⇒ 撞上 `kern.sysv.semmns`(本机 87381)上限 ⇒ +`semget` 失败 ⇒ 测试莫名其妙起不来。 +脚本用 `nsems==20` 这个 **PGlite 指纹**定位(零业务内容),只回收**当前用户**的。 + +### 4.8 生产档弱密钥守卫 + +```bash +SSW_PROFILE=prod SEED_ADMIN_PASSWORD=123456 ./target/release/ssw-jnpf-lite-rust +# ⇒ [启动失败] 生产档弱密钥守卫未通过(SSW_PROFILE=prod): +# - SEED_ADMIN_PASSWORD:判据③:值等于已知弱值(123456) +# - SEED_ADMIN_PASSWORD:判据⑥:长度 6 < 12 +# ⇒ 退出码 1 +``` + +🔴 **六条判据**:① 键不在清单里 ⇒ 跳过 ② 空/空白 ③ 精确等于已知弱值 +④ **含**已知弱值(反绕过,`123456x` 也拦)⑤ 命中弱标记词(**整体词**,`administrator` 不误伤) +⑥ 长度 < 12。 +🔴 **两道检查**:配置级(本次用的种子口令)+ **库内级**(回读 `base_user` 的 admin 行)—— +库内级是必须的:种子口令只对**空库**生效 ⇒ 生产库里那个可能是当初种下的 `123456`, +运维后来才设了 `SEED_ADMIN_PASSWORD` ⇒ 只查配置 = 守卫形同虚设。 +🔴 **不做误伤**:管理员**合法改过**口令后,库里那个不再等于任何已知弱值 ⇒ 放行。 + +--- + +## 5. 前端手验清单(验收门④) + +```bash +bash run.sh dev +``` + +浏览器打开 **http://127.0.0.1:5173**: + +1. `admin` / `123456` 登录 ⇒ 进 Dashboard; +2. 菜单树正确:系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市; +3. 5 个管理页可增删改(用户 / 角色 / 机构 / 菜单 / 授权); +4. 3 个业务页可用(DemoItem / Product / Book); +5. 退出再登录 ⇒ 仍正常。 + +**代理自检**(不开浏览器也能验): + +```bash +curl --noproxy '*' -s http://127.0.0.1:5173/ | grep '
' +curl --noproxy '*' -s http://127.0.0.1:5173/api/health +# => {"ok":true,"tables":10,"version":"0.1.0"} ← 说明 vite 代理把 /api 转到了 30010 +``` + +--- + +## 6. 常见故障 + +### 6.1 本机特有 + +| 症状 | 根因 | 处理 | +|---|---|---| +| `curl http://127.0.0.1:5173` 连不上 / 502 | 本机 curl 走**系统代理** | 加 `--noproxy '*'` | +| `localhost:5173` 连不上 | macOS 上 vite 默认只 bind `::1` | 用 `127.0.0.1:5173`(`vite.config.ts` 已强制 IPv4) | +| 起后台进程后工具一返回就没了 | `nohup … &` 会被回收 | 用 Bash 工具的 `run_in_background`;stdout **不要**指向 `/dev/null`(进程会以 100 退出) | +| vite 报端口被占 | `strictPort: true`(故意不自动换端口) | `lsof -ti:5173` 看清是谁;或 `bash run.sh stop` | +| `npm install` 卡在 esbuild | npm 11 的 `allowScripts` 闸门 | `npm --prefix src/frontend install-scripts approve esbuild && npm --prefix src/frontend install` | +| 第二个后端实例起不来 | **pglite 单实例独占数据目录** | 换 `PGLITE_DIR` 或换端口 | + +### 6.2 契约层(与 `CLAUDE.md` 的踩坑清单一一对应) + +| 症状 | 根因 | 处理 | +|---|---|---| +| 登录必失败(400 账号或密码错误) | cipher key 当成 16 字节原始摘要 ⇒ AES-128 | key = `md5_hex` 的 **32 个 ASCII 字节** ⇒ AES-256 | +| `f_price` 回显 `9.9` 而不是 `"9.90"` | `row_to_json` 把 numeric 给了数字 | 投影里 `f_price::text AS price` | +| 角色授权写了不生效 | 写进 `base_role_relation.f_user_id`(**不存在此列**) | 用户 id 写 `f_object_id` + `f_object_type='user'` | +| 组织/岗位授权不生效 | 写进 `base_role_relation` | 写 `base_user_relation`(那里才有 `f_user_id`) | +| 授权接口返 200 但一行没写 | `objectType` 传了 `'Role'`(大写) | 必须小写 `'role'`;`module` 传一维数组 | +| 非管理员拿到了全部菜单 | 只查了角色授权 | 四源合并(直授+角色+组织+岗位) | +| 菜单授权没生效但接口放行 | 菜单 `f_url_address` ≠ 前端 Route path | 三处(urlAddress / Route path / 守卫 key)必须一字不差 | +| 405 返回 HTML / 丢 `Allow` 头 | 用了 axum 的 `method_not_allowed_fallback` | 用响应改写中间件(链尾) | +| DDL 能从 HTTP 下载 | DDL 落在 web root | 移到 `db/` + 兜底守卫 | + +--- + +## 7. 数据重置 + +库是**嵌入式 pglite 数据目录**(默认 `src/backend/data/lite.pg`),**没有独立的 PG 服务**。 + +```bash +bash run.sh stop +mv src/backend/data src/backend/data.bak-$(date +%s) # 改名备份(可恢复),下次启动重建空库 +bash run.sh dev # 空库 ⇒ 重新种子(admin/123456) +``` + +🔴 **schema 只在首次建表时执行** ⇒ 改了 `src/backend/db/schema.sql` 之后**必须**走这一步,否则改动不生效。 + +--- + +## 8. 边界(别越界) + +- `tdc-rs` 兄弟项目:**不共享**代码 / 端口 / 数据目录。`run.sh` 的 `kill_ports` 只清 30010 与 5173。 +- `~/Desktop/workspace/skills/ssw-jnpf-lite-react/`(参照物):**只读**。本仓 `src/frontend/` 是它的逐字复制, + 唯一改动是 `vite.config.ts` 的代理端口**改成 30010**(连注释行一起改); + `src/api/request.ts` 的**陈旧端口注释**(写的仍是旧端口号)与 `:31` 的 axios **30 秒超时** + (`timeout` 毫秒数,**不是**端口)**刻意逐字节不动**。 + `vite.config.ts:11` 的注释里仍写着「NestJS 后端」(本仓是 Rust)—— 同样**刻意逐字保留**,只记档。 +- `src/backend/**`、`docs/contract.md`、`scripts/perm-smoke.sh`:**已定稿**,改动需走评审。 +- **前端 Dashboard 只渲染「目录的子项」**(`node.children`)⇒ `Demo 示例` / `产品管理` / `图书超市` + 是**顶层页面型菜单**(`parent_id='0'`、无子项)⇒ **Dashboard 里没有它们的按钮**, + 只能按 URL 直达(`/demo-item`、`/shop/Product`、`/books/Book`)。 + 这是**参照物原样行为**且与契约 §8.4 一致 ⇒ **不改**,只记档。 +- `/favicon.ico` 在 vite dev server 上返 **404**(`index.html` 没有 favicon 引用)⇒ 浏览器 console 两条 404;无害。 diff --git a/references/BaseCrudController.java b/references/BaseCrudController.java new file mode 100644 index 0000000..0690e50 --- /dev/null +++ b/references/BaseCrudController.java @@ -0,0 +1,332 @@ +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 new file mode 100644 index 0000000..0626273 --- /dev/null +++ b/references/README.md @@ -0,0 +1,49 @@ +# 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/run.sh b/run.sh new file mode 100755 index 0000000..c7d55b4 --- /dev/null +++ b/run.sh @@ -0,0 +1,277 @@ +#!/usr/bin/env bash +# ssw-platform 一键脚本 +# +# 后端 = Rust 单二进制(cargo workspace 根 = 仓库根 ⇒ target/ 在仓库根)。 +# 数据库为嵌入式 pglite-rs(进程内原生 PostgreSQL),零服务 / 零 Docker / 零 WASM。 +# +# 用法: +# ./run.sh install 安装依赖(cargo fetch + npm install) +# ./run.sh build 构建(cargo build --release + vite build) +# ./run.sh dev 后台起后端(30010) + 前端(5173),日志进 .logs/,PID 写入 .run/ +# (**后端与前端都就绪**才算成功;任一没就绪 ⇒ 退出码 1) +# ./run.sh backend 前台起后端 +# ./run.sh frontend 前台起前端 +# ./run.sh stop 用 PID 文件停后台进程 + 兜底 kill_ports +# ./run.sh logs tail .logs/{backend,frontend}.log +# ./run.sh --help 本用法 +# +# 退出码:0 成功 / 1 运行期失败 / 2 用法错 +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")" && pwd)" +LOGS="$ROOT/.logs" +RUN="$ROOT/.run" + +# 后端端口:兄弟项目 tdc-rs 已占用它自己的后端端口,本仓一律用 30010。 +# 前端 vite 端口固定 5173(vite.config.ts 里 strictPort: true)。 +BACKEND_PORT=30010 +FRONTEND_PORT=5173 + +# 🔴 kill_ports 用的是 kill -9 ⇒ 端口列表**只能是本仓自己的这两个端口**。 +# 不许把兄弟项目 tdc-rs 的端口写进来(打死它就是破坏兄弟项目)。 +BACKEND_BIN="$ROOT/target/release/ssw-platform" + +# 加载项目根 .env(后端不 import dotenv,靠这里把 PORT / PGLITE_DIR 导出给子进程) +if [ -f "$ROOT/.env" ]; then + set -a; . "$ROOT/.env"; set +a +fi + +export PORT="${PORT:-30010}" + +# 🔴 **端口守卫**:只在**真会启动后端**的子命令(`dev` / `backend`)里生效。 +# 理由:守卫存在的唯一理由是「后端子进程会继承 `PORT` 并真的绑那个端口」。 +# `frontend` / `stop` / `install` / `build` / `logs` / `--help` / 无参**根本不碰端口** +# ⇒ 不该因为环境里恰好有个 `PORT` 就失败(那是误伤)。 +# 🔴 本仓端口是硬约定:后端固定 30010、前端固定 5173。 +# (不是「改成用 $PORT 清端口」——那会让 kill_ports 去杀**任意端口**上的进程。) +guard_port() { + if [ "${PORT}" != "${BACKEND_PORT}" ]; then + echo "[用法错] PORT=${PORT} 与本仓硬约定的后端端口 ${BACKEND_PORT} 不一致。" + echo " 本仓端口是硬约定(兄弟项目已占用它自己的端口,两套服务必须彻底分开)。" + echo " 要用别的端口请直接跑二进制:PORT=${PORT} ${BACKEND_BIN}" + exit 2 + fi +} + +usage() { + cat <<'EOF' +用法: ./run.sh <子命令> + install 安装依赖(cargo fetch + npm install) + build 构建(cargo build --release + vite build) + dev 后台起后端(30010) + 前端(5173);**后端与前端都就绪**才算成功 + backend 前台起后端 + frontend 前台起前端 + stop 停止后台进程 + logs 打印后端/前端日志尾部 + --help 本用法 +退出码: 0 成功 / 1 运行期失败 / 2 用法错 +端口: 后端固定 30010、前端固定 5173(硬约定;PORT 改成别的值 ⇒ dev/backend 退出码 2) +EOF +} + +# 端口守护:dev/start 前清掉残留进程,避免 EADDRINUSE 被静默吞掉(旧进程仍占端口, +# 新进程崩溃但请求全部打到旧实例 → 看起来「改了 seed 但菜单不变」之类的灵异 bug)。 +kill_ports() { + local killed=0 + for p in "$@"; do + local pids + pids="$(lsof -ti:"$p" 2>/dev/null || true)" + if [ -n "$pids" ]; then + echo " ↳ 端口 $p 被旧进程占用 (PID: $pids),清理中…" + # shellcheck disable=SC2086 + kill -9 $pids 2>/dev/null || true + killed=1 + fi + done + # 注意 set -e:端口空闲时 [ ] 返回 1 会炸掉调用方(dev 走不到 start_logged) + [ "$killed" -eq 1 ] && sleep 1 + return 0 +} + +# 🔴 **就绪轮询**:起完进程不等于服务可用。 +# 旧版 dev 起完就打印「服务已在后台启动」并 exit 0 ⇒ 后端起不来(数据库路径写错等) +# 时**脚本报成功、实际没有服务** ⇒ 极难定位。 +# ⇒ 轮询 /api/health(routes.rs 里真有的探活端点),最长 30 秒。 +# 本机 curl 走系统代理 ⇒ 必须带 --noproxy '*'。 +wait_backend_ready() { + local i + for i in $(seq 1 30); do + if curl --noproxy '*' -fsS -m 2 "http://127.0.0.1:${BACKEND_PORT}/api/health" >/dev/null 2>&1; then + return 0 + fi + sleep 1 + done + return 1 +} + +# 🔴 **就绪轮询(前端)**:与 wait_backend_ready 同形,轮 vite 的根路径。 +# 超时 60 秒(比后端长):vite 首次启动要做依赖预打包,冷启动可能十几秒。 +# 没有它 ⇒ 前端 vite 起不来(依赖没装 / 端口被占 / npm run dev 立刻报错退出)时, +# 脚本照样打印「服务已在后台启动」⇒ **脚本报成功、实际没有前端**。 +# 本机 curl 走系统代理 ⇒ 必须带 --noproxy '*'。 +wait_frontend_ready() { + local i + for i in $(seq 1 60); do + if curl --noproxy '*' -fsS -m 2 "http://127.0.0.1:${FRONTEND_PORT}/" >/dev/null 2>&1; then + return 0 + fi + sleep 1 + done + return 1 +} + +# 用 PID 文件优雅停(先 SIGTERM,宽限期内还在才 SIGKILL),清理 root 进程树 +# 🔴 宽限期**可按进程给**:后端的优雅停机要「关嵌入式 PostgreSQL」(main.rs 给 PG 的预算是 3 秒), +# 若这里只等 1 秒就 SIGKILL ⇒ 正好把 M-9 要修的「PG 被 SIGKILL 打断 ⇒ crash recovery」又打回来。 +# ⇒ 后端给 3 秒(与 main.rs 的预算对齐);前端(npm/vite)1 秒足够。 +stop_pid() { + local f="$1" grace="${2:-1}" + [ -f "$f" ] || return 0 + local pid + pid="$(cat "$f" 2>/dev/null || true)" + if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then + echo " ↳ stop $(basename "$f") PID=$pid SIGTERM(宽限 ${grace}s)" + kill -TERM "$pid" 2>/dev/null || true + # 进程**提前退出就立刻收工**(不空等满宽限期)⇒ 0.2s 一跳地轮询存活。 + # (后端实测 ~200ms 就退 ⇒ 不该为此白等 3 秒。) + local waited=0 total=$((grace * 5)) + while [ "$waited" -lt "$total" ] && kill -0 "$pid" 2>/dev/null; do + sleep 0.2 + waited=$((waited + 1)) + done + kill -0 "$pid" 2>/dev/null && kill -KILL "$pid" 2>/dev/null || true + fi + rm -f "$f" +} + +# 用 nohup 后台起,stdout/stderr 都进日志;写 PID 便于 ./run.sh stop 精准收 +start_logged() { + local dir="$1" cmd="$2" name="$3" + mkdir -p "$LOGS" + : > "$LOGS/${name}.log" + ( + cd "$ROOT/$dir" || exit 1 + # nohup + & 把子进程从父进程会话脱离,CI/harness 退出不会拖垮服务; + # setsid 让子进程成为新进程组领头,避免父 SIGINT 误杀。 + # macOS 无 setsid(Linux util-linux 专有),探测后回退纯 nohup。 + if command -v setsid >/dev/null 2>&1; then + setsid nohup $cmd > "$LOGS/${name}.log" 2>&1 & + else + nohup $cmd > "$LOGS/${name}.log" 2>&1 & + fi + echo $! > "$RUN/${name}.pid" + ) + echo " ↳ $name PID=$(cat "$RUN/${name}.pid") log=$LOGS/${name}.log" +} + +case "${1:-}" in + -h|--help|help) + usage + ;; + install) + (cd "$ROOT" && cargo fetch) + npm --prefix "$ROOT/src/frontend" install + ;; + build) + (cd "$ROOT" && cargo build --release) + npm --prefix "$ROOT/src/frontend" run build + ;; + dev) + # 🔴 守卫与二进制检查**都在** kill_ports **之前** —— + # 否则「用法错 / 二进制缺失」会先把 30010/5173 上的进程 kill -9 了(失败却先破坏现场)。 + guard_port + if [ ! -x "$BACKEND_BIN" ]; then + echo "[启动失败] 后端二进制不存在: $BACKEND_BIN" + echo " 先跑「./run.sh build」(cargo build --release)。" + exit 1 + fi + kill_ports "$BACKEND_PORT" "$FRONTEND_PORT" + mkdir -p "$LOGS" "$RUN" + # 🔴 后端 cwd = 仓库根(dir=".")⇒ 相对路径的 PGLITE_DIR 也落在仓库内。 + # 🔴 命令行**不带** PORT= 前缀 —— PORT 已由 .env / export 导出,子进程继承。 + start_logged . "./target/release/ssw-platform" backend + start_logged src/frontend "npm run dev" frontend + # 🔴 就绪校验:后端没真正起来 ⇒ **不许**报成功。 + if ! wait_backend_ready; then + echo + echo "[启动失败] 后端在 30 秒内没就绪(/api/health 不通)。" + # 🔴 本次刚起的前端**一并收掉** —— 不许把一个 vite dev server 残在后台占着 5173 + # (用户看到「启动失败」,机器上却留着一个前端 dev server,极难联想到是同一次启动留下的)。 + # **两条都做**:`stop_pid` 走 PID 文件(SIGTERM → 1s → SIGKILL), + # `kill_ports` 按端口 kill -9 **兜底** —— + # 因为 `stop_pid` 依赖 npm 把 SIGTERM 转发给 vite(npm 的内部实现细节,**不是保证**), + # 有了 `kill_ports` 兜底 ⇒「不会在 5173 上留残进程」**无条件**成立。 + # **不用** pkill(模式太宽会误杀别的项目)。 + stop_pid "$RUN/frontend.pid" + kill_ports "$FRONTEND_PORT" + echo " ↳ 本次刚起的前端进程已一并收掉(PID 文件 SIGTERM → SIGKILL + 按端口 kill -9 兜底)" + echo "--- .logs/backend.log 尾部 ---" + tail -n 20 "$LOGS/backend.log" 2>/dev/null || true + exit 1 + fi + # 🔴 就绪校验(前端):vite 起不来时同样**不许**报成功。 + if ! wait_frontend_ready; then + echo + echo "[启动失败] 前端在 60 秒内没就绪(http://127.0.0.1:${FRONTEND_PORT}/ 不通)。" + # 🔴 同上:PID 文件 + 按端口兜底,两条都做 ⇒ 不在 5173 上留残进程。 + stop_pid "$RUN/frontend.pid" + kill_ports "$FRONTEND_PORT" + echo " ↳ 本次刚起的前端进程已一并收掉(PID 文件 SIGTERM → SIGKILL + 按端口 kill -9 兜底)" + # 🔴 本仓既定裁决:dev 失败**不收后端**(后端可能只是慢;下一次 dev/stop 的 + # kill_ports ${BACKEND_PORT} 会自愈)⇒ 但必须把后端的去留**说清楚**。 + echo " ↳ 后端仍在 ${BACKEND_PORT} 上运行,要停请执行「./run.sh stop」" + echo "--- .logs/frontend.log 尾部 ---" + tail -n 20 "$LOGS/frontend.log" 2>/dev/null || true + exit 1 + fi + echo + echo "服务已在后台启动(后端与前端**都已就绪**)。后端: http://127.0.0.1:${BACKEND_PORT} 前端: http://127.0.0.1:${FRONTEND_PORT}" + echo "日志:tail -f $LOGS/{backend,frontend}.log" + echo "停止:./run.sh stop" + ;; + backend) + # 🔴 守卫在 kill_ports 之前(同 dev:失败却先破坏现场是不对的)。 + guard_port + if [ ! -x "$BACKEND_BIN" ]; then + echo "[启动失败] 后端二进制不存在: $BACKEND_BIN" + echo " 先跑「./run.sh build」(cargo build --release)。" + exit 1 + fi + kill_ports "$BACKEND_PORT" + # 🔴 用 exec ⇒ 后端**自己的**退出码原样透传(本仓二进制 panic 时是 101,不是 1)。 + (cd "$ROOT" && exec ./target/release/ssw-platform) + ;; + frontend) + kill_ports "$FRONTEND_PORT" + npm --prefix "$ROOT/src/frontend" run dev + ;; + stop) + mkdir -p "$LOGS" "$RUN" + # 🔴 **实际的停止路径 = PID 文件(SIGTERM→SIGKILL)+ kill_ports(按端口 kill -9)**。 + # pkill 只作为最后一道兜底,且**模式必须精确**: + # macOS/BSD 的 `pkill -f` 匹配的是**完整命令行**(argv 全部拼接), + # 宽模式(如按进程名)会连「命令行里提到本仓名字」的无关进程一起杀掉 + # (本脚本自己、harness 的监督 shell、tail -f 日志、别的项目的 vite)。 + stop_pid "$RUN/backend.pid" 3 + stop_pid "$RUN/frontend.pid" + kill_ports "$BACKEND_PORT" "$FRONTEND_PORT" + # 只匹配后端本体的完整路径(cargo/rustc 的 argv 里是目录名与下划线形式,都不匹配)。 + # 🔴 vite **不**用 pkill 收 —— 它由上面的 kill_ports 5173 按**端口**收, + # 不会误杀别的项目的 vite dev server。 + pkill -f "target/release/ssw-platform" 2>/dev/null || true + # 🔴 旧名兜底:名称历经 `tds-lite-rs` → `ssw-jnpf-lite-rust` → `ssw-platform`, + # 改名之前起的后端进程不会被上一行 pkill 匹配到 ⇒ 这里补收一次。 + pkill -f "target/release/tds-lite-rs" 2>/dev/null || true + echo "stopped" + ;; + logs) + mkdir -p "$LOGS" "$RUN" + # 🔴 补 || true:日志文件不存在时 [ -f ] 返回 1,set -e 下会让脚本以 1 退出。 + { [ -f "$LOGS/backend.log" ] && echo "=== backend ===" && tail -n 50 "$LOGS/backend.log"; } || true + { [ -f "$LOGS/frontend.log" ] && echo "=== frontend ===" && tail -n 50 "$LOGS/frontend.log"; } || true + ;; + *) + usage + exit 2 + ;; +esac diff --git a/scripts/check-boundary-scan.py b/scripts/check-boundary-scan.py new file mode 100644 index 0000000..bd954db --- /dev/null +++ b/scripts/check-boundary-scan.py @@ -0,0 +1,246 @@ +#!/usr/bin/env python3 +"""check-boundary-scan.py —— 平台层「零业务知识」扫描器(`check-boundary.sh` 的 CP1 后端)。 + +🔴 **为什么需要它**:CLAUDE.md 红线 12 要求「加一个业务模块只碰业务层」 + ⇒ 平台层(`src/backend/src/platform/`)里**不许出现任何业务标识符** + (业务表名 / 实体名 / 路由前缀 / 菜单 id / 菜单 url / 菜单 en_code)。 + 这条规则**只靠人看代码守不住** —— 加模块的人不会主动去看平台层 ⇒ 需要一把尺子。 + +🔴 **禁止的标识符清单从业务层自己派生**(不是手写常量表): + 业务层说了什么 ⇒ 平台层就不许出现什么 ⇒ **加一个业务模块,这把尺子自动变严**, + 不会出现「忘了同步常量表 ⇒ 漏检」。 + +🔴 **只扫「字符串字面量」**(注释不算): + 注释里举例说明业务名是**文档行为**(例如解释 CTE 作用域)⇒ 允许; + 代码里出现业务标识符才是**耦合** ⇒ 拦。 + +用法: + python3 scripts/check-boundary-scan.py [...] + +退出码: + 0 = 干净(平台层零业务标识符) + 1 = 发现泄漏(逐条打印 `文件:行号: [种类] token`) + 2 = 用法错 +""" + +import os +import re +import sys + +# 🔴 业务层里「哪些字段是业务知识」的抽取规则(与 `EntitySpec` / `MenuSpec` 的字段名对齐)。 +SPEC_TABLE_RE = re.compile(r'table:\s*"([^"]+)"') +SPEC_ENTITY_RE = re.compile(r'entity:\s*"([^"]+)"') +SPEC_APP_RE = re.compile(r'app_code:\s*"([^"]+)"') +MENU_BLOCK_RE = re.compile(r'MenuSpec\s*\{(.*?)\n\};', re.DOTALL) +MENU_FIELD_RE = { + # 🔴 `\b` 不可省:否则 `parent_id: "0"` 里的 `id:` 会被当成菜单 id。 + "id": re.compile(r'\bid:\s*"([^"]+)"'), + "en_code": re.compile(r'\ben_code:\s*"([^"]+)"'), + "url_address": re.compile(r'\burl_address:\s*"([^"]+)"'), +} + +# 🔴 字符串字面量:`r#"..."#` / `r"..."` / `"..."`(普通串的转义 `\"` 不影响子串判定)。 +LITERAL_RE = re.compile(r'r(#*)"(.*?)"\1|"((?:[^"\\]|\\.)*)"', re.DOTALL) + + +def strip_comments(src): + """去掉 `//` 行注释与 `/* */` 块注释(保留字符串字面量里的内容)。 + + 🔴 逐字符扫描 ⇒ 字符串里的 `//`(如 `"http://x"`)不会被误当注释。 + """ + out = [] + in_block = False + for line in src.splitlines(): + if in_block: + end = line.find("*/") + if end == -1: + continue + line = line[end + 2:] + in_block = False + buf = [] + in_str = False + i = 0 + n = len(line) + while i < n: + c = line[i] + if in_str: + buf.append(c) + if c == "\\" and i + 1 < n: + buf.append(line[i + 1]) + i += 2 + continue + if c == '"': + in_str = False + i += 1 + continue + if c == '"': + in_str = True + buf.append(c) + i += 1 + continue + if line.startswith("//", i): + break + if line.startswith("/*", i): + in_block = True + rest = line[i + 2:] + end = rest.find("*/") + if end == -1: + break + line = rest[end + 2:] + buf = [] + i = 0 + n = len(line) + in_str = False + continue + buf.append(c) + i += 1 + out.append("".join(buf)) + return out + + +def literals_with_lines(path): + """⇒ [(行号, 字面量内容)](注释已剔除)。""" + with open(path, "r", encoding="utf-8") as fh: + lines = strip_comments(fh.read()) + out = [] + for idx, line in enumerate(lines, start=1): + for m in LITERAL_RE.finditer(line): + content = m.group(2) if m.group(1) is not None else m.group(3) + if content is not None: + out.append((idx, content)) + return out + + +def business_tokens(modules_dir): + """从业务层派生「平台层不许出现」的标识符清单。 + + ⇒ [(种类, token)],种类用于报错时点名「漏的是哪一类」。 + """ + tokens = [] + seen = set() + + def add(kind, value): + if not value: + return + key = (kind, value) + if key in seen: + return + seen.add(key) + tokens.append((kind, value)) + + for name in sorted(os.listdir(modules_dir)): + if not name.endswith(".rs") or name == "mod.rs": + continue + path = os.path.join(modules_dir, name) + with open(path, "r", encoding="utf-8") as fh: + src = "\n".join(strip_comments(fh.read())) + for m in SPEC_TABLE_RE.finditer(src): + add("业务表名", m.group(1)) + for m in SPEC_ENTITY_RE.finditer(src): + add("业务实体名", m.group(1)) + for m in SPEC_APP_RE.finditer(src): + add("业务路由前缀", "/api/ssw/{}/".format(m.group(1))) + for m in MENU_BLOCK_RE.finditer(src): + body = m.group(1) + for kind, rx in MENU_FIELD_RE.items(): + for f in rx.finditer(body): + add("业务菜单 {}".format(kind), f.group(1)) + return tokens + + +def rust_files(root): + """⇒ root 下全部 `.rs` 文件(递归,按路径排序)。""" + out = [] + for dirpath, dirnames, filenames in os.walk(root): + dirnames.sort() + for name in sorted(filenames): + if name.endswith(".rs"): + out.append(os.path.join(dirpath, name)) + return out + + +def main(argv): + if len(argv) >= 2 and argv[1] == "--self-test": + return self_test() + + if len(argv) < 3: + sys.stderr.write( + "用法: python3 scripts/check-boundary-scan.py [...]\n" + ) + return 2 + + modules_dir = argv[1] + scan_dirs = argv[2:] + tokens = business_tokens(modules_dir) + if not tokens: + sys.stderr.write("业务层没解析出任何标识符(modules_dir 有问题?)\n") + return 2 + + violations = [] + scanned = 0 + for root in scan_dirs: + for path in rust_files(root): + scanned += 1 + rel = os.path.relpath(path) + for lineno, content in literals_with_lines(path): + for kind, token in tokens: + if token in content: + violations.append((rel, lineno, kind, token, content.strip())) + + for rel, lineno, kind, token, content in violations: + print("{}:{}: [{}] {} ← 字面量: {}".format(rel, lineno, kind, token, content[:120])) + + print("scanned_files={} tokens={} violations={}".format(scanned, len(tokens), len(violations))) + return 1 if violations else 0 + + +def self_test(): + """🔴 **反自证**:造一个「平台层泄漏业务表名」的假文件 ⇒ 必须被抓出来。 + + 🔴 **为什么必须有**:一把永远返回「干净」的尺子 = 没有尺子。 + 自证 = 用同一条规则去抓一个**明知存在**的泄漏 ⇒ 抓到了 ⇒ 规则本身有效。 + """ + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + mods = os.path.join(tmp, "modules") + plat = os.path.join(tmp, "platform") + os.makedirs(mods) + os.makedirs(plat) + with open(os.path.join(mods, "demo.rs"), "w", encoding="utf-8") as fh: + fh.write( + 'pub const DEMO_SPEC: EntitySpec = EntitySpec {\n' + ' app_code: "demo",\n' + ' entity: "DemoItem",\n' + ' table: "demo_item",\n' + '};\n' + ) + # 泄漏:平台层里出现了业务表名(**在字符串字面量里**)。 + with open(os.path.join(plat, "leak.rs"), "w", encoding="utf-8") as fh: + fh.write('const SQL: &str = "SELECT * FROM demo_item";\n') + # 不泄漏:只在**注释**里提到业务表名(文档行为,允许)。 + with open(os.path.join(plat, "doc.rs"), "w", encoding="utf-8") as fh: + fh.write('// 例:SELECT * FROM demo_item\nconst OK: &str = "SELECT 1";\n') + + tokens = business_tokens(mods) + # 表名 + 实体名 + 路由前缀(假 spec 里没有 MenuSpec ⇒ 没有菜单那三类)。 + if len(tokens) != 3: + print("self-test: token 抽取数不对: {}".format(len(tokens))) + return 1 + + hits = 0 + for path in rust_files(plat): + for _lineno, content in literals_with_lines(path): + for _kind, token in tokens: + if token in content: + hits += 1 + if hits != 1: + print("self-test: 应恰好抓到 1 处泄漏,实际 {} 处".format(hits)) + return 1 + + print("self-test: OK(泄漏被抓到、注释里的举例未被误报)") + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv)) \ No newline at end of file diff --git a/scripts/check-boundary.sh b/scripts/check-boundary.sh new file mode 100755 index 0000000..416e305 --- /dev/null +++ b/scripts/check-boundary.sh @@ -0,0 +1,268 @@ +#!/usr/bin/env bash +# ssw-platform 分层红线自检 —— 「平台层 / 业务层」不许互相渗透 +# +# 目的:把 CLAUDE.md **红线 12**(「加一个业务模块只碰业务层」)变成**可执行的尺子**。 +# 这条红线靠人读代码守不住 —— 加模块的人不会主动去看平台层 ⇒ 必须自动查。 +# +# 🔴 **纯静态**:不启动后端、不发请求。只需要 `python3`(macOS 自带)。 +# +# 用法: +# bash scripts/check-boundary.sh # 无参 ⇒ 全查 +# bash scripts/check-boundary.sh --help # 本用法 +# +# 退出码:0 全过 / 1 有 ❌ 项 / 2 用法错 +# +# ── 判据 ── +# CP1 平台层零业务标识符(业务表名 / 实体名 / 路由前缀 / 菜单 id / url / en_code) +# —— 只扫**字符串字面量**(注释里举例说明业务名是文档行为,允许) +# —— 禁止清单**从业务层自己派生** ⇒ 加模块时这把尺子自动变严 +# CP1' 扫描器**反自证**:造一个明知存在的泄漏 ⇒ 必须被抓到(永远返回「干净」的尺子 = 没有尺子) +# CP2 平台层**不反向依赖**业务层:`platform/**` 不许 `use crate::modules` +# CP3 业务层**不直接调**平台层的种子:`modules/**` 不许 `platform::seed` +# (接线只在装配根 `bootstrap.rs`) +# CP4 每个业务模块必须声明自己的菜单(`*_MENU: MenuSpec`)⇒ 且被 `modules/mod.rs` +# 的 `ALL_MENUS` 收编(漏一处 ⇒ 菜单不显示 / admin 少一条授权) +# ⇒ 且声明的菜单 id 与**契约** `[MENU]` 里该模块那一行一致 +# CP5 `platform::seed::ensure_base` 的调用点**只有** `bootstrap.rs` +# (应用与测试都走装配根 ⇒ 测到的库 == 上线的库) +# CP6 平台层自带菜单**恰好 N 条**(N 由**契约**推出来:契约菜单数 − 业务模块数) +# ⇒ 且平台层那几条的 id **逐条**等于契约里「非业务」的那些菜单 +# +# 🔴 **期望值来自 `docs/contract.md` 附录 A**(机器可读)⇒ 加业务模块时 +# 「契约加一行」自动把 CP4/CP6 的期望值也带上了(脚本不硬编码 5 / 3 / 8)。 + +set -u + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" + +BACKEND="$ROOT/src/backend" +SRC="$BACKEND/src" +PLATFORM="$SRC/platform" +MODULES="$SRC/modules" +MODULES_MOD="$MODULES/mod.rs" +BOOTSTRAP="$SRC/bootstrap.rs" +SCAN="$ROOT/scripts/check-boundary-scan.py" + +usage() { + echo "用法: bash scripts/check-boundary.sh" + echo " 纯静态检查「平台层 / 业务层」分层红线(CLAUDE.md 红线 12)" + echo "退出码: 0 全过 / 1 有 ❌ 项 / 2 用法错" +} + +if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then + usage + exit 0 +fi +if [ "$#" -ne 0 ]; then + echo "❌ 未知参数: ${1}" + usage + exit 2 +fi + +# ---- 前置:python3 必须在(扫描器靠它)---- +PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}" +if [ -z "${PY_BIN}" ]; then + echo "❌ 找不到 python3(扫描器需要它)" + exit 2 +fi +if [ ! -f "${SCAN}" ]; then + echo "❌ 缺扫描器: ${SCAN}" + exit 2 +fi + +# ---- 契约期望值(唯一真源:docs/contract.md 附录 A)---- +CE_PY="$ROOT/scripts/contract_expect.py" +if [ ! -f "${CE_PY}" ]; then + echo "❌ 缺契约期望值读取器: ${CE_PY}" + exit 2 +fi +ce() { "${PY_BIN}" "${CE_PY}" "$@"; } +CE_MENU_ROWS="$(ce rows MENU 2>/dev/null)" || CE_MENU_ROWS="" +CE_MOD_ROWS="$(ce rows MODULE 2>/dev/null)" || CE_MOD_ROWS="" +CE_RULER_ROWS="$(ce rows RULER 2>/dev/null)" || CE_RULER_ROWS="" +if [ -z "${CE_MENU_ROWS}" ] || [ -z "${CE_MOD_ROWS}" ] || [ -z "${CE_RULER_ROWS}" ]; then + echo "❌ 读契约期望值失败(docs/contract.md 附录 A 是不是被改坏了?)" + exit 2 +fi +CE_MENU_COUNT="$(printf '%s\n' "${CE_MENU_ROWS}" | awk -F'\t' 'NR>1 { n++ } END { print n + 0 }')" +CE_MOD_COUNT="$(printf '%s\n' "${CE_MOD_ROWS}" | awk -F'\t' 'NR>1 { n++ } END { print n + 0 }')" +# 平台层该有几条菜单 = 契约菜单总数 − 业务模块数(每个业务模块恰好一条业务菜单) +CE_EXP_PLATFORM_MENUS=$((CE_MENU_COUNT - CE_MOD_COUNT)) +# 契约里「属于业务模块的那些菜单 id」(= [MODULE] 的 menuId 列) +CE_BUSINESS_MENU_IDS="$(printf '%s\n' "${CE_MOD_ROWS}" | awk -F'\t' 'NR>1 { print $6 }' | tr '\n' ' ')" + +PASS=0; FAIL=0 +ok() { echo " ✅ $1"; PASS=$((PASS+1)); } +no() { echo " ❌ $1"; FAIL=$((FAIL+1)); } +hdr() { echo; echo "── $1 ──"; } + +# ---- CP1' 反自证:扫描器自己必须能抓到泄漏 ---- +hdr "[CP1'] 扫描器反自证(--self-test 必须过)" +SELFTEST_OUT="$("${PY_BIN}" "${SCAN}" --self-test 2>&1)" +if [ "$?" -eq 0 ]; then + ok "扫描器自证通过:${SELFTEST_OUT}" +else + no "扫描器自证失败:${SELFTEST_OUT}" +fi + +# ---- CP1 平台层零业务标识符 ---- +hdr "[CP1] 平台层零业务标识符(扫字符串字面量;禁止清单从业务层派生)" +SCAN_OUT="$("${PY_BIN}" "${SCAN}" "${MODULES}" "${PLATFORM}" "${SRC}/routes.rs" "${SRC}/main.rs" "${BOOTSTRAP}" 2>&1)" +if [ "$?" -eq 0 ]; then + ok "平台层没有业务标识符($(printf '%s\n' "${SCAN_OUT}" | tail -1))" +else + no "平台层出现业务标识符:" + printf '%s\n' "${SCAN_OUT}" | sed 's/^/ /' +fi + +# ---- CP2 平台层不反向依赖业务层 ---- +hdr "[CP2] 平台层不反向依赖业务层(platform/** 不许 use crate::modules)" +CP2_HITS="$(grep -rn "use crate::modules" "${PLATFORM}" 2>/dev/null)" +if [ -z "${CP2_HITS}" ]; then + ok "platform/** 没有 use crate::modules" +else + no "platform/** 引用了业务层:" + printf '%s\n' "${CP2_HITS}" | sed 's/^/ /' +fi + +# ---- CP3 业务层不直接调平台层的种子 ---- +hdr "[CP3] 业务层不直接调平台层种子(modules/** 不许 platform::seed)" +CP3_HITS="$(grep -rn "platform::seed" "${MODULES}" 2>/dev/null)" +if [ -z "${CP3_HITS}" ]; then + ok "modules/** 没有 platform::seed(接线只在装配根)" +else + no "modules/** 调了平台层的种子:" + printf '%s\n' "${CP3_HITS}" | sed 's/^/ /' +fi + +# ---- CP4 每个业务模块声明自己的菜单 + 被 ALL_MENUS 收编 ---- +hdr "[CP4] 每个业务模块声明自己的菜单(*_MENU: MenuSpec)并被 ALL_MENUS 收编" +MENU_FILES=0 +MENU_MISSING="" +MENU_UNREGISTERED="" +MENU_MISMATCH="" +for f in "${MODULES}"/*.rs; do + base="$(basename "$f")" + [ "${base}" = "mod.rs" ] && continue + MENU_FILES=$((MENU_FILES+1)) + consts="$(grep -o "^pub const [A-Z_]*_MENU: MenuSpec" "$f" 2>/dev/null | sed 's/^pub const //; s/: MenuSpec$//')" + if [ -z "${consts}" ]; then + MENU_MISSING="${MENU_MISSING} ${base}" + continue + fi + for c in ${consts}; do + if ! grep -q "${c}," "${MODULES_MOD}" 2>/dev/null; then + MENU_UNREGISTERED="${MENU_UNREGISTERED} ${c}(${base})" + fi + done + # 🔴 声明的菜单 id 必须与**契约** `[MODULE].menuId` 一致(该模块的菜单是哪一条, + # 是契约说了算,不是代码自己说了算)。 + C_MENU_ID="$(printf '%s\n' "${CE_MOD_ROWS}" | awk -F'\t' -v f="${base}" 'NR>1 && $8==f { print $6; exit }')" + D_MENU_ID="$(awk '/^[ \t]*id:[ \t]*"/ { s = $0; sub(/^[ \t]*id:[ \t]*"/, "", s); sub(/".*/, "", s); print s; exit }' "$f")" + if [ -z "${C_MENU_ID}" ]; then + MENU_MISMATCH="${MENU_MISMATCH} ${base}(契约 [MODULE] 里没有它)" + elif [ "${C_MENU_ID}" != "${D_MENU_ID}" ]; then + MENU_MISMATCH="${MENU_MISMATCH} ${base}(声明=${D_MENU_ID:-无} 契约=${C_MENU_ID})" + fi +done +if [ -n "${MENU_MISSING}" ]; then + no "这些业务模块没声明菜单(缺 *_MENU: MenuSpec):${MENU_MISSING}" +else + ok "${MENU_FILES} 个业务模块都声明了 *_MENU: MenuSpec" +fi +if [ -n "${MENU_UNREGISTERED}" ]; then + no "这些菜单没被 modules/mod.rs 的 ALL_MENUS 收编(菜单不会被种、admin 少一条授权):${MENU_UNREGISTERED}" +else + ok "全部业务菜单都被 ALL_MENUS 收编" +fi +if [ -n "${MENU_MISMATCH}" ]; then + no "这些业务模块声明的菜单 id 与契约 [MODULE] 对不上:${MENU_MISMATCH}" +else + ok "业务模块声明的菜单 id 与契约 [MODULE] 逐条一致" +fi + +# 🔴 **数量对账**:业务模块文件里的 *_MENU 个数 == ALL_MENUS 里的条目数。 +ALL_MENUS_COUNT="$(awk ' + /pub const ALL_MENUS: &\[MenuSpec\] = &\[/ { inb = 1; next } + inb && /^\];/ { inb = 0; next } + inb && /_MENU,/ { n++ } + END { print n + 0 } +' "${MODULES_MOD}")" +DECLARED_COUNT="$(grep -h -c "^pub const [A-Z_]*_MENU: MenuSpec" "${MODULES}"/*.rs 2>/dev/null | awk '{ s += $1 } END { print s + 0 }')" +if [ "${ALL_MENUS_COUNT}" = "${DECLARED_COUNT}" ]; then + ok "ALL_MENUS 条目数 = 各模块声明的 *_MENU 个数(${ALL_MENUS_COUNT})" +else + no "ALL_MENUS 有 ${ALL_MENUS_COUNT} 条,各模块声明了 ${DECLARED_COUNT} 个 *_MENU ⇒ 对不上" +fi + +# ---- CP5 ensure_base 的调用点只有装配根 ---- +hdr "[CP5] platform::seed::ensure_base 的调用点只有装配根 bootstrap.rs" +CP5_HITS="$(grep -rn "seed::ensure_base" "${SRC}" 2>/dev/null | grep -v "^${BOOTSTRAP}:" )" +if [ -z "${CP5_HITS}" ]; then + ok "只有 bootstrap.rs 调 seed::ensure_base(应用与测试走同一条路)" +else + no "这些地方绕过装配根调了 seed::ensure_base:" + printf '%s\n' "${CP5_HITS}" | sed 's/^/ /' +fi + +# ---- CP6 平台层自带菜单:条数与 id 都由**契约**推出来 ---- +hdr "[CP6] 平台层自带菜单(条数与 id 都由契约 [MENU] 推出来;业务菜单不许混进 platform/seed.rs)" +PLATFORM_MENU_COUNT="$(awk ' + /const BUILTIN_MENUS: \[MenuSpec; / { inb = 1; next } + inb && /^\];/ { inb = 0; next } + inb && /^[[:space:]]*id: "/ { n++ } + END { print n + 0 } +' "${PLATFORM}/seed.rs")" +if [ "${PLATFORM_MENU_COUNT}" -eq "${CE_EXP_PLATFORM_MENUS}" ]; then + ok "platform/seed.rs 的 BUILTIN_MENUS 恰好 ${CE_EXP_PLATFORM_MENUS} 条系统菜单(契约菜单 ${CE_MENU_COUNT} 条 − 业务模块 ${CE_MOD_COUNT} 个)" +else + no "platform/seed.rs 的 BUILTIN_MENUS 有 ${PLATFORM_MENU_COUNT} 条(契约推出应为 ${CE_EXP_PLATFORM_MENUS} 条 = 契约菜单 ${CE_MENU_COUNT} − 业务模块 ${CE_MOD_COUNT})" +fi +# 平台层那几条的 id,必须**逐条**等于契约 [MENU] 里「不属于任何业务模块」的那些 id +PLATFORM_MENU_IDS="$(awk ' + /const BUILTIN_MENUS: \[MenuSpec; / { inb = 1; next } + inb && /^\];/ { inb = 0; next } + inb && /^[[:space:]]*id: "/ { s = $0; sub(/^[ \t]*id: "/, "", s); sub(/".*/, "", s); print s } +' "${PLATFORM}/seed.rs" | sort | tr '\n' ' ')" +CE_PLATFORM_MENU_IDS="$(printf '%s\n' "${CE_MENU_ROWS}" | awk -F'\t' -v biz="${CE_BUSINESS_MENU_IDS}" ' + NR > 1 { + skip = 0 + n = split(biz, ids, " ") + for (i = 1; i <= n; i++) if (ids[i] != "" && ids[i] == $1) skip = 1 + if (!skip) print $1 + } +' | sort | tr '\n' ' ')" +if [ "${PLATFORM_MENU_IDS}" = "${CE_PLATFORM_MENU_IDS}" ]; then + ok "平台层菜单 id 与契约逐条一致:${PLATFORM_MENU_IDS}" +else + no "平台层菜单 id 与契约不一致:平台=${PLATFORM_MENU_IDS:-无} 契约=${CE_PLATFORM_MENU_IDS:-无}" +fi + +# -------- 尺子自证:跑出来的条数必须等于契约里登记的条数 -------- +# +# 🔴 尺子自己知道它断言了几条(PASS+FAIL)。哪天有人删掉几条断言、或者某个分支提前 +# return 了,尺子照样「全绿」—— 变弱的尺子比没有尺子更危险 ⇒ 条数由**契约**钉死。 +CE_EXP_ASSERTIONS="$(printf '%s\n' "${CE_RULER_ROWS}" | awk -F'\t' '$1=="check-boundary.sh" { print $2; exit }')" +hdr "[自证] 尺子条数与契约登记一致" +if [ -n "${CE_EXP_ASSERTIONS}" ]; then + CE_ACT_ASSERTIONS=$((PASS + FAIL)) + if [ "${CE_ACT_ASSERTIONS}" -eq "${CE_EXP_ASSERTIONS}" ]; then + # 自证**不计入** PASS/FAIL(它是元断言,不是业务断言) + echo " ✅ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言 = 契约登记的 ${CE_EXP_ASSERTIONS} 条" + else + echo " ❌ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言,契约登记 ${CE_EXP_ASSERTIONS} 条 ⇒ 尺子被改弱了(少了/多了断言)" + FAIL=$((FAIL + 1)) + fi +fi + +# -------- 总结 -------- +echo +echo "── 总结 ──" +echo "PASS=$PASS FAIL=$FAIL" +if [ "$FAIL" -eq 0 ]; then + echo "全 ✅ 分层红线没被打破" +else + echo "有 ❌,请按上面修复" +fi + +exit $([ "$FAIL" -eq 0 ] && echo 0 || echo 1) diff --git a/scripts/check-citations-scan.py b/scripts/check-citations-scan.py new file mode 100644 index 0000000..5125ee8 --- /dev/null +++ b/scripts/check-citations-scan.py @@ -0,0 +1,570 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""check-citations-scan —— 文档引文(`路径:行号`)校验扫描器。 + +🔴 为什么存在: + 本仓的文档(`SKILL.md` / `MIGRATION.md` / `JNPF_SOURCE_AUDIT.md` / `PERMISSION.md` …) + 大量引用源码位置,语法有三种: + `文件.ext:行号` 单行 + `文件.ext:起-止` 区间 + `文件.ext:行/行/行` 多个散行(斜杠 = 「这几行分别」) + `文件.ext:行+` 该行及其后 + 这些行号是**会漂移**的:源码改一行 ⇒ 上游行号整体位移 ⇒ 文档里的引用 + **静默指向别的行**——不报错,只是悄悄说错话。⇒ 必须有把行号核对清楚的尺子。 + +🔴 纯静态:只读文件,不起服务、不连库、不发请求。纯 `python3`(macOS 自带)。 + +用法: + check-citations-scan.py --root <仓根> [--jnpf <官方源码根>] [--react ] + check-citations-scan.py --list # 打印每条引文明细(排查用) + check-citations-scan.py --self-test # 反自证:注入已知坏引用 ⇒ 必须被抓 + +输出协议(制表符分隔,逐行一条): + CHECK\t\t\t<说明> + WARN\t\t<说明> + +退出码:0 = 扫完(看输出里的 DRIFT)/ 2 = 致命错误(参数错等) +""" + +import argparse +import os +import re +import shutil +import sys +import tempfile + +HERE = os.path.dirname(os.path.abspath(__file__)) +ROOT = os.path.dirname(HERE) + +# 外部参照根(可用环境变量 / 命令行覆盖) +DEFAULT_JNPF = os.path.expanduser("~/Desktop/workspace/jnpf") +DEFAULT_REACT = os.path.expanduser("~/Desktop/workspace/skills/ssw-jnpf-lite-react") +DEFAULT_DDL = os.path.expanduser( + "~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql" +) +# 依赖源码根(cargo registry)—— 文档里会引「某个 crate 的某一版源码的某一行」 +DEFAULT_CARGO = os.path.expanduser("~/.cache/cargo/registry/src") +CARGO_FALLBACK = os.path.expanduser("~/.cargo/registry/src") + +# 遍历时跳过的目录(构建产物 / 依赖树 / 运行期数据) +SKIP_DIRS = { + ".git", ".idea", ".vscode", "node_modules", "target", "dist", "build", + ".next", ".nuxt", "data", "__pycache__", ".venv", "venv", "vendor", + ".workbuddy", ".superpowers", "coverage", ".pytest_cache", ".mypy_cache", +} + +# 文档语料:仓根 *.md + docs/** + references/**(不含 template-boot-jnpf —— 那是另一份骨架) +DOC_GLOBS = ( + ("", "*.md"), + ("docs", "**/*.md"), + ("references", "*.md"), +) + +# 承认的文件后缀(决定什么算「一条引文」) +EXTS = ( + "rs|ts|tsx|jsx|js|vue|sql|sh|py|java|kt|xml|yml|yaml|json|md|html|" + "css|scss|toml|properties|gradle|c|h|go|txt|conf|ini" +) + +# 引文本体:路径 + 行号部分 +CITE_RE = re.compile( + r"(?P(?:[A-Za-z0-9_.\-]+/)*[A-Za-z0-9_.\-]*\.(?:" + EXTS + r"))" + r":(?P\d+(?:(?:\s*[/\-]\s*)\d+)*\+?)" +) + +# 「被提及的文件名」(不带行号)—— 用于给孤儿行号继承上文文件名 +# 🔴 允许 `~/` 前缀(文档里常见 `~/Desktop/workspace/jnpf/…` 这种绝对坐标) +FILE_RE = re.compile( + r"(?P~?/?(?:[A-Za-z0-9_.\-]+/)*[A-Za-z0-9_.\-]*\.(?:" + EXTS + r"))" +) + +# 孤儿行号(`:4503` 这种没有路径的续行引用)—— 只报不判失败 +ORPHAN_RE = re.compile(r"(? 0 and text[m.start() - 1] in "\"'": + continue + # 🔴 **端口号不是引文**:本仓的端口一律写成反引号包裹的 `` `:30010` ``。 + # 判据 = 反引号包裹 **且** 数值 ≥ 1024(真引文的行号在同一写法下都 < 1024, + # 而 DDL 那种大行号(812/2209/…)**不**用反引号包裹)。 + # 🔴 **端口号不是引文**:本仓的端口写成 `` `:30010` `` 或行内的 `后端 :30010`。 + # 判据 = 数字**后面还跟着别的内容**(行内写法)⇒ 端口 / 版本号 / 别的数值; + # 数字**后面是行尾或表格竖线**(列写法)⇒ 才是行号引用。 + # (两种写法的区别是结构性的,不是猜的。) + tail = text[m.end():] + stripped = tail.lstrip(" \t`") + if stripped and not stripped.startswith("|"): + continue + # 表格单元格里的 `` `:30000` `` 同样是端口(数值 ≥ 1024 且被反引号包着) + num = int(m.group(1)) + backticked = (m.start() > 0 and text[m.start() - 1] == "`" + and m.end() < len(text) and text[m.end()] == "`") + if backticked and num >= 1024: + continue + inherited = None + for pos, name in reversed(mentions): + if pos < m.start(): + inherited = name + break + orphans.append({ + "doc": path, + "doc_line": text.count("\n", 0, m.start()) + 1, + "line": int(m.group(1)), + "inherited": inherited, + }) + return cites, orphans, mentions_by_doc + + +def resolve(cite_path, roots, indexes): + """把引文里的路径解析成候选文件列表 [(root名, 绝对路径), …]。 + + 三级解析(先精确后模糊): + ① 精确:<根>/<路径> 存在 + ② 后缀:某根下存在相对路径以 `/<路径>` 结尾(覆盖 `db/schema.sql` → `src/backend/db/schema.sql`) + ③ 基名:路径里没有 `/` 时,按文件名在全仓找(官方源码文档里大量 `XxxController.java:27` 这类写法) + 🔴 `~/` 开头的按**绝对路径**处理(文档里直接写官方源码坐标)。 + """ + cands = [] + expanded = os.path.expanduser(cite_path) + if expanded.startswith("/"): + if os.path.isfile(expanded): + cands.append(("abs", expanded)) + return cands, "abs" + + for name, base in roots.items(): + p = os.path.join(base, cite_path) + if os.path.isfile(p): + cands.append((name, p)) + if cands: + return cands, "exact" + + suffix = "/" + cite_path + for name, base in roots.items(): + for rel, ap in indexes.get(name, {}).items(): + if rel.endswith(suffix): + cands.append((name, ap)) + if cands: + return cands, "suffix" + + if "/" not in cite_path: + for name, base in roots.items(): + for rel, ap in indexes.get(name, {}).items(): + if os.path.basename(rel) == cite_path: + cands.append((name, ap)) + if cands: + return cands, "basename" + return [], "none" + + +def judge(citation, roots, indexes): + """判定一条引文。返回 (状态, 解析结果, 说明)。 + + 状态:OK / RANGE_BAD(文件在但行号越界)/ UNRESOLVED(文件找不到) + """ + cands, tier = resolve(citation["path"], roots, indexes) + if not cands: + return "UNRESOLVED", [], "找不到文件" + fits = [] + for name, ap in cands: + lc = line_count(ap) + if all(start <= lc and (end is None or end <= lc) for start, end in citation["spans"]): + fits.append((name, ap)) + if fits: + return "OK", fits, tier + detail = "、".join( + "%s(%d 行)" % (os.path.relpath(ap, roots[name]), line_count(ap)) + for name, ap in cands[:3] + ) + return "RANGE_BAD", cands, detail + + +# ---------------------------------------------------------------- 检查项 + + +def check_citations(cites, roots, indexes, missing_roots): + """CIT1 可解析 / CIT2 行号有效。返回 (c1_status, c1_detail, c2_status, c2_detail, bad列表)。""" + unresolved = [] + bad_range = [] + for c in cites: + status, cands, detail = judge(c, roots, indexes) + c["status"] = status + c["detail"] = detail + if status == "UNRESOLVED": + unresolved.append(c) + elif status == "RANGE_BAD": + bad_range.append(c) + + # CIT1 —— 可解析 + if not unresolved: + c1_status, c1_detail = "OK", "%d 条引文全部定位到真实文件" % len(cites) + elif missing_roots: + c1_status = "SKIP" + c1_detail = "%d 条引文定位不到(外部参照根缺失:%s ⇒ 跳过,不判失败)" % ( + len(unresolved), "、".join(missing_roots)) + else: + c1_status = "DRIFT" + c1_detail = "%d 条引文定位不到文件:%s" % ( + len(unresolved), + ";".join("%s:%d → %s" % (os.path.basename(c["doc"]), c["doc_line"], c["path"]) + for c in unresolved[:6])) + + # CIT2 —— 行号有效 + if not bad_range: + c2_status, c2_detail = "OK", "%d 条引文的行号全部落在文件行数内" % len(cites) + else: + c2_status = "DRIFT" + c2_detail = "%d 条引文行号越界:%s" % ( + len(bad_range), + ";".join("%s:%d → %s(文件最多 %s 行)" % ( + os.path.basename(c["doc"]), c["doc_line"], c["path"], c["detail"]) + for c in bad_range[:6])) + return c1_status, c1_detail, c2_status, c2_detail, unresolved + bad_range + + +# 孤儿行号的「上文窗口」:文件通常在同一个小节 / 同一张表里被点名 +ORPHAN_WINDOW = 40 + + +def check_orphans(orphans, roots, indexes, mentions_by_doc): + """核对「孤儿行号」(`:NNN`)。 + + 🔴 **为什么不能简单「继承上文最近的文件名」**:同一张表里**相邻两行可能指的是不同文件** + (官方文档的表常在「官方出处」列里写 `前端 xxx.ts:14` 与 `XxxController.java:107-110` 混排) + ⇒ 机械继承会**大量误报**。 + + ⇒ 折中口径:取**上文 40 行内被点名过的所有文件**,只要**其中任意一个**的行数 + 覆盖得住这个行号 ⇒ 视为「对得上」(弱判据、低误报)。 + 一个都对不上 ⇒ 报「疑似漂移」(**只报不判失败**)。 + """ + checked = 0 + unresolved = 0 + suspects = [] + for o in orphans: + near = mentions_by_doc.get(o["doc"], []) + cands = [] + for (line, name) in near: + if not (o["doc_line"] - ORPHAN_WINDOW <= line <= o["doc_line"]): + continue + got, _ = resolve(name, roots, indexes) + cands.extend(got) + if not cands: + unresolved += 1 + continue + checked += 1 + if not any(o["line"] <= line_count(ap) for _, ap in cands): + suspects.append("%s:%d → 引用了第 %d 行,但上文 40 行内点名的文件最多只有 %d 行" % ( + os.path.basename(o["doc"]), o["doc_line"], o["line"], + max(line_count(ap) for _, ap in cands))) + return checked, unresolved, suspects + + +def check_ddl_table(root, ddl_path): + """CIT3 —— 文档里的 DDL 行号表 ↔ 官方 DDL 真实行。 + + 文档写「`base_authorize` | 812」⇒ 官方 DDL 第 812 行必须真的有 + `CREATE TABLE base_authorize` ⇒ 行号漂移(DDL 增删表)当场被抓。 + """ + claude = os.path.join(root, "CLAUDE.md") + if not os.path.isfile(claude): + return "SKIP", "仓根没有 CLAUDE.md" + if not os.path.isfile(ddl_path): + return "SKIP", "官方 DDL 不存在:%s" % ddl_path + with open(claude, "r", encoding="utf-8", errors="replace") as fh: + text = fh.read() + rows = DDL_ROW_RE.findall(text) + if not rows: + return "SKIP", "CLAUDE.md 里没有 DDL 行号表" + try: + with open(ddl_path, "r", encoding="utf-8", errors="replace") as fh: + ddl_lines = fh.readlines() + except OSError as exc: + return "SKIP", "读官方 DDL 失败:%s" % exc + + bad = [] + for name, num in rows: + n = int(num) + if n < 1 or n > len(ddl_lines): + bad.append("%s 标 %d 行(DDL 共 %d 行)" % (name, n, len(ddl_lines))) + continue + line = ddl_lines[n - 1] + if not re.search(DDL_CREATE_RE.format(name=re.escape(name)), line, re.I): + bad.append("%s 标 %d 行,但该行是「%s」" % (name, n, line.strip()[:60])) + if bad: + return "DRIFT", "DDL 行号漂移 %d 条:%s" % (len(bad), ";".join(bad)) + return "OK", "%d 条 DDL 行号与官方 DDL 逐行对上" % len(rows) + + +# ---------------------------------------------------------------- 反自证 + + +def self_test(): + """注入已知坏引文 ⇒ 必须被抓到。永远返回「干净」的尺子 = 没有尺子。""" + failures = [] + + tmpdir = tempfile.mkdtemp(prefix="cite-selftest-") + try: + # 造一份「干净」的文档 + 一个假源码文件 + src_dir = os.path.join(tmpdir, "src") + os.makedirs(src_dir) + code = os.path.join(src_dir, "demo.rs") + with open(code, "w", encoding="utf-8") as fh: + fh.write("\n".join("line%d" % i for i in range(1, 21)) + "\n") # 20 行 + doc = os.path.join(tmpdir, "doc.md") + with open(doc, "w", encoding="utf-8") as fh: + fh.write("见 `src/demo.rs:5` 与 `src/demo.rs:12-18`。\n") + + roots = {"tmp": tmpdir} + indexes = {"tmp": build_index(tmpdir)} + cites, _, _ = extract_citations([doc]) + c1, _, c2, _, bad = check_citations(cites, roots, indexes, []) + if c1 != "OK" or c2 != "OK" or bad: + failures.append("干净引文被误判(c1=%s c2=%s bad=%d)" % (c1, c2, len(bad))) + + # 注入 1:行号越界 + with open(doc, "w", encoding="utf-8") as fh: + fh.write("见 `src/demo.rs:999`。\n") + cites, _, _ = extract_citations([doc]) + _, _, c2, _, bad = check_citations(cites, roots, indexes, []) + if c2 != "DRIFT": + failures.append("行号越界没被抓到(c2=%s)" % c2) + + # 注入 2:文件不存在 + with open(doc, "w", encoding="utf-8") as fh: + fh.write("见 `src/nope.rs:3`。\n") + cites, _, _ = extract_citations([doc]) + c1, _, _, _, bad = check_citations(cites, roots, indexes, []) + if c1 != "DRIFT": + failures.append("文件不存在没被抓到(c1=%s)" % c1) + + # 注入 3:DDL 行号写错 + ddl = os.path.join(tmpdir, "ddl.sql") + with open(ddl, "w", encoding="utf-8") as fh: + fh.write("CREATE TABLE base_alpha (\n a int\n);\n") + claude = os.path.join(tmpdir, "CLAUDE.md") + with open(claude, "w", encoding="utf-8") as fh: + fh.write("| `base_alpha` | 1 | x |\n") + st, _ = check_ddl_table(tmpdir, ddl) + if st != "OK": + failures.append("正确 DDL 行号被误判(%s)" % st) + with open(claude, "w", encoding="utf-8") as fh: + fh.write("| `base_alpha` | 2 | x |\n") + st, _ = check_ddl_table(tmpdir, ddl) + if st != "DRIFT": + failures.append("DDL 行号错位没被抓到(%s)" % st) + finally: + shutil.rmtree(tmpdir, ignore_errors=True) + + if failures: + for f in failures: + print("SELFTEST-FAIL\t%s" % f) + return 1 + print("反自证通过:行号越界 / 文件缺失 / DDL 行号错位 三类坏引用都被抓到,干净引文不误报") + return 0 + + +# ---------------------------------------------------------------- 主流程 + + +def main(argv): + ap = argparse.ArgumentParser(description="文档引文(路径:行号)校验扫描器") + ap.add_argument("--root", default=ROOT, help="仓根(默认:本脚本所在仓)") + ap.add_argument("--jnpf", default=os.environ.get("JNPF_SRC_ROOT", DEFAULT_JNPF), + help="官方 JNPF 源码根") + ap.add_argument("--react", default=os.environ.get("REACT_SKILL_ROOT", DEFAULT_REACT), + help="react 姊妹技能根") + ap.add_argument("--ddl", default=os.environ.get("JNPF_DDL", DEFAULT_DDL), + help="官方 DDL 文件") + ap.add_argument("--cargo", default=os.environ.get("CARGO_SRC_ROOT", DEFAULT_CARGO), + help="cargo registry 的 src 目录(引文指到依赖源码时用)") + ap.add_argument("--list", action="store_true", help="打印每条引文明细") + ap.add_argument("--self-test", action="store_true", help="反自证模式") + args = ap.parse_args(argv) + + if args.self_test: + return self_test() + + root = os.path.abspath(args.root) + if not os.path.isdir(root): + print("❌ 仓根不存在:%s" % root) + return 2 + + roots = { + "repo": root, + "jnpf": os.path.abspath(os.path.expanduser(args.jnpf)), + "react": os.path.abspath(os.path.expanduser(args.react)), + } + # 依赖源码根(pglite-rs 的各版本)—— 文档里会引「某依赖的某一行」 + cargo_base = os.path.abspath(os.path.expanduser(args.cargo)) + if not os.path.isdir(cargo_base) and os.path.isdir(CARGO_FALLBACK): + cargo_base = CARGO_FALLBACK + for i, crate_root in enumerate(cargo_crate_roots(cargo_base)): + roots["cargo%d" % i] = crate_root + + missing_roots = [n for n, p in roots.items() if not os.path.isdir(p)] + indexes = {n: build_index(p) for n, p in roots.items() if os.path.isdir(p)} + + docs = collect_docs(root) + cites, orphans, mentions_by_doc = extract_citations(docs) + + c1, c1d, c2, c2d, bad = check_citations(cites, roots, indexes, missing_roots) + emit_check("CIT1", c1, c1d) + emit_check("CIT2", c2, c2d) + c3, c3d = check_ddl_table(root, os.path.abspath(os.path.expanduser(args.ddl))) + emit_check("CIT3", c3, c3d) + + o_checked, o_unresolved, o_suspects = check_orphans(orphans, roots, indexes, mentions_by_doc) + if orphans: + emit_warn("CIT-W1", "%d 处「无路径的续行行号」(`:NNN`,本仓的表格约定)—— " + "按上文最近的文件名继承核对:%d 处对得上,%d 处无法定位" % ( + len(orphans), o_checked, o_unresolved)) + for s in o_suspects[:8]: + emit_warn("CIT-W1", "疑似漂移:%s" % s) + if missing_roots: + emit_warn("CIT-W2", "外部参照根缺失:%s ⇒ 指向它们的引文按「跳过」处理" + % "、".join("%s=%s" % (n, roots[n]) for n in missing_roots)) + + if args.list: + print("---- 引文明细 ----") + for c in cites: + print("%s:%d\t%s:%s\t%s\t%s" % ( + os.path.relpath(c["doc"], root), c["doc_line"], c["path"], c["body"], + c.get("status", "?"), c.get("detail", ""))) + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/scripts/check-citations.sh b/scripts/check-citations.sh new file mode 100644 index 0000000..c24a6ea --- /dev/null +++ b/scripts/check-citations.sh @@ -0,0 +1,150 @@ +#!/usr/bin/env bash +# ssw-platform 引文校验尺子 —— 文档里的「路径:行号」是否还指得到真东西 +# +# 目的:本仓的文档(SKILL / README / MIGRATION / JNPF_SOURCE_AUDIT / PERMISSION …) +# 大量引用源码位置 `文件.ext:行号`。这些行号**会漂移**:源码改一行 ⇒ +# 上游行号整体位移 ⇒ 文档里的引用**静默指向别的行**——不报错,只是悄悄说错话。 +# 本尺子把每条引文**解析到真实文件**并核对行号区间;顺带核对 +# 「文档里的 DDL 行号表 ↔ 官方 DDL 真实行」。 +# +# 🔴 **纯静态**:不启动后端、不发请求、不连库。只需要 `python3`(macOS 自带)。 +# +# 用法: +# bash scripts/check-citations.sh # 无参 ⇒ 全查 +# bash scripts/check-citations.sh --list # 顺带打印每条引文明细 +# bash scripts/check-citations.sh --help +# +# 退出码:0 全过 / 1 有 ❌ 项 / 2 用法错或前置错误 +# +# ── 判据(CIT1–CIT3)── +# CIT1 引文**可解析**:每条 `路径:行号` 都能定位到真实文件 +# CIT2 引文**行号有效**:行号区间落在该文件的行数范围内 +# CIT3 **DDL 行号表**对账:文档写的建表行号 ↔ 官方 DDL 那一行真的有 `CREATE TABLE` +# CIT1' **反自证**:注入已知坏引用 ⇒ 必须被抓到(永远返回「干净」的尺子 = 没有尺子) +# +# 🔴 **期望值来自 `docs/contract.md` 附录 A 的 `[RULER]`**(条数由契约钉死)。 + +set -u + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +SCRIPTS="$ROOT/scripts" +SCAN="$SCRIPTS/check-citations-scan.py" +CE_PY="$SCRIPTS/contract_expect.py" +CONTRACT="$ROOT/docs/contract.md" + +usage() { + echo "用法: bash scripts/check-citations.sh [--list]" + echo " 静态校验文档里的「路径:行号」引文是否还指得到真东西" + echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错或前置错误" +} + +LIST="" +while [ "$#" -gt 0 ]; do + case "$1" in + -h|--help) usage; exit 0 ;; + --list) LIST="--list"; shift ;; + *) echo "❌ 未知参数: $1"; usage; exit 2 ;; + esac +done + +# ---- 前置:python3 / 扫描器 / 契约文件 ---- +PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}" +if [ -z "${PY_BIN}" ]; then + echo "❌ 找不到 python3(扫描器需要它)" + exit 2 +fi +if [ ! -f "${SCAN}" ]; then + echo "❌ 缺扫描器: ${SCAN}" + exit 2 +fi +if [ ! -f "${CE_PY}" ] || [ ! -f "${CONTRACT}" ]; then + echo "❌ 缺契约期望值读取器或契约文件(docs/contract.md 附录 A)" + exit 2 +fi + +# ---- 契约期望值(唯一真源:docs/contract.md 附录 A)---- +CE_RULER_ROWS="$("${PY_BIN}" "${CE_PY}" rows RULER 2>/dev/null)" || CE_RULER_ROWS="" +if [ -z "${CE_RULER_ROWS}" ]; then + echo "❌ 读契约期望值失败(docs/contract.md 附录 A 是不是被改坏了?)" + exit 2 +fi +CE_EXP_ASSERTIONS="$(printf '%s\n' "${CE_RULER_ROWS}" | awk -F'\t' '$1=="check-citations.sh" { print $2; exit }')" + +PASS=0; FAIL=0 +ok() { echo " ✅ $1"; PASS=$((PASS+1)); } +no() { echo " ❌ $1"; FAIL=$((FAIL+1)); } +skip(){ echo " ⏭ $1"; PASS=$((PASS+1)); } # 外部参照根缺失 ⇒ 跳过但仍计入条数 +hdr() { echo; echo "── $1 ──"; } + +# ---- 跑扫描器 ---- +SCAN_OUT="$("${PY_BIN}" "${SCAN}" --root "${ROOT}" ${LIST} 2>&1)" +SCAN_RC=$? +if [ "${SCAN_RC}" -eq 2 ]; then + echo "❌ 扫描器前置失败:" + printf '%s\n' "${SCAN_OUT}" | sed 's/^/ /' + exit 2 +fi + +hdr "[CIT1–CIT3] 文档引文(路径:行号)逐条核对" +DRIFT_LINES="" +while IFS=$'\t' read -r kind f1 f2 f3; do + [ -z "${kind:-}" ] && continue + case "${kind}" in + CHECK) + case "${f2}" in + OK) ok "${f1}:${f3}" ;; + SKIP) skip "${f1}:${f3}" ;; + *) no "${f1}:${f3}" ;; + esac + ;; + WARN) + # WARN 行只有 3 列(kind / id / 说明)⇒ 说明在 f2 + if [ -n "${f3:-}" ]; then + DRIFT_LINES="${DRIFT_LINES}${f1}:${f3}"$'\n' + else + DRIFT_LINES="${DRIFT_LINES}${f1}:${f2}"$'\n' + fi + ;; + esac +done <<< "${SCAN_OUT}" + +if [ -n "${DRIFT_LINES}" ]; then + hdr "提示" + printf '%s' "${DRIFT_LINES}" | sed 's/^/ ⚠️ /' +fi + +# ---- CIT1' 反自证:尺子自己必须能抓到坏引用 ---- +hdr "[CIT1'] 扫描器反自证(--self-test 必须过)" +SELFTEST_OUT="$("${PY_BIN}" "${SCAN}" --self-test 2>&1)" +if [ "$?" -eq 0 ]; then + ok "扫描器自证通过:${SELFTEST_OUT}" +else + no "扫描器自证失败:${SELFTEST_OUT}" +fi + +# -------- 尺子自证:跑出来的条数必须等于契约里登记的条数 -------- +hdr "[自证] 尺子条数与契约登记一致" +if [ -n "${CE_EXP_ASSERTIONS}" ]; then + CE_ACT_ASSERTIONS=$((PASS + FAIL)) + if [ "${CE_ACT_ASSERTIONS}" -eq "${CE_EXP_ASSERTIONS}" ]; then + echo " ✅ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言 = 契约登记的 ${CE_EXP_ASSERTIONS} 条" + else + echo " ❌ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言,契约登记 ${CE_EXP_ASSERTIONS} 条 ⇒ 尺子被改弱了(少了/多了断言)" + FAIL=$((FAIL + 1)) + fi +else + echo " ❌ 契约 [RULER] 里没有登记 check-citations.sh 的期望条数" + FAIL=$((FAIL + 1)) +fi + +# -------- 总结 -------- +echo +echo "── 总结 ──" +echo "PASS=${PASS} FAIL=${FAIL}" +if [ "${FAIL}" -eq 0 ]; then + echo "全 ✅ 文档引文没漂移" +else + echo "有 ❌,请按上面修复(改文档里的行号 ⇒ 跟着源码一起改)" +fi + +exit $([ "${FAIL}" -eq 0 ] && echo 0 || echo 1) diff --git a/scripts/check-contract-scan.py b/scripts/check-contract-scan.py new file mode 100644 index 0000000..f9aa49a --- /dev/null +++ b/scripts/check-contract-scan.py @@ -0,0 +1,756 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""check-contract-scan —— **契约 ↔ 代码** 对账扫描器。 + +🔴 为什么存在: + `docs/contract.md` 的端点表原先是**散文表格**(§6.1–§6.5), + 代码里的路由注册是**另一处**(`routes.rs` / `modules/*.rs`)⇒ + 加端点、改路径、改守卫 ⇒ 契约与代码**各改各的** ⇒ 漂移没人发现。 + 本脚本把契约的机器可读区段 `[ENDPOINT]` / `[FACE]` 与**代码里真实注册的路由** + 逐条对账,**双向**都查(契约多 / 代码多 / 方法不符 / 归属层不符 / 守卫不符)。 + +🔴 **只做静态检查**:不启动后端、不发请求。纯 `python3`(macOS 自带)。 + +用法: + check-contract-scan.py --contract <契约文件> --src <后端 src 目录> + check-contract-scan.py --self-test + +输出协议(制表符分隔,逐行一条): + CHECK\t\t\t<说明> + WARN\t\t<说明> # 推不出守卫之类的「非失败但要看见」 + +退出码:0 = 扫完(可能有 DRIFT,看输出)/ 2 = 致命错误(契约读不出来等) +""" + +import io +import os +import re +import shutil +import sys +import tempfile + +HERE = os.path.dirname(os.path.abspath(__file__)) +ROOT = os.path.dirname(HERE) +if HERE not in sys.path: + sys.path.insert(0, HERE) + +import contract_expect # noqa: E402 (同目录) + +# ---------------------------------------------------------------- Rust 源码扫描 + +# 路由注册:`.route("/api/x", get(handler))`(允许跨行) +# 🔴 路径是**字符串字面量** ⇒ 在 masked 里是空白 ⇒ 只在 masked 里定位 `.route(`, +# 再用**同一偏移**去原文取路径与方法。 +ROUTE_CALL_RE = re.compile(r'\.route\(') +# 路由后面的 handler 表达式:`sys::user_list` / `demo_item_list` / `|State(..)| ..`(闭包) +HANDLER_RE = re.compile(r'\s*(?:([A-Za-z_][A-Za-z0-9_]*)::)?([A-Za-z_][A-Za-z0-9_]*)') +# 契约表里 `{param}` ⇒ 代码里的通配 +PARAM_RE = re.compile(r'\{[A-Za-z_][A-Za-z0-9_]*\}') +# 测试用的固定路径前缀(**不在契约端点表里** ⇒ 全部扫描都排除) +TEST_PATH_PREFIX = "/api/__test__/" + + +def mask_rust(text): + """把字符串字面量 / 注释**挖空**(保持长度不变)⇒ 结构扫描不会被注释/字面量骗。 + + 挖空后拿到的偏移量与原文一一对应 ⇒ 需要字面量的值时,用同一偏移去原文里取。 + """ + out = list(text) + n = len(text) + + def blank(a, b): + for k in range(a, b): + if out[k] != "\n": + out[k] = " " + + i = 0 + while i < n: + c = text[i] + if c == "/" and i + 1 < n and text[i + 1] == "/": + j = text.find("\n", i) + j = n if j < 0 else j + blank(i, j) + i = j + continue + if c == "/" and i + 1 < n and text[i + 1] == "*": + depth, j = 1, i + 2 + while j < n and depth: + if text.startswith("/*", j): + depth += 1 + j += 2 + elif text.startswith("*/", j): + depth -= 1 + j += 2 + else: + j += 1 + blank(i, j) + i = j + continue + if c == "r" and i + 1 < n and text[i + 1] in '#"': + m = re.match(r'r(#*)"', text[i:]) + if m: + hashes = m.group(1) + end = text.find('"' + hashes, i + m.end()) + j = n if end < 0 else end + 1 + len(hashes) + blank(i, j) + i = j + continue + if c == '"': + j = i + 1 + while j < n: + if text[j] == "\\": + j += 2 + continue + if text[j] == '"': + j += 1 + break + j += 1 + blank(i, j) + i = j + continue + if c == "'": + m = re.match(r"'(\\.|[^\\'])'", text[i:]) + if m: + blank(i, i + m.end()) + i += m.end() + continue + i += 1 # 生命周期(`'a`)不是字面量 ⇒ 留着 + continue + i += 1 + return "".join(out) + + +def read(path): + with io.open(path, encoding="utf-8") as fh: + return fh.read() + + +def brace_span(masked, start): + """从 `start`(`{` 的位置)开始做括号配对 ⇒ 返回 body 的 (开, 闭) 区间。""" + depth = 0 + i = start + n = len(masked) + while i < n: + c = masked[i] + if c == "{": + depth += 1 + elif c == "}": + depth -= 1 + if depth == 0: + return start, i + 1 + i += 1 + return start, n + + +def find_fn_body(masked, fname): + """找 `fn (` 的函数体区间 ⇒ 返回 (start, end) 或 None。""" + m = re.search(r"\bfn\s+" + re.escape(fname) + r"\s*\(", masked) + if not m: + return None + i = masked.find("{", m.end()) + if i < 0: + return None + return brace_span(masked, i) + + +def scan_routes(path, owner): + """扫一个源文件里的 `.route(...)` ⇒ [{path, method, handler_mod, handler_fn, closure}]。""" + orig = read(path) + masked = mask_rust(orig) + out = [] + for m in ROUTE_CALL_RE.finditer(masked): + p = m.end() + while p < len(orig) and orig[p] in " \t\r\n": + p += 1 + if p >= len(orig) or orig[p] != '"': + continue + q = p + 1 + while q < len(orig) and orig[q] != '"': + if orig[q] == "\\": + q += 1 + q += 1 + if q >= len(orig): + continue + route = orig[p + 1:q] + p = q + 1 + while p < len(orig) and orig[p] in " \t\r\n": + p += 1 + if p < len(orig) and orig[p] == ",": + p += 1 + while p < len(orig) and orig[p] in " \t\r\n": + p += 1 + mm = re.match(r"(get|post|put|delete)\s*\(", orig[p:]) + if not mm: + continue + if masked[p:p + len(mm.group(1))] != mm.group(1): + continue # 方法名其实落在字符串里(误报) + method = mm.group(1).upper() + after = p + mm.end() + if route.startswith(TEST_PATH_PREFIX): + continue # 仅测试构建存在的端点 ⇒ 不在契约端点表里 + rest = orig[after:after + 240] + hm = HANDLER_RE.match(rest) + mod, fn, closure = None, None, True + if hm and hm.group(2): + mod, fn = hm.group(1), hm.group(2) + closure = False + out.append({ + "path": route, + "method": method, + "mod": mod, + "fn": fn, + "closure": closure, + "owner": owner, + "file": path, + }) + return out, orig, masked + + +def resolve_const(orig, masked, name): + """`const NAME: &str = "value";` ⇒ value(取原文里的字面量)。""" + m = re.search(r"\bconst\s+" + re.escape(name) + r"\b[^=]*=\s*\"([^\"]*)\"", orig) + return m.group(1) if m else None + + +def guard_of_platform(plat_files, mod, fn): + """平台层 handler 的守卫 ⇒ 菜单 key / 点权限编码 / 登录 / 无;推不出 ⇒ None。 + + `plat_files` = {"sys": (orig, masked), "jnpf": (orig, masked), ...} + """ + if mod == "auth" and fn == "login_handler": + return "无" + if mod is None: + # routes.rs 里自己定义的 handler(如 `health`)⇒ 没有守卫调用 ⇒ 无 + pair = plat_files.get("__routes__") + if not pair: + return None + orig, masked = pair + span = find_fn_body(masked, fn) + if not span: + return None + body = masked[span[0]:span[1]] + if re.search(r"require_(login|module|login_jnpf)\s*\(", body) or re.search(r"\bguard\s*\(", body): + return None + return "无" + pair = plat_files.get(mod) + if not pair: + return None + orig, masked = pair + span = find_fn_body(masked, fn) + if not span: + return None + body = masked[span[0]:span[1]] + if mod == "sys": + m = re.search(r"require_module\(\s*&state\s*,\s*&headers\s*,\s*([A-Z_][A-Z0-9_]*)\s*\)", body) + if m: + return resolve_const(orig, masked, m.group(1)) + if re.search(r"require_login(_any)?\s*\(", body): + return "登录" + return None + if mod == "jnpf": + m = re.search(r"guard\(\s*&state\s*,\s*&headers\s*,\s*([A-Z_][A-Z0-9_]*)\s*\)", body) + if m: + return resolve_const(orig, masked, m.group(1)) + if re.search(r"require_login_jnpf\s*\(", body): + return "登录" + return None + return None + + +def guard_of_closure(orig, masked, rest): + """闭包 handler(只有 `CurrentUser` 一处)⇒ 看它调了谁。""" + if "auth::current_user" in rest: + return "登录" + return None + + +def guard_of_module(orig, masked): + """业务模块的守卫 ⇒ 它的 `EntitySpec.module_key`(None ⇒ 仅登录)。 + + 🔴 在 **masked** 里定位 `module_key:`(注释里的假 mention 被挖空了), + 再用**同一偏移**去原文取真值(字面量在 masked 里是空格)。 + """ + for m in re.finditer(r"module_key:", masked): + tail = orig[m.end():m.end() + 60] + if re.match(r"\s*None", tail): + return "登录" + mm = re.match(r'\s*Some\(\s*"([^"]*)"\s*\)', tail) + if mm: + return mm.group(1) + return None + + +def parse_str_array(orig, masked, decl_re): + """从 `const X: [&str; N] = [ "a", "b" ];` 里取字符串数组(原文字面量)。""" + m = re.search(decl_re, masked) + if not m: + return None + i = masked.find("[", m.end()) + if i < 0: + return None + j = masked.find("]", i) + if j < 0: + return None + return re.findall(r'"([^"]*)"', orig[i:j]) + + +def path_to_regex(pattern): + """`/a/{id}/b` ⇒ 正则(`{id}` 当通配)⇒ 用来对钉子测试里的具体路径。""" + parts = [] + last = 0 + for m in PARAM_RE.finditer(pattern): + parts.append(re.escape(pattern[last:m.start()])) + parts.append("[^/]+") + last = m.end() + parts.append(re.escape(pattern[last:])) + return re.compile("^" + "".join(parts) + "$") + + +# ---------------------------------------------------------------- 对账 + +class Report(object): + def __init__(self): + self.checks = [] + self.warns = [] + self.infos = [] + + def add(self, cid, ok, detail): + self.checks.append((cid, "OK" if ok else "DRIFT", detail)) + + def warn(self, cid, detail): + self.warns.append((cid, detail)) + + def info(self, cid, detail): + """**不计入 PASS/FAIL** 的进度信息(例:官方端点覆盖 N/M)。""" + self.infos.append((cid, detail)) + + def lines(self): + out = [] + for cid, status, detail in self.checks: + out.append("CHECK\t%s\t%s\t%s" % (cid, status, detail.replace("\t", " "))) + for cid, detail in self.warns: + out.append("WARN\t%s\t%s" % (cid, detail.replace("\t", " "))) + for cid, detail in self.infos: + out.append("INFO\t%s\t%s" % (cid, detail.replace("\t", " "))) + return out + + +def analyze(contract_path, src_dir): + """契约 ↔ 代码 对账主体。返回 (Report, 诊断用数据)。""" + rep = Report() + + sections = contract_expect.load_sections(contract_path) + eps = sections["ENDPOINT"] + faces = sections["FACE"] + + # ---- 代码侧:平台层 + 业务层 ---- + routes_path = os.path.join(src_dir, "routes.rs") + plat, plat_orig, plat_masked = scan_routes(routes_path, "platform") + + plat_dir = os.path.join(src_dir, "platform") + plat_files = {"__routes__": (plat_orig, plat_masked)} + if os.path.isdir(plat_dir): + for name in sorted(os.listdir(plat_dir)): + if name.endswith(".rs"): + p = os.path.join(plat_dir, name) + o = read(p) + plat_files[name[:-3]] = (o, mask_rust(o)) + + mod_dir = os.path.join(src_dir, "modules") + mod_files = [] + if os.path.isdir(mod_dir): + for name in sorted(os.listdir(mod_dir)): + if name.endswith(".rs") and name != "mod.rs": + mod_files.append((name[:-3], os.path.join(mod_dir, name))) + biz = [] + mod_orig = {} + mod_masked = {} + for app, path in mod_files: + rs, orig, masked = scan_routes(path, app) + biz.extend(rs) + mod_orig[app] = orig + mod_masked[app] = masked + code = plat + biz + + code_index = {} + for r in code: + code_index.setdefault((r["method"], r["path"]), r) + + # ---- CC2 端点总数 ---- + ok = len(eps) == len(code) + rep.add("CC2", ok, "契约 %d 条 / 代码 %d 条" % (len(eps), len(code))) + + # ---- CC3 契约 → 代码(存在 + 方法一致)---- + bad3 = [] + for row in eps: + key = (row["method"], row["path"]) + if key in code_index: + continue + other = [k for k in code_index if k[1] == row["path"]] + if other: + bad3.append("%s %s:契约方法 %s,代码是 %s" + % (row["method"], row["path"], row["method"], "/".join(k[0] for k in other))) + else: + bad3.append("%s %s:代码里没有这条路由" % (row["method"], row["path"])) + rep.add("CC3", not bad3, + "契约的 %d 条端点在代码里都能找到(且方法一致)" % len(eps) + if not bad3 else "契约→代码 漂移 %d 条" % len(bad3)) + for d in bad3: + rep.warn("CC3", d) + + # ---- CC4 代码 → 契约(代码多出来的)---- + bad4 = [] + for r in code: + if (r["method"], r["path"]) not in {(x["method"], x["path"]) for x in eps}: + bad4.append("%s %s(%s)" % (r["method"], r["path"], r["owner"])) + rep.add("CC4", not bad4, + "代码里的 %d 条路由都在契约端点表里" % len(code) + if not bad4 else "代码→契约 漂移 %d 条" % len(bad4)) + for d in bad4: + rep.warn("CC4", d) + + # ---- CC5 归属层 ---- + bad5 = [] + for row in eps: + hit = code_index.get((row["method"], row["path"])) + if hit and hit["owner"] != row["owner"]: + bad5.append("%s %s:契约写 %s,代码在 %s" % (row["method"], row["path"], row["owner"], hit["owner"])) + rep.add("CC5", not bad5, + "每条端点的归属层与代码所在文件一致" if not bad5 else "归属层漂移 %d 条" % len(bad5)) + for d in bad5: + rep.warn("CC5", d) + + # ---- CC6 守卫 ---- + bad6 = [] + unknown6 = [] + for row in eps: + hit = code_index.get((row["method"], row["path"])) + if not hit: + continue + derived = None + if hit["owner"] == "platform": + if hit["closure"]: + tail = plat_orig[plat_orig.find(hit["path"]):][:400] + derived = guard_of_closure(plat_orig, plat_masked, tail) + else: + derived = guard_of_platform(plat_files, hit["mod"], hit["fn"]) + else: + derived = guard_of_module(mod_orig[hit["owner"]], mod_masked[hit["owner"]]) + if derived is None: + unknown6.append("%s %s:推不出守卫" % (row["method"], row["path"])) + elif derived != row["guard"]: + bad6.append("%s %s:契约写 %s,代码是 %s" + % (row["method"], row["path"], row["guard"], derived)) + rep.add("CC6", not bad6, + "每条端点的守卫与代码静态推导一致" if not bad6 else "守卫漂移 %d 条" % len(bad6)) + for d in bad6: + rep.warn("CC6", d) + for d in unknown6: + rep.warn("CC6", d + "(**推不出 ≠ 一致**,请人工核对)") + + # ---- CC7 钉子测试清单 ↔ 代码注册路由(双向覆盖)---- + pins = [] + for name in ("REGISTERED", "JNPF_REGISTERED"): + arr = parse_str_array(plat_orig, plat_masked, + r"const\s+" + name + r"\s*:\s*\[&str;\s*\d+\]\s*=") + if arr is not None: + pins.extend(arr) + # 🔴 钉子测试的**字面量清单**(`REGISTERED` / `JNPF_REGISTERED`)只覆盖**平台层**路由; + # 业务路由在钉子测试里是**遍历 `modules::ALL_ROUTES`** ⇒ 归 CC8 对账。 + plat_routes = [r for r in code if r["owner"] == "platform"] + unmatched_pin = [] + for p in pins: + if not any(path_to_regex(r["path"]).match(p) for r in plat_routes): + unmatched_pin.append(p) + unmatched_code = [] + for r in plat_routes: + if not any(path_to_regex(r["path"]).match(p) for p in pins): + unmatched_code.append("%s %s" % (r["method"], r["path"])) + ok7 = not unmatched_pin and not unmatched_code + rep.add("CC7", ok7, + "钉子测试的 %d 条路径与代码注册的 %d 条平台路由双向覆盖" % (len(pins), len(plat_routes)) + if ok7 else "钉子测试清单与代码路由对不上:清单多 %d / 代码多 %d" + % (len(unmatched_pin), len(unmatched_code))) + for d in unmatched_pin: + rep.warn("CC7", "钉子测试里的 %s 在代码里没有对应路由" % d) + for d in unmatched_code: + rep.warn("CC7", "代码里的 %s 没被钉子测试覆盖" % d) + + # ---- CC8 业务路由三处一致(ROUTES 常量 / router() / ALL_ROUTES)---- + bad8 = [] + all_routes = [] + for app, path in mod_files: + orig, masked = mod_orig[app], mod_masked[app] + const = parse_str_array(orig, masked, r"pub\s+const\s+ROUTES\s*:\s*\[&str;\s*\d+\]\s*=") + rs = [r for r in biz if r["owner"] == app] + reg = [r["path"] for r in rs] + if const is None: + bad8.append("%s:没有 ROUTES 常量" % app) + continue + if const != reg: + bad8.append("%s:ROUTES 常量 %s ≠ router() 注册 %s" % (app, const, reg)) + all_routes.extend(const) + # modules/mod.rs 的 ALL_ROUTES(形如 demo::ROUTES[0])⇒ 解析成具体路径 + mod_mod = os.path.join(mod_dir, "mod.rs") + if os.path.isfile(mod_mod): + orig = read(mod_mod) + masked = mask_rust(orig) + m = re.search(r"pub\s+const\s+ALL_ROUTES\s*:\s*&\[&str\]\s*=\s*&\[", masked) + if m: + # 🔴 数组本体是 `&[ ... ]` ⇒ 要**配对**找结尾的 `]`(不能 find 第一个 `]`) + open_at = masked.find("[", m.end() - 1) + depth = 0 + close_at = -1 + for k in range(open_at, len(masked)): + if masked[k] == "[": + depth += 1 + elif masked[k] == "]": + depth -= 1 + if depth == 0: + close_at = k + break + entries = re.findall(r"([a-z_]+)::ROUTES\[(\d+)\]", orig[open_at:close_at]) + resolved = [] + for app, idx in entries: + pair = (mod_orig.get(app, ""), mod_masked.get(app, "")) + c = parse_str_array(pair[0], pair[1], + r"pub\s+const\s+ROUTES\s*:\s*\[&str;\s*\d+\]\s*=") + if c and int(idx) < len(c): + resolved.append(c[int(idx)]) + # 🔴 比**集合**不比你序(`mod_files` 是按文件名排序的,ALL_ROUTES 是按声明序的) + if sorted(resolved) != sorted(all_routes): + bad8.append("modules/mod.rs 的 ALL_ROUTES %s ≠ 各模块 ROUTES 拼接 %s" + % (sorted(resolved), sorted(all_routes))) + else: + bad8.append("modules/mod.rs 里找不到 ALL_ROUTES") + rep.add("CC8", not bad8, + "业务路由三处一致(各模块 ROUTES 常量 / router() 注册 / ALL_ROUTES)" + if not bad8 else "业务路由清单对不上 %d 处" % len(bad8)) + for d in bad8: + rep.warn("CC8", d) + + # ---- CC9 契约面计数自洽 ---- + bad9 = [] + for row in faces: + actual = sum(1 for e in eps if e["face"] == row["face"]) + if str(actual) != row["count"]: + bad9.append("面 %s:契约 [FACE] 登记 %s 条,[ENDPOINT] 里实际 %d 条" + % (row["face"], row["count"], actual)) + total_face = sum(int(r["count"]) for r in faces) + if total_face != len(eps): + bad9.append("[FACE] 合计 %d ≠ [ENDPOINT] 行数 %d" % (total_face, len(eps))) + rep.add("CC9", not bad9, + "各契约面的条数与 [ENDPOINT] 自洽(A/B/AB 合计 %d)" % total_face + if not bad9 else "契约面计数不自洽 %d 处" % len(bad9)) + for d in bad9: + rep.warn("CC9", d) + + # ---- CC10 官方端点台账 ↔ 代码真实路由(双向)---- + # + # 🔴 为什么要它:面 B 的「做了多少」原先只有**尺子的断言数**(18/18)这一个信号, + # 而**官方端点全表**(JNPF_SOURCE_AUDIT.md §4)是**散文表格** ⇒ 官方端点做没做、 + # 做到什么程度,**没有机器可读的账** ⇒ 「覆盖率」只能靠人读散文。 + # 本检查把契约附录 A 的 [OFFICIAL](机器可读)当成**账本**, + # 与代码里**真实注册**的路由双向对账,并打印覆盖 N/M。 + off = sections["OFFICIAL"] + + def norm_path(p): + # `{param}` 归一 ⇒ 官方台账与代码的**参数名不同**也不算漂移 + return re.sub(r"\{[^/{}]*\}", "{}", p) + + code_norm = {} + for r in code: + code_norm.setdefault((r["method"], norm_path(r["path"])), r) + eps_face = {} + for e in eps: + eps_face[(e["method"], norm_path(e["path"]))] = e["face"] + + bad10 = [] + counts = {"implemented": 0, "partial": 0, "absent": 0, "oos": 0} + for row in off: + method, path, status = row["method"], row["path"], row["status"] + if status not in counts: + bad10.append("台账状态非法 %r(%s %s)" % (status, method, path)) + continue + if method == "*" or path.endswith("/**"): + # 「一族端点」的范围声明(如数据权限链接)⇒ 不做存在性对账,只计入 oos + counts["oos"] += 1 + continue + hit = code_norm.get((method, norm_path(path))) + if status in ("implemented", "partial"): + counts[status] += 1 + if hit is None: + bad10.append("台账写 %s(%s %s),代码里**没有**这条路由" % (status, method, path)) + else: + counts[status] += 1 + if hit is not None: + bad10.append("台账写 %s(%s %s),代码里却**注册了**这条路由" % (status, method, path)) + # 反向:代码里**面 B / 共用**的每条路由,都必须在台账里**有账**(防止"实现了但没记账") + off_index = set((r["method"], norm_path(r["path"])) for r in off if r["method"] != "*") + for r in code: + key = (r["method"], norm_path(r["path"])) + if eps_face.get(key) in ("B", "AB") and key not in off_index: + bad10.append("代码注册了面 %s 路由 %s %s,但官方端点台账里**没有这一条**" + % (eps_face.get(key), r["method"], r["path"])) + covered = counts["implemented"] + counts["partial"] + total = covered + counts["absent"] + rep.add("CC10", not bad10, + "官方端点台账与代码真实路由双向对得上(已落地 %d / 在范围 %d)" % (covered, total) + if not bad10 else "官方端点台账漂移 %d 处" % len(bad10)) + for d in bad10: + rep.warn("CC10", d) + rep.info("CC10-COVER", + "官方端点覆盖 %d/%d(implemented %d / partial %d / absent %d;oos %d 单列,不进分母)" + % (covered, total, counts["implemented"], counts["partial"], + counts["absent"], counts["oos"])) + + return rep + + +# ---------------------------------------------------------------- 反自证 + +def self_test(): + """🔴 **反自证**:造几种已知漂移 ⇒ 必须被抓到;再验一遍真实契约**没有**漂移。 + + 永远返回「干净」的尺子 = 没有尺子 ⇒ 这一段是尺子可信的前提。 + """ + contract = os.path.join(ROOT, "docs", "contract.md") + src_dir = os.path.join(ROOT, "src", "backend", "src") + if not os.path.isfile(contract): + sys.stderr.write("check-contract-scan: 找不到契约 %s\n" % contract) + return 2 + + base = analyze(contract, src_dir) + drifts = [c for c in base.checks if c[1] == "DRIFT"] + if drifts: + for cid, _s, detail in drifts: + sys.stderr.write("check-contract-scan: 真实契约就有漂移(%s: %s)\n" % (cid, detail)) + return 1 + + with io.open(contract, encoding="utf-8") as fh: + text = fh.read() + + def mutate(fn): + return fn(text) + + cases = [] + + def add_row(t): + return t.replace("[ENDPOINT]\n", "[ENDPOINT]\nA\tGET\t/api/zzz/Fake/List\t登录\tplatform\n", 1) + + def drop_row(t): + return t.replace("A\tGET\t/api/health\t无\tplatform\n", "", 1) + + def bad_method(t): + return t.replace("A\tGET\t/api/health\t无\tplatform\n", + "A\tPOST\t/api/health\t无\tplatform\n", 1) + + def bad_guard(t): + return t.replace("A\tGET\t/api/ssw/sys/User/List\tsystem/User\tplatform\n", + "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) + + def bad_face(t): + # 🔴 **动态取现值再减 1**(别写死数字):加端点会让 [FACE] 的 A 条数变化, + # 写死的锚点会过期 ⇒ 反自证用例静默失效(「改不动契约」)。 + m = re.search(r"(?m)^A\t(\d+)\t", t) + if not m: + return t + return t[: m.start(1)] + str(int(m.group(1)) - 1) + t[m.end(1):] + + # ---- CC10 的三类漂移(官方端点台账 ↔ 代码真实路由)---- + def off_says_absent(t): + # 台账把「代码里有」的端点说成未实现 + return t.replace( + "GET\t/api/permission/Users\timplemented\t", + "GET\t/api/permission/Users\tabsent\t", 1) + + def off_fake_path(t): + # 台账说已实现,但那条路径代码里根本没有 + return t.replace( + "GET\t/api/system/Menu/ModuleBySystem\timplemented\t", + "GET\t/api/system/Menu/ModuleBySystemXX\timplemented\t", 1) + + def off_drop_row(t): + # 代码里有面 B 路由,但台账里没记账("实现了但没记账") + return t.replace( + "GET\t/api/permission/Role\timplemented\tRoleController.java:99-100\t" + "面 B 已落地:PageListVO 形状\n", "", 1) + + cases.append(("契约多一条端点", add_row, "CC3")) + cases.append(("契约少一条端点", drop_row, "CC2")) + cases.append(("方法写错", bad_method, "CC3")) + cases.append(("守卫写错", bad_guard, "CC6")) + cases.append(("归属层写错", bad_owner, "CC5")) + cases.append(("契约面计数写错", bad_face, "CC9")) + cases.append(("台账把已实现的端点说成未实现", off_says_absent, "CC10")) + cases.append(("台账写了代码里没有的端点", off_fake_path, "CC10")) + cases.append(("面 B 路由没记账", off_drop_row, "CC10")) + + failed = 0 + for name, fn, expect in cases: + mutated = mutate(fn) + if mutated == text: + sys.stderr.write("check-contract-scan: 反自证用例「%s」改不动契约(锚点没了)\n" % name) + failed += 1 + continue + tmpdir = tempfile.mkdtemp(prefix="cc-selftest-") + tmp = os.path.join(tmpdir, "contract.md") + with io.open(tmp, "w", encoding="utf-8") as fh: + fh.write(mutated) + try: + rep = analyze(tmp, src_dir) + except Exception as exc: # noqa: BLE001 + sys.stderr.write("check-contract-scan: 反自证用例「%s」分析异常:%s\n" % (name, exc)) + failed += 1 + continue + finally: + shutil.rmtree(tmpdir, ignore_errors=True) + hit = [c for c in rep.checks if c[0] == expect and c[1] == "DRIFT"] + if hit: + print(" ✅ 反自证「%s」被 %s 抓到" % (name, expect)) + else: + print(" ❌ 反自证「%s」**没**被 %s 抓到(尺子被改弱了?)" % (name, expect)) + failed += 1 + + if failed: + sys.stderr.write("check-contract-scan: 反自证失败 %d 例\n" % failed) + return 1 + print("反自证 %d 例全部通过(真实契约零漂移 + 每种注入漂移都被抓到)" % len(cases)) + return 0 + + +def main(argv): + if "--self-test" in argv: + return self_test() + + contract = os.path.join(ROOT, "docs", "contract.md") + src_dir = os.path.join(ROOT, "src", "backend", "src") + i = 1 + while i < len(argv): + if argv[i] == "--contract" and i + 1 < len(argv): + contract = argv[i + 1] + i += 2 + continue + if argv[i] == "--src" and i + 1 < len(argv): + src_dir = argv[i + 1] + i += 2 + continue + sys.stderr.write("check-contract-scan: 未知参数 %r\n" % argv[i]) + return 2 + + try: + rep = analyze(contract, src_dir) + except contract_expect.ContractError as exc: + sys.stderr.write("check-contract-scan: %s\n" % exc) + return 2 + for line in rep.lines(): + print(line) + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv)) diff --git a/scripts/check-contract.sh b/scripts/check-contract.sh new file mode 100644 index 0000000..cc3a351 --- /dev/null +++ b/scripts/check-contract.sh @@ -0,0 +1,168 @@ +#!/usr/bin/env bash +# ssw-platform 契约对账尺子 —— `docs/contract.md` ↔ 代码里的真实路由 +# +# 目的:把「契约文档」和「代码」这两份**独立**的真相**对账**。 +# 契约 §6 的端点表原先是**散文表格**,代码里的路由注册是**另一处** +# ⇒ 加端点 / 改路径 / 改守卫 ⇒ 各改各的 ⇒ 漂移没人发现。 +# 本尺子把契约附录 A 的 `[ENDPOINT]`(机器可读)与代码里**真实注册**的路由 +# **双向**逐条对账:契约多 / 代码多 / 方法不符 / 归属层不符 / 守卫不符。 +# +# 🔴 **纯静态**:不启动后端、不发请求。只需要 `python3`(macOS 自带)。 +# +# 用法: +# bash scripts/check-contract.sh # 无参 ⇒ 全查 +# bash scripts/check-contract.sh --help # 本用法 +# +# 退出码:0 全过 / 1 有 ❌ 项 / 2 用法错或前置错误 +# +# ── 判据(CC1–CC10)── +# CC2 端点**总数**一致(契约 N 条 == 代码 N 条) +# CC3 契约 → 代码:每条端点在代码里存在且**方法**一致 +# CC4 代码 → 契约:代码里没有契约未登记的端点 +# CC5 **归属层**一致(platform / 业务模块代号) +# CC6 **守卫**一致(面A 菜单 key / 面B 点权限编码 / 登录 / 无)——静态推导 +# CC7 钉子测试的**字面量清单**(REGISTERED / JNPF_REGISTERED)与平台层路由双向覆盖 +# CC8 业务路由**三处**一致(各模块 ROUTES 常量 / router() 注册 / ALL_ROUTES) +# CC9 契约面计数**自洽**([FACE] 登记的条数 == [ENDPOINT] 里各 face 的实际条数) +# CC10 **官方端点台账** ↔ 代码真实路由(双向)+ 打印「官方端点覆盖 N/M」 +# CC1' **反自证**:注入已知漂移 ⇒ 必须被抓到(永远返回「干净」的尺子 = 没有尺子) +# +# 🔴 **期望值来自 `docs/contract.md` 附录 A**(机器可读)⇒ 改契约只改那一处。 + +set -u + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +SCRIPTS="$ROOT/scripts" +CONTRACT="$ROOT/docs/contract.md" +SRC="$ROOT/src/backend/src" +SCAN="$SCRIPTS/check-contract-scan.py" +CE_PY="$SCRIPTS/contract_expect.py" + +usage() { + echo "用法: bash scripts/check-contract.sh" + echo " 纯静态对账「契约端点表 ↔ 代码里真实注册的路由」" + echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错或前置错误" +} + +if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then + usage + exit 0 +fi +if [ "$#" -ne 0 ]; then + echo "❌ 未知参数: ${1}" + usage + exit 2 +fi + +# ---- 前置:python3 / 扫描器 / 契约文件 ---- +PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}" +if [ -z "${PY_BIN}" ]; then + echo "❌ 找不到 python3(扫描器需要它)" + exit 2 +fi +if [ ! -f "${SCAN}" ]; then + echo "❌ 缺扫描器: ${SCAN}" + exit 2 +fi +if [ ! -f "${CE_PY}" ]; then + echo "❌ 缺契约期望值读取器: ${CE_PY}" + exit 2 +fi +if [ ! -f "${CONTRACT}" ]; then + echo "❌ 缺契约文件: ${CONTRACT}" + exit 2 +fi + +# ---- 契约期望值(唯一真源:docs/contract.md 附录 A)---- +CE_RULER_ROWS="$("${PY_BIN}" "${CE_PY}" rows RULER 2>/dev/null)" || CE_RULER_ROWS="" +if [ -z "${CE_RULER_ROWS}" ]; then + echo "❌ 读契约期望值失败(docs/contract.md 附录 A 是不是被改坏了?)" + exit 2 +fi +CE_EXP_ASSERTIONS="$(printf '%s\n' "${CE_RULER_ROWS}" | awk -F'\t' '$1=="check-contract.sh" { print $2; exit }')" + +PASS=0; FAIL=0 +ok() { echo " ✅ $1"; PASS=$((PASS+1)); } +no() { echo " ❌ $1"; FAIL=$((FAIL+1)); } +hdr() { echo; echo "── $1 ──"; } + +# ---- 跑扫描器 ---- +SCAN_OUT="$("${PY_BIN}" "${SCAN}" --contract "${CONTRACT}" --src "${SRC}" 2>&1)" +SCAN_RC=$? +if [ "${SCAN_RC}" -eq 2 ]; then + echo "❌ 扫描器前置失败(契约读不出来 / 参数错):" + printf '%s\n' "${SCAN_OUT}" | sed 's/^/ /' + exit 2 +fi + +hdr "[CC2–CC10] 契约端点表 ↔ 代码真实路由 逐条对账" +DRIFT_LINES="" +while IFS=$'\t' read -r kind f1 f2 f3; do + [ -z "${kind:-}" ] && continue + case "${kind}" in + CHECK) + if [ "${f2}" = "OK" ]; then + ok "${f1}:${f3}" + else + no "${f1}:${f3}" + fi + ;; + INFO) + # 🔴 进度信息(官方端点覆盖 N/M)—— **不计入** PASS/FAIL + echo " 📊 ${f1}:${f2}" + ;; + WARN) + # WARN 行只有 3 列(kind / id / 说明)⇒ 说明在 f2 + if [ -n "${f3}" ]; then + DRIFT_LINES="${DRIFT_LINES}${f1}:${f3}"$'\n' + else + DRIFT_LINES="${DRIFT_LINES}${f1}:${f2}"$'\n' + fi + ;; + esac +done <<< "${SCAN_OUT}" + +if [ -n "${DRIFT_LINES}" ]; then + hdr "漂移明细" + printf '%s' "${DRIFT_LINES}" | sed 's/^/ ⚠️ /' +fi + +# ---- CC1' 反自证:尺子自己必须能抓到漂移 ---- +hdr "[CC1'] 扫描器反自证(--self-test 必须过)" +SELFTEST_OUT="$("${PY_BIN}" "${SCAN}" --self-test 2>&1)" +if [ "$?" -eq 0 ]; then + ok "扫描器自证通过:${SELFTEST_OUT}" +else + no "扫描器自证失败:${SELFTEST_OUT}" +fi + +# -------- 尺子自证:跑出来的条数必须等于契约里登记的条数 -------- +# +# 🔴 尺子自己知道它断言了几条(PASS+FAIL)。哪天有人删掉几条断言、或者某个分支提前 +# return 了,尺子照样「全绿」—— 变弱的尺子比没有尺子更危险 ⇒ 条数由**契约**钉死。 +hdr "[自证] 尺子条数与契约登记一致" +if [ -n "${CE_EXP_ASSERTIONS}" ]; then + CE_ACT_ASSERTIONS=$((PASS + FAIL)) + if [ "${CE_ACT_ASSERTIONS}" -eq "${CE_EXP_ASSERTIONS}" ]; then + # 自证**不计入** PASS/FAIL(它是元断言,不是业务断言) + echo " ✅ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言 = 契约登记的 ${CE_EXP_ASSERTIONS} 条" + else + echo " ❌ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言,契约登记 ${CE_EXP_ASSERTIONS} 条 ⇒ 尺子被改弱了(少了/多了断言)" + FAIL=$((FAIL + 1)) + fi +else + echo " ❌ 契约 [RULER] 里没有登记 check-contract.sh 的期望条数" + FAIL=$((FAIL + 1)) +fi + +# -------- 总结 -------- +echo +echo "── 总结 ──" +echo "PASS=${PASS} FAIL=${FAIL}" +if [ "${FAIL}" -eq 0 ]; then + echo "全 ✅ 契约与代码没漂移" +else + echo "有 ❌,请按上面修复(改契约 ⇒ 改 docs/contract.md 附录 A 的 [ENDPOINT])" +fi + +exit $([ "${FAIL}" -eq 0 ] && echo 0 || echo 1) diff --git a/scripts/check-module.sh b/scripts/check-module.sh new file mode 100755 index 0000000..dd97b68 --- /dev/null +++ b/scripts/check-module.sh @@ -0,0 +1,573 @@ +#!/usr/bin/env bash +# ssw-platform 加业务模块的「接触点」静态自检(Rust 版) +# +# 目的:在跑 perm-smoke 之前,**快速发现漏改的文件或字符串不一致**——这类问题一旦漏掉, +# 表现是「菜单不显示」「页面 404」「权限静默放行」,非常难定位。 +# +# 🔴 **10 个接触点**(每个业务模块都要碰这 10 处): +# ① 业务模块文件 + 3 条路由 ② spec 定义 ③ 实体表 DDL ④ 守卫 module_key +# ⑤ 前端 api 文件 ⑥ 前端页面 ⑦ 前端路由 ⑧ **菜单声明**(`*_MENU`) +# ⑨ **菜单登记**(`ALL_MENUS`) ⑩ 三处一字不差(module_key == url_address == Route path) +# +# 🔴 **纯静态**:不启动后端、不发一个请求、不依赖 node(契约明令:后端与冒烟脚本零 node 依赖)。 +# ⇒ 用法里**没有** `--live`;传了未知参数 ⇒ 退出码 2(用法错)。 +# +# 🔴 **期望值的唯一真源 = `docs/contract.md` 附录 A**(机器可读区段 `[MODULE]` / `[MENU]` / +# `[RULER]`,由 `scripts/contract_expect.py` 解析)。 +# 本脚本**不再硬编码**表名 / 路由 / 菜单 id ⇒ +# ① 改契约(加模块、改菜单)⇒ 只改 contract.md 一处; +# ② 代码漂移 ⇒ 本脚本立刻报「与契约不一致」(不是默默放过)。 +# +# 用法: +# bash scripts/check-module.sh # 无参 ⇒ 检查契约里登记的全部业务模块 +# bash scripts/check-module.sh # 也可只查一个(如 books Book) +# bash scripts/check-module.sh --help # 本用法 +# +# 例: +# bash scripts/check-module.sh # demo / shop / books 全查 +# bash scripts/check-module.sh books Book # 单模块 +# +# 退出码:0 全过 / 1 有 ❌ 项 / 2 用法错 + +# 🔴 **故意只用 `set -u`,不加 `-e` / `pipefail`** —— 这是有意的取舍,不是漏写: +# 本脚本的判定**依赖 grep 的返回码**(grep 命中 ⇒ 记一条 ✅,不命中 ⇒ 记一条 ❌)。 +# 若加 `-e`,**第一条没命中的 grep 就会中止整个脚本** ⇒ 闸门只跑了一半就“静默变绿/变红”, +# 反而把闸门弄坏。加 `pipefail` 同理(管道里任一段非 0 都会中止)。 +# ⇒ 想要「失败即停」请自己看末尾的 `PASS=` / `FAIL=` 与退出码。 +set -u + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" + +BACKEND="$ROOT/src/backend" +MODULES_DIR="$BACKEND/src/modules" +MODULES_MOD="$MODULES_DIR/mod.rs" +ROUTES="$BACKEND/src/routes.rs" +SCHEMA="$BACKEND/db/schema.sql" +CRUD="$BACKEND/src/platform/crud.rs" +FE="$ROOT/src/frontend" + +# 🔴 **本仓是后端-only**(CLAUDE.md §2.2:前端/移动端本期不动,沿用 Java 版)。 +# 脚手架原版假设 `src/frontend` 存在 ⇒ 前端接触点(5 前端 api / 6 前端页面 / +# 7 前端路由 / 全局面 A 判别头)在本仓**不适用**。 +# ⇒ 无前端时这些接触点打印 `⏭` 并**仍计入条数**(与 check-citations.sh 的 skip +# 语义一致)—— 不许静默减条数,否则尺子会被悄悄改弱。 +if [ -d "$FE/src" ]; then HAS_FE=1; else HAS_FE=0; fi + +# ---- 契约期望值(唯一真源:docs/contract.md 附录 A)---- +CE_PY="$ROOT/scripts/contract_expect.py" +if ! command -v python3 >/dev/null 2>&1; then + echo "❌ 前置错误:找不到 python3(读契约期望值用)。" + exit 2 +fi +if [ ! -f "$CE_PY" ]; then + echo "❌ 前置错误:找不到 ${CE_PY}。" + exit 2 +fi +ce() { python3 "${CE_PY}" "$@"; } + +# 一次取全表(表头行 + 数据行,制表符分隔) +CE_MOD_ROWS="$(ce rows MODULE 2>/dev/null)" || { + echo "❌ 前置错误:读契约的 [MODULE] 区段失败(docs/contract.md 的附录 A 是不是被改坏了?)。" + exit 2 +} +CE_MENU_ROWS="$(ce rows MENU 2>/dev/null)" || { + echo "❌ 前置错误:读契约的 [MENU] 区段失败(docs/contract.md 的附录 A 是不是被改坏了?)。" + exit 2 +} +CE_RULER_ROWS="$(ce rows RULER 2>/dev/null)" || { + echo "❌ 前置错误:读契约的 [RULER] 区段失败(docs/contract.md 的附录 A 是不是被改坏了?)。" + exit 2 +} + +# 从「表头行 + 数据行」里按首列取某列的值;找不到 ⇒ 返回空 + 非 0 +# +# 🔴 用 awk(-F'\t')而**不是** bash `read`:bash 的 `read` 按 IFS 空白折叠连续分隔符, +# 会把**空字段**(如 MENU.icon = NULL)吃掉 ⇒ 读出来错位。awk 保留空字段。 +row_field() { + local rows="$1" key="$2" col="$3" + printf '%s\n' "${rows}" | awk -F'\t' -v key="${key}" -v col="${col}" ' + NR == 1 { for (i = 1; i <= NF; i++) if ($i == col) c = i; next } + $1 == key { print $c; found = 1; exit } + END { if (!found) exit 3 } + ' +} + +usage() { + echo "用法: bash scripts/check-module.sh [ ...]" + echo " 无参 ⇒ 检查全部三个业务模块(demo / shop / books)" + echo "例: bash scripts/check-module.sh" + echo " bash scripts/check-module.sh books Book" + echo "退出码: 0 全过 / 1 有 ❌ 项 / 2 用法错" +} + +if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then + usage + exit 0 +fi + +# ---- 目标清单:appCode:Entity(默认取**契约** [MODULE] 区段登记的全部模块)---- +CE_ALL_TARGETS="$(printf '%s\n' "${CE_MOD_ROWS}" | awk -F'\t' 'NR>1 { print $1 ":" $2 }')" +TARGETS=() +if [ "$#" -eq 0 ]; then + while IFS= read -r line; do + [ -n "${line}" ] || continue + TARGETS+=("${line}") + done <<< "${CE_ALL_TARGETS}" +else + APP_ARG="$1" + shift + if [ "$#" -eq 0 ]; then + echo "❌ 用法错: 后面至少要跟一个 " + usage + exit 2 + fi + for ENT_ARG in "$@"; do + case "${ENT_ARG}" in + -*) + echo "❌ 未知参数: ${ENT_ARG}" + usage + exit 2 + ;; + esac + TARGETS+=("${APP_ARG}:${ENT_ARG}") + done +fi + +# ---- 期望值表(**逐字来自契约** `docs/contract.md` 附录 A 的 `[MODULE]` 区段)---- +# 每个目标:表名 / urlAddress(= 前端 Route path)/ 菜单 id / module_key(None = 仅登录) +# / **前端 api 文件该有没有**(有 = 有 / 无 = 走 view 直连分支) +# / **业务模块文件**(`src/backend/src/modules/.rs` —— spec + handler + 路由) +# +# 🔴 **新增业务模块时**:在契约 `[MODULE]` 加一行 + 在 `[MENU]` 加一行 ⇒ 本脚本自动覆盖它。 +# (本脚本**不再硬编码**任何业务标识符 ⇒ 加模块不用改脚本。) +T_COUNT=${#TARGETS[@]} +T_APP=(); T_ENT=(); T_TABLE=(); T_ROUTE=(); T_SEED=(); T_MK=(); T_API=(); T_FILE=() +for T in "${TARGETS[@]}"; do + A="${T%%:*}" + E="${T##*:}" + C_ENT="$(row_field "${CE_MOD_ROWS}" "${A}" entity)" + C_TABLE="$(row_field "${CE_MOD_ROWS}" "${A}" table)" + C_URL="$(row_field "${CE_MOD_ROWS}" "${A}" urlAddress)" + C_MK="$(row_field "${CE_MOD_ROWS}" "${A}" moduleKey)" + C_MENU="$(row_field "${CE_MOD_ROWS}" "${A}" menuId)" + C_API="$(row_field "${CE_MOD_ROWS}" "${A}" apiFile)" + C_FILE="$(row_field "${CE_MOD_ROWS}" "${A}" rsFile)" + if [ -z "${C_FILE}" ] || [ -z "${C_TABLE}" ]; then + echo "❌ 契约的 [MODULE] 区段里没有 app=${A} 这一行。" + echo " 本仓已知: $(printf '%s\n' "${CE_ALL_TARGETS}" | tr '\n' ' ')" + echo " ⇒ 新增模块请在 docs/contract.md 附录 A 的 [MODULE] 与 [MENU] 里各加一行。" + exit 2 + fi + if [ "${C_ENT}" != "${E}" ]; then + echo "❌ 契约里 app=${A} 的 entity 是 ${C_ENT},你传的是 ${E}" + exit 2 + fi + T_APP+=("${A}"); T_ENT+=("${E}") + T_TABLE+=("${C_TABLE}"); T_ROUTE+=("${C_URL}") + T_SEED+=("${C_MENU}"); T_MK+=("${C_MK}") + T_API+=("${C_API}"); T_FILE+=("${C_FILE}") +done + +PASS=0; FAIL=0 +ok() { echo " ✅ $1"; PASS=$((PASS+1)); } +no() { echo " ❌ $1"; FAIL=$((FAIL+1)); } +# ⏭ = 本仓不适用(当前只有「无前端」一种情形)—— **仍计入条数**,防止尺子被改弱 +skip(){ echo " ⏭ $1"; PASS=$((PASS+1)); } +hdr() { echo; echo "── $1 ──"; } + +# 小写(兼容 bash 3.x,不用 ${var,,}) +lower() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; } + +# 自然英语复数(兼容 bash 3.x,不依赖 declare -A) +# Apply → Applies / Box → Boxes / Match → Matches / Buy → Buys(y 辅音前) / Boy → Boys +plural() { + case "$1" in + *s|*x|*ch|*sh) echo "${1}es" ;; # -s/-x/-ch/-sh 直接加 es + *ay|*ey|*oy|*uy) echo "${1}s" ;; # 单元音 + y → 保留 +s(Boy → Boys) + *y) echo "${1%y}ies" ;; # 辅音 + y → 去 y 加 ies + *) echo "${1}s" ;; # 默认 +s + esac +} + +# 从业务模块文件里取该模块的 spec 常量名(如 DEMO_SPEC / PRODUCT_SPEC / BOOK_SPEC) +spec_const_of() { + awk ' + /pub const [A-Z_]+_SPEC: EntitySpec/ { + n = $0; sub(/.*pub const /, "", n); sub(/: EntitySpec.*/, "", n); print n; exit + } + ' "$1" +} + +# 从业务模块文件里取某个 spec 的 table 字面量 +spec_table_of() { + awk -v want="$1" ' + /entity: "/ { e = $0; sub(/.*entity: "/, "", e); sub(/".*/, "", e) } + /table: "/ { t = $0; sub(/.*table: "/, "", t); sub(/".*/, "", t); + if (e == want) { print t; exit } } + ' "$2" +} + +# 从业务模块文件里取某个 spec 的 module_key(None 或 Some("x") 的 x) +spec_module_key_of() { + awk -v want="$1" ' + /entity: "/ { e = $0; sub(/.*entity: "/, "", e); sub(/".*/, "", e) } + /module_key:/ { + m = $0; sub(/.*module_key:[[:space:]]*/, "", m); sub(/,[[:space:]]*$/, "", m) + if (e == want) { + if (m ~ /^Some\(/) { s = m; sub(/^Some\("/, "", s); sub(/"\)$/, "", s); print s } + else print "None" + exit + } + } + ' "$2" +} + +# 从业务模块文件的 MenuSpec 块里取该模块声明的**菜单 id** +# +# 🔴 **正则必须锚到行首的 `id:`** —— 否则 `parent_id: "0"` 里的 `id:` 会被误取。 +menu_id_of() { + awk ' + /^[ \t]*id:[ \t]*"/ { s = $0; sub(/^[ \t]*id:[ \t]*"/, "", s); sub(/".*/, "", s); print s; exit } + ' "$1" +} + +# 从业务模块文件的 MenuSpec 块里取**某个菜单 id 的某个字段** +# +# menu_field_of +# field ∈ id | full_name | en_code | url_address | parent_id | menu_type | icon | sort_code +# `Some("x")` ⇒ `x`;`None` ⇒ `None`;字符串去引号;数字原样。 +menu_field_of() { + awk -v want="$1" -v field="$2" ' + /^[ \t]*id:[ \t]*"/ { + cur = $0; sub(/^[ \t]*id:[ \t]*"/, "", cur); sub(/".*/, "", cur) + } + cur == want { + key = $0; sub(/^[ \t]*/, "", key); sub(/:.*$/, "", key) + if (key == field) { + val = $0; sub(/^[ \t]*[A-Za-z_]+:[ \t]*/, "", val); gsub(/,$/, "", val) + if (val ~ /^Some\(/) { sub(/^Some\("/, "", val); sub(/"\)$/, "", val) } + else { sub(/^"/, "", val); sub(/"$/, "", val) } + print val; exit + } + } + ' "$3" +} + +menu_url_of() { menu_field_of "$1" url_address "$2"; } + +# 逐字核对「代码里声明的菜单字段」与「契约 [MENU] 里那一行」 +# check_menu_field <契约列名> <代码字段名> +check_menu_field() { + local mid="$1" ccol="$2" cfield="$3" cval dval + cval="$(row_field "${CE_MENU_ROWS}" "${mid}" "${ccol}")" + dval="$(menu_field_of "${mid}" "${cfield}" "$MODFILE_CUR")" + if [ "${cval}" = "${dval}" ]; then + ok "菜单 ${mid}.${ccol} = ${cval}" + else + no "菜单 ${mid}.${ccol} = ${dval:-(没取到)},契约期望 ${cval:-(NULL)}" + fi +} + +# 从 schema.sql 里取某张表的 CREATE TABLE 块 +schema_block_of() { + awk -v t="$1" ' + $0 ~ ("CREATE TABLE " t " \\(") { inb = 1 } + inb { print } + inb && /^\);/ { exit } + ' "$SCHEMA" +} + +for i in $(seq 0 $((T_COUNT - 1))); do + APP="${T_APP[$i]}" + ENT="${T_ENT[$i]}" + TABLE="${T_TABLE[$i]}" + ROUTE="${T_ROUTE[$i]}" + SEED_ID="${T_SEED[$i]}" + MK="${T_MK[$i]}" + API_EXP="${T_API[$i]}" + MODFILE="$MODULES_DIR/${T_FILE[$i]}" + MODFILE_CUR="${MODFILE}" # 供 check_menu_field 用(bash 没有闭包,只能走全局) + MODNAME="${T_FILE[$i]%.rs}" + LC="$(lower "$ENT")" + URL="${APP}/${ENT}" + + hdr "[${ENT}] 1) 后端路由注册:modules/${T_FILE[$i]} 含 /api/ssw/${URL}/{List|Save|Delete}" + if [ -f "$MODFILE" ]; then + ok "业务模块文件存在: src/backend/src/modules/${T_FILE[$i]}" + else + no "缺业务模块文件: src/backend/src/modules/${T_FILE[$i]}" + fi + for ep in List Save Delete; do + if grep -q "/api/ssw/${URL}/${ep}" "$MODFILE" 2>/dev/null; then + ok "modules/${T_FILE[$i]} 已注册 /api/ssw/${URL}/${ep}" + else + no "modules/${T_FILE[$i]} 缺 /api/ssw/${URL}/${ep} → 端点 404" + fi + done + # 🔴 **业务路由不许进平台层** —— 平台层只 merge 一次(`modules::router()`)。 + # 只看**真正的注册调用**(`.route("…")`)—— routes.rs 的路由表钉子测试里 + # 有一份**路径清单**(那是契约快照,不是注册)⇒ 不能拿它当判据。 + if grep -qE "\.route\(\"/api/ssw/${URL}/" "$ROUTES" 2>/dev/null; then + no "routes.rs 里注册了业务路由 /api/ssw/${URL}/ ⇒ 平台层混进了业务知识" + else + ok "routes.rs 未注册业务路由(平台层只 merge modules::router())" + fi + # 🔴 **模块必须被业务层登记表收编** —— `modules/mod.rs` 的 `router()` 要 merge 它、 + # `ALL_SPECS` 要收它的 spec(漏一处 ⇒ 端点 404 / 启动自检报错)。 + if grep -q "${MODNAME}::router()" "$MODULES_MOD" 2>/dev/null; then + ok "modules/mod.rs 的 router() merge 了 ${MODNAME}::router()" + else + no "modules/mod.rs 的 router() 没 merge ${MODNAME}::router() ⇒ 端点 404" + fi + SPEC_CONST="$(spec_const_of "$MODFILE")" + if [ -n "${SPEC_CONST}" ] && grep -q "${SPEC_CONST}" "$MODULES_MOD" 2>/dev/null; then + ok "modules/mod.rs 的 ALL_SPECS 收了 ${SPEC_CONST}" + else + no "modules/mod.rs 的 ALL_SPECS 没收 ${SPEC_CONST:-(没取到 spec 常量)} ⇒ 启动白名单自检会失败" + fi + + hdr "[${ENT}] 2) spec 定义:modules/${T_FILE[$i]} 含 entity: \"${ENT}\" + table: \"${TABLE}\"" + if grep -q "entity: \"${ENT}\"" "$MODFILE" 2>/dev/null; then + ok "modules/${T_FILE[$i]} 含 entity: \"${ENT}\"" + else + no "modules/${T_FILE[$i]} 缺 entity: \"${ENT}\"(spec 没登记这个实体)" + fi + SPEC_TABLE="$(spec_table_of "${ENT}" "$MODFILE")" + if [ "${SPEC_TABLE}" = "${TABLE}" ]; then + ok "spec.table = ${TABLE}" + else + no "spec.table = ${SPEC_TABLE:-(没取到)},期望 ${TABLE}" + fi + + hdr "[${ENT}] 3) 实体表存在:schema.sql 含 CREATE TABLE ${TABLE}" + if grep -q "CREATE TABLE ${TABLE}" "$SCHEMA" 2>/dev/null; then + ok "schema.sql 有表 ${TABLE}" + else + no "schema.sql 缺表 ${TABLE} → 业务模块跑不起来" + fi + + hdr "[${ENT}] 4) 守卫 module_key:modules/${T_FILE[$i]} 的 spec.module_key" + SPEC_MK="$(spec_module_key_of "${ENT}" "$MODFILE")" + if [ "${SPEC_MK}" = "${MK}" ]; then + ok "spec.module_key = ${MK}" + else + no "spec.module_key = ${SPEC_MK:-(没取到)},期望 ${MK}" + fi + + hdr "[${ENT}] 5) 前端 api 文件:api/${LC}.ts 含 list/save/delete 三导出(期望:${API_EXP})" + API="$FE/src/api/${LC}.ts" + VIEW="$FE/src/views/${ENT}.tsx" + if [ "${HAS_FE}" -eq 0 ]; then + skip "本仓无前端(后端-only)⇒ 跳过 api/${LC}.ts 接触点(契约期望:${API_EXP})" + elif [ "${API_EXP}" = "有" ]; then + # 期望**有** api 文件 ⇒ 缺文件就是 ❌(**不许**再打「无 api/xxx.ts」这种误导性绿灯)。 + if [ -f "$API" ]; then + # 命名约定:list 函数走「自然英语复数」(Book → listBooks / Product → listProducts) + # save/delete 用 Entity 单数(PascalCase),与后端端点命名一致。 + PLURAL_ENT="$(plural "$ENT")" + for fn in "list${PLURAL_ENT}" "save${ENT}" "delete${ENT}"; do + if grep -qE "export[[:space:]]+const[[:space:]]+${fn}" "$API" 2>/dev/null; then + ok "${fn} 导出存在" + else + no "${API} 缺 export const ${fn}(前端解构会 undefined)" + fi + done + else + no "缺 api/${LC}.ts(期望有:${ENT} 的前端必须有 api 层)" + fi + else + # 期望**无** api 文件 ⇒ 本仓前端是逐字复制:demo 模块没有 api 文件, + # views/DemoItem.tsx 直接 request.get('/ssw/demo/DemoItem/List') ⇒ + # 「前端 api 文件」这一接触点对 demo 走**直连分支**(两种都查不到才算 ❌)。 + if [ -f "$API" ]; then + no "多出 api/${LC}.ts(期望无:${ENT} 走 view 直连分支)—— 请同步期望值表" + else + ok "无 api/${LC}.ts(期望无 ⇒ 走 view 直连分支)" + if [ -f "$VIEW" ]; then + for ep in List Save Delete; do + if grep -qE "request\.(get|post|delete)\([^)]*/ssw/${URL}/${ep}" "$VIEW" 2>/dev/null; then + ok "views/${ENT}.tsx 直连 request → /ssw/${URL}/${ep}" + else + no "views/${ENT}.tsx 没有直连 request → /ssw/${URL}/${ep}" + fi + done + else + no "views/${ENT}.tsx 不存在,无法核对直连分支" + fi + fi + fi + + hdr "[${ENT}] 6) 前端页面:views/${ENT}.tsx 存在" + if [ "${HAS_FE}" -eq 0 ]; then + skip "本仓无前端(后端-only)⇒ 跳过 views/${ENT}.tsx 接触点" + elif [ -f "$VIEW" ]; then + ok "views/${ENT}.tsx" + else + no "缺文件: views/${ENT}.tsx" + fi + + hdr "[${ENT}] 7) 前端路由:App.tsx 含 ),BSD grep 不支持 -P 跨行匹配, + # 用 tr 把换行去掉再 grep 最稳。 + if [ "${HAS_FE}" -eq 0 ]; then + skip "本仓无前端(后端-only)⇒ 跳过 App.tsx 路由接触点(path=\"/${ROUTE}\")" + elif tr '\n' ' ' < "$FE/src/App.tsx" | grep -q "]*path=\"/${ROUTE}\"" 2>/dev/null; then + ok "Route path=\"/${ROUTE}\" 已注册" + else + no "App.tsx 缺 .rs` 的 + # `*_MENU: MenuSpec` 里,由装配根注入平台层的种子。 + # 期望值来自**契约** `[MENU]` 区段 ⇒ 代码改了菜单名/编码/图标 ⇒ 这里立刻报漂移。 + DECL_ID="$(menu_id_of "${MODFILE}")" + if [ "${DECL_ID}" = "${SEED_ID}" ]; then + ok "modules/${T_FILE[$i]} 声明的菜单 id = ${SEED_ID}" + else + no "modules/${T_FILE[$i]} 声明的菜单 id = ${DECL_ID:-(没取到)},期望 ${SEED_ID}" + fi + SEED_URL="$(menu_url_of "${SEED_ID}" "${MODFILE}")" + if [ "${SEED_URL}" = "${ROUTE}" ]; then + ok "菜单 ${SEED_ID}.url_address = ${ROUTE}" + else + no "菜单 ${SEED_ID}.url_address = ${SEED_URL:-(没取到)},期望 ${ROUTE} → 菜单不显示" + fi + # 契约 [MENU] 里这一行的其余字段,逐字核对 + check_menu_field "${SEED_ID}" fullName full_name + check_menu_field "${SEED_ID}" enCode en_code + check_menu_field "${SEED_ID}" parentId parent_id + check_menu_field "${SEED_ID}" type menu_type + check_menu_field "${SEED_ID}" sortCode sort_code + # icon:契约里空 = NULL,代码里写 `None` ⇒ 归一化后再比 + C_ICON="$(row_field "${CE_MENU_ROWS}" "${SEED_ID}" icon)" + D_ICON="$(menu_field_of "${SEED_ID}" icon "${MODFILE}")" + if [ "${D_ICON}" = "None" ]; then D_ICON=""; fi + if [ "${C_ICON}" = "${D_ICON}" ]; then + ok "菜单 ${SEED_ID}.icon = ${C_ICON:-(NULL)}" + else + no "菜单 ${SEED_ID}.icon = ${D_ICON:-(NULL)},契约期望 ${C_ICON:-(NULL)}" + fi + + hdr "[${ENT}] 9) 菜单登记:modules/mod.rs 的 ALL_MENUS 收了本模块的菜单" + MENU_CONST="$(grep -o "^pub const [A-Z_]*_MENU: MenuSpec" "${MODFILE}" 2>/dev/null | sed 's/^pub const //; s/: MenuSpec$//')" + if [ -z "${MENU_CONST}" ]; then + no "modules/${T_FILE[$i]} 没有 *_MENU: MenuSpec 声明" + elif grep -q "${MENU_CONST}," "${MODULES_MOD}" 2>/dev/null; then + ok "modules/mod.rs 的 ALL_MENUS 收了 ${MENU_CONST}" + else + no "modules/mod.rs 的 ALL_MENUS 没收 ${MENU_CONST} ⇒ 菜单不会被种、admin 少一条授权" + fi + + hdr "[${ENT}] 10) 三处一字不差:module_key == url_address == Route path(去前导斜杠)" + if [ "${MK}" = "None" ]; then + # 🔴 demo 是「仅登录」守卫 ⇒ **没有** module_key 这一侧 ⇒ 只比 url_address == Route path。 + if [ "${SEED_URL}" = "${ROUTE}" ]; then + ok "url_address == Route path:${SEED_URL} == ${ROUTE}(demo 仅登录 ⇒ 跳过 module_key 侧)" + else + no "url_address=${SEED_URL:-无} / Route=${ROUTE} 不一致" + fi + elif [ "${SPEC_MK}" = "${SEED_URL}" ] && [ "${SEED_URL}" = "${ROUTE}" ]; then + ok "三处相等:${SPEC_MK} == ${SEED_URL} == ${ROUTE}" + else + no "三处不一致:module_key=${SPEC_MK:-无} / url_address=${SEED_URL:-无} / Route=${ROUTE}" + fi + + hdr "[${ENT}] 实体列 f_ 前缀 + 主键 f_id VARCHAR(50)(契约红线 4)" + BLOCK="$(schema_block_of "${TABLE}")" + if [ -z "${BLOCK}" ]; then + no "schema.sql 里没解析出 ${TABLE} 的建表块" + else + COLS="$(printf '%s\n' "${BLOCK}" | sed -n 's/^ \([A-Za-z_][A-Za-z0-9_]*\).*/\1/p')" + if [ -z "${COLS}" ]; then + no "${TABLE} 的建表块里没解析出任何列" + else + BADCOLS="" + for c in ${COLS}; do + case "${c}" in + f_*) ;; + *) BADCOLS="${BADCOLS} ${c}" ;; + esac + done + if [ -n "${BADCOLS}" ]; then + no "列名不是 f_ 前缀:${BADCOLS}" + else + ok "全部列名都是 f_ 前缀($(printf '%s\n' "${COLS}" | wc -l | tr -d ' ') 列)" + fi + fi + if printf '%s\n' "${BLOCK}" | grep -q "f_id VARCHAR(50)"; then + ok "主键 f_id VARCHAR(50)(36 位 UUID 装得下)" + else + no "主键必须是 f_id VARCHAR(50)(不要写成 32,否则 36 位 UUID 装不下)" + fi + fi + + hdr "[${ENT}] 软删契约:list 带 f_delete_mark = 0 + remove 走软删(不是物理 DELETE)" + if grep -q "WHERE f_delete_mark = 0" "$CRUD" 2>/dev/null; then + ok "list 查询带 f_delete_mark = 0" + else + no "list 查询缺 f_delete_mark = 0 → 软删数据会显示" + fi + if grep -q "SET f_delete_mark = 1" "$CRUD" 2>/dev/null; then + ok "remove 置 f_delete_mark = 1(软删)" + else + no "remove 没软删(应是 UPDATE f_delete_mark=1,非物理 DELETE)" + fi +done + +# -------- 全局红线(与具体模块无关,但一样会让闸门失真)-------- +# +# 🔴 **面 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` 是本仓前端唯一不发的** ⇒ 判别只能用它。 +# 本仓前端一旦开始发 `Vue-Version` ⇒ 面 A 的请求会被误判成面 B ⇒ 契约整体错位。 +hdr "[全局] 面 A/面 B 判别头:前端**禁发** Vue-Version" +if [ "${HAS_FE}" -eq 0 ]; then + skip "本仓无前端(后端-only)⇒ 判别头检查不适用;面 A/面 B 分流仍由后端按头判定" +elif grep -q "Vue-Version" "$FE/src/api/request.ts" 2>/dev/null; then + no "前端 request.ts 发了 Vue-Version 头 ⇒ 面 A 请求会被误判成面 B" +else + ok "前端 request.ts 未发 Vue-Version(面 A/面 B 判别成立)" +fi + +hdr "[全局] 面 B 尺子必须带判别头 Vue-Version: 3" +if grep -q "Vue-Version: 3" "$ROOT/scripts/perm-smoke-jnpf.sh" 2>/dev/null; then + ok "perm-smoke-jnpf.sh 带了 Vue-Version: 3" +else + no "perm-smoke-jnpf.sh 缺 Vue-Version: 3 ⇒ 面 B 请求不会被识别成面 B" +fi + +# -------- 尺子自证:跑出来的条数必须等于契约里登记的条数 -------- +# +# 🔴 **为什么要有这一条**:尺子自己**知道**自己断言了几条(PASS+FAIL)。 +# 如果哪天有人删掉了几条断言、或者某个分支提前 return 了,尺子照样「全绿」—— +# 变弱的尺子比没有尺子更危险。⇒ 条数由**契约**钉死,对不上 ⇒ 失败。 +# +# 🔴 只在**全量跑**(无参)时对账;单模块跑的条数本来就不是全量条数。 +CE_EXP_ASSERTIONS="$(row_field "${CE_RULER_ROWS}" "check-module.sh" assertions)" +if [ "$#" -eq 0 ] && [ -n "${CE_EXP_ASSERTIONS}" ]; then + CE_ACT_ASSERTIONS=$((PASS + FAIL)) + if [ "${CE_ACT_ASSERTIONS}" -eq "${CE_EXP_ASSERTIONS}" ]; then + # 🔴 自证**不计入** PASS/FAIL(它是元断言,不是业务断言)⇒ 契约里登记的条数 + # 永远是「业务断言数」,与文档里说的「N 条」是同一个数。 + echo " ✅ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言 = 契约登记的 ${CE_EXP_ASSERTIONS} 条" + else + echo " ❌ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言,契约登记 ${CE_EXP_ASSERTIONS} 条 ⇒ 尺子被改弱了(少了/多了断言)" + FAIL=$((FAIL + 1)) + fi +fi + +# -------- 总结 -------- +echo +echo "── 总结 ──" +echo "Modules: ${TARGETS[*]}" +echo "PASS=$PASS FAIL=$FAIL" +if [ "$FAIL" -eq 0 ]; then + echo "全 ✅ 可以跑 perm-smoke 了" +else + echo "有 ❌,请按上面修复后再跑 perm-smoke" +fi + +exit $([ "$FAIL" -eq 0 ] && echo 0 || echo 1) diff --git a/scripts/contract_expect.py b/scripts/contract_expect.py new file mode 100755 index 0000000..2d05719 --- /dev/null +++ b/scripts/contract_expect.py @@ -0,0 +1,227 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""contract_expect —— 读 `docs/contract.md` 里的**机器可读期望值**区段。 + +🔴 为什么存在: + 期望值(菜单表 / 菜单树 / 业务模块清单 / 各尺子的断言数)原先散落在 + **契约文档(散文表格)+ 尺子脚本(硬编码)** 两处 ⇒ 改一处忘另一处 ⇒ 漂移。 + 本脚本把 `docs/contract.md` 附录 A 的 `` 块 + 解析成结构化数据,**所有尺子都从那里读期望值** ⇒ 单一真源 + 自动对账。 + +用法: + contract_expect.py sections # 列出所有区段名 + contract_expect.py dump # 打印全部(调试用) + contract_expect.py rows
# 打印整段(表头行 + 数据行,制表符分隔) + contract_expect.py menu-tree # 期望菜单树字符串(一行) + contract_expect.py menu # 某菜单的某列 + contract_expect.py module # 某业务模块的某列 + contract_expect.py endpoint # 某端点的某列 + contract_expect.py endpoints # 全部端点(method\tpath) + contract_expect.py face # 某契约面的某列 + contract_expect.py official # 官方端点台账全表(method/path/status/src/note) + contract_expect.py official-coverage # 官方端点覆盖 N/M(+ implemented/partial/absent/oos 计数) + contract_expect.py ruler # 某把尺子的期望断言数 + +退出码:0 = 查到 / 2 = 契约里没有这一项(🔴 绝**不**返回空串冒充「查到了」) +""" + +import io +import os +import sys + +BEGIN = " + + + 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 new file mode 100755 index 0000000..7ce2b0e --- /dev/null +++ b/template-boot-jnpf/scripts/verify.sh @@ -0,0 +1,125 @@ +#!/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 new file mode 100644 index 0000000..9e514bf --- /dev/null +++ b/template-boot-jnpf/ssw-admin/pom.xml @@ -0,0 +1,91 @@ + + + + + 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 new file mode 100644 index 0000000..e5ac8c8 --- /dev/null +++ b/template-boot-jnpf/ssw-admin/src/main/java/ssw/SswAdminApplication.java @@ -0,0 +1,30 @@ +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 new file mode 100644 index 0000000..43a5b50 --- /dev/null +++ b/template-boot-jnpf/ssw-admin/src/main/java/ssw/common/config/SswMapperConfig.java @@ -0,0 +1,22 @@ +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 new file mode 100644 index 0000000..2eaabb1 --- /dev/null +++ b/template-boot-jnpf/ssw-admin/src/main/resources/application-dev.yml @@ -0,0 +1,111 @@ +# 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 new file mode 100644 index 0000000..fd78c64 --- /dev/null +++ b/template-boot-jnpf/ssw-admin/src/main/resources/application.yml @@ -0,0 +1,41 @@ +# 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 new file mode 100644 index 0000000..a8dd48f --- /dev/null +++ b/template-boot-jnpf/ssw-demo/pom.xml @@ -0,0 +1,24 @@ + + + + + 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 new file mode 100644 index 0000000..48b3491 --- /dev/null +++ b/template-boot-jnpf/ssw-demo/ssw-demo-controller/pom.xml @@ -0,0 +1,36 @@ + + + + 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 new file mode 100644 index 0000000..f00b1b3 --- /dev/null +++ b/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/controller/DemoController.java @@ -0,0 +1,65 @@ +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 new file mode 100644 index 0000000..5a395b9 --- /dev/null +++ b/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/mapper/DemoMapper.java @@ -0,0 +1,19 @@ +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 new file mode 100644 index 0000000..1f4bad2 --- /dev/null +++ b/template-boot-jnpf/ssw-demo/ssw-demo-entity/pom.xml @@ -0,0 +1,26 @@ + + + + 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 new file mode 100644 index 0000000..e4ac43d --- /dev/null +++ b/template-boot-jnpf/ssw-demo/ssw-demo-entity/src/main/java/ssw/demo/entity/DemoEntity.java @@ -0,0 +1,37 @@ +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