# CLAUDE.md

此文件为 Claude Code (claude.ai/code) 提供在此代码库中工作的指导。

## 项目概述

这是一个 WMS（仓库管理系统），后端采用 ASP.NET Core 6.0，前端采用 Vue 3。系统管理仓库运营，包括入库、出库、库存、任务和基础主数据。

```
WMS/
├── WIDESEA_WMSServer/           # 后端 (ASP.NET Core 6.0)
│   ├── WIDESEA_WMSServer/       # 主 API 项目
│   ├── WIDESEA_Core/            # 核心框架（基础控制器、服务、仓储）
│   ├── WIDESEA_Model/           # 按领域组织的数据模型
│   ├── WIDESEA_*Service/        # 服务实现（Basic、Inbound、Outbound、Stock 等）
│   ├── WIDESEA_I*Service/       # 服务接口
│   ├── WIDESEA_DTO/             # 数据传输对象
│   └── WIDESEA_Common/          # 公共工具类
└── WIDESEA_WMSClient/           # 前端 (Vue 3 + Vite)
    ├── src/api/                 # HTTP 客户端和 API 调用
    ├── src/components/basic/    # 可复用组件（ViewGrid、VolForm、VolTable）
    ├── src/extension/           # 与后端匹配的领域特定配置
    ├── src/views/               # Vue 页面组件
    ├── src/router/              # Vue Router 配置
    └── src/store/               # Vuex 状态管理
```

## 开发命令

### 后端 (ASP.NET Core)
```bash
# 构建解决方案
cd WIDESEA_WMSServer
dotnet build WIDESEA_WMSServer.sln

# 运行服务器（默认端口：9291）
cd WIDESEA_WMSServer/WIDESEA_WMSServer
dotnet run

# 还原包
dotnet restore

# 使用特定配置运行
dotnet run --configuration Release
```

### 前端 (Vue 3 + Vite)
```bash
cd WIDESEA_WMSClient

# 安装依赖（使用 yarn）
yarn install

# 开发服务器（端口 8080）
yarn dev

# 生产构建
yarn build

# 预览生产构建
yarn preview

# 运行单元测试
yarn test:unit

# 代码检查
yarn lint
```

## 架构

### 后端架构

**采用清洁架构原则的分层架构：**

- **控制器** (`WIDESEA_WMSServer/Controllers/`)：继承自 `ApiBaseController<TService, TEntity>`，自动提供 CRUD 端点。领域特定控制器按文件夹组织（Basic、Inbound、Outbound、Stock、System、TaskInfo 等）。

- **服务层** (`WIDESEA_*Service/`)：业务逻辑层。服务继承自 `ServiceBase<T, TEntity>` 并实现 `WIDESEA_I*Service/` 中的领域接口。通过 Autofac DI 注册。

- **仓储层** (`WIDESEA_Core/BaseRepository/`)：使用 SqlSugar ORM 的数据访问层。泛型 `IRepository<T>` 和 `RepositoryBase<T>` 提供通用 CRUD 操作。

- **模型** (`WIDESEA_Model/Models/`)：按领域组织（Basic、Check、Inbound、Outbound、Stock、System、TaskInfo、Record、Config、ApprovalFlow）。模型继承自 `BaseEntity` 或 `BaseWarehouseEntity`。

- **DTO** (`WIDESEA_DTO/`)：API 请求/响应的数据传输对象，按领域组织。

**关键基础设施组件：**
- `WIDESEA_Core/BaseController/ApiBaseController.cs`：具有自动 CRUD 路由的基础控制器
- `WIDESEA_Core/BaseServices/IService.cs`：基础服务接口
- `WIDESEA_Core/Extensions/AutofacModuleRegister.cs`：Autofac DI 注册
- `WIDESEA_Core/DB/`：SqlSugar 数据库配置
- `WIDESEA_Core/Authorization/`：JWT 身份验证
- `WIDESEA_Core/Filter/`：全局异常处理和操作过滤器

### 前端架构

**带有自定义组件框架的 Vue 3 组合式 API：**

- **ViewGrid 组件** (`src/components/basic/ViewGrid/`)：核心表格/网格组件，处理数据显示、分页、搜索和 CRUD 操作。通过扩展文件高度可配置。

