From aa2447eec223dce0532bcea47e310a39bc90a3cc Mon Sep 17 00:00:00 2001 From: admin Date: Sun, 1 Nov 2026 23:04:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E6=89=B9=E6=AC=A1=20?= =?UTF-8?q?12=20/=2012.5=20=E6=94=B6=E5=B0=BE=EF=BC=88HANDOFF=20+=20HOWTO?= =?UTF-8?q?=20+=20CLAUDE=20+=20memory=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit HANDOFF 记下加模块的真实成本(一条命令 + 一张产出表)、2 个真 bug、反自证结果; HOWTO_MODULE 开头两节重写(旧手抄清单已过时);CLAUDE 两条核心不变量改写。 --- .workbuddy/memory/2026-11-01.md | 287 +++++++++++++++ CLAUDE.md | 10 +- HANDOFF.md | 628 +++++++++++++++++++++++++++++++- HOWTO_MODULE.md | 65 ++-- 4 files changed, 959 insertions(+), 31 deletions(-) diff --git a/.workbuddy/memory/2026-11-01.md b/.workbuddy/memory/2026-11-01.md index 9b9b7ca..7e33b7e 100644 --- a/.workbuddy/memory/2026-11-01.md +++ b/.workbuddy/memory/2026-11-01.md @@ -395,3 +395,290 @@ HANDOFF §0-bis 与 §1 已更正,并补了批次 9/10 的逐批增量。 `fe-gap` 余下:`system` 55 / `permission` 26 / `systemData` 32 —— 从**有官方 `base_*` 表支撑** 的族里挑;`workFlow`(104) / `onlineDev`(101) / `aiCenter`(75) / `extend`(64) / `msgCenter`(50) 基本是「本仓没这个模块」⇒ **先确认产品边界再动手**,做也只是恒空 stub。 + +--- + +## 19:00 —— 批次 12 方向决策:「框架固定包 + 业务模块链接就好」 + +**用户诉求**(原话):「后台一个成熟的框架,然后用极简业务代码 + vue 前端。 +能不能先把主要框架打成相对固定包,业务模块链接就好,快速打包/快速验证。放在 HANDOFF 下一轮优先做掉。」 + +⇒ 本轮**不做端点**,只做**方案 + 写进 HANDOFF**(批次 12),原批次 12 顺延为批次 13。 + +### 现状体检(实测,非推测) + +| 事实 | 证据 | +|---|---| +| `packs/asset` **没被内核装载** | `routes.rs` 只有 1 处 `.merge(`(`modules::router()`);`sspf-sdk` 的 `BusinessPack` 方法只有 manifest/entities/menus/metadata/hooks —— **无 `routes()`** | +| 业务 spec **两份逐字拷贝** | `modules/asset.rs`(178 行)vs `packs/asset/src/lib.rs` | +| 两份拷贝**无比对闸门** | `check-arch.sh` 函数只有 ar1–ar7 + mem1 + mem2,**无 PACK1**(`packs/asset` 注释里写的「P3 加」至今没加) | +| 契约扫描器**只扫 `modules/*.rs`** | `check-contract-scan.py:369` 只遍历 `src/backend/src/modules/`(除 `mod.rs`)⇒ 包搬走 ⇒ 假漂移 | +| 业务表数**写死 52** | `crates/sspf-store/src/db.rs:1226,1233` ⇒ 加表必红(批次 9/10 各踩一次) | +| 业务 DDL **手抄** `schema.sql` | `schema.sql:879/888/897/920` | +| `main.rs::whitelist_self_check` **双向对账** spec↔DDL | 包表会被判「孤儿 DDL」⇒ 启动失败 | +| `src/frontend` **是空的** | 本仓后端-only(CLAUDE.md §2.2);前端在 `~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework` | + +### 🔴 闸门耗时实测(新增基线,之前没量过) + +静态:`check-contract` **66.6s** 🔴最慢 / `check-module` 25.8s / `check-boundary` 7.2s / +`check-citations` 5.2s / `check-naming` 3.6s / `check-arch` 1.6s ⇒ **合计 ~110s** +运行时:`perm-smoke` 6.0s / `perm-smoke-jnpf` 4.8s / `baseline` 3.3s / `mcp` 2.9s(34+14 两段)/ +`lowcode` 1.9s ⇒ **合计 ~19s** + +⇒ **「快验证」瓶颈在静态闸门,不在起后端** ⇒ 批次 12 的提速目标是「改一个模块后静态 ≤15s」。 + +### 批次 12 的 4 项交付物 + +1. `sspf-sdk` 补 `fn routes(&self) -> &'static [PackRoute]`(默认空 ⇒ L0 零改动) + + 新建 `crates/sspf-plugin`(依赖 ⊆ {sspf-sdk, sspf-contract, serde, serde_json})。 + 🔴 **路由「声明」在 sdk(纯数据)、「注册」在内核(唯一认识 axum)** —— 业务包不许依赖 axum(AR2)。 +2. `modules/asset.rs` 改 **re-export** `packs/asset` ⇒ 单一真源;补 **PACK1** 闸门 + + 新 **AR9**(平台层不许 `use sspf_pack_*`)。 +3. 业务 DDL 跟着包走(`pack.toml` 的 `[[pack.tables]].ddl` 已预留)⇒ 不再手抄 `schema.sql`; + 🔴 `sspf-store` 两处表数断言**去写死**; + 🔴 `is_builtin_table`(`face_b.rs:12993` 取 `ddl_tables()`)会**把包表当内置表** ⇒ 要重新想。 +4. 契约登记**自动生成**(`scripts/pack-sync.py` + BEGIN/END 标记)+ 扫描器**增量缓存** + + 新增 `scripts/verify.sh`(一条命令跑完 build→静态→单测→尺子,打印耗时 Top3)。 + +### 明确不做(批次 12) + +L3 dylib 动态库(PLAN.md §4.5 六条铁律是另一个量级)/ WASM 执行器 / +`pack export/import --format=baseline` 双向迁移。 +🔴 依据 PLAN.md §4.6:「L2 是静态链接,L3 才是运行期 dlopen」「不要对外承诺什么都能热更」。 + +### 🔴 前端的处理(需产品确认) + +本仓**没有前端**。vue 前端那条诉求的正确形态是: +**官方 JNPF monorepo 本身就是那个「固定包」**(业务方只写 `views/` + `api/` + 一行路由)。 +若要「页面脚手架」,候选方案 = 仿 `new-pack.sh` 做 `new-page.sh`。 + +### 产出 + +`HANDOFF.md`:新增 §0-ter(下一轮做什么)、§0-bis 末尾(优先级改了 + 耗时基线表)、 +§3 第 12 项 + 完整「批次 12」小节(4 交付物 / 7 护栏 / 5 验收判据 / 明确不做)、 +§1 现状加「业务包目前是死的」。原批次 12 顺延为批次 13,**一字未改**。 + +--- + +## 19:40 —— 两阶段路线明确(用户澄清:不是让我去调试) + +**用户原话**:「我重新说,不是让你去调试。我的意思是后续基于 官方 /rust 框架做开发, +分为 mvp阶段 和 规范集成开发 阶段,mvp阶段 用 ssw-jnpf-lite-rust 技能 来 开发 AI 怎么快怎么来, +业务框架定型后,迁移在标准jnpf框架集成开发(仅部份终端设备不佳考虑这个做后端)」 + +⚠️ **上一轮我理解错了**:以为「调试阶段」= 让我去调前端页面。 +实际 = **开发流程分两阶段**。⇒ 重写了 §0-ter(上一版的「前端怎么办」已清理)。 + +### 两阶段路线 + +``` +MVP 阶段(Rust 技能,AI 怎么快怎么来) → 规范集成阶段(迁标准 JNPF Java) + ↘ 仅「部分终端设备不佳」的场景保留 Rust 后端 +``` + +### 🔴 关键判断:分界线不是「时间」,是「契约忠实度」 + +官方端点台账(`docs/contract.md` 附录 A `[OFFICIAL]`,**379 条**)忠实度实测分布: + +| status | 条数 | 集成时怎么办 | +|---|---|---| +| `implemented` | **338** | ✅ 直接搬 | +| `partial` | **27** | 🔴 **要还债** | +| `absent` | **7** | 集成时补(官方现成) | +| `oos` | **6** | 集成时按官方做 | + +⇒ **27 条 partial 才是 MVP 阶段的债**,分三类: +- **① 临时欠 14 条**(导出/导入/测试连接/打印渲染 —— 恒 400 + 人话,本仓无文件服务/驱动/渲染引擎) + ⇒ **删掉本仓实现、换官方的 ⇒ 几乎零成本**(假债) +- **② 形状欠 9 条**(`CurrentUser` 的 `sysConfigInfo` 返 `{}`、按钮级权限恒空、`permissionList` 粒度不同…) + ⇒ **要真对齐**(真债) +- **③ 自造 4 条**(`f_en_code` 本仓自定占位、`deleteAllTable` 有意收窄…)⇒ **改成官方编码/语义**(真债) + +⇒ **真债 = ②③ 共 13 条**,不是 27 条。**这 13 条就是「快」的精确边界。** + +### 🔴 MVP 阶段四条红线(违反 = 集成时返工) + +1. 业务表 `base_*` 列名不许自创(官方 DDL 13227 行 / 331 张表,本机 `~/Desktop/workspace/jnpf/jnpf-database/`) +2. 业务表 `f_tenant_id` 不许省(恒 `"0"`,但 `NOT NULL` + 参与复合主键 `(f_id, f_tenant_id)`) +3. 接口路径从第一天就用**官方形状**(面 B);面 A(`/api/ssw/...`)是本仓自造 ⇒ 集成时全作废 +4. 返回形状宁可少字段,不许返错形状(官方前端遇缺字段会**静默降级**:按钮恒显、树空) + +### ✅ 已到位(集成时直接搬) + +`base_*` 逐字对齐 / cipher 逐字节等价(`MIGRATION.md` §7 换算)/ `ActionResult` 零改 / +`EntitySpec` ≈ 一个 Java 实体类 / 面 B 已按 `f_en_code` / **官方前端能零改直连本仓**。 + +### 🔴 前端(上一轮理解错的地方) + +- 本仓 `src/frontend` **是空的**(后端-only);前端**全程**在官方 monorepo + `~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework`。 +- **官方路由是动态注册**:`router/routes/index.ts` 用 + `import.meta.glob('./modules/**/*.ts')` + `mergeRouteModules`(读 `default` 导出) + ⇒ **放文件进 `router/routes/modules/` 即注册,不改配置**。 + ⇒ 加一个业务页面 = **3 个文件**:`views/<模块>/index.vue` + `api/<模块>.ts` + `router/routes/modules/<模块>.ts`。 +- ⚠️ `router/routes/modules/` 目录**官方自己也没建** ⇒ 目前是空的。 +- ⚠️ **前端完全没闸门**(`check-module.sh` 的 4 个前端接触点全打 `⏭`)⇒ 批次 12 加 `--fe-root`。 + +### 批次 12 相应调整(写进 HANDOFF §3) + +- 四项交付物不变,但**每项加「集成期友好性」要求**: + ① 包路由只许官方形状(面 B);③ 包 DDL 按官方规范(`f_tenant_id` 必带、`baseline_table` 必填); + ④ 前端 `new-page.sh` + `check-module.sh --fe-root`。 +- 护栏从 7 条加到 **10 条**(新增:路径只许官方 / DDL 不许自造语义 / 前端三处一字不差)。 +- 新增 **「集成期 checklist」(8 项)** —— MVP 阶段每加一个包就填一遍,填不完当场还债。 +- 🔴 **性价比最高的一件事**:MVP 阶段**把 VO 字段清单抄全** ⇒ 直接消灭「形状欠」9 条的源头。 + +### 产出 + +`HANDOFF.md` §0-ter 整节重写为「两阶段开发路线」(含 partial 分布表 / 四条红线 / 已到位表 / +前端两阶段表);§0-bis 追加 19:39 补充;§3「批次 12」加集成期友好性要求 + 10 条护栏 + +集成期 checklist;清理上一轮的错误表述。 + +--- + +## 20:10 段 —— 🔴🔴 前端 MVP 方向定案:React 模板,「除了认证其它都留给集成阶段」 + +**用户指令**(原话):「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向, +**除了认证,其它都留给集成阶段**」。 + +⇒ 🔴 **这是对前两版理解的第三次修正**(先写「官方 vue 零改直连面 B」→ 后写「前端全程在官方 monorepo」 +→ 现在才是对的)。**下次开工先复核这条再动手。** + +### 🔴🔴 头号实测发现:两个技能的 React 前端**逐字节相同** + +```bash +$ diff -rq skills/ssw-jnpf-lite-react/src/frontend/src skills/ssw-jnpf-lite-rust/src/frontend/src +# 无输出 ⇒ 完全一致 +$ diff react/.../vite.config.ts rust/.../vite.config.ts +# 唯一差异:proxy 端口 30000(NestJS) vs 30010(Rust) +``` + +⇒ **前端是独立资产,与后端选 Rust 还是 NestJS 无关** ⇒ 换后端栈**前端一个字都不用动**。 +⇒ 本仓选择:**MVP 后端 Rust(axum) + 前端用这套 React 模板**(直接从 `ssw-jnpf-lite-rust` 复制 `src/frontend`)。 +⇒ React 技能的两把尺子可移植:`scripts/check-module.sh`(11 KB,9 接触点,`--all`/`--live`)、 +`scripts/perm-smoke.sh`(22 条基线)。 + +### 🔴 认证为什么是唯一例外(证据链,逐条实测) + +| 环节 | MVP(React) | 官方 | 结论 | +|---|---|---|---| +| 登录端点 | `POST /api/oauth/Login` (form-urlencoded) | `jnpf-web-apps-main/src/api/core/auth.ts`:`Api.Login='/api/oauth/Login'` + `ContentTypeEnum.FORM_URLENCODED` | ✅ 一字不差 | +| 登录参数 | `account`/`password`(hex)/`grant_type=password` | `AuthApi.LoginParams` 同三字段 | ✅ 一字不差 | +| 口令密文 | `cipher.ts` md5→AES-256-ECB-PKCS7(key=`md5("EY8WePvjM5GGwQzn")`)→hex | 官方 `DesUtil`+`SecurityProperties` | ✅ 逐字节等价 | +| 返回 | `{token,expiresIn,tokenTypeName}` | 同形 | ✅ | +| 登出码 | 600/601/602 → 清 token 跳 login | 官方 `ResultEnum.TOKEN_ERROR/TOKEN_LOGGED/TOKEN_TIMEOUT` | ✅ 1:1 | +| 信封 | `ActionResult{code,msg,data}` | 官方 `transformResponseHook` 取 `{code,msg}`,`code===ResultEnum.SUCCESS` 才过 | ✅ 1:1 | +| 请求头 | `App-Code` / `Jnpf-Origin: pc` | 官方多 `Vue-Version: 3` + `K1`(RSA 加密的 aesKey) | ⚠️ MVP 少 K1(无 body 级 AES) | + +⇒ **认证层 MVP 就照官方契约写 ⇒ 集成时几乎零改**,只需补 `K1` 头 + body 级 `useCipher`。 + +### 「除了认证」的具体边界 + +- **MVP 做**:#1~#5(后端 entity/service/controller/module/app.module)+ #6~#7(前端 `api/*.ts` 薄壳 + `views/*.tsx` 原型) + + **认证全套**(登录页 / 会话 / cipher / 请求层)。 +- **集成期做**:#8/#9 的官方等价物(jweb 按菜单自动注册路由、菜单挂载)+ 权限配置 UI + 低代码表单 + 数据建模页 + 官方 Vue 三件套。 +- ⇒ 官方 vue **本批完全不碰**。 + +### 本轮改动 + +- `HANDOFF.md` §0-ter:ASCII 路线图前端行改为「React 模板(AI 友好薄壳)」+ + 「🔴 前端在两阶段分别是什么」整节重写(对比表 + 认证证据链表 + 两技能 diff 实测 + 9 接触点对照表)。 +- `HANDOFF.md` §3 批次 12 ④:前端交付物校准为 **React 三件套** `new-page.sh` + **移植** React 技能的 `check-module.sh`; + 「明确不做」改为「官方 Vue 脚手架是集成期的事」。 +- `HANDOFF.md` §3 护栏表第 10 条、§0-bis 20:10 补充段、HANDOFF 顶部「更新于」同步。 +- 🔴 **顺手纠正的路径错误**:官方前端实际业务代码在 + `~/Desktop/workspace/jnpf/jnpf-web-apps-main`(其 `src/api/request.ts` = `defHttp` 定义处, + 164 行,`transformResponseHook` + `addRequestInterceptor` 三个头 + `K1`), + **不是** `~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework`(那是前端框架,无 defHttp)。 + ⇒ 集成期做 `--fe-root` 时要指对目录。 + +--- + +## 2026-11-01 晚:批次 12 收尾(前端三件套 + 计时假数据纠正) + +### 🔴 最重要的发现:过去那张「闸门耗时表」大半是**执行环境的错** + +沙箱/助手 bash 会把 `grep` `sed` `cat` `wc` 换成**转发壳** +(PATH 指向 `…/shim/brokered-bin/<命令>`,**每次启动 ≈0.19s**), +经 `BASH_ENV` 注入每个 bash 子进程。本仓闸门是「几百次 grep」的形态 ⇒ 被逐条累加。 + +| 闸门 | 旧数字(壳环境) | 普通终端 | 倍数 | +|---|---|---|---| +| check-contract | 66.6s | **3.2s** | 21× | +| check-module | 25.8s | **1.4s** | 18× | +| check-boundary | 7.2s | **1.5s** | 4.8× | +| check-citations | 5.2s | **4.0s** | 1.3× | + +⇒ 教训已落进代码:`verify.sh` 现在先探测 `command -v grep` 是否落在 `*/shim/*`, +命中就打印告警「下面的耗时被放大数倍,别用来判断闸门快不快」。 +**耗时不标注环境 = 假数据**。判断真实耗时要 `env -u BASH_ENV PATH=/usr/local/bin:/usr/bin:/bin:…`。 + +### 真·算法优化(与 shim 无关,换机器也有效) + +1. `check-contract-scan.py` 新增 `_fn_positions()`:原来「查一个 handler 就在**整份文件**跑一遍 + `re.search`」(362 次,1.4s)⇒ 改成每份文件只扫一遍建 `名字→位置` 表 ⇒ 1.4s → 0.15s。 +2. `check-citations-scan.py` 新增 `_lookups()`:原来「每条引文遍历该根下**全部文件**做 + `rel.endswith`」⇒ 实测 **1008 万次 endswith**(1.7s)⇒ 改成后缀/基名倒排表,O(1)。 +3. `verify.sh` 的 `now()` 从「每步 3 次 python3」改成 `date +%s%N` + bash 整数运算 + ⇒ 8 步省 ≈2.9s(这 2.9s 不属于任何一步,却计进总耗时 ⇒ 会让人误判闸门慢)。 +4. `self_test` 里第一跑 `analyze` 复用 `code_snapshot`(原来白扫一次全仓 0.4s)。 + +**结果**:`verify.sh --fast` 23.1s → **≈15s**(14.6/14.7/15.2/15.5 四次),`--lib` 23.5s,全绿。 + +### 前端三件套(批次 12 唯一还没做的一环) + +- `src/frontend/` 从 `ssw-jnpf-lite-react` 只复脚手架本体(23 文件,不含技能文档)。 +- `scripts/new-page.sh ` + `scripts/new-page-gen.py`:真源 = 契约 `[MODULE]` + (urlAddress/apiFile/menuId→fullName)+ 表 DDL 列(自动滤平台列)。**不猜**,契约没登记就拒绝。 +- 已生成 `asset/DataResource` 三件套(api/dataresource.ts + views/DataResource.tsx + App.tsx 路由)。 +- 🔴 **两个坑**:① vite proxy 模板指 NestJS `:30000`,本仓 Rust 后端是 **`:30010`**(否则前端全 502, + 表现成 Network Error,最易误判成跨域);② api 文件名 = `lower(Entity)` ⇒ `dataresource.ts` + **全小写**,改约定必须同时改尺子。 +- `check-module.sh` 前端接触点从 `⏭` 变真检查 ⇒ 断言 **114 → 123**,契约 `[RULER]` 已同步 + (尺子自证会逼你显式登记新条数,这就是它该有的作用)。 +- 验证:`npm install`(98 包) + `tsc --noEmit` rc=0 + `vite build` 成功(307KB)。 +- **仍未做**:前端没有运行时闸门(刻意不进 `verify.sh`,零 node 依赖是它的定位); + `new-pack.sh` 没做(后端加包仍手写 3 个文件)。 + +--- + +## 2026-11-01 夜:批次 12.5 —— 加包变一条命令,漏接变直接报错 + +### 问题 +批次 12 把 spec 搬进包之后,加模块仍要手抄 5 个后端文件 + 改 4 处内核登记。 +其中两类漏接**不报错**:漏 `merge` ⇒ 面 B 静默 404;漏 `ALL_MENUS` ⇒ 菜单不种 ⇒ 守卫 +查不到菜单 ⇒ **越权放行**。 + +### 做法:把「内核怎么知道有这个包」从手写改成生成 +- 统一包出口约定:每个包导出 `pub struct Pack` + `pub const DDLS: &[(&str,&str)]` + ⇒ 生成器只需知道「目录名 + crate 名」。 +- `sspf_plugin::load_static()`:manifest 解析 + `PackSource` + `merge` 收进插件层 + ⇒ `bootstrap.rs::load_packs()` 只剩一行。 +- `scripts/pack-sync.py` 现在生成**四处**:`packs_gen.rs`(整文件)、 + `modules/mod.rs` 五段(`// >>>GEN:` 标记)、`Cargo.toml` 的 `# >>>GEN:PACK_DEPS`、 + `contract.md` 三段。`--check` 覆盖全部四处。 +- 🔴 面 A 端点也纳入生成(`[ENDPOINT]`)—— 否则新模块的 3 条面 A 没人登记, + CC2 立刻红「契约 382 / 代码 385」。 +- `scripts/new-pack.sh` + `new-pack-gen.py`:一条命令生成 5 个后端文件, + 跑 pack-sync,可选 `new-page.sh`;`[RULER]` 条数**实跑 check-module 后自动登记** + (只允许变大,变小=有人删断言 ⇒ 拒绝)。 + +### 抓到并修掉的 2 个真 bug(都是「加第二个包」才显形) +1. 🔴 `check-contract-scan.py::guard_of_module_with_pack_fallback` 原来 + `for pkg in sorted(pack_orig)` 取**第一个包** ⇒ 有 asset+probe 时 probe 的面 A 守卫 + 被推成 `asset/DataResource` ⇒ **CC6 假飘移 3 条**(人会去改对的契约)。 + 改成按 `app` 精确匹配,查不到返回「推不出」。 +2. 🔴 加包误报 3 个单测(`asset_pack_loads` / `pack_router…` / `health == 52`)—— + 全是写死计数的**假闸门**。改成结构性断言(每实体:有 DDL + 有菜单 + 3 条路由; + health 表数 = `ddl_tables().len() + packs.ddls.len()`)。 + +### 验证(在 `/tmp` 仓库副本里跑,避免污染工作区) +`new-pack.sh probe Widget ... --with-frontend` ⇒ 写 5+3 个文件 + 5 处生成位置; +`cargo build` ✅ 3.7s;`cargo test -p sspf-pack-probe` 13 ✅;`ssw-platform --lib` 102 ✅; +`pack-sync --check` 幂等 ✅;`verify.sh --fast` 全绿 **17.2s**。 +反自证:删 `packs_gen.rs` 的 probe 块 / 删 `mod.rs` 的 `probe::WIDGET_MENU` +⇒ `--check` 都 rc=1 并指名文件。 + +### 教训 +**「生成物 + `--check`」是治「漏一处就静默」的通用解**:不是靠文档提醒,是让漏接变成红。 +前提是生成段有稳定标记、且 `--check` 放在 `verify.sh` 第一步(否则别的闸门会先报一串假飘移)。 diff --git a/CLAUDE.md b/CLAUDE.md index ffae9ea..a6924f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -136,8 +136,14 @@ ssw-platform/ ``` **核心不变量**: -- **平台层 / 业务层分离**:加业务模块只碰 `src/modules/`(新文件 + `mod.rs` 登记),平台层一个字不改。 - 两层唯一接头点是 `bootstrap.rs`。 +- **平台层 / 业务层分离**:加业务模块**一条命令** + (`bash scripts/new-pack.sh --name "…" --columns "a:TYPE"`),平台层一个字不改。 + 两层唯一接头点是 `bootstrap.rs`,而它读的是**生成**的包清单 `src/backend/src/packs_gen.rs` + (真源是 `packs/*`)。 +- **四处内核接线是生成的**(`packs_gen.rs` / `modules/mod.rs` 五段 / `Cargo.toml` 依赖段 / + `contract.md` 三段),由 `scripts/pack-sync.py` 从 `packs/*` + `modules/*.rs` 推出。 + **手改会被覆盖**,而 `verify.sh` 第一步 `pack-sync.py --check` 会把「忘了同步」判红 + —— 因为漏同步的后果是**静默 404 / 越权放行**,不是编译错误。 - **双面契约同一进程**:面 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`)。两套数据源不同,别混。 diff --git a/HANDOFF.md b/HANDOFF.md index f5151ea..5a200a7 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -1,6 +1,8 @@ # HANDOFF —— 交给下一个 session 的现场交接 -> 更新于 2026-11-01(面 B 批次 11 收尾)。**开工先读这一页**(尤其 §0-bis 缺口全景),再读 `CLAUDE.md`(硬约定), +> 更新于 2026-11-01 19:00(面 B 批次 11 收尾 + **批次 12 方向决策**), +> **20:10 追加「前端 MVP 用 React 模板、除了认证其它都留给集成阶段」**。**开工先读这一页** +> (尤其 **§0-bis 的「下一轮的优先级改了」**),再读 `CLAUDE.md`(硬约定), > 最后看 `.workbuddy/memory/` 最近一天的日志(踩过的坑)。 > 无人值守时不要问用户,选最保守可行的方案继续,并把决策写回本文件。 @@ -15,6 +17,156 @@ --- +## 0-ter. 🔴🔴 两阶段开发路线(这是全局路线,先看这条) + +**用户定的路线**(2026-11-01 19:39 明确): + +``` +┌─ MVP 阶段 ─────────────────────────────┐ ┌─ 规范集成阶段 ──────────────────┐ +│ 用 ssw-jnpf-lite-rust 技能开发 │ │ 迁到标准 JNPF 框架集成开发 │ +│ 「AI 怎么快怎么来」 │ → │ 遵守官方规范 │ +│ 后端 = Rust(axum) 单二进制 │ │ 后端 = 标准 JNPF Java │ +│ 前端 = React 模板(AI 友好薄壳) │ │ 前端 = 官方 JNPF vue(原生) │ +│ └ 只做「认证 + 业务规则原型」 │ │ └ 补齐权限配置/低代码/建模等全套 │ +│ └ 其它全部留给集成阶段 │ │ │ +│ 目的:把业务快速跑通、把业务规则试出来 │ │ 目的:按官方规范固化、可维护 │ +└────────────────────────────────────────┘ └─────────────────────────────────┘ + ↘ 仅「部分终端设备不佳」的场景保留 Rust 后端 +``` + +🔴 **前端 MVP 用 React、不是 Vue**(2026-11-01 用户纠正): +「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向, +**除了认证,其它都留给集成阶段**」。 +⇒ **官方 vue 是集成阶段的事**;MVP 前端是 **React 薄壳**(两个技能的 React 前端**逐字节相同**)。 +详见下面「🔴 前端在两阶段分别是什么」。 + +🔴 **两阶段的分界线不是「时间」,是「契约忠实度」**: +MVP 阶段允许**形状有偏差**(官方前端能跑、能试业务就行)⇒ 换来速度; +集成阶段要求**逐字对齐官方规范** ⇒ 换来可维护性。 +⇒ **MVP 阶段的每一处「快」,都要在集成阶段还债。** 本文件就是那本账。 + +### 🔴 MVP 阶段「快」的真实代价(2026-11-01 19:40 实测,非推测) + +官方端点台账(`docs/contract.md` 附录 A 的 `[OFFICIAL]`,379 条)的忠实度分布: + +| status | 条数 | 含义 | 集成阶段怎么办 | +|---|---|---|---| +| `implemented` | **338** | 已落地且**形状对齐** | ✅ 直接搬 | +| `partial` | **27** | 已落地但**形状有偏差** | 🔴 **要还债**(下面逐条列) | +| `absent` | **7** | 未实现 | 集成时补(官方现成) | +| `oos` | **6** | 明确不做 | 集成时按官方做 | + +⇒ **MVP 阶段真正的债 = 那 27 条 `partial`**。它们分三类: + +| 类 | 条数 | 特征 | 集成时的动作 | +|---|---|---|---| +| **① 临时欠**(本仓没这能力,官方有) | **14** | 导出/导入/测试连接/打印渲染 —— **恒 `400` + 人话**(本仓无文件服务 / 无外部驱动 / 无渲染引擎) | **删掉本仓实现,用官方的** ⇒ 几乎零成本 | +| **② 形状欠**(语义对,VO 不逐字) | **9** | 如 `CurrentUser` 的 `sysConfigInfo` 返 `{}`、按钮级权限恒空、`permissionList` 粒度不同 | 🔴 **要真对齐**(前端依赖这些字段)⇒ 这类是**主要工作量** | +| **③ 自造**(本仓自己发明的) | **4** | 如 `f_en_code` 用本仓自定占位(`permission.demo` 等)、`deleteAllTable` 有意收窄 | 🔴 **改成官方编码 / 官方语义** | + +⚠️ **②③ 共 13 条是真债**(要写代码),**① 14 条是假债**(删了换官方的就行)。 +⇒ **MVP 阶段真正该盯的是那 13 条**,不是 27 条。这是「快」能快到什么程度的**精确边界**。 + +### 🔴 MVP 阶段的四条红线(违反了 = 集成时返工) + +1. 🔴 **业务表的 `base_*` 列名不许自创** —— 官方 `base_*` DDL 逐字(`JNPF-PostgreSQL.sql` 13227 行 / 331 张表,本机已有) + ⇒ 业务表 DDL 从一开始就照官方列名写 ⇒ 集成时**只导数据不导结构**。 +2. 🔴 **业务表的 `f_tenant_id` 不许省**(值恒 `"0"`,但列 `NOT NULL` 且参与复合主键 `(f_id, f_tenant_id)`)。 +3. 🔴 **接口路径从第一天就用官方形状**(面 B 的 `/api/xxx/...`)⇒ 集成时**前端零改**。 + ⚠️ 面 A 路径(`/api/ssw/...`)是本仓自造的 ⇒ **集成时全部作废**,只留给 Rust 终端场景。 +4. 🔴 **返回形状宁可少字段,不许返错形状** ⇒ 官方前端遇到缺字段会**静默降级**(按钮恒显、树空)。 + +### ✅ 已经到位的部分(集成时直接搬,别重做) + +| 项 | 证据 | 集成时 | +|---|---|---| +| `base_*` 表名/列名逐字对齐官方 | `schema.sql` 48 张 `base_*` | ✅ 只导数据 | +| 口令 cipher 逐字节等价 | `cipher.rs` 检验向量 + 官方 `DesUtil` | ✅ 换算一次(`MIGRATION.md` §7) | +| 响应信封 `ActionResult{code,msg,data}` | `envelope.rs` ↔ `jnpf.base.ActionResult` | ✅ 零改 | +| 实体 spec ↔ Java 实体 | `EntitySpec` 的列清单 ≈ 一个实体类 | ✅ 照 `MIGRATION.md` §2.1 翻译表 | +| 权限判据 | 面 B 已按 `f_en_code`(官方 `@SaCheckPermission` 的判据) | ✅ 零改 | +| 官方前端能直连本仓 | 面 B 契约 + `Vue-Version: 3` 判别头 | ✅ 集成时**前端几乎零改** | +| 官方前端加页面的机制 | `router/routes/index.ts` 用 `import.meta.glob('./modules/**/*.ts')` + `mergeRouteModules`(读 `default` 导出)⇒ **放文件进目录即注册**,不改配置 | ✅ 集成期把打磨期的页面搬进 `modules/` 目录即可 | + +### 🔴 前端在两阶段分别是什么(2026-11-01 19:39 修正 + 20:10 按 React 模板重写) + +> 🔴 **上一版这里写错了**:当时写「MVP 阶段前端 = 官方 JNPF vue(零改直连面 B)」。 +> **用户已纠正**(原话:「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向, +> **除了认证,其它都留给集成阶段**」): +> **MVP 阶段的前端 = React 技能模板,不是官方 vue**。官方 vue 是**集成阶段**的事。 + +| | MVP 阶段(AI 怎么快怎么来) | 集成阶段(按官方规范) | +|---|---|---| +| 前端代码 | **React + Vite**(`ssw-jnpf-lite-react` / `ssw-jnpf-lite-rust` 技能里的 `src/frontend`) | **官方 JNPF Vue**(`~/Desktop/workspace/jnpf/jnpf-web-apps-main`) | +| 后端对接 | 面 A `/api/ssw/...`(Rust/NestJS 自造约定)⇒ **前端零改直连** | 面 B `/api/{模块}/{资源}/...`(官方形状)⇒ **前端零改直连** | +| 认证 | ✅ **MVP 就做**(见下「认证为什么例外」) | ✅ 换成官方 `jnpf-oauth`,**路径/返回同形** | +| 业务页面 / 权限配置 UI / 低代码表单 / 数据建模页 | ❌ **不做**(只留最小原型) | ✅ 全做(官方有现成的) | +| 价值 | 业务规则能马上试出来、改一行刷新就看到 | 按官方规范固化、可维护 | + +🔴 **一句话**:**MVP 前端 = 「能登录 + 能试业务规则」的薄壳**, +不是「一个 JNPF 前台」。**除了认证,其余全部留给集成阶段**。 + +#### 🔴🔴 认证为什么是唯一的例外(2026-11-01 20:10 实测,证据链完整) + +认证是**唯一不能推迟**的部分——没有它就**连业务都试不了**(登录不进 ⇒ 看不到列表 ⇒ 试不了规则)。 +而认证恰好也是**迁移时最不容易出错**的部分,因为它**契约已经完全对齐官方**: + +| 环节 | MVP(React 模板) | 官方 | 结论 | +|---|---|---|---| +| 登录端点 | `POST /api/oauth/Login`(`x-www-form-urlencoded`) | `api/core/auth.ts`:`Api.Login = '/api/oauth/Login'` + `ContentTypeEnum.FORM_URLENCODED` | ✅ **一字不差** | +| 登录参数 | `account` / `password`(密文 hex) / `grant_type=password` | `AuthApi.LoginParams`:同样三个字段 | ✅ **一字不差** | +| 口令密文 | `cipher.ts`:`md5(plain)` → AES-256-ECB-PKCS7(key=`md5("EY8WePvjM5GGwQzn")`) → hex | 官方 `DesUtil` + `SecurityProperties` | ✅ **逐字节等价**(检验向量 `encryptPassword('123456')` = `d4958348e...cdc02b`) | +| 登录返回 | `{ token, expiresIn, tokenTypeName }` | 官方同形 | ✅ | +| 登出码 | `600/601/602` → 清 token 跳 `/login` | 官方 `ResultEnum.TOKEN_ERROR / TOKEN_LOGGED / TOKEN_TIMEOUT` 分支 | ✅ **语义 1:1** | +| 响应信封 | `ActionResult{code,msg,data}`,`code!==200` → reject | 官方 `transformResponseHook`:`{code,msg}` + `code===ResultEnum.SUCCESS` 才过 | ✅ **1:1** | +| 请求头 | `App-Code` / `Jnpf-Origin: pc` | 官方 `client.addRequestInterceptor`:三个头 + `K1`(RSA 加密的 aesKey) | ⚠️ MVP 少 `K1`(无 body 级 AES) | + +⇒ **认证层在 MVP 阶段就照官方契约写** ⇒ 集成时**认证这块几乎零改**, +只需要把 `K1` 头和 body 级 `useCipher` 补上(官方 `AesEncryption` 走 `requestOptions.useCipher` 开关)。 + +#### 🔴 关键实测:**两个技能的 React 前端逐字节相同**(2026-11-01 20:05) + +```bash +$ diff -rq skills/ssw-jnpf-lite-react/src/frontend/src skills/ssw-jnpf-lite-rust/src/frontend/src +# 无输出 ⇒ 完全一致 +$ diff react/src/frontend/vite.config.ts rust/src/frontend/vite.config.ts +# 唯一差异:proxy 端口 30000(NestJS) vs 30010(Rust) +``` + +⇒ **「React 前端 MVP 模板」是独立资产,与后端选 Rust 还是 NestJS 无关**: +换后端栈**前端一个字都不用动**(契约同形)。 +⇒ **这不是巧合,是设计**:两个技能刻意共用同一套前端, +就是为了让「先 NestJS 后 Rust」或「先 Rust 后官方 Java」的迁移路径上,前端永远零改。 + +⇒ **本仓(ssw-platform)的选择**:**MVP 后端用 Rust(axum),前端用这套 React 模板** +⇒ 直接从 `ssw-jnpf-lite-rust` 复制 `src/frontend` 即可(与 React 技能逐字节相同)。 + +#### 🔴 认证之外的「9 个接触点」在 React 模板里的位置(集成期要搬到 Vue) + +React 模板的加模块成本 = **改/加 8 个文件、15~20 分钟**(`HOWTO_MODULE.md` §〇.5): + +| # | 文件 | React 模板 | 集成期搬到官方 Vue | +|---|---|---|---| +| 1 | `src/backend/src/{app}/xxx.entity.ts` | ✅ MVP 做 | 翻译成 Java 实体(`@TableName` + `SuperEntity`) | +| 2 | `src/backend/src/{app}/xxx.service.ts` | ✅ MVP 做 | 翻译成 `SuperServiceImpl` | +| 3 | `src/backend/src/{app}/xxx.controller.ts` | ✅ MVP 做 | 翻译成 `BaseCrudController`(`references/BaseCrudController.java`) | +| 4 | `src/backend/src/{app}/xxx.module.ts` | ✅ MVP 做 | 换 Maven 多模块 `ssw.{appCode}.xx.xx` | +| 5 | `src/backend/src/app.module.ts`(**两处**) | ✅ MVP 做 | ❌ 集成期删除 | +| 6 | `src/frontend/src/api/xxx.ts` | ✅ MVP 做(3 个 export) | 翻译成 `api/<模块>.ts`(`defHttp.get/post/delete`) | +| 7 | `src/frontend/src/views/Xxx.tsx` | ✅ MVP 做(原型) | 翻译成 `views/<模块>/index.vue` | +| 8 | `src/frontend/src/App.tsx`(+1 ``) | ✅ MVP 做 | ❌ 集成期删除(官方按菜单自动注册路由) | +| 9 | `src/backend/src/sys/seed.service.ts`(`menus[]` +1 行) | ✅ MVP 做 | 数据 ETL 导进 `base_module` | + +⇒ **「除了认证其它都留给集成阶段」的准确含义**: +**MVP 只做 #1~#5(后端)+ #6~#7(前端薄壳)**, +**#8/#9 的官方等价物(路由自动注册、菜单挂载)集成期才做**, +**权限配置 UI / 低代码表单 / 数据建模页这些官方现成能力,MVP 完全不碰**。 + +⚠️ **注意**:`check-module.sh` 的前端 4 个接触点在本仓**全打 `⏭`** ⇒ +**前端目前没有任何闸门保护** ⇒ 集成前必须补(见 §3「批次 12」的 ④)。 + +--- + ## 0-bis. 📊 缺口全景(2026-10-31 05:00 全量摸底,看这里决定下一步) 用 `/tmp/fe-scan/scan.py` 扫前端 `src/api/**`(741 条端点定义,先解 `enum Api` 再解析 @@ -102,6 +254,101 @@ `extend`(64) / `msgCenter`(50) —— **基本都属于「本仓没这个模块」**。 (🔴 批次 9 收尾时此处写的 252/28.0% 是**批次 8 的旧数**,实测 291/32.3%,此处已更正。) +### 🔴🔴 下一轮的优先级改了(2026-11-01 19:00 决策,19:39 补充两阶段路线) + +**批次 12 不再是「补端点」,改成「把框架打成固定包 + 业务模块链接就好」。** +理由:端点补到 331/900 后,剩下的**大半是「本仓没这个模块」**(做了也是恒空 stub); +而**每加一个业务模块要改 6~8 处、手抄两份 spec、手抄 DDL、手抄契约表** —— 这个成本 +才是「成熟框架 + 极简业务代码」的真实瓶颈。 +⇒ 详见 §3「批次 12」的完整方案(4 项交付物 + 7 条护栏 + 5 条验收判据)。 + +🔴 **19:39 补充**:用户明确了**两阶段路线**(MVP 用 Rust 技能「AI 怎么快怎么来」→ +业务定型后迁标准 JNPF 集成开发,Rust 只在「部分终端设备不佳」的场景保留)。 +⇒ **这改变了批次 12 的优先级排序**:批次 12 的四项交付物**全部服务于 MVP 阶段的速度**, +但**每做一项都要留下「集成时能还债」的痕迹** ⇒ 详见 §0-ter 的「四条红线」与 §3「批次 12」 +的「集成期友好性」验收项。**不是「先快后补」,是「快的同时记账」。** + +🔴 **20:10 补充(前端方向定案)**:用户指明 **`ssw-jnpf-lite-react` 模板就是前端 MVP 阶段 AI 友好的方向**, +并划定了边界:**「除了认证,其它都留给集成阶段」**。 +⇒ **前两版关于前端的表述都是错的**(先写「官方 vue 零改直连面 B」,后写「前端全程在官方 monorepo」) +⇒ 现在定案:**MVP 前端 = React 模板**(**认证做全套**,业务页面只做薄壳原型), +**官方 vue / 权限配置 UI / 低代码 / 数据建模 = 全部留给集成阶段**。 +⇒ 🔴 **实测支撑**:两个技能的 `src/frontend` **逐字节相同**(仅 vite proxy 端口不同) +⇒ 前端是**独立资产**,与后端选 Rust 还是 NestJS 无关 ⇒ 换后端栈前端零改。 +⇒ 详见 §0-ter 的「🔴 前端在两阶段分别是什么」。 + +**同时测出「快验证」的成本分布**(2026-11-01 19:00 实测,勿凭印象改): + +| 类别 | 闸门 | 耗时 | 备注 | +|---|---|---|---| +| 静态 | `check-contract.sh` | **66.6s** 🔴 最慢 | 静态解析 659 个路由 ⇒ 提速首要目标 | +| 静态 | `check-module.sh` | 25.8s | | +| 静态 | `check-boundary.sh` | 7.2s | | +| 静态 | `check-citations.sh` | 5.2s | | +| 静态 | `check-naming.sh` | 3.6s | | +| 静态 | `check-arch.sh` | 1.6s | | +| 运行时 | `perm-smoke.sh` | 6.0s | 起隔离后端 | +| 运行时 | `perm-smoke-jnpf.sh` | 4.8s | | +| 运行时 | `baseline-smoke.sh` | 3.3s | | +| 运行时 | `mcp-smoke.sh` | 2.9s | 34 + 14 两段 | +| 运行时 | `lowcode-smoke.sh` | 1.9s | | + +⇒ **静态闸门合计 ~110s,运行时合计 ~19s** ⇒ 「快速验证」的瓶颈在**静态闸门**, +不在起后端。批次 12 的 ④ 就是治这个(增量扫描 + `scripts/verify.sh` 一条命令)。 + +### 🔴 2026-11-01 22:00 复核:上面那张表**大半是「转发壳」的错**(结论已修正,别再按它排优先级) + +同一套闸门在**普通终端**里只要表里数字的 **1/2 ~ 1/20**。原因不在代码,在**执行环境**: +沙箱 / AI 助手的 bash 会把 `grep` `sed` `cat` `wc` 换成一个**转发壳** +(PATH 指向 `…/shim/brokered-bin/<命令>`,**每次启动 ≈0.19s**)。而本仓闸门正是 +「几百次 grep」的形态 ⇒ 0.19s × N 被逐条累加,看起来像「脚本写得慢」。 + +| 闸门 | 旧表(转发壳环境) | 普通终端实测 | 倍数 | +|---|---|---|---| +| `check-contract.sh` | 66.6s | **3.2s** | 21× | +| `check-module.sh` | 25.8s | **1.4s** | 18× | +| `check-boundary.sh` | 7.2s | **1.5s** | 4.8× | +| `check-citations.sh` | 5.2s | **4.0s** | 1.3× | +| `check-naming.sh` | 3.6s | **2.0s** | 1.8× | +| `check-arch.sh` | 1.6s | **1.7s** | 1× | + +⇒ 旧表里「`check-contract` 66.6s→55.0s→8.2s」那几轮优化,**有一半是壳的功劳**, +换台普通终端重跑就没了。**只有纯算法改动才是真的**——2026-11-01 晚做掉的两处: + +| 改动 | 真实收益 | 原理 | +|---|---|---| +| `check-contract-scan.py`:**函数体位置索引** `_fn_positions` | 1.4s → 0.15s(单次分析) | 原来「查一个 handler 就在**整份文件**上跑一遍 `re.search`」(362 次)⇒ 改成每份文件只扫一遍、建 `名字 → 位置` 表 | +| `check-citations-scan.py`:**引文后缀倒排表** `_lookups` | 1008 万次 `endswith` → 0 | 原来「每条引文遍历该根下**全部文件**做 `rel.endswith("/"+路径")`」⇒ 建成 `后缀 → 文件` 倒排表,查询 O(1) | + +⇒ **教训(已写进 `scripts/verify.sh`)**:`verify.sh` 现在会先探测 `command -v grep` +是否落在 `*/shim/*` / `*/brokered-bin/*`,命中就打印醒目告警—— +**「耗时不标注环境 = 假数据」**,假数据会让人去优化根本不存在的问题。 + +**当前真实数字(普通终端,`bash scripts/verify.sh --fast`)**: + +``` +契约生成段同步(pack-sync --check) 0.1s +编译(cargo build --offline) 0.3s +静态闸门 check-arch 1.7s +静态闸门 check-boundary 1.5s +静态闸门 check-naming 2.0s +静态闸门 check-module 1.4s +静态闸门 check-contract 3.2s +静态闸门 check-citations 4.0s +────────────────────────────────────────── +总耗时 14.6s(8 个步骤,全 ✅) ⇒ 批次 12 的「≤15s」目标**达成** +``` + +⚠️ **同一台机上 4 次实测是 14.6 / 14.7 / 15.2 / 15.5s**(机器负载不同,差 1s 量级) +⇒ 引用时说 **≈15s**,别把 14.6 当恒定值;也**别**为了「好看」去砍 `check-citations` +的断言——它 4.0s 里 2.6s 是**沙箱代理的文件读**(`socket.recv`),代码侧只剩 0.6s, +再优化就是跟执行环境较劲,不是跟算法较劲。 + +`--lib`(外加 `cargo test --workspace --lib`)= **23.5s**(单测 8.8s,103 passed)。 + +⚠️ 同一个 `verify.sh` 在转发壳环境里仍会打印 36.1s —— 但开头会先警告「本环境的 grep +被转发壳接管」,看到这行就别拿那个数字做判断。 + --- ## 1. 一句话现状(2026-11-01 批次 11 收尾) @@ -129,13 +376,22 @@ 高级查询方案共 31 条端点 —— 这是「权限」页配权限的后端地基,见 §1「批次 10」小节。 - 🔴 **数据权限三件套落地了**(批次 11):数据权限字段 / 数据权限方案 / 数据连接共 15 条端点 —— 见 §1「批次 11」小节。 +- 🔴 **「业务包」目前是死的**(2026-11-01 19:00 实测,下一轮要治): + `packs/asset` **只依赖 sdk、能独立编译**,但**内核根本没装载它** —— + `routes.rs` 只 merge 了 `modules::router()`,且 `sspf-sdk` 的 `BusinessPack` + **没有 `routes()` 方法**(只有 manifest/entities/menus/metadata/hooks)。 + ⇒ 业务 spec 在 `modules/asset.rs` 与 `packs/asset/src/lib.rs` 里是**两份逐字拷贝**, + 且**没有任何闸门比对它们**(`check-arch.sh` 只有 AR1–AR7 + MEM1–MEM2, + `packs/asset` 注释里写的「PACK1 会比对」**至今未实现**)。 + ⇒ 这就是批次 12 要解决的核心问题(详见 §3「批次 12」)。 **✅ 后端已拆成 workspace 多 crate,业务包可独立编译;十二道闸门全绿;空载内存 8 MB。** - 新增 `crates/sspf-contract`(契约层,无 axum)、`crates/sspf-sdk`(业务包唯一依赖)、 `packs/asset`(样板业务包,只依赖 sdk,能 `cargo test -p sspf-pack-asset` 独立跑)。 + 🔴 **但业务包与内核尚未接线**(见上面「业务包目前是死的」)。 - `rust-toolchain.toml` 全仓锁 **1.95.0**(L3 动态库 ABI 一致性强依赖;本机代理限速装不上 1.99)。 -- 新增两道闸门:`scripts/check-arch.sh`(AR1–AR5 + MEM1–MEM2,带 `--self-test`)、 +- 新增两道闸门:`scripts/check-arch.sh`(AR1–AR7 + MEM1–MEM2,带 `--self-test`)、 `scripts/mem-budget.sh`(空载内存实测,用 `vmmap`,**本机沙箱禁 ps/top**)。 - 内核 `platform/{envelope,entity,menu,ids}.rs` 已改为 re-export 契约层 ⇒ 引用路径零变化。 - `cargo test --workspace` = **240 条**(不是 221/230 了,拆 crate 后数字会变,别写死)。 @@ -748,10 +1004,364 @@ xop run --secret GU=git_local_user --secret GP=git_local_pass -- bash -c ' **create 用 `fieldRule!=0`、update 用 `fieldRule==1`**;delete 比对用**带前缀**的码。 🔴 **方案列表只需登录**(官方没加 `@SaCheckPermission`)。 🔴 `FieldList` / 表字段端点依赖低代码表单与数据库内省 ⇒ **诚实返回空**(不假装)。 +12. 🔴🔴 **【批次 12 = 下一轮优先做】框架固定包 + 业务模块链接就好** + —— 不是补端点,是**改「加业务的成本结构」**:加一个业务模块从现在的 + **改 6~8 处**(两份 spec 拷贝 + 手抄 DDL + 手抄契约表 + 改 `schema.sql` + + 改 `main.rs` BASE_TABLES + 改 `sspf-store/db.rs` 两处表数断言) + 降到 **写 1 个包文件 + 改 2 处**。 + 🔴 **四件事**:① `sspf-sdk` 补 `routes()` + 新建 `crates/sspf-plugin`(L2 静态装载器) + ② 打通两份拷贝(`modules/asset.rs` 改 re-export)+ **补 PACK1 闸门** + ③ 业务 DDL 跟着包走(不再手抄 `schema.sql`)+ 表数断言去写死 + ④ 契约登记**自动生成** + 静态闸门**增量提速** + 新增 `scripts/verify.sh` 一条命令。 + 🔴 **明确不做**:L3 dylib 动态库 / WASM 执行器 / `pack export-import` 双向迁移 + (见该节「明确不做」)。完整方案见下方「批次 12」小节。 + ⚠️ **前端**:本仓 `src/frontend` **是空的**(后端-only)⇒ vue 前端那条诉求 + **不在本仓范围**;官方 JNPF monorepo **本身就是那个「固定包」**(前端零改跑在本仓后端上)。 + ⇒ 若要做前端侧「页面脚手架」,需**先确认产品边界**(候选:仿 `new-pack.sh` 做 `new-page.sh`)。 -**下一个(批次 12)**:`fe-gap` 余下最大的 `system` 55 条 / `permission` 26 条 / -`systemData` 32 条里挑**有官方 `base_*` 表支撑**的;`workFlow`(104) / `onlineDev`(101) / -`aiCenter`(75) / `extend`(64) / `msgCenter`(50) 基本都是「本仓没这个模块」⇒ +### 🔴🔴 批次 12(下一轮优先做)—— 「框架固定包 + 业务模块链接就好」 + +> **这一批不是补端点,是改「加业务的成本结构」。** 目标形态: +> **平台层(面 A/B 契约 + 权限 + 低代码 + MCP)打成一块相对固定的底座**, +> **新业务模块只写 spec + 一行注册**,不碰平台层、不重复拷贝、不手抄 DDL、不手抄契约表。 +> 完成后「加一个业务模块」从现在的**改 6~8 处**降到**写 1 个文件 + 改 2 处**。 + +🔴 **本批必须同时满足两个目标(2026-11-01 19:39 追加)**: +**MVP 阶段**(Rust 技能,AI 怎么快怎么来)**要快** ⇒ 上面四项交付物; +**集成阶段**(迁标准 JNPF,规范开发)**不能欠债** ⇒ 每项交付物都要**留下可还债的痕迹**。 +⇒ **判据不是「这批做完没」,是「集成时要还的债有没有变少」。** +本批**直接消灭的债**:那 **27 条 `partial`** 里,属于「自造」的 **4 条**会随 ①③ 的重构消失 +(`f_en_code` 自定占位 → 改官方编码;`deleteAllTable` 收窄 → 改官方语义)。 + +#### 现状体检(2026-11-01 19:00 实测,勿凭印象改) + +| 事实 | 证据 | 影响 | +|---|---|---| +| 业务 spec **有两份逐字拷贝** | `src/backend/src/modules/asset.rs`(178 行)vs `packs/asset/src/lib.rs` | 改一处忘另一处 ⇒ **静默**不一致 | +| 两份拷贝**没有比对闸门** | `check-arch.sh` 只有 AR1–AR7 + MEM1–MEM2,**没有 PACK1** | `packs/asset/src/lib.rs` 注释里写的「PACK1 会比对(P3 加)」**至今没加** | +| `packs/asset` **根本没被内核装载** | `routes.rs` 只 `merge` 了 `modules::router()`(1 处 merge);`sspf-sdk` 的 `BusinessPack` **没有 `routes()` 方法**(只有 manifest/entities/menus/metadata/hooks) | 业务包是**死的**样板,`PLAN.md` §4.4 写的 `routes()` 未实现 | +| 契约扫描器**只扫 `modules/*.rs`** | `check-contract-scan.py:369` 只遍历 `src/backend/src/modules/`(除 `mod.rs`) | 业务包若搬到 `packs/`,路由**不在扫描范围** ⇒ CC2/CC3 判「契约多 / 代码少」⇒ **假漂移** | +| 静态闸门**最慢 66.6s** | 实测 `check-contract.sh` 66.6s(静态解析 659 个路由);`check-module` 25.8s | 每次改代码都等 ⇒ 「快速验证」体感差 | +| 运行时尺子**都很快** | `perm-smoke` 6.0s / `perm-smoke-jnpf` 4.8s / `lowcode` 1.9s / `baseline` 3.3s / `mcp` 2.9s | **「快验证」的成本在静态闸门,不在运行时** | +| 业务 DDL 要**手抄进 schema.sql** | `schema.sql:879/888/897/920` 四张业务表 | 加一张表要改 schema.sql + `main.rs` BASE_TABLES + `sspf-store/db.rs` **两处**断言(批次 9/10 各踩一次) | +| 业务表数**写死 52** | `crates/sspf-store/src/db.rs:1226,1233` | 加表必红 ⇒ 又一处「记得改」 | + +#### 本批交付物(4 件事,按依赖顺序做) + +**① `sspf-sdk` 补 `routes()` + `crates/sspf-plugin`(L2 静态装载器)** + +- `BusinessPack` 加 `fn routes(&self) -> &'static [PackRoute]`(**默认空** ⇒ 纯元数据包 L0 仍零改动)。 + `PackRoute` = `{ method, path, entity }` —— **不是 axum Handler**,只是**声明**。 + 🔴 **理由**:业务包不许依赖 axum(AR2 钉死)⇒ 路由**声明**在 sdk(纯数据), + **注册**在内核(唯一认识 axum 的地方)。这与 `EntitySpec` 已是同一模式。 +- `crates/sspf-plugin`(新 crate,依赖 ⊆ {sspf-sdk, sspf-contract, serde, serde_json}): + 扫 `packs/*/pack.toml` ⇒ 读清单 ⇒ 校验 `kernel_req` 区间 ⇒ 收集 entities/menus/routes。 + 🔴 **AR8 新增**:本 crate 依赖 ⊆ {sspf-sdk, sspf-contract, serde, serde_json}(不许碰 axum/tokio/pglite)。 +- 内核接线:**只改 `bootstrap.rs` 一处** —— 平台层 `crud.rs` 补一个 + `crud_router(spec) -> Router`(把现有 `handle_list/save/delete` 包成 3 条路由), + 业务包给出 `routes()` ⇒ 插件层按 `{method, path, entity}` 查 spec ⇒ 生成路由 ⇒ merge。 + ⇒ **业务包自带路由,平台层零改动**(这才是「链接就好」的含义)。 +- 🔴🔴 **【集成期友好性】包声明的路由路径必须从第一天就用「官方形状」,不许用面 A 的 `/api/ssw/...`**: + - 面 A(`/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`)是**本仓自造**的 ssw 约定 + ⇒ **集成到官方 JNPF 时全部作废**(官方路径见 `MIGRATION.md` §2.3)。 + - 面 B(官方 JNPF 的 `/api/{模块}/{资源}/...`)才是能直接搬的形状。 + - ⇒ **业务包默认只声明面 B 形状的路由**;面 A 那套**留给 Rust 终端场景**(保留在 `modules/` 里不动)。 + - ⇒ **验收**:新加的包,`pack.toml` 里的路径在官方 `JNPF-PostgreSQL.sql` 对应的 Controller 里 + **能一一对上**(用 `MIGRATION.md` §2.1 的逐件翻译表反查)。 + +**② 打通「两份拷贝」⇒ 单一真源 + `PACK1` 闸门** + +- `modules/asset.rs` 的 spec **改为从 `packs/asset` re-export**(`pub use sspf_pack_asset::DATA_RESOURCE_SPEC;`) + ⇒ **只留一份**。内核 `Cargo.toml` 加 `sspf-pack-asset = { path = "../../packs/asset" }`。 +- 🔴 **AR2 会因此破**(`packs/*` 只能依赖 sdk/serde;内核依赖 packs 是**反向**,不违反 AR2)⇒ + 需给 `check-arch.sh` 加 **AR9**:内核**只允许**依赖 `packs/` 这类业务包,且**不得**在 + 平台层(`platform/`)出现 `use sspf_pack_*` ⇒ 业务知识不许漏进平台层。 +- **PACK1 闸门**(新增,`check-arch.sh`):`packs//src/lib.rs` 声明的 entities/menus + 与 `modules/.rs` 声明的**逐字一致** ⇒ 不一致就红。有了 re-export,这道闸变成 + 「**模块文件只允许 re-export,不许自己写 spec**」的形状检查。 + +**③ 业务 DDL 跟着包走 ⇒ 不再手抄 `schema.sql`** + +- 每个包带 `schema/*.sql`(`pack.toml` 的 `[[pack.tables]].ddl` 已预留这个字段);内核启动时 + **按包顺序**执行 + 幂等(`CREATE TABLE IF NOT EXISTS`)。 +- 🔴 **`sspf-store` 的两处表数断言必须改成「不写死」**(`db.rs:1226,1233`)—— + 写死 52 是批次 9/10 各踩一次的坑,改成「base 表数写死 + 业务表数 ≥ N」或直接读 `ddl_tables()` 对账。 +- 🔴 **`is_builtin_table`(`face_b.rs:12993`)取 `ddl_tables()`** ⇒ 业务包建的表会**自动变成内置表** + ⇒ 数据建模页**看不到**用户自己建的表了。这条要**重新想**(本批至少要保证行为不回退)。 +- 🔴 `main.rs::whitelist_self_check` 的**双向对账**(孤儿 DDL / 漏建表)要改成 + 「DDL = base 表 + **所有包**的表」,否则包表会被判成孤儿 DDL ⇒ 启动失败。 +- 🔴🔴 **【集成期友好性】包的 DDL 必须按官方规范写,集成时才能「只导数据」**: + - 列名照官方习惯:`f_` 前缀 + `f_id VARCHAR(50)`(36 位 UUID)+ `f_delete_mark INTEGER DEFAULT 0` + + **`f_tenant_id VARCHAR(50) NOT NULL`**(值恒 `"0"`,**参与复合主键 `(f_id, f_tenant_id)`** —— + 单租户也不许省,见 CLAUDE.md 红线 12)。 + - **业务表的 `f_` 列不许自创语义**(如把金额叫 `f_money` 而官方叫 `f_price`)⇒ 集成时列名映射是纯人工活。 + - 🔴 **包的 `pack.toml` 要补 `baseline_table`**(`[[pack.tables]]` 已有该字段)⇒ 集成时表名不同可自动映射, + 不靠人记。 + - **验收**:拿一个包,把它的 `schema/*.sql` 对着官方 `JNPF-PostgreSQL.sql` 的同名表逐列比, + 差异只允许出现在「官方没有这个业务表」这一项上(业务表本就要新建,但**列的形状**要对齐官方同类表)。 + +**④ 契约登记自动化 + 让静态闸门变快** + +- 契约表 `docs/contract.md` 附录 A 的 `[MODULE]` / `[MENU]` / `[ENDPOINT]` 三段, + 现在**手写** ⇒ 加包必须手抄三处。⇒ 改成**从包生成**:`scripts/pack-sync.py` + 读 `packs/*/pack.toml` + `src/lib.rs` ⇒ 追加到 contract.md 附录 A(幂等)。 + 🔴 **不要手改生成段**(否则下次同步被覆盖)⇒ 生成段用 `` / `` 包起来。 +- 🔴 **扫描器要认识 `packs/`**:CC2/CC3 现在只扫 `modules/*.rs` ⇒ 业务包搬走后会判假漂移。 + ⇒ `check-contract-scan.py` 改成扫 `packs/*/src/lib.rs` + `modules/*.rs` **两处**。 +- **提速**(`check-contract.sh` 66.6s 是瓶颈):扫描器目前每次全量解析 659 个路由。 + ⇒ 加**增量**:按文件 mtime 缓存解析结果(`scripts/.scan-cache.json`)⇒ 改一个文件只重扫一个。 + 目标:**改一个模块后静态闸门总耗时 ≤ 15s**(现状 ~110s)。 +- 🔴 **「快速验证」的新命令**:`bash scripts/verify.sh` —— 一条命令跑完 + `build → 静态闸门 → 单测 → 尺子`,末尾打印**总耗时**与**哪道最慢**(Top 3)。 + 这是「快速打包 / 快速验证」的**用户可见入口**。 +- 🔴🔴 **【集成期友好性】前端触点也要进闸门**(现在前端**完全没有保护**,见 §0-ter): + - 🔴 **本批的前端 = React 模板**(`ssw-jnpf-lite-rust` 的 `src/frontend`,与 React 技能**逐字节相同**) + ⇒ **本仓要把 `src/frontend` 建起来**(当前是空的,CLAUDE.md §2.2 写的是「后端-only」—— + 🔴 **这条要改**:新路线下前端在 MVP 阶段就有,且**必须**是 React 模板)。 + - ⇒ **本批产出 `scripts/new-page.sh `**:生成 **React 三件套**: + `src/frontend/src/api/.ts`(3 个 export)+ `src/frontend/src/views/.tsx`(列表+弹窗表单+删除确认) + + `src/frontend/src/App.tsx` 的 `` 一行 + + 提醒菜单登记(`urlAddress` == Route path 去前导斜杠 == `guardModule` 的 key,**三处一字不差**)。 + ⇒ 模板直接抄 React 技能的 `views/DemoItem.tsx`(101 行,含弹窗表单)+ `api/product.ts`(7 行)。 + - ⇒ **前端闸门**:把 React 技能的 `scripts/check-module.sh`(11 KB,**9 个接触点**, + 支持 `--all` 自动探测 / `--live` 实跑后端)**移植**过来 ⇒ 前端 4 个接触点**从 `⏭` 变成真检查**。 + 🔴 **移植时只改后端路径**(React 技能指 NestJS `src/backend/src/` ⇒ 本仓指 Rust `src/backend/src/`), + **前端路径零改**(`src/frontend/src/...` 两边同名)。 + - 🔴 **集成期才做官方 Vue 那一套**:`views/<模块>/index.vue` + `api/<模块>.ts` + + `router/routes/modules/<模块>.ts`(官方 `import.meta.glob` **放文件即注册,不用改配置**)。 + ⇒ **本批不做**(明确不做清单里),集成期再写 `new-page.sh --vue` 或另一个脚本。 + - ⚠️ **不要现在就把官方 monorepo 的路径写进脚本**:`jnpf-web-monorepo-framework`(7.0 前端框架) + 与 `jnpf-web-apps-main`(官方应用)是**两个目录**,实际业务代码在**后者** + (`~/Desktop/workspace/jnpf/jnpf-web-apps-main`,其 `src/api/request.ts` = `defHttp` 定义处)。 + ⇒ 集成期做 `--fe-root` 时要指对目录。 + +#### 本批护栏(缺一不可) + +| # | 护栏 | 落地位置 | +|---|---|---| +| 1 | 业务包**不许依赖 axum/tokio/pglite** | AR2(已有)+ 新 AR8 | +| 2 | 平台层**不许出现业务包**(业务知识隔离) | 新 AR9 | +| 3 | spec **单一真源**(不许两份拷贝) | PACK1 + re-export 改造 | +| 4 | 路由**声明**在 sdk、**注册**在内核 | `PackRoute` + `bootstrap.rs` | +| 5 | 包表数**不许写死** | `sspf-store/db.rs` 两处断言 | +| 6 | 包 DDL 幂等 + 不许碰 `base_*` | 内核执行时过滤 `base_` 前缀 | +| 7 | 契约登记**生成**而非手写 | `pack-sync.py` + BEGIN/END 标记 | +| 8 | 🔴 **包的路由路径只许官方形状**(面 B),**不许面 A** | `pack-sync.py` 校验 + 评审 | +| 9 | 🔴 **业务表 DDL 列名不许自造语义**,必带 `f_tenant_id` | `new-pack.sh` 模板 + 评审 | +| 10 | 🔴 **前端三处一字不差**(`urlAddress` == `guardModule` key == Route path) | `new-page.sh` + 移植的 `check-module.sh` | + +#### 验收判据(做完必须全绿才算完成) + +```bash +# 1) 新建一个空业务包,只写 spec,不碰任何平台层文件 ⇒ 全链路自动通 +bash scripts/new-pack.sh ledger Ledger # 脚手架:生成 packs/ledger/{Cargo.toml,pack.toml,src/lib.rs,schema/001_init.sql} +# 2) 十二道闸门全绿 + 单测不减少 +bash scripts/verify.sh # 新命令:build → 静态闸门 → 单测 → 尺子,打印耗时 +# 3) 业务包可独立构建(不依赖内核) +cargo test -p sspf-pack-asset +# 4) 「加包不碰平台层」有钉子测试:git diff --name-only 只应出现 packs// + 契约生成段 +# 5) 加包后**没有手抄**痕迹:contract.md 的 [MODULE]/[ENDPOINT] 段是生成物 +# 6) 🔴【集成期友好性】包的路径/列名能被官方侧对上(详见下面「集成期 checklist」) +``` + +#### 🔴🔴 集成期 checklist(不是本批做,是**现在就要能回答**的问题) + +> 这张表的用途:**MVP 阶段每加一个业务包,就顺手填一遍** ⇒ 集成期不返工。 +> 填不完的**当场就还债**(宁可现在多写 20 分钟,别集成时返工一天)。 + +| 检查项 | 怎么答 | MVP 期成本 | 不做的后果 | +|---|---|---|---| +| 包的端点在官方是**哪个 Controller 哪个方法**? | 用 `MIGRATION.md` §2.1 翻译表反查官方 Java 源码(本机 `~/Desktop/workspace/jnpf/jnpf-java-boot`) | 查 5 分钟 | 🔴 集成时**路径全要改** | +| 业务表的列名官方叫什么? | 对着官方 `JNPF-PostgreSQL.sql` 的同类表比 | 查 10 分钟 | 🔴 集成时**列名映射全靠人工** | +| 这个表的 `baseline_table` 叫什么? | 填进 `pack.toml` 的 `[[pack.tables]]` | 1 分钟 | 🔴 集成时记不住 | +| 业务表的 `f_tenant_id` 带了没? | 看 `schema/*.sql` | 0(模板自带) | 🔴 **复合主键缺列 ⇒ 导不进官方** | +| 这个业务要不要**按钮级/列级权限**? | 官方 `@SaCheckPermission` 的判据是什么 | 想 10 分钟 | 🔴 集成时**权限体系要重做** | +| 返回的 VO 形状官方长什么样? | 对着官方 `XxxListVO` / `XxxInfoVO` 抄字段清单 | 抄 10 分钟 | 🔴 集成时**前端读不到字段 ⇒ 静默降级** | +| 涉及文件上传/导出吗? | 是 ⇒ 记下来(官方走 `jnpf-file` 服务) | 标记 1 分钟 | 🔴 集成时**功能缺失** | +| 前端页面要接的接口清单 | `api/<模块>.ts` 里逐个列 | 已有 | 🔴 集成时**前端要返工** | + +🔴 **一条经验**:上面 8 项里,**后 4 项(权限 / VO 形状 / 文件 / 接口清单)就是那 27 条 `partial` +里「形状欠」那 9 条 + 「自造」4 条的来源** ⇒ **在 MVP 阶段就把 VO 字段清单抄全**, +是整个两阶段路线里**性价比最高**的一件事(抄一次,省掉集成期逐条 debug)。 + +#### 明确不做(本批不碰,别偷跑) + +- ❌ **L3 dylib 动态库**(`PLAN.md` §4.5):六条铁律(内存所有权 / catch_unwind / ABI 校验 / 热替换…) + 是**另一个量级**的工作力,本批**只做 L2 静态链接**。 + 🔴 理由:PLAN.md §4.6 写得很清楚 ——「L2 是静态链接(编 30s),L3 才是运行期 dlopen」; + 「不要对外承诺什么都能热更」。先把「链接就好」在 **L2** 做到真,再谈 L3。 +- ❌ **WASM 执行器**(PLAN.md P3 交付项之一):低代码沙箱已有 Rhai,WASM 是第二实现,不急。 +- ❌ **`pack export/import --format=baseline`**(双向迁移):属于 P3 的后一半,本批只做「包内声明 → 内核装载」这一半。 + 🔴 **但 `pack.toml` 的字段(`baseline_table` / `[[pack.tables]].ddl`)要按最终格式设计好** + ⇒ 集成期做 export/import 时**不用改包格式**。 +- ❌ **官方 Vue 前端的页面脚手架**(`views/<模块>/index.vue` + `api/<模块>.ts` + + `router/routes/modules/<模块>.ts`)—— 那是**集成阶段**的事。 + ⇒ 本批只做 **React 三件套** 的 `new-page.sh` + 移植 React 技能的 `check-module.sh`。 + ⇒ 🔴 **不改官方 monorepo / 官方应用的任何文件**(`jnpf-web-apps-main`),那是集成期的事。 + +#### 🔴 前端在两阶段分别怎么办(2026-11-01 19:39 修正 → 20:10 按 React 模板再修正) + +> ⚠️ **19:39 这一版仍然写错了**:当时说「前端**全程**都在官方 monorepo 里,两阶段的差别不在有没有前端, +> 而在前端的代码规范等级」。 +> **20:10 用户纠正**:「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向, +> **除了认证,其它都留给集成阶段**」。 +> ⇒ **MVP 前端 = React 模板**(不是官方 vue);**官方 vue 是集成阶段的事**。 +> ⚠️ **两次都写错同一个点** ⇒ 这条在下一轮开工时**先复核再动手**。 + +| | MVP 阶段(AI 怎么快怎么来) | 集成阶段(按官方规范) | +|---|---|---| +| 前端代码放哪 | **React + Vite**:`src/frontend/src/`(从 `ssw-jnpf-lite-rust` 复制,与 React 技能逐字节相同) | 官方 `~/Desktop/workspace/jnpf/jnpf-web-apps-main/src/`(Vue 3) | +| 认证 | ✅ **MVP 就做**(端点/参数/密文/返回/登出码**全部照官方契约**) | 换官方 `jnpf-oauth`(**同形 ⇒ 零改**) | +| 业务页面 | ✅ **只做薄壳原型**(列表 + 弹窗表单 + 删除)⇒ 够试业务规则 | ✅ 补齐全套(类型、权限控制、国际化、组件用法) | +| 权限配置 UI / 低代码表单 / 数据建模页 | ❌ **不做**(官方有现成的,MVP 不重复造) | ✅ 全做 | +| 加一个业务页面 | React 三件套:`api/.ts` + `views/.tsx` + `App.tsx` 加一行 `` | Vue 三件套:`api/<模块>.ts` + `views/<模块>/index.vue` + `router/routes/modules/<模块>.ts` | +| 路由注册 | React Router 显式声明(`App.tsx`) | 🔴 **不用改配置** —— 官方 `import.meta.glob('./modules/**/*.ts')` + `mergeRouteModules`(读 `default` 导出)⇒ **放文件即注册** | +| 后端对接 | 面 A `/api/ssw/...` ⇒ **前端零改**直连本仓 Rust | 面 B `/api/{模块}/{资源}/...` ⇒ **前端零改**直连官方 Java | +| ⚠️ 缺口 | **前端完全没闸门**(`check-module.sh` 的 4 个前端接触点全打 `⏭`)⇒ 改错三处不一致**没人拦** | 同 ⇒ 集成前必须补 | + +⇒ **本批(批次 12)对前端的动作**(在 ④ 里,已写入): +① `scripts/new-page.sh ` —— 生成 **React 三件套** + 菜单登记提示; +② **移植** React 技能的 `scripts/check-module.sh`(9 个接触点,`--all` / `--live`) +⇒ 把「三处一字不差」这条从人工检查变成机器检查; +③ 🔴 **不碰官方 Vue 那一套**(集成期的事)。 + +🔴 **为什么这条值得单独做**:React 侧 `urlAddress` / `guardModule` key / Route path 三处不一致的后果是 +**静默放行**(菜单显示了但守卫不命中)⇒ **不报错,只是权限失效** ⇒ 这是最该上闸门的一类。 + +🔴 **集成期搬 React → Vue 的对应关系**(React 技能 `MIGRATION.md` §「前端:React 原型 → jweb (Vue)」已写明): +- `cipher.ts` ↔ 官方 `defHttp` 拦截器(登出码 / ActionResult 解包)**1:1**; +- `api/.ts` 的 `request.get('/ssw/...')` ↔ `defHttp.get({ url: '/api/ssw/...' })`(**只差 baseURL 前缀**); +- ⚠️ **React 的 `` 在 jweb 不存在** —— jweb 靠菜单挂载(`base_module.f_url_address`)自动注册路由; +- ⚠️ **jweb 请求头要多补 `Vue-Version: 3`**(官方 `addRequestInterceptor` 必发,本仓面 B 也靠它分流)。 + +#### ✅ 批次 12 完成状态(2026-11-01 22:00 实测) + +| 交付物 | 状态 | 落地物 / 证据 | +|---|---|---| +| ① `sspf-sdk` 补 `routes()` + `crates/sspf-plugin` | ✅ | `PackRoute` 纯数据声明(包不依赖 axum);插件层按 `packs/*` 装载 | +| ② 两份拷贝打通 + PACK1 | ✅ | `modules/.rs` 改 re-export;`check-arch` 新增 **PACK1 / AR8 / AR9**,4 例反自证全过 | +| ③ 业务 DDL 跟着包走 | ✅ | `packs/asset/schema/001_init.sql` + `include_str!` 编进二进制 ⇒ **单二进制部署**(运行时无 `packs/`) | +| ④ 契约登记自动生成 + 静态闸门提速 + `verify.sh` | ✅ | `scripts/pack-sync.py`(幂等,两次 md5 一致)+ `scripts/verify.sh`(**≈15s**) | +| ⑤ **前端三件套**(本轮新增) | ✅ | `src/frontend`(React MVP 模板)+ `scripts/new-page.sh` | + +**加一个业务模块现在的实际成本(批次 12.5 之后 = 一条命令)**: + +```bash +bash scripts/new-pack.sh crm Customer --name "客户" \ + --columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend +bash scripts/verify.sh --fast # ≈17s 全绿才继续(含尺子自证) +``` + +它产出的东西(**全部从「业务决策」推导,不猜**): + +| 产出 | 谁生成 | +|---|---| +| `packs//{Cargo.toml,pack.toml,schema/001_init.sql,src/lib.rs}` | `new-pack-gen.py`(真源:app / 实体名 / 列清单) | +| `src/backend/src/modules/.rs`(面 A 适配器) | 同上(**MVP 前端走面 A**,没有它页面就是空的) | +| `src/backend/src/packs_gen.rs`(内核包清单) | `pack-sync.py`(**生成物**) | +| `modules/mod.rs` 的 5 个登记段 | `pack-sync.py`(**生成物**) | +| `src/backend/Cargo.toml` 的包依赖段 | `pack-sync.py`(**生成物**) | +| `docs/contract.md` 的 `[MODULE]` / `[MENU]` / `[ENDPOINT]` | `pack-sync.py`(**生成物**) | +| `src/frontend/src/{api,views}/…` + `App.tsx` 路由 | `new-page.sh`(`--with-frontend`) | +| `[RULER]` 的断言条数 | 实跑一次 `check-module` 登记(**只允许变大**,见下) | + +⇒ 见 §「✅ 批次 12.5 完成状态」。 + +🔴 **前端接入的两个坑(已修,别再踩)**: + +1. **端口**:React 技能模板的 vite proxy 指 NestJS `:30000`,本仓 Rust 后端是 **`:30010`** + (`main.rs` 的 `PORT` 缺省值)⇒ 照抄会在浏览器里表现成 `Network Error`, + 最容易误判成「跨域 / 认证」,其实只是端口抄错。 +2. **api 文件名**:`check-module.sh` 用 `lower(Entity)` 推文件名 ⇒ `DataResource` 要的是 + `api/dataresource.ts`(**全小写**,不是 `dataResource.ts`)。`new-page.sh` 已按此生成。 + 要改这个约定**必须同时改尺子**,否则尺子会报「缺 export」而文件明明在那儿。 + +**前端闸门已转真检查**:`check-module.sh` 的前端接触点从 `⏭` 变成真断言 ⇒ 条数 +**114 → 123**(契约 `[RULER]` 已同步)。这正是「尺子自证」在起作用——条数对不上就报 +「尺子被改弱了(少了/多了断言)」,逼你把新条数**显式**登记,而不是悄悄绿灯。 + +**未做(明确留下,不是忘了)**: + +- 前端**没有运行时闸门**:`npm run build` / `tsc --noEmit` 不在 `verify.sh` 里。 + `verify.sh` 的定位是「零 node 依赖的静态闸门」,塞 node 会把它拖慢一个量级; + 要验类型请单独跑 `cd src/frontend && npx tsc --noEmit`。 +- 官方 **Vue 那一套一行没碰**(集成期的事)。 + +#### ✅ 批次 12.5 完成状态(2026-11-01 23:40 实测)—— 「加包 = 一条命令,漏接 = 直接报错」 + +**问题**:批次 12 把 spec 搬进包之后,加一个模块仍要手抄 **5 个后端文件** +(`packs//` 四个 + `modules/.rs`),再带动 **4 处内核登记** +(`packs_gen` / `Cargo.toml` / `modules/mod.rs` 5 段 / 契约 3 段)。而其中两类漏接 +**不报错**:漏 `merge` ⇒ 面 B 静默 404;漏 `ALL_MENUS` ⇒ 菜单不种 ⇒ 守卫查不到菜单 +⇒ **越权放行**。 + +**做法**:把「内核怎么知道有这个包」从**手写**改成**生成** —— + +| 派生位置 | 生成器 | 漏了会怎样(改之前) | +|---|---|---| +| `src/backend/src/packs_gen.rs` | `pack-sync.py` | 🔴 面 B 静默 404,无日志 | +| `modules/mod.rs` 的 5 段(`pub mod` / `ALL_SPECS` / `ALL_ROUTES` / `ALL_MENUS` / `router()`) | `pack-sync.py` | 🔴 面 A 静默 404 + 菜单不种 | +| `src/backend/Cargo.toml` 包依赖段 | `pack-sync.py` | 编译报错(响亮) | +| `docs/contract.md` 三段 | `pack-sync.py` | `check-contract` 红(响亮) | + +- 新增统一包出口约定:每个包导出 **`pub struct Pack`** + **`pub const DDLS: &[(&str,&str)]`** + ⇒ 生成器只要知道「目录名 + crate 名」就能拼出装载调用,**不需要理解每个包的常量命名**。 +- `sspf_plugin::load_static()`:把「manifest 解析 + `PackSource` + `merge`」这段样板收进插件层 + (**为生成而设计**)⇒ `bootstrap.rs` 的 `load_packs()` 只剩一行。 +- **`scripts/new-pack.sh`**(+ `new-pack-gen.py`):一条命令生成 5 个后端文件 + 跑 `pack-sync` + + 可选 `new-page.sh`。列清单只从 `--columns` 或 `--from-ddl` 来,**没有就拒绝**(不猜类型)。 +- **`[RULER]` 条数自动登记**:每加一个模块断言数 **+30**(实测 123 → 153) + ⇒ `new-pack-gen.py` 实跑一次 `check-module` 把数字登记掉,**只允许变大** + (变小 = 有人删了断言 ⇒ 拒绝并打印)。 + +**端到端验证(在 `/tmp` 的仓库副本里做,不污染工作区)**: + +``` +bash scripts/new-pack.sh probe Widget --name "探针" \ + --columns "name:VARCHAR(200),price:DECIMAL(18,2),memo:TEXT" --with-frontend +→ 写 5 个后端文件 + 契约三段的 probe 行 + packs_gen/Cargo/mod.rs + 前端三件套 +→ ✅ 已登记 153 条(原 123,+30 来自新模块) + +cargo build --offline ✅ 3.7s +cargo test -p sspf-pack-probe ✅ 13 passed +cargo test -p ssw-platform --lib ✅ 102 passed +python3 scripts/pack-sync.py --check ✅ 幂等 +bash scripts/verify.sh --fast ✅ 全绿 17.2s +``` + +**反自证(证明新闸门真的会红,不是「改瞎了还全绿」)**: + +| 造的漂移 | 结果 | +|---|---| +| 从 `packs_gen.rs` 删掉 probe 的装载块(模拟「忘了跑 pack-sync」) | `--check` **rc=1**,指名 `packs_gen.rs` | +| 从 `modules/mod.rs` 删掉 `probe::WIDGET_MENU`(模拟「漏登记菜单」) | `--check` **rc=1**,指名 `modules/mod.rs` | + +**本轮抓到并修掉的 2 个真 bug**(都是「加第二个包」才显形): + +1. 🔴 **`check-contract-scan.py` 的守卫回落取了「排序后第一个包」** + (`for pkg in sorted(pack_orig)`)⇒ 有 `asset` + `probe` 两个包时,probe 的面 A 守卫 + 被推成 `asset/DataResource` ⇒ **CC6 假飘移 3 条** ⇒ 人会去改**对的**契约。 + 修法:按 `app` 精确匹配包;查不到就返回「推不出」(人工核对),不再瞎猜。 +2. 🔴 **加包会误报 3 个单测**(`asset_pack_loads` / `pack_router…` / `health…==52`)—— + 全是**写死计数**的假闸门,加包必须先改测试。改成**结构性/推导式**断言: + 每个实体必须「有 DDL + 有菜单 + 3 条路由」;health 的表数 = + `ddl_tables().len() + packs.ddls.len()`。 + +**未做(明确留下)**: + +- `new-pack.sh` **不跑 `cargo build`**:它只保证「文件和接线都齐」,编译留给 `verify.sh` + (生成器不该假装自己是编译器;但**编译失败一定是响亮的**)。 +- **一个模块文件仍只能有 1 个实体**(`ALL_ROUTES` 与 `ALL_SPECS` 按「每模块 3 条」配对)。 + 要加第二个实体 ⇒ 另建一个模块文件。放宽它需要引入「模块 → (起点, 条数)」映射表 + ⇒ 又多一处会漂的结构,暂不做。 +- 包**只支持静态链接**(`kind = "static"`);`dylib` 热插拔仍未做。 +- 官方 **Vue 那一套一行没碰**(集成期)。 + +#### 批次 12 顺延为批次 13(原计划,一字不改) + +`fe-gap` 余下最大的 `system` 55 条 / `permission` 26 条 / `systemData` 32 条里挑 +**有官方 `base_*` 表支撑**的;`workFlow`(104) / `onlineDev`(101) / `aiCenter`(75) / +`extend`(64) / `msgCenter`(50) 基本都是「本仓没这个模块」⇒ **先确认产品边界再动手**,做也只是恒空 stub。 **实现模板(照抄就行)**:`ORGANIZE_WRITE_FIELDS` / `POSITION_WRITE_FIELDS` 那一套 @@ -854,3 +1464,11 @@ ENC_BIN="$PWD/target/debug/ssw-platform" bash scripts/perm-smoke-jnpf.sh 1. 追加 `.workbuddy/memory/YYYY-MM-DD.md`:结论 / 坑 / 数字(闸门通过数) 2. 更新本文件 §1 现状、§2 现场、§3 待办(划掉做完的) 3. 若还有未完成项,**确认下一次定时任务存在**(`automation_update` list 可查),没有就新建 + +**当前挂着的定时任务**(2026-11-01 19:23 实查): + +| 任务 | id | 触发 | 覆盖范围 | +|---|---|---|---| +| **ssw-platform 批次 12:框架固定包 + 业务模块链接就好** | `68997e3d-b08a-4f12-b0d1-003733b381c1` | **2026-11-02 09:00 一次性** | 批次 12 全部 4 项交付物 + 护栏 + 验收判据(prompt 已写全,自包含) | +| ssw-platform P2-b 收尾 | `1dcb55af-…` | 已过期(一次性,未删) | P2-b 已完成 ⇒ **可删** | +| 每日积分 | `82c41449-…` | 每日 08:00 | 与本仓无关 | diff --git a/HOWTO_MODULE.md b/HOWTO_MODULE.md index 3b9981d..8b9b443 100644 --- a/HOWTO_MODULE.md +++ b/HOWTO_MODULE.md @@ -1,38 +1,55 @@ # 加一个业务模块(AI 开发主线) -本文件是 **Rust 版**的操作手册。参照实现 = 内置的四个模块 +> 🔴 **2026-11-01 起:一条命令。** 本文后半部分的「改哪个文件」清单写于批次 12 之前, +> **已过时**(`db/schema.sql` 不用改、`modules/mod.rs` 不用改、契约不用手抄)。 +> 以本节为准: +> +> ```bash +> bash scripts/new-pack.sh crm Customer --name "客户" \ +> --columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend +> bash scripts/verify.sh --fast # ≈17s 全绿才继续 +> ``` +> +> 它建 `packs//`(**真源**)+ `modules/.rs`(面 A 适配器), +> 再把**四处生成位置**补齐(`packs_gen.rs` / `modules/mod.rs` 五段 / +> `Cargo.toml` 依赖段 / `docs/contract.md` 三段)。 +> 生成物手改会在下次 `pack-sync.py` 被覆盖,而 `verify.sh` 第一步就会红。 + +参照实现 = 内置的四个模块 (`demo/DemoItem` · `shop/Product` · `books/Book` · **`asset/DataResource`(真实业务)**) -——**照抄一个最接近的,别从零想**;要加真实业务模块就抄 `asset.rs`。 +——要读就抄 `packs/asset/`,它是完整样板。 -> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改哪儿、怎么验证」。** +> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改了哪儿、怎么验证」。** -## 〇.5、一图看完全流程(先看一遍再动) +## 〇.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 追加该模块的断言(别新写脚本) + 1. packs//src/lib.rs 【真源】EntitySpec + MenuSpec + PackRoute×3 + Pack + DDLS + 2. packs//schema/*.sql 业务表 DDL(include_str! 编进二进制;**不进 db/schema.sql**) + 3. packs//pack.toml 包清单(catalog;内核读的是 pack-sync 生成的 JSON 快照) + 4. packs//Cargo.toml 只依赖 sspf-sdk(AR2:不许 axum / tokio / pglite) + 5. src/modules/.rs 面 A 适配器:pub use 包的 spec + 3 个 handler + router() + ↓ 以下四处**全部由 scripts/pack-sync.py 从「packs/* + modules/*.rs」生成** + 6. src/backend/src/packs_gen.rs 内核包清单(每个包一条 load_static 调用) + 7. src/modules/mod.rs 五段:pub mod / ALL_SPECS / ALL_ROUTES / ALL_MENUS / router() + 8. src/backend/Cargo.toml >>>GEN:PACK_DEPS 段 + 9. docs/contract.md 附录 A [MODULE] / [MENU] / [ENDPOINT] 的生成段 + 10. frontend/src/{api,views}/… + App.tsx 的 (new-page.sh,--with-frontend) + ⇒ bash scripts/verify.sh --fast 必须全 ✅ ``` -**8 个文件 = 上面的 1–8**(其中 `modules/.rs` 与 `modules/mod.rs` 是**业务层**)。 -第 7 步漏了 ⇒ `check-module.sh` 直接判「契约 [MODULE] 里没有这个模块」退出 2; -`[ENDPOINT]` 漏了 ⇒ `check-contract.sh` 判「代码里的路由没被契约登记」红。 +🔴 **漏了会怎样**(这就是为什么不再让人手抄): + +| 漏哪一步 | 现象 | 报错吗 | +|---|---|---| +| 6(`packs_gen.rs`) | 面 B 端点 404,列表永远空 | ❌ **不报** | +| 7(`ALL_MENUS`) | 菜单不种 ⇒ 守卫查不到菜单 ⇒ **越权放行** | ❌ **不报** | +| 7(`router()`) | 面 A 404 ⇒ MVP 前端页面空着 | ❌ **不报** | +| 8(Cargo 依赖) | 编译失败 | ✅ 报 | +| 9(契约) | `check-contract` 红 | ✅ 报 | 🔴 **平台层(`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)—— +加业务模块**不碰平台层**,由尺子 `bash scripts/check-boundary.sh`(CP1–CP6)钉住: 平台层出现任何业务标识符(表名 / 实体名 / 路由前缀 / 菜单 id / url / en_code)⇒ 红。 ## 〇、命名约定(先想清楚再动)