dingqiuyu
/
SFT
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
SFT/docs/superpowers/specs/2026-07-08-fryl-frontend-ov...

12 KiB
Raw Blame History

凡荣e链前端系统 — 总体设计与实施规划

  • 状态: 已与用户确认(架构部分 + 阶段划分部分均已批准)
  • 关联文档: 2026-07-08-module-requirements-mapping.md(逐功能点的需求条款与原型页面映射,字段/业务规则的详细来源)
  • 需求来源: 凡荣e链前端业务需求说明书.docx(项目根目录)
  • 原型参考: website_detail/(项目根目录,70 页面截图+HTML+摘要,来自已上线的稠州银行商业平台)

1. 项目范围

严格按照需求说明书"业务功能列表"(1.2.3 节)定义的范围实施,不做任何范围扩展。共 9 个一级模块、24 个二级/三级功能点 + 登录页:

  1. 系统管理:用户管理、角色管理、机构管理
  2. 授信管理:贷款申请
  3. 支付管理:订单支付
  4. 订单管理:汇总订单、原始订单
  5. 客户管理:个人客户、企业客户
  6. 钱包管理:账户列表页、个人账户开立、企业账户开立、账户主页面、交易明细查询、主账户提现、回单下载、对账单下载、保证金缴纳、保证金释放
  7. 商户中心:商户管理、发票管理
  8. 基础配置:核心企业、客户经理
  9. 登录页面

明确排除(原型网站存在但需求说明书未提及,属于该银行平台其他既有业务线,不在本次实施范围):非银专区、分账专区、税筹专区、农都专区、业务配置(期权代理配置)、驾驶舱、首页仪表盘;以及上述 9 个模块下需求说明书未详述的其他原型子页面(如系统管理下的权限管理/文件存储信息/短信记录/日志管理/二维码业务/三方应用管理/第三方接口记录;客户管理下的开户登记;基础配置下的参数配置/贷款产品/销售平台/来账白名单/手续费规则;钱包管理下的待清算户/清分协议/来账白名单/通用支付服务费配置;商户中心下的店铺管理/提现记录/待审批事项/代销协议;授信管理下的白名单/担保人;支付管理下的支付协议/归集协议/协议支付;订单管理下的订单导入/订单录入/原始结算订单/汇总结算订单/鉴证订单/提现记录)。

登录后由于没有独立首页/仪表盘,默认落地页 = 当前用户菜单权限列表中的第一个可访问页面。

2. 技术栈

  • Vue 3 + Vite,纯 JavaScript(不使用 TypeScript)
  • UI 组件库:Ant Design Vue(原型页面 HTML 的 class 均为 ant-menu/anticon 等,确认原网站基于 AntD 构建;延用 AntD 可最大程度还原原型的深色顶部导航 + 可关闭多标签页 + 表格/表单/弹窗风格)
  • 状态管理:Pinia(用户信息、access_token、菜单权限树、打开的标签页列表)
  • 路由:Vue Router,路由表按登录后返回的菜单权限动态生成/挂载
  • HTTP:Axios 封装单例,withCredentials: true
  • 无 Node.js 服务端代码,纯静态 SPA,构建产物可用 Nginx 或任意静态服务器托管
  • BASE_URL:提供可配置入口(界面可修改,持久化 localStorage,默认值来自 .env),便于后续对接真实后端环境切换

3. 整体布局(还原原型风格)

  • 顶部深色水平主菜单:一级模块(系统管理/授信管理/支付管理/订单管理/客户管理/钱包管理/商户中心/基础配置),仅渲染当前用户有权限的模块
  • 主菜单下方"多标签页"条:点击二级菜单在标签栏打开对应页面,支持关闭,与原型截图交互一致
  • 内容区统一模板:查询筛选行 + 操作按钮行(新增/编辑/删除/导出等,均带 loading 防重复点击) + 表格(支持勾选、分页 10/20/50 条切换) + 弹窗表单(新增/编辑/查看复用同一表单组件,查看态字段只读)

4. 登录鉴权设计(access_token + refresh_token)

