Files
ssw-mvp/docs/README.md
T
admin 3247e9fd15 init: ssw-mvp initial commit
- boot/ (Java/Maven, JNPF 7.0) — 移除旧的 boot/.git,源码直接纳入仓库
- web/ (Vue 3 + Vite + Ant Design Vue, pnpm)
- docs/, scard/, nax/
- refs/INDEX.md + refs/国标/(其余 refs/* 开源子仓库不纳入)
- 已忽略: connector_data/, jweb/, log/, web/{dist,node_modules,.pnpm}, boot/*/target/, .DS_Store, .idea, .vscode
2026-08-05 18:29:12 +08:00

105 lines
7.6 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.
# 尚数网可信数据空间 — 文档索引
本目录是「尚数网可信数据空间」(Shangshuwang Trusted Data Space)的需求与设计文档中心。
## 需求基线(必须实现,不可裁剪)
| 文件 | 说明 | 地位 |
|---|---|---|
| [`功能清单.md`](./功能清单.md) | 19 个章节、约 100 个功能点,覆盖服务平台与接入连接器 | **需求基线 A** |
| [`附件1:技术协议_可信数据空间_0512.docx`](./附件1:技术协议_可信数据空间_0512.docx) | 吉利控股 2026 年可信数据空间平台能力建设项目技术协议,38 个功能点 + 非功能要求 + 验收标准 | **需求基线 B** |
> 两份文档是合同级需求,**全部功能点必须实现**。所有设计文档中的需求条目都带 `[FL-x.y]`(功能清单)或 `[TP-n]`(技术协议)编号,可双向追溯。
## 文档结构
```
docs/
├── README.md # 本文件:索引与阅读顺序
├── 功能清单.md # 需求基线 A
├── 附件1:技术协议_*.docx # 需求基线 B
│
├── arch/ # 全局架构
│ ├── ARCHITECTURE.md # 三子系统总体架构、部署形态、通信协议
│ ├── REQUIREMENT_MATRIX.md # 需求追溯矩阵(功能清单 × 技术协议 × 模块 × 状态)
│ └── MIGRATION.md # sswflow → 尚数网可信数据空间 升级方案
│
├── tds/ # 可信数据空间管理服务平台
│ ├── REQUIREMENTS.md # 需求规格
│ └── DOMAIN_MODEL.md # 领域模型与库表设计
│
├── tdc/ # 数据接入连接器
│ ├── REQUIREMENTS.md # 需求规格
│ └── DOMAIN_MODEL.md # 领域模型与库表设计
│
├── tdd/ # TDD 验证报告与端到端烟测
│ ├── P1P2_CHAIN_K8S_REPORT.md # P1/P2:飞梭链存证 + k8s 沙箱/TEE 落地与验证(核心)
│ ├── P1P2_GAP_REPORT.md # P1/P2 能力缺口分析
│ ├── P0_GAP_REPORT.md # P0 缺口分析
│ └── B1~B7_REPORT.md # 绿色场景端到端验证报告
│
├── security/ # 安全平面(scard)
│ └── SECURITY_PLANE.md # 根密钥/安全启动/远程证明/隧道/通讯加密/国密,软实现与端到端跑通
└── sswflow/ # 隐私计算流程编排(既有子系统)
├── PROJECT.md # 既有项目说明
└── NAX_ENGINE.md # Nax 真实隐私计算执行层(V0.13,ComputeEngine SPI 接入)
```
## 三个子系统
| 代号 | 全称 | 定位 | 业务库 | 独立部署 |
|---|---|---|---|---|
| **TDS** | 可信数据空间管理服务平台 | 空间运营方视角:身份、空间、连接器、目录、合约、使用控制、审计、运营 | `tds` | 是 |
| **TDC** | 数据接入连接器 | 数据提供方/使用方视角:本地资源、产品封装、合约履行、交付、使用控制、数据治理 | `tdc` | 是(多虚拟连接器,租户隔离) |
| **SSWFLOW** | 隐私计算流程编排 | 密态计算引擎的编排层,被 TDS 使用控制环境调用 | `sswflow` | 随平台 |
## 阅读顺序
1. **先读** [`arch/ARCHITECTURE.md`](./arch/ARCHITECTURE.md) —— 理解三子系统边界与交互
2. **再读** [`arch/REQUIREMENT_MATRIX.md`](./arch/REQUIREMENT_MATRIX.md) —— 掌握需求全景与实现进度
3. **按需读** `tds/` 或 `tdc/` 下的需求规格与领域模型
4. **开发前读** [`JNPF_BACKEND_GUIDE.md`](./JNPF_BACKEND_GUIDE.md) —— 后端编码规范(JNPF 7.0 框架约定)
5. **看落地实现读** [`tdd/P1P2_CHAIN_K8S_REPORT.md`](./tdd/P1P2_CHAIN_K8S_REPORT.md) —— 飞梭链存证 + k8s 沙箱/TEE 的设计、回退机制与端到端验证
## 参考资料
`../refs/` 目录:
- `refs/国标/` —— 7 份可信数据空间国家标准技术文件(技术架构、数字合约、使用控制、接入管理、安全能力、功能节点、评价规范)
- `refs/INDEX.md` —— 国标要点索引与条款映射
- `refs/secretpad/` —— 蚂蚁 SecretPad 开源实现,隐私计算平台参考
## 关键约束(来自功能清单「特别说明」)
1. **服务平台与连接器分开部署**,独立的包、独立的数据库;连接器支持多虚拟连接器,**多租户隔离**(复用 JNPF 内置租户字段,不单独设计)
2. **区块链**采用开源**飞梭链**集成
3. **数据沙箱**采用 **kata confidential containers**(K8s 标准接口调用)
4. **数字合约**采用 **OPA + 区块链** 实现
5. **隐私计算**采用沙箱调度,集成隐语 SecretFlow / WeDPR 星隐 / PrimiHub 原语
6. 集成 **JupyterLab** 作为通用数据线上开发能力,生产时将数据、算法调度到沙箱自动执行
7. 采用**研发/生产分离、审核、审计**机制保障数据过程安全
8. **用户、角色、权限、授权复用 JNPF 平台默认能力**,不重新建表
## 已落地能力(best-effort 集成,非合同基线强制部分)
以下扩展以「**零 SDK 依赖 + 进程外适配器 + best-effort 回退**」模式落地,对应关键约束 2/3/4/5/6。设计与端到端验证见 [`tdd/P1P2_CHAIN_K8S_REPORT.md`](./tdd/P1P2_CHAIN_K8S_REPORT.md)。
| 能力 | 设计约束 | 实现 | 状态 |
|---|---|---|---|
| 飞梭链存证 | 约束 2:开源飞梭链 | `FiscoChainClient` + `ChainEvidenceService` + 60s 补偿 ticker;ProcessBuilder 调 `fisco/fisco_adapter.py`(pyweb3sdk)。禁用/失败落 `LOCAL`/`PENDING` **不阻断主流程** | ✅ best-effort(本环境未起链,走回退) |
| k8s 安全沙箱(JupyterLab) | 约束 4/6:kata + JupyterLab | `K8sSandboxClient`(零 `kubernetes-client-java`,直接 `kubectl`)拉起 Notebook Pod+Service;`runtimeClass` 可选,无 kata 时整行删除字段 | ✅ OrbStack k8s 真起 Pod / JupyterLab |
| k8s TEE 交付 | 约束 3:kata confidential containers | `runTeeJob` 渲染 `tee-job.yaml` 起 TEE Job;`k8s → NAX → 本地模拟` 三级回退 | ✅ OrbStack 真跑 `tee-<taskId>` Job(Complete 1/1) |
| 隐私计算引擎 | 约束 5:SecretFlow/WeDPR/PrimiHub 原语 | `NaxComputeEngine`(ComputeEngine SPI),ProcessBuilder 调 `nax/nax_adapter.py` | ✅ 已接入(mpc 模拟) |
| 前端页面 | — | `web/` 新增 TDS 链存证、TDC 沙箱 / 隐私计算 / Notebook 四页,驱动上述能力 | ✅ 已构建验证 |
> 引擎识别:Privacy 交付 `runLog` 含 `[K8S]` / `[NAX]` / `[模拟]` 标记,前端据此显示实际执行引擎。
## 本地运行要点(开发)
- **后端** `boot/ssw-admin`(Spring Boot 3 + JNPF 7.0,Java 21),三业务包 `ssw-sswflow` / `ssw-tds` / `ssw-tdc`,API 前缀 `/api/ssw/{sswflow,tds,tdc}`。
- **启动**:`cd boot && java -DDB_HOST=127.0.0.1 -DDB_PORT=15432 -DREDIS_HOST=127.0.0.1 -DREDIS_PORT=16379 -Dserver.port=30000 -jar ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar`(端口必须 30000;Redis **DB=8** 已写死在 `application-*.yml`,避免与其他实例重复)。
- **前端** `web/`:`pnpm dev`(http://localhost:5173,proxy `/api`→30000)。
- **依赖映射**:Redis 经容器映射端口 `16379`(DB 8),Postgres 映射 `15432`;k8s 走 OrbStack(`kubeconfig ~/.orbstack/k8s/config.yml`,context `orbstack`,镜像须用国内源如 `docker.m.daocloud.io/library/python:3.11-slim`)。
- **鉴权**:`CIPHER_KEY=EY8WePvjM5GGwQzn`,登录密码 `123456`,`account=admin`。
- ⚠️ 后端须以**宿主机网络**启动(如 `run_in_background`),否则连不上 Redis/Postgres 映射端口。