Files
tdc-rs/README.md
T
adminandClaude Code e475137366 feat(auth): 本地账号层 + JNPF 兼容登录,上游完整控制台可登录
- cipher.rs:MD5 + AES-256-ECB,与上游前端 cipher.ts 逐字对齐(含上游自检向量)
- account.rs:本地账号库存 data/accounts.json(不建 tdc_* 表,30 表口径不变),首启引导 admin
- 新增 POST /api/oauth/Login(grant_type=password)与 /api/permission/Users*(仅管理员)
- AppState 增 accounts 字段与 with_accounts 构造器
- 账号登录走 SessionKind::Account,Auth/Me 返 accessAllowed + account
- README:订正「/api/oauth/Login 尚未实现」并补新端点表

Co-Authored-By: Claude Code <[email protected]>
2026-10-25 11:23:12 +08:00

170 lines
11 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`**(⚠️ **本地调试默认值**,对外部署前必须改掉)。
> 连接器身份登录(`/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 请求)。
## 编译缓存(按 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` | 资源 / 数据集聚合详情 |
`{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` 串行化。
## 已实现范围
**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`
- `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 契约接入本连接器。
## 目录
```
tdc-rs/
├── Cargo.toml # 含 pglite-rs = "0.2"
├── src/
│ ├── main.rs # axum:内嵌 PGlite + 路由装配 + 中间件
│ └── routes/ # 按域装配:health / auth / crud / mw(405 改写)/ fallback(404 + SPA 兜底)
├── static/ # 上游 SPA 构建产物(index.html + logo.png + assets/)
├── schema/
│ └── migrate.sql # tdc_* schema(include_str! 内嵌进二进制;**不在 web root**)
├── scripts/ # build-frontend.sh(前端产物)/ gen-migrate.sh(schema 生成)/ reset-data.sh
├── docs/ # 补充文档
├── tds-stub/ # 本地 TDS 契约桩(零依赖,仅供端到端调试)
└── data/ # 运行期数据(tdc.pg/,已 gitignore)
```