From db997c540ea44e1c7e029d92f57e97d99ede2978 Mon Sep 17 00:00:00 2001 From: admin Date: Thu, 13 Aug 2026 21:49:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E4=B8=89=E5=AD=90=E7=B3=BB?= =?UTF-8?q?=E7=BB=9F(TDS/TDC/SSWFLOW)=E8=BE=B9=E7=95=8C=E5=85=A5=E5=8F=A3?= =?UTF-8?q?=E4=B8=8E=E9=83=A8=E7=BD=B2=E5=BD=A2=E6=80=81=E7=9F=A9=E9=98=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新建根 README.md: 边界速览表(职责/库/@DS/API前缀) + 关键红线 + HTTP 契约客户端清单 + 部署形态矩阵(full/tdc-only/j7node/sswflow-only) + 文档导航 - AGENTS.md: 红线段补 HTTP 解耦客户端清单(TdcTdsClient/TdcSswflowClient/ SswflowClient/TdsCallbackClient), 新增部署形态矩阵并厘清 tdc-only jar 红线 vs j7node 用 full jar+Noop 的现状(红线禁编译期耦合, 非 jar 含类) --- AGENTS.md | 12 ++++++++++++ README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 README.md diff --git a/AGENTS.md b/AGENTS.md index 5fa433b..d8f503b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,11 +38,23 @@ This file provides guidance to AI coding agents (Claude Code, Aider, Cursor, Cod **关键原则**: - TDS(运营方中枢) ↔ TDC(数据持有方本地) ↔ SSWFLOW(密态计算执行后端)三足鼎立,**数据不经平台**,TDC 之间点对点交付。 - 🚫 **红线:禁止 TDS-TDC 强耦合。** TDC **永远不**在编译期依赖 `ssw-tds` 模块——不得在 `ssw-tdc-*` 的 pom.xml 引入 `ssw-tds-*`;跨系统读/写只能经 `TdcTdsClient` HTTP 抽象(`ssw.tds.base-url` 配则走 `HttpTdcTdsClient`,缺则 `NoopTdcTdsClient` 降级),**绝不允许 import TDS 的 Service / Entity / Mapper**。全 `ssw-tdc` 模块的 `@DS` 必须为 `@DS("tdc")`,零 `@DS("tds")`。Maven `tdc-only` profile 打包出的 fat-jar 必须不含任何 `ssw-tds-*` / `ssw-sswflow-*` 类,否则视为强耦合回归(回归验证见 `boot/dist/bin/verify_*` 与每日日志)。 +- 🔌 **跨子系统只走 HTTP 契约客户端**(勿 import 对方类):`TdcTdsClient`(TDC→TDS,配 `ssw.tds.base-url` 走 `HttpTdcTdsClient` 否则 `NoopTdcTdsClient`)、`TdcSswflowClient`(TDC→SSWFLOW)、`SswflowClient`(TDS→SSWFLOW)、`TdsCallbackClient`(SSWFLOW→TDS 回调)。 - SSWFLOW 算法算子从 V0.13 起走真实 Nax 引擎(`engine="mpc"`),通过 `ProcessBuilder` 调 `boot/ssw-sswflow/ssw-sswflow-biz/src/main/resources/nax/nax_adapter.py`。 - TDC 多虚拟连接器通过 JNPF 内置 `f_tenant_id` 隔离,**复用平台租户字段不单独设计**。 > **部署形态红线**:本机 `ssw-admin` 单 fat-jar 仅供**开发联调**,**不是 TDC 的正式部署形态**。TDC 作为数据持有方本地连接器,**正式部署必须落在 `scard` 安全方案内**(`scard/` Go 安全平面 server+connector,软 PKI + 软 TPM;部署范式见 `docs/scard/VM_DEPLOY.md` 与 `scard/CLAUDE.md`),按"数据可用不可见"安全模型交付,不当普通 web 服务裸跑。 +**部署形态矩阵**(Maven profile 决定打哪些子系统类,`application-role/j7node` yml 决定连哪些库): + +| 形态 | Maven profile | 业务库 | 场景 | +|---|---|---|---| +| 运营主节点 | `full`(默认) | tds+tdc+sswflow | 运营方全量中枢 | +| 纯 TDC 数据持有方 | `tdc-only` | tdc | 正式 TDC 节点(scard 安全平面) | +| **j7node**(TDC+SSWFLOW 开发/演示节点) | 当前 `full` jar | tdc+sswflow(**不连 tds**) | VM 内 k3s 业务栈;`TdcTdsClient`→Noop,不提供 TDS 服务 | +| 密态计算节点 | `sswflow-only`(2026-08-13 预留) | sswflow | 预留 | + +> j7node 以 `full` jar + `application-j7node.yml`(只声明 tdc+sswflow 数据源)运行,`TdcTdsClient` 因未配 `ssw.tds.base-url` 走 `Noop`——运行时零 TDS 查询,**符合红线**(红线禁的是编译期耦合,不是 jar 是否含类)。后续构建 tdc+sswflow-only jar 可进一步消除 tds 调度日志噪音(见 `docs/scard/VM_DEPLOY.md` §9)。 + ## 命令速查 ### 后端(必须在 `boot/` 目录) diff --git a/README.md b/README.md new file mode 100644 index 0000000..04120ea --- /dev/null +++ b/README.md @@ -0,0 +1,44 @@ +# 尚数网可信数据空间(SSW / SSWFlow) + +对标国家标准的可信数据空间体系,在 SSWFlow 隐私计算编排平台之上构建。核心特征:**数据不经平台**——平台只流转元数据/合约/控制指令,实际数据在 TDC(数据持有方)之间点对点交付,或在密态计算底座中"可用不可见"。 + +> 完整工程视角与三子系统边界见 [`docs/arch/ARCHITECTURE.md`](docs/arch/ARCHITECTURE.md) §2;给 AI 编码 agent 的操作红线见 [`AGENTS.md`](AGENTS.md);文档总索引见 [`docs/README.md`](docs/README.md)。 + +## 三子系统边界(速览) + +| 代号 | 全称 | 职责 | Maven 模块 | 业务库 | `@DS` | API 前缀 | +|---|---|---|---|---|---|---| +| **TDS** | 可信数据空间管理服务平台 | 运营方中枢:身份·空间·连接器·目录·合约·授权·计量·存证 | `ssw-tds` | `tds` | `@DS("tds")` | `/api/ssw/tds` | +| **TDC** | 数据接入连接器 | 数据持有方本地代理:接入数据源·封装产品·交付·使用控制 | `ssw-tdc` | `tdc` | `@DS("tdc")` | `/api/ssw/tdc` | +| **SSWFLOW** | 隐私计算流程编排引擎 | 密态计算执行后端:DAG 编排·运行引擎·Nax 算子·产物 | `ssw-sswflow-{entity,biz,controller}` | `sswflow` | `@DS("sswflow")` | `/api/ssw/sswflow` | + +**三库物理隔离**(同 PostgreSQL 实例,各自独立数据库):`j7`(JNPF 主库) / `tds` / `tdc` / `sswflow`,表前缀 `tds_*` / `tdc_*` / `flow_*`,均建于 `public` schema。 + +## 关键原则与红线 + +- 🚫 **禁止编译期跨边界耦合。** 任一子系统模块(如 `ssw-tdc-*`)的 pom **不得**依赖另一子系统的 `-*controller/-*biz/-*entity`;跨系统读/写**只经各子系统的 HTTP Client 抽象**(见下),绝不允许 `import` 对方 Service/Entity/Mapper。 +- 🔌 **跨子系统仅走 HTTP 契约**,现有解耦客户端: + - `TdcTdsClient`(TDC→TDS,配 `ssw.tds.base-url` 走 `HttpTdcTdsClient`,缺则 `NoopTdcTdsClient` 降级) + - `TdcSswflowClient`(TDC→SSWFLOW) + - `SswflowClient`(TDS→SSWFLOW) + - `TdsCallbackClient`(SSWFLOW→TDS 回调) +- 🗄️ **`@DS` 严格模式**:Mapper 与 ServiceImpl 都必须显式标注本子系统 `@DS`;`ssw-tdc` 模块内零 `@DS("tds")`。 +- 🔒 **TDC 正式部署落在 `scard` 安全平面**(软 PKI + 软 TPM,数据可用不可见),不当普通 web 服务裸跑。 + +## 部署形态矩阵 + +| 形态 | Maven profile | 连哪些业务库 | 场景 | +|---|---|---|---| +| 运营主节点 | `full`(默认) | tds + tdc + sswflow | 运营方全量中枢 | +| 纯 TDC 数据持有方 | `tdc-only` | tdc | 正式 TDC 节点(scard 安全平面) | +| **j7node**(TDC+SSWFLOW 开发/演示节点) | 当前 `full` jar | tdc + sswflow(**不连 tds**) | VM 内 k3s 业务栈;`TdcTdsClient`→Noop,不提供 TDS 服务。详情见 [`docs/scard/VM_DEPLOY.md`](docs/scard/VM_DEPLOY.md) | +| 密态计算节点 | `sswflow-only`(2026-08-13 预留) | sswflow | 预留 | + +> j7node 目前以 `full` jar + `application-j7node.yml`(只声明 tdc+sswflow 数据源)运行,`TdcTdsClient` 因未配 `ssw.tds.base-url` 走 `Noop`——运行时零 TDS 查询,符合红线。后续可构建 tdc+sswflow-only jar 进一步消除日志噪音(见 VM_DEPLOY §9)。 + +## 文档导航 + +- [`docs/arch/ARCHITECTURE.md`](docs/arch/ARCHITECTURE.md) — 工程总览 + 三子系统边界(职责表/架构图/13 步流程) +- [`AGENTS.md`](AGENTS.md) — AI agent 操作红线、命令速查、DB 铁律 +- [`docs/scard/VM_DEPLOY.md`](docs/scard/VM_DEPLOY.md) — scard 安全平面 + j7node k3s 业务栈部署 +- [`docs/README.md`](docs/README.md) — 文档中心索引