docs: 补三子系统(TDS/TDC/SSWFLOW)边界入口与部署形态矩阵
- 新建根 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 含类)
This commit is contained in:
1 parent
bce94aaeb8
commit
db997c540e
2 files changed
+56
No files matched your search
@@ -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/` 目录)
|
||||
|
||||
@@ -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) — 文档中心索引
|
||||
Reference in new issue
Block a user