快照查询

查询模型

SnapshotQueryService<S> 查询 MaterializedSnapshot<S>：它包含 aggregateId、tenantId、ownerId、spaceId、version、事件时间、deleted 等系统字段，以及当前业务状态 state。快照适合读取聚合的当前状态，不是完整事件历史；公共请求形态见数据查询。

字段路径

业务字段从 state 开始，例如 state.status、state.total。Kotlin DSL 的 pathState { ... } 是该根路径的简写：

import me.ahoo.wow.query.dsl.pagedQuery
import me.ahoo.wow.query.snapshot.SnapshotQueryService
import me.ahoo.wow.query.snapshot.pathState
import me.ahoo.wow.query.snapshot.query

fun findPaidOrders(queryService: SnapshotQueryService<OrderState>) = pagedQuery {
    filter {
        pathState { "status" eq "PAID" }
    }
    pagination { index(1); size(20) }
}.query(queryService)

同一请求的 HTTP JSON 使用完整逻辑路径：

{
  "filter": { "op": "EQ", "field": "state.status", "value": "PAID" },
  "pagination": { "index": 1, "size": 20 }
}

字段是否可查询仍由运行时 Schema 与后端能力决定；不要因 state-only 响应而把请求字段写成 status。

默认删除条件

快照查询默认追加 DELETION = ACTIVE，因此不会返回已删除快照。根表达式或根 AND 合取树中的显式 DELETION 会覆盖默认范围；位于 OR 或 NOR 内的删除条件不会移除 ACTIVE guard。需要 DELETED 或 ALL 时显式使用该操作符，详见过滤条件。

JVM 查询

注入聚合级 SnapshotQueryService<S> 后，可通过扩展执行 typed 的 single/list/paged/count；dynamicQuery 返回 DynamicDocument，适用于 projection 改变返回形状的场景。服务经 Spring QueryGateway 的策略边界、直接 Factory 的绕过条件见查询后端与查询网关。

HTTP 路由

以下为 sales-order 已发布的基础快照数据查询路由；聚合与 Schema 不在本表中：

POST /sales-order/snapshot/single
POST /sales-order/snapshot/single/state
POST /sales-order/snapshot/list
POST /sales-order/snapshot/list/state
POST /sales-order/snapshot/paged
POST /sales-order/snapshot/paged/state
POST /sales-order/snapshot/count

相同的 single、single/state、list、list/state、paged、paged/state 和 count 操作还发布 tenant 与 owner 作用域变体：

POST /tenant/{tenantId}/sales-order/snapshot/{operation}
POST /owner/{ownerId}/sales-order/snapshot/{operation}

其中 {operation} 是上述七种操作之一。list 可以协商 JSON 或 SSE；single 与 paged 返回 JSON。聚合路由及 Query Model Schema（当前说明） 路由是独立合同；精确路径以运行实例生成的 OpenAPI 为准。HTTP guard 仍可能限制本来有效的 DTO。

完整快照、state-only 与动态结果

• 完整快照返回 MaterializedSnapshot<S>，用于同时读取状态和系统元数据。
• state-only 路由只解包 S；它只改变响应，不改变 state.* 请求字段。
• dynamic 结果返回 DynamicDocument，用于自定义 projection，但不保留 S 的编译期字段类型。

响应式与同步 API Client 的 typed、state-only、dynamic 调用见API 客户端。

空结果与 404

JVM single 无匹配时返回空 Mono；list 返回空 Flux，paged 返回空页。HTTP snapshot/single 与 snapshot/single/state 无匹配时为 404。API Client 会把 single 的 404 转为响应式空 Mono 或同步 null；其他错误继续传播。

何时使用快照查询

当问题是“当前订单是什么状态”“当前余额是多少”或需要按当前业务状态筛选时，选择快照查询。需要命令产生的完整历史、事件版本或事件 payload 时，选择事件流查询。