数据库命名规范 (Database Naming Convention)

1. 核心规则：模块化前缀

1.1 命名格式

{module_prefix}_{entity_name}

组成部分	规则	示例
模块前缀	小写英文 + 下划线结尾	sys_ / chat_ / task_
实体名称	复数小写英文 + 下划线分隔	users / agent_nodes / execution_logs
完整表名	前缀 + 实体名（snake_case）	sys_users / chat_agent_nodes / task_exec_logs

1.2 模块前缀注册表

所有前缀必须先在此表中注册，方可使用。新增模块时需更新此表。

前缀	业务域	负责人	说明
sys_	系统基础 / 通用	-	用户、角色、权限、菜单、日志、通知、配置等跨模块共用基础能力
chat_	对话 / Agent 核心	-	会话、消息、记忆、快照、Agent 节点管理等对话相关功能
task_	任务调度	-	定时任务、执行日志、调度策略等
fin_	金融系统	TBD	账户、交易记录、资产、风控规则等（规划中）
pay_	支付 / Token 计费	TBD	订单、支付流水、Token 包、消费记录、计费规则等（规划中）

1.3 新增模块流程

1. 在上表中申请前缀（避免与其他项目/系统冲突）
2. 更新本文档的前缀注册表
3. 在 PR 描述中引用本文档版本号
4. Code Review 时检查命名合规性

---

2. 详细命名规则

2.1 表名规则

规则	正确示例	错误示例
全部小写	sys_user_roles	Sys_User_Roles
单词间下划线连接	chat_agent_node_groups	chatAgentNodeGroups
使用复数名词	sys_users, chat_messages	sys_user, chat_message
有明确前缀	task_schedules	schedules
前缀 2-6 个字符	sys_, chat_, finance_	s_, systematic_

2.2 字段名规则

规则	正确示例	错误示例
snake_case	created_at, user_id	createdAt, userID
主键统一用 id	id Int @id	userId Int @id
外键格式 {table}_id	session_id, group_id	sessionId, gid
时间字段后缀 _at / _ms	started_at, duration_ms	startTime, duration
布尔值前缀 is_	is_read, is_deleted	read, deleted
通用时间戳	created_at(创建), updated_at(更新)	createTime, updateTime

2.3 索引命名

比如：sys_user_roles_user_id_idx（用户角色表的用户 ID 字段复合索引），或 @@index([field1, field2]) 声明。

2.4 中间表（多对多关联）

中间表命名格式：{prefix}_{entity1}_{entity2}（按字母序排列）

// 正确：用户-角色关联表
model SysUserRole {
  @@map("sys_user_roles")   // user < role（字母序）
}

// 正确：角色-菜单关联表
model SysRoleMenu {
  @@map("sys_role_menus")   // menu > role（字母序）
}

---

3. Prisma Model 层约定

3.1 Model 名 vs 数据库表名

Prisma Model 名使用大驼峰单数（TypeScript 标准风格），通过 @@map 映射到带前缀的数据库表名：

// Prisma Model（代码中使用）    →  数据库表（实际存储）
model User {                   →  @@map("sys_users")
model Session {                →  @@map("chat_sessions")
model ScheduledTask {          →  @@map("task_schedules")
}

关键原则: 表名重命名只改 @@map() 字符串，不改 Model 名和字段名。这样 TypeScript 代码零改动。

3.2 文件组织

每个新模块的 Prisma Model 应在 schema.prisma 中按模块分组，用注释分隔：

// ============================================
// sys_ 模块：系统基础
// ============================================
model User { ... }
model Role { ... }

// ============================================
// chat_ 模块：对话/Agent 核心
// ============================================
model Session { ... }

// ============================================
// fin_ 模块：金融系统（规划中）
// ============================================
// model FinAccount { ... }

7. 合规检查清单

在提交包含新表的 PR 时，请逐项确认：

• [ ] 表名以已注册的模块前缀开头
• [ ] 实体名称使用复数形式
• [ ] 全部字符为小写，单词间用下划线分隔
• [ ] 主键命名为 id
• [ ] 外键命名为 {referenced_table}_id
• [ ] 时间戳字段使用 created_at / updated_at
• [ ] 布尔字段使用 is_ 前缀
• [ ] schema.prisma 中按模块分组并添加注释分隔
• [ ] @@map() 与 Prisma Model 名不同（Model 用大驼峰，map 用带前缀的 snake_case）
• [ ] 本文档的前缀注册表已更新（如果是新模块）