Files
ssw-mvp/docs/arch/MIGRATION.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

7.9 KiB
Raw Permalink Blame History

迁移说明 — 从 SSWFlow 到尚数网可信数据空间

本文记录本次架构升级实际改了什么、为什么这么改、以及踩过的坑。 面向的是接手这套代码的人,不是给验收看的漂亮话。


1. 升级前后对照

维度 升级前(SSWFlow) 升级后(可信数据空间)
定位 隐私计算流程编排平台 可信数据空间平台,编排降级为其中一个子系统
子系统 1 个 3 个:TDS / TDC / SSWFLOW
数据库 单库 sswflow 三库物理隔离:sswflow / tds / tdc
后端模块 ssw-sswflow-* 增 ssw-tds-*、ssw-tdc-*、ssw-common-*
API 前缀 /api/ssw/sswflow 增 /api/ssw/tds、/api/ssw/tdc
前端路由 扁平 /home、/projects… 三级隔离 /tds/*、/tdc/*、/flow/*
前端构建产物 单包 按子系统分包:tds.js / tdc.js / sswflow.js

2. 数据库:为什么是三个库而不是三个 schema

application-dev.yml 里配置了三个独立数据源:

sswflow: jdbc:postgresql://${host}:${port}/${SSWFLOW_DB:sswflow}?currentSchema=public
tds:     jdbc:postgresql://${host}:${port}/${TDS_DB:tds}?currentSchema=public
tdc:     jdbc:postgresql://${host}:${port}/${TDC_DB:tdc}?currentSchema=public

选物理分库的理由只有一个:TDC 将来要独立部署到数据持有方本地。 如果三者共享一个库,TDC 搬出去的那天必须做一次数据拆分,代价远大于现在多配两个数据源。 分库之后跨子系统只能走 HTTP,这个约束是刻意的 —— 它逼着接口边界保持干净。

代价是不能跨库 join。需要对端数据时冗余存一份关键字段(如 tdc_contract.f_tds_contract_id、 tdc_product.f_tds_product_id),靠同步接口对齐。

迁移脚本(手动执行,无 Flyway):

boot/db/sswflow/V1.0.0__schema.sql          原有基线
boot/db/tds/V1.0.0__tds_schema.sql          TDS 14 张表
boot/db/tds/V1.0.1__tds_policy_seed.sql     国标 34 策略 + 12 组合模板种子
boot/db/tdc/V1.0.0__tdc_schema.sql          TDC 14 张表

执行脚本时注意:-- 注释与语句同行会被简单切分器吞掉,先剥注释再按 ; 切。

3. 后端模块结构

boot/
├── ssw-common/          三子系统共用(异常处理、CRUD 基类的公共部分)
│   └── ssw-common-controller/
├── ssw-tds/             {entity, biz, controller}
├── ssw-tdc/             {entity, biz, controller}
├── ssw-sswflow/         {entity, biz, controller}   原有
└── ssw-admin/           启动模块,聚合以上全部

三个业务子系统在 boot 内是独立 Maven 模块,为独立部署预留: 未来只需给 TDC 单独加一个启动模块并引 ssw-tdc-* 即可,业务代码零改动。

4. 升级过程中踩的坑(重要)

4.1 Mapper Bean 重名

三个子系统各有 ContractMapper、DatasourceMapper、ProductMapper, MyBatis 默认按类名首字母小写注册 Bean,直接冲突启动失败。

解法:自定义 SswMapperBeanNameGenerator,用全限定名生成 Bean 名。

4.2 编译器版本被 JNPF 锁在 8

JNPF 的 boot3 profile 把 maven.compiler.source 设成 8。 新模块用了 String.isBlank()(Java 11+)就报"找不到符号"。

解法:每个业务子系统 pom 都要显式抬到 17,包括 ssw-common/pom.xml (这个最容易漏 —— 它是父 pom,不抬会连累所有子模块)。

<properties>
  <maven.compiler.source>17</maven.compiler.source>
  <maven.compiler.target>17</maven.compiler.target>
</properties>

4.3 业务异常被吞成"系统异常"

JNPF 全局异常处理会把未捕获异常统一转成"系统异常", 导致 Controller 里精心写的"内置策略模板不允许删除,可停用"这类提示前端根本看不到。

解法:新增 SswExceptionHandler,@Order(HIGHEST_PRECEDENCE) 且 basePackages 限定在 ssw.tds/tdc/sswflow/common,只接管四类可安全外露的异常:

异常 转成
IllegalArgumentException 原始 message(业务校验提示)
IllegalStateException "当前状态不允许该操作"
HttpMessageNotReadableException "请求体格式有误…"
MissingServletRequestParameterException "缺少必填参数:xxx"

NPE、SQL 异常故意不接管,继续走 JNPF 兜底,避免把内部细节泄露给前端。

4.4 审计日志非空约束

tds_audit_log.f_log_no 非空,但写入方经常不传,直接 PSQLException。 解法:AuditLogController.beforeSave 兜底生成 LOG + yyyyMMddHHmmssSSS + 4 位随机, 不依赖调用方自觉。

4.5 泛型擦除下的 QueryWrapper

TdsCrudController<T> / TdcCrudController<T> 拿不到 T 的 lambda 字段引用, 所以基类里的隔离条件一律用字符串列名("f_space_id" / "f_tenant_id")写 QueryWrapper。 不要试图改成 LambdaQueryWrapper,编译不过。

5. 前端改造

5.1 路由三级隔离

src/router/
├── index.ts              总装 + 鉴权 + document.title
└── modules/
    ├── tds.ts            /tds/*      6 页
    ├── tdc.ts            /tdc/*      6 页
    └── sswflow.ts        /flow/*     9 页

每条路由带 meta.subsystem,App.vue 的侧边菜单直接由 router.getRoutes() 推导, 不再手写一份菜单数组 —— 升级前正是因为菜单与路由各写一份,改了路由忘了改菜单导致整片死链。

根路径与 404 都 redirect 到 /tds/spaces,老书签不会白屏。

5.2 CrudPage 通用骨架

TDS/TDC 十几个主数据页结构完全一致(搜索栏 + 表格 + 抽屉表单 + 状态流转按钮), 抽成 components/ssw/common/CrudPage.vue,页面只声明三样东西:

  • columns —— 列定义(form:false 不进表单,table:false 不进表格)
  • filters —— 过滤项
  • actions —— 行操作(支持 visible 条件显示、prompt 补充输入)

prompt 支持两种形态:给了 options 渲染下拉(枚举类操作,如分类分级), 否则渲染多行文本(原因类,如下架原因)。

extraQuery 变化时自动 reload() —— 切换空间后停留在旧数据第 3 页是很容易误判的坑。

5.3 axios 类型声明

响应拦截器已把 ActionResult.data 解出来了,返回的不再是 AxiosResponse, 但 axios 自带类型描述的是"没装拦截器"的形态,导致每个调用点都报 Property 'list' does not exist on type 'AxiosResponse'(升级前累积了 20+ 处)。

解法:在 api/request.ts 按实际运行时形态重新声明接口 SswRequest,一处解决全部。

5.4 顺带修掉的真实 bug

类型检查暴露出几个一直存在但没人发现的问题:

文件 问题 影响
api/ssw/operators.ts 端口用 id/name,消费端读 key/label 端口标签渲染空白,连线端口 fallback
api/ssw/operators.ts 算子用 name/description,后端 catalog 是 label/desc 字段对不上
api/ssw/sswflow.ts 缺 flow.all()、project.stats() 概览页与项目统计调用不存在的方法
api/ssw/mock.ts 已无人引用的死代码 已删除

6. 验证结论

项 结果
后端启动 ✅ 端口 30000
TDS/TDC 端到端烟测 ✅ 62/62 通过(/tmp/ssw_tds_tdc_smoke.js)
国标策略种子 ✅ 约束 16 + 行为 18 + 组合模板 12
前端类型检查 ✅ vue-tsc 0 error
前端生产构建 ✅ 三子系统独立分包

7. 后续事项

  • TDS ↔ TDC 之间目前是手动录入回调(注册审批、发布审核),真实联调时需接 mTLS 外呼
  • 存证上链(tds_chain_evidence)表已建,逻辑待接入
  • 交付任务的实际数据搬运(tdc_delivery_log)目前只记录状态,执行引擎待接
  • vendor chunk 2.9MB 偏大,后续按需做 manualChunks 拆分