junhong_cmp_fiber/openspec/changes/archive/2026-01-14-add-platform-role-management/proposal.md

Change: 平台角色管理功能增强

Why

现有的角色管理系统虽然已实现完整的 RBAC 功能，但缺少面向平台管理员的专用角色管理接口。当前接口设计为通用型（同时支持平台角色和客户角色），但在实际使用中，平台管理员主要管理平台角色（用于分配给平台用户），而客户角色的管理需求相对较少且需要单独的权限控制。

此外，权限分配时缺少对"哪些权限可以分配给平台角色"的明确过滤机制，导致在创建角色时可能分配不合适的权限。未来需要提供内部开发人员专用的权限配置接口，用于标记权限的可用角色类型。

What Changes

• ✅ 扩展 Permission 模型，增加 available_for_role_types 字段，用于标记权限可分配给哪些角色类型
• ✅ 修改权限列表查询接口，支持按 available_for_role_type 过滤
• ✅ 修改权限树查询接口，支持按 available_for_role_type 过滤
• ✅ 新增角色状态切换接口：PUT /api/admin/roles/:id/status
• ✅ 扩展角色列表查询，支持按 status 过滤
• ✅ 更新角色 Service 层，在分配权限时验证权限的 available_for_role_types
• ✅ 提供数据库迁移脚本，为现有权限设置默认值 1,2（兼容平台角色和客户角色）

注意：暂不实现权限配置接口（修改 available_for_role_types），该功能仅供内部开发人员手动修改数据库使用。

Impact

Affected specs:

• role-permission — 修改权限查询和角色权限分配的需求

Affected code:

• internal/model/permission.go — 增加 AvailableForRoleTypes 字段
• internal/model/permission_dto.go — 修改 PermissionListRequest，增加 AvailableForRoleType 查询参数
• internal/model/role_dto.go — 修改 RoleListRequest，增加 Status 查询参数；增加 UpdateRoleStatusRequest
• internal/store/postgres/permission_store.go — 修改 List() 和 GetAll() 方法，支持按 available_for_role_types 过滤
• internal/service/permission/service.go — 修改 List() 和 GetTree() 方法，支持新的过滤参数
• internal/service/role/service.go — 修改 AssignPermissions() 方法，验证权限的 available_for_role_types；增加 UpdateStatus() 方法
• internal/handler/admin/role.go — 增加 UpdateStatus() Handler
• internal/handler/admin/permission.go — 修改 List() 和 GetTree() Handler，支持新的查询参数
• internal/routes/role.go — 注册状态切换路由
• migrations/ — 增加迁移脚本：添加 available_for_role_types 字段

Breaking changes:

• 无

Database changes:

-- 添加 available_for_role_types 字段
ALTER TABLE tb_permission 
ADD COLUMN available_for_role_types VARCHAR(20) DEFAULT '1,2' 
COMMENT '可用角色类型 1=平台 2=客户';

-- 为现有权限设置默认值（兼容所有角色类型）
UPDATE tb_permission SET available_for_role_types = '1,2' WHERE available_for_role_types IS NULL;

Non-breaking enhancements:

• 权限列表查询新增可选参数 available_for_role_type
• 角色列表查询新增可选参数 status
• 新增角色状态切换接口 PUT /api/admin/roles/:id/status