Files
tdc-rs/README.md
T
adminandClaude Code 52074a136d docs(tds): 补齐 P4 出向通道的契约文档与项目指引
影响:
- `docs/TDC-TDS-CONTRACT.md` 由「P4 的输入清单」改写为「已落地契约」:
  只走 internal 通道、6 个固定出向头、10 个对外端点 → 出向 TDS 端点映射、
  降级三档、7 条刻意分歧、真 TDS 实测记录。
- `README.md` / `CLAUDE.md` 补上 10 个出向端点、两个环境变量、TDS 通道小节与踩坑行。

改动:
- 契约文档重写:新增「返回风格两套」「身份解析两套口径」「降级三档」三节,
  补录本仓 10 个端点与 TDS 侧 11 条原始返回的实测表。
- README:后端 API 表增 7 行、环境变量表增 `SSW_TDS_BASE_URL` /
  `SSW_TDS_INTERNAL_TOKEN`(令牌值只指向 `src/config.rs`,不入文档)。
- CLAUDE.md:目录树、红线、API 表、关键实现细节 13–14、TDS 出向通道小节、
  踩坑表 6 行、范围外声明同步。
- 计划文件:修正「12 条用例」为实际的 4 条用例(219 = 207 + 8 + 4),
  并记录实施后与上游的三处差异(空体可选、connectorId 取值宽松、query 传参)。
- 工作日志追加 P4 小节:4 个 commit、5 个变异自证表、真 TDS 实跑结果、3 个遗留项。

设计:
- 不改 `static/`:上游 SPA 的 serviceCatalog / billing 两个 api 对象要的正是
  这 10 个路径,后端补齐即可 ⇒ 前端一个字不动。
- 遗留 R10(`GET /api/ssw/tdc/Identity` 泄漏 `secretKey`,上游是 `@JsonIgnore`)
  与 R11(13 个文件的 rustfmt 漂移)本轮不修,超出 P4 范围,已登记。

Co-Authored-By: Claude Code <[email protected]>
2026-10-25 14:24:54 +08:00

