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

管理 Web 与管理 H5 页面接口矩阵

本文描述页面需要承载的业务信息和接口组合。完整请求、响应字段、校验规则和枚举以 docs/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
店铺级联选择	关键词、父节点	店铺 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。若后续业务确认移动端必须配置，再按权限增加，不提前复制整套页面。