版本日志

v3.3.1

2025/9/29

此版本添加了一些功能。

新增

1. 新增流程节点备注功能，支持管理员在流程设计界面添加备注信息。
2. 新增流程操作手册上传功能，支持在流程办理界面查看。
3. 新增流程数据推送新版实现，提升推送性能。
4. 新增 OBS 对象存储服务集成。
5. 文件响应特性 [ResponseFile] 新增下载链接属性，支持浏览器直接访问并以原文件名下载。
6. 新增图形验证码功能，支持图片生成与验证。 注意：每个图形验证码仅能使用一次，若验证失败应请求生成新的验证码。
7. 新增基于 UMPP 的短信、邮箱验证码发送与验证功能。
8. 新增基于 SAG 的 UAC 用户相关接口声明，详情请查看 HZCC.Frm.Service.Http.ISagApi。
9. 流程引擎新增会签功能，支持多人办理任务。
10. 流程引擎办理任务时支持指定办理人，详情请查看 WorkStepDto/WorkStepNodeDto.OperatorId。
11. 流程引擎新增节点离开事件，支持在节点离开时执行自定义逻辑。实现 INodeEventHandler.OnLeave 方法即可。
12. 组织机构新增 Code 字段，支持从上游同步。
13. 基础服务 BaseGenericService 新增了事务操作方法，方便在服务层使用。

修正

1. 修复流程引擎已读事件可能触发多次的问题。

变更

1. 流程数据推送默认使用新版实现。
2. 对象存储服务不再默认使用 MinIO，存储类别由MinioConfig.Type配置项指定。
3. 框架根据上述配置自动注册对应的对象存储客户端服务，开发人员必须移除项目中单独注册的IMinioClient。
4. 同一流程（code 相同）现在只能启用一个版本，不再支持同时启用多个版本。
5. 流程引擎办理人员规则中的表单人员，现在支持读取以逗号分隔的多个人员数据。

移除

无

升级指南

1. 执行v3.3.1.sql。
2. 推荐使用新版流程数据推送，该版本优化了触发机制和性能。在配置文件添加如下配置项：

   "Workflow": {
      "EmpCenter": {
           "LegacyPushMode": false, // 是否使用旧版推送模式，默认false
           "MaxTransExecSeconds": 5, // 事务最长执行时间（秒），在此时间内会积极获取新数据
           "MaxRetry": 3, // 最大重试次数
           "RetryDelayMillis": 1000, // 重试间隔时间（毫秒）
           "RetryGrowFactor":  2 // 重试间隔增长因子，下次重试间隔=当前间隔*增长因子
       }
   }

   注意：要继续使用旧版，请将 LegacyPushMode 设置为 true。
3. 要使用对象存储服务，配置文件需要添加Type配置项：

   "MinioConfig": {
      "Type": "MinIO", // 对象存储服务类型，可选：MinIO、OBS、None
   }

   注意：指定Type后，框架会自动注册对应的客户端服务，请检查并移除项目中单独注册的IMinioClient。
4. 基于合规要求，OBS 默认不支持在线预览文件，即图片、视频等文件无法直接在浏览器中打开。 要支持在线预览，需开启 CDN 功能。具体请参考官方文档。
5. 基于[ResponseFile] 特性返回的文件信息中，添加了 DownloadUrl字段，前端可直接跳转此链接下载文件，文件名与原文件一致。
6. 要使用图形验证码功能，需要复制 fonts 目录到项目根目录；并修改 Dockerfile 文件：

   COPY --from=publish /app/publish .
   # 添加如下内容
   COPY --from=publish /src/fonts /usr/share/fonts

   前端请求 /api/caps/{id} 即可获取验证码图片，其中 {id} 为8位随机数字。
7. 要使用短信、邮箱验证码功能，需要在配置文件添加如下配置项：

   "Sag": {
       "Umpp": {
         # 其它配置项省略
         "CapBizCode": "user_register_sys" # 默认的验证码业务标识，由 UMPP 下发
       }
   }

   调用示例：

   // 注入服务
   [Autowired]
   IUmppApiWrapper apiWrapper;
   // 发送验证码。出于安全考虑，用户必须先通过图形验证码验证，因此需要传入验证码ID和值。
   apiWrapper.SendCaptcha(new UmppCaptchaSendDto(UmppChannel.Sms, "166xxxx1234", capId, capCode));
   apiWrapper.SendCaptcha(new UmppCaptchaSendDto(UmppChannel.Email, "wangdachui@hzcctech.net", capId, capCode));
   // 验证验证码
   apiWrapper.ValidateCaptcha(new UmppCaptchaVerifyDto(UmppChannel.Sms, "18600005917", capCode));
   apiWrapper.ValidateCaptcha(new UmppCaptchaVerifyDto(UmppChannel.Email, "wangdachui@hzcctech.net", capCode))

   注意：默认使用配置文件中指定的业务标识，要使用其它标识请使用 Dto 的重载方法。

