weaver-work-cli 0.1.24 → 0.1.26

package/skills/weaver-e10-builder/references/form/guide-virtual-form.md

@@ -0,0 +1,156 @@
+# 虚拟表创建与维护
+
+虚拟表把已有数据源的字段映射为 EB 表单，用于统一展示 EB 表单、系统业务表或数据加工结果。虚拟表保留来源字段的数据键与类型，布局、视图和菜单继续使用表单现有能力。
+
+## 创建顺序
+
+1. 确定来源类别和数据源。
+2. 校验数据源具有稳定 ID 字段。
+3. 读取来源字段，选择需要展示的字段。
+4. 按来源类型保留字段映射，设置名称、顺序和显示属性。
+5. 创建虚拟表并初始化 FLOW 或 EXCEL 布局。
+6. 按需求配置分组、默认台账、显示列和菜单。
+
+## 数据源类别
+
+| 来源 | `dataSourceType` | `dataSourceGroup` |
+| --- | --- | --- |
+| EB 表单 | `LOGIC` | `weaver-ebuilder-form-service` |
+| 系统业务表 | `LOGIC` | 对应业务服务，如 `weaver-hrm-service` |
+| 数据加工 | `ETEAMS` | 数据集分组 ID |
+
+查询普通逻辑数据源：
+
+```bash
+e10-cli form virtual source-groups --source-type LOGIC
+e10-cli form virtual sources <groupId> --source-type LOGIC --name <名称>
+```
+
+查询数据加工：
+
+```bash
+e10-cli form virtual dataset-groups
+e10-cli form virtual datasets <groupId> --name <名称>
+e10-cli form virtual dataset-info <datasetId>
+```
+
+## 数据源与字段预检
+
+```bash
+e10-cli form virtual fields <appId> \
+  --source-type LOGIC \
+  --source-group weaver-hrm-service \
+  --source-id <数据源ID>
+```
+
+命令先检查来源是否具有稳定 ID，再返回可选字段。每个字段重点保留：
+
+```text
+dataKey
+virtualFieldId
+sourceFieldType
+sourceFieldTitle
+type / componentKey
+```
+
+## 字段选择文件
+
+
+```json
+[
+  "username",
+  {
+    "sourceField": "ACTIVE_DATE",
+    "fieldName": "激活时间",
+    "componentKey": "DateTime",
+    "format": "yyyy-MM-dd HH:mm",
+    "readOnly": true,
+    "singleRow": false
+  }
+]
+```
+
+- 字符串简写按 `dataKey`、`virtualFieldId` 或来源字段名称匹配。
+- 未指定 `componentKey` 时使用平台推荐类型。
+- `fieldName`、`required`、`readOnly`、`hidden`、`singleRow` 用于表单展示。
+- 来源字段标识由 CLI 从接口结果中补齐。
+
+## 类型兼容
+
+| 来源类型 | 默认类型 | 可用的同族展示类型 |
+| --- | --- | --- |
+| `String-普通文本` | `Text` | `Text`、`TextArea` |
+| `Number-数值` | `Number` | `Number`、`Money` |
+| `Date-日期` | `Date` | `Date`、`DateTime` |
+| 选项、人员、部门、关联等复杂字段 | 来源组件 | 保留来源组件类型与配置 |
+
+CLI 在保存前校验类型兼容性。长度、数字精度和日期格式可在同族类型内设置；复杂字段沿用数据源返回的组件结构。
+
+## 创建
+
+系统业务表：
+
+```bash
+e10-cli form virtual create <appId> "人员虚拟表" \
+  --source-type LOGIC \
+  --source-group weaver-hrm-service \
+  --source-id <人员表数据源ID> \
+  --source-name "人员表" \
+  --source-module hrm \
+  --fields @virtual-fields.json \
+  --layout FLOW
+```
+
+EB 表单：
+
+```bash
+e10-cli form virtual create <appId> "项目虚拟表" \
+  --source-type LOGIC \
+  --source-group weaver-ebuilder-form-service \
+  --source-id <来源表单数据源ID> \
+  --source-app-id <来源应用ID> \
+  --fields @virtual-fields.json \
+  --layout FLOW
+```
+
+数据加工：
+
+```bash
+e10-cli form virtual create <appId> "合同加工结果" \
+  --source-type ETEAMS \
+  --source-group <数据集分组ID> \
+  --source-id <数据集ID> \
+  --dataset-type sql \
+  --fields @virtual-fields.json \
+  --layout FLOW
+```
+
+创建结果返回 `objId`、`formId` 和默认视图 ID。来源访问范围随已选择的数据源配置保存，虚拟表命令不单独修改数据源权限。
+
+## 读取与增加字段
+
+```bash
+e10-cli form virtual read <objId> <appId>
+
+e10-cli form virtual add-fields <objId> <appId> <formId> \
+  --source-type LOGIC \
+  --source-group weaver-hrm-service \
+  --source-id <数据源ID> \
+  --fields @add-fields.json
+```
+
+增加字段时重新从原数据源读取当前可选字段，并保留来源映射。字段移除和更换数据源按取得的实际接口配置另行维护。
+
+## 后续配置
+
+虚拟表创建后继续使用现有命令：
+
+- 布局：`form layout read/init/move/set-read-only/set-required`
+- 分组：`form group`
+- 默认台账和显示列：`form list-columns`、`form nlist`
+- 视图：`form view`、`form table-view`
+- 菜单：`menu add-table`
+
+## Plan 记录
+
+虚拟表在表单清单中注明：名称、来源类别、数据源名称或 ID、选用字段、字段映射、布局和视图。执行时依次销号数据源定位、主键校验、字段映射、创建、布局和视图配置。

