# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

ERPTurbo_Admin 是一个基于 React 生态系统的企业级管理后台系统，采用 Monorepo 架构。使用 UmiJS Max 作为应用框架，Ant Design 作为 UI 组件库。

## 项目结构

```
ERPTurbo_Admin/
├── packages/
│   ├── app-operation/           # 运营管理系统主应用
│   │   ├── src/
│   │   │   ├── pages/          # 页面组件（约定式路由）
│   │   │   ├── components/     # 业务组件
│   │   │   │   ├── Biz/        # Biz 核心组件库
│   │   │   │   ├── BasicData/  # 基础数据组件
│   │   │   │   ├── Company/    # 公司组件
│   │   │   │   ├── Order/      # 订单组件
│   │   │   │   └── ...         # 其他业务组件
│   │   │   ├── services/       # API 服务层（自动生成）
│   │   │   ├── models/         # 状态管理
│   │   │   ├── locales/        # 国际化文件
│   │   │   └── app.tsx         # 应用入口
│   │   └── dist/              # 构建输出
│   └── app-sso-server/        # SSO 单点登录系统
├── shared/                    # 共享资源
├── swagger/                   # OpenAPI 文档
├── .husky/                   # Git Hooks 配置
├── .lingma/                  # 开发规则文档
│   └── rules/
│       ├── design.md         # 架构设计规则
│       ├── biz.md           # Biz 组件设计规则
│       └── add-new-page.md  # 添加页面指南
└── pnpm-workspace.yaml       # PNPM 工作区配置
```

## 核心命令

### 包管理器
- **PNPM** - 项目使用 PNPM 作为包管理器
- 工作区配置在 `pnpm-workspace.yaml`

### 根级别命令（在项目根目录执行）

```bash
# 安装依赖
pnpm install

# 启动所有应用的开发服务器
pnpm dev

# 构建所有应用
pnpm build

# 格式化所有应用的代码
pnpm format
```

### 应用级别命令（在具体应用目录下执行）

```bash
# 进入应用目录
cd packages/app-operation

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 代码格式化
pnpm format

# 生成 OpenAPI 客户端代码
pnpm openapi

# 初始化/设置
pnpm setup
```

### 单一组件/页面开发

```bash
# 在 app-operation 中开发特定功能
cd packages/app-operation

# 启动单个应用
pnpm dev

# 运行测试（如果需要）
pnpm test
```

## 架构设计

### 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| React | ^18.0.0 | 前端核心框架 |
| UmiJS Max | ^4.4.9 | 应用框架和构建工具 |
| Ant Design | ^5.25.2 | UI 组件库 |
| Ant Design Pro Components | ^2.8.6 | 高级业务组件 |
| TypeScript | ^5.6.3 | 类型检查 |
| TailwindCSS | ^3.4.17 | CSS 框架 |
| PNPM | ^9.0.0 | 包管理器 |

### 核心架构模式

#### 1. BizContainer 组件模式
所有业务页面基于 `BizContainer` 组件构建，这是项目的核心业务组件：

- **位置**: `packages/app-operation/src/components/Biz/BizContainer.tsx`
- **功能**: 统一的增删改查容器组件
- **特点**: 支持列表、详情、创建、更新、删除、导入导出、树形结构等

```tsx
<BizContainer<
  typeof business.newComponent,      // API 函数类型
  BusinessAPI.NewComponentVO,        // 视图对象类型
  BusinessAPI.NewComponentPageQry,   // 查询参数类型
  BusinessAPI.NewComponentCreateCmd, // 创建命令类型
  BusinessAPI.NewComponentUpdateCmd  // 更新命令类型
>
  rowKey={'id'}
  permission={'operation-new-component'}
  func={business.newComponent}
  method={'newComponent'}
  methodUpper={'NewComponent'}
  intlPrefix={'newComponent'}
  // ... 其他配置
/>
```

#### 2. Biz 组件族
围绕 BizContainer 的配套组件：

- **BizPage** - 分页表格组件
- **BizTree** - 树形结构组件
- **BizDrag** - 拖拽排序组件
- **BizCreate** - 创建操作组件
- **BizUpdate** - 更新操作组件
- **BizDetail** - 详情查看组件
- **BizDestroy** - 删除操作组件
- **BizImport** - 批量导入组件

#### 3. 权限控制系统

**页面级权限**：
```tsx
<PageContainer permission="operation-new-component">
  {/* 页面内容 */}
</PageContainer>
```

**按钮级权限**：
```tsx
<ButtonAccess permission="operation-new-component-create">
  <Button>新增</Button>
</ButtonAccess>
```

#### 4. 动态路由与菜单

- 使用约定式路由（pages 目录）
- 路由配置从服务端获取
- 支持嵌套路由和面包屑导航

## 开发指南

### 添加新页面

