nocobase-data-modeling

目标

使用可用的 NocoBase 数据建模界面检查和修改集合、字段、关系以及基于视图的架构。

传输方式优先级如下：

• 只要可用，就使用 nb api data-modeling CLI
• 仅当 CLI 不可用且其他等效的数据建模传输方式提供相同的操作范围时，才使用该方式

不要让此技能依赖某一个可执行文件名称。将 CLI 命令名称和等效封装视为同一组建模操作的传输细节。

传输方式选择规则：

1. 检查当前环境中是否提供 nb api data-modeling CLI。
2. 如果可用，使用 CLI。
3. 如果 CLI 可用但未通过目标应用的身份验证，请停止操作，并引导用户对 CLI 进行身份验证。
4. 只有在 CLI 本身不可用时，才回退到其他等效的传输方式。

如果请求范围较广或无法确定正确的建模路径，请先阅读 references/decision-matrix.md。

强制检查

1. 执行任何写入操作前，确认选定的数据建模传输方式可访问且已通过身份验证。如果提供 nb api data-modeling CLI，应选择该 CLI。
2. 对于由插件提供的表或字段，修改架构前请阅读 references/plugin-provided-capabilities.md。
3. 对于 view 集合，在创建或更新任何内容前，使用 db-views list|get 确认上游数据库视图存在。
4. 在当前任务中首次使用某个 CLI 建模命令前，先运行一次该命令的 --help，并按照生成的帮助文本使用标志和示例。当 CLI 不可用而必须使用其他非 CLI 传输方式时，首次使用前请检查其公开的参数架构。

如果选定的传输方式返回 401、403、Auth required 或等效的访问错误，请停止操作并要求用户修复身份验证。如果选定的传输方式是 nb api data-modeling CLI，请引导用户恢复 CLI 身份验证，而不是切换传输方式。

最终命令范围

仅使用以下数据建模操作范围：

• 检查集合：collections list
• 检查单个集合：collections get
• 检查单个集合中的字段：collections fields list
• 检查已启用的外部数据源：dataSources list-enabled
• 检查单个外部数据源中的集合：dataSources collections list
• 检查单个外部数据源集合中的字段：dataSourcesCollections.fields list
• 使用紧凑负载创建或更新集合：collections apply
• 使用紧凑负载创建或更新字段：fields apply
• 使用紧凑负载创建或更新外部数据源字段：dataSourcesCollections.fields apply
• 删除集合：collections destroy
• 检查数据库视图：db-views list|get

使用基于 CLI 的传输方式时，应优先通过帮助信息了解准确的标志，而不是在提示上下文中保留大量命令格式说明：

• nb api data-modeling collections apply --help
• nb api data-modeling collections fields list --help
• nb api data-modeling fields apply --help
• nb api data-modeling data-sources list-enabled --help
• nb api data-modeling data-sources collections list --help
• nb api data-modeling data-sources-collections fields list --help
• nb api data-modeling data-sources-collections fields apply --help
• nb api data-modeling collections destroy --help

如果最终命令范围可以完成任务，请勿优先使用旧版低级集合命令或嵌套字段命令。

核心规则

