必填字段的判定

接口参考里每个字段都有「必填」列，但它只反映后端接口规格显式声明的必填。实际调用时还有两类约束不在其中，这里把三者的边界讲清楚——否则很容易出现「文档说可选、传了却报错」或者反过来的情况。

三个来源，只有两个约束 API

来源	由谁执行	是否约束开放接口	是否随租户变化
接口规格声明（DTO 的 `@Schema(requiredMode)`）	后端	✅ 是	否
服务内的前置校验（`Preconditions`）	后端	✅ 是	否
租户配置的字段必填	主站前端表单	❌ 否	✅ 是

一、接口规格声明

字段表「必填」列标「是」的，来自后端 DTO 字段上的 @Schema(requiredMode = REQUIRED)。这部分准确可信，但覆盖面有限：平台现有约 3 万个字段行中只有约 3% 作了这样的声明。

需要说明的是，这是文档注解而非校验注解——后端各服务的 DTO 上没有 @NotNull / @NotBlank，Controller 也未启用 @Valid，故这层声明不参与运行时校验，只用于生成接口规格。「必填」列显示「—」不等于该字段可以不传。

二、服务内的前置校验

大量必填实际写在服务方法内部，例如创建客户：

只传 name          → 60033 客户负责人不能为空
补上 ownerId 后    → 创建成功

这类校验不体现在接口规格里，字段表无从反映。判断某字段是否必填，最可靠的方式是实际调用一次——失败时响应的 message 会指明缺了什么，接口页的「试一试」面板可以直接验证。

平台没有把这类校验反推进文档：服务内的校验常带条件分支（某状态下才必填）、或在循环与嵌套对象中，静态提取的准确率不足以支撑一个可信的「必填」标记。与其给出半准确的结论，不如说明清楚判定方式。

三、租户配置的必填不约束接口

物料、客户、商机、项目、供应商、销售合同等业务支持在主站配置字段，管理员可以把某个字段（含自建的自定义字段）设为必填。

这类必填只作用于主站的表单校验，不约束开放接口。 例如某租户把「客户分类」配成必填，通过开放接口创建客户时不传它依然会成功。

由此带来一个需要注意的后果：

经开放接口写入的数据，可能缺少租户认为必填的字段。这些记录在主站界面上打开编辑时会被要求补填，保存前无法提交。

如果集成方希望与主站表单保持一致，应当自行读取租户的字段配置并在写入前校验。

查询租户当前的字段配置

system.field.list 返回指定业务的字段清单，其中包含各字段是否被配置为必填、是否为租户自建字段。该接口同时是高级筛选可用字段的来源。

字段含义与两个易读错之处（isNull 取 0 才是必填、同一字段会因 fieldScope 出现多次）详见字段清单与自定义字段。

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 等；具体可用值以该接口返回为准。

写接口在服务端校验必填

开放平台（包括 MCP 的 call_api）直接调用后端接口，不经过主站的网页表单—— 表单上的必填提示、格式检查、下拉选择在这条链路上都不存在。为此，写接口（新增、修改、状态变更）的必填与取值校验以后端服务端为准：缺字段或取值不合法时直接拒绝，不会写入半截数据。

主站表单上的关键校验正按业务逐步补到服务端，补齐的范围随版本在更新日志公布。对尚未补齐的字段，上文「租户配置的必填不约束接口」仍然成立，需要对齐时仍按该节自行校验。

去哪里查某个接口的必填字段

途径	内容
MCP 元工具 `describe_api`	返回的 `paramsDesc` 按固定行文列出参数，必填项标注「必填」，如 `id（客户ID，必填）`
接口参考页	页首的参数说明与 `paramsDesc` 同源；字段表「必填」列标「是」的为接口规格声明的必填
实际调用	以上两处都没写明时，调用一次，失败响应的 `message` 会指明缺了什么

写入前建议 agent 先 describe_api，按 paramsDesc 组装参数，再向用户确认内容后调用。

典型的失败响应

缺少必填字段或取值不合法时，响应仍是 HTTP 200，信封 code 为下游业务码（非 92xxx 段）， message 说明原因，data 为空：

{ "code": 60033, "message": "客户负责人不能为空", "data": null }

经 MCP 调用时，工具返回 isError: true，文本为：

{ "ok": false, "code": 60033, "message": "客户负责人不能为空" }

这类错误可以修正后重试：按 message 补齐或更正参数再调用即可，不会产生重复数据—— 请求在校验阶段就被拒绝，没有写入。与之相对，92205（结果未知）不能直接重试，见错误码。

批量导入的必填校验按行返回，见批量操作。

小结

字段表的「必填」是下限，不是全集：标「是」的一定必填，标「—」的未必可选
要确认某接口的真实必填，调用一次最快，用接口页的「试一试」即可
租户配置的必填属于主站表单行为，接口不强制；需要对齐时用 system.field.list 自行校验
MCP / 开放接口不经网页表单，写接口以服务端校验为准：先看 describe_api 的 paramsDesc，缺参失败按 message 修正后重试

三个来源，只有两个约束 API​

一、接口规格声明​

二、服务内的前置校验​

三、租户配置的必填不约束接口​

查询租户当前的字段配置​

写接口在服务端校验必填​

去哪里查某个接口的必填字段​

典型的失败响应​

小结​