@antprofuse/saddle-db-design 0.1.0

package/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: saddle-db-design
+description: 在 Saddle 后端研发前，从 Islands Spec 与已确认的前后端 API 契约设计可追溯的数据库表结构 YAML。适用于判定内部持久化实体、定义字段类型与约束、设计索引和关联，并报告局部输入缺口。不用于 API 设计、外部 RPC 设计、生成 SQL 或编写数据库访问代码。
+---
+
+# Saddle DB 设计
+
+为 Saddle 后端需要持久化的内部业务实体产出完整、自包含、可追溯的表结构 YAML。数据库是 API 后端实现与持久化之间的边界，不能反向决定前后端 API。
+
+执行前必须阅读 [references/db-table-v1.md](references/db-table-v1.md)。遇到实体归属、生命周期、字段来源、唯一性、类型、关联或索引无法唯一确定时，阅读 [references/findings.md](references/findings.md)。
+
+## 输入
+
+- 用户明确提供的交付目录；不得自行改用固定仓库路径。
+- 已编译 Islands Spec 中相关 Structure、Logic、Rule、Visual 与 Test Responsibility。
+- 已确认的前后端 API 契约，尤其是字段来源、派生依赖和调用责任。
+- 当前 Saddle 数据库平台已经确认的物理能力；不得从旧 Harness 规范继承未经确认的策略。
+
+## 工作流程
+
+1. 先按 API 后端责任识别需要持久化的业务事实，再回到 Structure 判断实体归属与生命周期。不能看到实体就机械建表。
+2. 将实体分类为内部持久化、外部事实或瞬时/派生事实。只有内部持久化实体进入表设计。
+3. 每个内部持久化实体产出一个 v1 表结构 YAML；逐字段关联 Structure，并明确物理类型、nullable、主键、唯一约束、关联和索引。
+4. 使用 API access pattern 证明表和索引服务于哪些读写责任。不能用“以后可能查询”增加字段或索引。
+5. 跨文件检查表名、列名、约束名全局唯一，引用目标存在且类型兼容。
+6. 只交付完整表文件。局部不确定项写入 findings，并继续设计不受影响的实体。
+
+## 产出
+
+在用户提供的交付目录中写入：
+
+- 每个内部持久化实体一个 `<table_name>.table.yaml`；
+- 存在问题时写一个 `db-design-findings.yaml`。
+
+使用 [assets/table.template.yaml](assets/table.template.yaml) 作为起始结构。交付文件不得包含 TODO、占位符、阻塞标记或诊断节点。
+
+不生成、拼接、维护或要求 `structure.sql`。DDL 与迁移脚本属于后续确定性生成和部署工作，不是本 Skill 的设计产物。
+
+## 边界
+
+- API 先于 DB；表结构必须链接其支持的 API 后端责任，但 API 字段不必机械等同于数据库列。
+- 标记为外部、外部共享、外部只读或由 external 能力维护的实体不建本地表。
+- 查询响应、页面模型、统计值、当次外部快照和可重新计算派生值默认不建表；只有 Spec 明确要求跨请求持久保存且生命周期闭合时才可进入表。
+- 不默认增加代理主键、审计时间、软删除、版本号、租户字段或状态列。每个字段都必须有明确来源或已确认的工程必要性。
+- 不默认禁用或启用外键、CHECK、JSON、生成列、触发器等能力；v1 中未定义的物理能力产出 `unsupported-shape` finding，等待后续版本扩展。
+- 一个不完整实体只阻塞对应表，不阻塞其他完整表的交付。

package/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Saddle DB 设计"
+  short_description: "从 Islands Spec 与 API 契约设计可追溯的表结构"

package/assets/table.template.yaml

@@ -0,0 +1,19 @@
+schemaVersion: saddle-db-table/v1
+entity:
+  source: {entity: 替换为内部持久化实体}
+  persistenceReason: 替换为可追溯的持久化原因。
+table:
+  name: replace_with_table_name
+  comment: 替换为表的业务语义。
+columns:
+  replace_with_identity_column:
+    type: {kind: varchar, length: 64}
+    nullable: false
+    comment: 替换为字段语义。
+    source: {entity: 替换为内部持久化实体, field: 替换为稳定身份字段}
+primaryKey:
+  columns: [replace_with_identity_column]
+uniqueConstraints: []
+indexes: []
+references: []
+apiResponsibilities: []

package/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@antprofuse/saddle-db-design",
+  "version": "0.1.0",
+  "description": "从 Islands Spec 与 API 契约设计可追溯的 Saddle 数据库表结构。",
+  "license": "MIT OR Apache-2.0",
+  "files": ["SKILL.md", "agents", "assets", "references"],
+  "publishConfig": {"access": "public", "registry": "https://registry.npmjs.org/"}
+}

package/references/db-table-v1.md

