feat: add analytics metric granularity query

docs/technical/ANALYTICS_DATE_DIMENSION_IMPLEMENTATION_2026-05-04.md

@@ -281,6 +281,85 @@ SpacetimeClient::seed_analytics_date_dimensions
 3. 如需要由 `api-server` 触发 seed/ensure，再补 `spacetime-client` facade。
 4. 进入 Step 7/8/9：事件写入链路、聚合查询 API、前端 contracts。
 
+## Step 7/8/9 后续接入记录（2026-05-04）
+
+本次继续推进此前暂缓的 Step 7/8/9 中“按日期维度聚合查询 API / contracts / client facade”部分。
+
+### 已新增能力
+
+1. `module-runtime` 新增 analytics metric 聚合领域类型与纯函数：
+   - `AnalyticsGranularity = day | week | month | quarter | year`
+   - `AnalyticsMetricQueryInput`
+   - `AnalyticsBucketMetric`
+   - `AnalyticsMetricQueryResponse`
+   - `aggregate_runtime_tracking_daily_stats(...)`
+
+2. `spacetime-module` 新增 `query_analytics_metric` procedure，直接聚合 tracking daily stat，输出按 bucket 排序的统计结果。
+
+3. `spacetime-client` 新增 facade：
+
+```rust
+SpacetimeClient::query_analytics_metric(event_key, scope_kind, scope_id, granularity)
+```
+
+4. `api-server` 新增登录态接口：
+
+```http
+GET /api/profile/analytics/metric?eventKey=...&scopeKind=user&scopeId=...&granularity=day
+```
+
+请求参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `eventKey` | 埋点事件 key，必填 |
+| `scopeKind` | `site | work | module | user` |
+| `scopeId` | 对应范围 ID，必填 |
+| `granularity` | `day | week | month | quarter | year` |
+
+响应 data：
+
+```ts
+type AnalyticsMetricQueryResponse = {
+  buckets: Array<{
+    bucketKey: string;
+    bucketStartDateKey: number;
+    bucketEndDateKey: number;
+    value: number;
+  }>;
+};
+```
+
+5. shared contracts / 前端 shared contracts 已新增 analytics query 类型：
+   - `AnalyticsMetricQueryRequest`
+   - `AnalyticsMetricQueryResponse`
+   - `AnalyticsBucketMetricResponse` / `AnalyticsBucketMetric`
+   - `AnalyticsGranularity`
+
+### 本次验证
+
+从 `server-rs/` 执行通过：
+
+```bash
+cargo test -p module-runtime --test analytics_granularity
+cargo check -p spacetime-module
+cargo check -p spacetime-client
+cargo check -p api-server
+```
+
+验证结果：
+
+- `analytics_granularity` 测试通过：3 passed。
+- `spacetime-module` 编译通过，仅存在既有 dead_code warnings。
+- `spacetime-client` 编译通过。
+- `api-server` 编译通过，仅存在既有 prompt dead_code warnings。
+
+### 注意事项
+
+当前环境未检测到 `spacetime` / `spacetimedb` CLI，因此 analytics metric 相关 `module_bindings` 是按现有生成物结构手动补齐的临时生成物。后续有 CLI 的开发机应优先通过项目脚本重新生成 bindings，并复核手写生成物是否可被正式生成输出覆盖。
+
+---
+
 ## 阶段结论
 
 当前阶段已经完成“个人任务埋点范围收紧”和“日期维表 module 侧能力”的核心落地，并已生成 SpacetimeDB Rust client bindings。