后端返回 access_token(响应体 JSON)+ 通过 Set-Cookie(HttpOnly)下发 refresh_token。前端设计:

  1. 登录:提交用户名+密码+短信验证码 → 成功后拿到 access_token 与菜单权限树 → access_token 存入 Pinia 并持久化到 localStorage;refresh_token 全程不经过前端 JS。
  2. Axios 实例全局 withCredentials: true,保证所有请求自动带上 HttpOnly Cookie(要求后端 CORS 显式允许前端源 + Access-Control-Allow-Credentials: true,Set-Cookie 配置合适的 SameSite/Secure 属性 —— 该要求记录进《缺失的后端接口.md》提醒后端配合)。
  3. 刷新策略:仅被动刷新(401 触发),不做基于 expires_in 的主动提前刷新:
    • 响应拦截器捕获 401(非刷新接口自身的 401)→ 暂停并缓存当前失败请求 → 调用 POST /auth/refresh(浏览器自动带 Cookie,无需手动传参)→ 成功则更新 access_token 并重放队列中所有失败请求;
    • 并发多个请求同时 401 时,使用请求队列 + 单次刷新锁,避免 /auth/refresh 被重复调用;
    • 刷新失败(refresh_token 也失效)→ 清空本地 access_token → 跳转登录页。
  4. 登出:清本地 access_token 的同时调用后端 /auth/logout,由后端使 refresh_token 失效并清除 Cookie。
  5. 会话超时:前端监听全局最后活跃时间,无操作超过 5 分钟(需求 3.4 节)则主动登出跳转登录页,与 token 是否仍有效无关。
  6. 登录失败锁定:连续 5 次密码错误自动锁定账号(后端校验,前端仅展示提示文案)。

5. 跨模块公共能力(提前封装)

  1. BASE_URL 配置入口
  2. 登录鉴权体系(见第 4 节)+ 路由守卫(未登录/无权限强制跳转)+ 403 统一提示
  3. 通用列表页组合式函数:查询表单状态、分页表格、导出按钮 loading
  4. 机构树选择组件(用户管理、客户管理、账户查询等多处复用)
  5. 状态 Tag 组件(正常/锁定、审批中/已签约/已拒绝等统一颜色映射,颜色枚举随各模块业务规则确定)
  6. 文件上传 + OCR 回显表单组件(身份证/营业执照通用,供个人客户、企业客户、账户开立复用;传输方式见 5.1 节)
  7. 短信验证码输入组件(发送倒计时 + 校验,供登录、支付、提现、保证金缴纳/释放复用;调用后端短信发送接口,见 5.1 节)
  8. 金额输入组件(精确到分,统一格式化/校验规则)

5.1 基础通用能力接口调用约定(文件上传 / OCR / 身份证校验 / 短信发送)

后端已规划/提供以下几类基础通用能力接口,前端直接调用即可,不做任何本地/前端侧的替代实现:

  • 文件上传:身份证正反面照片、营业执照照片等文件,前端读取后转换为 Base64 字符串,以 JSON 请求体字段(而非 multipart/form-data)传给后端上传接口;后端返回文件存储标识(如文件 ID / URL),表单提交时使用该标识而非原始文件。
  • OCR 识别:图片以 Base64 形式传给后端 OCR 接口,后端返回识别结果字段(如身份证的姓名/证件号/地址/有效期,营业执照的企业名称/统一社会信用代码/经营范围等),前端将识别结果回显到对应表单字段,允许用户手动修正。
  • 身份证 / 证件校验(联网核查):证件号码、姓名等信息以 JSON 形式传给后端校验接口,返回是否一致/有效。
  • 短信发送与校验:调用后端发送短信验证码接口(传手机号+业务场景标识),用户输入后调用后端校验接口(不在前端本地生成或校验验证码)。
  • 人脸识别 / 卡信息查询等其他第三方能力(个人/企业开户涉及):同样是"前端仅传参调用后端接口,不做本地实现"的模式。

上述接口均由后端提供,前端只需按约定的入参/出参对接。所有涉及文件的字段在《缺失的后端接口.md》中统一注明"文件以 Base64 字符串形式作为 JSON 字段传输"这一约定,避免误用 FormData。

6. 开发阶段划分

