Mutual_Fund/开发计划-前端.md

华夏基金 PC 前端详细开发计划

1. 计划概览

项目	内容
项目名称	华夏基金 PC 网页平台前端
计划版本	V1.0
编制日期	2026-09-13
开发范围	PC 浏览器前端
后端约束	只调用现有 FastAPI 接口，不修改后端代码、数据库和权限逻辑
产品形态	用户端官网 + 用户服务页面 + 员工后台管理系统

1.1 总体开发顺序

项目勘察
  ↓
前端工程与基础架构
  ↓
统一品牌视觉与公共组件
  ↓
用户端官网长页面
  ↓
基金列表与基金详情
  ↓
登录、注册与用户中心
  ↓
员工后台壳层与权限菜单
  ↓
投顾、风控和通用员工页面
  ↓
Agent 聊天框
  ↓
API 联调与异常处理
  ↓
PC 浏览器验收与交付

2. 开发原则

1. 前端只负责页面、状态、交互、展示和接口调用。
2. 不修改现有 Python/FastAPI 后端代码。
3. 不修改数据库表结构、数据内容和后端权限判断。
4. 基金净值、收益和产品信息全部来自后端 API，不在前端写死真实业务数据。
5. 用户端和后台共用品牌色、字体、按钮、标签、弹窗和状态反馈规范。
6. 用户端强调品牌和转化，后台强调信息密度和业务效率。
7. 所有接口都需要处理加载中、空数据、失败、超时和 Token 失效状态。
8. 先建立稳定的页面结构，再根据后续图片进行视觉细化。

3. 阶段划分

阶段	名称	主要产出
Phase 0	项目勘察与接口确认	页面地图、接口清单、字段映射表、风险清单
Phase 1	前端工程搭建	前端应用、路由、环境变量、API 客户端
Phase 2	统一设计系统	品牌色、字体、按钮、表单、标签、图标、布局规范
Phase 3	用户端官网	可下滑首页、导航、基金展示、Agent 入口
Phase 4	基金数据页面	基金列表、详情、历史净值和走势图
Phase 5	登录与用户中心	登录、注册、身份跳转、账户、持仓、风险测评
Phase 6	员工后台基础框架	后台壳层、菜单、角色显示、通用状态
Phase 7	员工业务页面	工作台、客户、投顾、风控、基金数据、设置
Phase 8	Agent 聊天框	右下角浮动入口、聊天面板、消息状态
Phase 9	联调与质量验收	API 联调、权限验证、视觉检查、浏览器验收

4. Phase 0：项目勘察与接口确认

4.1 目标

在开发前确认当前后端能力、接口返回格式和页面实际需要的数据，避免前端基于错误字段开发。

4.2 工作内容

• 确认 FastAPI 服务启动地址和 API 前缀。
• 确认统一响应格式 {code, message, data, trace_id}。
• 确认登录返回的 Token 字段和用户信息字段。
• 确认 user_type 的实际值。
• 确认后端实际员工角色值，并在前端建立显示映射。
• 整理基金列表接口字段。
• 整理基金历史净值接口字段。
• 整理投顾工作台接口清单。
• 整理风控接口清单。
• 整理 Agent 接口、会话字段和流式/非流式返回方式。
• 记录接口暂不可用、需要登录或需要特定角色的页面。

4.3 产出

• 前端页面路由表。
• API 接口清单。
• API 字段映射表。
• 角色与菜单映射表。
• 接口异常码处理表。
• 待确认问题清单。

4.4 验收标准

• 每个计划开发的页面都有对应接口或明确的空状态方案。
• 不把数据库结构直接暴露给页面组件。
• 关键接口能够通过 Swagger 或实际请求确认返回格式。

5. Phase 1：前端工程搭建

5.1 目标

建立独立、可维护的 PC 前端工程，不侵入现有后端目录和代码。

5.2 建议目录

frontend/
├── app/                  # 页面路由
│   ├── page              # 用户端首页
│   ├── products          # 基金列表
│   ├── products/[code]   # 基金详情
│   ├── login             # 登录
│   ├── register          # 注册
│   ├── account           # 用户中心
│   └── admin             # 员工后台
├── components/           # 公共 UI 组件
├── features/             # 用户端和后台业务组件
├── lib/                  # API、鉴权、格式化工具
├── types/                # TypeScript 类型
├── styles/               # 全局样式和设计变量
└── public/               # Logo、背景图和静态素材

