Files
ssw-platform/crates/sspf-contract/src/route.rs
T
admin ecb77b230f 平台包零业务:示例移到技能仓、解绑 example-packs、闸门全部改防回流
- 物理移出 packs/{asset,books,demo,shop}、modules/ 四个面 A 适配器、纯技能副本、
  纯业务测试 crud_it.rs 与 new-pack 脚手架(v0.3.0 tag 完整保留旧形态)。
- 删 example-packs feature / example_packs() / sspf-pack-* 依赖 / packs/* member;
  packs_gen.rs 与 modules/mod.rs 生成段降级为恒空的注入点,装配链一条不删;
  pack-sync.py 把「零包」钉成合法目标态。
- 尺子不再「跳过」:CP1 防回流清单、check-module 三条、AR2/PACK1 正向断言、
  AR17 升级为零业务依赖判据(含注入式反自证)、契约反自证换平台锚点、FACE 零包重算。
- 面 A 冒烟 43→21 条(17 条平台权限闭环 + 4 条业务端点 404);pack_smoke_it 改
  运行时防回流探针;auth/db/batch7/permission/seed/routes 单测换平台内置夹具。
- 契约 [MENU_TREE] 收成 5 条系统菜单、[RULER] 改 21/3;README/CLAUDE/HANDOFF/
  CHANGELOG/contract §5.1/schema.sql/db.rs 注释同步。

验收:cargo test --workspace --no-fail-fast 649 passed / 0 failed / 6 ignored;
verify.sh --smoke 14/14;check-arch 24/24 + 反自证 14/14;
cargo tree -p sspf 无 sspf-pack-*。前端 src/frontend 按要求保留。
2026-11-04 21:54:22 +08:00

218 lines
8.6 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! route —— **业务包路由声明的类型**(契约层)。
//!
//! 🔴 **本文件只放「类型」,不放任何具体路由** ——
//! 业务包在自己的 `packs/<app>/src/lib.rs` 里声明路由,
//! 内核按声明**生成**路由 ⇒ **加一个业务模块不用改内核**。
//!
//! 🔴 **为什么路由「声明」与「注册」要分开**(PLAN.md §4.6 的 L2 级):
//! - **声明**在契约层(纯数据,无 axum)⇒ 业务包可以整目录搬走;
//! - **注册**在内核(唯一认识 axum 的地方)⇒ 框架只有一个装配点。
//! 这与 [`crate::entity::EntitySpec`] 是同一模式:**业务声明数据,平台读数据造 handler**。
//!
//! 🔴 **本类型里没有 handler** —— 只有「路径 + 方法 + 指向哪个实体」。
//! 内核拿到实体名 ⇒ 查 [`crate::entity::EntitySpec`] ⇒ 用 spec 驱动通用 CRUD 引擎。
//! ⇒ 业务包**不需要**(也不允许)依赖 axum。
/// 🔴 **一条路由的守卫声明**(权限判据)。
///
/// 🔴 **为什么必须由业务包自己声明**:
/// 业务包的路由是**面 B**(官方 JNPF 形状)⇒ 官方前端会直接调它
/// ⇒ 它的守卫**必须**是面 B 的判据(`f_en_code` 点权限),
/// **不是**面 A 的菜单路径(`f_url_address`)。
/// ⇒ 守卫是**业务知识**(这个模块的权限编码是什么)⇒ 住在包里,
/// 内核只读声明(与 `EntitySpec` 同一模式)。
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum RouteGuard {
/// **仅登录**(无菜单/点权限要求)。
///
/// 🔴 官方 `@SaCheckPermission` **可以完全不打** ⇒ 只要求登录。
Login,
/// **点权限**(官方 `@SaCheckPermission("xxx.yyy")` ⇒ 判据是 `base_module.f_en_code`)。
///
/// 🔴 **面 B 的判据** —— 与面 A 的菜单路径(`f_url_address`)是**两套并存**的判据。
EnCode(&'static str),
}
impl RouteGuard {
/// 转成字符串(写契约表用)。
pub fn as_str(&self) -> &'static str {
match self {
RouteGuard::Login => "登录",
RouteGuard::EnCode(code) => code,
}
}
/// 从字符串解析(契约表 → 结构体时用)。
///
/// 🔴 **入参是 `&'static str`** —— [`RouteGuard::EnCode`] 装的是**静态**权限编码
/// (`Copy` 的代价:不能持有运行时产生的字符串)⇒ 只能解析**编译期已知**的文本。
/// 契约表 → 结构体的转换由 Python 侧(`contract_expect.py`)做,
/// Rust 侧只在校验向量里用这个函数。
pub fn parse(s: &'static str) -> Option<RouteGuard> {
let t = s.trim();
if t == "登录" {
return Some(RouteGuard::Login);
}
if t.is_empty() || t == "无" {
return None;
}
Some(RouteGuard::EnCode(t))
}
}
/// HTTP 方法。
///
/// 🔴 只保留 CRUD 引擎真正支持的四个 —— 加方法就要加引擎分支,
/// 不做「先留口子以后填」的假泛化。
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum HttpMethod {
Get,
Post,
Put,
Delete,
}
impl HttpMethod {
/// 转成大写字符串(写契约表 / 日志用)。
pub fn as_str(&self) -> &'static str {
match self {
HttpMethod::Get => "GET",
HttpMethod::Post => "POST",
HttpMethod::Put => "PUT",
HttpMethod::Delete => "DELETE",
}
}
/// 从字符串解析(契约表 → 结构体时用)。
pub fn parse(s: &str) -> Option<HttpMethod> {
match s.trim().to_ascii_uppercase().as_str() {
"GET" => Some(HttpMethod::Get),
"POST" => Some(HttpMethod::Post),
"PUT" => Some(HttpMethod::Put),
"DELETE" => Some(HttpMethod::Delete),
_ => None,
}
}
}
/// 一条业务路由的**声明**。
///
/// 🔴 **不是 axum 的 `Route`** —— 它只是数据:
/// `path` + `method` + `entity`(指向本包声明的哪个 [`crate::entity::EntitySpec`])。
/// 内核按 `entity` 找到 spec ⇒ 用通用 CRUD 引擎生成真正的 handler。
///
/// 🔴 **`path` 必须是官方 JNPF 的形状**(`/api/{模块}/{资源}/...`),
/// **不许**用面 A 的 `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}` ——
/// 面 A 是本仓自造的 ssw 约定,集成到官方 JNPF 时**全部作废**。
/// (见 `技能仓 MIGRATION.md` §2.3 的逐条对照表。)
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct PackRoute {
/// 完整路径(**以 `/` 开头**,不含 query string)。
pub path: &'static str,
/// HTTP 方法。
pub method: HttpMethod,
/// 指向本包声明的实体名(= [`crate::entity::EntitySpec`] 的 `entity` 字段)。
///
/// 🔴 内核按 `app_code + entity` 查 spec ⇒ **同名但不同 app 的实体不会串**。
pub entity: &'static str,
/// 该路由属于哪个动作(`List` / `Save` / `Delete` / …)—— 供 CRUD 引擎选分支。
///
/// 🔴 引擎按**动作**分派(`List` 查、`Save` 写、`Delete` 删),
/// 所以这一列是**必需的**,不能靠路径后缀猜。
pub action: RouteAction,
/// 🔴 **这条路由的守卫**(面 B 的判据)。
///
/// 🔴 **为什么必须显式声明**:包路由是**面 B**(官方形状)⇒
/// 官方前端会直连 ⇒ 它的守卫必须是**点权限**(`f_en_code`),
/// **不是**面 A 的菜单路径(`f_url_address`)—— 两套判据**并存**、互不影响。
/// ⇒ 守卫是**业务知识**(这个模块的权限编码)⇒ 住在包里,内核只读声明。
pub guard: RouteGuard,
}
/// 路由的动作(CRUD 引擎的分派依据)。
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum RouteAction {
/// 列表查询。
List,
/// 新建 / 更新。
Save,
/// 删除。
Delete,
/// 🔴 **自定义动作** —— 引擎不认识 ⇒ 内核**拒载**这条路由
/// (而不是给它一个空实现 ⇒ 静默返回 200 空数据)。
///
/// 🔴 存在的理由:官方 JNPF 有一批「非 CRUD」端点
/// (`/AsyncList/{id}` / `/Actions/ResetPassword` / `ModuleBySystem` …)。
/// 本仓要么用面 B 的专用 handler 实现(不归业务包管),
/// 要么**不在业务包里声明** ⇒ 用本枚举把「我没实现」变成**显式的、可校验的**。
Custom,
}
impl RouteAction {
/// 转成字符串(契约表 / 日志用)。
pub fn as_str(&self) -> &'static str {
match self {
RouteAction::List => "List",
RouteAction::Save => "Save",
RouteAction::Delete => "Delete",
RouteAction::Custom => "Custom",
}
}
/// 从字符串解析。
pub fn parse(s: &str) -> Option<RouteAction> {
match s.trim() {
"List" => Some(RouteAction::List),
"Save" => Some(RouteAction::Save),
"Delete" => Some(RouteAction::Delete),
"Custom" => Some(RouteAction::Custom),
_ => None,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn method_round_trips() {
for m in [
HttpMethod::Get,
HttpMethod::Post,
HttpMethod::Put,
HttpMethod::Delete,
] {
assert_eq!(HttpMethod::parse(m.as_str()), Some(m));
}
assert_eq!(HttpMethod::parse("get"), Some(HttpMethod::Get));
assert_eq!(HttpMethod::parse(" PATCH "), None);
}
#[test]
fn action_round_trips() {
for a in [
RouteAction::List,
RouteAction::Save,
RouteAction::Delete,
RouteAction::Custom,
] {
assert_eq!(RouteAction::parse(a.as_str()), Some(a));
}
assert_eq!(RouteAction::parse("list"), None);
}
/// 🔴 守卫的字符串往返 —— 契约表的 `guard` 列与代码里的声明必须能互转。
#[test]
fn guard_round_trips() {
assert_eq!(RouteGuard::parse("登录"), Some(RouteGuard::Login));
assert_eq!(RouteGuard::Login.as_str(), "登录");
let g = RouteGuard::EnCode("permission.asset.dataResource");
assert_eq!(g.as_str(), "permission.asset.dataResource");
assert_eq!(RouteGuard::parse(g.as_str()), Some(g));
// 🔴 空串 /「无」**不是合法守卫** ⇒ 解析失败(宁可显式失败,不要默默放行)。
assert_eq!(RouteGuard::parse(""), None);
assert_eq!(RouteGuard::parse("无"), None);
}
}