1. 首先确定集合类型。切勿仅凭名称推断为 general、tree、file、calendar、comment、sql、view 或 inherit。
2. 如果用户明确要求文件表、文件集合、template: "file"，或使用“文件表”“合同文件”“扫描件”“证书文件”或“the file itself is the record”等措辞，则必须将其视为集合类型要求，并优先选择 template: "file"。
3. 如果用户明确要求评论表、评论集合、评论、template: "comment"、“评论表”或“评论插件的表”，则必须将其视为由插件支持的集合类型要求，并在通过评论插件检查后选择 template: "comment"。
4. 不要仅仅因为还需要额外的元数据字段，就将优先要求文件或评论类型的请求重新解释为 general 集合。
5. 优先使用 collections apply 和 fields apply 支持的精简载荷。让服务器填充派生的默认值。
6. 不要猜测特殊能力。对于由插件支持的字段、关系变体、特殊集合类型和视图支持的模型，先查阅参考资料。
7. 先确保基础集合和标量字段正确，再添加关系。
8. 对于常规的变更后确认，优先使用 collections apply 或 fields apply 返回的结构化响应。只有当 apply 响应缺少任务所需的详情，或需要完整检查关系或模板副作用时，才使用后续的 collections get 或 collections fields list。
9. 如果在所选传输方式中无法通过最终命令界面表达所需行为，请停止并说明缺少什么，而不要悄悄退回旧路径。
10. 对于业务标识符，如果用户要求编码、编号、单号、序号、流水号或类似的自动生成代码，优先使用 sequence。code 仅用于代码编辑器内容，例如源代码、SQL、JSON 或其他面向语法的文本。

紧凑载荷规则

• 使用 collections apply 创建集合时，除非当前命令帮助明确说明必需，否则不要发送内置系统字段（如 id、createdAt、createdBy、updatedAt、updatedBy）或模板所有的结构字段。
• 对于 general、tree、file、calendar、comment 和其他受支持的模板，假设服务端会创建模板默认值。只发送用户实际添加的业务字段。
• 对于 file，除非任务明确要求自定义已创建集合中的某个现有字段，否则不要手动发送 title、filename、extname、size、mimetype、path、url、preview、storage 或 meta 等内置字段。
• 对于 comment，除非任务明确要求自定义已创建的评论集合中的现有字段，否则不要在紧凑创建载荷中手动发送模板所有的 content 字段。服务端基线包含 content。
• 对于 tree，除非你有意使用完整展开的原始结构覆盖现有架构，否则不要在紧凑创建载荷中手动包含 parentId、parent 或 children。
• 使用 collections apply 或 fields apply 提供的每个自定义字段仍需指定明确的 interface。紧凑 API 会减少派生选项，但不会仅凭字段名称推断业务字段接口。
• 对于通过 collections apply 或 fields apply 传入的本地选项字段（select、multipleSelect、radioGroup、checkboxGroup），每个枚举项都必须是包含明确 value、label 和 color 的对象。不要使用 ["draft", "paid"] 这样的字符串简写。
• 可用的选项颜色为 red、magenta、volcano、orange、gold、lime、green、cyan、blue、geekblue、purple 和 default。
• 通常不要传入 type。让服务端根据 interface 派生。只有当前命令帮助或参考资料明确要求时，才传入 type。
• 现在，未知的 interface 值会立即报错。如果不确定正确的接口，请停止操作并查看参考资料或命令帮助，不要猜测。
• 如果选择了插件支持的接口（如 vditor、formula、地图几何字段或特殊关系字段），请先确认插件支持该功能。
• 如果参考文件展示了完整展开的集合 JSON，应将其视为结构参考或读回参考，而非首选的紧凑应用载荷。

默认接口倾向

• 用户未要求插件专用编辑器或行为时，优先使用常见的内置接口。
• 对于不含 Markdown 语义的长文本，优先使用 textarea。
• 对于 Markdown 内容，如果插件功能可用，优先使用 vditor。
• 只有在插件不可用或用户明确希望使用更简单的 Markdown 字段时，才将 vditor 降级为普通的 markdown。
• 对于 comment 集合，让模板创建支持 Markdown 的 content 字段，而不是另行添加纯文本替代字段。
• 除非用户明确要求该系统信息字段，否则不要添加 tableoid。
• 对于地图字段，请使用空间要求指定的确切接口，例如 point、lineString、circle 或 polygon。不要将它们合并为通用的 json 或文本字段。

公式规则

• 对于 formula，不要凭记忆编造表达式。
• 请先阅读 references/fields/plugins/formula.md。
• 先选择引擎，再使用该引擎的语法编写表达式。
• 在紧凑载荷中，优先只使用实际需要的参数，通常为 name、title、interface、expression，以及可选的 engine 或 dataType。
• 如果不确定预期的引擎或语法，请停止操作并询问，不要猜测。