5.3 工作内容

• 初始化 PC 前端应用。
• 配置开发、测试和生产 API 地址。
• 配置 TypeScript 和代码格式化规范。
• 建立基础路由。
• 建立统一 API 客户端。
• 建立 Token 存储和请求拦截逻辑。
• 建立统一接口错误处理。
• 建立页面级 loading、error 和 empty 状态。
• 将提供的背景图复制或引用到前端静态资源目录。

5.4 API 客户端要求

• 所有请求从统一 API 模块发出。
• 自动拼接后端 API 基地址。
• 需要登录的接口自动添加 Authorization: Bearer <token>。
• 收到 401 时清理登录状态并跳转登录页。
• 统一解包后端 data 字段。
• 保留 trace_id，便于页面显示错误信息或排查问题。
• 不在组件中重复编写请求地址和鉴权逻辑。

5.5 验收标准

• 前端可以独立启动。
• 首页路由可以打开。
• 可以成功请求一个公开基金接口。
• Token 能够被保存、读取和清理。
• API 错误不会导致页面白屏。

6. Phase 2：统一设计系统

6.1 目标

建立用户端和后台共用的视觉基础，确保两套产品属于同一个华夏基金平台。

6.2 颜色体系

• 主色：沿用后台管理系统的品牌主色，用于主按钮、链接、选中态和重要操作。
• 深蓝：用于用户端首页背景和金融氛围。
• 金色：用于收益、资产、重点数据和基金视觉强调。
• 白色与浅灰：用于用户端内容背景和后台页面背景。
• 深灰：用于正文和后台侧边栏。
• 绿色：成功状态。
• 黄色：提醒状态。
• 红色：风险、错误和危险操作。

颜色需要集中定义为设计变量，禁止在业务页面中大量散落硬编码颜色值。

6.3 公共组件

优先实现以下组件：

• 品牌 Logo 和文字标识。
• 用户端顶部导航。
• 后台侧边栏。
• 后台顶部工具栏。
• 主按钮、次按钮、危险按钮。
• 输入框、下拉框、搜索框。
• 状态标签。
• 统计卡片。
• 数据表格。
• 分页器。
• Modal 弹窗。
• Toast 消息提示。
• Skeleton 加载占位。
• Empty 空数据状态。
• Error 错误状态。
• 基金净值走势图容器。
• 用户头像和角色标识。
• Agent 浮动入口和聊天面板。

6.4 视觉验收标准

• 用户端和后台主色一致。
• 主按钮、链接、标签、图表重点线条使用统一色变量。
• 圆角、边框、阴影和字体层级保持一致。
• 用户端可以更宽松、更有品牌感，但不能出现完全不同的主题。
• 后台保持紧凑、清晰和可扫描。

7. Phase 3：用户端官网首页

7.1 页面形态

• PC 端纵向可下滑长页面。
• 顶部导航固定或在滚动后保持可见。
• 各模块按顺序组织，支持导航锚点跳转。
• 页面底部包含联系入口、员工后台入口、登录注册入口和合规信息。

7.2 页面模块

7.2.1 首屏 Hero

• 品牌名称：华夏基金。
• 主标题体现智能财富管理和长期投资理念。
• 使用指定背景图作为视觉参考。
• 背景采用深蓝金融城市氛围。
• 对图片增加适度遮罩，保障文字可读性。
• 设置“查看基金产品”“登录/注册”等主要按钮。
• 员工后台入口作为次要入口。

7.2.2 品牌介绍

• 展示企业使命：“让财富管理更智能、更普惠”。
• 展示专业、稳健、合规、科技驱动等核心价值。
• 采用宽幅信息模块或简洁分栏布局。

7.2.3 核心服务

建议展示：

• 公募基金产品。
• 智能资产配置。
• 风险评估与适当性服务。
• 投顾服务。
• 客户资产与持仓管理。

7.2.4 基金数据亮点

• 从 API 获取并展示基金产品数量或可用统计数据。
• 展示热门基金或精选基金。
• 展示最新净值、日涨跌幅和风险等级。
• 页面必须标记数据更新时间。
• 无数据时展示稳定的空状态，不使用虚假数字替代。

