@lovrabet/rabetbase-cli 2.5.3 → 2.5.4-beta.2

package/skills/rabetbase/guides/custom-page-flow-timeline-display.md

@@ -0,0 +1,289 @@
+# Flow SDK 时间线展示指南
+
+生成包含 `timeline` 的流程页面时，先阅读本指南，再在页面内编写 JSX 和样式。本指南定义展示方式，不要求新增业务组件、组件包或修改 SDK。接口和字段契约见 [Flow SDK 指南](custom-page-flow-sdk.md)。
+
+## 默认布局：节点 → 办理人状态 → 操作记录
+
+使用单列纵向时间线。左侧是一根细连接线和节点圆点，右侧依次展示节点名称、办理人状态、该任务下发生的操作。用户应能直接看出“走到了哪一步、现在谁在处理、之前发生了什么”。
+
+默认标题为“流程进度”；纯审批场景可用“审批流程”。标题旁放流程总状态，`approvalRound > 1` 时加“第 N 轮”。以下示意中的颜色说明不作为页面文字；具体名字、节点和时间来自响应，不是业务默认值。
+
+中文页面必须显式展示字段标题，例如“提交人：”“处理人：”“处理结果：”“处理说明：”“处理时间：”。仅把 `COMPLETED` 翻译成“已完成”不满足要求。页面作者负责把展示标题与接口值绑定，不需要等待后端新增中文字段，也不能动态翻译 JSON 属性名来生成标题。应用使用其他语种时翻译相同的字段标题，仍保留标签与值的对应关系。
+
+```text
+审批流程                                      进行中
+
+○ 提交                                           绿色
+│ 提交人：binggan
+│ 提交时间：2026-09-17 14:01:18
+│
+○ 第一审批节点                                   绿色
+│   处理人：binggan
+│   处理结果：通过
+│   处理说明：预算已确认
+│   处理时间：2026-09-17 14:03:00
+│
+○ 第二审批节点                                   蓝色
+│ 当前办理人：weiyuan    任务状态：进行中
+│   处理人：binggan
+│   处理结果：转签
+│   处理说明：转签：binggan -> weiyuan；说明：123
+│   处理时间：2026-09-17 14:05:05
+│
+○ 后续节点                                       灰色
+  预计办理人：财务人员    节点状态：尚未到达
+
+───────────────────────────────────────────────────
+同意   拒绝   转签   退回        撤回 / 撤销 / 作废
+```
+
+底部操作区表示可用动作的布局位置，不代表这些按钮同时存在。按当前详情的权限、任务模式和候选列表生成，见后文。不得把截图中的按钮直接写死。
+
+节点是一级，`tasks` 是二级，`comments` 是三级。不要把三个数组摊平成同级时间线，也不要用一张原始字段表、JSON 或 BPMN 大图代替默认阅读视图。流程图可作为独立的“查看流程图”入口。
+
+## 可见字段标题与去重规则
+
+下表是页面展示文案契约。字段可按场景省略；一旦展示其值，就必须显示对应标题。节点名称作为标题、节点旁自解释的中文状态徽标可以直接展示，其余人员、模式、说明和时间不能仅靠位置或分隔符让用户猜含义。
+
+| 场景 / 数据 | 页面字段标题 | 示例 |
+| --- | --- | --- |
+| START 的发起人 | 提交人 | `提交人：binggan` |
+| START 的发起时间 | 提交时间 | `提交时间：2026-09-17 17:47:47` |
+| `step.approvalMode` | 审批方式 | `审批方式：单人审批 / 会签 / 或签`；仅在已确认审批语义时使用 |
+| `step.sequential` | 处理顺序 | `处理顺序：依次处理 / 并行处理`；不适用或未知时隐藏 |
+| 当前真实任务的 `assigneeName` | 当前办理人 | `当前办理人：weiyuan` |
+| 历史任务归属人（确需单独展示时） | 办理人 | `办理人：binggan` |
+| 尚未创建任务的计划人员 | 预计办理人 | `预计办理人：财务人员` |
+| 单独展示的 `task.status` 与结论文案 | 任务状态 | `任务状态：进行中 / 已同意 / 已拒绝 / 已跳过` |
+| `comment.name` 或用户 ID 回退值 | 处理人 | `处理人：binggan`；系统操作显示 `处理人：系统` |
+| `comment.typeName` 或动作映射 | 处理结果 | `处理结果：通过 / 拒绝 / 转签 / 超时自动拒绝` |
+| `comment.fullMessage` | 处理说明 | `处理说明：审核拒绝`；空值隐藏整行 |
+| `comment.time` | 处理时间 | `处理时间：2026-09-18 10:36:15` |
+| 没有操作时间可展示时的任务时间 | 接收时间 / 完成时间 | `接收时间：…`、`完成时间：…`，不能冒充处理时间 |
+| 确需展示的 `step.startTime/endTime` | 节点开始时间 / 节点结束时间 | 放入“节点详情”展开区，避免默认重复任务时间 |
+| 实际 END 的结束时间 | 结束时间 | `结束时间：2026-09-18 10:36:16` |
+| `task.cancelReason` / `timeline.cancelReason` 的兜底原因 | 撤销原因 / 作废原因 | 按事件使用对应标题；有同义处理说明时不重复 |
+| `fieldChanges[]` | 字段 / 修改前 / 修改后 | 用 `fieldLabel` 对应业务字段的中文名，旧值新值各有标题 |
+
+默认一项一行，标签使用次级文本色，值使用正常文本色。可以在宽屏同一行排两个有完整标签的字段，窄屏自然换行；不能退化成 `拒绝 · binggan · 2026/9/18 10:36:15`，也不能显示 `binggan · 已完成` 和一个无标题的时间区间。中文标题后的冒号保持统一。
+
+时间和人员去重遵守以下规则：
+
+- 提交节点只显示“提交人”“提交时间”一次，不再重复遍历其合成任务生成办理人和起止时间。
+- 已完成的单人节点，若只有一条完成操作且操作人与任务归属一致，直接显示带标题的处理记录；不再额外打印“办理人 + 已完成 + 任务时间”。有多任务、转签、代办或其他操作时保留必要的归属层级。
+- 有评论处理时间时，默认不再展示相同任务起止时间和节点起止时间。需要查耗时或到达时间时，放入有明确标题的“节点详情”展开区。
+- 无评论的人工任务按真实状态显示“办理人 / 当前办理人”“任务状态”；时间使用“接收时间 / 完成时间”。不能为了凑四行而编造处理人、处理结果或处理说明。
+- 自动节点使用紧凑的一行节点标题和中文状态；确需显示时间时，按事实标“开始时间 / 完成时间”，不输出两端相同的时间区间。
+- 每条独立操作保留自己的处理人和处理时间，不能为了去重而合并不同操作。折叠记录展开后仍按相同标签规则展示。
+
+例如已完成的单人拒绝节点应展示为（示例值不作为默认数据）：
+
+```text
+编辑主管终审                                  已拒绝〔红色〕
+  审批方式：单人审批
+  处理人：binggan
+  处理结果：拒绝
+  处理说明：审核拒绝
+  处理时间：2026-09-18 10:36:15
+```
+
+节点标题旁的“已拒绝”取该节点的实际结论，处理记录中的“拒绝”取该评论的动作，不能因为样例里相同就混用来源。处理时间取评论时间，不用晚一秒的节点结束时间替代。
+
+## 数据到画面的映射
+
+优先使用当前详情响应中的 `detail.timeline`；单独查询时使用 `getTimeline(processInstanceId)`。同一块时间线只消费一个快照，不把两次请求的 `steps`、任务和评论拼起来。
+
+| 画面位置 | 数据来源 | 展示规则 |
+| --- | --- | --- |
+| 标题旁总状态 | `timeline.status`，以及实际到达的 `END.approvalResult` | 进行中、已撤回、已撤销等；正常结束且实际 END 结论为 `REJECTED` 时显示“已拒绝”，结论缺失则只显示“已完成” |
+| 左侧圆点 | `step.status` 和 `step.approvalResult` | 表示整个节点状态；不能使用最后一条评论或第一个人的结果替代 |
+| 节点标题 | `step.nodeName` | 原样展示；为空才回退 `nodeKey`，两者均空显示“流程节点” |
+| 多人模式说明 | `step.approvalMode`、`step.sequential` | `SINGLE` 单人、`ANY` 或签、`ALL` 会签；多人时再标“依次处理”或“并行处理”，`null` 不猜 |
+| 办理人主行 | `task.assigneeName`、`task.assignee`、`task.status`、`task.approvalResult` | 使用“当前办理人 / 办理人”和“任务状态”标题；每个任务独立一行，符合单人完成去重条件时可省略重复主行 |
+| 处理人 | `comment.name` → `comment.userId` | 这是该操作的实际操作人，不能用当前任务的办理人覆盖 |
+| 处理结果 | `comment.typeName` → `comment.type` 的动作字典 | “转签”“通过”“修改表单”等是操作记录的动作名，不是节点终态 |
+| 处理说明 | `comment.fullMessage` | 纯文本、保留换行、允许换行折行；空时隐藏这一行，不填“同意”“无意见”等推测文字 |
+| 处理时间 | `comment.time` | 按毫秒时间戳格式化；不能用任务完成时间替代评论时间 |
+| 字段修改详情 | `comment.fieldChanges` | 在这条操作下展开“字段：旧值 → 新值”，不混到审批意见里 |
+
+所有时间采用页面所在应用的时区和统一格式，例如 `YYYY-MM-DD HH:mm:ss`；不得乘以 1000。时间未知可隐藏或显示“时间未记录”，不能显示当前时间或 1970 年。人物姓名、评论和字段值均按文本渲染。
+
+## 排序、执行次数与节点选择
+
+1. `order` 齐全时，复制 `steps` 后按 `order` 稳定升序排列，相同值保留原相对顺序；若部分 `order` 缺失，保留服务端数组顺序，不补成 0 或推测重排。不要原地修改响应，不按 `endTime` 重新排列，也不要在前端重跑条件表达式。
+2. 每条节点轨迹使用 `processInstanceId + nodeKey + occurrence` 作为基本身份，必要时附加 `order` 区分。不能仅按 `nodeKey` 去重。同一审批节点再次执行时必须保留两条轨迹。
+3. `nodeName` 已可能包含“（第二次）”。直接使用服务端标题，不再追加“第 2 次”。`occurrence` 表示节点执行次数，`approvalRound` 表示流程审批轮次，两者不能互相替代。
+4. 同一节点内保留任务数组顺序；串行多人尤其不能按姓名排序。以真实 `taskId` 为任务 key；计划/虚拟任务使用所属节点身份加数组位置，不把空 ID 当真实任务。
+5. 每个任务内的评论按 `time` 稳定升序，时间缺失放最后并保留相对顺序。评论没有独立 ID，可用所属任务身份与原数组位置做渲染 key；不要按姓名或时间去重合法操作。
+6. 默认展示已发生节点和当前节点。正常完成的 `CONDITION`、`SCRIPT`、`NOTIFICATION` 等自动节点可缩成一行，连续自动节点可折叠为“系统处理（N 项）”；运行中、异常、退回或带操作说明的节点保持可见。
+7. `PENDING` 节点放在后续区域，以灰色显示“尚未到达”；计划人员标“预计办理人”。服务端后续路径可能是配置预览，不能表述为一定会执行，也不能把所有未来节点标成“待我审批”。多个后续节点可折叠为“查看后续节点（N 项，预计）”。
+8. 未发生且没有评论的 `SKIPPED` 节点可收进“未执行节点”；有实际任务、时间或评论的跳过节点要保留可展开记录。流程已结束后不要继续用“等待审批”的口吻展示未执行节点。
+
+如果响应包含多个运行节点，全部保留运行状态。纵向排列只表示展示顺序，不据此声称它们串行或属于某一并行分支；`steps` 没有分支分组字段。
+
+## 节点和人员状态如何落字
+
+按下表从上到下判断。同一套生命周期优先级可用于节点圆点和任务状态，但展示节点结果只读 `step`，展示人员状态只读对应 `task`。评论用自己的动作样式，不改变父级状态。
+
+| 判断条件 | 建议文案 | 视觉 |
+| --- | --- | --- |
+| `status=SKIPPED`，无论 `approvalResult` 是什么 | 已跳过；有 `AUTO_SKIP` 时可写“自动跳过” | 灰色，跳过图标 |
+| `status=RETURNED` | 已退回 | 警示色，退回图标 |
+| `status=RETURNED_TO_STARTER` | 已退回发起人 | 警示色，退回图标 |
+| `status=WITHDRAWN` | 已撤回 | 警示色，撤回图标 |
+| `status=VOIDED` | 已作废 | 终止图标，弱化色 |
+| `status=CANCELLED` | 已撤销 | 终止图标，弱化色 |
+| `status=PENDING` | 尚未到达；已创建但未开始的具体任务可写“待处理” | 灰色，空心圆 |
+| `status=RUNNING` | 进行中 | 蓝色，时钟图标 |
+| `status=PARTIALLY_COMPLETED` | 部分已完成 | 蓝色，时钟图标；节点仍在运行 |
+| 具体任务 `status=COMPLETED`，决定本次结果的是 `TIMEOUT_APPROVE` / `TIMEOUT_REJECT` | 超时自动同意 / 超时自动拒绝 | 同意绿色、拒绝红色；明确系统动作 |
+| 具体任务 `status=COMPLETED`，详情匹配到 `taskMode=HANDLE` 或历史完成动作为 `COMPLETE` | 办理完成 | 绿色，完成图标；不把办理写成审批同意 |
+| `status=COMPLETED` 且 `approvalResult=REJECTED` | 节点“已拒绝”；人员“已拒绝” | 红色，拒绝图标 |
+| `status=COMPLETED` 且 `approvalResult=APPROVED` | 节点“已通过”；人员“已同意” | 绿色，勾选图标 |
+| `status=COMPLETED` 且为 `RESUBMIT` / `RESUBMITTED` | 重新提交 | 绿色，提交图标 |
+| `status=COMPLETED`，没有明确业务结论 | 已完成 | 绿色，完成图标；不补“同意” |
+| 未知状态或状态缺失 | 状态待确认 | 中性色；原始码只在辅助信息中显示 |
+
+特殊业务结果 `RETURNED` / `RETURNED_TO_STARTER` / `WITHDRAWN` / `VOIDED` / `CANCELLED` 若随 `COMPLETED` 返回，沿用对应特殊文案；不能覆盖仍为 `RUNNING` 或 `PENDING` 的生命周期。
+
+人工节点中，`taskId` 为空且 `startTime/endTime` 均为空时按计划人员展示，不生成实际待办入口；即使父节点运行中，也不要声称这个计划人员已有任务。节点已跳过时该计划人员仍显示“未执行 / 已跳过”，不再写“等待处理”。该判断只用于人工节点，不能误伤 `START`、`RESUBMIT` 和撤销/作废的虚拟事件任务。
+
+任务状态为 `RUNNING`，但 `assigneeName/assignee` 均空时写“当前办理人：待确定”“任务状态：进行中”；计划人员未解析时写“预计办理人：到达节点时确定”。不能根据当前登录人补姓名。姓名解析失败但 ID 存在时，用弱化的“用户 {ID}”。
+
+时间线任务没有 `taskMode`。不能因为 `nodeType=APPROVAL` 就断言它一定是“同意/拒绝”型审批；它也可能是人工办理。当前详情中与 `taskId` 精确匹配的 `taskMode=HANDLE`，或该历史任务的 `COMPLETE` 动作，可以支持“办理完成”的文案；无法确认时使用“进行中 / 已完成”。
+
+`TIMEOUT_APPROVE` / `TIMEOUT_REJECT` 要显式写“超时自动同意 / 超时自动拒绝”，操作人显示评论中的系统身份。任务主行可以保留办理人作为任务归属，但不得写成该人员主动点击了同意或拒绝。`AUTO_SKIP` 同样是系统动作。
+
+## 各类节点的具体内容
+
+| 节点 | 默认内容 | 边界 |
+| --- | --- | --- |
+| `START` | 标题 `nodeName`；“提交人：{startUserName}”“提交时间：{startTime}” | 提交人、时间优先用 timeline 顶层；缺失可用 START 任务/节点中的对应值。服务端已有 START 时不要再追加一个提交节点 |
+| `APPROVAL` | 节点名称 + 多人模式；逐个 task 展示姓名/状态，再展示各自 comments | 不能只取 `tasks[0]`；没有任务则展示节点状态和对应空态 |
+| `RESUBMIT` | 标题“重新提交”；任务/评论中的操作人与时间，说明和字段变更仍放下面 | 是已经发生的独立事件，taskId 可以为空；不得再手工从原任务中复制出第二个重提节点 |
+| `CONDITION` | 节点名称 + “条件判断” + 节点状态 | 不渲染审批人，不把表达式作为审批意见，也不把预览分支当已命中 |
+| `SCRIPT` / `SERVICE_TASK` | 节点名称 + “系统处理” + 节点状态 | 已完成只表示该系统节点执行完毕，不说明某个人已审批通过 |
+| `NOTIFICATION` | 节点名称 + “通知环节” + 节点状态 | 完成不等于收件人已读；没有收件/阅读字段时不补“已读” |
+| `END` | 实际结束状态、明确结论和结束时间；有任务/评论时展示对应操作人、原因 | 运行中的未来 END 显示“尚未结束”；未到达的 END 不能决定整个流程结论 |
+| 其他类型 | 节点名称 + 服务端状态，保留任务与评论 | 使用通用布局，不把未知节点丢弃 |
+
+`START` 使用带标题的提交摘要；`RESUBMIT` 使用已有评论的“处理人 / 处理结果 / 处理说明 / 处理时间”，不再重复输出合成人员主行。撤销/作废时服务端可能已经返回一个合成的 `END`，直接使用，不能再添加相同终止节点。终止原因优先展示该事件评论的 `fullMessage`；没有正文时才补 `task.cancelReason` 或 `timeline.cancelReason`，避免同一原因重复显示。
+
+流程总状态是 `WITHDRAWN` / `RETURNED` 时，标题下提示“等待修改后重新提交”；这不是结束状态，不能给未完成的 END 画成功圆点。`canResubmit` 为 true 才显示重提入口。
+
+## 操作记录：完整、紧凑、不误归属
+
+每条评论默认采用上方示意的四行布局：处理人、处理结果、处理说明、处理时间。处理结果可用小标签或有色文字，但普通状态文字不能做成看似可点击的链接。操作人名称为空时回退用户 ID，两者均空显示“操作人未记录”。没有正文时仅省略“处理说明”；即使只有动作没有正文，这条记录仍要保留。
+
+任务归属人和实际操作人也可能因代办而不同。若明确的完成评论操作人不同于 `task.assignee`，人员主行使用“办理人：{办理人}”“任务状态：已通过 / 已拒绝 / 办理完成”，在记录中显示真正的操作人；不能写成该办理人亲自同意，也不能仅凭人员不同就猜“管理员代办”。
+
+空间紧张时仍保留每个字段的中文标题，通过换行和折叠控制高度，不合并成无标签的操作摘要。当前节点的全部任务状态默认展开；每个任务评论超过 3 条时默认展示最近 3 条（仍按时间升序），较早记录通过“展开更早 N 条记录”查看。不能只取最后一条评论。
+
+转签必须同时保留两件事实：
+
+- 人员主行使用 `task.assigneeName`，显示当前返回的办理人和任务状态。
+- 转签记录使用 `comment.name`，显示执行转签的人；`fullMessage` 保留完整的转出、转入及说明。
+
+转签在原 task 上增加 `TRANSFER` 评论并变更办理人，不等于节点完成，不新增一个“已通过”的节点。`fullMessage` 是服务端文本，响应没有独立的转签双方字段；不要用 `split('->')`、正则或名字匹配反推身份。一次任务可以多次转签，按返回的全部评论展示，不覆盖旧记录。
+
+`FORM_UPDATE` 先显示操作人、动作名、摘要、时间，再提供“查看字段变更（N 项）”。字段名用 `fieldLabel || fieldKey`；金额、日期、选项、附件按已知业务字段契约格式化，`null` 显示“空”，`0` 和 `false` 保留真实值。未知复杂值显示“复杂内容”，通过可展开的只读格式化详情查看，不能直接输出 `[object Object]`。不要从当前 `formData` 反推历史旧值，或者补回服务端未返回的字段。
+
+## 多人、重复执行与结论
+
+- 会签、或签的每个任务都保留自己的人员状态和意见。`approvalMode=ANY` 不代表第一人同意后其他人也同意；`ALL` 不代表所有任务都已完成。
+- 若要展示统计，使用“已返回任务中：N 已完成，M 进行中，K 已跳过”。串行任务可能尚未全部创建，不能把 `tasks.length` 当配置中的总人数，不展示推测的 `1/3` 审批进度或百分比。
+- `PARTIALLY_COMPLETED` 节点保持蓝色；不要用已完成子任务的绿色覆盖节点状态。节点/流程结论由后端字段决定，前端不根据人数重新计算通过条件。
+- `SKIPPED + APPROVED` 的人员仍显示“已跳过”。这表示任务可能继承了节点最终结论，不表示此人操作过“同意”。有 `AUTO_SKIP` 时展开系统原因。
+- 退回后保留原节点的“已退回”以及新出现的同名节点。不能用最新 occurrence 覆盖旧轨迹，也不能把旧轮次拒绝结果当当前流程最终结果。
+- 整体拒绝结论只取正常结束后实际到达的 `END.approvalResult`。不要从历史上任一 `REJECT` 评论、未执行的拒绝分支 END 或 `flowDiagram.nodes[].result` 推导整体已拒绝。
+
+## 样式、交互与页面内生成步骤
+
+白底卡片，内边距建议桌面 24px、窄屏 16px。圆点约 10–12px、连接线 2px；节点标题约 16px/600，人员主行 14px，说明和时间 13px。节点间距 24–32px，人员主行距标题 8px，操作记录再内缩 24px。具体尺寸可适配页面密度，不复制截图的大块空白。
+
+颜色使用应用设计 token：完成用成功色，进行中用主色，拒绝用错误色，退回/撤回用警示色，未发生/跳过用弱化色；正文、辅助文字和边框分别使用文本/次级文本/边框 token。图标可用页面已允许的图标库。颜色必须同时有文字或图标表达，灰色说明仍应清晰可读。
+
+窄屏仍采用单列，时间自然换行；长意见允许折行，长内容提供展开；不使用固定高度裁掉记录。当前节点可轻微加浅色背景，不要闪烁、强制滚动或在多个地方重复“进行中”。可提供“定位当前节点”，由用户点击后滚动。
+
+在当前页面里按以下次序生成 JSX；允许本地格式化函数，不要求抽取共享组件：
+
+```text
+读取 detail.timeline 或 getTimeline 的单次响应
+  → 渲染标题、流程状态、必要的等待重提提示
+  → 稳定排序 steps，保留 occurrence
+  → 每个 step：确定节点圆点和标题
+      START：渲染提交摘要一次
+      RESUBMIT：渲染重提摘要和已有评论一次
+      其他节点：按对应节点模板展示
+      每个 task：先判断是否计划人员，再判断生命周期，再读业务结论
+        → 当前办理人 / 办理人：姓名；任务状态：本任务状态（符合去重条件则省略重复主行）
+        → 按时间遍历本任务 comments
+            处理人：操作人
+            处理结果：动作
+            处理说明：原始说明（为空则隐藏）
+            处理时间：操作时间
+            若有 fieldChanges，再提供字段变更展开区
+  → 可折叠后续节点/正常系统节点（不删除原始数据）
+  → 在时间线外渲染当前详情允许的动作
+```
+
+动作区使用同一个流程当前详情快照：`canHandle && taskId` 才能办理；`taskMode=APPROVAL` 提供同意/拒绝，`HANDLE` 提供办理完成；转签还要求 `transferCandidates` 非空；退回要求 `canReturn` 且从 `returnTargets` 选目标。流程级撤回、重提、撤销、作废分别使用对应 `can*`。按钮不能根据时间线某条历史任务的颜色、人员名或登录人匹配生成。
+
+办理成功后重新读取当前详情及正在显示的时间线；刷新失败时保留旧内容并提示“操作已成功，最新进度加载失败，可重试刷新”，暂停旧动作入口。不能直接把当前节点改绿或把下一节点改蓝。加载失败、暂无轨迹、没有评论是不同状态，不能把请求失败显示成空数据。抄送详情使用历史快照并注明快照时间，保持只读。
+
+## 转签示例：同一响应的预期画面
+
+以下是假数据，仅用于解释字段映射；运行时 ID、用户和时间必须从真实响应取得。展示时区按此例为 Asia/Shanghai。
+
+```json
+{
+  "order": 3,
+  "nodeKey": "approval_2",
+  "nodeName": "第二审批节点",
+  "occurrence": 1,
+  "nodeType": "APPROVAL",
+  "approvalMode": "SINGLE",
+  "status": "RUNNING",
+  "approvalResult": null,
+  "tasks": [{
+    "taskId": "example-task-2",
+    "assignee": "example-user-b",
+    "assigneeName": "weiyuan",
+    "status": "RUNNING",
+    "approvalResult": null,
+    "comments": [{
+      "userId": "example-user-a",
+      "name": "binggan",
+      "type": "TRANSFER",
+      "typeName": "转签",
+      "fullMessage": "转签：binggan -> weiyuan；说明：123",
+      "time": 1789625105000
+    }]
+  }]
+}
+```
+
+预期：第二审批节点为蓝色；人员主行显示“当前办理人：weiyuan”“任务状态：进行中”；下面分行显示“处理人：binggan”“处理结果：转签”“处理说明：转签：binggan -> weiyuan；说明：123”“处理时间：2026-09-17 14:05:05”。不能把 binggan 显示成当前待办人，不能因为已有转签记录就把 weiyuan 或整个节点显示为完成。
+
+## 展示验收场景
+
+| 输入情形 | 必须看见的结果 |
+| --- | --- |
+| 中文页面中的人员、模式、说明和时间 | 每个可见值都有“提交人 / 审批方式 / 处理人 / 处理结果 / 处理说明 / 处理时间”等对应中文标题，不是只有值的拼接 |
+| 已完成单人任务只有一条完成操作，操作人与归属人相同 | 直接显示带标题的处理记录，不重复人员主行、节点和任务起止时间 |
+| 单人审批已同意、下一人处理中 | 前节点绿色、当前节点蓝色，人员状态分别独立 |
+| 进行中任务含一条/多条 `TRANSFER` | 当前办理人仍进行中，转签操作人及每次转签可查看 |
+| 并行会签部分完成 | 同一节点内同时出现已完成和进行中的人员，节点保持蓝色 |
+| 或签剩余任务 `SKIPPED + APPROVED` | 剩余人员显示跳过，不能显示已同意 |
+| 未来任务无 ID 和时间 | 预计办理人、尚未到达，不展示办理入口 |
+| `START` / `RESUBMIT` 任务无 ID 但事件已发生 | 提交/重提事件仍正常展示，不显示成计划人员 |
+| 已完成任务无审批结论、有 `COMPLETE` | 办理完成；没有动作事实时只写已完成 |
+| 超时自动拒绝 | 明确系统自动拒绝，保留系统操作说明，不能伪造成手动拒绝 |
+| 同一 `nodeKey` 两次执行，第二次名字已带次数 | 两条节点，原样标题，不去重、不重复追加次数 |
+| 流程 `COMPLETED`、实际 END 为 `REJECTED` | 总状态为已拒绝，不是已通过 |
+| 未执行的拒绝 END 或旧轮次拒绝记录 | 不影响当前流程总状态 |
+| 撤回/退回发起人后尚未重提 | 显示等待修改后重新提交，不画成功结束 |
+| 撤销/作废已有合成 END | 终止事件只出现一次，原因不重复 |
+| 评论姓名/时间/正文为空，字段值是 `0`/`false` | 不编造人物时间意见，保留真实零值和布尔值 |
+| 评论含字段修改、长文本、未知动作 | 信息可展开查看、不截丢、不当作 HTML 执行 |
+| 时间线请求失败或办理后刷新失败 | 明确提示失败和重试，不伪造新进度 |

