Files
ssw-platform/docs/contract.md
T
admin a25bd5ef96 feat(permission): 迁入 Standing/PermissionGroup/Action 三族 21 条面 B 端点
新增官方表(DDL 逐字对齐 JNPF-PostgreSQL.sql):
- base_standing(:4071,15 列;f_is_system 1=系统/2=自定义 ⇒ 新建写 2)
- base_permission_group(:3278,16 列;f_permission_member 存逗号分隔 id 串)
- base_action(:1,15 列;f_enabled_mark 是 VARCHAR(11),官方陷阱照抄)

新增端点:
- permission/Standing 8 条(guard=permission.identity)
- permission/PermissionGroup 8 条(guard=permission.authGroup)
- permission/Action 5 条(guard=permission.action)

修复 4 个真 bug(每个都有回归测试 + 反自证):
- PermissionMember 列表的 ANY($1::text[]) 被 pglite-rs 当成数组类型 _text
  ⇒ 改 string_to_array($1::text, ',')
- 权限组软删 SQL 有未使用的 $1 ⇒ PG 42P18 ⇒ 把 f_delete_user_id 写进 SET
- Standing 软删关联的占位符与参数顺序错位 ⇒ 关联残留 ⇒ 参数与 $1/$2/$3 对齐
- 权限组列表 permissionMember 漏了官方 getFullNameByIds ⇒ 改子查询换成人名串

数字:契约 155→176(面 B 125→146)、tables 18→21、官方台账 144/151→165/172、
cargo test 226→230、六闸全绿、perm-smoke-jnpf 面 B 首次 23/23 全覆盖
2026-10-31 09:00:03 +08:00

103 KiB
Raw Blame History

契约规格 —— ssw-jnpf-lite-rust

本文件是唯一规格来源(binding spec)。 所有实现任务、代码评审、最终评审都以此为准。 与 HANDOFF.md 冲突时,以本文件为准;与本文件冲突的计划文字由控制者裁决并记入 ledger。

🔴 本文件 = 面 A(ssw/react 契约)的规格,冻结不动。 面 B(官方 JNPF 契约面)的规格在 JNPF_COMPAT_SURFACE.md(已落地 18/18), 两面共用同一套 base_* 表 / cipher / seed,但权限判据不同(面 A 按菜单路径、面 B 按 f_en_code)。


0. 术语与参照物

参照物 路径 地位
官方 JNPF DDL ~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql 数据模型真源(base_* 表名/列名逐字)
ssw-jnpf-lite-react ~/Desktop/workspace/skills/ssw-jnpf-lite-react/ 行为真源(NestJS 版把契约跑起来了)
tdc-rs ~/Desktop/workspace/tdc-rs/ 工程手法参考(只读;不共享代码/端口/数据目录)

1. 全局红线(每个任务都必须满足)

R1.1 契约优先于实现

端点路径、入参、返回形状、错误码逐字对齐 ssw-jnpf-lite-react。不确定时读 react 源码,不凭印象。

R1.2 业务失败一律 HTTP 200 + {code,msg,data}

  • 成功:code=200, msg='成功'
  • 业务失败:code=400,data=null,msg 透传业务提示
  • 未登录:code=600,msg='未登录'
  • 无菜单权限:code=403,msg='无菜单权限'
  • 未捕获异常(panic / DB 报错)⇒ 同样 HTTP 200 + {code:400,msg:'系统异常,请联系管理员',data:null} (对齐 react 的全局 ActionResultFilter 兜底分支:真实堆栈只进服务端日志,不外泄)
  • 唯一例外:未知路由 → HTTP 404,body 仍是 {code:404,msg:'接口不存在',data:null} (404 是传输层例外,不是业务失败;同理 405 保留 HTTP 405,见 §6.5)

R1.3 base_* 表名/列名逐字对齐官方 DDL

不得自创表名/列名。迁移期靠 --data-only 导数据,列名差一个字符就导不进去。

R1.4 不得用 SELECT *

所有 SELECT 必须显式列出列名。原因:react 版库(TypeORM synchronize)只有 entity 里的列, 官方 DDL 有 30~60 列。显式投影让本仓后端能开 react 建出来的库,且响应 JSON 与 react 逐字相同。

🔴 每列还要显式 AS "<JSON键>"(camelCase + 双引号,见 §4)——row_to_json 用列的输出名当 JSON 键。 写成 AS creator_time 会得到 "creator_time",react 是 "creatorTime" ⇒ 前端读不到字段。

🔴🔴 别名必须加双引号(2026-10-25 修订,Ruling P23)—— PostgreSQL 会把未加双引号的标识符折叠成小写:AS realName 的输出列名是 realname ⇒ row_to_json 出来的键是 "realname",不是 "realName" ⇒ 前端读不到字段,且静默。 实测:SELECT row_to_json(q)::text FROM (SELECT 1 AS realName) q ⇒ {"realname":1}; 写成 AS "realName" 才是 {"realName":1}。 ⇒ 规范写法:f_real_name AS "realName"、f_price::text AS "price"。 (db.rs 另有一层键归一兜底,见 §5.4 —— 它是安全网,不是本规范;规范写法本身不依赖它。)

R1.5 numeric 列必须序列化成 JSON 字符串

f_price 回显 "9.90",不是 9.9。手段:在 SQL 投影里就 cast 成 text(f_price::text AS price)。 int 列(f_delete_mark / f_stock / f_is_administrator)保持数字。

R1.6 口令不得外泄

库内存 md5(明文) 小写 hex。对外响应手工挑字段(用户列表去掉 password)。密文只在请求体里出现,永不回显。

R1.7 四源权限合并 + 管理员短路 + 未映射放行

  • 管理员(f_is_administrator=1)在任何 SQL 之前短路放行;
  • 权限 = 用户直授 + 角色 + 组织 + 岗位,只查角色会漏授权;
  • 菜单未映射到 base_module ⇒ 放行(对齐 SswPermissionGuard 的 warn 路径),不是拒绝。 这条最容易写反且静默,必须有测试钉住。

R1.8 前端不直接持有数据库

一切访问经 /api/**。

R1.9 schema DDL 绝不可从 HTTP 下载

db/schema.sql 不在 web root。后端若托管静态产物,只能托管前端 dist/。

R1.10 标识符白名单

任何拼进 SQL 的表名/列名都要过白名单([A-Za-z][A-Za-z0-9_]*),启动时自检全部拼接点,不过白名单 ⇒ 秒退。

R1.11 同一文件的多个 Edit 必须串行

并行 Edit 同一文件 = last-writer-wins 静默覆盖。改完必须 grep 复核全部改动点。

R1.12 bash 变量后紧跟中文必须写 ${VAR}

"$RC里已有" 会把中文字节并入变量名,set -u 下直接 unbound variable。写中文提示的 shell 脚本一律用 ${VAR} 包裹。


2. 统一信封

{ "code": 200, "msg": "成功", "data": null }
  • code:int
  • msg:string
  • data:任意 JSON(失败时为 null)

Rust 侧固定形态(src/backend/src/platform/envelope.rs):

use axum::Json;
use serde_json::Value;

#[derive(serde::Serialize)]
pub struct ActionResult {
    pub code: i32,
    pub msg: String,
    pub data: Value,
}

/// 成功:code=200, msg='成功'
pub fn ok(data: Value) -> Json<ActionResult>;
/// 失败:code=<code>, msg=<msg>, data=null(**恒 HTTP 200**)
pub fn fail(code: i32, msg: impl Into<String>) -> Json<ActionResult>;

没有第三种形状。 禁止 {"success":false,...}、禁止 401/403 裸 body(那是 tdc-rs 的形状,不要抄)。


3. cipher(与 cipher.ts 逐字节等价)

// src/backend/src/platform/cipher.rs
pub fn md5_hex(s: &str) -> String;
pub fn encrypt_password(plain: &str) -> String;   // hex 输出
pub fn decrypt_to_md5(encrypted_hex: &str) -> Option<String>;  // 解出 md5(明文);非法 hex ⇒ None

算法:

  1. key = md5_hex("EY8WePvjM5GGwQzn") ⇒ 32 个 ASCII 字节(不是 16 字节摘要!)
  2. src = md5_hex(plaintext) 的 32 个 ASCII 字节
  3. AES-256-ECB-PKCS7,输出 hex

🔴 key 当成 hex 串当 ASCII 用 ⇒ 32 字节 ⇒ AES-256。若当 16 字节摘要用 ⇒ AES-128 ⇒ 登录全挂。

上游检验向量(必须逐字节相等):

encrypt_password("123456")
== "d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b"

中间值(已用 openssl 独立验算通过,2026-10-25):

md5_hex("EY8WePvjM5GGwQzn") = "05b0175907a859751f57a04d5a5ee9ac"   ← 32 字符,当 32 个 ASCII 字节用
md5_hex("123456")            = "e10adc3949ba59abbe56e057f20f883e"   ← 32 字符,当 32 个 ASCII 字节用

🔴 输出长度:输入是 32 字节(= 16 的整数倍)⇒ PKCS7 补满一整块 16 字节 ⇒ 密文 48 字节 ⇒ hex 96 个字符(不是 64)。 自查:若你的实现输出 64 个 hex 字符 ⇒ 漏了 PKCS7 填充。 解密时必须去掉 PKCS7 填充;填充非法 ⇒ 返回 None。

口令比对:库内存 md5(明文);登录时 decrypt_to_md5(密文) 得到 md5(明文) ⇒ 大小写不敏感比较。

🔴 解密失败(None)⇒ 登录端点返回 400 '账号或密码错误',与 react 完全同形。 react 的 decryptToMd5 遇非法 hex / 非法填充返回空串 ⇒ 与库里的 md5 比对不等 ⇒ 抛 账号或密码错误。 ⇒ 本仓的 None 必须映射到同一条消息,不要另造「密文格式错误」之类的新提示。 (也别再加「解密结果长度必须 == 32」这类额外校验 —— react 没有,额外校验只会让行为与 react 不一致。)

依赖版本组合(别混用):aes 0.8 + ecb 0.1(cipher 0.4 家族);md-5 0.10(crate 名 md5,use md5::{Digest, Md5};)。 aes 0.9/ecb 0.2 是 cipher 0.5 家族,两套泛型不通用。


4. JSON 键名映射(列名 ↔ JSON 键)

规则:列名去 f_ 前缀 → 剩余部分按 _ 拆 → camelCase。

🔴 投影时别名一律写 AS "<JSON键>"(带双引号) —— PG 会把未加引号的标识符折叠成小写 (AS realName ⇒ 键 "realname" ⇒ 前端读不到,且静默)。详见 §R1.4。

列 JSON 键
f_id id
f_tenant_id tenantId
f_account account
f_real_name realName
f_password password
f_secretkey secretkey
f_is_administrator isAdministrator
f_role_id roleId
f_organize_id organizeId
f_creator_user_id creatorUserId
f_creator_time creatorTime
f_enabled_mark enabledMark
f_delete_mark deleteMark
f_full_name fullName
f_en_code enCode
f_url_address urlAddress
f_parent_id parentId
f_sort_code sortCode
f_type type
f_category category
f_icon icon
f_object_type objectType
f_object_id objectId
f_item_type itemType
f_item_id itemId
f_role_id roleId
f_user_id userId
f_org_id orgId
f_title title
f_status status
f_price price
f_stock stock
f_author author
f_isbn isbn

Rust 侧固定形态(src/backend/src/platform/db.rs):

pub fn column_to_json_key(col: &str) -> String;
pub fn json_key_to_column(key: &str) -> String;   // 逆规则
pub fn valid_table(name: &str) -> Option<String>;
pub fn valid_column(name: &str) -> Option<String>;

请求体键名 = JSON 键名(去前缀名):title 不是 fTitle,realName 不是 fRealName。


5. 数据库

5.1 表清单(10 张)

base_* 7 张 —— 官方 DDL 逐字(源行号见括号): base_authorize(812) · base_module(2209) · base_organize(3178) · base_role(3686) · base_role_relation(3729) · base_user(4479) · base_user_relation(4707)

官方 DDL 原文已提取到 .tmp/base_ddl_raw.sql(逐字,未改写)。 复合主键一律 (f_id, f_tenant_id);f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL。 除 f_id 外没有其它 NOT NULL 列 ⇒ 插入只需给业务列 + f_tenant_id。 唯一性(f_account / f_en_code)无 DB 约束,应用层保证。

🔴 「两版后端可开同一个库」这句话的适用范围 = 下面那 3 张业务表(本节的措辞如此)。 base_* 7 张是官方 DDL 逐字(本仓的「契约」),而 react 的 base_* entity 只是它的子集 (react 的 base_module 没有 f_creator_user_id;base_authorize 没有 f_creator_time / f_creator_user_id;base_role_relation 这两列都没有)⇒ react 后端本来就打不开本仓的库 (它的 TypeORM synchronize: true 会 ALTER 掉官方 DDL 的多余列)。 ⇒ 本仓真正复用的是 react 的前端产物,不是 react 的后端。 两个方向的依据分开:写以官方 DDL 为准(本仓的种子会写 f_creator_user_id / f_creator_time);读以 react 的 entity 列集为准(见 §5.3 的投影规则)。

业务表 3 张 —— 表名与 react 版同名(两版后端可开同一个库):

表 列
demo_item f_id / f_title / f_status / f_creator_user_id / f_creator_time / f_delete_mark
shop_product f_id / f_title / f_price numeric(12,2) / f_creator_user_id / f_creator_time / f_delete_mark
book_shop_book f_id / f_title / f_author / f_isbn / f_category / f_price numeric(12,2) / f_stock int / f_creator_user_id / f_creator_time / f_delete_mark

业务表主键 f_id VARCHAR(50) PRIMARY KEY,时间列 TIMESTAMP(0) WITHOUT TIME ZONE。

🔴 业务表的列宽与默认值必须逐字对齐 react 的 TypeORM entity (demo-item.entity.ts / product.entity.ts / book.entity.ts)—— 这是「两版后端可开同一个库」能成立的前提:TypeORM synchronize 建的库与我们的 schema.sql 必须是同一张表,否则一边 synchronize 会 ALTER 掉另一边建好的列。

表 逐字 DDL
demo_item f_id VARCHAR(50) PRIMARY KEY / f_title VARCHAR(255) / f_status VARCHAR(32) / f_creator_user_id VARCHAR(50) / f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE / f_delete_mark INTEGER DEFAULT 0
shop_product f_id VARCHAR(50) PRIMARY KEY / f_title VARCHAR(255) / f_price NUMERIC(12,2) / f_creator_user_id VARCHAR(50) / f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE / f_delete_mark INTEGER DEFAULT 0
book_shop_book f_id VARCHAR(50) PRIMARY KEY / f_title VARCHAR(255) / f_author VARCHAR(100) / f_isbn VARCHAR(32) / f_category VARCHAR(50) / f_price NUMERIC(12,2) / f_stock INTEGER DEFAULT 0 / f_creator_user_id VARCHAR(50) / f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE / f_delete_mark INTEGER DEFAULT 0
asset_data_resource f_id VARCHAR(50) PRIMARY KEY / f_name VARCHAR(200) / f_category VARCHAR(50) / f_scenario VARCHAR(500) / f_provider VARCHAR(200) / f_format VARCHAR(50) / f_scale VARCHAR(50) / f_source VARCHAR(50) / f_register_time TIMESTAMP(0) WITHOUT TIME ZONE / f_creator_user_id VARCHAR(50) / f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE / f_delete_mark INTEGER DEFAULT 0

🔴 asset_data_resource 是尚数网真实业务表(不是脚手架示例):列名逐字取自公司本体 DataResource(数据资源)。它没有 react 版对应表 ⇒ §5.1 那条「两版同库」不适用; 但它同样遵守全部 DDL 红线(f_ 前缀 / f_id VARCHAR(50) / 软删 / 业务列无 DB 默认值)。

🔴 有 DB 默认值的只有两处:f_delete_mark(三张表都有)与 book_shop_book.f_stock。 react 的 book.entity.ts 上 stock 也有 default: 0 ⇒ TypeORM 建的库同样带这个默认值。 §7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建)依赖它们补出 0。 其余业务列(f_title / f_status / f_price / f_author / f_isbn / f_category / f_creator_user_id / f_creator_time)不得有 DB 默认值(§7.6 路径 2 要求"没给就是 NULL")。

5.2 时间列口径

官方 DDL 是 TIMESTAMP(0) WITHOUT TIME ZONE(秒精度、无时区)。 写入一律 UTC 朴素时间;读出投影成 JS ISO 串:

to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS creatorTime

🔴 投影的 AS 别名必须就是 §4 的 JSON 键(camelCase),且必须加双引号 —— row_to_json 用的是列的输出名当 JSON 键。别名写成 AS creator_time 会得到 "creator_time", 与 react 的 "creatorTime" 对不上 ⇒ 前端所有字段读不到。 每一列都要显式 AS "<JSON键>"(带双引号 —— PG 折叠未加引号的标识符,见 §R1.4)。

5.3 精确列清单(投影真源)

🔴 SELECT 的列必须逐字取自下表 —— 这是 react 版 entity 的精确列集(~/Desktop/workspace/skills/ssw-jnpf-lite-react/src/backend/src/**/*.entity.ts), 不是官方 DDL 的全列。官方 DDL 有 3060 列,react entity 只有 813 列。 取下表的列 ⇒ ① 响应 JSON 与 react 逐字相同;② 本仓后端能打开 react 建出来的库。

