Add skill for gameplay entry type workflows

docs/technical/PROFILE_TASK_AND_TRACKING_SYSTEM_2026-05-03.md

@@ -0,0 +1,78 @@
+# 个人任务与埋点系统技术方案
+
+更新时间：`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 契约和前端入口同步更新。