实现客户端埋点上传清理与后台查询

新增客户端每十五分钟上传及入库确认后批次清理
新增私有事件表、原子幂等入库及鉴权查询接口
新增后台客户端埋点明细、筛选、分页与权限
补充定向测试、真实数据库联调脚本及工程验收文档

docs/technical/【技术方案】客户端本地埋点与主站入库契约-2026-09-21.md

@@ -1,15 +1,17 @@
 # 客户端本地埋点与主站入库契约
 
-Version: 0.23
-Status: 本期本地采集已实现并通过验收；不加密、不上传，证据与未验证范围见第 12 节
+Version: 0.25
+Status: 本地采集及上传、入库、成功清理、后台查询已实现并完成本地隔离环境验收；未部署生产
 Date: 2026-09-21
 需求来源：[Game Agent 埋点设计原始方案](./【需求来源】GameAgent埋点设计原始方案-2026-09-05.md)；原始方案与后续已确认决策有差异时，以本文为准。
 
 ## 1. 交付目标与范围
 
-交付结果：在 Game Agent 与现役 Design Agent 客户端的真实业务节点产生有明确语义的产品事件，以明文 JSONL 批次持久化在应用级目录；后续主站按统一事件合同入库。
+阅读说明：第 1 至 12 节记录本地采集合同及其已完成的验收证据；当前上传、入库、清理与后台查询的实施合同统一见第 13 节。第 13 节细化第 8 节，不改变现有 12 类事件和采集触发点。当前整体仍在实施验收中，不表示已经上线。
 
-本阶段验收以本地记录为准：字段来源可追溯、事件不会冒充业务成功、正常重放不重复、跨账号不串归属、埋点故障不影响正常操作。没有上传成功、服务端去重或报表已可用的承诺。
+交付结果：在 Game Agent 与现役 Design Agent 客户端的真实业务节点产生有明确语义的产品事件，以明文 JSONL 批次持久化在应用级目录；当前实施增加主站入库、确认后清理与后台明细查询，验收要求见第 13 节。
+
+本地采集阶段的既有验收以本地记录为准：字段来源可追溯、事件不会冒充业务成功、正常重放不重复、跨账号不串归属、埋点故障不影响正常操作。这些证据不替代当前上传成功、服务端去重与后台查询的验收。
 
 优先级：
 
@@ -17,7 +19,7 @@ Date: 2026-09-21
 - 风险项：项目目标身份稳定性、跨账号在途操作、多窗口前台时间、崩溃未闭合区间、revision 与保存事实、重复回调。
 - 可选项：无；本阶段不扩充分析维度或细粒度点击事件。
 
-本阶段不实现文件加密、上传定时器、HTTP 接口、数据库表、服务端聚合或后台看板。不读取或批量转换已有对话历史为埋点，不改变现有 Agent 产物与恢复账本的职责。
+当前实施包括上传定时器、HTTP 接口、一张私有事件表与后台明细栏目；不实现文件加密、服务端聚合或统计看板。不读取或批量转换已有对话历史为埋点，不改变现有 Agent 产物与恢复账本的职责。
 
 2026-09-21 存储范围确认：用户决定本阶段先不做加密，直接保存明文事件批次；无公钥配置、密钥生成或轮换前置要求。以后若启用加密，另行定义文件格式与接收兼容合同。
 
@@ -27,13 +29,13 @@ Date: 2026-09-21
 
 2026-09-21 执行终态口径确认：等待澄清或审批算本次 run 正常完成，通过 end_reason 区分；用户取消和进程崩溃不计入 agent_run_failed，不进入已知成功/失败终态的分母。
 
-2026-09-21 本地保留策略确认：埋点队列及相关索引最多保留 7 天、总量上限 20 MiB。任一条件达到即按第 7.3 节清理，未上传的数据也适用；不影响项目、Agent 对话或创作成果。本版尚不上传，数据不会无限保留等待上传功能上线。
+2026-09-21 本地保留策略确认：埋点队列及相关索引最多保留 7 天、总量上限 20 MiB。任一条件达到即按第 7.3 节清理，未上传的数据也适用；不影响项目、Agent 对话或创作成果。上传失败的数据同样不会无限保留。
 
 2026-09-21 本地封存时间确认：从当前批次第一条事件进入开始，5 分钟到期后封存落盘；没有事件不生成空批次。该时间与后续每 15 分钟上传的周期独立，本轮实施评审采用 500 条及 1 MiB 的提前封存上限，作为内部常量。
 
 2026-09-21 策划成果采集确认：审批通过后实际进入下一阶段，且该阶段变化成功持久化，视为一次 project_revision_created；不严格校验文档版本或文件差异，不为埋点新增文件 revision 机制。阶段内随意修改文件不逐次采集，打开、重开或关闭项目不补历史阶段事件。同策划会话同目标阶段幂等；不独立采集策划进度事件或审批、澄清状态字段。5 分钟是封存落盘周期，后续 15 分钟是上传周期，均不是采集周期。
 
