EMS_Platform/AI_DEVELOPMENT_RULES.md

AI 辅助开发规范 (AI Development Rules)

请在每次开启新对话或进行功能开发时，首先读取并遵循本文件中的规则。

1. 核心原则：数据库变更必须代码化 (Database Schema & Data Migration)

本项目严格采用 版本化迁移 (Schema & Data Migration) 管理数据库结构及关键初始化数据，严禁依赖 ORM 的自动同步 (AutoMigrate) 或手动修改数据库。

⚠️ 数据库变更流程 (必须严格执行)

当你的开发任务涉及数据库修改（如：新增表、字段、索引）或关键初始化数据变更（如：预置角色、管理员账号）时，必须按以下步骤操作：

1. 检查当前版本：查看 backend/db/migrations/ 目录下现有的最大序号文件 (e.g., 000001_init.up.sql)。
2. 创建迁移文件：
   • 路径：backend/db/migrations/
   • 命名格式：{6位数字序号}_{简短描述}.up.sql
   • 示例：如果当前是 000001，且需要添加设备维护时间，则新建 000002_add_maintenance_time.up.sql。
3. 编写 SQL：在新建的文件中编写标准的 PostgreSQL DDL 语句 (CREATE TABLE, ALTER TABLE 等)。
4. 同步 Go 模型：修改 backend/models 下对应的 struct 定义，确保 gorm 标签与数据库结构一致。

❌ 禁止行为

• 禁止 仅修改 Go Struct 而不创建 SQL 迁移文件。
• 禁止 假设 AutoMigrate 会自动处理字段变更（生产环境不使用 AutoMigrate）。
• 禁止 编写破坏性 SQL（如 DROP COLUMN）除非用户明确确认。

---

2. 目录结构规范 (Directory Structure)

保持当前的运维目录结构，所有新增配置或脚本应放入对应目录：

• backend/ : Golang 后端代码
• frontend/ : Vue 前端代码
• configs/ : 配置文件挂载源 (Nginx, EMQX 等)
• data/ : (忽略) 本地数据持久化目录，不要提交到 git
• scripts/ : 运维脚本 (备份, 恢复等)
• docker-compose.yaml : 服务编排

3. 编码习惯 (Coding Standards)

• 语言：与用户交流使用 中文。
• 代码注释：关键逻辑必须添加注释。
• 配置文件：涉及敏感信息（密码、密钥）必须通过环境变量传入，参考 .env 和 docker-compose.yaml。

---

4. 常用命令参考

• 添加 Go 依赖：修改代码后运行 go mod tidy。
• 启动服务：docker-compose up -d --build (会自动执行新的 SQL 迁移)。