package/skills/rabetbase/guides/custom-page-workflow.md

@@ -8,11 +8,13 @@
 
 - 新建或修改 自定义页面、看板、门户、落地页或复杂交互页面
 - 使用 ECharts 实现图表、统计卡片和数据大屏
+- 为 `INDEPENDENT_FLOW + CUSTOM_PAGE` 实现发起、待办、详情和任务办理页面
 
 ## 前置上下文
 
 - 创建页面前确认 `appCode`；修改页面前确认 `pageId`
 - 确认页面目标，以及影响实现的布局、交互、数据和样式约束
+- 页面需要驱动独立工作流时，确认 `flowCode`、业务变量契约和页面承担的发起/办理阶段
 - 无法确定新建页面或目标页面时，先向用户确认
 
 ## 编排规则
@@ -44,7 +46,7 @@
 ### 查找或修改已有页面
 
 1. 未知页面 ID 时，先阅读 [`rabetbase-page-custom-list.md`](../references/rabetbase-page-custom-list.md)，执行 `page custom-list`；仅在跨应用或覆盖工作区默认应用时传 `--appcode <appCode>`
-2. 根据 `data.pages[].pageId` 与 `label` 与用户确认目标页面；`data.pages[].pageUrl` 用于查看最新保存内容，`data.pages[].editPageUrl` 用于打开页面编辑器
+2. 根据 `data.pages[].pageId` 与 `label` 与用户确认目标页面；`data.pages[].pageUrl` 用于查看最新保存内容，`data.pages[].runtimePageUrl` 是完整运行态地址、无论页面是否发布都会返回，但页面从未发布时打开会显示错误提示，`data.pages[].editPageUrl` 用于打开页面编辑器
 3. 阅读 [`rabetbase-page-custom-detail.md`](../references/rabetbase-page-custom-detail.md)，执行 `page custom-detail --id <pageId>`
 4. 只在返回的最新 `data.codeContent` 基础上编辑，不得根据旧缓存或猜测覆盖文件
 
