# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

### 代码开发规范
- **引用检查**：编写代码时，必须检查所有using引用是否正确，确保引用的命名空间和类存在
- **编译验证**：完成一个功能时必须执行编译检查，发现错误立即修复，确保代码能够正常编译

### 深度思考与详细实现要求
- **深度思考原则**：对每个业务问题都要进行深度思考，分析所有可能的边界情况和业务场景
- **最终抉择要求**：在分析各种方案后，必须给出明确的最终决策和理由，不允许含糊其辞
- **详细实现标准**：所有功能都必须详细实现，不允许简化或省略关键逻辑
- **完整性验证**：实现功能时必须考虑所有相关的上下文和依赖关系
- **业务场景覆盖**：确保代码能够处理所有合理的业务场景，包括异常情况
- **错误处理完整性**：每个方法都必须包含适当的异常处理和错误信息
- **注释详细程度**：关键业务逻辑必须包含详细的业务思考过程注释

## 项目概述

NPP.SmartSchedue 是一个智能生产调度系统，基于 .NET 9.0 和中台Admin框架开发，实现生产任务的智能排班和调度管理。

## 架构设计

### 项目结构
- **NPP.SmartSchedue.Api.Contracts**: 契约层，包含实体、接口和DTO定义
- **NPP.SmartSchedue.Api**: 业务逻辑层，包含Repository和Service实现
- **NPP.SmartSchedue.Host**: 宿主程序，Web API启动入口
- **NPP.SmartSchedue.Tests**: 单元测试项目

### 核心领域模块
1. **Work**: 工作任务管理
   - WorkOrderEntity: 工作任务实体（支持多租户）
   - WorkOrderFLPersonnelEntity: 任务与FL人员关联
   - ProcessEntity: 工序管理
   - ProcessGroupEntity: 工序组管理

2. **Time**: 时间和班次管理
   - ShiftEntity: 班次定义
   - ShiftRuleEntity: 班次规则
   - CalendarEntity: 日历管理
   - EmployeeLeaveEntity: 员工请假

3. **Personnel**: 人员管理
   - PersonnelQualificationEntity: 人员资质
   - PersonnelWorkLimitEntity: 人员工作限制
   - QualificationEntity: 资质定义

4. **Schedule**: 排班调度
   - AutoScheduleInput: 自动排班输入
   - ScheduleValidationService: 排班验证服务
   - TaskIntegrationInput: 任务整合输入

### 技术栈
- **.NET 9.0**: 主要开发框架
- **FreeSql**: ORM框架，支持MySQL
- **ZhonTai.Admin**: 中台管理框架
- **DotNetCore.CAP**: 事件总线，支持RabbitMQ
- **xUnit**: 单元测试框架

## 常用命令

### 构建和运行
```bash
# 构建整个解决方案
dotnet build NPP.SmartSchedue.sln

# 运行Host项目
dotnet run --project NPP.SmartSchedue.Host

# 发布项目
dotnet publish NPP.SmartSchedue.Host -c Release
```

### 测试
```bash
# 运行所有测试
dotnet test NPP.SmartSchedue.Tests

# 运行特定测试文件
dotnet test NPP.SmartSchedue.Tests --filter ClassName=TestName

# 生成测试覆盖率报告
dotnet test NPP.SmartSchedue.Tests --collect:"XPlat Code Coverage"
```

### 数据库相关
```bash
# 项目使用FreeSql进行数据库操作，支持Code First
# 数据库连接配置在 ConfigCenter/dbconfig.json
# 初始化SQL脚本位于 ConfigCenter/createdbsql.txt
```

## 开发规范

### 实体设计
- 工作任务相关实体继承 `EntityTenant`（支持多租户）
- 基础配置实体继承 `EntityBase`
- 使用 FreeSql 特性进行数据库映射

### 服务层架构
- Repository层：数据访问，继承自 `AppRepositoryBase<T>`
- Service层：业务逻辑，实现对应的Interface
- 输入输出模型：使用Input/Output后缀命名

### 命名约定
- 实体类：Entity后缀
- 仓储接口：I前缀 + Repository后缀
- 服务接口：I前缀 + Service后缀
- 数据库表名：使用 DbConsts.TableNamePrefix 前缀

### 排班业务逻辑要点
- 任务状态使用 `WorkOrderStatusEnum` 枚举管理
- 支持任务优先级、紧急程度、复杂度等多维度排序
- FL人员与任务为多对多关系，通过 WorkOrderFLPersonnelEntity 关联
- 支持批量任务整合和验证功能
- 班次规则支持多种类型，通过 ShiftRuleTypeEnum 管理

### 多任务验证架构决策
- **单一验证原则**：所有冲突检查统一在 `ValidateWorkOrderWithBatchContextAsync` 中完成
- **批次上下文集成**：每个单任务验证都考虑批次内其他任务的影响
- **取消跨任务验证**：原有的 `CheckCrossTaskConflictsAsync` 已被移除，避免重复验证
- **全面冲突检查**：包含时间冲突、工作量限制、班次规则、时间段重叠等所有验证维度
- **性能优化**：减少重复查询，统一数据获取和验证逻辑

## 配置文件
- 应用配置：ConfigCenter/appconfig.json
- 数据库配置：ConfigCenter/dbconfig.json  
- JWT配置：ConfigCenter/jwtconfig.json
- 缓存配置：ConfigCenter/cacheconfig.json
- CAP事件总线：appsettings.json中的CAP节点