weaver-e10-builder 1.6.9 → 1.6.11

package/dist/services/workflow-after-submit-comment.js

@@ -0,0 +1,81 @@
+import { SignFileSettings } from './workflow-sign-file-settings.js';
+import { formOf, normalized, wire, verify, keys, P } from './workflow-base-settings.js';
+import { booleanValue } from './workflow-opinion-settings.js';
+import { id } from './workflow-function-management.js';
+export const displayFields = {
+    'after-submit-display': ['customOpen', 'pcForwardType', 'mobileForwardType', 'pcStopInChart', 'mobileStopInChart', 'customPcUrl', 'customMobileUrl'],
+    'comment-set': ['commentSetTypeDTO', 'enableComment', 'allowCommentRelate', 'relateRangeSelect', 'relateRangeBrowser', 'allowUpload', 'uploadCatalogBrowser', 'commentdisplayTypeDTO', 'displayReplyDTO', 'defaultDisplayComment'],
+};
+const routes = {
+    'after-submit-display': ['pathSet/afterSubmitDisplay/getAfterSubmitDisplayFormData', 'pathSet/afterSubmitDisplay/saveAfterSubmitConfig'],
+    'comment-set': ['commentset/getCommentSet', 'commentset/saveCommentSet'],
+};
+export class AfterSubmitCommentSettings extends SignFileSettings {
+    async readDisplay(kind, w) {
+        const raw = await this.get(`${P}/${routes[kind][0]}`, { workflowId: id(w), ...(kind === 'after-submit-display' ? { global: false } : {}) });
+        const f = formOf(kind === 'comment-set' ? raw.commentSet : raw);
+        for (const k of ['pcStopInChart', 'mobileStopInChart', 'displayReplyDTO'])
+            if (Array.isArray(f.data[k]))
+                f.data[k] = f.data[k].filter((v) => v !== '');
+        return f;
+    }
+    async displayCandidates(w, k) {
+        const f = await this.readDisplay('comment-set', w), b = f.items[k]?.browserBean;
+        const expected = k === 'uploadCatalogBrowser' ? ['doc', 'folder'] : ['bcw', 'relevanceScopeItemBrowser'];
+        if (!b || b.module !== expected[0] || b.type !== expected[1])
+            throw Error('当前环境未开放支持的候选浏览器');
+        return this.post(`/api/${b.module}/common/browser/data/${b.type}`, { ...b.commonParams, ...b.dataParams, current: 1, pageNo: 1, pageSize: 100 });
+    }
+    async saveDisplay(kind, w, p) {
+        const allowed = displayFields[kind];
+        keys(p, allowed);
+        if (!Object.keys(p).length)
+            throw Error('请指定修改项');
+        const f = await this.readDisplay(kind, w), before = normalized(f), flag = kind === 'comment-set' ? 'commentSetTypeDTO' : 'customOpen';
+        let next = normalized(f);
+        for (const [k, v] of Object.entries(p)) {
+            const item = f.items[k];
+            if (!item || item.disabled || item.disable || item.readOnly)
+                throw Error(`${k} 当前环境不可编辑`);
+            if (['relateRangeBrowser', 'uploadCatalogBrowser'].includes(k)) {
+                const alias = k === 'relateRangeBrowser' ? 'relateMatterRangeBrowser' : k;
+                next[k] = await this.selection({ ...f, items: { ...f.items, [alias]: item } }, alias, v);
+            }
+            else if (item.itemType === 'INPUT') {
+                if (typeof v !== 'string')
+                    throw Error(`${k} 必须为字符串`);
+                next[k] = v;
+            }
+            else
+                next[k] = (await this.patch(f, { [k]: v }, allowed))[k];
+        }
+        if (!booleanValue(next[flag]) && Object.keys(p).some(k => k !== flag))
+            throw Error('修改具体配置须先或同时 --custom 1；关闭自定义时只修改自定义开关');
+        if (kind === 'after-submit-display' && booleanValue(next.customOpen)) {
+            for (const [type, url] of [['pcForwardType', 'customPcUrl'], ['mobileForwardType', 'customMobileUrl']])
+                if (next[type] === '3') {
+                    const value = next[url];
+                    if (typeof value !== 'string' || !value.trim() || value !== value.trim() || !(/^(\/(?!\/)|https?:\/\/[^/\s]+)/i.test(value)) || /[\r\n]/.test(value))
+                        throw Error(`${url} 必须是 / 开头内部地址或 http(s) 地址`);
+                }
+        }
+        if (kind === 'comment-set' && booleanValue(next[flag]) && booleanValue(next.enableComment) && booleanValue(next.allowCommentRelate) && next.relateRangeSelect === '1' && !next.relateRangeBrowser?.length)
+            throw Error('选择关联范围须指定非空 --relate-items');
+        const payload = { ...wire(f, next), workflowId: id(w) };
+        if (kind === 'after-submit-display')
+            payload.global = false;
+        else {
+            payload.commentSetTypeDTO = booleanValue(next.commentSetTypeDTO);
+            if ('uploadCatalogBrowser' in next)
+                payload.uploadCatalog = next.uploadCatalogBrowser?.[0]?.id ?? '0';
+        }
+        const result = await this.post(`${P}/${routes[kind][1]}`, payload);
+        if (kind === 'after-submit-display' ? !(typeof result === 'number' && result > 0) : !result || typeof result !== 'object' || !result.id)
+            throw Error('保存未返回有效成功结果');
+        const after = normalized(await this.readDisplay(kind, w));
+        const inherited = kind === 'comment-set' && !booleanValue(next[flag]);
+        verify(next, after, inherited ? [flag] : allowed);
+        return { workflowId: w, before, after, verified: true, ...(inherited ? { effectiveScope: 'application', verificationScope: '自定义已关闭；after为全局生效配置' } : {}) };
+    }
+}
+//# sourceMappingURL=workflow-after-submit-comment.js.map

