2024-09-20 更新日志

📋 本次更新

GitLab 域名统一

• ✅ 将文档中所有 git.woowis.com 链接替换为 https://glab.woowis.com
• ✅ 全部升级为 HTTPS 协议
• ✅ 保留 ngitl.woowis.com（框架核心库使用）

受影响文件

文件	修改内容
src/guide/CreateModule.md	示例仓库链接
src/guide/GetingStart.md	git clone 命令、Issues 链接
src/guide/README.md	GitLab 和示例项目链接
src/extend/MSBuild.md	RepositoryUrl
src/update/2020-04-18.md	RepositoryUrl
src/platform/NuGet.md	PackageProjectUrl、RepositoryUrl
src/frendEnd/Skins.md	git clone 命令、源码链接
src/frendEnd/Framework.md	Git 仓库链接
src/fundamentals/ModuleCatalog.md	多个模块 Git 地址
src/fundamentals/SystemCatalog.md	系统模块 Git 地址
src/modules/00_Admin.md	Admin 模块 Git 地址
src/.vuepress/config.js	导航栏 GitLab 链接、更新日志菜单

统计

• 12 个文件 被修改
• 64 处 URL 被更新
• 0 处 功能变更（仅链接更新）

---

🔗 域名说明

域名	状态	用途
glab.woowis.com	✅ 使用中	DarkM 业务模块、示例项目、OA 项目
ngitl.woowis.com	✅ 使用中	DarkM 框架核心库（framework 目录）
git.woowis.com	❌ 已废弃	已全部迁移

---

最后更新: 2024-09-20

Bug 修复

文件	问题	修复
src/modules/00_Admin.md	Git 仓库地址错误 (glab.woowis.com/doterra/oa/NewOA)	更正为 ngitl.woowis.com/framework/darkm/darkm.module.admin.git

Bug 修复

Admin 模块 Git 仓库地址修正

文件	问题	修复
src/modules/00_Admin.md	Git 仓库地址错误	更正为 ngitl.woowis.com/framework/darkm/darkm.git

说明：

• Admin 模块代码包含在 darkm.git 核心库中，不是独立仓库
• darkm.git 包含 Framework 核心代码 + Admin 核心模块
• NewOA.git 是启动项目（不含业务代码），地址：glab.woowis.com/doterra/oa/NewOA.git

ModuleCatalog.md 修正

问题	修正
NOA-启动器 (StartNOA) 标题错误	改为 NOA-需求管理 (Project)
project.git 功能描述错误	改为"IT 需求申请/审批、需求收集、需求评审、需求跟踪、需求统计"
误将 project.git 当作启动器	project.git 是 OA 普通业务模块（需求管理）

说明：

• NewOA 启动器 = NewOA.git（主系统入口）
• project.git = 需求管理业务模块（为业务部门提供线上需求申请/审批功能）

SystemCatalog.md 术语统一

问题： 文档中混淆了"模块"和"系统"的概念

修正：

• 明确术语定义：
  • 模块 = DarkM 模块（如 Admin、Common、WorkFlow 等），是功能单元
  • 系统 = 启动器项目（如 NewOA、JoyIn、StartEDW 等），是独立运行的应用入口
• 更新统计：18 个模块 + 6 个系统（启动器）
• 修正所有"业务系统"为"业务模块"（非启动器项目）
• 更新架构图说明，标注系统与模块数量

影响范围：

• 文档标题、术语说明、统计表格
• NewOA/会员/商城系统架构说明
• 模块与系统组合模式说明
• 开发规范中的命名规范

DI 和 Options 文档优化

DI.md 优化：

• ✅ 重构文档结构，增加核心概念说明（DI vs IoC）
• ✅ 补充 .NET Core DI 三种生命周期详解（Singleton/Scoped/Transient）
• ✅ 添加 DarkM 框架自动注册机制说明（SingletonAttribute）
• ✅ 新增最佳实践章节（5 条实践指南）
• ✅ 新增常见问题 Q&A（3 个问题）
• ✅ 更新代码示例为现代 C# 风格

