- 新增 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 端点契约与响应形状未变
609 lines
56 KiB
Markdown
609 lines
56 KiB
Markdown
# 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`**,
|
||
本文件只留「原则 + 决定 + 一句话摘要」。
|