@microi.net/cli 4.9.6 → 4.9.7

package/skills/v8-table-event/references/progressive-01-informv8-js-/350/241/250/345/215/225/346/211/223/345/274/200/344/272/213/344/273/266.md

@@ -0,0 +1,216 @@
+# v8-table-event 详细参考 1
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=v8-table-event-005 sha256=38d1253f165733f4d1064dea9d381c087848f715da8acda7d5aa3bbbee464a86 -->
+## InFormV8.js — 表单打开事件
+
+```javascript
+// 新增时设置默认值
+if (V8.FormMode === 'Add') {
+  V8.FormSet('Status', 1);
+  V8.FormSet('CreateTime', DateNow('yyyy-MM-dd HH:mm:ss'));
+  V8.FormSet('CreatorId', V8.CurrentUser.Id);
+  V8.FormSet('CreatorName', V8.CurrentUser.Name);
+}
+
+// 编辑时禁用某些字段
+if (V8.FormMode === 'Edit') {
+  V8.FieldSet('Account', 'Readonly', true);  // 账号不可修改
+}
+
+// 查看模式隐藏操作按钮
+if (V8.FormMode === 'View') {
+  V8.HideFormBtn('Save');
+}
+
+// 根据角色控制字段可见性
+if (V8.CurrentUser.RoleName.indexOf('管理员') === -1) {
+  V8.FieldSet('AuditField', 'Visible', false);
+}
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-table-event-006 sha256=e62b20919da58241cbe816a3b62d9a8eef5b713f8afab776f69c26f87df691c7 -->
+## SubmitFormV8.js — 前端提交校验
+
+```javascript
+// 自定义校验
+var phone = V8.Form.Phone;
+if (phone && !/^1[3-9]\d{9}$/.test(phone)) {
+  V8.Tips('手机号格式不正确', false);
+  return false;  // 返回 false 阻止提交
+}
+
+// 业务逻辑校验
+if (V8.Form.StartDate > V8.Form.EndDate) {
+  V8.Tips('开始日期不能大于结束日期', false);
+  return false;
+}
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-table-event-007 sha256=4187c2ed36373b1ee239c5668c2ec898a52029b3ce5443aba688ffec4a690a8e -->
+## SubmitBeforeServerV8.js — 服务端提交前
+
+```javascript
+// V8.Form 是即将写入数据库的数据
+// V8.OldForm 是修改前的旧数据（仅更新时有值）
+// V8.FormSubmitAction：'Insert' / 'Update' / 'Delete'
+
+// 新增时：自动填充审计字段
+if (V8.FormSubmitAction === 'Insert') {
+  V8.Form.CreateTime = DateNow('yyyy-MM-dd HH:mm:ss');
+  V8.Form.CreateUserId = V8.CurrentUser.Id;
+}
+
+// 更新时：记录修改人
+if (V8.FormSubmitAction === 'Update') {
+  V8.Form.UpdateTime = DateNow('yyyy-MM-dd HH:mm:ss');
+  V8.Form.UpdateUserId = V8.CurrentUser.Id;
+}
+
+// 删除时：校验是否允许删除
+if (V8.FormSubmitAction === 'Delete') {
+  var related = V8.FormEngine.GetTableDataCount('OrderDetail', {
+    _Where: [['OrderId', '=', V8.Form.Id]]
+  });
+  if (related.DataCount > 0) {
+    return { Code: 0, Msg: '该订单下有明细数据，不允许删除' };
+  }
+}
+
+// 唯一性校验
+if (V8.FormSubmitAction === 'Insert' || V8.FormSubmitAction === 'Update') {
+  var where = [['Code', '=', V8.Form.Code]];
+  if (V8.FormSubmitAction === 'Update') {
+    where.push(['AND', 'Id', '<>', V8.Form.Id]);
+  }
+  var exist = V8.FormEngine.GetFormData('Product', { _Where: where });
+  if (exist.Code === 1 && exist.Data) {
+    return { Code: 0, Msg: '编码已存在' };
+  }
+}
+
+// 返回 { Code: 0, Msg: '...' } 阻止提交并自动回滚事务
+// 无需手动调用 V8.DbTrans.Rollback()
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-table-event-008 sha256=be4accafd23b39c0a2be912d4c0b4f3bc79e43c88604d7a0bfc5637357e13550 -->
+## SubmitAfterServerV8.js — 服务端提交后
+
+```javascript
+// 此时数据已成功写入数据库（仍在事务中）
+// 返回 { Code: 0 } 仍可回滚事务
+
+// 新增后：自动创建关联数据。保持默认 Server 调用，不触发目标表事件
+if (V8.FormSubmitAction === 'Insert') {
+  V8.FormEngine.AddFormData('UserProfile', {
+    UserId: V8.Form.Id,
+    NickName: V8.Form.Name
+  }, V8.DbTrans);
+}
+
+// 更新后：同步更新其它表的冗余字段
+if (V8.FormSubmitAction === 'Update') {
+  if (V8.OldForm.Name !== V8.Form.Name) {
+    V8.FormEngine.UptFormDataByWhere('OrderHeader', {
+      _Where: [['CustomerId', '=', V8.Form.Id]],
+      CustomerName: V8.Form.Name
+    });
+  }
+}
+
+// 通知（调用其他接口引擎，可共享事务）
+V8.ApiEngine.Run('send-notification', {
+  userId: V8.Form.Id,
+  type: V8.FormSubmitAction
+}, V8.DbTrans);
+
+// 记录操作日志
+V8.Method.AddSysLog({
+  Title: V8.FormSubmitAction + ' ' + V8.TableModel.Name,
+  Content: JSON.stringify({ Id: V8.Form.Id }),
+  Type: '业务日志'
+});
+```
+
+`SubmitAfterServerV8` 的“After”仍是“写入后、提交前”。需要在事务真正提交后才发布的缓存版本、跨节点通知等副作用，不能直接在事件中执行。平台为 `microi_database` 提供专用 `V8.Method.RefreshExtensionDatabases()`：事件调用时只登记提交后回调，提交成功才递增当前租户共享 Redis 版本，回滚时自动丢弃。普通业务的外部消息仍优先使用同事务 outbox，不能把任意不可撤销副作用都塞进内存回调。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-table-event-009 sha256=d415302a8108d9e11755a046bdbffe0c84a135ec6ed0e6b1dc3fc128a8ef38b6 -->
+## DataFilterV8.js — 服务端数据处理事件
+
+获取列表/表单数据后，每行数据都会执行一次此事件。
+
+```javascript
+// V8.RowIndex — 当前行索引（从 0 开始）
+// V8.Form — 当前行数据
+// V8.NotSaveField — 指定哪些字段编辑时不保存（数组）
+// V8.CacheData — 用于缓存数据，避免每行重复查询
+
+// 补充计算字段
+V8.Form.TotalPrice = V8.Form.Price * V8.Form.Quantity;
+
+// 指定某些字段不保存（仅在编辑表单时有效）
+V8.NotSaveField = ['TotalPrice', 'CompanyName'];
+
+// 使用 CacheData 避免 N+1 查询
+if (!V8.CacheData.deptMap) {
+  var depts = V8.FormEngine.GetTableData('Department', {});
+  var map = {};
+  for (var i = 0; i < depts.Data.length; i++) {
+    map[depts.Data[i].Id] = depts.Data[i].Name;
+  }
+  V8.CacheData.deptMap = map;
+}
+V8.Form.DeptName = V8.CacheData.deptMap[V8.Form.DeptId] || '';
+
+// 数据脱敏
+if (V8.Form.Phone) {
+  V8.Form.Phone = V8.Form.Phone.substring(0, 3) + '****' + V8.Form.Phone.substring(7);
+}
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-table-event-010 sha256=e3e0593f037fcfe66b6aa12dd342a10e8b270fcfef2cb3dd0dac52d3796973c5 -->
+## 事件上下文变量
+
+### 前端事件
+
+| 变量 | 说明 | 可用事件 |
+|------|------|---------|
+| `V8.Form` | 当前表单数据（新增时也有 Id） | 全部 |
+| `V8.OldForm` | 已加载的修改前旧数据 | 普通表单；提交前/后 |
+| `V8.FormMode` | `'Add'` / `'Edit'` / `'View'` | 全部 |
+| `V8.FormOutAction` | `'Insert'`/`'Update'`/`'Close'`/`'Delete'` | FormOut |
+| `V8.FormSubmitAction` | `'Insert'` / `'Update'` / `'Delete'` | SubmitBefore |
+| `V8.EventName` | 当前事件名 | 全部 |
+| `V8.CurrentUser` | 当前用户 | 全部 |
+| `V8.TableId` / `V8.TableName` | 当前表 Id / Name | 全部 |
+| `V8.SelectedData` / `V8.TableRowSelected` | 选中的行数组 | 列表/批量按钮 |
+| `V8.CurrentTableData` | 当前表当页数据 | 全部 |
+| `V8.ClientType` | `'PC'`/`'IOS'`/`'Android'`/`'H5'`/`'WeChat'` | 全部 |
+| `V8.ThisValue` | 当前字段新值：可能是对象、原始值或行内 `{New,Old}` | FieldValueChange |
+| `V8.OldValue` | 当前字段旧值，仅行内编辑可靠 | 表格行内 FieldValueChange |
+| `V8.KeyCode` | 键盘事件的键码 | FieldOnKeyup |
+| `V8.Event` | 原生事件；键盘事件目前不提供 | FieldSlotButtonClick 等显式事件 |
+| `V8.ParentV8` | 子表中访问父表 V8 对象 | 子表事件 |
+
+### 后端事件
+
+| 变量 | 说明 | 可用事件 |
+|------|------|---------|
+| `V8.Form` | 当前表单/行数据 | 全部 |
+| `V8.OldForm` | 提交前旧数据 | SubmitBefore/After |
+| `V8.FormSubmitAction` | `'Insert'`/`'Update'`/`'Delete'` | SubmitBefore/After |
+| `V8.TableModel` | 表模型（Id, Name 等） | SubmitBefore/After |
+| `V8.EventName` | 当前事件名 | 全部 |
+| `V8.InvokeType` | `'Server'`/`'Client'` | 全部 |
+| `V8.CurrentUser` | 当前用户 | 全部 |
+| `V8.RowIndex` | 行索引（从 0） | DataFilter |
+| `V8.NotSaveField` | 不保存的字段（数组，可写） | DataFilter |
+| `V8.CacheData` | 缓存数据（避免 N+1，可写） | DataFilter |
+
+<!-- /microi-progressive:chunk -->