@@ -0,0 +1,196 @@
+# Saddle DB 表结构 v1
+
+## 设计单位与文件身份
+
+一个 `*.table.yaml` 只定义一个内部持久化实体的一张表。v1 不支持一个实体拆多表或多实体合表；遇到该场景产出 `unsupported-shape` finding。
+
+文件固定命名为 `<table_name>.table.yaml`。`table.name` 必须是全局唯一的 snake_case 标识符，并与文件名去掉 `.table.yaml` 后原样一致。
+
+## 完整结构
+
+```yaml
+schemaVersion: saddle-db-table/v1
+entity:
+  source: {entity: 用户账单}
+  persistenceReason: 用户账单由本系统创建并跨请求保留，供查询与状态更新使用。
+table:
+  name: user_bill
+  comment: 用户账单持久化事实
+columns:
+  bill_id:
+    type: {kind: varchar, length: 64}
+    nullable: false
+    comment: 用户账单稳定标识
+    source: {entity: 用户账单, field: 账单ID}
+  user_id:
+    type: {kind: varchar, length: 64}
+    nullable: false
+    comment: 账单所属用户标识
+    source: {entity: 用户账单, field: 用户ID}
+  amount:
+    type: {kind: decimal, precision: 18, scale: 2}
+    nullable: false
+    comment: 应缴金额，单位为人民币元，按业务金额规则舍入。
+    source: {entity: 用户账单, field: 应缴金额}
+  bill_status:
+    type: {kind: varchar, length: 32}
+    nullable: false
+    comment: 账单状态
+    source: {entity: 用户账单, field: 账单状态}
+primaryKey:
+  columns: [bill_id]
+uniqueConstraints: []
+indexes:
+  - name: idx_user_bill_user_status
+    columns:
+      - {column: user_id, order: asc}
+      - {column: bill_status, order: asc}
+    purpose: 支持按当前用户和账单状态查询账单。
+    supports:
+      - {apiId: query_user_bill, accessPattern: 按用户与状态过滤}
+references: []
+apiResponsibilities:
+  - apiId: query_user_bill
+    operations:
+      - kind: read
+        columns: [bill_id, user_id, amount, bill_status]
+        predicateColumns: [user_id, bill_status]
+  - apiId: update_user_bill_status
+    operations:
+      - kind: update
+        columns: [bill_status]
+        predicateColumns: [bill_id]
+```
+
+顶层字段 `schemaVersion / entity / table / columns / primaryKey / uniqueConstraints / indexes / references / apiResponsibilities` 全部必填。没有内容的集合显式写 `[]`，禁止未知顶层字段。
+
+## Entity 与持久化判定
+
+`entity.source` 使用 Islands Structure 的稳定实体身份。`persistenceReason` 说明为什么该业务事实必须由 Saddle 跨请求保存，并必须能从 Logic 生命周期和 API 后端责任得到证明。
+
+以下内容不得产出表文件：
+
+- Spec 标记为 external、外部共享或外部只读的实体；
+- 由真实外部 SOFA RPC 负责维护的业务事实；
+- 页面状态、API response model、统计结果与可重新计算派生字段；
+- 只在一次请求或一次外部查询中成立的快照；
+- 生命周期、唯一身份或所有权尚未闭合的候选实体。
+
+“页面需要展示”或“API 需要返回”本身不构成持久化理由。
+
+## 表与列命名
+
+表名、列名、约束名和索引名均使用完整、无歧义的英文 snake_case，不使用缩写。表名和列名分别在其作用域内唯一。
+
+表名、列名及命名对象格式为 `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`。名称必须稳定，实现层不得再次重命名。
+
+## 列来源
+
+每个业务列必须具有且仅具有一个直接 Structure 来源：
+
+```yaml
+source: {entity: 用户账单, field: 账单状态}
+```
+
+v1 不把派生值作为持久化列。若业务明确要求保存派生结果，但其刷新时机、一致性和来源依赖已经闭合，产出 `unsupported-shape` finding 以驱动后续格式扩展，不能先用自然语言列绕过。
+
+不得默认增加 `id`、`created_at`、`updated_at`、`deleted`、`version`、`tenant_id` 等工程字段。只有它们已是 Structure 字段或存在已确认、可追溯的系统级持久化规范时才能加入；v1 暂不定义自由 `systemField`。
+
+## 物理类型
+
+v1 面向 Saddle 当前 MySQL/MariaDB 数据源，允许以下封闭类型：
+
+```yaml
+{kind: varchar, length: 64}
+{kind: text}
+{kind: signed_integer, bits: 32}
+{kind: signed_integer, bits: 64}
+{kind: unsigned_integer, bits: 32}
+{kind: unsigned_integer, bits: 64}
+{kind: decimal, precision: 18, scale: 2}
+{kind: boolean}
+{kind: date}
+{kind: datetime, precision: 6}
+{kind: binary, length: 32}
+```
+
+规则：
+
+- `varchar.length` 与 `binary.length` 必须是正整数，来自业务最大长度或已确认编码上界，不能随意统一为 255。
+- integer 的 signed 与 bits 必须由值域证明。
+- decimal 必须明确 precision、scale、单位及舍入语义；单位写入 comment，舍入语义来自 Structure/Rule。
+- `date` 表示 `YYYY-MM-DD` 业务日期；`datetime` 表示精确时刻，必须有统一时区语义。
+- 枚举在 v1 中映射为具有充分 length 的 `varchar`，合法值仍由 Structure 枚举定义；DB CHECK 策略尚未纳入 v1。
+- JSON、浮点数、数据库 enum、blob、timestamp、生成列及其他类型不在 v1 中，遇到时产出 `unsupported-shape` finding。
+
+API 类型不能单独决定 DB 类型；必须结合 Structure 值域、持久化语义和查询需求。
+
+## Nullable
+
+`nullable` 表示持久化事实是否允许缺失，不表示页面暂时不展示、API 字段可选或 external 偶发未返回。
+
+必须从实体生命周期证明 nullable。若字段仅在某状态后产生，需要确认是允许 NULL、拆分实体，还是业务模型缺少状态事实；DB Skill 不自行选择。
+
+## 主键与唯一约束
+
+`primaryKey.columns` 是非空列数组。主键优先使用 Structure 已定义的稳定实体身份，不能默认制造代理主键。
+
+复合业务身份使用 `uniqueConstraints`：
+
+```yaml
+uniqueConstraints:
+  - name: uq_user_bill_user_period
+    columns: [user_id, bill_period]
+    reason: 同一用户同一账期最多存在一张本系统账单。
+    evidence:
+      - {entity: 用户账单, fields: [用户ID, 账期]}
+```
+
+唯一性必须由 Structure/Logic 明确证明；案例数据不构成唯一性证据。
+
+## References
+
+跨内部表关联显式写入：
+
+```yaml
+references:
+  - name: ref_user_bill_user
+    columns: [user_id]
+    target:
+      entity: 用户
+      table: user
+      columns: [user_id]
+    enforcement: logical
+    reason: 当前平台尚未确认使用数据库外键约束，由后端保持引用一致性。
+```
+
+`enforcement` v1 只允许 `logical`。是否启用数据库 FOREIGN KEY 尚未形成平台统一规范，不由业务 Agent 自行打开。
+
+引用 external 实体时不能建立目标表或 reference；只在本实体确有业务需要时保存 external 的稳定标识字段。
+
+## Indexes 与 API responsibility
+
+索引必须由已确认 API 的实际访问模式证明。每个索引包含稳定 name、有序 columns、purpose 和至少一个 supports。
+
+`apiResponsibilities` 穷举当前表支持的 API 读写责任：
+
+- `kind` 只允许 `read / insert / update / delete`；
+- `columns` 是读取、插入或变更的列；
+- `predicateColumns` 是定位或过滤使用的列；
+- `apiId` 必须解析到已确认 API 契约。
+
+不要求每个 predicate 都单独建立索引；应按组合过滤、排序、唯一性和预期访问方式形成最小充分索引。没有 API 或 Logic 证据的预防性索引禁止加入。
+
+## 完成门禁
+
+表文件可交付必须满足：
+
+1. 实体已证明为内部持久化实体；
+2. 文件名与 `table.name` 原样一致且全局唯一；
+3. 每个业务列都能解析到唯一 Structure 字段；
+4. 类型参数、nullable、主键与唯一性均有依据；
+5. reference 目标存在、列数和类型一致；
+6. 每个索引都有 API/Logic 访问证据；
+7. 每个 `apiId` 都能解析到已确认 API；
+8. 不存在 external 多建表、瞬时数据落库、TODO、占位符或诊断标记；
+9. 交付目录中不存在本 Skill 生成的 `structure.sql`。