按数据依赖关系(客户数据 → 账户数据 → 授信/支付/商户数据)分 8 个阶段推进。每个阶段独立走一轮"brainstorming → 设计文档 → 实施计划 → 编码"流程:

阶段 模块内容 功能点数 说明
0 工程基础设施 - 脚手架、整体布局、路由守卫、鉴权体系、第 5 节公共组件
1 登录页 + 系统管理 4 登录、用户管理、角色管理、机构管理 —— 全系统权限基础,必须最先完成
2 基础配置 2 核心企业(渠道字典)、客户经理 —— 静态字典数据
3 客户管理 2 个人客户、企业客户 —— 账户/授信的主数据入口,企业客户依赖个人客户(股东/高管/受益人需从已登记个人客户中选择)
4 钱包管理 10 账户列表、个人/企业开户、账户主页面(含交易明细/提现/回单/对账单/保证金缴纳释放)—— 原型完全缺失详情页,需按需求文档字段全自行设计,是工作量最大、风险最高的阶段
5 授信管理 1(含个人/企业两套表单) 贷款申请 —— 依赖客户 + 钱包
6 商户中心 2 商户管理、发票管理 —— 依赖客户 + 钱包
7 订单管理 + 支付管理 3 原始订单、汇总订单、订单支付 —— 处于依赖链末端,汇总订单原型也缺失需自行设计

原型缺失页面统一处理原则:登录页、个人/企业账户开立表单、账户主页面及其 6 个子功能、汇总订单、核心企业(基础配置)—— 这些功能原型未能提供直接可参考的页面,将严格依据需求文档字段表设计表单/页面结构,但视觉风格、组件用法(表格/弹窗/按钮位置)复用第 3 节确定的 AntD 统一模板,保证整站视觉一致。

⚠️ 特别提醒(易混淆点):原型目录 website_detail/驾驶舱/核心企业 与需求文档 2.8.1"核心企业"并非同一功能,前者是已排除的驾驶舱模块下的数据看板页面,后者是基础配置下的渠道信息 CRUD 页面,开发时不可混用其页面结构,仅可参考其"缴纳/释放"按钮交互作为保证金缴纳/释放功能的交互模式参考。

7.《缺失的后端接口.md》组织方式

按模块分节,文档最前设两个通用小节:

  1. 通用鉴权接口:登录、刷新令牌、登出、获取当前用户信息、获取当前用户菜单权限。
  2. 基础通用能力接口:文件上传(Base64)、OCR 识别(身份证/营业执照)、证件联网核查、短信发送、短信校验、人脸识别/卡信息查询等第三方能力接口(见 5.1 节约定)。这些接口按后端说法"均已规划提供",仍需在本文档中完整记录其入参/出参,便于前后端对齐字段。

再往后按 9 个业务模块分节。每个接口固定包含:

  • 接口名称 / 功能描述
  • Method + Path
  • 请求参数表:字段名、类型、是否必填、说明(枚举值必须注明具体枚举来源,不编造)
  • 响应参数表:同上
  • 关键业务校验点:该接口需要后端完成哪些校验逻辑,便于后端对齐(如唯一性校验、状态流转、额度计算公式等,均来自需求文档业务规则)

日期字段统一使用 yyyy-MM-dd HH:mm:ss 格式。

8. 非功能性需求要点(需求文档第 3 章,影响前端设计的部分)

  • 密码强度:8 位以上,含大小写字母 + 数字
  • 连续 5 次登录失败自动锁定账号
  • 会话无操作超时 5 分钟自动登出
  • 单点登录:新登录使旧会话失效(后端保证,前端被动接受 401/踢出提示)
  • 所有增删改锁定解锁密码重置操作需前端呈现完整反馈(成功/失败提示),具体操作日志由后端记录,前端无需单独实现日志模块(日志管理本身不在本次范围内)

9. 后续步骤

本文档为总体设计与阶段规划,已获用户确认。下一步:针对**阶段 1(登录页 + 系统管理:用户管理/角色管理/机构管理)**发起独立的详细 brainstorming,产出该阶段专属设计文档,再调用 writing-plans 生成可执行的实施计划。