feat: JNPF 7.0 通用资产包独立分发,示例数据与官方 init SQL 对齐

- 新增 pack-jnpf-assets.sh:web 构建产物 + 示例数据库种子按 JNPF 版本单独出包,
  与 sspf 版本、OS/CPU、工具链解耦;manifest 声明版本绑定,SHA256SUMS 可逐项校验。
- demo_seed.sql 以官方 jnpf_dbnull_init.sql 为真源:58 表 / 14242 行,
  补齐行政区划、国际化、地图三张表,DDL 幂等可重复启动。
- 新增 SSW_ASSETS_DIR / SSW_DEMO_SEED_FILE 外置加载,编译期内嵌为兜底;
  换 JNPF 版本的演示数据无需重编二进制;release.sh 以资产包为 web/ 唯一真源,
  并加 --no-web 剥离选项。
- 修 SSW_STATIC_DIR 相对路径在 PGlite chdir 后失效;补 14 张官方图标并加
  /api/file/Image 精确白名单,其它 /api/** 仍保持信封 404。
- 新增 65 页 A/B 走查报告与 CHANGELOG v0.5.0 条目:UI/路由/接口形状与
  init SQL 基础数据页已 1:1,运行时业务数据页差异源于参考库额外演示数据。
This commit is contained in:
admin committed 2026-11-06 15:50:15 +08:00
1 parent 8af5b901b5
commit d8a9d16d2c
37 files changed
+79350 -36

No files matched your search

+191
View File
@@ -0,0 +1,191 @@
# A/B 走查差异报告:官方 JNPF 7.0 vs ssw-platform
> 日期:2026-11-06
> 目标:① 用 agent-browser 对比「官方 web 连官方后端」与「官方 web 连 ssw-platform 后端」的差异;
> ② 让 ssw-platform 以官方 `jnpf_dbnull_init.sql`(示例数据)初始化,而非空库。
## 0. 一句话结论
ssw-platform 现在以官方 `jnpf_dbnull_init.sql` 为**契约**对齐「用示例数据初始化」,并把
**静态前端 + 示例数据库**打成一个只绑定 JNPF 版本、与环境 / 平台 / 工具链无关的**通用资产包**
`dist/jnpf-7.0-assets.tar.gz`(解包后 `SSW_ASSETS_DIR` 一个 env 即用)。
修复后同一时刻双走查(65 页,见 §9):官方 163 端点 / 57 有数据 vs ssw 155 / 41;
65 页里 **47 页表格行数一致**、核心系统页 35 个里 22 个一致。
**主要系统管理页已做到 1:1**(前端本身就是官方 7.0.0 构建产物、同源托管);
剩余差异全部属于「运行时数据表(init SQL 本来就是 0 行)」或「ssw 自管表的设计内差异」,
**不是渲染 / 接口缺陷**。
---
## 1. 走查方法
- **面 A / 面 B 分流**:官方前端发 `Vue-Version: 3` 头 ⇒ 后端走面 B(官方 `PcUserVO` 形状,15 字段),
否则走面 A(6 字段)。判据唯一,已确认(`apps/jnpf-web-apps-main/src/api/request.ts` 确实发送此头)。
- **三个 v4 走查任务**(Playwright + 真实登录 + 等待渲染稳定):
| 任务 | 前端 | 后端 | 结果 |
|---|---|---|---|
| official_v4 | 官方 web @3100(开发侧 vite 代理) | 官方后端 192.168.1.26:30093 | 65 页 / 526 次 API |
| ssw_v4 | 官方 web @3100 | ssw 后端 @30010 | 78 页(含掉线,见 §2) |
| static_v4 | **官方 web 静态包 @30010(同源)** | ssw 后端 @30010 | 65 页 / 369 次 API |
- **端点级对比**(`cmp_v3.py`):端点身份 = 去 query 的 `path`;「有数据」= 该端点某次响应 `listLen > 0`。
---
## 2. 关键发现:ssw 开发侧走查"掉线"是假象(非前端 bug)
`ssw_v4` 里 **59/78 页渲染的是登录页**,一度以为后端崩了。定位后结论:
- 三个走查**并发**打**同一个** ssw 后端 ⇒ 偶发 `GET /api/oauth/CurrentUser` 返回 **500**
(实测:单跑 240 次并发 curl **全 200**;单独浏览器逐页访问也 200)。
- 根因是并发抢同一 PGlite 后端时的偶发失败,与前端无关。
- **公平对照应取 `static_v4`(同源)**——前端与后端同进程、同库,才是「官方前端 + ssw 后端」的纯净对比。
---
## 3. 端点覆盖对比(官方 vs 静态包同源)
| 指标 | 官方(30093) | ssw(修复前) |
|---|---|---|
| 端点总数 | 163 | 155 |
| 有数据端点 | 57 | 39 |
- 🟢 ssw 补上(官方有数据 ⇒ ssw 也有):**38 个**
- 🔴 ssw 缺数据(官方有数据 ⇒ ssw 空):**19 个** → 见 §4 分类
- 🟡 ssw 多出(ssw 有数据 ⇒ 官方空):1 个(`/api/system/DictionaryData/...`,ssw 自带字典种子)
- ⚪ 仅单方走查调到:官方 9 / ssw 1(路由未命中,非功能缺口)
---
## 4. 19 个"缺数据"端点的根因分类
| 类别 | 端点 | 根因 | 处置 |
|---|---|---|---|
| **可修 → 已修** | `/api/system/Area/-1`(34 行)、`/api/system/BaseLang`(20 组)、`/api/system/atlas`(3210 行) | 三张表在 init SQL 有数据,但 ssw 之前没导入 | 按 `PARTIAL` 规则裁列+裁行后**补入 `demo_seed.sql`**,已验证返数据与官方一致 |
| **init SQL 本就空**(运行时由管理员在 UI 创建) | `CommonWords`、`Kit`、`DataInterface`、`Dataset`、`Authority/Data`、`message/Receive`、`PermissionGroup`、`Position`、`Standing`(+`/list`)、`UserRelation/userList`、`HomeData`、`workflow/template/TreeList`、`Ai/Knowledge`、`AiSupplier/Selector` | 官方 `jnpf_dbnull_init.sql` 里这些表 **0 行**;参考环境 30093 被额外灌过演示数据,所以参考侧有数据 | **对齐契约的正确行为**。补全需 30093 的整库 dump,超出 `jnpf_dbnull_init.sql` 范围 |
> ⚠️ **重要澄清**:30093 参考环境 ≠ 纯 `jnpf_dbnull_init.sql`——它带额外演示业务数据。
> ssw 的契约目标是 `jnpf_dbnull_init.sql`,故上述 16 个"缺口"是**预期内**的,不是缺陷。
---
## 5. 页面渲染对比(修复前,65 可比页)
| 维度 | 数量 | 说明 |
|---|---|---|
| 表格行数**一致** | 46 页 | 绝大多数列表页已对齐 |
| **官方多** | 16 页 | 主要是日志/在线/收件箱/权限组等运行时表;其中 `sysData/area`(34)、`sysData/language`(20) **已修复对齐** |
| **ssw 多** | 3 页 | `commonCenter/sysFunction`(35 vs 17)、`permission/menu`(104 vs 99,ssw 多一个 `appBackend` 节点)、`sysData/dictionary`(13 vs 0,ssw 自带字典种子) |
修复后:`sysData/area`、`sysData/language` 现已与官方行数一致。其余"官方多"的页面均属 §4 第二类
(运行时表 / init SQL 空),符合契约。
---
## 6. 已完成的修复清单
1. **示例数据落地(对齐契约)**
- `src/backend/db/demo_seed.sql`(**58 表 / 14242 行 / 8.1 MB**),由 `scripts/gen-demo-seed.py`
从官方 `jnpf_dbnull_init.sql`(106 MB / 331 表)裁剪生成,**编译期内嵌** ⇒ 随版本包分发。
- 裁剪规则:排除 5 张纯大表(占原文 88% 体积)+ 7 张本仓自管表(撞复合主键);
部分保留 `base_province`(省/市/区 4061 行) / `base_language`(1538 组×3 语种) / `base_province_atlas`(3210 行)。
- `SSW_DEMO_DATA` 缺省**开**;`false/0/off/no` 可关(纯净库)。
- 每条 INSERT 带 `ON CONFLICT DO NOTHING` ⇒ 幂等、不覆盖人工改动。
2. **DDL 幂等**:示例 DDL 归一化为 `CREATE TABLE IF NOT EXISTS`,消除「二次启动刷表已存在」噪音。
3. **静态通用前端(随包分发)**
- `scripts/build-web.sh` 从官方 monorepo 构建 → `dist/web/`(**2104 文件 / 107 MB**)。
- `scripts/release.sh` 把它拷进包内 `web/`,README 说明 `SSW_STATIC_DIR=./web` 同源托管。
- **修复静态目录相对路径 bug**:`SSW_STATIC_DIR` 在配置解析时按进程 CWD 绝对化
(PGlite 打开数据目录时会 `chdir` 到 `PGLITE_DIR`,相对路径会指错 ⇒ 之前 `/` 全返 JSON 404)。
- 端到端验证:`/`、`/login`、SPA 深链 `/permission/menu` 均 200。
4. **`sysConfigInfo` 形状对齐**:官方 37 个核心字段全部命中(此前是 `{}`)。
5. **资产包外置**(§7):`SSW_ASSETS_DIR` / `SSW_DEMO_SEED_FILE` + `ensure_demo_data_sql`
⇒ 示例数据不再被编译期钉死,换 JNPF 版本不必重编二进制;编译期内嵌保留兜底。
6. **官方图标资源补齐**:`/api/file/Image/**` 之前全返信封 404(9 条控制台报错、数据库/AI 图标不显示)。
资产包内置 14 张官方 PNG(入仓 `src/backend/assets/jnpf-7.0/file-images/`),后端 fallback 加
**精确白名单**(含百分号解码 + 目录穿越防护)⇒ 抽查 8 个 URL 全部 `200 image/png`,
其它 `/api/**` 仍信封 404、SPA 深链仍 200。快速复核 3 个相关页 `HTTP>=400` 归零。
---
## 7. JNPF 通用资产包(静态前端 + 示例数据库,单独分发)
> 🔴 **分发模型(2026-11-06 修订)**:静态前端与示例数据库**跟部署环境、目标平台、
> sspf 版本、rust 工具链都无关,只跟 JNPF 版本有关** ⇒ 不该绑在按
> `sspf 版本 × target` 出的平台包上,改成**一份独立资产包**给所有平台/版本复用。
- 产物:`scripts/pack-jnpf-assets.sh` → `dist/jnpf-7.0-assets.tar.gz`(47 MB / 2136 项)。
- 包内:
| 路径 | 内容 |
|---|---|
| `web/` | 官方 JNPF 7.0 web 前端构建产物(2104 文件 / 107 MB),API 前缀为空 ⇒ 同源托管 |
| `db/demo_seed.sql` | 官方示例数据裁剪版(58 表 / 14242 条 INSERT,幂等) |
| `db/schema.sql` / `db/SOURCE.md` | 本仓使用的官方 DDL / 来源与裁剪规则 |
| `tools/gen-demo-seed.py` | 生成器副本(换 JNPF 版本时可复现) |
| `manifest.json` | 版本绑定声明、官方 init SQL 的 sha256、web 全树摘要、统计、消费方式 |
| `SHA256SUMS` | 2110 个文件逐文件校验(解包后 `shasum -a 256 -c` 全 OK) |
- 消费(一个 env 搞定,解包即用):
```bash
tar -xzf jnpf-7.0-assets.tar.gz
SSW_ASSETS_DIR=./jnpf-7.0-assets PORT=30010 ./bin/sspf-admin
```
优先级:`SSW_STATIC_DIR` / `SSW_DEMO_SEED_FILE` > `SSW_ASSETS_DIR` 自动推导 > 二进制**编译期内嵌**兜底
⇒ 换 JNPF 版本的演示数据**不需要重编二进制**。
- 端到端验证:从 tar 解包到 `/tmp`、用**相对路径** `SSW_ASSETS_DIR=./jnpf-7.0-assets` 起服务,
日志 `[demo-data] 使用外置 JNPF 资产包示例数据: /private/tmp/.../db/demo_seed.sql`,
导入 14255 条语句零失败,`/` 200(相对路径绝对化修复仍生效)。
- `scripts/release.sh` 的 `web/` 改以资产包为唯一真源,新增 `--no-web` 可把静态前端完全剥离出平台包;
默认仍携带一份(向后兼容「跟版本包一起分发」)。
---
## 9. 修复后重跑 v5:主要页面能不能 1:1
> 同一时刻、同一 `capture5.mjs`、同一 65 路由集,两侧**都是生产构建产物 + 同源后端**:
> 官方 `http://192.168.1.26:30093` vs ssw 资产包同源 `http://127.0.0.1:30010`。
> 口径:页面「一致」= 渲染稳定后表格行数相同;端点「有数据」= 某次响应 `listLen > 0`。
| 指标 | 官方 30093 | ssw 资产包 30010 | v4(修复前) |
|---|---|---|---|
| 走查页面 / API 次数 | 65 / 526 | 65 / 369 | 65 / 369 |
| 端点总数 / 有数据 | 163 / 57 | 155 / 41 | 155 / 39 |
| 官方有数据而 ssw 空 | — | **17** | 19 |
| 65 页表格行数一致 | — | **47**(官方多 15 / ssw 多 3) | 46 |
| 核心系统页 35 个一致 | — | **22** | — |
| console / page 错误 | 0 / 11 | 11 / 11 | — |
- 补数据后端点缺口 **19 → 17**(`/api/system/Area/-1` 34 行、`/api/system/BaseLang` 20 组补齐),
`/sysData/area` 与 `/sysData/language` 两个页面行数与官方一致。
- `pageErrors` 两侧都是 11 条,全是页面里的说明文案被选择器抓到,**不是异常**。
- v5 抓包时还未补官方图标:ssw 的 11 条 console 里 9 条是 `/api/file/Image/**` 404(官方走 302 到文件服务)。
补完图标后快速复核 3 个相关页:`HTTP>=400 = 0`、图标请求 404 = 0;
剩下的是登录页 SVG 负值警告、AI 配置页一个 TypeError、WebSocket 推送(两侧都报 ws 握手错误)。
### 差异逐条归因(15 页「官方多」+ 3 页「ssw 多」)
| 类别 | 页面 | 根因 |
|---|---|---|
| 运行时 / 参考库额外演示数据(15 页**全部**) | `sysLog/{error,login,operate,request}Log`、`monitor/userOnline`、`msgCenter/receiveConfig`、`permission/{organize,user,authGroup,identity}`、`dataCenter/{dataset,dataService}`、`templateCenter/{commonWords,kit}`、`sysService/cache` | 官方 `jnpf_dbnull_init.sql` 里这些表 **0 行**;30093 被额外灌过演示数据 / 是运行时产生 ⇒ 对齐 init SQL 契约的正确行为 |
| ssw 自管种子(3 页) | `permission/menu` 104 vs 99、`sysData/dictionary` 13 vs 0、`commonCenter/sysFunction` 35 vs 17 | 本仓种子自己生成的节点 / 字典 / 功能项,属**设计内差异**;改它们会动既有菜单 / 字典行数断言 |
| 端点缺口 17 个 | `message/Receive`、`system/{HomeData,Dataset,Kit,CommonWords,DataInterface}`、`permission/{Position,Standing,PermissionGroup,UserRelation}`、`ai/{Knowledge,AiSupplier}`、`workflow/template/TreeList` 等 | 同样是运行时表(init SQL 0 行);`ai/AiSupplier/Selector` 与 `Authority/Data/.../Values` 是参考库才调到 |
### 结论(分层回答「1:1」)
1. **UI / 路由 / 交互 / 接口形状:是 1:1**。前端就是官方 JNPF 7.0.0 源码的构建产物(`pnpm run build:main`),
同源托管、免 node;65 页全部正常渲染,155/163 个端点被调到,核心系统配置字段(`sysConfigInfo` 37 项)全中。
2. **由 init SQL 提供基础数据的页面:是 1:1**。58 表 / 14242 行导入,行政区划 34、国际化 20、地图 3210
与官方一致;核心系统页里**凡数据来自 init SQL 契约的配置页,行数全部相同**。
3. **含运行时 / 演示业务数据的列表页:还做不到逐行 1:1**。差异不是渲染或接口缺陷,而是
30093 参考环境比纯 `jnpf_dbnull_init.sql` 多灌了演示数据(日志、在线用户、组织用户、数据集…)。
要 100% 复刻需取该环境**整库 dump** 作为附加种子,超出 init SQL 契约。
4. **3 个自管种子页**:菜单多 `appBackend` 节点、字典 13 项、功能 35 项 —— 要逐行一致可调种子,
但会影响既有断言,当前判定为设计内差异、不修。
---
## 10. 后续可选(非阻塞)
- 若要 100% 复刻 30093 的"演示业务数据",需取该环境的整库 dump 作为额外种子(超出 `jnpf_dbnull_init.sql` 契约)。
- 若要连 3 个自管种子页也逐行一致,需调整 `menus.rs` / 字典种子并同步更新行数断言。
- AI 配置页的 `TypeError`(`/api/ai/AiSupplier/Selector` 形状)与 WebSocket 推送属接口层能力差异,
不影响主要系统管理页;按需再补。
- 静态包登录页首屏依赖字体/图标 CDN;纯内网离线场景可改为本地化资源(按需)。