-用户已确定的后续要求：上传至主站数据库；客户端每 15 分钟上传一次；绑定真实用户与业务标识；成功后删除对应待上传副本；失败无弹窗、不阻塞正常进程；失败是否重试可选。本草案建议后续失败保留至下一个周期重试，不做立即重试；这是建议，不是已实现行为。
+用户已确定并授权实施的上传要求：上传至主站数据库；客户端每 15 分钟上传一次；绑定真实用户与业务标识；成功后删除对应待上传副本；失败无弹窗、不阻塞正常进程。当前实现采用失败保留至下一个周期重试，不做立即重试，仍受本地保留上限约束；整体完成情况以第 13 节验收为准。
 
 本文是团队共享的埋点技术方案唯一维护入口，原始需求副本仅用于追溯。正式编码前，按仓库规范驱动工作流在 `docs/project-memory/plans/` 补齐里程碑规范及当前里程碑实施计划，并完成对应评审；本文的建议项不因迁入仓库而自动视为已确认。本次按技术负责人授权推进实施，里程碑仍按规范逐项评审和验收。
 
@@ -334,7 +336,7 @@ session.json 是本地恢复元数据，不是待上传事件；事件文件不
 
 实例生命周期标记、打开历史索引与批次幂等映射均需有界清理；索引过期后不承诺识别无限久远的重放或首次打开。不可因此将未知 is_first_open 填 true。项目级首次创作提交标记跟随项目业务记录，不随埋点批次保留期清理。
 
-本阶段没有成功上传清理，正常数据只因容量/保留期策略清理；不得启动一个空上传器并将数据标成“已上传”。这也意味着本阶段积累的数据不保证一直保留到上传功能上线。
+容量/保留期清理与上传成功清理独立：前者不表示已入库，后者必须收到主站匹配的整批确认，详见第 13.7 节。任何批次均不保证无限保留至上传成功。
 
 ### 7.4 数据最小化与文件边界
 
@@ -342,21 +344,21 @@ session.json 是本地恢复元数据，不是待上传事件；事件文件不
 - 事件只包含本方案白名单字段；session.json 与 meta.json 只保存路由、实例身份、生命周期、幂等和清理所需元数据。
 - 不采集 Prompt、对话正文、工具参数/结果、代码、文件正文、Token、Cookie、API Key 或异常堆栈；不因取消加密扩大采集范围。
 - 正式事件写入 analytics 队列，不在普通应用日志、诊断包中重复输出完整事件正文。目录沿用现有应用私有目录权限。
-- 后续网络传输仍使用 HTTPS，并由主站验证用户身份与字段。文件不加密不等于取消传输安全或服务端校验；本阶段无上传行为。
+- 网络传输使用 HTTPS，本地开发仅允许显式配置的 loopback HTTP；由主站验证用户身份与字段。文件不加密不等于取消传输安全或服务端校验，上传实现见第 13 节。
 
-## 8. 为后续主站入库预留的合同
+## 8. 主站入库的事件与传输合同
 
 ### 8.1 保持事件与传输分离
 
 本地事件 envelope 保持第 4 至 6 节合同，不添加 uploaded、retry_count、last_upload_error 等会随传输变化的业务字段。批次目标、发送进度与确认信息留在传输元数据。
 
-后续批量请求固定包含 schema_version（整数 1）、batch_id（批次 UUID）、destination_origin（规范平台 origin）、user_id（真实用户 ID 字符串或 JSON null）、events（从 JSONL 解析得到的事件对象数组）。全批事件用户必须一致；本地路由只作发送提示，不能作为服务端归属的唯一证据。
+批量请求固定包含 schema_version（整数 1）、batch_id（批次 UUID）、destination_origin（规范平台 origin）、user_id（真实用户 ID 字符串）、events（从 JSONL 解析得到的事件对象数组）。本地匿名事件仍可保留 null，但本次上传不接收匿名批次。全批事件用户必须一致；本地路由只作发送提示，不能作为服务端归属的唯一证据。
 
-后续客户端通过 HTTPS 上传 JSON 批次，传输体类型为 application/json；保持各事件的原 ID、时间和字段值。本阶段不实现该请求，不虚构 URL 或物理表名。
+客户端通过 HTTPS 上传 JSON 批次，传输体类型为 application/json；保持各事件的原 ID、时间和字段值。具体接口、物理表与本地开发例外以第 13.3 至 13.4 节为准。
 
