weaver-e10-builder 1.6.0 → 1.6.5

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

@@ -1,29 +1,37 @@
 # 页面编码指南
 
-> 本文件为 SKILL.md 的子模块，在需要写页面代码时加载。
-> 页面是搭建流程的最后一步，写代码前确保应用、表单、流程都已建好。
+> 本文件是 Ecode React 页面的主入口。用户明确要求 Ecode、还原 HTML 原型或不要设计器时，直接按本指南执行，不要再建议改用设计器。
+> 页面是搭建的最后一步，写代码前确保应用、表单、流程已建好。
 
 ---
 
-## 项目结构（从sample拷贝过来）
+## 一、项目结构
 
 ```
-├── entry.js          ← 路由注册入口
-├── pages/            ← 页面组件
+├── entry.js                 ← 路由注册入口
+├── pages/                   ← 页面组件
+│   └── Items.js
 ├── api/
-│   └── formApi.js    ← 表单数据 API
-└── config/           ← 配置文件（不用管）
+│   └── formApi.js           ← formClient
+├── app/
+│   ├── config.js            ← APP_ID / OBJ_ID
+│   └── fields.js            ← 字段 ID 常量
+├── styles/
+│   └── prototypeStyles.js     ← 原型的 CSS 字符串
+└── resources/               ← 图片等静态资源
 ```
 
-- entry.js 只完成入口注册，不要写入业务逻辑。
-- formApi.js 默认自带。
-- 该项目只能在泛微云运行，其他环境缺少依赖都会报错。
-- 只能支持 js 编码，**不支持 jsx 或 ts**。
-- 尽量使用原生 React 编码。
+- `entry.js` 只做入口注册，不写业务逻辑。
+- 只能在泛微云运行，其他环境缺少 `@weapp/*` 依赖。
+- 只支持 JS，不支持 JSX 文件扩展名或 TS；JSX 写在 `.js` 里由 Babel 编译。
+- 所有页面代码全 ESM（`import` / `export`），不要 `module.exports`。
+- **应用配置不要放 `config/`**：平台把 `config/` 当内置配置目录，普通模块导入拿不到（实测 `OBJ_ID` 为 undefined）。放 `app/`、`lib/` 这类普通目录。
+
+参考完整样例：`assets/sample/`。
 
 ---
 
-## entry.js 路由注册模板（严格照抄）
+## 二、entry.js：`${appId}` 是固定字符串
 
 ```js
 import React from 'react';
@@ -31,20 +39,17 @@ import { Route } from 'react-router-dom';
 import { regOvProps, appInfo, regReactChildren } from '@weapp/utils';
 import { asyncImport } from '@weapp/ecodesdk';
 
-var { publicUrl } = appInfo('@weapp/ecodesdk');
+var publicUrl = appInfo('@weapp/ecodesdk').publicUrl;
 
-// 1. 异步引入页面组件 — asyncImport 第一个参数固定为 '${appId}'，不允许留空
-var MyPage = React.lazy(function () {
-  return asyncImport('${appId}', 'pages/MyPage');
+var ItemsPage = React.lazy(function () {
+  // 单引号里的 ${appId} 是固定字符串，不是应用 ID，不要替换成数字
+  return asyncImport('${appId}', 'pages/Items');
 });
 
-// 2. 路由 path 写死字符串，
-var ROUTE_PATH = '/sp/custom/ecode/my-page';
-
 var extract = (
-  <Route path={publicUrl + ROUTE_PATH}>
+  <Route path={publicUrl + '/sp/custom/ecode/items'}>
     <React.Suspense fallback={<div>Loading...</div>}>
-      <MyPage />
+      <ItemsPage />
     </React.Suspense>
   </Route>
 );
@@ -55,192 +60,214 @@ regOvProps('weappEcodesdk', 'Switch', function (props) {
 }, 0);
 ```
 
