从 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/ 记录跨方契约细节
197 lines
12 KiB
Markdown
197 lines
12 KiB
Markdown
# 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`**,
|
||
本文件只留「原则 + 决定 + 一句话摘要」。
|