common_agent/docs/数据库设计/0.数据库与枚举总览.md

数据库与枚举总览

1. 文档目的

本文集中说明本轮数据库和枚举脚本的更新范围，避免需求文档、设计文档、前端文档、后端文档与 SQL 脚本出现冲突。

2. SQL 脚本分层

脚本位置	作用
script/sql/	可执行的模块化建表或初始化脚本
docs/MODEL_PROVIDER_SCHEMA.sql	模型平台 schema 汇总
docs/STUDIO_PROTOTYPE_SCHEMA.sql	Studio 原型 schema 汇总

模块化脚本是后续落库执行的优先参考，docs/*SCHEMA.sql 是完整设计快照。

3. 必须保持不变的内容

script/sql/enum.sql 中 sys_enum 表结构不变：

• catalog
• type
• name
• value
• strvalue
• sort
• version
• create_time
• update_time
• remark
• create_by
• update_by

Java 枚举契约 PersistableSysEnumDefinition 的格式不变。后续如果实现新枚举类，仍按现有 getCatalog()、getType()、getValue()、getLabel()、getRemark() 风格实现。

4. 本轮新增脚本

脚本	内容
script/sql/studio_project.sql	Studio 项目空间表
script/sql/workflow.sql	Workflow 定义、版本、运行、步骤日志
script/sql/mcp.sql	MCP Server 与能力表
script/sql/skill.sql	Skill 定义与版本表
script/sql/agent_session.sql	Agent 会话与消息表
script/sql/agent_capability_binding.sql	Agent/Workflow 与 MCP/Skill/知识能力绑定表
script/sql/studio_enum.sql	Studio 相关枚举初始化

5. 校验规则

• 所有新增表必须包含 id、version、create_time、update_time、remark、create_by、update_by。
• 需要唯一业务编码的表必须增加唯一约束。
• 需要跨模块引用的字段必须在文档中说明外键关系。
• JSON 扩展字段统一使用 JSONB。
• 枚举初始化脚本必须使用 ON CONFLICT (catalog, type, name) DO UPDATE，与现有脚本风格一致。