Options.md 优化：

• ✅ 重构文档结构，增加配置项说明
• ✅ 补充所有配置节的详细说明和表格（Host/Db/Cache/Serilog/Admin/Upload）
• ✅ 添加 4 种配置读取方式（IOptions/IOptionsSnapshot/IOptionsMonitor/IConfiguration）
• ✅ 新增配置验证示例
• ✅ 新增最佳实践章节（5 条实践指南：强类型、命名规范、验证、环境隔离、敏感信息保护）
• ✅ 新增常见问题 Q&A（3 个问题）

统计：

• DI.md: 128 行 → 450 行（+322 行）
• Options.md: 156 行 → 479 行（+323 行）

13_Options 改为 13_Config

变更：

• ✅ 重命名文件：13_Options.md → 13_Config.md
• ✅ 基于源代码重写文档内容
• ✅ 更新 VuePress 导航配置

新文档内容：

• ✅ 模块架构说明（项目结构：Config.Abstractions/Config.Core/Config.Cache/Config.Redis）
• ✅ 核心概念详解（IConfig/ConfigType/ConfigEnumProvider/ConfigDescriptor）
• ✅ 核心接口说明（IConfigProvider/IConfigStorageProvider/IConfigChangeEvent）
• ✅ 依赖注入自动注册机制（扫描所有 IConfig 实现类）
• ✅ 完整使用示例（定义配置/监听变更/读取配置/更新配置）
• ✅ 配置存储提供器（Memory/Cache/Redis 三种实现）
• ✅ 内置配置类（SystemConfig/ComponentConfig/PathConfig）
• ✅ 最佳实践（4 条：命名规范/变更处理/配置验证/存储选择）
• ✅ 常见问题 Q&A（3 个：配置类识别/变更事件触发/存储选择）

统计： 156 行 → 520 行（+364 行，+233%）

菜单更新与 PDF 文档新增

菜单变更：

• ✅ 更新菜单名称：配置管理 (13_Options) → 配置管理 (13_Config)
• ✅ 新增框架菜单：PDF 处理 (14_Pdf)

14_Pdf.md 新文档：

• ✅ 模块架构说明（项目结构：Abstractions/Integration/iText/PDFSharp/iText.Excel）
• ✅ 核心接口详解（IPdfHandler/IPdfExportHandler/PdfProvider/PdfConfig）
• ✅ 依赖注入自动注册机制（根据配置加载对应实现）
• ✅ 完整使用示例（配置/注册/PDF 信息获取/报表导出/多 Sheet 导出/导出模型配置）
• ✅ 实现提供器对比（iText vs PDFSharp vs iText.Excel）
• ✅ 最佳实践（4 条：中文支持配置/大数据导出优化/临时文件清理/导出性能优化）
• ✅ 常见问题 Q&A（3 个：中文乱码/内存溢出/提供器选择）

统计： 新增 520 行

文件存储 (16_OSS) 文档新增

菜单变更：

• ✅ 新增框架菜单：文件存储 (16_OSS)

16_OSS.md 新文档：

• ✅ 模块架构说明（项目结构：Abstractions/Integration/Local/Qiniu/Aliyun/Qiniu.SDK）
• ✅ 核心接口详解（IFileStorageProvider/OSSProvider/OSSConfig/QiniuConfig/AliyunConfig/QiniuZone）
• ✅ 依赖注入自动注册机制（根据配置加载对应实现）
• ✅ 完整使用示例（配置/注册/Base64 图片上传/文件对象上传/批量上传/删除文件/获取 URL）
• ✅ 存储提供器对比（Local vs Qiniu vs Aliyun，含适用场景）
• ✅ 最佳实践（4 条：文件命名规范/文件类型限制/上传进度跟踪/敏感文件加密存储）
• ✅ 常见问题 Q&A（3 个：提供器选择/七牛 Token 过期处理/断点续传实现）

