- 新增 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 端点契约与响应形状未变
56 KiB
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—— axummerge要求状态同型, 且两套路由有 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。
命令速查
# 编译(自动走本机统一缓存:~/.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 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 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.mdL8。 - 🔴 基线断言数 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.mdL3。
鉴权三道门(顺序与文案与上游一致)
| 门 | 通道 | 判据 | 失败 |
|---|---|---|---|
| ① 协议版本 | 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.mdL4。 - 🔴 只读/只写分档仍在:
no_create/no_update/no_delete(src/tdc/entity/mod.rs)。 - 🔴 部署退出门槛:账号发放只给受信人(默认口令
admin公开已知;TDC_STRICT_SECRETS=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(),不要另起逐类型分支。 - 单 backend 串行化:pglite 是单 in-process backend,所有 DB 访问必须持
state.db_lock(tokio::Mutex)。 - 表名白名单:
valid_table()只允许[A-Za-z][A-Za-z0-9_]*,任何拼接表名的地方都要走它;entity::validate()在启动时自检全部拼进 SQL 的标识符(不过白名单 ⇒ 秒退)。 - 路径与 cwd 解耦:
resolve_project_dir()从可执行文件向上找含static/index.html的目录,static/与data/都基于它,不要改成相对 cwd(后台启动时会 500)。 include_str!路径相对src/platform/db.rs:写../../schema/migrate.sql,不是../schema/。- camelCase ↔ snake_case:请求结构体一律加
#[serde(rename_all = "camelCase")]。 🔴 例外:/api/oauth/Login的表单字段名就是grant_type(上游送的就是这个)⇒ 不能加 camelCase (加了字段永远为None),改用#[serde(default, alias = "grantType")]。 - axum 0.8 的
Router<S>语义:S是「还缺什么状态」;with_state把状态烤进当前已有的 endpoint。 ⇒build_router返回Router<AppState>,由main.rs在挂完静态兜底与中间件之后统一with_state收口。 Form<T>在 axum 0.8.9 只实现FromRequest(没有OptionalFromRequest)⇒Option<Form<T>>编译不过 ⇒ 需要「解析失败也走业务信封」的表单端点,取原始 body 自己用serde_urlencoded::from_bytes解析。- 405 的 JSON 兜底在
platform::mw::json_method_not_allowed(响应改写中间件,挂链尾), 不是 axum 的method_not_allowed_fallback(后者只对调用那一刻已注册的路由生效,且丢Allow头)。 - schema 初始化:启动时探测
tdc_identity是否存在,不存在才按;拆分执行migrate.sql。 ecb0.1 只实现*_block_mut(原地改块)⇒ 用encrypt_block_mut/decrypt_block_mut,不是encrypt_block。- 同一文件的多个 Edit 必须串行(并行 Edit 会 last-writer-wins 静默覆盖)。
- 出向 TDS 判定成功必须看
body.code == 200(TDS 业务失败也是 HTTP 200)。 解包型端点用tds::unwrap_data、整包型用tds_biz::unwrap_envelope—— 别混用。 - 出向请求只带 6 个应用层头(
src/tdc/client/tds.rs的internal_headers());reqwest会自己加host/content-length/accept⇒ 断言「头数」时别把这三个算进去。 - 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)。 - 引导身份要显式递业务配置(C8):
identity::bootstrap_identity(state, &tdc_config)——身份码/身份名/身份密钥不在state.config里 ⇒ 由装配层(main.rs)造TdcConfig::from_env()递进去。TdcConfig::from_raw(..)是纯函数(不读全局 env)⇒ 可单测。 - 状态两半的取法(C9):业务层
TdcStatederef 到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)。 - 领域 SQL 归业务服务层(C10):
tdc_identity的领域 SQL 全部住在src/tdc/service/identity.rs(控制器层不再自己拼)⇒ 领域查询只 SELECT 明确列, 永不SELECT *(别把f_secret_key整行拖进内存)。 🔴tdc_identity因此有两条读写路径(领域 SQL + 通用 CRUD 引擎)⇒ 已记进docs/known-limitations.mdL1(上游无「通用引擎」概念,硬收会失真 ⇒ 显式承认 + 收口)。 - 常量时间比较只有一份实现(C11):实现住在
src/platform/compare.rs; 业务侧(tdc::service::identity/tdc::service::account)用pub use crate::platform::compare::constant_time_eq;复用 ⇒ 不许再抄一份。 - 时间口径分两套,不是随手写的(C12):仓里不再手写日历算法,一律
chrono;- 服务器本地时区(
chrono::Local):业务编码(tdc/util/code.rs)与 DB 审计列(SQLnow()) ⇒ 必须与上游 JavaLocalDateTime.now()/ MySQLnow()同口径(否则编码日期段差一天); - UTC(
chrono::Utc):账号库自己的审计字段(tdc/service/account.rs::now_iso)——本仓自有格式,无上游对照物。 🔴 完整对照表 + 「别把 Local 写成 UTC / 别把 UTC 写成 Local」见docs/contract.md§时间口径。
- 服务器本地时区(
- 子表挂载面逐父子不同(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§子表聚合。
- 🔴 父行取值列不一定是
- 生产档弱密钥守卫是纯函数**(上游
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.mdD22。
- 🔴 六条判据:①键不在 map⇒跳过 ②值为 null/空白⇒违规 ③值精确等于弱值⇒违规
④值含弱值⇒违规(反绕过:默认值加个后缀也拦住)⑤值命中弱标记词⇒违规 ⑥长度<12⇒违规。
只实现 ③ 而漏 ④ ⇒ 把默认值改成
- 出向 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.mdD23。
- 🔴 只有 cause 链里有超时(
数据模型
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.mdL2)。
改 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)。
- 口令公式(官方双 md5):
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.mdD20/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),不是对象。
- 出向头正好 6 个(
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.mdL5; 「吞掉」这条见 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 通道。 已永久下线(旧 Bridge 通道,⇒ 404)⇒ 别再复活。/api/ssw/tdc/tds/*代理网关- JNPF 角色 / 菜单 / 授权模型(j7 的
base_module/base_authorize/base_organize等)不引入 ⇒ 本仓的权限判定走上游三件套(登录态 / 角色码 / 管理员位),不走菜单。 角色码只用了base_role/base_role_relation两张表(D6/D20)。
记忆约定
遵循项目级约定:踩坑清单与长 traceback 进 docs/(本文件表格即其索引),工作日志进 .workbuddy/memory/YYYY-MM-DD.md,
本文件只留「原则 + 决定 + 一句话摘要」。