---
description: "Hyperf ORM + MySQL 数据库规范 — Schema 设计/迁移/查询优化/高并发"
globs:
  - "**/*.sql"
  - "Case-Database-Backend/**/*.php"
  - "Case-Database-Backend/database/migrations/**"
  - "Case-Database-Backend/database/seeders/**"
  - "Case-Database-Backend/modules/**/database/migrations/**"
  - "Case-Database-Backend/modules/**/database/seeders/**"
  - "Case-Database-Backend/app/Model/**"
  - "Case-Database-Backend/config/autoload/databases.php"
alwaysApply: false
---

# 🗄️ Hyperf ORM + MySQL Database Standards (Core)

参考文档: @docs/architecture/data-model.md

## 核心原则

- 所有 schema 变更必须通过 Migration 执行
- 高风险变更采用 Expand-Contract，不做一次性破坏升级
- 查询默认参数化，避免拼接 SQL
- 大表变更先评估锁表风险与回滚路径
- 读写分层：Controller 不直接操作 Model

## 表命名规范（模块前缀）

**表名必须以所属模块名作为前缀**，格式：`<module>_<entity_plural>`。

| 模块 | 前缀 | 示例 |
|------|------|------|
| 用户与权限 | `auth_` | `auth_users`, `auth_roles` |
| 案例核心 | `case_` | `case_cases`, `case_images` |
| 设计师 | `designer_` | `designer_profiles`, `designer_awards` |
| 运营内容 | `operation_` | `operation_banners`, `operation_topics` |
| 用户互动 | `interaction_` | `interaction_favorites`, `interaction_comments` |
| 日志 | `log_` | `log_user_logins`, `log_downloads` |
| 安全风控 | `security_` | `security_blacklists`, `security_risk_events` |
| 系统配置 | `system_` | `system_configs` |

> 多对多关联表同样需要加模块前缀，以主体模块为准：`<module>_<a>_belongs_<b>`。

## 文件目录约定

- **根目录**（兜底，用于跨模块全局迁移/种子）：
  - `Case-Database-Backend/database/migrations/` — MigratorFactory 自动扫描
  - `Case-Database-Backend/database/seeders/` — SeedFactory 自动扫描
- **模块目录**（按模块归属）：
  - `Case-Database-Backend/modules/<Module>/database/migrations/` — 该模块迁移
  - `Case-Database-Backend/modules/<Module>/database/seeders/` — 该模块种子

执行 `migrate` / `db:seed` 时，MigratorFactory / SeedFactory 会扫描根目录 + 所有 `modules/*/database/migrations` 与 `modules/*/database/seeders`，无需额外配置。

## 迁移最小流程

1. 明确需求与回滚方案（必填）
2. 生成 migration（命名可读，幂等）：`gen:migration` 自动写入 `database/migrations/`
3. 本地执行 migrate + rollback 演练
4. 校验索引、默认值、nullability 与历史数据兼容
5. 更新文档（字段、索引、业务约束）

## 查询与索引约束

- 高频筛选列必须有索引；复合索引按最左前缀设计
- 分页使用稳定排序（主键兜底）
- 禁止 `SELECT *` 用于高频路径
- 避免 N+1；需要时使用 eager loading

## 安全与合规

- 敏感字段加密或脱敏存储
- 生产环境禁止临时 SQL 脚本直改
- 迁移文件要可审计、可回放

## 验证清单

- [ ] migration 可执行且可回滚
- [ ] 关键查询通过 explain 检查
- [ ] 新增/变更字段有兼容策略
- [ ] 文档已同步

## Tier 3 深度参考

- `.cursor/rules/references/014-database-deep.md` — 完整数据库规范与示例