Files
go-sms-V2/memory-bank/docs/Go-sms-前端开发计划.md
T

14 KiB

Go-sms(go-sms)前端开发计划

【文档状态】⛔ 已废止(FE-1~FE-5 + UI 重构 W1-W6 已完成;FE-6 未竟部分转入《Go-sms-重建计划.md》一期)

编制日期:2026-09-03 · 依据:《需求分析》(18 模块/94 页面,P0P2 分级)、《技术方案》(前端栈空缺,本计划补齐)、《实施计划》(阶段 0-7)、《开发计划》(前端 2 人,阶段 26) 配置:前端工程师 2 名(FE-A 主架构/权限/业务流;FE-B 组件库/列表页/图表),共 40 个工作日 × 2 人,与后端 Day 21-70 窗口并行 代码位置:本仓库 web/ 子目录(monorepo,共享 CI 与 CHANGELOG)


一、现状与依据分析

1.1 后端进度(硬依赖)

后端阶段 状态 提供的前端依赖
阶段 0 环境与 CI(Day 1-10) ✅ 完成 make up 中间件、CI 流水线、/health、/metrics
阶段 1 数据模型与组件(Day 11-20) ✅ 完成 36 表模型、ISC:xxx 错误码、统一响应 {code,msg,data}、JWT、Casbin RBAC、迁移工具
阶段 2 账号与权限(Day 21-30) 🔜 当前 登录/账号 CRUD/配置/充值/角色权限 API
阶段 3 通道与路由(Day 31-40) 待开始 通道/上家/通道组/策略 API
阶段 4 消息发送(Day 41-50) 待开始 发送/模板/审核 API
阶段 5 回执与记录(Day 51-60) 待开始 记录查询/回执/上行 API
阶段 6 统计结算(Day 61-70) 待开始 统计/结算/工作台 API

1.2 关键决策

  1. 技术栈(补齐技术方案空缺):Vue 3.4+ / TypeScript 5 / Vite 5 / Element Plus 2.x / Pinia / Vue Router 4 / Axios / ECharts 5 / Vitest + Playwright。理由:管理后台表格表单生态最成熟、团队招聘与上手成本最低、ECharts 对齐开发计划 Day 63 的既有表述。
  2. 契约先行 + Mock 并行:后端 API 未就绪前,前端依据 api/openapi.yaml(后端 Day 30 交付物)或本地 Mock(msw/json-server)开发,后端阶段验收周切换联调,前端永不被后端阻塞。
  3. P0→P1 优先,业务线 P2 后置:视频/CSP/空号/短链四条增值业务线(需求文档已建议后置)不占本期 40 天,列入迭代二。
  4. 统一对接既有规范:请求层对接后端统一响应 {code,msg,data} 与 ISC:xxx 错误码(401→登录页/403→提示/500→人工核查提示),trace_id 透传 X-Trace-Id。

二、总体节奏:六个前端阶段(对齐后端)

前端阶段 工作日 对齐后端 主题 页面覆盖(需求模块)
FE-0 工程与骨架 Day 1-5 阶段 2 前半 脚手架/布局/登录鉴权 (全局壳)
FE-1 账号与权限 Day 6-10 阶段 2(Day 21-30) 帐号管理 8 页 ③帐号管理
FE-2 通道与路由 Day 11-16 阶段 3(Day 31-40) 通道/策略 12 页 ⑩通道配置 ⑪规则策略
FE-3 发送与审核 Day 17-23 阶段 4(Day 41-50) 发送/模板/审核 10 页 ④业务审核 ⑤短信业务
FE-4 记录与回执 Day 24-29 阶段 5(Day 51-60) 记录/工具 8 页 ⑤短信业务(记录)/下载中心
FE-5 统计结算与运营 Day 30-36 阶段 6(Day 61-70) 图表/结算/配置 12 页 ①主页 ⑬用户统计 ⑭通道统计 ⑮结算 ⑯日志报表 ⑰系统配置 ⑫通讯录
FE-6 联调加固上线 Day 37-40 阶段 7(Day 71-80) 全量回归/性能/CI 全部走查

页面合计约 50 页(P0 全量 + P1 主体),P2 业务线(视频/CSP/空号/短链/大屏/主题)为迭代二。


三、按天开发明细(产出物 + 验收标准)

FE-0 工程与骨架(Day 1-5)

工作日 任务(FE-A / FE-B) 产出物 验收标准
D1 A:Vite+Vue3+TS 脚手架、ESLint+Prettier+git hooks;B:目录规范(api/components/composables/stores/views/router)、环境变量(.env.dev/.test) web/ 工程骨架、README pnpm i && pnpm dev 一键起;pnpm lint 0 error 0 warning
D2 A:Axios 封装(拦截器:ISC 码分流/token 注入/X-Trace-Id);B:统一响应类型 + Mock 服务(msw) request.ts、api/types.ts、mocks/ Mock 登录接口返回 ISC:000;401 拦截跳登录(单测)
D3 A:主布局(侧边栏 18 模块导航/顶栏/面包屑/多标签页);B:主题与全局样式(样式变量/暗色预留) layouts/、styles/ 导航与需求模块地图一致;路由与菜单联动刷新不丢标签
D4 A:登录页(表单校验/验证码占位)+ token 存取;B:Pinia 用户态 + 路由守卫(白名单/重定向) views/login、stores/user、router/guard 登录→工作台→登出闭环(Mock);未登录访问任意页重定向 /login
D5 A:动态路由与权限指令 v-permission、按钮级权限;B:错误页(403/404/500 对接 ISC 码) directive/permission、views/error 隐藏无权菜单与按钮(Mock admin/customer 两角色实测);阶段走查 FE-0 验收单