- **扩展文件** (`src/extension/`)：配置每个实体的 ViewGrid 行为的 JavaScript 文件。它们定义表格列、表单字段、搜索条件和自定义操作。模式：`src/extension/{domain}/{entityName}.js` 匹配后端控制器。

- **API 层** (`src/api/`)：封装 Axios 的 HTTP 客户端，具有身份验证和错误处理拦截器。

- **路由器** (`src/router/index.js`)：带有哈希模式、身份验证守卫和从 `viewGird.js` 动态路由加载的 Vue Router。

**关键前端模式：**
- 扩展文件（如 `src/extension/basic/materielInfo.js`）定义表头、表单字段和自定义业务逻辑
- `src/views/` 中的视图很精简，大多使用由扩展配置的 ViewGrid 组件
- Vuex 存储管理身份验证状态和加载指示器

## 配置

### 后端配置

`WIDESEA_WMSServer/WIDESEA_WMSServer/appsettings.json` 中的关键设置：
- `urls`：服务器端口（默认：`http://*:9291`）
- `ConnectionString`：SQL Server 数据库连接
- `MainDB`：主数据库名称
- `Cors`：前端源头的 CORS 策略
- `WebSocketPort`：实时更新的 WebSocket 端口（默认：9296）
- `AutoOutboundTask`：自动出库操作的后台任务配置

### 前端配置

- `vite.config.js`：Vite 构建配置，`@` 别名指向 `src/`
- 服务器默认运行在端口 8080
- 基于哈希的路由（`createWebHashHistory`）

## 代码约定

### 后端

1. **命名规范**：
   - 控制器：`{Entity}Controller.cs`
   - 服务：`{Entity}Service.cs`（实现 `I{Entity}Service`）
   - 模型：`Dt_{EntityName}.cs`（数据库实体使用 `Dt_` 前缀）
   - API 路由：`api/{ControllerName}`

2. **服务注册**：实现 `IDependency` 的服务会通过 Autofac 从所有项目程序集中自动注册。

3. **控制器模式**：大多数控制器继承自 `ApiBaseController<TService, TEntity>`，只需要构造函数。根据需要添加自定义操作。

4. **响应格式**：`WebResponseContent` 包装器，包含 `Status`（布尔值）和 `Data` 属性。

### 前端

1. **扩展文件模式**：对于每个后端实体，在 `src/extension/{domain}/{entity}.js` 创建扩展文件，包含：
   - 表格列定义
   - 表单字段配置
   - 自定义 URL 模式
   - 业务逻辑钩子

2. **组件命名**：Vue 组件使用 PascalCase，尽可能匹配后端实体名称。

3. **API 调用**：使用全局 `this.http` 对象进行 HTTP 请求。

## 添加新功能

### 后端
1. 在 `WIDESEA_Model/Models/{Domain}/` 中创建模型
2. 在 `WIDESEA_I{Domain}Service/` 中创建服务接口
3. 在 `WIDESEA_{Domain}Service/` 中创建服务实现
4. 在 `WIDESEA_WMSServer/Controllers/{Domain}/` 中创建控制器，继承自 `ApiBaseController<TService, TEntity>`
5. 服务通过 `IDependency` 接口自动注册

### 前端
1. 在 `src/extension/{domain}/{entity}.js` 创建扩展文件
2. 如需自定义 UI，在 `src/views/{domain}/{entity}.vue` 创建可选视图组件
3. 如需要，添加路由配置
4. ViewGrid 组件配合扩展配置可自动处理大多数 CRUD 操作

## 数据库

- **ORM**：SqlSugar
- **数据库**：SQL Server
- **连接字符串**：在 `appsettings.json` 中配置
- **迁移**：通过 SqlSugar 的 Code First 方式处理

## 实时功能

- SignalR 用于服务器和客户端之间的实时更新
- WebSocket 服务器在单独端口（可在 `appsettings.json` 中配置）
- 前端 SignalR 客户端集成在 `src/main.js` 中

## API 文档

运行后端服务器时可用 Swagger UI（查看 `/swagger` 端点）。