fix(skill): 自检/文档同步到方案 C(SC3/SC4/SC5 + rustdocflags + description)

- check-scaffold.py: 三条判据从旧模型(sspf 必须声明为 Cargo 依赖)改为方案 C:
  SC3 应用不声明平台/框架件;SC4 业务包不声明外部依赖;
  SC5 Cargo.toml 不出现 sspf(平台由 .cargo/config.toml 的 --extern 提供)。
  _base_tree 与 VIOLATIONS 同步,反自证仍 6/6。
- fetch-platform.sh: 生成的 .cargo/config.toml 同时写 rustdocflags
  (cargo test 的 doctest 走 rustdoc,不吃 build.rustflags,之前 E0432)。
- SKILL.md frontmatter description 改为「预编译 rlib / Gitea Release 按 tag+平台取包 / 零重编」。
- Cargo.toml 头部、HOWTO_MODULE、docs/runbook、new-pack/pack-sync 注释同步。

验证:verify.sh 全量 7/7(静态 3 步 + cargo test + release 构建 + 面 A/面 B 各 18 断言)。
This commit is contained in:
admin committed 2026-11-05 13:54:52 +08:00
1 parent a9c6bd34a3
commit d8a8165dd7
8 files changed
+82 -62

No files matched your search

+10 -9
View File
@@ -1,23 +1,24 @@
# ssw-jnpf-lite-rust —— cargo workspace 根
#
# 🔴 **平台不在本仓**(2026-11-04 改造):
# 🔴 **平台不在本仓**(2026-11-04 改造;2026-11-05 升级为方案 C):
# 平台能力(登录 / 权限 / 面 A·B / 低代码 / MCP / 177 张 base_* 表)来自
# **已发布的 `sspf` 包**(git tag `v0.5.0`),不是本仓自己实现的一份。
# **平台仓每版本发布的 sspf 包**(预编译 rlib,不再消费源码),不是本仓自己实现的一份。
# 本仓只留:**示例业务包(`packs/*`)+ 面 A 适配器(`src/backend/src/modules`)
# + 薄装配入口(`src/backend/src/main.rs`)+ 前端产物**。
#
# 🔴 **依赖只有一个来源**:`[workspace.dependencies] sspf`,成员 crate 一律
# `sspf = { workspace = true }`。要升平台版本 ⇒ **只改这一行**(升 tag),
# 不许在任何成员里写第二份 git/path 依赖。
# 🔴 **本文件不声明任何外部依赖**(方案 C):`sspf` / `axum` / `tokio` / `serde` /
# `serde_json` / `http` / `bytes` 全部由 `scripts/fetch-platform.sh` 生成的
# `.cargo/config.toml`(`--extern` + `-L dependency`)从平台包 `lib/` 喂入。
# 升平台 = `bash scripts/fetch-platform.sh <版本>`;**不要**再写回 git/path/version
# 依赖(会导致「同名 crate 两实例」→ 跨 sspf API 边界 E0308)。
#
# 🔴 成员 crate 不得再写 `[profile.*]`(cargo 直接报错),profile 只在本文件。
[workspace]
members = ["src/backend", "packs/*"]
# 🔴 **exclude vendor/**:平台发布包解包在这里(`vendor/sspf-vX.Y.Z/`),它自带
# 自己的 workspace 根(含 `[workspace.dependencies]`)。若不 exclude,cargo 会把
# 包内 crate 误并入职本仓 workspace,导致 `libc` 等 `workspace = true` 继承解析失败。
# exclude 后,包内 crate 用包自己的 workspace 根解析,path 依赖照常工作。
# 🔴 **exclude vendor/**:平台包解包在这里(`vendor/sspf-vX.Y.Z/`,方案 C 只含
# `lib/` 等,不含 crate 源码)。仍排除它,防止将来手工解出源码时被误并入本仓
# workspace(那会让 `libc` 等 `workspace = true` 继承解析失败)。
exclude = ["vendor"]
resolver = "2"
+2 -2
View File
@@ -11,7 +11,7 @@
```
packs/<app>/ ← 业务真源(你写的)
Cargo.toml 只依赖 sspf 门面
Cargo.toml 不声明外部依赖(sspf 走 .cargo/config.toml 的 --extern)
pack.toml 清单:app_code / 表 / 契约版本区间
schema/001_init.sql 建表(跟着包走,include_str! 进二进制)
src/lib.rs 列 + spec + 菜单 + 面 B 路由 + Pack 实现
@@ -41,7 +41,7 @@ bash scripts/new-pack.sh blog Post --name "文章" \
它会:
1. 建 `packs/blog/{Cargo.toml,pack.toml,schema/001_init.sql,src/lib.rs}`(表名 `blog_post`);
1. 建 `packs/blog/{Cargo.toml,pack.toml,schema/001_init.sql,src/lib.rs}`(表名 `blog_post`;`Cargo.toml` 的 `[dependencies]` **留空**);
2. 建 `src/backend/src/modules/blog.rs`(面 A 适配器,3 条路由);
3. 跑 `pack-sync.py` 把四处生成位置补齐。
+1 -1
View File
@@ -1,6 +1,6 @@
---
name: ssw-jnpf-lite-rust
description: Rust 全栈 MVP 脚手架(**平台来自 sspf 发布包,vendor/ 解包,不再依赖 git 仓**;本仓只有业务样板 + 薄装配 + 前端产物 + 尺子),契约与数据模型从第一天起对齐 JNPF 标准版(cipher / ActionResult / f_ 列 / varchar(50) UUID / base_* 权限表 / 进程内原生 PostgreSQL),前后端同一进程同时提供「面 A(ssw 契约 30 条)」与「面 B(官方 JNPF 形状 5 条 + 2 条共用按 Vue-Version 头分流)」两套契约。适用于「AI 开发 MVP 阶段要 Rust 全栈快速迭代、稳定后迁 JNPF 标准栈」的场景,含用户/角色/机构/菜单/授权五套管理页与四源合并菜单守卫。加业务模块见同目录 HOWTO_MODULE.md。
description: Rust 全栈 MVP 脚手架(**平台来自 sspf 预编译 rlib:按 tag+目标平台从 Gitea Release 取包,零重编平台与 axum**;本仓只有业务样板 + 薄装配 + 前端产物 + 尺子),契约与数据模型从第一天起对齐 JNPF 标准版(cipher / ActionResult / f_ 列 / varchar(50) UUID / base_* 权限表 / 进程内原生 PostgreSQL),前后端同一进程同时提供「面 A(ssw 契约 30 条)」与「面 B(官方 JNPF 形状 5 条 + 2 条共用按 Vue-Version 头分流)」两套契约。适用于「AI 开发 MVP 阶段要 Rust 全栈快速迭代、稳定后迁 JNPF 标准栈」的场景,含用户/角色/机构/菜单/授权五套管理页与四源合并菜单守卫。加业务模块见同目录 HOWTO_MODULE.md。
type: skill
---
+3 -3
View File
@@ -208,9 +208,9 @@ python3 scripts/check-scaffold.py --self-test # 期望:反自证 6/6
|---|---|
| **SC1** | 本仓没有平台实现(`src/backend/src/platform/` · `routes.rs` · `bootstrap.rs` · `db/schema.sql` · `crates/`) |
| **SC2** | 业务侧没有 `base_*` 建表语句(`docs/` 里的参考 DDL 不算 —— 它不参与运行) |
| **SC3** | 应用 crate 只依赖门面 `sspf`(+ axum/tokio + 业务包),不直接依赖 `sspf-*` 内部 crate |
| **SC4** | 每个业务包只依赖 `sspf`,且 `Cargo.toml` / `pack.toml` / `schema/001_init.sql` / `src/lib.rs` 齐全 |
| **SC5** | `sspf` 只从 workspace 根的 **vendor 包 path** 来(`vendor/sspf-vX.Y.Z/crates/sspf`);成员不许另写 `git` / `path` / `version` |
| **SC3** | 应用 crate **不声明**平台/框架件(`sspf`/`axum`/`tokio`/…),平台走 `.cargo/config.toml` 的 `--extern` |
| **SC4** | 每个业务包**不声明外部依赖**,且 `Cargo.toml` / `pack.toml` / `schema/001_init.sql` / `src/lib.rs` 齐全 |
| **SC5** | `Cargo.toml`(workspace 与成员)里**不出现 `sspf`**;平台由 `.cargo/config.toml` 的 `--extern` 提供 |
| **SC6** | 生成物与 `packs/*` 不漂移(复用 `pack-sync.py --check`) |
🔴 **反自证**:`--self-test` 给 6 条判据各造一个**真实违规**(抄回 `platform/`、写
+55 -43
View File
@@ -14,9 +14,9 @@
|---|---|---|
| SC1 | 没有平台实现目录(`platform/` / `routes.rs` / `crates/` / `db/schema.sql`) | 把平台源码抄回来 |
| SC2 | 没有 `base_*` 建表语句 | 业务包/应用自建平台表 |
| SC3 | 应用 crate 只依赖 `sspf` 门面 | 直接依赖 `sspf-core` / `pglite-rs` 等内部件 |
| SC4 | 每个业务包只依赖 `sspf`,且目录齐全 | 包里去连库 / 缺 `pack.toml` |
| SC5 | `sspf` 只从 workspace 的 git tag 来(成员不另写来源) | 有人偷偷改成 `path = "../ssw-platform"` |
| SC3 | 应用 crate 不声明平台/框架件(`sspf`/`axum`/`tokio`/… 全走 `--extern`) | 声明 `sspf-core` / `sspf` / `axum` 等,破坏 rlib 同源 |
| SC4 | 每个业务包不声明外部依赖,且目录齐全 | 包里去连库 / 缺 `pack.toml` |
| SC5 | `Cargo.toml` 里不出现 `sspf`(平台由 `.cargo/config.toml` 的 `--extern` 提供) | 有人又把 `sspf` 写成 path/git/version 依赖 |
| SC6 | 生成物与 `packs/*` 不漂移 | 加包没跑 `pack-sync.py` |
用法:
@@ -111,30 +111,34 @@ def _deps(toml_path):
return data.get("dependencies", {}) or {}
# 方案 C(2026-11-05):下面这些全部由平台包 lib/ 经 `.cargo/config.toml` 的 `--extern`
# 提供;一旦在 Cargo.toml 再声明一份,就是「同名 crate 两个实例」→ 跨 sspf API 边界 E0308。
_EXTERN_ONLY = (
"sspf", "axum", "tokio", "serde", "serde_json", "http", "bytes",
"ssw-platform", "pglite-rs", "aes", "ecb", "md-5",
)
def sc3_app_only_needs_facade(root):
"""应用 crate 只准依赖门面 `sspf`(+ 纯业务/框架件)。"""
"""应用 crate 只依赖业务包;平台/框架件一律走 .cargo/config.toml 的 --extern。"""
path = os.path.join(root, "src/backend/Cargo.toml")
if not os.path.isfile(path):
return False, "找不到 src/backend/Cargo.toml"
deps = _deps(path)
# 🔴 `sspf-pack-*` 是**业务包**(本仓自己的东西),不是平台内部件;
# 真正不许出现的是平台拆出来的那些 crate 与「被门面收编」的基础件。
# `sspf-pack-*` 是本仓自己的业务包(合法);其余平台拆件/框架件都不许声明。
bad = [
k
for k in deps
if (k.startswith("sspf-") and not k.startswith("sspf-pack-"))
or k in ("ssw-platform", "pglite-rs", "aes", "ecb", "md-5")
if k in _EXTERN_ONLY or (k.startswith("sspf-") and not k.startswith("sspf-pack-"))
]
if "sspf" not in deps:
return False, "应用 crate 没依赖 `sspf`(平台从哪来?)"
if bad:
return False, "应用 crate 直接依赖了平台内部件/被门面收编的件:" + ", ".join(sorted(bad))
return True, "应用 crate 只依赖 `sspf` 门面(+ axum/tokio + 业务包)"
return False, "应用 crate 声明了平台/框架件(应由 .cargo/config.toml --extern 提供):" + ", ".join(sorted(bad))
return True, "应用 crate 只依赖业务包(平台/框架件走 --extern)"
def sc4_packs_are_thin(root):
"""每个业务包只依赖 `sspf`,且四件套齐全。"""
"""每个业务包不声明外部依赖(`sspf` 走 --extern),且四件套齐全。"""
packs_dir = os.path.join(root, "packs")
if not os.path.isdir(packs_dir):
return False, "没有 packs/(示例业务包在哪?)"
@@ -155,41 +159,41 @@ def sc4_packs_are_thin(root):
cargo = os.path.join(base, "Cargo.toml")
if os.path.isfile(cargo):
deps = _deps(cargo)
extra = [k for k in deps if k != "sspf"]
if "sspf" not in deps:
problems.append(f"packs/{app} 没依赖 `sspf`")
if extra:
problems.append(f"packs/{app} 多了依赖:{', '.join(sorted(extra))}")
if deps:
problems.append(
f"packs/{app} 声明了依赖(应留空,平台/框架件走 --extern):{', '.join(sorted(deps))}"
)
if problems:
return False, ";".join(problems)
return True, f"{len(apps)} 个包都只依赖 `sspf`,目录齐全"
return True, f"{len(apps)} 个包都不声明外部依赖,目录齐全"
def sc5_sspf_comes_from_a_tag(root):
"""`sspf` 必须从 workspace 的 **git tag** 来,成员不许另写来源。"""
def sc5_no_sspf_in_cargo(root):
"""`Cargo.toml` 里不得出现 `sspf`:平台由 `.cargo/config.toml` 的 `--extern` 提供。"""
ws = os.path.join(root, "Cargo.toml")
with open(ws, "rb") as f:
data = tomllib.load(f)
dep = (data.get("workspace", {}).get("dependencies", {}) or {}).get("sspf")
if dep is None:
return False, "workspace.dependencies 里没有 `sspf`"
if isinstance(dep, str):
return False, "`sspf` 写成版本号(应锁 git tag,否则本地与 CI 拿到的不是同一份)"
if "git" not in dep or "tag" not in dep:
return False, "`sspf` 必须同时写 `git` 与 `tag`(现在是 %r)" % (dep,)
wdeps = (data.get("workspace", {}) or {}).get("dependencies", {}) or {}
if "sspf" in wdeps:
return False, "workspace.dependencies 仍声明了 `sspf`(方案 C 应由 .cargo/config.toml 的 --extern 提供)"
# 成员不许另写来源
offenders = []
for member in ("src/backend/Cargo.toml",):
path = os.path.join(root, member)
if os.path.isfile(path):
d = _deps(path).get("sspf")
if isinstance(d, dict) and ("git" in d or "path" in d or "version" in d):
offenders.append(member)
if os.path.isfile(path) and "sspf" in _deps(path):
offenders.append(member)
if offenders:
return False, "成员自己写了 `sspf` 来源(应 `{ workspace = true }`):" + ", ".join(offenders)
return True, f"`sspf` 锁 git tag `{dep.get('tag')}`"
return False, "成员声明了 `sspf`(应由 .cargo/config.toml 的 --extern 提供):" + ", ".join(offenders)
# 若已生成 config,顺手校验它确实喂了 sspf(没生成不算错:verify 可在 fetch 之前跑)
cfg = os.path.join(root, ".cargo/config.toml")
if os.path.isfile(cfg):
text = open(cfg, encoding="utf-8", errors="ignore").read()
if "sspf=" not in text or "dependency=" not in text:
return False, ".cargo/config.toml 里没有 `--extern sspf=…` + `-L dependency=…`(重跑 scripts/fetch-platform.sh)"
return True, "平台经 .cargo/config.toml 的 --extern 提供(Cargo.toml 未声明 sspf)"
return True, "Cargo.toml 未声明 sspf(构建前先跑 scripts/fetch-platform.sh 生成 .cargo/config.toml)"
def sc6_generated_files_in_sync(root):
@@ -211,9 +215,9 @@ def sc6_generated_files_in_sync(root):
CHECKS = [
("SC1", "本仓没有平台实现", sc1_no_vendored_platform),
("SC2", "业务侧不建 base_* 表", sc2_no_base_tables),
("SC3", "应用只依赖门面 sspf", sc3_app_only_needs_facade),
("SC4", "业务包只依赖 sspf", sc4_packs_are_thin),
("SC5", "sspf 锁 git tag", sc5_sspf_comes_from_a_tag),
("SC3", "应用不声明平台/框架件", sc3_app_only_needs_facade),
("SC4", "业务包不声明外部依赖", sc4_packs_are_thin),
("SC5", "Cargo.toml 不出现 sspf", sc5_no_sspf_in_cargo),
("SC6", "生成物无漂移", sc6_generated_files_in_sync),
]
@@ -249,19 +253,27 @@ def _base_tree(root):
_mk(
root,
"Cargo.toml",
'[workspace]\nmembers = ["src/backend", "packs/demo"]\n'
'[workspace.dependencies]\nsspf = { git = "http://x/y.git", tag = "v0.4.0" }\n',
'[workspace]\nmembers = ["src/backend", "packs/demo"]\n',
)
# 方案 C:平台经 .cargo/config.toml 的 --extern 提供(不再写进 Cargo.toml)
_mk(
root,
".cargo/config.toml",
'[build]\nrustflags = [\n'
' "--extern", "sspf=/tmp/lib/libsspf-x.rlib",\n'
' "-L", "dependency=/tmp/lib",\n'
']\n',
)
_mk(
root,
"src/backend/Cargo.toml",
'[package]\nname = "app"\nversion = "0.0.0"\n[dependencies]\nsspf = { workspace = true }\n',
'[package]\nname = "app"\nversion = "0.0.0"\n[dependencies]\n',
)
_mk(root, "src/backend/src/lib.rs", "// app\n")
_mk(
root,
"packs/demo/Cargo.toml",
'[package]\nname = "sspf-pack-demo"\nversion = "0.0.0"\n[dependencies]\nsspf = { workspace = true }\n',
'[package]\nname = "sspf-pack-demo"\nversion = "0.0.0"\n[dependencies]\n',
)
_mk(root, "packs/demo/pack.toml", '[pack]\napp_code = "demo"\n')
_mk(root, "packs/demo/src/lib.rs", "// pack\n")
@@ -289,7 +301,7 @@ def _base_tree(root):
_mk(
root,
"src/backend/Cargo.toml",
'[package]\nname = "app"\nversion = "0.0.0"\n[dependencies]\nsspf = { workspace = true }\n'
'[package]\nname = "app"\nversion = "0.0.0"\n[dependencies]\n'
"# >>>GEN:PACK_DEPS\n# <<<GEN:PACK_DEPS\n",
)
subprocess.run(
+7 -1
View File
@@ -179,11 +179,17 @@ if [[ -n "${SSPF_RLIB}" ]]; then
# ⚠️ 前提:rustc 版本 == vendor/${PKG}/rust-toolchain.toml(ABI 锁,否则链接失败)。
# 极端回退(要改平台源码):删本文件 + 改用 git 依赖 sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v${VERSION}" }
[build]
# rustc 用
rustflags = [
${EXTERN_LINES} "-L", "dependency=${SKILL_ROOT}/vendor/${PKG}/lib",
]
# 🔴 cargo test 的 doctest 走 rustdoc,**不吃 build.rustflags**;必须同样喂一遍,
# 否则测试阶段 doctest 里的 `use sspf::` 会 E0432(unresolved import)。
rustdocflags = [
${EXTERN_LINES} "-L", "dependency=${SKILL_ROOT}/vendor/${PKG}/lib",
]
EOF
echo "==> 已生成 .cargo/config.toml(--extern sspf/axum/tokio/serde/serde_json/http/bytes + -L dependency)"
echo "==> 已生成 .cargo/config.toml(rustflags + rustdocflags:--extern sspf/axum/tokio/serde/serde_json/http/bytes + -L dependency)"
echo " 消费方 Cargo.toml 无需声明这些依赖;代码照用 use sspf:: / use axum::"
else
echo "!! ⚠️ 包内 lib/ 缺 libsspf-*.rlib(旧包?)。请用新版 release.sh 重新出包:" >&2
+3 -2
View File
@@ -185,8 +185,9 @@ def pack_lib(app, entity, name, table, columns, sort):
//!
//! 🔴 **这里是业务真源**:表 + 列 + 菜单 + 面 B 路由都在这个目录里。
//! 面 A 适配器在同仓 `src/backend/src/modules/{app}.rs`(只做转发,不重写 spec)。
//! 🔴 **依赖纪律**:本包只依赖 `sspf` 门面;出现 axum / tokio / pglite 会被
//! `scripts/check-scaffold.sh` 判红 —— 这是「整目录可搬走」的技术保证。
//! 🔴 **依赖纪律**:本包**不声明外部依赖**(`sspf` 走 `.cargo/config.toml` 的 --extern);
//! 出现 sspf / axum / tokio / pglite 会被 `scripts/check-scaffold.py` 判红 ——
//! 这是「整目录可搬走」的技术保证。
use sspf::{{
BusinessPack, ColumnSpec, EntitySpec, HttpMethod, Manifest, MenuSpec, PackRoute, RouteAction,
+1 -1
View File
@@ -15,7 +15,7 @@
`--check` 在「改了包没跑生成」时**红**,不要让漂移活到运行时。
🔴 **真源**:
- 表 DDL / 列 / 菜单 / 面 B 路由 ⇒ `packs/<app>/`(业务包,只依赖 `sspf` 门面)
- 表 DDL / 列 / 菜单 / 面 B 路由 ⇒ `packs/<app>/`(业务包,不声明外部依赖,走 --extern)
- 面 A 适配器 / spec 转发 ⇒ `src/backend/src/modules/<app>.rs`
用法: