@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-backend-deploy/references/release-strategies.md

@@ -0,0 +1,256 @@
+# 发布策略（backend-deploy）
+
+> 滚动发布 / 蓝绿部署 / 灰度（金丝雀）。
+
+---
+
+## 1. 滚动发布（Rolling Update）
+
+### 1.1 默认策略
+
+K8s Deployment 默认滚动发布：
+
+```
+v1 (3 副本)
+   ↓
+v1 (2) + v2 (1)        启动新版本
+   ↓
+v1 (1) + v2 (2)        继续滚动
+   ↓
+v2 (3)                 完成
+```
+
+### 1.2 配置
+
+```yaml
+spec:
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1           # 最多多 1 个 pod
+      maxUnavailable: 0     # 不可用 ≤ 0
+```
+
+### 1.3 适用
+
+- 无状态服务
+- 启动快
+- 兼容性要求不高
+
+## 2. 蓝绿部署（Blue-Green）
+
+### 2.1 流程
+
+```
+蓝色（当前版本）  ← 100% 流量
+绿色（新版本）    ← 0% 流量
+   ↓ 验证
+绿色               ← 切流量（100%）
+蓝色               ← 0%（保留，回滚用）
+   ↓ 验证 OK
+蓝色               ← 销毁
+```
+
+### 2.2 实现
+
+```yaml
+# 蓝色（当前）
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: your-service-blue
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: your-service
+      version: blue
+  template:
+    metadata:
+      labels:
+        app: your-service
+        version: blue
+    spec:
+      containers:
+        - name: app
+          image: registry.example.com/your-service:v1.2.3
+---
+# 绿色（新）
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: your-service-green
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: your-service
+      version: green
+  template:
+    metadata:
+      labels:
+        app: your-service
+        version: green
+    spec:
+      containers:
+        - name: app
+          image: registry.example.com/your-service:v1.3.0
+---
+# Service 通过 version 标签路由
+apiVersion: v1
+kind: Service
+metadata:
+  name: your-service
+spec:
+  selector:
+    app: your-service
+    version: blue       # 切到 green → 全量切到新版本
+  ports:
+    - port: 80
+      targetPort: 8080
+```
+
+切流量：
+
+```bash
+# 一行命令完成切换
+kubectl patch service your-service -p '{"spec":{"selector":{"version":"green"}}}'
+```
+
+回滚：
+
+```bash
+kubectl patch service your-service -p '{"spec":{"selector":{"version":"blue"}}}'
+```
+
+### 2.3 适用
+
+- 关键业务（金融、订单）
+- 数据库 schema 变更需谨慎
+- 出了问题要立即回滚
+
+## 3. 灰度发布（金丝雀）
+
+### 3.1 流量比例
+
+```
+v1 (90%) + v2 (10%)   ← 灰度开始
+   ↓ 观察
+v1 (50%) + v2 (50%)   ← 监控正常
+   ↓
+v2 (100%)             ← 全量
+```
+
+### 3.2 Istio 灰度
+
+```yaml
+apiVersion: networking.istio.io/v1beta1
+kind: VirtualService
+metadata:
+  name: your-service
+spec:
+  hosts:
+    - your-service
+  http:
+    - match:
+        - headers:
+            user-agent:
+              regex: ".*beta.*"
+      route:
+        - destination:
+            host: your-service
+            subset: v2
+    - route:
+        - destination:
+            host: your-service
+            subset: v1
+          weight: 90
+        - destination:
+            host: your-service
+            subset: v2
+          weight: 10
+```
+
+按 Header / Cookie / 权重分流。
+
+### 3.3 适用
+
+- 大流量服务
+- 重要版本
+- 灰度验证
+
+## 4. 数据库迁移
+
+### 4.1 兼容性原则
+
+**新版本加列 → nullable**：
+
+```sql
+-- 新版本加列
+ALTER TABLE t_order ADD COLUMN new_field VARCHAR(50) NULL;
+```
+
+旧版本代码忽略新字段；新版本代码读新字段。
+
+### 4.2 双写
+
+```
+旧版本：写 t_order_old
+新版本：写 t_order_new + t_order_old（双写）
+   ↓
+数据同步完成
+   ↓
+新版本：只写 t_order_new
+```
+
+### 4.3 灰度回滚
+
+如果新版本数据库变更需要回滚：
+- 保留旧版本 schema 兼容
+- 双写未关闭 → 数据安全
+
+## 5. 发布检查清单
+
+- [ ] 新版本镜像已构建 + 推送到 registry
+- [ ] 配置文件已更新（ConfigMap / Nacos）
+- [ ] 数据库变更已执行（兼容旧版本）
+- [ ] 健康检查 URL 可用
+- [ ] 监控指标已就绪
+- [ ] 回滚预案就绪
+- [ ] 灰度比例已规划
+- [ ] 团队已通知
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 全量直接推
+
+```bash
+# ❌ 错：直接全量推
+kubectl set image deployment/your-service app=registry/app:v2.0.0
+```
+
+✅ 先灰度 → 监控 → 推全。
+
+### 6.2 ❌ 数据库破坏性变更
+
+```sql
+-- ❌ 错：直接删列
+ALTER TABLE t_order DROP COLUMN old_field;
+```
+
+✅ 先加 nullable → 新版本不用 → 数据迁移 → 删列（多版本发布）。
+
+### 6.3 ❌ 无回滚预案
+
+```bash
+# ❌ 错：上线后没保留旧版本
+kubectl delete deployment your-service-v1
+```
+
+✅ 保留历史版本 + Deployment 历史。
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — 后端部署基础
+- [health-monitor-log.md](health-monitor-log.md) — 健康检查 + 监控 + 日志
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-bpm/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: meritdata-platform-bpm
+description: |
+  流程引擎（BPM）接入。设计审批流 BPMN 图、配置节点/网关/条件、把流程实例 ID 接入业务表、监听回调、流程状态变更。
+  触发场景：业务模块需要加审批流；流程图调整；流程回调处理。
+  何时不用：纯业务状态管理（无审批）→ 用 domain-model；流程已建好只调 API → 用 entities。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: medium
+  layer: L2
+  sub-layer: L2-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 流程引擎（BPM）
+
+## 触发
+- 新业务模块需要加审批流（BPMN）
+- 已有流程图调整节点/条件/审批人
+- 流程回调/状态变更需要写入业务表
+- 流程与业务状态字段同步问题
+
+## 不触发
+- 业务表设计/聚合根 → 用 `meritdata-platform-domain-model`
+- 业务编码规范自查 → 用 `meritdata-platform-code-spec`
+- 平台 Flowable/Camunda API 直接调用（已知方法名）→ 用 `meritdata-platform-entities`
+
+## 前置约束
+- 业务状态字段与流程实例 ID **必须分离**（详见 [rules/code-dev-rules.md §八.2](../../rules/code-dev-rules.md#82-业务建模规则domain-model)）
+- 流程状态变更走平台公共方法，不直接 UPDATE 业务表 status
+
+## 路由
+- BPMN 设计要点 + 节点类型 → [references/guide.md](references/guide.md)
+- 与 domain-model 字段对应关系 → [references/status-mapping.md](references/status-mapping.md)

package/skills/meritdata-platform-bpm/references/bpm-/346/224/273/347/225/245/INDEX.md

@@ -0,0 +1,140 @@
+# BPM 流程二开攻略索引
+
+> **来源**：研发版 `meritdata-bpm-2nd-dev`（v2.3.1 整合，原独立 skill 已并入本 skill）
+> **实际内容位置**：[`meritdata-dev-docs-file-finder/references/dev-docs/攻略-NN-*.md`](../../../meritdata-dev-docs-file-finder/references/dev-docs/)
+> **策略**：**索引 + 指向**（不复制文件，避免内容重复）——所有章节内容均在 dev-docs/ 维护，本目录仅提供"按场景→攻略→章节"的导航。
+
+---
+
+## 一、6 篇攻略总览
+
+| 攻略 | 主题 | 章节数 | 总览入口 | 触发场景 |
+|------|------|:------:|---------|---------|
+| **攻略-01** | 流程 API | 16 | [攻略-01-流程API-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-00_总览.md) | 调用启动/完成/退回/追踪 API |
+| **攻略-02** | 工作流程 | 8 | [攻略-02-工作流程-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-02-工作流程-00_总览.md) | 从零创建 BPM 工程（pom / bootstrap）|
+| **攻略-03** | 监听表达式 | 6 | [攻略-03-监听表达式-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-03-监听表达式-00_总览.md) | 自定义流程监听器（JavaDelegate）|
+| **攻略-06** | 系统认证 | 5 | [攻略-06-系统认证-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-06-系统认证-00_总览.md) | 系统认证集成（token / CAS / 第三方）— 详见 `meritdata-platform-sso` |
+| **攻略-07** | 流程模块设计 | 8 | [攻略-07-流程模块设计-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-07-流程模块设计-00_总览.md) | BPM 模块前后端架构设计 |
+| **攻略-08** | 流程前端组件 | 6 | [攻略-08-流程前端组件-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-08-流程前端组件-00_总览.md) | BpmFormTools / BpmGridButtonsNew — 详见 `meritdata-platform-frontend` |
+
+---
+
+## 二、按场景快速匹配
+
+| 我想做什么 | 看哪个攻略 |
+|-----------|-----------|
+| 启动流程实例 / 完成任务 / 退回拟稿人 | 攻略-01（章节03 启动流程 / 章节05 完成任务 / 章节09 退回拟稿人）|
+| 查询个人待办 / 阅知消息 | 攻略-01（章节12 个人待办 / 章节13 阅知）|
+| 查询流程追踪图 | 攻略-01（章节08 查看追踪接口）|
+| 从零搭建 BPM 工程（pom + bootstrap）| 攻略-02（章节02 后端工程创建）|
+| 自定义流程监听器 | 攻略-03（章节01 实现策略）|
+| 系统认证 token 集成 | 攻略-06（章节02 token 认证集成）|
+| CAS 单点登录 | 攻略-06（章节03 CAS 统一认证中心）|
+| BPM 模块前后端设计 | 攻略-07（章节05 流程后端设计 / 章节06 流程前端设计）|
+| 自定义 BPM 前端组件 | 攻略-08（章节03 BpmFormTools / 章节04 BpmGridButtonsNew）|
+
+---
+
+## 三、章节清单
+
+### 攻略-01 流程 API（16 章）
+
+| 章节 | 标题 | 路径 |
+|:-:|------|------|
+| 00 | 总览 | [攻略-01-流程API-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-00_总览.md) |
+| 01 | 前置条件 | [攻略-01-流程API-章节01_前置条件.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节01_前置条件.md) |
+| 02 | 规则引擎初始化接口 | [攻略-01-流程API-章节02_规则引擎初始化接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节02_规则引擎初始化接口.md) |
+| 03 | 启动流程实例接口 | [攻略-01-流程API-章节03_启动流程实例接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节03_启动流程实例接口.md) |
+| 04 | 运行规则引擎 | [攻略-01-流程API-章节04_运行规则引擎.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节04_运行规则引擎.md) |
+| 05 | 完成任务接口 | [攻略-01-流程API-章节05_完成任务接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节05_完成任务接口.md) |
+| 06 | 填写意见接口 | [攻略-01-流程API-章节06_填写意见接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节06_填写意见接口.md) |
+| 07 | 根据任务节点获取意见内容 | [攻略-01-流程API-章节07_根据任务节点获取意见内容.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节07_根据任务节点获取意见内容.md) |
+| 08 | 查看追踪接口 | [攻略-01-流程API-章节08_查看追踪接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节08_查看追踪接口.md) |
+| 09 | 退回拟稿人接口 | [攻略-01-流程API-章节09_退回拟稿人接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节09_退回拟稿人接口.md) |
+| 10 | 退回上一环节处理人接口 | [攻略-01-流程API-章节10_退回上一环节处理人接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节10_退回上一环节处理人接口.md) |
+| 11 | 流程设计器列表查询 | [攻略-01-流程API-章节11_流程设计器列表查询.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节11_流程设计器列表查询.md) |
+| 12 | 个人待办 | [攻略-01-流程API-章节12_个人待办.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节12_个人待办.md) |
+| 13 | 阅知 | [攻略-01-流程API-章节13_阅知.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节13_阅知.md) |
+| 14 | 流程最新定义 ID | [攻略-01-流程API-章节14_流程最新定义ID.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节14_流程最新定义ID.md) |
+| 15 | 业务相关接口 | [攻略-01-流程API-章节15_业务相关接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节15_业务相关接口.md) |
+| 16 | 流程分类相关 | [攻略-01-流程API-章节16_流程分类相关.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-01-流程API-章节16_流程分类相关.md) |
+
+### 攻略-02 工作流程（8 章）
+
+| 章节 | 标题 | 路径 |
+|:-:|------|------|
+| 00 | 总览 | [攻略-02-工作流程-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-02-工作流程-00_总览.md) |
+| 01 | 样例说明 | [攻略-02-工作流程-章节01_样例说明.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-02-工作流程-章节01_样例说明.md) |
+| 02 | 后端工程创建 | [攻略-02-工作流程-章节02_后端工程创建.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-02-工作流程-章节02_后端工程创建.md) |
+| 03 | 后端工程配置 | [攻略-02-工作流程-章节03_后端工程配置.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-02-工作流程-章节03_后端工程配置.md) |
+| 04 | 后端工程业务类创建 | [攻略-02-工作流程-章节04_后端工程业务类创建.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-02-工作流程-章节04_后端工程业务类创建.md) |
+| 05 | 启动后端应用工程 | [攻略-02-工作流程-章节05_启动后端应用工程.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-02-工作流程-章节05_启动后端应用工程.md) |
+| 06 | 流程应用前端开发 | [攻略-02-工作流程-章节06_流程应用前端开发.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-02-工作流程-章节06_流程应用前端开发.md) |
+| 07 | 启动前端应用工程 | [攻略-02-工作流程-章节07_启动前端应用工程.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-02-工作流程-章节07_启动前端应用工程.md) |
+| 08 | 流程设计 | [攻略-02-工作流程-章节08_流程设计.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-02-工作流程-章节08_流程设计.md) |
+
+### 攻略-03 监听表达式（6 章）
+
+| 章节 | 标题 | 路径 |
+|:-:|------|------|
+| 00 | 总览 | [攻略-03-监听表达式-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-03-监听表达式-00_总览.md) |
+| 01 | 实现策略 | [攻略-03-监听表达式-章节01_实现策略.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-03-监听表达式-章节01_实现策略.md) |
+| 02 | 自定义 jar 包的实现流程 | [攻略-03-监听表达式-章节02_自定义_jar_包的实现流程.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-03-监听表达式-章节02_自定义_jar_包的实现流程.md) |
+| 03 | 自定义服务搭建 | [攻略-03-监听表达式-章节03_自定义服务搭建（若已存在工程和接口，此步骤可省略）.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-03-监听表达式-章节03_自定义服务搭建（若已存在工程和接口，此步骤可省略）.md) |
+| 04 | 流程设计中设置 listener 参数 | [攻略-03-监听表达式-章节04_流程设计中设置_listener_参数.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-03-监听表达式-章节04_流程设计中设置_listener_参数.md) |
+| 05 | 测试触发流程监听事件 | [攻略-03-监听表达式-章节05_测试触发流程监听事件是否生效.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-03-监听表达式-章节05_测试触发流程监听事件是否生效.md) |
+| 06 | 备注 | [攻略-03-监听表达式-章节06_备注：.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-03-监听表达式-章节06_备注：.md) |
+
+### 攻略-06 系统认证（5 章）— 已归口 `meritdata-platform-sso`
+
+| 章节 | 标题 | 路径 |
+|:-:|------|------|
+| 00 | 总览 | [攻略-06-系统认证-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-06-系统认证-00_总览.md) |
+| 01 | 系统认证集成介绍 | [攻略-06-系统认证-章节01_系统认证集成介绍.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-06-系统认证-章节01_系统认证集成介绍.md) |
+| 02 | token 认证集成 | [攻略-06-系统认证-章节02_token_认证集成.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-06-系统认证-章节02_token_认证集成.md) |
+| 03 | CAS 统一认证中心 | [攻略-06-系统认证-章节03_cas_统一认证中心.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-06-系统认证-章节03_cas_统一认证中心.md) |
+| 04 | 第三方认证中心 | [攻略-06-系统认证-章节04_第三方认证中心.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-06-系统认证-章节04_第三方认证中心.md) |
+| 05 | 附录：认证中心端配置 | [攻略-06-系统认证-章节05_附录_1_认证中心端配置.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-06-系统认证-章节05_附录_1_认证中心端配置.md) |
+
+> **归口说明**：攻略-06 主题是 SSO 集成（BPM 工程经常需要 token / CAS），**主要用法在 `meritdata-platform-sso/references/`**，本目录仅保留索引。
+
+### 攻略-07 流程模块设计（8 章）
+
+| 章节 | 标题 | 路径 |
+|:-:|------|------|
+| 00 | 总览 | [攻略-07-流程模块设计-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-07-流程模块设计-00_总览.md) |
+| 01 | 背景 | [攻略-07-流程模块设计-章节01_背景.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-07-流程模块设计-章节01_背景.md) |
+| 02 | 工作流相关介绍 | [攻略-07-流程模块设计-章节02_工作流相关介绍.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-07-流程模块设计-章节02_工作流相关介绍.md) |
+| 03 | 应用开发平台流程包含模块 | [攻略-07-流程模块设计-章节03_应用开发平台流程包含模块.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-07-流程模块设计-章节03_应用开发平台流程包含模块.md) |
+| 04 | 流程功能模块介绍 | [攻略-07-流程模块设计-章节04_流程功能模块介绍.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-07-流程模块设计-章节04_流程功能模块介绍.md) |
+| 05 | 流程后端设计 | [攻略-07-流程模块设计-章节05_流程后端设计.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-07-流程模块设计-章节05_流程后端设计.md) |
+| 06 | 流程前端设计 | [攻略-07-流程模块设计-章节06_流程前端设计.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-07-流程模块设计-章节06_流程前端设计.md) |
+| 07 | 二次开发 | [攻略-07-流程模块设计-章节07_二次开发.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-07-流程模块设计-章节07_二次开发.md) |
+| 08 | 个人样例流程的配置 | [攻略-07-流程模块设计-章节08_个人样例流程的配置.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-07-流程模块设计-章节08_个人样例流程的配置.md) |
+
+### 攻略-08 流程前端组件（6 章）— 已归口 `meritdata-platform-frontend`
+
+| 章节 | 标题 | 路径 |
+|:-:|------|------|
+| 00 | 总览 | [攻略-08-流程前端组件-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-08-流程前端组件-00_总览.md) |
+| 01 | 概述 | [攻略-08-流程前端组件-章节01_概述.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-08-流程前端组件-章节01_概述.md) |
+| 02 | 组件与方法概览表 | [攻略-08-流程前端组件-章节02_组件与方法概览表.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-08-流程前端组件-章节02_组件与方法概览表.md) |
+| 03 | BpmFormTools - BPM 表单工具组件 | [攻略-08-流程前端组件-章节03_BpmFormTools_-_BPM表单工具组件.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-08-流程前端组件-章节03_BpmFormTools_-_BPM表单工具组件.md) |
+| 04 | BpmGridButtonsNew - BPM 表格按钮组件 | [攻略-08-流程前端组件-章节04_BpmGridButtonsNew_-_BPM表格按钮组件.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-08-流程前端组件-章节04_BpmGridButtonsNew_-_BPM表格按钮组件.md) |
+| 05 | 后端 BpmEngine 核心接口 | [攻略-08-流程前端组件-章节05_后端BpmEngine核心接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-08-流程前端组件-章节05_后端BpmEngine核心接口.md) |
+| 06 | 附录 | [攻略-08-流程前端组件-章节06_附录.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-08-流程前端组件-章节06_附录.md) |
+
+> **归口说明**：攻略-08 是前端组件（BpmFormTools / BpmGridButtonsNew），**主要用法在 `meritdata-platform-frontend/references/`**，本目录仅保留索引。
+
+---
+
+## 四、使用规则
+
+- 本目录**仅是导航**：实际章节内容在 dev-docs/。
+- 找内容时优先用 `meritdata-dev-docs-file-finder`（带场景匹配 + 关键词反查）。
+- 想了解 BPM 全貌（API + 工作流 + 监听 + 模块设计），按上述表格按攻略-01→02→03→07 顺序读。
+
+---
+
+**最后更新**：2026-09-08（v2.3.1 P1 补齐）
+**来源**：研发版 `meritdata-bpm-2nd-dev` + dev-docs/ 攻略-01~08

package/skills/meritdata-platform-bpm/references/guide.md

@@ -0,0 +1,204 @@
+# BPM 流程引擎使用指南（bpm）
+
+> **核心约束**：业务状态字段（`status`）与流程实例 ID（`process_instance_id`）**必须分离**。流程状态变更走平台公共方法，不直接 UPDATE 业务表 status。
+
+---
+
+## 1. BPMN 设计要点
+
+### 1.1 节点类型
+
+| 类型 | 用途 | 关键配置 |
+|------|------|---------|
+| `startEvent` | 流程起点 | 单节点 |
+| `userTask` | 审批节点 | 审批人 + 表单字段 |
+| `serviceTask` | 自动任务 | 调用 Java 类 / 表达式 |
+| `exclusiveGateway` | 排他网关 | 条件表达式 |
+| `parallelGateway` | 并行网关 | 多分支合并 |
+| `endEvent` | 流程终点 | 单节点 |
+
+### 1.2 审批人配置
+
+```
+方式 1：固定人员
+  → assignee = "${userId}"
+
+方式 2：角色
+  → candidateGroups = "dept_leader"
+
+方式 3：发起人上级
+  → ${initiatorLeader}
+
+方式 4：表单字段
+  → ${form.approverId}
+```
+
+---
+
+## 2. 业务表设计（与 domain-model 配合）
+
+### 2.1 必须字段
+
+```sql
+CREATE TABLE t_purchase_order (
+  id              BIGINT PRIMARY KEY,
+  order_no        VARCHAR(64) NOT NULL,
+  status          VARCHAR(32) NOT NULL DEFAULT 'DRAFT',     -- 业务状态
+  process_instance_id VARCHAR(64),                          -- 流程实例 ID（可空）
+  -- ... 其他业务字段
+  deleted         TINYINT DEFAULT 0,
+  uk_order_no     UNIQUE (order_no, deleted)
+);
+```
+
+### 2.2 status 字典（与流程节点对应）
+
+| status | 含义 | 触发时机 |
+|--------|------|---------|
+| `DRAFT` | 草稿 | 创建时 |
+| `PENDING` | 审批中 | 提交后 |
+| `APPROVED` | 已通过 | 流程结束-通过 |
+| `REJECTED` | 已驳回 | 流程结束-驳回 |
+| `WITHDRAWN` | 已撤回 | 发起人撤回 |
+
+---
+
+## 3. 启动流程
+
+### 3.1 注入 RuntimeService
+
+```java
+@Autowired
+private RuntimeService runtimeService;
+```
+
+### 3.2 启动并关联业务
+
+```java
+// ✅ 正确：通过 BusinessKey 关联
+ProcessInstance pi = runtimeService.startProcessInstanceByKey(
+    "purchase_order_approval",       // BPMN key
+    businessKey,                     // 通常是业务单据 ID
+    variables                        // 流程变量
+);
+
+// 保存流程实例 ID 到业务表
+order.setProcessInstanceId(pi.getProcessInstanceId());
+order.setStatus("PENDING");
+orderRepository.save(order);
+```
+
+### 3.3 ❌ 反例：业务 ID 与流程实例 ID 混用
+
+```java
+// ❌ 错：把 process_instance_id 当业务 ID
+String procId = pi.getId();
+order.setId(procId);   // 错！应该分开
+```
+
+---
+
+## 4. 流程回调（监听）
+
+### 4.1 实现方式
+
+```java
+@Component
+public class PurchaseOrderProcessListener implements ProcessEventListener {
+
+    @EventListener
+    public void onComplete(ProcessCompletedEvent event) {
+        String processInstanceId = event.getProcessInstance().getId();
+        String businessKey = event.getProcessInstance().getBusinessKey();
+
+        // 通过 businessKey 找到业务单据
+        PurchaseOrder order = orderRepository.findById(Long.parseLong(businessKey))
+            .orElseThrow(() -> new BizException("单据不存在"));
+
+        // 更新业务状态（走 service，不直接 UPDATE）
+        orderService.updateStatusAfterProcess(order, event.getProcessInstance().getVariables());
+    }
+}
+```
+
+### 4.2 状态变更必须走 Service
+
+```java
+// ✅ 正确
+orderService.markApproved(order);
+
+// ❌ 错误：直接在监听器里 UPDATE
+orderRepository.updateStatus(order.getId(), "APPROVED");
+```
+
+---
+
+## 5. 流程与业务状态字段同步
+
+### 5.1 同步矩阵
+
+| 流程事件 | 业务 status |
+|---------|------------|
+| 流程启动 | `DRAFT` → `PENDING` |
+| 审批通过 | `PENDING` → `APPROVED` |
+| 审批驳回 | `PENDING` → `REJECTED` |
+| 发起人撤回 | `PENDING` → `WITHDRAWN` |
+
+### 5.2 状态一致性校验（定时 Job）
+
+```java
+// 每天凌晨扫描 process_instance_id 非空但 status 与流程实例不一致的记录
+List<PurchaseOrder> inconsistent = orderRepository.findInconsistent();
+for (PurchaseOrder order : inconsistent) {
+    ProcessInstance pi = runtimeService.createProcessInstanceQuery()
+        .processInstanceId(order.getProcessInstanceId())
+        .singleResult();
+    if (pi == null) {
+        // 流程已结束但 status 还是 PENDING，查历史
+        HistoricProcessInstance historic = historyService.createHistoricProcessInstanceQuery()
+            .processInstanceId(order.getProcessInstanceId())
+            .singleResult();
+        // 校正 status
+    }
+}
+```
+
+---
+
+## 6. 常见反模式
+
+### 6.1 ❌ 把流程状态当业务状态唯一来源
+
+```java
+// ❌ 错：业务查询不查 status，只查 process_instance_id
+List<PurchaseOrder> list = orderRepository.findByProcessInstanceIdNotNull();
+```
+
+业务查询应该查 `status`（业务状态字段），不依赖流程引擎。
+
+### 6.2 ❌ 在业务代码里直接调 RuntimeService 启动/结束流程
+
+应该封装成 `OrderProcessService.start(order)` / `complete(order)`，不在 Controller 直接调 RuntimeService。
+
+### 6.3 ❌ 流程图频繁修改导致历史数据不一致
+
+流程图改了，旧实例按新图跑会出错。**生产流程图只能新增版本**，不能原地修改。
+
+---
+
+## 7. 与其他 skill 的配合
+
+| skill | 配合方式 |
+|-------|---------|
+| `meritdata-platform-domain-model` | 先做表设计（含 status + process_instance_id）|
+| `meritdata-platform-code-spec` | 流程回调的代码规范自查 |
+| `meritdata-platform-entities` | 获取审批人 UserDTO |
+| `meritdata-platform-integration` | 流程回调里 Feign 通知 |
+
+---
+
+## 8. 关联阅读
+
+- [SKILL.md](../SKILL.md)
+- [rules/code-dev-rules.md §八.2](../../rules/code-dev-rules.md#82-业务建模规则domain-model)
+- [meritdata-platform-domain-model](../meritdata-platform-domain-model/SKILL.md)

package/skills/meritdata-platform-bpm/references/status-mapping.md

@@ -0,0 +1,36 @@
+# 流程状态 ↔ 业务字段映射
+
+> **v2.6.1 补建**：v2.5.0 拆分出 bpm 子目录时遗漏创建。
+> 配套主文档：[guide.md](guide.md)
+
+## 一、流程实例状态 ↔ 业务字段
+
+| 流程实例状态 | 业务表字段（建议） | 字段类型 | 说明 |
+|------------|------------------|---------|------|
+| `RUNNING` | `bpm_instance_id` + `bpm_status='RUNNING'` | `VARCHAR(64)` + `VARCHAR(16)` | 流程进行中，可撤回 |
+| `SUSPENDED` | `bpm_status='SUSPENDED'` | `VARCHAR(16)` | 流程挂起（管理员操作）|
+| `COMPLETED` | `bpm_status='COMPLETED'` + `bpm_complete_time` | `VARCHAR(16)` + `DATETIME` | 流程结束 |
+| `TERMINATED` | `bpm_status='TERMINATED'` + `bpm_terminate_reason` | `VARCHAR(16)` + `VARCHAR(255)` | 流程撤销/驳回终态 |
+
+## 二、节点 ↔ 审批人字段
+
+| 节点类型 | 审批人字段 | 数据来源 |
+|---------|-----------|---------|
+| 发起人 | `applicant_user_id` | `PF_USER.ID`（同 JVM 走 `IUserService`）|
+| 部门负责人 | `applicant_dept_id` → 部门负责人 | `IOrgService.getDeptLeader` |
+| 角色 | `*_role_id` | `IAssignService` 资源授权 |
+| 指定用户 | `assignee_user_ids`（多人逗号分隔或关联表）| 手动指定 |
+
+## 三、平台字段命名约定
+
+- **流程实例 ID**：`bpm_instance_id`（CHAR(64)，存 Activiti/TBPM 的 processInstanceId）
+- **当前节点**：`bpm_current_node`（VARCHAR(64)，存流程当前节点 name）
+- **审批状态**：`bpm_status`（VARCHAR(16)，业务展示字段；不要混用流程实例 ID）
+- **审批历史**：单独 `t_bpm_audit_log` 关联表，**不要**把审批意见塞业务主表
+
+> **配套规范**：`meritdata-platform-domain-model` §3.1 平台语义硬规则 → 审批状态独立字段
+
+## 四、参考
+
+- [guide.md](guide.md) — BPMN 节点类型 + 触发条件
+- [rules/meritdata-platform-domain-model-rules.md §3.1](../../../../rules/meritdata-platform-domain-model-rules.md) — 平台语义路由