@@ -74,6 +76,8 @@
 
 `data.pageUrl` 用于查看最新保存内容，包含尚未发布的修改；`data.editPageUrl` 用于打开页面编辑器；`page custom-publish` 成功返回的 `data.runtimePageUrl` 用于查看已发布内容。不要将三者混用。
 
+将页面绑定到独立工作流时，`flowJson.startPath`、`APPROVAL.path` 和 `END.path` 填写完整 `runtimePageUrl`，不能填写菜单原始 `path` 或其他地址。绑定前必须用 `custom-detail` 确认 `status === "FORMAL"`；未发布时停止填写并询问用户是否先发布，发布成功并回读 `FORMAL` 后再绑定。
+
 ## 页面生命周期
 
 自定义页面的 React JSX 实现有“未发布”和“已发布”两种状态。未发布的修改可通过 `pageUrl` 或编辑器查看，已发布页面只展示最近一次发布的内容。
@@ -109,7 +113,7 @@ page create --page-pattern <BLANK|ONEPAGE|DASHBOARD>
 | --- | --- | --- |
 | 创建/保存成功 | `pageUrl`、`editPageUrl` | `pageUrl` 查看最新保存内容，`editPageUrl` 打开页面编辑器 |
 | 发布成功 | `runtimePageUrl` | 查看最近一次已发布内容 |