格式:列名 → JSON 键。列顺序 = react entity 的声明顺序。

🔴 投影写法:每列都写成 f_xxx AS "<JSON键>"(别名 = 右边的 JSON 键,camelCase,且带双引号)。 row_to_json 用的就是别名当 JSON 键 —— 别名写错 ⇒ 响应键名对不上 react; 双引号漏了 ⇒ PG 折叠成小写 ⇒ 键名对不上且静默(见 §R1.4)。 例:f_real_name AS "realName"、f_is_administrator AS "isAdministrator"、 f_creator_time ⇒ to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS "creatorTime"、 f_price ⇒ f_price::text AS "price"(numeric 必须是字符串)。

base_authorize(9 列)

f_id → id            f_tenant_id → tenantId   f_object_type → objectType
f_object_id → objectId   f_item_type → itemType   f_item_id → itemId
f_org_id → orgId    f_sort_code → sortCode   f_delete_mark → deleteMark

⚠️ react 的 base_authorize entity 没有 f_creator_time / f_creator_user_id(官方 DDL 有)⇒ 投影里不要它们。

base_module(13 列)

f_id → id            f_tenant_id → tenantId   f_full_name → fullName
f_url_address → urlAddress   f_parent_id → parentId   f_type → type
f_category → category   f_en_code → enCode   f_icon → icon
f_sort_code → sortCode   f_enabled_mark → enabledMark
f_creator_time → creatorTime   f_delete_mark → deleteMark

⚠️ 没有 f_creator_user_id。

base_organize(11 列)

f_id → id            f_tenant_id → tenantId   f_full_name → fullName
f_parent_id → parentId   f_category → category   f_en_code → enCode
f_manager_id → managerId   f_sort_code → sortCode   f_enabled_mark → enabledMark
f_creator_time → creatorTime   f_delete_mark → deleteMark

⚠️ 没有 f_creator_user_id。

base_role(11 列)

f_id → id            f_tenant_id → tenantId   f_full_name → fullName
f_en_code → enCode   f_type → type   f_description → description
f_enabled_mark → enabledMark   f_sort_code → sortCode
f_creator_user_id → creatorUserId   f_creator_time → creatorTime
f_delete_mark → deleteMark

base_role_relation(8 列)

f_id → id            f_tenant_id → tenantId   f_object_type → objectType
f_object_id → objectId   f_role_id → roleId   f_sort_code → sortCode
f_delete_mark → deleteMark

⚠️ 没有 f_creator_time / f_creator_user_id。

base_user(13 列)

f_id → id            f_tenant_id → tenantId   f_account → account
f_real_name → realName   f_password → password   f_secretkey → secretkey
f_is_administrator → isAdministrator   f_role_id → roleId
f_organize_id → organizeId   f_creator_user_id → creatorUserId
f_creator_time → creatorTime   f_enabled_mark → enabledMark
f_delete_mark → deleteMark

🔴 没有 f_manager_id / f_position_id / f_gender / f_email 等 —— 官方 DDL 有,react entity 没有 ⇒ 不投影。

base_user_relation(8 列)

f_id → id            f_tenant_id → tenantId   f_user_id → userId
f_object_type → objectType   f_object_id → objectId
f_sort_code → sortCode   f_delete_mark → deleteMark

demo_item(6 列)/ shop_product(6 列)/ book_shop_book(10 列)

demo_item:      f_id → id, f_title → title, f_status → status,
                f_creator_user_id → creatorUserId, f_creator_time → creatorTime,
                f_delete_mark → deleteMark
shop_product:   f_id → id, f_title → title, f_price → price,
                f_creator_user_id → creatorUserId, f_creator_time → creatorTime,
                f_delete_mark → deleteMark
book_shop_book: f_id → id, f_title → title, f_author → author, f_isbn → isbn,
                f_category → category, f_price → price, f_stock → stock,
                f_creator_user_id → creatorUserId, f_creator_time → creatorTime,
                f_delete_mark → deleteMark

已知无害偏离(记入 ledger,不必对齐):

  • f_sort_code 是 BIGINT,直投影为 JSON 数字;react 因 pg 驱动把 int8 返回成字符串。 前端只在 <td> 里原样渲染(MenuManage.tsx:75)⇒ 显示一致。
  • 时间列:react 返回 JS Date ⇒ JSON "2026-01-01T00:00:00.000Z";我们投影 "2026-01-01T00:00:00Z"(秒精度)。 前端完全不用 creatorTime ⇒ 无影响。

5.4 pglite 封装(src/backend/src/platform/db.rs)

pub const SCHEMA_SQL: &str = include_str!("../db/schema.sql");

pub struct Db { /* PGlite + 进程级 Mutex */ }

impl Db {
    pub async fn open(dir: &Path) -> Result<Db, pglite::Error>;
    pub async fn open_temp() -> Result<Db, pglite::Error>;
    pub async fn ensure_schema(&self) -> Result<(), pglite::Error>;
    pub async fn query_json(&self, sql: &str) -> Result<Vec<serde_json::Value>, pglite::Error>;
    pub async fn query_json_params(&self, sql: &str, params: &[&(dyn pglite::ToSql + Sync)])
        -> Result<Vec<serde_json::Value>, pglite::Error>;
    pub async fn exec(&self, sql: &str) -> Result<(), pglite::Error>;
    pub async fn exec_params(&self, sql: &str, params: &[&(dyn pglite::ToSql + Sync)])
        -> Result<(), pglite::Error>;
    pub async fn scalar_text(&self, sql: &str) -> Result<Option<String>, pglite::Error>;
}

/// 字面量感知 SQL 切分(单引号串 / dollar-quote / 行注释 / 块注释内的 `;` 不切)
pub fn split_sql_statements(sql: &str) -> Vec<String>;

序列化手法(沿用 tdc-rs):

SELECT row_to_json(q)::text AS _row FROM (<sql>) AS q

⇒ 取单列文本 ⇒ serde_json::from_str。不要另起逐列类型映射分支。

🔴 键归一安全网(db.rs 内建,Ruling P23):query_json 返回前会把 JSON 键还原成 camelCase —— ① 内层 SQL 里 AS <别名>(含大写字母)的别名 ⇒ 按作者原样还原(AS realName ⇒ "realName"); ② 键以 f_ 开头 ⇒ 走 column_to_json_key(f_real_name ⇒ realName,与 tdc-rs 同思路)。 已加双引号的别名(AS "realName")PG 原样保留 ⇒ 两条规则都不动它。 ⇒ 两种写法都能出正确键;但规范写法是加双引号(原生 PG 行为,不依赖这层解析)。 安全网存在的意义是:万一某处漏了双引号,不会静默产出小写键。

绑定参数一律按 text 传(&str / Option<&str> 都实现了 ToSql); 类型转换由 SQL 里的 CAST / 列上下文负责(PG 从目标列推断参数类型)。

单 backend 独占:pglite-rs 每进程只允许一个 PGlite 实例 ⇒ 集成测试必须共用一个实例, 且各自用独立数据目录的多个测试二进制不能并行跑。

5.5 schema 初始化

启动时探测 base_user 是否存在;不存在才按 ; 拆分执行 schema.sql(拆分要字面量感知)。

🔴 schema.sql 只在「base_user 不存在」时整体执行一次,不是「每次启动都跑」。

  • 改了 schema(加列/改类型)⇒ 必须清空数据目录(src/backend/data/)重建,否则旧库仍是老结构。
  • 7 张 base_* 的 CREATE TABLE 块与 docs/ddl/base_ddl_raw.sql 逐字相同; 文件尾部另有 4 条官方索引(i_ba_foi / i_brr_fri / i_bu_fa / i_bur_fui), 官方全部非唯一 ⇒ 账号唯一性仍由应用层保证(不会有 23505)。
  • 4 条索引都带 IF NOT EXISTS ⇒ schema.sql 重复执行不会报 42P07。

6. 端点全表

🔴 本节是「人读」版;机器可读版在附录 A 的 [ENDPOINT] 区段 (列:face / method / path / guard / owner,一行一条端点,132 条; 外加 [FACE] 区段登记各契约面的条数)。 由 scripts/check-contract.sh 把它与代码里真实注册的路由逐条对账 (总数 / 存在性 / 方法 / 归属层 / 守卫,双向)⇒ 改契约忘了改代码(或反之)立刻报。 🔴 改端点时两处都要改:本节的散文表 + 附录 A 的 [ENDPOINT]。

📊 本仓对「官方 JNPF 契约面」的覆盖是另一本账:附录 A 的 [OFFICIAL] 区段 (53 行 = 官方端点全表 + 每个端点的 status 四态 + 官方出处 文件:行号)⇒ 由 check-contract.sh 的 CC10 与代码真实路由双向对账 ⇒ 打印「官方端点覆盖 N/M」。官方端点全表的人读版在 JNPF_SOURCE_AUDIT.md §4。

6.1 认证

方法 路径 守卫 说明
POST /api/oauth/Login 无 form-urlencoded:account / password(密文 hex) / grant_type=password
GET /api/oauth/CurrentUser 登录 {userInfo:{userId,userAccount,userName,isAdministrator}, menuList}
POST /api/oauth/Logout 登录 恒成功 {data:null}(前端忽略返回值,但 404 会弹红条 ⇒ 必须得是 200)
GET /api/system/BaseLang/LangJson 登录 i18n 远端词条包;恒 {data:null} ⇒ 前端不 merge

登录失败文案(逐字):

  • 缺 account 或 password ⇒ 400 '缺少 account / password'
  • grant_type 非空且 ≠ password ⇒ 400 '不支持的 grant_type'
  • 口令错 / 账号不存在 ⇒ 400 '账号或密码错误'
  • 密文非法(非法 hex / 非法 PKCS7 填充 ⇒ decrypt_to_md5 返回 None)⇒ 同一条 400 '账号或密码错误' (react 的 decryptToMd5 失败返空串 ⇒ 比对不等 ⇒ 同一条消息。不要另造提示文案。)

实现注记:axum 0.8.9 的 Form<T> 没有 OptionalFromRequest ⇒ Option<Form<T>> 编译不过。 ⇒ handler 取原始 body(Bytes),自己 serde_urlencoded::from_bytes::<LoginForm>(&body); 解析失败也走业务信封(fail(400, "缺少 account / password")),不要 axum 默认的 400 文本。

登录成功体:{token, expiresIn: 7200, tokenTypeName: 'bearer'}

token 形态:lite- + 32 位小写 hex(lite- 前缀 + md5)。进程重启即失效(内存表)。

Authorization 头:bearer <token>(大小写不敏感前缀)。

CurrentUser 的 userName = 账号(react 版 userName: u.account,不是 realName)。 isAdministrator 是 JSON 布尔(isAdmin === 1)。

6.2 系统管理(5 组)

方法 路径 守卫菜单 key
GET/POST/DELETE /api/ssw/sys/User/{List,Save,Delete?id=} system/User
GET/POST/DELETE /api/ssw/sys/Role/{List,Save,Delete?id=} system/Role
GET /api/ssw/sys/Role/Modules?roleId= 仅登录
GET/POST/DELETE /api/ssw/sys/Organize/{List,Save,Delete?id=} system/Organize
GET/POST/DELETE /api/ssw/sys/Module/{List,Save,Delete?id=} system/Module

