- jweb: 真源 src/ssw -> src/views/ssw,164 处 @/ssw/ -> @/views/ssw/ access.ts 现有 glob ../views/**/*.vue 自动覆盖,官方 jnpf_app_ 动态路由直接命中(B 无需改平台代码) - web: web/src/ssw 软链重指向 jweb src/views/ssw;删除 web 自有 ssw 副本 (api/components/types/store/utils/views),统一经软链消费 jweb 真源 - VCS: 移除 jweb/.git(嵌套仓库使 force-add 静默失效),git add -f 将 jweb/.../src/views/ssw(86 文件)纳入本仓库;.gitignore 注明机制 - 文档/记忆: AGENTS.md、MEMORY.md、.gitignore 同步更新路径与路由说明
16 KiB
AGENTS.md
This file provides guidance to AI coding agents (Claude Code, Aider, Cursor, Codex, etc.) when working with code in this repository.
项目定位
尚数网可信数据空间(Shangshuwang Trusted Data Space)—— 在 SSWFlow 隐私计算编排平台之上升级出的、对标国家标准的可信数据空间体系。需求基线见 docs/功能清单.md(FL)+ docs/附件1:技术协议_可信数据空间_0512.docx(TP),所有功能点必须实现。
完整工程视角总览见
docs/PROJECT.md(建议先读docs/arch/ARCHITECTURE.md理解三子系统边界)。
顶层目录速览
| 目录 | 技术栈 | 职责 |
|---|---|---|
boot/ |
Spring Boot 3 + JNPF 7.0 + Java 21(src=17) + Maven | 后端聚合工程,统一入口 ssw-admin |
web/ |
Vite + Vue3 + TS + ant-design-vue | 临时前端(AI/手写轻量 dev 入口) |
jweb/ |
Vben + Turbo + pnpm | JNPF 官方前端 monorepo;dev 入口 = apps/jnpf-web-apps-main(port 3000) |
jweb/apps/jnpf-web-apps-main/src/views/ssw/ |
Vue3 + TS | SSW 业务代码真源(api/components/views/types/store/utils);web/src/views/ssw 软链至此 |
nax/ |
Python 3.9+ (Ray ≥2.9) | 隐私计算执行引擎(PSI / LR / MLP / FedAvg / SCQL) |
scard/ |
Go 1.21 | 安全平面(server + connector,软 PKI + 软 TPM) |
docs/ |
Markdown | 文档中心(README.md 为索引) |
dacli/ |
TypeScript + commander 12 | JNPF 低代码 CLI;详见 .claude/skills/dacli/SKILL.md(gitignored,本地工具) |
refs/ |
多语言 | 国标 / 开源参考(FISCO-BCOS、SecretFlow、SecretPad、WeDPR、PrimiHub、kuscia、tee、国标)—— 勿动 |
log/ |
日志 | 运行时日志(按子系统分目录) |
.claude/ |
配置 | Claude Code 项目配置(含 memory/ 软链到 .workbuddy/memory) |
.workbuddy/memory/ |
Markdown | 长期记忆 + 每日日志(通过 .claude/memory 软链访问) |
三子系统(业务包)
后端 boot/ 下三个 Maven 模块对应三子系统,业务库、API 前缀、@DS 名一一对应:
| 代号 | 全称 | Maven 模块 | 业务库 | @DS |
API 前缀 |
|---|---|---|---|---|---|
| TDS | 可信数据空间管理服务平台 | ssw-tds |
tds |
@DS("tds") |
/api/ssw/tds |
| TDC | 数据接入连接器 | ssw-tdc |
tdc |
@DS("tdc") |
/api/ssw/tdc |
| SSWFLOW | 隐私计算流程编排 | ssw-sswflow-{entity,biz,controller} |
sswflow |
@DS("sswflow") |
/api/ssw/sswflow |
关键原则:
- TDS(运营方中枢) ↔ TDC(数据持有方本地) ↔ SSWFLOW(密态计算执行后端)三足鼎立,数据不经平台,TDC 之间点对点交付。
- 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隔离,复用平台租户字段不单独设计。
命令速查
后端(必须在 boot/ 目录)
cd boot
# 编译(必须 -am 拉所有业务模块)
mvn -pl ssw-admin -am package -DskipTests
# 启动(端口必须 30000;-Dspring.profiles.active=dev 实测不生效)
java -DDB_HOST=192.168.97.3 \
-DREDIS_HOST=192.168.97.2 \
-Dserver.port=30000 \
-jar ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar
⚠️ 后端必须宿主机网络启动(用 run_in_background),否则连不上 192.168.97.0/24 上的容器化 Postgres / Redis。不要用 nohup ... & 双重后台。
前端(jweb/apps/jnpf-web-apps-main,官方 jnpf_app_ 动态路由)
cd jweb/apps/jnpf-web-apps-main && pnpm dev # http://localhost:3000,冷启动 30s+(接受)
唯一入口机制 = JNPF 官方多 app + 后端菜单动态路由注册:
http://localhost:3000/login、/home—— 主平台http://localhost:3000/jnpf_app_{appCode}/login、/home—— 子 app(勿改APP_PREFIX,影响平台)- 路由不写死在前端:登录后
setupAccessGuard→generateAccess()(src/router/access.ts)拿后端菜单 (accessStore.backMenus)动态注册,菜单的urlAddress映射到pageMap里的组件。 - ⚠️
pageMap = import.meta.glob('../views/**/*.vue')—— 官方只扫描src/views/**。 SSW 业务真源已迁到src/views/ssw/**(即src/views/ssw/views/{tds,tdc,sswflow}),已被该 glob 自动覆盖,无需改access.ts。 - 菜单/应用由后端数据驱动,用
dacli(dacli/src/cli.ts)的app create/menu create --type=2 --urlAddress建。
❌
test_app_轻量入口机制已废弃并于 2026-08-06 彻底移除(views/testApp/、router/routes/testApp.ts、TEST_APP_PREFIX、getTestAppEnCode()、test-pages.json全部删除,guard.ts已还原官方版)。 不要再重建这套东西 —— 一律走上面的jnpf_app_官方动态路由。
SSW 业务代码真源(web / jweb 双栈共享,见 .workbuddy/memory/MEMORY.md):
- 真源落盘
jweb/apps/jnpf-web-apps-main/src/views/ssw/{api,components,views,types,store,utils}(67 个 .vue:35 tds + 23 tdc + 9 sswflow) web/src/views/ssw是指向它的软链(web 仅作临时调试入口)- 真源按 jweb 规范写:
import { defHttp } from '@/api/request',内部 import 用@/views/ssw/*,API 前缀/api/ssw/* request→defHttp翻译规则:request.get(url, { params: q })→defHttp.get({ url, params: q })request.post(url, d)→defHttp.post({ url, data: d })request.put(url, d)→defHttp.put({ url, data: d })request.delete(url)→defHttp.delete({ url })- 非 GET 带 query 时 params 会被吞进 body → 加
requestOptions: { joinParamsToUrl: true } - api 层统一
.then((r) => r.data)解包,视图直接消费res.xxx
旧 web/ 仍是 AI 手写栈临时入口(port 5173,独立),可继续用于纯前端调试:
cd web && pnpm dev # port 5173,独立轻量栈
- dev server 进程被杀后端口不再监听,用
run_in_background启动,别用nohup双重后台 - 类型检查:
pnpm exec vue-tsc --noEmit(在对应 app 目录内) - 生产构建:
pnpm build(子系统独立分包 + vendor)
Nax 引擎(nax/)
cd nax
pip install -e ".[dev]" # 可选 [ray]
pytest # 全量
pytest -m 'not slow' # 跳过长用例(公钥密码学预处理)
pytest tests/<file>::<test> -v # 单测
Nax 默认 LocalBackend;NAX_BACKEND=ray 切到 Ray 集群(V0.14 自动化 Party endpoint → Ray 资源映射)。nax/examples/12_k8s_two_party/ 是 k8s 跨方示例。
安全平面(scard/code/)
cd scard/code
export PATH=$HOME/go/go/bin:$PATH
export GOPROXY=https://goproxy.cn,direct
go build ./... # 全量
go build -o bin/security-server ./server
go build -o bin/connector ./connector
go test ./common/crypto/... -v # 单测
scard 详细文档见 docs/security/SECURITY_PLANE.md 与 scard/CLAUDE.md(包含 Zynq-7015 硬件配置、SSH 方式、MAC 冲突修复等)。
JNPF 前端 monorepo(jweb/,仅参考)
cd jweb
pnpm dev # turbo-run dev
pnpm build # turbo build
pnpm dlx vsh check-circular && pnpm dlx vsh check-dep
依赖锁定 [email protected]、Node >=20.19.0,运行时 NODE_OPTIONS=--max-old-space-size=8192。这是 vendor 代码,不要直接改。
关键约定(必读)
鉴权(前端 crypto-js + 后端 Sa-Token)
- 密码加密:
AES-256-ECB-PKCS7,key = md5(CIPHER_KEY)32 字节 UTF8,明文 = md5(plain)(官方默认约定,与旧变体「明文」不兼容),输出ciphertext.toString(Hex) CIPHER_KEY = EY8WePvjM5GGwQzn(同 JNPF webVITE_CIPHER_KEY)- 登录端点:
POST /api/oauth/Login(不是/api/ssw/login),Content-Type: application/x-www-form-urlencoded,bodyaccount=admin&password=<加密>&grant_type=password;发 JSON 或漏grant_type→ 400「不支持此登录方式」 - token:登录返回
data.token="bearer eyJ...",原样存,请求头Authorization: <token>;Sa-TokengetTokenPrefix="bearer"只剥小写前缀,大写Bearer→ 600 登录过期 - 必带头:
App-Code: sswflow/Jnpf-Origin: pc/Vue-Version: 3
数据库
- ⚠️ 所有表都建在
publicschema(DSNcurrentSchema=public),不要写sswflow./tds./tdc.前缀 - 三库物理隔离:
sswflow/tds/tdc同 PostgreSQL 实例(192.168.97.3:5432,user=dacli,pwd=dacli123),各自独立数据库 - 表前缀按子系统识别:
flow_*/tds_*/tdc_* - 迁移手动执行(无 Flyway):
boot/db/V1.0.0__schema.sql(基线)、V1.0.2__flow_run_scope.sql、V1.0.3__flow_schedule.sql;用psycopg2/psql跑,先剥--注释再按;切分 - 软删除:
f_delete_mark=1,查询带f_delete_mark IS NULL - TDS 新建记录勿
setDeleteMark(0),保持 NULL(TdcCrudController 允许(f_delete_mark IS NULL OR =0),TdsCrudController 只认IS NULL)
后端规范(对齐 JNPF 7.0)
完整版见 docs/JNPF_BACKEND_GUIDE.md,易踩坑要点:
scanBasePackages必须写 Java 顶级包jnpf(不是 Maven groupIdcom.jnpf!写错无报错但鉴权/DS 全失效)SswAdminApplication.main()必须addInitializers(new jnpf.util.context.SpringContext())(FQN 是jnpf.util.context.SpringContext而不是jnpf.SpringContext;代码注册而不依赖META-INF是因为 fat-jar repackage 后路径错位)application.yml必须:spring.main.allow-bean-definition-overriding: true+spring.mvc.pathmatch.matching-strategy: ant_path_matcher- 实体基类用
SuperExtendEntity<String>(带sortCode,已javap确认;非SuperEntity<String>) - 业务 Service 统一
extends SswflowServiceImpl<Mapper,Entity>(已实现DynamicSourceGeneratorInterface,DS_KEY="sswflow") - 显式 bean 名防 JNPF 内部撞名:Controller
@RestController("sswflowXxxController")、Service@Service("sswflowXxxService"),实体@Alias("SswflowXxxEntity") @DS严格模式:Entity 上的@DS不一定生效,Mapper 和 ServiceImpl 都要加@DS("tds")/@DS("tdc")/@DS("sswflow")- 禁
@Transactional(强切 master);updateById跳 null,重置用"NONE"哨兵 - 实体表必含 10 基类列(
SuperExtendEntity全字段),否则 SELECT 报 column not exist - JNPF 源码只要本地
~/.m2/repository/com/jnpf/有 jar 即可;首次部署按JNPF_BACKEND_GUIDE.md§〇-B.1 clone 官方模块到~/workspace/jnpf/平级目录后mvn install
前端规范
web/三级导航:App.vue顶栏subsystems[](tds/tdc/sswflow)+ 侧栏由router.getRoutes()过滤meta.subsystem推导(避免菜单与路由漂移)- 通用 CRUD 骨架:
web/src/components/ssw/common/CrudPage.vue,props{title, api, columns, filters, actions, extraQuery, defaults, prompt?};列表响应读res.list(后端返回{pagination, list}) - axios 拦截器解开
ActionResult.data,重声明SswRequest解决类型报错 - 子系统路由:
web/src/router/modules/{tds,tdc,sswflow}.ts,API 客户端:web/src/api/ssw/{tds,tdc,sswflow}.ts
算子协议(SSWFLOW 子系统)
- 类别:
source/prep/stat/model/sink label(非name);key 形如source.dataset/prep.intersect;params type:DATASET / COLUMNS / STRING / SELECT / BOOL / INT / FLOAT / PARTY / SLIDERengine="local"→SimulationComputeEngine(兜底);engine="mpc"→NaxComputeEngine(order=100,首选);engine="tee"→ 预留(TEE 引擎 V0.14+)- 新增算子:
stat.scql(密态 SQL)/model.mlp.train(密文 MLP)/model.fedavg.train(横向联邦)/model.gbdt.train(不支持 mpc → FALLBACK)
架构图(一句话版)
┌─────────────────────────────────────────────────────────────┐
│ 区域 / 行业功能节点(上级) 身份核验 / 产品登记 / 信息上报 │
└──────────────────────────────┬──────────────────────────────┘
│ ① 注册/上报/核验
┌──────────────────────────────┴──────────────────────────────┐
│ TDS 可信数据空间管理服务平台 身份·空间·连接器·目录·合约· │
│ 使用控制·审计·运营·应用生态 │
└──┬───────────────┬──────────────┬───────────────┬──────────┘
│ ②③④ │ ③合约下发 │ ⑥编排调度 │ ⑤关键操作上链
┌──┴──────────┐ ┌─┴───────────┐ ┌┴────────────┐ ┌┴──────────┐
│ TDC 连接器 │ │ TDC 连接器 │ │ SSWFLOW 编排 │ │ 飞梭链 │
│ (供方) │ │ (需方) │ │ (DAG·运行) │ │ (开源) │
└──┬───────────┘ └──────────────┘ └──┬────────────┘ └───────────┘
│ ④数据交付(点对点,不经平台) │ ⑦沙箱调度
└────────────────────────────┐ │
▼ ▼
┌─────────────────────────────┐
│ 密态计算底座 │
│ · scard 安全平面(Go) │
│ · nax 引擎(Python / Ray) │
│ · kata confidential containers │
│ · TEE(CVM / AMD SEV) │
│ · JupyterLab │
└─────────────────────────────┘
scard → TDS 集成(V1.3.2+):DB 迁移 tds_security_device / tds_attest_record + tds_connector +4 列;Java 桥 SecurityPlaneClient + SyncService @Scheduled(30s cron) + SecurityDevice/AuditController;前端 /tds/security 镜像至 SSWFlow 管理面。详情 docs/security/SECURITY_PLANE.md。
验证脚本
/tmp/ssw_tds_tdc_smoke.js— TDS+TDC 后端全链路 62/62/tmp/ssw_login_test.js— 通用登录+业务烟测(接受端口参数)/tmp/cipher_check.mjs—crypto-js加密自检/tmp/ssw_proxy_probe.cjs— 经 5173 代理端到端验证docs/tdd/nax_e2e_smoke.cjs— Nax 引擎烟测(PSI/LR/MLP/FedAvg/SCQL)
参考完整端到端验证报告:docs/VERIFICATION_2026-08-02.md(TDS+TDC 62/62)、docs/tdd/P1P2_CHAIN_K8S_REPORT.md(飞梭链 + k8s 沙箱/TEE)、docs/sswflow/NAX_ENGINE.md(Nax 引擎 V0.13)。
移动目录注意事项
- 工作区相对路径全部存在
.claude/memory(软链到.workbuddy/memory)与boot/db/,移动目录前:lsof :30000杀后端 java 进程lsof :5173杀前端 vite 进程- 移动后
/Users/xs/.workbuddy/{SOUL,IDENTITY,USER}.md不受影响(用户级独立存储) - 移动后须重新创建
.claude/memory软链:ln -s .workbuddy/memory .claude/memory
- 不要破坏
boot/ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar——已编译产物;如需重编mvn -pl ssw-admin -am package -DskipTests web/pnpm-lock.yaml锁定前端依赖完整版本图,移动后pnpm install会快很多
记忆与上下文
- 长期笔记:
/Users/xs/Desktop/ssw/.claude/memory/MEMORY.md(≤3000 字符/会话;物理位于.workbuddy/memory/) - 每日日志:
/Users/xs/Desktop/ssw/.claude/memory/YYYY-MM-DD.md(append-only;物理位于.workbuddy/memory/) - 用户身份:
/Users/xs/.workbuddy/{SOUL,IDENTITY,USER}.md(用户级,与项目无关;不要迁移到.claude/) - 对话历史检索:使用
conversation_search工具