Files
tdc-rs/AGENTS.md
T
xstudio 885b108fe0 init: TDC 连接器 Rust MVP(pglite-rs 内嵌 + 静态 HTML 控制台)
从 ssw-mvp/boot/ssw-tdc(Spring Boot/JNPF,37 Controller)剥离重底座的本地优先实现:
- axum 单进程承担控制面/数据面/静态托管/TDC→TDS HTTP 契约网关
- pglite-rs 0.2 内嵌原生 PostgreSQL(进程内,非浏览器 WASM),19 张 tdc_* 表
- 静态 HTML + 原生 JS 控制台:schema 自省驱动 CRUD + 按表生命周期动作
- 红线:TDC↔TDS 只走 HTTP 契约,未配 SSW_TDS_BASE_URL 时 Noop 降级
- AGENTS.md 记录架构红线、命令速查与踩坑清单;docs/ 记录跨方契约细节
2026-10-24 10:31:06 +08:00

197 lines
12 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.
# AGENTS.md
This file provides guidance to AI coding agents (CodeBuddy / Claude Code / Cursor / Codex 等) when working in this repository.
## 项目定位
**TDC 连接器(tdc-rs)** —— 尚数网可信数据空间中「数据接入连接器(TDC)」子系统的**本地优先 Rust 重实现**。
上游真源是 `~/Desktop/workspace/ssw-mvp/boot/ssw-tdc`(Spring Boot 3 + JNPF 7.0 + Java 21,37 个 Controller)。
本仓库把它的**核心数据生命周期**剥离出 JNPF 重底座,重做成 **单二进制、零外部服务**的形态:
| 层 | 技术栈 | 职责 |
|---|---|---|
| 后端 | Rust 2021 + axum 0.8 + tokio | 控制面 + 数据面 + 静态托管 + TDC→TDS HTTP 契约网关 |
| 数据库 | `pglite-rs` 0.2(进程内原生 PostgreSQL) | 承载全部 `tdc_*` 业务表,数据落盘 `data/tdc.pg/` |
| 前端 | 静态 HTML + 原生 ESM JS,零构建 | 操作员控制台:schema 自省驱动的通用 CRUD + 生命周期动作 |
| 调试对端 | 零依赖 Node(`tds-stub/`) | 无真 TDS 时提供 TDS 契约桩 |
> **pglite-rs ≠ 浏览器 PGlite**。crate 名 `pglite-rs`、import 名 `pglite`;它把 postgres-pglite 编译成原生静态库链接进二进制,
> 是**真实 PostgreSQL 语义**(类型 / MVCC / 事务 / 扩展 / 线协议),进程内单 backend,**无服务器、无 Docker、无 WASM**。
> 浏览器端 WASM 版(`@electric-sql/pglite` + IndexedDB)曾是本项目的错误实现,已废弃删除,勿再引入。
## 顶层目录速览
```
tdc-rs/
├── Cargo.toml # 依赖 + release 优化(lto=thin / strip / panic=abort)
├── Cargo.lock # 锁定版本
├── src/main.rs # 全部后端逻辑(769 行,单文件)
├── static/
│ ├── index.html # SPA 外壳(无 import map、无构建产物)
│ ├── app.js # 通用 CRUD + 生命周期动作(465 行)
│ ├── style.css
│ └── migrate.sql # tdc_* schema(include_str! 内嵌进二进制,19 表)
├── tds-stub/server.js # TDS 契约桩(仅调试用,非产品)
├── docs/ # 补充文档
└── data/ # 运行期数据(tdc.pg/ + node-identity.json,已 gitignore)
```
**没有** `build.rs` / `export_dynamic` / 前端打包步骤 / Docker Compose / 外部数据库进程。
## 架构约定(红线)
- 🔴 **TDC 与 TDS 只走 HTTP 契约,绝不编译期耦合。** 跨系统读写一律经 `/api/ssw/tdc/tds/{*path}` 代理网关;
未配置 `SSW_TDS_BASE_URL` 时降级为 **Noop(HTTP 501)**,对应原 `TdcTdsClient` → `NoopTdcTdsClient`。
禁止在本仓库引入任何 TDS 侧的 Service / Entity / Mapper 概念或直连 TDS 数据库。
- 🔴 **前端不直接持有数据库。** 所有数据访问经 `/api/db/*` REST;不得把 PGlite 重新塞回浏览器。
- 🔴 **业务错误必须读 body 的 `code`。** 真实 TDS 用 HTTP 200 承载业务错误码(如 `code:600` 登录过期),
只看 HTTP 状态会把失败误判成成功。
- 🔴 **私钥不得外泄。** `NodeIdentity.private_key` 只落盘 `data/node-identity.json`,
API 一律经 `identity_view()` 返回去敏后的公开视图(`#[serde(skip_serializing)]` 会让落盘 JSON 缺字段导致回读失败,**不要用**)。
## 命令速查
```bash
# 编译(自动走本机统一缓存:~/.cargo/registry 软链 + sccache)
cargo build # debug
cargo build --release # 发布版,约 2 分钟
# 运行
PORT=30000 ./target/debug/tdc-connector
SSW_TDS_BASE_URL=http://127.0.0.1:30040 PORT=30000 ./target/debug/tdc-connector # 接真实 TDS
cd tds-stub && node server.js # 无 TDS 时起契约桩(:30100)
# 冒烟
curl -s http://127.0.0.1:30000/api/health
curl -s http://127.0.0.1:30000/api/db/tables | head -c 200
```
> 本机 curl 走系统代理,**测 localhost 必须加 `--noproxy '*'`**,否则会得到 502。
> 后台常驻进程必须用 Bash 工具的 `run_in_background` 托管;`nohup ... &` 在工具调用返回后会被回收。
## 后端 API
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/health` | 健康检查(含 `tds_mode` / `tds_base_url` / db 模式) |
| GET | `/api/db/tables` | 列出 public schema 下所有表 |
| GET | `/api/db/table/{name}/columns` | 列信息(表名白名单校验,防注入) |
| GET | `/api/db/table/{name}/rows?limit=` | 行数据(`SELECT * LIMIT n`,默认 200 / 上限 1000) |
| POST | `/api/db/query` | 只读查询 → JSON 数组 |
| POST | `/api/db/exec` | 写操作(INSERT/UPDATE/DELETE/DDL) |
| GET/POST | `/api/ssw/tdc/node/identity` | 连接器身份(读 / ed25519 签发) |
| POST | `/api/ssw/tdc/node/identity/register` | 向 TDS 注册;真 TDS 无该端点则返回 `UNSUPPORTED_BY_TDS` |
| POST | `/api/ssw/tdc/node/identity/heartbeat` | 心跳(置 ONLINE;配 base-url 时一并上报 TDS `NodeReport`) |
| ANY | `/api/ssw/tdc/tds/{*path}` | TDC→TDS 契约代理(无 base-url → 501 Noop) |
### 关键实现细节(改代码前必读)
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_]*`,任何拼接表名的地方都要走它。
4. **路径与 cwd 解耦**:`resolve_project_dir()` 从可执行文件向上找含 `static/index.html` 的目录,
`static/` 与 `data/` 都基于它,**不要改成相对 cwd**(后台启动时会 500)。
5. **`include_str!` 路径相对 `src/main.rs`**:写 `../static/migrate.sql`,不是 `../../static/`。
6. **逐跳头剥离**:代理转发必须跳过 `host/content-length/connection/transfer-encoding/upgrade/keep-alive/te/trailer`;
`Bridge/**` 由代理统一注入 `App-Code: tdc`,并丢弃客户端自带的该头。
7. **camelCase ↔ snake_case**:请求结构体一律加 `#[serde(rename_all = "camelCase")]`,否则 `orgName`/`endpoint` 恒为 null。
8. **schema 初始化**:启动时探测 `tdc_identity` 是否存在,不存在才按 `;` 拆分执行 `migrate.sql`。
## 数据模型
`static/migrate.sql` 忠实移植原 `ssw-mvp/boot/db/tdc/V1.0.0__tdc_schema.sql`,**19 张表**:
身份 / 数据源 / 资源 / 资源字段 / 脱敏规则 / 数据产品 / 数据需求 / 订单 / 合约 / 使用控制策略 /
策略校验记录 / API 交付服务 / 交付任务 / 交付日志 / TDS 同步日志 / 审计日志 / 环境空间 / 成员 / 机密文件,
另含 6 条内置脱敏规则与默认开发环境空间。列名沿用原 JNPF 约定(`f_` 前缀 + 9 个系统列 + 逻辑删除位)。
**改 schema 时**:`migrate.sql` 是编译期内嵌的,改完必须清空 `data/` 重建(探针逻辑只在首次建表),
并同步更新 README 的表清单。
## 控制台能力
schema 自省驱动的通用 CRUD(新建 / 编辑 / 逻辑删除 / 搜索,全部 19 表)+ 按表生命周期:
| 表 | 动作 |
|---|---|
| `tdc_product` | 发布 / 下架 / 提交审核 |
| `tdc_order` | 通过 / 驳回 / 签署 |
| `tdc_demand` | 发布 / 关闭 |
| `tdc_contract` | 生效 / 终止 |
| `tdc_resource` | 启用 / 停用 |
| `tdc_datasource` | 测试连接 / 同步资源 |
| `tdc_delivery_task` | 策略校验(写 `tdc_policy_check_log`)/ 完成 / 取消 / 销毁(留证写 `tdc_delivery_log`) |
## 编译缓存(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"` / `panic="abort"` / `codegen-units=16`。
- 体积构成:二进制 **27 MB**(主体是内嵌的 PostgreSQL 引擎)+ static 64 KB → **tar.gz 约 11 MB**。
对照真实 TDS 的 `ssw-admin` fat jar **368 MB** + 目标机装 JVM + PostgreSQL 四库 + Redis。
- 首次启动生成 `data/tdc.pg` 约 38 MB(运行期数据,不随包分发)。
## 对接真实 TDS(`ssw-mvp/boot/ssw-admin`)
TDS **不是独立服务**,而是 `ssw-admin` 的角色 profile:
```bash
# 1) 打包:-pl 时父 pom 的 activeByDefault 不传播到子模块,必须显式 -P full 才把 ssw-tds 打进 fat jar
mvn -f boot/pom.xml -P full -pl ssw-admin -am package -DskipTests
# 2) 运行(端口避开连接器的 30000;中和本机未启的外部依赖)
DB_HOST=127.0.0.1 DB_PORT=15432 REDIS_HOST=127.0.0.1 REDIS_PORT=16379 \
java -Xmx2g -jar boot/ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar \
--spring.profiles.active=dev,full --server.port=30040 \
--fisco.enabled=false --k8s.enabled=false --kbs.url= \
--ssw.security-plane.base-url=http://127.0.0.1:1
```
依赖本机已有容器 `jnpf-postgres`(15432) / `jnpf-redis`(16379) 与 `j7 / tdc / tds / sswflow` 四库(PostgreSQL)。
启动约 30s;跨方算力(30011)、scard 安全平面(8443) 未启只报非致命告警。
**真实 TDS 契约要点**:
- `Bridge/**` 需请求头 **`App-Code: tdc`**(`TdsBridgeInternalController` 白名单只放行 `tdc`);
`X-Internal-Token` 仅在 `tds.internal-secret` 非空时校验(默认空 = 免 token)。
- 业务错误走 HTTP 200 + body `code`。
- **无 `POST /Connector/Register`**(连接器由运营方 CRUD 侧建档)→ 连接器如实返回 `UNSUPPORTED_BY_TDS`。
- 审计/留痕:`POST {base}/api/ssw/tds/Bridge/{AuditChain,ChainEvidence,AuditRecord,AuditTrail}`。
## 已知踩坑清单
| 症状 | 根因 | 处理 |
|---|---|---|
| `include_str!` 编译失败找不到文件 | 路径相对 `src/main.rs` | 用 `../static/migrate.sql` |
| `/` 返回 500、静态资源 404 | 路径基于 cwd,后台启动 cwd 漂移 | 用 `resolve_project_dir()`(已修) |
| curl 测 localhost 得 502 | 走了系统 HTTP 代理 | 加 `--noproxy '*'` |
| `GET /api/ssw/tdc/node/identity` 404 | 落盘 JSON 缺 `private_key` 无法反序列化 | 磁盘存全量、API 走 `identity_view()` 去敏 |
| 注册返回 600「登录过期」却判成功 | 只看 HTTP 状态 | 必须同时判 body 的 `code` |
| `orgName`/`endpoint` 恒为 null | 请求 camelCase vs 后端 snake_case | 结构体加 `#[serde(rename_all = "camelCase")]` |
| 浏览 `tdc_audit_log` 直接 500 | 查询假定存在 `f_delete_mark`/`f_sort_code` | 改用 `SELECT * LIMIT n` |
| 表名注入 | 直接拼表名 | 一律走 `valid_table()` |
| 两个实例共用 `data/` 报 `postmaster.pid` 锁冲突 | pglite 单实例独占数据目录 | 用不同目录/端口起第二个实例 |
| release 首次编译慢 | 全依赖需重编 | 走 sccache;`cargo build --release` 约 2 分钟 |
## 明确不在本仓库范围
原 `ssw-tdc` 的隐私计算作业——`NaxJob / Nax2PJob / TeeJob / Sandbox / Privacy / AnnotationTask /
Notebook / VizChart / Quality* / HostingJob / DestroyLog` 等——依赖 **Nax 隐私计算引擎**与
**scard 安全平面(软 PKI + 软 TPM)**,本地不可行,**未纳入本次重做**。
需要这部分应保留原 Java/Scala 服务,或作为独立后端经 HTTP 契约接入本连接器。
## 记忆约定
遵循项目级约定:**踩坑清单与长 traceback 进 `docs/`(本文件表格即其索引),工作日志进 `.workbuddy/memory/YYYY-MM-DD.md`**,
本文件只留「原则 + 决定 + 一句话摘要」。