111

docs/前端建设/管理端页面接口矩阵.md

@@ -0,0 +1,186 @@
+# 管理 Web 与管理 H5 页面接口矩阵
+
+> 本文描述页面需要承载的业务信息和接口组合。完整请求、响应字段、校验规则和枚举以 [`docs/admin-openapi.yaml`](../admin-openapi.yaml) 为准。
+
+## 一、页面生成原则
+
+管理 Web 和管理 H5 都允许超级管理员、平台账号、代理账号、企业账号登录，但不按账号类型写死整套路由。
+
+登录后按以下顺序生成可用界面：
+
+1. 使用 `user.user_type` 确定组织身份和数据范围提示。
+2. 使用后端返回的 `menus` 生成路由和导航。
+3. 使用 `buttons` 控制创建、编辑、删除、审核等操作入口。
+4. 服务端返回 403 时仍必须阻止操作，不能因为前端存在按钮就认为有权限。
+5. Web 登录传 `device=web`，管理 H5 登录传 `device=h5`。
+
+管理 H5 不建议机械复制全部 Web 表格。首期应覆盖查询、现场操作、审批和通知；复杂配置、批量导入和大报表优先保留在 Web。
+
+## 二、公共页面
+
+| 页面 | Web | 管理 H5 | 核心字段 | 主要操作 | 接口 |
+| --- | --- | --- | --- | --- | --- |
+| 登录 | 必须 | 必须 | 用户名/手机号、密码、终端 | 登录、记住账号 | `POST /api/auth/login` |
+| 当前账号 | 必须 | 必须 | 用户名、手机号、用户类型、店铺、企业 | 查看当前身份 | `GET /api/auth/me` |
+| 修改密码 | 必须 | 必须 | 旧密码、新密码、确认密码 | 修改并重新登录 | `PUT /api/auth/password` |
+| 通知中心 | 必须 | 必须 | 类型、标题、内容、风险、关联资源、时间、已读状态 | 查看目标、单条已读、全部已读 | `/api/admin/notifications/*` |
+| 退出登录 | 必须 | 必须 | 无 | 注销 Token | `POST /api/auth/logout` |
+
+登录响应需持久化：`access_token`、`refresh_token`、`expires_in`、`user`、`menus`、`buttons`、`permissions`。权限变更后菜单不会自动刷新，应重新登录或提供“刷新会话”动作。
+
+## 三、工作台建议
+
+当前后端没有统一 Dashboard 接口。首期不要为了首页一次性改造后端，可使用现有轻量接口拼装：
+
+| 卡片 | 数据来源 | 适用说明 |
+| --- | --- | --- |
+| 未读通知 | `GET /api/admin/notifications/unread-summary` | 所有具备通知菜单的账号 |
+| 代理资金概况 | `GET /api/admin/shops/fund-summary` | 具备代理资金菜单且非企业账号 |
+| 临期资产 | `GET /api/admin/expiring-assets` | 具备资产/套餐运营权限的账号 |
+| 轮询状态 | `GET /api/admin/polling-stats` | 运维角色，优先 Web |
+| 待处理退款 | `GET /api/admin/refunds` | 使用状态筛选，具体权限由菜单和服务端决定 |
+| 待处理换货 | `GET /api/admin/exchanges` | 使用状态筛选 |
+
+页面加载时各卡片独立失败、独立重试，不能因一个无权限卡片导致整个工作台失败。
+
+## 四、组织与权限
+
+### 4.1 账号管理
+
+| 页面 | 主要查询字段 | 列表/详情字段 | 操作 | 接口 | H5建议 |
+| --- | --- | --- | --- | --- | --- |
+| 账号列表 | 用户名、手机号、用户类型、状态、店铺、企业、分页 | 用户名、手机号、用户类型名称、所属店铺/企业、状态名称、企微绑定状态、创建时间 | 新建、编辑、启停、重置密码、删除、分配角色、绑定企微 | `/api/admin/accounts*` | 查询和启停可做；复杂角色分配优先 Web |
+
+表单关键规则：
+
+- 平台账号不关联店铺或企业。
+- 代理账号关联 `shop_id`。
+- 企业账号关联 `enterprise_id`。
+- 超级管理员不分配角色；平台账号可多角色；代理和企业账号最多一个客户角色。
+
+### 4.2 角色与权限
+
+| 页面 | 核心字段 | 操作 | 接口 | H5建议 |
+| --- | --- | --- | --- | --- |
+| 角色列表/编辑 | 角色名、角色类型、状态、默认信用额度 | 新建、编辑、启停、删除 | `/api/admin/roles*` | 只读或不做 |
+| 角色权限配置 | 权限树、终端 `web/h5/all`、菜单/按钮类型 | 分配、单项移除、批量移除 | `/api/admin/roles/:id/permissions*` | 不做 |
+| 权限管理 | 权限名、权限码、菜单/按钮类型、适用终端、父级、路由、排序、状态 | 新建、编辑、删除 | `/api/admin/permissions*` | 不做 |
+
+权限记录的 `available_for_role_types` 区分平台角色和客户角色；代理、企业均使用客户角色，不应按“代理端菜单”硬编码。
+
+### 4.3 店铺
+
+| 页面 | 主要查询字段 | 列表/详情字段 | 操作 | 接口 | H5建议 |
+| --- | --- | --- | --- | --- | --- |
+| 店铺列表 | 关键词、店铺编号、联系人手机号、状态、层级、父店铺、分页 | 店铺名、编号、层级、上级、联系人、地址、业务员、状态、C端登录限制 | 创建、编辑、删除、查看详情 | `GET|POST /api/admin/shops`、`GET|PUT|DELETE /api/admin/shops/:id` | 列表、详情可做；复杂建档优先 Web |
+| 店铺级联选择 | 关键词、父节点 | 店铺 ID、名称、层级、子节点 | 选择目标店铺 | `GET /api/admin/shops/cascade` | 必须复用 |
+| 店铺默认角色 | 店铺 ID | 已分配客户角色 | 分配、移除 | `/api/admin/shops/:shop_id/roles*` | 不做或只读 |
+| 店铺授信 | 店铺 ID | 现金余额、信用额度、总可用、欠款 | 调整信用额度 | `PUT /api/admin/shops/:id/credit-limit` | 可做但必须二次确认 |
+
+企业账号不得进入店铺管理。代理账号只允许管理本店及下级店铺，能否创建和修改仍取决于菜单、按钮和服务端校验。
+
+## 五、企业与授权
+
+| 页面 | 主要查询字段 | 列表/详情字段 | 操作 | 接口 | H5建议 |
+| --- | --- | --- | --- | --- | --- |
+| 企业列表 | 名称、编号、联系人、状态、归属店铺、分页 | 企业名、编号、归属店铺、联系人、地址、状态、企业账号 | 创建、编辑、启停、重置企业密码 | `/api/admin/enterprises*` | 查询和详情可做 |
+| 企业卡授权 | 企业 ID、卡关键词、状态、分页 | ICCID/虚拟号、运营商、归属店铺、授权状态、授权时间 | 分配、回收 | `/api/admin/enterprises/:id/allocate-cards`、`recall-cards`、`cards` | 现场授权可做 |
+| 企业设备授权 | 企业 ID、设备关键词、状态、分页 | 虚拟号、IMEI、SN、型号、归属店铺、授权状态、绑定卡 | 分配、回收 | `/api/admin/enterprises/:id/allocate-devices`、`recall-devices`、`devices` | 现场授权可做 |
+| 授权记录 | 企业、资产类型、资产标识、授权状态、时间、分页 | 企业、资产摘要、授权人、授权时间、回收人、回收时间、备注 | 详情、修改备注 | `/api/admin/authorizations*` | 列表和详情可做 |
+
+企业授权不改变卡或设备的店铺归属。设备授权时，后端会同步处理其绑定卡；前端只提交设备选择结果，不自行拆成多次卡授权。
+
+## 六、资产
+
+### 6.1 统一资产工作台
+
+| 页面 | 输入/筛选 | 需要展示 | 操作 | 接口 | H5建议 |
+| --- | --- | --- | --- | --- | --- |
+| 资产快速查询 | ICCID、虚拟号、MSISDN、IMEI、SN | 资产类型、主标识、归属店铺、企业授权、业务状态、网络状态、实名、当前套餐、余额、换货链 | 进入详情 | `GET /api/admin/assets/resolve/:identifier` | 必须 |
+| 资产详情 | 资产标识 | 实时状态、套餐、当前套餐、钱包、订单、操作日志 | 刷新、停机、复机、停用、修改实名/轮询、调整套餐用量/到期时间 | `/api/admin/assets/:identifier/*` | 必须，但高风险动作二次确认 |
+| 分配记录 | 单号、资产类型、来源、目标、状态、时间、分页 | 分配单号、来源/目标、总数、成功数、失败数、操作人 | 查看详情 | `/api/admin/asset-allocation-records*` | 查询可做 |
+| 临期资产 | 资产类型、关键词、店铺、套餐、剩余天数、日期、分页 | 资产、套餐、预计最终到期、剩余天数、临期级别、优先标记 | 跳转资产、手动扫描 | `/api/admin/expiring-assets*` | 列表可做，扫描优先 Web |
+
+### 6.2 IoT 卡
+
+| 页面 | 主要查询字段 | 需要展示 | 操作 | 接口 | H5建议 |
+| --- | --- | --- | --- | --- | --- |
+| 独立卡列表 | ICCID/虚拟号/MSISDN、运营商、店铺、状态、实名、系列、分页 | 标识、运营商、店铺、流量、网络/实名/业务状态、系列、轮询状态 | 分配、回收、批量实名策略、批量系列绑定、实名链接、固定档位限速 | `/api/admin/iot-cards/*` | 查询、分配、实名链接可做；导入和批量配置优先 Web |
+| 卡导入任务 | 任务号、状态、分页 | 文件、总数、成功/失败数、状态、失败原因、时间 | 上传、创建任务、查看详情 | `/api/admin/iot-cards/import*` | 不做 |
+
+固定档位限速只适用于 IoT 卡，设备页面不得出现限速按钮。
+
+### 6.3 设备
+
+| 页面 | 主要查询字段 | 需要展示 | 操作 | 接口 | H5建议 |
+| --- | --- | --- | --- | --- | --- |
+| 设备列表 | 虚拟号、IMEI、SN、店铺、状态、实名、在线状态、系列、分页 | 设备标识、型号、店铺、在线状态、业务状态、实名策略、系列、卡槽摘要 | 分配、回收、绑定/解绑卡、实名策略、系列绑定、删除 | `/api/admin/devices*` | 查询、分配、卡槽操作可做 |
+| 设备控制 | 设备标识 | 网关卡槽、WiFi、切卡模式、在线状态、最后同步 | WiFi、切卡、切换模式、重启、恢复出厂 | `/api/admin/devices/by-identifier/:identifier/*` | 必须，危险操作二次确认 |
+| 设备导入/批量分配任务 | 任务类型、状态、分页 | 文件、操作类型、目标、总数、成功/失败数、错误明细 | 上传、导入、批量分配、查看任务 | `/api/admin/devices/import*` | 不做 |
+
+## 七、运营商、套餐与分销
+
+| 页面 | 主要字段 | 操作 | 接口 | H5建议 |
+| --- | --- | --- | --- | --- |
+| 运营商 | 名称、类型、接口配置、状态 | CRUD、启停 | `/api/admin/carriers*` | 不做 |
+| 套餐系列 | 名称、编码、佣金触发规则、状态 | CRUD、启停 | `/api/admin/package-series*` | 只读 |
+| 套餐 | 系列、名称、类型、周期、流量、成本价、零售价、上下架、有效期基准 | CRUD、启停、上下架、调价 | `/api/admin/packages*` | 查询可做 |
+| 套餐用量明细 | 套餐使用 ID、日期范围 | 每日使用量、剩余量 | 查询 | `GET /api/admin/package-usage/:id/daily-records` | 可做 |
+| 系列授权 | 目标店铺、系列、允许套餐、状态 | 创建、编辑、删除、批量管理套餐 | `/api/admin/shop-series-grants*` | 查询可做，配置优先 Web |
+| 套餐批量分配 | 目标店铺、套餐列表、成本价、零售价、上下架、有效期覆盖 | 批量分配 | `POST /api/admin/shop-package-batch-allocations` | 不做 |
+| 套餐批量定价 | 目标店铺、套餐和价格 | 批量调价 | `POST /api/admin/shop-package-batch-pricing` | 不做 |
+
+## 八、订单与售后
+
+| 页面 | 主要查询字段 | 需要展示 | 操作 | 接口 | H5建议 |
+| --- | --- | --- | --- | --- | --- |
+| 订单列表/详情 | 订单号、资产、店铺、状态、支付方式、购买角色、时间、分页 | 订单号、资产、套餐、买卖方、金额、实付、支付/订单状态、来源、审批/退款摘要 | 购买校验、创建、取消 | `/api/admin/orders*` | 列表、详情、现场代购可做 |
+| 退款 | 退款号、订单号、资产、店铺、状态、审批状态、提交人、时间、分页 | 申请金额、实付、原因、凭证、审批渠道/状态、套餐权益结果 | 创建、通过、驳回、退回、重新提交 | `/api/admin/refunds*` | 查询、提交、审批可做 |
+| 换货 | 旧资产、新资产、店铺、状态、提交人、时间、分页 | 新旧资产、收货信息、物流、状态时间线、迁移结果 | 创建、发货、完成、取消、续期 | `/api/admin/exchanges*` | 查询、发货、完成可做 |
+| 批量购买套餐 | 文件、套餐、支付方式、凭证 | 任务状态、逐行资产、订单结果、失败原因 | 上传、创建任务、查询详情 | `/api/admin/asset-package-batch-orders*` | 不做 |
+| 套餐失效任务 | 订单、任务状态、时间、分页 | 任务状态、处理结果和失败原因 | 创建、查询 | `/api/admin/order-package-invalidate-tasks*` | 不做 |
+
+企微审批启用后，前端只读展示 `approval_provider`、`approval_status`、`approval_status_name`；存在企微审批实例时，不再显示旧人工通过、驳回或线下确认按钮。
+
+## 九、代理资金业务
+
+“代理资金”是管理系统中的业务模块，不是独立前端。账号是否可见由权限控制，企业账号应禁止访问。
+
+| 页面 | 主要查询字段 | 需要展示 | 操作 | 接口 | H5建议 |
+| --- | --- | --- | --- | --- | --- |
+| 店铺资金概况 | 店铺、欠款、状态、分页 | 现金余额、冻结金额、信用额度、总可用、欠款、佣金 | 查看店铺明细、调额 | `GET /api/admin/shops/fund-summary` | 必须 |
+| 主钱包流水 | 店铺、类型、时间、分页 | 变动金额、前后余额、关联业务、资产、操作人 | 查看关联业务 | `GET /api/admin/shops/:shop_id/main-wallet/transactions` | 必须 |
+| 佣金明细/统计 | 店铺、类型、状态、时间、分页 | 订单、来源、佣金类型、金额、状态、每日趋势 | 查看、修正待审记录 | `/api/admin/shops/:shop_id/commission-*` | 必须 |
+| 提现申请 | 店铺、状态、时间、分页 | 申请金额、手续费、实付、收款信息、冻结状态、审批结果 | 代理提交、平台审批/驳回 | `/shops/:shop_id/withdrawal-requests`、`/commission/withdrawal-requests*` | 必须 |
+| 提现配置 | 最低金额、每日次数、手续费率、生效状态 | 新建配置、查看当前和历史 | `/api/admin/commission/withdrawal-settings*` | 不做 |
+| 代理充值 | 店铺、充值号、方式、状态、审批状态、时间、分页 | 金额、支付方式、支付状态、凭证、提交人、审批状态 | 在线充值、线下代充值、查询支付、线下确认、驳回 | `/api/admin/agent-recharges*` | 必须 |
+
+在线充值创建后使用 `GET /agent-recharges/:id/payment-status` 轮询本地支付和到账状态。
+
+## 十、系统配置、集成与运维
+
+| 页面 | 主要内容 | 接口 | H5建议 |
+| --- | --- | --- | --- |
+| 微信支付配置 | 配置列表、生效配置、启停 | `/api/admin/wechat-configs*` | 不做 |
+| 系统配置 | 注册状态、Key、值、说明 | `/api/admin/system-configs*` | 不做 |
+| 企业微信审批配置 | 应用、连接测试、成员同步、默认发起人、模板解析、场景映射 | `/api/admin/wecom*` | 不做 |
+| 超管操作密码 | 是否已设置、重新设置 | `/api/admin/super-admin/operation-password*` | 可做但仅超管 |
+| 导出任务 | 场景、筛选快照、状态、文件、失败原因 | `/api/admin/export-tasks*` | 查询和下载可做 |
+| 对象存储 | 上传用途、文件名、类型、大小；批量下载对象 Key | `/api/admin/storage*` | 上传凭证可做 |
+| 轮询配置/监控 | 配置、并发、队列、任务、初始化进度、手动触发 | `/api/admin/polling-*` | 监控可做，配置优先 Web |
+| 告警与清理 | 告警规则/历史、清理配置/预览/进度/日志 | `/api/admin/polling-alert-*`、`/api/admin/data-cleanup*` | 告警查看可做，配置不做 |
+
+## 十一、管理 H5 首期建议
+
+管理 H5 首期建议只实现以下任务型页面：
+
+1. 登录、当前账号、修改密码、通知。
+2. 工作台待办。
+3. 统一资产搜索和详情。
+4. 卡/设备列表、状态查看和必要现场操作。
+5. 订单、退款、换货列表和详情。
+6. 代理资金概况、充值、佣金和提现。
+7. 企业卡/设备授权。
+8. 导出文件下载和异步任务结果查看。
+
+账号、角色、权限、运营商、套餐复杂配置、企微配置、轮询配置、数据清理、批量导入优先放在 Web。若后续业务确认移动端必须配置，再按权限增加，不提前复制整套页面。