package/skills/weaver-e10-builder/references/form/ref-form-fields.md

@@ -0,0 +1,293 @@
+# 表单字段类型与配置
+
+本文件维护 EB 表单字段的类型码表、选型规则和通用配置。表单结构、明细表和布局组件的创建方式见 `guide-create-form.md`。
+
+## 通用结构
+
+```json
+{
+  "componentKey": "Text",
+  "fieldName": "项目名称",
+  "dataKey": "xmmc",
+  "columnName": "xmmc",
+  "required": true,
+  "readOnly": false,
+  "hidden": false,
+  "singleRow": false,
+  "group": "基本信息",
+  "defaultValue": ""
+}
+```
+
+| 属性 | 说明 |
+| --- | --- |
+| `componentKey` | 字段类型标识 |
+| `fieldName` | 字段名称 |
+| `dataKey` / `columnName` | 字段编码 / 数据库列名。**两者是两个独立的东西**，可分别指定；都不写则同为字段名拼音首字母，只写 `dataKey` 时列名跟随。建后由 `add-field --data-key/--column-name`、`edit-field --column-name` 调整 |
+| `required` / `readOnly` / `hidden` | 必填、只读、隐藏 |
+| `singleRow` | 独占一行 |
+| `group` | 所属分组 |
+| `multiple` | 是否多选；`false` 为单选，`true` 为多选 |
+| `defaultValue` | 默认值；人员、部门和日期写 `true` 表示动态当前值 |
+
+## 字段类型分类
+
+### 基本类型
+
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 单行文本 | `Text` | `maxLen`，缺省 100 |
+| 多行文本 | `TextArea` | `maxLen`，缺省 4000 |
+| 邮箱 / 电话 / 手机 / 身份证 | `Email` / `Phone` / `Mobile` / `IDCard` | `maxLen`、对应格式校验 |
+| 数字 | `Number` | `precision`、`delimiter`、`percent`、`capital` |
+| 金额 | `Money` | `precision`、`delimiter`、`capital` |
+| 开关 | `Switch` | 开关值 |
+| 附件 | `FileComponent` | 附件上传设置（**没有 `Attachment` 这个类型名**） |
+| 图片 | `Image` | 图片上传设置 |
+| 语音 | `AudioRecord` | 语音录制与上传 |
+| 视频 | `VideoRecord` | 视频录制与上传 |
+
+### 选项类型
+
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 下拉单选 | `Select` | `fieldOptions` 或 `optionTemplate` |
+| 下拉多选 | `SelectMultiple` | `fieldOptions` 或 `optionTemplate` |
+| 单选框 | `RadioBox` | `fieldOptions` 或 `optionTemplate` |
+| 复选框 | `CheckBox` | `fieldOptions` 或 `optionTemplate` |
+| 级联选择 | `Cascade` | 级联选项数据 |
+| 树形选择 | `Tree` | 树形选项数据 |
+| 矩阵选择 | `Matrix` | 矩阵配置 |
+
+### 日期类型
+
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 日期 | `Date` | `format`、`minField`、`maxField`、`defaultValue` |
+| 日期时间 | `DateTime` | `format`、`minField`、`maxField`、`defaultValue` |
+| 日期区间 | `DateRange` / `DateInterval` | `format`、`startPlaceholder`、`endPlaceholder` |
+| 时间 | `Time` | 格式 `HH:mm:ss`；平台组件是 `TimeComponent`（`componentKey` 与类型名不同） |
+
+一个字段名称或业务含义同时包含开始、结束、起止、期间、周期等区间含义时，优先使用日期区间；两个独立字段分别表达起点和终点时，再使用两个日期字段并通过 `minField` / `maxField` 约束。
+
+### 组织类型
+
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 人员选择 | `Employee` | `multiple` |
+| 部门选择 | `Department` | `multiple` |
+| 分部选择 | `SubCompany` | `multiple`（默认单选）；平台读回的组件名为 `Subcompany` |
+| 共享人 | `Sharer` | 共享范围设置 |
+
+创建“分部选择”字段使用原生组织类型 `SubCompany`，例如 `form add-field <objId> <appId> 所属分部 SubCompany`；多选时加 `--multiple`。它与“关联浏览”中选择分部数据源是两种字段配置。
+
+### 关联类型
+
+以下为原生关联对象码表。需求明确指向这些业务对象时，直接使用对应类型。
+
+| 界面名称 | `componentKey` | 平台组件 | 主要配置或说明 |
+| --- | --- | --- | --- |
+| 关联 e-builder | `EBuilder` | `Ebuilder` | `sformId`、`dataTitle`、`displayColumns` |
+| 关联项目 | `Project` | `Mainline` | 项目选择范围 |
+| 关联任务 | `Task` | `Task` | 任务选择范围 |
+| 关联文档 | `Document` | `Document` | 文档选择范围 |
+| 关联流程 | `Flow` | `Workflow` | `target_workflow_form_name`、流程范围 |
+| 关联日程 | `Agenda` | `AgendaComponent` | 日程选择范围 |
+| 关联上报 | `FormData` | `FormComponent` | 上报表单、显示列、条件和数据标题 |
+| 关联客户 | `Customer` | `CustomerComponent` | 客户选择范围 |
+| 关联线索 | `Clue` | `ClueComponent` | 线索选择范围 |
+| 关联联系人 | `Contact` | `ContactComponent` | 联系人选择范围 |
+| 关联商机 | `Chance` | `ChanceComponent` | 商机选择范围 |
+| 关联订单 | `Order` | `OrderComponent` | 订单选择范围；不执行客户编号未填校验 |
+| 关联合同 | `Contract` | `ContractComponent` | 合同选择范围 |
+| 关联产品 | `Product` | `ProductionComponent` | 产品选择范围 |
+| 关联活动 | `Activity` | `ActivityComponent` | 活动选择范围 |
+| 关联报价 | `Quote` | `QuoteComponent` | 报价选择范围 |
+| 关联对手 | `Competitor` | `CompetitorComponent` | 竞争对手选择范围 |
+| 关联绩效 | `Performance` | `KpiFlowComponent` | 绩效选择范围 |
+| 关联报告 | `Report` | `WorkreportComponent` | 报告选择范围 |
+| 关联考勤 | `Attend` | `AttendComponent` | `attendDateType` |
+| 关联浏览 | `Browser` / `RelateBrowser` | `RelateBrowser` | 通过 `browserType` 选择浏览子类 |
+| 电子发票 | `EInvoice` | `EinvoiceComponent` | 发票选择配置 |
+| 行车记录 | `DrivingRecord` | `DrivingRecord` | `defaultRows` |
+| 关联公文 | `RelateODoc` | `RelateODoc` | 公文选择范围 |
+| 关联标签 | `RelateTag` | `RelateTag` | `range` |
+
+#### 关联类型选型
+
+| 需求语义 | 选择 |
+| --- | --- |
+| 关联电子发票 | `EInvoice` |
+| 关联上报数据 | `FormData` |
+| 关联合同业务对象 | `Contract` |
+| 关联某张 EB 表单，如“合同信息表” | `EBuilder` |
+| 关联人事合同 | `RelateBrowser`，`browserType: "hrcontract"` |
+| 关联流程数据 | `Flow` |
+| 浏览工作流定义 | `RelateBrowser`，`browserType: "workflow"` |
+| 关联业务表单或 EB 表单数据 | `RelateBrowser`，`browserType: "form"` |
+
+`FormData` 表示“关联上报”，与通用关联浏览中的表单浏览不是同一配置。`EBuilder` 用于关联明确的 EB 表单；`RelateBrowser + form` 用于通用表单浏览。
+
+#### 关联 e-builder
+
+```json
+{
+  "fieldName": "关联客户",
+  "componentKey": "EBuilder",
+  "target_form_name": "客户信息表",
+  "dataTitle": "客户名称",
+  "displayColumns": ["客户名称", "客户编号"],
+  "multiple": false
+}
+```
+
+- `sformId` 可直接指定目标表单 ID；按需求编排时也可使用 `target_form_name`，执行阶段解析为目标表单。
+- `dataTitle` 指定已选数据的标题字段。
+- `displayColumns` 指定选择窗口显示列；省略时使用目标表单的业务字段。
+- `multiple: false` 对应单选，`multiple: true` 对应多选。
+
+字段带出使用 `relateFrom`：
+
+```json
+{
+  "fieldName": "客户名称",
+  "componentKey": "Text",
+  "relateFrom": {
+    "ebuilderField": "关联客户",
+    "sourceFieldId": "目标表单字段ID"
+  }
+}
+```
+
+`sourceFieldId` 使用目标表单字段的数字 ID。
+
+#### 通用关联浏览子类
+
+| `browserType` | 作用 | 主要配置 |
+| --- | --- | --- |
+| `workflow` | 浏览工作流定义 | 工作流范围 |
+| `hrcontract` | 浏览人事合同 | 人事合同范围 |
+| `form` | 浏览业务表单或 EB 表单数据 | `browserFormSource`、目标表单、标题和显示列 |
+| `role` | 浏览角色 | 角色范围 |
+| `archive` | 浏览档案 | 档案范围 |
+| `hrm_sex` | 浏览人事「性别」 | — |
+| `hrmJobcall` | 浏览人事「职称」 | — |
+
+已明确的专属参数包括考勤 `attendDateType`、行车记录 `defaultRows`、标签 `range`。参数值按实际需求或接口返回配置。
+
+业务表单浏览：
+
+```json
+{
+  "fieldName": "关联业务数据",
+  "componentKey": "RelateBrowser",
+  "browserType": "form",
+  "browserFormSource": "business",
+  "target_form_name": "业务表单",
+  "multiple": false
+}
+```
+
+EB 表单浏览：
+
+```json
+{
+  "fieldName": "关联EB数据",
+  "componentKey": "RelateBrowser",
+  "browserType": "form",
+  "browserFormSource": "ebuilder",
+  "target_form_name": "客户信息表",
+  "multiple": true
+}
+```
+
+### 行政区域
+
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 行政区域 / 城市选择 | `City` | 区域层级与选择范围 |
+
+### 其他
+
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 进度 | `Progress` | 进度值范围 |
+| 评分 | `Score` | 评分范围 |
+| 签名 | `Signature` | 签名设置 |
+| 定位 | `Location` | 位置信息；用于支持该组件的布局 |
+| 颜色选择 | `ColorPicker` | 颜色值 |
+| 富文本 | `RichText` | 富文本内容 |
+| 文档目录 | `DocFolder` / `DocFloder` | 文档目录选择 |
+
+## 文本、数字和日期配置
+
+```json
+[
+  {"fieldName": "标题", "componentKey": "Text", "maxLen": 100},
+  {"fieldName": "说明", "componentKey": "TextArea", "maxLen": 4000},
+  {"fieldName": "数量", "componentKey": "Number", "precision": 0},
+  {"fieldName": "金额", "componentKey": "Money", "precision": 2, "delimiter": true},
+  {"fieldName": "完成比例", "componentKey": "Number", "precision": 2, "percent": true},
+  {"fieldName": "开始日期", "componentKey": "Date"},
+  {"fieldName": "结束日期", "componentKey": "Date", "minField": "开始日期"},
+  {"fieldName": "创建日期", "componentKey": "Date", "defaultValue": true}
+]
+```
+
+- 百分比字段按 0–100 的显示语义设计，公式按实际业务口径编写。
+- `Number` 缺省精度为 0；`Money` 缺省精度为 2。
+- `minField` / `maxField` 用于两个独立日期字段的先后约束。
+- 日期字段的 `defaultValue: true` 表示默认当前日期。
+
+## 选项、默认值与多选
+
+```json
+{
+  "fieldName": "项目状态",
+  "componentKey": "Select",
+  "fieldOptions": [
+    {"name": "审批"},
+    {"name": "立项"},
+    {"name": "执行"},
+    {"name": "结案"}
+  ]
+}
+```
+
+- `valueKey` 可省略，由 CLI 生成；手工指定时使用稳定的数字字符串。
+- 公共选项模板使用 `optionTemplate`；`fieldOptions` 与 `optionTemplate` 二选一。
+- `multiple: false` 保存为单选（`isSingle: true`），`multiple: true` 保存为多选（`isSingle: false`）。
+- `Select` 开启多选后使用 `SelectMultiple`。
+
+```json
+{
+  "fieldName": "重要程度",
+  "componentKey": "Select",
+  "optionTemplate": "重要程度"
+}
+```
+
+## 公式
+
+```json
+{
+  "fieldName": "项目收益",
+  "componentKey": "Number",
+  "precision": 2,
+  "readOnly": true,
+  "formula": "{主表.项目已收款}-({主表.项目工时}*100+{主表.项目费用})"
+}
+```
+
+- 公式字段通常设为只读。
+- 主表字段使用 `{主表.字段名}`，明细字段按对应表和字段引用。
+- 公式对象还可包含 `expression`、`returnType` 和 `name`。
+- 公式、联动和校验在字段与布局初始化后使用各自命令配置。
+
+## 相关文档
+
+- 表单创建与主表、明细表结构：`guide-create-form.md`
+- 布局：`guide-form-layout.md`
+- 字段事件：`guide-field-event.md`
+- 字段公式函数：`guide-form-formula-functions.md`
+- CLI 命令：`../common/ref-cli-commands.md`