-| 页面查询 | `pageUrl`、`editPageUrl` | 快速打开最新保存内容或页面编辑器 |
+| 页面查询 | `pageUrl`、`runtimePageUrl`、`editPageUrl` | 快速打开最新保存内容、运行态页面或页面编辑器 |
 
 ## 数据与服务契约
 
@@ -124,8 +128,9 @@ page create --page-pattern <BLANK|ONEPAGE|DASHBOARD>
 | 单一数据集请求 | 只涉及一个数据集的查询、详情、分页、筛选、创建、更新或删除 | 严格按照当前数据集 API-doc 返回的调用说明实现，不得自行推测或自由发挥调用标识、方法、字段、参数、返回值或异常处理 |
 | Custom SQL | 需要组合多个数据集，或需要数据库完成关联、聚合、分组、排序、计算和复杂筛选 | 先复用或按 SQL 工作流创建、校验并发布 Custom SQL，再通过 `client.sql.execute({ sqlCode, params })` 调用；不要把 CLI 的 `data.rows` 当作运行时返回结构 |
 | Backend Function | 需要按当前用户、角色、数据范围或业务规则额外鉴权，或需要数据转换、条件分支、多步编排和外部服务调用 | 将校验和编排放入已确认的 Backend Function，由页面通过 SDK 调用；前端只传业务参数，Backend Function 内按需执行已发布的 Custom SQL；简单查询不额外包装成 Backend Function |