-为简化客户端文件管理，后续保留整批确认语义：服务端只有在全批事件已可靠保存，或按 event_id 去重确认内容相同时，才返回 `acknowledged_batch_ids`。客户端核对响应来自预期主站且 batch_id 属于本次请求后，删除对应整个批次目录。
+保持整批确认语义：服务端只有在全批事件已可靠保存，或按 event_id 去重确认内容相同时，才返回 `acknowledged_batch_ids`。客户端核对预期主站、成功 envelope、批次 ID 与事件数均匹配本次请求后，删除对应整个批次目录。
 
-部分入库后失败时不确认整批；客户端保留原事件批次并在后续重发全批，由服务端按 event_id 去重。无需为了全批确认强制采用一个数据库大事务，但必须可靠判断全批完成。相同 event_id 不同内容为冲突，不能覆盖原记录或谎报确认。
+本次使用单批原子事务，任一事件冲突导致整批回滚且不确认；客户端保留原批次并在下个周期重发，由服务端按 event_id 去重。相同 event_id 不同内容为冲突，不能覆盖原记录或谎报确认。
 
 本版不实现逐事件确认后的部分文件重写。永久无效批次的拒收/过期清理不得记为上传成功，也不能因为 HTTP 200、收到字节或仅解析成功就删除本地数据。
 
@@ -369,9 +371,9 @@ session.json 是本地恢复元数据，不是待上传事件；事件文件不
 - event_id 是全局唯一去重键。导入时保留原 ID、发生时间、关联字段和客户端版本，不重生成事件身份。
 - 服务端单独生成 received_at，用于观察延迟；不覆盖 event_time。
 - 不要求会话、任务、run 与 revision 按顺序到达，不因父事件丢失或批次乱序拒绝所有子事件；关联不完整需可识别。
-- 查询维度需要支持 user_id、project_id、creative_task_id、agent_run_id、event_name、event_time 和 client_version。主站物理表、索引和现有 tracking 适配在后续阶段核查后确定。
+- 查询维度支持 user_id、project_id、creative_task_id、agent_run_id、event_name、event_time 和 client_version。主站独立事件表、索引与后台查询以第 13 节为准，不进入现有主站 tracking 聚合链路。
 - 本地匿名事件、未知平台、未知 schema 版本不能静默改写归属或格式后入库。
-- 未来每 15 分钟触发后台上传、同一客户端同时最多一个上传任务；成功清理、失败静默、不阻塞退出。重试策略、请求上限和超时在上传里程碑定义。
+- 每 15 分钟触发后台上传、同一应用数据目录同时最多一个上传轮次；成功清理、失败静默、不阻塞退出。重试策略、请求上限和超时以第 13.6 节为准。
 
 ### 8.3 可用指标的限制
 
@@ -428,7 +430,7 @@ session.json 是本地恢复元数据，不是待上传事件；事件文件不
 | A 数据合同与本地队列 | 强类型事件、捕获身份、JSONL 批次、有界异步写入与恢复、静默失败 | 字段校验、JSONL 读取、跨账号、不阻塞、损坏隔离、容量与幂等测试通过 |
 | B 会话、窗口与项目 | start/end/focus/create/open，以及下次启动的本地 incomplete 标记 | 多窗口、重载、最小化、正常退出、旧实例存活识别、异常未闭合、项目重复打开测试与桌面 smoke |
 | C 两类 Agent 与成果链路 | submit/run、策划阶段推进成果、已有真实 revision、preview/save | 成功失败与等待、阶段实际推进且持久化成功与幂等、重试关联、无变化、版本漂移、真实访问与保存边界全部可核对；不新建策划文件 revision 机制 |
-| 后续独立阶段 | 上传主站与查询 | 另立规范；不在本版实施范围 |
+| 当前上传阶段 | 上传主站、确认后清理与后台查询 | 按第 13 节及配套里程碑实施，尚待完成整体验收 |
 
 实施前为选定里程碑生成单独实现计划，前一个里程碑评审/验收后再推进下一项。
 
@@ -485,7 +487,7 @@ session.json 是本地恢复元数据，不是待上传事件；事件文件不
 | output_change_detected / duration_ms | 证据不足允许 null | 原方案未明确可空性，不能用 false/0 伪造确定值 |
 | 策划阶段成果（已确认） | 审批通过并实际进入下一阶段，成功持久化后复用 project_revision_created；同会话同目标阶段幂等 | 不采独立进度与审批字段；不严格校验文档版本/差异；阶段内修改不逐次采集，重开不补历史 |
 | revision | Game Agent 与其他已有正式 revision 路径按真实变化采集；策划使用 design:<session_id>:<target_phase> 阶段事实标识 | 策划标识不是文件版本，不据此伪造 run 文件变化；其他来源剔除纯元数据同步 |