package/skills/weaver-e10-builder/references/form/style-templates.md

@@ -0,0 +1,97 @@
+# 表单布局样式模板
+
+`form layout init --style-template <名|id>` 用这些模板初始化布局。
+
+## ⚠ 流式和表格式是**两套独立模板**，不能混用
+
+同一个名字在两套里往往是**不同的 id**（紧凑版 / 轻便版 / 碧海蓝天 / 极简白 / 极简淡蓝 /
+清新蓝绿 / 商务蓝 / 淡雅丁香 两套都有），而且各自还有对方没有的模板。所以**解析模板名必须
+先知道表单的布局类型**。
+
+| 表单布局 | 接口 | 内置模板数 |
+|---|---|---|
+| 流式 `FLOW` | `/api/form/flow/template/list` | 24（本环境另有若干用户导入的） |
+| 表格式 `EXCEL` | `/api/form/form/layout/template/listTemplateAdvancedByPage` | 20 |
+
+**拿错一套不会报错**——平台收到一个不属于该布局类型的 id，直接忽略；命令照常打印"已初始化"，
+样式却纹丝不动。这是最容易踩的坑：改了没效果，还以为模板名写错了。
+
+CLI 已按布局类型自动选接口并校验：传了不属于当前布局那一套的名字或 id 会直接报错，并列出该
+布局类型下可用的模板。
+
+## 用法
+
+```bash
+# 按名字（按当前表单的布局类型实时解析，推荐）
+e10-cli form layout init <objId> <appId> --style-template 碧空如洗
+
+# 按 id（同样会校验它属于当前布局那一套）
+e10-cli form layout init <objId> <appId> --style-template 830000000000000022
+
+# 不传则用该布局类型的缺省模板：流式=标准版、表格式=表格版
+e10-cli form layout init <objId> <appId>
+
+# 指定视图 + 只读/必填
+e10-cli form layout init <objId> <appId> --view-id <viewId> --style-template 紧凑版 --read-only
+```
+
+## 内置模板
+
+> 模板列表**按租户动态**（用户可以自行导入模板，本环境流式那套就多出十几个带「(导入)」的
+> 副本），**以命令输出为准**；下表是验证环境的内置项，供参考。
+
+### 流式（FLOW）
+
+| styleTemplateId | 模板名 |
+|---|---|
+| `820000000000000001` | 标准版（**缺省**） |
+| `820000000000000002` | 标准版（无表头） |
+| `820000000000000011` | 表格版 |
+| `810000000001000004` | 轻量设置版 |
+| `810000000001000001` / `002` / `003` | 分区卡片版 1 / 2 / 3 |
+| `830000000000000010` | 紧凑版 |
+| `830000000000000011` | 轻便版 |
+| `830000000000000012` | word版 |
+| `830000000000000015` / `016` / `017` | 轻量紫 / 轻量白 / 轻量蓝 |
+| `830000000000000018` | 简约瀑布流 |
+| `830000000000000019` | 半透蒙版 |
+| `830000000000000021` | 碧海蓝天 |
+| `830000000000000022` | 碧空如洗 |
+| `830000000000000023` | 淡雅丁香 |
+| `830000000000000024` | 极简白 |
+| `830000000000000025` | 极简淡蓝 |
+| `830000000000000026` | 简洁现代 |
+| `830000000000000027` | 清新蓝绿 |
+| `830000000000000028` | 深蓝商务 |
+| `830000000000000029` | 商务蓝 |
+
+### 表格式（EXCEL）
+
+| styleTemplateId | 模板名 |
+|---|---|
+| `700000000000000007` | 标准版 |
+| `700000000000000008` | 表格版（**缺省**，生成的 comps 默认只读） |
+| `700000000000000009` | 紧凑版 |
+| `700000000000000010` | 轻便版 |
+| `830421425497325568` | 靛青线条 |
+| `830662158415355904` | 简约深蓝 |
+| `830714355284320256` | 极简淡蓝 |
+| `830718787623460864` | 现代简约 |
+| `830722618751066113` | 商务淡蓝 |
+| `830743788745531393` | 极简白 |
+| `830749075757998081` | 极简灰 |
+| `830751622581329920` | 清新蓝绿 |
+| `830764108161785857` | 淡蓝水晶 |
+| `830765800429674496` | 银光浅灰 |
+| `831747419499700225` | 暗夜流光 |
+| `831759140499447809` | 公文样式 |
+| `831897833480421377` | 淡雅丁香 |
+| `917557790734188546` | 商务蓝 |
+| `933871446777094145` | 碧海蓝天 |
+| `1000599952745676801` | 青蓝冰水 |
+
+## 注意
+
+- 模板只影响**布局样式**（间距/边框/配色），不影响字段的 readOnly/required（这俩由 `--read-only`/`--required` 或 fields.json 控制）。
+- `表格版`（EXCEL 008）历史问题：生成的 comps 默认 readOnly=true。`form layout init` 会显式按 `--read-only`（默认 false 可编辑）覆盖，所以即使用 008 也能可编辑。
+- 建表（`form create`）时**不能**指定样式模板，只能建完再 `form layout init --style-template` 换。