weaver-e10-builder 1.0.10-beta → 1.0.12-beta

package/skill-docs/references/auth/guide-auth.md

@@ -0,0 +1,88 @@
+# 鉴权与多环境管理
+
+> e10-cli 支持多环境 Profile 切换，auth 文件和 config 按环境隔离存储。
+
+## 目录结构
+
+```
+~/.e10-cli/
+├── profile                    ← 当前激活的 profile 名
+└── profiles/
+    ├── yunteams/
+    │   ├── auth               ← 加密的认证凭证
+    │   └── config.json        ← baseUrl + passportUrl
+    └── mulinquan/
+        ├── auth
+        └── config.json
+```
+
+## 命令参考
+
+### 登录认证
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli auth set --eteamsid <id> --base-url <url>` | 直接写入 ETEAMSID（**当前唯一可用方式**）。ETEAMSID 从浏览器 DevTools → Application → Cookies 复制。自动解析 userId + tenantKey |
+| `e10-cli auth status` | 查看当前登录状态（含 profile 名、cookie 有效性） |
+
+> ⚠️ `e10-cli auth login`（浏览器 OIDC 登录）**暂未实现，已禁用**，执行会提示"开发中"。当前一律用 `auth set`。
+
+### Profile 管理
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli auth profile list` | 列出本地所有 Profile |
+| `e10-cli auth profile current` | 查看当前激活的 Profile |
+| `e10-cli auth profile use <name>` | 切换到指定 Profile（不存在则自动创建） |
+
+**单次覆盖**：所有命令支持 `--profile <name>` 临时用指定 profile（auth + config baseUrl），不切换全局激活态：
+```bash
+e10-cli --profile e-cology form list <appId>   # 只用这一次，不改变当前环境
+```
+
+## 典型用法
+
+```bash
+# 在 yunteams 环境登录
+e10-cli auth set --eteamsid "PCACCOUNT_xxx" --base-url "https://weapp.yunteams.cn"
+# → 自动创建/切换到 profile: yunteams
+
+# 切到 mulinquan
+e10-cli auth set --eteamsid "PCACCOUNT_yyy" --base-url "https://weapp.mulinquan.cn"
+# → 自动创建/切换到 profile: mulinquan
+
+# 查看所有环境
+e10-cli auth profile list
+
+# 切回 yunteams
+e10-cli auth profile use yunteams
+
+# 查看当前
+e10-cli auth status
+```
+
+## 全局选项
+
+| 选项 | 说明 |
+|------|------|
+| `--auth <path>` | 临时指定 auth 文件路径（覆盖 profile） |
+| `--base-url <url>` | 临时指定平台地址 |
+| `--json` | JSON 格式输出 |
+
+## Profile 命名规则
+
+`auth set` 时根据 `baseUrl` 域名自动生成 profile 名：
+- `https://weapp.yunteams.cn` → `yunteams`
+- `https://weapp.mulinquan.cn` → `mulinquan`
+
+也可用 `auth profile use <自定义名>` 手动创建命名。
+
+## 凭证加密
+
+Auth 文件使用 AES-256-GCM 加密存储，密钥存于 **OS keychain**（每机一把动态密钥，源码不含密钥），headless 无 keychain 后端时回退到 `~/.e10-cli/.key`（0600）。详见 `core/crypto.ts`。格式：
+```json
+{ "enc": true, "v": 1, "data": "<base64>" }
+```
+
+> 与 `e10-login` 共用同一 keychain 条目（service=`e10-cli`/account=`auth-key`），auth 文件在 e10-cli 与 e10-login 间互通——用任一登录后另一个可直接用。
+> ⚠️ 从硬编码密钥迁移到动态密钥后，旧版 auth 文件无法解密，需重新登录（`auth login` 或 `auth set --eteamsid`）。

package/skill-docs/references/coding/guide-edit-backfill.md