6.3 授权

方法 路径 守卫 说明
PUT /api/permission/Authority/Data/{objectId} 仅登录 body {objectType:'role', module:['m1','m2']}(一维)
GET /api/permission/Authority/RoleModules?roleId= 仅登录 返 string[](菜单 id)

module 归一化(react normalizeModule):一维数组直接用;历史二维形态 [[checked],[halfChecked]] 展平后同样落库; 非数组 ⇒ 视作空数组;只保留非空字符串元素。

⚠️ body 里的 objectType 被完全忽略(react 只读 body.module,落库的 f_object_type 硬编码为 'role')⇒ 不要因为 body 传了 'Role' 就拒绝。详见 §7.5 与 §7.7。

6.4 业务模块(3 组)

方法 路径 守卫菜单 key
GET/POST/DELETE /api/ssw/demo/DemoItem/{List,Save,Delete?id=} 仅登录(无菜单守卫)
GET/POST/DELETE /api/ssw/shop/Product/{List,Save,Delete?id=} shop/Product
GET/POST/DELETE /api/ssw/books/Book/{List,Save,Delete?id=} books/Book

6.5 其它

  • 未知路由 ⇒ HTTP 404 + {code:404,msg:'接口不存在',data:null}
  • 405(路径存在、方法不对)⇒ HTTP 405 + {code:405,msg:'方法不被允许',data:null},保留 Allow 头 (react 侧 Express 路由对错误方法其实返 404,但前端从不发错方法 ⇒ 这条不在契约面上, 按「传输层状态码保留」处理,别让它掉进 R1.2 的 HTTP 200 规则。)
  • 未捕获异常(panic / DB 报错)⇒ HTTP 200 + {code:400,msg:'系统异常,请联系管理员',data:null} (必须装 catch-all 中间件,不能让 axum 的默认 500 空 body 漏出去)
  • GET /api/health ⇒ {ok, tables, version}(非契约,探活用)

7. 各端点语义(逐字对齐 react 版)

本节每一条都逐字核对过 react 源码 (~/Desktop/workspace/skills/ssw-jnpf-lite-react/src/backend/src/{auth,sys,demo,shop,books}/)。 括号里的 react: 行号是出处。凡与 react 有故意偏离的(只有一条:User Save 的 password), 都标了 🔴 刻意偏离 并在 §7.7 记录原因。

🔴 全局覆盖规则(§7.1–§7.4 通用):后文所有「覆盖 f_xxx」默认指 只 SET body 里出现的键(body 里没出现 ⇒ 该列不动原值)—— 这就是 react / TypeORM save 的 undefined 语义(save 跳过 undefined 的列)。 body 里出现了但值为 null ⇒ 写 NULL;出现了且值为 '' ⇒ 写空串。 例外:凡是本节显式写出兜底表达式的列(?? 原值 / || '0' / ? 1 : 0), 一律按该表达式求值 —— body 缺该键时取兜底值(?? 原值 ⇒ 原值、 || '0' ⇒ '0'),不是「不动原值」。 🔴 承重之处:§7.4 的 f_url_address 是 §8.2 权限守卫的比对键。 把它清成 NULL ⇒ 该菜单变成「未映射」⇒ 守卫走「未映射放行」 ⇒ 任何登录用户都能访问该模块(静默越权)。⇒ 更新菜单时绝不可把 f_url_address 写成本仓未提供的值。

7.1 User(/api/ssw/sys/User/*)

  • List
    • base_user:f_delete_mark=0,f_creator_time DESC。
    • 关联:base_role_relation 取 f_object_type='user' 的全部行(不按 f_delete_mark 过滤), 再按 f_object_id == 用户 id 过滤 ⇒ roleIds = 命中行的 f_role_id 数组(保持库里顺序)。
    • roleNames = base_role 中 f_delete_mark=0 的行按 id 查 f_full_name; 查不到就跳过(不是填空串、不是 null)⇒ 数组长度可能小于 roleIds。
    • 输出去掉 password,追加 roleIds / roleNames(两个都是一维 string[])。
  • Save(POST /api/ssw/sys/User/Save,body 是 JSON)
    1. account 为空 ⇒ 400 '账号不能为空'。
    2. 查重(新建和更新都查):base_user 中 f_account = <account> AND f_delete_mark = 0。 ⚠️ 官方 DDL 对 f_account 无 UNIQUE,唯一性只在应用层。
    3. 无 id ⇒ 新建:
      • f_id = 36 位 UUID v4(带连字符),f_tenant_id='0';
      • f_account = body.account;
      • f_real_name = body.realName(body 没有 ⇒ NULL);
      • f_password = md5(body.password);body.password 为空 ⇒ md5('123456');
      • f_is_administrator = body.isAdministrator 真值 ⇒ 1,否则 0(缺省即 0,不是「保持原值」);
      • f_organize_id = body.organizeId || '0';
      • f_creator_user_id = 'admin',f_creator_time = now(UTC), f_enabled_mark=1,f_delete_mark=0。
      • f_secretkey / f_role_id 不写(NULL)。
      • 若 dup 存在 ⇒ 400 '账号已存在:<account>'(HTTP 200,不是 500)。
    4. 有 id ⇒ 更新:
      • 先按 f_id = <id> 查(不按 f_delete_mark 过滤 ⇒ 软删过的行也算存在), 查不到 ⇒ 400 '用户不存在';
      • 若 dup 存在且 dup.f_id != <id> ⇒ 400 '账号已存在:<account>';
      • 覆盖规则(只覆盖 body 里出现的键,undefined ⇒ 不动原值): f_account(必覆盖)、f_real_name(body 有才覆盖)、 f_is_administrator(总是覆盖为 body 真值 ? 1 : 0)、 f_organize_id(总是覆盖为 body.organizeId || '0')、 f_password(body.password 非空才覆盖为 md5(body.password))。
      • ⚠️ 更新不碰 f_creator_time / f_enabled_mark / f_delete_mark。
    5. roleIds 是数组 ⇒ 先硬删该用户的 base_role_relation 旧行 (f_object_type='user' AND f_object_id=<id>),再每个 roleId 插一行 (f_id=UUID v4、f_tenant_id='0'、f_object_type='user'、f_object_id=<id>、 f_role_id=<rid>、f_sort_code=0、f_delete_mark=0)。空数组 ⇒ 只删不插。
    6. 响应 = 落库后该用户行(去掉 password)+ roleIds + roleNames。 🔴 刻意偏离:react 的 Save 响应带着 password 的 md5 摘要(可被重新加密成合法登录密文)。 本仓按 R1.6 剥掉 password(List 与 Save 都剥)。前端从不读该字段 ⇒ 无影响。
  • Delete(DELETE /api/ssw/sys/User/Delete?id=)
    • 软删 base_user:f_delete_mark=1(按 id,不按 f_delete_mark 过滤 ⇒ 幂等);
    • 硬删 base_role_relation:f_object_type='user' AND f_object_id=<id>;
    • 不检查用户是否存在 ⇒ 不存在也返回成功。

7.2 Role(/api/ssw/sys/Role/*)

  • List:f_delete_mark=0,f_sort_code ASC。
  • Save
    1. fullName 为空 ⇒ 400 '角色名称不能为空'。
    2. 无 id ⇒ 新建:
      • 先查重 base_role 中 f_en_code = <enCode> AND f_delete_mark = 0; 命中 ⇒ 400 '角色编码已存在:<enCode>';
      • f_id=UUID v4、f_tenant_id='0'、f_full_name=body.fullName、f_en_code=body.enCode、 f_type = body.type ?? 'user'、f_description=body.description、 f_enabled_mark=1、f_sort_code = body.sortCode ?? 0、 f_creator_user_id='admin'、f_creator_time=now、f_delete_mark=0。
    3. 有 id ⇒ 更新:
      • 按 f_id 查(不带 f_delete_mark 过滤),查不到 ⇒ 400 '角色不存在';
      • 覆盖(body 有才覆盖,见本节全局规则):f_full_name、f_en_code、 f_type = body.type ?? 原值、f_description;
      • ⚠️ 更新不做 f_en_code 查重;不碰 f_sort_code / f_enabled_mark。
  • Delete
    • 软删 base_role(f_delete_mark=1,按 id);
    • 软删 base_authorize:f_object_type='role' AND f_object_id=<id> ⇒ f_delete_mark=1 (⚠️ 不带 f_item_type 过滤);
    • 硬删 base_role_relation:f_role_id=<id>(⚠️ 不带 f_object_type 过滤)。
  • GET /api/ssw/sys/Role/Modules?roleId= ⇒ base_authorize 中 f_object_type='role' AND f_item_type='module' AND f_object_id=<roleId> AND f_delete_mark=0 的 f_item_id 数组(string[])。

7.3 Organize(/api/ssw/sys/Organize/*)

  • List:f_delete_mark=0,f_sort_code ASC。
  • Save
    1. fullName 为空 ⇒ 400 '机构名称不能为空'。
    2. 无 id ⇒ 新建:f_id=UUID v4、f_tenant_id='0'、f_full_name=body.fullName、 f_parent_id = body.parentId || '0'、f_category = body.category ?? NULL、 f_sort_code = body.sortCode ?? 0、f_enabled_mark=1、f_creator_time=now、f_delete_mark=0。 ⚠️ 不写 f_creator_user_id(react 的 base_organize entity 没有该列)⇒ NULL。
    3. 有 id ⇒ 更新:按 f_id 查(不带 f_delete_mark 过滤),查不到 ⇒ 400 '机构不存在'; 覆盖(body 有才覆盖,见本节全局规则):f_full_name、 f_parent_id = body.parentId || '0'、f_category = body.category ?? 原值。 ⚠️ 更新不碰 f_sort_code / f_enabled_mark。
  • Delete
    • 先查子机构:base_organize 中 f_parent_id=<id> AND f_delete_mark=0; 非空 ⇒ 400 '该机构下还有子机构,先删除子机构';
    • 否则软删(f_delete_mark=1,按 id)。

7.4 Module(/api/ssw/sys/Module/*)

  • List:f_delete_mark=0,f_sort_code ASC。
  • Save
    1. fullName 为空 ⇒ 400 '菜单名称不能为空'。
    2. 无 id ⇒ 新建:f_id=UUID v4、f_tenant_id='0'、f_full_name=body.fullName、 f_url_address=body.urlAddress、f_parent_id = body.parentId || '0'、 f_type = body.type ?? 2(INTEGER:1=目录 2=页面)、 f_category = body.category ?? NULL(VARCHAR 分类)、 f_icon=body.icon、f_sort_code = body.sortCode ?? 0、 f_enabled_mark=1、f_creator_time=now、f_delete_mark=0。 ⚠️ 不写 f_creator_user_id ⇒ NULL。
    3. 有 id ⇒ 更新:按 f_id 查(不带 f_delete_mark 过滤),查不到 ⇒ 400 '菜单不存在'; 覆盖(body 有才覆盖,见本节全局规则):f_full_name、f_url_address、 f_parent_id = body.parentId || '0'、f_type = body.type ?? 原值、 f_category = body.category ?? 原值、f_icon、f_sort_code = body.sortCode ?? 0。
  • Delete
    • 软删 base_module(f_delete_mark=1,按 id);
    • 软删 base_authorize:f_item_type='module' AND f_item_id=<id> ⇒ f_delete_mark=1 (⚠️ 不带 f_object_type 过滤)。

7.5 授权(/api/permission/Authority/*)

  • PUT /api/permission/Authority/Data/{objectId},body {objectType, module}:
    1. 守卫:未登录 ⇒ 600 '未登录'。
    2. 归一化 module(react normalizeModule):
      • body 里没有 module 或不是数组 ⇒ [];
      • 若 module[0] 是数组 ⇒ 展平一层(兼容官方前端的 [checked, halfChecked] 二维形态);
      • 只保留非空字符串。
    3. ⚠️ body 里的 objectType 被完全忽略(react 只读 body.module)⇒ 落库一律 f_object_type='role'、f_item_type='module'、f_object_id=<objectId>。 (不要因为 body 传了 'Role' 而拒绝 —— react 不校验,本仓也不校验。)
    4. 先软删旧行:base_authorize 中 f_object_type='role' AND f_item_type='module' AND f_object_id=<objectId> ⇒ f_delete_mark=1(⚠️ 不带 f_delete_mark 过滤)。
    5. 再插新行(每个 moduleId 一行):f_id=UUID v4、f_tenant_id='0'、 f_object_type='role'、f_item_type='module'、f_item_id=、 f_sort_code=0、f_delete_mark=0。空数组 ⇒ 只软删不插。
    6. 成功 ⇒ {code:200,msg:'成功',data:null}。
  • GET /api/permission/Authority/RoleModules?roleId= ⇒ 同 §7.2 的 Role/Modules (string[])。未登录 ⇒ 600 '未登录'。

7.6 业务模块(spec 引擎,3 组同构)

  • List:f_delete_mark=0,f_creator_time DESC。
  • Save —— 三条互不相同的路径,按 body 里有没有 id、以及该 id 存不存在分流:
    1. 无 id ⇒ 新建(只写下列字段,不多写):
      • demo_item:f_id=UUID v4、f_title=body.title、f_status = body.status ?? '草稿'、 f_creator_user_id = 'admin'(硬编码,不取 body)、f_creator_time=now、f_delete_mark=0;
      • shop_product:f_id=UUID v4、f_title=body.title、f_price = body.price ?? '0.00'、 f_creator_user_id = body.creatorUserId || 'admin'、f_creator_time=now、f_delete_mark=0;
      • book_shop_book:f_id=UUID v4、f_title=body.title、f_author=body.author、 f_isbn=body.isbn、f_category=body.category、f_price = body.price ?? '0.00'、 f_stock = body.stock ?? 0、f_creator_user_id = body.creatorUserId || 'admin'、 f_creator_time=now、f_delete_mark=0。
    2. 有 id 但库里查不到该行 ⇒ 用这个 id 新建:
      • 写入 body 里该实体的已知列(§5.3 的列集),不加任何默认值: 没有 f_creator_time ⇒ NULL;没有 f_status / f_price ⇒ NULL;
      • f_delete_mark:body 没给 ⇒ 0(业务表该列 DDL 带 DEFAULT 0);
      • f_stock(仅 book_shop_book):body 没给 ⇒ 0(该列 DDL 也带 DEFAULT 0, 与 react 的 book.entity.ts 一致 ⇒ 两版后端开同一个库时结果相同)。
    3. 有 id 且库里查得到 ⇒ 覆盖更新:只覆盖 body 里出现的该实体已知列(Object.assign 语义), body 没出现的列保持原值。
    • 三个模块共用一条规则:body 里不属于该实体列集的键一律忽略(不建列、不报错)。
    • 响应体 = 落库后重新读回的那一行(这样 numeric 的 "9.90" 由投影 ::text 保证)。
  • Delete(DELETE .../Delete?id=):软删 f_delete_mark=1(按 id,不检查是否存在 ⇒ 幂等)。

7.7 与 react 的唯一刻意偏离

项 react 行为 本仓行为 理由
User Save 响应 带 password 字段(md5 摘要) 剥掉 password R1.6 口令不得外泄。md5 摘要可被前端用 cipher.ts 重新加密成合法登录密文 ⇒ 泄露即等于泄露凭据。前端从不读该字段 ⇒ 无功能影响。List 响应两版都剥。

8. 权限与菜单树

8.1 四源合并

resolve_user_module_ids(userId) 返回菜单 id 集合,四个来源:

  1. 直授:base_authorize 中 f_object_type='user' AND f_object_id=<userId> AND f_item_type='module' AND f_delete_mark=0 ⇒ f_item_id
  2. 角色:base_role_relation 中 f_object_type='user' AND f_object_id=<userId> ⇒ 每行的 f_role_id ⇒ 对每个 roleId 取 base_authorize 中 f_object_type='role' AND f_object_id=<roleId> AND f_item_type='module' AND f_delete_mark=0 ⇒ f_item_id
  3. 组织:base_user_relation 中 f_user_id=<userId> AND f_object_type='organize' ⇒ 每行的 f_object_id ⇒ 对每个 objectId 取 base_authorize 中 f_object_type='organize' AND f_object_id=<objectId> ... ⇒ f_item_id
  4. 岗位:base_user_relation 中 f_user_id=<userId> AND f_object_type='position' ⇒ 同上,f_object_type='position'

8.2 菜单守卫 has_module(userId, isAdmin, moduleKey)

  1. isAdmin == 1 ⇒ 放行(不查任何 SQL)
  2. 查 base_module 中 f_url_address = moduleKey AND f_delete_mark=0(取第一条); 查不到 ⇒ 放行(未映射放行)
  3. 查得到 ⇒ 该菜单 f_id 是否在四源合并集合里;在 ⇒ 放行,否则 ⇒ 403

8.3 菜单树 build_menu_list(userId, isAdmin)

  • 取 base_module 中 f_delete_mark=0 的行,按 f_sort_code ASC
  • 非管理员:过滤成「id 在四源集合里」的子集
  • 建树:f_parent_id 为空或 '0' 或父节点不在集合内 ⇒ 该节点是根;否则挂到父节点 children
  • 节点形状:{id, fullName, urlAddress, icon, parentId, children} (urlAddress / icon 库里是 NULL ⇒ JSON 里就是 null,不要省略这两个键; parentId 取 f_parent_id,为 NULL/空 ⇒ '0')
  • 根按 f_sort_code 升序;同层 children 按 f_sort_code 升序

8.4 种子菜单(8 行,f_tenant_id='0',f_enabled_mark=1,f_delete_mark=0)

id fullName urlAddress parentId type icon sortCode
m_sys 系统管理 system 0 1 setting 1
m_user 用户管理 system/User m_sys 2 — 2
m_role 角色管理 system/Role m_sys 2 — 3
m_org 机构管理 system/Organize m_sys 2 — 4
m_menu 菜单管理 system/Module m_sys 2 — 5
m_demo Demo 示例 demo-item 0 2 app 6
m_product 产品管理 shop/Product 0 2 app 7
m_book 图书超市 books/Book 0 2 app 8

期望菜单树字符串(冒烟断言用;值在附录 A 的 [MENU_TREE] 区段,脚本从那里读):

系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:

🔴 这 8 行的值住在哪(分层红线 12):

  • 前 5 行(系统管理 + 4 个系统页)= 平台层的种子,值在 platform/seed.rs 的 BUILTIN_MENUS;
  • 后 3 行(Demo / 产品 / 图书)= 业务层的菜单,值在各自 modules/<app>.rs 的 *_MENU: MenuSpec, 经 modules::ALL_MENUS 交给装配根 src/bootstrap.rs 回灌。 ⇒ 加一个业务模块只碰 modules/(平台层一个字都不改),但菜单行数会变 ⇒ 本节表格与 modules::ALL_MENUS 必须同步;scripts/check-boundary.sh 的 CP4/CP6 静态钉住这两处一致。

8.5 种子角色(2 行)

id enCode fullName sortCode
role_admin admin 管理员 1
role_user user 使用者 2

其它列:f_tenant_id='0'、f_type='user'、f_enabled_mark=1、f_delete_mark=0。

8.6 两段式种子

ensure_base()(每次启动都跑,幂等)

  • 补内置角色:查 base_role 的全部行(🔴 不按 f_delete_mark 过滤), 凡 f_en_code 命中内置清单(admin / user)的一律视为已存在 ⇒ 不补、不覆盖。 缺的行按 §8.5 的值插入。
  • 补内置菜单:查 base_module 的全部行(🔴 含软删行), 凡 f_url_address 命中内置清单的一律视为已存在 ⇒ 不复活软删的菜单。 缺的行按 §8.4 的值插入(f_tenant_id='0'、f_enabled_mark=1、f_delete_mark=0)。
  • 补 admin 授权:
    • 取 base_role 中 f_en_code='admin' 的行(🔴 不按 f_delete_mark 过滤,取到软删行也用它);
    • 取 base_module 中 f_delete_mark=0 且 f_url_address 命中内置清单的行(builtin_live);
    • 查 base_authorize 中 f_object_type='role' AND f_object_id=<adminRoleId> AND f_item_type='module' 的全部行(🔴 不按 f_delete_mark 过滤 ⇒ 软删的授权行也算「已授权」⇒ 不补);
    • builtin_live 里没出现在上述集合中的行 ⇒ 补一条授权 (f_id=UUID v4、f_tenant_id='0'、f_object_type='role'、f_object_id=<adminRoleId>、 f_item_type='module'、f_item_id=<menuId>、f_sort_code=0、f_delete_mark=0)
  • 只补缺项:不覆盖已改值(人工改名/调序会被保留)

first_seed()(仅 base_user 行数为 0 时跑一次)

  • 建 admin 用户:f_id=UUID v4、f_account='admin'、f_real_name='管理员'、 f_password=md5_hex('123456')、f_is_administrator=1、f_organize_id='0'、 f_creator_user_id='admin'、f_creator_time=now、f_enabled_mark=1、f_delete_mark=0、f_tenant_id='0'
  • 建一条 base_role_relation:f_object_type='user'、🔴 f_object_id='admin'(账号名,不是 UUID!)、 f_role_id='role_admin'、f_sort_code=0、f_delete_mark=0、f_tenant_id='0'、f_id=UUID v4 (react 源码里就是 'admin',逐字照抄;admin 本人是管理员,不靠这条授权吃饭)

9. Rust 模块接口契约

🔴 代码分两层(对齐 react 版的 common+auth+sys / demo+shop+books, 以及官方 JNPF 的 jnpf-common+jnpf-system / jnpf-admin):

层 目录 职责 加业务模块
平台层 src/backend/src/platform/ 契约实现(信封 / cipher / 登录 / 权限 / base_* 管理 / 面 B / CRUD 引擎) 不动
业务层 src/backend/src/modules/ 业务 spec + 各自的 handler 与路由 只动这里

所有模块由 src/backend/src/lib.rs 统一 pub mod 导出。

// ---- lib.rs ----
pub mod modules;   // 业务层:demo / shop / books
pub mod platform;  // 平台层:契约实现
pub mod routes;    // 路由装配

ids.rs

pub fn new_uuid() -> String;   // 36 位 UUID v4(带连字符)

session.rs

#[derive(Clone)]
pub struct TokenUser { pub user_id: String, pub account: String, pub is_admin: i32 }

#[derive(Clone, Default)]
pub struct SessionStore { /* Arc<RwLock<HashMap<String, TokenUser>>> */ }