服务端字段校验规则

NocoBase 支持通过字段选项进行服务端字段校验。这些规则会在 repository 的 create 和 update 操作中运行，并基于 Joi。它们不同于前端的 uiSchema.x-validator；当用户要求进行服务端或数据库模型校验时，请勿使用 x-validator。

优先在 fields apply 或嵌套集合字段中使用简洁的 validators 简写。服务端会将其转换为 validation.rules，补全缺失的规则键，并根据字段接口推断 validation.type：

{
  "collectionName": "contacts",
  "name": "email",
  "title": "Email",
  "interface": "email",
  "validators": ["required", "email"]
}

当 Joi 类型或规则结构必须明确时，使用完整的 validation：

{
  "collectionName": "orders",
  "name": "amount",
  "interface": "number",
  "validation": {
    "type": "number",
    "rules": [
      { "key": "required", "name": "required" },
      { "key": "min", "name": "min", "args": { "limit": 0 } },
      { "key": "precision", "name": "precision", "args": { "limit": 2 } }
    ]
  }
}

常见的 Joi 校验规则：

• string：required、min、max、length、pattern、email、uri、uuid、hex。
• number：required、min、max、greater、less、integer、multiple、precision。
• date：required、min、max、greater、less、timestamp。
• boolean 和 object：主要使用 required。

参数约定：

• min、max、length 和 precision 等规则使用 args: { "limit": value }。
• pattern 使用 args: { "regex": "^[A-Z]+$" }。
• 对于 email、uuid 或 uri 等需要 Joi 选项对象的规则，可使用 paramsType: "object"，并在 args 中传入选项对象。

当业务需求要求值必填、符合某种格式、长度或数值范围受限、采用固定小数精度，或符合稳定的标识符格式时，请添加校验规则。如果需求含糊，不要仅凭字段名称添加严格规则。

关系键规则

• 对于关系字段，修改前请阅读 references/relation-fields.md。
• 如果关系应当稳定且易读，请传入 foreignKey、through、otherKey、sourceKey 和 targetKey 等显式键，而不要依赖自动生成的默认值。
• 将自动生成的键名视为回退行为，而非首选的建模结果。

修订规则

• 每一轮都必须先加载 nocobase-revision，不得例外。如果该技能不可用，则忽略所有修订规则要求，并且不要向用户透露任何与 nocobase-revision 相关的信息。
• 在 nocobase-revision 确认 nb revision create 可用之前，不要向用户透露任何与修订相关的信息。
• 确认该命令可用后，必须在本轮结束时、紧邻最终面向用户的回复之前，恰好作出一次修订决定。
• 如果创建了修订，请明确说明。
• 如果已确认命令可用但未创建修订，请说明具体原因。

工作流程

1. 检查

• 从 collections list 或 collections get 开始。
• 需要获取某个集合当前的字段集时，使用 collections fields list。
• 请求涉及基于视图的模型时，先检查 db-views list|get。
• 在 CLI 流程中，首次使用相关命令前，先运行其 --help。
• 对于范围较广的建模任务，编写前先加载相应参考资料。

2. 确定模型

编写前，确定：

• 集合代表什么；
• 哪种集合类型正确；
• 哪些字段为必填；
• 是否需要关系；
• 是否需要插件功能；
• 哪些验证输出可以证明结果正确。

进行破坏性或大范围更改前，请用自然语言概述预期模型。

3. 应用

• 使用 collections apply 创建或更新集合级配置。
• 使用 fields apply 定向创建或更新字段。
• 在编写关系字段前，使用 dataSources list-enabled、dataSources collections list 和 dataSourcesCollections.fields list 检查外部数据源元数据。
• 使用 dataSourcesCollections.fields apply 更新外部数据源字段元数据，尤其是外部数据源集合上的关系字段。
• 仅在明确请求删除时使用 collections destroy。