package/skills/v8-table-event/references/progressive-02-/345/211/215/347/253/257/344/272/213/344/273/266/345/220/215-v8-eventname-/345/217/257/350/203/275/347/232/204/345/200/274.md

@@ -0,0 +1,46 @@
+# v8-table-event 详细参考 2
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=v8-table-event-011 sha256=20342f03d457bd86d1d3e4b80ee8f2ffa254f0b60312a18bc3dab2ce2d448308 -->
+## 前端事件名（V8.EventName 可能的值）
+
+| 值 | 说明 |
+|---|---|
+| `FormIn` | 进入表单事件 |
+| `FormSubmitBefore` | 提交前事件 |
+| `FormOut` | 离开表单事件 |
+| `FieldValueChange` | 字段值变更事件 |
+| `FieldOnKeyup` | 文本框键盘事件 |
+| `TableFieldOnKeyup` | 表格行内文本框键盘事件 |
+| `FieldSlotButtonClick` | 单行文本插槽按钮点击事件 |
+| `V8BtnRun` | V8 按钮执行事件 |
+| `V8BtnLimit` | V8 按钮是否显示事件 |
+| `BtnFormDetailRun` | 详情按钮 V8 按钮 |
+| `TableRowClick` | 表格行点击 V8 事件 |
+| `OpenTableBefore` | 弹出表格前事件 |
+| `OpenTableSubmit` | 弹出表格提交事件 |
+| `PageTab` | 多 Tab 页签 V8 事件 |
+| `WFNodeStart` | 流程节点开始 V8 事件 |
+| `WFNodeEnd` | 流程节点结束 V8 事件 |
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-table-event-012 sha256=380fc790dcf02a27f8b47d9a894b98cb90ebc7ea6b57a5b30075d3d9d32a0262 -->
+## 注意事项
+
+- 前端事件可使用 `window` 对象和 `async/await`，后端事件不可以
+- 后端提交前/后事件返回 `{ Code: 0, Msg: '...' }` 可阻止数据写入并回滚事务
+- 直接修改 `V8.Form` 的字段值即可改变最终写入的数据
+- 后端事件中使用 `V8.FormEngine` 默认是 Server 调用，不触发目标表事件；`_InvokeType:'Client'` 恰好会触发目标表事件，不能用于“避免递归”
+- `_InvokeType:'Server'` 只表达事件调用语义，不是客户端授权开关；浏览器伪造它不会获得受信任权限
+- `V8.FormSubmitAction` 的值是 `'Insert'`/`'Update'`/`'Delete'`（非 Add/Upt/Del）
+- 在 DataFilterV8 中使用 `V8.CacheData` 缓存查询结果，避免每行执行 N+1 查询
+- 表事件调用下游接口时，`diy_table.V8Unlimited` 不会自动放开下游接口；下游 `sys_apiengine.V8Unlimited` 必须独立配置，避免一次开关无边界扩散到整条调用链
+
+### 复盘：提交后事件误把增量表单当作完整记录
+
+- 触发场景：插件、MCP 或后端只更新代码等少数字段时，`SubmitAfterServerV8` 直接对 `V8.Form.Id`、业务 Key 调用 `toLowerCase()`，保存动作因字段未出现在增量参数中而异常。
+- 根因：事件假设 `V8.Form` 始终包含整行数据，没有兼容稀疏更新（sparse patch）。
+- 通用规则：提交后事件使用非本次必传字段前，必须从 `V8.OldForm` 合并兜底，或凭已有 `Id` 回查当前记录；调用字符串方法前先显式 `String(...)` 并校验空值。写缓存时应缓存合并后的完整模型，不能用稀疏对象覆盖整行缓存。
+- 自动化检查：分别只更新一个普通字段、只更新大文本代码字段并执行一次完整表单保存；事件均不得报错，按 Id、唯一 Key 和可选地址回读缓存都应得到完整记录。
+<!-- /microi-progressive:chunk -->

