【易飞】易飞ERP全能WebAPI更新日志

系统更新日志（Change Log）

[5.7.2] – 2026-07-26

更新概览

今日完成 6大模块 优化与修复，涉及 40+ 文件。

架构优化

1. 请求链路追踪（Serilog+TraceId）

• 新增 RequestTraceMiddleware.cs，自动注入TraceId到所有日志
• 记录请求耗时、状态码，支持全链路追踪

2. 缓存配置统一到appsettings.json

• 建立6个缓存档位（Long/MediumLong/Medium/MediumShort/Short/Business）
• 30+控制器硬编码过期时间改为配置文件管理

3. 测试项目编译修复

• 添加缺失项目引用，修复命名空间错误
• 测试项目编译成功

Bug修复

4. 采购/销售订单金额汇总计算错误

• 修复7个控制器共15处累加逻辑错误（= → +=）
• 涉及：Puri07/09/11、Copi05/08/09/13
• 确保财务数据准确汇总

代码质量

5. 消除可空引用类型警告

• 修复5个文件共7处CS86xx警告
• 提升代码类型安全性

验证结果

[5.7.1] – 2026-07-25

发布日期：2026-07-25

更新类型：代码质量优化、可维护性提升、系统健壮性增强

更新概览

本次更新共涉及 8个优化项，修改 15个文件，消除约 200处硬编码，提升了代码的可维护性和系统的健壮性。

新增功能

1. 完整健康检查体系

• 新增 Redis 健康检查：验证 Redis 分布式缓存连接和读写能力
• 新增许可证健康检查：验证许可证配置完整性
• 新增内存缓存健康检查：验证内存缓存服务状态
• 新增分组健康检查端点：
  • /health/database – 仅检查数据库连接
  • /health/cache – 仅检查缓存服务

文件：

• YiFeiWebApi.Service/RedisHealthCheck.cs
• YiFeiWebApi.Service/LicenseHealthCheck.cs
• YiFeiWebApi.Service/CacheHealthCheck.cs

2. 配置常量类

• 新增 ConfigConstants：统一管理配置键名常量，解决跨项目引用问题

文件：

• YiFeiWebApi.Common/Config/ConfigConstants.cs

代码优化

3. 错误消息常量化

优化内容：

收益：统一错误消息管理，修改只需改一处

文件：

• YiFeiWebApi/Models/AppConstants.cs
• 66个控制器文件

4. 数字错误码常量化

优化内容：

• 将硬编码 -1 替换为 AppConstants.ErrorCodeFailure
• 将硬编码 -2 替换为 AppConstants.ErrorCodeInvalidParameter

涉及文件：

• YiFeiWebApi/Controllers/Cmsi06Controller.cs
• YiFeiWebApi/Controllers/Cmsi19Controller.cs
• YiFeiWebApi/Controllers/Cmsi21Controller.cs

5. 配置键名硬编码优化

优化内容：将硬编码 _SqlConnection 替换为 ConfigConstants.ConfigKeyConnectionSuffix

涉及文件：

• YiFeiWebApi.Service/CacheWarmUpService.cs
• YiFeiWebApi.Service/ErpConnectService.cs
• YiFeiWebApi.Service/ErpHealthCheck.cs

6. 异步操作优化

优化内容：将 BaseDataCacheService.CleanupExpiredLock 方法中的同步 Wait(0) 改为异步 WaitAsync(0)

文件：

• YiFeiWebApi.Service/BaseDataCacheService.cs

7. 通用CRUD模板方法

优化内容：在 BaseController 中新增 CreateDocumentAsync<THead, TDetail> 通用方法，封装以下通用逻辑：

文件：

• YiFeiWebApi/Controllers/BaseController.cs

8. Puri05Controller 使用通用方法

优化内容：将 CreatePurchaseRequisitions 方法重构为使用通用方法，原有代码保留注释

文件：

• YiFeiWebApi/Controllers/Puri05Controller.cs

Bug修复

9. 内存缓存健康检查修复

问题：内存缓存健康检查因未指定 Size 属性导致异常（"Cache entry must specify a value for Size when SizeLimit is set."）

修复：在设置缓存项时指定 Size = 1

文件：

• YiFeiWebApi.Service/CacheHealthCheck.cs

优化收益

接口变更

新增端点

响应格式

健康检查响应格式统一为 JSON：

{
"status": "Healthy",
"checks": [
{ "name": "erp_database", "status": "Healthy", "description": "…", "exception": null }
],
"totalDuration": 156.32
}

注意事项

[5.7.0] – 2026-07-23

一、功能优化

模型验证错误消息增强

• 问题描述：当接口接收包含列表数据的请求时，模型验证失败后返回的错误信息无法区分是主档还是明细数据的错误，也无法定位具体行号
• 修改文件：
  • YiFeiWebApi/Program.cs（第50-88行）- ConfigureApiBehaviorOptions 配置
  • YiFeiWebApi/Filters/ValidationFilter.cs（第17-59行）- 全局验证过滤器
• 优化内容：
• 从 ModelState 的键中提取列表索引信息
• 根据索引数量区分错误来源：
  • 单个索引 → 标记为"主档第N行"
  • 多个索引 → 标记为"明细第N行"
