weaver-e10-builder 1.6.0 → 1.6.4

package/skill-docs/references/common/ref-cli-commands.md

@@ -18,7 +18,7 @@
 | 命令 | 说明 |
 |------|------|
 | `e10-cli project create <name> [desc]` | 新建 Ecode 项目（名称自动追加时间戳） |
-| `e10-cli project import <projectId> <zip> --main-url <url>` | 导入 zip 包，`--main-url` **必填** |
+| `e10-cli project import <projectId> <zip> --main-url <url> [--replace]` | 导入 zip 包，`--main-url` **必填**；`--replace` 导入前清理同名旧应用目录（含 `ecode1`/`ecode2` 后缀），避免并存 |
 | `e10-cli project tree <parentId>` | 查看目录结构 |
 | `e10-cli project read <fileId>` | 读取代码文件内容 |
 | `e10-cli project update <fileId> <content>` | 更新代码文件（content 以 `@` 开头则为文件路径） |
@@ -28,7 +28,8 @@
 | `e10-cli project delete-folder <folderId>` | 删除文件夹（= 删除应用） |
 
 - 导入成功后会在 Ecode 项目下生成应用文件夹
-- 二次导入之前先删掉旧应用文件夹（通过 `e10-cli project tree` 找到 folderId）
+- 二次导入用 `--replace`；不带时会新建一个同名/带数字后缀的目录
+- `--replace` 先删同名旧目录再导入；如果导入失败，旧目录已删除，需要重新导入
 
 ---
 
@@ -70,8 +71,8 @@
 | `e10-cli app unpublish <appId>` | 取消发布（收回前台入口）。⚠ **不可逆、无回收站**；重新发布是新入口。回读确认入口确实没了才报成功 |
 | `e10-cli app lang get <appId>` | 查看应用名各语言译文 |
 | `e10-cli app lang set <appId> [--zh] [--en]` | 设置应用名多语言。**简体中文那档就是应用名本身**；只给 `--en` 不会清空中文（内部先读回再整份写回）。改应用名（`app edit --name`）不动多语言配置 |
-| `e10-cli form read <objId> [--app-id <appId>] [--out <file>]` | 读取表单字段。`--app-id` 含明细表字段+Select/RadioBox/CheckBox 选项、**并标注每个字段属于哪张物理表**（`· 物理表: 表1`，JSON 里是 `formTable` 键；多物理表见 `form physical-table list`）；**输出里的字段名（文本那栏 / JSON 的 `fieldName`）就是字段标题** —— 与设计器「字段管理」里看到的是同一个值，它为空就说明标题没写进去；`--out fields.json` 写 UTF-8 JSON（推荐，机器可读）。旧版 `[dir]` 参数写 memo.md，已过时 |
-| `e10-cli form read <objId> --app-id <appId> --out fields.json` | 读取字段含选项（Select/RadioBox/CheckBox 自动带 options）。**含明细表字段**，配动作流/联动拿明细 fieldId 用这个 |
+| `e10-cli form read <objId> [--app-id <appId>] [--out <file>]` | 读取表单字段。`--app-id` 含明细表字段、Select/RadioBox/CheckBox 选项、`dataKey`（写入 request key）、`multiSelect`、日期 `format`、`optionIds`（选项名→ID）及物理表归属；`--out fields.json` 写 UTF-8 JSON。**字段名就是字段标题**；标题为空说明没写进去 |
+| `e10-cli form read <objId> --app-id <appId> --out fields.json` | 生成页面 `fields.js` 和选项映射的推荐入口：选项、dataKey、多选、日期格式一次导出 |
 | `e10-cli form list <appId>` | 列出应用下的所有表单 |
 | `e10-cli form create <appId> <name> <dir> --fields @<json文件>` | 创建表单。`--fields` **必填**。支持 DetailTable(嵌套formFields)、EBuilder(sformId+dataTitle，**明细 `formFields` 内的 EBuilder 同样绑定**)、relateFrom(联动)。**开关 `Switch` 自动配置固定选项 开启=1 / 关闭=0**（主表/明细/后续加字段同）。fields.json 字段可带 `"required":true`/`"readOnly":true` 直标（写进布局 comps）。**字段名与平台系统字段重名（标题/创建者/创建时间/数据ID/最后更新人/数据状态）→ 不新建物理字段、复用系统字段**，并把该字段在**布局置为可见**（platform 系统字段默认隐藏；可写 `"singleRow":true` 独占一行、`"hidden":true` 保持隐藏）。`--json` 返回 `skippedSys`。**默认不加菜单**，要入口传 `--menu`（台账菜单 VIEWPORT）；漏加 `e10-cli menu add-table <appId> <objId>` 补。**`--table-name <名>` 自定义数据库表名**（平台前缀如 `uf_` 由 CLI 自动补，传 `cs_khxx` 与 `uf_cs_khxx` 等价；字母开头、只含字母数字下划线；自定义部分受平台长度上限约束——`uf_` + 总长 30 时最多 27 位，越界直接报错不建半张表；建成后回读校验实际表名；仅物理表应用适用） |
 | `e10-cli form virtual source-groups` / `sources <groupId>` | 查询 EB 表单和系统业务数据源分组、数据源列表 |
