shenyifei b4ce6e45dc refactor(order): 重构发货单功能模块

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

2026-01-08 16:15:03 +08:00

8.7 KiB

Raw Blame History

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，基本流程：

创建页面组件

// packages/app-operation/src/pages/NewPage.tsx
import { NewComponentList } from '@/components';

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

创建业务组件（如果需要）
- 使用 BizContainer 构建标准 CRUD 页面
- 定义 columns（表格列）和 formContext（表单字段）
- 配置国际化前缀 intlPrefix
配置国际化
- 在 packages/app-operation/src/locales/zh-CN.ts 中添加翻译

API 集成

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

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 - 英文翻译

开发注意事项

不要直接修改 services/ 目录
- 这些文件由 OpenAPI 自动生成
- 修改 swagger/ 规范后重新生成
遵循组件命名约定
- 页面组件：文件名 + Page 后缀，导出为 Page
- 业务组件：语义化命名，如 NewComponentList
国际化是必需的
- 所有用户可见文本必须使用 useIntl() 和 intl.formatMessage()
- 定义 intlPrefix 前缀
权限控制
- 页面使用 PageContainer 包装
- 操作按钮使用 ButtonAccess 包装
- 权限标识格式：operation-{resource}-{action}
响应式设计
- 使用 isMobile 属性自动适配移动端
- 表单宽度和布局会自动调整
状态管理
- 使用 UmiJS 内置状态管理（initialState、model）
- 组件间通信使用 actionRef

故障排除

构建问题

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

API 更新后类型错误

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

权限问题

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

国际化文本缺失

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

8.7 KiB Raw Blame History Unescape Escape