详细步骤请参考 `.lingma/rules/add-new-page.md`，基本流程：

1. **创建页面组件**
   ```tsx
   // packages/app-operation/src/pages/NewPage.tsx
   import { NewComponentList } from '@/components';

   export default function Page() {
     return <NewComponentList />;
   }
   ```

2. **创建业务组件**（如果需要）
   - 使用 `BizContainer` 构建标准 CRUD 页面
   - 定义 `columns`（表格列）和 `formContext`（表单字段）
   - 配置国际化前缀 `intlPrefix`

3. **配置国际化**
   - 在 `packages/app-operation/src/locales/zh-CN.ts` 中添加翻译

### API 集成

1. **OpenAPI 自动生成**
   ```bash
   cd packages/app-operation
   pnpm openapi
   ```
   - 从 `swagger/` 目录读取 OpenAPI 规范
   - 自动生成 `src/services/` 下的 API 客户端代码
   - 生成 TypeScript 类型定义

2. **API 调用**
   ```tsx
   import { business } from '@/services';

   // 调用 API
   const result = await business.newComponent.page({});
   ```

### 代码规范

- **格式化**: 使用 Prettier，配置在各个包的 package.json 中
- **代码检查**: Husky + lint-staged，在提交前自动检查
- **类型检查**: TypeScript 严格模式
- **国际化**: 所有 UI 文本必须支持多语言

## 关键配置文件

### package.json (根目录)
- 定义了工作区结构
- 包含全局脚本：`dev`、`build`、`format`

### pnpm-workspace.yaml
- 定义 PNPM 工作区配置
- 包含 packages/* 和 shared/** 目录

### .husky/
- Git Hooks 配置
- pre-commit: 运行 lint-staged 检查
- commit-msg: 提交消息规范检查

### swagger/
- OpenAPI 规范文件
- 用于生成 API 客户端代码

## 重要目录说明

### packages/app-operation/src/components/

#### Biz/ 目录
核心业务组件库，包含：
- `BizContainer.tsx` - 核心容器组件
- `BizPage.tsx` - 列表页面组件
- `BizCreate.tsx` / `BizUpdate.tsx` / `BizDetail.tsx` / `BizDestroy.tsx` - CRUD 操作组件
- `BizTree.tsx` - 树形组件
- `BizDrag.tsx` - 拖拽组件
- `ButtonAccess.tsx` - 权限按钮组件

#### 业务组件目录
- `BasicData/` - 基础数据管理
- `Company/` - 公司管理
- `Order/` - 订单管理
- `Material/` - 素材库
- `Employee/` - 员工管理
- `Supplier/` - 供应商管理

### packages/app-operation/src/services/
- API 服务层
- 自动生成，不应手动编辑
- 通过 `pnpm openapi` 命令更新

### packages/app-operation/src/locales/
- 国际化文件
- `zh-CN.ts` - 中文翻译
- `en-US.ts` - 英文翻译

## 开发注意事项

1. **不要直接修改 services/ 目录**
   - 这些文件由 OpenAPI 自动生成
   - 修改 swagger/ 规范后重新生成

2. **遵循组件命名约定**
   - 页面组件：文件名 + `Page` 后缀，导出为 `Page`
   - 业务组件：语义化命名，如 `NewComponentList`

3. **国际化是必需的**
   - 所有用户可见文本必须使用 `useIntl()` 和 `intl.formatMessage()`
   - 定义 `intlPrefix` 前缀

4. **权限控制**
   - 页面使用 `PageContainer` 包装
   - 操作按钮使用 `ButtonAccess` 包装
   - 权限标识格式：`operation-{resource}-{action}`

5. **响应式设计**
   - 使用 `isMobile` 属性自动适配移动端
   - 表单宽度和布局会自动调整

6. **状态管理**
   - 使用 UmiJS 内置状态管理（initialState、model）
   - 组件间通信使用 `actionRef`

## 故障排除

### 构建问题
- 确保运行 `pnpm install` 安装依赖
- 清理构建缓存：`rm -rf packages/app-operation/.umi`

### API 更新后类型错误
- 重新生成 API 客户端：`pnpm openapi`
- 检查 swagger/ 目录下的规范文件

### 权限问题
- 检查 `access.ts` 文件中的权限配置
- 确认路由权限标识与服务端一致

### 国际化文本缺失
- 检查 `locales/zh-CN.ts` 中是否添加对应翻译
- 确认 `intlPrefix` 配置正确

## 相关文档

- 项目架构设计：`.lingma/rules/design.md`
- Biz 组件设计规则：`.lingma/rules/biz.md`
- 添加新页面指南：`.lingma/rules/add-new-page.md`
- UmiJS Max 文档：https://umijs.org/docs/max/introduce
- Ant Design 文档：https://ant.design
- PNPM 文档：https://pnpm.io