4.0 KiB
4.0 KiB
Context
项目使用 Vue 3、TypeScript、Element Plus 和 BaseService。后端控制菜单模式下，超级管理员直接使用全部静态路由，普通用户使用授权菜单；按钮控制复用现有 useAuth，身份复用 userStore.isSuperAdmin。
Goals / Non-Goals
- Goals: 完整接入文档声明的 API、可操作的管理页面、可靠表单校验、清晰权限配置交付。
- Non-Goals: 不实现后端限流，不改变旧轮询/停复机行为，不部署，不猜测统计指标字段。
Decisions
- 四页统一归属「轮询管理」，不新增一级菜单：
| 页面 | URL | 父菜单 |
|---|---|---|
| 停复机记录 | /polling-management/stop-resume-records |
轮询管理 /polling-management |
| 上游错误分类 | /polling-management/error-classifications |
轮询管理 /polling-management |
| 网关限流组 | /polling-management/rate-limit-groups |
轮询管理 /polling-management |
| 网关调用统计 | /polling-management/gateway-stats |
轮询管理 /polling-management |
| 网关限流组详情（隐藏路由） | /polling-management/rate-limit-groups/detail/:id |
轮询管理 /polling-management |
- 页面权限分别为
card_stop_resume_record:page、gateway_error_classification:page、gateway_rate_limit_group:page、gateway_call_stats:page，隐藏详情路由使用gateway_rate_limit_group:detail_page。普通操作权限为gateway_error_classification:test、gateway_rate_limit_group:detail、gateway_call_stats:trend；单卡入口按资产类型使用iot_info:stop_resume_records/device_info:stop_resume_records。这些是前端配置约定，不声称来自后端接口文档；详情页与按钮使用独立编码，避免菜单与按钮编码冲突。 - 超级管理员维护入口不定义供普通账号分配的增删改权限；UI 与事件处理双重身份检查，后端继续独立鉴权。
- 提取专用新模块承载网关契约，避免覆盖旧
/api/cards/{iccid}/suspend-resume-records接口及其不同 DTO。 - 枚举请求失败显式展示错误和重试，不把不可用枚举误报为空；未知值在只读展示中保留原值。
- 时间统一转换 RFC3339；全局记录查询必须有完整区间，单卡可使用后端默认；分页最大 100。
- 统计内部字段使用
unknown/记录值承载，只展示实际返回字段，空值不转成业务零；不从不明确字段推导图表或指标。 - 界面复用项目现有表格、搜索区、分页、弹窗、主题变量及状态标签；参考 UI/UX skill 的加载反馈、可访问标签、键盘焦点与响应式原则，不更换全站字体、颜色或新增表单依赖。
- 用户补充要求：列表严格复用店铺列表的 ArtSearchBar / ArtTableHeader / ArtTable / ArtTableFullScreen；详情使用店铺详情的返回、标题和双列描述表。时间展示复用同一个
formatDateTime，不改变请求与数据源；展开按钮仅在搜索条件数 >= 4 时出现。 - 运营商账户一律名称搜索下拉，复用
CarrierService.getCarriers({ page: 1, page_size: 20, carrier_name })，保留原账户名称回显，选中后仍提交 ID；趋势额外保留「无法解析账户的卡」的值 0。
Risks / Trade-offs
- 统计契约缺字段 → 接口和数据可查看，但正式业务趋势图需后端样例或完整 DTO 后再确定。
- 前端权限编码未在 API 文档定义 → 交付明确为菜单按钮配置编码，不替代后端鉴权。
- 31 天日期窗口和不同时区 → 按实际时间戳差值校验，测试边界与非法值。
- 用户已有未提交改动 → 不碰部署文件及 package 配置，不引入新依赖。
Validation
服务契约测试覆盖所有 17 个接口；业务测试覆盖时间范围、QPS、优先级操作、超级管理员门禁、枚举值和统计未知字段。执行 vue-tsc --noEmit、Vite 构建、针对性 lint/格式/编码检查。没有真实后端响应时，明确区分本地 mock 验证与线上联调。