+| Flow SDK | 页面发起、查询或办理已发布的独立自定义页面工作流 | 先完整阅读 [`custom-page-flow-sdk.md`](custom-page-flow-sdk.md) 的返回对象字段字典、状态映射和页面组合规则；使用页面注入的 `client.flow()`，不手动拼 Runtime URL、传 `appCode` 或根据字段名猜展示语义 |
 
-判断顺序：先确认单一数据集请求能否满足需求；数据组合和数据库计算是主要问题时选择 Custom SQL；当前用户、角色、数据范围或业务规则需要额外控制时选择 Backend Function。三种方式可以根据已确认的 SDK 契约配合使用，但不得自行推测方法、参数或返回结构。
+判断顺序：先确认单一数据集请求能否满足需求；数据组合和数据库计算是主要问题时选择 Custom SQL；当前用户、角色、数据范围或业务规则需要额外控制时选择 Backend Function；页面需要推进独立工作流时使用 Flow SDK。四种方式可以根据已确认的 SDK 契约配合使用，但不得自行推测方法、参数或返回结构。
 
 页面通过已发布 Custom SQL 的 `sqlCode` + `params` 执行查询；Backend Function 默认使用 `context.client.sql.byName(sqlName).execute({ params })`，`sql.execute({ sqlCode, params })` 仅作兼容路径。Dataset、Custom SQL 或 Backend Function 执行失败时，保留并报告原始错误，根据资源状态、参数与权限定位问题。
 
