weaver-e10-builder 1.6.14 → 1.6.16

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

@@ -1,381 +1,381 @@
-# 页面编码指南
-
-> 本文件是 Ecode React 页面的主入口。用户明确要求 Ecode、还原 HTML 原型或不要设计器时，直接按本指南执行，不要再建议改用设计器。
-> 页面是搭建的最后一步，写代码前确保应用、表单、流程已建好。
-
----
-
-## 一、项目结构
-
-```
-├── entry.js                 ← 路由注册入口
-├── pages/                   ← 页面组件
-│   └── Items.js
-├── api/
-│   └── formApi.js           ← formClient
-├── app/
-│   ├── config.js            ← APP_ID / OBJ_ID
-│   └── fields.js            ← 字段 ID 常量
-├── styles/
-│   └── prototypeStyles.js     ← 原型的 CSS 字符串
-└── resources/               ← 图片等静态资源
-```
-
-- `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：`${appId}` 是固定字符串
-
-```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').publicUrl;
-
-var ItemsPage = React.lazy(function () {
-  // 单引号里的 ${appId} 是固定字符串，不是应用 ID，不要替换成数字
-  return asyncImport('${appId}', 'pages/Items');
-});
-
-var extract = (
-  <Route path={publicUrl + '/sp/custom/ecode/items'}>
-    <React.Suspense fallback={<div>Loading...</div>}>
-      <ItemsPage />
-    </React.Suspense>
-  </Route>
-);
-
-regOvProps('weappEcodesdk', 'Switch', function (props) {
-  regReactChildren(props, extract);
-  return props;
-}, 0);
-```
-
-**`asyncImport` 的第一个参数是字面量 `'${appId}'`**：
-
-```js
-// 正确：原样保留这个字符串
-asyncImport('${appId}', 'pages/Items')
-
-// 错误：把 Ebuilder 应用 ID、Ecode 项目 ID 或任何数字填进去
-asyncImport('1330584721118584834', 'pages/Items')
-asyncImport('1328370888652840961', 'pages/Items')
-```
-
-它不是变量，也不是当前应用的 `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 一致 |
-
-其它铁律：
-
-- `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` 注册。
-
----
-
-## 三、字段常量
-
-先用 CLI 导出字段：
-
-```bash
-e10-cli form read <objId> --app-id <appId> --out fields.json
-```
-
-再生成 `app/fields.js`：
-
-```js
-export var F = {
-  name: '4765111450482898127',
-  status: '4765111450482898155',
-  owner: '4765111450482898160'
-};
-
-export var LABELS = {
-  name: '名称',
-  status: '状态',
-  owner: '负责人'
-};
-```
-
-字段 ID 必须是 `fields.json` 里的 `fieldId`，不要手写、不要用字段名代替。
-
----
-
-## 四、表单数据：只用 formClient
-
-```js
-import { formClient } from '../api/formApi.js';
-import { APP_ID, OBJ_ID } from '../app/config.js';
-
-var items = formClient({ objId: OBJ_ID, appId: APP_ID });
-```
-
-页面只记三件事：
-
-```js
-page.rows[i].values / display / items   // 一个行形状
-items.list / get / save / update / remove  // 一套 CRUD
-```
-
-完整用法见 `guide-form-crud.md`，编辑回显见 `guide-edit-backfill.md`。最小列表页：
-
-```js
-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>
-  );
-}
-```
-
-不要再在页面里：
-
-- 传 `userId` / `tenantKey`
-- 调 `getSimpleData` / `getAllData` / `withDisplayNames`
-- 拼 `mainTable`、判断随机 key、数组还是对象
-- 把 `display` 里的中文名写回接口
-
-这些都在 `formApi.js` 里处理。
-
----
-
-### 页面上还能拿到什么：`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`。核心规则：
-
-- 原型 `<style>` 整段复制到 `styles/prototypeStyles.js` 的字符串里，页面用 `<style>{PROTOTYPE_CSS}</style>` 渲染一次
-- 不新写 CSS、不建独立 `.css`、不 `import` CSS、不把规则逐条改写成内联 style
-- 保留原 class 名和 DOM 层级，只做 `class`→`className`、`for`→`htmlFor`、`style` 字符串→对象、模板字符串→组件/`map` 的机械转换
-- 全局选择器、`:root`、keyframes 收敛到页面根容器，避免污染平台壳
-- 图片走 `${appRes}/...`
-
----
-
-## 六、@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，平台组件只用于人员/部门选择、上传、文件预览等必须能力。
-
-组件的通用属性（`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`。
-
----
-
-## 七、平台硬规则
-
-| 规则 | 说明 |
-|---|---|
-| 资源统一 `${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` 只做路由注册，没有业务逻辑
-
----
-
-## 九、常见错误
-
-| 错误 | 正确做法 |
-|---|---|
-| 把 `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` 里 |
-
----
-
-## 十、页面与流程协作
-
-**发起流程走平台页面，不要自己调接口创建流程。** 页面里只负责拼链接：
-
-```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`），需要给用户看待办时跳转过去；页面不自行调用任务列表接口。
+# 页面编码指南
+
+> 本文件是 Ecode React 页面的主入口。用户明确要求 Ecode、还原 HTML 原型或不要设计器时，直接按本指南执行，不要再建议改用设计器。
+> 页面是搭建的最后一步，写代码前确保应用、表单、流程已建好。
+
+---
+
+## 一、项目结构
+
+```
+├── entry.js                 ← 路由注册入口
+├── pages/                   ← 页面组件
+│   └── Items.js
+├── api/
+│   └── formApi.js           ← formClient
+├── app/
+│   ├── config.js            ← APP_ID / OBJ_ID
+│   └── fields.js            ← 字段 ID 常量
+├── styles/
+│   └── prototypeStyles.js     ← 原型的 CSS 字符串
+└── resources/               ← 图片等静态资源
+```
+
+- `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：`${appId}` 是固定字符串
+
+```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').publicUrl;
+
+var ItemsPage = React.lazy(function () {
+  // 单引号里的 ${appId} 是固定字符串，不是应用 ID，不要替换成数字
+  return asyncImport('${appId}', 'pages/Items');
+});
+
+var extract = (
+  <Route path={publicUrl + '/sp/custom/ecode/items'}>
+    <React.Suspense fallback={<div>Loading...</div>}>
+      <ItemsPage />
+    </React.Suspense>
+  </Route>
+);
+
+regOvProps('weappEcodesdk', 'Switch', function (props) {
+  regReactChildren(props, extract);
+  return props;
+}, 0);
+```
+
+**`asyncImport` 的第一个参数是字面量 `'${appId}'`**：
+
+```js
+// 正确：原样保留这个字符串
+asyncImport('${appId}', 'pages/Items')
+
+// 错误：把 Ebuilder 应用 ID、Ecode 项目 ID 或任何数字填进去
+asyncImport('1330584721118584834', 'pages/Items')
+asyncImport('1328370888652840961', 'pages/Items')
+```
+
+它不是变量，也不是当前应用的 `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 一致 |
+
+其它铁律：
+
+- `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` 注册。
+
+---
+
+## 三、字段常量
+
+先用 CLI 导出字段：
+
+```bash
+e10-cli form read <objId> --app-id <appId> --out fields.json
+```
+
+再生成 `app/fields.js`：
+
+```js
+export var F = {
+  name: '4765111450482898127',
+  status: '4765111450482898155',
+  owner: '4765111450482898160'
+};
+
+export var LABELS = {
+  name: '名称',
+  status: '状态',
+  owner: '负责人'
+};
+```
+
+字段 ID 必须是 `fields.json` 里的 `fieldId`，不要手写、不要用字段名代替。
+
+---
+
+## 四、表单数据：只用 formClient
+
+```js
+import { formClient } from '../api/formApi.js';
+import { APP_ID, OBJ_ID } from '../app/config.js';
+
+var items = formClient({ objId: OBJ_ID, appId: APP_ID });
+```
+
+页面只记三件事：
+
+```js
+page.rows[i].values / display / items   // 一个行形状
+items.list / get / save / update / remove  // 一套 CRUD
+```
+
+完整用法见 `guide-form-crud.md`，编辑回显见 `guide-edit-backfill.md`。最小列表页：
+
+```js
+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>
+  );
+}
+```
+
+不要再在页面里：
+
+- 传 `userId` / `tenantKey`
+- 调 `getSimpleData` / `getAllData` / `withDisplayNames`
+- 拼 `mainTable`、判断随机 key、数组还是对象
+- 把 `display` 里的中文名写回接口
+
+这些都在 `formApi.js` 里处理。
+
+---
+
+### 页面上还能拿到什么：`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`。核心规则：
+
+- 原型 `<style>` 整段复制到 `styles/prototypeStyles.js` 的字符串里，页面用 `<style>{PROTOTYPE_CSS}</style>` 渲染一次
+- 不新写 CSS、不建独立 `.css`、不 `import` CSS、不把规则逐条改写成内联 style
+- 保留原 class 名和 DOM 层级，只做 `class`→`className`、`for`→`htmlFor`、`style` 字符串→对象、模板字符串→组件/`map` 的机械转换
+- 全局选择器、`:root`、keyframes 收敛到页面根容器，避免污染平台壳
+- 图片走 `${appRes}/...`
+
+---
+
+## 六、@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，平台组件只用于人员/部门选择、上传、文件预览等必须能力。
+
+组件的通用属性（`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`。
+
+---
+
+## 七、平台硬规则
+
+| 规则 | 说明 |
+|---|---|
+| 资源统一 `${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` 只做路由注册，没有业务逻辑
+
+---
+
+## 九、常见错误
+
+| 错误 | 正确做法 |
+|---|---|
+| 把 `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` 里 |
+
+---
+
+## 十、页面与流程协作
+
+**发起流程走平台页面，不要自己调接口创建流程。** 页面里只负责拼链接：
+
+```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`），需要给用户看待办时跳转过去；页面不自行调用任务列表接口。