feat(role): 新增平台角色管理功能增强

- 权限表增加 available_for_role_types 字段，支持标记权限可用角色类型
- 权限列表和权限树接口支持按 available_for_role_type 过滤
- 新增角色状态切换接口 PUT /api/admin/roles/:id/status
- 角色分配权限时验证权限的可用角色类型
- 完善数据库迁移脚本和单元测试
- 补充数据库迁移相关开发规范文档

AGENTS.md

@@ -189,6 +189,185 @@ func (ModelName) TableName() string {
 - 包含: method, path, query, status, duration, request_id, ip, user_agent, user_id, bodies
 - 使用 JSON 格式，配置自动轮转
 
+## 数据库迁移
+
+### 迁移工具
+
+项目使用 **golang-migrate** 进行数据库迁移管理。
+
+### 基本命令
+
+```bash
+# 查看当前迁移版本
+make migrate-version
+
+# 执行所有待迁移
+make migrate-up
+
+# 回滚上一次迁移
+make migrate-down
+
+# 创建新迁移文件
+make migrate-create
+# 然后输入迁移名称，例如: add_user_email
+```
+
+### 迁移文件规范
+
+迁移文件位于 `migrations/` 目录：
+
+```
+migrations/
+├── 000001_initial_schema.up.sql
+├── 000001_initial_schema.down.sql
+├── 000002_add_user_email.up.sql
+├── 000002_add_user_email.down.sql
+```
+
+**命名规范**:
+- 格式: `{序号}_{描述}.{up|down}.sql`
+- 序号: 6位数字，从 000001 开始
+- 描述: 小写英文，用下划线分隔
+- up: 应用迁移（向前）
+- down: 回滚迁移（向后）
+
+**编写规范**:
+
+```sql
+-- up.sql 示例
+-- 添加字段时必须考虑向后兼容
+ALTER TABLE tb_users 
+ADD COLUMN email VARCHAR(100);
+
+-- 添加注释
+COMMENT ON COLUMN tb_users.email IS '用户邮箱';
+
+-- 为现有数据设置默认值（如果需要）
+UPDATE tb_users SET email = '' WHERE email IS NULL;
+
+-- down.sql 示例
+ALTER TABLE tb_users 
+DROP COLUMN IF EXISTS email;
+```
+
+### 迁移执行流程（必须遵守）
+
+当你创建迁移文件后，**必须**执行以下验证步骤：
+
+1. **执行迁移**:
+   ```bash
+   make migrate-up
+   ```
+
+2. **验证迁移状态**:
+   ```bash
+   make migrate-version
+   # 确认版本号已更新且 dirty=false
+   ```
+
+3. **验证数据库结构**:
+   使用 PostgreSQL MCP 工具检查：
+   - 字段是否正确创建
+   - 类型是否符合预期
+   - 默认值是否正确
+   - 注释是否存在
+
+4. **验证查询功能**:
+   编写临时脚本测试新字段的查询功能
+
+5. **更新 Model**:
+   在 `internal/model/` 中添加对应字段
+
+6. **清理测试数据**:
+   如果插入了测试数据，记得清理
+
+### 迁移失败处理
+
+如果迁移执行失败，数据库会被标记为 dirty 状态：
+
+```bash
+# 1. 检查错误原因
+make migrate-version
+# 如果显示 dirty=true，说明迁移失败
+
+# 2. 手动修复数据库状态
+# 使用 PostgreSQL MCP 连接数据库
+# 检查失败的迁移是否部分执行
+# 手动清理或完成迁移
+
+# 3. 清除 dirty 标记
+UPDATE schema_migrations SET dirty = false WHERE version = {失败的版本号};
+
+# 4. 修复迁移文件中的错误
+
+# 5. 重新执行迁移
+make migrate-up
+```
+
+### 使用 PostgreSQL MCP 访问数据库
+
+项目配置了 PostgreSQL MCP 工具，用于直接访问和查询数据库。
+
+**可用工具**:
+
+1. **查看表结构**:
+   ```
+   PostgresGetObjectDetails: 
+   - schema_name: "public"
+   - object_name: "tb_permission"
+   - object_type: "table"
+   ```
+
+2. **列出所有表**:
+   ```
+   PostgresListObjects:
+   - schema_name: "public"
+   - object_type: "table"
+   ```
+
+3. **执行查询**:
+   ```
+   PostgresExecuteSql:
+   - sql: "SELECT * FROM tb_permission LIMIT 5"
+   ```
+
+**使用场景**:
+- ✅ 验证迁移是否成功执行
+- ✅ 检查字段类型、默认值、约束
+- ✅ 查看现有数据
+- ✅ 测试新增字段的查询功能
+- ✅ 调试数据库问题
+
+**注意事项**:
+- ⚠️ MCP 工具只支持只读查询（SELECT）
+- ⚠️ 不要直接修改数据，修改必须通过迁移文件
+- ⚠️ 测试数据可以通过临时 Go 脚本插入
+
+### 迁移最佳实践
+
+1. **向后兼容**:
+   - 添加字段时使用 `DEFAULT` 或允许 NULL
+   - 删除字段前确保代码已不再使用
+   - 修改字段类型要考虑数据转换
+
+2. **原子性**:
+   - 每个迁移文件只做一件事
+   - 复杂变更拆分成多个迁移
+
+3. **可回滚**:
+   - down.sql 必须能完整回滚 up.sql 的所有变更
+   - 测试回滚功能: `make migrate-down && make migrate-up`
+
+4. **注释完整**:
+   - 迁移文件顶部说明变更原因
+   - 关键 SQL 添加行内注释
+   - 数据库字段使用 COMMENT 添加说明
+
+5. **测试数据**:
+   - 不要在迁移文件中插入业务数据
+   - 可以插入配置数据或枚举值
+   - 测试数据用临时脚本处理
+
 ## OpenSpec 工作流
 
 创建提案前的检查清单：