-| 本地保留（已确认） | 最多 7 天或总量 20 MiB，任一条件达到即清理；超量先清最旧批次 | 未上传数据也会清理，本版不保证保留至上传功能上线；不删除项目及 Agent 业务数据 |
+| 本地保留（已确认） | 最多 7 天或总量 20 MiB，任一条件达到即清理；超量先清最旧批次 | 未上传数据也会清理，不保证保留至上传成功；不删除项目及 Agent 业务数据 |
 | 本地封存时间（已确认） | 当前批次首条事件进入后 5 分钟封存；无事件不生成空批次 | 与 15 分钟上传独立；强退可能丢失尚未落盘的一批事件 |
 | 本地批量上限（实施采用） | 达到 500 条或 1 MiB 序列化事件大小提前封存；超大单事件静默拒绝 | 内部常量，与 5 分钟条件并行；不新增用户设置 |
 | 字段补充 | schema_version、focus_interval_id、run end_reason；incomplete 仅是本地生命周期状态 | 需与后续接收端按同版合同实现，不任意扩展 properties，不将本地状态冒充产品事件 |
@@ -530,3 +532,194 @@ session.json 是本地恢复元数据，不是待上传事件；事件文件不
 | 预览前端来源、生产编译及条款验收 | 合并 master 后 `appSurface.test.ts --threads=false -t 'preview\|预览\|play request\|run local\|local game'` 104 项、shell tsc、生产 `cargo +stable check`、fmt/编码/索引/diff及独立验收 | 全部通过；旧草稿自动预览不传 user，不据任意外部 URL 推断项目成果。Direct 原 run capture 与临时 guard 经独立接线审查；实测 host HTTP 可访问性不等价于完整 Chrome 双端验证。无上传、外部探测或新增业务版本；临时计划已融合删除 |
 
 环境限制：本机固定 1.98.1 工具链缺可用 cargo，实际显式使用 stable（1.96.0）完成编译测试，未更改仓库固定版本。真实 GUI smoke 使用隐藏窗口，只证明启动与正常退出，不证明实际焦点操作；窗口并集、最小化和重复通知以状态测试验证，锁屏/休眠为已知观测限制。真实付费 Provider 和完整 GUI run smoke 未执行，Runtime 模拟 Provider 与前端 helper 测试不等价于真实模型验证。Direct 未完成交付合同的 guard 释放可能将账本中断，本版不改变其业务恢复行为，不承诺所有认证刷新都能继续生成；埋点不会将此类中断报告记为成功。人工和 UI 保存已有真实业务函数/文件/JSONL及前端 hook 验证，尚无完整 GUI 跨层操作 smoke；预览已有真实宿主 HTTP 和 JSONL 验证，未运行完整 Chrome 双端验证。