FE-1 账号与权限(Day 6-10,联调后端阶段 2)

工作日 任务 产出物 验收标准
D6 账号列表:搜索(用户名/角色/状态/日期)、分页表格、批量启停/标星;导出(admin) views/account/list 与后端 /api/v1/accounts 分页排序联调一致;列 12+;空态/加载态
D7 开户表单:多业务线勾选(国内/国际/视频/空号/CSP)、四接入协议、单价时间线、授信/IP 绑定/审核模式 views/account/create 分步表单校验(手机号 util 同规则);提交后列表可见(联调)
D8 账号详情+配置页:基础信息、业务配置矩阵、签名限制、推送地址;切换上级(多级代理) views/account/detail 只读/可编辑分区清晰;保存后二次进入回显正确
D9 充值与余额:单个/批量充值(二级权限按钮)、余额变动日志、预警设置 views/account/recharge 余额变动流水与后端 balance_log 一致;无权限按钮隐藏(v-permission)
D10 角色权限管理(角色列表/权限树勾选/Casbin 策略展示)、登录审计查询 views/account/roles、views/audit/login 权限树勾选→菜单/按钮实时生效;审计表可按账号/IP/日期检索;FE-1 验收=A-2.x 联调通过

FE-2 通道与路由(Day 11-16,联调阶段 3)

