Files
tdc-rs/CLAUDE.md
T
admin 43dcd3f9eb chore(p4): 收拢库操作到唯一出口,为统一 sspf Db.lock 做准备
- 新增 platform::db::exec_params,收拢业务层 12 处裸 state.db.query
- 新增 check-db-access.sh 护栏:白名单 3 文件,7 处命中 0 越界
- 平台侧需求写入 ssw-platform/docs/SSPF-BUSINESS-DB-ACCESS.md(目标 v0.5.0)
- Cargo.toml 仍锁 v0.3.0,132 端点契约与响应形状未变
2026-11-04 22:20:55 +08:00

609 lines
56 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AGENTS.md
This file provides guidance to AI coding agents (CodeBuddy / Claude Code / Cursor / Codex 等) when working in this repository.
> ⚠️ **本文件是项目级 agent 指引**,内容必须与代码**同步**。改代码后回头核对本文件是否还成立。
## 项目定位
**TDC 连接器(tdc-rs)** —— 尚数网可信数据空间中「数据接入连接器(TDC)」子系统的**本地优先 Rust 重实现**。
上游真源:**最新版**在 `http://192.168.1.2:8080/ssw/trusted-space/ssw-tdc`(只读克隆在 `/tmp/sswtdc-probe`);
更早的 `~/Desktop/workspace/ssw-mvp/boot/ssw-tdc`(Spring Boot 3 + JNPF 7.0 + Java 21)仍在,但**已过时**。
本仓库把上游的**数据生命周期 + 控制台**重做成 **单二进制、零外部服务**的形态:
| 层 | 技术栈 | 职责 |
|---|---|---|
| 平台底座 | **`sspf` v0.3.0**(`ssw-platform` 发布的标准平台包,git tag 锁版本) | **单进程 / 单库 / 单端口**:开唯一的 PGlite 实例、建平台 `base_*` 表、提供面 B(JNPF 兼容)全套端点。`Cargo.toml` 里只认这一个依赖 |
| 后端 | Rust 2021 + axum 0.8 + tokio(**业务层**) | 鉴权 / 会话 / 18 实体 CRUD / 聚合详情 / 账号层 / 静态托管;由 `sspf::Platform` **两阶段装配**(`assemble()` → 引导业务状态 → `finish()`) |
| 数据库 | `pglite-rs` 0.2(进程内原生 PostgreSQL,**平台与业务共用同一个实例**) | 平台 `base_*` 表(百余张)+ `tdc_*` 业务表(**30 张**);`migrate.sql` 声明的 3 张账号层表由平台代建,数据落盘 `data/tdc.pg/` |
| 前端 | **上游(Java/Vue)完整前端的构建产物**,托管在 `static/` | **零自研前端、零构建步骤**(`scripts/build-frontend.sh` 可重放) |
| 账号层 | **数据库表 `base_user`**(B4 起) | 顶替上游的 JNPF j7 账号库(上游完整前端的 JNPF 兼容登录);口令按**官方双 md5 公式**入库 |
> **P2 装配要点**:业务 Router 自带 `TdcState`,平台 Router 自带 `sspf::AppState` —— axum `merge` 要求状态同型,
> 且两套路由有 6 条 path 完全撞车(`/api/health`、`/api/oauth/Login`、`/api/permission/Users` …)。
> ⇒ 用 **`fallback_service` 嵌套**(业务优先 + 平台兜底),**不是 `merge`**:业务侧胜出冲突路径,
> 面 B 其余端点同端口可达。共库后 `pglite-rs` 每进程只允许一个实例 ⇒ 业务仓绝不能另开 `PGlite::open()`。
> **P3 会话桥(兼容 JNPF 的最后一块)**:两套会话表原本互不相识 —— tdc 用 32 位 hex / 30 分钟 TTL,
> 面 B 用 `lite-*` / 进程内不过期;而 `/api/oauth/Login` 被业务侧接管 ⇒ 平台登录 handler 永不执行
> ⇒ 拿 tdc token 打 `/api/oauth/CurrentUser` 实测恒返 **602**(面 A 600)。
> 解法全在业务侧:登录成功时 `tdc::session_bridge::mirror_login` 往平台会话表镜像一条,
> 把平台 token 挂在 **tdc 会话行**上;平台 Router 上单独挂一层翻译中间件,把 `Authorization`
> 换成平台 token。🔴 翻译层**只挂平台 Router**,`Finish.layers` 是全局层会把业务侧的头也改掉 ⇒ 401。
> 映射随 tdc 会话过期 / 吊销一起消失 ⇒ 面 B 不会比业务侧晚失效;对外 `data.token` 仍是 32 位 hex。
> **P4 待办:库操作统一走 sspf 的 `Db`(等平台 `v0.5.0`)**:`Db::pg()` 把同一个
> `Arc<PGlite>` 交给业务仓,但没把 `Db.lock` 交出来 ⇒ 平台侧 SQL 持 `Db.lock`、
> 业务侧 SQL 持 tdc 自己的 `db_lock`,两把锁互不覆盖,并发写同库可能交错。
> 🔴 **不能直接换 `sspf::Db::query_json`**:它会多做一层 `f_`→camelCase 归一和别名还原,
> 而业务仓的归一在上层 mapper ⇒ 换过去会改掉 132 条端点的响应形状。
> 平台需求见 `ssw-platform/docs/SSPF-BUSINESS-DB-ACCESS.md`(要「持同一把锁、不碰归一」
> 的 Raw API)。本轮已把散在 `service/{crud,account,identity}.rs` 的 **12 处**裸
> `state.db.query(...)` 收进 `platform::db::exec_params`,并用 `check-db-access.sh` 钉死
> ⇒ tag 到位后**只改 `platform/db.rs` 的 6 个函数**,业务层零改动。
> **pglite-rs ≠ 浏览器 PGlite**。crate 名 `pglite-rs`、import 名 `pglite`;它把 postgres-pglite 编译成原生静态库链接进二进制,
> 是**真实 PostgreSQL 语义**(类型 / MVCC / 事务 / 扩展 / 线协议),进程内单 backend,**无服务器、无 Docker、无 WASM**。
> 浏览器端 WASM 版(`@electric-sql/pglite` + IndexedDB)曾是本项目的错误实现,已废弃删除,勿再引入。
## 顶层目录速览
```
tdc-rs/
├── Cargo.toml # 依赖(含 sspf git tag)+ release 优化(lto=thin / strip / unwind)
├── Cargo.lock # 锁定版本
├── rust-toolchain.toml # 锁 rustc 1.95.0(与 sspf 平台包同版本,L3 dylib ABI 前提)
├── src/
│ ├── main.rs # 启动装配:sspf::Platform::assemble() 开唯一库 / on_ready 补建 tdc 表 / 引导身份与账号层 / finish() 嵌套路由
│ ├── lib.rs # 模块声明(只暴露 `platform` 与 `tdc` 两层,bin 只做装配)
│ ├── platform/ # 【平台层】与业务**零**知识(边界由 check-boundary.sh 静态钉住)
│ │ ├── state.rs # AppState(config + db + db_lock + sessions)—— **零业务字段**(业务态在 `tdc/state.rs`)
│ │ ├── config.rs # **平台**环境变量配置(端口/数据目录/令牌/出向地址)+ 密钥守卫(**零业务字段**)
│ │ ├── db.rs # PGlite 封装(**库操作唯一出口**:query_json / exec_params / query_scalar_text / column_types / ensure_schema)
│ │ ├── session.rs # 会话存储(两种 kind:Identity / Account;Account 行携带镜像的平台 token)
│ │ ├── envelope.rs # 业务信封 ActionResult(HTTP 200 + {code,msg,data})
│ │ ├── auth.rs # 入向鉴权中间件 + 三道门 + 主体(Principal)
│ │ ├── cipher.rs # 登录口令加解密(MD5 + AES-256-ECB,对齐上游 cipher.ts)
│ │ ├── guard.rs # 生产档弱密钥判据(**纯函数**,照抄上游 ssw.common.guard.ProdGuard)
│ │ ├── compare.rs # 常量时间比较(**全仓唯一一份实现**,业务侧 pub use 复用)
│ │ ├── ids.rs # id 生成
│ │ ├── protocol.rs # 协议版本闸门
│ │ ├── body.rs # 宽松 JSON 体
│ │ ├── mw.rs # 405 JSON 改写中间件
│ │ └── fallback.rs # 404 JSON + SPA 静态兜底 + DDL 两层守卫
│ └── tdc/ # 【业务层】对位上游 `ssw.tdc.*` 包族
│ ├── entity/ # 18 个实体各一文件 + mod.rs(ALL_SPECS / validate / 子表挂载声明)
│ ├── mapper.rs # SQL 组装与执行、投影与序列化(引擎的机械活,**实体无关**)
│ ├── service/ # 业务规则:crud(写路径分档)/ account(**base_user 账号层**)/ identity(身份域)
│ ├── schema.rs # 共库建表:跳过平台同源 base_* 语句、只补 tdc 表;`baseTables` 声明清单
│ ├── session_bridge.rs # P3 会话桥:登录镜像平台会话 + 只作用于面 B 的 Authorization 翻译层
│ ├── controller/ # HTTP 端点:crud / health / auth / account / tds_biz
│ ├── client/tds.rs # TDS 出向客户端(照抄上游 TdsReportClient 的 internal 通道,9 个方法)
│ ├── util/code.rs # 业务编码生成器(原 src/codec.rs:PRO/RES/API/DS 前缀 + 两套上游生成器)
│ ├── config.rs # **业务**配置 TdcConfig(身份码/身份名/身份密钥/引导管理员账号口令)
│ ├── constant.rs # **业务**常量(身份码/身份名默认值 + 业务 env 名清单)
│ ├── state.rs # **业务**态 TdcState(platform + 业务配置 + 引导身份 + TDS 客户端 + 平台会话表 Arc)
│ ├── support/ # 业务侧公共清单(public_paths:免鉴权端点)
│ └── policy/ engine/ schedule/ notify/ heartbeat/ sso/ # 上游同名包占位(后续批)
├── static/ # 上游 SPA 构建产物(index.html + logo.png + assets/,8 个产物文件)
├── schema/
│ └── migrate.sql # tdc_* + base_* schema(include_str! 内嵌进二进制,**30 + 3 表**,**不在 web root**)
├── scripts/ # build-frontend.sh / gen-migrate.sh / reset-data.sh / reap-ipc-leaks.sh
│ # + **五把尺子**:smoke.sh(HTTP 契约)/ check-boundary.sh(边界静态)
│ # / check-entity.sh(实体静态)/ check-contract.sh(契约对账)
│ # / check-upstream-tests.sh(**上游测试用例移植台账**对账)
│ # + check-dual-contract.sh(**P2 附加尺子**:双契约 + P3 会话桥,真进程,17 断言)
│ # + check-db-access.sh(**P4 附加静态尺子**:库操作单一出口,0 处越界)
│ # + contract_probe.py(check-contract 的探针)/ check-citations.py(文档引用自检)
│ # + upstream-action-census.py(上游动作端点普查 · 只读上游克隆)
│ # + upstream-test-census.py(**上游测试类普查**)/ upstream-test-ledger.tsv(台账真源)
│ # + boundary-ledger.txt / upstream-json-ignore.tsv
├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_model / spa_fallback / bootstrap_fail / tds_biz)
│ # + upstream_guard_parity.rs / upstream_tds_timeout_parity.rs(**上游用例移植** · 29 条)
├── docs/ # **契约四件套**(B5):contract.md(唯一真源)/ decisions.md / known-limitations.md / runbook.md
│ # + ACCOUNT-LAYER.md(账号层契约)
│ # + 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md / CONSOLE-ACCEPTANCE.md)
│ # + UPSTREAM-TEST-PARITY.md(**上游测试用例移植台账**·人读版)
│ # + superpowers/(v3 spec / 执行提示词 / 上游差异表)
├── MIGRATION.md # **Java TDC ⇄ Rust 逐件翻译表** + 数据 ETL + 口令换算(B5)
├── HOWTO_ENTITY.md # **加一个实体**的操作手册(B5)
├── tds-stub/server.js # TDS 契约桩(零依赖,仅供端到端调试)
└── data/ # 运行期数据(tdc.pg/,已 gitignore)
# ⚠️ accounts.json **保留但后端不再读取**(B4 起账号层落 `base_user` 表)
```
**没有** `build.rs` / `export_dynamic` / 前端打包步骤 / Docker Compose / 外部数据库进程。
## 架构约定(红线)
- 🔴 **平台层 / 业务层边界**(v3 spec §2.3):`src/platform/` 里**不许出现业务知识**
——业务表名(`tdc_*`)、实体名(`Product` / `Resource` / …)、具体端点路径(`/api/ssw/tdc/…`)、
业务表数量;`src/tdc/` 里**不许出现平台能力的第二份实现**。
这条**可被静态检查** ⇒ `scripts/check-boundary.sh` 的 **5 个接触点(CP1–CP5)**。
🔴 **通用 CRUD 引擎住在业务层**(`tdc/mapper.rs` + `tdc/service/crud.rs` + `tdc/controller/crud.rs`,
对位上游 `TdcCrudController`)但**逻辑必须实体无关(零 `match api_name`)** ⇒ 分支只能读 `TableSpec` 字段。
- 🔴 **平台态与业务态分家**(v3 spec §2.3.1 C9):平台 `platform::state::AppState` 只留
**配置 / db / db_lock / 会话**;**引导身份 / 本地账号库 / TDS 客户端 / 业务配置** 归业务层
`tdc::state::TdcState`(`platform` 那一半 + 业务字段)⇒ **平台层不再 import 业务模块**
(CP5 专门盯这条)。
业务层拿平台那一半靠两件套:`TdcState: Deref<Target = AppState>`(字段直取)
+ `impl FromRef<TdcState> for AppState`(axum 里 `State<AppState>` 可用)。
- 🔴 **平台配置与业务配置分家**(v3 spec §2.3.1 C8):平台 `platform::config::Config` 只留
**端口 / 数据目录 / 入向令牌 / 出向令牌与地址 / 单机模式 / 密钥守卫**;
**身份码 / 身份名 / 身份密钥 / 引导管理员账号与口令** 归业务层 `tdc::config::TdcConfig`
(默认值与 env 名清单在 `tdc::constant`)⇒ 平台层**不认识**「本连接器是谁」。
平台层只提供**机制**(`platform::config::env_or_default`:空白 ⇒ 回落默认值),业务层提供**清单**。
- 🔴 **前端不直接持有数据库。** 所有数据访问经 `/api/ssw/tdc/*` REST;不得把 PGlite 重新塞回浏览器。
- 🔴 **不自研前端。** 控制台 = **上游完整前端的构建产物**(`static/`)。改 UI 改上游,**不在本仓写前端**。
- 🔴 **业务错误必须读 body 的 `code`。** 上游 TDS 用 HTTP 200 承载业务错误码(如 `code:600` 登录过期),
只看 HTTP 状态会把失败误判成成功。本仓的**业务失败一律 HTTP 200 + `{code,msg,data}`**;
**鉴权/授权失败是另一种形状**:HTTP 401/403 + 裸 `{"success":false,"code":…,"msg":"…"}`(**无 `data` 键**)。
- 🔴 **schema DDL 绝不可从 HTTP 下载。** `schema/migrate.sql` **刻意不在 web root**(`static/` 会被挂上去),
另有**两层兜底**(`src/platform/fallback.rs` 的 `ddl_guard` 前置守卫 + `ddl_content_guard` 内容兜底)。
- 🔴 **私钥不得外泄。** 身份私钥只落盘 `data/`;API 一律返回去敏后的公开视图
(**不要**用 `#[serde(skip_serializing)]` —— 会让落盘 JSON 缺字段、回读失败)。
🔴 **CRUD 出参也不许带密钥**:上游实体上标了 `@JsonIgnore` 的属性(`Identity.secretKey` /
`DeliveryTask.devUrl` / `devToken`)在本仓由 `crate::tdc::entity::TableSpec::hidden_fields` 登记 ⇒
出参**整条删键**、入参**静默忽略**(照抄 Jackson 双向语义)。**新增实体/字段前先查上游
`ssw-tdc-entity` 有没有 `@JsonIgnore`**,别靠「这列没人写」蒙混。
- 🔴 **口令不得外泄。** 账号库只存 `md5(明文)`;对外响应**手工挑字段**(`account_view`),不得把 `Account` 整个塞出去。
- 🔴 **TDC ↔ TDS 已对接(P4)**,但**只走 internal 通道**(≡ 上游 `TdsReportClient`):
出向**固定 6 个头**(`Content-Type` / `App-Code: sswflow` / `Jnpf-Origin: pc` / `Vue-Version: 3` /
`X-Internal-Token` / `X-Protocol-Version: 1.0`)⇒ **绝不**带 `Authorization` / cookie / 本地会话令牌。
旧版的 `/api/ssw/tdc/tds/*` 代理网关**已下线**(⇒ 404,别再复活)。
出向 URL **只由固定路径模板拼出**(路径段过白名单:ASCII 字母/数字/下划线/短横线,1..=64)⇒ 用户输入绝不直接进 URL。
出向失败**三档降级**:NOOP(未配 `SSW_TDS_BASE_URL`)/ 不可达 / TDS 业务失败(HTTP 200 + `code != 200`)——
**都不许变成 HTTP 500、不许 panic**。契约与实测表见 `docs/TDC-TDS-CONTRACT.md`。
## 命令速查
```bash
# 编译(自动走本机统一缓存:~/.cargo/registry 软链 + sccache)
cargo build # debug
cargo build --release # 发布版
# 测试(⚠️ 跑之前先看 SysV 信号量余量,见「已知踩坑」最后几行)
cargo test # 全量(lib + bin + 集成 + 文档)
cargo test --test upstream_guard_parity --test upstream_tds_timeout_parity # 上游用例移植(29 条)
# 运行
PORT=30000 ./target/debug/tdc-connector
cd tds-stub && node server.js # 无 TDS 时起契约桩(:30100)
# 冒烟
curl -s --noproxy '*' http://127.0.0.1:30000/api/health
curl -s --noproxy '*' -X POST http://127.0.0.1:30000/api/oauth/Login \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'account=admin' --data-urlencode "password=<密文hex>" --data-urlencode 'grant_type=password'
# 回收 macOS 上泄漏的 SysV 信号量(PGlite 专用;见「已知踩坑」最后一行)
bash scripts/reap-ipc-leaks.sh --dry-run # 只报不删
bash scripts/reap-ipc-leaks.sh # 回收(会改系统 IPC 表)
```
> 本机 curl 走系统代理,**测 localhost 必须加 `--noproxy '*'`**,否则会得到 502。
> 后台常驻进程必须用 Bash 工具的 `run_in_background` 托管;`nohup … &` 在工具调用返回后会被回收。
> 起服务时 stdout **不要**指向 `/dev/null`(进程会以 100 退出),**不要**落进提交或报告
> (首启会打印一次性 `secretKey`)。
## 五把尺子(B1a 建立 · 回归网)
🔴 **`cargo test` 打不到 HTTP 层**(进程内 `oneshot`)⇒ HTTP 状态码 / 响应头 / body 原始 JSON 文本 /
404·405 真实形状 / 隐藏字段是否真不在出参 —— **全都没被测到**。⇒ 尺子补上这一层。
```bash
bash scripts/smoke.sh # ① HTTP 契约(真进程真 HTTP,零 node 依赖)→ PASS=80 FAIL=0
bash scripts/check-boundary.sh # ② 边界静态(平台层不含业务知识)→ 账本制
bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完整性)→ PASS=13 FAIL=0
bash scripts/check-contract.sh # ④ 契约对账(docs/contract.md 端点表 ↔ 实际注册路由)→ 132 条端点一致
bash scripts/check-upstream-tests.sh # ⑤ 上游测试用例移植台账对账(台账 ⇄ 代码 ⇄ 上游测试类集合)
python3 scripts/check-citations.py # 附:文档引用自检(`文件:行号` 指向真文件真行)
```
**P2 附加尺子**(不改「五把尺子」编号体系,因为它验的是**平台包装配链**,必须起真二进制):
```bash
bash scripts/check-dual-contract.sh # PASS=17 FAIL=0
bash scripts/check-db-access.sh # 库操作单一出口:7 处命中全在白名单,0 处越界
```
一个进程、一个端口、一个库同时验:业务侧 `/api/health` 裸对象(`tables=30` / `baseTables=3`)、
面 B 独有 `/api/oauth/getLoginConfig` 与 `/api/app/Menu` 返回平台信封、6 条撞车路径里
`/api/oauth/Login` 由业务侧胜出、SPA 深链回退 200;**P3 会话桥**另验登录 token 仍是 32 位 hex、
面 A / 面 B `CurrentUser` 认同一个 token(200 + `userAccount` / `isAdministrator`)、
无 token 仍返 602、业务受保护端点仍返 200。
🔴 `baseTables` 口径是「`migrate.sql` 声明的 3 张表」,不是全库 `base_*` 计数 ——
共库后平台自带 120+ 张,按全库数会让契约从 3 漂到 123。
| 尺子 | 覆盖 | 退出码 |
|---|---|---|
| `scripts/smoke.sh` | ① 业务信封 200 + `code` ② 鉴权 401/403 裸三键(**无 `data`**) ③ `/api/**` 未命中 = **404 JSON**(不是 SPA HTML) ④ 405 = `{code,msg,data:null}` 且**保留 `Allow` 头** ⑤ `hidden_fields`(`secretKey`/`devUrl`/`devToken`)**不在出参** ⑥ **numeric 列 = JSON 数字**(与上游 Jackson 默认一致,见下) ⑦ 列表分页信封 `{pagination,list}` ⑧ `/api/health` 真查库 | 0 全绿 / 1 有失败 / 2 前置错 |
| `scripts/check-boundary.sh` | 4 个接触点:CP1 平台层无 `tdc_`/实体端点前缀 · CP2 平台层无业务实体名 · CP3 引擎不按实体名分支(零 `match api_name`) · CP4 平台 auth 无字面量端点路径 | 同上 |
| `scripts/check-entity.sh` | E1 表在 `migrate.sql` · E2 `path` == `/api/ssw/tdc/<api_name>` · E3 六条路由齐全 · E4 `hidden_fields` 覆盖上游 `@JsonIgnore` · E5 编码前缀不重复 · E6 权限键不重复(B4 删表后自动跳过) · E7 `f_`↔camelCase 双向闭合 | 同上 |
| `scripts/check-contract.sh` | **端点表 ↔ 实际注册路由**双向对账:路径全集相等 + 每路径的方法集合相等(运行时探测:404=未注册 / 405=方法不对 / 其它=已注册)+ **端点数相等** | 0 一致 / 1 不一致 / 2 前置错 |
| `scripts/check-upstream-tests.sh` | 台账(`scripts/upstream-test-ledger.tsv`)自检:每行 8 列 + `status` 合法 + `reason` 非空 · `PORTED` 行的对位文件**存在**且登记的用例函数**真在**里面 · `OUT-OF-SCOPE` 行的对位为空 · **文件级集合相等**(防少登记/多登记)· 上游克隆在场时**上游测试类集合 == 台账登记集合**(新增上游类没登记 ⇒ 红) | 同上 |
- 🔴 **`docs/contract.md` 的端点表不许手工维护**(B5)⇒ 由 `scripts/contract_probe.py --gen` 生成,
由 `scripts/check-contract.sh` 对账(**漏写 / 多写 / 写错方法** 三种都判红)。
- 🔴 **上游测试用例的「搬没搬」也不许靠记忆** ⇒ 台账 `scripts/upstream-test-ledger.tsv` 是唯一真源,
`scripts/check-upstream-tests.sh` 对账(上游新增一个测试类而台账没登记 ⇒ 红)。
⇒ **上游 `*SelfTest.java` 没有 runner 接线**(surefire 只跑 `@Test`;上游自己靠
`tools/run-java-selftests.sh` 人工跑,退出码 4 = UNVERIFIED ≠ 过)⇒ 本仓把它们落成
`cargo test` 常规用例(判据是纯函数 ⇒ 可离线断言)。
逐类对照见 `docs/UPSTREAM-TEST-PARITY.md`,超范围清单见 `docs/known-limitations.md` **L8**。
- 🔴 **基线断言数 N = 80**(B1a 锁 75,B4 加 5)⇒ **后续每批只许增不许减**;
**B1b 搬家前后必须 == 75**(搬家不改对外契约 ⇒ 断言数不增不减)。
- 🔴 **边界尺子用「账本制」(ratchet)**:越界不是一律红,而是**必须被记账**
(`scripts/boundary-ledger.txt`)。没记账的越界 ⇒ 当场红(抓新增泄漏);
**账本里已失效的条目 ⇒ 也红**(账本只许变短)。⇒ B1b 做完,7 条 `B1b` 条目必须清空;
2 条 `永久` 是假阳性豁免(`SessionKind::Identity` 是会话口径,不是业务实体 `tdc_identity`)。
- 🔴 **numeric 列输出 JSON 数字,不是 JSON 字符串**:上游 `ProductEntity.java:88` 的
`BigDecimal price` 只带 `@TableField`(无 `@JsonSerialize`)、`application.yml` 无 `spring.jackson`
设置、上游全树无 `SimpleModule`/`ToStringSerializer`、**无 jnpf jar 含 BigDecimal 类**
⇒ **Jackson 默认** ⇒ 上游发数字 ⇒ 本仓 `row_to_json` 的 `"price":9.9` **与上游一致**。
依据:v3 spec §12 **D16**。
- `scripts/smoke.sh` 的 cipher 用**后端自证**:`./target/debug/tdc-connector --enc '<明文>'`
打印密文 hex(前端自带的 `cipher.ts` 也验过 ⇒ `docs/CONSOLE-ACCEPTANCE.md` §3.1)。
## 后端 API
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/health` | 健康检查(`tables: 30`(`tdc_*`)/ `baseTables: 3`(`base_*`)/ `tdsMode` / `protocolVersion`) |
| POST | `/api/oauth/Login` | **JNPF 兼容登录**(form-urlencoded:`account` / `password`(密文 hex) / `grant_type=password`) |
| POST | `/api/ssw/tdc/Auth/Login` | 连接器身份登录(软 PKI,签发会话令牌) |
| GET | `/api/ssw/tdc/Auth/Me` | 当前身份视图(**去敏**:不含私钥/一次性密钥) |
| GET | `/api/ssw/tdc/Auth/Spaces` | 环境空间列表 |
| GET | `/api/ssw/tdc/Auth/SsoConfig` | SSO 配置(上游前端登录页用;本仓恒 `enabled:false`) |
| GET / POST | `/api/permission/Users` | 用户管理 · 列表 / 新建(**仅管理员**) |
| PUT / DELETE | `/api/permission/Users/{id}` | 用户管理 · 改资料 / 删账号(**仅管理员**) |
| POST | `/api/permission/Users/{id}/Actions/ResetPassword` | 重设口令(收 `md5(明文)`;**仅管理员**) |
| PUT | `/api/permission/Users/{id}/Actions/State` | 启用 / 禁用(**仅管理员**) |
| GET / POST | `/api/ssw/tdc/{Entity}` | 18 个实体的列表 / 新建 |
| GET | `/api/ssw/tdc/{Entity}/All` | 不分页全量 |
| GET / PUT / DELETE | `/api/ssw/tdc/{Entity}/{id}` | 详情 / 修改 / 逻辑删除 |
| GET | `/api/ssw/tdc/Resource/{id}/Detail`、`/api/ssw/tdc/Dataset/{id}/Detail` | 资源 / 数据集聚合详情(带 `fieldRules` / `maskRules` 两张子表) |
| GET | `/api/ssw/tdc/ServiceCatalog` | **服务目录**(出向 TDS `Catalog/Internal/Catalog`) |
| POST | `/api/ssw/tdc/ServiceCatalog/Buy`、`/api/ssw/tdc/ServiceCatalog/BuyBatch` | **目录下单**(出向 TDS `TradeOrder/Internal/Apply` / `ApplyBatch`) |
| GET | `/api/ssw/tdc/Billing/List` | **本方账单列表**(出向 TDS `BillingLedger/Internal/List`) |
| PUT | `/api/ssw/tdc/Billing/{id}/Dispute`、`/Confirm`、`/Settle`、`/Receipt` | **账单动作**(出向 TDS `BillingLedger/{id}/*`;带越权自检) |
| GET | `/api/ssw/tdc/Billing/{id}/Voucher` | **对账凭证**(出向 TDS `BillingLedger/{id}/Voucher`) |
| GET | `/api/ssw/tdc/Billing/LocalCompare?contractId=` | **本地计量比对**(读本地 `tdc_api_consume_log`,**零出向**) |
> 🔴 最后 7 行 = **P4 TDS 出向通道**(照抄上游新版 TDC 的 `ServiceCatalogController` + `BillingController`)。
> 完整契约(出向路径 / 6 个固定头 / 降级三档 / 刻意分歧 / 实测表)见 `docs/TDC-TDS-CONTRACT.md`。
>
> 🔴 **上表是速查,不是真源** ⇒ **132 条端点的全表在 `docs/contract.md`**
> (由 `scripts/contract_probe.py --gen` 生成、`scripts/check-contract.sh` 对账)。
`{Entity}` 的 18 个全名:
`ApiConsumeLog` / `AuditLog` / `Contract` / `Credential` / `DataInterface` / `Dataset` /
`Datasource` / `DeliveryLog` / `DeliveryTask` / `DestroyLog` / `Identity` / `Notification` /
`Order` / `Policy` / `PolicyCheckLog` / `PolicyTemplate` / `Product` / `Resource`
> ⚠️ 写入能力**按实体分档**(真值见 `src/tdc/entity/mod.rs` 的 `no_create` / `no_update` / `no_delete`):
> `Dataset` 是 `tdc_resource` 的**只读视图**(禁增/改/删);`ApiConsumeLog` 全只读;
> `AuditLog` 禁改禁删(可增);`DeliveryTask` / `DestroyLog` 禁增禁删(可改);
> `Contract` / `DeliveryLog` / `PolicyCheckLog` 禁删(可增可改)。
> 🔴 **子表聚合(B3)**:上游 7 张「无独立控制器」的子表**挂在父实体的响应里**,
> 本仓**不新增端点**,挂载位置逐父子不同(照抄上游):
> `Resource`/`Dataset` ⇒ 子表**只在** `/Detail` 聚合体(普通详情不带);
> `DataInterface` ⇒ `params` / `fields` **只在**普通详情 `GET /{id}`;
> `DeliveryTask` ⇒ `participants` 挂详情**与**列表、`outbox` 挂详情。
> 声明在 `src/tdc/entity/*.rs` 的 `child_tables`(`ChildTable` 结构:外键列 / 父行取值列 / 排序列 / 存活谓词 / 挂载面),
> 引擎**零 `match api_name`**。逐条口径见 **`docs/contract.md` §子表聚合**;
> `tdc_demo_car_insurance`(无父外键)挂不了 ⇒ 记在 `docs/known-limitations.md` L3。
### 鉴权三道门(顺序与文案与上游一致)
| 门 | 通道 | 判据 | 失败 |
|---|---|---|---|
| ① 协议版本 | `X-Protocol-Version` | 与 `protocol::PROTOCOL_VERSION` 不兼容 ⇒ 拒 | 401「跨端协议版本不兼容,请升级对端」 |
| ② 内部令牌 | `X-Internal-Token` | 与 `SSW_INTERNAL_TOKEN` 相等 | 401「内部接口凭证无效」 |
| ③ 会话令牌 | `X-Auth-Token` 或 `Authorization: bearer <token>` | 命中会话(**身份会话** 或 **本地账号会话**) | 401「内部接口凭证无效」 |
- 🔴 内部令牌**只看 `X-Internal-Token` 头**,不接受 query / body。
- 🔴 `TDC_STRICT_SECRETS=1` ⇒ 默认口令即视为不安全 ⇒ **启动即失败**(`config::check_secret_guard`)。
- 白名单 `WHITE_URL` 含 `/api/oauth/Login`(登录端点本身不过闸门)。
### 权限模型(三件套,与上游同构)
| 面 | 判据 | 代码位置 |
|---|---|---|
| **登录态** | 内部令牌 **或** 已登录主体(身份会话 / 本地账号会话) | `src/platform/auth.rs`(`require_menu_permission`) |
| **角色码** | `base_role.f_en_code` ∈ {`tdcProvider`,`tdcConsumer`,`tdsReadOnly`} | `src/tdc/service/account.rs`(`role_codes`) |
| **管理员位** | `base_user.f_is_administrator = 1`(**fail-closed**) | `src/tdc/service/account.rs`(`is_administrator`) |
- 🔴 **实体级写权限没有隔离**(D6/D11):除管理员端点外,**任何登录用户可写全部 18 个实体**
—— 与上游 `TdcCrudController.requireMenuPermission()` **完全同构**(上游也没有实体级隔离)。
旧的 18 条「实体 → 权限键」链路(`entity::PERMISSION_KEYS` + `identity::capabilities()` +
`crud::require_write_permission()`)**已在 B4 整条删除**(那层「解析不出 ⇒ fail-open」从来没在管)
⇒ 详见 `docs/known-limitations.md` **L4**。
- 🔴 **只读/只写分档仍在**:`no_create` / `no_update` / `no_delete`(`src/tdc/entity/mod.rs`)。
- 🔴 **部署退出门槛**:账号发放**只给受信人**(默认口令 `admin` 公开已知;
`TDC_STRICT_SECRETS=1` 会在管理员仍用默认口令时拒绝启动)。
## 关键实现细节(改代码前必读)
1. **查询结果序列化**:任意 SELECT 用 `SELECT row_to_json(q)::text AS _row FROM (<sql>) q` 包成单列文本,
后端 `rows[i].get::<Option<String>>(0)` 取文本后 `serde_json::from_str` 得标准 JSON。
**这是规避逐列类型映射的关键手法**,新增查询一律沿用 `query_json()`,不要另起逐类型分支。
2. **单 backend 串行化**:pglite 是单 in-process backend,所有 DB 访问必须持 `state.db_lock`(`tokio::Mutex`)。
3. **表名白名单**:`valid_table()` 只允许 `[A-Za-z][A-Za-z0-9_]*`,任何拼接表名的地方都要走它;
`entity::validate()` 在**启动时**自检全部拼进 SQL 的标识符(不过白名单 ⇒ 秒退)。
4. **路径与 cwd 解耦**:`resolve_project_dir()` 从可执行文件向上找含 `static/index.html` 的目录,
`static/` 与 `data/` 都基于它,**不要改成相对 cwd**(后台启动时会 500)。
5. **`include_str!` 路径相对 `src/platform/db.rs`**:写 `../../schema/migrate.sql`,不是 `../schema/`。
6. **camelCase ↔ snake_case**:请求结构体一律加 `#[serde(rename_all = "camelCase")]`。
🔴 **例外**:`/api/oauth/Login` 的表单字段名就是 `grant_type`(上游送的就是这个)⇒ **不能**加 camelCase
(加了字段永远为 `None`),改用 `#[serde(default, alias = "grantType")]`。
7. **axum 0.8 的 `Router<S>` 语义**:`S` 是「还缺什么状态」;`with_state` 把状态烤进**当前已有**的 endpoint。
⇒ `build_router` 返回 `Router<AppState>`,由 `main.rs` 在挂完静态兜底与中间件**之后**统一 `with_state` 收口。
8. **`Form<T>` 在 axum 0.8.9 只实现 `FromRequest`**(没有 `OptionalFromRequest`)⇒ `Option<Form<T>>` **编译不过**
⇒ 需要「解析失败也走业务信封」的表单端点,取**原始 body** 自己用 `serde_urlencoded::from_bytes` 解析。
9. **405 的 JSON 兜底**在 `platform::mw::json_method_not_allowed`(**响应改写中间件**,挂链尾),
不是 axum 的 `method_not_allowed_fallback`(后者只对调用那一刻已注册的路由生效,且丢 `Allow` 头)。
10. **schema 初始化**:启动时探测 `tdc_identity` 是否存在,不存在才按 `;` 拆分执行 `migrate.sql`。
11. **`ecb` 0.1 只实现 `*_block_mut`**(原地改块)⇒ 用 `encrypt_block_mut` / `decrypt_block_mut`,**不是** `encrypt_block`。
12. **同一文件的多个 Edit 必须串行**(并行 Edit 会 last-writer-wins 静默覆盖)。
13. **出向 TDS 判定成功必须看 `body.code == 200`**(TDS 业务失败也是 HTTP 200)。
解包型端点用 `tds::unwrap_data`、整包型用 `tds_biz::unwrap_envelope` —— **别混用**。
14. **出向请求只带 6 个应用层头**(`src/tdc/client/tds.rs` 的 `internal_headers()`);
`reqwest` 会自己加 `host` / `content-length` / `accept` ⇒ 断言「头数」时别把这三个算进去。
15. **CRUD 出参要过 `row_to_json_spec(spec, row)`**(不是 `row_to_json`)——
它按 `spec.hidden_fields` 把上游 `@JsonIgnore` 的键**整条删掉**(不是置 null);
写路径用 `body_to_columns(body, &types, spec.hidden_fields)` **静默跳过**同一批键。
🔴 `hidden_fields` 的键名是 **camelCase JSON 键**(不是列名);
`update` 的 frozen 列自检必须**跳过 hidden 列**(上游 `devUrl`/`devToken` 既是
`@JsonIgnore` 又是 frozen ⇒ Jackson 绑不上 ⇒ 上游既不拒也不写 ⇒ 本仓不能 400)。
16. **引导身份要显式递业务配置**(C8):`identity::bootstrap_identity(state, &tdc_config)`
——身份码/身份名/身份密钥**不在** `state.config` 里 ⇒ 由装配层(`main.rs`)造
`TdcConfig::from_env()` 递进去。`TdcConfig::from_raw(..)` 是**纯函数**(不读全局 env)⇒ 可单测。
17. **状态两半的取法**(C9):业务层 `TdcState` **deref 到** `platform::state::AppState`
⇒ `state.db` / `state.db_lock` / `state.sessions` / `state.config` 照旧可用;
axum 里想只拿平台那一半 ⇒ `State<AppState>`(靠 `impl FromRef<TdcState> for AppState`)。
🔴 `FromRef` 在 **`axum::extract::FromRef`**(不是 `axum::core::extract::FromRef`)。
18. **领域 SQL 归业务服务层**(C10):`tdc_identity` 的领域 SQL **全部住在
`src/tdc/service/identity.rs`**(控制器层不再自己拼)⇒ 领域查询**只 SELECT 明确列**,
永不 `SELECT *`(别把 `f_secret_key` 整行拖进内存)。
🔴 `tdc_identity` 因此**有两条读写路径**(领域 SQL + 通用 CRUD 引擎)⇒ 已记进
`docs/known-limitations.md` L1(上游无「通用引擎」概念,硬收会失真 ⇒ 显式承认 + 收口)。
19. **常量时间比较只有一份实现**(C11):实现住在 `src/platform/compare.rs`;
业务侧(`tdc::service::identity` / `tdc::service::account`)用
`pub use crate::platform::compare::constant_time_eq;` 复用 ⇒ **不许再抄一份**。
20. **时间口径分两套,不是随手写的**(C12):仓里**不再手写日历算法**,一律 `chrono`;
- **服务器本地时区**(`chrono::Local`):业务编码(`tdc/util/code.rs`)与 DB 审计列(SQL `now()`)
⇒ **必须**与上游 Java `LocalDateTime.now()` / MySQL `now()` 同口径(否则编码日期段差一天);
- **UTC**(`chrono::Utc`):账号库自己的审计字段(`tdc/service/account.rs::now_iso`)——本仓自有格式,无上游对照物。
🔴 完整对照表 + 「别把 Local 写成 UTC / 别把 UTC 写成 Local」见 **`docs/contract.md` §时间口径**。
21. **子表挂载面逐父子不同**(B3):子表声明用 `entity::ChildTable`
(`key` / `table` / `fk_column` / `parent_column` / `order_column` / `alive` / `mounts`),
挂载面三选:`Aggregate`(`/Detail` 聚合体)/ `Detail`(普通详情)/ `List`(列表,**批量**查)。
- 🔴 **父行取值列不一定是 `f_id`**:参与方按 `f_tds_task_id` 挂 ⇒ 任务没有平台任务号时
参与方是**空集合**(上游同口径)。
- 🔴 **存活谓词逐表不同**:四张「资源 / 接口」子表**没有** `f_delete_mark`(上游物理删除)⇒ 不加谓词;
参与方表有 ⇒ 用 `ALIVE`。
- 🔴 表名 / 列名**全部来自注册表**,启动时 `entity::validate()` 走标识符白名单(不过 ⇒ 秒退)。
逐条口径见 **`docs/contract.md` §子表聚合**。
22. **生产档弱密钥守卫是**纯函数**(上游 `ProdGuard` 的六条判据,一条不能少)**:
`src/platform/guard.rs` 的 `guard_violations(map)` **不读进程全局 env**(上游把判据抽成纯函数就是为了能离线断言)。
- 🔴 **六条判据**:①键不在 map⇒跳过 ②值为 null/空白⇒违规 ③值**精确等于**弱值⇒违规
④值**含**弱值⇒违规(**反绕过**:默认值加个后缀也拦住)⑤值命中**弱标记词**⇒违规 ⑥长度<12⇒违规。
**只实现 ③ 而漏 ④** ⇒ 把默认值改成 `…-e2e1` 就能绕过。
- 🔴 **弱标记词按整体词匹配**(上游正则 `(?i)(^|[\-_.])(…)([\-_.]|$)`)⇒ 用 `contains` 会**误拦**合法部署
(强随机串里偶然出现 `test`)。
- 🔴 **`CIPHER_KEY` 不受管**(上游 chg_0020 同款裁定:那是**协议共享值**,必须发给浏览器)⇒
把它塞进受管清单 ⇒ "保持默认同值"这种正常部署会被**恒假红**。
- 🔴 **出向令牌只在配了 `SSW_TDS_BASE_URL` 时才受管** ⇒ 本地单机模式不会被误停。
逐条对照见 `docs/UPSTREAM-TEST-PARITY.md` §2.1,决策见 `docs/decisions.md` **D22**。
23. **出向 TDS 的超时分类靠 cause 链,不靠错误文案**:
`src/tdc/client/tds.rs` 的 `cause_chain_has_timeout()` 沿 `Error::source()` **有界**(`depth < 16`,照抄上游)往下找。
- 🔴 **只有** cause 链里有超时(`reqwest::Error::is_timeout()` 或 `io::ErrorKind::TimedOut`)才改写成
「调用 TDS 超时(当前 connect=…ms / read=…ms,可用 `SSW_TDS_CONNECT_TIMEOUT_MS` / `SSW_TDS_READ_TIMEOUT_MS` 调大)」;
**连接被拒 / DNS 失败 / 无 cause ⇒ 不改写**(仍是「TDS 不可达」)——
🔴 **把连接被拒说成"超时"会把排查引向错误方向**(调超时没用,要查网络/证书)。
- 超时值**外置到 env**(`SSW_TDS_CONNECT_TIMEOUT_MS` 默认 3000 / `SSW_TDS_READ_TIMEOUT_MS` 默认 5000),
`platform::config::timeout_ms_from` 对**空白 / 非法 / ≤0** 一律回落默认值。
决策见 `docs/decisions.md` **D23**。
## 数据模型
`schema/migrate.sql`(3249 行)= 上游 `tdc_*` schema 的生成产物(**30 张业务表**)
**+ 账号层 3 张 `base_*` 表**(B2 起):
| 域 | 表 |
|---|---|
| 身份 / 凭据 | `tdc_identity`、`tdc_credential`、`tdc_p2p_session` |
| 数据源 / 接口 | `tdc_datasource`、`tdc_data_interface`、`tdc_data_interface_field`、`tdc_data_interface_param` |
| 资源 / 脱敏 | `tdc_resource`、`tdc_resource_field`、`tdc_resource_mask_rule` |
| 目录 / 交易 | `tdc_product`、`tdc_order`、`tdc_contract` |
| 策略 | `tdc_policy`、`tdc_policy_template`、`tdc_policy_check_log` |
| 交付 | `tdc_delivery_task`、`tdc_delivery_task_participant`、`tdc_delivery_log`、`tdc_delivery_outbox` |
| 执行 / 销毁 | `tdc_privacy_exec_run`、`tdc_sandbox_exec_run`、`tdc_destroy_log` |
| 日志 / 通知 | `tdc_audit_log`、`tdc_api_consume_log`、`tdc_sync_log`、`tdc_notify` |
| 上游示例 | `tdc_demo_car_insurance`、`tdc_demo_insurance_claims`、`tdc_demo_pii` |
| **账号层(B2 建表 / B4 起真正使用)** | `base_user`、`base_role`、`base_role_relation` |
其中 **24 张**带齐 10 个系统列(`f_id` / `f_tenant_id` / `f_sort_code` + 创建·修改·删除审计列),
其余 **6 张**为精简变体;逻辑删除位为 `f_delete_mark`;21 个唯一索引中 14 个是 partial 唯一索引。
### 账号层三表(`base_*`,B2 建表 / B4 起使用)
🔴 **真源 = 上游 j7** `boot/db/j7/V1.0.0__jnpf_base_schema.sql`
(`base_user` 在该文件 `:17384`)⇒ **逐字搬运**,只加一处:
| 表 | 用途 | 差异 |
|---|---|---|
| `base_user` | 账号(`f_account` / `f_password` / `f_secretkey` / `f_is_administrator` / `f_enabled_mark` / `f_delete_mark` …) | 主键内联(见下) |
| `base_role` | 角色(`f_en_code` = `tdcProvider` / `tdcConsumer` / `user`) | 同上 |
| `base_role_relation` | 用户 ↔ 角色(`f_object_type='user'` + `f_object_id` + `f_role_id`) | 同上 |
- 🔴 **主键**:上游这三张表的 `CREATE TABLE` 里**没有**主键(官方 dump 后置
`ALTER TABLE … ADD CONSTRAINT …_pkey PRIMARY KEY (f_id, f_tenant_id)`)⇒ 本仓把主键**内联**进
`CREATE TABLE`(pglite 只吃 `migrate.sql` ⇒ 必须自带;与 JNPF 官方 dump 后置 ALTER 等价)。
- ⚠️ **不建** `base_module` / `base_authorize` / `base_organize` / 其余 120 张 `base_*`
(上游 `ssw.jnpf-permission.enabled=false` ⇒ 菜单授权行是死的;见 v3 spec §3.1)。
- ⚠️ 上游 `base_user` 另有 `f_maxkey_user_id` 一列(V1.0.3 的 MaxKey SSO 认亲键)
⇒ 本仓**不实现 MaxKey SSO** ⇒ **不建该列**(记 `docs/known-limitations.md` L2)。
**改 schema 时**:`migrate.sql` 是编译期内嵌的,改完必须清空 `data/` 重建(探针逻辑只在首次建表),
并同步更新 README 的表清单。
🔴 **探针只看「public schema 里有没有表」**(`table_count > 0` 就跳过整个迁移)⇒
**半途失败的迁移会留下一个「建了一半」的库**,此后每次启动都跳过迁移、缺的表永远补不上
⇒ 迁移报错后**必须** `bash scripts/reset-data.sh` 再起(已实测踩到,见坑位表)。
## 账号层(`base_user` 表,B4 起)
🔴 **载体变了**:B4 之前是本机 JSON 文件 `data/accounts.json` ⇒ 现在**账号落 `base_user` 表**。
JSON 文件**保留不删**,但**后端不再读取**(存量账号**不导入**,D8)。
- `src/platform/cipher.rs`:MD5 + AES-256-ECB,与上游 `frontend/web/src/utils/cipher.ts` **逐字对齐**。
key = `md5_hex(CIPHER_KEY)` 的 **32 个 ASCII 字节**(⇒ AES-256,**不是** 16 字节原始摘要);
src = `md5_hex(plain)` 的 32 个 ASCII 字节;Pkcs7 补 16×0x10 ⇒ 48 字节 / 96 hex。
🔴 这条契约有**两道**回归防线:`src/platform/cipher.rs` 单测里的**上游原始向量**
(`encryptPassword('123456')`)**+** `tests/account_api.rs::login_accepts_the_upstream_literal_ciphertext`
—— 后者拿**字面密文**真打登录端点(改密钥它必红,**不是**自证自洽)。
浏览器侧也已验过(上游自己的 `cipher.ts` 加密后能登录 ⇒ 见 `docs/CONSOLE-ACCEPTANCE.md` §3.1)。
- `src/tdc/service/account.rs`:**账号层数据面**(读写 `base_user` / `base_role` / `base_role_relation`)。
- **口令公式(官方双 md5)**:`f_password = md5(lower(md5(明文)) + lower(f_secretkey))`
(上游 `PasswordTokenGranter.java:186`)⇒ 存的不是裸 md5。
- `f_secretkey` = **每账号随机**(UUID v4 大写)⇒ **改密不换 secretkey**(与官方一致)。
- **首启引导**:`base_user` 无存活行时种一个管理员(`f_is_administrator=1`),**幂等**;
`base_role` 逐字照抄上游 `V1.0.1__connector_seed.sql` 的三行(`tdcProvider`/`tdcConsumer`/`user`),
管理员绑 `user` 角色。
- **管理员判据** = `f_is_administrator=1`,**查询异常 ⇒ false(fail-closed)**。
- **角色码**:`role_codes` 逐字照抄上游 SQL(`IN ('tdcProvider','tdcConsumer','tdsReadOnly')`)
⇒ 引导管理员绑的 `user` **不在判据里** ⇒ 它的角色码数组是**空的**(上游同口径,D9/S7)。
- `src/tdc/controller/account.rs`:登录 + 用户管理 6 端点 + 管理员闸门 `require_admin`
(连接器身份会话 / 管理员账号放行;**内部令牌刻意 403**,比上游严一档;查不到账号 ⇒ fail-closed 403)。
出参形状**不变**(`id`/`account`/`realName`/`gender`/`mobilePhone`/`enabledMark`/`creatorTime`/`description`),
🔴 **不回显** `f_password` / `f_secretkey`。
- 逐条口径见 **`docs/contract.md` §账号层**;决策见 `docs/decisions.md` **D20/D21**。
## TDS 出向通道(P4)
- `src/tdc/client/tds.rs`:**出向客户端**,照抄上游 `TdsReportClient` 的 internal 通道(9 个方法)。
- 出向头**正好 6 个**(`internal_headers()`),**绝不**带 `Authorization` / cookie。
- 超时 3s 连 / 5s 读;`.no_proxy()` 绕开系统代理。
- 路径段白名单 `is_safe_path_segment`(ASCII 字母/数字/下划线/短横线,1..=64)。
- **两种返回风格别混**:**解包型**(`internal_catalog` / `internal_apply` / `internal_apply_batch`
⇒ `data` 或 `Err(msg)`)/**整包型**(`list_billing_for_connector` / `dispute` / `confirm` /
`settle` / `receipt` / `voucher` ⇒ 原始 `{code,msg,data}`)。
⚠️ 整包型**成功**时 `data` 是**字符串**(账本 id),不是对象。
- `src/tdc/controller/tds_biz.rs`:**10 个对外端点**(服务目录 3 + 账单 7),照抄上游
`ServiceCatalogController` + `BillingController`。
- 身份解析**两套口径**:宽松(List/Dispute/Receipt/Voucher/LocalCompare)/
严格(Confirm/Settle)—— 照抄上游,不统一。
- 越权自检 `owns_ledger`(先 `BillingLedger/Internal/List` 查本方账本)⇒ **fail-closed**。
- `LocalCompare` 读**本地** `tdc_api_consume_log`,**零出向**。
- 完整契约(出向路径表 / 6 个头 / 降级三档 / 7 条刻意分歧 / 真 TDS 实测表)见
**`docs/TDC-TDS-CONTRACT.md`**。
## 工程化外壳(文档层 · B5)
🔴 **契约的唯一真源是 `docs/contract.md`** —— 端点全表(132 条)· 4 种响应形状 ·
分页信封 · `f_`↔camelCase 命名契约 · 数据模型(30 + 3 张表)· 权限章节。
| 文档 | 讲什么 | 什么时候看 |
|---|---|---|
| `docs/contract.md` | **对外契约真源**(132 端点全表 / 响应形状 / 命名 / 数据模型) | 改端点、改出参形状 |
| `docs/decisions.md` | **为什么这么定**(D1–D21,每条带代码落点 `文件:行号`) | 有人问「为什么不那样写」 |
| `docs/known-limitations.md` | 已知限制 **L1–L8**(双读写路径 / 未建列 / 挂不了的子表 / 权限敞开 / 动作端点未实现 / 分发形态 / 单段尾被吞 / **上游测试类超范围**) | 有人问「这功能怎么没有」 |
| `docs/runbook.md` | 怎么起 / 跑尺子 / 常见故障(11 条) | 服务起不来、尺子红了 |
| `docs/UPSTREAM-TEST-PARITY.md` | **上游测试用例移植台账**(15 个上游类 → 3 搬 / 12 超范围 · 逐条对照 + 复跑命令) | 有人问「上游那个用例我们搬了吗」 |
| `docs/ACCOUNT-LAYER.md` | `base_user` 契约 + 官方双 md5 公式 + 管理员位 fail-closed + 角色码 | 改登录 / 改口令 / 加账号 |
| `MIGRATION.md` | **Java TDC ⇄ Rust 逐件翻译表** + 数据 ETL + 口令换算 | 迁数据 / 对上游 |
| `HOWTO_ENTITY.md` | **加一个实体**的操作手册(只碰 `entity/` 一处) | 加表 / 加端点 |
- 🔴 **端点数不许手工维护**:`docs/contract.md` 的表由 `scripts/contract_probe.py --gen` 生成,
`scripts/check-contract.sh` 对账(**漏写 / 多写 / 写错方法** 三种都判红)。
- 🔴 **文档里的 `文件:行号` 引用要能落地**:`python3 scripts/check-citations.py` 机械查
(文件存在 + 行号在范围内;上游 Java 引用去 `/tmp/sswtdc-probe` 快照里查)。
- 🔴 **语义**不归脚本管 ⇒ 改代码后**抽查 5 条**引用是否还成立(v3 spec §8 B5 验收)。
## 编译缓存(dev-cache-layout 规范)
本机已统一,**无需在项目内做任何配置**:
- `~/.cargo/registry` → `~/.cache/cargo/registry`(软链)
- sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCCACHE_DIR` 启用
- 缓存实体在 `~/.cache/sccache`(`~/Library/Caches/Mozilla.sccache` 软链透明访问)
`cargo build` 直接命中。**不要**在仓库内新建 `.cargo/config.toml` 或把 `target/` 挪走。
## 发布与体积
- release 配置:`opt-level=2` / `lto="thin"` / `strip="symbols"` / `codegen-units=16`;
**不设 `panic="abort"`** —— 单进程链接 sspf 后平台契约要求 panic ⇒ HTTP 200 + `code=400`,
catch-all 中间件依赖默认 `unwind`。
- 体积构成:debug 二进制 **~35 MB**(主体是内嵌的 PostgreSQL 引擎)+ static **2 MB**(上游 SPA 产物)。
- 首次启动生成 `data/tdc.pg` 约 **39 MB**(运行期数据,不随包分发)。
## 已知踩坑清单
| 症状 | 根因 | 处理 |
|---|---|---|
| `include_str!` 编译失败找不到文件 | 路径相对 `src/platform/db.rs` | 用 `../../schema/migrate.sql` |
| `/` 返回 500、静态资源 404 | 路径基于 cwd,后台启动 cwd 漂移 | 用 `resolve_project_dir()` |
| curl 测 localhost 得 502 | 走了系统 HTTP 代理 | 加 `--noproxy '*'` |
| 落盘 JSON 回读失败 | 用了 `#[serde(skip_serializing)]` | 磁盘存全量、API 走单独的对外视图 |
| 注册返回 600「登录过期」却判成功 | 只看 HTTP 状态 | 必须同时判 body 的 `code` |
| `orgName`/`endpoint` 恒为 null | 请求 camelCase vs 后端 snake_case | 结构体加 `#[serde(rename_all = "camelCase")]` |
| `grant_type` 永远是 `None` | 给表单结构体加了 camelCase | 改用 `#[serde(default, alias = "grantType")]` |
| `Option<Form<T>>` 编译不过 | axum 0.8.9 的 `Form` 无 `OptionalFromRequest` | 取原始 body 自己解析 |
| 405 返回 HTML / 丢 `Allow` 头 | 用了 axum 的 `method_not_allowed_fallback` | 用 `platform::mw::json_method_not_allowed` |
| DDL 能从 HTTP 下载 | DDL 落在 web root | 移到 `schema/` + `ddl_guard` 两层兜底(**Range 分段也要拦**) |
| 表名注入 | 直接拼表名 | 一律走 `valid_table()` + `entity::validate()` |
| 两个实例共用 `data/` 报 `postmaster.pid` 锁冲突 | pglite 单实例独占数据目录 | 用不同目录/端口起第二个实例 |
| 迁移报语法错后,改好 `migrate.sql` 再启动,**新表没出现**(`baseTables` 仍 0) | 探针只看「public 有没有表」⇒ 上次失败已建了一半的库 ⇒ 每次启动都**跳过**整个迁移 | `bash scripts/reset-data.sh`(把 `data/tdc.pg` 挪进回收站)后重启 |
| 并行测试互相撞车 | `tdc_identity` 有唯一约束 / 账号库是持久文件 | 每个用例用**唯一**身份码 + **独立**账号文件 |
| release 首次编译慢 | 全依赖需重编 | 走 sccache |
| 脚本里 `wait` 挂死 7 分钟+ | **后端不响应 SIGTERM**(实测:kill 后进程仍在) | TERM → 最多等 5 秒 → `kill -9` → 最后 `wait` 收尸 |
| `/api/health` 的断言套「业务信封」判红 | 它是**裸对象**(`{status,service,version,protocolVersion,tdsMode,db,tables}`),**没有 `code` 键** | 单独断言 HTTP 状态码 + 断言「无 `code` 键」 |
| 边界尺子漏报(代码整片消失) | 朴素正则剥注释把**字符串里的 `/*`** 当成块注释开头 | 用**字符串感知的状态机**剥注释(`scripts/check-boundary.sh` 的 `strip_comments()`) |
| 「不含 `secretKey`」断言恒真通过 | 取键名的辅助模式对对象返回 `ERR` ⇒ 断言变成真空 | 用 `objkeys`(取对象键名)模式,别用 `listkeys` |
| 自动化里 antd 抽屉停在屏幕外、点不到「保存」 | 内核浏览器在**后台标签** ⇒ `visibilityState=hidden` ⇒ rAF + CSS transition 全冻结 | 注入 `*{transition:none !important}` + 摘掉卡住的 motion 类(**测试环境假象,非产品缺陷**,见 `docs/CONSOLE-ACCEPTANCE.md` §5) |
| 出向 TDS 得 502 / 连接超时 | `reqwest` 读了**系统代理**(`HTTP_PROXY` / macOS 网络设置)⇒ loopback 被劫持 | `ClientBuilder::no_proxy()`(TDS 是**内网直连**服务) |
| 出向 TDS 拿到 200 却当成功 | TDS 业务失败也走 **HTTP 200 + `code != 200`** | 判 `body.code == 200`(解包型)/ `unwrap_envelope`(整包型) |
| 上游动作端点**不 404**,前端下拉框却是空的 | 通用详情路由 `/{Entity}/{id}`(`src/tdc/controller/crud.rs:65-93`)把 `/{Entity}/{action}` **吞掉** ⇒ HTTP 200 + `code:400` | **必须读 body 的 `code`**;26 条形态 A 的清单见 `docs/known-limitations.md` **L7**(`python3 scripts/upstream-action-census.py` 可复算) |
| 出向头被算成 8 个 | `reqwest` 会**自己加** `host` / `content-length` / `accept` | 应用层只断言自己那 6 个(传输层头不在管辖范围) |
| `Billing/{id}/Dispute` 等越权时仍看到出向请求 | `ownsLedger` 自检本身**就要**发一次 `BillingLedger/Internal/List` | 只断言**动作端点没被调用**,别断言「零出向」 |
| `ServiceCatalog/Buy` 空体报「请求体格式有误」 | 用了 `JsonBody`(空体 ⇒ 拒) | 这几个端点体**可空** ⇒ 用 `tds_biz::OptionalJsonBody`(空体当空对象) |
| 出向 URL 拼出注入 | 用户输入直接进 URL 路径 | 只用固定模板 + `tds::is_safe_path_segment` 校验过的段 |
| `GET /api/ssw/tdc/Identity` 回显 `secretKey` | CRUD 出参是 `SELECT *` + camelCase 直出,没走上游 `@JsonIgnore` 白名单 | 出参过 `crud::row_to_json_spec()`(按 `spec.hidden_fields` 删键)⇒ 新增实体先对照上游 `ssw-tdc-entity` 查 `@JsonIgnore` |
| `cargo test` 全挂在 `initdb failed: … could not create semaphores: No space left on device` | **macOS 不回收进程退出时创建的 SysV 信号量集**(且无 `ipcrm`)⇒ 每轮 `cargo test` 的 PGlite 实例各漏 20 个信号量,攒够就把 `kern.sysv.semmns`(87381) 撑满 | 跑 `bash scripts/reap-ipc-leaks.sh` 回收(只删 `nsems==20` + 本 uid + 久未使用的 set);**跑测试前先看一眼余量** |
| 账号层改成 DB 后 `INSERT` 报 `column is of type integer but expression is of type text` | Rust 只有 `String` ⇒ 参数天然是 `text` ⇒ **单层 `CAST($1 AS text)` 不够**(PG 仍按 `text` 匹配目标列) | **双层 CAST**:`CAST(CAST($n AS text) AS <coltype>)`(`src/tdc/service/account.rs` 的 `p()` 助手);空串要落 NULL 时再包 `NULLIF(...,'')` |
| 账号层改成 DB 后 `mobilePhone`/`description` 从 `null` 变 `""` | 存了空串 | 用 `NULLIF(<cast>,'')` ⇒ 空串落 SQL NULL(**出参形状不变**) |
| 引导管理员的 `/Auth/Me` 角色码是**空数组** | 判据的 `IN` 列表是 `tdcProvider/tdcConsumer/tdsReadOnly`,而引导绑的是 `user` | **上游同口径**(D9/S7)⇒ 别去"修"它 |
| 改完口令还是登不进去 | 存成了裸 `md5(明文)`,而登录走 `md5(md5(明文)+secretkey)` | 入库必须用**官方双 md5 公式**(`official_password_hash`);改密**不换** secretkey |
| 弱密钥守卫形同虚设(默认值加个后缀就放过) | 只比了**精确值**,漏了上游判据④(**含**弱值片段) | 六条判据一条不能少(`src/platform/guard.rs`);对位用例 `prod_guard_default_value_with_suffix_is_blocked` |
| 部署后启动就被拒,但令牌看着没问题 | 把 `CIPHER_KEY`(**协议共享值**)也塞进了受管清单 | 上游 chg_0020 已把 `security.security-key` 移出受管清单 ⇒ 本仓 `CIPHER_KEY` 同款裁定(**不得**受管) |
| 出向 TDS 报「超时」但把超时调大也没用 | **连接被拒 / DNS 失败**被误判成超时 | 超时分类只认 **cause 链**里的超时(`is_timeout()` / `ErrorKind::TimedOut`)⇒ 被拒/解析失败**不改写**文案 |
| 上游加了新测试类,本仓毫无察觉 | 上游 `*SelfTest.java` **surefire 不跑**(无统一入口) | `scripts/check-upstream-tests.sh` 对账台账 `scripts/upstream-test-ledger.tsv`(上游新增类没登记 ⇒ 红) |
## 明确不在本仓库范围
- **上游那 109 条「动作端点」**(发布 / 下架 / 提交审核 / 策略校验 / 同步资源 / 销毁 …)属 P2–P5,尚未实现
⇒ 上游前端这些按钮点了会 404(**分期的正常状态**)。
⚠️ 但其中 **26 条**(路径形状 `/{Entity}/{action}`)**不会 404** ——
会被通用详情路由 `/{Entity}/{id}` 吞掉 ⇒ HTTP 200 + `code:400`(POST 则是 405)。
逐条清单 + 依赖分析(哪 1/4 依赖 Nax 引擎而本地不可行)见 `docs/known-limitations.md` **L5**;
「吞掉」这条见 **L7**。
- 原 `ssw-tdc` 的**隐私计算作业**——`NaxJob / Nax2PJob / TeeJob / Sandbox / Privacy / AnnotationTask /
Notebook / VizChart / Quality* / HostingJob / DestroyLog` 等——依赖 **Nax 隐私计算引擎**与
**scard 安全平面(软 PKI + 软 TPM)**,本地不可行。需要这部分应保留原 Java/Scala 服务。
- **TDS 的 login / `ensureToken` 通道**(JNPF 登录换 token)**不做** —— P4 只实现 internal 通道。
- ~~`/api/ssw/tdc/tds/*` 代理网关~~ **已永久下线**(旧 Bridge 通道,⇒ 404)⇒ 别再复活。
- **JNPF 角色 / 菜单 / 授权模型**(j7 的 `base_module` / `base_authorize` / `base_organize` 等)**不引入**
⇒ 本仓的权限判定走**上游三件套**(登录态 / 角色码 / 管理员位),**不走菜单**。
角色码只用了 `base_role` / `base_role_relation` 两张表(D6/D20)。
## 记忆约定
遵循项目级约定:**踩坑清单与长 traceback 进 `docs/`(本文件表格即其索引),工作日志进 `.workbuddy/memory/YYYY-MM-DD.md`**,
本文件只留「原则 + 决定 + 一句话摘要」。