+
+## 13. 上传、入库、成功清理与后台查询工程方案
+
+### 13.1 交付目标与边界
+
+状态：implemented / verified；技术负责人已授权开工，本地隔离环境验收完成，证据与限制见 §13.11，未核验或变更线上 schema。客户端定期上传已有封存批次，主站可靠保存并确认后清理对应本地副本，管理员能够查询真实入库的事件明细。
+
+- 必须项：一张私有持久表、批量接收 API、后台上传器、确认后删除、一个后台明细栏目、身份和幂等验证。
+- 风险项：服务端已提交但响应丢失、跨账号/平台串传、保留清理与上传并发、删除导致观测资格重置、查询截断冒充最新数据。
+- 可选项：本版无。暂不做加密、匿名接收、聚合表、统计看板、Excel 导出、后台编辑/删除、立即重试或新增采集事件。
+- 采集仍为现有 12 类事件；不上传对话、提示词、文件内容、策划快照、本地路径、Token、项目资格账本或会话 incomplete 元数据。
+- 5 分钟 / 500 条 / 1 MiB 封存和 7 天 / 20 MiB 本地保留合同继续生效。上传成功清理与保留上限清理是两种独立原因，不能把后者统计为上传成功。
+
+### 13.2 现状与接入边界
+
+现有 `tracking_event` 保存主站的 event_key、scope、用户及 metadata_json，`tracking_daily_stat` 保存每日聚合；后台已有 `#tracking` 和 `#tables`。本方案新增 `agc_tracking_event`，不改主站埋点表、不进入个人任务奖励或主站每日统计链路。
+
+正式路径为：客户端 Rust 上传器 → api-server 用户鉴权与 DTO 校验 → module-* 中的事件规则 → spacetime-client typed facade → spacetime-module 原子事务。后台通过管理端鉴权 BFF 和同一 facade 读取私有表，浏览器不直连数据库。
+
+主站接受的是客户端观测数据，不因此确认项目所有权、成果真实性或奖励资格。允许父事件缺失、乱序、迟到，不给本地项目 ID 添加主站项目外键约束。
+
+### 13.3 数据表与字段映射
+
+新增普通私有持久表 `agc_tracking_event`，不是仅供实时订阅的 SpacetimeDB event table。一条事件一行。
+
+| 字段 | 数据库类型 | 来源与约束 |
+| --- | --- | --- |
+| event_id | String，主键 | 原事件 UUID；唯一去重键 |
+| schema_version | u32 | 原事件版本，首版只接收 1 |
+| event_name | String | 原事件名，现有 12 类白名单 |
+| event_time | Timestamp | 原 UTC 毫秒时间，无损转换，不用接收时间替代 |
+| user_id | String | 本版只接收非匿名用户；与鉴权主体及批次 user_id 相同 |
+| editor_session_id | String | 原编辑器会话 ID |
+| project_id | Option<String> | 原值，保留 null |
+| creative_task_id | Option<String> | 原值，按事件合同与 project_id 一致 |
+| agent_run_id | Option<String> | 原值，保留 null |
+| agent_turn_id | Option<String> | 原值，保留 null |
+| status | Option<String> | 原枚举 success / failed 或 null |
+| error_code | Option<String> | 原错误码白名单或 null |
+| source | String | 原来源枚举 |
+| client_version | String | 原客户端版本 |
+| properties_json | String | 按事件类型验证后的专属属性 JSON；不接受任意字段 |
+| batch_id | String | 首次接收入库时的批次 UUID；重复事件不改写 |
+| received_at | Timestamp | 首次插入事务的 ctx.timestamp；重传不刷新 |
+
+字段和 nullable 语义以第 4 至 6 节为准，不能用空串或零替代未知。传输 origin 不作为事件新增采集字段或表内分析维度；部署环境由服务端配置及批次 origin 校验隔离。
+
+索引：received_at、(user_id, received_at)、(event_name, received_at)。主键承担去重。SpacetimeDB 2.8.3 的索引过滤不支持 Option<String> 项目字段（已由编译核验），项目条件使用上述时间索引候选进行精确筛选，不增加空串哨兵或重复项目字段。其余关联字段先作为受限查询条件，不为了预想报表遍建索引。
+
+本版只新增表，同步 migration 注册、架构表目录、生成绑定和 schema 检查；不迁移旧主站埋点，不改动已有表字段。服务端暂不设置自动到期删除；本地 7 天 / 20 MiB 不适用于数据库。数据库容量与后续留存另行评估，不在本次加入自动清库。
+
+### 13.4 上传接口与确认合同
+
+新增 `POST /api/agc/analytics/batches`，使用现有用户 Bearer 认证与平台会话能力，HTTPS、`Content-Type: application/json`。本地开发仅复用既有显式配置的开发服务地址。该路径不是 external v1，不引入开发者 API Key。
+
+请求保持第 8 节合同，snake_case：
+
+| 字段 | 类型与来源 |
+| --- | --- |
+| schema_version | 整数 1，上传协议版本 |
+| batch_id | 原批次 UUID 字符串 |
+| destination_origin | 批次原目标平台 origin |
+| user_id | 批次原真实用户 ID 字符串 |
+| events | 从原 JSONL 解析的事件对象数组，完整对象示例见第 9 节 |
+
+- 一次请求只发一个已封存批次，1 至 500 条。事件数据沿用 1 MiB 上限，JSON 请求体上限 2 MiB，容纳数组及 envelope 开销；服务端不依赖 Content-Length 自报大小。
+- 批次与所有事件的 user_id 必须相同且等于鉴权主体；匿名、未知 origin 批次不上传，不补认领到后来登录的账号。
+- destination_origin 必须匹配当前服务部署的可信公开 origin 配置，不使用未经信任的 Host 头作为判据。
+- 接收端配置 `GENARRATIVE_AGC_ANALYTICS_ORIGIN` 为规范 origin（无路径和尾部斜杠）：正式站 `https://www.genarrative.world`，测试站 `https://dev.genarrative.world`，本地联调填写客户端实际连接的 loopback origin。未配置/非法配置时接口返回 503，不猜测默认站点；允许 HTTPS 和本地 loopback HTTP。
+- 复用现有事件版本、枚举、字段长度与必填 nullable 校验；批内重复 event_id、未知字段或非法事件整批拒绝。
+- 本接口不进入普通成功路由 tracking 映射，不为每次上传另生成主站产品事件。
+
+成功响应使用现有 API 成功 envelope，其 payload 为：
+
+```json
+{
+  "acknowledged_batch_ids": ["<本次请求的 batch_id>"],
+  "event_count": 12
+}
+```
+
+`event_count` 是本次确认的事件总数，包含内容一致的已有事件，不是新增行数。客户端只在成功 envelope、批次 ID 和本次事件数均匹配时删除。HTTP 200 本身不足以证明入库。
+
+| 返回 | 意义 | 客户端处理 |
+| --- | --- | --- |
+| 200 且确认匹配 | 整批已提交或已存在且内容相同 | 删除该批次待上传副本 |
+| 400 | 格式、事件合同或 schema 不支持 | 本轮跳过，保留至后续周期或保留清理 |
+| 401 / 403 | 凭据失效、用户或 origin 不匹配 | 本轮停止该身份上传，不弹登录窗口、不替换归属 |
+| 409 | event_id 已存在但内容不同 | 不覆盖、不确认，保留原批次 |
+| 413 | 请求超限 | 不拆分或改写原批次，保留 |
+| 429 / 5xx / 网络超时 | 本轮不可确认 | 保留，下周期重试，不立即循环重试 |
+| 响应缺字段、ID/数量不符 | 确认无效 | 保留 |
+
+沿用现有错误 envelope；响应不回显事件正文、凭据或其他用户数据。
+
+### 13.5 原子入库与幂等
+
+首版单批最多 500 条 / 1 MiB，采用一个原子事务完成，不新增批次回执表或服务端任务队列。
+
+1. API 先鉴权并校验完整请求，再通过受信任服务身份调用数据库写路径；普通客户端身份不能直接写表。
+2. 事务核验全批事件。event_id 不存在则插入；已存在时比较原事件全部业务字段，properties 按解析后的结构比较，JSON 对象键顺序不影响等价。
+3. 相同事件视为已接收，保留第一次的 batch_id 和 received_at；事件 ID 相同但用户或任意事件内容不同则冲突，整批回滚。
+4. 只在确认数据库事务已提交后响应。Reducer 如被采用，facade 必须等待其已提交结果，不能将“已发送调用”当作完成。
+5. 服务端已提交但响应丢失、客户端确认后崩溃或本地删除失败，均可用原批次重发；不增加事件行数。
+
+batch_id 是传输关联标识，event_id 是持久幂等依据。一张表不提供独立批次审计、批次内容哈希登记或永久批次状态机；本版不承诺这些能力。
+
+### 13.6 客户端调度与身份
+
+- 从客户端后台上传器启动时计时，每 15 分钟触发一次；首次不立即上传。休眠恢复最多执行一次到期轮次，不补跑错过的全部轮次。运行不足 15 分钟的数据留待后续启动并达到上传周期；退出不强制联网。
+- 每轮串行处理当时已封存且身份匹配的批次，优先旧批次；轮次开始后新封存的批次留待下一轮。
+- 同一应用数据目录通过一个非阻塞上传锁只允许一个实例执行上传轮次；竞争者本轮跳过。不使用长时间文件锁包住正常采集或网络等待。
+- 单请求总超时 30 秒；每轮最多处理 20 批、最多 2 分钟，不重叠执行。下一轮重新扫描；以上均为内部常量，不新增设置界面。
+- 仅使用与批次 user_id、destination_origin 完全一致的当前认证会话。账号或平台切换后不发起旧身份的新请求；已经发出的请求仍绑定原身份，收到有效确认可以清理原批次。
+- Token 只在内存请求中使用，不写入批次、表或日志。复用现有凭据获取能力，不新增埋点专属登录、刷新循环或登录提示。
+- 未登录、匿名、未知平台数据保留到原有保留策略清理；不主动登录所有历史账号来上传。
+- 400/409/413 等单批错误跳过该批继续本轮剩余候选，避免毒批次独占队列；认证错误或暂时服务故障结束本轮。下一周期仍按相同有界规则处理，不无限立即重试。
+
+### 13.7 本地成功清理与现有状态边界
+
+上传只读取已发布批次的 meta.json 和 events.jsonl，使用现有安全路径、大小、事件清单及一致性校验；不扫描项目内容。不得根据服务端返回字符串直接拼出待删路径，删除目标只能是本次本地选中的批次目录。
+
+上传器持有一个有界批次内存副本再执行网络请求，不在网络等待期间占用 writer。保留清理可能先删原目录：发送前已缺失就跳过；发送后已缺失则确认清理视为无事可做。允许既有保留策略丢弃未上传数据，不建立第二套 durable outbox。
+
+有效确认后调用本地存储层的批次删除入口，只删除对应目录，并同步/失效化有关批次缓存。删除失败保留，下一轮允许重传。上传异常只增加有界诊断计数，不弹窗、不阻塞 Agent、项目操作或退出。
+
+不能删除项目 `.agent/analytics-goal.json`、`.agent/analytics-runs.json`、正式会话、对话或成果。保留会话恢复所需的控制元数据，空实例目录交给既有保留清理。
+
+现有 store 的去重索引会随批次清理重建。上传更早删除批次不能重授首次提交资格或重置 run 身份：项目资格/run 账本保持原生命周期。当前实例另保留有界内存中的近期事实及项目观测，分别最多 16,384 项、最多 7 天，超限淘汰最旧项而非停止后续采集，避免最近已确认批次的重复回调重新生成 ID。内存缓存不承诺无限历史去重，不新增永久历史索引，也不从服务器或完整对话回填历史。
+
+### 13.8 后台“客户端埋点”栏目
+
+新增路由 `#agc-tracking`，显示名“客户端埋点”，与现有主站“埋点数据”并列；复用后台布局、筛选表单、用户引用组件及详情弹窗。owner 按现有规则可访问，member 必须具备新增页签权限 `agc-tracking`，接口同时执行权限校验。
+
+新增 `GET /admin/api/agc/tracking-events`，管理端 DTO 沿用 camelCase：
+
+- 筛选参数：`userId`、`projectId`、`creativeTaskId`、`agentRunId`、`eventName`、`clientVersion`、`startTime`、`endTime`、`cursor`、`limit`。
+- UI 首版展示发生时间范围、用户、项目和事件类型；其他关联筛选可通过详情入口携带，均使用精确匹配，不引入全文搜索。
+- 时间范围按 event_time，起点包含、终点不包含；时间格式为带时区 RFC3339。默认不设时间过滤，默认每页 50 条，最大 200 条。
+- 返回 payload：`entries`、`nextCursor`。条目包括表内字段的 camelCase 映射，`properties` 返回解析后的 JSON 对象；时间转为 UTC 字符串，Option 转 null，不向 UI 暴露 SATS 原始值。
+- 列表按首次入库时间 received_at 倒序，同时间按 event_id 稳定排序；明确列标题为“入库时间”和“发生时间”，不混称最新发生的事件。
+- cursor 固定查询快照上界、最后一行的 (received_at, event_id) 和筛选摘要；切换筛选重置游标，非法游标返回 400。新增数据点击刷新后出现，分页不依赖会随插入漂移的 offset。
+- 由数据库查询路径按索引及条件确定排序候选与页边界；若当前 SQL 不支持排序，通过受限 typed procedure 完成。不能任取 LIMIT N 行后排序并宣称为全表最新；实现计划须在现役 2.8.3 上验证此点，不照搬旧页面的截断查询方式。
+
+列表列：入库时间、发生时间、用户、事件中文名、项目、来源、结果、客户端版本。空值显示“—”。详情展示全部既有字段与格式化 properties，包括会话/run/批次 ID；不新增编辑或删除按钮。空结果、加载失败、无权限沿用后台现有反馈，移动端表格支持横向滚动。
+
+### 13.9 兼容、上线与回退
+
+- 本地事件 schema_version 继续为 1，不改写已封存批次；升级后只处理仍在保留范围内且身份匹配的数据，不恢复已过期数据。
+- 发布顺序：新增数据库表/事务 → API 与后台 → 带上传器的客户端。旧客户端继续只写本地，旧批次无须迁移。
+- API 未部署或服务不可用时客户端静默保留并按周期重试；现有本地保留上限仍有效。
+- 回退客户端上传器或接收路由时保留已入库表，不删除正式数据；本地清理只对真实确认发生。没有新增远程开关或复杂灰度框架。
+- 新增事件版本必须显式扩展接收合同，不能靠忽略未知字段兼容。首次接收字段校验必须与客户端合同做对应测试。
+
+### 13.10 实施边界与验收
+
+技术负责人已授权按本方案开工；里程碑验收证据已融合至 §13.11，完成的临时里程碑规范与实施计划已删除。实现可在正确配置的部署环境使用，不代表已发布上线。
+
+实现涉及 analytics 存储/上传器与平台会话、shared-contracts、现有 module-* 领域、spacetime-module 表/事务/migration、spacetime-client facade/绑定、api-server 用户及后台路由、admin-web 页面/权限。不更改 Game/Design Agent 埋点触发逻辑。
+
+| 验收项 | 必须取得的证据 |
+| --- | --- |
+| 正常闭环 | 真实本地批次 → 测试主站数据库 → 确认 → 本地删除 → 后台可查相同 event_id |
+| 原子与去重 | 首传、原批重传不增行；任一冲突导致本次新行全部不落库；确认丢失后重传成功 |
+| 身份 | A 批次不能用 B 凭据或另一平台发送；匿名不认领；后台未授权读被拒绝 |
+| 静默失败 | 断网、超时、非成功/无效确认时保留；业务调用和退出不等待上传；下一周期可恢复 |
+| 清理边界 | 删除失败可重传；保留清理并发不误删其他批次；首次提交资格/run 身份保持；现有 7 天/20 MiB 不变 |
+| 调度 | 15 分钟、单目录互斥、有界轮次、休眠不积压补跑、毒批次不阻塞本轮其他数据 |
+| 后台查询 | 筛选、null/时间/属性显示、跨页稳定顺序及新数据刷新；数据量超过一页，不用截断结果冒充全量 |
+| 回归 | 现有事件合同、store/goal/run 定向测试及主站 tracking 不受影响 |
+| 工程检查 | schema 生成/检查、相关 Rust 测试与编译、后台类型检查、文档索引、编码和 diff 检查 |
+
+运行时 smoke 必须包含真实 SpacetimeDB 提交及后台页面；mock 请求成功不算完成入库验收。不需要为本轮重新调用付费模型或扩大 Agent 创作测试。
+
+本版实施口径为：只接收已登录用户、一张事件表、原子整批提交、首轮等待 15 分钟、30 秒请求超时、20 批/2 分钟轮次预算、失败下周期重试、后台按入库时间分页、服务端暂不自动过期。已确认的采集范围、上传周期、静默非阻塞和成功删除原则不变。
+
+### 13.11 实现与验证记录（2026-09-21）
+
+实现沿用既有 12 类事件和采集入口。新增 `analytics/upload.rs`、`agc_tracking_event` 私有持久表、批量接收与后台查询接口，以及后台“客户端埋点”页；未部署生产。
+
+| 验证 | 结果与边界 |
+| --- | --- |
+| 客户端 | `cargo +stable test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell analytics -- --test-threads=1`：56 项通过，真实服务联调用例默认 ignored；普通客户端程序同时编译通过。覆盖调度、锁、身份匹配、错误确认/503 保留、成功清理、近期事实去重和既有 store/goal/run 回归 |
+| 领域与 API | module-runtime `agc_analytics` 4 项、api-server `agc_analytics` 3 项和后台权限 2 项通过；覆盖 12 类事件合同、非法字段、身份/origin、请求大小和后台权限 |
+| 真实数据库 | `scripts/agc-analytics-smoke.mjs` 在独立临时 SpacetimeDB 2.8.3 上使用最终源码 WASM 通过首传、重传、属性键序等价、冲突整批回滚、保留首次入库值、用户筛选、稳定分页、分页期间插入与刷新、UTC/null 和服务身份限制 |
+| 同一事件完整链路 | 手工执行 ignored `app::tests::agc_analytics_real_database_http_roundtrip`：真实客户端 Store 封存 JSONL → 生产上传器 → Axum HTTP → 真实数据库事务 → 确认后删除 → 后台接口查到相同 event_id/batch_id；同一事件重传只保留一行。用户认证使用测试夹具，未通过完整客户端 GUI 登录 |
+| 后台静态验证 | 28 项定向测试、admin-web 类型检查与作用域 ESLint 通过 |
+| 后台运行时 | 已编译 API 以临时 test 配置连接同一隔离数据库，`/healthz` 返回 200；真实浏览器登录、进入客户端埋点页、查看上传器生成记录、用户筛选及详情成功，时间、null 与 properties 显示正常。分页及刷新由真实数据库多页测试和页面定向测试验证 |
+| 数据契约 | migration 注册、表目录与生成绑定已同步；schema 检查通过 145 张表，DDD 边界检查通过；未改变既有表字段 |
+
+编码、文档索引、作用域 Rust 格式与 diff 检查通过。`npm run dev:api-server` 编译通过，但本机启动脚本以既有短信配置覆盖测试环境变量，因缺少阿里云短信凭据而退出；页面 smoke 改为直接启动同一已编译 API，使用进程级 mock 认证/test 配置，未改本地配置文件。未验证完整客户端 GUI 登录、15 分钟墙钟等待、操作系统休眠及生产部署；调度周期与恢复通过定向状态测试验证。本轮不调用付费 Provider，不扩大 Agent 创作验收。