TKWF.Ext.Settings 0.3.1

TKWF.Extensions

TKWF 扩展模块仓库——权限、导航、身份、审计、设置、邮件、存储、账户、数据字典等。

扩展模块与主框架 TKW.Framework 解耦：扩展代码、测试、使用指南独立演进，不进入主框架 TKW.Framework.slnx。

扩展模块一览

各扩展模块使用说明

列说明：README = 扩展技术规范（随 NuGet 发布，位于 _Framework/{扩展名}/）；指南 = 使用指南（公开文档，位于 docs/{扩展名}/）。Permissions.Abstractions/Validation、SecurityLog.Abstractions、Account.Abstractions、Navigation.Abstractions、UserCenter.Abstractions 无独立文档，详见对应主扩展的 README 与指南。

全量 1841 测试全绿（40 测试项目——含 Federation.QQ V0.1.0（N3，16 用例：QqOauthChannel 生产路径正负 + QqApiClient 直构单测 + redirect_uri 一致性契约（P1-4）+ unionid 开关（P1-2）+ 协议结构断言 fmt=json/JSONP 剥壳/ret-msg 模型——tkwf-extension 铁律落地实证） + V0.8.0 认证 API 补全（AuthCenter V0.8.0 124——/verify /grants /sms/verify 三端点冒烟 6 + 配置断言 2 + AuthGrantCommandServiceTests 4 + BindTicketAsync 全矩阵 6，103→124 零回归） + E4 密钥管理抽象（框架 v4.10.61 配套，三扩展：AuthCenter V0.7.0 103 / Federation V0.2.0 23 / MFA V0.2.0 65——删 5 静态密钥类 → 框架 keyed ISymmetricKeyProvider + DevKeyCache，加密边界上移服务层，格式统一单段） + Identity/Notifications REST 直接暴露 8 用例 + v4.10.39 聚合 SQL 下推 3 用例 + 04 方案 OU/DataDictionary VEntity 下推 N1-N6 用例 + FileManagement v0.3.0 并发上传竞态加固用例（并发同名不同内容双成功） + v4.10.45 Web 装配钩子收敛迁移（4 先例 → IWebExtension + JwtAuth TestServer 黑盒哨兵冒烟——顺序串 ContextExtraction→JwtAuth验签→HttpAuthentication 锁定锚点分桶 P0-1） + v4.10.46 lockstep（BUG005 纯修复复验） + v4.10.53 领域自治根治（ADR90——批次 0-7 门面化整改 + 注册形态断言 + 测试宿主生产路径 + 批次间交互遗留修复 ab5f5ee） + v4.10.55 多实现集合守卫工厂（ADR92/T3 闭环——4 扩展 TryAddEnumerableConstructible 迁移：Authentication 登录编排门面 3 用例 + Provider 守卫形态断言 / FeatureManagement 4 Provider 守卫形态 / MFA 2 Method / Notifications InboxNotifier；BackgroundJobs JobExecutionRecorder 泛型化） + Authentication V0.6.0 SSO 消费面契约（5 用例：ISsoAccountQueryService DTO 返回/联邦映射 upsert/联盟锚点列唯一） + Federation V0.1.0（19 用例：token2 ES256 签发验签负路径轮转/JWKS + accesscode 原子 CAS 重放/PKCE + client 注册校验/origin 白名单 + 生产路径全链跨扩展；2026-10-05 归层：SSO→Federation 命名归层） + Federation.WeChat V0.1.0（18 用例：WeChatOauthChannel 正负 + 事件签名信任根正负 + AES 解密 + 探针门面生产路径枚举——tkwf-extension 铁律落地实证））——dotnet test 零失败。（Approval v0.2.0 + FeatureManagement v0.3.0 + FileManagement v0.2.0 + Calendar + OrganizationUnit + 三件套基础设施 + BlobStoring 安全修复 + Tagging v0.4.0 + HealthCheck v0.2.0 + Notifications v0.2.0 多通道路由 + AuditLogging v0.3.0/v0.4.0 统计聚合与管理 API + Permissions v0.9.0 多用户批量权限检查 + Notifications v0.3.0 偏好路由与权限门控 + Notifications v0.4.0 SignalR 通道（12 用例，独立包） + Metrics v0.2.0 指标结果持久化（15 用例：Mapper 6 + Store 9） + SecurityLog v0.3.0/Account v0.4.0 契约拆包回归 + Authentication v0.2.0 查询契约 + UserCenter v0.1.0 档案面 + Identity v0.4.0/Notifications v0.5.0 VEntity REST 直接暴露（8 用例） + v4.10.39 聚合 SQL 下推（AuditLogging v0.4.2/SecurityLog v0.3.1/Tagging v0.4.3——GroupCountAsync/GroupByAsync 下推 + 空白键 SQL 过滤，3 用例） 后）