统计： 新增 680 行

支付管理 (17_Payment) 文档新增

菜单变更：

• ✅ 新增框架菜单：支付管理 (17_Payment)

17_Payment.md 新文档：

• ✅ 模块架构说明（项目结构：Abstractions/Integration/Alipay/WeChatPay/Sandpay）
• ✅ 核心配置类详解（AlipayOptions/WeChatPayOptions 完整配置项说明）
• ✅ 依赖注入自动注册机制（扫描所有支付模块）
• ✅ 完整使用示例（配置/注册/支付宝扫码支付/微信小程序支付/支付控制器/回调通知处理）
• ✅ 支付提供器对比（Alipay vs WeChatPay vs Sandpay，含支持功能列表）
• ✅ 最佳实践（3 条：支付安全验证/幂等性处理/支付日志记录）
• ✅ 常见问题 Q&A（3 个：支付宝证书模式配置/微信支付证书获取/支付回调超时处理）

统计： 新增 780 行

微信 (18_Wechat) 文档新增

菜单变更：

• ✅ 新增框架菜单：微信 (18_Wechat)

18_Wechat.md 新文档：

• ✅ 模块架构说明（项目结构：Abstractions/Core/Integration/WxPayAPI）
• ✅ 核心配置类详解（WechatConfig/WechatAccount/JsSdkConfig 完整配置项说明）
• ✅ 依赖注入自动注册机制（加载 Wechat.Core 程序集）
• ✅ 完整使用示例（配置/注册/消息处理中间件/Token 获取/JS-SDK 签名配置/微信支付 JSAPI）
• ✅ 核心功能说明（7 种消息类型/6 种事件类型/6 种支付功能表格）
• ✅ 最佳实践（3 条：多账号管理/Token 缓存机制/消息回复模板）
• ✅ 常见问题 Q&A（3 个：微信服务器验证失败/Token 频繁失效/证书加载失败）

统计： 新增 850 行

脚本语言 (19_JavaScript) 文档新增

菜单变更：

• ✅ 新增框架菜单：脚本语言 (19_JavaScript)

19_JavaScript.md 新文档：

• ✅ 模块架构说明（项目结构：Abstractions/Integration/ChakraCore/NodeJs）
• ✅ 核心接口详解（IJavaScriptHandler/JavaScriptProvider/JavaScriptConfig）
• ✅ 依赖注入自动注册机制（根据配置加载对应引擎实现）
• ✅ 完整使用示例（配置/注册/执行 JS 代码/调用模块函数/动态规则引擎/JS 控制器）
• ✅ 引擎提供器对比（ChakraCore vs NodeJs，含特点/安装/适用场景）
• ✅ 最佳实践（4 条：脚本缓存/超时控制/沙箱安全/版本管理）
• ✅ 常见问题 Q&A（3 个：ES6 特性支持/JS 代码调试/异步代码处理）

统计： 新增 720 行

邮件 (20_Email) 文档新增

菜单变更：

• ✅ 新增框架菜单：邮件 (20_Email)

20_Email.md 新文档：

• ✅ 模块架构说明（项目结构：Abstractions/Integration/MailKit/MailKitOffice365/Reciver/SmtpClient/SystemMail）
• ✅ 核心接口详解（IEmailSender/EmailProvider/EmailConfig/EmailMessage/EmailAddress/EmailBody/EmailAttachment/EmailServer 完整说明）
• ✅ 依赖注入自动注册机制（加载所有邮件实现程序集）
• ✅ 完整使用示例（配置/注册/简单邮件/HTML 邮件/带附件邮件/群发邮件/分批群发/邮件控制器）
• ✅ 邮件提供器对比（MailKit vs SmtpClient vs MailKitOffice365，含特点/适用场景）
• ✅ 最佳实践（3 条：邮件模板/邮件队列/发送重试）
• ✅ 常见问题 Q&A（3 个：SSL 连接失败/认证失败/邮件被标记为垃圾邮件）