@@ -177,7 +178,8 @@
 | `e10-cli form layout delete <objId> <appId> <布局ID>` | 删除一套布局（设计器的「删除」）。⚠ **不可逆**。删完**回读确认列表里确实没了**才算成功；该布局原先占的用途档位会一并打印。删掉正占着 `all` 的那套会怎样**未验证**，慎用 |
 | `e10-cli form group <objId> <appId> --groups '{"基本信息":["字段名/fieldId",...]}'` | 给**已建好的 eb 表**加字段分组（折叠容器）。建组 saveFieldGroup → 分配 updateFormFieldGroup → initLayout generateCollapse 渲染。`--groups` 可 `@文件`；`--required` 同时设分组内字段必填；同名分组复用不重复建（去重）。建表时一次性带分组用 `form create` 的 fields.json `group` 属性 |
 | `e10-cli form data add <objId> <appId> <json>` | 写入表单数据（`@` 开头为 JSON 文件路径）。JSON key 可用 fieldId 或字段名；Select/RadioBox 值填选项名（自动解析 valueKey）或 valueKey、CheckBox/SelectMultiple 用数组、TextArea 直接值、Employee/Department 用 ID。详见 `form/guide-form-data.md` |
-| `e10-cli form data list <objId> [--page <n>] [--size <n>]` | 查询表单数据（**只含主表**）。`--page` 页码（缺省1）、`--size` 每页条数（缺省1000；不传 pageInfo 平台默认卡 10） |
+| `e10-cli form data upload --file <路径...> [--create-doc on\|off] [--module ebuilder]` | 上传附件文件，返回 `fileId` / `docId`。表单附件默认 `createDoc=true`，同时生成文档；`--create-doc off` 只留文件、文档中心没有文档。输出 `fileIds` 逗号串，可直接填 `form data add/update` 的附件字段 |
+| `e10-cli form data list <objId> [--page <n>] [--size <n>]` | 查询表单数据（**只含主表**）。`--page` 页码（缺省1）、`--size` 每页条数（缺省1000；不传 pageInfo 平台默认卡 10）。平台返回 `datajson.status=false` 时命令报错并打印原始 message，不再显示“共 0 条” |
 | `e10-cli form data detail <objId> <appId> <dataId> [--no-detail]` | 读一条数据详情，**默认连明细一起读**（`--no-detail` 只要主表）。要明细用这条，`list` 不返回明细。详见 `form/guide-form-data.md` |
 | `e10-cli form data update <objId> <appId> <dataId> <json> [--detail-mode cover\|append]` | 按数据 ID 修改（`@` 开头为文件路径）。只需写要改的字段；带明细表名即处理明细，缺省 `cover` **整表覆盖**，`append` 只追加 |
 | `e10-cli form data delete <objId> <dataId>` | 删除一条表单数据 |
@@ -225,6 +227,11 @@
 | `e10-cli form formula-linkage add <appId> <objId> --target <字段> --expression <函数体>` | 新增函数联动。**`--event <事件...>` 可给多个**（一条联动能挂多个触发时机），每个可自带触发字段：`--event changeField:数量,单价 onclick:按钮`；没自带字段的字段级事件回退 `--trigger <字段...>`。默认 `changeField`。`--effect form\|formLayout\|workFlow\|includeNode`（后两者需 `--workflow-id`，`includeNode` 另需 `--node`）、`--name`。表达式**只给右侧**，左侧 `{主表.目标}=` 自动拼。**目标只能是业务字段**，模块字段可作来源/触发。详见 `form/guide-formula-linkage.md` |
 | `e10-cli form formula-linkage update <appId> <objId> <id> [--event...] [--trigger...] [--effect] [--workflow-id] [--node] [--name] [--state on\|off]` | 改触发时机/生效维度/名称/启停。**不给 `--event`/`--trigger` 就原样沿用现有的触发时机**（不会按第一条重建）。生效维度在「表单/布局 ↔ 工作流/节点」之间切换时**必须**同时给 `--event` |
 | `e10-cli form formula-linkage delete <appId> <objId> <ids...>` | 删除（批量）。`form field-linkage delete` 删不掉这类，会报错指路 |