package/skills/v8-workflow/SKILL.md

@@ -9,6 +9,8 @@ description: Microi V8 工作流事件指南。用于编写审批流条件、节
 
 你正在开发 Microi 吾码平台的工作流（审批流程）V8 事件。流程引擎基于表单引擎，通过 V8 事件控制审批逻辑。
 
+<!-- microi-progressive:begin -->
+<!-- microi-progressive:chunk id=v8-workflow-000 sha256=9030cd2de9f1febfb9a749c82cf83e97ccb8fb972a3f8f0ff11067488e14cd8e -->
 ## 本地优先与版本头（必做）
 
 工作流节点、连线条件、开始/结束节点等 V8 代码如果有本地文件，必须优先修改 `microi-v8-engine/<租户>/<项目>/...` 下的本地文件，再同步到数据库。插件提示本地/远端不一致时，先比对并合并，不得直接覆盖。
@@ -30,6 +32,8 @@ description: Microi V8 工作流事件指南。用于编写审批流条件、节
 
 生成工作流 V8 代码时，代码内容本身（文件头、普通注释、`console.log`、返回 `Msg` 等）不要包含 `Microi`、`吾码` 等平台品牌文字，除非业务数据或字段值本身必须如此。生成代码要有可维护注释：每个 `function` 前写清用途、关键参数和返回值；路线选择、审批人计算、状态回写、撤回/驳回处理、跨表联动等复杂代码段前写短注释说明业务原因；避免“给变量赋值”这类无信息量注释。若工作流存储表支持 `Version`/`ChangeHistory`，历史说明也必须最新在前并保留旧记录。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-001 sha256=013233bfa935a24b668691318ea79c2f0a95787d05d0b033b82859a5999878ba -->
 ## 工作流物理表
 
 | 表名 | 说明 |
