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

12 KiB
Raw Blame History

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 缺字段导致回读失败,不要用)。

命令速查

# 编译(自动走本机统一缓存:~/.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:

# 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, 本文件只留「原则 + 决定 + 一句话摘要」。