- 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 断言)。
440 lines
14 KiB
Python
Executable File
440 lines
14 KiB
Python
Executable File
#!/usr/bin/env python3
|
||
# -*- coding: utf-8 -*-
|
||
"""new-pack —— 造一个业务包(`packs/<app>/`)+ 它的面 A 适配器。
|
||
|
||
🔴 **加业务只碰两处**:业务包(表 / 列 / 菜单 / 面 B 路由)与面 A 适配器。
|
||
其余(`packs_gen.rs`、`modules/mod.rs` 的五个段、应用 `Cargo.toml` 的包依赖)
|
||
全部由 `pack-sync.py` 生成 ⇒ 手抄漏一处就静默 404 的情况**在机制上不存在**。
|
||
|
||
用法:
|
||
python3 scripts/new-pack.py <app> <Entity> --name "中文名" \\
|
||
[--columns "title:VARCHAR(255),price:NUMERIC(12,2)"] [--sort 20]
|
||
|
||
例:
|
||
python3 scripts/new-pack.py blog Post --name "文章" --columns "title:VARCHAR(255),body:TEXT"
|
||
⇒ packs/blog/{Cargo.toml,pack.toml,schema/001_init.sql,src/lib.rs}
|
||
⇒ src/backend/src/modules/blog.rs
|
||
⇒ 自动跑 pack-sync.py 补齐生成段
|
||
|
||
生成后:`cargo check` + `bash scripts/verify.sh`(面 A / 面 B 两把尺子会打到新端点)。
|
||
|
||
退出码:0 = 成功 / 2 = 用法错或目标已存在
|
||
"""
|
||
|
||
import os
|
||
import re
|
||
import subprocess
|
||
import sys
|
||
|
||
HERE = os.path.dirname(os.path.abspath(__file__))
|
||
ROOT = os.environ.get("PACK_SYNC_ROOT") or os.path.dirname(HERE)
|
||
|
||
|
||
def camel_to_snake(s):
|
||
s = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", s)
|
||
return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s).lower()
|
||
|
||
|
||
def camel_to_kebab(s):
|
||
return camel_to_snake(s).replace("_", "-")
|
||
|
||
|
||
def lower_camel(s):
|
||
return s[0].lower() + s[1:]
|
||
|
||
|
||
def split_columns(spec):
|
||
"""按逗号切列定义,但**不切括号里的逗号**(`NUMERIC(12,2)`)。"""
|
||
parts, buf, depth = [], "", 0
|
||
for ch in spec:
|
||
if ch == "(":
|
||
depth += 1
|
||
elif ch == ")":
|
||
depth -= 1
|
||
if ch == "," and depth == 0:
|
||
parts.append(buf)
|
||
buf = ""
|
||
else:
|
||
buf += ch
|
||
if buf.strip():
|
||
parts.append(buf)
|
||
return parts
|
||
|
||
|
||
def parse_columns(spec):
|
||
"""`"title:VARCHAR(255),price:NUMERIC(12,2)"` ⇒ [(name, sql_type, numeric)]。"""
|
||
cols = []
|
||
if not spec:
|
||
return cols
|
||
for item in split_columns(spec):
|
||
item = item.strip()
|
||
if not item:
|
||
continue
|
||
if ":" not in item:
|
||
raise SystemExit(f"列定义缺类型:{item!r}(应该是 `名字:SQL类型`)")
|
||
name, sql_type = item.split(":", 1)
|
||
name = name.strip()
|
||
if not re.fullmatch(r"[a-z][a-z0-9_]*", name):
|
||
raise SystemExit(f"列名只收小写字母/数字/下划线:{name!r}")
|
||
sql_type = sql_type.strip()
|
||
numeric = sql_type.upper().startswith(("NUMERIC", "DECIMAL", "REAL", "DOUBLE"))
|
||
cols.append((name, sql_type, numeric))
|
||
return cols
|
||
|
||
|
||
def pack_toml(app, entity, name, table, columns):
|
||
return f"""# 业务包清单 —— `{app}`({name})。
|
||
# 🔴 本文件不是给 cargo 读的,是给装载器(`sspf::load_static` 的 JSON 快照对账)
|
||
# 与导出工具读的。改了它 ⇒ 必须跑 `python3 scripts/pack-sync.py`。
|
||
|
||
[pack]
|
||
app_code = "{app}"
|
||
name = "{name}"
|
||
version = "1.0.0"
|
||
kernel = ">=0.4,<0.5" # 契约版本区间(不是 cargo 版本)
|
||
migratable = true
|
||
|
||
[pack.compat]
|
||
baseline = "react-demo" # 对齐基准
|
||
frontend = "vue3" # 前端族(决定表单 JSON 方言)
|
||
tenant = false # 本期单租户(列仍带 f_tenant_id,见 DDL 注释)
|
||
|
||
[[pack.tables]]
|
||
name = "{table}"
|
||
ddl = "schema/001_init.sql"
|
||
baseline_table = "{table}"
|
||
|
||
[pack.metadata]
|
||
forms = []
|
||
models = []
|
||
menus = []
|
||
flows = []
|
||
|
||
[pack.build]
|
||
kind = "none"
|
||
"""
|
||
|
||
|
||
def pack_cargo(app):
|
||
return f"""[package]
|
||
name = "sspf-pack-{app}"
|
||
version.workspace = true
|
||
edition.workspace = true
|
||
rust-version.workspace = true
|
||
|
||
# 🔴 业务包只允许依赖平台门面 `sspf`。
|
||
# 出现 axum / tokio / pglite ⇒ `scripts/check-scaffold.sh` 直接红
|
||
# ⇒ 「整目录可搬走」的技术保证。
|
||
[dependencies]
|
||
sspf = {{ workspace = true }}
|
||
"""
|
||
|
||
|
||
def ddl_sql(app, entity, table, columns):
|
||
col_lines = "".join(f" f_{n} {t},\n" for n, t, _ in columns)
|
||
return f"""-- {table} —— {entity} 的业务表(业务包自带的 DDL)。
|
||
--
|
||
-- 🔴 **DDL 跟着包走**:本文件由 `packs/{app}/src/lib.rs` 用 `include_str!`
|
||
-- 编译进二进制 ⇒ 启动时按包顺序幂等执行(不再手抄进平台 schema)。
|
||
-- 🔴 **只许建本包自己的表**,**不许建 `base_*`**(装载器会拦)。
|
||
-- 🔴 `f_tenant_id` 是包 DDL 的硬要求(本期单租户,值恒 `'0'`);
|
||
-- spec 的列清单**不含**它 ⇒ 面 A / 面 B 的 JSON 形状不受影响。
|
||
|
||
CREATE TABLE IF NOT EXISTS {table} (
|
||
f_id VARCHAR(50) NOT NULL,
|
||
{col_lines} f_creator_user_id VARCHAR(50),
|
||
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
|
||
f_delete_mark INTEGER DEFAULT 0,
|
||
f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
|
||
PRIMARY KEY (f_id, f_tenant_id)
|
||
);
|
||
"""
|
||
|
||
|
||
def pack_lib(app, entity, name, table, columns, sort):
|
||
up = camel_to_snake(entity).upper() # DATA_RESOURCE
|
||
lc = lower_camel(entity) # dataResource
|
||
cols_rs = []
|
||
for n, _t, numeric in columns:
|
||
cols_rs.append(
|
||
f""" ColumnSpec {{
|
||
column: "f_{n}",
|
||
json_key: "{lower_camel(n)}",
|
||
default: None,
|
||
numeric: {"true" if numeric else "false"},
|
||
}},"""
|
||
)
|
||
cols_rs.append(
|
||
""" ColumnSpec {
|
||
column: "f_creator_user_id",
|
||
json_key: "creatorUserId",
|
||
default: None,
|
||
numeric: false,
|
||
},
|
||
ColumnSpec {
|
||
column: "f_creator_time",
|
||
json_key: "creatorTime",
|
||
default: None,
|
||
numeric: false,
|
||
},"""
|
||
)
|
||
columns_block = "\n".join(cols_rs)
|
||
numeric_list = ", ".join(f'"f_{n}"' for n, _t, num in columns if num)
|
||
|
||
return f'''//! {app} —— {name}业务包。
|
||
//!
|
||
//! 🔴 **这里是业务真源**:表 + 列 + 菜单 + 面 B 路由都在这个目录里。
|
||
//! 面 A 适配器在同仓 `src/backend/src/modules/{app}.rs`(只做转发,不重写 spec)。
|
||
//! 🔴 **依赖纪律**:本包**不声明外部依赖**(`sspf` 走 `.cargo/config.toml` 的 --extern);
|
||
//! 出现 sspf / axum / tokio / pglite 会被 `scripts/check-scaffold.py` 判红 ——
|
||
//! 这是「整目录可搬走」的技术保证。
|
||
|
||
use sspf::{{
|
||
BusinessPack, ColumnSpec, EntitySpec, HttpMethod, Manifest, MenuSpec, PackRoute, RouteAction,
|
||
RouteGuard,
|
||
}};
|
||
|
||
/// 本包自带的 DDL(编译进二进制 ⇒ 包目录可整目录搬走)。
|
||
pub const {up}_DDL: &str = include_str!("../schema/001_init.sql");
|
||
|
||
/// 包的统一 DDL 出口(`表名 → DDL 文本`)—— 内核只认这一种写法。
|
||
pub const DDLS: &[(&str, &str)] = &[("{table}", {up}_DDL)];
|
||
|
||
/// `{table}` 的列清单(**顺序 = 响应 JSON 的键序**)。
|
||
const {up}_COLUMNS: &[ColumnSpec] = &[
|
||
{columns_block}
|
||
];
|
||
|
||
/// 实体 spec(面 A / 面 B 共用这一份)。
|
||
pub const {up}_SPEC: EntitySpec = EntitySpec {{
|
||
app_code: "{app}",
|
||
entity: "{entity}",
|
||
table: "{table}",
|
||
// 🔴 `module_key` 必须 == 菜单 `url_address` == 前端 Route path(三处一字不差)。
|
||
module_key: Some("{app}/{entity}"),
|
||
columns: {up}_COLUMNS,
|
||
numeric_columns: &[{numeric_list}],
|
||
creator_fixed: None,
|
||
}};
|
||
|
||
/// 本包的内置菜单(`url_address` 与 spec 的 `module_key` 一字不差)。
|
||
pub const {up}_MENU: MenuSpec = MenuSpec {{
|
||
id: "m_{app}",
|
||
full_name: "{name}",
|
||
en_code: "permission.{app}.{lc}",
|
||
url_address: "{app}/{entity}",
|
||
parent_id: "0",
|
||
menu_type: 2,
|
||
icon: Some("app"),
|
||
sort_code: {sort},
|
||
system_en_code: "mainSystem",
|
||
}};
|
||
|
||
/// 包清单(与 `pack.toml` 的 `[pack]` 段一致)。
|
||
const MANIFEST: Manifest = Manifest {{
|
||
app_code: "{app}",
|
||
name: "{name}",
|
||
version: "1.0.0",
|
||
kernel_req: ">=0.4,<0.5",
|
||
migratable: true,
|
||
}};
|
||
|
||
// ---------------------------------------------------------------- 面 B 路由
|
||
//
|
||
// 🔴 **官方 RESTful 形状**:`GET/POST /api/{app}/{entity}` + `DELETE .../{{id}}`
|
||
// —— 不是面 A 的 `/api/ssw/...`。面 A 在 `modules/{app}.rs`。
|
||
|
||
/// `GET /api/{app}/{entity}` —— 列表。
|
||
pub const {up}_LIST_ROUTE: PackRoute = PackRoute {{
|
||
path: "/api/{app}/{entity}",
|
||
method: HttpMethod::Get,
|
||
entity: "{entity}",
|
||
action: RouteAction::List,
|
||
guard: RouteGuard::Login,
|
||
}};
|
||
|
||
/// `POST /api/{app}/{entity}` —— 新建 / 更新(body 带 `id` 就是更新)。
|
||
pub const {up}_SAVE_ROUTE: PackRoute = PackRoute {{
|
||
path: "/api/{app}/{entity}",
|
||
method: HttpMethod::Post,
|
||
entity: "{entity}",
|
||
action: RouteAction::Save,
|
||
guard: RouteGuard::Login,
|
||
}};
|
||
|
||
/// `DELETE /api/{app}/{entity}/{{id}}` —— 软删。
|
||
pub const {up}_DELETE_ROUTE: PackRoute = PackRoute {{
|
||
path: "/api/{app}/{entity}/{{id}}",
|
||
method: HttpMethod::Delete,
|
||
entity: "{entity}",
|
||
action: RouteAction::Delete,
|
||
guard: RouteGuard::Login,
|
||
}};
|
||
|
||
/// 本包声明的全部路由(每条实体恰好 3 条)。
|
||
pub const {up}_ROUTES: &[PackRoute] = &[{up}_LIST_ROUTE, {up}_SAVE_ROUTE, {up}_DELETE_ROUTE];
|
||
|
||
/// 业务包本体(类型名固定 `Pack` —— `packs_gen.rs` 按 `sspf_pack_<app>::Pack` 拼)。
|
||
pub struct Pack;
|
||
|
||
impl BusinessPack for Pack {{
|
||
fn manifest(&self) -> &'static Manifest {{
|
||
&MANIFEST
|
||
}}
|
||
|
||
fn entities(&self) -> &'static [EntitySpec] {{
|
||
&[{up}_SPEC]
|
||
}}
|
||
|
||
fn menus(&self) -> &'static [MenuSpec] {{
|
||
&[{up}_MENU]
|
||
}}
|
||
|
||
fn routes(&self) -> &'static [PackRoute] {{
|
||
{up}_ROUTES
|
||
}}
|
||
}}
|
||
'''
|
||
|
||
|
||
def module_rs(app, entity, name):
|
||
up = camel_to_snake(entity).upper()
|
||
snake = camel_to_snake(entity)
|
||
svc = camel_to_kebab(entity)
|
||
return f'''//! {app} —— 面 A 适配器:{entity}(物理表 `{app}_{snake}`)。
|
||
//!
|
||
//! 🔴 **spec 的家在 `packs/{app}/src/lib.rs`**(业务包),本文件只做 `pub use` 转发
|
||
//! ⇒ **spec 只有一份**(两份拷贝迟早分叉)。
|
||
//! 🔴 **面 A 与面 B 各住一处**:
|
||
//! - 本文件 = 面 A(`/api/ssw/{app}/{entity}/…`,本仓自造约定,前端在用);
|
||
//! - 业务包 = 面 B(`/api/{app}/{entity}`,官方 JNPF 形状)。
|
||
|
||
use axum::body::Bytes;
|
||
use axum::extract::{{RawQuery, State}};
|
||
use axum::http::HeaderMap;
|
||
use axum::routing::{{delete, get, post}};
|
||
use axum::{{Json, Router}};
|
||
|
||
use sspf::crud::{{handle_delete, handle_list, handle_save}};
|
||
use sspf::envelope::ActionResult;
|
||
use sspf::AppState;
|
||
|
||
// 🔴 **spec 与菜单的单一真源 = 业务包** —— 这里只转发,不重写。
|
||
pub use sspf_pack_{app}::{up}_MENU;
|
||
pub use sspf_pack_{app}::{up}_SPEC;
|
||
|
||
/// 本模块的 3 条路由(面 A)。
|
||
pub const ROUTES: [&str; 3] = [
|
||
"/api/ssw/{app}/{entity}/List",
|
||
"/api/ssw/{app}/{entity}/Save",
|
||
"/api/ssw/{app}/{entity}/Delete",
|
||
];
|
||
|
||
/// `GET /api/ssw/{app}/{entity}/List`。
|
||
pub async fn {snake}_list(State(state): State<AppState>, headers: HeaderMap) -> Json<ActionResult> {{
|
||
handle_list(&state, &headers, &{up}_SPEC).await
|
||
}}
|
||
|
||
/// `POST /api/ssw/{app}/{entity}/Save`。
|
||
pub async fn {snake}_save(
|
||
State(state): State<AppState>,
|
||
headers: HeaderMap,
|
||
body: Bytes,
|
||
) -> Json<ActionResult> {{
|
||
handle_save(&state, &headers, &{up}_SPEC, &body).await
|
||
}}
|
||
|
||
/// `DELETE /api/ssw/{app}/{entity}/Delete?id=`。
|
||
pub async fn {snake}_delete(
|
||
State(state): State<AppState>,
|
||
headers: HeaderMap,
|
||
raw: RawQuery,
|
||
) -> Json<ActionResult> {{
|
||
handle_delete(&state, &headers, &{up}_SPEC, &raw).await
|
||
}}
|
||
|
||
/// 本模块的路由(面 A,`Router::merge` 进平台装配链)。
|
||
///
|
||
/// 🔴 路径写字面量(不用下标):契约与静态扫描都是**文本对账**,写下标会判「登记了、代码里没有」。
|
||
pub fn router() -> Router<AppState> {{
|
||
Router::new()
|
||
.route("/api/ssw/{app}/{entity}/List", get({snake}_list))
|
||
.route("/api/ssw/{app}/{entity}/Save", post({snake}_save))
|
||
.route("/api/ssw/{app}/{entity}/Delete", delete({snake}_delete))
|
||
}}
|
||
'''
|
||
|
||
|
||
def main(argv):
|
||
pos = [a for a in argv if not a.startswith("--")]
|
||
opts = {}
|
||
i = 0
|
||
while i < len(argv):
|
||
if argv[i].startswith("--"):
|
||
key = argv[i][2:]
|
||
val = argv[i + 1] if i + 1 < len(argv) else ""
|
||
opts[key] = val
|
||
i += 2
|
||
else:
|
||
i += 1
|
||
|
||
if len(pos) < 2 or "--help" in opts or "-h" in argv:
|
||
print(__doc__)
|
||
return 2
|
||
|
||
app, entity = pos[0], pos[1]
|
||
if not re.fullmatch(r"[a-z][a-z0-9_]*", app):
|
||
print(f"❌ app 只收小写字母/数字/下划线:{app!r}")
|
||
return 2
|
||
if not re.fullmatch(r"[A-Z][A-Za-z0-9]*", entity):
|
||
print(f"❌ Entity 必须是 UpperCamelCase:{entity!r}")
|
||
return 2
|
||
|
||
name = opts.get("name") or entity
|
||
sort = int(opts.get("sort") or 20)
|
||
columns = parse_columns(opts.get("columns", ""))
|
||
|
||
pack_dir = os.path.join(ROOT, "packs", app)
|
||
mod_file = os.path.join(ROOT, "src/backend/src/modules", f"{app}.rs")
|
||
if os.path.exists(pack_dir) or os.path.exists(mod_file):
|
||
print(f"❌ 目标已存在:{pack_dir} 或 {mod_file}(换个 app 名,或先删掉)")
|
||
return 2
|
||
|
||
table = f"{app}_{camel_to_snake(entity)}"
|
||
|
||
os.makedirs(os.path.join(pack_dir, "schema"), exist_ok=True)
|
||
os.makedirs(os.path.join(pack_dir, "src"), exist_ok=True)
|
||
|
||
def write(rel, content):
|
||
path = os.path.join(pack_dir, rel)
|
||
with open(path, "w", encoding="utf-8") as f:
|
||
f.write(content)
|
||
|
||
write("Cargo.toml", pack_cargo(app))
|
||
write("pack.toml", pack_toml(app, entity, name, table, columns))
|
||
write("schema/001_init.sql", ddl_sql(app, entity, table, columns))
|
||
write("src/lib.rs", pack_lib(app, entity, name, table, columns, sort))
|
||
with open(mod_file, "w", encoding="utf-8") as f:
|
||
f.write(module_rs(app, entity, name))
|
||
|
||
print(f"✅ 建包:packs/{app}/(表 {table})+ modules/{app}.rs")
|
||
|
||
sync = subprocess.run(
|
||
[sys.executable, os.path.join(HERE, "pack-sync.py")],
|
||
cwd=ROOT,
|
||
env=dict(os.environ, PACK_SYNC_ROOT=ROOT),
|
||
capture_output=True,
|
||
text=True,
|
||
)
|
||
print(sync.stdout.strip() or sync.stderr.strip())
|
||
if sync.returncode != 0:
|
||
print("❌ pack-sync 失败 —— 生成段没补上,先修上面的错")
|
||
return sync.returncode
|
||
|
||
print("下一步:`cargo check` 然后 `bash scripts/verify.sh`")
|
||
return 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
sys.exit(main(sys.argv[1:]))
|