@@ -0,0 +1,189 @@
+# 编辑回显指南
+
+编辑已有数据时，需要将表单数据加载回表单控件中。`getSimpleData` 对特殊类型统一返回 ID，可直接用于表单回显，但选择器组件需要额外提取 name 信息。
+
+---
+
+## 核心流程
+
+### 第一步：加载时同时获取两份数据
+
+```js
+// loadData 中用 Promise.all 同时获取两份数据
+function loadData() {
+  Promise.all([
+    getSimpleData(OBJ_ID, USER_ID),
+    getAllData(OBJ_ID, USER_ID),
+  ]).then(function ([simpleRows, allRows]) {
+    setData(withDisplayNames(simpleRows, statusMap));
+    setRawData(allRows);  // 保存原始数据用于编辑回显
+  });
+}
+```
+
+### 第二步：编辑按钮点击时回填表单
+
+```js
+function handleEdit(rowData) {
+  var dataId = rowData._raw.id;  // Table 回调的 rowData 有 _raw，不是 getSimpleData 返回的行
+
+  // 1. 从 rawData(原始接口数据) 中查找对应记录
+  var rawEntry = rawData.find(function (r) {
+    return r.mainTable && r.mainTable.id && r.mainTable.id.fieldValue === dataId;
+  });
+
+  // 2. 用 getSimpleData 的值填充表单（所有特殊字段已是 ID，可直接用）
+  var editForm = {};
+  Object.keys(emptyForm).forEach(function (key) {
+    editForm[key] = rowData._raw[key] || '';
+  });
+
+  // 3. 从 rawEntry.mainTable 中提取 name 信息（选择器组件需要 [{id, name}] 格式）
+  var newSelectedPerson = [];
+  var newSelectedDept = [];
+  var newUploadedFiles = [];
+
+  if (rawEntry && rawEntry.mainTable) {
+    Object.keys(rawEntry.mainTable).forEach(function (key) {
+      var val = rawEntry.mainTable[key];
+      if (!val) return;
+
+      if (Array.isArray(val) && val.length > 0) {
+        var fieldId = val[0].fieldId;
+        var fieldType = val[0].fieldType;
+
+        if (fieldId === F.person) {
+          newSelectedPerson = val.map(function (v) {
+            return { id: v.fieldOptionId, name: v.fieldOptionName };
+          });
+        } else if (fieldId === F.dept) {
+          newSelectedDept = val.map(function (v) {
+            return { id: v.fieldOptionId, name: v.fieldOptionName };
+          });
+        } else if (fieldId === F.attachment) {
+          newUploadedFiles = val.map(function (v) {
+            return { fileid: v.fieldOptionId, name: v.fieldOptionName };
+          });
+        } else if (fieldType === 'Select' || fieldType === 'RadioBox' || fieldType === 'CheckBox') {
+          // getSimpleData 已返回 ID，此处从 rawEntry 再次确认（多选时覆盖）
+          editForm[fieldId] = val.map(function (v) { return v.fieldOptionId; }).join(',');
+        }
+      }
+    });
+  }
+
+  // 4. 一次性设置所有状态
+  setForm(editForm);
+  setSelectedPerson(newSelectedPerson);
+  setSelectedDept(newSelectedDept);
+  setUploadedFiles(newUploadedFiles);
+  setModalVisible(true);
+}
+```
+
+---
+
+## 关键点总结
+
+| 要点 | 说明 |
+|------|------|
+| `getAllData` 返回结构中 `id` 在 `mainTable` 内部 | 查找原始记录必须是 `r.mainTable.id.fieldValue`，**不能**写成 `r.id.fieldValue` |
+| `Browser`(人员/部门) 的 `value` | 需要 `[{id, name}]` 格式 |
+| `Upload`(附件) 的 `data` | 需要 `[{fileid, name}]` 格式 |
+| `Select` 下拉框的 `value` | 需要匹配 `fieldOptionId`（即 `opt.valueKey`），不能是显示名 |
+| Table 的 `onRowClick` 回调 | `rowData._raw` 引用了原始数据行，`rowData._raw.id` 是 dataId |
+| 表单字段值来源 | 从 `getSimpleData` 取值（已是 ID），选择器显示名从 `getAllData` 提取 |
+
+---
+
+## getSimpleData vs getAllData 结构对比
+
+### getSimpleData 返回（扁平，纯 ID，用于写入）
+
+```json
+[
+  {
+    "1290462231772995585": "张三",                   // Text：直接就是值
+    "1290462231772995586": "1290462231772995612",    // Select：选项 ID
+    "1290462231772995589": "2765550234448235905",    // Employee：用户 ID
+    "id": "1290469928435908609"
+  }
+]
+```
+
+所有特殊字段统一返回 `fieldOptionId`（纯 ID），直接用于 `formToSave`。
+
+### getAllData 返回（含名称，用于展示/回显）
+
+```json
+{
+  "mainTable": {
+    "sjhfa391": {                                     // ← key 是随机哈希，不是 fieldId！
+      "fieldId": "1290462231772995590",
+      "fieldType": "Text",
+      "fieldValue": "13800138000"
+    },
+    "zssj98f9d": [{                                   // ← Employee 是数组！
+      "fieldId": "1290462231772995589",
+      "fieldType": "Employee",
+      "fieldOptionId": "2765550234448235905",
+      "fieldOptionName": "张三"
+    }],
+    "bm1d630": [{                                     // ← Select 也是数组！
+      "fieldId": "1290462231772995586",
+      "fieldType": "Select",
+      "fieldOptionId": "1290462231772995612",
+      "fieldOptionName": "技术部"
+    }],
+    "id": {                                           // ← 只有 id 的 key 是 "id"
+      "fieldId": "5",
+      "fieldType": "Text",
+      "fieldValue": "1290469928435908609"
+    }
+  }
+}
+```
+
+### 三个关键规则
+
+| 规则 | 说明 |
+|------|------|
+| **key 是随机哈希** | `mainTable` 的 key（如 `sjhfa391`）是随机字符串，**不能**用 `mainTable[fieldId]` 直接取值 |
+| **只能用 fieldId 匹配** | 必须遍历 `Object.values(mainTable)`，通过 `val.fieldId` 或 `val[0].fieldId` 匹配目标字段 |
+| **数组 vs 对象** | Employee / Select / FileComponent / RadioBox / CheckBox → **数组** `[{...}]`；Text / Number / DateComponent → **对象** `{...}` |
+| **只有 id 是 deterministic** | 数据行 ID 的 key 固定为 `"id"`，可直接用 `mainTable.id.fieldValue` |
+
+### 字段值 → 组件 props 映射表
+
+> 这是整个编辑回显最容易出错的一步。getAllData 中的字段形状各不相同，映射到组件 props 的方式也不同。
+
+| 字段类型 | getAllData 中的形状 | 目标组件 | 需要的 props 格式 | 映射方式 |
+|---------|-------------------|---------|-----------------|---------|
+| Employee | `[{fieldOptionId, fieldOptionName}]` | `Browser` | `value={[{id, name}]}` | `v.fieldOptionId → id`，`v.fieldOptionName → name` |
+| Department | `[{fieldOptionId, fieldOptionName}]` | `Browser` | `value={[{id, name}]}` | 同上 |
+| FileComponent | `[{fieldOptionId, fieldOptionName}]` | `Upload` | `data={[{fileid, name}]}` | `v.fieldOptionId → fileid`，`v.fieldOptionName → name` |
+| Select（单选） | `[{fieldOptionId}]` | `<select>` | `value="fieldOptionId"` | 取 `val[0].fieldOptionId` |
+| Select（多选） | `[{...}, {...}]` → 多个 | `<select multiple>` | 逗号分隔串 | `val.map(...).join(',')` |
+| Text / Number | `{fieldValue}` | `<input>` | `value="fieldValue"` | 直接用 `getSimpleData` 的值 |
+
+### 正确的字段提取方式
+
+```js
+// 查找 mainTable 中 fieldId 匹配的字段值
+function findField(mainTable, targetFieldId) {
+  var keys = Object.keys(mainTable);
+  for (var i = 0; i < keys.length; i++) {
+    var val = mainTable[keys[i]];
+    if (!val) continue;
+    // 数组类型（Employee/Select 等）取 val[0].fieldId
+    if (Array.isArray(val) && val.length > 0 && val[0].fieldId === targetFieldId) {
+      return val;
+    }
+    // 普通类型（Text/DateComponent 等）取 val.fieldId
+    if (!Array.isArray(val) && val.fieldId === targetFieldId) {
+      return val;
+    }
+  }
+  return null;
+}
+```

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

