@antprofuse/saddle-db-design 0.1.2 → 0.1.3

package/SKILL.md

@@ -42,6 +42,7 @@ description: 在 Saddle 后端研发前，从已编译 Islands Spec 设计可追
 - 不设计业务唯一约束、普通索引或数据库外键。索引属于运行后的观测与运维优化。
 - 实体关联字段保留 Structure 的关联业务语义；内部关联存目标 uid，external 关联存可长期解析的外部身份引用，不强制本地 UUID。多重关联依靠原始角色语义区分。不得为制造 uid 而给 external 实体建表，也不要求业务 Spec 定义技术编码。
 - varchar 使用已确认的长度分档；人民币金额沿用有符号 BIGINT 分存储，不沿用 API 的元字符串作为物理列类型。
+- 文章正文等长文本可使用 `type: {kind: text}`，对应 MySQL TEXT，不填写 length。仍需真实 Structure 字段来源、nullable 为 true 且无默认值；TEXT 不是无限容量，也不用于绕过不明确的结构化建模。具体容量边界见类型参考。
 - 新版 Flow 使用真实板块/节点记录 Logic、Branch 访问责任，也覆盖 Visual 的持久读取；不虚构旧 Paragraph/Transaction。已传入 Row 的纯内存消费不等于再次读库。
 - 删除统一为软删除。Saddle 数据访问层必须对普通读取强制过滤 `is_deleted = false`；业务查询不得各自实现这条规则。
 - 把业务状态更新为“已删除”仍是 update，不等于实体 delete，不自动联动 is_deleted。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antprofuse/saddle-db-design",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "从 Islands Spec 设计可追溯的 Saddle 逻辑数据库表契约。",
   "license": "MIT OR Apache-2.0",
   "files": ["SKILL.md", "agents", "assets", "references"],

package/references/db-table-v1.md

@@ -157,6 +157,7 @@ v1 只允许以下封闭类型：
 
 ```yaml
 {kind: varchar, length: 64}
+{kind: text}
 {kind: bigint}
 {kind: decimal, precision: 18, scale: 2}
 {kind: boolean}
@@ -166,13 +167,25 @@ v1 只允许以下封闭类型：
 
 - `varchar.length` 默认采用已确认的64/256/1024档：标识符、编码、户号文本、枚举64；名称256；地址1024。明确的项目约定优先。外部复合身份引用不是裸户号文本，应按已确认编码预算选档；例如 bill 的用户引用64、户号引用256。内部 uid 固定32。不要求 Spec 精确给出数据库长度；超出已选上界或需要新类型时讨论，不静默截断。
 - `bigint` 固定生成 MySQL 64 位有符号整数。
+- `text` 对应 MySQL `TEXT`，类型节点仅为 `{kind: text}`，不允许 length、precision 或 scale。适用于文章正文等有明确业务含义的长文本，不强制按 varchar 的长度分档。最大容量为 65,535 字节而非字符数，可容纳字符数取决于数据库字符集；环境字符集仍由运维负责，不新增实例配置。业务长度与内容格式由业务逻辑处理，不生成数据库约束，不静默截断。明确超过 TEXT 容量时反馈讨论，不自动升级 MEDIUMTEXT/LONGTEXT。依据：[MySQL 字符串类型](https://dev.mysql.com/doc/refman/8.4/en/string-type-syntax.html)。
+- TEXT 字段继续使用 `nullable: true`、无数据库默认值和原始 Structure 字段来源。仅选择存储类型，不擅自规定正文是纯文本、HTML 或 Markdown，也不因正文可能很长而另拆表、增加索引或生成 DDL。不能用 TEXT 序列化未知对象来绕过未支持的结构或关联。
 - `decimal` 必须明确 precision、scale 和单位；精度与小数位来自 Structure/Rule。
 - 人民币金额使用有符号 `bigint` 保存分，附加 `money: {currency: CNY, unit: minor, minorUnitsPerMajor: 100}`；与 API 的元精确十进制字符串在应用边界准确换算，不使用二进制浮点数。非负等业务值域仍由业务逻辑负责。其他币种或需要不足一分的精度时先讨论，不套用人民币比例。没有本地金额字段时不为使用此规则新增字段或表。
 - `boolean` 固定生成 MySQL `TINYINT(1)`，但契约保留布尔业务语义。
 - `date` 表示业务日期。
 - `datetime` 必须明确 precision；系统时间列固定为 3。
 - 枚举使用能够容纳全部合法值的 `varchar`；合法值由业务逻辑校验，不生成数据库 ENUM 或 CHECK。
-- JSON、TEXT、BLOB、浮点数、TIMESTAMP、数据库 ENUM、生成列等不在 v1 中；确定需要时产出 `unsupported-shape` finding。
+- JSON、TINYTEXT、MEDIUMTEXT、LONGTEXT、BLOB、浮点数、TIMESTAMP、数据库 ENUM、生成列等不在 v1 中；确定需要时产出 `unsupported-shape` finding。
+
+长文本业务列示例（只在输入确有此字段时使用，不是要求所有表增加正文）：
+
+```yaml
+文章内容:
+  type: {kind: text}
+  nullable: true
+  comment: 文章正文内容
+  source: {entity: 文章, field: 文章内容}
+```
 
 ## 数据库约束边界