ERPTurbo_Admin/CLAUDE.md

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

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

# 安装依赖
pnpm install

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

# 构建所有应用
pnpm build

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

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

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

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 代码格式化
pnpm format

# 生成 OpenAPI 客户端代码
pnpm openapi

# 初始化/设置
pnpm setup

单一组件/页面开发

# 在 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
• 功能: 统一的增删改查容器组件
• 特点: 支持列表、详情、创建、更新、删除、导入导出、树形结构等

<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. 权限控制系统

页面级权限：

<PageContainer permission="operation-new-component">
  {/* 页面内容 */}
</PageContainer>

按钮级权限：

<ButtonAccess permission="operation-new-component-create">
  <Button>新增</Button>
</ButtonAccess>

4. 动态路由与菜单

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

开发指南

添加新页面

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

1. 创建页面组件

   // 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 自动生成

   cd packages/app-operation
   pnpm openapi
   

   • 从 swagger/ 目录读取 OpenAPI 规范
   • 自动生成 src/services/ 下的 API 客户端代码
   • 生成 TypeScript 类型定义

2. API 调用

   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 自动生成，修改后会被覆盖
   • 详细规则见 .claude/rules/services-generated.md

2. 不要加载或修改 swagger/*.json 文件

   • 详细规则见 .claude/rules/swagger-json.md

3. 遵循组件命名约定

   • 页面组件：文件名 + Page 后缀，导出为 Page
   • 业务组件：语义化命名，如 NewComponentList

4. 国际化是必需的

   • 所有用户可见文本必须使用 useIntl() 和 intl.formatMessage()
   • 定义 intlPrefix 前缀

5. 权限控制

   • 页面使用 PageContainer 包装
   • 操作按钮使用 ButtonAccess 包装
   • 权限标识格式：operation-{resource}-{action}

6. 响应式设计

   • 使用 isMobile 属性自动适配移动端
   • 表单宽度和布局会自动调整

7. 状态管理

   • 使用 UmiJS 内置状态管理（initialState、model）
   • 组件间通信使用 actionRef

故障排除

构建问题

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

API 更新后类型错误

• 重新生成 API 客户端：pnpm openapi
• 检查 swagger/ 目录下的规范文件

权限问题

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

国际化文本缺失

• 检查 locales/zh-CN.ts 中是否添加对应翻译
• 确认 intlPrefix 配置正确

相关文档

开发规则

• services 自动生成规则：.claude/rules/services-generated.md
• 不要查看或修改 swagger JSON：.claude/rules/swagger-json.md
• 项目架构设计：.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