@@ -159,6 +164,9 @@ page create --page-pattern <BLANK|ONEPAGE|DASHBOARD>
 
 - 选择、组合或新增 UI 组件时，按需阅读 [`components.md`](../knowledge/components.md)
 - 调用页面上下文、国际化、路由或数据客户端时，按需阅读 `generation-standards.md` 中的“页面上下文内置能力”
+- 使用 `client.flow()` 时，先完整阅读 [`custom-page-flow-sdk.md`](custom-page-flow-sdk.md) 的全部固定返回对象与嵌套字段说明
+- 展示流程时间线时，再阅读 [`custom-page-flow-timeline-display.md`](custom-page-flow-timeline-display.md)，在页面内按节点、办理人状态、操作记录三层生成纵向视图
+- 使用 Ant Design 组件时，先确认页面实际使用的 Ant Design 版本，并严格按照该版本的公开文档和类型定义编写组件 API；不得沿用其他版本写法，也不得凭经验猜测组件属性、组合结构或事件签名
 - 未登记的组件、方法、参数和返回结构不得猜测，先补充确认后的规范再复用
 
 ## 页面文件与代码约束
@@ -218,3 +226,4 @@ CLI 当前不提供本地预览或独立删除命令。
 - [`generation-standards.md`](../knowledge/custom-page/generation-standards.md)
 - [`components.md`](../knowledge/components.md)
 - [`rabetbase-codegen-sdk.md`](../references/rabetbase-codegen-sdk.md)
+- [`custom-page-flow-sdk.md`](custom-page-flow-sdk.md)

package/skills/rabetbase/guides/sql-creation-workflow.md

