跳到主要内容

字段清单与自定义字段

物料、客户、商机、项目、供应商、销售合同等业务支持租户在主站自行配置字段—— 既能调整系统字段的显示与必填，也能新增自定义字段。这些配置每个租户各不相同， 静态文档无从表达，需要在运行时查询。

system.field.list 就是这个查询入口，一个接口能回答三件事：

  • 某业务有哪些字段，包括租户自建的
  • 哪些字段被配置为必填
  • 高级筛选可以用哪些字段名

调用​

curl -X POST https://open.risemap.cn/v1/api/invoke \
  -H "X-App-Key: <appKey>" \
  -H "X-App-Secret: <appSecret>" \
  -H "Content-Type: application/json" \
  -d '{ "apiCode": "system.field.list", "query": { "label": "customer" } }'

label 是业务标识，取 customer / product / opportunity / supplier / project / sales_contract 等；具体可用值以接口返回为准。所需范围 system:read。

返回一条字段的形态：

{
  "id": "2092601027944525825",
  "label": "customer",
  "fieldScope": "form",
  "fieldName": "field_ogwkl4",
  "name": "测试---单行文本",
  "type": 1,
  "fieldType": 0,
  "isNull": 0,
  "isSystem": 0,
  "options": null,
  "maxLength": null
}

三个容易读错的字段​

isNull —— 0 才是必填​

字面是「是否可为空」，所以取值与直觉相反：

取值含义
0必填
1选填

判断必填请写 isNull === 0，主站前端表单也是这么判的。

fieldScope —— 同一字段会出现多次​

同一个字段可能同时配置在表单（form）与详情（detail）两个场景下， 因此按 fieldName 去重前会看到重复项。要取表单的必填配置， 应先按 fieldScope === 'form' 过滤。

以某租户的客户业务为例：接口返回 95 条，其中 form 87 条，name 因两个 场景各有一条而出现两次。

isSystem / fieldType —— 区分系统字段与自建字段​

字段取值含义
isSystem1系统内置字段
isSystem0租户自建的自定义字段
fieldType0自定义
fieldType1系统固定
fieldType2系统字段但值存于扩展表

自建字段的 fieldName 形如 field_ogwkl4——随机后缀，各租户不同， 不要硬编码。

用途一：写入前自行校验必填​

需要特别说明：租户配置的必填不约束开放接口。某租户把「客户分类」配成必填， 经开放接口创建客户时不传它依然会成功——那层校验只作用于主站表单。

后果是：经接口写入的数据可能缺少租户认为必填的字段，这些记录在主站界面上 打开编辑时会被要求补填。

如果希望与主站表单保持一致，就用本接口读取配置、在写入前自行校验：

const fields = await invoke('system.field.list', { query: { label: 'customer' } });
const required = fields
  .filter((f) => f.fieldScope === 'form' && f.isNull === 0)
  .map((f) => f.fieldName);
// required 形如 ['name', 'categoryId', 'field_ogwkl4']

接口本身强制的必填是另一回事，边界见必填字段的判定。

用途二：取高级筛选可用的字段名​

带高级筛选的查询接口（客户、商机、物料、供应商等的 .page）接受 advancedFilters 参数，其中的字段名就取自本接口的 fieldName—— 包括租户自建字段，这也是筛选自定义字段的唯一途径。

{
  "apiCode": "sales.customer.page",
  "body": {
    "pageNum": 1,
    "pageSize": 10,
    "advancedFilters": "{\"field_ogwkl4\":{\"op\":\"contains\",\"value\":\"测试\"}}"
  }
}

算子清单与转义规则见对应接口的参数说明。该能力依赖检索索引，索引未就绪时 结果为空。

只读​

开放平台只提供字段清单的查询，不开放字段的创建、修改与删除—— 那属于租户管理员在主站的配置动作，不宜由集成方代为变更。 角色字段权限、用户列配置等同理，均未开放。