518 lines
13 KiB
Markdown
518 lines
13 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
---
|
||
|
||
# React Arco Design Pro 项目指南
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于 React 17 + Arco Design + TypeScript + Vite 的企业级中后台管理系统模板项目。项目采用前后端分离架构，使用 Redux 进行状态管理，使用 Mock.js 模拟后端数据。
|
||
|
||
## 常用命令
|
||
|
||
### 开发与构建
|
||
|
||
```bash
|
||
# 启动开发服务器（推荐）
|
||
npm run dev
|
||
# 或
|
||
npm start
|
||
|
||
# 生产环境构建
|
||
npm run build
|
||
|
||
# 预览生产构建
|
||
npm run preview
|
||
```
|
||
|
||
### 代码质量检查
|
||
|
||
```bash
|
||
# ESLint 检查并自动修复
|
||
npm run eslint
|
||
|
||
# Stylelint 检查并自动修复
|
||
npm run stylelint
|
||
|
||
# Git 提交前检查（自动执行）
|
||
npm run pre-commit
|
||
```
|
||
|
||
**注意**: 建议在 `.eslintrc.js` 中配置规则，禁止在响应码判断时使用严格相等：
|
||
|
||
```javascript
|
||
// 可选：配置 ESLint 规则提醒
|
||
rules: {
|
||
// 其他规则...
|
||
// 在代码审查时人工检查响应码判断逻辑
|
||
}
|
||
```
|
||
|
||
### 包管理
|
||
|
||
项目使用 pnpm 作为包管理器，但 npm/yarn 也兼容。建议使用 pnpm 以保持依赖一致性。
|
||
|
||
## 核心架构设计
|
||
|
||
### 技术栈核心
|
||
|
||
- **构建工具**: Vite 2.6.14（快速 HMR，基于 ESM）
|
||
- **UI 框架**: React 17.0.2
|
||
- **UI 组件库**: @arco-design/web-react 2.32.2（字节跳动开源）
|
||
- **状态管理**: Redux 4.1.2（传统模式，非 Redux Toolkit）
|
||
- **路由**: React Router 5.2.0
|
||
- **HTTP 客户端**: Axios 0.24.0
|
||
- **CSS 预处理**: Less 4.1.2
|
||
- **类型系统**: TypeScript 4.5.2（strict: false）
|
||
|
||
### 架构分层
|
||
|
||
```
|
||
src/
|
||
├── pages/ # 页面组件（按功能模块组织，支持懒加载）
|
||
├── components/ # 公共组件（NavBar, TabBar, Footer 等）
|
||
├── layout.tsx # 主布局组件（侧边栏、标签页、内容区）
|
||
├── routes.ts # 路由配置 + 权限过滤逻辑
|
||
├── store/ # Redux 状态管理（settings, userInfo, tabs）
|
||
├── utils/ # 工具函数（认证、主题、国际化等）
|
||
├── mock/ # Mock.js 数据模拟
|
||
├── locale/ # 国际化资源文件
|
||
└── main.tsx # 应用入口
|
||
```
|
||
|
||
### 关键架构模式
|
||
|
||
#### 1. 路由懒加载机制
|
||
|
||
- 使用 `import.meta.glob()` 动态导入页面组件
|
||
- 通过 `@loadable/component` 实现代码分割
|
||
- 路由配置在 `src/routes.ts`，约定式路由：`./pages/${route.key}/index.tsx`
|
||
|
||
#### 2. 权限控制系统
|
||
|
||
- **路由级权限**: `routes.ts` 中的 `useRoute` Hook 根据用户权限过滤路由
|
||
- **组件级权限**: 使用 `<PermissionWrapper>` 组件包裹需要权限控制的元素
|
||
- **权限验证**: `utils/authentication.ts` 提供权限判断逻辑
|
||
- **角色系统**: 简单的 Admin/User 角色，权限存储在 Redux Store
|
||
|
||
#### 3. 状态管理架构
|
||
|
||
Redux Store 管理三类全局状态：
|
||
|
||
```typescript
|
||
// src/store/index.ts
|
||
GlobalState {
|
||
settings: { // 系统设置（主题色、布局配置）
|
||
themeColor,
|
||
navbar,
|
||
menu,
|
||
footer
|
||
},
|
||
userInfo: { // 用户信息
|
||
name,
|
||
avatar,
|
||
permissions // 权限映射表
|
||
},
|
||
tabs: { // 多标签页状态
|
||
activeKey,
|
||
tabs[]
|
||
}
|
||
}
|
||
```
|
||
|
||
**重要**: Redux 使用传统模式（非 Redux Toolkit），所有 Action 通过字符串类型派发。
|
||
|
||
#### 4. 主题系统
|
||
|
||
- **主题配置**: `src/settings.json` 定义默认主题色
|
||
- **主题切换**: `utils/changeTheme.ts` 切换明暗模式
|
||
- **色值计算**: `utils/initThemeColor.ts` 根据主题色自动生成 10 个梯度色
|
||
- **Vite 集成**: `vite.config.ts` 通过 `@arco-plugins/vite-react` 注入主题变量
|
||
|
||
#### 5. 多标签页系统
|
||
|
||
标签页状态由 Redux 管理，支持：
|
||
|
||
- 添加/关闭标签页（`tabs/addTab`, `tabs/removeTab`）
|
||
- 切换标签页（`tabs/setActiveTab`）
|
||
- 右键菜单操作（关闭左侧/右侧/其他）
|
||
|
||
标签页与路由联动，在 `layout.tsx` 中实现。
|
||
|
||
### 数据流设计
|
||
|
||
```
|
||
用户交互 → Component
|
||
↓
|
||
dispatch Redux Action
|
||
↓
|
||
Reducer 更新 Store
|
||
↓
|
||
useSelector 订阅变化
|
||
↓
|
||
Component 重新渲染
|
||
```
|
||
|
||
HTTP 请求流：
|
||
|
||
```
|
||
Component → axios → Mock.js (开发环境) / Backend API (生产环境) → Component State/Redux
|
||
```
|
||
|
||
### 路径别名配置
|
||
|
||
```typescript
|
||
// 在代码中使用 @/ 代替 src/
|
||
import utils from '@/utils/xxx';
|
||
```
|
||
|
||
配置位置：
|
||
|
||
- `tsconfig.json`: `"@/*": ["src/*"]`
|
||
- `vite.config.ts`: `alias: [{ find: '@', replacement: '/src' }]`
|
||
|
||
## API 开发规范
|
||
|
||
### 响应码处理规范
|
||
|
||
**【重要】必须使用宽松相等判断响应码，避免类型不一致问题**
|
||
|
||
#### 问题背景
|
||
|
||
后端不同接口可能返回不同类型的响应码：
|
||
|
||
- 部分接口返回字符串 `"0"`
|
||
- 部分接口返回数字 `0`
|
||
|
||
使用严格相等 `===` 判断时会导致类型不匹配，即使业务成功也会被判断为失败。
|
||
|
||
#### 强制规范
|
||
|
||
**1. 在所有业务代码中判断响应码时，必须使用宽松相等 `==`**
|
||
|
||
```typescript
|
||
// ✅ 正确：使用宽松相等
|
||
if (result.code == SUCCESS_CODE) {
|
||
// 处理成功逻辑
|
||
}
|
||
|
||
if (result.code == 0) {
|
||
// 处理成功逻辑
|
||
}
|
||
|
||
// ❌ 错误：使用严格相等
|
||
if (result.code === SUCCESS_CODE) {
|
||
// 可能导致字符串 "0" !== 数字 0
|
||
// 处理成功逻辑
|
||
}
|
||
```
|
||
|
||
**2. 响应拦截器中必须使用宽松相等**
|
||
|
||
在 `src/utils/request.ts` 响应拦截器中：
|
||
|
||
```typescript
|
||
// ✅ 正确
|
||
if (data.code == SUCCESS_CODE) {
|
||
return response;
|
||
}
|
||
|
||
// ❌ 错误
|
||
if (data.code === SUCCESS_CODE) {
|
||
return response;
|
||
}
|
||
```
|
||
|
||
**3. 类型守卫函数中必须使用宽松相等**
|
||
|
||
在 `src/types/api.ts` 中：
|
||
|
||
```typescript
|
||
// ✅ 正确
|
||
export function isSuccessResponse<T>(response: R<T>): boolean {
|
||
return response.code == 0;
|
||
}
|
||
|
||
// ❌ 错误
|
||
export function isSuccessResponse<T>(response: R<T>): boolean {
|
||
return response.code === 0;
|
||
}
|
||
```
|
||
|
||
#### 适用范围
|
||
|
||
以下场景必须遵守此规范：
|
||
|
||
1. **登录处理** (`src/pages/login/form.tsx`)
|
||
2. **用户信息页面** (`src/pages/user-info/index.tsx`)
|
||
3. **用户管理页面** (`src/pages/user-management/`)
|
||
4. **所有调用后端 API 的业务代码**
|
||
5. **所有自定义的响应处理工具函数**
|
||
|
||
#### 常量定义
|
||
|
||
在 `src/constants/index.ts` 中：
|
||
|
||
```typescript
|
||
// 响应码定义为数字类型（推荐）
|
||
export const SUCCESS_CODE = 0;
|
||
export const ERROR_CODE = 1;
|
||
```
|
||
|
||
#### 检查清单
|
||
|
||
在编写或修改 API 调用代码时，必须检查：
|
||
|
||
- [ ] 所有 `result.code === xxx` 改为 `result.code == xxx`
|
||
- [ ] 所有 `response.code === xxx` 改为 `response.code == xxx`
|
||
- [ ] 响应拦截器使用宽松相等判断
|
||
- [ ] 工具函数使用宽松相等判断
|
||
|
||
#### 历史问题记录
|
||
|
||
**问题日期**: 2025-11-17
|
||
|
||
**问题描述**: 登录功能失效，用户管理页面空白
|
||
|
||
**根本原因**:
|
||
|
||
- 后端登录接口返回 `code: "0"` (字符串)
|
||
- 前端使用 `result.code === 0` (严格相等判断数字)
|
||
- 导致 `"0" !== 0`，成功响应被判断为失败
|
||
|
||
**解决方案**:
|
||
|
||
1. 将所有 `===` 改为 `==` 进行宽松相等判断
|
||
2. 修改了以下文件：
|
||
- `src/utils/request.ts`
|
||
- `src/pages/login/form.tsx`
|
||
- `src/pages/user-info/index.tsx`
|
||
- `src/pages/user-management/UserFormModal.tsx`
|
||
- `src/pages/user-management/index.tsx`
|
||
- `src/types/api.ts`
|
||
|
||
**预防措施**: 制定本规范文档，在代码审查时强制检查
|
||
|
||
### API 调用最佳实践
|
||
|
||
```typescript
|
||
// 1. 标准 API 调用模式
|
||
async function fetchData() {
|
||
try {
|
||
const result = await apiFunction(params);
|
||
|
||
// ✅ 使用宽松相等判断
|
||
if (result.code == SUCCESS_CODE) {
|
||
// 处理成功逻辑
|
||
setData(result.data);
|
||
}
|
||
// 错误消息已在拦截器中显示，无需额外处理
|
||
} catch (error) {
|
||
console.error('请求失败:', error);
|
||
// 异常已在拦截器中提示，此处仅需记录日志
|
||
}
|
||
}
|
||
|
||
// 2. 带加载状态的 API 调用
|
||
async function handleSubmit() {
|
||
try {
|
||
setLoading(true);
|
||
const result = await apiFunction(params);
|
||
|
||
if (result.code == SUCCESS_CODE) {
|
||
Message.success('操作成功');
|
||
onSuccess();
|
||
}
|
||
} catch (error) {
|
||
console.error('操作失败:', error);
|
||
} finally {
|
||
setLoading(false);
|
||
}
|
||
}
|
||
```
|
||
|
||
## 关键开发约定
|
||
|
||
### 页面组件开发
|
||
|
||
1. **文件位置**: 所有页面放在 `src/pages/{module-name}/index.tsx`
|
||
2. **路由注册**: 在 `src/routes.ts` 的 `routes` 数组中添加路由配置
|
||
3. **权限控制**: 通过 `requiredPermissions` 和 `oneOfPerm` 配置权限
|
||
4. **国际化**: 页面标题使用 `locale` 多语言 key
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
// src/routes.ts
|
||
{
|
||
name: 'menu.moduleName', // 国际化 key
|
||
key: 'module-name', // 对应 pages/module-name/index.tsx
|
||
requiredPermissions: [ // 可选：需要的权限
|
||
{ resource: 'module', actions: ['read'] }
|
||
]
|
||
}
|
||
```
|
||
|
||
### Redux 状态操作
|
||
|
||
```typescript
|
||
// 获取状态
|
||
import { useSelector } from 'react-redux';
|
||
const { userInfo, settings } = useSelector((state: GlobalState) => state);
|
||
|
||
// 更新状态
|
||
import { useDispatch } from 'react-redux';
|
||
const dispatch = useDispatch();
|
||
dispatch({
|
||
type: 'update-userInfo',
|
||
payload: { userInfo: newUserInfo },
|
||
});
|
||
```
|
||
|
||
### 国际化使用
|
||
|
||
```typescript
|
||
// 在组件中使用国际化
|
||
import useLocale from '@/utils/useLocale';
|
||
import locale from './locale'; // 本地语言文件
|
||
|
||
function MyComponent() {
|
||
const t = useLocale(locale);
|
||
return <div>{t['key.name']}</div>;
|
||
}
|
||
```
|
||
|
||
### 主题色动态修改
|
||
|
||
```typescript
|
||
// 修改主题色（自动生成 10 个梯度色 CSS 变量）
|
||
import initThemeColor from '@/utils/initThemeColor';
|
||
|
||
initThemeColor('#026166', false); // (颜色值, 是否暗色模式)
|
||
```
|
||
|
||
## Mock 数据开发
|
||
|
||
- Mock 文件位置: `src/mock/`
|
||
- 使用 Mock.js 拦截 axios 请求
|
||
- 在 `src/main.tsx` 中导入: `import './mock'`
|
||
- 生产环境需移除 mock 导入
|
||
|
||
## 已知技术债务
|
||
|
||
1. **TypeScript 严格模式未开启**: `tsconfig.json` 中 `strict: false`，建议开启以提升类型安全
|
||
2. **依赖版本较旧**:
|
||
- React 17（建议升级到 18）
|
||
- axios 0.24.0（存在安全漏洞，建议立即升级）
|
||
- React Router 5（建议升级到 v6）
|
||
3. **缺少测试**: 项目无单元测试和集成测试
|
||
4. **Redux 传统模式**: 代码冗长，建议迁移到 Redux Toolkit
|
||
5. **安全防护不足**:
|
||
- localStorage 明文存储敏感信息
|
||
- 缺少 CSRF 防护
|
||
- 缺少输入验证和清洗
|
||
|
||
## 常见问题排查
|
||
|
||
### API 响应成功但业务逻辑未执行
|
||
|
||
**症状**:
|
||
|
||
- API 请求返回成功（控制台显示 `code: "0"` 或 `code: 0`）
|
||
- 但成功回调未执行，数据未更新
|
||
- 或登录成功但未跳转
|
||
|
||
**原因**:
|
||
使用了严格相等 `===` 判断响应码，导致字符串 `"0"` 和数字 `0` 类型不匹配
|
||
|
||
**排查步骤**:
|
||
|
||
1. 打开浏览器开发者工具的 Network 标签页
|
||
2. 查看 API 响应中的 `code` 字段类型（字符串还是数字）
|
||
3. 检查业务代码中是否使用了 `result.code === xxx`
|
||
4. 将所有 `===` 改为 `==`
|
||
|
||
**解决方案**:
|
||
|
||
```typescript
|
||
// ❌ 错误写法
|
||
if (result.code === SUCCESS_CODE) { ... }
|
||
if (result.code === 0) { ... }
|
||
|
||
// ✅ 正确写法
|
||
if (result.code == SUCCESS_CODE) { ... }
|
||
if (result.code == 0) { ... }
|
||
```
|
||
|
||
**预防措施**:
|
||
|
||
- 遵守 [API 开发规范](#api-开发规范) 中的响应码处理规范
|
||
- 代码审查时检查所有响应码判断逻辑
|
||
|
||
### 路由懒加载失败
|
||
|
||
检查页面组件路径是否符合约定：`src/pages/{route.key}/index.tsx`
|
||
|
||
### 权限控制不生效
|
||
|
||
1. 检查 Redux Store 中的 `userInfo.permissions` 是否正确
|
||
2. 检查路由配置中的 `requiredPermissions` 格式
|
||
3. 检查 `utils/authentication.ts` 的权限判断逻辑
|
||
|
||
### 主题色不生效
|
||
|
||
1. 检查 `src/settings.json` 中的 `themeColor` 配置
|
||
2. 确保在应用启动时调用了 `initThemeColor()`（位于 `src/main.tsx:64-70`）
|
||
3. 明暗模式切换时需重新调用 `initThemeColor()`
|
||
|
||
### Vite 构建失败
|
||
|
||
1. 检查 TypeScript 类型错误（虽然 noEmit: true，但仍需类型正确）
|
||
2. 检查 Less 语法错误
|
||
3. 检查路径别名配置是否正确
|
||
|
||
## 性能优化建议
|
||
|
||
- 大数据量表格使用虚拟滚动
|
||
- 图片较多时使用懒加载
|
||
- 搜索、滚动等高频操作添加防抖节流
|
||
- 使用 `rollup-plugin-visualizer` 分析打包产物
|
||
|
||
## 安全注意事项
|
||
|
||
- 敏感信息（Token、用户数据）应加密后再存储到 localStorage
|
||
- 所有用户输入需进行验证和清洗
|
||
- 生产环境强制使用 HTTPS
|
||
- 定期运行 `npm audit` 检查依赖漏洞
|
||
|
||
## 扩展开发指引
|
||
|
||
### 添加新页面
|
||
|
||
1. 创建页面组件: `src/pages/new-page/index.tsx`
|
||
2. 添加路由配置: `src/routes.ts`
|
||
3. 添加国际化: `src/locale/zh-CN.ts` 和 `en-US.ts`
|
||
4. 如需权限控制，配置 `requiredPermissions`
|
||
|
||
### 添加新组件
|
||
|
||
- 业务组件: `src/pages/{module}/components/`
|
||
- 公共组件: `src/components/`
|
||
- 组件应包含独立的样式文件（`.module.less`）
|
||
|
||
### 添加新的 Redux 状态
|
||
|
||
在 `src/store/index.ts` 中：
|
||
|
||
1. 扩展 `GlobalState` 接口
|
||
2. 更新 `initialState`
|
||
3. 在 `reducer` 中添加新的 case
|
||
|
||
## 参考文档
|
||
|
||
- [Arco Design 官方文档](https://arco.design/)
|
||
- [Vite 官方文档](https://vitejs.dev/)
|
||
- [React Router v5 文档](https://v5.reactrouter.com/)
|