数据库表结构设计（design-database-schema）¶

目标：根据**需求文档**产出一份可评审、可落地的库表结构设计文档。本技能**只写设计文档，不执行 DDL、不生成 .form / workspace XML**。

流水线边界（必须遵守）：

SCHEMA 定库表 → PLAN 定蓝图
  → 事务表：普通表单 + .create_form_table → TLK_*
  → 主数据表（手工 SQL）：映射表单 type=65536（先 DDL，不投递 create_form_table）

本技能产出 SCHEMA；下游 plan-application 写蓝图（主数据规划为映射表单）；事务表由 generate-form-file + .create_form_table 落地。

产出物¶

部分	落盘	形态
库表结构设计	与功能规格说明书同目录下的 `DATABASE_SCHEMA.md`；用户显式指定路径时从其指定	Markdown

默认落盘（硬规则）：

{功能规格说明书所在目录}/DATABASE_SCHEMA.md

示例：需求为 docs/apps/fixed-assets-management/固定资产管理模块功能规格说明书.md 时，成果写到：

docs/apps/fixed-assets-management/DATABASE_SCHEMA.md

以本次读取的功能规格说明书（或等价需求文档）的**所在目录**为基准，勿写入 {软件名}.application/。
用户已明确指定其它路径时从其指定。
尚不知规格说明书路径时：先确认路径再写，禁止落到无关目录。

模板见 schema-template.md。

何时触发¶

用户提供/指向需求文档，要求做**数据库 / 表结构 / 表设计 / 数据表设计 / 数据结构设计 / 数据模型 / ER**设计
用户明确提到**事务表 / 主数据表 / 统计表** 或 TLK_
新建应用且尚无可用的 DATABASE_SCHEMA.md：宜**先于** plan-application 完成本技能（SCHEMA → PLAN → form）

与下游关系：本技能定表类型、字段与关联；plan-application 依据已确认的 SCHEMA（及需求）写应用蓝图与实施清单。二者冲突时以**已确认的需求文档**为准，并回写差异说明。

三类表（分类必须准确）¶

设计时每张表必须归入且仅归入一类。下列定义**按原文使用，勿改写**：

事务表（Transaction Table）：通常由动态表单自动创建的数据库表，特点为 TLK_XXX，通常用于业务事务流水，记录原始流水记录
主数据表（Master Table）：通过 sql 或数据库工具手工创建的数据库表，通常用于基础数据记录
统计表（Summary Table）：通过 sql 或数据库工具手工创建的数据库表，通常由事务明细聚合计算得出

分类判定¶

问自己	归类
是否对应一张业务表单的流水/单据，且由平台动态表落库？	事务表 → `TLK_{表单名}`
是否相对稳定的基础档案/字典/配置，手工建表维护？	主数据表
是否由流水聚合/快照得到，供报表或查询，手工建表？	统计表

禁止：把主数据或统计结果硬塞进 TLK_；禁止把应落动态表的业务流水改成纯手工表却仍标成事务表。

平台统一处理的表（模块不建）：操作日志 / 登录日志 / 异常日志 / 接口(API)日志 / 操作审计日志由平台统一记录，业务模块**不再自建**此类通用日志表（如 *_INTERFACE_LOG / *_API_LOG / *_OPLOG / OP_* / LOG_* 等）。设计文档只在 §1 约定注明"由平台统一记录"。仅保留：业务域历史/执行记录（资产变更追溯、价格变更、SOP 步骤、自动化执行、印发登记/督办子表、生产异常单、品质异常等）与共享中心变更传播机制表（DSC_MASTER_CHANGE_LOG / DSC_CHANGE_EVENT）。

命名与平台约定¶

事务表（动态表）¶

项	约定
表名	`TLK_` + 表单 `name`（英文标识），全大写，如表单 `Leave` → `TLK_LEAVE`
业务列	`ITEM_` + 字段名大写，如字段 `reason` → `ITEM_REASON`
主键	通常 `ID`（VARCHAR）；与 `T_DOCUMENT.MAPPINGID` 对应
系统列	平台固定列（`PARENT`、`CREATED`、`AUTHOR`、`DOMAINID`、`ISTMP` 等）由引擎创建；设计文档业务字段节只列业务列，固定列用一节摘要引用即可，勿逐列杜撰类型
列类型映射（设计→落库）	`VARCHAR`→`VARCHAR(100)`（可按需加长）；`NUMBER`→`DECIMAL(22,10)`（MySQL）；`DATE`→`DATETIME`/`TIMESTAMP`；长文本→`TEXT`/`LONGTEXT`；附件类→`TEXT`（列内存 JSON，描述存储路径、文件名等元信息，不落二进制；勿映射为 `BLOB`）
创建方式	表单保存 / `.create_form_table`；不要在设计文档中写手工 `CREATE TABLE TLK_…` 作为主路径

子表单：独立 TLK_{子表单名}，用 PARENT（或业务外键字段）关联主表文档。

主数据表 / 统计表（手工表）¶

