Files
tdc-rs/CLAUDE.md
T
adminandClaude Code bafdc98228 refactor(b1b): 搬家 —— 平台层/业务层分离(行为零变化)
按 v3 spec §2.1 的目录映射,把 9810 行代码重组成「平台层 + 业务层」两段:

**平台层 `src/platform/`**(12 个文件,与业务零知识)
- state / config / db / session / envelope / cipher / ids / protocol
- body / mw / fallback(原 `src/routes/`,是通用响应改写与兜底,不是业务)

**业务层 `src/tdc/`**(对位上游 `ssw.tdc.*` 包族)
- `entity/` —— `registry.rs` 拆成 **18 个实体各一文件** + `mod.rs`(`ALL_SPECS` / `validate` / 权限键)
- `mapper.rs` —— 原 `crud.rs` 的 SQL 组装/投影/序列化半边(机械活、实体无关)
- `service/crud.rs` —— 原 `crud.rs` 的写路径规则/分档判定半边
- `service/identity.rs` / `service/account.rs` —— 原 `domain/identity.rs` / `account.rs`
- `controller/` —— 原 `routes/`(crud / health / auth / account / tds_biz)
- `client/tds.rs` —— 原 `tds/mod.rs`(TDS 出向客户端)
- `util/code.rs` —— 原 `codec.rs`(**业务**编码生成器,非平台件)
- `support/public_paths.rs` —— 免鉴权端点清单(业务侧持有,C5 接线)
- `policy/ engine/ schedule/ notify/ heartbeat/ sso/` —— 上游同名包占位

**行为零变化**:HTTP 契约、响应形状、SQL、口令算法、权限判定全部不动。
- `cargo test` 223 passed / 0 failed / 1 ignored(与 B1a 基线一致)
- `scripts/smoke.sh` PASS=75 / FAIL=0(断言数 == 基线 N=75,不增不减)
- `scripts/check-boundary.sh` exit 0(账本 7 条 B1b 待清 + 2 条永久豁免)
- `scripts/check-entity.sh` PASS=15 / FAIL=0

**边界账本同步**:CP3 的 `routes/crud.rs` 条目改为 `controller/crud.rs`(账本按路径后缀匹配,搬家不失效)。

**为什么搬家必须一个 commit**:`check-boundary.sh` 的 NEW_LAYOUT/LEGACY 判定是**全有或全无**
(`src/platform/` 目录存在即切新布局)⇒ 分批搬会让账本条目在中间态失效 ⇒ 尺子当场红。
⇒ 搬家一个 commit,之后 C1–C12 各一个 commit。

Co-Authored-By: Claude Code <[email protected]>
2026-10-26 20:15:09 +08:00

31 KiB
Raw Blame History

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)仍在,但已过时。

本仓库把上游的数据生命周期 + 控制台重做成 单二进制、零外部服务的形态:

层 技术栈 职责
后端 Rust 2021 + axum 0.8 + tokio 鉴权 / 会话 / 权限键 / 18 实体 CRUD / 聚合详情 / 账号层 / 静态托管
数据库 pglite-rs 0.2(进程内原生 PostgreSQL) 承载全部 tdc_* 业务表(30 张),数据落盘 data/tdc.pg/
前端 上游(Java/Vue)完整前端的构建产物,托管在 static/ 零自研前端、零构建步骤(scripts/build-frontend.sh 可重放)
账号层 本机 JSON 文件 data/accounts.json 顶替上游的 JNPF j7 账号库(上游完整前端的 JNPF 兼容登录)

pglite-rs ≠ 浏览器 PGlite。crate 名 pglite-rs、import 名 pglite;它把 postgres-pglite 编译成原生静态库链接进二进制, 是真实 PostgreSQL 语义(类型 / MVCC / 事务 / 扩展 / 线协议),进程内单 backend,无服务器、无 Docker、无 WASM。 浏览器端 WASM 版(@electric-sql/pglite + IndexedDB)曾是本项目的错误实现,已废弃删除,勿再引入。

顶层目录速览