@@ -0,0 +1,262 @@
+# 表单数据操作指南
+
+Ebuilder 项目没有后端，但可以通过读写 Ebuilder 的表单来实现数据交互。所有 CRUD 接口已实现在 `/api/formApi.js` 中。
+
+> 应用已注册的表单信息及字段用 `e10-cli form read <objId> --app-id <appId> --out fields.json` 导出（机器可读 JSON），为空说明还没注册。
+
+---
+
+## 〇、非对称设计（读写分离）
+
+**这是整份指南最核心的概念，每次写表单页面之前必须理解。**
+
+`getSimpleData` 对所有特殊类型（Select / RadioBox / CheckBox / Employee / Department / FileComponent）**统一返回 ID**（`fieldOptionId`）。好处是写入简单——直接拿 ID 原样写入，不用做任何转换。代价是展示麻烦——ID 是长数字，用户完全看不懂。
+
+```
+写入路径（简单）：getSimpleData → form 直接用 ID → saveFormData/updateFormData
+展示路径（复杂）：getSimpleData → ID → 映射为名称 → 表格渲染
+```
+
+**不同字段类型，名称来源不同**：
+
+| 字段类型 | getSimpleData 返回值 | 名称来源 |
+|---------|---------------------|---------|
+| 普通文本/数字/日期 | `"名称"` / `123` / `"2026-01-01"` | 直接展示 |
+| Select / RadioBox / CheckBox | `"1283421826353889337"`（ID） | `getFieldOptions` 映射 `valueKey → name` |
+| Employee / Department | `"5140559860850691459"`（用户ID） | `getAllData` 提取 `fieldOptionName` |
+| FileComponent | `"fileid1,fileid2"`（文件ID串） | 上传组件的 `name` 字段 |
+
+> **铁律：表格里永远不要直接渲染 `row[字段ID]`。** 用户看到一列长数字 = 你漏掉了名称转换。
+
+---
+
+## 一、四个 API 的职责
+
+| API | 职责 |
+|-----|------|
+| `getAllData` | 做源（含 `fieldOptionName`，用于提取名称信息） |
+| `getSimpleData` | 做读写（纯 ID，不含名称） |
+| `withDisplayNames` | 做展示（ID → 名称转换） |
+| `getFieldOptions` | 做下拉（拿 `valueKey` + `name`） |
+
+---
+
+## 二、核心规则：读取用 ID，展示用名称
+
+**最容易出错的点，每次编码前务必理解：**
+
+`getSimpleData` 对所有特殊类型（Select/RadioBox/CheckBox/Employee/Department/FileComponent）**统一返回 ID**（`fieldOptionId`），读写一致。
+
+> 写完代码逐条自检，90% 的 bug 都是这几个：
+> 1. `if (row[roomField] === '101')` — Select 字段值是 `fieldOptionId`（长数字如 `"1283421826353889337"`），永远不等于选项名称
+> 2. `{row[empField]}` 直接渲染 — Employee/Department 返回的是长数字 ID，人名需从 `getAllData` 提取 `fieldOptionName`
+> 3. 表格里直接显示 `row[fieldId]` — 用户看到一列长数字。展示用 `withDisplayNames()`
+
+- **写入保存** → 直接用 `getSimpleData` 的返回值，所有字段都是 ID，无需转换
+- **表格展示** → 用 `withDisplayNames()` 把 ID 转成名称，否则用户看到的是数字
+
+---
+
+## 三、读取表单数据
+
+### 3.1 getSimpleData — 获取简单格式数据
+
+```js
+import { getSimpleData } from '../api/formApi.js';
+const CONFIG = {
+  objId: '12556432068......',
+  userId: TEAMS.currentUser.id
+};
+const data = await getSimpleData(CONFIG.objId, CONFIG.userId);
+```
+
+返回格式：
+```js
+[
+  {
+    "4765111450482898127": "具体的数据内容",
+    "4765111450482898155": "具体的数据内容",
+    "id":"1259017552222814208"  // 表单数据固有的数据ID字段，fieldId固定为"id"
+  },
+  {.....}
+]
+```
+
+`getSimpleData` 返回的是扁平对象，字段 ID 作为 key 直接挂载在行上，**没有 `_raw` 层**。直接用 `item[字段ID]` 访问。
+
+> 注意：Table 组件的 `onRowClick` 回调参数中会带 `_raw`（引用原始数据行），仅在编辑回显等场景通过回调参数访问，不要主动去构造 `_raw`。
+
+### 3.2 withDisplayNames — ID → 名称转换（表格展示用）
+
+用于在表格中把 Select/Employee/Department 等字段的 ID 转成可读名称。
+
+推荐写法：
+```js
+import { getSimpleData, withDisplayNames, getFieldOptions } from '../api/formApi.js';
+
+function TemplatePage() {
+  const [data, setData] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(function () {
+    Promise.all([
+      getSimpleData(CONFIG.objId, CONFIG.userId),
+      // 为每个需要展示名称的 Select 字段调用 getFieldOptions
+      getFieldOptions(F.status, OBJ_ID),
+    ]).then(function ([rows, statusOpts]) {
+      setData(withDisplayNames(rows, { [F.status]: statusOpts }));
+    }).catch(function () {})
+      .finally(function () { setLoading(false); });
+  }, []);
+  // ......
+```
+
+### 3.3 getFieldOptions — 获取选项列表
+
+动态获取 Select/RadioBox/CheckBox 字段的可选值：
+
+```js
+import { getFieldOptions } from './api/formApi.js';
+```
+
+返回结构：
+```js
+[
+    {
+        "valueKey": "1263421826353889337",
+        "name": "已入职"
+    },{
+        "valueKey": "1263421826353889338",
+        "name": "已离职"
+    }
+]
+```
+
+---
+
+## 四、字段类型对应组件
+
+`form read --out fields.json` 导出的字段列表会告诉你每个字段的类型和 ID，有一些特殊的类型你必须选用对应的组件进行输入：
+
+| 字段类型 | 对应组件 |
+|---------|---------|
+| Employee | `Browser` — 人员选择框（`module="hrm" type="resource"`） |
+| Department | `Browser` — 部门选择框（`module="hrm" type="department"`） |
+| FileComponent | `Upload` — 文件上传（参考 `references/components/form-Upload.md`） |
+
+---
+
+## 五、数据写入
+
+### 5.1 formData 格式
+
+**一定是字段 ID 作为 key 的格式**，字段 ID 是纯数字组成的字符串，不包含任何其他符号。必须对照 `form read --out fields.json` 导出的字段来写，不要自己编造。
+
+```
+{
+  "4765111450482898127": "数据内容1",
+  "4765111450482898155": "数据内容2"
+}
+```
+
+### 5.2 三个写接口
+
+**新增：**
+```js
+export async function saveFormData(objId, formData, userId)
+```
+
+**更新（多一个 dataId 参数）：**
+```js
+export async function updateFormData(objId, formData, dataId, userId)
+```
+
+**删除：**
+```js
+export async function deleteFormData(objId, dataId, userId)
+```
+
+### 5.3 调用方式
+
+```js
+if (editingId) {
+  promise = updateFormData(OBJ_ID, formToSave, editingId, USER_ID);
+} else {
+  promise = saveFormData(OBJ_ID, formToSave, USER_ID);
+}
+```
+
+### 5.4 写入时直接使用 form 的值（已全部为 ID）
+
+`getSimpleData` 对所有特殊类型（Select/Employee/Department/FileComponent）统一返回 ID。编辑保存时无需跳过任何字段，`form` 中的值可直接写入。
+
+```js
+var formToSave = {};
+
+// 所有字段统一处理，getSimpleData 已返回 ID
+Object.keys(form).forEach(function (key) {
+  var val = form[key];
+  if (val !== '' && val !== null && val !== undefined) {
+    formToSave[key] = val;
+  }
+});
+
+// 用户操作选择器时用新值覆盖
+if (selectedPerson.length > 0) {
+  formToSave[F.person] = selectedPerson[0].id;
+}
+if (selectedDept.length > 0) {
+  formToSave[F.dept] = selectedDept[0].id;
+}
+if (uploadedFiles.length > 0) {
+  formToSave[F.attachment] = uploadedFiles.map(function (f) { return f.fileid; }).join(',');
+}
+```
+
+---
+
+## 六、三个高频编码错误
+
+编写 Ebuilder 页面时，以下三个错误非常高发，生成代码前务必检查：
+
+### 错误 1：数据访问用错层级
+
+`getSimpleData` 返回的每一行直接用 `item[字段ID]`，**没有 `_raw` 层**。
+
+```js
+// 错误
+var title = item._raw[F.title];
+
+// 正确
+var title = item[F.title];
+```
+
+### 错误 2：Select 字段用名称做判断
+
+`getSimpleData` 对 Select/RadioBox/CheckBox 字段返回的是**选项 ID**（`fieldOptionId`，即 `valueKey`），如 `"1283421826353889337"`，不是显示名称。
+
+```js
+// 错误
+if (item[F.status] === '已完成') { ... }  // 显示名称永远不匹配
+
+// 正确
+if (item[F.status] === '1283421826353889337') { ... }  // 用选项 ID
+```
+
+**表格中显示名称**请使用 `withDisplayNames()`，不要在表格列渲染时逐行查 ID。
+
+### 错误 3：React state 直接修改
+
+直接修改对象属性再 `setForm` 不会触发 React 重新渲染。
+
+```js
+// 错误
+form[F.name] = value;
+setForm(form);
+
+// 正确
+var newForm = {};
+Object.keys(form).forEach(function (k) { newForm[k] = form[k]; });
+newForm[F.name] = value;
+setForm(newForm);
+```