package/dist/services/workflow-after-submit-comment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-after-submit-comment.js","sourceRoot":"","sources":["../../src/services/workflow-after-submit-comment.ts"],"names":[],"mappings":"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"}

package/ecodecmd/src/build.js

@@ -141,6 +141,15 @@ function scannerResources(path_name, rootFolder, resFolder, temp_dir) {
   return resources;
 }
 
+/**
+ * pidMap 的键归一化：统一分隔符与盘符大小写。
+ * Windows 下 parse_path 可能来自命令行（正斜杠），而 path.join 产出反斜杠，
+ * 直接用原串当键会导致根目录下的子文件夹取不到 parentId，导入后整棵子树丢失。
+ */
+function pkey(p) {
+  return String(p || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+}
+
 /**
  * 获取pids
  * @param pidMap id映射关系
@@ -159,7 +168,7 @@ function getPids(pidMap, rootFolder, tmp_path, parse_path) {
     if (t++ > 10) {
       throw new Error("文件层级超过10");
     }
-    path.push(pidMap[itemObj.parentDir]);
+    path.push(pidMap[pkey(itemObj.parentDir)]);
     itemObj = utils.parseFileObj(itemObj.parentDir);
     // console.log('111itemObj', itemObj.path);
   }
@@ -174,7 +183,7 @@ function getPids(pidMap, rootFolder, tmp_path, parse_path) {
  * @param parse_path
  */
 function checkAddConfig(cfgName, rootFolder, pidMap, parse_path, ecodeJson, state) {
-  let fincCfg = ecodeJson.codes.find(c => c.name === cfgName && c.parentId === pidMap[path.join(parse_path, 'config')]);
+  let fincCfg = ecodeJson.codes.find(c => c.name === cfgName && c.parentId === pidMap[pkey(path.join(parse_path, 'config'))]);
   if (!fincCfg) {
     // 添加文件
     ecodeJson.codes.push({
@@ -186,8 +195,8 @@ function checkAddConfig(cfgName, rootFolder, pidMap, parse_path, ecodeJson, stat
       flowNum: 0,
       id: createSnowFlakeId(),
       name: cfgName,
-      parentId: pidMap[path.join(parse_path, 'config')],
-      parentIds: `,${rootFolder.id},${pidMap[path.join(parse_path, 'config')]},`,
+      parentId: pidMap[pkey(path.join(parse_path, 'config'))],
+      parentIds: `,${rootFolder.id},${pidMap[pkey(path.join(parse_path, 'config'))]},`,
       rootFolderId: rootFolder.id,
       sourceId: 0,
       state,
@@ -197,7 +206,13 @@ function checkAddConfig(cfgName, rootFolder, pidMap, parse_path, ecodeJson, stat
 }
 
 function pretreatmentCode(content, tmpObj, parse_path) {
-  const refPath = tmpObj.path.replace(parse_path, '').replace(/\\/g, '/').substring(1);
+  // 模块名必须是相对项目根的路径。Windows 下 parse_path 与文件路径的分隔符可能不一致，
+  // 直接 replace 会剥不掉前缀，模块名变成 ":/盘符/绝对路径"，运行时 require 失败（白屏）
+  const normFile = String(tmpObj.path).replace(/\\/g, '/');
+  const normRoot = String(parse_path).replace(/\\/g, '/').replace(/\/+$/, '');
+  const refPath = normFile.startsWith(normRoot)
+    ? normFile.slice(normRoot.length).replace(/^\//, '')
+    : normFile.split('/').pop();
   let res = content
       .replace(/"use strict";\n\n/, "")
       .replace(/(\n)+/g, (v) => `${v}    `)
@@ -311,6 +326,9 @@ async function buildWithE10(path_name) {
   }
   // 查询是否存在配置文件
   const buildJson = JSON.parse(fs.readFileSync(path.join(path_name, 'build.json')));
+  // build.json 的键由本机路径拼成（Windows 下是反斜杠），查 state 时统一归一化
+  const buildCodesNorm = {};
+  Object.keys(buildJson.codes || {}).forEach((k) => { buildCodesNorm[pkey(k)] = buildJson.codes[k]; });
   // 创建临时目录
   const temp_dir = path.join(parse_path, ".temp");
   if (!utils.mkdirs(temp_dir, true)) {
@@ -351,7 +369,7 @@ async function buildWithE10(path_name) {
   const resources = scannerResources(path_name, rootFolder, resFolder, temp_dir);
   ecodeJson.resources = resources;
   const pidMap = {};
-  pidMap[parse_path] = rootFolder.id;
+  pidMap[pkey(parse_path)] = rootFolder.id;
   const path_dp = [];
   path_dp.push(parse_path);
   // 遍历当前目录
@@ -382,7 +400,13 @@ async function buildWithE10(path_name) {
         compileContent = pretreatmentCode(compileJsE10(compileContent, tmpObj.path) || '', tmpObj, parse_path);
       }
       // 需要兼容window 处理路径
-      let codeKeyPath = tmpObj.path.replace(parse_path, '').substring(1);
+      // 相对路径同样要归一化：Windows 下 parse_path 与 path.join 产出的分隔符可能不同，
+      // 直接 replace 会剥不掉前缀，导致 build.json 里的 state 查不到（entry.js 退化成非前置加载）
+      const normFile = String(tmpObj.path).replace(/\\/g, '/');
+      const normRoot = String(parse_path).replace(/\\/g, '/').replace(/\/+$/, '');
+      let codeKeyPath = normFile.startsWith(normRoot)
+        ? normFile.slice(normRoot.length).replace(/^\//, '')
+        : normFile.split('/').pop();
       // if (codeKeyPath && codeKeyPath.includes("\\")) {
       //   codeKeyPath = codeKeyPath.replace(/\\/g, '/');
       // }
@@ -401,8 +425,8 @@ async function buildWithE10(path_name) {
         rootFolderId: rootFolder.id,
         sourceId: 0,
         systemFlag: rootFolder.systemFlag,
-        state: (buildJson.codes[codeKeyPath] || buildJson.codes['/' + codeKeyPath])?.state || 'n', // 是否前置加载,
-        parentId: pidMap[tmpObj.parentDir],
+        state: (buildCodesNorm[pkey(codeKeyPath)] || buildCodesNorm[pkey('/' + codeKeyPath)])?.state || 'n', // 是否前置加载,
+        parentId: pidMap[pkey(tmpObj.parentDir)],
         parentIds: getPids(pidMap, rootFolder, tmp_path, parse_path)
       };
       // console.info('file tmpObj.name => ', tmpObj.name, tmpObj.path, tmpObj.isDir)
@@ -435,12 +459,12 @@ async function buildWithE10(path_name) {
           officialFlag: rootFolder.officialFlag,
           systemFlag: rootFolder.systemFlag,
           treeType: 'R',
-          parentId: pidMap[utils.parsePath(tmpObj.parentDir)],
+          parentId: pidMap[pkey(utils.parsePath(tmpObj.parentDir))],
           parentIds: getPids(pidMap, rootFolder, tmp_path, parse_path),
           attribute,
         }
         // console.info('tmpObj.name => ', tmpObj.name, tmpObj.path, tmpObj.isDir)
-        pidMap[tmp_path] = folderObj.id;
+        pidMap[pkey(tmp_path)] = folderObj.id;
         ecodeJson.folders.push(folderObj);
       }
 
@@ -459,7 +483,7 @@ async function buildWithE10(path_name) {
   });
   if (!findConfigFolder) {
     const configId = createSnowFlakeId();
-    pidMap[path.join(parse_path, 'config')] = configId;
+    pidMap[pkey(path.join(parse_path, 'config'))] = configId;
     ecodeJson.folders.push({
       appUUID: rootFolder.appUUID,
       attribute: 'G',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weaver-e10-builder",
-  "version": "1.6.9",
+  "version": "1.6.11",
   "description": "Eteams/Ebuilder CLI — 泛微 OA 命令行工具",
   "type": "module",
   "files": [

package/skill-docs/SKILL.md

@@ -2,11 +2,11 @@
 name: weaver-e10-builder
 display_name: 泛微E10智能搭建Skill
 display_name_en: E10 Builder
-description: 泛微E10智能搭建skill v2（通用版），辅助编写泛微Ebuilder自定义应用，对应CLI版本1.6.9
-description_zh: 泛微Ebuilder低代码应用智能搭建工具 v2（通用版），辅助编写自定义应用（表单/流程/列表/动作流/权限/分组/编号等），与 e10-cli 配套使用，当前对应 CLI 版本 1.6.9。
-description_en: E10 Ebuilder low-code app builder skill v2 (general) — helps build Weaver E10 custom apps (forms/workflows/lists/actionflows/permissions/groups/numbering) via e10-cli, currently paired with CLI 1.6.9.
+description: 泛微E10智能搭建skill v2（通用版），辅助编写泛微Ebuilder自定义应用，对应CLI版本1.6.11
+description_zh: 泛微Ebuilder低代码应用智能搭建工具 v2（通用版），辅助编写自定义应用（表单/流程/列表/动作流/权限/分组/编号等），与 e10-cli 配套使用，当前对应 CLI 版本 1.6.11。
+description_en: E10 Ebuilder low-code app builder skill v2 (general) — helps build Weaver E10 custom apps (forms/workflows/lists/actionflows/permissions/groups/numbering) via e10-cli, currently paired with CLI 1.6.11.
 category: coding
-version: 1.6.9
+version: 1.6.11
 author: 泛微网络科技股份有限公司
 auto: true
 ---

package/skill-docs/_catalog.md

@@ -58,8 +58,16 @@
 | 报表权限、共享范围、viewRight、权责矩阵 | `references/report/report-permission-guide.md` |
 | 报表版本、快照、生命周期、回收站、复制挂菜单 | `references/report/report-lifecycle-api-guide.md` |
 | 报表条件格式、数据条、图标集 | `references/report/condition-format-guide.md` |
+| 汇总格、合计行、合计列、分组汇总、子表 1:N 收敛成一行、汇总锚点、汇总格父格、扩展块父格、合计行父格、自增序号、Sheet 跳转 | `references/report/cross-dataset-filter-guide.md`（§2.3.2 汇总格三件套）· `references/report/expansion-block-parent-config-guide.md` · `references/report/branch-scene-guide.md` |
+| 卡片式报表、一条记录一张卡片、发票卡片、设备卡、工单卡、段落明细表、档案报表、人物档案、钻取、下钻、分页分组、每页固定行数、分片冻结、宽表不分页、行分栏、列分栏、分栏报表、折叠树、树形展开、多级列组、同比环比、财务统计表、多报表交叉案例 | `references/report/card-report-guide.md` · `dossier-report-guide.md` · `drilldown-report-guide.md` · `paged-group-report-guide.md` · `shard-freeze-report-guide.md` · `column-split-report-guide.md` · `advanced-crosstab-tree-guide.md` · `crosstab-raw-workbook-guide.md` · `financial-stats-report-guide.md` · `multi-report-crosstab-casebook.md`（同目录） |
+| 报表验证纪律、回读清单、diff 键、字节安全、克隆纪律、服务端与浏览器端差异 | `references/report/report-verification-discipline-guide.md` |
+| 报表案例提示语、可粘贴需求描述、需求分析模板、需求拆解 | `references/report/report-case-prompts.md` · `references/report/report-requirement-analysis-template.md` |
+| 报表设计器功能说明、帮助手册、打印导出、主题样式、页面布局 | `references/report/report-help-guide.md` · `references/report/report-designer-feature-map.md` |
+| 报表搭建失败收尾、空壳清理、失败不阻塞、部分保存 | `references/report/build-resilience-guide.md` · `references/report/safe-partial-save-guide.md` · `references/report/failure-cleanup-and-nonblocking-guide.md` |
+| 报表搭建顺序、建壳流程、保存判定、公式四件套、克隆纪律、字段绑定、雪花 id 精度 | `references/report/report-building-guide.md` · `references/report/api-report-build-fast-path.md` · `references/report/snowflake-id-precision-guide.md` · `references/report/field-bind-exact-match-guide.md` |
+| 报表定位、只改点名项、改动范围、修复顺序 | `references/report/targeted-fix-guide.md` · `references/report/user-request-scope-only-guide.md` |
 | 新页面、导出、路由、entry.js、regOvProps、regReactChildren、asyncImport、publicUrl、Suspense、${appId} 固定写法、appId 填数字 | `references/coding/guide-page-export.md`（前端代码） |
-| 写页面、页面代码、React编码、组件、entry.js模板、formClient、字段常量 | `references/coding/guide-page-code.md`（前端代码） |
+| 写页面、页面代码、React编码、组件、entry.js模板、formClient、字段常量、当前用户、currentUser、window.TEAMS、租户、tenantKey、主题色、语言、权限码、authorityList、部门树、组织架构、getOrgTree、人员搜索、getEmployeeByKeyWords、页面发起流程、flowpage、预填跳转 | `references/coding/guide-page-code.md`（前端代码） |
 | HTML 原型还原、HTML 转 React、原型 CSS、复用样式、不写 CSS、class/className、内联 style、浮层、Portal、CSS 作用域 | `references/coding/guide-html-to-react.md`（前端代码） |
 | 页面设计器、配置式页面、仪表盘、看板页、designer、page create、comp-add、工厂模板、factory、组件模板、页面布局、designer layout/save、页面版本、version revert、发布页面菜单、publish-menu、自定义CSS、组件样式、选择器、DOM结构、样式不生效 | `references/ebuilder-designer/guide-designer.md`（布局层主干）· `guide-designer-components.md`（组件 config）· `guide-designer-factory.md`（工厂模板）· `guide-designer-version.md`（版本）· `guide-designer-css.md`（自定义 CSS 与 DOM 结构索引） |
 
@@ -80,6 +88,7 @@
 
 | 用户意图关键词 | 加载文档 |
 |---------------|---------|
+| 组件通用属性、components 通用、className、style、customRender、overlayClassName、prefixCls、CSS 变量、组件主题、弹层样式、表单组件通用属性、readOnly/required/disabled | `references/components/ref-component-common.md` |
 | Button、按钮 | `references/components/@weapp-Button.md` |
 | Table、表格 | `references/components/display-Table.md` |
 | List、列表 | `references/components/display-List.md` |

package/skill-docs/actionflows/SKILL.md

@@ -34,6 +34,7 @@ description: "将业务需求编译为 Weaver ESB 动作流，或读取已有动
 - 流程：`e10-cli actionflow workflow-browser-list` / `workflow-search` / `workflow-nodes`。
 - 流程动态字段：`e10-cli actionflow workflow-context-fields`。默认每页 20 条；按需求字段名先传 `query`（例如 `{"workflowId":"<id>","query":"数据ID"}`），只使用本次返回的 `fields[].paramKey`。完整响应过大时用 `--out context.json` 落盘，禁止依赖终端截断后的片段。
 - 其他组件动态字段：`e10-cli actionflow component-context-fields '{"componentType":"<组件类型>","currentApplication":"<当前动作流ID；新建传0>","eventNodeId":"<上游节点ID>","params":{...},"query":"<字段名或关键词>"}'`。该命令会先解析数据源 Browser，再查询 `showDataSourceFields` 匹配实际可选输出字段，随后编译组件上下文并调用 `getComponentContext`。`EnquiryForm`、`TimeBatchTrigger`、`DateTrigger` 都适用。**必须在写入任何动态赋值前查询来源组件**；只允许从本次 `getComponentContext` 结果选择 `fields[].paramKey`，接口未返回的字段必须先查明该组件是否有受支持的依据值/循环语义，否则停止该映射，不得凭字段名、约定根节点或历史经验补造。
+- 数据源名称通过 Browser 模糊搜索：只有一个候选时使用该候选；多个候选时展示名称、所属应用和 ID，让用户选择。拿到选择的 ID 后重新解析；数据源 ID 和 `type/sourceType` 均使用接口返回值。
 - 计划按执行顺序构造时，先查询触发器，再逐个查询会提供动态数据的上游动作；每一步都用该组件本次真实参数（尤其数据源、目标表和选中的字段）查询。下游映射只能选择已查询来源返回的字段。`generate` 的预检是最后一道校验，不可代替生成前的字段发现。
 - e-builder（**已知表名时首选**）：`e10-cli actionflow form-search '{"keyword":"<表名>"}'` 一次拿到表单 `objId` 与它所属的业务应用 `appId`。服务端是**子串模糊匹配**，同名表跨多个应用很常见（返回体里的 `完全同名` 即同名条数）—— **多于一条时必须按 `appName` 收窄再取**，不得自行挑一个：`'{"keyword":"<表名>","appName":"<应用名>"}'`。`keyword` 传 `objId` 则是精确命中，可用来由 id 反查所属应用。
   - **`appName` 走服务端过滤**（不是本地二次筛）：应用名精确唯一才用；**同名多命中或查无此名会直接报错并列出候选**，此时改用 `appId` 指定，不要换个近似名重试。

package/skill-docs/actionflows/references/components/ebuilder/EnquiryForm.md

@@ -55,7 +55,7 @@
 关键结构（与旧结论不同，已修正）：
 
 1. **EnquiryForm 节点（首动作）**：
-   - `dataSource.type = "LOGIC"`、`dataSource.groupId = "weaver-ebuilder-form-service"`（不是表单所属应用 id！）
+   - 此历史样本的 `dataSource.type` 是 `LOGIC`；生成时必须使用当前 Browser 返回的真实 `type/sourceType`，不能据样本推断。查询服务组是 `weaver-ebuilder-form-service`。
    - `queryFields[].id = "id"`（简写，不是 `{表id}[].id`）；`fieldGroup = { name: 表名, id: 表id }`
    - 筛选：`filterInput.datas[].conditions.value` 用流程上下文 type=3（`ApprovalData.{wfId}.requestId`）
    - 首动作 **不需要 sources**（undefined），ActionEbAdd 的 sources 指向 EnquiryForm 节点 wId
@@ -68,7 +68,7 @@
 
 3. 其余明细字段仍用依据值下级 type=10 直连（paramKey `{wfId}.{明细表id}[].{子字段id}`，source=event 节点 id）。
 
-4. 挂接注意：EnquiryForm 作为**流程首动作**保存成功；此前「两个起始执行组件」报错疑与给首动作补 sources 或 dataSource.type 用 FORM 有关，**勿给首动作补 sources**。
+4. 挂接注意：EnquiryForm 作为**流程首动作**保存成功，首动作不要补 sources。数据源类型以当前接口实际返回为准。
 
 计划中引用该结果时，必须显式写 `kind:"query_result"`，不能把它写成普通流程字段。例如：
 

package/skill-docs/actionflows/references/components/trigger/CustomTrigger.md

@@ -43,6 +43,8 @@
 
 自定义参数的字段定义是业务特定的。根据需求新建时可以直接提供 `tableList` 和字段；`tableList` 或其中的 `fields` 为空时，设计器“输入参数设置”就是空白。已有组件的更新场景如需保留平台生成的 `customId`，应使用平台回读 DTO，不要把更新 DTO 当作新建 DTO。
 
+需求中的每张明细表都在 `tableList` 中单独配置一个 `isMain: false` 的表，并将该表的明细字段放入它自己的 `fields`。多张明细表分别配置；不要把它们的字段合并到一张表或主表。明细表在运行时表示可重复的对象列表，后续新增目标明细时先查询 `getComponentContext`，再从返回结果选择对应明细表作为依据值，选择该表的下级字段进行映射。
+
 根触发器图标不是 `Icon-custom-trigger`，编译器统一保存为 `Icon-N-Triggerrul`。
 
 ## 上下文

package/skill-docs/actionflows/references/components/trigger/WebHookTrigger.md

@@ -60,7 +60,25 @@
 
 Webhook 请求运行时由平台解析为三个上下文分组：`Params`、`Header`、`Body`。动作参数中的上下文引用使用完整路径，例如 `Params.orderId`、`Header.Authorization`、`Body.customer.name`；不要把它们写成 `FormData.*`。
 
-`authAppIds` 是 WebHook 触发器的必填认证应用列表，元素必须是 `{ "id": <应用ID>, "content": "<应用名称>" }`。生成前 CLI 会使用当前会话调用 `openApplicationBrowser` 并自动回填；默认使用接口返回的全部应用。如需限定范围，可在语义计划中传 `authAppNames: ["普通应用-wull"]`，CLI 会将筛选结果写入 `authAppIds`。没有认证应用时，CLI 不应生成 WebHook 触发器。
+### 请求中的明细表
+
+需求中有明细表时，每张明细表对应 Body 中一个 JSON 对象数组。参数设置里，数组父参数使用 `paramType: "json"`、`arrs: true`；每个明细字段作为子参数，通过 `parentId` 指向所属数组。多张明细表分别配置，允许不同数组包含同名子字段。例如：
+
+```json
+{
+  "name": "Body",
+  "tableData": [
+    { "id": "devices", "paramName": "devices", "showName": "设备明细", "paramType": "json", "arrs": true },
+    { "id": "deviceName", "parentId": "devices", "paramName": "name", "showName": "设备名称", "paramType": "string" },
+    { "id": "materials", "paramName": "materials", "showName": "材料明细", "paramType": "json", "arrs": true },
+    { "id": "materialName", "parentId": "materials", "paramName": "name", "showName": "材料名称", "paramType": "string" }
+  ]
+}
+```
+
+上例对应请求 `{"devices":[{"name":"设备A"}],"materials":[{"name":"材料A"}]}`。配置新增明细时，先调用 `getComponentContext`，使用返回的数组字段作为对应目标明细的依据值，使用该数组下级字段映射目标明细字段；参数路径、字段 ID 和上下文根以接口返回值为准。不得混用不同数组的子字段。
+
+`authAppIds` 是 WebHook 触发器的认证应用列表，必须明确指定一个应用。可传应用 ID 或 `authAppNames: ["普通应用-wull"]`；生成前 CLI 调用 `openApplicationBrowser` 匹配并回填 `{ "id": <应用ID>, "content": "<应用名称>" }`。未指定或匹配不到时停止生成。
 
 ## 终止节点响应
 

package/skill-docs/references/coding/guide-form-crud.md

@@ -4,6 +4,8 @@ Ebuilder 项目没有后端，页面通过读写 Ebuilder 表单完成增删改
 
 > 表单元数据用 `e10-cli form read <objId> --app-id <appId> --out fields.json` 导出。字段 ID 以导出结果为准，不要自己编。
 
+> `formClient` 只管**表单和明细表**的数据。人员、部门、组织、文档这些平台域数据不在这里，也不要用它去查：选人和上传用 `@weapp/ui` 的 `Browser` / `Upload`，它们自带数据层。组件选中的值在写进表单字段时才交给 `formClient`，见 `guide-page-code.md` 第六节。
+
 ---
 
 ## 一、先准备字段常量

package/skill-docs/references/coding/guide-page-code.md

@@ -189,6 +189,68 @@ export default function Items() {
 
 ---
 
+### 页面上还能拿到什么：`window.TEAMS`
+
+页面运行在平台壳里，当前用户、租户、主题、语言都挂在全局 `window.TEAMS` 上，**不要硬编码**。模块顶层取一次：
+
+```js
+function readTeams() {
+  if (typeof window !== 'undefined' && window.TEAMS) return window.TEAMS;
+  return {};
+}
+
+var TEAMS = readTeams();
+var ME = TEAMS.currentUser || {};
+var TENANT = TEAMS.currentTenant || {};
+```
+
+| 用途 | 取值 |
+|---|---|
+| 当前用户 ID（写入创建人、参与人） | `ME.id` |
+| 姓名 / 工号 / 账号 | `ME.name` / `ME.jobNum` / `ME.username` |
+| 所属部门 | `ME.department.id` / `ME.department.name`（另有 `datarank` / `rank`） |
+| 系统角色与管理员标记 | `ME.authorityList`（如 `["ROLE_ADMIN"]`）、`ME.admin` / `ME.sysAdmin` / `ME.moduleAdmin` |
+| 租户 | `TENANT.tenantKey` / `TENANT.tenantName` |
+| 跟随平台主题 | `TEAMS.theme.primaryColor` / `TEAMS.theme.fontDensity` |
+| 语言 | `TEAMS.locale.lang` |
+| 已开通模块 | `TEAMS.displayModules` |
+
+**边界**：
+
+- 这些字段随平台版本增减，只取用到的，不要整个对象透传或落库；
+- `authorityList` 是**系统级**角色码，不等于业务角色；业务上的"谁能审批、谁能看这个页面"，以服务端权限和数据为准；
+- 前端按这些字段隐藏按钮只是体验优化，**不能当权限校验**；
+- 拿不到时（本地调试、非平台环境）按空对象降级，不要直接抛错。
+
+### 组织架构：部门树与人员
+
+**默认用组件**：选人、选部门、人员列表都用 `Browser`（`module="hrm"`，`type="resource"` / `"department"`），它自带数据、分页与权限口径。不要把组件能做的事改成自己拉接口。
+
+只有页面要**自己画出部门树**（组件只提供选择弹窗，给不了树）或**自己写人员搜索框**时，才用下面两个平台接口。同源请求自动带 cookie：
+
+```js
+// 部门树
+var res = await fetch('/api/hrm/common/getOrgTree?menuCode=eBuilder&onlySubcompany=false'
+  + '&containDisableDept=false&moduleCode=EBUILDER&virtualId=1&loadCount=false&isMobile=false');
+var tree = (await res.json()).data;   // 节点：{ id, content, parentId, children, isLeaf, nodeType: 'department' }
+
+// 人员搜索
+var r2 = await fetch('/api/hrm/common/getEmployeeByKeyWords', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ keyword: '张', searchType: 1, searchCount: 20, pageNo: 1, pageSize: 20,
+    appDetachModule: 'EM', disableAppDetach: 0 })
+});
+var users = (await r2.json()).data.userList;   // { id, name, department, departmentId, avatar, status }
+```
+
+| 接口 | 返回 |
+|---|---|
+| `GET /api/hrm/common/getOrgTree` | `data[]` 部门树，`content` 是部门名，`parentId` 串成树 |
+| `POST /api/hrm/common/getEmployeeByKeyWords` | `data.userList[]`，`id` 是人员 ID，`department` / `departmentId` 是所属部门 |
+
+**边界**：这两个是平台前端内部接口，随版本可能变；能用 `Browser` 的地方不要用接口。人员 ID 写进表单字段时按 `values` 的规则处理（多值逗号串）。
+
 ## 五、HTML 原型还原
 
 用户提供 HTML / 设计稿并要求还原时，读 `guide-html-to-react.md`。核心规则：
@@ -223,6 +285,21 @@ export default function Items() {
 
 文本框、数字、日期、下拉框用原生 HTML，不要为了用组件而用组件。原型还原优先用原生 HTML + 原型 CSS，平台组件只用于人员/部门选择、上传、文件预览等必须能力。
 
+组件的通用属性（`className` / `style` / `customRender` / 表单类通用属性）与改样式的四层钩子见 `references/components/ref-component-common.md`。
+
+### 组件自带的数据，不要再自己查
+
+`Browser`（人员 / 部门 / 组织）、`Upload`、`FilePreview` 自带数据层：搜索、选择、回显都由组件去请求平台对应的组织、人员、文档接口。页面不要再自己调这些接口，也不要用 `formClient` 去查 —— 组织、人员、文档不属于表单数据，换了通道也拿不到同一份权限口径。
+
+分工是单向的：
+
+| 环节 | 归谁 |
+|---|---|
+| 选人 / 选部门 / 选组织、上传、预览 | 组件 |
+| 把选中的值写进表单字段、再读回来 | `formClient` |
+
+组件的 `value` 与 `onChange` 都是 `[{ id, name }]`。`onChange` 拿到后只把 `id` 写进 `values`（多值逗号串）；回显用行里的 `items[字段ID]`，见 `guide-edit-backfill.md`。
+
 ---
 
 ## 七、平台硬规则
@@ -271,3 +348,34 @@ export default function Items() {
 | 列表没传 `page/size` | 默认可能只回 10 条，显式传 |
 | 样式拆成独立 `.css` | 放回原型 CSS 字符串 |
 | 把 `const appId = '${appId}'` 当变量用 | 不需要这个变量，直接写在 `asyncImport` 里 |
+
+---
+
+## 十、页面与流程协作
+
+**发起流程走平台页面，不要自己调接口创建流程。** 页面里只负责拼链接：
+
+```js
+// 流程 ID 放 app/config.js；具体值用 e10-cli workflow list <appId> 查
+var WORKFLOW_ID = '流程ID';
+
+function startFlow(workflowId, prefill) {
+  var url = '/sp/workflow/flowpage/create/' + workflowId;
+  var params = Object.keys(prefill || {}).map(function (k) {
+    return k + '=' + encodeURIComponent(prefill[k]);
+  });
+  if (params.length) url += '?' + params.join('&');
+  window.open(url, '_blank');
+}
+```
+
+| 规则 | 说明 |
+|---|---|
+| 预填参数名 | 表单**字段 ID**（纯数字字符串），不是字段名 |
+| 预填参数值 | `encodeURIComponent` 包裹 |
+| Select 字段 | 传**选项 ID**（`valueKey`），不能传显示名 |
+| 多值字段 | 按表单写入规则用逗号串 |
+
+预填规则详见 `references/workflow/guide-workflow.md` 的「URL 传参预填」；参数值的来源可以先 `formClient` 读出来，再拼进 URL。
+
+**待办、已办、流程状态不在页面里自己拉。** 平台有待办页（菜单系统页 `todo` → `/sp/ebdfpage/workflow/{appId}_todo`），需要给用户看待办时跳转过去；页面不自行调用任务列表接口。

package/skill-docs/references/components/ref-component-common.md

@@ -0,0 +1,98 @@
+# 组件通用属性与样式
+
+> 适用 `@weapp/ui` 全部组件：属性与样式这部分是共通的，单看这一份即可。组件各自的专有属性见同目录下的组件文档。
+
+## 一、每个组件都有的属性（BaseProps）
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `className` | string | 挂到组件根节点，用来加自己的样式作用域 |
+| `style` | CSSProperties | 合并到组件根节点的行内样式 |
+| `customRender` | `(ctx, element) => ReactNode` | 包一层或整体替换组件的渲染结果 |
+| `overlayClassName` | string | 浮层样式名。**只有部分组件实现**（Radio / Checkbox / Menu / At / BreadCrumb 等），用前确认该组件是否支持 |
+| `prefixCls` | string | class 前缀。**不要用来改样式**：less 里的前缀是编译期写死的，改它只会换类名，样式表仍指向 `.ui-*` |
+| `weaComId` | string | 组件标识，一般不用 |
+| `children` | ReactNode | 子节点 |
+
+`customRender` 的第一个参数是组件实例，用来读取组件状态；返回的节点会**直接替代**原渲染结果，所以包裹时记得把 `element` 放回去：
+
+```jsx
+<Browser
+  module="hrm"
+  type="resource"
+  customRender={function (ctx, element) {
+    return <div className="my-browser-wrap">{element}</div>;
+  }}
+/>
+```
+
+## 二、表单类组件的通用属性（FormProps）
+
+表单类组件（Input / Select / Checkbox / Radio / Switch / Upload / Browser 等）在 BaseProps 之外还有：
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `readOnly` | boolean | 只读，只显示值、不加载输入工具 |
+| `disabled` | boolean | 禁用 |
+| `required` | boolean | 必填 |
+| `passport` | boolean | 加密显示为 `********` |
+| `placeholder` | string | 占位提示 |
+| `rule` | string \| function | 校验规则 |
+| `showRequiredMark` | boolean | 是否显示必填标记 |
+| `fieldId` / `fieldName` | string \| number | 隐藏域标识 |
+
+## 三、样式：四层钩子
+
+按可靠性从高到低，优先用上面的：
+
+| 层 | 手段 | 作用范围 |
+|---|---|---|
+| 变量层 | 在**页面根节点**重声明 CSS 变量（`--primary` 等） | 整个页面子树 |
+| 组件根层 | `className` / `style` | 组件根节点 |
+| 内容层 | `customRender` / 组件的 `bodyRender`、`customRenderItem` | 组件内部指定位置 |
+| 浮层专用 | `overlayClassName`、组件的弹层属性（如 `browserDialogProps`） | 该组件的弹层 |
+
+```jsx
+// 页面根节点声明变量，只影响这个页面
+<div className="my-page" style={{ '--primary': '#2f6fed', '--border-radius-md': '8px' }}>
+  ...
+</div>
+```
+
+**不要把变量写在 `:root` 上** —— 那会改掉整个平台的样式。
+
+## 四、浮层不在页面 DOM 里
+
+弹窗、下拉这类浮层通过 Portal 挂到 `body` 下的 `.ui-dialog-portal`：
+
+- 页面根节点上声明的 CSS 变量和后代选择器**都够不到浮层**；
+- 部分组件的弹层会继承组件上的 `className`（例如 Browser 把属性透传给内部 Dialog），所以同一个 className 有时会同时命中根节点和弹层；
+- 需要单独控制弹层时，用该组件的弹层属性或 `overlayClassName`，不要靠 DOM 层级猜；
+- 层级由变量控制：`--dialog-zindex`、`--popover-zindex`、`--modal-zindex`、`--toast-zindex`、`--picker-zindex` 等。
+
+## 五、常用 CSS 变量
+
+| 类别 | 变量 |
+|---|---|
+| 主色与状态色 | `--primary`、`--success`、`--warning`、`--danger`、`--info` |
+| 文字色 | `--main-fc`、`--regular-fc`、`--secondary-fc`、`--placeholder-fc`、`--link-fc` |
+| 背景 | `--bg-white`、`--bg-base`、`--bg-weak`、`--bg-gray` |
+| 边框与圆角 | `--border-color`、`--diviling-line-color`、`--border-solid`、`--border-radius-xs/sm/md/lg` |
+| 间距 | `--h-spacing-xs/sm/md/lg/xl`、`--v-spacing-xs/sm/md/lg/xl` |
+| 字号与行高 | `--font-size-sm/md/lg/base/heading`、`--line-height-base`、`--line-height-sm` |
+| 密度 | `--hd`（1px 换算单位，组件按它缩放） |
+
+## 六、不要做的事
+
+- 不用 `.ui-browser__xxx` 这类**内部 class** 覆盖样式，也不读 `weId`、不依赖 DOM 层级 —— 平台升级就会断；
+- 不改 `prefixCls` 指望换一套样式；
+- 不把 CSS 变量写到 `:root` 或 `body`；
+- 不编造组件或 props，列表见 `guide-page-code.md` 第六节。
+
+## 七、自检
+
+- [ ] 组件根节点上的样式走 `className` / `style`，没有去写内部 class
+- [ ] CSS 变量声明在页面根节点，没有写到 `:root`
+- [ ] 需要改弹层时用了组件的弹层属性，没有去猜 DOM 结构
+- [ ] `customRender` 包裹时把 `element` 渲染回去了
+- [ ] 没有依赖 `prefixCls` 改样式