b4ce6e45dc
- 将 ShipOrderList 组件从 Delivery 模块迁移至 Order 模块 - 移除 Delivery 模块的导出并在 Order 模块中新增 OrderShipList 和相关组件 - 更新发货单列表的列配置，添加订单、经销商、公司等关联字段 - 修改发货单列表的字段映射，将经销商名称和车次号格式从短横线改为竖线分隔 - 在 BizPage 组件中添加 convertValue 属性支持数据转换 - 更新左侧菜单组件的依赖数组以包含 menuData - 调整发货单列表的国际化配置，更新字段标题和状态枚举值 - 新增 OrderShip 页面路由文件 - 移除项目根目录的 AGENTS.md 和 project.md 文件 - 从组件索引中移除 Delivery 模块并添加 SearchMenu 组件
325 lines
8.7 KiB
Markdown
325 lines
8.7 KiB
Markdown
# 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
|