# 权限矩阵与接口联调契约

## 一、管理端权限计算模型

管理页面和操作的最终可用性不是只看 `user_type`，而是四个条件的交集：

```text
终端适用范围 web/h5/all
        ∩
账号所绑定角色的菜单和按钮权限
        ∩
账号身份的硬性业务限制
        ∩
当前组织的数据范围
```

### 1.1 终端

权限记录包含 `platform`：

- `web`：只在管理 Web 登录时返回。
- `h5`：只在管理 H5 登录时返回。
- `all`：两端都返回。

### 1.2 角色

- 超级管理员不分配角色。
- 平台账号使用平台角色，可绑定多个。
- 代理和企业账号使用客户角色，最多绑定一个。
- 登录返回 `menus`、`buttons` 和兼容字段 `permissions`。

因此，“代理可用什么”应由给该代理账号绑定的客户角色决定，而不是维护一套固定代理菜单。

### 1.3 身份硬限制

角色权限不能突破组织身份的业务限制。例如：

- 企业账号即使错误分配了店铺菜单，也不应管理店铺。
- 企业账号不应访问代理资金、佣金、提现和代理充值。
- 代理账号不能越过本店及下级店铺的数据范围。
- 代理账号不能管理平台直属企业。
- 只有超管或平台管理身份可以维护支付、企微和全局系统配置。

### 1.4 数据范围

| 用户身份 | 组织字段 | 正常数据范围 |
| --- | --- | --- |
| 超级管理员 | 无 | 全平台 |
| 平台账号 | 无 | 全平台，但功能仍受角色权限控制 |
| 代理账号 | `shop_id` | 本店及全部下级店铺 |
| 企业账号 | `enterprise_id` | 本企业有效授权资产和本企业业务记录 |
| 个人客户 | `customer_id` | 本人绑定资产及本人订单、充值、通知 |

## 二、目标权限矩阵

下表是产品和安全目标，不代表当前每条后端接口都已完整实现。

图例：

- `权限控制`：角色有相应菜单/按钮且数据范围满足时可用。
- `范围受限`：可用，但只能处理当前组织范围。
- `只读建议`：首期只开放查询。
- `禁止`：角色配置也不得突破。

| 业务模块 | 超管 | 平台账号 | 代理账号 | 企业账号 | 个人客户 |
| --- | --- | --- | --- | --- | --- |
| 账号管理 | 全部 | 权限控制 | 范围受限 | 禁止 | 不适用 |
| 角色/权限配置 | 全部 | 权限控制 | 建议禁止 | 禁止 | 不适用 |
| 店铺管理 | 全部 | 权限控制 | 本店及下级、权限控制 | 禁止 | 不适用 |
| 企业管理 | 全部 | 权限控制 | 本店及下级企业、权限控制 | 只读本企业资料 | 不适用 |
| 企业资产授权 | 全部 | 权限控制 | 本店及下级企业、权限控制 | 只读本企业授权 | 不适用 |
| 卡/设备库存 | 全部 | 权限控制 | 本店及下级、权限控制 | 仅本企业授权资产 | 仅本人绑定资产 |
| 资产分配 | 全部 | 权限控制 | 通常仅直属下级、权限控制 | 禁止 | 禁止 |
| 资产状态与设备控制 | 全部 | 权限控制 | 范围受限、权限控制 | 本企业授权范围、权限控制 | 本人绑定范围 |
| 运营商配置 | 全部 | 权限控制 | 禁止 | 禁止 | 不适用 |
| 套餐系列/套餐设计 | 全部 | 权限控制 | 建议只读 | 禁止 | 只看可购投影 |
| 套餐授权/分配/定价 | 全部 | 权限控制 | 直属下级、权限控制 | 禁止 | 禁止 |
| 管理端订单 | 全部 | 权限控制 | 范围受限、权限控制 | 视业务角色决定 | 仅本人 C 端订单 |
| 退款/换货 | 全部 | 权限控制 | 范围受限、权限控制 | 只读建议 | C 端只提交换货收货信息 |
| 代理主钱包/佣金/提现 | 全部 | 权限控制 | 本店及下级、权限控制 | 禁止 | 不适用 |
| 代理充值 | 全部 | 权限控制 | 本店在线充值、权限控制 | 禁止 | 不适用 |
| 资产钱包 | 全部 | 权限控制 | 范围受限、权限控制 | 授权资产只读建议 | 本人绑定资产 |
| 导入/批量处理 | 全部 | 权限控制 | 范围受限、权限控制 | 禁止 | 禁止 |
| 导出 | 全部 | 权限控制 | 按数据范围导出 | 只导本企业且需明确开放 | 禁止 |
| 微信/支付宝/企微配置 | 全部 | 权限控制 | 禁止 | 禁止 | 禁止 |
| 轮询、告警、清理 | 全部 | 权限控制 | 只读建议 | 禁止 | 禁止 |
| 通知 | 全部 | 当前账号 | 当前账号 | 当前账号 | 当前客户 |

