vf_react/CLAUDE.md

CLAUDE.md

🌐 语言偏好: 请始终使用中文与用户交流，包括所有解释、分析、文档编写和代码注释。

本文件为 Claude Code 提供在此代码库中工作的指导说明。

---

项目概览

混合式 React 仪表板，用于金融/交易分析，采用 Flask 后端。基于 Argon Dashboard Chakra PRO 模板构建。

技术栈

前端

• 核心: React 18.3.1 + TypeScript 5.9.3（渐进式迁移中）
• UI: Chakra UI 2.10.9（主要）+ Ant Design 5.27.4（表格/表单）+ HeroUI 3.0.0-beta（AgentChat）
• 状态: Redux Toolkit 2.9.2
• 路由: React Router v6.30.1 + React.lazy() 代码分割
• 构建: CRACO 7.1.0 + webpack 5 优化
• 图表: ECharts 5.6.0、ApexCharts、Recharts、D3、Visx
• 其他: Framer Motion、FullCalendar、Socket.IO Client、MSW、PostHog

后端

• Flask + SQLAlchemy ORM
• ClickHouse（分析型）+ MySQL（事务型）+ Redis（缓存）
• Flask-SocketIO（WebSocket）+ Celery（后台任务）

---

开发命令

# 前端开发
npm start                    # Mock 模式启动（默认）
npm run start:real           # 真实后端
npm run build                # 生产构建
npm run lint:check           # ESLint 检查
npm run type-check           # TypeScript 类型检查

# 后端开发
python app.py                # Flask 服务器
python simulation_background_processor.py  # Celery 后台处理

# 部署
npm run deploy               # 部署到生产环境

---

架构

应用入口流程

src/index.js → App.js
├── AppProviders (Redux → Chakra → Ant ConfigProvider → Notification → Auth)
├── AppRoutes (src/routes/index.js)
└── GlobalComponents

路由保护模式

• PUBLIC - 无需认证
• MODAL - 未登录显示认证模态框
• REDIRECT - 未登录重定向到登录页

目录结构速查

目录	用途
src/views/	页面组件（按功能模块组织）
src/components/	可复用 UI 组件
src/services/	API 服务层
src/store/slices/	Redux 状态
src/hooks/	自定义 Hooks
src/contexts/	React Context
src/utils/	工具函数
src/constants/	常量定义
src/types/	TypeScript 类型
src/theme/	Chakra UI 主题
src/routes/	路由配置
src/mocks/	MSW Mock 数据
src/layouts/	页面布局模板

路径别名

@/ → src/
@components/ → src/components/
@views/ → src/views/
@services/ → src/services/
@store/ → src/store/
@hooks/ → src/hooks/
@utils/ → src/utils/
@types/ → src/types/
@constants/ → src/constants/

---

开发工作流

添加新路由

1. src/routes/lazy-components.js - 添加 lazy import
2. src/routes/routeConfig.js - 配置路由（path、component、protection、layout）

添加新 API

1. src/services/ - 创建服务函数
2. src/mocks/handlers/ - 添加 MSW handler（Mock 模式）

添加新 Redux Slice

1. src/store/slices/yourSlice.ts - 创建 slice
2. src/store/index.js - 导入并添加到 store

组件组织

• 原子设计: Atoms → Molecules → Organisms
• 页面专属组件: 放在 views/{PageName}/components/
• 可复用组件: 放在 src/components/

---

配置

环境文件

• .env.mock - Mock 模式（默认，REACT_APP_ENABLE_MOCK=true）
• .env.development - 开发模式
• .env.production - 生产环境

MSW Mock

• 激活: REACT_APP_ENABLE_MOCK=true
• Handlers: src/mocks/handlers/
• 数据: src/mocks/data/

---

TypeScript 接入

状态: 渐进式迁移中，支持 JS/TS 混合开发

类型定义位置: src/types/

• api.ts - ApiResponse、PaginatedResponse、ApiError
• stock.ts - StockInfo、StockQuote、KLineData
• user.ts - UserInfo、AuthInfo

开发规范:

• 新代码必须使用 TypeScript
• 避免使用 any
• 组件 Props 使用 interface 定义

命令:

npm run type-check        # 类型检查
npm run type-check:watch  # 监听模式

详细指南参考: TYPESCRIPT_MIGRATION.md

---

后端架构

核心文件

• app.py - Flask 主应用（API + WebSocket）
• simulation_background_processor.py - Celery 后台任务
• concept_api.py - 概念分析独立服务

数据库

数据库	用途
ClickHouse	时序数据（股票日线、分钟线）
MySQL	事务数据（用户、订单、持仓）
Redis	缓存 + Celery 消息队列

API 规范

# RESTful 风格
GET    /api/stocks           # 获取列表
GET    /api/stocks/:id       # 获取单个
POST   /api/stocks           # 创建
PUT    /api/stocks/:id       # 更新
DELETE /api/stocks/:id       # 删除

# 统一响应格式
{ "code": 200, "message": "success", "data": {...} }

---

代码规范

命名约定

• 组件/目录: PascalCase (EventCard)
• 文件/函数: camelCase (formatPrice.js)
• 常量: SCREAMING_SNAKE_CASE (API_BASE_URL)
• 路由路径: kebab-case (/trading-simulation)

最佳实践

• 组件不直接调用 axios，通过 service 层
• 使用 getApiBase() 获取 API 基础 URL
• 页面超过 500 行考虑拆分
• 复用组件需在 2+ 个页面使用

---

更新本文档

在以下情况下更新此文档:

• 添加新的架构模式
• 做出重要技术决策
• 进行重要代码重构