makedsl

makedsl 用法

当你需要为 make platform 或 make 开发平台设计或生成 DSL 时，请使用此技能。 make platform 借鉴了 Kubernetes 和 Ansible 的设计思路，通过 DSL 对业务模型进行建模定义， 然后通过 DataAPI 对数据执行 CRUD-LS 操作。 生成的 DSL（yaml）文件应通过 makecli 提交到 make platform（make 开发者平台）。

对于 CanvasTable 的显示、列、渲染器或单元格编辑，请使用 canvas-table-integration。makedsl 仅负责 Schema 建模语义。

运行时边界

• DSL YAML 是设计和部署输入，并非已发布 App Service 必须使用的运行时文件。
• 不要生成将容器路径（例如 /dsl/00-app.yaml）硬编码的 Service 启动逻辑。
• 已发布的 Service 应从 Make 远程 Schema API 或环境提供的配置加载 Schema。本地 DSL 文件可用于开发、测试夹具、测试和 makecli apply，但不能作为 k8s 启动时唯一必需的来源。
• 如果 Service 需要本地 Schema 作为离线开发的回退方案，请明确说明，并分别测试远程 Schema 路径和回退路径。
• 如果前端构建或已发布 App 的运行时需要远程 Schema，请使用 @references/MetaAPIDesign.md 中的 Meta Service API，而不是读取本地 DSL 文件。

参考索引

主题	阅读
Make Meta API Schema 访问	references/MetaAPIDesign.md
Make Data API 和关联载荷	references/DataAPIDesign.md
关联声明	references/RelationDesign.md
基础字段 DSL 和查找字段	references/FieldDesign.md
用户字段设计	references/UserFieldDesign.md
部门字段设计	references/DepartmentFieldDesign.md
文件字段设计	references/FileFieldDesign.md
Entity 数据筛选器用法	references/EntityDataFilterUsage.md

DSL 定义

APP

从逻辑概念上对应数据库中的一个 database。

APP DSL

key: <KEY> # 创建后不可更新, 只允许英文字符、数字、下划线, 长度 2-20
name: String # 必填, 用户可见的展示名称, 允许中英文数字下划线, 长度 2-20
type: Make.App
meta:
  version: SemanticVersion
properties:
  timezone: String? # 可选，如 "Asia/Shanghai"、"UTC"；若未指定，使用系统默认"Asia/Shanghai"
  description: String?

约束条件

• 所有 App 的 key 创建后不可更新，在一个 org 下面唯一。
• 所有 App 的 key 不能以下划线 (_) 开头，下划线开头是预留关键字。
• 所有 App 的 name 是用户可见的展示名称。

App 示例

key: MatrixProject
name: 烽火项目管理
type: Make.App
meta:
  version: 1.0.0
properties:
  description: 烽火项目管理演示项目

Entity

从逻辑概念上对应数据库 table 中的一个 Table，在底层实现中，${App}.${Entity} 是 TiDB 的一个 Table。

Entity DSL

key: <KEY> # 仅英文字符、数字、下划线, 长度 2-20, 创建后不可更新
name: String # 必填, 用户可见的展示名称, 允许中英文数字下划线, 长度 2-20
type: Make.Entity
appKey: <Make.App>
meta:
  version: SemanticVersion
properties:
  fields:
    - Make.Field
    - Make.Field
    - ...

约束条件

• 所有 Entity 的 key 创建后不可更新，在一个 App 下面唯一。
• 所有 Entity 的 key 不能以下划线 (_) 开头，下划线开头是预留关键字。
• 所有 Entity 的 name 是用户可见的展示名称。

Entity 示例

项目 Entity

key: project
name: 项目
type: Make.Entity
appKey: <Make.App>
meta:
  version: 1.0.0
properties:
  fields:
    - key: project_name
      name: 项目名称
      type: Make.Field.Text
      meta:
        version: 1.0.0
      properties: null
    - key: project_description
      name: 项目描述
      type: Make.Field.TextArea
      meta:
        version: 1.0.0
      properties: null

任务 Entity

key: task
name: 任务
type: Make.Entity
appKey: <Make.App>
meta:
  version: 1.0.0
properties:
  fields:
    - key: task_name
      name: 任务名称
      type: Make.Field.Text
      meta:
        version: 1.0.0
      properties: null
    - key: task_description
      name: 任务描述
      type: Make.Field.TextArea
      meta:
        version: 1.0.0
      properties: null
    - key: task_status
      name: 任务状态
      type: Make.Field.SingleSelect
      meta:
        version: 1.0.0
      properties:
        options:
          - label: "待处理"
            value: "todo"
          - label: "进行中"
            value: "doing"
          - label: "已完成"
            value: "done"

Relation | 关联

• Relation 是描述 Entity 之间关系的纯结构声明——谁和谁有关系、几对几。不涉及任何展示逻辑。（详见 @references/RelationDesign.md）
• 关联数据的展示通过 LookupField 实现（详见 @references/FieldDesign.md）。
• 写入关联数据时，需要在 Data API 的 data.qfei_relation 中显式传递关联对象。（详见： @references/DataAPIDesign.md）

Field | 字段

从逻辑概念上对应数据库 table 中的一个 column，一个 Entity 会包含多个 Field。 详情请见 @references/FieldDesign.md

Record | 记录

从逻辑概念上对应数据库 table 中的一个 row，一个 Entity 会包含多个 Record。

DataAPI | 数据 CRUD-LS

对数据的操作可以参考 @references/DataAPIDesign.md

MetaAPI | 元数据与 Schema

前端构建、运行时 Schema 加载、实体/字段/关联元数据读取可以参考 @references/MetaAPIDesign.md