weaver-work-cli 0.1.23 → 0.1.25

package/skills/weaver-e10-builder/references/coding/guide-page-code.md

@@ -0,0 +1,244 @@
+# 页面编码指南
+
+> 本文件为 SKILL.md 的子模块，在需要写页面代码时加载。
+> 页面是搭建流程的最后一步，写代码前确保应用、表单、流程都已建好。
+
+---
+
+## 项目结构（从sample拷贝过来）
+
+```
+├── entry.js          ← 路由注册入口
+├── pages/            ← 页面组件
+├── api/
+│   └── formApi.js    ← 表单数据 API
+└── config/           ← 配置文件（不用管）
+```
+
+- entry.js 只完成入口注册，不要写入业务逻辑。
+- formApi.js 默认自带。
+- 该项目只能在泛微云运行，其他环境缺少依赖都会报错。
+- 只能支持 js 编码，**不支持 jsx 或 ts**。
+- 尽量使用原生 React 编码。
+
+---
+
+## entry.js 路由注册模板（严格照抄）
+
+```js
+import React from 'react';
+import { Route } from 'react-router-dom';
+import { regOvProps, appInfo, regReactChildren } from '@weapp/utils';
+import { asyncImport } from '@weapp/ecodesdk';
+
+var { publicUrl } = appInfo('@weapp/ecodesdk');
+
+// 1. 异步引入页面组件 — asyncImport 第一个参数固定为 '${appId}'，不允许留空
+var MyPage = React.lazy(function () {
+  return asyncImport('${appId}', 'pages/MyPage');
+});
+
+// 2. 路由 path 写死字符串，
+var ROUTE_PATH = '/sp/custom/ecode/my-page';
+
+var extract = (
+  <Route path={publicUrl + ROUTE_PATH}>
+    <React.Suspense fallback={<div>Loading...</div>}>
+      <MyPage />
+    </React.Suspense>
+  </Route>
+);
+
+regOvProps('weappEcodesdk', 'Switch', function (props) {
+  regReactChildren(props, extract);
+  return props;
+}, 0);
+```
+
+**铁律**：
+- `asyncImport('${appId}', 'pages/xxx')` — 第一个参数**固定**是 `'${appId}'`，不能写空字符串、不能写别的值
+- `React.Suspense` **只包裹一层**，不要双层嵌套
+- 路由 path 写死字符串（如 `/sp/custom/ecode/my-page`），**不拼接 `${appId}` 变量**
+
+**一个项目可以包含多个页面**，在 entry.js 中按同样模式注册：
+
+```js
+var MeetingList = React.lazy(function () {
+  return asyncImport('${appId}', 'pages/MeetingList');
+});
+
+var MeetingForm = React.lazy(function () {
+  return asyncImport('${appId}', 'pages/MeetingForm');
+});
+
+var extract = (
+  <>
+    <Route path={publicUrl + '/sp/custom/ecode/meeting-list'}>
+      <React.Suspense fallback={<div>Loading...</div>}>
+        <MeetingList />
+      </React.Suspense>
+    </Route>
+    <Route path={publicUrl + '/sp/custom/ecode/meeting-form'}>
+      <React.Suspense fallback={<div>Loading...</div>}>
+        <MeetingForm />
+      </React.Suspense>
+    </Route>
+  </>
+);
+```
+
+> 新页面导出和路由注册详见 `references/coding/guide-page-export.md`
+
+---
+
+## 引用规则
+
+- **前置加载文件（entry.js）**可以直接 import：`import { getSimpleData } from './api/formApi.js'`
+- **非前置加载文件（pages/ 下的所有文件）**只能通过 `React.lazy(() => asyncImport('${appId}', 'pages/xxx'))` 引用
+- entry.js 中只能使用 `React`、`ReactDOM`、`@weapp/utils`、`@weapp/ecodesdk`、`axios`，**不能使用 `@weapp/ui` 组件**
+
+---
+
+## @weapp/ui 可用组件清单
+
+**只能使用以下明确列出的组件**，不要从 `@weapp/ui` 里编造任何不在此列表中的组件名。
+
+| 组件 | import 方式 | 参考文档 |
+|------|-----------|---------|
+| Table | `import { Table } from '@weapp/ui'` | `references/components/display-Table.md` |
+| Avatar | `import { Avatar } from '@weapp/ui'` | `references/components/display-Avatar.md` |
+| List | `import { List } from '@weapp/ui'` | `references/components/display-List.md` |
+| Pagination | `import { Pagination } from '@weapp/ui'` | `references/components/display-Pagination.md` |
+| Icon | `import { Icon } from '@weapp/ui'` | `references/components/display-Icon.md` |
+| Button | `import { Button } from '@weapp/ui'` | `references/components/@weapp-Button.md` |
+| EChart | `import { EChart } from '@weapp/ui'` | `references/components/generic-Echarts.md` |
+| CorsComponent | `import { CorsComponent } from '@weapp/ui'` | `references/components/display-FilePreview.md` |
+| Browser（人员） | `import { Browser } from '@weapp/ui'`<br>`type="resource"` | `references/components/form-EmployeeBrowser-api.md` |
+| Browser（部门） | `import { Browser } from '@weapp/ui'`<br>`type="department"` | `references/components/form-DepartmentBrowser-api.md` |
+| Upload | `import { Upload } from '@weapp/ui'` | `references/components/form-Upload.md` |
+| Badge | `import { Badge } from '@weapp/ui'` | `references/components/base-Badge.md` |
+| Tag | `import { Tag } from '@weapp/ui'` | `references/components/base-Tag.md` |
+
+表单输入控件（文本框、下拉框、日期选择等）用原生 HTML：
+```js
+<input type="text" value={form[F.name]} onChange={...} />
+<input type="date" value={form[F.date]} onChange={...} />
+<select value={form[F.status]} onChange={...}>
+  {options.map(function (opt) {
+    return <option key={opt.valueKey} value={opt.valueKey}>{opt.name}</option>;
+  })}
+</select>
+```
+
+---
+
+## 表单数据操作（核心模式）
+
+**四个 API 各有分工，不要混用：**
+
+| API | 用途 | 返回内容 |
+|-----|------|---------|
+| `getSimpleData(objId, userId)` | 读 ID、写回 formToSave | 所有特殊字段统一返回 `fieldOptionId`（纯数字串） |
+| `getAllData(objId, userId)` | 提取名称、编辑回显 | 含 `fieldOptionName`，mainTable key 是随机哈希 |
+| `withDisplayNames(rows, map)` | 表格展示：ID → 名称 | 把 Select 的 `valueKey` 映射为中文名 |
+| `getFieldOptions(fieldId, objId)` | 拿下拉选项 | `[{valueKey, name}]` |
+
+**不同字段类型，名称来源不同（写在墙上）：**
+
+| 字段类型 | getSimpleData 返回 | 展示时名称来源 |
+|---------|-------------------|--------------|
+| Text / Number / Date | `"值"` / `123` / `"2026-01-01"` | 直接展示 |
+| Select / RadioBox / CheckBox | `"1283421826353889337"`（选项 ID） | `getFieldOptions` → `withDisplayNames` 映射 |
+| **Employee** | `"2765550234448235905"`（用户 ID） | `getAllData` 的 `fieldOptionName`，**不是** getFieldOptions |
+| **Department** | `"2765550234448235905"`（部门 ID） | 同上 |
+| FileComponent | `"fileid1,fileid2"`（文件 ID 串） | 上传组件的 `name` |
+
+**表格页面标准加载模式：**
+
+```js
+var [data, setData] = useState([]);
+
+useEffect(function () {
+  Promise.all([
+    getSimpleData(OBJ_ID, USER_ID),
+    getFieldOptions(F.status, OBJ_ID),   // Select 字段拿选项
+  ]).then(function ([rows, statusOpts]) {
+    // 加载时为每个需要展示名称的 Select/Employee 字段做映射
+    // Employee/Department 的名称要另外从 getAllData 提取！
+    var displayRows = withDisplayNames(rows, {
+      [F.status]: statusOpts,
+    });
+    // Employee 字段需要额外用 getAllData 构建 ID→名称 map
+    setData(displayRows);
+  });
+}, []);
+```
+
+**写入 / 更新：**
+
+```js
+// form 中所有值已经是 ID，直接拼入 formToSave
+var formToSave = {};
+Object.keys(form).forEach(function (key) {
+  if (form[key] !== '' && form[key] !== null && form[key] !== undefined) {
+    formToSave[key] = form[key];
+  }
+});
+// 选择器新值覆盖
+if (selectedPerson.length > 0) formToSave[F.person] = selectedPerson[0].id;
+
+if (editingId) {
+  updateFormData(OBJ_ID, formToSave, editingId, USER_ID);
+} else {
+  saveFormData(OBJ_ID, formToSave, USER_ID);
+}
+```
+
+> 完整的数据读写指南见 `references/coding/guide-form-crud.md`，编辑回显见 `references/coding/guide-edit-backfill.md`（前端代码）。
+
+---
+
+## 编译规则（简要）
+
+- `ecodecmd build {project-dir} --target=e10` 打包（cd 到项目前一级）
+- 所有变量用 `var` 声明
+- 不支持的语法：`catch{}` 无参数 catch、`??`、`import()` 动态导入、`BigInt`
+- 详见 `references/coding/ref-compile-rules.md`（编译配置）、`references/coding/guide-page-export.md`（引用规范）
+
+---
+
+## E10 平台硬规则（白屏 / 无样式 / 资源 404 的真凶）
+
+> 上面的规则管「能不能编译、数据对不对」；本节管平台**导入 / 运行期**的硬约束。
+> 违反不会报编译错，只会让页面发布后白屏、样式丢失或资源 404，且本地很难发现，写完务必逐条对照。
+
+| 规则 | 说明 |
+|------|------|
+| **资源统一用 `${appRes}/相对路径`**（如 `${appRes}/logo.png`） | `${appRes}` 是平台模板变量，导入后自动替换成正式静态地址。**禁止**写 `./resources/...`、`../resources/...`、`/resources/...`，发布后必 404。 |
+| **禁止在线资源** | 不要 `loadjs('http(s)://...')`、CDN、外链脚本——平台不加载外网资源。确需第三方脚本：先下载进项目，再按上一条 `${appRes}` 引用。 |
+| **禁止在 JS 里 `import` CSS** | ecode 没有 CSS 模块解析，`import './x.css'` 不会生效，样式静默丢失。少量样式用内联 style；独立 CSS 文件的打包规则见 `ref-compile-rules.md`「E10 打包与平台加载规则」。 |
+| **全部用 ESM `import` / `export`，禁止 `module.exports`** | 平台按模块加载，CommonJS 导出解析不到。 |
+| **只用白名单组件及其文档化 props** | 拿不准的组件 / prop / 图标名，先查 `references/components/`，不要凭记忆从 `@weapp/ui` 编造。 |
+| **不碰平台组件内部** | 不读 `props.children[...]`（含可选链写法）、不依赖内部 class / `weId` 段、不做全局无条件 `regOvComponent` 复写——内部结构不是稳定 API，平台升级即坏。 |
+
+---
+
+## 代码质量检查清单
+
+生成代码后逐项检查：
+
+1. [ ] 变量用 `var` 声明，非 `const`/`let`
+2. [ ] 非前置加载文件引用使用 `React.lazy(() => asyncImport(...))`
+3. [ ] **表格中没有任何裸 ID 展示**：Employee/Department 用 `fieldOptionName`，Select 用 `withDisplayNames`，用户看到的必须是中文名称
+4. [ ] `getSimpleData` 返回值直接 `item[字段ID]`，没有 `_raw` 层
+5. [ ] Select 字段读写统一用选项 ID（`valueKey`），不是显示名称
+6. [ ] React state 不直接修改，创建新对象 `var newForm = {}; Object.keys(form).forEach(...)`
+7. [ ] entry.js 不引入 `@weapp/ui` 组件
+8. [ ] 没有 `forEach/map/filter(fn, this)` 传 context 的写法，用 `var self = this;` 替代
+9. [ ] 表单数据 key 用字段 ID（纯数字字符串），对照 `form read --out fields.json`
+10. [ ] Employee/Department 字段写入前已转为 ID
+11. [ ] 页面没有 JS `import` CSS、没有 `module.exports`（全 ESM）
+12. [ ] 图片等静态资源统一 `${appRes}/相对路径`，没有写死相对路径或在线热链（loadjs/CDN）
+13. [ ] 只用清单内的 `@weapp/ui` 组件，不读 `props.children[...]`、不依赖内部 class/weId
+14. [ ] entry.js 只做路由注册，没有业务逻辑 / 轮询 / 直接 import 页面组件
+15. [ ] 写完代码后运行 `e10-cli check <项目目录>` 逐条自检