-**铁律**：
-- `asyncImport('${appId}', 'pages/xxx')` — 第一个参数**固定**是 `'${appId}'`，不能写空字符串、不能写别的值
-- `React.Suspense` **只包裹一层**，不要双层嵌套
-- 路由 path 写死字符串（如 `/sp/custom/ecode/my-page`），**不拼接 `${appId}` 变量**
-
-**一个项目可以包含多个页面**，在 entry.js 中按同样模式注册：
+**`asyncImport` 的第一个参数是字面量 `'${appId}'`**：
 
 ```js
-var MeetingList = React.lazy(function () {
-  return asyncImport('${appId}', 'pages/MeetingList');
-});
+// 正确：原样保留这个字符串
+asyncImport('${appId}', 'pages/Items')
 
-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>
-  </>
-);
+// 错误：把 Ebuilder 应用 ID、Ecode 项目 ID 或任何数字填进去
+asyncImport('1330584721118584834', 'pages/Items')
+asyncImport('1328370888652840961', 'pages/Items')
 ```
 
-> 新页面导出和路由注册详见 `references/coding/guide-page-export.md`
+它不是变量，也不是当前应用的 `APP_ID`；平台在运行时会替换这个固定占位符。几个名字不要混：
 
----
+| 名称 | 是什么 | 用在哪 |
+|---|---|---|
+| `${appId}` | 固定占位字符串 | `asyncImport` 第一个参数，原样保留 |
+| `APP_ID` | 当前 Ebuilder 应用 ID | `formClient({ appId: APP_ID })`、数据接口请求头 |
+| `ecodeAppId` | Ecode 应用文件夹 ID | `ecodInfo.json`，与 Ebuilder 应用 ID 不同 |
+| `mainUrl` | 页面主路由 | `ecodInfo.json`，必须和 `entry.js` 的 route path 一致 |
 
-## 引用规则
+其它铁律：
 
-- **前置加载文件（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` 组件**
+- `React.Suspense` 只包一层。
+- 路由 path 写死字符串（如 `/sp/custom/ecode/items`），不要拼 `${appId}` 变量。
+- entry.js 里只能使用 `React`、`ReactDOM`、`react-router-dom`、`@weapp/utils`、`@weapp/ecodesdk`、`axios`；不要使用 `@weapp/ui` 组件。
+- 一个项目可以有多个页面，每个页面按同样方式 `React.lazy` + `asyncImport` 注册。
 
 ---
 
-## @weapp/ui 可用组件清单
+## 三、字段常量
 
-**只能使用以下明确列出的组件**，不要从 `@weapp/ui` 里编造任何不在此列表中的组件名。
+先用 CLI 导出字段：
 
-| 组件 | 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` |
+```bash
+e10-cli form read <objId> --app-id <appId> --out fields.json
+```
+
+再生成 `app/fields.js`：
 
-表单输入控件（文本框、下拉框、日期选择等）用原生 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>
+export var F = {
+  name: '4765111450482898127',
+  status: '4765111450482898155',
+  owner: '4765111450482898160'
+};
+
+export var LABELS = {
+  name: '名称',
+  status: '状态',
+  owner: '负责人'
+};
 ```
 
----
-
-## 表单数据操作（核心模式）
+字段 ID 必须是 `fields.json` 里的 `fieldId`，不要手写、不要用字段名代替。
 
-**四个 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}]` |
+## 四、表单数据：只用 formClient
 
-**不同字段类型，名称来源不同（写在墙上）：**
+```js
+import { formClient } from '../api/formApi.js';
+import { APP_ID, OBJ_ID } from '../app/config.js';
 
-| 字段类型 | 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` |
+var items = formClient({ objId: OBJ_ID, appId: APP_ID });
+```
 
-**表格页面标准加载模式：**
+页面只记三件事：
 
 ```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);
-  });
-}, []);
+page.rows[i].values / display / items   // 一个行形状
+items.list / get / save / update / remove  // 一套 CRUD
 ```
 
-**写入 / 更新：**
+完整用法见 `guide-form-crud.md`，编辑回显见 `guide-edit-backfill.md`。最小列表页：
 
 ```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);
