用途：实现 Forze 的文档持久化、过滤列表、游标分页、文本搜索、hub 搜索与联邦搜索。通常与 forze-domain-aggregates（聚合模型）和 forze-specs-infrastructure（把 spec.name 映射到表与索引）配合使用。
主要能力： 文档端口：内核 DocumentSpec 只承载模型类型与逻辑名，PostgresDepsModule / MongoDepsModule 提供表、历史关系与记账。运行时 ctx.doc_query(spec) 解析 DocumentQueryDepKey 注册的工厂，返回 DocumentQueryPort[read]；ctx.doc_command(spec) 同理返回 DocumentCommandPort。
doc_q = self.ctx.doc_query(project_spec) doc_c = self.ctx.doc_command(project_spec)
project = await doc_q.get(project_id) page = await doc_q.find_page(filters={"$fields": {"status": "active"}}, pagination={"limit": 20, "offset": 0}, sorts={"created_at": "desc", "id": "asc"}) rows, total = page.hits, page.count updated = await doc_c.update(project_id, project.rev, UpdateProjectCmd(title="Done"))
带修订号的写入会强制乐观并发；用 project / project_many 做部分读取；更新不需返回新模型时用 return_new=False。
查询 DSL：应用代码使用共享 JSON DSL，而非适配器专属 SQL/Mongo 语法。常见操作符：$eq、$neq、$gt、$gte、$lt、$lte、$in、$nin、$null、$empty、$superset、$subset、$overlaps、$disjoint。
缓存感知文档：把 CacheSpec 挂到 DocumentSpec.cache 并注册匹配缓存路由（通常在 RedisDepsModule.caches）。接入 AfterCommitPort 后，缓存预热/失效在提交成功后进行。
搜索：用 SearchSpec 描述可搜索模型，ctx.search_query(spec) 解析 SearchQueryDepKey 返回 SearchQueryPort；物理 FTS/PGroonga 布局放在 PostgresDepsModule.searches（或 hub/联邦映射）中，不放在 spec 上。
Hub 与联邦搜索：一个 hub 实体跨加权成员腿搜索用 HubSearchSpec；合并独立搜索 spec 用 FederatedSearchSpec，通过 ctx.hub_search_query(spec) 或 ctx.federated_search_query(spec) 解析。快照存储与游标/keyset 行为保留在基础设施配置中。
适配器边界：Postgres 与 Mongo 在配置处实现文档查询/命令网关与历史；Mock 为单元测试实现文档/搜索行为；适配器用于集成测试或 deps 模块，不用于 usecase。
限制与反模式：不要把表/集合/索引名放进 DocumentSpec 或 SearchSpec；不要在 usecase 导入 Postgres/Mongo 适配器；不要用旧的 ctx.doc_read / ctx.doc_write / ctx.search；游标分页要含确定性排序键（通常为 id）；写入不要绕过修订字段。参考资料位于 pages/docs 下相关文档与 src/forze/application/contracts/search。