package/skills/weaver-e10-builder/references/coding/guide-page-export.md

@@ -0,0 +1,119 @@
+# 页面导出与路由注册指南
+
+## 引用规范
+
+### 前置加载文件（entry.js）
+
+只有前置加载的文件才可以直接 import：
+
+```js
+import { getSimpleData } from './api/formApi.js';  // entry.js 中可以直接引用
+```
+
+- entry.js 中只能使用 `React`、`ReactDOM`、`@weapp/utils`、`@weapp/ecodesdk`、`axios`
+- **不能使用 `@weapp/ui` 组件**
+- entry 只完成入口的注册，不要写入业务逻辑
+
+### 非前置加载文件（pages/ 目录）
+
+**非常关键！！！** 非前置加载的文件（新增的所有文件），只能通过以下方式引用：
+
+```js
+import { asyncImport } from '@weapp/ecodesdk';
+const AgentSxxx = React.lazy(() => asyncImport('${appId}', 'pages/AgentSxxx'));
+// '${appId}' 是固定写法，是内置的ecode应用ID，不用管
+```
+
+引用路径要根据文件相对位置判断：
+- entry.js 中引用 `api/formApi.js`：`'./api/formApi.js'`
+- pages/ 目录下引用 `api/formApi.js`：`'../api/formApi.js'`
+
+---
+
+## 页面导出（路由注册）
+
+在 `entry.js` 中通过 `regOvProps` + `regReactChildren` 注册路由：
+
+```js
+import { regOvProps, appInfo, regReactChildren } from '@weapp/utils';
+const { publicUrl } = appInfo('@weapp/ecodesdk');
+const extract = (
+  <Route path={`${publicUrl}/sp/custom/abc123123/abc123`}> // 导出页面的具体路径
+    <React.Suspense fallback={<div>Loading...</div>}>
+      <Test />  // 导出页面的组件
+    </React.Suspense>
+  </Route>
+);
+regOvProps('weappEcodesdk', 'Switch', (props) => {
+  regReactChildren(props, extract);
+  return props;
+}, 0);
+```
+
+---
+
+## 路由规范
+
+> **核心规则：entry.js 中的路由 path 不要拼接变量，直接写死字符串。**
+
+| 端 | 路由前缀 |
+|----|---------|
+| PC 端 | `/sp/custom/...` |
+| 移动端 | `/mobile/custom/...` |
+
+- path 写固定字符串，如 `/sp/custom/ecode/onboarding`，不拼接 `${appId}`
+- 使用 `appInfo('@weapp/ecodesdk').publicUrl` 处理二级路径兼容（`publicUrl` 本身已包含二级路径前缀）
+- 页面跳转使用 `Link` 或 `withRouter` 的 `history.push`，需拼接 `publicUrl`
+
+---
+
+## ecodInfo.json
+
+项目根目录下的 `ecodInfo.json` 记录项目元信息：
+
+```json
+{
+  "ecodeProjId": "",
+  "ecodeAppId": "",
+  "ebuilderAppId": "",
+  "mainUrl": ""
+}
+```
+
+- 如果文件不存在或内容为空，说明项目还未上传到 Ecode 平台
+- **导入 Ecode 成功后，必须将主页面路径写入 `mainUrl` 字段**，格式如 `/sp/custom/......`，和 entry.js 里必须完全相同
+- **如果当前 Ecode 项目关联了 Ebuilder 应用，必须将 Ebuilder 应用 ID 写入 `ebuilderAppId`**。注意：`ebuilderAppId` 是 Ebuilder 应用的 ID，与 `ecodeAppId`（Ecode 应用文件夹 ID）不同
+
+---
+
+## entry.js 完整模板
+
+```js
+import React from 'react';
+import { regOvProps, appInfo, regReactChildren } from '@weapp/utils';
+import { asyncImport } from '@weapp/ecodesdk';
+
+const { publicUrl } = appInfo('@weapp/ecodesdk');
+const appId = '${appId}';
+
+// 异步引入页面组件
+const MyPage = React.lazy(() => asyncImport('${appId}', 'pages/MyPage'));
+
+// 注册路由 — path 写死固定字符串，和
+var ROUTE_PATH = '/sp/custom/ecode/my-page';
+const myRoute = (
+  <Route path={`${publicUrl}${ROUTE_PATH}`}>
+    <React.Suspense fallback={<div>Loading...</div>}>
+      <MyPage />
+    </React.Suspense>
+  </Route>
+);
+
+regOvProps('weappEcodesdk', 'Switch', (props) => {
+  regReactChildren(props, myRoute);
+  return props;
+}, 0);
+```
+> `ROUTE_PATH` 不要在这里拼接 `appId` 变量，`publicUrl` 已包含二级路径前缀。
+
+> 完成后记得告诉用户哪些页面对应哪些 URL。