v3.3.0

2025/4/23

此版本实现了语言本地化支持，修复了一些问题。

新增

1. 新增 FxResoures.System.ComponentModel.Annotations.zh-Hans、zh-Hant 依赖，支持模型验证默认错误消息本地化。
2. 各项目添加 LocalRes.resx 资源文件，支持简体中文、繁体中文、英文。
3. 新增超级管理员是否可禁用开关 SuperAdminDisableAllowed。
4. 新增基于 DictData 特性的列表数据字典翻译服务，配合 Excel 导出使用。
5. 新增用户设置功能，允许保存用户自定义设置。
6. 工作消息新增链接，支持跳转至工作详情。
7. 新增流程引擎与第三方系统集成功能，支持工作数据推送到员工中心。
8. 新增消息平台重载方法，支持基于网关认证的企微消息发送。

修正

1. 修复 sql 日志无法开启显示问题。
2. 修复用户日志异步环境报错问题。
3. 修正工作任务当前用户查询数据包含空用户问题。
4. 修正工作任务历史节点查询数据重复问题。
5. 修复查看模式下无法查看工作最新节点表单问题。

变更

1. 各项目硬编码中文文本调整为资源类属性，支持本地化输出。
2. 工作转发时不再限制任务必须为可办理状态。
3. 工作台转发工作列表现在仅显示未读数据。
4. 工作人员现在支持使用禁用用户，以使工作代理生效。
5. 用户搜索功能现在支持简拼与全拼搜索。
6. 用户搜索方法 GetBySnOrName 默认不再返回禁用用户，如有需要请指定 includeDisabled 参数。
7. 工作消息现在使用基于 SAG 的消息平台接口，不再依赖 UHP 服务。请按照升级指南步骤 5 进行更新。

移除

1. 移除 WorkflowConsts 部分无用常量。

升级指南

1. 执行v3.3.0.sql。
2. 配置文件添加工作流配置节：

   "Workflow": {
       "Notice": {
         "LinkPrefix": "", // 工作流消息链接前缀，通常为前端域名。如：http://foo.com
         "Email": false, // 是否启用邮件通知
         "WeChat": false // 是否启用企微通知
       }
   }

3. 如果要开启推送数据到员工中心，配置文件添加如下配置节：

   "Workflow": {
       EmpCenter": {
           "SysCode": "frm", // 当前系统在员工中心的系统标识
           "Interval": 5, // 推送频率（秒）
           "ErrorThreshold": 10, // 连续错误阈值。当连续错误次数达到此值时，推送频率将倍数增长。
           "GrowFactor": 2, // 推送频率增长因子。即连续错误次数达到阈值时，推送频率将乘以此值。
           "MaxInterval": 300, // 推送频率最大值（秒）。推送频率超出此值时，将重置为初始值。
           "Enable": true // 是否启用
       }
   }

   注意：同时需要添加网关配置信息，请查看下一条说明。
4. 如果要调用基于网关的接口，配置文件添加配置节：

   "Sag": {
   	"Url": "http://118.195.128.183:3095", // 网关地址
   	"AppId": "frm", // 网关下发的应用标识
   	"Secret": "46xxxxxxa74" // 网关下发的应用密钥
   }

5. 调整消息发送代码，使用新版企微消息推送（不经过 UHP）功能，配置文件添加配置节：

   "Sag": {
   	"Umpp": {
           "AppCode": "frm", // 发送方标识
           "EmailAccountCode": "52xxxxx54", // UMPP 下发的邮箱账户编码
           "QyAgentId": "1a7xxxxxx966d" // SAG 下发的企微应用标识
       }
   }

   调用示例：

   IOptions<SagUmppOptions> options;
   await api.SendQyWechatTextAsync(new UmppQyAppTextMsg(
       options.Value.QyAgentId,
       "hello from frm",
       new List<string> { "001001" },
       UmppQyMsgTo.User,
       options.Value.AppCode)
   );

6. 关于语言本地化详细内容，请查看线上文档。

v3.2.1

2024/11/20

此版本添加了一些功能。

新增

1. 工作流：流程新增分类功能，支持按分类查询待办。
2. 工作流：新增用户工作查询功能，支持按需关联业务数据查询。
3. 工作流：工作组件支持接收 BizId / WorkId 参数，查看任意工作信息，不限制实际操作人。
4. 新增SignedOldApiFilterAttribute、SignedPlusApiFilterAttribute特性，支持不同版本的 API 签名认证。
5. OptionalExpressionBuilder 新增 Where 方法，支持添加固定条件。

修正