• 使用最后一个索引作为明细行号，第一个索引作为主档行号
• 效果示例：
  • 修改前："单据日期不能为空；单据日期不能为空；单据日期不能为空"
  • 修改后："主档第1行：单据日期不能为空；明细第1行：单据日期不能为空；明细第3行：单据日期不能为空"
• 影响范围：所有使用 ASP.NET Core 模型验证的控制器接口，全局生效

技术细节

• 使用正则表达式 $$(\\d+)$$ 匹配键中的索引格式
• 将 0-based 索引转换为 1-based 行号，符合用户习惯
• 支持嵌套结构（主档列表 + 明细列表）的正确识别
• 保持与原有错误响应格式一致，不影响前端解析

二、重大优化 DTO基类统一改造

目的 ：降低DTO类的维护成本，消除冗余代码

修改内容 ：

• 将所有100+个DTO类统一改为继承 EntityBase 基类
• 从每个DTO中移除了7个公共字段（company、creator、usr_group、create_date、modifier、modi_date、flag）
• 从每个DTO中移除了24个UDF字段（udf01-udf12、udf51-udf62）
  涉及文件 ：
• EntityBase.cs – 基类定义
• 所有 ErpDtos 目录下的DTO文件（100+个）

[5.6.8] 2026-07-22

一、代码优化

1. QueryService.cs – 冗余方法清理

• 删除了已被 ProcessQueryWithDbPagingAsync 替代的过时方法
• 移除：ApplyDynamicSorting、ApplyPagination 等方法
• 代码量减少约 45.6%，降低了维护复杂度

2. ValidationService.cs – 命名优化

• 重命名模糊变量以提高代码可读性
• qty2 → warehouseStockQty（仓库库存数量）
• qty3 → batchStockQty（批次库存数量）

3. Program.cs – 内存缓存配置优化

• 更新 MemoryCache SizeLimit 为 100_000（10万条）
• 支持通过 appsettings.json 配置缓存大小限制
• 确保缓存项正确设置 SetSize() 属性

4. RateLimitFilter.cs – 缓存大小修复

• 为限流缓存项添加 SetSize(1) 设置
• 修复因未设置Size导致的潜在异常

二、代码文档完善

1. Service接口层注释补充

为以下接口文件添加了完整的XML文档注释：

• [ISysDocStateService.cs]
• [IDocNoGeneratorService.cs]
• [ICompanyMappingService.cs]
• [ISysInvalidService.cs]
• [IErpConnectService.cs]

2. Middleware中间件注释补充

为以下中间件文件添加了完整的XML文档注释：

• [ExceptionHandlingMiddleware.cs]
• [CompanyInfoMiddleware.cs]

3. Common类库注释补充

为以下公共类库文件添加了完整的XML文档注释：

• [DbContextTransactionExtensions.cs]
• [SysDocType.cs]
• [DocumentNoGenerator.cs]
• [ProgramTableConfig.cs]
• [SysDocTypeConfig.cs]
• [EFRawSqlUpdateGenerator.cs]
• [EnrichmentConfigs.cs]
• [SysDocDate.cs]

[5.6.7] – 2026-07-22

🛡️ 安全性优化

1. 修复授权响应状态码

• 文件: YiFeiWebApi/Filters/AuthorizeFilter.cs
• 变更: 授权失败时返回 HTTP 401 Unauthorized 而非 HTTP 200 OK
• 影响: 前端可正确识别未授权状态，符合RESTful规范

2. 修复权限校验状态码

• 文件: YiFeiWebApi/Filters/LicenseAuthorizationFilter.cs
• 变更: 权限不足时返回 HTTP 403 Forbidden 而非 HTTP 200 OK
• 影响: 区分未授权(401)和权限不足(403)两种场景

3. 新增授权响应工具类

• 文件: YiFeiWebApi/Filters/AuthorizationHelper.cs（新增）
• 变更: 统一的授权响应生成逻辑，避免代码重复
• 功能:
  • SetUnauthorizedResult(): 返回401未授权响应
  • SetForbiddenResult(): 返回403禁止访问响应

4. 新增错误码常量

• 文件: YiFeiWebApi/Models/AppConstants.cs
• 变更: 添加 ErrorCodeUnauthorized(-4) 和 ErrorCodeForbidden(-5)
• 影响: 统一管理错误码，避免硬编码

🔧 代码质量优化

5. 合并 AddControllers() 调用

• 文件: YiFeiWebApi/Program.cs
• 变更: 将3次分散的调用合并为1次集中配置
• 优化内容:
  • SuppressImplicitRequiredAttributeForNonNullableReferenceTypes
  • 全局过滤器注册
  • ConfigureApiBehaviorOptions
  • AddNewtonsoftJson
• 收益: 消除配置覆盖风险，代码结构更清晰

6. 移除无效异常过滤器

• 文件: YiFeiWebApi/Program.cs
• 变更: 移除 GlobalExceptionFilter 注册
• 原因: 该过滤器从未执行（异常已被 ExceptionHandlingMiddleware 捕获）
• 收益: 减少约70行无效代码

7. 增强异常处理中间件

