trait-kit 0.4.2

# 更新日志

本项目所有显著变更将记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
并遵循 [语义化版本](https://semver.org/lang/zh-CN/v2.0.0.html)。

## [Unreleased]

_暂无未发布变更。_

## [0.4.2] - 2026-08-06

### 修复

#### AsyncKit decorator 存储 key 错误
- `AsyncKit::decorate()` 将 decorator 存储在 `TypeId::of::<M>()`（模块 TypeId）下，
  但 `apply_decorators()` 按 `TypeId::of::<M::Capability>()`（能力 TypeId）查找，
  导致 decorator 永远不会被应用，返回未装饰的原始能力。
- 修复：存储 key 改为 `TypeId::of::<M::Capability>()`，与同步 `Kit::decorate()` 对齐。
- 影响范围：所有使用 `AsyncKit::decorate()` 的异步模块。

## [0.4.1] - 2026-08-06

### 新增

#### 国际化增强
- ICU4X 重依赖门控在 `i18n` feature 后，无 feature 时 `tr()` 和 `I18nManager` 仍可用（轻量 FTL 翻译）
- Kit 构造点诊断标记支持翻译键
- `I18nError::Display` 修复

#### 优雅关闭协调器补充
- 关闭协调器 example + 集成测试 + doctest 修复

#### 配置扩展 API 文档
- 补充 `load_and_validate`、`snapshot_config`、`restore_config`、`has_snapshot`、`load_config_with` API 文档
- 补充 `toggle`（`enable_toggle`/`is_toggle_enabled`/`register_if_toggle`）API 文档
- 补充 `Validatable` trait 和 `interpolate_json_value` 函数文档
- 新增 `snapshot_restore`、`toggle_basic`、`validation` example

### 修复

- **安全**: `EncryptedBlob` Debug 实现不再泄露加密材料
- **异步**: `decorate()` 装饰器在 `build()` 中从未生效的问题已修复
- 多项 bug 修复 + 文档示例修复 + 测试门控修正
- CI clippy 与 dead_code 错误修复

### 性能

- `Kit::require()`、`reload_config()`、`transfer_lazy_builders()` 优化
- `find_cycle()` 使用 HashMap 实现 O(1) 栈位置查找

### 重构

- `TraitKitError` 的 context/key 字段改为 `String` 支持翻译文本
- `EncryptedBlob` 字段封装在构造器和 getter 后
- examples 按模块结构重组

### 杂项

- workspace 元数据继承 + `trait-kit` 加入 `workspace.dependencies`

## [0.4.0] - 2026-08-04

### 新增

#### 生命周期管理（feature = "lifecycle"）
- `Lifecycle` trait — 同步生命周期钩子：`on_ready`（构建后）+ `on_shutdown`（清理）
- `AsyncLifecycle` trait — 异步生命周期钩子（需同时启用 `async`）
- `Kit::register_lifecycle::<M>()` / `AsyncKit::register_lifecycle::<M>()`
- `Kit::shutdown()` / `AsyncKit::shutdown()` — 按逆拓扑序执行 `on_shutdown`
- `TraitKitError::LifecycleFailed` 变体

#### 健康检查（feature = "health"）
- `HealthCheck` / `AsyncHealthCheck` trait — 模块运行时状态报告
- `HealthStatus` 枚举（`Healthy` / `Degraded` / `Unhealthy`）
- `Kit::register_health_check::<M>()` / `Kit::health_check::<M>()`

#### 作用域依赖（feature = "scope"）
- `Scope` — 基于 `RefCell` 的轻量级每请求实例隔离容器
- `AsyncScope` — `Send + Sync` 异步作用域（需同时启用 `async`）

#### 条件注册（feature = "conditional"）
- `Kit::register_if::<M>(predicate)` — 运行时谓词控制的模块注册

#### 构建可观测（feature = "observability"）
- `BuildObserver` trait — 构建管线回调（`on_module_start` / `on_module_built` / `on_build_error`）
- `Kit::with_observer(obs)` / `AsyncKit::with_observer(obs)`

#### 工厂模式（feature = "factory"）
- 每次调用创建新实例（非单例）

#### 模块装饰器（feature = "decorator"）
- `Kit::decorate::<M>(f)` — 构建后能力包装/增强

#### 国际化增强
- `I18nManager` + `tr()` — 基于 Fluent FTL 的中英文消息翻译，系统环境自动检测
- `I18nFormatter` — ICU4X 驱动的数字/日期/复数/排序格式化
- `TraitKitError` Display 实现通过 `tr()` 自动本地化输出
- `icu`、`writeable`、`sys-locale` 成为必需依赖（不再通过 feature 门控）

### ⚠️ BREAKING CHANGES

- **TraitKitError 移除 `thiserror` derive** — 不再 `#[derive(Error)]`，改为手动实现 `Display` + `std::error::Error`；`Display` 输出通过 `tr()` 自动本地化
- **TraitKitError::NotReady 变体移除** — 已在 0.2.x 标记 `#[deprecated]`，现正式移除
- **TraitKitError 新增变体** — `MissingConfig`（无条件）和 `LifecycleFailed`（需 `feature = "lifecycle"`）；现有 `match` 需补充分支
- **`impl_module_meta!` 依赖名生成逻辑变更** — 从 `stringify!($dep)` 改为 `<$dep as ModuleMeta>::NAME`，依赖解析名称可能与之前不同
- **`Kit::load_config_or_default` 返回类型变更** — `Result<(), TraitKitError>` → `Result<bool, TraitKitError>`（`true` 表示加载成功，`false` 表示使用默认值）
- **i18n 变为必选依赖** — `icu`、`writeable`、`sys-locale` 不再通过 feature 门控，所有用户均编译 i18n 模块；`i18n` feature flag 移除
- **`ModuleMeta::dependencies()` 新增默认实现** — 默认返回 `&[]`，无依赖模块不再需要手动实现
- **`TraitKitResult<T>` 正式导出** — 移除 `#[allow(dead_code)]`，通过 `lib.rs` 公开 re-export

### 变更

- `examples/integration-app` 重命名为 `examples/trait-kit-example`（独立 workspace 成员）
- `kit.set_config()` 现在可在 `Kit<Unbuilt>` 和 `Kit<Ready>` 上调用
- 错误模块路径 `src/core/error.rs` → `src/error.rs`

### 依赖

- `confers` 0.4 → 0.5（传递依赖升级：notify 7→8、hkdf 0.12→0.13、sha2 0.10→0.11 等）
- `serial_test` 3 → 4.0（dev-dependency）
- 统一依赖版本写法为 `x.x` 格式（serde/serde_json/thiserror/trybuild/static_assertions）

### 构建

- 新增 `[workspace.dependencies]` 集中管理 `confers` 和 `serde`，examples crate 通过 `workspace = true` 继承

## [0.3.1] - 2026-07-22

### 修复

- `kit.rs` 重构：裸指针转型改为 `.cast::<Kit>()`（更安全），`require_all` 消费所有权避免迭代器复用错误

### CI / 依赖

- 新增跨平台 CI 矩阵（ubuntu/macos/windows）
- 修复 `cargo fmt` + `clippy` 在 main 的失败
- 解决 `integration-app` 与 dbnexus `default=[]` 的兼容性
- 移除 `examples/integration-app`（仅本地依赖 sibling path crate，不发布）
- 依赖 bump：github/codeql-action 3→4、actions/checkout 4.2.2→7.0.0、trybuild 1.0.117→1.0.118

### 测试

- 新增 `tests/e2e_advanced.rs`（78 个测试）：覆盖 B01/B03/B04/B06/B07/B09/B11/B12/B13、A01-A08/A25、E03/E05/E06/E08/E11/E19/E26、C01-C04/C06-C08/C10/C11/C13/C22/C23、A09-A12/A26/E23-E25/C19、A19/A20/E07/E27、I01-I19/E20-E22/C20/C21、C14/C15/E15/E17 等场景，补全现有测试套件的覆盖盲区

## [0.3.0] - 2026-07-13

### 新增

#### Phase 1: Override + require_ref
- `Kit::override_module<M>()` — 用预构建值覆盖模块能力，跳过 build_fn（测试注入）
- `Kit::override_module_strict<M>()` — 覆盖但验证依赖存在性
- `Kit::require_ref<M>()` — 零拷贝能力检索，返回 `Ref<'_, M::Capability>`
- `TypeMap::inner_ref()` — 暴露内部 HashMap 借用

#### Phase 2: Lazy + 多绑定
- `Kit::register_lazy<M>()` — 延迟构造，首次 `require()` 时触发构建并缓存
- `Kit::register_multi<M>()` — 多绑定注册，相同能力类型聚合为 Vec
- `Kit::require_all<M>()` — 按注册顺序返回所有多绑定能力

#### Phase 3: 接口分离（feature = "interface"）
- `Interface` marker trait — 支持 `dyn Trait` 类型擦除（`?Sized` blanket impl）
- `InterfaceBuilder` 扩展 trait — 关联 `Capability` 与 `Interface`，通过 `into_interface` 执行类型擦除
- `Kit::register_as<M>()` — 按接口类型注册，`M::Interface` 作为 key
- `Kit::resolve<I>()` — 按接口类型检索 `Arc<I>`

#### Phase 4: 宏扩展
- `impl_module_meta!` 宏 — 生成 `ModuleMeta` impl（无依赖 / 有依赖两种语法）
- `impl_async_auto_builder!` 宏（feature = "async"）— 生成 `AsyncAutoBuilder` impl

#### 跨平台与集成
- 跨平台 CI 矩阵（ubuntu/macos/windows）验证 apple/windows/linux 平台兼容性
- `examples/integration-app`：dbnexus default=[] 后显式启用 default-no-db + sqlite + kit
- `examples/integration-app`：新增 [patch.crates-io] 解决 trait-kit 版本冲突
- `examples/integration-app`：governor 改为 re-export `limiteron::Governor`（修复私有模块访问）

### 变更

- MSRV 从 1.85 提升至 1.91
- clippy/fmt 修复
- `build()` 方法优先检查 overrides map，跳过 build_fn
- `build()` 新增 lazy_slots / multi_capabilities / interface_builders 构建循环
- `build()` 中 topo-sorted 循环对 multi-binding 和 interface 模块 `continue`（与单绑定模式一致）
- 移除 trait-kit 对下游 crate（oxcache/dbnexus/limiteron/sdforge/inklog）的 dev-dependencies 循环依赖；e2e 测试由 `examples/integration-app` 承担

## [0.2.5] - 2026-07-12

### ⚠️ BREAKING CHANGES

- `KitError` 重命名为 `TraitKitError`，遵循 `ProjectNameError` 命名约定
- 新增 `TraitKitResult<T>` 类型别名
- `error` 模块从 `src/core/error.rs` 迁移到 `src/error.rs`，导入路径 `crate::core::error::KitError` → `crate::error::TraitKitError`

## [0.2.4] - 2026-07-11

### 变更

- 无代码变更，版本号对齐 workspace 同步升级

### 变更（Phase 6 前置）

- 升级至 Rust edition 2024
- 最低支持 Rust 版本 (MSRV) 设为 1.85
- 统一采用 MIT 许可证

### 新增

- `i18n` feature：集成 ICU4X，提供区域感知的数字、日期、复数和排序能力
- `async` feature：`AsyncKit` 支持 `Send + Sync` 异步能力管理

## [0.2.3]

### 新增

- `ModuleConfig` trait：模块级配置元数据（PATH + default_value）
- 四级 confers feature flag 体系（confers / confers-macros / hot-reload / encryption）
- XChaCha20-Poly1305 加密配置存储（HKDF 密钥派生）
- 热重载订阅 API（subscribe / reload_config）

### 变更

- `Kit` 采用 typestate 模式（`Kit<Unbuilt>` → `Kit<Ready>`）
- 能力检索改为按模块类型（TypeId），移除字符串键查找

## [0.2.2]

### 新增

- `ModuleMeta` + `AutoBuilder` 标准模块接口
- `Kit` 能力与配置管理中心
- `TypeMap` 类型安全存储（以 `TypeId` 为键）
- 依赖图验证：环检测 + 拓扑排序构建

[Unreleased]: https://github.com/Kirky-X/trait-kit/compare/v0.4.1...HEAD
[0.4.1]: https://github.com/Kirky-X/trait-kit/compare/v0.4.0...v0.4.1
[0.4.0]: https://github.com/Kirky-X/trait-kit/compare/v0.3.1...v0.4.0
[0.3.1]: https://github.com/Kirky-X/trait-kit/compare/v0.3.0...v0.3.1
[0.3.0]: https://github.com/Kirky-X/trait-kit/compare/v0.2.5...v0.3.0
[0.2.5]: https://github.com/Kirky-X/trait-kit/compare/v0.2.4...v0.2.5
[0.2.4]: https://github.com/Kirky-X/trait-kit/compare/v0.2.3...v0.2.4
[0.2.3]: https://github.com/Kirky-X/trait-kit/releases/tag/v0.2.3
[0.2.2]: https://github.com/Kirky-X/trait-kit/releases/tag/v0.2.2