1. 修正 UAC 代理配置不生效问题。
2. 修正 ApiPlus 认证模式在部分情况下不生效问题。
3. 修正字典翻译接口无法接收请求体问题。

变更

1. 工作流：在工作组件查看工作详情时，支持仅传递 WorkId 参数。
2. 工作流：结束节点任务不再使用当前处理人信息，无需办理。

移除

无

升级指南

1. 执行v3.2.1.sql。

v3.2.0

2024/10/25

此版本添加了工作流、岗位同步功能，以及一些其它优化。

新增

1. 新增工作流功能，支持流程定义、任务办理、超时提醒、流程干预等功能。具体请参考框架在线文档。
2. 新增岗位同步功能。
3. 用户新增岗位与上下级信息，用户服务支持根据上下级查询。
4. 新增 AllowedEnvironmentsAttribute 特性，限定接口服务仅在指定环境下可访问。
5. 新增 OptionalExpressionBuilder 类，提供多个判断方法简化服务层的动态条件生成。
6. BaseEntity 添加 ClearBaseFields 方法，支持清空实体基础属性。

修正

无

变更

1. BaseDal 中的 QueryListPage 已调整为公共方法，支持由传入的 Query 参数返回分页结果。
2. 进一步优化 NAutowired 库，添加 AspectCore 支持，不再依赖 AspectCore.Extensions.DependencyInjection.NAutowired。

移除

无

升级指南

1. 执行v3.2.0.sql。
2. 将 Program.cs 中导入的命名空间 AspectCore.Extensions.DependencyInjection.NAutowired，修改为 AspectCore.Extensions.DependencyInjection。
3. 如果需要使用工作流完整功能
   • 请在 XxlJob 服务端创建 wf-timeout、wf-message 两个任务，触发频率建议分别为 20 分钟、5 分钟。
   • 在配置文件中添加 xxlJob 配置，启用定时任务。

     "xxlJob": {
       "Enable": true,
       "AdminAddresses": "http://服务地址/xxl-job-admin",
       "appName": "执行器名",
       "specialBindUrl": "http://程序地址/xxl-job",
       "specialBindPath": "/xxl-job",
       "autoRegistry": true,
       "accessToken": "",
       "logRetentionDays": 30
     },

   • 在配置文件中添加消息服务配置。

     "Umpp": {
       "Url": "uip地址",
       "AppId": "uip应用",
       "Secret": "uip密钥",
       "QyId": "uhp企业应用",
       "EmailAccountCode": "umpp邮箱码"
     }

v3.1.1

2024/9/12

此版本添加了一些功能。

新增

1. 新增文件对象存储管理功能，支持文件状态记录、业务绑定、数据查询。
   • 新增BindBizFileAttribute特性，支持声明式的业务数据与文件记录绑定。
   • 新增ResponseBizFileAttribute特性，支持声明式的业务数据已关联的文件记录查询返回。
2. 新增Xxl-Job任务调度集成，简化配置与开发模式。详情请查看框架在线文档。
   • 新增XxlJobHandler特性，声明任务处理器并注册为 Scoped 服务。
3. 新增LoginLogAttribute、LogoutLogAttribute特性，支持声明式的登录、登出日志记录。
4. 新增日志清理功能，支持以多种形式清理系统、用户、登录日志。详情请查看框架在线文档。
5. UserLogAttribute 特性新增几个参数，支持限定内容长度与忽略请求头或请求体。

修正

无

变更

1. Swagger 文档地址修改。
2. About 接口除 version 外，不再支持匿名访问。
3. 登录日志清理接口不再支持传入时间参数，需要前端 2.2.0+ 版本支持。
4. NAutowired 库切换为自定义版本，提升性能。

移除

无

升级指南

1. 执行v3.1.1.sql。
2. 如果需要启用Xxl-Job功能，请参考框架在线文档进行配置。
3. 如果需要启用日志自动清理功能，请参考框架在线文档进行配置。

v3.1.0

2024/2/6

此版本重构部分代码，添加了一些新功能。

新增

1. 新增第三方接口请求响应日志记录功能。
2. 新增接口配置功能，支持独立设置每个接口的日志启用状态。
3. 新增系统设置功能，可以进行网络请求等相关参数设置。
4. 新增登录日志功能，记录登录与登出日志。
5. 新增在线用户功能，支持在线用户查询与清除。
6. 新增缓存管理功能，支持缓存数据查询与清除。
7. 新增彩色日志输出，区分不同级别日志。
8. 任意级别的日志，当内容以[force]开头时，会写入数据库保存。
9. 新增ToResult方法，简化控制器响应对象创建方式。具体请参考各控制器方法。
10. BaseGenericService类中支持排序的方法，新增了对应重载方法，支持传入任意数量的排序字段。
11. BaseGenericService.GetListPage方法现在可以传入字符串式排序信息，以支持前端页面的自定义排序情况。
12. 新增WebApiClient引用，支持声明式调用外部Http接口。具体使用方法参考IUacApi相关代码。
13. Common库新增ValidationHelper，支持手动调用模型验证。
14. Common库新增IpAddressHelper，支持IP归属地离线查询。