## 三、统一认证契约

### 3.1 管理 Web/H5 登录

```http
POST /api/auth/login
Content-Type: application/json
```

```json
{
  "username": "账号或手机号",
  "password": "密码",
  "device": "web"
}
```

管理 H5 将 `device` 改为 `h5`。

成功后保存：

```json
{
  "access_token": "...",
  "refresh_token": "...",
  "expires_in": 86400,
  "user": {
    "id": 1,
    "username": "admin",
    "user_type": 2,
    "user_type_name": "平台用户",
    "shop_id": 0,
    "enterprise_id": 0
  },
  "menus": [],
  "buttons": [],
  "permissions": []
}
```

所有受保护请求携带：

```http
Authorization: Bearer <access_token>
```

### 3.2 Token 刷新

```http
POST /api/auth/refresh-token
```

```json
{
  "refresh_token": "..."
}
```

前端请求模块需要实现单次刷新队列：多个并发请求同时收到 401 时，只允许一个请求刷新 Token，其余等待结果；刷新失败统一清除会话并跳转登录。

### 3.3 C 端认证

C 端使用 `/api/c/v1/auth/*`，不使用管理端登录或刷新 Token：

1. `verify-asset`。
2. `wechat-login` 或 `miniapp-login`。
3. 必要时 `bind-phone`。
4. 后续请求携带 C 端 Bearer Token。
5. 认证失效重新走资产验证和微信登录。

## 四、响应与错误契约

### 4.1 统一响应

```json
{
  "code": 0,
  "msg": "success",
  "data": {},
  "timestamp": "2026-07-29T12:00:00+08:00"
}
```

前端成功判断必须同时尊重 HTTP 状态和业务 `code`，不能只判断 HTTP 200。

### 4.2 分页

常见请求参数为 `page`、`page_size`，常见返回为：

```json
{
  "items": [],
  "total": 0,
  "page": 1,
  "size": 20
}
```

不同历史模块的列表 DTO 可能有差异，类型生成和页面开发必须以对应 OpenAPI Operation 为准，不能强制假设所有列表结构完全相同。

### 4.3 HTTP 错误处理

| HTTP 状态 | 前端行为 |
| --- | --- |
| 400 | 定位请求字段，展示后端安全中文提示 |
| 401 | 管理端尝试刷新；C 端重新登录 |
| 403 | 显示无权限，不重试，不猜测资源是否存在 |
| 404 | 显示资源不存在或已失效 |
| 409 | 提示状态已变化，重新拉取详情 |
| 429 | 提示操作频繁，按 `Retry-After` 或短时退避 |
| 5xx | 展示通用错误和 Request ID，允许用户手动重试 |

## 五、数据展示契约

- 金额：接口整数单位通常为分，展示时格式化为元，提交时转换回分；禁止浮点数直接参与计算。
- 状态：优先使用响应中的 `status_name`、`*_name`，不要在多个前端重复维护中文枚举。
- 时间：按 ISO 8601 解析，统一展示为当前业务时区；提交日期范围按接口约定处理起止边界。
- ID：前端将 ID 当作不透明标识，不参与金额或业务计算。
- 空值：区分 `null`、空字符串、0 和空数组，不能用统一假值替换。
- 资产标识：按字符串保存和上传，避免 ICCID 被转为科学计数法或丢失前导零。
- 支付方式：使用 `allowed_payment_methods` 或支付方式查询接口，不写死微信/支付宝/钱包组合。
- 状态流转：按钮是否出现先看权限和当前状态；提交后仍以后端状态机结果为准。

## 六、关键接口调用顺序

### 6.1 管理端创建订单

1. 解析或选择资产。
2. 查询资产可用套餐。
3. `POST /api/admin/orders/purchase-check`。
4. 展示后端计算的购买条件、金额和支付方式。
5. `POST /api/admin/orders`。
6. 查询订单详情确认最终状态。