impl SessionStore {
    pub fn new() -> Self;
    pub fn issue(&self, account: &str, user_id: &str, is_admin: i32) -> String;  // "lite-" + 32 hex
    pub fn resolve(&self, auth_header: Option<&str>) -> Option<TokenUser>;       // 去 bearer 前缀(大小写不敏感)
}

config.rs

pub struct Config {
    pub port: u16,             // 默认 30010,env PORT
    pub pg_dir: PathBuf,       // env PGLITE_DIR;"memory://" ⇒ open_temp()
    pub project_dir: PathBuf,
    pub static_dir: Option<PathBuf>,   // src/frontend/dist 存在才有
}
impl Config { pub fn from_env(project_dir: PathBuf) -> Config; }

auth.rs

/// 三个字段全是 Option:缺字段也要走业务信封(code=400),不能落到 axum 默认的 400 文本。
/// `grant_type` 是 snake_case 字面量,**不能**改名为 camelCase。
#[derive(serde::Deserialize)]
pub struct LoginForm {
    pub account: Option<String>,
    pub password: Option<String>,
    pub grant_type: Option<String>,
}

pub async fn login(state: &AppState, body: LoginForm) -> Json<ActionResult>;
pub async fn current_user(state: &AppState, headers: HeaderMap) -> Json<ActionResult>;

/// 守卫:未登录 ⇒ `fail(600, "未登录")`;无菜单权限 ⇒ `fail(403, "无菜单权限")`
pub async fn require_login(state: &AppState, headers: &HeaderMap) -> Result<TokenUser, Json<ActionResult>>;
pub async fn require_module(state: &AppState, headers: &HeaderMap, module_key: &str)
    -> Result<TokenUser, Json<ActionResult>>;

permission.rs

pub async fn resolve_user_module_ids(db: &Db, user_id: &str) -> HashSet<String>;
pub async fn has_module(db: &Db, user_id: &str, is_admin: i32, module_key: &str) -> bool;
pub async fn build_menu_list(db: &Db, user_id: &str, is_admin: i32) -> Vec<MenuNode>;

#[derive(serde::Serialize)]
pub struct MenuNode {
    pub id: String, pub full_name: String,   // #[serde(rename="fullName")]
    pub url_address: Option<String>,        // #[serde(rename="urlAddress")]
    pub icon: Option<String>,
    pub parent_id: String,                   // #[serde(rename="parentId")]
    pub children: Vec<MenuNode>,
}

platform/entity.rs(业务实体 spec 的类型)+ modules/(业务 spec 本体)

🔴 类型在平台层、spec 在业务层(加业务模块只碰业务层)。

platform/entity.rs:

pub struct EntitySpec {
    pub app_code: &'static str,      // "demo" / "shop" / "books"
    pub entity: &'static str,        // "DemoItem" / "Product" / "Book"
    pub table: &'static str,         // "demo_item" / "shop_product" / "book_shop_book"
    pub module_key: Option<&'static str>,  // None = 仅登录守卫;Some("shop/Product")
    pub columns: &'static [ColumnSpec],
    pub numeric_columns: &'static [&'static str],   // 需要 ::text 投影的列
    // 🔴 `f_creator_user_id` 的写死值(裁决 S22):
    //    Some("admin") ⇒ 恒写 admin(demo);None ⇒ `body.creatorUserId || 'admin'`。
    //    平台层**不认 app_code** ⇒ 加新表不必改引擎。
    pub creator_fixed: Option<&'static str>,
}

pub struct ColumnSpec {
    pub column: &'static str,        // "f_title"
    pub json_key: &'static str,      // "title"
    pub default: Option<&'static str>, // 新建时的默认值
    pub numeric: bool,               // true ⇒ 投影 ::text
}

modules/mod.rs(业务层登记表):

pub fn all_specs() -> &'static [EntitySpec];
pub fn find_spec(app_code: &str, entity: &str) -> Option<&'static EntitySpec>;
pub const ALL_ROUTES: &[&str];   // 全部业务路由(业务层的路由表)
pub fn router() -> Router<AppState>;   // 全部业务模块的路由

platform/crud.rs(spec 驱动的通用 CRUD 引擎)

pub(crate) async fn handle_list(state: &AppState, headers: &HeaderMap, spec: &EntitySpec) -> Json<ActionResult>;
pub(crate) async fn handle_save(state: &AppState, headers: &HeaderMap, spec: &EntitySpec, body: &Bytes) -> Json<ActionResult>;
pub(crate) async fn handle_delete(state: &AppState, headers: &HeaderMap, spec: &EntitySpec, raw: &RawQuery) -> Json<ActionResult>;

🔴 平台层不含任何业务表名 / app_code ⇒ 加业务表不用改本文件。

routes.rs

pub fn build_router(state: AppState) -> Router;

(with_state 由 main.rs 在链尾调用; 业务路由由 routes.rs 的 .merge(modules::router()) 一次并入 ⇒ 加业务模块不动平台层。)

AppState(src/backend/src/platform/state.rs)

#[derive(Clone)]
pub struct AppState {
    pub config: Arc<Config>,
    pub db: Arc<Db>,
    pub sessions: Arc<SessionStore>,
}

🔴 src/backend/src/lib.rs 现在只声明三层:pub mod platform; / pub mod modules; / pub mod routes; —— 平台层的模块清单在 platform/mod.rs 里,业务层的在 modules/mod.rs 里。 (AppState 在 platform/state.rs。)


10. 启动装配(main.rs)