@@ -64,6 +68,8 @@ var history = V8.Db.FromSql(
  .ToArray();
 ```
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-002 sha256=1f94d40c041929aafc45ec975f42bcbbc50c3ba424ed499c7bdf65fa73a41041 -->
 ## 流程 V8 事件执行顺序
 
 1. 用户点击发起流程或处理工作
@@ -80,6 +86,8 @@ var history = V8.Db.FromSql(
 12. **节点结束 V8 事件（后端 WFNodeEnd）**
 13. **节点结束 V8 事件（前端 WFNodeEnd）**
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-003 sha256=f5776a5b8fe4e460f79e20e9806b3a80bcadf6f1e09408880bd5ca911cb79533 -->
 ## V8.WF 上下文属性
 
 ### 所有流程事件可访问
@@ -113,6 +121,8 @@ var history = V8.Db.FromSql(
 |------|------|
 | `V8.WF.WorkResult` | 流程执行结果（发送到了哪个节点、哪些审批人） |
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-004 sha256=d8445c1d473579fde063179d6330eefaa2373f1166e837656b780058295de3a3 -->
 ## ApprovalType 审批类型
 
 | 值 | 说明 |
@@ -122,6 +132,8 @@ var history = V8.Db.FromSql(
 | `Recall` | 撤回 |
 | `Auto` | 发起流程(开始节点) / 业务节点 / 自动结束节点 |
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-005 sha256=96e49e15fcb4b9da83f46b6818e198f338cb77ce76d11c56dfddebc2cc24f881 -->
 ## 条件判断 V8 事件（后端 WFNodeLine）
 
 根据业务规则决定流程走向。优先推荐设置 `V8.NextNodeId` 直接指定下一节点；如仍使用条件线的条件值，也可以设置 `V8.LineValue`。
@@ -139,88 +151,8 @@ if (V8.Form.Money <= 100) {
 }
 ```
 
-## 节点开始 V8 事件
-
-### 前端 — 指定审批人
-
-```javascript
-// V8.EventName === 'WFNodeStart'
-// 可以强制指定下一节点审批人
-if (V8.Form.DeptId === 'special-dept') {
-  V8.WF.ForceSelectUsers = ['user-id-1', 'user-id-2'];
-}
-```
-
-### 后端 — 阻止流程提交
-
-```javascript
-// V8.EventName === 'WFNodeStart'
-// 返回 Code: 0 可以阻止流程提交并回滚事务
-if (!V8.Form.ApprovalFiles) {
-  V8.Result = { Code: 0, Msg: '请先上传审批附件' };
-}
-```
-
-## 节点结束 V8 事件
-
-### 后端 — 流程结束后业务处理
-
-```javascript
-// V8.EventName === 'WFNodeEnd'
-var approvalType = V8.WF.ApprovalType;
-
-// 同意 — 更新业务状态
-if (approvalType === 'Agree') {
-  // 判断是否到达最终节点
-  var nextNode = V8.WF.NextNode;
-  if (!nextNode || nextNode.NodeType === 'End') {
-    // 流程结束，更新业务状态
-    V8.FormEngine.UptFormData(V8.TableModel.Name, {
-      Id: V8.Form.Id,
-      ApprovalStatus: 'Approved',
-      ApprovalTime: DateNow('yyyy-MM-dd HH:mm:ss')
-    });
-  }
-}
-
-// 拒绝 — 回退状态
-if (approvalType === 'Disagree') {
-  V8.FormEngine.UptFormData(V8.TableModel.Name, {
-    Id: V8.Form.Id,
-    ApprovalStatus: 'Rejected',
-    RejectReason: V8.WF.ApprovalIdea
-  });
-}
-
-// 撤回
-if (approvalType === 'Recall') {
-  V8.FormEngine.UptFormData(V8.TableModel.Name, {
-    Id: V8.Form.Id,
-    ApprovalStatus: 'Draft'
-  });
-}
-
-// 通知下一审批人
-if (V8.WF.NextTodoUsers && V8.WF.NextTodoUsers.length > 0) {
-  for (var i = 0; i < V8.WF.NextTodoUsers.length; i++) {
-    V8.ApiEngine.Run('send-notification', {
-      userId: V8.WF.NextTodoUsers[i].Id,
-      title: '您有新的审批任务',
-      content: V8.CurrentUser.Name + '提交了' + V8.TableModel.Name + '审批'
-    });
-  }
-}
-```
-
-### 前端 — 流程提交后提示
-
-```javascript
-// V8.EventName === 'WFNodeEnd'
-if (V8.WF.WorkResult) {
-  V8.Tips('流程已提交', true);
-}
-```
-
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-006 sha256=e67b72bf060a38ed5f94a57f3978026d151bb971fcf47a0b30a434dba819c264 -->
 ## 前端发起流程
 
 ```javascript
@@ -242,83 +174,10 @@ V8.WF.StartWork({
 });
 ```
 
-## 前端打开流程表单
-
-```javascript
-// 发起流程
-V8.OpenFormWF(V8.Form, 'Add', {
-  WorkType: 'StartWork',
-  FlowDesignId: 'flow-design-id'
-});
+<!-- /microi-progressive:chunk -->
+## 详细参考路由（渐进披露）
 
-// 查看流程
-V8.OpenFormWF(V8.Form, 'View', {
-  WorkType: 'ViewWork',
-  FlowDesignId: 'flow-design-id'
-});
-```
+仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
 
-## MCP 创建/检查/测试工作流
-
-从自然语言需求创建审批流时，优先整理成完整 Manifest 的 `workflows` 配置，再走 MCP 干跑和验收流程。
-
-```json
-{
-  "workflows": [
-    {
-      "FlowDesign": { "FlowName": "请假审批", "table": "diy_leave", "IsEnable": 1 },
-      "Nodes": [
-        { "Id": "start", "NodeName": "发起人", "NodeType": "Start", "LineValueV8": "" },
-        { "Id": "leader", "NodeName": "部门负责人审批", "NodeType": "Approve", "Roles": "dept-leader" },
-        { "Id": "end", "NodeName": "结束", "NodeType": "End" }
-      ],
-      "Lines": [
-        { "Id": "line_start_leader", "FromNodeId": "start", "ToNodeId": "leader", "LineName": "发起人 到 部门负责人审批", "LineValue": "" },
-        { "Id": "line_leader_end", "FromNodeId": "leader", "ToNodeId": "end", "LineName": "部门负责人审批 到 结束", "LineValue": "" }
-      ]
-    }
-  ]
-}
-```
-
-MCP 操作顺序：
-
-1. `microi_get_db_schema`：确认业务表、已有流程、角色、字段。
-2. `microi_get_manifest_schema`：按 Manifest 协议生成 tables/modules/workflows。
-3. `microi_plan_system`：本地干跑，必须修复 workflow 拓扑错误。
-4. `microi_check_workflow_package`：单独检查某个 workflow package。
-5. `microi_test_workflow_condition`：对图形条件生成的 `LineValueV8` 传入样例 `formData`，验证会选中哪条路线。
-6. `microi_generate_system` 或 `microi_save_workflow_package`：用户明确确认后再写入。
-
-工作流建模规则：
-
-- 必须有且仅有 1 个开始节点，至少 1 个结束节点。
-- 所有 `wf_line.FromNodeId/ToNodeId` 必须指向存在的节点。
-- 线路标题 `LineName` 默认使用 `{起点节点名称} 到 {终点节点名称}`，不要把业务条件名写成线路标题。
-- 条件名称只作为图形配置/注释标记里的业务说明；修改条件名称不应改变线路标题。
-- 多出线节点必须配置条件判断 V8，优先设置 `V8.NextNodeId`，只有兼容旧条件值时才设置 `V8.LineValue`。
-- 图形条件生成的 V8 会带 `MICROI_WF_LINE_CONDITION_JSON` 标记，MCP 测试工具只解析该标记，不执行任意手写 V8。
-
-## 发起流程与表单保存
-
-新建业务数据并发起流程时，应先保存表单，再启动流程，或使用平台的合并接口 `StartWorkWithForm` 在同一事务里完成。首次发起建议以 `Add` 模式打开流程表单；如果前端提前生成了 `Id` 但业务表还没有该行，后端会使用 `_NoLineForAdd` 兜底，避免 `UptFormData` 报“数据显示不存在”。
-
-## 流程相关表
-
-| 表 | 说明 |
-|---|---|
-| `WF_FlowDesign` | 流程图设计表 |
-| `WF_Node` | 流程节点属性表 |
-| `WF_Line` | 流程条件(线)属性表 |
-| `WF_Flow` | 流程实例表 |
-| `WF_Work` | 流程工作待办表 |
-| `WF_History` | 流程轨迹表 |
-
-## 注意事项
-
-- 条件判断 V8 事件可以设置 `V8.NextNodeId` 直接指定下一节点；未设置时才按 `V8.LineValue` 匹配条件线的**条件值**
-- 配置图形化条件时，节点/路线标识来自流程拓扑，条件名称只是规则名称，不要用条件名称覆盖 `wf_line.LineName`
-- 节点开始后端事件返回 `{ Code: 0, Msg: '...' }` 或 `V8.Result = { Code: 0 }` 可阻止流程提交
-- 流程事件在事务中执行，任何节点返回失败都会回滚
-- `V8.WF.ApprovalType === 'Auto'` 表示自动节点（发起、业务节点、自动结束），无需人工审批
-- `V8.WF.ForceSelectUsers` 仅在**前端节点开始事件**中有效
+- [references/progressive-01-节点开始-v8-事件.md](references/progressive-01-节点开始-v8-事件.md)：节点开始 V8 事件；节点结束 V8 事件；前端打开流程表单；MCP 创建/检查/测试工作流；发起流程与表单保存；流程相关表；注意事项
+<!-- microi-progressive:end -->

package/skills/v8-workflow/references/progressive-01-/350/212/202/347/202/271/345/274/200/345/247/213-v8-/344/272/213/344/273/266.md

@@ -0,0 +1,180 @@
+# v8-workflow 详细参考 1
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=v8-workflow-007 sha256=9c40c62b67065c7e9f6821ef748d75595f004f069909258d9867490b74e115b7 -->
+## 节点开始 V8 事件
+
+### 前端 — 指定审批人
+
+```javascript
+// V8.EventName === 'WFNodeStart'
+// 可以强制指定下一节点审批人
+if (V8.Form.DeptId === 'special-dept') {
+  V8.WF.ForceSelectUsers = ['user-id-1', 'user-id-2'];
+}
+```
+
+### 后端 — 阻止流程提交
+
+```javascript
+// V8.EventName === 'WFNodeStart'
+// 返回 Code: 0 可以阻止流程提交并回滚事务
+if (!V8.Form.ApprovalFiles) {
+  V8.Result = { Code: 0, Msg: '请先上传审批附件' };
+}
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-008 sha256=f023312e7d95c518428c2e6d1df99b43cc36d41659aa75768b13ff83cf52b3b0 -->
+## 节点结束 V8 事件
+
+### 后端 — 流程结束后业务处理
+
+```javascript
+// V8.EventName === 'WFNodeEnd'
+var approvalType = V8.WF.ApprovalType;
+
+// 同意 — 更新业务状态
+if (approvalType === 'Agree') {
+  // 判断是否到达最终节点
+  var nextNode = V8.WF.NextNode;
+  if (!nextNode || nextNode.NodeType === 'End') {
+    // 流程结束，更新业务状态
+    V8.FormEngine.UptFormData(V8.TableModel.Name, {
+      Id: V8.Form.Id,
+      ApprovalStatus: 'Approved',
+      ApprovalTime: DateNow('yyyy-MM-dd HH:mm:ss')
+    });
+  }
+}
+
+// 拒绝 — 回退状态
+if (approvalType === 'Disagree') {
+  V8.FormEngine.UptFormData(V8.TableModel.Name, {
+    Id: V8.Form.Id,
+    ApprovalStatus: 'Rejected',
+    RejectReason: V8.WF.ApprovalIdea
+  });
+}
+
+// 撤回
+if (approvalType === 'Recall') {
+  V8.FormEngine.UptFormData(V8.TableModel.Name, {
+    Id: V8.Form.Id,
+    ApprovalStatus: 'Draft'
+  });
+}
+
+// 通知下一审批人
+if (V8.WF.NextTodoUsers && V8.WF.NextTodoUsers.length > 0) {
+  for (var i = 0; i < V8.WF.NextTodoUsers.length; i++) {
+    V8.ApiEngine.Run('send-notification', {
+      userId: V8.WF.NextTodoUsers[i].Id,
+      title: '您有新的审批任务',
+      content: V8.CurrentUser.Name + '提交了' + V8.TableModel.Name + '审批'
+    });
+  }
+}
+```
+
+### 前端 — 流程提交后提示
+
+```javascript
+// V8.EventName === 'WFNodeEnd'
+if (V8.WF.WorkResult) {
+  V8.Tips('流程已提交', true);
+}
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-009 sha256=a927ce0325e130608823800c83c85d9e83d54fea61dbcfed32208d49f4012118 -->
+## 前端打开流程表单
+
+```javascript
+// 发起流程
+V8.OpenFormWF(V8.Form, 'Add', {
+  WorkType: 'StartWork',
+  FlowDesignId: 'flow-design-id'
+});
+
+// 查看流程
+V8.OpenFormWF(V8.Form, 'View', {
+  WorkType: 'ViewWork',
+  FlowDesignId: 'flow-design-id'
+});
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-010 sha256=ea15dea212f044a16bdccbf75ebe3a28ce3eb3ff27c989e8c6b4ec567e170032 -->
+## MCP 创建/检查/测试工作流
+
+从自然语言需求创建审批流时，优先整理成完整 Manifest 的 `workflows` 配置，再走 MCP 干跑和验收流程。
+
+```json
+{
+  "workflows": [
+    {
+      "FlowDesign": { "FlowName": "请假审批", "table": "diy_leave", "IsEnable": 1 },
+      "Nodes": [
+        { "Id": "start", "NodeName": "发起人", "NodeType": "Start", "LineValueV8": "" },
+        { "Id": "leader", "NodeName": "部门负责人审批", "NodeType": "Approve", "Roles": "dept-leader" },
+        { "Id": "end", "NodeName": "结束", "NodeType": "End" }
+      ],
+      "Lines": [
+        { "Id": "line_start_leader", "FromNodeId": "start", "ToNodeId": "leader", "LineName": "发起人 到 部门负责人审批", "LineValue": "" },
+        { "Id": "line_leader_end", "FromNodeId": "leader", "ToNodeId": "end", "LineName": "部门负责人审批 到 结束", "LineValue": "" }
+      ]
+    }
+  ]
+}
+```
+
+MCP 操作顺序：
+
+1. `microi_get_db_schema`：确认业务表、已有流程、角色、字段。
+2. `microi_get_manifest_schema`：按 Manifest 协议生成 tables/modules/workflows。
+3. `microi_plan_system`：本地干跑，必须修复 workflow 拓扑错误。
+4. `microi_check_workflow_package`：单独检查某个 workflow package。
+5. `microi_test_workflow_condition`：对图形条件生成的 `LineValueV8` 传入样例 `formData`，验证会选中哪条路线。
+6. `microi_generate_system` 或 `microi_save_workflow_package`：用户明确确认后再写入。
+
+工作流建模规则：
+
+- 必须有且仅有 1 个开始节点，至少 1 个结束节点。
+- 所有 `wf_line.FromNodeId/ToNodeId` 必须指向存在的节点。
+- 线路标题 `LineName` 默认使用 `{起点节点名称} 到 {终点节点名称}`，不要把业务条件名写成线路标题。
+- 条件名称只作为图形配置/注释标记里的业务说明；修改条件名称不应改变线路标题。
+- 多出线节点必须配置条件判断 V8，优先设置 `V8.NextNodeId`，只有兼容旧条件值时才设置 `V8.LineValue`。
+- 图形条件生成的 V8 会带 `MICROI_WF_LINE_CONDITION_JSON` 标记，MCP 测试工具只解析该标记，不执行任意手写 V8。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-011 sha256=ab8c37da582f7463663ab9a609cf31e95c94e38181bc37b7c880a27f19f01a0e -->
+## 发起流程与表单保存
+
+新建业务数据并发起流程时，应先保存表单，再启动流程，或使用平台的合并接口 `StartWorkWithForm` 在同一事务里完成。首次发起建议以 `Add` 模式打开流程表单；如果前端提前生成了 `Id` 但业务表还没有该行，后端会使用 `_NoLineForAdd` 兜底，避免 `UptFormData` 报“数据显示不存在”。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-012 sha256=39a371dc5106862955945741a65c2fd08423cfedbc028e6aba0ba6aadde9cc34 -->
+## 流程相关表
+
+| 表 | 说明 |
+|---|---|
+| `WF_FlowDesign` | 流程图设计表 |
+| `WF_Node` | 流程节点属性表 |
+| `WF_Line` | 流程条件(线)属性表 |
+| `WF_Flow` | 流程实例表 |
+| `WF_Work` | 流程工作待办表 |
+| `WF_History` | 流程轨迹表 |
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-workflow-013 sha256=1e0afbf91035c773357ab43dbc3658a62e368ce65ca329d1047d543558ea2e90 -->
+## 注意事项
+
+- 条件判断 V8 事件可以设置 `V8.NextNodeId` 直接指定下一节点；未设置时才按 `V8.LineValue` 匹配条件线的**条件值**
+- 配置图形化条件时，节点/路线标识来自流程拓扑，条件名称只是规则名称，不要用条件名称覆盖 `wf_line.LineName`
+- 节点开始后端事件返回 `{ Code: 0, Msg: '...' }` 或 `V8.Result = { Code: 0 }` 可阻止流程提交
+- 流程事件在事务中执行，任何节点返回失败都会回滚
+- `V8.WF.ApprovalType === 'Auto'` 表示自动节点（发起、业务节点、自动结束），无需人工审批
+- `V8.WF.ForceSelectUsers` 仅在**前端节点开始事件**中有效
+<!-- /microi-progressive:chunk -->