• 文件: YiFeiWebApi/Middleware/ExceptionHandlingMiddleware.cs
• 变更: 添加追踪ID和控制器信息
• 功能:
  • 每次异常生成8位追踪ID
  • 获取 Controller/Action 名称
  • 在日志和响应中包含追踪信息
• 收益: 便于问题排查，提升可观测性

8. 删除过时代码

• 文件: YiFeiWebApi/SysMis.cs（已删除）
• 变更: 移除标记为 [Obsolete] 的未使用文件
• 原因: 代码无任何引用，仅用于测试兼容
• 收益: 减少编译警告，清理无用代码

✅ 验证结果

⚠️ 注意事项

前端兼容性

• HTTP状态码变更: 授权失败从200变为401，权限不足从200变为403
• 建议: 前端需增加401/403状态码处理逻辑

日志变化

• 新增追踪ID: 异常日志和响应中包含8位短ID
• 格式: [a1b2c3d4] Controller:Puri01 Action:Query

📈 优化收益

[5.6.7] – 2026-07-21

🔴 P0 级别修复（重大更新）

1. 查询接口数据库分页优化（97个控制器）

问题描述：原查询接口先将全量数据加载到内存，再进行排序和分页，大数据量时导致内存溢出、数据库索引失效。

解决方案：新增 ProcessQueryWithDbPagingAsync 方法，将排序（OrderBy）和分页（Skip/Take）下推到数据库执行，仅加载一页数据到内存。

涉及文件：

控制器迁移统计：

性能提升：

ValidationService 代码冗余优化方案

• 新增泛型核心方法 ： BatchValidateCoreAsync + BuildContainsExpression （私有）
• 改造基础校验方法 ：Customers、Suppliers、Warehouses、Departments、Currencies、WorkCenters
• 改造带条件校验方法 ：Items、PaymentTerms
• 编译验证 ：确保无编译错误
• 单元测试 ：验证每个方法的返回值与原逻辑一致
• 删除旧代码 ：确认无误后删除旧的方法实现

[5.6.6] 2026-07-20 – 同步阻塞问题修复

✨ 性能优化

修复 BaseController 线程池饥饿问题

• 问题描述：BaseController.GetCompanyId() 方法中使用 .GetAwaiter().GetResult() 同步阻塞调用异步方法 GetCompanyDbNameAsync()，在缓存未命中时会导致线程池线程被阻塞，高并发下引发线程池饥饿
• 影响范围：50+个控制器、200+处调用，是所有API请求的必经之路
• 解决方案：采用中间件预加载模式，在请求管道中异步获取公司映射信息并存入 HttpContext.Items，控制器直接读取，无需阻塞等待

📁 新增文件

• YiFeiWebApi/Middleware/CompanyInfoMiddleware.cs – 公司信息中间件，负责在请求管道中异步获取公司映射信息

📝 修改文件

🔄 技术方案

请求处理流程优化：

优化前：
请求 → Authorization → LicenseMiddleware → Controller.GetCompanyId() → .GetAwaiter().GetResult() [阻塞线程]

优化后：
请求 → Authorization → LicenseMiddleware → CompanyInfoMiddleware [异步预加载] → IPWhitelist → Controller.GetCompanyId() [直接读取]

⚡ 性能提升

[5.6.5] – 2026-07-20

✨ 新功能

• 新增 DbContextTransactionExtensions 扩展方法，提供统一的事务处理能力
  • 文件：YiFeiWebApi.Common/Extensions/DbContextTransactionExtensions.cs
  • 提供 ExecuteWithTransactionAsync 两个重载：
    • ExecuteWithTransactionAsync(Func<Task>) – 无返回值事务操作
    • ExecuteWithTransactionAsync<TResult>(Func<Task<TResult>>) – 有返回值事务操作

🚀 性能优化

• 全面优化控制器事务处理机制：将所有控制器的手动事务管理替换为统一的扩展方法
  • 涉及模块：采购(Puri)、销售(Copi)、库存(Invi)、生产(Moci)、BOM(Bomi)、财务(Acpi/Acri)、生管(Sfci)、品管(Qmsi)
  • 修改文件数：69个控制器
  • 事务修复数：187处
  • 核心改进：
    • 自动集成 EF Core 执行策略（EnableRetryOnFailure）
    • 数据库瞬时故障自动重试（最多3次，指数退避）
    • 异常时自动回滚事务
    • 简化事务管理代码，减少样板代码

🔧 技术改进

🛡️ 安全性

• 提升了事务操作的可靠性和数据一致性保障
• 增强了对数据库瞬时故障的容错能力

[5.6.3] – 2026-07-19

性能优化

资源管理

配置优化

DataEnrichmentService 反射性能问题优化

[5.6.1] – 2026-07-17

优化

文件统一管理所有 NuGet 包版本