顺序:

  1. resolve_project_dir() —— 从可执行文件向上找锚点文件(src/backend/db/schema.sql + 根 Cargo.toml),与 cwd 解耦
  2. Config::from_env(project_dir)
  3. 标识符白名单自检(不过 ⇒ 秒退 exit 1),放在开库之前
  4. Db::open / Db::open_temp ⇒ ensure_schema()
  5. seed::ensure_base() ⇒ 若用户数为 0 则 seed::first_seed() 🔴 种子失败 ⇒ 打印人话错误 + exit 1(启动期不变量破了就立刻退出), 与第 3 步的白名单自检同一处置。react 的 onModuleInit 是 try/catch + logger.warn 后继续跑, 本仓刻意不同(react 那边是 NestJS 容器里已挂载的应用,退出不了;本仓是单二进制,退出更干净)。 这条不在 HTTP 契约面上(服务要么正常起来,要么根本不起来)。
  6. build_router(state) + 404 兜底 + 405 改写中间件 + catch-all(panic/未捕获异常 ⇒ HTTP 200 + code=400) + with_state(state)(链尾)
  7. TcpListener::bind ⇒ 绑定失败打印人话 + exit 1(不 panic)

子命令:--enc <明文> ⇒ 打印 hex 到 stdout,退出码 0(冒烟脚本用它自证 cipher,不依赖 node)。 --help / 未知参数 ⇒ 打印用法,退出码 0 或 2。

PGLITE_DIR=memory:// ⇒ Db::open_temp()(pglite-rs 0.2.7 没有真正的内存模式,open() 只接受路径)。


11. 验收门(六道,全绿才算完成)

门 命令 通过标准
① 编译 cargo build --release 0 error 0 warning;release profile:根 Cargo.toml 写 opt-level=2 / lto="thin" / strip="symbols" / codegen-units=16;🔴 不要写 panic="abort"(Ruling P19:abort 下 catch_unwind 抓不到 panic,与 §6.5 的「panic ⇒ HTTP 200 + code=400」冲突 ⇒ 必须用默认的 unwind)
② 单测 cargo test 见 §12
③ 冒烟 bash scripts/perm-smoke.sh 全部断言全绿(FAIL=0),断言集与 react 版逐条对应;🔴 后端不用先起 —— 尺子默认自起隔离实例(见下)
④ 前端手验 cd src/frontend && npm run dev http://127.0.0.1:5173 → admin/123456 登录 → 菜单树正确 → 5 个管理页可增删改 → 3 个业务页可用 → 退出再登录
⑤ 静态闸门 bash scripts/check-module.sh + bash scripts/check-boundary.sh + bash scripts/check-contract.sh + bash scripts/check-citations.sh 四把尺子全绿(86 / 11 / 10 / 4 条断言,FAIL=0)——纯静态,不起后端。🔴 本仓后端-only:check-module 的 10 个前端接触点打 ⏭(仍计入条数),见附录 A [RULER]

脚本退出码约定(各入口一致): run.sh 0=成功 / 1=运行期失败 / 2=用法错; check-module.sh 0=全过 / 1=有 ❌ / 2=用法错; check-boundary.sh 0=全过 / 1=有 ❌ / 2=用法错; check-contract.sh 0=全过 / 1=有 ❌ / 2=用法错或前置错误(契约读不出来); check-citations.sh 0=全过 / 1=有 ❌ / 2=用法错或前置错误; perm-smoke.sh 0=全绿 / 1=有断言失败 / 2=前置错误(后端不可达且显式指定了 B ⇒ 不自起)。

🔴 两把契约尺子默认自起隔离后端(scripts/smoke_backend.sh): 没给 B ⇒ 先探 :30010;通 ⇒ 用它;不通 ⇒ 自起隔离实例(空闲端口 + mktemp -d 临时 PGLITE_DIR),跑完即删 ⇒ 两把尺子互不污染、不留脏数据、CI 可跑。 显式给了 B ⇒ 不自起,不可达即退出码 2(尊重外部后端)。

🔴 官方端点覆盖是一本「账」(附录 A 的 [OFFICIAL] 区段,机器可读): 官方 JNPF 契约面的端点全表在 JNPF_SOURCE_AUDIT.md §4(散文表格), 本仓的覆盖账本在附录 A [OFFICIAL](机器可读)⇒ check-contract.sh 的 CC10 与代码真实路由双向对账,并打印 「官方端点覆盖 N/M」(N = implemented + partial;M = 再加 absent;oos 单列不进分母)。 状态词表:implemented(已落地且形状对齐)/ partial(已落地但形状有偏差, 偏差逐条记在 JNPF_COMPAT_SURFACE.md §8 的 B1–B10)/ absent(未实现,可后置)/ oos(v1 明确不做)。🔴 面 B / 共用的每条路由都必须在账上(防止"实现了但没记账")。

🔴 尺子的期望值只有一处:附录 A(机器可读)。 菜单表 / 菜单树 / 业务模块清单 / 端点表(路径 / 方法 / 守卫 / 归属) / 各尺子的断言条数都不写在脚本里, 一律由 scripts/contract_expect.py 从附录 A 读 ⇒ ① 改契约只改附录 A 一处;② 代码漂移尺子立刻报;③ 加模块不用改脚本。 🔴 每把尺子都自证:结尾比对「本尺子实际跑了多少条断言」与附录 A [RULER] 登记的条数, 对不上 ⇒ 失败 ⇒ 尺子不会被人悄悄改弱(这条是故意的:加断言必须同步契约)。


12. 单测覆盖清单(门② 必须全过)

  • cipher:上游向量逐字节相等;md5_hex ↔ decrypt_to_md5 往返;非法 hex ⇒ None
  • envelope:业务失败 HTTP 200 + code=400;code=600/403 同形;成功 code=200+msg='成功'
  • db:split_sql_statements 字面量感知(单引号 / dollar-quote / 注释内的 ; 不切); column_to_json_key / json_key_to_column 互逆;valid_table 只收 [A-Za-z][A-Za-z0-9_]*
  • ids:UUID 36 位带连字符、格式合法
  • session:登录后可查回;错误 token 查不到;bearer 前缀大小写不敏感
  • permission:四源合并各源单独可注入;管理员短路不查 SQL(无授权记录的管理员仍放行);未映射菜单放行
  • seed:空库启动 ⇒ admin/123456 + 2 角色 + 8 菜单 + admin 授权;再启动一次库内容不变;不复活软删行
  • CRUD 往返:36 位 UUID;numeric ⇒ "9.90";int ⇒ 100;软删过滤生效;账号重复返 400(不是 500)

13. 冒烟断言集(门③,逐条对应 react 版)

react 版 scripts/perm-smoke.sh 实际有 32 条断言。移植后一条不落,另加 9 条真实业务模块断言(33–41,asset/DataResource)+ 2 条多应用断言(42/43)⇒ 本仓共 43 条:

# 断言 期望
1 无 token 访问 User/List code=600
2 admin 加密登录 code=200
3 token 非空 真
4 CurrentUser code=200
5 菜单树 系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:
6 新建 smoke_user code=200
7 重复账号 HTTP 状态 200(不是 500)
8 重复账号业务码 code=400
9 重复账号 msg 账号已存在:smoke_user
10 写授权(一维数组) code=200
11 写授权(二维兼容) code=200
12 smoke_user 登录 code=200
13 smoke_user 菜单收窄 Demo 示例:
14 smoke_user 访问 User/List code=403
15 smoke_user 访问 DemoItem/List code=200
16 未知路由 HTTP 404
17 admin 访问 Product/List code=200(管理员短路)
18 Product 新建 code=200
19 Product 主键长度 36
20 Product numeric 往返 "9.90"
21 Product 无 token code=600
22 Product 未授权非管理员 code=403
23 Book 列表(admin 短路) code=200
24 Book 新建(6 字段) code=200
25 Book 主键长度 36
26 Book title 往返 三体
27 Book author 往返 刘慈欣
28 Book numeric 往返 "58.00"
29 Book int 库存往返 100
30 Book 列表含新建项 长度 ≥ 1
31 Book 无 token code=600
32 Book 未授权非管理员 code=403
33 数据资源列表(admin 短路) code=200
34 数据资源新建(6 字段) code=200
35 数据资源主键长度 36
36 数据资源 name 往返 全国企业工商登记数据
37 数据资源 category 往返 结构化
38 数据资源 provider 往返 尚数网
39 数据资源列表含新建项 长度 ≥ 1
40 数据资源无 token code=600
41 数据资源未授权非管理员 code=403
42 多应用:CurrentUser 无 App-Code 头 data.currentSystemId = "mainSystem"(官方 JnpfConst.MAIN_SYSTEM_CODE,回落主系统)
43 多应用:CurrentUser 带 App-Code: app-b data.currentSystemId = "app-b"(应用路由生效)

脚本不得依赖 node(react 版依赖 node + crypto-js + src/backend/node_modules,本仓一律不用):

  • cipher 加密 ⇒ 调用后端自证:./target/release/ssw-platform --enc '<明文>' 输出 hex(退出码 0)。 (冒烟脚本自带 --enc 的向量自检,不假设 node 存在。)
  • JSON 取值 ⇒ jq(若已装)或 python3(macOS 自带)写的取字段小工具;不得用 node。
  • 期望菜单树 ⇒ 从附录 A 的 [MENU_TREE] 区段读(不是写死在脚本里)—— 值仍是 §8.4 的 系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:。 react 版是从 src/backend/src/sys/seed.service.ts 里 grep 菜单数组动态算的 —— 本仓是 Rust,没有那个文件 ⇒ 直接用字面量(§8.4 的表就是它的来源)。
  • 后端地址 ⇒ B 环境变量,默认 http://127.0.0.1:30010(本仓端口,不是 react 的 30000)。
  • 所有 curl 都要带 --noproxy '*'(本机 curl 走系统代理,不加会打不通 loopback)。
# 契约期望值 —— **唯一真源**。
#
# 🔴 下面这段是**机器可读**的(`scripts/contract_expect.py` 解析),
#    所有尺子(check-module.sh / check-boundary.sh / check-contract.sh /
#    perm-smoke.sh / perm-smoke-jnpf.sh)
#    的**期望值都从这里读** ⇒
#    ① 改契约 ⇒ 改这一处,尺子自动跟着走;
#    ② 代码漂移 ⇒ 尺子立刻报「与契约不一致」(不是默默放过)。
#
# 格式:区段 `[NAME]` + **制表符**分隔的列;`#` 开头是注释行(忽略)。
# 列名以各区段的表头注释为准。空字段 = 空值(NULL)。
#
# 区段:
#   [MENU]       种子菜单 8 行(id / fullName / enCode / urlAddress / parentId / type / icon / sortCode)
#   [MENU_TREE]  期望菜单树字符串(面 A 的 CurrentUser 对账用)
#   [MODULE]     业务模块清单(app / entity / table / urlAddress / moduleKey / menuId / apiFile / rsFile)
#   [ENDPOINT]   **端点表**(face / method / path / guard / owner)—— 由 `scripts/check-contract.sh`
#                与**代码里真实注册的路由**逐条对账(总数 / 存在性 / 方法 / 归属层 / 守卫,双向)
#   [FACE]       各契约面的条数(自洽对账用)
#   [OFFICIAL]   **官方端点台账**(method / path / status / src / note)—— 官方 JNPF 契约面的
#                覆盖账本;由 `scripts/check-contract.sh` 的 CC10 与代码真实路由**双向**对账
#   [RULER]      各尺子的期望断言条数(尺子自证用)

[MENU]
# id	fullName	enCode	urlAddress	parentId	type	icon	sortCode
m_sys	系统管理	permission	system	0	1	setting	1
m_user	用户管理	permission.user	system/User	m_sys	2		2
m_role	角色管理	permission.role	system/Role	m_sys	2		3
m_org	机构管理	permission.organize	system/Organize	m_sys	2		4
m_menu	菜单管理	permission.menu	system/Module	m_sys	2		5
m_demo	Demo 示例	permission.demo	demo-item	0	2	app	6
m_product	产品管理	permission.shop.product	shop/Product	0	2	app	7
m_book	图书超市	permission.books.book	books/Book	0	2	app	8
m_resource	数据资源	permission.asset.dataResource	asset/DataResource	0	2	app	9

[MENU_TREE]
系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:|数据资源:

[MODULE]
# app	entity	table	urlAddress	moduleKey	menuId	apiFile	rsFile
#   moduleKey = 该模块的守卫菜单 key;`None` = 仅需登录(无菜单权限要求)
#   apiFile  = 前端**应不应该**有 `src/frontend/src/api/<name>.ts`(`有` / `无`)
#   rsFile   = 业务模块源文件 `src/backend/src/modules/<name>.rs`
demo	DemoItem	demo_item	demo-item	None	m_demo	无	demo.rs
shop	Product	shop_product	shop/Product	shop/Product	m_product	有	shop.rs
books	Book	book_shop_book	books/Book	books/Book	m_book	有	books.rs
asset	DataResource	asset_data_resource	asset/DataResource	asset/DataResource	m_resource	有	asset.rs

