# 店铺级角色继承功能提案

## Why

当前系统的角色分配是账号级别的，平台需要为每个代理店铺的每个账号逐一分配角色。在 MVP 阶段，一个店铺内的所有账号权限通常是一致的（如 10 个员工都是"代理店长"角色），逐个分配造成了不必要的操作负担。本变更通过引入店铺级角色继承机制，允许平台在店铺层面设置默认角色，该店铺下所有账号自动继承，同时保留账号级覆盖能力以支持未来的权限差异化需求。

## What Changes

- **新增店铺级角色管理功能**：平台可为代理店铺设置默认角色，该店铺下所有账号自动继承
- **账号级角色覆盖机制**：特殊账号可单独设置角色，覆盖店铺默认角色
- **角色解析逻辑升级**：权限检查时优先查找账号级角色，如无则继承店铺级角色
- **新增数据库表**：`tb_shop_role` 用于存储店铺-角色关联关系
- **新增 API 接口**：`POST/GET/DELETE /api/admin/shops/:id/roles` 用于管理店铺角色
- **适用范围限定**：仅适用于代理账号（UserType=3），企业账号和平台账号保持现状（账号级角色）

## Capabilities

### New Capabilities
- `shop-role-management`: 店铺级角色管理能力，包括为店铺分配角色、查询店铺角色、删除店铺角色等功能

### Modified Capabilities
- `rbac-permission-check`: 角色权限检查能力需要修改，增加店铺级角色继承逻辑，权限解析时需要支持"账号角色优先，无则继承店铺角色"的规则

## Impact

### 数据库层
- **新增表**：`tb_shop_role`（店铺-角色关联表）
- **保留表**：`tb_account_role`（向后兼容）

### 代码模块
- **新增**：
  - `internal/model/shop_role.go`（ShopRole 模型）
  - `internal/store/postgres/shop_role_store.go`（ShopRoleStore 数据访问层）
  - `internal/service/shop/shop_role.go`（店铺角色业务逻辑）
  - `internal/handler/admin/shop_role.go`（店铺角色 HTTP 处理器）
  - `internal/model/dto/shop_role_dto.go`（店铺角色 DTO）
- **修改**：
  - `internal/service/account/role_resolver.go`（新增角色解析逻辑）
  - `internal/service/permission/service.go`（修改权限检查，使用新的角色解析）
  - `internal/routes/shop.go`（注册店铺角色路由）
  - `internal/bootstrap/stores.go`（注册 ShopRoleStore）
  - `internal/bootstrap/handlers.go`（注册 ShopRoleHandler）

### API 接口
- **新增**：
  - `POST /api/admin/shops/:shop_id/roles`（分配店铺角色）
  - `GET /api/admin/shops/:shop_id/roles`（查询店铺角色）
  - `DELETE /api/admin/shops/:shop_id/roles/:role_id`（删除店铺角色）
- **行为变更**：
  - `GET /api/admin/accounts/:id/roles`（查询账号角色时，返回结果可能包含继承的店铺角色，需要标识来源）

### 用户类型影响范围
- **代理账号（UserType=3）**：受影响，支持继承店铺角色
- **平台账号（UserType=2）**：不受影响，保持账号级角色
- **企业账号（UserType=4）**：不受影响，保持账号级角色
- **超级管理员（UserType=1）**：不受影响，跳过权限检查
- **个人客户（UserType=5）**：不受影响，无角色系统

### 性能考虑
- 角色解析增加一次额外查询（查询店铺角色），但通过 Redis 缓存权限结果（30 分钟），性能影响可忽略
- 店铺角色修改时需清理该店铺下所有账号的权限缓存

### 向后兼容性
- ✅ 完全向后兼容：保留 `tb_account_role` 表和现有逻辑
- ✅ 现有账号级角色不受影响，优先级高于店铺级角色
- ✅ 不设置店铺角色的店铺，行为与现在完全一致