package/skills/weaver-e10-builder/references/coding/ref-compile-rules.md

@@ -0,0 +1,130 @@
+# 编译规则参考
+
+## 编译命令
+
+```bash
+ecodecmd build {project-dir} --target=e10
+```
+
+- 其中 `{project-dir}` 为代码项目的目录
+- 打包会在项目产生一个 `.target` 文件夹，包含一个 `.zip` 文件
+- **打包得 cd 到项目的前一级**，要不然传的目录里面没有名称
+
+---
+
+## 编译配置
+
+ecodecmd 内部使用 `@babel/standalone` v7.5.5 编译代码，E10 模式下调用 `compileJsE10`。
+
+```
+presets: ['es2015', 'react', ['stage-2', {decoratorsLegacy: true, loose: true}]]
+plugins: ['proposal-object-rest-spread', 'proposal-optional-chaining']
+```
+
+---
+
+## 支持的语法
+
+| 语法 | 示例 |
+|------|------|
+| JSX | `<div className="app">{content}</div>` |
+| 箭头函数 | `(x) => x + 1` |
+| async/await | `const data = await getSimpleData(...)` |
+| 模板字符串 | `` `Hello ${name}` `` |
+| 对象展开 `...` | `{ ...oldObj, newKey: val }` |
+| 可选链 `?.` | `obj?.nested?.value` |
+| Class 组件 | `class MyPage extends React.Component {}` |
+
+---
+
+## Babel 编译陷阱（语法合法但编译后行为异常）
+
+| 陷阱 | 说明 | 解决方案 |
+|------|------|---------|
+| `forEach(fn, this)` 传 context | `this` 在 Babel 编译后丢失，回调内的 `this` 变成 `undefined` | 提前 `var self = this;`，回调内用 `self` |
+| `map/filter/find` 同样受影响 | 所有数组方法只要传了第二个参数 `this`，编译后都失效 | 一律用 `var self = this;` 模式 |
+| 漏写 `var` 直接赋值 | `x = {}` 未经声明直接赋值，Babel 编译后严格模式报 `ReferenceError: x is not defined` | **所有变量必须先 `var x = ...` 再使用** |
+
+```js
+// ❌ Babel 编译后 this 丢失，setState 报错
+data.forEach(function (item) {
+  this.setState({ ... });
+}, this);
+
+// ✅ 提前捕获 this
+var self = this;
+
+// ❌ 漏写 var，Babel 编译后报 ReferenceError
+priorityColorCache = {};
+priorityOpts.forEach(function(opt) { ... });
+
+// ✅ 先声明再赋值
+var priorityColorCache = {};
+priorityOpts.forEach(function(opt) { ... });
+data.forEach(function (item) {
+  self.setState({ ... });
+});
+```
+
+---
+
+## 不支持的语法（会编译报错）
+
+| 语法 | 解决方案 |
+|------|---------|
+| `catch { }` 无参数 catch | 必须写成 `catch(e) {}` |
+| `??` 空值合并运算符 | 用 `||` 或三元表达式替代 |
+| `import()` 动态导入 | 必须用 `asyncImport` |
+| `private class fields #` | 不用 class fields，用普通方法 |
+| `globalThis` | 用 `window` |
+| `BigInt` | 不用 |
+
+---
+
+## 打包 & 上传流程
+
+```bash
+# 1. 编译检查
+e10-cli check <项目目录>
+
+# 2. 打包（cd 到项目前一级）
+cd /path/to/parent && ecodecmd build project-dir --target=e10
+
+# 3. 上传（先删旧应用）
+e10-cli project tree <projectId>              # 找旧应用 folderId
+e10-cli project delete-folder <folderId>
+e10-cli project import <projectId> .target/xxx.zip --main-url /sp/custom/...
+```
+
+---
+
+## E10 打包与平台加载规则（build.json / CSS / 资源）
+
+> 首次 build 会自动生成 `build.json`。它决定每个文件是否**前置加载**，平台导入后按它加载代码。
+> 违反本节规则不报编译错，只会让页面发布后白屏 / 无样式 / 资源 404。
+
+### build.json：前置加载登记表
+
+- 首次 `ecodecmd build` 在项目根自动生成 `build.json`：`entry.js`、`formApi.js`、`.css`、`.pre.js` → `state:"y"`（平台前置加载）；其余 `.js` → `"n"`（按需，经 `asyncImport` 加载）。
+- **再次 build 以已存在的 `build.json` 为准，不会自动补登记之后新增的文件。** 新增 / 删除文件后若平台表现异常，先检查 `build.json`（必要时删掉让它重新生成，或手动补登记）。
+- `entry.js` 是唯一前置业务 JS，必须在 codes 里 `state:y`；其他业务 JS 不要批量设成 `y`（会让首屏变慢）。
+
+### CSS 规则
+
+- **禁止在 JS 里 `import` CSS**：ecode 无 CSS 模块解析，写了必丢、发布后无样式。
+- 少量页面样式用内联 style；确需独立 `.css` 文件时，确认它在 `build.json` 的 codes 里（首次自动生成时 `.css` 会登记为 `y`；文件是后加的要自行补登记），否则平台不合并加载。
+- 业务 CSS 选择器挂在页面根容器下，避免裸 `.类名`、`body`、`:root` 或平台内部 class 污染全局。
+
+### 资源规则
+
+- 工程 `resources/` 目录内容打包进 zip 的 `${resources` 物理目录；**业务代码引用统一用模板变量 `${appRes}/相对路径`**（导入后平台自动替换成正式地址），如 `${appRes}/logo.png`。
+- 禁止 `./resources/...`、`../resources/...`、`/resources/...` 相对写法，以及在线 `loadjs('http(s)://...')` / CDN。
+
+---
+
+## 关键注意事项
+
+1. **所有变量用 var 声明**，非前置加载文件引用确保使用 `React.lazy(() => asyncImport...)`
+2. `${appId}` 是占位符，运行时由 ecode SDK 替换
+3. 写完代码后运行 `e10-cli check <项目目录>` 逐条自检，全部确认通过后再 build
+4. 本地修改后一定要及时 `ecodecmd build` + `import` 上传，否则用户无法验证（用户看不到本地代码）