tdc-rs/
├── Cargo.toml                # 依赖 + release 优化(lto=thin / strip / panic=abort)
├── Cargo.lock                # 锁定版本
├── src/
│   ├── main.rs               # 启动装配:PGlite open / 引导身份 / 账号库 / 路由 / 中间件 / 静态兜底
│   ├── lib.rs                # 模块声明(只暴露 `platform` 与 `tdc` 两层,bin 只做装配)
│   ├── platform/             # 【平台层】与业务**零**知识(边界由 check-boundary.sh 静态钉住)
│   │   ├── state.rs          # AppState(config + db + db_lock + sessions + accounts + bootstrap + tds)
│   │   ├── config.rs         # 环境变量配置 + 密钥守卫
│   │   ├── db.rs             # PGlite 封装(query_json / ensure_schema / f_↔camelCase 映射)
│   │   ├── session.rs        # 会话存储(两种 kind:Identity / Account)
│   │   ├── envelope.rs       # 业务信封 ActionResult(HTTP 200 + {code,msg,data})
│   │   ├── auth.rs           # 入向鉴权中间件 + 三道门 + 主体(Principal)
│   │   ├── cipher.rs         # 登录口令加解密(MD5 + AES-256-ECB,对齐上游 cipher.ts)
│   │   ├── 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(本地账号库)/ identity(身份域)
│       ├── 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 前缀 + 两套上游生成器)
│       ├── support/          # 业务侧公共清单(public_paths:免鉴权端点)
│       └── policy/ engine/ schedule/ notify/ heartbeat/ sso/   # 上游同名包占位(后续批)
├── static/                   # 上游 SPA 构建产物(index.html + logo.png + assets/,8 个产物文件)
├── schema/
│   └── migrate.sql           # tdc_* schema(include_str! 内嵌进二进制,**30 表**,**不在 web root**)
├── scripts/                  # build-frontend.sh / gen-migrate.sh / reset-data.sh
│                             # + **三把尺子**:smoke.sh(HTTP 契约)/ check-boundary.sh(边界静态)
│                             #   / check-entity.sh(实体静态)+ boundary-ledger.txt / upstream-json-ignore.tsv
├── tests/                    # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_gate / spa_fallback / bootstrap_fail / tds_biz)
├── docs/                     # 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md / CONSOLE-ACCEPTANCE.md)
│                             # + superpowers/(v3 spec / 执行提示词 / 上游差异表)
├── tds-stub/server.js        # TDS 契约桩(零依赖,仅供端到端调试)
└── data/                     # 运行期数据(tdc.pg/ + accounts.json,已 gitignore)

没有 build.rs / export_dynamic / 前端打包步骤 / Docker Compose / 外部数据库进程。

架构约定(红线)

  • 🔴 平台层 / 业务层边界(v3 spec §2.3):src/platform/ 里不许出现业务知识 ——业务表名(tdc_*)、实体名(Product / Resource / …)、具体端点路径(/api/ssw/tdc/…)、 业务表数量;src/tdc/ 里不许出现平台能力的第二份实现。 这条可被静态检查 ⇒ scripts/check-boundary.sh 的 4 个接触点(CP1–CP4)。 🔴 通用 CRUD 引擎住在业务层(tdc/mapper.rs + tdc/service/crud.rs + tdc/controller/crud.rs, 对位上游 TdcCrudController)但逻辑必须实体无关(零 match api_name) ⇒ 分支只能读 TableSpec 字段。
  • 🔴 前端不直接持有数据库。 所有数据访问经 /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。

命令速查

# 编译(自动走本机统一缓存:~/.cargo/registry 软链 + sccache)
cargo build                      # debug
cargo build --release            # 发布版

# 运行
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'

本机 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 scripts/smoke.sh            # ① HTTP 契约(真进程真 HTTP,零 node 依赖)→ PASS=75 FAIL=0
bash scripts/check-boundary.sh   # ② 边界静态(平台层不含业务知识)→ 账本制
bash scripts/check-entity.sh     # ③ 实体静态(加实体的接触点完整性)→ PASS=15 FAIL=0
尺子 覆盖 退出码
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 双向闭合 同上
  • 🔴 基线断言数 N = 75(2026-10-26,B1a 锁定)⇒ 后续每批只许增不许减; 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 / 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 资源 / 数据集聚合详情
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。

