a332d5571a
- 将文件从 61KB 精简到 5.5KB（减少 91%） - 删除冗长的目录结构详解，改为表格速查 - 删除大量代码示例，保留核心概念 - 引用独立文档（TYPESCRIPT_MIGRATION.md）替代详细内容 - 保留技术栈、命令、目录结构、开发工作流等核心信息 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
209 lines
5.3 KiB
Markdown
209 lines
5.3 KiB
Markdown
# 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（后台任务）
|
||
|
||
---
|
||
|
||
## 开发命令
|
||
|
||
```bash
|
||
# 前端开发
|
||
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` 定义
|
||
|
||
**命令**:
|
||
```bash
|
||
npm run type-check # 类型检查
|
||
npm run type-check:watch # 监听模式
|
||
```
|
||
|
||
详细指南参考: [TYPESCRIPT_MIGRATION.md](./TYPESCRIPT_MIGRATION.md)
|
||
|
||
---
|
||
|
||
## 后端架构
|
||
|
||
### 核心文件
|
||
- `app.py` - Flask 主应用（API + WebSocket）
|
||
- `simulation_background_processor.py` - Celery 后台任务
|
||
- `concept_api.py` - 概念分析独立服务
|
||
|
||
### 数据库
|
||
| 数据库 | 用途 |
|
||
|--------|------|
|
||
| ClickHouse | 时序数据（股票日线、分钟线） |
|
||
| MySQL | 事务数据（用户、订单、持仓） |
|
||
| Redis | 缓存 + Celery 消息队列 |
|
||
|
||
### API 规范
|
||
```python
|
||
# 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+ 个页面使用
|
||
|
||
---
|
||
|
||
## 更新本文档
|
||
|
||
在以下情况下更新此文档:
|
||
- 添加新的架构模式
|
||
- 做出重要技术决策
|
||
- 进行重要代码重构
|