weaver-e10-builder 1.0.11-beta → 1.0.12-beta

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

@@ -0,0 +1,224 @@
+# 页面编码指南
+
+> 本文件为 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`（引用规范）
+
+---
+
+## 代码质量检查清单
+
+生成代码后逐项检查：
+
+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. [ ] 写完代码后运行 `e10-cli check <项目目录>` 逐条自检

package/skill-docs/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/skill-docs/references/coding/ref-compile-rules.md

@@ -0,0 +1,106 @@
+# 编译规则参考
+
+## 编译命令
+
+```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/...
+```
+
+---
+
+## 关键注意事项
+
+1. **所有变量用 var 声明**，非前置加载文件引用确保使用 `React.lazy(() => asyncImport...)`
+2. `${appId}` 是占位符，运行时由 ecode SDK 替换
+3. 写完代码后运行 `e10-cli check <项目目录>` 逐条自检，全部确认通过后再 build
+4. 本地修改后一定要及时 `ecodecmd build` + `import` 上传，否则用户无法验证（用户看不到本地代码）