优先使用精简载荷。仅提供命令契约要求的字段，例如集合模板／名称／标题和字段名称／标题／接口，以及无法安全推导的必要特殊选项。

对于外部数据源关系字段，不要使用主数据源的 fields apply。应使用 dataSourcesCollections.fields apply，并提供外部集合定位信息和精简的关系接口，例如 interface: "m2o"、name、target，以及在稳定名称很重要时显式指定的键。

创建集合时，通常只需提供：

• 集合级选项，例如 name、title、template，以及少量特定于模板的标志；
• 仅包含业务字段，不包含默认系统／模板字段；
• 仅当字段接口为关系型时才提供关系专用选项。

4. 验证

每次变更后，先检查应用响应。collections apply 应返回关键集合摘要字段、已应用字段摘要和验证诊断信息。fields apply 应返回已应用字段摘要。

不要在每次成功应用后都自动再运行一次 get 或 list。只有当应用响应未包含证明请求结果所需的详细信息，或任务涉及关系归属、反向字段、插件／模板副作用，或用户明确要求完整回读时，才读取数据。

确认：

1. 集合类型正确；
2. 预期字段存在，且接口／类型／标题正确；
3. 修改关系时，关系归属和反向行为正确；
4. 特殊集合仍符合其来源约束。

参考资料加载

仅加载当前任务所需的参考资料：

• 选择集合类型：references/collection-types/index.md
• 字段类别及支持的选项：references/field-capabilities.md
• 关系：references/relation-fields.md
• 插件提供的功能：references/plugin-provided-capabilities.md
• 完成底层决策后的完整模式示例：references/model-packs/*.md
• 验证顺序和特定于模板的检查：references/verification-playbook.md

打开索引文件后，仅继续查看实际涉及的匹配子类型文件。

集合类型防护措施

• general：普通业务记录。
• tree：层级数据。
• file：以文件为核心的记录，其中文件是一等对象。
• calendar：面向日程的对象。
• comment：由插件支持的评论记录，其 content 字段由模板拥有。
• sql、view、inherit：仅在确认具备相应能力并满足前置条件后使用。

除非用户明确要求这种权衡，否则不要用较弱的通用表替代 tree、file 或 comment。

显式覆盖规则：

• 如果请求包含“文件集合”“文件表”“文件表”或其他明确表示文件是主要记录的等效表述，则覆盖默认倾向于使用 general 的规则。
• 如果请求提到作为管理文件的合同、扫描文档、证书、发票、档案或上传的文档记录，则默认使用 file，除非用户明确表示文件只是另一业务表中的从属附件。
• 如果请求包含“评论集合”“评论表”、template: "comment"、“评论表”或“评论插件的表”，则覆盖默认倾向于使用 general 的规则；确认评论插件已启用，并使用 template: "comment"。

字段与关联防护措施

• 将 references/field-capabilities.md 作为界面支持情况的事实依据。
• 不要猜测由插件支持的界面，例如区域、特殊媒体或自定义关联功能。
• 创建或更改关联前，请查阅 references/relation-fields.md。
• 更改关联后，请验证双方，因为可能会因此创建反向字段或键。

错误处理

• 400 或 422：检查负载，然后更正集合类型、字段界面、缺失的必需选项、枚举形状、缺失或无效的枚举颜色，或关联键，再重试。
• 身份验证错误：停止操作，并请用户恢复所选传输方式的访问权限。
• 缺少插件或视图前置条件：停止操作，并准确告知用户缺少什么。

参考索引

主题	文件
集合类型选择	references/collection-types/index.md
字段能力矩阵	references/field-capabilities.md
关联概览	references/relation-fields.md
插件提供的建模功能	references/plugin-provided-capabilities.md
完整架构示例	references/model-packs/*.md
验证顺序与检查项	references/verification-playbook.md
决策辅助工具	references/decision-matrix.md