把 v3 spec §11.2 要求的整套文档层补齐,并把 spec §11.1 欠下的
「浏览器验收重跑」在真实上游 SPA 上补做完(内核浏览器 aix 驱动)。
新增文档:
- `docs/contract.md`(重写):**132 端点全表** + 4 种响应形状 + 数据模型 + 时间口径,
唯一真源。端点表由 `scripts/check-contract.sh` 与源码注册路由**逐条对账**。
- `docs/decisions.md`(重写):逐条裁决 D1–D21。
- `docs/known-limitations.md`(重写):L1–L7,含 §5.4 权限敞开的显式条目(L4)。
- `docs/runbook.md`(新):怎么起 / 怎么冒烟 / 常见故障。
- `MIGRATION.md`(新):Java TDC ⇄ Rust 逐件翻译表 + 口令换算 + 数据 ETL。
- `HOWTO_ENTITY.md`(新):加一个实体(含子表挂载面)。
- `docs/ACCOUNT-LAYER.md`(新):`base_user` 账号层(官方双 md5 公式)。
- `docs/CONSOLE-ACCEPTANCE.md`(重写):**B5 重跑版**浏览器验收。
新增尺子(第四把 + 两把专项):
- `scripts/check-contract.sh`:端点表 vs 实际注册路由对账(132 == 132)。
- `scripts/check-citations.py`:文档里 `文件:行号` 引用逐条校验(139 条 0 失效)。
- `scripts/upstream-action-census.py`:上游动作端点普查(只读上游克隆,可复算)。
- `scripts/contract_probe.py`:动作端点形状探针(109 条逐条打过,零偏差)。
影响:
- **L5 数字纠正**:原先记的「111 条上游动作端点未实现」口径错了
(`grep -rhoE` 只抓带参数的映射、且跨了全部 31 个控制器)
⇒ 真实数字 **109**(122 声明 − 11 CRUD 基线 − 2 聚合详情 = 26 形态 A + 83 形态 B)。
- **L7(新增)**:**26 条**上游动作端点**不会 404** ⇒ 被通用详情路由 `/{Entity}/{id}`
吞掉(`src/tdc/controller/crud.rs:65-93`)⇒ GET 返回 **200 + `code:400`**、
POST 返回 **405** ⇒ 上游前端下拉框静默变空。**只判 HTTP 状态码会误判成成功**。
- **CONSOLE-ACCEPTANCE §4 纠正**:服务目录 / 我的账单**已实现**(P4),
失败点在**连接器身份闸门**(`f_tds_space_id` / `f_tds_connector_id` 为空 ⇒ 出向前 fail-closed),
**不是** TDS NOOP 降级、也不是代理 404。
- `CLAUDE.md` 同步:目录树、红线、坑位表(「上游动作端点不 404」新增一行)。
实测:cargo test **246** 项全绿 0 failed(1 ignored)· smoke.sh PASS=80 FAIL=0 ·
check-boundary.sh exit 0 · check-entity.sh PASS=13 FAIL=0 ·
check-contract.sh 132 条端点一致 · check-citations.py 139 条引用 0 失效 ⇒ **六把尺子全绿**。
⚠️ 口径更正:此前(B4 提交信息与记忆文件)记的「172 lib + 62 集成 = 236」是**误数**
—— `src/` 与 `tests/` 自 B4 起未变,逐二进制实测就是 246 ⇒ 从本批起统一用 246。
Co-Authored-By: Claude Code <[email protected]>
15 KiB
HOWTO_ENTITY —— 加一个实体
🔴 本手册只讲一件事:怎么加一个新的可 CRUD 实体。 加实体的全部改动落在 4 个文件里,通用 CRUD 引擎一行都不用碰。
目标读者:要给
tdc-rs加一个新表 / 一组新端点的人。
一句话版本:
新建 src/tdc/entity/<名字>.rs → 在 src/tdc/entity/mod.rs 加 2 行 → (新表则)schema/migrate.sql 加 DDL
→ 重生成 docs/contract.md 的端点表 → 跑五把尺子
0. 前置:确认这个实体该加在这儿
本仓的 CRUD 引擎是声明式的:实体 = 一张表 + 一组元数据。 先确认你要做的不是下面这几类(它们不走本手册):
| 你要做的事 | 该去哪 |
|---|---|
| 隐私计算 / Nax / Sandbox 作业 | ❌ 不做(依赖 Nax 引擎 + scard 安全平面,见 CLAUDE.md §明确不在范围) |
| 策略校验 / 策略执行 | ❌ 同上 |
| 交付执行 / 调度 / 心跳 | ❌ 同上 |
| 菜单 / 角色 / 授权 | ❌ 不引入 j7 菜单模型(docs/known-limitations.md L2) |
| 出向 TDS 的新接口 | 改 src/tdc/client/tds.rs(不是 CRUD 引擎) |
| 账号 / 权限管理 | 改 src/tdc/service/account.rs(不是 CRUD 引擎) |
| 一张新的业务表,要在本仓自己的控制台里增删改查 | ✅ 本手册 |
1. 改动清单(4 个文件)
| # | 文件 | 改什么 | 必改? |
|---|---|---|---|
| ① | src/tdc/entity/<名字>.rs |
新建:一个 pub const SPEC: TableSpec |
✅ |
| ② | src/tdc/entity/mod.rs |
pub mod <名字>; + ALL_SPECS 里加一行 |
✅ |
| ③ | schema/migrate.sql |
新表的 DDL(复用已有表则不用) | 视情况 |
| ④ | docs/contract.md |
端点表重生成(自动,见 §5) | ✅ |
外加两个可选:
| 文件 | 什么时候 | 怎么改 |
|---|---|---|
src/tdc/entity/mod.rs 的 create_codes |
新增时要服务端生成编码(如 PRO20260127xxxx) |
加一个 "<Entity>" => &[CodeSpec{…}] 分支 |
src/tdc/entity/mod.rs 的 create_defaults / create_now_columns |
新增时要服务端补默认值 | 同上,加一个分支 |
scripts/upstream-json-ignore.tsv |
上游实体标了 @JsonIgnore |
加一行 <实体>\t<驼峰键> |
🔴 不改这些(引擎不许出现实体名):
src/tdc/service/crud.rs(CRUD 引擎)· src/tdc/mapper.rs(SQL 拼装)·
src/tdc/controller/crud.rs(路由装配)—— 它们遍历 ALL_SPECS,新实体自动生效。
2. 步骤
2.1 照抄一个最简的模板
新文件 src/tdc/entity/<名字>.rs(用 policy_template 当模板,它最简):
//! `<Entity>` 的实体元数据(对位上游 `ssw.tdc.entity.<Entity>Entity`)。
//!
//! <一句话说明与上游的差异,没有就写「与上游逐字一致」>
//!
//! 本文件只放**这一个**实体的 spec —— 通用元数据结构见 [`super::TableSpec`]。
use super::TableSpec;
/// 本实体的完整元数据(注册表唯一真源)。
pub const SPEC: TableSpec = TableSpec {
api_name: "PolicyTemplate",
path: "/api/ssw/tdc/PolicyTemplate",
table: "tdc_policy_template",
// 关键字模糊匹配列(多列 OR)。🔴 列**必须真实存在**(查 `migrate.sql`)。
keyword_columns: &["f_name"],
// 精确过滤:`(请求参数名, DB 列名)`。请求参数名是 camelCase。
filter_columns: &[("status", "f_status")],
// 租户列;`Some` 时客户端传 `tenantId` 一律拒(对齐上游 `tenantColumn()`)。
tenant_column: Some("f_tenant_id"),
// 默认排序列(**倒序**)。
default_order_column: "f_creator_time",
// 附加固定谓词(与 `ALIVE` AND 起来);没有就 `None`。
extra_where: None,
// 三个「禁改写」拒因;`None` = 允许。上游只读视图才禁。
no_create: None,
no_update: None,
no_delete: None,
// 不可经编辑入口改写的列(服务端权威列)。
frozen_columns: &[],
// **不外泄字段**(上游 `@JsonIgnore`)—— 键是 camelCase JSON 键。
hidden_fields: &[],
// 子表挂载声明;没有子表就 `&[]`。
child_tables: &[],
// 「查无此条」文案(上游逐字)。
not_found_msg: "记录不存在或已删除",
// 是否注册只读聚合体路由 `GET {path}/{id}/Detail`。
aggregate_detail: false,
};
2.2 字段怎么填(逐条对着上游抄)
| 字段 | 上游对应 | 本仓怎么写 |
|---|---|---|
api_name |
控制器的实体名 | 原样(如 PolicyTemplate) |
path |
@RequestMapping 的值 |
必须 = /api/ssw/tdc/<api_name>(尺子 E2 会断言) |
table |
实体上的 @TableName |
如 tdc_policy_template;🔴 必须是 migrate.sql 里已存在的表(E1) |
keyword_columns |
控制器 keywordColumns() |
逐字抄;🔴 列必须真实存在(上游 ApiConsumeLog 抄漏过一列 ⇒ 一搜就 42703) |
filter_columns |
控制器 filterColumns() |
逐字抄;键是请求参数名(camelCase),值是列名(f_ 前缀) |
tenant_column |
控制器 tenantColumn() |
逐字抄(Identity 是 None) |
default_order_column |
控制器 defaultOrderColumn() |
逐字抄 |
extra_where |
控制器里的固定谓词 | 照抄(如 Dataset 的 DATASET_EXTRA_WHERE) |
no_create / no_update / no_delete |
上游的只读视图 | 写上游的原话;允许写就 None |
frozen_columns |
控制器 changedAuthorityColumn() |
逐字抄(列名 + 中文标签) |
hidden_fields |
实体上的 @JsonIgnore |
camelCase JSON 键;🔴 尺子 E4 断言上游清单 ⊆ 本仓 |
child_tables |
服务的 withChildren() |
见 §2.3 |
not_found_msg |
控制器「查无此条」文案 | 上游逐字 |
aggregate_detail |
控制器有 GET /{id}/Detail |
true / false |
2.3 子表挂载(child_tables)
如果新实体的详情要带子表:
use super::{ChildMount, ChildTable, TableSpec};
child_tables: &[
ChildTable {
key: "fieldRules", // 输出 JSON 键(上游实体属性名)
table: "tdc_resource_field", // 子表名
fk_column: "f_resource_id", // 子表侧外键列
parent_column: "f_id", // 父行取值列
order_column: "f_sort_code", // 子表侧排序列
alive: None, // 存活谓词;该子表无逻辑删除列 ⇒ None
mounts: &[ChildMount::Aggregate],
},
],
mounts 三个值对应三个挂载面(上游逐父子不同,别猜):
ChildMount |
挂在哪 | 上游对照 |
|---|---|---|
Aggregate |
GET {path}/{id}/Detail |
ResourceController#detailOf |
Detail |
GET {path}/{id} |
DataInterfaceController#detail |
List |
列表响应(分页 + 全量) | DeliveryTaskController#decorate |
🔴 aggregate_detail: true 必须配至少一个 Aggregate 面的子表
(单测 aggregate_detail_is_pinned_to_the_resource_side 会断言)——
否则聚合体和普通详情没区别 ⇒ 白开一条路由。
2.4 在 mod.rs 注册(2 行)
// ① 模块声明(按字母序插在正确位置)
pub mod policy_template; // ← 已有;你的加在正确字母位
// ② ALL_SPECS 里加一行(按 api_name 字母序)
pub static ALL_SPECS: &[TableSpec] = &[
// …
policy_template::SPEC,
<你的>::SPEC, // ← 加这一行
// …
];
2.5 加表(schema/migrate.sql)
如果新实体复用已有表(像 Dataset 复用 tdc_resource)⇒ 跳过本步。
否则在 schema/migrate.sql 里加 CREATE TABLE public.tdc_<名字> (...):
CREATE TABLE public.tdc_<名字> (
f_id character varying(50) NOT NULL,
f_tenant_id character varying(50) DEFAULT '0'::character varying,
f_sort_code integer DEFAULT 0,
f_name character varying(255),
f_status character varying(50),
f_delete_mark integer DEFAULT 0,
f_creator_time timestamp without time zone DEFAULT now(),
f_creator_id character varying(50),
f_last_modify_time timestamp without time zone DEFAULT now(),
f_last_modify_id character varying(50)
);
🔴 必须带的列(引擎硬依赖):
| 列 | 少了会怎样 |
|---|---|
f_id |
主键;缺 ⇒ 插入直接报错 |
f_delete_mark |
存活谓词 (f_delete_mark IS NULL OR f_delete_mark = 0);缺 ⇒ 列表 500 |
f_creator_time |
默认排序列;缺 ⇒ 列表 500 |
f_tenant_id |
租户过滤列(若 tenant_column: Some(...)) |
🔴 改完 migrate.sql 必须清数据重建(探针只在首次建表时跑):
bash scripts/reset-data.sh # 走访达回收站,可恢复
PORT=30000 ./target/debug/tdc-connector
2.6 可选:服务端生成编码 / 默认值
若上游在 beforeSave 里生成编码或补默认值(照抄上游 beforeSave):
// src/tdc/entity/mod.rs
pub fn create_codes(api_name: &str) -> &'static [CodeSpec] {
match api_name {
// …已有的…
"<你的>" => &[CodeSpec {
key: "<驼峰键>", // 如 "xxxCode"
prefix: "XXX", // 🔴 尺子 E5:前缀不能和别的实体重复
style: CodeStyle::DaySeqTail8,
retries: 5,
fail_msg: "…生成失败(连续 5 次撞库),请重试",
baseline_alive: false,
}],
_ => &[],
}
}
同理还有 create_defaults((驼峰键, 常量文本),支持 {id} 占位)和
create_now_columns(要补 now() 的列)。
🔴 这三个函数在 entity/mod.rs 里,是业务层的 match api_name ——
允许(红线的「零 match api_name」只针对引擎:service/crud.rs / mapper.rs / controller/crud.rs)。
2.7 可选:上游 @JsonIgnore
# 追加到 scripts/upstream-json-ignore.tsv(制表符分隔)
printf '<你的实体>\t<驼峰键>\n' >> scripts/upstream-json-ignore.tsv
🔴 尺子 E4 断言上游清单 ⊆ 本仓 hidden_fields ⇒ 漏一条 = 泄密(尺子会红)。
3. 试跑(照着加一个)
完整的「加一个试跑」演练 —— 用 PolicyTemplate 当例子(18 个实体里最简的一个):
3.1 改前基线
cargo build && bash scripts/check-entity.sh # ⇒ PASS=13 FAIL=0
3.2 加
src/tdc/entity/policy_template.rs—— 抄 §2.1 的模板。src/tdc/entity/mod.rs—— 加pub mod policy_template;+ALL_SPECS加policy_template::SPEC,。schema/migrate.sql—— 加CREATE TABLE public.tdc_policy_template (...)。
3.3 跑
cargo build # 编译
bash scripts/check-entity.sh # E1 表在不在 / E2 路径对不对 / E7 键闭合
bash scripts/check-boundary.sh # 引擎仍然零 match api_name
cargo test # 全绿
3.4 起服务真打一遍
bash scripts/reset-data.sh # 让新表建出来
PORT=30000 ./target/debug/tdc-connector &
sleep 5
TOKEN="ssw-internal-token-e2e"
# 列表
curl -s --noproxy '*' -H "X-Internal-Token: ${TOKEN}" \
http://127.0.0.1:30000/api/ssw/tdc/PolicyTemplate
# 新增
curl -s --noproxy '*' -H "X-Internal-Token: ${TOKEN}" -H 'Content-Type: application/json' \
-d '{"name":"试跑实体","status":"ENABLED"}' \
http://127.0.0.1:30000/api/ssw/tdc/PolicyTemplate
# 详情 / 修改 / 删除
curl -s --noproxy '*' -H "X-Internal-Token: ${TOKEN}" \
http://127.0.0.1:30000/api/ssw/tdc/PolicyTemplate/<上面返回的 id>
3.5 收尾
bash scripts/smoke.sh # PASS=80 FAIL=0
bash scripts/check-contract.sh # 端点表要对账(见 §5)
4. 常见坑
| 症状 | 根因 | 处理 |
|---|---|---|
列表 500,日志 42703 column … does not exist |
keyword_columns / filter_columns 里的列表里没有 |
逐字核对 migrate.sql 的列名 |
列表 500,column f_delete_mark does not exist |
新表漏了 f_delete_mark |
补 DDL + reset-data.sh |
| 新表根本没建 | 探针只看「public schema 有没有表」⇒ 有表就跳过整个迁移 | bash scripts/reset-data.sh 后重起 |
| 尺子 E2 红 | path ≠ /api/ssw/tdc/<api_name> |
改 path |
| 尺子 E1 红 | table 不在 migrate.sql |
补 DDL |
| 尺子 E4 红 | 上游 @JsonIgnore 字段没进 hidden_fields |
补进 spec + scripts/upstream-json-ignore.tsv |
| 尺子 E5 红 | 编码前缀和别的实体重复 | 换前缀 |
| 尺子 E7 红 | 列名 ↔ camelCase 不闭合(如 f_url → url → f_url ✅;f_2d_code → 2dCode → f_2_d_code ❌) |
换列名,或在 src/platform/db.rs 的映射里补特例 |
| 405 / 端点数对不上 | docs/contract.md 的端点表没重生成 |
见 §5 |
| 详情报「记录不存在或已删除」 | not_found_msg 抄错 / id 取值列不对 |
抄上游原话 |
新增返回 500(null value in column … violates not-null constraint) |
该列 NOT NULL 且无 DEFAULT,客户端又不送 | 要么加 create_codes / create_defaults,要么改 DDL 给 DEFAULT |
5. 端点表必须重生成(docs/contract.md)
docs/contract.md 的端点表是脚本生成 + 脚本对账的 ⇒ 加实体后必须重生成:
# ① 生成新表(Markdown 行)
python3 scripts/contract_probe.py --gen
# ② 把输出贴进 docs/contract.md 的
# <!-- BEGIN ENDPOINTS --> … <!-- END ENDPOINTS --> 之间
# (保留表头那一行:| 方法 | 路径 | 说明 |)
# ③ 对账(真起一个进程,逐条打)
bash scripts/check-contract.sh
# ⇒ ✅ 端点表与实际注册路由完全一致(N 条端点)
🔴 加一个实体 ⇒ 端点数 +6(列表 / All / 详情 / 新增 / 修改 / 删除);
再开 aggregate_detail ⇒ +1(/Detail)。
6. 做完之后
| 动作 | 为什么 |
|---|---|
cargo test |
注册表自检 + 引擎回归 |
bash scripts/check-entity.sh |
E1–E7 七项 |
bash scripts/check-boundary.sh |
引擎仍然零 match api_name(红线) |
bash scripts/smoke.sh |
HTTP 契约 |
bash scripts/check-contract.sh |
端点表 ↔ 实际路由 |
更新 docs/contract.md 的数据模型段 |
表数量变了 |
更新 CLAUDE.md 的实体清单 |
18 → 19 |
更新 MIGRATION.md §1.2 的逐件翻译表 |
加一行对照上游 |
记一条 docs/decisions.md |
如果与上游有偏差 |
7. 相关文档
| 想知道的 | 去哪 |
|---|---|
TableSpec 每个字段的完整语义 |
src/tdc/entity/mod.rs:96(结构定义 + 注释) |
ChildMount 三个挂载面 |
src/tdc/entity/mod.rs:51 |
| 引擎怎么用 spec | src/tdc/service/crud.rs |
| 路由怎么自动注册 | src/tdc/controller/crud.rs:27(遍历 ALL_SPECS) |
| SQL 怎么拼 | src/tdc/mapper.rs |
| 对外契约(端点 / 形状 / 命名) | docs/contract.md |
| 踩坑历史 | CLAUDE.md §已知踩坑清单 |
| 上游真源(只读) | /tmp/sswtdc-probe/boot/ssw-tdc/ssw-tdc-entity/src/main/java/ssw/tdc/entity/ |