### 6.2 代理在线充值

1. `GET /api/admin/agent-recharges/payment-methods`。
2. `POST /api/admin/agent-recharges`。
3. 按响应拉起支付。
4. 轮询 `GET /api/admin/agent-recharges/:id/payment-status`。
5. 查询详情和主钱包流水确认到账。

### 6.3 企业资产授权

1. 查询企业详情。
2. 查询候选卡或设备。
3. 提交 `allocate-cards` 或 `allocate-devices`。
4. 重新查询企业卡/设备列表。
5. 查询授权记录确认结果。

设备授权由后端同步处理绑定卡，前端不得自行拆分请求。

### 6.4 文件上传和异步任务

1. `POST /api/admin/storage/upload-url`。
2. 直接向响应的对象存储 URL 上传。
3. 将 `file_key` 提交业务任务接口。
4. 轮询任务详情。
5. 完成后展示结果或下载文件。

### 6.5 第三方支付

1. 创建业务订单或充值单。
2. 使用后端返回的支付参数/链接拉起支付。
3. 支付平台回调只由服务端接收，前端不得调用 `/api/callback/*`。
4. 用户返回页面后重新查询业务单状态。
5. 结果未知时保持“处理中”，不在前端直接改为成功。

## 七、管理 Web/H5 的路由和权限约定

1. 登录后以 `menus[].url` 建立可访问路由白名单。
2. 路由守卫同时检查登录状态和菜单权限。
3. 按钮组件检查 `buttons`，但按钮隐藏只负责体验，不是安全门禁。
4. Web/H5 使用同一权限码，不创建 `web_xxx`、`h5_xxx` 两套业务权限码；终端差异使用权限记录的 `platform` 字段。
5. 不给当前终端返回的菜单不得通过手输 URL 进入。
6. 页面加载收到 403 后应移除当前不可用操作并提示重新登录获取最新权限。

## 八、联调验收矩阵

每个管理接口至少使用以下账号验证：

| 用例 | 超管 | 有权限平台 | 无权限平台 | 有权限代理 | 越权代理 | 企业账号 |
| --- | --- | --- | --- | --- | --- | --- |
| 菜单是否返回 | 验证 | 验证 | 不返回 | 验证 | 验证 | 验证 |
| 页面能否进入 | 验证 | 验证 | 禁止 | 验证 | 视权限 | 视权限 |
| API 能否调用 | 验证 | 验证 | 403 | 验证 | 403/空范围 | 仅目标能力 |
| 列表数据范围 | 全部 | 全部 | 无调用 | 本店及下级 | 不含平级/上级 | 仅本企业 |
| 详情越权 | 可见 | 可见 | 403 | 非范围资源 403 | 403 | 非本企业 403 |
| 写操作越权 | 可操作 | 按权限 | 403 | 仅允许范围 | 403 | 仅明确开放能力 |

C 端接口至少覆盖：本人绑定资产、本人未绑定资产、其他客户订单、Token 被新登录替换、资产解绑、店铺禁止新 C 端登录。

## 九、当前后端安全缺口

以下问题是上线门禁，不应交给前端规避：

1. `/api/admin` 当前统一挂载认证中间件，但没有发现逐路由普遍挂载 `RequirePermission`。
2. 当前 `menus/buttons` 主要用于前端显示，不能证明每个接口已做相同权限校验。
3. 部分接口明确说明按钮权限不在后端校验。
4. 企业账号没有店铺下级范围，部分使用宽松店铺过滤的查询可能需要专项验证。
5. 企业、企业授权、卡和设备列表需要使用真实企业 Token 做越权测试。

前端可以按权限正确隐藏界面，但生产上线前必须由后端补齐或验证：

- 功能权限门禁。
- 资源级权限校验。
- 企业数据范围。
- 写操作状态机和幂等。
- 敏感配置和高风险动作的身份限制。

## 十、联调权威来源

1. 路由和 DTO：`internal/routes`、`internal/model/dto`。
2. 机器可读契约：`docs/admin-openapi.yaml`。
3. 业务和页面组合：`docs/前端建设`。
4. 七月迭代新增字段：`docs/7月迭代/七月迭代实现与接口对接说明.md`。

发现接口与 OpenAPI 不一致时，先修正文档生成器和 DTO，不在前端编写长期兼容分支掩盖契约问题。