统计： 新增 900 行

短信 (21_SMS) 文档新增

菜单变更：

• ✅ 新增框架菜单：短信 (21_SMS)

21_SMS.md 新文档：

• ✅ 模块架构说明（项目结构：Abstractions/Integration/Aliyun/OneXinXi）
• ✅ 核心接口详解（ISms/SMSProvider/SmsConfig/SmsRequest/SmsResponse/QueryDetailsResponse 完整说明）
• ✅ 依赖注入自动注册机制（加载所有短信实现程序集）
• ✅ 完整使用示例（配置/注册/验证码短信/通知短信/批量发送/状态查询/短信控制器）
• ✅ 短信提供器对比（Aliyun vs OneXinXi，含特点/适用场景/配置示例）
• ✅ 最佳实践（3 条：验证码防刷/短信模板管理/发送日志记录）
• ✅ 常见问题 Q&A（3 个：发送失败处理/服务商选择/短信回执处理）

统计： 新增 750 行

第三方 (99_Third) 文档新增

菜单变更：

• ✅ 新增框架菜单：第三方 (99_Third)

99_Third.md 新文档：

• ✅ 模块架构说明（项目结构：Abstractions/Integration/JPush/WPSWebOffice/Spire.Office）
• ✅ 核心接口详解（IJiguangService/JPushConfig/MessageResult 完整说明）
• ✅ 依赖注入自动注册机制（加载 JPush 实现程序集）
• ✅ 完整使用示例（配置/注册/全部推送/按标签推送/按别名推送/订单通知/状态查询/推送控制器）
• ✅ 第三方服务对比（JPush vs WPSWebOffice vs Spire.Office，含特点/适用场景/推送方式表格）
• ✅ 最佳实践（3 条：推送频率控制/推送日志记录/推送模板管理）
• ✅ 常见问题 Q&A（3 个：推送失败处理/推送方式选择/推送回执处理）

统计： 新增 700 行

框架文档深度优化（00_Host 到 12_Excel）

优化范围： 13 个核心框架文档全面深度优化

优化文档列表：

• ✅ 00_Host.md - 主机配置（~14,500 行）

  • 完整目录结构
  • HostOptions 配置类详解
  • IpRateLimitConfig 配置详解
  • ServiceCollectionExtensions 源码解析
  • ApplicationBuilderExtensions 中间件管道源码
  • 5 个使用示例
  • 5 个常见问题及解决方案

• ✅ 01_Utils.md - 通用工具（~11,000 行）

  • ResultModel 结果模型详解
  • Check 参数检查工具类
  • 扩展方法使用示例
  • 工具类使用示例
  • 加密类使用示例
  • 5 个常见问题及解决方案

• ✅ 02_Data.md - 数据访问（~11,000 行）

  • 支持的数据库对比表格
  • IDbContext 接口详解
  • IDbSet 接口详解（BulkMerge 详解）
  • 配置项详解表格
  • 实体定义示例
  • 仓储接口示例
  • Service 层使用示例
  • 事务操作示例
  • BulkMerge 使用示例（3 个场景）
  • 分表操作示例
  • 5 个常见问题及解决方案

• ✅ 03_Logging.md - 日志模块（~14,600 行）

  • OpenTracingConfig 配置类详解
  • 配置项详解表格
  • AddOpenTracingLog 源码解析
  • 手动创建 Span 示例
  • 链路追踪上下文传递示例
  • Jaeger Docker 部署脚本
  • 典型请求链路图
  • 5 个常见问题及解决方案

• ✅ 04_Mapper.md - 对象映射（~10,900 行）

  • IMapperConfig 接口详解
  • IMapper 接口说明
  • AddMappers 源码解析
  • _MapperConfig 配置类完整示例
  • 新增/更新/查询/分页查询使用示例
  • 7 个高级用法示例
  • 5 条最佳实践
  • 5 个常见问题及解决方案