7.2.5 客户评价或信任模块

• 根据后续提供的图片和文案决定是否保留。
• 如果没有真实客户素材，使用中性占位结构，不伪造客户身份和评价。

7.2.6 风险提示

• 说明基金投资有风险。
• 不使用保证收益、稳赚等表述。
• 风险内容作为正式页面模块展示，不藏在弹窗中。

7.2.7 联系与底部区域

• 公司名称：华夏基金。
• 联系方式和公司信息根据确认后的企业资料填写。
• 提供登录、注册和员工后台入口。
• 预留合规声明、隐私政策和用户协议入口。

7.3 验收标准

• 首页可以顺畅纵向浏览。
• 顶部导航能够定位页面模块。
• 首屏背景、文案和按钮层级清晰。
• 基金数据模块从 API 加载真实数据。
• Agent 入口固定在右下角且不遮挡核心内容。
• 页面滚动时无明显跳动或布局错位。

8. Phase 4：基金数据页面

8.1 基金列表页

页面内容：

• 页面标题和说明。
• 关键词搜索。
• 基金类型筛选。
• 风险等级筛选。
• 在售状态筛选。
• 基金列表或数据表格。
• 分页。
• 基金详情入口。

字段展示：

• 基金代码。
• 基金名称。
• 基金类型。
• 风险等级。
• 最新单位净值。
• 净值日期。
• 基金经理。
• 基金状态。

交互要求：

• 搜索和筛选时显示 loading。
• 筛选条件变化后重新请求 API。
• 无结果时显示空状态。
• 接口错误时提供重试按钮。
• 点击基金行或卡片进入详情页。

8.2 基金详情页

页面结构：

1. 基金基本资料。
2. 最新净值和累计净值。
3. 净值日期和数据更新时间。
4. 区间收益指标。
5. 历史净值走势图。
6. 风险等级和风险提示。
7. 申购、赎回或登录操作入口。

走势图要求：

• 调用 /api/products/{product_code}/history。
• 支持净值和收益两种序列展示。
• 支持时间范围选择。
• 展示 tooltip、日期、数值和单位。
• 无历史数据时显示空状态。
• 图表颜色使用统一品牌色，收益重点可使用金色辅助强调。

8.3 验收标准

• 基金列表能够正常加载真实数据。
• 搜索、筛选和分页行为正确。
• 基金详情与列表选择的产品一致。
• 图表数据与后端返回数据一致。
• 页面不显示未经后端返回的虚构净值或收益率。

9. Phase 5：登录、注册与用户中心

9.1 登录页

• 用户名输入。
• 密码输入。
• 登录按钮。
• 注册入口。
• 返回官网入口。
• 登录加载状态。
• 错误提示。
• 登录成功后的身份跳转。

9.2 注册页

• 用户名。
• 手机号。
• 密码。
• 真实姓名。
• 注册按钮。
• 字段校验。
• 用户协议和隐私政策勾选位预留。
• 注册成功提示并引导登录。

9.3 鉴权状态

• 登录成功保存 JWT Token。
• 应用启动时恢复登录状态。
• 调用 /api/auth/me 获取当前用户。
• Token 失效时清理状态并跳转登录页。
• 退出登录清理 Token 和用户缓存。

9.4 用户中心页面

• 用户基本信息。
• 账户余额。
• 基金持仓。
• 风险测评入口和状态。
• 申购入口。
• 赎回入口。
• 用户消息或客服入口。

9.5 验收标准

• 普通用户能够注册并登录。
• 登录后能够读取当前用户信息。
• 未登录用户访问受保护页面会被引导登录。
• Token 过期后不会继续展示受保护数据。
• 申购、赎回和风险测评表单有成功、失败和确认反馈。

10. Phase 6：员工后台基础框架

10.1 页面壳层

参考 admin-panel-template 实现：

• 深色固定侧边栏。
• 品牌 Logo 区域。
• 角色相关菜单。
• 顶部工具栏。
• 当前页面标题。
• 通知入口。
• 用户头像和角色显示。
• 退出登录。
• 主内容区域。

10.2 前端角色显示映射

前端统一显示：

投顾专员
风控专员
员工通用

后端返回值仅在前端适配层进行映射。前端不修改后端数据库中的角色值和权限判断。