{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 禁删(可增可改)。

鉴权三道门(顺序与文案与上游一致)

门 通道 判据 失败
① 协议版本 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/tdc/entity/mod.rs 的 PERMISSION_KEYS 声明 18 条「实体 → 权限键」;权限键来自 tdc_identity.f_capability(domain::identity::capabilities())。

  • 能力集解析不出 ⇒ fail-open(本地单机模式没有能力集,不该把写操作全锁死)。
  • 解析出来 ⇒ 按键判定;* / all 放行。
  • 无凭证 ⇒ 403;内部令牌 ⇒ 放行;本地账号(Principal::Account)⇒ 放行(⚠️ 已知边界,见 ledger)。

关键实现细节(改代码前必读)

  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 兜底在 routes::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/tds/mod.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)。

数据模型

schema/migrate.sql(3017 行)是上游 tdc_* schema 的生成产物,30 张表:

域 表
身份 / 凭据 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

其中 24 张带齐 10 个系统列(f_id / f_tenant_id / f_sort_code + 创建·修改·删除审计列), 其余 6 张为精简变体;逻辑删除位为 f_delete_mark;21 个唯一索引中 14 个是 partial 唯一索引。

改 schema 时:migrate.sql 是编译期内嵌的,改完必须清空 data/ 重建(探针逻辑只在首次建表), 并同步更新 README 的表清单。

账号层(本地账号库)

  • src/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/cipher.rs 单测里的上游原始向量 (encryptPassword('123456'))+ tests/account_api.rs::login_accepts_the_upstream_literal_ciphertext —— 后者拿字面密文真打登录端点(改密钥它必红,不是自证自洽)。 浏览器侧也已验过(上游自己的 cipher.ts 加密后能登录 ⇒ 见 docs/CONSOLE-ACCEPTANCE.md §3.1)。
  • src/account.rs:JSON 文件 data/accounts.json + 进程内互斥锁;刻意不建 tdc_* 表 ⇒ migrate.sql 保持逐字节一致、/api/health 的 tables 恒为 30。 首启引导 admin / admin(⚠️ 本地调试默认值,对外部署前必须改掉)。 口令只存 md5(明文);update 不动口令;管理员账号不可删;落盘走 .tmp → rename,失败当业务失败抛出。
  • src/tdc/controller/account.rs:登录 + 用户管理 6 端点 + 管理员闸门 require_admin (连接器身份会话 / 管理员账号放行;内部令牌刻意 403,比上游严一档;查不到账号 ⇒ fail-closed 403)。

TDS 出向通道(P4)

  • src/tds/mod.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。

编译缓存(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" / panic="abort" / codegen-units=16。
  • 体积构成: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 用 routes::mw::json_method_not_allowed
DDL 能从 HTTP 下载 DDL 落在 web root 移到 schema/ + ddl_guard 两层兜底(Range 分段也要拦)
表名注入 直接拼表名 一律走 valid_table() + entity::validate()
两个实例共用 data/ 报 postmaster.pid 锁冲突 pglite 单实例独占数据目录 用不同目录/端口起第二个实例
并行测试互相撞车 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(整包型)
出向头被算成 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

明确不在本仓库范围

  • 上游那 100+ 个「动作端点」(发布 / 下架 / 提交审核 / 策略校验 / 同步资源 / 销毁 …)属 P2–P5,尚未实现 ⇒ 上游前端这些按钮点了会 404(分期的正常状态)。
  • 原 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_role / base_module 等)不引入 ⇒ 本仓的权限判定走声明式权限键(entity::PERMISSION_KEYS),不走菜单。

记忆约定

遵循项目级约定:踩坑清单与长 traceback 进 docs/(本文件表格即其索引),工作日志进 .workbuddy/memory/YYYY-MM-DD.md, 本文件只留「原则 + 决定 + 一句话摘要」。