zhanghongyu_0626
b841f68295
- Added a new visitor chat API endpoint (`/api/chat/visitor`) to allow unauthenticated users to engage in conversations without requiring customer data. - Introduced a visitor context dependency to manage visitor interactions seamlessly. - Enhanced the chat API to support explicit session termination and improved response handling for customer service interactions. - Updated the database configuration to include Redis client support for caching visitor data. - Added a new customer note repository to persist user notes independently of the L1 profile slots. This update significantly improves the customer service experience by enabling visitor interactions and ensuring efficient data handling for both registered and unregistered users.
378 lines
15 KiB
Markdown
378 lines
15 KiB
Markdown
# JinRong 前端现代化重构设计
|
||
|
||
> 日期：2026-09-09
|
||
> 状态：设计已获用户确认，待实施计划
|
||
> 关联：`docs/superpowers/specs/2026-09-09-frontend-p0-design.md`、`docs/superpowers/specs/2026-09-09-frontend-wealth-dashboard-design.md`
|
||
|
||
## 1. 背景与目标
|
||
|
||
当前 `web/` 已具备 React 19、Vite、TypeScript、React Router、Ant Design、四角色 Dashboard、API hooks 和基础测试，但页面仍大量使用 Ant Design 默认视觉、Vite 初始 CSS 与内联样式，整体更像通用后台而不是成熟的金融科技产品。
|
||
|
||
本次重构的目标是：
|
||
|
||
1. 在不改变现有业务行为的前提下，将整个前端统一为 B「静奢智能」视觉方向。
|
||
2. 建立可被后续 agent 直接复用的 Tailwind UI 基础组件和页面组合组件。
|
||
3. 保留现有 API、鉴权、路由、数据聚合和复杂交互，降低功能回归风险。
|
||
4. 为登录页、应用壳层、四个真实 Dashboard、占位页、错误页和 Agent 提示建立一致的状态与视觉规范。
|
||
5. 提供可执行的交接手册，使后续功能接入不依赖本次重构的隐含上下文。
|
||
|
||
## 2. 非目标
|
||
|
||
本次不做以下事项：
|
||
|
||
- 不更换后端 API、接口字段、请求参数或鉴权协议。
|
||
- 不重写现有数据 hooks、聚合纯函数、金额/百分比 formatter 或路由契约。
|
||
- 不实现 Chat、SSE、完整持仓页、预警处置和问数能力等原有待办业务。
|
||
- 不把所有 Ant Design 交互控件替换成自研 Headless 组件。
|
||
- 不引入 Next.js、服务端渲染、全局状态管理或新的数据请求框架。
|
||
- 不在本次范围内增加实时行情、K 线、自选产品或交易 CTA。
|
||
|
||
## 3. 方案与技术边界
|
||
|
||
采用 Tailwind CSS 与 Ant Design 的混合方案：
|
||
|
||
```text
|
||
React 19
|
||
├── Tailwind CSS 负责设计令牌、布局、间距、排版、颜色、响应式和轻量动效
|
||
├── Ant Design 保留 Table、Pagination、Alert、Result、Empty、Skeleton、message 等交互
|
||
├── @ant-design/charts 保留现有图表实现和数据配置
|
||
├── React Router 保留现有路由与鉴权跳转
|
||
└── API + hooks 保留现有数据请求和聚合链路
|
||
```
|
||
|
||
### 3.1 Tailwind 的职责
|
||
|
||
Tailwind 负责新视觉层，包括：
|
||
|
||
- 暖白/米灰页面背景；
|
||
- 墨蓝品牌色和正文色；
|
||
- 翡翠绿、朱砂红、浅金色等语义色；
|
||
- 卡片边框、圆角、阴影和状态层级；
|
||
- 页面网格、响应式布局、标题层级和数字排版；
|
||
- hover、focus、淡入等低强度反馈动效。
|
||
|
||
### 3.2 Ant Design 的职责
|
||
|
||
Ant Design 继续承载已经验证的复杂行为：
|
||
|
||
- 数据表格、排序、分页和空数据渲染；
|
||
- Alert、Result、Empty、Skeleton 等状态组件；
|
||
- toast/message；
|
||
- 图表组件及其 tooltip、legend 和数据配置。
|
||
|
||
新代码不通过全局 `!important` 破坏 Ant Design 内部行为。视觉适配使用组件 wrapper、`className`、局部选择器和主题变量。
|
||
|
||
## 4. 设计语言
|
||
|
||
### 4.1 视觉定位
|
||
|
||
「静奢智能」强调长期财富管理场景需要的可信、克制和精致，同时吸收 Stripe、Linear、Notion 等科技产品的留白、信息层次和细节质感。
|
||
|
||
- 不使用大面积高饱和渐变；
|
||
- 不使用重玻璃拟态或强烈霓虹效果；
|
||
- 不用装饰图替代数据层级；
|
||
- 通过排版、留白、细边框、微阴影和状态色建立高级感；
|
||
- 数据页保持足够密度，避免为了视觉留白牺牲可读性。
|
||
|
||
### 4.2 设计令牌
|
||
|
||
| 用途 | 令牌 | 值 |
|
||
| --- | --- | --- |
|
||
| 页面背景 | `--jr-bg` | `#F6F5F1` |
|
||
| 内容面 | `--jr-surface` | `#FBFAF7` |
|
||
| 纯白面 | `--jr-surface-strong` | `#FFFFFF` |
|
||
| 墨蓝主色 | `--jr-ink` | `#132B3A` |
|
||
| 标题文字 | `--jr-text` | `#17212B` |
|
||
| 次级文字 | `--jr-muted` | `#71808A` |
|
||
| 边框 | `--jr-border` | `#E5E2DB` |
|
||
| 翡翠绿 | `--jr-positive` | `#178A68` |
|
||
| 朱砂红 | `--jr-negative` | `#C9564A` |
|
||
| 浅金 | `--jr-gold` | `#C9A66B` |
|
||
| 信息蓝 | `--jr-info` | `#3F718A` |
|
||
| 大圆角 | `--jr-radius-lg` | `16px` |
|
||
| 普通圆角 | `--jr-radius-md` | `12px` |
|
||
| 小圆角 | `--jr-radius-sm` | `8px` |
|
||
| 内容阴影 | `--jr-shadow` | 低强度暖灰阴影 |
|
||
|
||
收益语义继续遵循现有产品约定：正值朱砂红、负值翡翠绿、零值次级灰。令牌集中定义，页面不硬编码新的品牌色。
|
||
|
||
### 4.3 字体与数字
|
||
|
||
中文使用系统 UI 字体栈，数字和关键金额使用等宽数字特性：
|
||
|
||
```css
|
||
font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI",
|
||
"PingFang SC", "Microsoft YaHei", sans-serif;
|
||
font-variant-numeric: tabular-nums;
|
||
```
|
||
|
||
## 5. 目录与组件边界
|
||
|
||
目标目录如下：
|
||
|
||
```text
|
||
web/src/
|
||
├── components/
|
||
│ ├── ui/
|
||
│ │ ├── Button.tsx
|
||
│ │ ├── Surface.tsx
|
||
│ │ ├── Badge.tsx
|
||
│ │ ├── MetricCard.tsx
|
||
│ │ ├── PageHeader.tsx
|
||
│ │ ├── SectionHeading.tsx
|
||
│ │ ├── EmptyState.tsx
|
||
│ │ └── cn.ts
|
||
│ ├── layout/
|
||
│ │ ├── AppShell.tsx
|
||
│ │ ├── BrandSidebar.tsx
|
||
│ │ └── Topbar.tsx
|
||
│ └── dashboard/
|
||
│ ├── DashboardLayout.tsx
|
||
│ ├── DashboardHero.tsx
|
||
│ ├── ChartCard.tsx
|
||
│ ├── QuickActionBar.tsx
|
||
│ └── DataSection.tsx
|
||
├── pages/
|
||
├── hooks/
|
||
├── api/
|
||
├── routes/
|
||
├── stores/
|
||
├── utils/
|
||
└── styles/
|
||
├── tokens.css
|
||
└── global.css
|
||
```
|
||
|
||
### 5.1 `components/ui`
|
||
|
||
纯视觉基础组件，不导入 API、hooks、authStore 或业务类型：
|
||
|
||
- `Button`：有限的 variant/size，统一 focus、disabled、loading 视觉；链接场景通过 props 或外部 `Link` 组合。
|
||
- `Surface`：统一面板边框、圆角、内边距和层级变体。
|
||
- `Badge`：角色、状态、环境和风险标签。
|
||
- `MetricCard`：标题、主值、辅助说明、趋势/状态插槽。
|
||
- `PageHeader`：eyebrow、标题、说明和右侧 action 区。
|
||
- `SectionHeading`：数据区标题、说明和扩展操作。
|
||
- `EmptyState`：品牌化空状态，支持插画、说明和下一步入口。
|
||
- `cn`：合并 className 的小型工具，不承载业务逻辑。
|
||
|
||
每个组件都使用明确的 TypeScript props，并通过有限变体避免页面自由拼接出不一致的样式。
|
||
|
||
### 5.2 `components/layout`
|
||
|
||
应用级布局只接收 props：
|
||
|
||
- `AppShell`：组合侧栏、顶栏和内容区，不发起 API 请求。
|
||
- `BrandSidebar`：接收角色、菜单项、当前路径、折叠状态和导航回调；继续消费 `buildMenuGroups()` 产出的菜单。
|
||
- `Topbar`：接收角色、actor ID、当前页面上下文、折叠回调和退出回调。
|
||
|
||
布局组件不读取 `authStore`，由 `AppLayout` 负责组装现有 auth 数据和路由状态。
|
||
|
||
### 5.3 `components/dashboard`
|
||
|
||
只负责 Dashboard 的视觉组合和布局，不改变数据：
|
||
|
||
- `DashboardLayout`：统一 PageHeader、Notice、Hero、ActionRail、InsightGrid 和 DataSection。
|
||
- `DashboardHero`：主指标、辅助指标、金额掩码和角色状态。
|
||
- `ChartCard`：图表标题、说明和图表容器。
|
||
- `QuickActionBar`：快捷入口卡片/按钮。
|
||
- `DataSection`：表格标题、数据范围、AntD Table wrapper。
|
||
|
||
页面继续持有 `useHoldingsDashboard`、`useAdvisorRosterDashboard`、`useMarketSnapshot`、`useAlertsDashboard`，并把结果传入组合组件。
|
||
|
||
## 6. 页面设计
|
||
|
||
### 6.1 登录页
|
||
|
||
结构：
|
||
|
||
```text
|
||
LoginPage
|
||
├── BrandPanel
|
||
│ ├── Logo + 品牌名
|
||
│ ├── 产品定位和环境标识
|
||
│ ├── 轻量金融插画
|
||
│ └── 产品能力摘要
|
||
└── LoginPanel
|
||
├── eyebrow / 标题 / 说明
|
||
├── 四个演示账号卡片
|
||
└── Mock JWT / FastAPI 环境说明
|
||
```
|
||
|
||
行为保持不变：点击账号仍调用 `login()`，成功后保存 `AuthState`、显示成功消息并跳转账号的 `defaultRoute`；失败仍显示 `ApiError` 信息。
|
||
|
||
账号卡片只增加角色标签、actor ID 和工作台描述，不改变账号配置或登录请求。
|
||
|
||
### 6.2 应用壳层
|
||
|
||
```text
|
||
AppLayout
|
||
└── AppShell
|
||
├── BrandSidebar
|
||
├── Topbar
|
||
└── MainContent
|
||
└── Outlet
|
||
```
|
||
|
||
- 展开态侧栏保留品牌、角色上下文和菜单分组；
|
||
- 折叠态保留 Logo 和图标，确保 tooltip/可访问名称可用；
|
||
- 顶栏保留 actor ID 复制、角色标识和退出入口；
|
||
- 当前路由选中规则继续基于 `location.pathname`；
|
||
- 宽屏使用固定侧栏，窄屏使用抽屉或可收起侧栏，不改变菜单路径；
|
||
- 内容区不设置会压缩数据表格的固定最大宽度。
|
||
|
||
### 6.3 四个 Dashboard
|
||
|
||
统一结构：
|
||
|
||
```text
|
||
PageHeader
|
||
Notice
|
||
DashboardHero
|
||
QuickActionBar
|
||
InsightGrid
|
||
DataSection
|
||
```
|
||
|
||
各页只改变文案、指标和现有数据配置：
|
||
|
||
| 页面 | Hero | 图表 | 表格 |
|
||
| --- | --- | --- | --- |
|
||
| 客户资产 | 总市值、昨日收益、累计盈亏、持仓只数 | 持仓结构、产品盈亏 | 现有 HoldingRow |
|
||
| 理财师客户 | 客户数、客户总市值、最大客户、待跟进 | 客户资产结构、Top 客户 | 现有 AdvisorRosterRow |
|
||
| 分析员市场 | 产品数、上涨、下跌、平盘 | 产品类型分布、类型平均涨跌 | 现有 ProductRow Top10 |
|
||
| 风控监测 | 待审总数、今日新增、涉及客户 | 预警类型分布、平均风险分 | 现有 RiskAlertItem |
|
||
|
||
现有列、默认排序、分页、行操作、数据截至文案、金额掩码、收益颜色、风控 disclaimer 和图表数据均保持原行为。
|
||
|
||
### 6.4 占位页、错误页与 Agent 提示
|
||
|
||
- `PlaceholderPage`：使用 `PageHeader + EmptyState + 返回/下一步入口`，不显示假 KPI。
|
||
- `ApiErrorResult`：使用品牌化错误面板，但继续展示 error code、message、trace ID 和重试按钮。
|
||
- `AgentBanner`：保留 info/warning 语义，统一成窄幅提示面板。
|
||
- `Empty`、`Skeleton`、`Alert` 等 AntD 组件通过 wrapper 进入新的 Surface 层，不改变状态触发条件。
|
||
|
||
## 7. 数据与功能不变约束
|
||
|
||
以下契约在迁移前后必须一致：
|
||
|
||
```text
|
||
API URL、HTTP method、参数和请求头 不变
|
||
AuthState 字段和 localStorage key 不变
|
||
路由 path 和登录默认落点 不变
|
||
Hook 返回字段和加载/错误生命周期 不变
|
||
聚合纯函数和数值公式 不变
|
||
金额、百分比、收益颜色语义 不变
|
||
表格排序、分页、行操作和跳转 不变
|
||
错误码、trace_id、disclaimer 展示 不变
|
||
```
|
||
|
||
页面层仅替换 JSX 外壳、className 和组合组件；不把请求逻辑迁移进视觉组件，也不使用假数据作为错误兜底。
|
||
|
||
## 8. 迁移顺序
|
||
|
||
### 阶段 1：设计系统
|
||
|
||
1. 安装并配置 Tailwind CSS。
|
||
2. 建立 `tokens.css`、global reset 和 AntD bridge。
|
||
3. 实现 `components/ui` 基础组件。
|
||
4. 保持旧页面可构建，暂不删除旧样式。
|
||
|
||
### 阶段 2：壳层与通用状态
|
||
|
||
1. 实现 `AppShell`、`BrandSidebar`、`Topbar`。
|
||
2. 迁移 `AppLayout`，保留菜单计算、selected key、退出和 Outlet。
|
||
3. 迁移登录页。
|
||
4. 迁移 `PageShell`、`PlaceholderPage`、`ApiErrorResult`、`AgentBanner`。
|
||
5. 验证四个 Demo 账号、菜单和退出。
|
||
|
||
### 阶段 3：Dashboard 组合
|
||
|
||
1. 迁移 `DashboardHero`。
|
||
2. 实现 `ChartCard`、`DataSection`、新版 `QuickActionBar`。
|
||
3. 迁移 `DashboardLayout`，保留现有图表和 Table 数据配置。
|
||
4. 先完成客户资产页并验证金额、收益、掩码、表格排序。
|
||
|
||
### 阶段 4：角色页面
|
||
|
||
依次迁移：客户资产、分析员市场、理财师客户、风控预警。每页迁移后执行构建、测试和浏览器走查。
|
||
|
||
### 阶段 5：收尾与文档
|
||
|
||
1. 删除已无引用的 Vite 默认 CSS 和旧布局样式。
|
||
2. 统一状态、窄屏布局和 focus 样式。
|
||
3. 编写 `docs/frontend/FRONTEND-HANDOFF.md`。
|
||
4. 执行完整 build、test、lint 和实际浏览器验收。
|
||
|
||
## 9. 测试与验收
|
||
|
||
### 9.1 自动化命令
|
||
|
||
```bash
|
||
cd web
|
||
npm run build
|
||
npm run test
|
||
npm run lint
|
||
```
|
||
|
||
### 9.2 功能验收
|
||
|
||
- 四个演示账号登录后进入各自 Dashboard；
|
||
- 侧栏分组、选中态、折叠态、窄屏抽屉和退出可用；
|
||
- 刷新按钮仍重新调用对应 API；
|
||
- 客户金额掩码仍写入并读取原 localStorage key；
|
||
- 表格排序、分页和行操作不变；
|
||
- 风控无预警时显示空状态，有预警时显示表格、图表和 disclaimer；
|
||
- API 失败时显示统一错误面板和 trace ID；
|
||
- 1280px 桌面布局无异常，窄屏无横向溢出；
|
||
- 不出现假数字、空白白屏或浏览器 console 中新增的严重错误。
|
||
|
||
### 9.3 数值回归锚点
|
||
|
||
沿用现有 Dashboard 设计稿的验收值：
|
||
|
||
- 客户 CUST-9527：总市值 `149940.00`、累计盈亏 `+137.08`、昨日收益 `-254.40`；
|
||
- 理财师 STAFF-10086：客户数 `12`、总市值 `1654850.00`；
|
||
- 分析员 STAFF-20001：产品 `14`、上涨 `10`、下跌 `4`；
|
||
- 风控 reset 后：待审预警 `0`，显示 Empty 而非假数据。
|
||
|
||
## 10. 交接手册
|
||
|
||
新增 `docs/frontend/FRONTEND-HANDOFF.md`，内容包括：
|
||
|
||
1. 启动、构建、测试和 lint 命令；
|
||
2. 目录地图及 API/hooks/ui 的依赖方向；
|
||
3. Tailwind 令牌、语义颜色、字体和间距规范；
|
||
4. UI 组件 props、变体和最小用法；
|
||
5. Dashboard 页面模板与角色页接入步骤；
|
||
6. 新 API hook 的页面接入边界；
|
||
7. Loading、Success、Empty、Error、Permission 状态规范；
|
||
8. Ant Design 与 Tailwind 的职责边界；
|
||
9. Chat、表格、图表的扩展位置；
|
||
10. 浏览器验收清单和常见故障；
|
||
11. 后续 agent 的工作约定和禁止事项。
|
||
|
||
后续 agent 应优先复用 `components/ui` 和 `components/dashboard`，页面负责数据请求与路由，领域组件负责业务组合，任何共享组件修改都必须运行完整验证命令。
|
||
|
||
## 11. 风险与控制
|
||
|
||
| 风险 | 控制措施 |
|
||
| --- | --- |
|
||
| Tailwind 与 AntD 样式冲突 | 使用 CSS layer、局部 wrapper 和 token，不使用全局强制覆盖 |
|
||
| 页面迁移导致数据回归 | 不修改 hooks/API/utils，逐页迁移并保留数值锚点 |
|
||
| 共享组件被过度业务化 | `ui` 组件禁止导入业务模块，props 只传展示所需数据 |
|
||
| 窄屏表格溢出 | 壳层采用可伸缩内容区，表格保留 AntD 横向滚动能力 |
|
||
| 删除旧 CSS 过早导致回归 | 阶段 5 才清理无引用样式，先通过构建和浏览器验证 |
|
||
| 后续 agent 不知道扩展位置 | 交接手册记录目录、边界、模板和验收矩阵 |
|
||
|
||
## 12. 完成定义
|
||
|
||
重构完成需同时满足：
|
||
|
||
1. 登录、壳层、四个 Dashboard、占位页和错误页采用统一「静奢智能」视觉；
|
||
2. Tailwind 设计令牌和可复用 UI 组件可被其他页面直接使用；
|
||
3. 原 API、鉴权、路由、数据公式和交互契约未改变；
|
||
4. `npm run build`、`npm run test`、`npm run lint` 全部通过；
|
||
5. 浏览器完成四角色登录、导航、刷新、空态、错误态和窄屏走查；
|
||
6. `docs/frontend/FRONTEND-HANDOFF.md` 可指导后续 agent 新增页面或组件。
|