仓库定位

目录结构

_TKWF.Extensions/
├── _Framework/                     # 扩展源码（每个扩展一个项目）
│   ├── Permissions/                 # 权限扩展（V0.7.0：定义/检查/存储/管理 API/Admin.All）
│   ├── Permissions.Abstractions/    # 权限契约抽象（ADR48 D7 依赖倒置）
│   ├── Permissions.Validation/       # PERM001 编译期校验 Analyzer（V0.8.0，扩展侧）
│   ├── Identity/                     # 用户 + 角色 + 用户角色分配 + 凭据验证
│   ├── Account/                      # 账户锁定 + 密码重置流程（主框架缺口补齐）
│   ├── Navigation/                  # 菜单数据模型 + 贡献机制 + 权限过滤
│   ├── AuditLogging/                # 审计日志 FreeSql 存储
│   ├── Settings/                    # 设置管理 FreeSql 存储 + 分层读取
│   ├── BlobStoring/                 # 二进制存储（本地文件系统 + FreeSql 记录）
│   ├── Emailing/                    # SMTP/MailKit 邮件发送（V0.2.0：指数退避重试）
│   ├── Emailing.Abstractions/       # 邮件发送契约（IEmailSender——ADR48 D7 依赖倒置）
│   ├── DataDictionary/              # 数据字典集中管理
│   ├── Tagging/                     # 标签存储扩展（算法已回归 TKW.Framework.Utility.Tags）
│   ├── Notifications/              # 通知中心（发布/收件箱/订阅 + 多通道路由 + 偏好路由/权限门控）
│   ├── Notifications.SignalR/      # 通知中心 SignalR 实时推送通道（v0.4.0 独立包，服务端非 UI）
│   ├── BackgroundJobs/              # 后台任务持久化增强（执行历史 + 业务结果追踪）
│   ├── BackgroundJobs.Quartz/       # Quartz AdoJobStore 一键封装
│   ├── HealthCheck/                 # 系统健康探测（/health 端点接线 + 内置 DB 探针 v0.2.0）
│   ├── RateLimiting/                # Web 层限流接线（IP/用户分区 + 429）
│   ├── SecurityLog/                 # 安全日志（登录/改密/锁定等安全事件）
│   ├── Approval/                    # 轻量审批引擎（流程定义/实例/任务 + 状态机）
│   ├── OrganizationUnit/            # 组织单元（树形部门/团队/分组 + 用户归属）
│   ├── Calendar/                    # 日历/排程（日历+事件 + 重复规则子集）
│   ├── BlobStoring.Abstractions/    # Blob 存储契约（IBlobStorageService——ADR50 L2 依赖倒置）
│   ├── FileManagement/              # 文件管理（目录树 + 文件元数据 + 版本化/配额 + 上传安全链）
│   ├── Federation/                  # 联邦互联（外交部——认证中心对外身份接口，归层后命名，原 SSO）
│   ├── Federation.WeChat/           # 微信公众平台连接器（大使馆/平台网关库——纯库无装配，TKWF.Federation.WeChat）
│   ├── Federation.QQ/               # QQ 互联连接器（大使馆/平台网关库——出站-only，TKWF.Federation.QQ）
│   └── FeatureManagement/           # 功能管理（特性开关——定义收集 + 分层值 + IFeatureChecker）
├── _Tests/                          # 测试（一组扩展一个测试项目）
│   ├── Extension.Permissions.Tests/
│   ├── Extension.Permissions.Consumer/    # 消费方集成验证
│   ├── Extension.Permissions.Validation.Tests/  # Analyzer 单测
│   ├── Extension.Identity.Tests/
│   ├── Extension.Account.Tests/
│   ├── Extension.Navigation.Tests/
│   ├── Extension.AuditLogging.Tests/
│   ├── Extension.Settings.Tests/
│   ├── Extension.BlobStoring.Tests/
│   ├── Extension.Emailing.Tests/
│   ├── Extension.DataDictionary.Tests/
│   ├── Extension.Tagging.Tests/
│   ├── Extension.OrganizationUnit.Tests/
│   ├── Extension.Calendar.Tests/
│   ├── Extension.FileManagement.Tests/
│   ├── Extension.Federation.Tests/
│   ├── Extension.Federation.WeChat.Tests/
│   ├── Extension.Federation.QQ.Tests/
│   └── Extension.FeatureManagement.Tests/
├── docs/                           # 公开使用指南（每个扩展一份）
│   ├── Permissions/权限扩展-使用指南.md
│   ├── Identity/身份管理扩展-使用指南.md
│   ├── Account/账户管理扩展-使用指南.md
│   ├── Navigation/导航扩展-使用指南.md
│   ├── AuditLogging/审计日志扩展-使用指南.md
│   ├── Settings/设置管理扩展-使用指南.md
│   ├── BlobStoring/二进制存储扩展-使用指南.md
│   ├── Emailing/邮件发送扩展-使用指南.md
│   ├── DataDictionary/数据字典扩展-使用指南.md
│   ├── Tagging/标签服务扩展-使用指南.md
│   ├── OrganizationUnit/组织单元扩展-使用指南.md
│   ├── Calendar/日历排程扩展-使用指南.md
│   ├── FileManagement/文件管理扩展-使用指南.md
│   └── FeatureManagement/功能管理扩展-使用指南.md
├── Directory.Build.props           # TKWFSourceRoot + MinVer + 打包属性
├── Directory.Packages.props         # CPM 集中包版本
├── AGENTS.md                        # 扩展仓库开发规则（AI Agent 与人工开发者必读）
└── TKWF.Extensions.slnx            # 扩展解决方案