工作日 任务 产出物 验收标准
D11 上家管理(CRUD/分类/联系人) views/channel/upstream CRUD 联调通过;删除二次确认
D12 通道列表:协议/状态筛选、启停、连接测试按钮、通道号截断/夜间管控等 20+ 字段 views/channel/list 筛选组合联调;测试连接结果 Toast 回显
D13 通道新建/编辑:CMPP/HTTP/SGIP/SMPP 参数分区、拦截配置(频次/黑关键字/屏蔽地区)、模板 ID 模式 views/channel/edit 四协议表单动态切换;必填校验与后端 ISC:400 对齐提示
D14 通道组与四步路由配置器:条件过滤→优先通道(省网/关键字)→权重→兜底,拖拽排序 views/channel/group 四步配置保存/回显一致;权重可视化条形展示
D15 策略中心:黑白名单(导入导出)、黑白关键字、频次策略、白名单、屏蔽码号 views/policy/* 5 页 各策略 CRUD+批量导入模板下载;命中预演(调后端校验接口)
D16 导流策略 + 签名/码号报备页;阶段走查 views/policy/route、views/channel/report 规则优先级排序正确;FE-2 验收=A-3.x 联调通过

FE-3 发送与审核(Day 17-23,联调阶段 4)

工作日 任务 产出物 验收标准
D17 发送工作台-群发:号码输入/文件导入(TXT/CSV/XLSX 预览)、内容输入(计费条数实时展示,规则同后端 util) views/sms/batch 文件预览前 50 行;条数/拆分提示与后端 SmsLength 一致
D18 个性短信(变量表格编辑)+ 拆分短信;模板选择联动 views/sms/personal 变量校验({name} 规则);模板套用预览
D19 定时发送(日期时间选择/批量重置)、发送记录摘要卡 views/sms/timer 定时任务列表可取消/改期(联调)
D20 模板管理:列表/报备/批量审核通过拒绝、变量限制提示 views/sms/template 模板状态流转(待审/通过/拒绝)实时刷新
D21 审核中心:待审聚合(短信/模板/签名/集团/短链 Tab)、批量通过/拒绝(填原因)、48h 超时标红 views/audit/center Tab 计数徽标;批量操作后列表与计数联动;超时项样式区分
D22 发送结果即时反馈:提交返回 task_no、失败明细(ISC 错误码中文表内嵌)下载 views/sms/result ISC 码→中文映射表(内置前端字典与后端 47 码同步)
D23 短信业务聚合页(发送/记录/模板三入口)+ 移动端适配走查;阶段走查 views/sms/home FE-3 验收=A-4.x 联调:四种发送方式可提交,审核流可闭环

FE-4 记录与回执(Day 24-29,联调阶段 5)

工作日 任务 产出物 验收标准
D24 下行记录(批次):状态/账号/时间筛选、批次进度(成功/失败/未知占比)、拦截失败号码下载 views/record/down 大数据量表格(分页 100/页)流畅;进度条与后端计数一致
D25 下行明细(号码级,5 天热数据):CMPP/通道日志钻入、错误码筛选 views/record/detail 明细与批次钻取链路正确;ISC 码筛选联调
D26 历史记录/明细(全量,>5 天):时间范围查询、异步导出 views/record/history 查询响应 <3s(后端 ClickHouse);导出去下载中心
D27 上行记录:码号/手机号查询、导出(权限控制) views/record/uplink 15 天窗口提示;无权限导出按钮隐藏
D28 回执重推工具(选用户+时间窗)与手动配对(四种方式) views/record/repush 30 天窗口校验;任务提交反馈;配对结果回写列表
D29 下载中心:任务列表/进度/文件下载;定时记录管理;阶段走查 views/record/download 异步任务状态轮询;FE-4 验收=A-5.x 联调:记录四页+两工具可用

FE-5 统计结算与运营(Day 30-36,联调阶段 6)

工作日 任务 产出物 验收标准
D30 图表基座:ECharts 封装(主题/自适应/loading)+ 通用过滤栏(时间/账号/通道/运营商) components/charts 图表空态/加载态统一;切换过滤无内存泄漏(路由切换销毁)
D31 用户统计:量级/成功率/回执速率趋势、7 维度下钻(时间/地区/签名/状态码…) views/stats/user 图表数据与明细核对一致(抽 3 日);导出 XLS
D32 通道统计:成功率/耗时/量级、估算余额、通道告警配置页 views/stats/channel 趋势与后端 stats_channel_daily 一致;告警阈值保存生效
D33 结算-下家:月度账单/明细/确认;结算-上家:账单/结账记录/单价追加 views/settle/* 4 页 账单金额=成功条数×单价(抽样对账);状态流转清晰
D34 利润分析(用户/通道两视角)+ 消耗/充值日志页 views/settle/profit 利润曲线与手工核算一致;日志可追溯操作人
D35 主页工作台:今日用量/待办(待审核数)/余额预警/公告;系统配置(参数/初始化/错误码表维护/备份);日志报表(操作日志) views/home、views/system/* 4 页 工作台 5s 内加载;错误码表与后端种子一致(可维护)
D36 通讯录+常用短语+常用号码(P2 顺带,轻量);预警公告管理;阶段走查 views/tools/* 3 页 FE-5 验收=A-6.x 联调:统计/结算/工作台可用

FE-6 联调加固与上线(Day 37-40,配合阶段 7)

工作日 任务 产出物 验收标准
D37 全站权限矩阵走查(admin/运维/客服/集团/客户 五角色 × 全菜单);Mock 全部下线切换真实 API 权限矩阵走查表 五角色各走查一遍并截图归档;无越权入口
D38 性能与体验:路由懒加载/打包分析/首屏优化;表格大数据虚拟滚动抽检;暗坑修复 性能报告(web-vitals) 首屏 LCP < 2s(内网);chunk 单包 < 500KB
D39 CI 集成:web 构建加入 make ci-local 与 .gitlab-ci(test→build);镜像多阶段构建(node→nginx) CI 配置、web/Dockerfile、nginx.conf CI 绿;容器化部署 kind Dev 通过(NodePort 30081)
D40 Playwright 冒烟(登录→发送→审核→记录→结算 主链 10 用例);前端验收会议;文档归档 e2e/ 10 用例、docs/frontend-review.md 冒烟全绿;FE 总验收:50 页走查表全过,零 P0 缺陷

四、交付物清单(累计)

  1. web/ 工程:源码 + 单测(Vitest 核心工具函数/请求层)+ E2E(Playwright 10 用例)
  2. 组件资产:布局/搜索表格套件(ProTable)/分步表单/图表基座/导入导出组件/权限指令
  3. 页面 50+(覆盖 P0 全量 + P1 主体,18 模块中 12 个)
  4. docs/frontend-review.md 前端验收报告 + 权限矩阵走查表
  5. CI/CD:lint→test→build→镜像→kind Dev 部署链路

五、Mock 与联调策略

  • 契约源:后端 api/openapi.yaml(Day 30 起维护);阶段 2 之前由前端按本计划接口约定建 Mock 契约,后端实现时对齐
  • 切换:.env 的 VITE_API_MODE=mock|real,联调周统一切 real;Mock 数据含错误分支(401/403/ISC:500)保证异常态开发
  • 联调窗口:每阶段最后 1 天为固定联调日(与后端阶段验收同周),问题当周清零

六、风险与依赖

风险 应对
后端阶段 2 接口延期 FE-1 前 2 天用 Mock,后端就绪即切换;计划已在缓冲
ISC 错误码双端不一致 前端字典从 internal/pkg/errors 生成脚本(D39 前完成 codegen)
大表渲染卡顿(明细页) ProTable 内置虚拟滚动;分页 100;导出走下载中心
四步路由配置器复杂度高 D14 预留 1.5 天;必要时降级为分步向导交互
P2 业务线(视频/CSP/空号/短链/大屏) 明确列入迭代二,本期仅保留菜单占位与路由 404 引导页

执行规范与主干一致:分支 feature/fe-* 从 develop 拉出,按 FE 阶段合并;每次推送更新 CHANGELOG.md;提交信息含自测报告。