• ✅ 05_Swagger.md - API 文档（~10,300 行）

  • API 分组约定源码解析
  • 4 个自定义过滤器源码详解
  • AddSwagger 源码解析
  • Controller 注释完整示例
  • 模型注释示例
  • 权限编码表格
  • JWT 认证配置示例
  • Swagger UI 自定义示例
  • 5 个常见问题及解决方案

• ✅ 06_Cache.md - 缓存服务（~10,000 行）

  • 缓存提供器对比表格
  • 配置项详解表格
  • ICacheHandler 接口完整说明
  • 6 个使用示例（获取/设置/删除/穿透保护/分布式锁/Hash 操作）
  • 3 种缓存策略详解
  • 5 条最佳实践
  • 缓存提供器选择建议表格
  • 5 个常见问题及解决方案

• ✅ 07_Validation.md - 模型验证（~9,200 行）

  • 配置项详解表格
  • 验证器类完整示例
  • 异步验证示例
  • 条件验证示例
  • 自定义验证示例
  • Controller 手动验证示例
  • 自动验证说明
  • 验证结果处理示例
  • 内置验证规则表格
  • 验证器复用示例
  • 级联验证示例
  • 5 个常见问题及解决方案

• ✅ 08_Auth.md - 身份认证（~15,000 行）

  • 支持的认证方式对比表格
  • 配置项详解表格
  • 5 个核心接口详解
  • ClaimsName 常量说明
  • JWT 认证登录完整示例
  • Token 结构示例
  • 获取当前用户信息示例
  • 数据权限过滤示例
  • 3 种权限控制特性
  • 权限编码表格
  • 数据维度级别枚举
  • Token 刷新机制示例
  • 密码加密示例
  • 权限缓存示例
  • 审计日志配置
  • 5 个常见问题及解决方案

• ✅ 09_Module.md - 模块抽象（~10,300 行）

  • 完整目录结构
  • 标准模块项目结构详解
  • 4 个核心接口详解
  • 模块描述符完整示例
  • 模块依赖声明示例
  • 模块初始化器示例
  • 模块配置示例
  • 模块依赖排序说明
  • 6 条最佳实践
  • 模块版本管理
  • 模块文档模板
  • 5 个常见问题及解决方案

• ✅ 10_MQ.md - 消息队列（~9,900 行）

  • 支持的消息队列对比表格
  • 配置项详解表格
  • 3 个核心接口详解
  • 消息定义示例
  • 发布消息示例
  • 订阅消息示例
  • 消息处理器注册示例
  • 3 个使用场景详解
  • 消息确认机制
  • 5 条最佳实践
  • 5 个常见问题及解决方案

• ✅ 11_Quartz.md - 任务调度（~15,800 行）

  • 配置项详解表格
  • 5 个核心接口详解
  • 3 个任务示例（简单任务/带参数任务/清理任务）
  • 代码配置和数据库配置两种方式
  • Cron 特殊字符说明表格
  • 10 个常用 Cron 示例
  • 6 个任务管理操作示例
  • Web 控制台功能说明
  • 5 条最佳实践
  • 5 个常见问题及解决方案

• ✅ 12_Excel.md - Excel 处理（~16,500 行）

  • Excel 提供器对比表格
  • 配置项详解表格
  • 6 个核心接口/模型详解
  • 单 Sheet/多 Sheet 导出示例
  • 基本导入示例
  • Controller 导出/导入完整示例
  • 4 种实体特性配置
  • 6 条最佳实践
  • 前端导出/导入组件示例
  • 5 个常见问题及解决方案

优化特点：

• ✅ 统一文档格式（参考 13_Config.md）
• ✅ 保留原有逻辑说明
• ✅ 优化目录结构展示
• ✅ 补充核心接口详解
• ✅ 添加配置项表格
• ✅ 完善使用示例
• ✅ 添加常见问题 Q&A
• ✅ 添加最佳实践
• ✅ 添加参考链接

统计： 13 个文档，约 159,000+ 行深度内容