扩展设计文档（开发方案/ADR/设计思路）+ 使用指南存放于本公开仓库 docs/（2026-09-15 裁定后新方案落公开仓库；历史方案/审核报告/总览跟踪在主框架私有仓库 _TKWF/docs/03_扩展模块/，渐进迁移）。

架构模式

所有扩展遵循统一架构模式（异常静默 + TryAddScoped + SG1 声明式实体）：

扩展项目（net10.0）
├── Entity（partial class + [Table] + [DomainGenerateCode] + FreeSql [Column]）
├── Store 抽象 + FreeSql 实现（internal sealed + 异常静默）
├── Manager 门面（internal sealed + 聚合查询）
├── ExtensionInitializer（[TKWFExtension] + TryAddScoped 三钩子）
└── README.md（技术规范）

测试项目（xunit.v3 + FreeSql SQLite 内存）
├── ConsumerHostInitializer（[TKWFEnabledExtension] 白名单样板）
└── 测试类（Store CRUD + Manager 聚合 + Initializer DI + 异常静默）

测试事务约定：SQLite 物理事务边界 + Noop 事务限制 + PG 测试容器评估见 docs/测试约定-SQLite物理事务与Noop限制.md（2026-10-02，转达登记落地）。

扩展启用（v4.9.85+ 必需）

扩展不再"发现即启用"——消费方须在领域初始化器上显式声明白名单：

using TKWF.Ext.Identity;

[TKWFEnabledExtension(typeof(IdentityExtensionInitializer<>))]
public class MyDomainInitializer : DomainHostInitializerBase<MyUserInfo> { ... }

声明后扩展三钩子（ConfigureServices/ConfigureFilters/InitializeAsync）自动接线。

依赖倒置（ADR48 D7）

扩展间依赖走 .Abstractions（接口/契约），不引用实现项目——L2 门控硬约束（TKWF0022 Error）。

Navigation → Permissions.Abstractions（✅ 合法）
Navigation → Permissions（❌ TKWF0022 Error）

快速开始

消费方引用扩展

NuGet 包模式（消费方推荐——扩展已发布 TKWF.Ext.* NuGet 包）：

<PackageReference Include="TKWF.Ext.Identity" Version="0.3.3" />

源码模式（本仓库开发/联调主框架新 API 时）：

<ProjectReference Include="..\_TKWF.Extensions\_Framework\Identity\TKWF.Ext.Identity.csproj" />

双模式并存：扩展自身构建用 PackageReference（主框架包）；需调试主框架源码新 API 时可临时切源码引用——消费方视角与 NuGet 模式一致。

启用 + 使用

// 1. 白名单声明（v4.9.85+）
[TKWFEnabledExtension(typeof(IdentityExtensionInitializer<>))]
public class MyDomainInitializer : DomainHostInitializerBase<MyUserInfo> { ... }

// 2. 注入 + 使用
public class AuthService(IUserManager userManager)
{
    public async Task<UserEntity?> LoginAsync(string name, string password)
        => await userManager.VerifyCredentialsAsync(name, password);
}

版本管理

