# 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 迁移)。