• 引入 Central Package Management (CPM)，通过在解决方案根目录创建 [Directory.Packages.props]文件统一管理所有 NuGet 包版本
• 启用 <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> 配置
• 启用 <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled> 配置，确保传递依赖版本一致性
• 将所有 NuGet 包版本按功能分类管理：
  • Microsoft ASP.NET Core：10.0.5
  • Entity Framework Core：10.0.5
  • Data Access：Microsoft.Data.SqlClient 7.0.0, System.Data.SqlClient 4.9.0, System.Data.SQLite 2.0.3
  • System：System.Management 10.0.5, System.Linq.Dynamic.Core 1.7.2
  • Third-party：AutoMapper 16.1.1, Newtonsoft.Json 13.0.4, AspNetCoreRateLimit 5.0.0, Swashbuckle.AspNetCore 7.3.2
  • Serilog：Serilog.AspNetCore 10.0.0, Serilog.Sinks.Async 2.1.0, Serilog.Sinks.File 7.0.0
  • Test：coverlet.collector 6.0.4, Microsoft.NET.Test.Sdk 17.14.1, Moq 4.20.70, xunit 2.9.3, xunit.runner.visualstudio 3.1.4
  • Build Tools：Obfuscar 2.2.41

AutoMapper 公共字段映射抽取