修正

1. 修正树字典查询时排序不正常问题。
2. 修正更新时间与创建时间一致性问题。现统一取web服务时间，不再使用数据库时间。
3. 修正特定情况下AutoMapper执行报错问题。

变更

1. 代码重构为使用主构造函数注入模式，同时保留[Autowried]注入支持。
2. 代码重构为使用文件域命名空间（file-scoped namespace）。
3. 模型层Input、Output、Bo类分别移至独立的命名空间。
4. 控制器参数错误不再返回500响应。修改为响应码200，错误码999。
5. Result<T>不再允许忽略Body参数。如有需要请使用非泛型类Result。
6. ServiceProviderAccessor变更为正式特性，可在请求管道范围内任意位置获取服务容器。
7. BaseGenericService类中支持两个排序字段的查询方法，标记为已过时。
8. BaseGenericService类中的分页查询方法，现已不再支持通过特殊参数值查询全量数据。
9. 默认不再在控制台显示SQL日志，需要时请至系统设置页面开启。
10. 非超级管理员操作角色时，可操作数据限定在其自身拥有的资源范围内。无法操作他人创建的角色，也无法授权给用户。
11. 优化部分类名。
    • AbstractRowObjectMapper更改为AbstractDbRowMapper。
    • WrapperBo更改为MultiApiCallResult。
12. 字典、用户、角色、资源等路由重构为Restfull格式，原路由已标记为过时。
13. 重构Common库Excel相关类方法。合并至ExcelHelper类，其它类标记为过时。
14. 调整Common库EPPlus依赖版本，消除潜在的版权问题。

移除

1. 移除Result<T>类的Success()、Success(msg)重载方法。
2. 移除HZCC.UAC.Client引用。

升级指南

1. 执行v3.1.0.sql。
2. 从HZCC.Frm.Api复制nlog.config文件，覆盖至Api项目根目录。
3. 按需修正模型类的引用命名空间。

v3.0.0

2023/12/18

此版本升级.NET框架至.NET8，使用C#12语法重构现有代码。同时添加了一些新功能，修复了一些已知问题。

新增

1. Swagger文档新增签名认证模式，支持基于签名认证的接口在线调用。
2. 新增OptionalExpression<>类，简化ORM动态条件生成。
3. BaseGenericService新增Add(object)方法。
4. DbCommandInterceptor添加sql参数输出。
5. 新增RequiredIfAttribute特性，支持根据其它属性值决定当前属性是否必填。
6. 支持低级别日志按需入库（日志内容以[db]开头即可）。
7. 新增ServiceProviderAccessor类，支持以静态属性获取ServiceProvider。[实验性功能]
8. 数据维度功能，支持针对树模式的更多配置选项。

修正

1. 修正用户数据权限不能按条件查询问题。
2. 修正用户数据权限列表排序混乱问题。
3. 修正用户无法批量查询问题。
4. 修正菜单禁用后无法再找回问题。
5. 修正默认认证策略在特殊情况下重复执行问题。
6. 修正组织机构同步中潜在的死循环问题。
7. 修正树字典缓存异常问题。
8. 修正同时使用新老版本签名认证时，新版本不生效问题。

以上修正已同步至2.6.0+。

变更

1. DataScopeAttribute、UserLogAttribute类移至Attributes命名空间。
2. 优化调整了操作日志记录格式。
3. 优化了swagger接口排序。
4. 消除部分分页参数PageInfo，由dto继承。
5. BaseService.Update方法忽略值为default(DateTime)的字段更新。
6. 增强版签名认证模式名称，由api-plus更名为sign。原api模式标记为过时。

移除

1. BaseGenericService移除Update(T)方法。
2. 移除CodeGenerateController控制器。
3. 移除UserService类无用的GetByEmp、GetListSimple、Update方法。
4. 移除RoleResService类无用的GetRoleResources方法。

升级指南

1. 确保项目从基础框架2.7.0版本开始升级。若低于该版本，请先参考各版本升级指南进行升级。(新项目忽略此条)
2. 更新后端开发工具软件至最新版。
3. 修改主项目中各csproj文件，更新为<TargetFramework>net8.0</TargetFramework>。
4. 从HZCC.Frm.Api项目复制nlog.config文件，覆盖至主项目Api项目根目录。
5. 从本项目根目录复制Dockerfile文件，覆盖至主项目根目录。
6. 开放接口给第三方调用时，优先使用AuthenticationSchemes = "sign"认证模式。具体算法请查看swagger文档。