10.3 菜单规划

投顾专员

• 工作台首页。
• 客户管理。
• 客户持仓。
• 组合诊断。
• 投顾报告。
• 回访记录。
• 待办事项。
• 公共基金数据。

风控专员

• 工作台首页。
• 风控预警。
• 风控工单。
• 基金数据。
• 消息通知。

员工通用

• 工作台首页。
• 公共基金数据。
• 消息通知。
• 个人设置。

10.4 验收标准

• 员工登录后进入后台而不是普通用户中心。
• 侧边栏菜单根据后端用户信息显示。
• 当前角色名称显示为统一前端文案。
• 未授权页面有明确提示或跳转处理。
• 后台布局与参考模板保持一致。

11. Phase 7：员工业务页面

11.1 工作台首页

• 统计卡片。
• 待办事项。
• 客户数量。
• 资产规模或业务指标。
• 风险预警数量。
• 最近活动。
• 根据角色显示不同重点内容。

11.2 客户管理

• 客户列表。
• 关键词搜索。
• 状态筛选。
• 分页。
• 客户详情抽屉或详情页。
• 客户持仓。
• 客户风险等级。
• 客户关系状态。
• 历史投顾报告。
• 敏感信息按后端返回结果展示。

11.3 投顾服务

• 客户组合诊断。
• 基金白名单筛选。
• 标准策略库。
• 投顾建议草稿。
• 沟通话术草稿。
• 回访记录。
• 待办处理。
• 个人绩效报表。

11.4 风控中心

• 风险预警列表。
• 预警状态筛选。
• 预警详情。
• 放行确认弹窗。
• 拦截确认弹窗。
• 冻结确认弹窗。
• 风控工单列表和详情。
• 操作完成后的消息反馈。

危险操作要求：

• 操作按钮使用危险色。
• 必须经过二次确认。
• 显示操作对象和影响范围。
• 请求期间禁用重复提交。
• 成功后刷新相关列表。

11.5 公共基金数据

• 复用用户端基金列表和详情组件。
• 根据后台布局调整为表格优先。
• 展示数据来源和更新时间。
• 允许员工查看历史走势。

11.6 验收标准

• 各角色能看到符合前端规划的菜单。
• 投顾页面能够请求并展示客户和投顾数据。
• 风控页面能够展示预警并调用现有处置接口。
• 危险操作具备确认、loading、成功和失败状态。
• 敏感数据不在前端绕过后端脱敏逻辑。

12. Phase 8：Agent 聊天框

12.1 入口

• 固定在用户端官网右下角。
• 使用统一品牌色的圆形或紧凑型浮动按钮。
• 提供清晰的客服/智能助手图标。
• 不遮挡主要 CTA、基金卡片和页面底部关键内容。

12.2 展开面板

• 点击入口打开聊天框。
• 再次点击或点击关闭按钮收起。
• 固定宽度和高度，避免消息内容改变页面布局。
• 头部显示 Agent 名称和状态。
• 中部显示消息列表。
• 底部显示输入框和发送按钮。
• 支持发送中状态。
• 支持请求失败提示和重新发送。
• 支持空白输入校验。
• 保持聊天滚动位置自动跟随最新消息。

12.3 风格要求

• 使用官网和后台共用的主色、深蓝、白色和中性色。
• 保持与官网按钮相同的圆角和阴影语言。
• 聊天消息区使用清晰的用户消息与 Agent 消息层级。
• 不使用与整体品牌冲突的独立渐变主题。

12.4 接口要求

• 使用现有 Agent 接口。
• 在 API 适配层统一处理会话 ID、用户身份和错误码。
• 如果后端返回流式消息，前端逐段更新消息内容。
• 如果后端返回完整消息，前端按消息完成状态展示。
• 不在前端实现或修改 Agent 业务逻辑。

12.5 验收标准

• 入口始终位于右下角。
• 点击后聊天框可以稳定打开和关闭。
• 消息能够正确显示顺序和发送者。
• 请求期间有明确反馈。
• 失败后用户可以重试。
• 聊天框不会造成页面主要内容错位。

13. Phase 9：API 联调与质量验收

13.1 联调顺序

1. 健康检查和 API 基地址确认。
2. 登录和注册。
3. 当前用户信息。
4. 基金列表。
5. 基金历史净值。
6. 用户账户和持仓。
7. 风险测评。
8. 投顾工作台。
9. 风控预警和处置。
10. Agent 聊天接口。