226 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# TDC 数据接入连接器 · Rust + 上游前端 SPA + PGlite
把 `ssw-mvp/boot/ssw-tdc`(Spring Boot / JNPF 重底座的「数据接入连接器」子系统)重做成
**本地优先、零外部服务**的 MVP:
- **Rust (axum)** —— 控制面 + 数据面 + 静态托管
- **上游(Java/Vue)完整前端的构建产物** —— 托管在 `static/`,**零自研前端、零构建步骤**
- **PGlite(pglite-rs,进程内原生 PostgreSQL)** —— 内嵌在 Rust 进程里,承载全部 `tdc_*` 业务数据,
数据落在 `data/tdc.pg/`(磁盘持久化,非浏览器 WASM/IndexedDB)
> 关键点:PGlite 用的是 **pglite-rs**(`crate pglite-rs`,import 为 `pglite`)——
> 把 postgres-pglite 编译成原生静态库、链接进二进制,是**真实 PostgreSQL 语义**
> (类型 / MVCC / 事务 / 扩展 / 线协议),进程内单 backend 运行,无服务器、无 Docker。
> 前端只发 REST 请求,不直接持有数据库。
> 红线:原 TDC 与 TDS **只走 HTTP 契约、不编译期耦合**。
> 本实现**不代理** TDS(TDS 侧出向客户端属后续任务)。
> 🔴 上游前端登录走 JNPF 门户账号(`POST /api/oauth/Login`)——**本仓已实现**
> (JNPF 兼容面:口令用上游 `cipher.ts` 的 **AES-256-ECB 密文 hex** 传输,
> `grant_type=password`;`grant_type=maxkey` 如实报业务失败,**不伪装成功**)。
> 但**不引入 j7** ⇒ 用本连接器自己的**本地账号库** `data/accounts.json` 顶替
> (口令只存 `md5(明文)`,**永不回显**);首次启动自动引导一个管理员账号
> **`admin` / `admin`**(⚠️ **本地调试默认值**,可用
> `TDC_BOOTSTRAP_ADMIN_PASSWORD` 覆盖;对外部署前必须改掉)。
> 连接器身份登录(`/api/ssw/tdc/Auth/Login`)也仍然可用。
## 运行
```bash
cd tdc-rs
cargo build # 编译(自动走 sccache + 统一 registry 缓存)
PORT=30000 ./target/debug/tdc-connector
# 浏览器打开 http://localhost:30000
```
- 启动即初始化:Rust 进程内 `PGlite::open(data/tdc.pg)`,若 `tdc_identity` 不存在则执行
内嵌的 `schema/migrate.sql`(`include_str!` 进二进制,**30 张表**,上游 `tdc_*` schema 的生成产物)。
- 数据全部落在 Rust 进程内嵌库;控制台(上游 SPA)通过 `/api/ssw/tdc/*` 读写。
- schema DDL 在 `schema/migrate.sql`(**编译期内嵌**,**刻意不在 web root**)⇒ 不可从 HTTP 下载;
另有**两道兜底**(`src/routes/fallback.rs`):**路径级**(任意一段路径的扩展名经 Unicode
大写折叠后等于 `SQL` ⇒ 404 JSON)+ **内容级**(响应体是内嵌 DDL 的**整份或 `Range` 分段**
⇒ 404 JSON)。
## 控制台(前端)
前端 = **上游(Java/Vue)完整版的构建产物**,托管在 `static/`:
```
static/
├── index.html # SPA 外壳(vite base=/ ⇒ 引用 /assets/...)
├── logo.png
└── assets/ # index-*.js / index-*.css / tdc-*.js / vendor-*.js / Login-*.js …
```
- 产物由 `scripts/build-frontend.sh` 落盘(可重放;默认走「搬运已构建好的 dist」,
`SKIP_NPM=0` 才跑 `npm ci` + `VITE_SSW_APP=tdc npx vite build`)。
- **SPA 深链**(`/tdc/home`、`/login` …)回退到 `index.html`(200 `text/html`),前端路由接管。
- **`/api/**` 未命中**回 **404 + JSON**(`{"success":false,"code":404,"msg":"接口不存在"}`),
**不是** SPA 的 HTML —— 前端 axios 错误分支据此显示「接口不存在」;
若回 HTML,前端会判 `body.code === undefined` 而**不 reject** ⇒ 静默渲染空表,
把「接口没了」误读成「没有数据」。
- 🔴 保留红线:**前端不直接持有数据库**(它只发 REST 请求)。
- ✅ **浏览器级实测**(2026-10-25):17 个路由逐个点过 —— 登录 / 鉴权 / 写路径 /
管理员闸门 / 逻辑删除全部按上游预期工作;两个 **TDS 代理页**(服务目录 / 我的账单)
按规划 404(属 P4)。逐页结果与踩坑见 **`docs/CONSOLE-ACCEPTANCE.md`**。
## 编译缓存(按 dev-cache-layout 规范)
本机已统一:`~/.cargo/registry` → `~/.cache/cargo/registry`(软链),
sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCCACHE_DIR`
启用,缓存实体在 `~/.cache/sccache`(经 `~/Library/Caches/Mozilla.sccache` 软链透明访问)。
`cargo build` 直接命中,无需额外操作。`pglite-rs` 为预编译原生库,依赖编译结果一并入缓存。
## 后端 API
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/health` | 健康检查(`tables: 30`) |
| 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 配置(上游前端登录页用) |
| POST | `/api/oauth/Login` | **JNPF 兼容登录**(`application/x-www-form-urlencoded`:`account` / `password`(**密文 hex**) / `grant_type=password`)|
| GET | `/api/permission/Users` | 用户管理 · 列表(分页 + 关键字;**仅管理员**)|
| POST | `/api/permission/Users` | 用户管理 · 新建(**仅管理员**;初始口令 `123456`)|
| PUT | `/api/permission/Users/{id}` | 用户管理 · 改资料(**仅管理员**)|
| DELETE | `/api/permission/Users/{id}` | 用户管理 · 删账号(**仅管理员**;管理员账号不可删)|
| POST | `/api/permission/Users/{id}/Actions/ResetPassword` | 重设口令(收 `md5(明文)`;**仅管理员**)|
| PUT | `/api/permission/Users/{id}/Actions/State` | 启用 / 禁用(`enabledMark`;**仅管理员**)|
| GET / POST | `/api/ssw/tdc/{Entity}` | 18 个实体的列表 / 新建 |
| GET | `/api/ssw/tdc/{Entity}/All` | 不分页全量 |
| GET / PUT / DELETE | `/api/ssw/tdc/{Entity}/{id}` | 详情 / 修改 / 逻辑删除 |
| GET | `/api/ssw/tdc/Resource/{id}/Detail`、`/api/ssw/tdc/Dataset/{id}/Detail` | 资源 / 数据集聚合详情 |
| GET | `/api/ssw/tdc/ServiceCatalog` | **服务目录**(出向 TDS `Catalog/Internal/Catalog`) |
| POST | `/api/ssw/tdc/ServiceCatalog/Buy`、`/api/ssw/tdc/ServiceCatalog/BuyBatch` | **目录下单**(出向 TDS `TradeOrder/Internal/Apply` / `ApplyBatch`) |
| GET | `/api/ssw/tdc/Billing/List` | **本方账单列表**(出向 TDS `BillingLedger/Internal/List`) |
| PUT | `/api/ssw/tdc/Billing/{id}/Dispute`、`/Confirm`、`/Settle`、`/Receipt` | **账单动作**(出向 TDS `BillingLedger/{id}/*`;带越权自检) |
| GET | `/api/ssw/tdc/Billing/{id}/Voucher` | **对账凭证**(出向 TDS `BillingLedger/{id}/Voucher`) |
| GET | `/api/ssw/tdc/Billing/LocalCompare?contractId=` | **本地计量比对**(读本地 `tdc_api_consume_log`,**零出向**) |
> 🔴 上表最后 7 行 = **P4 TDS 出向通道**(照抄上游新版 TDC 的 `ServiceCatalogController` +
> `BillingController`)。完整契约(出向路径 / 6 个固定头 / 降级三档 / 刻意分歧 / 实测表)见
> **`docs/TDC-TDS-CONTRACT.md`**。
`{Entity}` 的 18 个全名:
`ApiConsumeLog` / `AuditLog` / `Contract` / `Credential` / `DataInterface` / `Dataset` /
`Datasource` / `DeliveryLog` / `DeliveryTask` / `DestroyLog` / `Identity` / `Notification` /
`Order` / `Policy` / `PolicyCheckLog` / `PolicyTemplate` / `Product` / `Resource`
> ⚠️ 写入能力**按实体分档**(真值见 `src/registry.rs` 的 `no_create` / `no_update` / `no_delete`):
> `Dataset` 是 `tdc_resource` 的**只读视图**(禁增/改/删);
> `ApiConsumeLog` 全只读;`AuditLog` 禁改禁删(可增);
> `DeliveryTask` / `DestroyLog` 禁增禁删(可改);
> `Contract` / `DeliveryLog` / `PolicyCheckLog` 禁删(可增可改)。
> 鉴权:`X-Internal-Token`(内部令牌通道)或 `X-Auth-Token` / `Authorization: bearer <token>`(会话通道)。
> 业务失败一律 **HTTP 200 + `{code,msg,data}`**;鉴权失败是另一种形状:
> **HTTP 401/403 + `{"success":false,"code":401,"msg":"…"}`**(**无 `data` 键**)。
> 内部库为单 in-process backend,所有 DB 访问由 `tokio::Mutex` 串行化。
**鉴权三道门**(顺序与文案与上游一致):
| 门 | 载体 | 失败文案 |
|---|---|---|
| ① 协议版本 | `X-Protocol-Version` | 401「跨端协议版本不兼容,请升级对端」 |
| ② 内部令牌 | `X-Internal-Token`(**只看头**,不收 query/body) | 401「内部接口凭证无效」 |
| ③ 会话令牌 | `X-Auth-Token` 或 `Authorization: bearer <token>` | 401「内部接口凭证无效」 |
**写操作的权限键**(`src/registry.rs` 的 `PERMISSION_KEYS`,18 条「实体 → 权限键」):
- 权限键来自 `tdc_identity.f_capability`(`domain::identity::capabilities()`)。
- 能力集**解析不出** ⇒ **fail-open**(本地单机模式没有能力集,不该把写操作全锁死);
**解析出来** ⇒ 按键判定,`*` / `all` 通配放行。
- 无凭证 ⇒ 403;内部令牌 ⇒ 放行;**本地账号 ⇒ 放行**(⚠️ 已知边界,见 `.superpowers/sdd/` ledger)。
- 🔴 `TDC_STRICT_SECRETS=1` ⇒ 默认口令视为不安全 ⇒ **启动即失败**:
内部令牌等于公开默认值即拒绝;**且**本地管理员仍在用默认口令 `admin` 也拒绝
(口令改过、或用 `TDC_BOOTSTRAP_ADMIN_PASSWORD` 引导过 ⇒ 放行)。
**首次启动的本地管理员**:默认 `admin` / `admin`(⚠️ **本地调试默认值**)。
可用环境变量在**空库首次引导**时覆盖(**已有账号库时不再生效**,改密请走用户管理页):
| 环境变量 | 作用 | 默认 |
|---|---|---|
| `TDC_BOOTSTRAP_ADMIN_ACCOUNT` | 引导的管理员**账号名** | `admin` |
| `TDC_BOOTSTRAP_ADMIN_PASSWORD` | 引导的管理员**口令** | `admin`(公开默认值) |
| `SSW_TDS_BASE_URL` | **TDS 出向基地址**(P4);**留空 ⇒ NOOP 模式**(本地单机,不发任何出向请求) | 空(NOOP) |
| `SSW_TDS_INTERNAL_TOKEN` | 出向 `X-Internal-Token` 头的值(🔴 与**入向** `SSW_INTERNAL_TOKEN` **不同源**,方向相反别混用) | 见 `src/config.rs` 的 `DEFAULT_TDS_INTERNAL_TOKEN`(公开默认值) |
## 已实现范围
**30 张表**(上游 `tdc_*` schema 的生成产物):其中 **24 张**带齐 **10 个系统列**
(`f_id` / `f_tenant_id` / `f_sort_code` + 创建·修改·删除审计列),
其余 **6 张**为精简变体(`tdc_data_interface_field` / `tdc_data_interface_param` /
`tdc_resource_field` / `tdc_resource_mask_rule` 只有 `f_id` + `f_sort_code`,
`tdc_demo_insurance_claims` 只有 `f_id`,`tdc_delivery_outbox` 无系统列);
逻辑删除位为 `f_delete_mark`;**21** 个唯一索引中 **14** 个是 partial 唯一索引:
| 域 | 表 |
|---|---|
| 身份 / 凭据 | `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` |
**控制台能力**(**当前只实现通用读取 + 按实体分档的写入,以及聚合详情**):
- 18 个实体的**通用读取**:`列表` / `详情` / `/All`(不分页全量)
+ **按实体分档**的写入(`新建` / `修改` / `逻辑删除`)——
`Dataset` 是 `tdc_resource` 的只读视图;`AuditLog` / `DeliveryLog` / `DeliveryTask` /
`DestroyLog` / `PolicyCheckLog` / `Contract` / `ApiConsumeLog` 带写保护,详见 `src/registry.rs`
- 2 个聚合详情:`/api/ssw/tdc/Resource/{id}/Detail`、`/api/ssw/tdc/Dataset/{id}/Detail`
- 4 个 `Auth` 端点:`Auth/Login`、`Auth/Me`、`Auth/Spaces`、`Auth/SsoConfig`
- **JNPF 兼容登录 + 本地账号管理**(上游完整控制台的真登录链):
`POST /api/oauth/Login` + `/api/permission/Users*` 6 个端点(**仅管理员**),
账号库存本机 `data/accounts.json`(**不进数据库** ⇒ 30 表口径不变)
- `GET /api/health`
> 🔴 **上游那 100+ 个「动作端点」(发布 / 下架 / 提交审核 / 通过 / 驳回 / 签署 / 生效 / 终止 /
> 策略校验 / 测试连接 / 同步资源 / 启用停用 / 完成 / 取消 / 销毁 …)属后续分期,尚未实现**。
> 本仓**不提供**这些动作端点的占位实现 ⇒ 请求的实际表现分两种:
> - **两段式**(`/{Entity}/{id}/{Action}`,如 `/api/ssw/tdc/Product/{id}/Offline`)⇒ **404 + JSON**;
> - **单段式**(`/{Entity}/{Action}`,如 `/api/ssw/tdc/Product/publish`)⇒ 被详情路由
> `/{Entity}/{id}` 吃掉,`publish` 被当成 id ⇒ **GET** 得到 **200** 业务信封
> 『记录不存在或已删除』;**POST** 则该路径只注册了 `GET`/`PUT`/`DELETE`
> ⇒ **405**(由 `src/routes/mw.rs` 改写成业务信封,**保留 `Allow` 头**)。
## 明确不在 MVP 内(原 `ssw-tdc` 的隐私计算作业)
原 `NaxJob / Nax2PJob / TeeJob / Sandbox / Privacy / AnnotationTask / Notebook / VizChart /
Quality* / HostingJob` 等控制器依赖 **Nax 隐私计算引擎**与 **scard 安全平面(软 PKI / 软 TPM)**,
未纳入本次重做。若需这部分,应保留原 Java/Scala 服务,或将其作为独立后端通过 HTTP 契约接入本连接器。
另外两个上游控制台页面依赖 **TDS 侧数据**(本仓不代理 TDS ⇒ 404 `接口不存在`,属 P4):
`/tdc/service-catalog`(`ServiceCatalog` ⇒ 代理 TDS 目录查询)与
`/tdc/billing`(`Billing/List` ⇒ 账单在 TDS 侧)。二者**本地无表**,
契约清单见 `docs/TDC-TDS-CONTRACT.md`。
## 目录
```
tdc-rs/
├── Cargo.toml # 含 pglite-rs = "0.2"
├── src/
│ ├── main.rs # 启动装配:内嵌 PGlite + 引导身份 + 账号库 + 路由 + 中间件 + 静态兜底
│ ├── lib.rs # 模块声明(业务逻辑都在 lib,bin 只做装配)
│ ├── auth.rs / session.rs # 鉴权中间件 + 三道门 / 会话存储(身份会话 / 账号会话)
│ ├── registry.rs / crud.rs # 18 实体注册表 + 权限键 / CRUD 引擎(写操作二次校验)
│ ├── envelope.rs # 业务信封 ActionResult(HTTP 200 + {code,msg,data})
│ ├── account.rs / cipher.rs# 本地账号库(JSON 文件)/ 登录口令加解密(对齐上游 cipher.ts)
│ └── routes/ # 按域装配:health / auth / account / crud / body / mw(405 改写)/ fallback(404 + SPA 兜底 + DDL 守卫)
├── static/ # 上游 SPA 构建产物(index.html + logo.png + assets/)
├── schema/
│ └── migrate.sql # tdc_* schema(include_str! 内嵌进二进制;**不在 web root**;30 表)
├── scripts/ # build-frontend.sh(前端产物)/ gen-migrate.sh(schema 生成)/ reset-data.sh
├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_gate / spa_fallback / bootstrap_fail)
├── docs/ # 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md / CONSOLE-ACCEPTANCE.md)
├── tds-stub/ # 本地 TDS 契约桩(零依赖,仅供端到端调试)
└── data/ # 运行期数据(tdc.pg/ + accounts.json,已 gitignore)
```