# 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+ 个页面使用

---

## 更新本文档

在以下情况下更新此文档:
- 添加新的架构模式
- 做出重要技术决策
- 进行重要代码重构