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)

# 构建解决方案
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)

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）

代码约定

后端

命名规范：

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

服务注册：实现 IDependency 的服务会通过 Autofac 从所有项目程序集中自动注册。
控制器模式：大多数控制器继承自 ApiBaseController<TService, TEntity>，只需要构造函数。根据需要添加自定义操作。
响应格式：WebResponseContent 包装器，包含 Status（布尔值）和 Data 属性。

前端

扩展文件模式：对于每个后端实体，在 src/extension/{domain}/{entity}.js 创建扩展文件，包含：

表格列定义
表单字段配置
自定义 URL 模式
业务逻辑钩子

组件命名：Vue 组件使用 PascalCase，尽可能匹配后端实体名称。
API 调用：使用全局 this.http 对象进行 HTTP 请求。

添加新功能

后端

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

前端

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

数据库

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

实时功能

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

API 文档

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