+| `e10-cli form attachment-setting get <appId> <objId> [--field <字段>]` | 读取附件上传设置：不传 `--field` 看通用配置，传了看字段级覆盖。通用配置分上传目录、新建文档存储位置、新建方式、上传格式、大小限制；字段级空项表示继承通用 |
+| `e10-cli form attachment-setting set <appId> <objId> [--upload-dir] [--doc-dir] [--doc-types] [--formats] [--max-size] [--enable] [--display-tip]` | 修改通用配置。`--upload-dir` 附件/图片上传目录，`--doc-dir` 新建文档存储位置，`--doc-types` 新建方式（逗号分隔），`--formats` 上传格式（扩展名逗号串或 `@doc/@image/@video/@audio/@archive` 预设），写 `none` 清空。读—合并—写—回读校验 |
+| `e10-cli form attachment-setting set <appId> <objId> --field <字段> --upload-mode fixed\|option ...` | 修改字段级覆盖：`fixed` 配 `--upload-dir`，`option` 配 `--option-field`；`--doc-dir`/`--doc-types`/`--formats` 同样可用于字段级。字段级未写的项保持继承通用。详见 `form/guide-form-attachment-setting.md` |
+| `e10-cli form attachment-setting folders [--search <关键字>]` | 列出可用文档目录（系统知识库 + 公司/私有知识库）；`--upload-dir` / `--doc-dir` 可写目录 ID，也可写唯一名称或路径 |
+| `e10-cli form attachment-setting doc-types [--folder <目录ID>]` | 列出“新建方式设置”可选的文档类型（html / WORD / markdown / UPLOAD） |
 | `e10-cli form formula set <objId> <appId> --target <fieldId> --expression "<公式>"` | 给 eb 表字段**绑定**计算公式。`{主表.字段}` / `{明细表名.字段}`（平台存储格式）与设计器的 `[字段]` 两种写法都收，保存前归一化成花括号再下发。`--name`、`--return-type`（不传按目标字段类型推断）。**`--formula-id <id>` 原地更新已有公式**（平台认这个字段：不新建、返回 id 不变、字段绑定不受影响），不传才是新建；更新时不传 `--name` 会沿用原公式名，不会被改成「公式_&lt;时间戳&gt;」。另：`formula get <id>` / `list <objId> <appId>` / `functions`。**⚠ 公式语法四条**：函数名必须大写（自定义 JS 脚本函数除外）、逻辑比较用 `==`、给字段赋值用 `=`、跨表粘贴要换掉非本表字段变量 —— 写错**不报错**只是算不对，见 `references/form/guide-form-formula-functions.md` |
 
 > **创建表单流程**：
@@ -609,7 +616,7 @@ e10-cli report py preagg --report-id <id> [--app-id <id>]
 
 | 命令 | 说明 |
 |------|------|
-| `e10-cli check <项目目录>` | 代码质量检查，逐条自检，全部确认通过后再 build |
+| `e10-cli check <项目目录>` | 代码质量检查：递归扫描整个项目（排除 `node_modules/.target`），核对 `build.json` 是否登记全部运行时 JS，并检查 let/const、CSS import、options 短 ID、String(React 节点) 等；通过后再 build |
 
 ---
 

package/skill-docs/references/components/display-FilePreview.md

