14 KiB
14 KiB
Go-sms(go-sms)前端开发计划
【文档状态】⛔ 已废止(FE-1~FE-5 + UI 重构 W1-W6 已完成;FE-6 未竟部分转入《Go-sms-重建计划.md》一期)
编制日期:2026-09-03 · 依据:《需求分析》(18 模块/94 页面,P0
P2 分级)、《技术方案》(前端栈空缺,本计划补齐)、《实施计划》(阶段 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 关键决策
- 技术栈(补齐技术方案空缺):Vue 3.4+ / TypeScript 5 / Vite 5 / Element Plus 2.x / Pinia / Vue Router 4 / Axios / ECharts 5 / Vitest + Playwright。理由:管理后台表格表单生态最成熟、团队招聘与上手成本最低、ECharts 对齐开发计划 Day 63 的既有表述。
- 契约先行 + Mock 并行:后端 API 未就绪前,前端依据
api/openapi.yaml(后端 Day 30 交付物)或本地 Mock(msw/json-server)开发,后端阶段验收周切换联调,前端永不被后端阻塞。 - P0→P1 优先,业务线 P2 后置:视频/CSP/空号/短链四条增值业务线(需求文档已建议后置)不占本期 40 天,列入迭代二。
- 统一对接既有规范:请求层对接后端统一响应
{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 缺陷 |
四、交付物清单(累计)
web/工程:源码 + 单测(Vitest 核心工具函数/请求层)+ E2E(Playwright 10 用例)- 组件资产:布局/搜索表格套件(ProTable)/分步表单/图表基座/导入导出组件/权限指令
- 页面 50+(覆盖 P0 全量 + P1 主体,18 模块中 12 个)
docs/frontend-review.md前端验收报告 + 权限矩阵走查表- 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;提交信息含自测报告。