- permission.organize.tree(机构平铺列表,建用户前取 organizeId) - form.selector(挂菜单/绑流程选功能) - ops.db.stats(关键表行数 + 库体积,快速判断空库/错库) - 同步 docs/mcp.md / PLAN / HANDOFF 的 52 个口径;全量测试与八道静态闸门全绿
1001 lines
54 KiB
Markdown
1001 lines
54 KiB
Markdown
# PLAN —— 尚数网统一开发平台(SSPF)总体架构与路线
|
||
|
||
> 本文件回答 **「做成什么、为什么这么做、怎么算做完」**。
|
||
> `CLAUDE.md` 是红线与当前范围(随阶段滚动更新),本文件是**长期架构基线**,阶段推进时只改 §9 的勾。
|
||
> 术语:**基线平台** = 兼容目标(现称 JNPF v7 的那套 Java 平台,代码/文档内统一叫 `baseline`,不再出现原厂名)。
|
||
|
||
---
|
||
|
||
## 0. 一句话定位
|
||
|
||
**SSPF = 尚数网企业统一开发平台**:以「元数据驱动 + 契约兼容 + AI 原生接口」三层能力,
|
||
让业务系统从「写代码」变成「声明 + 验证」,并保证存量前端/移动端/数据库零改动平滑接管。
|
||
|
||
三层价值,缺一不可:
|
||
|
||
| 层 | 是什么 | 为什么必须有 |
|
||
|---|---|---|
|
||
| **兼容层** | 逐字对齐基线平台的 HTTP 契约、`base_*` DDL、口令算法、响应信封 | 前端/移动端/存量库不动,才有「切换」而不是「重做」 |
|
||
| **元数据层** | 表/模型/表单/菜单/流程/权限全部是**库里的数据**,引擎解释执行 | 这才是「低代码」;也是「后续开发不用编译」的唯一干净实现 |
|
||
| **AI 接口层** | MCP 2.0 元工具 + 自提示 + 分层加载 | 让 AI 成为第一开发者,而不是让人去点 20 个页面 |
|
||
|
||
---
|
||
|
||
## 1. 目标分解(三条时间线,别混)
|
||
|
||
| 时间线 | 目标 | 可验收的判据 | 依赖 |
|
||
|---|---|---|---|
|
||
| **N(现在–Q1)** | 提高基线平台开发速度 / 降低环境要求 | ① 同一需求 AI 交付耗时 ↓50% ② 部署从「Java+Redis+Nacos+DB」降到「单二进制 + 内嵌 PG」 | 轨道 A + B 并行 |
|
||
| **M(Q1–Q2)** | 完全稳定 / 行为一致后切换 Rust 版 | 影子对账 P0 差异 = 0;同一前端在两个后端跑同一套 E2E 全绿 | 轨道 B |
|
||
| **L(Q2+)** | 人 + AI 高效协作开发 | 业务需求从「提给开发」变成「对话产出 + 自动验证 + 可回滚」 | 轨道 A 成熟 |
|
||
|
||
### 1.1 🔴 关键:拆成两条轨道并行,不要串行
|
||
|
||
```
|
||
轨道 A(AI 工具面) ── 架在【现有 Java 后端】上,立刻可用 ──▶ 提速
|
||
│
|
||
│ 同一套 MCP 工具契约,后端实现可替换
|
||
▼
|
||
轨道 B(Rust 内核) ── 逐条迁契约,影子对账 ──▶ 降环境、去 Java ──▶ 切换
|
||
```
|
||
|
||
**理由**:基线平台的开发速度瓶颈**不在 Java 运行时**,而在「人/ AI 要理解平台、记住 50 个坑、点 20 个页面」。
|
||
dacli 的 4.7 万行 TypeScript 全部在解决这件事 —— 这证明「工具面」是可以独立于「后端实现」交付的价值。
|
||
反过来,如果先做 Rust 内核再想工具面,提速目标会被内核进度绑死半年。
|
||
|
||
**架构保证**:MCP 层只依赖 `PlatformAdapter` trait,不认具体后端。
|
||
|
||
```rust
|
||
// crates/sspf-mcp/src/adapter.rs
|
||
#[async_trait]
|
||
pub trait PlatformAdapter: Send + Sync {
|
||
async fn call(&self, op: &str, args: Value) -> Result<Value, ApiError>;
|
||
async fn describe_env(&self) -> EnvInfo; // app_code / system / db / 版本
|
||
}
|
||
// 两个实现:
|
||
// JnpfHttpAdapter —— 打现有 Java 后端(HTTP),P1 就能用
|
||
// SspfNativeAdapter —— 进程内直调 kernel,P4 切换
|
||
// 工具契约、自提示、返回形状,两边完全一致。
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 五条核心判断(都会影响后续所有设计)
|
||
|
||
### 判断 ①:不改前端 ⇒ 「低代码引擎」在后端只是「元数据服务 + 动态数据路由」
|
||
|
||
基线平台的低代码渲染器在**前端**(Vue 的 FormGenerator 解释表单 JSON)。既然不迁前端,
|
||
Rust 侧**不需要重写渲染器**,只需要三件事:
|
||
|
||
1. **存取**:`visualdev` 那套 JSON 原样存、原样取(同构,不改一个字段)
|
||
2. **动态 CRUD**:给定 `modelId` → 查元数据 → 解析出物理表/字段/权限 → 拼 SQL(**零编译**)
|
||
3. **发布/版本**:表单草稿 → 发布 → 版本快照
|
||
|
||
⇒ 低代码引擎的工作量比直觉小一个量级,**且天然满足「不编译」**。这是第 8 条需求的落地点。
|
||
|
||
### 判断 ②:「不编译」有四级;**动态库是必须项,不是可选项**
|
||
|
||
Rust 没有稳定 ABI,`cdylib` 跨编译器版本会段错误。按「稳定性 × 成本」排序:
|
||
|
||
| 级 | 机制 | 编译 | 适用 | 风险 |
|
||
|---|---|---|---|---|
|
||
| **L0 元数据** | 表单/模型/菜单/流程/权限 = 库里的 JSON | **零** | 80% 的业务 | 无 |
|
||
| **L1 表达式** | Rhai 求值(受限宿主 API + 资源上限) | **零** | 15% 的业务(业务规则) | 低(沙箱化) |
|
||
| **L2 静态 crate** | `packs/<app>/src` 编成 rlib,链进内核 | 只编业务 crate(~30s) | 4% 的业务(外部集成、复杂算法) | 无 |
|
||
| **L3 动态库** | `cdylib` + `libloading`,`plugins/*.dylib` 启动扫描 | 独立编、热替换 | **必须支持**(见 §4.5) | 🟡 中(靠 ABI 契约 + 工具链锁定压住) |
|
||
|
||
**L3 是硬需求**,理由是终端产品形态:客户现场要能单独替换/升级某个业务能力,不能等整包发版。
|
||
代价必须用工程手段压住,而不是回避:
|
||
|
||
1. **工具链锁死 `1.95.0`**(`rust-toolchain.toml` + `pack.toml` 的 `[pack.build].toolchain`,CI 双向校验)
|
||
2. **ABI 只暴露 4 个 C 函数**,其余全部走 JSON(见 §4.5)
|
||
3. **装载失败不能拖垮内核**:版本不匹配直接拒载;`catch_unwind` + 独立线程兜底
|
||
4. **热替换必须显式**:`sspf plugin reload <name>`,不做自动监控(自动热更 = 状态迁移地狱)
|
||
|
||
WASM 保留为 L3 的**并行**选项(不是替代):沙箱隔离更彻底,适合「AI 生成的业务逻辑先试跑」。
|
||
|
||
### 判断 ③:双向迁移的本质是「业务包格式」,不是「转换工具」
|
||
|
||
要做 `jnpf ⇄ sspf` 无缝,靠的不是写两个转换器,而是**一个两边都能读的中间格式**(见 §5)。
|
||
格式定得早,迁移就是打包/解包;定得晚,就是重写。
|
||
|
||
### 判断 ④:MCP 2.0 的胜负手是 token 预算,不是工具数量
|
||
|
||
200 个工具全量注册 ⇒ 光 schema 约 6 万 token,AI 直接被淹。
|
||
必须做 **L0 常驻 4 个元工具 + L1 分类索引 + L2 按需 describe**(见 §6)。
|
||
这与当前主流 agent 的「工具搜索 / 延迟加载」范式一致。
|
||
|
||
> 注:**「MCP 2.0」是本项目的工具层架构代号,不是协议版本号**。
|
||
> 协议侧按官方最新 spec 实现(`2025-06-18` / `2025-11-25`:`outputSchema`、`structuredContent`、
|
||
> `resources`、`prompts`、`elicitation`、tool annotations、Streamable HTTP)。
|
||
|
||
### 判断 ⑤:以「前端是否依赖」划界,不依赖的全改
|
||
|
||
「去掉原厂字眼」与「契约一致」的冲突,用一条判据解决:
|
||
**前端 / 移动端 / 存量数据库会读到的字符串,一个字不改;读不到的,全改。**(细化见 §7)
|
||
**改错层的后果是前端全挂**。
|
||
|
||
### 判断 ⑥:内存是一级设计约束,不是优化项 🔴
|
||
|
||
**产品形态**:尚数网的连接器是**终端产品**(客户现场 / 一体机 / 边缘节点),不是机房里的中台。
|
||
完整 Java 版基线平台在目标硬件上**跑不动**;勉强起来之后,也没有余量再跑业务、跑沙箱、跑计算。
|
||
|
||
这一条把 Rust 版的性质改了:
|
||
|
||
| 原来的假设 | 修正后 |
|
||
|---|---|
|
||
| Rust 版是「稳定后切换」的**优化项** | Rust 版是**唯一可部署形态**,是产品可行性的前置条件 |
|
||
| 轨道 B 可以慢慢来 | 轨道 B 的**内存指标**从 P0 就要进闸门,不能等 P5 |
|
||
| 沙箱/计算是后期增强 | 沙箱/计算是**终端产品的卖点**,架构必须从 P0 预留执行器位置 |
|
||
|
||
**内存预算(进 P0 出口判据,`scripts/mem-budget.sh` 可执行)**:
|
||
|
||
| 场景 | 目标常驻 | 实测(2026-10-31) | 说明 |
|
||
|---|---|---|---|
|
||
| 空载(内核 + 空库 21 表) | ≤ 40 MB | **7 MB** ✅ | 单二进制,strip 后静态链接;vmmap Physical footprint |
|
||
| 典型(20 表 / 1 万行 / 10 并发) | ≤ 120 MB | 待压测 | pglite 共享缓冲 + 会话表 |
|
||
| 峰值(导入导出 / 报表) | ≤ 256 MB | 待压测 | **必须流式**,禁止整表载入 |
|
||
| 沙箱单实例 | ≤ 64 MB(可配) | 待 P3 | 超限即杀,不拖累主进程 |
|
||
| 对照:Java 全套 | 2–4 GB | — | JVM + Spring + Redis + Nacos |
|
||
|
||
🔴 **7 MB 这个数字是终端产品可行性的第一份硬证据** —— 同一个业务契约,
|
||
Java 栈要 2–4 GB,Rust 栈空载 7 MB。它同时说明:内存预算的风险不在「做不到」,
|
||
而在「后续不加约束地长胖」(无界缓存、整表载入、每请求 clone 大对象)。所以 MEM1/MEM2 进闸门。
|
||
|
||
**四条内存红线**(写进 `check-arch.sh`):
|
||
1. 禁止 `SELECT *` 全表读进 `Vec` —— 导出/报表一律游标流式
|
||
2. 禁止无界缓存(所有缓存必须有 `max_entries` + LRU 淘汰)
|
||
3. 每个限额必须有默认值 + 可配,不许「不配就无限」
|
||
4. 沙箱/计算必须能独立限额并强杀,不影响主进程存活
|
||
|
||
### 判断 ⑦:执行器(沙箱 + 计算)从 P0 预留位置,P3 落地
|
||
|
||
终端产品要跑的不只是 CRUD。架构上预留三个执行层,共享同一套资源限额:
|
||
|
||
| 执行器 | 用途 | 隔离级别 | 落地阶段 |
|
||
|---|---|---|---|
|
||
| **表达式**(Rhai) | 字段校验/计算/联动 | 同进程,操作数上限 + 深度上限 | P2 |
|
||
| **WASM 沙箱** | AI 生成的业务逻辑、第三方脚本 | 同进程独立内存,fuel 计量 | P3 |
|
||
| **进程沙箱** | 重计算 / 不可信代码 / 调用外部 CLI | 独立进程,cgroup/Job 限额,可强杀 | P4 |
|
||
|
||
🔴 三者共用 `Executor` trait,**不许各写一套限额逻辑**。
|
||
|
||
---
|
||
|
||
## 3. 架构
|
||
|
||
### 3.1 总图
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ AI 客户端:Claude Code / Cursor / WorkBuddy / 自研 Agent │
|
||
└──────────────────────────┬───────────────────────────────────────────┘
|
||
│ MCP(stdio 本地 / Streamable HTTP 团队共享)
|
||
┌──────────────────────────▼───────────────────────────────────────────┐
|
||
│ sspf-mcp ── 元工具层(常驻 4 个,schema < 2K token) │
|
||
│ sspf_context 环境与工程上下文 │
|
||
│ sspf_discover 意图 → 工具/资源索引(L1 分类) │
|
||
│ sspf_describe 工具 → 完整 schema + 自提示(L2,含 pitfalls) │
|
||
│ sspf_call 统一执行(结构化返回 + next_actions) │
|
||
│ │
|
||
│ 唯一知识源 registry ──▶ 派生 tool schema / 文档 / 校验器 / CI 用例 │
|
||
└──────────────────────────┬───────────────────────────────────────────┘
|
||
│ trait PlatformAdapter(后端可替换)
|
||
┌────────────────┴─────────────────┐
|
||
▼ ▼
|
||
┌──────────────────┐ ┌──────────────────────────────────────┐
|
||
│ JnpfHttpAdapter │ │ SspfNativeAdapter │
|
||
│ 打现有 Java 后端 │ │ 进程内直调 │
|
||
└────────┬─────────┘ └──────────────┬───────────────────────┘
|
||
│ │
|
||
┌────────▼─────────┐ ┌──────────────▼───────────────────────┐
|
||
│ 基线平台(Java) │ │ sspf-kernel(单二进制) │
|
||
│ 现状,存量资产 │ │ ├ contract 信封/错误码/契约类型 │
|
||
└──────────────────┘ │ ├ auth cipher/session/guard │
|
||
│ ├ permission 四源合并 │
|
||
│ ├ lowcode 元数据引擎(解释型) │
|
||
│ ├ store pglite ⇄ 真实 PG │
|
||
│ └ plugin 业务包加载器(L0–L3) │
|
||
└──────────────┬───────────────────────┘
|
||
│
|
||
┌──────────────▼───────────────────────┐
|
||
│ packs/<app>/ ── 业务包(整目录可搬) │
|
||
│ ├ pack.toml 清单/兼容区间 │
|
||
│ ├ schema/*.sql DDL(f_ 前缀) │
|
||
│ ├ meta/*.json 表单/模型/菜单/流程 │
|
||
│ ├ src/ 可选:Rust 业务逻辑 │
|
||
│ └ tests/ 契约测试(两边都能跑) │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 目录重构(从单 crate → workspace 多 crate)
|
||
|
||
现状是 `src/backend` 单 crate(1.6 万行)。要满足「内核不编译、业务可搬」,必须拆:
|
||
|
||
```
|
||
ssw-platform/
|
||
├── crates/
|
||
│ ├── sspf-contract/ # 契约类型:ActionResult / EntitySpec / MenuSpec / 错误码 / 码表
|
||
│ ├── sspf-sdk/ # 🔴 业务包唯一依赖。只含 trait + 数据类型,依赖仅 serde
|
||
│ ├── sspf-store/ # DB 抽象:pglite 后端 + 真实 PG 后端
|
||
│ ├── sspf-auth/ # cipher / session / guard
|
||
│ ├── sspf-permission/ # 四源合并 + 管理员短路 + 菜单树
|
||
│ ├── sspf-lowcode/ # 元数据引擎:form/model/menu/flow + 动态 CRUD
|
||
│ ├── sspf-plugin/ # 业务包加载器:静态注册 / dylib / wasm(后两者可选 feature)
|
||
│ ├── sspf-kernel/ # 启动装配 + 路由挂载(bin 目标)
|
||
│ └── sspf-mcp/ # MCP 服务 + registry + 4 元工具 + adapter
|
||
├── packs/ # 🔴 业务包,只依赖 sspf-sdk
|
||
│ ├── asset/
|
||
│ └── ...
|
||
├── tools/
|
||
│ ├── diff-harness/ # 影子对账(§8)
|
||
│ ├── pack-cli/ # pack 导入导出
|
||
│ └── gates/ # 六道闸门(从 scripts/ 迁入,保持可独立跑)
|
||
├── web/ # 复用基线平台前端(不改)
|
||
└── docs/
|
||
```
|
||
|
||
**拆分纪律**(已实现为 `scripts/check-arch.sh`,`--self-test` 会造违规反自证):
|
||
|
||
| 规则 | 内容 | 违反后果 |
|
||
|---|---|---|
|
||
| AR1 | `sspf-sdk` 依赖**只能**是 `sspf-contract` | 业务包被框架绑架,不可搬 |
|
||
| AR2 | `packs/*` 依赖 ⊆ {`sspf-sdk`, `serde`} | 同上 |
|
||
| AR3 | `sspf-contract` 不许 `use axum/tokio/pglite/sqlx` | 契约层有 IO ⇒ 业务包再也不「轻」 |
|
||
| AR4 | `sspf-contract` 依赖 ⊆ {`serde`, `serde_json`, `uuid`, `http`} | 同上 |
|
||
| AR5 | `sspf-mcp` 依赖 ⊆ {`sspf-contract`, `serde`, `serde_json`} | 无法同时接「进程内内核」与「远端 Java 后端」 |
|
||
| MEM1 | 非注释代码不许 `SELECT *` | 整表读进 Vec ⇒ 直接超内存预算 |
|
||
| MEM2 | 缓存必须有 `MAX_*` / `CAPACITY_*` 上限常量 | 无界缓存 = 慢性内存泄漏 |
|
||
|
||
### 3.3 现状 vs 目标(差距表)
|
||
|
||
| 能力 | 现状 | 目标 | 差距 |
|
||
|---|---|---|---|
|
||
| 面 B 契约端点 | ✅ **346 条**(2026-11-01 批次 11 收尾) | 全量(含 lowcode/flow/file/message) | 官方端点覆盖 365/372;余下多为「本仓没这个模块」 |
|
||
| `base_*` DDL | ✅ **52 张**逐字对齐 | 全量 331 张中的必需集 | 按域补 |
|
||
| 平台/业务分层 | ✅ `check-boundary.sh` 钉住 | 升级为 crate 级隔离 | **P0 已拆 contract / store / sdk;asset 包可独立编译;`jnpf.rs`→`face_b.rs`** |
|
||
| 低代码元数据引擎 | ✅ **P2-b 完成**:解析 + 校验 + 建表 + 动态 CRUD(6 个工具) | visualdev 同构 + 动态 CRUD + 发布 | 读 release / 单据号 / 乐观锁 → P2-c |
|
||
| 业务包格式 | 🟡 `pack.toml` 已定稿、`packs/asset` 已有样板 | 导入导出工具 | **P3** |
|
||
| MCP 工具面 | 🟡 **P1 主体完成**:4 元工具 + registry + 分层加载 + 双适配器 + 52 个业务工具 + 3 个流程模板 | 约 55 个业务工具(补 model / verify / 发布) | P1 收尾 |
|
||
| 影子对账 | ❌ 无 | 语料库 + 归一化比对 | **全新,P4** |
|
||
| 部署形态 | 🟡 pglite 单二进制 | 单二进制 + 可选真实 PG | P5 收口 |
|
||
|
||
---
|
||
|
||
## 4. 动态加载机制(第 8 条落地)
|
||
|
||
### 4.1 业务实现四级(先判级,再动手)
|
||
|
||
写业务前先回答一个问题:**这件事能不能只用数据描述?**
|
||
|
||
```
|
||
需要新的业务能力
|
||
│
|
||
├─ 只是增删改查 + 表单 + 菜单 + 权限? ──────────▶ L0 元数据(零代码、零编译)
|
||
│
|
||
├─ 有校验/计算/联动/显隐等规则? ────────────────▶ L1 表达式(零编译)
|
||
│
|
||
├─ 要调外部系统 / 复杂算法 / 事务编排? ─────────▶ L2 业务 crate(编 30s)
|
||
│
|
||
└─ 需要独立发版、热替换、多团队并行? ───────────▶ L3 动态库(编 + 装载)
|
||
```
|
||
|
||
**比例目标**:L0+L1 ≥ 90%,L2 ≤ 9%,L3 ≤ 1%。达不到说明元数据层设计不足,而不是业务太复杂。
|
||
|
||
### 4.2 L0:元数据(真正的「不编译」)
|
||
|
||
引擎能力清单(`sspf-lowcode`):
|
||
|
||
| 能力 | 输入 | 行为 |
|
||
|---|---|---|
|
||
| 实体/表 | `EntitySpec`(列 + 类型 + 索引) | 建表 / 迁移(幂等) |
|
||
| 模型 | 模型 JSON(字段 + 关联 + 数据源) | 注册 + 动态解析 |
|
||
| 表单 | 表单 JSON(与基线平台同构) | 存取 + 发布 + 版本 |
|
||
| 菜单 | 菜单声明 | upsert 到 `base_module` + 授权 |
|
||
| 流程 | 流程 JSON(BPMN 子集) | 存取 + 节点绑定表单 |
|
||
| 数据 | `modelId` + 查询条件 | 动态拼 SQL(列白名单,非字符串拼接) |
|
||
|
||
🔴 **动态 CRUD 的安全铁律**:所有列名/表名**只能来自元数据白名单**,绝不接受请求体里的标识符。
|
||
这条比「参数化查询」更严 —— 参数化防值注入,白名单防**结构**注入。
|
||
|
||
### 4.3 L1:表达式 —— 用 Rhai,但必须沙箱化
|
||
|
||
**选型:Rhai**(成熟、纯 Rust、无 GC、可完全禁用危险能力)。
|
||
**不自研求值器** —— 类型系统、字符串、正则、闭包这些特性自己写会变成长期负债;
|
||
业务方要的表达式能力一定会超出最初设想。
|
||
|
||
Rhai 的能力**默认全关**,只开白名单:
|
||
|
||
| 配置项 | 值 | 理由 |
|
||
|---|---|---|
|
||
| `eval` | **禁用** | Rhai 的 `eval` 是元编程入口,等于开后门 |
|
||
| IO / 文件 / 网络 | **禁用** | 一律不注册 |
|
||
| `import` / 模块加载 | **禁用** | 防跨脚本注入 |
|
||
| 时钟 | 只读 + 固定时区 | 可复现;不许拿来做限流 |
|
||
| 宿主函数 | 白名单注册 | 只有 `lookup() / len() / matches() / hasRole() / now() / today() / coalesce()` |
|
||
|
||
资源限额(缺一不可,全部可配 + 有默认):
|
||
|
||
| 限额 | 默认 | 作用 |
|
||
|---|---|---|
|
||
| `max_operations` | 10,000 | 防长计算 / 死循环 |
|
||
| `max_expr_depths` | 32 | 防深度炸弹 |
|
||
| `max_call_levels` | 16 | 防递归 |
|
||
| 执行超时 | 50 ms | 兜底(`operations` 之外的阻塞) |
|
||
| 返回 / 中间值大小 | 64 KB | 防内存炸 |
|
||
|
||
四条实现约定:
|
||
|
||
1. **编译一次,缓存 AST**:`Engine::compile` → `AST`,按表达式源 + 版本哈希缓存(有上限,LRU)
|
||
2. **表达式存元数据表** ⇒ 改规则 = 改数据 = **零编译**
|
||
3. **错误必须可读**:`EvalAltResult` 要映射成「哪个字段 / 哪一行 / 期望什么」,不能把 Rhai 原始错误直接抛给业务
|
||
4. **每次求值独立 `Scope`**,不许跨请求共享变量(防串数据与越权读)
|
||
|
||
示例(业务方写的就是这个):
|
||
|
||
```
|
||
len(fullName) <= 50 && matches(code, "^[A-Z]{2}\\d{4}$")
|
||
amount * (1 + taxRate)
|
||
status == "draft" && hasRole("finance")
|
||
lookup("customer", customerId, "creditLimit") >= amount
|
||
```
|
||
|
||
### 4.4 L2:业务 crate(默认的「写代码」形态)
|
||
|
||
```rust
|
||
// packs/asset/src/lib.rs
|
||
//! 业务包唯一入口。依赖只有 sspf-sdk(+ serde)。
|
||
|
||
use sspf_sdk::{BusinessPack, Manifest, EntitySpec, MenuSpec, MetadataDoc, Result};
|
||
|
||
pub struct AssetPack;
|
||
|
||
impl BusinessPack for AssetPack {
|
||
fn manifest(&self) -> &Manifest {
|
||
&Manifest { app_code: "asset", name: "数据资源", version: "1.0.0" }
|
||
}
|
||
fn entities(&self) -> &[EntitySpec] { &[DATA_RESOURCE] }
|
||
fn menus(&self) -> &[MenuSpec] { &[DATA_RESOURCE_MENU] }
|
||
// 需要时再实现 routes() / hooks();L0 包一个都不用实现
|
||
}
|
||
|
||
// 注册(唯一接线点,不进内核)
|
||
sspf_sdk::register!(AssetPack);
|
||
```
|
||
|
||
内核侧:
|
||
```rust
|
||
// crates/sspf-kernel/src/main.rs —— 内核里唯一的「业务知识」
|
||
let packs: Vec<Box<dyn BusinessPack>> = vec![
|
||
Box::new(asset::AssetPack), // ← 加业务包只改这一行
|
||
];
|
||
```
|
||
🔴 这一行是**唯一**允许出现业务名的地方,由 `check-arch.sh` 白名单钉住。
|
||
|
||
### 4.5 L3:动态库(**必做**,feature `dylib`)
|
||
|
||
#### 为什么手写 C ABI,而不用 `abi_stable`
|
||
|
||
业务插件的交互本来就是「收一个 JSON、返回一个 JSON」,**不需要跨 ABI 传复杂类型**。
|
||
C ABI + JSON 的调试成本最低(`ctypes` / `dlopen` 直接能测),而 `abi_stable` 要求业务方
|
||
把所有类型标注 `StableAbi`,学习成本与耦合度都更高。
|
||
|
||
⇒ **边界只有 JSON 字符串 + 6 个函数**。
|
||
|
||
#### ABI 契约(v1,改动即升版本)
|
||
|
||
```rust
|
||
// 插件侧(每个业务 cdylib 必须导出,符号名固定)
|
||
#[no_mangle] pub extern "C" fn sspf_abi_version() -> u32; // 必须返回 1
|
||
#[no_mangle] pub extern "C" fn sspf_build_info() -> *mut c_char; // JSON: {rustc, profile, pack}
|
||
#[no_mangle] pub extern "C" fn sspf_init(ctx: *const c_char) -> *mut c_char; // 入参 JSON,返 handle 或 err
|
||
#[no_mangle] pub extern "C" fn sspf_invoke(handle: *const c_char, op: *const c_char,
|
||
args: *const c_char) -> *mut c_char;
|
||
#[no_mangle] pub extern "C" fn sspf_shutdown(handle: *const c_char) -> *mut c_char;
|
||
#[no_mangle] pub extern "C" fn sspf_free(ptr: *mut c_char); // 🔴 谁分配谁释放
|
||
```
|
||
|
||
#### 六条铁律
|
||
|
||
| # | 铁律 | 不做的后果 |
|
||
|---|---|---|
|
||
| 1 | **内存所有权单向**:插件分配的字符串必须由插件的 `sspf_free` 释放,内核只用不 free | 跨 allocator free ⇒ 堆破坏 / 随机崩溃 |
|
||
| 2 | **所有调用 `catch_unwind`**:插件 panic 转成 `{ok:false,error}` JSON | panic 跨 FFI 是 UB ⇒ 主进程直接死 |
|
||
| 3 | **ABI 版本不匹配直接拒载**,不尝试兼容 | 静默错位读写 ⇒ 最难查的一类 bug |
|
||
| 4 | **构建信息必须校验**:`ABI 版本 + rustc 版本 + panic 策略` 三者全对才加载 | 换工具链重编的插件混进来 ⇒ 段错误 |
|
||
| 5 | **热替换前先排空**:引用计数归零才 `dlclose`;`dlclose` 后**复制到新路径再 `dlopen`** | 同 inode 重载会拿到旧句柄 ⇒ "改了没生效" |
|
||
| 6 | **插件崩溃不能拖垮内核**:可选 `--plugin-isolation=process`(子进程 + IPC) | 一个坏插件等于整站宕机 |
|
||
|
||
#### 工具链锁定
|
||
|
||
```toml
|
||
# rust-toolchain.toml(仓库根,全仓生效)
|
||
[toolchain]
|
||
channel = "1.95.0"
|
||
components = ["rustfmt", "clippy"]
|
||
profile = "minimal"
|
||
```
|
||
|
||
`pack.toml` 的 `[pack.build]` 必须写同一版本,CI 双向校验:
|
||
|
||
```bash
|
||
ACTUAL=$(rustc --version | awk '{print $2}')
|
||
[ "$ACTUAL" = "1.95.0" ] || { echo "工具链漂移: $ACTUAL != 1.95.0"; exit 1; }
|
||
# 插件侧:读 build_info 里的 rustc 字段,与 manifest 声明比对
|
||
```
|
||
|
||
> **为什么是 1.95.0 而不是最新 stable**:锁版本的意义是**全仓可复现 + 插件 ABI 一致**,
|
||
> 不是追新。1.95.0 是本机既有版本,立即可用;1.99.1 下载受本机代理限速(6 MB 卡死)。
|
||
> 要升级时按 §4.5 的四步走(改文件 → 全仓重编 → 插件全部重发 → 同步 pack.toml)。
|
||
|
||
🔴 **`panic = "abort"` 绝对禁止**(workspace 根 `Cargo.toml` 已有此注记):
|
||
abort 下 `catch_unwind` 抓不到 panic,铁律 2 直接失效。
|
||
|
||
#### 装载流程
|
||
|
||
```
|
||
启动扫描 plugins/*/manifest.toml
|
||
│
|
||
├─ 读 build_info → 校验 ABI / rustc / profile ──✗──▶ 拒载 + 记 ERROR(不退出)
|
||
├─ dlopen(RTLD_NOW | RTLD_LOCAL) ──✗──▶ 拒载 + 记 ERROR
|
||
├─ sspf_init(ctx) → handle 或 err ──✗──▶ sspf_shutdown + 拒载
|
||
└─ 注册到 plugin registry(op → handler)
|
||
```
|
||
|
||
**降级原则**:插件加载失败 ⇒ 该插件提供的 op 返回 `PLUGIN_UNAVAILABLE`,
|
||
其余功能照常。**内核绝不因为插件问题拒绝启动。**
|
||
|
||
### 4.6 「链接就好」的准确含义(这段是给未来的自己看的)
|
||
|
||
| 说法 | 准确含义 |
|
||
|---|---|
|
||
| 「低代码不用编译」 | ✅ 真的。元数据在库里,改数据即生效 |
|
||
| 「内核不用编译」 | ✅ 加业务包时不用。加**平台能力**(新契约面/新存储)时仍要编,但频率极低 |
|
||
| 「业务链接就好」 | 🟡 L2 是**静态链接**(`cargo build` 30s,增量更快),L3 才是运行期 `dlopen` |
|
||
| 「热更新」 | ⚠️ 只有 L0/L1 是热的;L2 要重启进程;L3 要 `dlopen` + 状态迁移 |
|
||
|
||
不要对外承诺「什么都能热更」—— 会被 L2 打脸。
|
||
|
||
---
|
||
|
||
## 5. 业务包与双向迁移(第 8 条后半)
|
||
|
||
### 5.1 `pack.toml`
|
||
|
||
```toml
|
||
[pack]
|
||
app_code = "asset"
|
||
name = "数据资源"
|
||
version = "1.0.0"
|
||
kernel = ">=0.4,<0.5" # 内核兼容区间(不匹配则拒载)
|
||
migratable = true # 允许导出到基线平台
|
||
|
||
[pack.compat]
|
||
baseline = "v7" # 兼容基线版本
|
||
frontend = "vue3" # 前端族(决定表单 JSON 方言)
|
||
tenant = false # 本期单租户
|
||
|
||
[[pack.tables]]
|
||
name = "asset_data_resource"
|
||
ddl = "schema/001_init.sql"
|
||
baseline_table = "asset_data_resource" # 基线平台上的表名(允许不同,导出时映射)
|
||
|
||
[pack.metadata]
|
||
forms = ["meta/forms/data_resource.json"]
|
||
models = ["meta/models/data_resource.json"]
|
||
menus = ["meta/menus.json"]
|
||
flows = []
|
||
|
||
[pack.build] # 仅 L2/L3 需要
|
||
kind = "static" # static | dylib | wasm
|
||
toolchain = "1.85" # L3 必填,用于 ABI 校验
|
||
```
|
||
|
||
### 5.2 迁移 = 打包 / 解包,不是重写
|
||
|
||
```bash
|
||
sspf pack export asset --format=baseline --out=/tmp/asset.jnpfpack
|
||
# 产出:DDL(转基线方言) + visualdev JSON(字段名对齐) + 菜单/授权 SQL + 导入脚本
|
||
|
||
sspf pack import /tmp/asset.jnpfpack --format=baseline
|
||
# 读基线平台导出的包 → 归一化成 sspf pack → 落库 + 注册
|
||
```
|
||
|
||
对齐点(**这四条对了,迁移就是搬箱子**):
|
||
|
||
| 对齐项 | 规则 |
|
||
|---|---|
|
||
| 物理表 | 列名 `f_` 前缀 + `f_id VARCHAR(50)` + 软删列;导出时若基线侧表名不同,用 `baseline_table` 映射 |
|
||
| 表单 JSON | 与基线平台 `visualdev` **同构**,一个字段都不改(前端要靠它渲染) |
|
||
| 菜单 | `f_url_address` / `f_en_code` / `f_system_id` 三列语义一致 |
|
||
| 权限 | `base_authorize` 的 `f_object_type` + `f_item_type` 取值一致 |
|
||
|
||
🔴 **反向迁移的坑**:基线平台的口令是 `md5(lower(md5(pwd)) + lower(secretkey))`,
|
||
SSPF 侧若用简化式,导出时必须做一次换算(`MIGRATION.md` §7 已记录,**单向、先备份**)。
|
||
|
||
### 5.3 业务包的可搬性验收
|
||
|
||
一个包算合格,必须能过这条:
|
||
|
||
```bash
|
||
# 1) 独立构建(不依赖内核源码)
|
||
cd packs/asset && cargo build --target-dir /tmp/asset-build
|
||
|
||
# 2) 依赖审计:只能有 sspf-sdk + serde
|
||
cargo tree -p asset --depth 1 | grep -v "sspf-sdk\|serde" && exit 1
|
||
|
||
# 3) 导出 → 导入往返(幂等)
|
||
sspf pack export asset --format=baseline --out=/tmp/a.pack
|
||
sspf pack import /tmp/a.pack --target=/tmp/fresh-db
|
||
sspf verify contract --db=/tmp/fresh-db # 必须全绿
|
||
```
|
||
|
||
---
|
||
|
||
## 6. MCP 2.0:自提示 + 分层加载(第 6 条落地)
|
||
|
||
### 6.1 为什么不能「一个能力一个工具」
|
||
|
||
| 方案 | 常驻 token | 问题 |
|
||
|---|---|---|
|
||
| 全量注册 60 个工具 | ~18K | 还没干活就烧掉 1/6 上下文 |
|
||
| 全量注册 200 个工具 | ~60K | 直接废掉 |
|
||
| **L0 + L1 + L2 按需** | **~1.8K 常驻,峰值 ~5K** | 需要多一次 discover/describe 往返 |
|
||
|
||
### 6.2 L0:常驻四件套(协议层只注册这四个)
|
||
|
||
| 工具 | 入参 | 返回 | 作用 |
|
||
|---|---|---|---|
|
||
| `sspf_context` | `scope: project\|user\|db\|env` | `{app, system, user, db, version, entities[], capabilities[]}` | 会话第一步;后续工具的默认上下文 |
|
||
| `sspf_discover` | `query?, category?, limit=10` | `[{id, title, one_liner, category, mutates, cost}]` | 意图 → 工具索引;不带 query 返回分类树 |
|
||
| `sspf_describe` | `tool_id, level=brief\|full\|pitfalls` | `{schema, hints{...}, examples[], related[]}` | 取完整 schema + 自提示 |
|
||
| `sspf_call` | `tool_id, args, dry_run?` | `{ok, data, effects[], next_actions[], hints[]}` | 统一执行 |
|
||
|
||
**为什么 `describe` 和 `call` 要分开**:AI 可以先 `dry_run` + 看 pitfalls 再决定要不要真跑;
|
||
也允许「describe 一次、call 多次」,省掉重复 schema 成本。
|
||
|
||
### 6.3 L1/L2:工具分类(约 55 个,分 12 域)
|
||
|
||
| 域 | 工具(id) | 说明 |
|
||
|---|---|---|
|
||
| `context` | `context.get` `context.set_app` | 应用/系统切换 |
|
||
| `schema` | `schema.table.create` `schema.table.list` `schema.table.describe` `schema.table.migrate` | 物理表 |
|
||
| `model` | `model.create` `model.update` `model.list` `model.describe` | 数据模型 |
|
||
| `form` | `form.create` `form.update` `form.release` `form.preview` `form.list` `form.export` `form.import` | 低代码表单 |
|
||
| `menu` | `menu.create` `menu.tree` `menu.update` `menu.delete` | 菜单 |
|
||
| `permission` | `perm.authorize` `perm.role.create` `perm.user.create` `perm.check` `perm.group.*` | 权限 |
|
||
| `dict` | `dict.type.upsert` `dict.data.upsert` `dict.list` `dict.resolve` | 字典 |
|
||
| `data` | `data.query` `data.insert` `data.update` `data.delete` `data.import` | 通用数据 |
|
||
| `workflow` | `flow.create` `flow.bind` `flow.publish` `flow.start` `flow.status` | 流程 |
|
||
| `verify` | `verify.gates` `verify.contract` `verify.smoke` `verify.diff` | 验证(🔴 只读) |
|
||
| `release` | `release.build` `release.deploy` `release.rollback` | 发布 |
|
||
| `ops` | `ops.health` `ops.logs` `ops.db.dump` `ops.db.restore` | 运维 |
|
||
|
||
### 6.4 自提示:工具自带「坑」,不靠文档
|
||
|
||
每个工具必须提供五段(缺一段 CI 红):
|
||
|
||
```rust
|
||
pub struct Hints {
|
||
when_to_use: &'static [&'static str], // 什么场景用
|
||
when_not_to_use: &'static [&'static str], // 什么场景别用(防误用)
|
||
preconditions: &'static [&'static str], // 前置(如「先 context 拿 dbLinkId」)
|
||
pitfalls: &'static [Pitfall], // ❌ wrong / ✅ right / 为什么 / P0-P2
|
||
examples: &'static [Example], // 🔴 必须能被 CI dry_run 跑通
|
||
}
|
||
```
|
||
|
||
实际渲染效果(`sspf_describe("form.create", level="pitfalls")`):
|
||
|
||
```json
|
||
{
|
||
"tool_id": "form.create",
|
||
"hints": {
|
||
"preconditions": ["先调 sspf_context 取 dbLinkId;为空会导致表单挂在默认库"],
|
||
"pitfalls": [
|
||
{
|
||
"severity": "P0",
|
||
"wrong": "字段名用 f_user_id 且 jnpfKey=inputNumber",
|
||
"right": "jnpfKey=relationForm + modelId=关联表单 id",
|
||
"rationale": "关联字段若用 inputNumber,前端渲染不报错但保存时外键为空,列表页显示空白。"
|
||
},
|
||
{
|
||
"severity": "P1",
|
||
"wrong": "enCode 带连字符 registration-form",
|
||
"right": "registration_form(自动 strip,但会多一条修正记录)",
|
||
"rationale": "物理列名不支持连字符;strip 后与前端路由不一致会导致菜单 404。"
|
||
}
|
||
],
|
||
"examples": [
|
||
{ "args": { "enCode": "asset_ledger", "fields": [] }, "note": "最小可用调用" }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**自提示的三条铁律**:
|
||
1. **单一真值源**:`registry` 里写一次,派生 tool schema / `describe` 输出 / 静态文档 / CI 用例
|
||
2. **examples 必须可执行**:CI 对每个 example 跑 `dry_run`,跑不通 = 构建失败(防文档腐烂)
|
||
3. **失败即教学**:错误返回必须带 `hints[] + next_actions[] + doc_ref`,让 AI 一次就能自纠
|
||
|
||
### 6.5 失败返回的形状(比成功更重要)
|
||
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": {
|
||
"code": "FORM_ENCODE_EXISTS",
|
||
"message": "enCode 已存在:asset_ledger",
|
||
"field": "enCode",
|
||
"retryable": false
|
||
},
|
||
"hints": [
|
||
{ "level": "fix", "text": "换一个 enCode,或对已有表单调用 form.update", "auto_fixable": false }
|
||
],
|
||
"next_actions": [
|
||
{ "tool": "form.list", "args": { "keyword": "asset_ledger" }, "why": "先确认是否同一个表单" }
|
||
],
|
||
"doc": "sspf://errors#FORM_ENCODE_EXISTS"
|
||
}
|
||
```
|
||
|
||
### 6.6 Resources / Prompts / 协议特性
|
||
|
||
**Resources**(按需 `resources/read`,不占常驻上下文):
|
||
|
||
| URI | 内容 |
|
||
|---|---|
|
||
| `sspf://contract/endpoints` | 契约端点表(机器可读) |
|
||
| `sspf://ddl/base` | `base_*` DDL |
|
||
| `sspf://docs/module-howto` | 加业务模块指南 |
|
||
| `sspf://registry/tools` | 全量工具索引(离线用) |
|
||
| `sspf://pack/{app}` | 业务包清单与迁移状态 |
|
||
| `sspf://errors` | 错误码字典 |
|
||
|
||
**Prompts**(把多步流程固化成可复用模板):
|
||
|
||
| prompt | 作用 |
|
||
|---|---|
|
||
| `new_business_module` | 加业务模块(含 5 个 elicitation 追问) |
|
||
| `migrate_from_baseline` | 从基线平台导入 |
|
||
| `verify_all` | 跑全部闸门 + 出报告 |
|
||
| `diagnose_500` | 按错误码定位 |
|
||
|
||
**协议特性使用**:
|
||
- `outputSchema` + `structuredContent`:返回强类型,AI 不用解析文本
|
||
- `annotations`:`readOnlyHint`(verify/context 全只读)、`destructiveHint`(delete/restore)、`idempotentHint`(upsert)
|
||
- `elicitation`:缺关键信息时反向问用户(**不要瞎猜**)
|
||
- `Streamable HTTP`:团队共享一个 MCP 实例;本地 stdio 给单人
|
||
|
||
### 6.7 验收判据
|
||
|
||
一个「AI 能独立完成」的闭环,必须全绿:
|
||
|
||
```
|
||
自然语言需求
|
||
→ sspf_context(拿 app/db)
|
||
→ sspf_discover("建一个带审批的报销单")
|
||
→ sspf_describe("form.create", pitfalls)
|
||
→ sspf_call("schema.table.create") ← dry_run 先看 DDL
|
||
→ sspf_call("form.create")
|
||
→ sspf_call("menu.create")
|
||
→ sspf_call("perm.authorize")
|
||
→ sspf_call("form.release")
|
||
→ sspf_call("verify.gates") ← 必须全绿
|
||
→ 前端页面可打开、可增删改查
|
||
```
|
||
|
||
**任一步失败,AI 必须能靠 `hints + next_actions` 自纠,不需要人介入。** 这是 MCP 层的唯一 KPI。
|
||
|
||
---
|
||
|
||
## 7. 契约与命名(第 7 条落地)
|
||
|
||
### 7.1 唯一判据:**前端 / 移动端 / 存量库是否「依赖」它**
|
||
|
||
「依赖」的严格定义:**拿它做判断、查找、拼路径、解析、判分支**。
|
||
只是「显示给人看」的不算依赖。
|
||
|
||
| 类别 | 举例 | 处理 |
|
||
|---|---|---|
|
||
| **结构性字符串**(前端用它做逻辑) | HTTP 路径 `/api/permission/Users`、响应键名 `data.list`、请求头 `Vue-Version: 3`/`App-Code`/`Jnpf-Origin`、错误码 `602`、枚举值(`f_type` 的 1/2、`f_is_system` 的 1/2)、菜单 `urlAddress`/`enCode`、表单 JSON 的 `jnpfKey`、cipher key 字面量 | ❌ **一个字都不改** |
|
||
| **数据库标识**(存量库迁移依赖) | 表名 `base_user`、列名 `f_id`/`f_en_code` | ❌ **一个字都不改** |
|
||
| **展示性文案**(前端只渲染,不判断) | `msg` 里的中文提示、日志、注释、README | ✅ **全改**(语义一致即可) |
|
||
| **内部标识**(前端完全读不到) | crate 名、模块名、类型名、函数名、变量名、文件名 | ✅ **全改** |
|
||
|
||
🔴 这条判据解释了两个容易吵的点:
|
||
|
||
1. **`jnpfKey` 必须保留** —— 它出现在表单 JSON 里,前端 `componentMap.ts` 靠它选组件。
|
||
改了就白屏。名字难看也得留。
|
||
2. **`msg` 可以改** —— 前端只是 `message.error(res.msg)`,不解析内容。
|
||
但**语义不能变**("用户名已存在" 不能改成 "操作失败")。
|
||
|
||
**统一用词**(仅用于「非结构性」位置):
|
||
|
||
| 场合 | 用词 |
|
||
|---|---|
|
||
| 代码标识符 | `baseline`(`BaselineCompat`、`baseline_probe`、`crate::baseline`) |
|
||
| 文档 | **基线平台**(首次出现注明"兼容目标 v7") |
|
||
| 禁止 | `jnpf` / `引迈` / `JNPF` 出现在**新增**文件的标识符与文案里 |
|
||
|
||
### 7.2 `check-naming.sh` 的实现口径
|
||
|
||
不能简单 grep 关键词(会把契约字符串一起拦掉,改了就崩)。三层过滤:
|
||
|
||
```
|
||
第 1 层:豁免区(直接跳过,不检查)
|
||
docs/contract.md、db/schema.sql、src/**/routes.rs 里的路径字面量、
|
||
tests/**(断言要写真实路径)、任何 "..." 里被前端消费的常量白名单
|
||
|
||
第 2 层:必改区(出现即红)
|
||
*.rs / *.toml 里的 标识符(fn/struct/enum/mod/const/变量)、crate 名、注释
|
||
*.md 里的叙述文字(排除引用块与代码块中的契约示例)
|
||
|
||
第 3 层:人工复核区(黄灯,不阻断)
|
||
msg 文案、错误提示
|
||
```
|
||
|
||
实现建议:Rust 侧用 `syn` 解析取标识符(比正则可靠),文档侧用正则可接受。
|
||
🔴 **白名单必须是「显式文件 + 行号」而非「关键词豁免」** —— 否则会漏。
|
||
|
||
### 7.3 规范一致的落地方式
|
||
|
||
「规范保持一致」不等于「代码长得一样」。真正要一致的是**语义**:
|
||
|
||
| 规范项 | 一致性要求 |
|
||
|---|---|
|
||
| 命名规范(`f_` 前缀 / camelCase 键名 / 36 位 UUID) | 逐字一致 |
|
||
| 错误码语义 | 逐字一致(含 600/601/602 的用途区分) |
|
||
| 权限判据 | 两套并存(面 A 按菜单路径、面 B 按 `f_en_code`),语义各自一致 |
|
||
| 分层规范 | 一致,但用 Rust 的方式表达(crate 边界 + trait) |
|
||
| 提交/评审规范 | 沿用公司规范(`dacli/docs/尚数网基本开发规范v3.0.md`) |
|
||
|
||
---
|
||
|
||
## 8. 验证体系(「完全稳定/一致」怎么证明)
|
||
|
||
### 8.1 六道闸门 → 升级为八道
|
||
|
||
现状六道(静态 4 + 契约尺子 2)保留,新增两道:
|
||
|
||
| # | 闸门 | 测什么 | 何时跑 |
|
||
|---|---|---|---|
|
||
| 7 | `check-arch.sh` | crate 边界 AR1–AR5 + 业务包依赖审计 | 每次提交 |
|
||
| 8 | `diff-harness` | 同一语料打两个后端,归一化比对 | 每日 + 发版前 |
|
||
|
||
### 8.2 影子对账(diff harness)
|
||
|
||
```
|
||
tools/diff-harness/
|
||
├── corpus/ # JSONL 语料,一条一个请求
|
||
│ ├── auth.jsonl # 登录/CurrentUser/过期/无权限
|
||
│ ├── crud.jsonl # 5 组 base_* 的增删改查 + 分页 + 搜索
|
||
│ ├── menu.jsonl # 菜单树/多应用隔离
|
||
│ ├── permission.jsonl # 授权写入/读取/四源合并
|
||
│ └── errors.jsonl # 错误码矩阵(400/403/500/600/602)
|
||
├── run.sh # 双打 + 落盘
|
||
├── normalize.py # 归一化(见下)
|
||
└── report.html # 按端点分组的差异报告
|
||
```
|
||
|
||
**归一化规则(必须写死,否则天天误报)**:
|
||
|
||
| 类型 | 处理 |
|
||
|---|---|
|
||
| UUID / 主键 | → `<id>` |
|
||
| 时间戳 | → `<ts>`(保留"是否为空") |
|
||
| 列表顺序 | 按主键排序后再比 |
|
||
| 浮点/金额 | 转字符串比(防 `9.9` vs `9.90`) |
|
||
| 分页 total | 数据不同步时允许差,单独标 `DATA_DRIFT` 不算 P0 |
|
||
| 字段增删 | 基线有、SSPF 无 ⇒ **P0**;SSPF 多 ⇒ P2(前端不读就无害) |
|
||
|
||
**分级与出口**:
|
||
|
||
| 级别 | 定义 | 出口要求 |
|
||
|---|---|---|
|
||
| P0 | 字段缺失 / 类型不同 / 错误码不同 / 权限判定相反 | **= 0** |
|
||
| P1 | 值不同(非 ID/时间)/ 排序不同 | ≤ 3 且每条有豁免记录 |
|
||
| P2 | 多返回字段 / 文案差异 | 不限 |
|
||
|
||
### 8.3 切换的三道门(缺一不可)
|
||
|
||
1. **契约门**:八道闸门全绿 + diff P0=0
|
||
2. **体验门**:同一前端 E2E(登录→菜单→5 个核心页 CRUD)在两个后端全绿
|
||
3. **回滚门**:切流开关能 30 秒内切回;数据双写/单向同步有对账脚本
|
||
|
||
---
|
||
|
||
## 9. 路线图
|
||
|
||
> 阶段出口判据 = 硬条件,不达标不进下一阶段。周期是量级参考,不是承诺。
|
||
> 🔴 **P0 起每个阶段都要过内存门**(§2 判断 ⑥ 的预算表)—— 终端产品形态下,内存超标等于不可交付。
|
||
|
||
### P0 · 锁工具链、拆 crate(约 2 周)
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| 交付 | `rust-toolchain.toml` 锁 **1.95.0**;workspace 拆分(**contract / store / sdk 已落地**,kernel 原地待搬);`sspf-sdk` trait 定稿;`pack.toml` 定稿;`check-arch.sh`(AR1–AR5 + MEM1–MEM2);`check-naming.sh`(NM1–NM4);`mem-budget.sh` |
|
||
| 约束 | 行为零变化(九道闸门必须仍全绿) |
|
||
| 出口 | `cargo build` 通过;九闸绿;`packs/asset` 能独立构建;**空载常驻 ≤ 40 MB 实测(已达 7 MB)**;内部标识零原厂名(NM1–NM3) |
|
||
| 风险 | 拆 crate 引入循环依赖(已定位:`auth → jnpf` 只有 `is_jnpf` + `current_user` 3 处,`is_jnpf` 下沉 contract、分流上移到路由层即可解开) |
|
||
|
||
### P1 · MCP 2.0 骨架 + 基线适配器(约 4 周)
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| 交付 | `sspf-mcp`(4 元工具 + registry + discover/describe);`BaselineHttpAdapter`;首批 20 工具(context/form/menu/dict/permission/data);`sspf://` resources |
|
||
| 价值 | **立刻可用**:AI 通过 MCP 操作现有 Java 后端,开发速度提升先落地;同时充当 P4 对账的「参照侧」 |
|
||
| 出口 | §6.7 闭环全绿;单会话 token 峰值 < 8K;`examples` CI 全通过 |
|
||
| 风险 | 工具粒度设计反复 ⇒ 先按「一次调用 = 一个业务意图」定,别按 API 一一映射 |
|
||
|
||
**P1 已完成(2026-10-31)**:
|
||
|
||
- `crates/sspf-mcp`:协议(stdio NDJSON)+ registry + 4 元工具 + 五段自提示 + resources
|
||
- `NativeAdapter`(进程内,共用 `AppState`)+ `--mcp` 子命令 + `--mcp --with-http` 双形态
|
||
- 业务工具 **19 个**:context(1) / schema(3) / menu(3) / permission(6) / dict(3) / data(2)
|
||
- **授权闭环**:`authorize.grant` / `authorize.revoke` / `effective`(四源并集 + 应用过滤两组数)
|
||
+ `user.create`(建非管理员账号,让「授权是否真的生效」可验证)
|
||
- **多步模板 3 个**:`new_business_module` / `diagnose_menu_not_visible` / `verify_all`;
|
||
测试会核对模板里引用的工具 id 是否真实存在(防腐烂)
|
||
- **`BaselineHttpAdapter`**(`crates/sspf-adapter-baseline`):5 个只读 op 的端点映射
|
||
+ **形状归一化**(`{code,msg,data:{list}}` → native 形状),P4 对账的前置件
|
||
- 两道尺子:`mcp-smoke.sh` 32 条、`baseline-smoke.sh` 10 条
|
||
- 接入说明见 `docs/mcp.md`
|
||
|
||
**P1 待做**:业务工具补到约 55 个(缺 form / model / workflow 三大域)、
|
||
基线适配器按对账需要扩展 op。
|
||
|
||
> ⚠️ 轨道 A 的定位要摆正:它是**过渡期的开发加速器 + 对账基准**,不是终态。
|
||
> 终端产品交付形态只有 Rust 版(判断 ⑥)。
|
||
|
||
### P2 · 低代码元数据引擎 + Rhai 沙箱(约 6 周)
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| 交付 | `sspf-lowcode`:模型/表单/菜单/流程元数据 + 动态 CRUD + 发布版本;visualdev JSON 同构导入;`sspf-expr`(Rhai 沙箱,§4.3 全部限额);`Executor` trait 首版 |
|
||
| 出口 | 基线平台导出的表单 JSON,不改一个字段能在 SSPF 上渲染 + 存取;动态 CRUD 通过列白名单安全测试;Rhai 逃逸测试(`eval`/IO/递归/超深表达式)全部被拒 |
|
||
| 风险 | 表单 JSON 方言多(不同控件)⇒ 先覆盖 top 10 控件,其余降级 input |
|
||
|
||
**P2 已完成(2026-10-31,第一波 P2-a)**:
|
||
|
||
- `crates/sspf-lowcode`:`form`(控件树解析)/ `model`(表结构解析)/ `widget`(54 种 jnpfKey 分类)
|
||
/ `validate`(9 类诊断码),**纯计算**,38 个测试毫秒级跑完(AR7 钉住不许依赖 DB)
|
||
- DDL:`base_visual_dev` / `base_visual_release` 进 `schema.sql`,列与官方逐字一致(21 → 23 张表)
|
||
- 真实样例落地为 fixture:官方初始化数据里的「应收费用」表单(主表 6 字段 / 子表 8 字段)
|
||
- MCP 工具 3 个(只读):`form.list` / `form.describe` / `form.validate`;后两个支持 **inline JSON**
|
||
(不用入库就能校验草稿)
|
||
- `scripts/lowcode-smoke.sh` 8 条,含**两条反自证**:改坏 `__vModel__` 必须被抓、未知控件必须只 warn
|
||
|
||
**第一波刻意没做的**:动态 CRUD(写数据)、写表单定义。原因:写的前置是「解析 + 校验被真实数据验证透」,
|
||
否则等于让 AI 生成前端画不出来的 JSON。**动态 CRUD 已在第二波补上,写表单定义仍未做。**
|
||
|
||
**P2-b 已完成(2026-10-31,第二波)—— 动态 CRUD 闭环**:
|
||
|
||
- `sspf-lowcode::ddl`:**纯计算**建表 DDL(类型映射 / 复合主键 `(f_id, f_tenant_id)` /
|
||
系统列 / 逻辑删除列)+ `rewrite_model`(把真实列回写成 `f_tables_data` 的形态)
|
||
- 内核 `lowcode_ddl::create_and_sync`:建表 → 回写 `f_tables_data`(**幂等**;表已存在则跳过,
|
||
列不同报 `TABLE_EXISTS_DIFFERENT`,不自动 ALTER)
|
||
- 内核 `lowcode_crud` / `lowcode_check`:真实事务执行、子表差集对账、
|
||
**落库前三重校验**(单行唯一 `UNIQUE_CONSTRAINT_VIOLATED` / 业务主键组合唯一
|
||
`BUSINESS_KEY_VIOLATED` / 必填,失败一条 SQL 都不执行)
|
||
- MCP 工具 4 个(写):`schema.table.create` + `data.record.insert/update/delete`;
|
||
写工具**默认 `dryRun=true`**(不传就是演练)
|
||
- 开发期通道 `--seed-lowcode-demo [--dry-run]`:用官方 fixture 造一份可用的低代码功能
|
||
(固定 `enCode=receivableDemo`,幂等;prod 档开库前拒绝;dry-run 连库都不开)
|
||
- `scripts/mcp-smoke.sh` 扩到 **48 条**(M1–M47,其中阶段 B 用 python 动态驱动,
|
||
覆盖「演练不落库 → 真写 → 查证 → 子表差集 → 删除」)
|
||
- `scripts/lowcode-smoke.sh` 扩到 **15 条**(L9–L14:类型映射 / 复合主键 / 逻辑删除列 /
|
||
系统列视图类型,含两条反自证)
|
||
|
||
**P2-b 的关键判断(后续别改坏)**:
|
||
|
||
1. **建表后必须回写** `f_tables_data`:不回写 ⇒ CRUD 层在模型里找不到 `f_delete_mark`,
|
||
逻辑删除直接报 `LOGICAL_DELETE_UNSUPPORTED`(已真实踩到)。
|
||
2. 建表列来源 = **模型**(不是表单控件):官方 `f_tables_data` 本身就是建表后的回写产物,
|
||
列序与官方 DDL 逐列一致;模型驱动少一层「控件类型 ↔ DDL 类型」的多对一映射。
|
||
3. `f_delete_mark` 是 **INTEGER**,不是 boolean(官方 `TableFeildsEnum` 也是 `"int"`)。
|
||
4. **单租户**:`f_tenant_id` 固定 `"0"`,但列 `NOT NULL` 且**参与复合主键** —— 不能省。
|
||
5. 子表更新是**差集对账**(不是整条替换):入参没有的旧行会被删;主表则是部分更新。
|
||
|
||
**P2-b 刻意没做的**(留给 P2-c):读 `base_visual_release`(运行时读发布版)、
|
||
单据号生成器(需序号表)、真正的乐观锁(现在只写 `f_version=0`,不校验)。
|
||
|
||
**P2-b 的前置件**:`docs/visualdev-mechanism.md` —— 从 jnpf Java 源码逐条读出的运行时机制
|
||
(接口契约 15 个端点 / 列名规则 / 系统字段 / 自动填充 / 主子表),每条结论标了源码位置。
|
||
读这份文档时纠正了两个已实现代码里的错误判断(列名归因反了、`calculate` 不是只读)。
|
||
|
||
**实测发现的三条方言**(都已写进代码注释与测试):
|
||
|
||
1. `f_tables_data` 的 `columnName` **全是 null** ⇒ 只能从 `field` 推导,而推导**不等于**真实列名
|
||
(`F_CreatorTime` → `f_creatortime`,实际列是 `f_creator_time`)
|
||
⇒ 本 crate 只保证「表单 ↔ 模型设计稿」自洽;与真实库的一致性由 P2-b 的写工具在落库前比对
|
||
`information_schema`(对不上报 `COLUMN_MISMATCH`,拒绝写)
|
||
2. 子表内字段的 `tableName` 指向**主表**,不是子表 ⇒ 子表归属只能看父节点
|
||
3. `formRef` / `formModel` 是 Vue 变量名,不是固定常量(见过 `elForm`/`formData`,也见过 `formRef`/`dataForm`)
|
||
|
||
### P3 · 业务包 + 动态库 + 双向迁移(约 5 周)
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| 交付 | `sspf-plugin`(L2 静态 + **L3 dylib 完整实现**,§4.5 六条铁律全覆盖);`pack export/import --format=baseline`;`packs/asset` 样板;WASM 执行器(`Executor` 第二实现) |
|
||
| 出口 | §5.3 三条验收全过;asset 包往返幂等;**ABI 三个反自证**:版本不符拒载、插件 panic 不拖垮内核、热替换生效;插件内存超限被强杀 |
|
||
| 风险 | 表名/字段映射不一致 ⇒ 用 `baseline_table` 显式声明,禁止猜;`dlclose` 后重载拿到旧句柄 ⇒ 复制到新路径再 `dlopen` |
|
||
|
||
### P4 · 影子对账 + 切换准备(约 4 周)
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| 交付 | diff-harness + 语料库(≥300 条);切换开关(按 app_code / 菜单 / 用户组分流);回滚脚本;进程沙箱执行器 |
|
||
| 出口 | P0=0、P1≤3;体验门全绿;回滚演练成功一次;**整套峰值内存 ≤ 256 MB** |
|
||
| 风险 | 语料覆盖不足 ⇒ 用前端真实流量采样补语料(脱敏) |
|
||
|
||
### P5 · 切换与增强(持续)
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| 交付 | 真实 PG 支持收口;AI 协作流(需求 → 包 → 验证 → 发布);MCP 工具面全量化 |
|
||
| 出口 | 单二进制替代 Java 栈;部署步骤 ≤ 3 条命令;**目标硬件实测跑通业务 + 沙箱 + 计算三件套** |
|
||
|
||
---
|
||
|
||
## 10. 风险与待决策
|
||
|
||
### 10.1 已识别风险
|
||
|
||
| # | 风险 | 影响 | 缓解 |
|
||
|---|---|---|---|
|
||
| R1 | 拆 crate 破坏现有 147 端点行为 | 高 | P0 只搬不改;六闸 + diff 基线先跑一次存档 |
|
||
| R2 | 表单 JSON 方言覆盖不全 | 中 | 先 top 10 控件;缺失控件降级 + 明确报「不支持」而非静默 |
|
||
| R3 | Rust 动态库 ABI 崩 | 中 | 默认关 feature;只给明确需要的团队;强制版本校验 |
|
||
| R4 | MCP 工具粒度过细 → token 反弹 | 中 | 按业务意图设计;CI 统计 describe 后平均 token,超阈值报警 |
|
||
| R5 | 影子对账语料不足 → 假绿 | 高 | 语料必须来自真实流量采样 + 每条差异人工过一遍 |
|
||
| R6 | 「去原厂字眼」误改契约字符串 | 🔴 极高 | `check-naming.sh` 白名单 + 契约文件只读保护 |
|
||
| R7 | 业务包依赖偷偷膨胀 | 中 | `cargo tree` 审计进 CI;`sspf-sdk` 依赖锁死 serde |
|
||
|
||
### 10.2 待决策(开工前定,不定就按推荐走)
|
||
|
||
### 10.2 决策台账
|
||
|
||
**已定(2026-10-31)**:
|
||
|
||
| # | 决策 | 结论 | 约束 |
|
||
|---|---|---|---|
|
||
| D0 | 工具链 | **Rust 1.95.0**(`rust-toolchain.toml` 全仓锁定,本机既有版本) | L3 动态库强依赖;插件 `build_info` 必须匹配;升级走 §4.5 四步 |
|
||
| D3 | L3 动态加载 | **必做**(不是可选 feature 开关就不给降级余地) | §4.5 六条铁律;装载失败降级不退出 |
|
||
| D4 | 表达式引擎 | **Rhai**(沙箱化,能力全关 + 白名单) | §4.3 五项限额 + 四项约定 |
|
||
| D7 | 命名剥离判据 | **前端/移动端/存量库是否依赖**(§7.1) | 结构性字符串一字不改;展示性文案可改 |
|
||
| D8 | 部署形态 | **终端产品**(客户现场 / 一体机 / 边缘) | 内存预算进每阶段出口 |
|
||
|
||
**仍待定(不定就按推荐走)**:
|
||
|
||
| # | 决策 | 推荐 | 备选 |
|
||
|---|---|---|---|
|
||
| D1 | 数据库形态 | P0–P4 用 pglite(零依赖);P5 提供真实 PG 后端(同一 SQL 方言) | 直接上 PG(部署要求变高,违背终端形态) |
|
||
| D2 | MCP 传输 | 本地 stdio + 团队 Streamable HTTP 双支持 | 只 stdio |
|
||
| D5 | 工具命名 | MCP 层 `sspf_*`(4 个元工具)+ `域.动作`(tool_id) | 扁平命名 |
|
||
| D6 | 业务包目录 | `packs/<app_code>/`,与 `app_code` 同名 | 按团队分目录 |
|
||
| D9 | 插件隔离默认值 | `in-process`(快);客户端可切 `process`(稳) | 直接默认进程隔离(性能损失大) |
|
||
| D10 | 沙箱运行时 | WASM(wasmtime + 组件模型) | 独立进程 + 容器(重,但可跑任意语言) |
|
||
|
||
---
|
||
|
||
## 11. 与现有文档的关系
|
||
|
||
| 文档 | 职责 | 本文件与它的关系 |
|
||
|---|---|---|
|
||
| `CLAUDE.md` | 当前阶段红线 + 范围 | 本文件定长期架构;CLAUDE.md 的 §2 范围随阶段滚动 |
|
||
| `HANDOFF.md` | 现场交接 | 不变 |
|
||
| `MIGRATION.md` | Rust ⇄ 基线平台逐件映射 | 本文件 §5 是其上位设计 |
|
||
| `JNPF_COMPAT_SURFACE.md` | 面 B 规格 | 契约真源,不改 |
|
||
| `PERMISSION.md` | 权限与 `base_*` 红线 | 不改 |
|
||
| `HOWTO_MODULE.md` | 加模块操作手册 | P3 后改为「加业务包」手册 |
|
||
| 本文件 | **架构基线 + 路线图** | 阶段推进只改 §9 的勾 |
|
||
|
||
---
|
||
|
||
## 12. 变更记录
|
||
|
||
| 日期 | 变更 |
|
||
|---|---|
|
||
| 2026-10-31 | 首版:三层定位、双轨并行、五条核心判断、crate 拆分、L0–L3 动态加载、MCP 2.0 元工具设计、业务包双向迁移、影子对账、P0–P5 路线 |
|