mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-14 06:34:30 +08:00
6ab32032bc
- 重命名 local-plan 为 ai-plan，并收口 public 与 private 的目录语义 - 更新 AGENTS、README 与 boot skill 的恢复文档路径和安全约束 - 迁移共享 tracking 与 trace 文件到 ai-plan/public，并补充治理说明文档
68 lines
3.7 KiB
Markdown
68 lines
3.7 KiB
Markdown
# CQRS Cache And Docs Hardening Tracking
|
|
|
|
## Goal
|
|
|
|
Address the current CQRS follow-up issues across runtime caches, tests, and user-facing setup/integration
|
|
documentation so the repository state matches the published onboarding path and the runtime remains safe for
|
|
collectible assemblies.
|
|
|
|
## Current Recovery Point
|
|
|
|
- Recovery point: `CQRS-CACHE-DOCS-HARDENING-RP-001`
|
|
- Current phase: `Phase 2`
|
|
- Active focus:
|
|
- validation completed for the targeted CQRS test project
|
|
- the repository can resume from documentation follow-up or broader solution validation if needed
|
|
|
|
## Planned Work
|
|
|
|
- [x] Create the matching execution trace under `ai-plan/public/traces/`.
|
|
- [x] Update `README.md` quick-install guidance to include CQRS runtime packages.
|
|
- [x] Update the related Chinese setup/integration docs with CQRS runtime + source-generator wiring and a minimal
|
|
working CQRS generator example.
|
|
- [x] Replace static `ConcurrentDictionary<Assembly, ...>` / `ConcurrentDictionary<Type, ...>` CQRS caches with
|
|
weak-key caches that do not permanently root collectible assemblies or handler/message types.
|
|
- [x] Document the weak-cache thread-safety assumptions and recomputation behavior in code comments/XML docs.
|
|
- [x] Expand CQRS tests to assert that cached metadata still results in successful registration in every container.
|
|
- [x] Adapt dispatcher cache tests to the new unload-aware cache structure.
|
|
- [x] Run targeted CQRS test validation and capture the results here and in the trace.
|
|
|
|
## Validation
|
|
|
|
Executed:
|
|
|
|
```bash
|
|
dotnet test GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj -c Release
|
|
dotnet test GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj -c Release --no-restore
|
|
```
|
|
|
|
Results:
|
|
|
|
- `dotnet test ... -c Release`: passed, `62` tests passed.
|
|
- `dotnet test ... -c Release --no-restore`: passed, `62` tests passed.
|
|
- The first run exposed one nullable warning in `GFramework.Cqrs/Internal/WeakKeyCache.cs`; the follow-up fixed the
|
|
`WeakTypePairCache.TryGetValue(...)` null-flow and reran the full CQRS test project cleanly.
|
|
- The CQRS doc update intentionally did not rename handler examples from `GFramework.Cqrs.Cqrs.*` to
|
|
`GFramework.Cqrs.*`, because the current public handler base types still live under the double-`Cqrs` namespace.
|
|
Instead, the docs now explain the split between message namespaces and handler namespaces explicitly.
|
|
- A later follow-up added the missing `using GFramework.Cqrs.Command;` to the handler snippet so that the block can be
|
|
copied independently, documented the private dispatch-binding types in `CqrsDispatcher`, restored the explicit
|
|
`System.Runtime.CompilerServices` import in `WeakKeyCache.cs`, and removed the `WeakTypePairCache.GetOrAdd(...)`
|
|
closure allocation by routing the secondary-key factory through a stateful overload.
|
|
- A final documentation cleanup aligned the `WeakKeyCache<TKey, TValue>.GetOrAdd(...)` XML comments with the runtime
|
|
contract by stating that `valueFactory` must not return `null`.
|
|
|
|
## Known Risks
|
|
|
|
- `ConditionalWeakTable`-based caches trade deterministic retention for unload safety, so the implementation must make
|
|
the recomputation semantics explicit and keep hot-path lookups thread-safe.
|
|
- The source-generator docs already cover multiple generator families; adding CQRS guidance must stay aligned with the
|
|
actual runtime APIs and package split.
|
|
- The existing CQRS docs mix conceptual snippets and minimal examples; changes should improve correctness without
|
|
silently inventing APIs that the current packages do not expose.
|
|
|
|
## Recommended Resume Step
|
|
|
|
1. If broader regression confidence is needed, run solution-level CQRS/Core validation next.
|
|
2. If the public CQRS handler namespaces are flattened in a future refactor, update the docs again in the same change.
|