# 华夏基金 PC 前端详细开发计划 ## 1. 计划概览 | 项目 | 内容 | |---|---| | 项目名称 | 华夏基金 PC 网页平台前端 | | 计划版本 | V1.0 | | 编制日期 | 2026-09-13 | | 开发范围 | PC 浏览器前端 | | 后端约束 | 只调用现有 FastAPI 接口，不修改后端代码、数据库和权限逻辑 | | 产品形态 | 用户端官网 + 用户服务页面 + 员工后台管理系统 | ### 1.1 总体开发顺序 ```text 项目勘察 ↓ 前端工程与基础架构 ↓ 统一品牌视觉与公共组件 ↓ 用户端官网长页面 ↓ 基金列表与基金详情 ↓ 登录、注册与用户中心 ↓ 员工后台壳层与权限菜单 ↓ 投顾、风控和通用员工页面 ↓ 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 建议目录 ```text 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 `。 - 收到 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 前端角色显示映射 前端统一显示： ```text 投顾专员 风控专员 员工通用 ``` 后端返回值仅在前端适配层进行映射。前端不修改后端数据库中的角色值和权限判断。 ### 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 失效能够正确处理。 - [ ] 不修改后端代码、接口和数据库。