+import React, { useEffect, useState } from 'react';
+import { formClient } from '../api/formApi.js';
+import { APP_ID, OBJ_ID } from '../app/config.js';
+import { F, LABELS } from '../app/fields.js';
+
+var items = formClient({ objId: OBJ_ID, appId: APP_ID });
+
+export default function Items() {
+  var [rows, setRows] = useState([]);
+  var [error, setError] = useState('');
+
+  useEffect(function () {
+    items.list({ page: 1, size: 20 }).then(function (page) {
+      setRows(page.rows);
+    }).catch(function (err) {
+      setError(err.message);
+    });
+  }, []);
+
+  return (
+    <div>
+      {error ? <div>{error}</div> : null}
+      <table>
+        <thead>
+          <tr><th>{LABELS.name}</th><th>{LABELS.status}</th></tr>
+        </thead>
+        <tbody>
+          {rows.map(function (row) {
+            return (
+              <tr key={row.id}>
+                <td>{row.display[F.name]}</td>
+                <td>{row.display[F.status]}</td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
 }
 ```
 
-> 完整的数据读写指南见 `references/coding/guide-form-crud.md`，编辑回显见 `references/coding/guide-edit-backfill.md`（前端代码）。
+不要再在页面里：
+
+- 传 `userId` / `tenantKey`
+- 调 `getSimpleData` / `getAllData` / `withDisplayNames`
+- 拼 `mainTable`、判断随机 key、数组还是对象
+- 把 `display` 里的中文名写回接口
+
+这些都在 `formApi.js` 里处理。
 
 ---
 
-## 编译规则（简要）
+## 五、HTML 原型还原
+
+用户提供 HTML / 设计稿并要求还原时，读 `guide-html-to-react.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`（引用规范）
+- 原型 `<style>` 整段复制到 `styles/prototypeStyles.js` 的字符串里，页面用 `<style>{PROTOTYPE_CSS}</style>` 渲染一次
+- 不新写 CSS、不建独立 `.css`、不 `import` CSS、不把规则逐条改写成内联 style
+- 保留原 class 名和 DOM 层级，只做 `class`→`className`、`for`→`htmlFor`、`style` 字符串→对象、模板字符串→组件/`map` 的机械转换
+- 全局选择器、`:root`、keyframes 收敛到页面根容器，避免污染平台壳
+- 图片走 `${appRes}/...`
 
 ---
 
-## E10 平台硬规则（白屏 / 无样式 / 资源 404 的真凶）
+## 六、@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'`，`type="resource"` | `references/components/form-EmployeeBrowser-api.md` |
+| Browser（部门） | `import { Browser } from '@weapp/ui'`，`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，不要为了用组件而用组件。原型还原优先用原生 HTML + 原型 CSS，平台组件只用于人员/部门选择、上传、文件预览等必须能力。
+
+---
 
-> 上面的规则管「能不能编译、数据对不对」；本节管平台**导入 / 运行期**的硬约束。
-> 违反不会报编译错，只会让页面发布后白屏、样式丢失或资源 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 打包与平台加载规则」。 |
-| **HTML 原型：样式严格 100% 还原** | 用户提供 HTML 原型时，页面样式必须与原型严格一致（布局、间距、字号、颜色、圆角、边框、层级），不得用平台默认样式近似代替；交付前逐项对照原型自检。 |
-| **HTML 复刻：样式写进代码，不建独立 CSS 文件** | 用户提供 HTML/设计稿并要求完整复刻时，样式全部写在组件代码里（内联 `style` / 代码内样式对象），**不要生成独立 `.css` 文件**——拆出去不保证被加载，复刻会静默丢样式。 |
-| **全部用 ESM `import` / `export`，禁止 `module.exports`** | 平台按模块加载，CommonJS 导出解析不到。 |
-| **只用白名单组件及其文档化 props** | 拿不准的组件 / prop / 图标名，先查 `references/components/`，不要凭记忆从 `@weapp/ui` 编造。 |
-| **不碰平台组件内部** | 不读 `props.children[...]`（含可选链写法）、不依赖内部 class / `weId` 段、不做全局无条件 `regOvComponent` 复写——内部结构不是稳定 API，平台升级即坏。 |
+|---|---|
+| 资源统一 `${appRes}/相对路径` | 禁止 `./resources/...`、`../resources/...`、`/resources/...`；发布后会 404 |
+| 禁止在线资源 | 不要 CDN、`loadjs('http(s)://...')`；第三方库先下载进项目 |
+| 禁止 `import './x.css'` | ecode 无 CSS 模块解析；样式用原型 CSS 字符串或内联 style |
+| 全 ESM | 不要 `module.exports` |
+| 只用白名单组件 | 不编造组件/props，不读 `props.children[...]`、不依赖内部 class/`weId` |
+| 路由 path 写死 | 不拼 `${appId}` 变量 |
+
+---
+
+## 八、自检与交付
+
+1. 用 `e10-cli check <项目目录>` 扫描已知规则。
+2. 用 `ecodecmd build <项目目录> --target=e10` 做真实编译；**不要依赖 `e10-cli compile` 作为门禁**。
+3. 检查 `build.json`：`entry.js` 必须是 `state:"y"`；新增文件后再次 build 不会自动补登记。
+4. 部署后由用户在实际环境验收页面；本流程不提供本地预览。
+
+自检清单：
+
+- [ ] `asyncImport('${appId}', ...)` 是固定字符串，没有换成数字
+- [ ] 所有变量用 `var`，没有 `let/const`（import 除外）
+- [ ] 没有 `??`、无参 `catch {}`、动态 `import()`
+- [ ] 页面在模块顶层创建 `formClient`，没有放进 render
+- [ ] 列表只渲染 `display`，写入只用 `values`
+- [ ] 人员/部门/附件回显用 `items`
+- [ ] 没有 `import` CSS，样式来自原型 CSS 字符串
+- [ ] 图片/资源使用 `${appRes}/...`
+- [ ] 只用白名单组件，没有直接改平台组件内部
+- [ ] `entry.js` 只做路由注册，没有业务逻辑
 
 ---
 
-## 代码质量检查清单
-
-生成代码后逐项检查：
-
-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 <项目目录>` 逐条自检
+## 九、常见错误
+
+| 错误 | 正确做法 |
+|---|---|
+| 把 `asyncImport` 第一个参数换成应用 ID 数字 | 原样保留 `'${appId}'` |
+| 在 `pages/` 里直接 `import` 另一个页面 | 用 `React.lazy(function () { return asyncImport('${appId}', 'pages/xxx'); })` |
+| 用 `row.display` 回填表单 | 用 `row.values` |
+| 用中文选项名做 `===` 比较 | 用选项 ID / `valueKey` |
+| 列表没传 `page/size` | 默认可能只回 10 条，显式传 |
+| 样式拆成独立 `.css` | 放回原型 CSS 字符串 |
+| 把 `const appId = '${appId}'` 当变量用 | 不需要这个变量，直接写在 `asyncImport` 里 |

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

@@ -7,12 +7,12 @@
 只有前置加载的文件才可以直接 import：
 
 ```js
-import { getSimpleData } from './api/formApi.js';  // entry.js 中可以直接引用
+import { formClient } from './api/formApi.js'; // 路径示例；实际在 pages 里使用
 ```
 
-- entry.js 中只能使用 `React`、`ReactDOM`、`@weapp/utils`、`@weapp/ecodesdk`、`axios`
+- entry.js 中只能使用 `React`、`ReactDOM`、`react-router-dom`、`@weapp/utils`、`@weapp/ecodesdk`、`axios`
 - **不能使用 `@weapp/ui` 组件**
-- entry 只完成入口的注册，不要写入业务逻辑
+- entry 只完成入口的注册，不要写入业务逻辑；数据操作放在 `pages/` 里
 
 ### 非前置加载文件（pages/ 目录）
 
@@ -20,10 +20,14 @@ import { getSimpleData } from './api/formApi.js';  // entry.js 中可以直接
 
 ```js
 import { asyncImport } from '@weapp/ecodesdk';
-const AgentSxxx = React.lazy(() => asyncImport('${appId}', 'pages/AgentSxxx'));
-// '${appId}' 是固定写法，是内置的ecode应用ID，不用管
+var AgentSxxx = React.lazy(function () {
+  // 单引号里的 ${appId} 是固定字符串，不是应用 ID，不要替换成数字
+  return asyncImport('${appId}', 'pages/AgentSxxx');
+});
 ```
 
+> `asyncImport` 第一个参数必须原样保留 `'${appId}'`。它不是 Ebuilder 应用 ID、不是 Ecode 项目 ID，也不是任何数字；平台运行时会替换这个固定占位符。`app/config.js` 里的 `APP_ID` 是 Ebuilder 应用 ID，只用于数据接口请求头。
+
 引用路径要根据文件相对位置判断：
 - entry.js 中引用 `api/formApi.js`：`'./api/formApi.js'`
 - pages/ 目录下引用 `api/formApi.js`：`'../api/formApi.js'`
@@ -35,16 +39,20 @@ const AgentSxxx = React.lazy(() => asyncImport('${appId}', 'pages/AgentSxxx'));
 在 `entry.js` 中通过 `regOvProps` + `regReactChildren` 注册路由：
 
 ```js
+import React from 'react';
+import { Route } from 'react-router-dom';
 import { regOvProps, appInfo, regReactChildren } from '@weapp/utils';
-const { publicUrl } = appInfo('@weapp/ecodesdk');
-const extract = (
-  <Route path={`${publicUrl}/sp/custom/abc123123/abc123`}> // 导出页面的具体路径
+
+var publicUrl = appInfo('@weapp/ecodesdk').publicUrl;
+var extract = (
+  <Route path={publicUrl + '/sp/custom/ecode/my-page'}>
     <React.Suspense fallback={<div>Loading...</div>}>
-      <Test />  // 导出页面的组件
+      <Test />
     </React.Suspense>
   </Route>
 );
-regOvProps('weappEcodesdk', 'Switch', (props) => {
+
+regOvProps('weappEcodesdk', 'Switch', function (props) {
   regReactChildren(props, extract);
   return props;
 }, 0);
@@ -90,26 +98,27 @@ regOvProps('weappEcodesdk', 'Switch', (props) => {
 
 ```js
 import React from 'react';
+import { Route } from 'react-router-dom';
 import { regOvProps, appInfo, regReactChildren } from '@weapp/utils';
 import { asyncImport } from '@weapp/ecodesdk';
 
-const { publicUrl } = appInfo('@weapp/ecodesdk');
-const appId = '${appId}';
+var publicUrl = appInfo('@weapp/ecodesdk').publicUrl;
 
-// 异步引入页面组件
-const MyPage = React.lazy(() => asyncImport('${appId}', 'pages/MyPage'));
+var MyPage = React.lazy(function () {
+  // 单引号里的 ${appId} 是固定字符串，不是应用 ID
+  return asyncImport('${appId}', 'pages/MyPage');
+});
 
-// 注册路由 — path 写死固定字符串，和
 var ROUTE_PATH = '/sp/custom/ecode/my-page';
-const myRoute = (
-  <Route path={`${publicUrl}${ROUTE_PATH}`}>
+var myRoute = (
+  <Route path={publicUrl + ROUTE_PATH}>
     <React.Suspense fallback={<div>Loading...</div>}>
       <MyPage />
     </React.Suspense>
   </Route>
 );
 
-regOvProps('weappEcodesdk', 'Switch', (props) => {
+regOvProps('weappEcodesdk', 'Switch', function (props) {
   regReactChildren(props, myRoute);
   return props;
 }, 0);

package/skill-docs/references/coding/ref-compile-rules.md

@@ -29,7 +29,7 @@ plugins: ['proposal-object-rest-spread', 'proposal-optional-chaining']
 |------|------|
 | JSX | `<div className="app">{content}</div>` |
 | 箭头函数 | `(x) => x + 1` |
-| async/await | `const data = await getSimpleData(...)` |
+| async/await | `var page = await items.list({ page: 1, size: 20 })` |
 | 模板字符串 | `` `Hello ${name}` `` |
 | 对象展开 `...` | `{ ...oldObj, newKey: val }` |
 | 可选链 `?.` | `obj?.nested?.value` |
@@ -113,9 +113,9 @@ e10-cli project import <projectId> .target/xxx.zip --main-url /sp/custom/...
 
 - **禁止在 JS 里 `import` CSS**：ecode 无 CSS 模块解析，写了必丢、发布后无样式。
 - **用户提供 HTML 原型时，页面样式严格 100% 还原**（布局、间距、字号、颜色、圆角、边框、层级），不用平台默认样式近似代替。
-- **完整复刻用户提供的 HTML 时，样式一律内联进代码**（内联 style / 代码内样式对象），不要拆成独立 `.css` 文件：拆出去既不保证加载，也容易与页面结构脱节，复刻效果走样。
-- 少量页面样式用内联 style；确需独立 `.css` 文件时，确认它在 `build.json` 的 codes 里（首次自动生成时 `.css` 会登记为 `y`；文件是后加的要自行补登记），否则平台不合并加载。
-- 业务 CSS 选择器挂在页面根容器下，避免裸 `.类名`、`body`、`:root` 或平台内部 class 污染全局。
+- **复用原型 CSS**：把原型 `<style>` 整段复制到代码里的字符串（如 `styles/prototypeStyles.js`），页面用 `<style>{PROTOTYPE_CSS}</style>` 渲染一次。不要新写 CSS、不要拆独立 `.css` 文件、不要把规则逐条改写成内联 style。
+- 少量页面样式可以用内联 style；确需独立 `.css` 文件时，确认它在 `build.json` 的 codes 里（首次自动生成时 `.css` 会登记为 `y`；文件是后加的要自行补登记），否则平台不合并加载。
+- 业务 CSS 选择器挂在页面根容器下，避免裸 `.类名`、`body`、`:root` 或平台内部 class 污染全局；原型的全局选择器和 keyframes 要收敛到页面根并加前缀。
 
 ### 资源规则
 
@@ -126,7 +126,7 @@ 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
+1. **所有变量用 var 声明**，非前置加载文件引用确保使用 `React.lazy(function () { return asyncImport('${appId}', 'pages/xxx'); })`
+2. **`${appId}` 是固定占位字符串**，不是 Ebuilder 应用 ID、Ecode 项目 ID 或任何数字；原样写在 `asyncImport` 第一个参数里，运行时由 ecode SDK 替换
+3. 写完代码后运行 `e10-cli check <项目目录>` 扫描已知规则，再用 `ecodecmd build <项目目录> --target=e10` 做真实编译；**不要把 `e10-cli compile` 当作可靠门禁**
 4. 本地修改后一定要及时 `ecodecmd build` + `import` 上传，否则用户无法验证（用户看不到本地代码）

package/skill-docs/references/common/map.md

@@ -15,6 +15,7 @@
 - **Ebuilder 应用** — 独立概念，包含表单、流程等资源（与 Ecode 项目不同）。
 - **默认台账与菜单入口是两件事** — 表单创建后会生成默认台账/列表视图，但 `form create` 默认不加应用菜单；需要入口时用 `--menu`，或建表后 `menu add-table`。默认台账已存在不等于菜单入口已存在。
 - 只有图表仪表盘、跨表单聚合视图、特殊交互流程、对外公开页面等场景才需要自定义页面。
+- 用户明确要求 Ecode、还原 HTML 原型或说明不要设计器时，按定制页面规划，直接走 Ecode；不要建议改用设计器。
 - 所有系统交互命令均通过 `e10-cli` 执行（已全局 link）。auth 文件自动查找，也可 `--auth <path>` 指定。
 - 当前登录用户的 userId 是固定变量 `TEAMS.currentUser.id`，前端代码里可以直接使用。
 
@@ -40,7 +41,7 @@
 | 报表 | 统计、分组和报表布局 | 写单元格、查询、共享和交付效果 | 保存与实际展示分别核对 | [报表创建](../report/guide-report-build.md) |
 | 菜单 | 提供台账、流程或页面入口 | 目标资源先存在；写层级、名称与可见主体 | 验收点击目标与菜单权限 | [菜单](../menu/system-menus.md) |
 | 配置式页面 | 用设计器组件搭建页面 | 写数据源、组件、布局和 PC/MOBILE 要求 | 验收两端布局与数据绑定 | [设计器](../ebuilder-designer/guide-designer.md) |
-| 定制页面 | 实现标准配置之外的交互 | 写目标页面、作用范围、发布与入口 | 验收实际加载和业务交互 | [页面编码](../coding/guide-page-code.md) |
+| 定制页面 | 实现标准配置之外的交互 | 写目标页面、作用范围、发布与入口；HTML 原型还原写清样式复用方式 | 验收实际加载和业务交互 | [页面编码](../coding/guide-page-code.md)、[HTML 原型还原](../coding/guide-html-to-react.md) |
 | ESB 系统接口 | 从接口文档创建对外接口定义 | 写系统池、接口清单和文档来源 | 区分接口定义与动作流 HTTP 调用；验收创建结果 | [接口导入](../esb-interface/guide-import.md) |
 | 组织数据 | 维护部门、人员等基础数据 | 写机构归属、人员来源和导入范围 | 批量导入先预检；验收数据和归属 | [组织](../hrm/guide-org-employee.md) |