TKWF.Ext.Analytics 0.1.1

TKWF.Extensions

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

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

架构图

扩展仓架构图总览（archify 生成，自包含 HTML，可直接双击打开）：.archify/index.html

主框架（_TKWF / TKW.Framework）自己的架构图在主仓 .archify/index.html，由主框架维护。

扩展模块一览

各扩展模块使用说明

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

版本口径（2026-10-26 固化）：本表"版本"列 = 已发布 tag（git tag 按包名前缀 {Package}/vX.Y.Z 取最新，权威源）；打 tag 后须同步本表 + _Framework/{扩展名}/README.md + docs/变更记录.md。机器可读清单：docs/versions.json（build/gen-versions.ps1 从 git tag 生成，55 包 + 公共 v tag）；功能线领先行用双值写法（如 AuthCenter V0.12.0（功能线）／已发布 v0.10.1）。发布检查清单见 docs/目录结构与版本管理规则.md §3.2/§3.3。

受影响面定向（2026-10-25——AuthCenter V0.12.0 端点契约化 B3a/B3b，L1）：AuthCenter 198 用例全绿（181→198：+17——errorCode 存活断言 1 + DeclareEndpoints 门控锁定 2 + 既有适配 14）+ Federation 119 全绿 + WeChatOperations 143 全绿；双模式复验（DLL refs + NuGet 正式 4.10.84）slnx 构建 0 错误；框架 Domain.SG 297 + ApiService.SG 121 全绿；扩展 CI 40118994339 success；全量回归待发布前 L2。 受影响面定向（2026-10-20——Iteration 2 渠道关注关系域，L1）：Federation 114 用例全绿（79→114：+35 关注域实体/门面/编排记录在后/域事件/免登入口）+ Federation.WeChat 110 全绿（100→110：+10 EventType 归一/wechat. 前缀 Attributes/IFollowChannelQuery 反查/Capabilities 声明/{ticket} 免登）+ WeChatOperations 143 全绿（+2 派生改造适配——删 SubscriptionStatEntity 委托关注域）；slnx 构建 0 错误（L0 编译门）；全量回归待发布前 L2。 受影响面定向（2026-10-19——AuthCenter V0.10.0 票据 SPA 兑现迭代，L1）：AuthCenter 177 用例全绿（146→177：+31——FederatedLoginOrchestratorTests 8 + ExternalTicketLoginServiceTests 9 + 端点冒烟 5 + 配置断言 2 + 既有适配 7）+ Federation 79 全绿（事件链签票→兑现闭环关联方）；slnx 构建 0 错误（L0 编译门）；全量回归待发布前 L2。 全量 2343 测试全绿（43 测试项目 / 0 失败 0 跳过）——2026-10-27 CPM lockstep 4.10.85→4.10.87 双模式复验：NuGet 模式（-p:UseLocalFw=false，13 包全解析 4.10.87）执行 L2 全量回归 + DLL 模式（refs 4.10.88-preview）slnx 构建 0 错误；历史基线演进链（2019→2098→2195→2206→2220→2233→2343）见 docs/变更记录.md。

仓库定位

目录结构

_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/                  # 对外连接层（外交部——2026-10-09 三层化：TrustCenter 剥离后连接层壳，/feberation/* 端点 + 编排 + 桥接 + 多通道设施）
│   ├── Federation.Abstractions/     # 联邦通道编排契约包（IChannelRegistry/IChannelSource/ChannelConfig/IEventReplyHandler/IEventOrchestrator——V0.1.0 ④ 裁定收口，TKWF.Federation.Abstractions）
│   ├── TrustCenter.Abstractions/    # 信任契约包（ISsoChannel/IToken2Service/IAuthorizationCodeService——信任内核契约；面① ISealedTicketService<T> 在主框架 Domain.Ticket，零实体零 SG1）
│   ├── TrustCenter/                 # 信任中心（应用间信任中枢——2026-10-09 自 Federation 剥离，纯信任内核：应用注册/token2/accesscode/ISsoChannel 契约定义）
│   ├── Federation.WeChat/           # 微信公众平台连接器（大使馆/平台网关库——纯库无装配，TKWF.Federation.WeChat）
│   ├── Federation.WeChat.MessageGateway/  # 微信消息网关核心判定运行库（纯逻辑零实体零持久化零 DI——路由判定/幂等键/转发决策/熔断状态机，TKWF.Federation.WeChat.MessageGateway）
│   ├── WeChatOperations/            # 微信公众号运营（实体型——8 实体 + 6 门面 + 事件回复 handler + 生成端点（V0.4.0 `[GenerateController]`），TKWF.Ext.WeChatOperations）
│   ├── Federation.QQ/               # QQ 互联连接器（大使馆/平台网关库——出站-only，TKWF.Federation.QQ）
│   ├── Federation.Alipay/           # 支付宝开放平台连接器（大使馆/平台网关库——出站-only + RSA2 双向签名，TKWF.Federation.Alipay）
│   └── 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.TrustCenter.Tests/
│   ├── Extension.Federation.WeChat.Tests/
│   ├── Extension.Federation.WeChat.MessageGateway.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
│   ├── TrustCenter/信任中心-使用指南.md          # 信任中心（应用间信任中枢——token2/accesscode/应用注册/安全数据投递）
│   └── 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 纪律：必须有开发方案 + 审核报告，且征得用户同意