[ENDPOINT]
# face	method	path	guard	owner
#   face  = A(面A 专属) / B(面B 专属) / AB(两面共用,按判别头 `Vue-Version: 3` 分流)
#   guard = 无 / 登录 / 面A 的菜单路径 key / 面B 的点权限编码 `f_en_code`
#   owner = platform(平台层) / 业务模块代号(demo|shop|books) ⇒ 路由注册在哪个文件
#   path  = 与代码**逐字**一致(axum 0.8 的 `{param}` 花括号语法)
A	GET	/api/health	无	platform
A	POST	/api/oauth/Login	无	platform
AB	GET	/api/oauth/CurrentUser	登录	platform
A	GET	/api/ssw/sys/User/List	system/User	platform
A	POST	/api/ssw/sys/User/Save	system/User	platform
A	DELETE	/api/ssw/sys/User/Delete	system/User	platform
A	GET	/api/ssw/sys/Role/List	system/Role	platform
A	POST	/api/ssw/sys/Role/Save	system/Role	platform
A	DELETE	/api/ssw/sys/Role/Delete	system/Role	platform
A	GET	/api/ssw/sys/Role/Modules	登录	platform
A	GET	/api/ssw/sys/Organize/List	system/Organize	platform
A	POST	/api/ssw/sys/Organize/Save	system/Organize	platform
A	DELETE	/api/ssw/sys/Organize/Delete	system/Organize	platform
A	GET	/api/ssw/sys/Module/List	system/Module	platform
A	POST	/api/ssw/sys/Module/Save	system/Module	platform
A	DELETE	/api/ssw/sys/Module/Delete	system/Module	platform
AB	PUT	/api/permission/Authority/Data/{objectId}	登录	platform
A	GET	/api/permission/Authority/RoleModules	登录	platform
B	GET	/api/permission/Users	permission.user	platform
B	POST	/api/permission/Users	permission.user	platform
B	GET	/api/permission/Users/{id}	permission.user	platform
B	PUT	/api/permission/Users/{id}	permission.user	platform
B	DELETE	/api/permission/Users/{id}	permission.user	platform
B	POST	/api/permission/Users/BatchDelete	permission.user	platform
B	POST	/api/permission/Users/BatchUpdateState	permission.user	platform
B	GET	/api/permission/Users/{id}/GetPosition	permission.user	platform
B	POST	/api/permission/Users/{id}/Actions/ResetPassword	permission.user	platform
B	PUT	/api/permission/Users/{id}/Actions/unlock	permission.user	platform
B	GET	/api/permission/Group	permission.user	platform
B	POST	/api/permission/Group	permission.user	platform
B	GET	/api/permission/Group/{id}	permission.user	platform
B	PUT	/api/permission/Group/{id}	permission.user	platform
B	DELETE	/api/permission/Group/{id}	permission.user	platform
B	POST	/api/permission/Group/{id}/Actions/AddUser	permission.user	platform
B	POST	/api/permission/Group/{id}/Actions/DeleteUser	permission.user	platform
B	POST	/api/permission/Users/{id}/SetPosition	permission.user	platform
B	POST	/api/permission/Users/SetPositionBatch	permission.user	platform
B	POST	/api/permission/Users/workHandover	permission.user	platform
B	GET	/api/permission/Users/{id}/SelectorByUserPosId	permission.user	platform
B	GET	/api/system/System/getDevUser	permission.user	platform
B	DELETE	/api/permission/socials/{id}	permission.user	platform
B	GET	/api/system/DictionaryData/All	登录	platform
B	GET	/api/system/HomeData	登录	platform
B	POST	/api/system/MenuData/useModuleNum/{id}	登录	platform
B	GET	/api/oauth/getLoginConfig	无	platform
B	GET	/api/oauth/getConfig/{account}	无	platform
B	GET	/api/permission/Organize	permission.organize	platform
B	POST	/api/permission/Organize	permission.organize	platform
B	GET	/api/permission/Organize/{id}	permission.organize	platform
B	PUT	/api/permission/Organize/{id}	permission.organize	platform
B	DELETE	/api/permission/Organize/{id}	permission.organize	platform
B	GET	/api/permission/Organize/Selector	permission.organize	platform
B	POST	/api/permission/Role	permission.role	platform
B	GET	/api/permission/Role/{id}	permission.role	platform
B	PUT	/api/permission/Role/{id}	permission.role	platform
B	DELETE	/api/permission/Role/{id}	permission.role	platform
B	GET	/api/permission/Role/Selector	permission.role	platform
B	POST	/api/permission/Role/RoleCondition	permission.role	platform
B	GET	/api/permission/Position	permission.position	platform
B	POST	/api/permission/Position	permission.position	platform
B	GET	/api/permission/Position/{id}	permission.position	platform
B	PUT	/api/permission/Position/{id}	permission.position	platform
B	DELETE	/api/permission/Position/{id}	permission.position	platform
B	GET	/api/permission/Position/Selector	permission.position	platform
B	GET	/api/permission/Position/SelectorTree	permission.position	platform
B	POST	/api/permission/Position/PositionCondition	permission.position	platform
B	POST	/api/permission/Position/SelectedList	permission.position	platform
B	POST	/api/permission/Position/{id}/Actions/DutyPosition	permission.position	platform
B	POST	/api/permission/Position/{id}/Actions/DutyUser	permission.position	platform
B	GET	/api/permission/Group/Selector	permission.user	platform
B	GET	/api/permission/Organize/AsyncPosList	permission.organize	platform
B	POST	/api/system/Menu	permission.menu	platform
B	GET	/api/system/Menu/{id}	permission.menu	platform
B	PUT	/api/system/Menu/{id}	permission.menu	platform
B	DELETE	/api/system/Menu/{id}	permission.menu	platform
B	GET	/api/system/Menu/Selector/{id}	permission.menu	platform
B	GET	/api/system/Menu/Selector/All	permission.menu	platform
B	GET	/api/system/Menu/Selector/Form	permission.menu	platform
B	GET	/api/system/Menu/Selector/Page	permission.menu	platform
B	GET	/api/system/Menu/SelectorFilter/{id}	permission.menu	platform
B	GET	/api/system/Menu/getSystemMenu	permission.menu	platform
B	GET	/api/system/Menu/{id}/Actions/Export	permission.menu	platform
B	GET	/api/system/Menu/getPermissionGroup/{id}	permission.menu	platform
B	GET	/api/system/Menu/getPermission/{id}/{permissionId}	permission.menu	platform
B	GET	/api/system/DictionaryType	permission.dictionary	platform
B	POST	/api/system/DictionaryType	permission.dictionary	platform
B	GET	/api/system/DictionaryType/{id}	permission.dictionary	platform
B	PUT	/api/system/DictionaryType/{id}	permission.dictionary	platform
B	DELETE	/api/system/DictionaryType/{id}	permission.dictionary	platform
B	GET	/api/system/DictionaryType/Selector/{id}	permission.dictionary	platform
B	POST	/api/system/DictionaryData	permission.dictionary	platform
B	GET	/api/system/DictionaryData/{id}	permission.dictionary	platform
B	GET	/api/system/DictionaryData/{id}/Info	permission.dictionary	platform
B	PUT	/api/system/DictionaryData/{id}	permission.dictionary	platform
B	DELETE	/api/system/DictionaryData/{id}	permission.dictionary	platform
B	GET	/api/system/DictionaryData/{id}/Data/Selector	permission.dictionary	platform
B	GET	/api/system/DictionaryData/{id}/Selector/{pid}	permission.dictionary	platform
B	GET	/api/system/DictionaryData/{id}/Actions/Export	permission.dictionary	platform
B	GET	/api/permission/Users/Selector	permission.user	platform
B	POST	/api/permission/Users/getUserList	permission.user	platform
B	POST	/api/permission/Users/getSelectedList	permission.user	platform
B	POST	/api/permission/Users/getSelectedUserList	permission.user	platform
B	GET	/api/permission/Users/ReceiveUserList	permission.user	platform
B	GET	/api/permission/Users/getAllPermission	permission.user	platform
B	GET	/api/permission/Users/Authorize	permission.user	platform
B	GET	/api/permission/Authority/{kind}/{objectId}	permission.role	platform
B	POST	/api/permission/Authority/{kind}/{objectId}	permission.role	platform
B	GET	/api/permission/RoleRelation/roleList	permission.role	platform
B	POST	/api/permission/RoleRelation/addRoles	permission.role	platform
B	POST	/api/permission/RoleRelation/deleteRoles	permission.role	platform
B	POST	/api/permission/RoleRelation/delete	permission.role	platform
B	POST	/api/permission/UserRelation	permission.user	platform
B	POST	/api/permission/UserRelation/delete	permission.user	platform
B	GET	/api/permission/UserRelation/userList	permission.user	platform
B	GET	/api/permission/Role	permission.role	platform
B	POST	/api/oauth/Logout	登录	platform
B	GET	/api/system/BaseLang/LangJson	登录	platform
B	GET	/api/permission/Organize/AsyncList/{id}	permission.organize	platform
B	GET	/api/system/Menu/ModuleBySystem	permission.menu	platform
B	POST	/api/permission/Authority/Data/{objectId}/Values	登录	platform
B	GET	/api/permission/Users/Current/BaseInfo	登录	platform
B	PUT	/api/permission/Users/Current/BaseInfo	登录	platform
B	PUT	/api/permission/Users/Current/Avatar	登录	platform
B	PUT	/api/permission/Users/Current/SystemTheme	登录	platform
B	PUT	/api/permission/Users/Current/SystemLanguage	登录	platform
B	POST	/api/permission/Users/Current/Actions/ModifyPassword	登录	platform
B	GET	/api/permission/Users/Current/Subordinate/{id}	登录	platform
B	GET	/api/permission/Users/Current/SystemLog	登录	platform
B	GET	/api/permission/Users/Current/getUserOrganizes	登录	platform
B	GET	/api/permission/Users/Current/getUserPositions	登录	platform
B	GET	/api/permission/Users/Current/getUserRoles	登录	platform
B	PUT	/api/permission/Users/Current/major	登录	platform
B	GET	/api/permission/Users/Current/SignImg	登录	platform
B	POST	/api/permission/Users/Current/SignImg	登录	platform
B	DELETE	/api/permission/Users/Current/{id}/SignImg	登录	platform
B	PUT	/api/permission/Users/Current/{id}/SignImg	登录	platform
B	GET	/api/permission/Users/Current/getAppSecret	登录	platform
B	PUT	/api/permission/Users/Current/saveAppSecret	登录	platform
B	GET	/api/permission/Users/Current/saasList	登录	platform
B	GET	/api/permission/Users/Current/saasinfo	登录	platform
B	GET	/api/permission/Users/Current/saasTenantName/{id}	登录	platform
B	POST	/api/permission/Users/Current/saasjoin	登录	platform
B	DELETE	/api/permission/Users/Current/{id}/saas	登录	platform
B	GET	/api/permission/Standing	permission.identity	platform
B	POST	/api/permission/Standing	permission.identity	platform
B	GET	/api/permission/Standing/list	permission.identity	platform
B	GET	/api/permission/Standing/{id}	permission.identity	platform
B	PUT	/api/permission/Standing/{id}	permission.identity	platform
B	DELETE	/api/permission/Standing/{id}	permission.identity	platform
B	POST	/api/permission/Standing/{id}/Actions/AddObject	permission.identity	platform
B	POST	/api/permission/Standing/{id}/Actions/DeleteObject	permission.identity	platform
B	GET	/api/permission/PermissionGroup	permission.authGroup	platform
B	POST	/api/permission/PermissionGroup	permission.authGroup	platform
B	GET	/api/permission/PermissionGroup/{id}	permission.authGroup	platform
B	PUT	/api/permission/PermissionGroup/{id}	permission.authGroup	platform
B	DELETE	/api/permission/PermissionGroup/{id}	permission.authGroup	platform
B	POST	/api/permission/PermissionGroup/{id}/Actions/Copy	permission.authGroup	platform
B	GET	/api/permission/PermissionGroup/PermissionMember/{id}	permission.authGroup	platform
B	POST	/api/permission/PermissionGroup/PermissionMember/{id}	permission.authGroup	platform
B	GET	/api/permission/Action	permission.action	platform
B	POST	/api/permission/Action	permission.action	platform
B	GET	/api/permission/Action/{id}	permission.action	platform
B	PUT	/api/permission/Action/{id}	permission.action	platform
B	DELETE	/api/permission/Action/{id}	permission.action	platform
A	GET	/api/ssw/demo/DemoItem/List	登录	demo
A	POST	/api/ssw/demo/DemoItem/Save	登录	demo
A	DELETE	/api/ssw/demo/DemoItem/Delete	登录	demo
A	GET	/api/ssw/shop/Product/List	shop/Product	shop
A	POST	/api/ssw/shop/Product/Save	shop/Product	shop
A	DELETE	/api/ssw/shop/Product/Delete	shop/Product	shop
A	GET	/api/ssw/books/Book/List	books/Book	books
A	POST	/api/ssw/books/Book/Save	books/Book	books
A	DELETE	/api/ssw/books/Book/Delete	books/Book	books
A	GET	/api/ssw/asset/DataResource/List	asset/DataResource	asset
A	POST	/api/ssw/asset/DataResource/Save	asset/DataResource	asset
A	DELETE	/api/ssw/asset/DataResource/Delete	asset/DataResource	asset

[FACE]
# face	条数	说明
A	28	面 A 专属(+ 2 条共用 ⇒ 面 A 合计 30 条)
B	146	面 B 专属(官方 JNPF 形状)
AB	2	两面共用(CurrentUser / Authority Data —— 按判别头分流)

