# CloudCC 字段开发指南 ## 1. 模块定位 `fields` 模块用于管理 CloudCC 对象字段，当前提供字段列表查询、字段详情、创建、更新、删除能力。 可通过以下命令读取文档： ```bash cloudcc doc fields introduction cloudcc doc fields devguide ``` --- ## 2. 当前支持的命令 ```bash cloudcc get fields cloudcc detail fields cloudcc create fields [extraArg] cloudcc update fields [extraArg] cloudcc delete fields ``` 说明： - `projectPath`：本地项目路径，用于读取 `cloudcc-cli.config.js` - `objPrefix`：对象前缀，用于查询字段 - `fieldType`：字段类型编码（例如 `S`、`N`、`D` 等） - `objid`：对象 ID - `fieldLabel`：字段显示名称 - `extraArg`：部分字段类型需要的额外参数，如 `ptext` 或 `lookupObj` - `remark`：用于描述字段的业务功能（写入字段模板的 `obj.remark`，位置固定为 `argvs[6]`） - `fieldId`：字段 ID（`update` / `delete` 必填；可通过 `get fields` 返回的 `id` 获取） 说明： - 当前 CLI 参数以 `src/fields/buildFieldData.js`、`src/fields/create.js`、`src/fields/update.js`、`src/fields/get.js`、`src/fields/delete.js` 的实际实现为准 - 字段 API 名称在当前创建逻辑中默认由 CLI 自动生成，不要求单独传入 --- ## 3. 查询字段详情（detail） 用于拉取与平台「字段编辑」页一致的数据（简档列表、对象列表、`fieldObj` 等），对应接口 **`POST /api/fieldSetup/editField`**。 ### 3.1 基本命令 ```bash cloudcc detail fields ``` - `fieldId`：字段 ID（与 `get fields` 返回的 `id` 一致） - `fdtype`：字段类型编码（例如 `P`、`S`、`U`，与 `fdtype` / `schemefieldType` 一致） - `objid`：所属对象 ID 请求体示例： ```json { "fieldId": "ffe2026A3B035C748w95", "fdtype": "P", "objid": "2026BEECB242636G72cD" } ``` 成功时 CLI 将打印接口返回的 JSON（含 `result`、`data` 等，具体结构以平台为准）。 --- ## 4. 查询字段列表（get） ### 4.1 基本命令 ```bash cloudcc get fields ``` 入参： - `objPrefix`：对象前缀 返回结果包含： - `obj`：对象基础信息 - `stdFields`：标准字段列表 - `cusFields`：自定义字段列表 每个字段通常包含： - `fieldname`：字段显示名称 - `apiname`：字段 API 名称 - `schemefieldType`：字段类型编码 - `id`：字段 ID --- ## 5. 创建字段 ### 5.1 基本命令 ```bash cloudcc create fields [extraArg] ``` #### 公用参数（所有字段类型通用） - `projectPath`：本地项目路径 - `fieldType`：字段类型编码（例如 `S`、`U`、`L`、`Y` 等） - `objid`：对象 ID - `fieldLabel`：字段显示名称 - `remark`：字段业务功能描述（写入字段模板的 `obj.remark`；参数位置固定为 `argvs[6]`） - `helps`：帮助说明，固定`argvs[7]` - `defaultValue`：默认值，固定`argvs[8]` - `extraArg`：仅部分字段类型需要的额外入参；其含义与参数位置随 `fieldType` 变化（通常从 `argvs[9]` 开始） #### 字段特殊入参（按 `fieldType`） 以下均假定 **`create fields`** 的 argv 下标（**`update fields`** 因多一个 `fieldId`，`remark` 及之后的参数整体 **`+1`**，见 [5.2](#52-更新字段)）。 **约定**：**`helps`**、**`defaultValue`** 见上文公用参数（**`argvs[7]`**、**`argvs[8]`**）；本节只写各类型在 **`argvs[9]`** 起的**专属参数**。若不需要默认值，**`argvs[8]`** 仍请传 **`''`** 占位，避免与专属参数错位。 - `S`（文本） - `schemefieldLength`（可选）：字段长度；**`argvs[9]`**；不传默认 `255` - `isrepeat`（可选）：是否允许重复值；**`argvs[10]`**；`true` / `false`；不传默认 `true` - `placeholder`（可选）：输入框提示文案（`obj.placeholder`）；**`argvs[11]`**（与「空字符串占位」含义不同） - `casesensitive`（可选）：是否区分大小写；**`argvs[12]`**；仅当 `isrepeat=false` 时生效；空则默认 `false` - **空字符串占位**：**`argvs[9]`～`argvs[12]`** 顺序固定；若要向更后面的槽位传值，中间未用槽位须 **`''`** - `U`（URL） - `edittype`（可选）：链接打开方式，`_blank` 或 `_self`；**`argvs[9]`**；不传默认 `_blank`；非 `_self` 按实现回退为 `_blank` - `P`（百分比） - `schemefieldLength`（可选）：小数点**左侧**（整数部分）位数；**`argvs[9]`**；不传默认 `10` - `decimalPlaces`（可选）：小数点**右侧**位数；**`argvs[10]`**；不传默认 `2` - **约束**：两者须为非负整数，且**之和不能大于 18** - `C`（币种） - 专属参数与 **`P`** 相同（**`argvs[9]`**、**`argvs[10]`**），约束相同 - `N`（数字） - `schemefieldLength`（可选）：小数点**左侧**（整数部分）位数；**`argvs[9]`**；不传默认 `10` - `decimalPlaces`（可选）：小数点**右侧**位数；**`argvs[10]`**；不传默认 `0` - `isrepeat`（可选）：是否允许重复值；**`argvs[11]`**；`true` / `false`；不传默认 `true`（允许重复） - `displayThousands`（可选）：平台字段 **`obj.displayThousands`**；**`argvs[12]`**；**`"1"`** 表示不允许重复，**`"0"`** 表示允许重复；不传默认 **`"0"`** - **约束**：`schemefieldLength` 与 `decimalPlaces` 须为非负整数，且**之和不能大于 18**（与 `P`/`C` 精度规则一致） - `IMG`（图片） - **`defaultValue`**（**`argvs[8]`**）：**可上传图片数量**（写入 `obj.defaultValue`）；须为 **1～100** 的整数；空则默认 **`3`** - **`formulaType`**（可选）：录入方式 **`url`** 或 **`input`**（顶层 `formulaType`）；**`argvs[9]`**；不传默认 **`input`** - **`watermarkstatus`**（可选）：是否支持水印拍照；**`argvs[10]`**；**`"0"`** 不支持，**`"1"`** 支持；不传默认 **`"0"`** - `FL`（文件） - **`defaultValue`**（**`argvs[8]`**）：**可上传文件数量**（须为 **1～100** 的整数；写入 **`obj.defaultValue`**，并与 **`obj.isrepeat`** 设为**同一数值**）；空则默认 **`1`** - `ENC`（加密文本-存储加密）、`ENCD`（加密文本-显示加密） - 二者共用下列参数（**`argvs[9]`**～**`argvs[12]`**）： - **`schemefieldLength`**（可选）：文本最大长度，写入 **`obj.schemefieldLength`**；**`argvs[9]`**；须为 **1～255** 的整数；不传默认 **`255`** - **`masktype`**（可选）：掩码类型；**`argvs[10]`**；**`all`** 掩码全部；**`4`** 掩码后四位；**`card`** 卡号格式；**`custom`** 自定义；不传默认 **`all`** - **`encrypttype`**（可选）：**`masktype`=`custom`** 时生效，自定义掩码规则；**`argvs[11]`**；参考 **`"{AAAA}{****}{AAAA}"`**；空则使用默认示例串 - **`maskcharacter`**（可选）：掩码字符；**`argvs[12]`**；**`*`** 或 **`X`**；不传默认 **`*`** - `LT`（地理定位） - **`schemefieldLength`**（可选）：小数点**左侧**位数，写入 **`obj.schemefieldLength`**；**`argvs[9]`**；须为非负整数；不传默认 **`8`**（与默认 **`decimalPlaces`** 之和为 **18**，满足平台总位数上限） - **`decimalPlaces`**（可选）：小数点**右侧**位数，写入 **`obj.decimalPlaces`**；**`argvs[10]`**；须为非负整数；不传默认 **`10`** - **约束**：两者须为非负整数，且**之和不能大于 18**（与 **`P`** / **`C`** / **`N`** 精度规则一致） - **`displayType`**（可选）：纬度与经度显示方式；**`argvs[11]`**；**`"1"`** 数字展示，**`"2"`** 度、分、秒；不传默认 **`"1"`**（写入顶层 **`displayType`**） - **仅公用 `helps` / `defaultValue`、无 `argvs[9]` 起专属参数的类型**：`D`、`F`、`T`、`H`、`A`、`AD` 等（**不含** **`IMG`** / **`FL`** / **`ENC`** / **`ENCD`** / **`LT`** 等已单列的类型；见上文各节） - `J`（文本区-长） - 与 **`X`** 类似：多行文本；**`schemefieldLength`**（可选）为**最大字符数**；**`argvs[9]`**；须为 **1～32000** 的整数；不传默认 **`32000`** - **`placeholder`**（可选）：输入区**提示信息**；**`argvs[10]`** - **平台说明**：每个对象**最多 10 个** **`J`** 类型字段；条数由平台校验，**CLI 创建时不统计**，请在对象上自行控制数量 - `X`（文本区） - `schemefieldLength`（可选）：多行文本**最大字符数**；**`argvs[9]`**；须为 **1～4000** 的整数；不传默认 **`4000`**（与平台常见上限一致） - `placeholder`（可选）：输入区**提示信息**；**`argvs[10]`** - `SCORE`（评分） - `schemefieldLength`（可选）：**最大评分**，决定**星星图标显示个数**；**`argvs[9]`**；须为 **1～100** 的整数；不传默认 **`10`** - `E`（电子邮件） - `isrepeat`（可选）：是否允许重复；**`argvs[9]`**；**`"true"`** 允许重复，**`"false"`** 不允许重复；不传默认 **`"true"`** - `B`（复选框） - **`defaultValue`**（**`argvs[8]`**）：**仅** **`"0"`** 或 **`"1"`** —— **`"0"`** 表示默认**未选中**，**`"1"`** 表示默认**选中**；空或其它值按 **`"0"`** 处理 - `L`（选项列表-单选） - `ptext`（**`useGlobalSelect`=`"0"` 时必填**）：选项内容；**`argvs[9]`**；**格式**：多个选项用 **`\r\n`** 连接（勿用仅 `\n` 作为分隔）。**`useGlobalSelect`=`"1"`**（全局列表）时可为空字符串 - **`useGlobalSelect`**（可选）：是否使用全局选项列表；**`argvs[10]`**；**`"0"`** 不使用，**`"1"`** 使用；不传默认 **`"0"`** - **`edittype`**（可选）：选择样式，写入 **`obj.edittype`**；**`argvs[11]`**；**`radio`** 单选框列表，**`select`** 单选下拉；不传默认 **`select`** - **`isPicklistSorted`**（可选）：按字母顺序而非输入顺序排序；**`argvs[12]`**；**`"0"`** 否，**`"1"`** 是；不传默认 **`"0"`** - **`defPl`**（可选）：将第一个值作为默认值；**`argvs[13]`**；**`"0"`** 否，**`"1"`** 是；不传默认 **`"0"`** - **`globalSelectId`**：全局选项列表 id；**`argvs[14]`**。**`useGlobalSelect`=`"1"`** 时必填；为 **`"0"`** 时传 **`''`** 占位即可 - `Q`（选项列表-多选） - 与 **`L`** 相同的前缀参数：**`ptext`**、**`useGlobalSelect`**、**`edittype`**、**`isPicklistSorted`**、**`defPl`**、**`globalSelectId`**（**`argvs[9]`**～**`argvs[14]`**），含义与取值规则见上文 **「L（选项列表-单选）」**（**`useGlobalSelect`=`"0"`** 时 **`ptext`** 必填；**`"1"`** 时 **`globalSelectId`** 必填） - **`visibleLines`**（可选）：下拉最多展示几行选项，写入 **`obj.visibleLines`**；**`argvs[15]`**；须为 **1～100** 的整数；不传默认 **`4`** - **`showalloptions`**（可选）：是否显示所有选项，写入 **`obj.showalloptions`**；**`argvs[16]`**；**`"0"`** 否，**`"1"`** 是；不传默认 **`"0"`** - `Y`（查找关系） - `lookupObj`（必填）：关联对象；**`argvs[9]`** - **`lookupObjDefaultField`**（可选）：搜索辅助字段，写入 **`obj.lookupObjDefaultField`**；搜索时用于展示（如关联对象上用于显示的字段 API 名）；**`argvs[10]`**；不传或空字符串表示不指定 - `MR`（查找多选） - `lookupObj`（必填）：关联对象；**`argvs[9]`** - `M`（主详信息关系） - `lookupObj`（必填）：关联对象；**`argvs[9]`** ### 5.2 更新字段 更新时必须在请求体中设置 **`obj.id`** 为平台上的字段 ID，且 **不会** 自动绑定页面布局（不写入 `layoutIds`）。 ```bash cloudcc update fields [extraArg] ``` - `fieldId`：平台字段 ID（`argvs[3]`），对应保存时的 `fieldData.obj.id` - 其余参数与 `create fields` 含义相同，但整体下标相对 **create** 后移一位：`fieldType` 为 `argvs[4]`，`objid` 为 `argvs[5]`，`fieldLabel` 为 `argvs[6]`，`remark` 为 `argvs[7]`；**`helps`** 为 **`argvs[8]`**、**`defaultValue`** 为 **`argvs[9]`**；各类型专属参数在 **create** 中为 **`argvs[9]`** 起，在 **update** 中为 **`argvs[10]`** 起（相对 **create** 一律 **`+1`**） ### 5.3 支持的字段类型说明 根据 CloudCC 官方关于“对象-字段”的说明，平台层面支持文本、URL、百分比、币种、数字、文本区、长文本、富文本、电话、电子邮件、日期、日期/时间、评分、选项列表、图片、查找关系、主详信息关系、公式、自动编号、累计汇总、查找多选、复选框等类型。 当前 `src/fields/fields` 中已实现的 CLI 字段类型如下。 **说明**：下列类型在模板 **`obj`** 中带有固定的 **`schemefieldLength`** 默认值（与平台「最大长度」类属性对齐；未通过 CLI 覆盖时使用）：**`U`** `2000`，**`D`** / **`T`** `20`，**`F`** `30`，**`B`** `10`，**`H`** `15`，**`E`** `254`，**`IMG`** `255`，**`AD`** `500`；**`S`**、**`N`**、**`P`**、**`C`**、**`X`**、**`J`**、**`SCORE`** 等仍由各自字段逻辑或上文「字段特殊入参」定义。 #### 基础输入类 | CLI 类型编码 | 类型名称 | 说明 | | --- | --- | --- | | `S` | 文本 | 单行文本，默认长度 255（可通过 `schemefieldLength` 调整） | | `U` | URL | 输入有效网址，点击后可打开链接 | | `P` | 百分比 | 输入百分比数字；可通过 `schemefieldLength` / `decimalPlaces` 配置整数位与小数位 | | `C` | 币种 | 金额/币种场景，模板内部 `fdtype` 为 `c`；可通过 `schemefieldLength` / `decimalPlaces` 配置整数位与小数位（与 `P` 参数位一致） | | `N` | 数字 | 输入数值，适用于数量、金额基数等 | | `D` | 日期 | 仅日期 | | `T` | 时间 | 仅时间 | | `F` | 日期/时间 | 日期和时间组合 | | `B` | 复选框 | 默认值仅 `"0"` / `"1"`（未选中 / 选中），见上文 **「B（复选框）」** 专属说明 | | `H` | 电话 | 电话号码 | | `E` | 电子邮件 | 邮箱地址；可选 `isrepeat`（`argvs[9]`），见上文 **「E（电子邮件）」** | | `SCORE` | 评分 | 最大评分 1～100（`schemefieldLength`，星星个数），见 **「SCORE（评分）」** | #### 文本区与内容类 | CLI 类型编码 | 类型名称 | 说明 | | --- | --- | --- | | `X` | 文本区 | 多行文本，最多 4000 字符（`schemefieldLength`），见 **「X（文本区）」** | | `J` | 文本区（长） | 多行长文本，最多 32000 字符；每对象最多 10 个 `J` 字段（平台限制），见 **「J（文本区-长）」** | | `A` | 文本区（富文本） | 支持富文本内容、图文描述 | | `IMG` | 图片 | 上传数量见 **`defaultValue`**（`argvs[8]`），可选 **`formulaType`** / **`watermarkstatus`**（`argvs[9]` / `argvs[10]`），见上文 **「IMG（图片）」** | | `FL` | 文件 | 可上传文件数量见 **`defaultValue`**（`argvs[8]`），与 **`isrepeat`** 同步为同一数值，见上文 **「FL（文件）」** | #### 选择类 | CLI 类型编码 | 类型名称 | 说明 | | --- | --- | --- | | `L` | 选项列表 | 单选；**`ptext`** / **`useGlobalSelect`** / **`edittype`**（radio·select）等见上文 **「L（选项列表-单选）」** | | `Q` | 选项列表（多选） | 与 **`L`** 类似的全局/排序等 + **`visibleLines`** / **`showalloptions`**，见 **「Q（选项列表-多选）」** | **`L`**、**`Q`** 在 **`ptext`** 之后还可带可选参数：**`L`** 为 **`argvs[10..14]`**；**`Q`** 为 **`argvs[10..16]`**（在 **`L`** 的基础上多 **`visibleLines`**、**`showalloptions`**），详见上文 **「L」** / **「Q」** 小节。 ```bash cloudcc create fields L [helps] [defaultValue] [useGlobalSelect] [edittype] [isPicklistSorted] [defPl] [globalSelectId] cloudcc create fields Q [helps] [defaultValue] [useGlobalSelect] [edittype] [isPicklistSorted] [defPl] [globalSelectId] [visibleLines] [showalloptions] ``` 其中 **`helps`**、**`defaultValue`** 在 **`argvs[7]`**、**`argvs[8]`**，**`ptext`** 在 **`argvs[9]`**（若不需要帮助或默认值，可用 **`''`** 占位）。**`L` / `Q`** 在 **`useGlobalSelect`=`"0"`** 时 **`ptext`** 必填；**`useGlobalSelect`=`"1"`** 时 **`ptext`** 可为 **`''`**，但 **`globalSelectId`**（**`argvs[14]`**）必填。**`L` / `Q` 的 `ptext` 格式要求**（本地列表）：多个选项之间必须使用 **`\r\n`（CRLF）** 换行连接，逻辑上等价于字符串 `"a\r\nb\r\nc"`（一行一个选项）。在 Shell 中可用 `$'a\r\nb\r\nc'` 等形式传入真实回车换行序列。若要向 **`argvs[10]`**（**`L`/`Q`** 专属参数）及之后某槽位传值而保留更前面槽位的默认，中间未用的槽位须用 **`''`** 占位（与 **`S`** 等类型相同约定）。 平台层面的选项列表能力常用于： - 状态 - 阶段 - 分类 - 来源 - 优先级 #### 关系类 | CLI 类型编码 | 类型名称 | 说明 | | --- | --- | --- | | `Y` | 查找关系 | 关联另一个对象；可选 **`lookupObjDefaultField`**（`argvs[10]`），见 **「Y（查找关系）」** | | `MR` | 查找多选 | 多选关联对象 | | `M` | 主详信息关系 | 主从/主详关系字段 | 这三类字段创建时都需要额外传入目标对象参数： ```bash cloudcc create fields Y [helps] [defaultValue] [lookupObjDefaultField] cloudcc create fields MR [helps] [defaultValue] cloudcc create fields M [helps] [defaultValue] ``` 其中 **`helps`**、**`defaultValue`** 在 **`argvs[7]`**、**`argvs[8]`**，**`lookupObj`** 在 **`argvs[9]`**。`lookupObj` 表示被关联对象。**仅 `Y`** 还可选 **`lookupObjDefaultField`**（**`argvs[10]`**；不需要时可传 **`''`**）。 这类字段常用于： - 客户与联系人的关联 - 项目与客户的关联 - 主记录与明细记录的主详结构 - 多对象之间的一对多或多对多表达 #### 地址与定位类 | CLI 类型编码 | 类型名称 | 说明 | | --- | --- | --- | | `AD` | 地址 | 地址复合字段 | | `LT` | 地理定位 | **`schemefieldLength`** / **`decimalPlaces`** / **`displayType`**（`argvs[9..11]`），见 **「LT」** | #### 安全与加密类 | CLI 类型编码 | 类型名称 | 说明 | | --- | --- | --- | | `ENC` | 加密文本（存储加密） | 与 **`ENCD`** 相同的 **`argvs[9..12]`**（长度·掩码），见 **「ENC / ENCD」** | | `ENCD` | 加密文本（显示加密） | 与 **`ENC`** 相同的 **`argvs[9..12]`**，见 **「ENC / ENCD」** | 说明： - CLI 中使用的类型编码是 `ENC`、`ENCD` - 模板内部提交到接口时，对应的 `fdtype` 分别是 `enc`、`encd` - `C` 在模板内部对应的 `fdtype` 为小写 `c` - 这两类字段更适合身份证号、银行卡号、敏感联系方式等场景 ### 5.4 当前 CLI 未覆盖但平台支持的字段能力 根据官方文档，平台层面还支持以下字段能力，但当前 `src/fields/fields` 目录下尚未看到对应 CLI 创建模板： - 公式 - 自动编号 - 累计汇总 如果后续希望通过 CLI 直接创建这些字段类型，需要继续补充对应的模板实现。 --- ## 6. 删除字段 ### 6.1 基本命令 ```bash cloudcc delete fields ``` 删除前建议： - 先确认字段未被页面、公式、触发器、类或脚本依赖 - 先记录字段 API 名称与 ID，防止误删 - 在测试环境验证后再在正式环境执行 --- ## 7. 开发前检查 - 已完成 `cloudcc doc project devguide` 中的环境准备 - 项目根目录存在可用的 `cloudcc-cli.config.js` - 当前环境密钥配置正确 - 已确认对象 API 名称、字段类型和命名规则 --- ## 8. 常见实践建议 - 优先先做对象建模，再补字段明细，避免频繁返工 - 字段命名规范化（显示名称清晰、API 名称可维护） - 对核心字段（金额、状态、日期）提前统一格式约定 - 删除字段前先做依赖排查，确保不影响线上逻辑