Files
dacli/docs/web-patches

web-patches — jnpf / boot 基线改动存档

目的

jnpf / boot 基线 (jnpf/, boot/) 是平台源码 (JNPF 升级时会覆盖)。项目对基线的任何改动 必须在这里单独存档一份 patch, 升级后能 re-apply。

作用范围: 仅 jnpf / boot 基线定制 (boot/resources 模板 + boot/jnpf-admin 主入口)。 web 端前端源码 (web/.../src/** Vue/TS) 改动走 .claude/skills/dacli/ 流程, 不在本目录。

历史说明: 本目录最初也跟踪 web 端 Vue/TS 改造 (v0.11+ 之前), 当时 dacli 直接修改 web 端源码。 v0.11+ 镜像架构落地后, dacli 用 dynamic import 镜像 web 端函数 (零 web 改动), 该类 patch 已退役 — 镜像机制自有文档在 dacli/src/webapi/_loader.ts + dacli/src/commands/form/_buildformdata.ts + dacli/data/buildformdata-contract.md + dacli/docs/cmd-review/v0.13,v0.14*。

规则

  1. 改基线前先在本目录写 <file>.md (含"待改动清单")
  2. 改基线后完善该文档, 含:
    • 实际 diff (改前 vs 改后)
    • 改动原因 (为什么项目需要这个改动)
    • 验收方法 (怎么验证 patch 还在)
  3. 基线升级后重新读本目录所有 patch, 逐个对照, 缺失的重新应用

不写文档 = 改动 100% 会被升级覆盖丢失。

当前 Patches 状态

Patch 文件 对应文件 状态 备注
_codegen-ServiceImpMarco-virtual-field.md boot/resources/TemplateCodeVue3/PublicMacro/ServiceImpMarco.vm ✅ 已应用 (2026-06-23) 虚拟字段 null 守卫 (searchList 不在主表时跳过)
_jnpf-admin-scanBasePackages-ssw.md boot/jnpf-admin/src/main/java/jnpf/JnpfAdminApplication.java ✅ 已应用 (2026-04-07) scanBasePackages 加 "ssw", ssw-common bean 才能注册
_jnpf-bpmn-autoLayout-on-open.md web/packages/jnpf/plugins/jnpf-bpmn/src/components/bpmn/src/index.vue:210 ✅ 已应用 (2026-07-02) BPMN 编辑器打开时 autoLayout, 修复 Flowable normalize 后节点挤一起 (dacli workflow --ai P0-8 配套)

验收 / 升级流程

每次基线升级 (JNPF 平台 release) 后:

# 1. 看 patch 清单
ls dacli/docs/web-patches/*.md

# 2. 对每个 patch:
#    - 读 patch 文档的"实际 diff"
#    - 对照当前基线文件: 改动还在吗?
#    - 不在 → 重新应用, 跑 baseline 验证
#    - 在 → 文档标 ✅

# 3. 跑 baseline 验证
SKIP_PLAYWRIGHT=1 bash /home/ubuntu/ccWorkDir/.claude/skills/dacli/examples/baseline/all.sh

不在本目录的事

  • 删 web 端文件: 大概率不行 (其他模块依赖), 不在 patch 范围
  • 改 web 端 bug: 不属于 dacli 范围, 应报给 JNPF 平台组
  • dacli 自有模块改动: 走 git log + 源码头注释, 不在本目录 (含 v0.11+ 镜像机制)
  • web/.../src/ Vue/TS 改造**: 走 .claude/skills/dacli/ 流程

排除规则 (严格执行)

路径模式 类别 是否写入 web-patches 走什么流程
jnpf/.../TemplateCodeVue3/.../*.vm 基线 Velocity 模板 ✅ 是 (写 patch) 本目录 + diff 验证
boot/jnpf-admin/.../JnpfAdminApplication.java 基线主入口 ✅ 是 (写 patch) 本目录 + diff 验证
web/packages/jnpf/plugins/jnpf-bpmn/src/**/*.vue jnpf 平台 monorepo 包 (bpmn 组件) ✅ 是 (写 patch) 本目录 + 用户本地 build 验证
boot/resources/.../*.vm (非基线) 项目自有模板 ❌ 否 走 git log
web/.../src/**/*.vue (非 jnpf-monorepo) 前端源码 ❌ 否 走 .claude/skills/dacli/
web/.../src/**/*.ts 前端源码 ❌ 否 走 .claude/skills/dacli/
web/.../public/ssw/** 静态扩展产物 ❌ 否 走 git log
web/.../dist/ssw/** 构建产物 ❌ 否 走 git log
boot/**/ssw*/**/*.java 后端 Java 业务包 ❌ 否 走 backend-dev 流程
uniapp/pages/ssw/** 移动端 ssw 页面 ❌ 否 走 uniapp 流程

判断原则:

  • ✅ 触发: 改 jnpf/ 或 boot/ 下与 JNPF 基线同路径的文件, 或改 jnpf-monorepo 包 (web/packages/jnpf/plugins/*/src/**)
  • ❌ 不触发: 改 boot/ssw*/** (项目自有) + 业务前端 (含 public/ssw/) + uniapp + dacli 自身
  • 注: web/packages/jnpf/plugins/*/src/** 在 web 仓库是 gitignored (jnpf 团队自己 publish npm 包), 改动不能直接 commit 到 web/, 但需文档化到 web-patches 记录 baseline 改动

清理日志

  • 2026-07-02 第二轮 删除 2 个镜像契约 patch (本就是 dacli 自有模块文档, 不在 web-patches 范畴):
    • _buildformdata-formUtils.md — 镜像机制已在 dacli/src/commands/form/_buildformdata.ts 头注释 + dacli/data/buildformdata-contract.md 详述
    • _visualDev-api-shim.md — 镜像机制已在 dacli/src/webapi/_loader.ts 头注释 + dacli/docs/cmd-review/v0.13,v0.14* 详述
  • 2026-07-02 第一轮 删除 2 个误归类 patch (跟踪目标 web/public/ssw/ 违规):
    • jxcj-dashboard-portal-report.md
    • jxcj-official-site.md
  • 2026-07-02 移除 README 表格中 stale 引用 _ai_prompts-GEN_MODEL_QUESTION.md (文件已不存在)
  • 触发原因: 用户审查 web-patches 目录与 CLAUDE.md §代码修改权限 / memory feedback-web-patch-docs 规则的对齐情况, 指出镜像契约 patch 重复 dacli 源文档