@@ -36,11 +36,12 @@ export default class FilePreviewDemo extends React.Component {
 
 附件字段（FileComponent）的 `fileid` 可通过以下方式获取：
 
-**1. 从表单数据读取** — `getSimpleData` 对 FileComponent 字段返回 `fieldOptionId`（即 fileid）：
+**1. 从表单数据读取** — `formClient` 的行里，FileComponent 的 `items[字段ID]` 已经给出文件 ID 与名称；`values[字段ID]` 是逗号分隔的文件 ID 串：
 ```js
-var fileId = item[F.attachment];
-// 多文件时为逗号分隔，取第一个
-var firstFileId = (fileId || '').split(',')[0];
+var firstFileId = (row.values[F.attachment] || '').split(',')[0];
+var firstName = row.items[F.attachment] && row.items[F.attachment][0]
+  ? row.items[F.attachment][0].name
+  : '';
 ```
 
 **2. 上传时** — 从 `uploadedFiles` 状态中获取：

package/skill-docs/references/form/guide-field-linkage.md

@@ -134,9 +134,12 @@ e10-cli form field-linkage add <appId> <objId> \
 
 ### 明细行依据（`--basis`）
 
-`明细表名=源表字段名`。决定写入明细表时按哪一列匹配/生成行。不给则取该明细表第一个赋值的源字段；当被赋值的源字段正好是依据值时，设计器里显示为「依据值本身」。
+**不给 = 依据值选「表」**：用查询结果整表作为依据，设计器里显示为源表名（如 `产品清单(uf_clm_inv_content_51)`）；每个赋值都是这张表里的一列（`type=10` + `originValue`）。写明细表通常用这个，也是设计器的默认形态。
+
+只有确实需要按某个字段匹配/合并行时，才显式写 `明细表名=源表字段名`。这时设计器里的依据值是字段；当赋值源字段正好等于依据值时，显示为「依据值本身」。
 
 ```bash
+# 字段级依据（可选，按该字段匹配行）
 --basis "明细表1=测试字段C"
 ```
 

package/skill-docs/references/form/guide-form-attachment-setting.md

@@ -0,0 +1,95 @@
+# 附件上传与关联文档设置指南
+
+表单「附件设置」页控制附件文件存在哪里、能传什么、以及由附件创建文档时落在哪个目录。设置分**通用配置**和**字段级覆盖**两层：字段级未显式覆盖的项继承通用配置。
+
+## 三层对应关系
+
+| 界面 | 通用配置 | 字段级覆盖 |
+|---|---|---|
+| 附件/图片上传目录 | `folderId` + `folderIdBrowserValue` | 同名字段；`folderSelectType` 区分固定目录 / 选项关联 |
+| 关联文档 → 新建方式设置 | `addTypeConfig.types` | `docAddTypeConfig` |
+| 关联文档 → 新建文档存储位置 | `fixedDirectory.folderValue` | `docFixedDirectoryConfig` |
+| 上传格式 | `customLimitFormat` | 同名字段 |
+| 大小限制 / 启用 / 提示语 | `attmentSizeLimit` / `enableState` / `displayTip` | 同名字段 |
+
+两个目录不要混：
+
+- **上传目录**决定附件文件存放位置；为空表示没有落点。
+- **新建文档存储位置**决定由附件创建出来的文档放在哪个知识库目录。
+- 附件"没有进文档"时，先确认**新建方式**和**新建文档存储位置**，再看上传目录；字段级覆盖成"选项关联但没有匹配目录"也会导致附件没有落点。
+
+## 读取
+
+```bash
+# 通用配置 + 字段级覆盖概要
+e10-cli form attachment-setting get <appId> <objId>
+
+# 单个附件字段的覆盖配置
+e10-cli form attachment-setting get <appId> <objId> --field <字段名或fieldId>
+```
+
+## 修改通用配置
+
+```bash
+e10-cli form attachment-setting set <appId> <objId> \
+  --upload-dir <目录ID> \
+  --doc-dir <目录ID> \
+  --doc-types html,WORD,markdown,UPLOAD \
+  --formats @doc,@image,@archive \
+  --max-size 20 \
+  --enable on --display-tip on
+```
+
+| 参数 | 说明 |
+|---|---|
+| `--upload-dir` | 附件/图片上传目录，写文档目录 ID 或唯一名称/路径；`none` 清空 |
+| `--doc-dir` | 新建文档存储位置，写法同上；`none` 清空 |
+| `--doc-types` | 新建方式，逗号分隔；`none` 清空。可选值用 `doc-types` 查询 |
+| `--formats` | 上传格式：扩展名逗号串，或预设 `@doc` / `@image` / `@video` / `@audio` / `@archive`；`none` 清空 |
+| `--max-size` | 单文件大小限制（MB），不能超过平台系统上限 |
+| `--enable` | 启用状态 `on` / `off` |
+| `--display-tip` | 是否显示提示语 `on` / `off` |
+
+只提交显式给出的项：命令先读回现有配置，合并改动后整份保存，再回读比对；未给出的项保持原值。
+
+## 修改字段级覆盖
+
+```bash
+# 固定目录
+e10-cli form attachment-setting set <appId> <objId> \
+  --field <附件字段> --upload-mode fixed --upload-dir <目录ID>
+
+# 选项关联：上传目录跟随某个单选/下拉字段
+e10-cli form attachment-setting set <appId> <objId> \
+  --field <附件字段> --upload-mode option --option-field <选项字段>
+
+# 字段级的新建方式 / 存储位置 / 上传格式
+e10-cli form attachment-setting set <appId> <objId> \
+  --field <附件字段> --doc-dir <目录ID> --doc-types WORD,markdown --formats @image
+```
+
+- `--field` 给了才是字段级覆盖；不给就是通用配置。
+- 固定目录必须同时给 `--upload-dir`；选项关联必须同时给 `--option-field`。
+- 字段级只写给出的项，未给出的项保持继承通用。
+- `--max-size` / `--enable` / `--display-tip` 当前只支持通用配置。
+
+## 查询目录与新建方式
+
+```bash
+# 列出可用文档目录（系统知识库 + 公司/私有知识库）
+e10-cli form attachment-setting folders
+e10-cli form attachment-setting folders --search 合同
+
+# 列出新建方式可选类型
+e10-cli form attachment-setting doc-types
+```
+
+`folders` 输出目录 ID、标题和类型；`--upload-dir` / `--doc-dir` 可以直接写 ID，也可以写唯一名称或路径。名称匹配到多个时命令会报错并要求改用 ID。
+
+## 注意事项
+
+1. **目录 ID 是长数字**，按字符串处理，不要转成 Number。
+2. **读回形状与写入形状不同**：读回的上传目录只在 `folderIdBrowserValue[0]` 里，写报文才带顶层 `folderId`；命令内部会补齐，不要手工拼报文。
+3. **保存顺序**：先字段级列表，再通用配置；两条都成功后再回读校验。
+4. **字段级覆盖优先于通用配置**：字段级把上传目录设成固定目录但没选具体目录，会覆盖掉通用的有效目录。
+5. 命令在保存后会逐项回读；回读不一致会直接报错，不会静默成功。

package/skill-docs/references/form/guide-form-data.md

@@ -1,6 +1,6 @@
 # 表单数据 CLI 操作
 
-通过 CLI 读写表单数据（不需要写页面代码）。JS 编码 API（getSimpleData/saveFormData 等）见 `coding/guide-form-crud.md`。
+通过 CLI 读写表单数据（不需要写页面代码）。页面侧 JS 数据 API（`formClient` 的 list/get/save/update/remove）见 `coding/guide-form-crud.md`。
 
 ## 读数据
 
@@ -40,6 +40,27 @@ data.json 格式（`@` 开头为文件路径）。key 可用 **fieldId（长 ID
 | FileComponent | `"fileid1,fileid2"` |
 
 > **除非用户明确要求，否则不要往表单写入任何数据。** 表单创建完成后只需确认字段正确即可，不要自动插入测试数据。
+>
+> 上表的「选项名 / 数组」是 CLI `form data add` 的转换能力；页面里的 `formClient` 写入仍用选项 ID 和逗号串（数组会被归一化）。两边不要混用写法。
+>
+> Date / DateTime 按字段自身的 `format` 校验，同一张表单可能同时存在 `yyyy-MM-dd`、`yyyy-MM-dd HH:mm`、`yyyy-MM-dd HH:mm:ss`。用 `form read --app-id` 查看 `format`，写完用 `get` 回读比对。
+
+## 附件字段：先上传拿 fileId
+
+`FileComponent` 的值是逗号分隔的 `fileId`，`fileId` 先用上传命令获取：
+
+```bash
+e10-cli form data upload --file <路径> [--file <路径> ...] [--create-doc on|off]
+```
+
+- 默认 `--create-doc on`：上传同时生成文档，输出 `fileId` 与 `docId`
+- `--create-doc off`：只存文件，文档中心不会生成文档 —— 表单里能看到附件，但「文档ID」为空、文档中心查不到
+- 多文件可一次传：`--file a.pdf b.docx`
+- 输出末尾的 `fileIds: id1,id2` 可直接填 `form data add/update` 的附件字段
+
+`Document` 类型字段（文档ID）是关联文档浏览字段，**不需要回填**；附件字段只需要新的 `fileId`。
+
+历史数据只有附件没有文档时，用 `--create-doc on` 重新上传同一文件，再通过 `form data update` 只更新附件字段即可；dataId 和其余字段不变。
 
 ## 读明细：`detail`
 

package/skill-docs/assets/sample/readme.js

@@ -1,8 +0,0 @@
-const routes = [
-  {
-    fileName: "xxx.js",
-    className: "xxx",
-  }
-];
-
-export default routes;