package/skills/weaver-e10-builder/references/common/guide-plan-template.md

@@ -0,0 +1,164 @@
+# 搭建计划模板（按依赖与功能批次执行）
+
+使用本模板生成项目 `plan.md` 时，先读[规划能力地图](map.md)识别资源、配置和依赖；需要明确具体规则或能力边界时读对应专题指南，再填写实际涉及的条目。执行某项前仍须读取该项指南。
+
+规划阶段全部保持 `[ ]`。第一阶段先完成全部表单的字段、明细和布局，再以**功能项为外层、所有适用表单/视图为内层**组织配置：例如先完成所有表单的关联浏览数据范围，再处理所有表单的公式；视图也按显示列、搜索、排序等功能逐批覆盖。每进入一个功能项先读对应指南，确认方法、参数和边界；同一连续批次已读过的无需重复读取。每个对象及独立规则分别列项、核对、回填和销号；暂不能完成的保留 `[ ]` 并注明原因、已完成部分及所需条件，继续处理其他项目，不因步骤繁琐而省略。整个功能批次的覆盖对象处理完后进入下一批次，真实依赖优先于批次顺序。每段完成后停下让用户确认，确认后进入下一段。仅单步修改或查询不套用三段流程。
+
+## plan.md 参考骨架
+
+复制本节到项目工作区的 `plan.md`，只保留需求涉及的资源和功能；每条业务要求都有明确归属、来源、依赖和可观察结果。同类功能可连续执行，但不能把多条独立要求合成一个销号项。
+
+```md
+## 搭建计划
+
+> `[ ]` 为未完成；写入且按该项风险完成必要核验后，才改 `[x]` 并填写真实 ID 或结果。尚待后续资源的项保留 `[ ]` 并写明依赖。
+> 来源可用需求文档章节、表格或图片标题。已有资源先只读盘点，记明复用/修改/新建及实际 ID。
+
+### 0. 环境与范围
+- 目标环境/profile：<名称与地址>；所属机构：<名称/ID>；主应用：<名称/ID>
+- 跨应用资源与范围：<无/资源及归属>
+- 待业务确认：<歧义及其影响；无则“无”>
+- 待环境核查：<资源或环境行为；无则“无”>
+
+### 1. 资源清单与依赖
+
+| 资源 | 决策与归属 | 来源及用途 | 前置依赖 | 实际 ID/结果 |
+|---|---|---|---|---|
+| 应用 <名称> | 新建/复用；机构 <名称> | <来源> | 环境 | 待回填 appId |
+| 角色 <名称> | 新建/复用 | <来源、成员类型与范围> | 机构 | 待回填 roleId |
+| 矩阵 <名称> | 新建/复用 | <来源、条件列/值列/行数据> | 机构、人员/部门 | 待回填 matrixId |
+| 表单 <名称> | EB/虚拟/原生流程表单；新建/复用；应用 <名称> | <来源、用途> | 应用、数据源 | 待回填 objId/formId |
+| 视图 <名称> | 默认台账改名/复用/新增；PC/MOBILE | <来源、用途> | 所属表单 | 待回填 listId/viewId |
+| 流程 <名称> | EB/原生；普通/公文；固定/自由；新建/复用 | <来源、业务流转> | 表单、角色/矩阵 | 待回填 workflowId |
+| 权责表 <名称> | 随流程新建/独立复用 | <来源、分支场景> | 流程/变量 | 待回填 authRespId |
+| 报表/数据集 <名称> | 新建/复用 | <来源、统计目标> | 来源字段 | 待回填 ID |
+| 菜单/页面 <名称> | 新建/复用 | <来源、入口及目标> | 视图/流程/页面 | 待回填 ID |
+
+> 角色和矩阵先用 `role list`、`matrix list` 只读盘点同名资源及归属、成员或数据行，记录候选 ID，并与用户逐项确认复用还是新建。复用但需补成员或数据行的，在对应功能批次单独列项；没有矩阵需求则不创建。
+
+#### 1.1 表单字段与布局蓝图（每张表单各一份）
+
+##### 表单：<名称>；资源决策：<新建/复用>；objId/formId：<待回填>；来源：<章节>
+- 布局：FLOW/EXCEL；已有表单改造时记录现有布局及保留要求。
+- 字段清单：逐字段写主表/明细表、名称、componentKey、选项、默认值、长度/精度、关联目标、公式及明确的必填/只读/隐藏/独占一行/分组。字段名含中英文时分别记录。
+- 明细表：<名称、字段、层级>；二级明细逐条记录父明细→子明细、父子行标识及默认展开要求。
+- 虚拟表：<来源类别与资源ID、稳定主键、来源字段→展示类型映射>。
+- 关联依赖：<字段→目标表/流程及 ID 待回填位置>。
+- 布局样表来源：<章节/图片/表格；无则“未提供，使用约定布局”>。
+
+| 行 | 类型 | 左侧单元 | 右侧单元 | 跨列/占位 | 原文属性与说明 |
+|---|---|---|---|---|---|
+| 1 | 标题 | <标题> | — | 跨全部列 | <来源> |
+| 2 | 字段 | <标签>→[字段] | <标签>→[字段] | <同排/留空> | <必填/只读等> |
+| 3 | 分组 | <分组名> | — | 跨全部列 | <顺序> |
+
+> 样表有标题、分组、空白、字段同排或跨列时逐行保留，并与字段清单互相核对。缺少的合并范围标待确认。建新表时按蓝图准备 fields.json，按所选布局创建并初始化；公式、联动、校验等后续配置在功能批次单列。
+
+#### 1.2 视图与流程设计依据
+- 每张视图：所属表单、默认/新增、视图类型、终端、名称、数据范围及需要的显示列/交互要求。
+- 每个流程：表单来源、节点、操作者及签署方式、全部连线、默认出口、逐条条件、节点显示属性和动作流落点。普通流程和权责表流程分别按对应指南列出；权责表逐场景写说明、条件、经过节点及顺序，独立复用时写变量→主/明细字段映射。
+
+### 2. 第一阶段：应用、表单与视图
+
+#### 2.1 资源与字段布局批次
+- [ ] 应用 <名称> | 新建/复用 | appId：待回填 | 核验：<名称与归属>
+- [ ] 角色 <名称> | roleId：待回填 | 核验：<角色及成员；成员可另列项>
+- [ ] 表单 <名称> 的字段、明细及布局 | objId/formId：待回填 | 来源：1.1 <名称> | 核验：字段、布局及默认台账
+- [ ] 表单 <名称> 的字段、明细及布局 | objId/formId：待回填 | 来源：1.1 <名称> | 核验：字段、布局及默认台账
+
+> 先按跨表引用关系建立必要的表单骨架，再补关联目标；不为了凑齐所有表单而破坏实际依赖。新建 EB 表单尽量用 `form create --fields` 一次写入字段与布局属性。依赖流程 ID 的关联字段记录占位，流程建成后回填。
+
+#### 2.2 表单级功能批次（一个功能项覆盖全部相关表单）
+
+> 写实际 plan 时，按 `##### 功能批次：<功能名>｜覆盖表单：<A、B、...>` 分组；组内为每张表单的每条规则分别列 `[ ]`。例如“关联浏览数据范围”涉及客户表、合同表，就在同一批次下列两条，逐条配置并销号，再进入“字段公式”等下一批次。下列每行是应按需求展开的功能项示例，不代表只配置一张表单。
+
+##### 功能批次：关联浏览数据范围｜覆盖表单：<客户表、合同表>
+- [ ] 客户表 / 关联客户字段 | 条件：<规则> | 核验：可选记录
+- [ ] 合同表 / 关联项目字段 | 条件：<规则> | 核验：可选记录
+
+##### 功能批次：<从下列功能项选择一类>｜覆盖表单：<逐一列出>
+
+> 按需求复制此标题，每个标题只放同一功能的待办项，并把覆盖表单逐一展开；下列条目是可选的填写样式。
+- [ ] 关联字段及目标绑定 | 表单/字段：<名称> | 目标：<资源/ID> | 核验：选择范围
+- [ ] 关联浏览显示列 | 表单/字段：<名称> | 列：<字段及顺序> | 核验：弹窗显示
+- [ ] 二级明细关系 | 父表/子表：<名称> | 行标识：<字段> | 核验：逐父行归属
+- [ ] 字段多语言 | 表单/字段：<名称> | 中文/英文：<名称> | 核验：两种名称
+- [ ] 字段公式 | 表单/目标字段：<名称> | 表达式：<公式> | 核验：读回与样例值
+- [ ] 字段带出或函数联动 | 表单/规则：<名称> | 触发/来源/目标/表达式：<内容> | 核验：触发结果
+- [ ] 属性显隐联动 | 表单/规则：<名称> | 条件/目标/状态：<内容> | 核验：条件切换
+- [ ] 查重校验 | 表单/字段：<名称> | 行为：<提示/阻断> | 核验：重复样例
+- [ ] 编号规则 | 表单/字段：<名称> | 组成与位数：<内容> | 核验：生成值
+- [ ] 表单权限 | 表单/主体：<名称> | 新建/查看/编辑/删除范围：<内容> | 核验：授权结果
+- [ ] 表单页按钮 | 表单/页面/位置：<名称> | 目标与字段映射：<内容> | 核验：点击结果
+
+> 每个功能批次先核对覆盖表单清单，再逐表配置；同一表单有多条独立规则时继续拆行。建表时已配置并核验的分组、必填、只读、默认值等写在 2.1 的表单项结果中，不重复执行。
+
+#### 2.3 视图资源批次
+- [ ] 默认台账 <原名> 复用/改名为 <目标名> | 表单：<名称> | listId：待回填 | 核验：名称与类型
+- [ ] 新增视图 <名称> | 表单：<名称> | 类型/终端：<内容> | listId/viewId：待回填 | 核验：可打开且已填充
+
+#### 2.4 视图功能批次（一个功能项覆盖全部相关视图）
+
+> 沿用 2.2 的结构：`##### 功能批次：<功能名>｜覆盖视图：<视图A、视图B、...>`。例如“显示列”先列全部需配置的 PC/MOBILE 视图，每张视图及终端单独列项并完成；再处理搜索、排序等下一批次。以下为需要按需求展开的功能项示例。
+- [ ] 显示列 | 视图/终端：<名称/PC或MOBILE> | 字段/顺序/宽度：<内容> | 核验：列表显示
+- [ ] 列格式或单位 | 视图/字段：<名称> | 格式/单位：<内容> | 核验：展示值
+- [ ] 搜索与排序 | 视图：<名称> | 字段、入口与优先级：<内容> | 核验：查询及顺序
+- [ ] 筛选与顶部统计 | 视图：<名称> | 条件/函数：<内容> | 核验：记录及统计值
+- [ ] 普通分组或上下级 | 视图：<名称> | 分组/父级字段：<内容> | 核验：分组或层级
+- [ ] 视图权限 | 视图/主体：<名称> | 查看/操作范围：<内容> | 核验：权限读回
+- [ ] 行上或右上按钮 | 视图/位置：<名称> | 目标/当前行过滤/预填：<内容> | 核验：点击结果
+- [ ] 行点击或字段点击 | 视图/字段：<名称> | 打开目标和方式：<内容> | 核验：点击结果
+- [ ] 关联页签 | 表单/页签/目标视图：<名称> | 权限/布局/终端/筛选映射：<内容> | 核验：相关数据
+
+> 搜索、排序、筛选和统计若各有独立业务要求，分别建立功能批次和待办项。依赖第二阶段流程 ID 的按钮、流程关联字段等保留 `[ ]` 并注明依赖，在第二阶段回填后销号。第一阶段完成后请用户确认，再进入第二阶段。
+
+### 3. 第二阶段：流程与自动化
+
+#### 3.1 矩阵、权责表及流程资源
+- [ ] 矩阵 <名称> | 条件列/值列/行×列数据：<内容> | matrixId：待回填 | 核验：列、行和值
+- [ ] 流程 <名称> | EB/原生/公文，固定/自由，表单来源：<内容> | workflowId：待回填 | 核验：绑定表单
+- [ ] 本流程全部节点 | 节点名称、类型及顺序：<内容> | 核验：节点 ID 与清单一致
+- [ ] 本流程全部连线 | 源节点→目标节点、连线名称及默认出口：<内容> | 核验：完整拓扑
+- [ ] 本流程出口条件 <源节点→目标节点> | 字段来源、操作、值、AND/OR、明细量词：<内容> | 每条条件复制一项；核验：分支路由
+- [ ] 本流程节点操作者 <节点名> | 角色/矩阵/字段等来源及签署方式：<内容> | 每个节点复制一项；核验：人员范围
+- [ ] 本流程结构排版与核对 | 节点、连线、默认出口、条件及操作者：<内容> | 核验：流程图及配置读回
+- [ ] 权责表 <名称> | 随流程新建/独立复用 | authRespId：待回填 | 核验：场景与节点路径
+
+> 每个流程各复制一组“流程→节点→连线→条件→操作者→结构核对”，逐条流程完成核心流转；独立条件和操作者仍分别列项、分别销号。权责表流程的分支与经过节点按权责表指南在本流程下展开。实际配置按依赖进行，后续若有完整配置命令，可由同一组计划条目核对结果。
+
+#### 3.2 流程附加设置与功能批次
+- [ ] 节点字段权限或布局 | 流程/节点：<名称> | 字段/显示状态：<内容> | 核验：节点页面
+- [ ] 节点校验、退回、超时、菜单或其他行为 | 流程/节点：<名称> | 逐项写明：<内容> | 核验：配置读回
+- [ ] 流程编号、标题、提醒或流程级设置 | 流程：<名称> | 逐项写明：<内容> | 核验：配置读回
+- [ ] 公文专属设置 | 流程：<名称> | 按实际需求列出：<内容> | 核验：对应设置读回
+- [ ] 权责表场景/变量映射 | 权责表：<名称> | 场景条件、路径或变量→字段：<内容> | 核验：路径与映射
+- [ ] 动作流/节点字段赋值 | 触发流程/节点：<名称> | 目标、字段映射及定位：<内容> | 核验：绑定与结果
+- [ ] 回填第一阶段的流程依赖 | 表单字段/视图按钮：<名称> | workflowId/formId：<实际值> | 核验：选择或打开结果
+
+> 核心流转按 3.1 逐流程完成；本节的附加设置可按功能批次处理，但每条独立规则或动作流仍分别列项。第二阶段完成后请用户确认，再进入第三阶段。
+
+### 4. 第三阶段：报表、菜单与页面
+- [ ] 报表数据集 <名称> | 来源、字段、关联：<内容> | datasetId：待回填 | 核验：数据集字段
+- [ ] 报表 <名称> | 布局、查询及共享：<内容> | reportId：待回填 | 核验：展示与授权
+- [ ] 菜单 <名称> | 层级、目标资源及权限：<内容> | menuId：待回填 | 核验：入口与可见范围
+- [ ] 配置式或定制页面 <名称> | 终端、组件/交互、绑定资源：<内容> | pageId：待回填 | 核验：页面加载与业务结果
+
+### 5. 待确认、需补充及无法实现
+| 来源与原需求 | 状态 | 原因或缺失信息 | 影响与后续处理 |
+|---|---|---|---|
+| <章节及要求> | 待业务确认/待环境核查/需其他方式补充/已确认无法实现 | <内容> | <内容> |
+
+> 已确认无法实现的原需求项保持 `[ ]`，不得以替代配置冒充完成；在此说明原因和影响，交由用户决定。其他状态继续保留相应待办与依赖。
+
+### 6. 阶段验收与交付资源
+- 第一阶段：全部应建表单的字段、明细、布局和默认台账已核对；表单级与视图级需求逐项销号，后续流程依赖已标注。
+- 第二阶段：流程结构、关键条件、操作者及动作流已核对；第一阶段的流程依赖项已回填。
+- 第三阶段：报表、菜单和页面入口已核对；交付时列出应用→表单→视图、流程、矩阵、报表、页面的真实 ID 与未完成项。
+```
+
+## 使用边界
+
+- 资源清单负责保存“建什么、复用什么、谁依赖谁”，功能批次负责“具体配置什么”；两处用资源名称或实际 ID 对应，不重复创建同一资源。
+- 字段和布局蓝图仍逐表保存，防止按功能批次执行时遗失字段顺序、分组和表格空间结构。
+- 功能批次只规定同类操作的优先处理顺序。出现跨表循环、流程 ID、目标页面等依赖时，按真实依赖先建立资源，再回到相应条目完成配置。
+- 最小核验与业务风险相称；仅在用户要求时进行实际环境测试。计划销号仍以配置完成及必要的结果核对为准。