package/references/findings.md

@@ -0,0 +1,27 @@
+# DB 设计 Findings v1
+
+当输入不足或 v1 格式不支持某个确定需求时，在用户指定的交付目录写入 `db-design-findings.yaml`：
+
+```yaml
+findingsVersion: saddle-db-findings/v1
+findings:
+  - id: BILL-DB-001
+    severity: blocker
+    category: persistence-ownership-unknown
+    affected:
+      entity: 欠费单
+      path: entity.persistenceReason
+    evidence:
+      - {kind: structureEntity, entity: 欠费单}
+      - {kind: apiContract, apiId: query_bill}
+    message: 欠费单被标记为外部共享的当次查询事实，当前没有本系统持久化生命周期证据。
+    requiredUpstreamChange: 明确该事实由外部实时提供，或补齐由 Saddle 创建、更新和失效的生命周期。
+```
+
+必填字段为 `id / severity / category / affected / evidence / message / requiredUpstreamChange`。
+
+严重程度为 `blocker / warning`。
+
+v1 分类：`persistence-ownership-unknown / external-entity-local-table-conflict / missing-entity-identity / missing-field-source / missing-type-bound / nullable-ambiguous / unique-constraint-ambiguous / reference-target-missing / api-responsibility-missing / unsupported-shape`。
+
+Finding 必须精确到实体、表或字段。一个实体的问题不能阻塞其他完整表文件。Finding 不进入 `*.table.yaml`，也不授权 Agent 创建临时字段、宽泛类型或冗余表来绕过问题。