版本一览表口径（2026-10-26 固化，转达登记）：
- 发布事实源 = git tag（{Package}/vX.Y.Z 前缀，按包取最新）；本表"版本"列填已发布 tag 版本
- 打 tag 后必须同步本表（+ _Framework/{扩展名}/README.md + docs/变更记录.md），防止展示层滞后
- 功能线领先于已发布 → 双值写法：Vx.y.z（功能线）／已发布 vA.B.C（实例：AuthCenter V0.12.0（功能线）／已发布 v0.10.1）
- 发布检查清单与详细约定见 docs/目录结构与版本管理规则.md §3.2/§3.3

扩展规划

• 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 幂等）。
• ✅ TKWF.Ext.Federation 主包已废弃并全量 unlist（2026-10-10）——10 版本（0.2.1-preview.0.12 ~ 0.5.0，含连接层壳版）已 unlist（nuget.org 搜索不可见、flatcontainer 保留兼容既有引用）；消费方改引 TKWF.Ext.TrustCenter 新线 + 8 平台库 TKWF.Federation.{平台}（保留不 unlist，2026-10-10 已发 v0.2.2 ×7 + Alipay v0.1.1）。
• ✅ TKWF.Ext.TrustCenter V0.1.0 已发布（2026-10-10：框架组 v4.10.70 并入 SymmetricKeyProviderKeys.TrustCenter（C11 第 5 扩展边界）→ CPM 4.10.70 lockstep + 删过渡类 + 切主框架常量 → 全量 1913 用例 0 失败；TrustCenter/Abstractions/Federation v0.5.0/AuthCenter v0.9.2 四 tag + 8 平台库 tag 已发布 + CI 全绿 + nuget.org 实证上架）。
• ✅ V0.4.0 设计缺口修复 + ④ 契约包联动发布（2026-10-18，12 tag 全绿）——WeChatOperations/v0.4.0（①②③ 设计缺口修复：客户端 DTO 生成链路根治 + 网关 REST 端点 + 总开关 DB 化）+ Federation.Abstractions/v0.1.0（④ 新契约包首发——通道编排契约收口独立包）+ Federation/v0.10.0（契约迁出后主包新版本）+ 8 平台库新版本（Federation.WeChat v0.5.0 / QQ v0.4.0 / DingTalk v0.4.0 / WeCom v0.4.0 / Oidc v0.3.0 / Google v0.3.0 / Microsoft v0.3.0 / Alipay v0.3.0——依赖拓扑切 Abstractions）；逐个 tag push（多 tag 单命令会丢事件先例）→ 12 个 CI run 全部 success（含新契约包 Abstractions publish）。
• ✅ v4.10.76 HttpAuth 匿名端点排除机制收入（2026-10-15，ADR108）——主框架 v4.10.76（HttpAuthenticationMiddleware 锚点后移 AfterRouting 读端点 IAllowAnonymous 元数据——扩展声明 AllowAnonymous 即自动放行，消费方零配置；SG1b 生成器 AllowAnonymous=true → .AllowAnonymous() + 接口级 fallback）+ 扩展侧 CPM lockstep 4.10.76（12 包）+ 各 Web 扩展匿名端点自查零适配；消费方旧版手动 HttpAuth.ExcludedPathPrefixes.Add("/feberation") 冗余（保留无害）；详见 docs/HttpAuth匿名端点排除机制-开发方案.md。
• ✅ Federation 系列持续发布（2026-10-21~27，Iteration 2 关注域 + 微信测试反馈增强）——Federation/v0.11.0~v0.15.0（I2 渠道关注关系域 + 复查修复 + 审核 P1/P2 + 测试端点 HTML 化）+ Federation.Abstractions/v0.2.0~v0.5.0（I2 契约收口 + 联动 bump）+ Federation.WeChat/v0.6.0~v0.16.1（明文模式 + 图文模板解析链 4 级 + 免登链接基址 + {text} 占位符动态化）+ WeChatOperations/v0.5.0~v0.6.1（I2-10 订阅统计派生改造 + 事件回复排他单模型）+ Federation.WeChat.MessageGateway/v0.1.1；当前 55 包最新发布版本见 docs/versions.json（build/gen-versions.ps1 生成）。

设计思路与 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 — 文档体系脚手架来源