86 lines
3.2 KiB
Plaintext
86 lines
3.2 KiB
Plaintext
---
|
||
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` — 完整数据库规范与示例
|