项	建议
表名	全大写英文+下划线；不要使用 `TLK_` 前缀
主数据前缀（建议）	`MD_` 或业务域前缀，如 `MD_CUSTOMER`、`BASE_ORG`
统计前缀（建议）	`SUM_`，如 `SUM_LEAVE_MONTH`
主键	显式声明；常用 `ID VARCHAR(100)` 或自增（按目标库）
多租户	MyApps 业务库常带 `DOMAINID` / `APPLICATIONID`；需求涉及多域时必须设计
创建方式	文档末附建议 DDL（或说明用何工具创建）；注明刷新/聚合任务来源（定时任务、脚本、ETL）；下游 PLAN 对主数据（及需界面维护的手工表）使用映射表单 type=65536

工作流¶

读需求（及可选 PLAN.md）
  → 抽取实体 / 流水 / 基础数据 / 报表指标
  → 归类为 事务表 / 主数据表 / 统计表
  → 逐表设计字段（名称、类型、长度、约束、用途）
  → 画清关联（主键/外键/逻辑外键、基数、关联字段）
  → 按模板落盘到「功能规格说明书同目录」/DATABASE_SCHEMA.md
  → 自检清单全部通过后再交付

步骤说明¶

读需求：标出业务对象、单据流水、基础档案、报表/看板指标；不明处列入「开放问题」，勿臆造关键业务字段。同时记下功能规格说明书路径，用于确定落盘目录。
归类建表清单：每张表写清：中文名、物理表名、类型、用途、创建方式（动态表单 / SQL）。
字段设计：每字段必有：物理名、逻辑名、类型、长度/精度、约束（PK/FK/UK/NOT NULL/默认值）、用途。事务表业务列同时给出建议表单字段名（小写/驼峰）与 ITEM_ 列名。
关联：主表–子表、流水–主数据、统计←流水的关联键、基数（1:1 / 1:N / N:M）、是否物理外键或仅逻辑关联（动态表通常为逻辑关联）。
统计表来源：写明源事务表、聚合粒度（日/月/组织…）、度量字段、刷新方式。
落盘：写入 {功能规格说明书所在目录}/DATABASE_SCHEMA.md（或用户指定路径）；交付时告知完整路径。
自检：必须执行下文清单；有失败项则改设计后重检。

输出必须包含的内容¶

设计文档须覆盖用户要求的三类描述（缺一不可）：

数据表：名称、类型（事务表 / 主数据表 / 统计表）、用途
数据字段：名称、类型、长度、约束、用途
关联逻辑：表与表、字段与字段的对应关系

结构必须遵循 schema-template.md。

自检清单（交付前必做）¶

复制到文档末「自检记录」并逐项勾选；任一项不通过则不得宣称完成。

A. 与需求一致¶

需求中的每个核心业务对象均有对应表或明确「不做/合并到某表」的说明
需求中的关键指标/报表能从事务表直接查询，或能从统计表+定义的聚合规则得到
无超出需求的臆造实体（示例数据除外）；开放问题已列出
表类型划分与三类定义一致（事务=TLK_ 动态表；主数据/统计=手工表）

B. 自身逻辑合理¶

表名、字段名无冲突；同义字段跨表命名一致
每表有且仅有一个主键策略；关联两端类型与长度兼容
事务表业务列均为 ITEM_*；未给 TLK_ 表设计「手工 DDL 主路径」
主数据 / 统计表未误用 TLK_ 前缀
统计表的每个度量/维度能追溯到源事务字段或主数据
1:N / N:M 关系有中间表或子表方案；无悬空外键
多租户/域隔离字段（若需要）在相关表上一致
枚举/状态字段取值与需求状态机一致（若有）

C. 文档完整¶

每表含：名称、类型、用途
每字段含：名称、类型、长度、约束、用途
关联关系已用表格或列表写清（含关联字段）
已落盘到功能规格说明书同目录（或用户指定路径），而非 {软件名}.application/
自检记录已填写结论（通过 / 有条件通过 + 条件）

与其它技能的边界¶

SCHEMA 定库表 → PLAN 定蓝图
  → 事务表：普通表单 + .create_form_table → TLK_*
  → 主数据表（手工 SQL）：映射表单 type=65536（先 DDL）

技能	关系
`plan-application`	下游：依据已确认的 `DATABASE_SCHEMA.md`（及需求）写应用蓝图与实施清单；主数据表 / 需维护的手工 SQL 表规划为 `type=65536` 映射表单；事务表规划为普通表单；勿颠倒为先 PLAN 再补 SCHEMA（除非用户明确跳过库表设计）
`generate-form-file`	更下游：事务表 → `.form` type∈{1,3,16} + `.create_form_table` 落 `TLK_*`；主数据 → `.form` type=65536 + `mappingStr`（目标表须已 DDL）
`generate-datasource-file`	库连接；不定义业务表结构
`generate-task-file` / `iscript-usage`	统计表刷新任务、聚合脚本可在设计中点名，落盘时再调用

反例¶

把「客户档案」建成 TLK_CUSTOMER 却标注为主数据表，又不走表单 —— 类型与创建方式矛盾
统计表只写表名无聚合来源与粒度
只列字段名不写类型/长度/约束
子表不说明与主表关联键
跳过自检直接交付
把 DATABASE_SCHEMA.md 写到 {软件名}.application/，而未与功能规格说明书同目录