one-pipe-system/openspec/changes/add-shop-default-roles/specs/shop-management/spec.md

Shop Management - Specification Delta

ADDED Requirements

Requirement: Query Shop Default Roles

系统SHALL支持查询指定店铺的默认角色列表。

API端点: GET /api/admin/shops/{shop_id}/roles

路径参数:

• shop_id (integer, required): 店铺ID

响应数据:

{
  shop_id: number         // 店铺ID
  roles: ShopRole[] | null  // 角色列表
}

interface ShopRole {
  role_id: number      // 角色ID
  role_name: string    // 角色名称
  role_desc: string    // 角色描述
  shop_id: number      // 店铺ID
  status: number       // 状态 (0:禁用, 1:启用)
}

Scenario: 成功查询店铺默认角色

• WHEN 用户请求获取店铺ID为123的默认角色列表
• THEN 系统返回该店铺配置的所有默认角色
• AND 响应包含角色ID、名称、描述、状态等完整信息

Scenario: 查询不存在的店铺

• WHEN 用户请求获取不存在的店铺的默认角色
• THEN 系统返回400错误
• AND 错误消息说明店铺不存在

Scenario: 店铺没有配置默认角色

• WHEN 用户请求获取未配置默认角色的店铺
• THEN 系统返回成功响应
• AND roles 字段为空数组或null

---

Requirement: Assign Shop Default Roles

系统SHALL支持为指定店铺分配一个或多个默认角色。

API端点: POST /api/admin/shops/{shop_id}/roles

路径参数:

• shop_id (integer, required): 店铺ID

请求体:

{
  role_ids: number[] | null  // 角色ID列表
}

响应数据: 与"Query Shop Default Roles"相同的数据结构

Scenario: 成功分配单个默认角色

• WHEN 用户为店铺分配一个新的默认角色
• THEN 系统成功保存该角色配置
• AND 返回更新后的店铺默认角色列表
• AND 新分配的角色出现在列表中

Scenario: 成功分配多个默认角色

• WHEN 用户为店铺分配多个默认角色
• THEN 系统批量保存所有角色配置
• AND 返回完整的默认角色列表
• AND 所有新分配的角色都出现在列表中

Scenario: 分配已存在的角色

• WHEN 用户尝试分配店铺已配置的默认角色
• THEN 系统应当优雅处理(不重复添加或返回明确提示)
• AND 不影响其他正常角色的分配

Scenario: 分配不存在的角色

• WHEN 用户尝试分配不存在的角色ID
• THEN 系统返回400错误
• AND 错误消息说明哪些角色ID无效

Scenario: 空角色列表

• WHEN 用户提交空的角色ID列表
• THEN 系统接受请求
• AND 可能清空当前默认角色或保持不变(取决于业务需求)

---

Requirement: Delete Shop Default Role

系统SHALL支持删除指定店铺的某个默认角色配置。

API端点: DELETE /api/admin/shops/{shop_id}/roles/{role_id}

路径参数:

• shop_id (integer, required): 店铺ID
• role_id (integer, required): 角色ID

响应: 标准成功/错误响应

Scenario: 成功删除默认角色

• WHEN 用户删除店铺的一个默认角色配置
• THEN 系统成功移除该角色配置
• AND 返回成功响应(code: 0)
• AND 后续查询该店铺默认角色列表时不再包含该角色

Scenario: 删除不存在的角色配置

• WHEN 用户尝试删除店铺未配置的角色
• THEN 系统返回400错误
• AND 错误消息说明该角色不在店铺的默认角色列表中

Scenario: 删除不存在的店铺或角色

• WHEN 用户使用无效的shop_id或role_id
• THEN 系统返回400错误
• AND 错误消息说明参数无效

---

Requirement: Shop Default Roles UI

店铺管理页面SHALL提供默认角色管理的用户界面。

Scenario: 在店铺列表中访问默认角色设置

• WHEN 用户在店铺管理列表页查看店铺列表
• THEN 每个店铺的操作列应当包含"设置默认角色"按钮或菜单项
• AND 点击后打开默认角色管理对话框

Scenario: 查看店铺当前默认角色

• WHEN 用户打开某店铺的默认角色管理对话框
• THEN 对话框显示该店铺当前已配置的所有默认角色
• AND 每个角色显示名称、描述和状态
• AND 提供删除按钮用于移除默认角色

Scenario: 添加默认角色

• WHEN 用户在对话框中选择要添加的角色
• THEN 系统提供角色选择器,展示可用的系统角色列表
• AND 支持多选
• AND 点击确认后调用分配接口
• AND 成功后刷新默认角色列表

Scenario: 删除默认角色

• WHEN 用户点击某个默认角色的删除按钮
• THEN 系统显示确认对话框
• AND 用户确认后调用删除接口
• AND 成功后从列表中移除该角色

Scenario: 加载状态和错误处理

• WHEN 进行任何API操作时
• THEN 界面应当显示加载状态(loading indicator)
• AND 如果操作失败,应当显示友好的错误消息
• AND 允许用户重试或关闭对话框