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

更新时间：`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` |

用户打开任务中心时，后端会幂等记录当日 `daily_login` 埋点并刷新任务进度。用户点击领取时，后端校验当日进度、领奖记录和配置状态，然后同事务写入领奖记录与钱包流水。

后台任务配置页的 `Event Key` 使用可搜索下拉控件，选项来自前端后台的埋点定义注册表。当前注册表默认包含 `daily_login`，展示中文名称和备注；后续新增任务依赖的埋点时，应先补充注册表，再开放运营配置。

## 6. 接口

### 用户侧

- `GET /api/profile/tasks`：读取任务中心，同时记录当日登录埋点。
- `POST /api/profile/tasks/{task_id}/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. 验收

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