Files
tdc-rs/HOWTO_ENTITY.md
adminandClaude Code 2e7f9b1975 feat(b5): 工程化外壳(文档层)—— 契约四件套 + 两本手册 + 第四把尺子
把 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]>
2026-10-27 00:56:09 +08:00

368 lines
15 KiB
Markdown
Raw Permalink 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.
# 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` 当模板,它最简):
```rust
//! `<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`)
如果新实体的详情要带子表:
```rust
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 行)
```rust
// ① 模块声明(按字母序插在正确位置)
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_<名字> (...)`:
```sql
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
bash scripts/reset-data.sh # 走访达回收站,可恢复
PORT=30000 ./target/debug/tdc-connector
```
### 2.6 可选:服务端生成编码 / 默认值
若上游在 `beforeSave` 里生成编码或补默认值(照抄上游 `beforeSave`):
```rust
// 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`
```bash
# 追加到 scripts/upstream-json-ignore.tsv(制表符分隔)
printf '<你的实体>\t<驼峰键>\n' >> scripts/upstream-json-ignore.tsv
```
🔴 尺子 E4 断言**上游清单 ⊆ 本仓 `hidden_fields`** ⇒ 漏一条 = **泄密**(尺子会红)。
---
## 3. 试跑(照着加一个)
完整的「加一个试跑」演练 —— 用 `PolicyTemplate` 当例子(18 个实体里最简的一个):
### 3.1 改前基线
```bash
cargo build && bash scripts/check-entity.sh # ⇒ PASS=13 FAIL=0
```
### 3.2 加
1. `src/tdc/entity/policy_template.rs` —— 抄 §2.1 的模板。
2. `src/tdc/entity/mod.rs` —— 加 `pub mod policy_template;` + `ALL_SPECS` 加 `policy_template::SPEC,`。
3. `schema/migrate.sql` —— 加 `CREATE TABLE public.tdc_policy_template (...)`。
### 3.3 跑
```bash
cargo build # 编译
bash scripts/check-entity.sh # E1 表在不在 / E2 路径对不对 / E7 键闭合
bash scripts/check-boundary.sh # 引擎仍然零 match api_name
cargo test # 全绿
```
### 3.4 起服务真打一遍
```bash
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
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` 的端点表是**脚本生成 + 脚本对账**的 ⇒ 加实体后必须重生成:
```bash
# ① 生成新表(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/` |