个人任务与埋点系统技术方案

更新时间：2026-05-03

1. 目标

本轮新增一套可配置的个人任务系统，并补齐任务依赖的埋点统计能力。首个任务为“每日登录”，奖励 10 光点，入口放在“我的”页签；后台可修改任务配置。

2. 核心边界

埋点原始事实写入 tracking_event，这是实际存在的 SpacetimeDB 表。
聚合投影写入 tracking_daily_stat，这也是后端维护的真实表，不是 view。
任务配置写入 profile_task_config，默认配置包含 daily_login，后台修改后不得被默认初始化覆盖。
任务进度写入 profile_task_progress，用于任务中心快速读取状态。
领奖记录写入 profile_task_reward_claim，与钱包流水 profile_wallet_ledger 同事务写入。
“星光”奖励复用现有“光点”钱包，不新增第二种货币。

3. 埋点分层

层级	scope_kind	scope_id 口径
整站	`site`	固定为 `site` 或站点分区 key
作品	`work`	作品 profile_id / work_id
模块	`module`	模块 key，例如 `profile`、`puzzle`
用户	`user`	用户 id

每条埋点可同时记录 user_id、owner_user_id、profile_id、module_key 与 metadata_json。任务首版只依赖用户层 daily_login，表结构先保留四层统计能力。

4. 日期桶

任务统计使用北京时间自然日：day_key = floor((occurred_at_micros + 8h) / 1d)。

这样存储仍是 UTC 时间戳，日切规则固定为业务口径，不依赖服务器本地时区。tracking_event.occurred_at 保存精确发生时间，tracking_daily_stat.day_key 只承担聚合桶职责。

5. 首版任务

字段	默认值
task_id	`daily_login`
title	`每日登录`
event_key	`daily_login`
cycle	`daily`
threshold	`1`
reward_points	`10`
enabled	`true`

用户成功登录时，认证链路会通过统一后端埋点 helper 幂等记录当日 daily_login 并刷新任务进度；用户打开任务中心只记录 task_center_view 浏览事件，不再承担每日登录事实写入。用户点击领取时，后端校验当日进度、领奖记录和配置状态，然后同事务写入领奖记录与钱包流水。

后台任务配置页的 Event Key 使用可搜索下拉控件，选项来自前端后台的埋点定义注册表。后台全量埋点筛选候选应对齐 BACKEND_TRACKING_EVENT_COVERAGE_2026-05-09.md 的事件清单；任务配置页只展示标记为个人任务可用的事件，当前仅开放 daily_login，展示中文名称和备注。后续新增任务依赖的埋点时，应先补充注册表并显式标记任务可用，再开放运营配置。

6. 接口

用户侧

GET /api/profile/tasks：读取任务中心，并记录 task_center_view 浏览事件；不在此入口写入 daily_login。
POST /api/profile/tasks/{task_id}/claim：领取任务奖励，并记录 task_reward_claim 成功事件。

后台侧

GET /admin/api/profile/tasks：读取任务配置列表。
POST /admin/api/profile/tasks：新增或更新任务配置。
POST /admin/api/profile/tasks/disable：停用任务配置。

后台任务配置页进入时从 profile_task_config 对应的列表接口读取已有配置，点击列表项回填表单后仍通过同一个 upsert 接口修改原配置。最近一次保存结果可以保留为会话态提示，但不得作为任务配置列表的唯一来源。

7. 查询文档边界

docs/tracking/ 只存放具体埋点与埋点聚合查询，例如 tracking_event、tracking_daily_stat 的站点/作品/模块/用户查询。
docs/operations/ 存放运营核查查询，例如任务进度、领奖记录、钱包流水对账。

不要把任务进度、领奖记录或钱包对账查询塞进 docs/tracking/，它们不是埋点系统本身。

8. 通用后端埋点覆盖

后端用户行为埋点统一按 docs/technical/BACKEND_TRACKING_EVENT_COVERAGE_2026-05-09.md 执行。该文档维护通用 procedure、api-server 中间件、事件清单、排除范围与查询验收口径；每日登录也走该统一路径，仅保留认证 helper 作为业务语义入口。

9. 验收

profile_task_config 默认存在 daily_login，后台可修改奖励、阈值、标题和启用状态。
“我的”页可以打开每日任务面板，登录后任务可领取 10 光点。
登录成功会幂等记录 daily_login；重复打开任务中心只记录 task_center_view，不会重复增加领取资格。
重复领奖不会重复发放。
表目录、迁移白名单、Rust/TypeScript 契约和前端入口同步更新。

4.7 KiB Raw Permalink Blame History Unescape Escape