MinVer：各扩展包独立版本（git tag 命名空间前缀 + csproj MinVerTagPrefix 对齐，如 Identity/v0.3.2 → 0.3.2）
公共内容（构建基建/无扩展归属）：无前缀 v tag（如 v0.8.2）

机制：
- 每个扩展 csproj 设 <MinVerTagPrefix>{扩展名}/v</MinVerTagPrefix>——MinVer 只匹配该扩展自己的前缀 tag，
  各扩展版本完全独立（Permissions 0.9.x 与 Identity 0.3.x 互不影响）
- 扩展 tag 命名：{扩展名}/v{major}.{minor}.{patch}（如 Permissions/v0.9.0、Notifications/v0.3.0）
- 公共内容（Directory.Build.props/构建脚本等无扩展归属的变更）：打无前缀 v tag（既有 v0.1.0~v0.8.2）
- 契约包（*.Abstractions）独立 tag：Account.Abstractions/v0.1.0 等，版本与主扩展独立演进
- 与主框架 _TKWF 版本完全独立
Tag 纪律：必须有开发方案 + 审核报告，且征得用户同意

扩展规划

• P0（必须）：11/11 全部完成 ✅——Identity / Account / Navigation / AuditLogging / Settings / BlobStoring / Emailing / DataDictionary / Tagging / PrintTemplates + Permissions（V0.9.0）。注：Tagging 标签算法已按 ADR52 回归主框架 TKW.Framework.Utility.Tags，扩展保留存储层。
• P1（推荐）：20 扩展已实施（后台任务/功能管理/通知+SignalR/限流/健康检查/安全日志/组织单元/文件管理/审批/导入导出/日历/仪表盘/打印模板/指标/标签存储/数据字典/用户中心/多因素认证/分析服务）；剩余 14 项按需推进（OpenIddict/SSO/LDAP/后台服务/安全防护/媒体库/搜索/动态表单/动态字段/工作流/文本模板/报表/文档管理/ApiDocs）。
• P2（待定）：20 项全部按需启用（CMS/支付/订阅/聊天/GraphQL/可观测性/数据分析BI 等）。

NuGet 发布（2026-09-15 + 2026-10-06 增量）

• 30 包已发布 nuget.org（TKWF.Ext.*，v0.1.x–v0.9.x，依赖主框架稳定包 4.10.24）——经 GitHub Actions + Trusted Publishing（OIDC 免 API key：NuGet/login@v1 + nuget.org policy + NUGET_USER secret）自动发布，CI run 34897984278 30/30 pushed 确认。
• 2026-10-06 增量发布（run 37439864527 + 37445400545 全绿，AuthCenter/v0.8.0 tag 移绿树 3038d40 触发）：AuthCenter 0.8.0（stable）已上架 + AuthCenter.Abstractions 0.1.1-preview.0.19 / Federation 0.2.1-preview.0.12 首发 + 全部已发布扩展新 preview（--skip-duplicate 幂等 no-op）。
• ✅ TKWF.Federation.* 平台库（7 个）已全部发布（run 37445400545，0.1.1-preview.0.1——WeChat/DingTalk/Oidc/Google/Microsoft/WeCom/QQ；QQ 骨架 preview 首发，协议在 N3 V0.1.0 稳定版落地后将覆盖）。⚠️ 阻塞曾因 nuget.org Trusted Publishing 策略仅覆盖 TKWF.Ext.* 前缀（403 Forbidden）——用户已更新策略为 TKW.* + TKWF.* 全局前缀，权限更新后重触发补齐。Permissions.Validation（Analyzer）IsPackable=false 不发布。
• 后续版本发布：各扩展打 {扩展名}/v{x.y.z} tag（patch bump 指向目标 commit）→ push tag 即触发 CI 全量重建 + 发布（--skip-duplicate 幂等）。

设计思路与 ABP 兼容策略（最优设计为默认、兼容 ABP 为特殊需求、碰巧兼容只记录）+ 各扩展设计分类见 docs/扩展模块设计思路与ABP兼容策略.md；状态跟踪见主框架私有 _TKWF/docs/03_扩展模块/总览和跟踪.md。

许可证

Copyright © 2026 LoongBa · Apache-2.0

开源、允许商用与闭源衍生，但必须保留版权与归属声明（Attribution）。

相关仓库

• TKW.Framework（主框架） — 领域框架 + 扩展机制（TKWFExtensionAttribute + ExtensionInitializer 三钩子 + SG1 发现 + [TKWFEnabledExtension] 白名单启用 + 三层门控 ADR50）
• LoongBa-Scaffold — 文档体系脚手架来源