@@ -11,21 +11,23 @@ SQL 内容编写、参数绑定与 MyBatis 语法以 [`sql-mybatis.md`](sql-myba
 ## 工作流
 
 ```
-确认需求 → [按需]查现有 SQL → 校验字段 → 拉/落本地（pull/create）→ 编辑本地文件 → [建议]validate → status → push/delete → detail/exec 验证
+确认需求 → 查现有 SQL → 校验字段 → 拉/落本地（pull/create）→ 编辑本地文件 → 检查、修复与复验 → status → push/delete → detail/exec 验证
 ```
 
 ### 1. 确认需求
-写 SQL 前必须明确：查询目标、字段、筛选条件、排序分页、是否 JOIN、新建还是修改。缺失则先问用户。
+写 SQL 前必须明确：查询目标、字段、筛选条件、排序分页、是否 JOIN、新建还是修改。先读取已有需求、项目资料与相关元数据；仍缺少影响实现的业务信息时再向用户确认。
 
-### 2. 查现有 SQL（按需）
-* 新建 → 可跳过
-* 修改已有 → 执行 `rabetbase sql list --format json` 找到目标，确认 `sqlCode`
-* 不确定 → 查一下
+### 2. 查现有 SQL
+目标 `sqlCode` 已明确时直接回读 `sql detail`；否则执行 `rabetbase sql list --format json` 定位目标或可复用资源。
 
-命中同名或同语义 SQL 时，停下问用户：沿用还是另建。
+发现相似资源后，主动比较业务语义、参数、返回结构、目标连接及调用方。满足需求且兼容时直接复用；任务范围内的明确错误直接修复并验证。确需新建且已获授权时自行完成。只有存在无法从资料确定的业务取舍或影响既有调用方的范围变更时，才准备推荐方案并请求决策；同名不等于同语义。
 
 ### 3. 校验字段
-执行 `rabetbase dataset detail --code <数据集编码> --format json` 确认表名、字段名、字段类型。禁止凭经验猜。
+
+通过现有连接元数据确认目标数据库类型；版本等信息无法取得时明确标注未知，不默认采用 MySQL 语法。
+执行 `rabetbase dataset detail --code <数据集编码> --format json`，按 [dataset detail 输出契约](../references/rabetbase-dataset-detail.md)确认表名、字段名、字段类型及数据库 ID。`sql create --db-id` 使用已核实的目标连接 ID，不得猜测或复用其他应用的 ID。
+
+同时核对各表的逻辑删除字段及正常值。Instant API 的 `create`、`update`、`filter` 自动处理逻辑删除字段；Custom SQL 不会自动添加 `is_deleted` 条件，即使表结构已标记逻辑删除，也须在主表、关联表和子查询中按业务需要显式编写过滤条件。历史查询由 SQL 明确表达范围，并遵守授权约束。具体规则见 [Instant API 与 Custom SQL 的逻辑删除边界](sql-mybatis.md#instant-api-与-custom-sql-的逻辑删除边界)。
 
 同时核对各表所属连接与该 SQL 的执行连接；同名表须按真实连接消歧。不同连接的逻辑关联由 [跨库 BFF 查询与拼接](cross-database-bff.md)编排分库读取，不能用跨库 JOIN、子查询或视图绕过边界。`sql validate` 的静态检查不证明跨连接可执行、权限完整或全局结果正确。
 
@@ -33,7 +35,7 @@ SQL 内容编写、参数绑定与 MyBatis 语法以 [`sql-mybatis.md`](sql-myba
 
 #### 修改已有 SQL
 
-先执行：
+先检查本地是否有待保留的修改，再执行；出现分歧按下方“冲突处理”完成比较：
 
 ```bash
 rabetbase sql pull --sqlcode <sqlCode> --format json
@@ -43,7 +45,7 @@ rabetbase sql pull --sqlcode <sqlCode> --format json
 
 #### 新建 SQL
 
-先执行：
+先使用相同参数执行 `--dry-run`，由 Agent 核对名称、连接、模式与创建范围；符合已有授权后执行：
 
 ```bash
 rabetbase sql create --name <sqlName> --db-id <dbId> --mode sql --format json
@@ -82,8 +84,21 @@ select * from users
 
 可以保留并编辑这段头注释；`sql push` 上传时会自动剥离，不会把本地元信息写回平台正文。
 
-### 6. 验证（建议）
-执行 `rabetbase sql validate --file <sql文件路径> --format json` 传入 SQL 文件。未通过则修正后重新验证。
+### 6. 检查、修复与复验
+
+Agent 应主动核对 SQL 与业务意图、目标连接、字段、参数和必要条件是否一致。对证据明确且属于任务授权范围的错误，直接修复并复验，不因用户提供了原始实现或本地检查能力有限而忽略问题。
+
+修改 SQL 后，默认执行 `rabetbase sql validate --file <sql文件路径> --format json` 获取辅助诊断。已知超出其覆盖范围时，使用现有可用的元数据、相关测试或获授权的运行验证，并说明未覆盖部分；不为取得 `valid=true` 反复调用已知不适用的检查。
+
+| 诊断情况 | 后续动作 |
+| --- | --- |
+| 已确认的实现错误 | 修正错误，验证原问题消失，并检查受影响的业务结果 |
+| 事实不足 | 优先读取相关元数据、调用契约和已有测试；补充事实后继续判断，仅对仍无法取得的关键业务信息询问用户 |
+| 有依据的检查器误报 | 保留正确实现，说明依据与限制，使用适用的验证方式继续推进任务 |
+
+`valid=true` 后仍须检查业务条件与结果是否满足需求。保留的是业务意图及必要的锁、权限和范围条件；已证实写错或漏写的实现应修正，不得仅为消除告警删除必要条件。本地检查不参与 `sql push` 保存决策，实际提交仍须符合用户授权及平台规则。
+
+同一问题没有新证据却重复出现时，停止无依据的改写或重试，继续完成不受阻碍的工作。交付时列明已修复内容、实际验证、未验证项和具体阻碍；不以“检查器不支持”直接结束可继续处理的任务。
 
 ### 7. 查看同步状态
 
@@ -115,7 +130,7 @@ rabetbase sql status --remote --format json
 rabetbase sql push --sqlcode <sqlCode> --dry-run --format json
 ```
 
-确认无误后正式执行：
+Agent 核对预览与已有授权一致、命令前置要求满足后正式执行；只有新增关键取舍才请用户决策：
 
 ```bash
 rabetbase sql push --sqlcode <sqlCode> --format json
@@ -125,18 +140,19 @@ rabetbase sql push --sqlcode <sqlCode> --format json
 
 * 仅文件名变化时，`sql push` 会把新的文件名视作新的 `sqlName` 并回写远端
 * 文件移动到新的数据库目录时，`sql push` 会尝试按目录名重新绑定 `dbId`
-* 若提示 `missing remote version`，先执行 `sql pull` 刷新 lock 中的 `version`
+* 若提示 `missing remote version`，先保留本地修改、回读远端，再按“冲突处理”恢复同步；由 `sql pull` 刷新版本，不手改 lock 伪造版本
 
 ### 9. 测试
 
-推送成功后执行：
+推送成功后先回读内容：
 
 ```bash
 rabetbase sql detail --sqlcode <sqlCode> --format json
-rabetbase sql exec --sqlcode <sqlCode> --format json
 ```
 
-失败则修正 → validate → status → push → detail/exec。
+任务授权包含真实执行时，再使用 `rabetbase sql exec --sqlcode <sqlCode> --params '<JSON参数>' --format json` 验证相关业务结果；单纯保存成功不代表功能或锁效果已验收。
+
+根据失败原因处理：实现错误按第 6 步修复并复验；连接、权限或版本冲突先处理对应原因，不凭这些错误改写 SQL。运行验证受阻时，完成可进行的本地检查并报告剩余项。
 
 ### 10. 删除工作流
 
@@ -146,7 +162,7 @@ rabetbase sql exec --sqlcode <sqlCode> --format json
 rabetbase sql delete --sqlcode <sqlCode> --dry-run --format json
 ```
 
-确认无误后：
+Agent 核对预览中的资源与影响，满足删除授权和命令确认要求后执行；`--yes` 仅用于已获授权的确认，不能绕过用户取消：
 
 ```bash
 rabetbase sql delete --sqlcode <sqlCode> --yes --format json
@@ -156,18 +172,20 @@ rabetbase sql delete --sqlcode <sqlCode> --yes --format json
 
 ## 非 SELECT 语句
 
-DELETE / DDL（DROP / ALTER / CREATE / TRUNCATE）属高风险，不建议进入同步主路径。
-将 SQL 写入本地草稿文件，告知用户手动在平台操作。
-草稿路径可放在同步目录旁的 `.draft.sql`，例如：
+SQL 资源的保存与语句的真实执行分开判断。`sql exec` 的 `read` 标记不代表 SQL 没有写入或锁定影响；本地 `valid=true`、风险配置或 `--yes` 都不能替代对实际执行范围的授权。
 
-```text
-.rabetbase/sql/<appCode>/<dbName|db-<id>>/<sqlCode>_<sqlName>.draft.sql
-```
+**编写与准备由 Agent 完成**：确认目标连接、影响范围、实际入口能力与授权，写出具体 SQL，核对影响行数或对象范围，准备适用的验证方式与恢复方案；不因语句类型就把编写、排查和验证直接交给用户。
+
+**按具体方案或批次授权**：目标环境、连接、影响范围及后果已明确授权，且实际入口支持时，Agent 连续执行并验证，无需逐条重复确认。涉及尚未授权的数据删除、破坏性结构变更或不可逆后果时，先完成可审阅的 SQL、影响评估与恢复方案，再就整个具体方案请求一次确认；不把概括性任务目标视为这些后果的授权。目标环境或连接改变、影响范围扩大或出现新的重大后果时，重新提交关键决策。
+
+用户确认不扩展平台能力或权限。不为验证候选 SQL 而隐式执行它，也不把 `sql exec` 当作任意 SQL 执行器；入口不支持或用户取消时停止该操作，不通过换接口、包装 SQL 或反复尝试绕过，继续其他已授权且不受阻碍的工作。
+
+能力、权限或关键取舍仍阻塞时，完成可独立推进的准备，交付具体候选、影响、已验证结果和最小待办。未准备同步的候选文件放在同步目录外；`.draft.sql` 后缀不代表 CLI 自动忽略，不能把草稿写入同步目录后整批推送。
 
 ## 冲突处理
 
-* `sql pull` 提示 `local differs from remote` → 说明本地与远端已漂移；先和用户确认是否 `--force`
-* `sql push` 失败 → 明确告诉用户是哪一条 `sqlCode` 失败、为什么失败，不要粉饰为已同步
+* `sql pull` 提示 `local differs from remote` → 保留本地修改，使用 `sql detail` 回读远端并比较；有可靠基线且语义明确、互不冲突的修改由 Agent 合并并验证。基线不足先补证；涉及覆盖他人修改或业务冲突时，准备差异、推荐方案与影响再请求决策，不把 `--force` 当默认恢复方式。
+* `sql push` 失败或结果未知 → 按[写入结果与恢复动作](conflict-detection.md#写入结果与恢复动作)处理；逐项核对返回的 `pushed`、`skipped`、`failed` 与 `sqlCode`，不重复提交已成功项。
 
 ## SQL 调用差异
 

package/skills/rabetbase/guides/sql-mybatis.md

@@ -1,67 +1,33 @@
-# SQL CLI 命令与 MyBatis 语法指南
+# SQL 与 MyBatis 语法指南
 
-> 目标：指导 AI 如何正确使用 CLI 命令来完成 SQL 的查询、本地同步、验证、推送与测试，并提供平台支持的 MyBatis 动态 SQL 语法参考。
+> 目标：指导平台 Custom SQL 的语义处理与 MyBatis 动态 SQL 编写。
 >
-> 前置阅读：`sql-creation-workflow.md`（整体流程）、`data-api-guidelines.md`（字段约束）
+> 前置阅读：[SQL 工作流](sql-creation-workflow.md)、[数据接口约束](data-api-guidelines.md)
 
 ## 何时使用
 
 当任务满足任一条件时，必须阅读并遵守本指南：
 
-* 需要使用 CLI 命令处理自定义 SQL
+* 编写或修改平台 Custom SQL
 * 编写需要动态条件的复杂 SQL（如可选参数、范围过滤）
 * SQL 验证报错，需要排查语法或字段问题
 
-## CLI 命令调用规范
+## Instant API 与 Custom SQL 的逻辑删除边界
 
-在执行 `sql-creation-workflow.md` 规定的流程时，AI 必须严格按以下方式使用 CLI 命令。
+- **Instant API**：`create`、`update`、`filter` 接口由平台按逻辑删除配置自动处理 `is_deleted` 字段；`filter` 默认排除已删除记录。该行为仅适用于相应标准接口，不能推导为所有平台 SQL 都会自动过滤。
+- **Custom SQL**：平台不会自动添加 `is_deleted` 条件，也不会替开发者补齐逻辑删除字段处理。即使表结构已标记“逻辑删除”，查询正常记录仍须在 SQL 中显式编写过滤条件，例如 `is_deleted = 0`；字段名和正常值以实际表结构及配置为准。自定义 INSERT / UPDATE 所需的逻辑删除字段赋值或筛选也由 SQL 明确表达。
+- 编写或修改 SQL 前，通过 `dataset detail` 核对主表、关联表、子查询涉及表的逻辑删除字段和执行连接，逐处判断需要排除还是包含已删除记录。不得以“平台自动补充”为由移除已有条件；列表、计数、聚合和写入条件应保持业务口径一致。
+- `LEFT JOIN` 需要保留没有有效右表记录的主记录时，右表的逻辑删除条件写在 `ON` 中；不要移到外层 `WHERE` 导致主记录被过滤。主表和子查询各自显式处理删除条件，并保留业务状态、租户或门店范围及权限条件。
+- 已授权的历史查询可在 Custom SQL 中显式使用删除态条件（例如 `is_deleted = 1`），或按业务要求包含两种状态。`includeDeleted` 等自定义参数只有被 SQL 实际消费才有效；查询范围仍须受服务端授权和业务边界约束，不把读取历史记录等同于允许恢复或重复创建。
+- Java Mapper、数据库直连及其他执行通道按各自契约处理；不能套用 Instant API 的自动行为。CLI 的校验和同步不会替业务 SQL 补齐或删除逻辑删除条件。
+- `FOR UPDATE`、`FOR SHARE` 和 `LOCK IN SHARE MODE` 属于加锁查询，与逻辑删除过滤是两个独立要求。保留原锁语义与事务边界，不为通过校验删除锁或互换锁类型；`valid=true` 只表示静态校验通过，不证明锁在实际事务中生效。
+- 运行验证应覆盖主表、关联表与子查询的删除过滤，特别是 `LEFT JOIN` 右表已删除或不存在时的主记录保留语义，以及列表、计数和聚合的一致性。真实业务结果与锁效果交接运行态验证；不能仅凭 SQL 同步成功宣称业务验收通过。
 
-### 1. `rabetbase sql list --format json`
-* **用途**：创建或修改前，搜索同名或相似语义的 SQL。
-* **动作**：若发现相似项，必须与开发者确认是否复用或另起新名，避免冗余创建。
-
-### 2. `rabetbase dataset detail --code xxx --format json`
-* **用途**：写 SQL 前获取表结构，**绝对禁止凭空编造表名或字段名**。
-* **提取项**：
-  * 真实表名：`basic.tableName`
-  * 真实字段列表：`fields` 下的 `code`、`type`、`required`
-  * 数据库 ID：`basic.database.dbId`（`sql create` 时需要）
-
-### 3. `rabetbase sql pull --sqlcode xxx` / `rabetbase sql create --name ... --db-id ... --mode ...`
-* **用途**：把 SQL 先落到本地同步目录，再编辑。
-* **动作**：
-  * 修改已有 SQL → 先 `sql pull --sqlcode <sqlCode>`
-  * 新建 SQL → 先 `sql create --name <sqlName> --db-id <dbId> --mode sql|mybatisXml`
-* **目录**：长期维护的文件统一放在 `.rabetbase/sql/<appCode>/<dbName|db-<id>>/<sqlCode>_<sqlName>.sql|xml`
-
-### 4. `rabetbase sql validate --file xxx --format json`
-* **用途**：推送前的建议卡点。
-* **动作**：如果 `valid: false`，必须根据 `errors` 提示修改 SQL 内容，然后重新执行此命令，直到通过。
-
-### 5. `rabetbase sql status --format json`
-* **用途**：确认当前本地文件是否被识别为 `modified` / `added` / `missing` / `unchanged`。
-* **动作**：若状态与预期不符，先解释原因再继续，不要跳过状态检查直接推送。
-
-### 6. `rabetbase sql push --sqlcode xxx [--dry-run] --format json`
-* **用途**：将同步目录中的本地文件上传到平台。
-* **动作**：
-  * 先 `--dry-run` 看预览
-  * 再移除 `--dry-run` 正式执行
-* **补充**：
-  * 文件名变化会驱动远端 `sqlName` 更新
-  * 文件移动到新的数据库目录时，会尝试按目录重绑 `dbId`
-  * 如果提示 `missing remote version`，先执行 `sql pull`
-
-### 7. `rabetbase sql exec --sqlcode xxx --format json`
-* **用途**：推送成功后的功能测试。
-* **动作**：测试失败（如语法错、数据不符合预期）时，必须在本地文件中修改 SQL -> 重新 validate -> 重新 status -> 重新 push -> 重新 execute，形成闭环。
-
-
----
+资源复用、创建、同步、检查纠错与运行验收统一遵循 [SQL 工作流](sql-creation-workflow.md)。单条命令参数读取对应 reference；表结构与字段按 [dataset detail](../references/rabetbase-dataset-detail.md) 的实际输出获取。
 
 ## 📚 MyBatis 动态 SQL 语法参考（核心）
 
-平台支持 MyBatis 语法。在自定义 SQL 中处理动态参数时，必须遵守以下规范。
+平台支持 MyBatis 语法。在自定义 SQL 中处理动态参数时，必须遵守以下规范。`<foreach>`、`<include>` 等动态内容由平台处理，CLI 上传时保留原文；本地提示不证明所有参数分支可执行。
 
 ### 简单参数 vs 动态参数
 
@@ -72,10 +38,13 @@
 
 ### 动态 SQL 示例（推荐）
 
+以下示例假设 `company.is_deleted = 0` 表示正常记录；固定删除过滤不依赖可选参数。
+
 ```sql
 SELECT id, name, status_code 
 FROM company
 <where>
+    is_deleted = 0
     <if test="statusCode != null and statusCode != ''">
         AND status_code = #{statusCode, jdbcType=VARCHAR}
     </if>