13.2 测试维度

功能测试

• 路由跳转。
• 导航定位。
• 搜索和筛选。
• 分页。
• 登录注册。
• Token 恢复和退出。
• 图表展示。
• 表单提交。
• 后台角色菜单。
• 风控确认操作。
• Agent 收发消息。

状态测试

• 首次加载。
• 数据加载中。
• 数据为空。
• 接口失败。
• 网络超时。
• Token 过期。
• 无权限。
• 重复提交。

视觉测试

• 首屏背景裁切。
• 文案清晰度。
• 长页面滚动。
• 顶部导航固定效果。
• Agent 与页面内容的遮挡关系。
• 后台侧边栏和表格布局。
• 图表、标签、弹窗和按钮的一致性。

浏览器测试

• Chrome PC。
• Edge PC。
• 常见桌面分辨率。
• 大屏显示下的最大内容宽度。
• 页面缩放后的基本可用性。

13.3 数据一致性测试

• 列表中的基金代码与详情页一致。
• 基金详情净值与后端返回一致。
• 图表数据点与历史净值接口一致。
• 页面显示的数据更新时间与接口字段一致。
• 角色显示文案不影响后端请求权限。

14. 交付物

• PC 前端源代码。
• 前端环境变量示例文件。
• API 接口适配层。
• 用户端官网页面。
• 基金列表和详情页面。
• 登录注册和用户中心。
• 员工后台页面。
• Agent 聊天框。
• 前端启动说明。
• 页面路由说明。
• API 字段映射说明。
• 已知问题和待后端确认事项。

15. 依赖与风险

15.1 外部依赖

• FastAPI 服务可正常启动。
• MySQL 中存在基金产品和历史净值数据。
• API 文档、鉴权规则和接口地址可用。
• Agent 接口的请求格式和返回格式明确。
• 背景图具备使用权限或后续提供正式素材。

15.2 技术风险

• 当前项目没有现成前端工程，需要新建前端目录。
• README 描述与实际后端代码存在版本差异，需要以实际接口为准。
• 部分角色名称存在历史命名差异，前端只能做显示映射。
• 部分基金历史数据的 product_id 字段存在代码兼容逻辑，前端不得假设数据库字段结构，必须以 API 返回为准。
• 如果 API 没有返回首页所需统计字段，首页只能展示已有数据或采用不依赖真实数值的品牌模块。

15.3 产品风险

• 不得将示例数据误标为真实基金数据。
• 不得在前端使用保证收益或无风险等表述。
• 风险提示必须在基金详情和交易相关页面可见。
• 员工后台的前端菜单隐藏不能替代后端权限校验。

16. 待确认事项

1. 前端技术栈和工程目录是否直接新建 Next.js 应用。
2. 后端 API 的实际访问地址和跨域配置。
3. Agent 接口的具体路径、请求体和返回格式。
4. 首页需要展示的正式公司资料、联系方式和合规文案。
5. 背景图是否直接使用，或是否需要重新制作带华夏基金品牌的版本。
6. 用户端是否允许未登录用户查看全部基金详情。
7. 申购、赎回和风险测评页面的具体业务字段。
8. 三类员工实际登录账号的后端 user_type 和角色返回值。
9. 员工通用是否需要查看客户基础信息或只查看公共基金数据。
10. 是否需要加入隐私政策、用户协议和风险揭示书页面。

17. 最终验收清单

• PC 前端可以独立启动。
• 用户端首页为可下滑长页面。
• 首页使用指定金融背景视觉方向。
• 用户端和后台品牌色统一。
• 用户端包含登录和注册入口。
• 页面右下角存在统一风格 Agent 入口。
• Agent 聊天框可以打开、关闭和发送消息。
• 基金列表使用 API 真实数据。
• 基金详情展示历史净值和走势图。
• 用户中心展示账户和持仓信息。
• 员工可以进入后台。
• 投顾专员、风控专员、员工通用显示正确。
• 投顾页面和风控页面按角色展示。
• 风控危险操作有二次确认。
• 所有页面有加载、空数据和错误状态。
• Token 失效能够正确处理。
• 不修改后端代码、接口和数据库。