[OFFICIAL]
# 官方端点台账 —— 本仓对**官方 JNPF 契约面**的覆盖账本(机器可读)
#   method  = HTTP 方法;`*` = 端点**一族**(范围声明,不做存在性对账)
#   path    = 官方路径(axum 0.8 的 `{param}` 花括号语法)
#   status  = implemented(已落地且形状对齐) / partial(已落地但**形状有偏差**,见 note)
#             / absent(未实现,可后置) / oos(v1 明确不做,不进覆盖分母)
#   src     = 官方出处(`文件:行号` ⇒ 由 `scripts/check-citations.sh` 逐条核对)
#   note    = 偏差/取舍说明
#
# 🔴 由 `scripts/check-contract.sh` 的 **CC10** 与代码真实路由**双向**对账:
#    implemented/partial 的必须真的注册了;absent/oos 的必须**没有**注册;
#    反向:代码里**面 B / 共用**的每条路由都必须在本台账里**有账**。
#   覆盖 N/M = (implemented + partial) / (implemented + partial + absent)。
POST	/api/oauth/Login	partial	LoginController.java:117	路径与入参逐字一致;返回的是面 A 形状(token 同名同义),官方 LoginVO 的 theme/wlQrcode/isSaas/saasList 未返
POST	/api/oauth/Logout	implemented	LoginController.java:155	面 B 已落地:恒 `{data:null}`(前端 try/catch 丢弃返回值,但 404 会弹红条);服务端不撤销 token(进程内内存表无 revoke,已知限制 B5)
GET	/api/system/BaseLang/LangJson	implemented	baseLang.ts:28-30	面 B 已落地:恒 `{data:null}` ⇒ 前端 `locales/index.ts:114` 走 `!res.data` 早退,不 merge 远端词条(本仓无 base_language 表)
GET	/api/oauth/CurrentUser	partial	LoginController.java:192	面 B 返 PcUserVO 5 字段;sysConfigInfo 返空对象、currentSystemId 固定、按钮级权限恒空、permissionList 按菜单给
GET	/api/permission/Users	implemented	UserController.java:293	面 B 已落地:PageListVO 形状、列表项无 password/secretkey、isAdministrator 是数字
GET	/api/permission/Users/{id}	implemented	UserController.java:355	面 B 已落地:UserInfoVO 形状(Form.vue 的 field 逐字对齐),无 password/secretkey
POST	/api/permission/Users	implemented	UserController.java:409	面 B 已落地:白名单写库 + 账号查重 + 默认口令 md5(123456),返回 `{id}`
PUT	/api/permission/Users/{id}	implemented	UserController.java:429	面 B 已落地:**只 SET body 里出现的键**(未出现的列保持原值)
DELETE	/api/permission/Users/{id}	implemented	UserController.java:496	面 B 已落地:软删(f_delete_mark=1),幂等
POST	/api/permission/Users/BatchDelete	implemented	UserController.java:592	面 B 已落地:一条 UPDATE … IN ⇒ 原子;空集合返成功
POST	/api/permission/Users/BatchUpdateState	implemented	UserController.java:694	面 B 已落地:批量改 f_enabled_mark
GET	/api/permission/Users/All	absent	UserController.java:729	全量用户未做
GET	/api/permission/Users/Selector	implemented	UserController.java:769	用户下拉未做
POST	/api/permission/Users/UserCondition	absent	UserController.java:806	用户条件查询未做
GET	/api/permission/Users/{id}/GetPosition	implemented	UserController.java:273	面 B 已落地:无 base_position 表 ⇒ 由 f_position_id 反推,包成 `[{id}]`
POST	/api/permission/Users/{id}/Actions/ResetPassword	implemented	user.ts:37	面 B 已落地:body.password ⇒ md5;兼容 newPassword
PUT	/api/permission/Users/{id}/Actions/unlock	implemented	user.ts:45	面 B 已落地:清 f_lock_mark / f_unlock_time / f_log_error_count
GET	/api/permission/Users/ExportData	oos	user.ts:53	导入导出族(官方前端按需)—— v1 明确不做
GET	/api/permission/Users/TemplateDownload	oos	user.ts:57-69	导入导出族 —— v1 明确不做
POST	/api/permission/Users/ImportData	oos	user.ts:57-69	导入导出族 —— v1 明确不做
POST	/api/permission/Users/ImportPreview	oos	user.ts:57-69	导入导出族 —— v1 明确不做
GET	/api/permission/Users/ExportExceptionData	oos	user.ts:57-69	导入导出族 —— v1 明确不做
POST	/api/permission/Users/getUserList	implemented	user.ts:49	批量选择族(可后置,未列入 v1 范围也未明确排除)
POST	/api/permission/Users/getSelectedList	implemented	user.ts:73	批量选择族(可后置)
POST	/api/permission/Users/getSelectedUserList	implemented	user.ts:77	批量选择族(可后置)
GET	/api/permission/Group	implemented	group.ts:9	面 B 已落地:ListVO `{list}`(前端 `user/index.vue:340` 取 `res.data.list`);新表 `base_group`(官方 `JNPF-PostgreSQL.sql:1758`,14 列逐字)
POST	/api/permission/Group	implemented	group.ts:17	面 B 已落地:白名单写库 + 名称非空校验,返 `{id}`;成员关系**不在**本表
GET	/api/permission/Group/{id}	implemented	group.ts:25	面 B 已落地:`GroupForm.vue:64` 直接 `setFieldsValue(res.data)`
PUT	/api/permission/Group/{id}	implemented	group.ts:21	面 B 已落地:**只 SET body 里出现的键**
DELETE	/api/permission/Group/{id}	implemented	group.ts:29	面 B 已落地:软删分组 + 同步软删 `base_user_relation` 的 Group 关系行
POST	/api/permission/Group/{id}/Actions/AddUser	implemented	group.ts:37	面 B 已落地:`base_user_relation`(f_object_type='Group'),幂等插;空集合返成功
POST	/api/permission/Group/{id}/Actions/DeleteUser	implemented	group.ts:41	面 B 已落地:关系行软删;空集合返成功
POST	/api/permission/Users/{id}/SetPosition	implemented	user.ts:101	面 B 已落地:岗位写 `base_user.f_position_id`(逗号分隔);无 base_position 表
POST	/api/permission/Users/SetPositionBatch	implemented	user.ts:105	面 B 已落地:body `{userIds, ids}`,一条 UPDATE … ANY(string_to_array) 原子完成
POST	/api/permission/Users/workHandover	implemented	user.ts:85	面 B 已落地:置 `f_handover_mark=1`;工作流/流程任务不迁 ⇒ 只落能落的部分
GET	/api/permission/Users/{id}/SelectorByUserPosId	implemented	user.ts:93	面 B 已落地:同 `f_position_id` 的其它用户(ListVO)
GET	/api/system/System/getDevUser	implemented	system.ts:53	面 B 已落地:`QueryUserSelect` 的 `:api` ⇒ ListVO;无「开发者」列 ⇒ 退化为全体用户(管理员优先)
DELETE	/api/permission/socials/{id}	implemented	socialsUser.ts:21	面 B 已落地:本仓无 `base_socials_users` 表 ⇒ 无绑可解,恒成功(只返 msg)
GET	/api/system/DictionaryData/All	implemented	dictionary.ts:38-40	面 B 已落地:恒 `{list:[]}`(无 base_dictionary 表);前端 `store/base.ts:48` 取 `res.data.list` ⇒ 不能是裸数组
GET	/api/system/HomeData	implemented	homeData.ts:8	面 B 已落地:恒 `[]`(前端 `dashboard/index.vue:104` 读 `res.data.length` ⇒ 必须是数组)
POST	/api/system/MenuData/useModuleNum/{id}	implemented	collectMenu.ts:21	面 B 已落地:常用菜单计数**无表可记** ⇒ 恒成功(每页 afterEach 都调,404 会弹红条)
GET	/api/oauth/getLoginConfig	implemented	user.ts:33	面 B 已落地:恒 `{}`(**登录前**调用 ⇒ 无守卫;前端读 `res.data.redirect` ⇒ 必须是对象)
GET	/api/oauth/getConfig/{account}	implemented	user.ts:31	面 B 已落地:恒 `{}`(同登录前,无守卫)
GET	/api/permission/Organize	implemented	organize.ts:13	面 B 已落地:ListVO `{list}`(`organize/index.vue:280` 取 `res.data.list`);树本身走 `AsyncList/{parentId}`
POST	/api/permission/Organize	implemented	organize.ts:17	面 B 已落地:白名单写库 + 名称非空校验;`f_organize_id_tree`/`f_org_name_tree` 按「父树+自己」拼
GET	/api/permission/Organize/{id}	implemented	organize.ts:25	面 B 已落地:`OrganizeForm.vue:103` 直接 `setFieldsValue(res.data)`
PUT	/api/permission/Organize/{id}	implemented	organize.ts:21	面 B 已落地:**只 SET body 里出现的键**(表单提交 parentId/category/fullName/enCode/sortCode/description)
DELETE	/api/permission/Organize/{id}	implemented	organize.ts:29	面 B 已落地:软删本行;**不级联**子机构(已知限制)
GET	/api/permission/Organize/Selector	implemented	organize.ts:53	面 B 已落地:ListVO 全树(不做 parentId 剪枝 ⇒ 权限页选择器一次看到全树)
GET	/api/permission/Position	implemented	position.ts:9	面 B 已落地:ListVO `{list}`;新表 `base_position`(官方 DDL 逐字)
POST	/api/permission/Position	implemented	position.ts:13	面 B 已落地:`POSITION_WRITE_FIELDS` 白名单 + 名称非空;`f_position_id_tree` 恒为自己(本仓岗位无层级)
GET	/api/permission/Position/{id}	implemented	position.ts:21	面 B 已落地:岗位详情
PUT	/api/permission/Position/{id}	implemented	position.ts:17	面 B 已落地:**只 SET body 里出现的键**
DELETE	/api/permission/Position/{id}	implemented	position.ts:25	面 B 已落地:软删本行
GET	/api/permission/Position/Selector	implemented	position.ts:45	面 B 已落地:ListVO 全量岗位
GET	/api/permission/Position/SelectorTree	implemented	position.ts:41	面 B 已落地:`organizeId` 命中就只返该机构岗位;本仓岗位无层级 ⇒ 平铺
POST	/api/permission/Position/PositionCondition	implemented	position.ts:37	面 B 已落地:body `{ids}` ⇒ `ANY(string_to_array(...))`
POST	/api/permission/Position/SelectedList	implemented	position.ts:49	面 B 已落地:同 PositionCondition(**刻意不复用**,委托会让契约扫描器推不出守卫)
POST	/api/permission/Position/{id}/Actions/DutyPosition	implemented	position.ts:29	面 B 已落地:写 `base_organize.f_duty_position`;`organizeId` 缺失 ⇒ 400
POST	/api/permission/Position/{id}/Actions/DutyUser	implemented	position.ts:33	面 B 已落地:写 `base_position.f_duty_user`;`userId` 缺失 ⇒ 400
GET	/api/permission/Organize/AsyncPosList	implemented	organize.ts:68	面 B 已落地:按 `type` 分流(position ⇒ 岗位表,否则按 parentId 取机构)
GET	/api/permission/Group/Selector	implemented	group.ts:13	面 B 已落地:ListVO 全量分组
POST	/api/system/Menu	implemented	menu.ts:22	面 B 已落地:`MENU_WRITE_FIELDS` 白名单 + 名称非空;`f_system_id` 不传就落当前 App-Code 解析出的系统
GET	/api/system/Menu/{id}	implemented	menu.ts:31	面 B 已落地:菜单详情
PUT	/api/system/Menu/{id}	implemented	menu.ts:26	面 B 已落地:**只 SET body 里出现的键**
DELETE	/api/system/Menu/{id}	implemented	menu.ts:35	面 B 已落地:软删本行;**不级联**子菜单(已知限制)
GET	/api/system/Menu/Selector/{id}	implemented	menu.ts:15	面 B 已落地:上级菜单下拉,**排除自己及其直接子级**(防树成环)
GET	/api/system/Menu/Selector/All	implemented	menu.ts:19	面 B 已落地:ListVO 当前系统全量菜单
GET	/api/system/Menu/Selector/Form	implemented	menu.ts:56	面 B 已落地:同 Selector/All
GET	/api/system/Menu/Selector/Page	implemented	menu.ts:60	面 B 已落地:PageListVO;`type` 有值就按 `f_type` 过滤
GET	/api/system/Menu/SelectorFilter/{id}	implemented	menu.ts:52	面 B 已落地:同 Selector/{id}(本仓无「发布」概念,退化等价)
GET	/api/system/Menu/getSystemMenu	implemented	menu.ts:60	面 B 已落地:同 Selector/All
GET	/api/system/Menu/{id}/Actions/Export	implemented	menu.ts:38	面 B 已落地:**恒 `data:null`**(无导出文件服务);前端 `if (!res.data.url) return;` 静默跳过
GET	/api/system/Menu/getPermissionGroup/{id}	implemented	menu.ts:42	面 B 已落地:恒 `{list:[]}`(按钮/列/表单级权限不做,见已知限制 (ag))
GET	/api/system/Menu/getPermission/{id}/{permissionId}	implemented	menu.ts:46	面 B 已落地:恒 `{list:[]}`,同上
GET	/api/system/DictionaryType	implemented	dictionary.ts:8	面 B 已落地:ListVO;新表 `base_dictionary_type`(官方 DDL 逐字)
POST	/api/system/DictionaryType	implemented	dictionary.ts:16	面 B 已落地:`DICT_TYPE_WRITE_FIELDS` 白名单 + 名称非空
GET	/api/system/DictionaryType/{id}	implemented	dictionary.ts:28	面 B 已落地:字典分类详情
PUT	/api/system/DictionaryType/{id}	implemented	dictionary.ts:20	面 B 已落地:**只 SET body 里出现的键**
DELETE	/api/system/DictionaryType/{id}	implemented	dictionary.ts:32	面 B 已落地:软删本行;**不级联**字典数据
GET	/api/system/DictionaryType/Selector/{id}	implemented	dictionary.ts:12	面 B 已落地:ListVO 全量分类(本仓分类只有一层 ⇒ 忽略 id)
POST	/api/system/DictionaryData	implemented	dictionary.ts:50	面 B 已落地:`DICT_DATA_WRITE_FIELDS` 白名单 + 名称非空
GET	/api/system/DictionaryData/{id}	implemented	dictionary.ts:36	面 B 已落地:ListVO 按 `f_dictionary_type_id` 过滤
GET	/api/system/DictionaryData/{id}/Info	implemented	dictionary.ts:58	面 B 已落地:字典数据详情
PUT	/api/system/DictionaryData/{id}	implemented	dictionary.ts:54	面 B 已落地:**只 SET body 里出现的键**
DELETE	/api/system/DictionaryData/{id}	implemented	dictionary.ts:62	面 B 已落地:软删本行
GET	/api/system/DictionaryData/{id}/Data/Selector	implemented	dictionary.ts:44	面 B 已落地:按分类过滤的下拉
GET	/api/system/DictionaryData/{id}/Selector/{pid}	implemented	dictionary.ts:40	面 B 已落地:同分类下拉树(本仓字典数据无层级 ⇒ 平铺)
GET	/api/system/DictionaryData/{id}/Actions/Export	implemented	dictionary.ts:66	面 B 已落地:**恒 `data:null`**(无导出服务);前端 `if (!res.data.url) return;` 静默跳过
GET	/api/permission/Users/Selector	implemented	user.ts:13	面 B 已落地:用户选择器 ListVO;`keyword` 命中 `f_account`/`f_real_name`
POST	/api/permission/Users/getUserList	implemented	user.ts:49	面 B 已落地:body `{ids}` ⇒ `ANY(string_to_array(...))`
POST	/api/permission/Users/getSelectedList	implemented	user.ts:73	面 B 已落地:**刻意不复用** getUserList(委托会让契约扫描器推不出守卫)
POST	/api/permission/Users/getSelectedUserList	implemented	user.ts:77	面 B 已落地:组织维度已选用户,同 getSelectedList
GET	/api/permission/Users/ReceiveUserList	implemented	user.ts:89	面 B 已落地:交接接收人候选,同 Selector(**先自己判守卫再委托**)
GET	/api/permission/Users/getAllPermission	implemented	user.ts:109	面 B 已落地:点权限集合 = 可见菜单的 `f_en_code`(本仓只做菜单级,见限制 (ag))
GET	/api/permission/Users/Authorize	implemented	user.ts:113	面 B 已落地:同 getAllPermission(授权只到菜单级)
GET	/api/permission/Authority/{kind}/{objectId}	implemented	auth.ts:17	面 B 已落地:**恒 `{ids:[], all:false, list:[]}`**(本仓无 Portal/流程/打印模板三类对象)
POST	/api/permission/Authority/{kind}/{objectId}	implemented	auth.ts:21	面 B 已落地:恒成功(同上,无对象可授权)
GET	/api/permission/RoleRelation/roleList	implemented	roleRelation.ts:29	面 B 已落地:`base_role_relation` 只记用户↔角色 ⇒ `objectId` 当**用户 id** 用
POST	/api/permission/RoleRelation/addRoles	implemented	roleRelation.ts:21	面 B 已落地:body `{objectId, roleIds}`;幂等插(`ON CONFLICT DO NOTHING`)
POST	/api/permission/RoleRelation/deleteRoles	implemented	roleRelation.ts:25	面 B 已落地:body `{objectId, roleIds}` ⇒ 软删关系行
POST	/api/permission/RoleRelation/delete	implemented	roleRelation.ts:17	面 B 已落地:body `{objectId, ids}`,等价 deleteRoles
POST	/api/permission/UserRelation	implemented	userRelation.ts:13	面 B 已落地:body `{objectType, objectId, userIds}`,写 `base_user_relation`
POST	/api/permission/UserRelation/delete	implemented	userRelation.ts:17	面 B 已落地:软删关系行
GET	/api/permission/UserRelation/userList	implemented	userRelation.ts:9	面 B 已落地:`objectId` 下的用户 ListVO
GET	/api/permission/Role	implemented	RoleController.java:99-100	面 B 已落地:PageListVO 形状
GET	/api/permission/Role/{id}	implemented	role.ts:25	面 B 已落地:表单直接 `setFieldsValue(res.data)`
POST	/api/permission/Role	implemented	role.ts:17	面 B 已落地:`ROLE_WRITE_FIELDS` 白名单写库 + 名称非空校验,返 `{id}`
PUT	/api/permission/Role/{id}	implemented	role.ts:21	面 B 已落地:**只 SET body 里出现的键**
DELETE	/api/permission/Role/{id}	implemented	role.ts:29	面 B 已落地:软删本行;不级联解绑 `base_role_relation`
GET	/api/permission/Role/Selector	implemented	role.ts:13	面 B 已落地:ListVO;`type` 有值就按 `f_type` 过滤
POST	/api/permission/Role/RoleCondition	implemented	role.ts:33	面 B 已落地:body `{ids}`,`ANY(string_to_array(...))` 一次取回
GET	/api/permission/Organize/AsyncList/{id}	partial	OrganizeController.java:107-110	面 B 已落地:按父 id 逐层取,但**不分页**(pageSize = 本层条数)
GET	/api/permission/Organize	implemented	organize.ts:13	面 B 已落地:ListVO `{list}`(`organize/index.vue:280` 取 `res.data.list`);逐层树走 `AsyncList/{parentId}`
GET	/api/permission/Organize/{id}	implemented	organize.ts:25	面 B 已落地:`OrganizeForm.vue:103` 直接 `setFieldsValue(res.data)`
POST	/api/permission/Organize	implemented	organize.ts:17	面 B 已落地:白名单写库 + 名称非空;`f_organize_id_tree`/`f_org_name_tree` 按「父树+自己」拼
PUT	/api/permission/Organize/{id}	implemented	organize.ts:21	面 B 已落地:**只 SET body 里出现的键**
DELETE	/api/permission/Organize/{id}	implemented	organize.ts:29	面 B 已落地:软删本行;**不级联**子机构(已知限制)
GET	/api/permission/Organize/Selector	implemented	organize.ts:53	面 B 已落地:ListVO 全树(不做 parentId 剪枝 ⇒ 权限页选择器一次看到全树)
POST	/api/permission/Organize/SelectedList	absent	OrganizeController.java:341	机构已选列表未做
GET	/api/system/Menu/ModuleBySystem	implemented	ModuleController.java:121	面 B 已落地:ListVO 形状(不是裸数组)、节点 15 字段
GET	/api/system/Menu/{systemId}/TreeView	absent	ModuleController.java:332	管理端菜单树未做
GET	/api/system/Menu/Selector/{id}	implemented	menu.ts:15	面 B 已落地:上级菜单下拉,**排除自己及直接子级**(防树成环)
GET	/api/system/Menu/Selector/All	implemented	menu.ts:19	面 B 已落地:ListVO 当前系统全量菜单
POST	/api/system/Menu	implemented	menu.ts:22	面 B 已落地:`MENU_WRITE_FIELDS` 白名单 + 名称非空;`f_system_id` 不传就落当前 App-Code 解析出的系统
PUT	/api/system/Menu/{id}	implemented	menu.ts:26	面 B 已落地:**只 SET body 里出现的键**
GET	/api/system/Menu/{id}	implemented	menu.ts:31	面 B 已落地:菜单详情
DELETE	/api/system/Menu/{id}	implemented	menu.ts:35	面 B 已落地:软删本行;**不级联**子菜单(已知限制)
PUT	/api/system/Menu/{id}/Actions/State	absent	ModuleController.java:498-499	菜单启停未做
POST	/api/permission/Authority/Data/{objectId}/Values	partial	AuthorizeController.java:99-100	面 B 已落地:官方完整 body 真落库、读是 POST;但 list(权限树模型)返空数组
PUT	/api/permission/Authority/Data/{objectId}	partial	AuthorizeController.java:159-160	两面共用(按判别头分流);list(权限树模型)返空数组
GET	/api/permission/Authority/Model/{itemId}/{objectType}	absent	AuthorizeController.java:124-125	权限树模型读取未做
PUT	/api/permission/Authority/Model/{portalManageId}	absent	AuthorizeController.java:138-139	权限树模型保存未做
*	/api/system/ModuleDataAuthorizeLink/**	oos	authorize.ts:4	低代码数据权限方案(表/字段级)—— v1 明确不碰
GET	/api/permission/Users/Current/BaseInfo	implemented	userSetting.ts:13	个人资料:新表 `base_user_extra`(官方 `JNPF-PostgreSQL.sql:4637`,18 列逐字);`preferenceJson` 是**字符串**;`avatar` 与 `headIcon` 同值
PUT	/api/permission/Users/Current/BaseInfo	implemented	userSetting.ts:17	`SELF_WRITE_FIELDS` 白名单(**不含** account/organizeId/enabledMark)+ 只 SET body 里出现的键
PUT	/api/permission/Users/Current/Avatar	implemented	userSetting.ts:9	写 `base_user.f_head_icon`
PUT	/api/permission/Users/Current/SystemTheme	implemented	userSetting.ts:25	写 `base_user.f_theme`
PUT	/api/permission/Users/Current/SystemLanguage	implemented	userSetting.ts:29	写 `base_user.f_language`
POST	/api/permission/Users/Current/Actions/ModifyPassword	implemented	userSetting.ts:21	旧口令校验 + 新口令走官方 cipher;**不回显口令**
GET	/api/permission/Users/Current/Subordinate/{id}	implemented	userSetting.ts:33	查 `f_manager_id` 指向自己的下级
GET	/api/permission/Users/Current/SystemLog	implemented	userSetting.ts:37	本仓无登录日志表 ⇒ 恒空列表
GET	/api/permission/Users/Current/getUserOrganizes	implemented	userSetting.ts:41	`base_user_relation`(f_object_type='Organize')+ 祖先链
GET	/api/permission/Users/Current/getUserPositions	implemented	userSetting.ts:45	`f_position_id` 逗号串拆开 + 查 `base_position`
GET	/api/permission/Users/Current/getUserRoles	implemented	userSetting.ts:49	`f_role_id` 逗号串拆开 + 查 `base_role`
PUT	/api/permission/Users/Current/major	implemented	userSetting.ts:53	设默认岗位 / 切换身份 / 切换系统(`f_position_id`/`f_role_id`/`f_app_system_id`)
GET	/api/permission/Users/Current/SignImg	implemented	userSetting.ts:57	新表 `base_sign_img`(官方 `JNPF-PostgreSQL.sql:3937`,14 列逐字);`f_creator_user_id` 存**登录账号**
POST	/api/permission/Users/Current/SignImg	implemented	userSetting.ts:61	`signImg` 非空校验 + 默认签名落库
DELETE	/api/permission/Users/Current/{id}/SignImg	implemented	userSetting.ts:65	软删;**只能删自己的**(`f_creator_user_id` 匹配当前账号)
PUT	/api/permission/Users/Current/{id}/SignImg	implemented	userSetting.ts:69	设默认 ⇒ 同用户其余置 `f_is_default=0`
GET	/api/permission/Users/Current/getAppSecret	implemented	userSetting.ts:97	读 `base_user_extra.f_property_json`;没有 ⇒ 空串
PUT	/api/permission/Users/Current/saveAppSecret	implemented	userSetting.ts:101	重新生成 AppSecret 写回 `f_property_json`
GET	/api/permission/Users/Current/saasList	implemented	userSetting.ts:85	本仓单租户(§2.2 不做多租户)⇒ 恒空列表
GET	/api/permission/Users/Current/saasinfo	implemented	userSetting.ts:89	本仓单租户 ⇒ 恒空对象
GET	/api/permission/Users/Current/saasTenantName/{id}	implemented	userSetting.ts:93	本仓单租户 ⇒ 恒空串
POST	/api/permission/Users/Current/saasjoin	implemented	userSetting.ts:77	本仓单租户 ⇒ **明确失败**(不做静默假成功)
DELETE	/api/permission/Users/Current/{id}/saas	implemented	userSetting.ts:81	本仓单租户 ⇒ **明确失败**(同上)
GET	/api/permission/Standing	implemented	identity.ts:9	身份列表(PageListVO);新表 `base_standing`(官方 `JNPF-PostgreSQL.sql:4071`,15 列逐字);`isSystem` 归一化成 1/0
POST	/api/permission/Standing	implemented	identity.ts:13	`f_is_system` 默认写 **2**(自定义;官方 1=系统/2=自定义)+ 白名单写库 + 名称非空校验
GET	/api/permission/Standing/list	implemented	identity.ts:29	身份关联列表:`type=position` ⇒ 岗位,否则 ⇒ 角色;关系在 `base_authorize`(`f_item_type='standing'`)
GET	/api/permission/Standing/{id}	implemented	identity.ts:21	身份详情(`StandingInfoVO`)
PUT	/api/permission/Standing/{id}	implemented	identity.ts:17	**只 SET body 里出现的键**
DELETE	/api/permission/Standing/{id}	implemented	identity.ts:25	软删 + 同步软删 `base_authorize` 的关联行
POST	/api/permission/Standing/{id}/Actions/AddObject	implemented	identity.ts:33	body `{ids, type}` ⇒ 写 `base_authorize`(`f_item_type='standing'`);幂等
POST	/api/permission/Standing/{id}/Actions/DeleteObject	implemented	identity.ts:37	body `{ids, type}` ⇒ 关联行软删
GET	/api/permission/PermissionGroup	implemented	authGroup.ts:9	权限组列表(PageListVO);新表 `base_permission_group`(官方 `JNPF-PostgreSQL.sql:3278`,16 列逐字)
POST	/api/permission/PermissionGroup	implemented	authGroup.ts:25	`f_type` 默认 1(自定义)+ 白名单写库 + 名称非空校验
GET	/api/permission/PermissionGroup/{id}	implemented	authGroup.ts:13	权限组详情
PUT	/api/permission/PermissionGroup/{id}	implemented	authGroup.ts:21	**只 SET body 里出现的键**
DELETE	/api/permission/PermissionGroup/{id}	implemented	authGroup.ts:17	软删 + 同步软删该组的 `base_authorize` 行
POST	/api/permission/PermissionGroup/{id}/Actions/Copy	implemented	authGroup.ts:29	`fullName` 加 `.副本<5 位>`、`enCode` 加同 5 位、**清空** `f_permission_member`、复制授权关系
GET	/api/permission/PermissionGroup/PermissionMember/{id}	implemented	authGroup.ts:33	成员列表(ListVO);`f_permission_member` 是**逗号分隔 id 串**
POST	/api/permission/PermissionGroup/PermissionMember/{id}	implemented	authGroup.ts:37	body `{ids}` ⇒ 逗号串写回 `f_permission_member`
GET	/api/permission/Action	implemented	action.ts:9	动作列表(PageListVO);新表 `base_action`(官方 `JNPF-PostgreSQL.sql:1`,15 列逐字);`type` 1=自定义/其它=系统
POST	/api/permission/Action	implemented	action.ts:13	`f_type` 强制 1(自定义,官方 `insertOrUpdate`);🔴 `f_enabled_mark` 是 **VARCHAR(11)**(官方陷阱)
GET	/api/permission/Action/{id}	implemented	action.ts:21	动作详情
PUT	/api/permission/Action/{id}	implemented	action.ts:17	**只 SET body 里出现的键**;`f_enabled_mark` 不加 CAST(VARCHAR)
DELETE	/api/permission/Action/{id}	implemented	action.ts:25	软删

[RULER]
# name	期望断言数(尺子**自己**断言的条数;跑出来的条数对不上 ⇒ 失败)
# 43 = react 版对齐的 32 条 + 真实业务模块 asset/DataResource 9 条 + 多应用 2 条
#      (无 App-Code ⇒ 主系统 / App-Code: app-b ⇒ app-b)
perm-smoke.sh	43
# 23 = 原 18 条 + 多应用 1 条(App-Code: app-b ⇒ currentSystemId = app-b,与面 A 同一口径)
#      + 用户 CRUD 4 条(详情无口令 / 改档只 SET 出现的键 / 批量启停 + 软删)
perm-smoke-jnpf.sh	23
# 🔴 本仓是**后端-only**(CLAUDE.md §2.2:前端/移动端本期不动,沿用 Java 版)⇒
#    check-module 的「前端接触点」(4 模块 × 4 处 + 全局面 A 判别头)按 N/A 打 `⏭`
#    且**仍计入条数**;114 = 4 模块 × 28 条 + 全局面 B 判别头 1 条 + 全局面 A 判别头 1 条。
#    (脚手架原版口径 93 = 3 模块含真实前端的条数,本仓无 src/frontend,不适用。)
check-module.sh	114
check-boundary.sh	11
check-contract.sh	10
check-citations.sh	4