• 创建 [MappingExtensions.cs](file:///d:/DavidWorkProj/YiFeiWebApi/YiFeiWebApi/YiFeiWebApi/AutoMapper/MappingExtensions.cs) 扩展方法类，统一管理公共字段映射配置
• 通过 .MapCommonFields() 扩展方法自动映射以下字段：
  • 公共字段（7个）：company, creator, usr_group, create_date, modifier, modi_date, flag
  • UDF字段（24个）：udf01~udf12, udf51~udf62
• 批量重构 171个 Profile 文件，移除冗余的字段映射代码
• 优化收益：
  • 单文件代码行数减少约 37.5%（从 ~80行 降至 ~50行）
  • 总代码行数减少约 5,130行
  • 公共配置重复度从 171处 降至 1处，维护效率提升 171倍
• 采用反射机制动态检查属性是否存在，确保兼容性和安全性

[5.5.9] – 2026-07-16

优化

完善一些Swagger XML注释

• 所有DTO注释可以显示到Swagger

[5.5.9] – 2026-07-15

优化

1. 代码质量改进

• 统一 _mapper 字段命名：修复 27+ 个控制器中 _mapper 与 mapper 混用问题，统一使用 _mapper 私有字段命名规范
• 删除冗余 AsNoTracking()：移除 ExecuteDeleteAsync() 调用前的 AsNoTracking()，ExecuteDeleteAsync() 本身不需要追踪状态
• 简化事务代码：移除单操作事务的冗余包裹，仅在多操作场景保留事务

2. 静态 Validator 服务化改造

• 将 11 个静态 Validator 类重构为 IValidationService 依赖注入服务：
  • CmsmbValidator、CmsmcValidator、CmsmdValidator、CmsmeValidator、CmsmfValidator、CmsmiValidator
  • CmsmjValidator、CmsmkValidator、CmsmlValidator、CopmaValidator、PurmaValidator
• 移除 DbContextProvider 静态单例反模式，改为 IErpDbContextFactory 工厂模式
• 修复全表加载性能问题：使用 WHERE IN 查询替代内存过滤，显著减少数据库往返和内存占用

3. 安全与性能优化

• LicenseAuthorizationFilter 日志降级：将 5 处 Information 级日志降为 Debug 级，减少生产环境日志量
• MachineInfo 静态缓存：实现 GetMachineKey() 静态缓存模式，避免每次请求重复执行 WMI 查询（CPU/磁盘序列号采集）
• 敏感信息脱敏：从授权错误消息中移除 QQ 号、CPU/磁盘序列号等敏感数据

4. 序列化器统一

• 统一使用 Newtonsoft.Json：在 LicenseMiddleware 和 ExceptionHandlingMiddleware 中替换 System.Text.Json 为 Newtonsoft.Json
• 在 AppConstants.Json.Default 中配置统一的序列化设置：
  • CamelCasePropertyNamesContractResolver（驼峰命名）
  • DateFormatString = "yyyy-MM-dd HH:mm:ss"（统一日期格式）
  • NullValueHandling = NullValueHandling.Ignore（忽略空值）

5. LicenseMiddleware 状态码一致性修复

• 修复 HTTP 状态码与响应体 code 字段不一致问题：
  • 授权失败：状态码 401，响应体 code 401（原响应体 code 403）
  • 服务器配置缺失：状态码 500，响应体 code 500（原状态码 401）

6. 缓存配置外部化

• 将 BaseDataCacheService 中硬编码的缓存过期时间迁移至 appsettings.json
• 新增 CacheSettings 配置节点，支持按数据类型配置不同过期策略：
  • EmptyDataExpiration：空数据缓存过期时间（默认 5 分钟）
  • DataTypes：各数据类型的 AbsoluteExpiration 和 SlidingExpiration
• 通过 IOptions<CacheSettings> 注入配置，实现热更新支持

7. 服务层项目结构整合

• 将 YiFeiWebApi/Service/ 目录下的 4 个基础设施服务迁移至独立项目 YiFeiWebApi.Service/：
  • BaseDataCacheService.cs – 基础数据缓存服务
  • BitmapLicenseService.cs – 位图授权服务
  • CacheWarmUpService.cs – 缓存预热后台服务
  • GlobalVariablesService.cs – 全局变量服务
• 将 CacheSettings.cs 迁移至 YiFeiWebApi.Interface 项目，实现跨项目共享
• 更新 YiFeiWebApi.Service.csproj 添加缺失的 NuGet 包引用：
  • Microsoft.Extensions.Caching.Memory
  • Microsoft.Extensions.Hosting.Abstractions
  • Microsoft.Extensions.Logging.Abstractions
  • Microsoft.Extensions.Options
  • Microsoft.EntityFrameworkCore
  • Microsoft.Extensions.DependencyInjection.Abstractions
  • Microsoft.Extensions.Configuration.Binder
• 删除主项目目录下重复的废弃 csproj 文件（YiFeiWebApi.Service.csproj、YiFeiWebApi.Utility.csproj）

改进效果

风险评估

• 无破坏性变更：所有接口契约保持不变
• 兼容性：命名空间保持一致，无需修改外部调用代码
• 可回滚：每个优化项独立，可单独回滚

版本 [5.5.4] – 2026-07-14

优化

• 提取单号生成为独立服务 解耦控制器依赖
• 单据号生成服务并发安全优化
• -系统中常量分散在多个独立文件的问题，采用 嵌套静态类模式 将所有常量集中管理到 AppConstants.cs ，同时将混合常量与数据库方法的 SysMis 拆分为纯常量和服务接口，提升代码可维护性和依赖注入合规性。
• 原单据号生成逻辑存在 竞态条件（Race Condition） ：多个并发请求同时调用 GetMaxSerialNumber() 获取最大流水号时，可能返回相同值，导致生成重复单据号。

解决方案

引入 Serializable 事务 + 死锁重试机制 ，基于原生 SqlConnection 实现细粒度的并发控制。

技术实现

并发控制机制：

使用 Serializable 事务隔离级别，确保并发事务之间完全隔离：
1. 开启 Serializable 事务
2. 在事务内执行 MAX 查询获取当前最大流水号
3. 生成新单据号（MAX + 1）
4. 提交事务

死锁重试策略：

• 捕获 SqlException （Number = 1205，死锁错误码）
• 自动重试最多 3 次
• 指数退避：100ms → 200ms → 300ms

版本 [5.5.3] – 2026-07-13

优化

• 分页配置
• 中间件顺序错误 Program.cs 重新排列中间件顺序
• Redis 连接配置优化 appsettings.json 添加连接超时、同步超时、保持连接等参数
• HttpContext.Items 类型安全 HttpContextExtensions.cs 创建类型安全的扩展方法

版本 [5.5.2] – 2026-07-13

独立项目职责重复

• 主项目 YiFeiWebApi 内部存在与独立项目职责重复的目录：

解决方案

采用 依赖倒置 原则，通过 YiFeiWebApi.Common 作为中介层打破循环：

YiFeiWebApi (Controllers)
│
├──→ YiFeiWebApi.Interface (接口定义)
│
├──→ YiFeiWebApi.Service (服务实现)
│ │
│ └──→ YiFeiWebApi.Common (通用配置/工具)
│ │
│ └──→ YiFeiWebApi.Entity (实体模型)
│
└──→ YiFeiWebApi.Common

整合后的优势

版本 [5.4.7] – 2026-07-10

Attributes

• 创建自定义验证特性类：可复用，提高可维护性。
  • AccountingSourceCodeAttribute(来源码)
  • ApprovalStatusCodeAttribute(签核状态码)
  • ApprovalValidStatusAttribute(核准状况1)
  • ApprovalValidStatusCodeAttribute(核准状况2)
  • ApproveStatusCodeAttribute(审核码)
  • IsEndStatusAttribute(结束码)
  • ItemTypeCodeAttribute(品号类型)
  • PayableObjectCodeAttribute(应付对象)
  • SubItemRelationCodeAttribute(自件关系)
  • TaxTypeCodeAttribute(税种代码)
  • VerificationStatusCodeAttribute(核销状态)

版本 [5.4.6] – 2026-06-26

AutoMapper 映射修复

• 新增 Moctm → Wo_split_data 映射，解决缺失的 AutoMapper 配置
• 创建 CheckAutoMapperMappings.ps1 静态分析脚本，用于扫描映射完整性

安全修复

• 修复 RateLimitFilter 返回中文纯文本 "您访问太频繁了"，改为 JSON 格式 StdResult + 英文描述
• 修复 LicenseMiddleware 中 "Invalid customer ID" 返回纯文本，改为统一 JSON 格式
• 修复 DscsysDbContext 中 Debug.WriteLine(connectionString) 打印含密码连接字符串的调试代码

异步阻塞修复

• 修复 MachineInfo.cs 中 CPU/磁盘信息采集的 .Result 同步阻塞，新增 Initialize() 方法在启动时预采集
• 在 Program.cs 启动流程中集成 MachineInfo.Initialize() 调用
• 修复 Copi07Controller 中 cacheTasks[0].Result 同步阻塞，改为直接 await 异步调用

调试代码清理

• 移除 DscsysDbContext 中 Console.WriteLine EF Core SQL 日志输出
• 移除 RMBConverter 中残留的测试 Main 方法（含 Console.WriteLine）
• 移除 SysDocDate.cs 中空 try-catch 块（含被注释的 Console.WriteLine）
• 移除 BitmapLicenseService 中 2 处 Console.WriteLine 调试注释
• 移除 SysInvalidService 中 7 行 Console.WriteLine 调试注释
• 移除 SysDocStateService 中 2 处 Console.WriteLine 调试注释

注释代码清理（7 个文件，共 35 行）

• 清理 DscsysDbContext 中旧版连接字符串获取方式注释（7 行）
• 清理 LicenseMiddleware 中 3 处旧版纯文本返回注释（9 行）
• 清理 BaseController 中被注释的 HandleException 方法（32 行）
• 清理 BaseController 中被注释的审批状态旧值（2 行）
• 清理 CmsmoProfile 中被注释的旧版 AutoMapper 映射（13 行）

代码规范

• 提取 6 个 Controller 中 18 处硬编码单别前缀为常量，统一管理在 AppConstants 中：
  • Invi05Controller — 库存交易单 "11"（3 处）
  • Invi08Controller — 调拨单 "12"（3 处）
  • Qmsi07Controller — 进货检验单 "34"（3 处）
  • Qmsi14Controller — 到货检验单 "37"（3 处）
  • Qmsi08Controller — 委外进货检验单 "59"（3 处）
  • Qmsi15Controller — 委外到货单 "5D"（3 处）

版本 [5.4.5] – 2026-06-26

🚀 优化

主项目Common目录独立到项目.Common类库

• 项目结构优化：项目解耦，结构清晰。

提高测试覆盖率

• 单元测试：主要核心业务测试覆盖率达到80%

抽取QueryService

• 查询接口优化：抽取查询接口服务,所有查询接口代码量预计减少38%，可维护性提高

修复BUG

• 到货单接口异常修复：DTO未映射。

版本 [5.4.3] – 2026-06-24

🚀 新增属性校验

🚀 新增校验器

• 供应商、 客户、仓库、部门、币别、付款条件、工作中心校验器

版本 [5.4.2] – 2026-06-23

🚀 优化

全新注释规范

• 注释规范：适用于所有控制器
• 方法功能简要描述
• ：参数详细说明（必填字段标注）
• ：返回值描述
• ：HTTP响应码及含义（200/401/400/403）
• ：包含业务规则、状态限制、数据变更、授权码
  所有注释保持统一的缩进风格（4空格）和术语规范，确保文档一致性。

回参【重要】

• 返回指定选择字段：回参只会回selectedColumns指定的字段节点
  selectedColumns：“production_line_code,production_line_name”
  返回指定列结果集,增加调用的灵活性

版本 [5.3] – 2026-06-22

🚀 新增功能

缓存管理后台

• 精准清理缓存：支持按「公司 + 缓存类型」组合条件清除指定缓存数据。
• 租户级批量清理：支持一键清除指定公司下的全部缓存。
• 全量清理缓存：支持清空整个缓存存储池（含二次确认机制）。
• 缓存类型列表查询：支持获取系统当前所有可用的缓存类型枚举。
• 手动缓存预热：支持针对指定缓存键手动触发数据预加载。
• 缓存健康状态监控：支持实时检测缓存服务的连接状态与响应延迟。

🔧 优化改进

1. 请求前置校验

• 将 Datakeys 有效性校验前移至 Action 执行前统一拦截，提前过滤非法请求，降低业务层无效负载。

2. 统一错误响应格式

• 统一授权验证与机器验证的异常返回结构，确保所有错误响应遵循相同的数据格式规范，提升前端对接效率。

3. 冗余参数校验清理

• 移除读取和查询接口中「公司」参数及 datakeys[0] 为 null 的冗余重复判断逻辑，统一收敛至前置校验层处理，简化业务代码，降低维护成本。

4.属性校验

• 部分单据类型字段校验：工单、生产入库单、领退料单、进货单、采购单、请购单、工单变更单、采购变更单等单据的类型，必填而且只允许1.工程品号 2.正式品号[DEF:“2”]

5.取消重试策略

• 取消重试：因为网络不稳定，存在事务管理的作业导致错误，暂时取消重试，待后续更新重试机制。（因涉及单据较多风险高）

4. WMI 性能优化（CPU 读取超时处理）

• 问题描述：读取 WMI CPU 值时偶发超时，导致系统卡顿。
• 优化方案：
  • 在 AuthorizeFilter 中设置超时管理机制，控制 WMI 读取操作的最大等待时间，避免无限阻塞。
  • 引入 CPU 值缓存机制，缓存有效期为 5 分钟，后续请求直接从缓存读取，大幅降低高频 I/O 操作带来的性能开销。

📝 影响范围

⚠️ 升级注意事项

2026-06-21

🐛 缺陷修复

• 分页逻辑：请求的页面超出范围时，返回最后一页的数据
• 自动填充服务修复支持复合主键模式和单一主键模式(普通模式)

🐛 优化

• 错误信息冗余：错误信息冗余1551处
• 变更与单据验收：抽取通用审核和撤审 作废的通用方法。
• 公司参数校验：重复校验，剔除冗余代码。

2026-06-20

🐛 缺陷修复

• 分页逻辑：请求的页面超出范围时，返回最后一页的数据
• 自动填充服务修复支持复合主键模式和单一主键模式(普通模式)

🚀 性能与架构优化

• 控制器横切关注点增强：实现全局 Action Filter 自动服务填充机制，通过依赖注入在请求预处理阶段完成用户身份、租户ID等上下文参数的自动装配，减少控制器重复代码
• DTO 结构优化：库存交易单与调拨单 DTO 独立拆分，避免业务耦合，提升可维护性

🐛 缺陷修复

• 接口异常修复：修复 copi10/puri10 接口在特定边界条件下触发未捕获异常导致 HTTP 500 的问题
• 数据库连接异常增强：当获取数据库名称或ID时连接失败，现明确抛出包含上下文诊断信息的 DatabaseConnectionException 自定义异常，便于问题定位

2026-06-19

🔄 基础设施重构

• DbContext 依赖注入改造：
  • 消除 DbContext 直接实例化，全面实施 IDbContextFactory 依赖注入方案
  • 新增 IErpDbContextFactory 接口及实现
  • 改造 BaseController 支持 DbContext 工厂注入
  • 重构 SysDocStateService 使用工厂创建 DbContext
  • 为全部约 50 个业务控制器构造函数统一添加 IErpDbContextFactory 依赖注入

⚡ 性能与安全优化

• 序列化优化：DTO 主档列表属性添加 [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]，确保查询接口不返回空明细字段，减少网络传输
• 安全增强：CORS 跨域策略支持来源地址可配置；BaseDataCacheService 调整为单例模式，确保缓存一致性
• 缓存架构升级：BaseController 合并构造函数，剔除内存缓存服务，全面迁移至分布式缓存（Redis）

2026-06-18

🛡️ 基础数据缓存全面加固

⚡ 性能优化

• 解决 N+1 查询问题：批量校验品号、单位成本时，将循环逐条查询优化为单次批量查询，数据库访问次数从 O(n) 降为 O(1)
• 全面排查：对部分控制器中存在的 N+1 查询进行全面治理

2026-06-17

🏗️ 架构与规范优化

• 全局异常处理：以全局异常过滤器（IExceptionFilter）替代各控制器中散落的 try-catch，实现异常统一捕获、分类处理和标准化错误响应，代码冗余减少 70%
• 代码质量提升：
  • 消除魔法字符串，提取为常量或枚举，增强可维护性
  • 查询与读取接口响应格式与官方 JSON 规范完全对齐

2026-06-16

✨ 新功能发布

• 新增录入 EBOM（工程物料清单）
• 新增 EBOM 变更单
• 新增组合单、拆解单
• 新增工单拆分功能

2026-05-18

✨ 新功能发布

• 新增录入 BOM 变更单全套接口：查询、读取、新增、修改、更新

2026-04-18

⚡ 核心业务逻辑增强

• 成本计算自动化：库存交易单中影响成本码的单据，自动获取移动加权平均单位成本并同步计算金额
• 审核逻辑统一：所有审核接口的审核日期依据（审核日 vs 单据日期）统一遵从 ERP 系统共用参数中的「审核日设定」
• 异步化改造：所有审核接口和撤审接口全面切换为异步模式（async/await），提升并发吞吐量

2026-04-13

🏗️ 框架升级与代码质量

• 框架升级：从 .NET 8 升级至 .NET 10（为确保 Swagger UI 正常使用，Swashbuckle.AspNetCore 降级至 7.3.2）
• 抽象复用：将品号验证逻辑抽象至 BaseController，所有 Create 方法统一调用，消除重复代码
• 单元测试覆盖：为 SysInvalidService、BaseDataCacheService、Sys01Controller 编写单元测试
• 代码清理：移除被注释冗余代码，移除重复数据库查询
• Swagger 文档增强：补全 API 文档注释，提升可读性和可维护性

2026-04-12

🚀 查询性能大幅优化（O(n) → O(1)）

• 数据结构优化：将 FirstOrDefault 线性查找（O(n)）全面替换为字典 TryGetValue（O(1)）
• 并行化处理：使用 Task.WhenAll 并行执行最多 12 个缓存服务调用，数据获取时间显著降低
• 分布式缓存集成：基于查询参数 + 公司别生成缓存键，设置 60秒绝对过期 + 30秒滑动过期
• 动态排序：应用 ApplyDynamicSorting 支持灵活排序

🐛 缺陷修复

• 修复新增接口中公司编号误用账套名称的问题，统一使用 CompanyId
• 修复来源单据单别为空时的异常返回
• 补全 try-catch 块及错误日志记录
• 缓存策略精细化：基础数据根据异动频率区分缓存失效时间（1-12小时）

2026-04-08

⚡ 异步与缓存架构升级

• 同步操作全面改造为异步（async/await）
• 内存缓存替换为 Redis 分布式缓存，支持多实例共享

2026-04-07

🏗️ 开发体验与规范性提升

2026-04-01

🐛 缺陷修复

• 修复新增接口因目标表存在触发器导致的新增异常问题

2026-03-03

✨ 功能增强

• 采购变更单、订单变更单、工单变更单：变更版本号自动获取，无需人工传入
• 上述变更单单身序号自动补充（0001、0002…）

2026-01-02

🏗️ 接口规范统一

• 参数格式标准化：所有 DTO 统一添加字段：company、creator、usr_group、create_date、modifier、modi_date、flag，便于异构系统调用

🐛 PredicateBuilder 查询增强

• 修复操作符不支持 OR 条件的 BUG，空操作符默认使用 AND
• 新增过滤操作符：IN、NOT IN、BETWEEN、EXISTS、NOT EXISTS
• 所有查询接口支持用户自定义二次排序，逻辑抽象至 BaseController

2026-01-01

🏗️ BaseController 基类抽象（重大架构调整）

所有控制器继承 BaseController，基类统一封装：

• 公司数据库账套管理
• 分页参数标准化
• DbContext 创建与管理
• 单据状态判断（未审核/已审核）
• DTO 自动映射（AutoMapper）
• 日志记录、作废逻辑
• 基础数据缓存服务
• 程序ID与程序名称上下文

效果：各控制器代码量平均减少 60%，一致性大幅提升。

✨ 功能增强

• 补充其他应收款单新增和更新接口
• 新增单据支持：前端审核码未填或错误时，后台默认单头和单身审核码为 'N'

2025-12-30

🐛 缺陷修复

• 修复采购发票接口中 project_no 字段映射 Tb046 表导致读取失败的问题

2025-12-29

🚀 性能与代码质量优化

2025-12-28

🔒 安全与框架升级

• IP 白名单：支持 IP 地址白名单可配置
• 框架升级：.NET 8 → .NET 9，提升运行时性能
• 驱动替换：System.Data.SqlClient → Microsoft.Data.SqlClient，提升兼容性与未来支持

2025-12-27

✅ 接口校验增强

• 品号不存在或未核准时拦截并返回明确错误
• 校验单据性质设置：来源订单单别、单号、行号不允许为空

2025-12-26

✨ 自动单号生成

• 所有单据新增接口：单别或单号为空时，系统依据单据性质设置自动产生新单别单号

2025-12-21

✅ 业务规则校验增强

• 采购变更单新增：订单数量不允许小于已交货数量
• 所有新增接口增加品号有效性校验

2025-11-21

✨ 新功能发布

• 工单变更单：补全查询、读取、新增、更新、删除接口

2025-11-20

✨ 新功能发布

• 采购变更单、订单变更单：补全查询、读取、新增、更新、删除接口

2025-09-27

🚀 性能与规范性优化

✅ 参数校验规范（统一标准）

2025-09-26

✨ 功能增强

• 核价单 & 报价单接口优化：读取、新增、更新、删除增加子单身功能

2025-09-25

✨ 新功能发布

• 新增工单工艺接口
• 新增报工单接口
• 新增转移单接口

2025-09-24

✨ 新功能发布

• 新增退回委外验退件接口
• 新增预付款单接口

2025-09-23

✨ 新功能发布

• 新增报价单接口
• 新增验退件退回接口
• 新增工艺信息接口

2025-09-22

🔒 安全架构升级

2025-09-21

🔒 新功能发布

• API 接口授权机制上线：增强接口安全性，支持客户按需定制授权

2025-09-18

🏗️ 代码复用优化

• 抽象单据审核状态服务
• 抽象通用作废服务
• 大幅降低业务控制器代码冗余

2025-09-17

✅ 业务逻辑增强

• 更新所有审核/撤审核/删除/作废接口：增加单据状态判断逻辑控制，防止非法操作

2025-09-16 ~ 2025-09-04

✨ 大批量新接口发布（功能模块补全）

2025-09-07 ~ 2025-09-05

🛠️ 基础设施完善

• 全局异常中间件：早期捕获异常并结构化记录（2025-09-07）
• Serilog 结构化日志：替换默认日志，支持链路追踪（2025-09-06）
• 内存缓存机制：基础信息资料及计算量大数据缓存，降低数据库压力（2025-09-05）

2025-08-03 ~ 2025-07-28

✨ 功能与质量优化

• 新增作废接口（全部单据含变更单）（2025-08-03）
• 新增采购变更单、订单变更单、工单变更单、BOM 变更单接口（2025-08-02）
• 修复审核领料单接口数组与字符串类型转换失败异常（2025-08-01）
• DTO 字段补充说明、主键添加 [Required] 特性（2025-07-30）
• 新增异常信息抛出，提升可读性（2025-07-29）
• 新增与更新接口调整为异步，批量添加实体提升效率（2025-07-28）

2025-06-27 ~ 2025-06-26

✨ 功能增强

• 全部接口添加易飞标准自定义字段（24个）（2025-06-27）
• 主要单据新增和修改时，单头汇总数据自动重算（2025-06-26）

2025-05-25 ~ 2025-04-02

✨ 功能与安全持续交付

2025-03-30 ~ 2025-03-20

🔒 安全与身份认证

• 新增审核和撤审接口（最高支持易飞 9.0.8）（2025-03-30）
• 新增 JWT 身份验证（2025-03-20）

2025-02-10 ~ 2025-03-10

✨ 核心业务模块大规模交付

• 应收管理模块接口
• 应付管理模块接口
• 总账管理模块接口

2025-01-01 ~ 2025-01-30

✨ 基础模块交付

• 基本信息模块接口
• 采购模块接口
• 销售模块接口
• 存货模块接口
• 生产管理模块接口

📊 更新统计摘要