- 新增 scripts/fetch-platform.sh:读 .sspf-version 解包 vendor/ + 生成 .cargo/config.toml(rustflags + rustdocflags),只校工具链 channel - Cargo.toml 的 [dependencies]/[dev-dependencies] 清空:17 个 crate 全部 --extern 自平台闭包 - release profile lto 由 thin 改 false(平台 rlib bitcode-free,开 LTO 找不到 __bitcode) - tower-http 不在闭包 ⇒ 自研 platform::static_files(ServeDir 等价,含 Range 206)与 platform::cors(permissive 等价) - reqwest 与 extern tokio 双 runtime 必 panic(no reactor running)⇒ 自研 platform::http(HTTP/1.1 明文) - tests/auth_flow 的 reqwest 调用改用 lib 客户端;tds_biz 的头白名单补 connection - 新增尺子 check-platform-package.sh:依赖单一来源 + 真编一次证明平台闭包零重编 - 验收:cargo test 306 passed / 七把尺子 + 新尺子全绿;dev 构建 2.5s 只编本仓
227 lines
16 KiB
Markdown
227 lines
16 KiB
Markdown
# 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
|
||
bash scripts/fetch-platform.sh # 🔴 首次/换机/升级平台包:取预编译 rlib 包(生成 .cargo/config.toml)
|
||
cargo build # 编译(自动走 sccache + 统一 registry 缓存;平台闭包零重编,~2.5s)
|
||
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)
|
||
```
|