# 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` 交给业务仓,但没把 `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`(字段直取) + `impl FromRef for AppState`(axum 里 `State` 可用)。 - 🔴 **平台配置与业务配置分家**(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/` · 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 ` | 命中会话(**身份会话** 或 **本地账号会话**) | 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 () q` 包成单列文本, 后端 `rows[i].get::>(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` 是「还缺什么状态」;`with_state` 把状态烤进**当前已有**的 endpoint。 ⇒ `build_router` 返回 `Router`,由 `main.rs` 在挂完静态兜底与中间件**之后**统一 `with_state` 收口。 8. **`Form` 在 axum 0.8.9 只实现 `FromRequest`**(没有 `OptionalFromRequest`)⇒ `Option>` **编译不过** ⇒ 需要「解析失败也走业务信封」的表单端点,取**原始 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`(靠 `impl FromRef 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>` 编译不过 | 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 )`(`src/tdc/service/account.rs` 的 `p()` 助手);空串要落 NULL 时再包 `NULLIF(...,'')` | | 账号层改成 DB 后 `mobilePhone`/`description` 从 `null` 变 `""` | 存了空串 | 用 `NULLIF(,'')` ⇒ 空串落 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`**, 本文件只留「原则 + 决定 + 一句话摘要」。