---
name: app-schema-builder
description: 在 LessChaos 中新建 App，设计或调整 Table、Field、关联、主字段与约束。用户要求搭业务应用、增改表字段或演进现有结构时使用；录入和更新业务记录使用 app-record-editor，生成自由页面使用 app-page-builder。
---

<!-- 本 Skill 拥有业务需求到 App Definition 的建模、创建与演进流程；结构准入、权限和迁移由正式 App 域拥有。 -->

# App 结构搭建

把业务流程变为可维护的 Table 与 Field，提交正式定义并验证实际落地结果。默认沿用户现有 App 扩展，创建新 App 需要用户任务本身包含该意图。

下文 `app_*` 是工具用途名；从当前插件工具目录装载实际 Tool 定义后调用。App Tools 固定在本次 Run 的 Organization 内，不能通过参数选择其他账号或组织。

## 1. 取得业务模型与现有定义

从用户描述中确定管理对象、每行代表什么、对象间关系和关键状态。先用引用定位已有 App；需要发现来源时用 `app_list`。改现有结构必先 `app_definition`，保留完整定义和版本。

只询问会改变模型的缺口，例如“一张订单能否有多个商品”“客户是否可有多个联系人”。对名称、列顺序等可逆细节采用符合现有 App 的默认，不让用户逐字段配置。

完成条件：每张表的行粒度、主字段和与其他表的关系已确定。

## 2. 设计定义

| 决策                     | 采用方式                                            |
| ------------------------ | --------------------------------------------------- |
| 独立实体                 | 单独建表；重复明细不要展开为商品1、商品2等列        |
| 主字段                   | 选择用户能识别记录的字段；唯一性另用 `uniques` 声明 |
| 金额、数量、日期、状态   | 使用对应类型及配置；状态值使用稳定选项 ID           |
| 多选、多人员、关联       | 显式确定 cardinality；关联另确定方向与目标表        |
| 公式、查找引用、系统字段 | 按当前可用定义合同声明，值由系统产生                |
| 既有表或字段改名         | 保留原 ID；新建同名字段会成为不同数据身份           |

创建样例、关联配置和现有结构演进见 [建模与定义提交](references/definition-patterns.md)；提交定义前读取适用段落。复杂公式或跨 App 查找引用需要现有工具提供完整配置与授权依据；只有字段名称或自然语言公式不足以构造这些声明。

结构中保留用户现有规则、视图、用户属性和披露声明。跨 App 数据组合可以由查询和 Page bindings 完成，不因需要一张组合页面就复制来源表。

完成条件：每个字段均有真实类型、稳定 ID 和必要配置；所有结构变化都来自用户目标。

## 3. 提交创建或演进

新 App 用 `app_create` 一次提交完整初始定义，生成一次稳定 `appId`，`expectedVersion` 为 null。表、字段和选项的 ID 随方案确定并在重试时保留。

现有 App 用 `app_define` 提交完整下一版，`expectedVersion` 使用刚读到的 `definitionVersion`。从现有定义复制业务声明后做目标修改；不要把响应专属 `definitionVersion` 当作请求字段。省略原表或字段可能构成删除。

删除表、删字段、收窄关联和改变字段类型按用户明确意图执行；用户只说“整理”“优化”时先形成具体变更方案，保留现有业务数据。结构工具没有提供转换预览或公式诊断时，不声称已完成这些检查。

完成条件：正式回执确认定义已应用；创建不能只完成本地 JSON。

## 4. 重读验证与交付

重读 `app_definition`，逐项核对目标表、主字段、类型配置和版本，确认任务外声明仍在。对用户报告已建立的业务结构、实际版本及被拒绝的项目，附返回的资源链接。

用户明确要求样例数据、导入或迁移记录时继续使用 `app-record-editor`；建好结构本身不授权编造正式业务记录。用户还要求自由页面时，将已核对的 App、Table、Field 身份交给 `app-page-builder`。

## 失败恢复

| 观测               | 下一步                                                                                |
| ------------------ | ------------------------------------------------------------------------------------- |
| 定义版本冲突       | 重读最新完整定义，重新合并本次变更，再提交新的 expectedVersion                        |
| 字段或关联准入拒绝 | 按返回的 Table／Field 与规则修正方案，保留其他结构                                    |
| 配额或权限拒绝     | 报告具体缺口，不换组织或拆请求绕过                                                    |
| 创建请求结果未知   | 先用原 appId 查目录与定义；能够核对落地就继续验证，不能核对就保留未知，不换新 ID 重建 |
| 演进请求结果未知   | 重读版本和目标定义，确认本次变化是否已落地后再决定后续提交                            |

完成以正式定义与任务目标一致为准；记录数据、页面源码和页面运行各自验收。