142 lines
7.2 KiB
Markdown
Executable File
142 lines
7.2 KiB
Markdown
Executable File
# Task 9-b · full-stack-developer · 信标系统扩展（周挑战 + 信标链）
|
||
|
||
> 本文件为本 agent 在 Task 9-b 的工作记录，供后续 agent 查阅。
|
||
|
||
## 任务概述
|
||
|
||
为「回响星核 / Echo Nexus」v0.8 扩展深空信标系统，新增两大功能：
|
||
1. **周挑战（Weekly Challenge）** — 每周一 UTC 0 点刷新，目标更大、奖励更好，与日挑战并行
|
||
2. **信标链（Beacon Chain）** — 连续完成日挑战形成"链"，达成里程碑（3/7/14/30 天）领取递增大奖，含 grace 续命机制
|
||
|
||
## 阅读的前置工作
|
||
|
||
- `/home/z/my-project/worklog.md`（v0.8 项目状态，10 大系统，四色全息规范）
|
||
- `/home/z/my-project/src/lib/game/beacon.ts`（v0.5 原版 358 行：每日挑战 + 本地排行榜）
|
||
- `/home/z/my-project/src/components/game/BeaconPanel.tsx`（原版 301 行）
|
||
- `/home/z/my-project/src/store/gameStore.ts` 第 173 行 `trackBeacon` 函数 + 7 处调用点（pulse/clickNode/autoDecodeTick/resolveCurrentNode 等）
|
||
|
||
## 实现细节
|
||
|
||
### 1. beacon.ts 扩展（358 → 873 行）
|
||
|
||
**周挑战（WEEKLY CHALLENGE）section**：
|
||
- `BeaconWeeklyChallenge` 接口 + `BeaconWeeklyProgress` 接口
|
||
- `getWeekKey(now)`：ISO 8601 周键（YYYY-Www，周一为起点，含首个周四的周为第一周）
|
||
- `weekKeyToSeed`：FNV-1a 哈希
|
||
- `generateWeeklyChallenge(now)`：基于 weekKey 种子确定性生成
|
||
- 难度加权：anomaly 60% / singular 40%
|
||
- mult = 3 + floor(rng() * 3) → 3-5 倍
|
||
- goal 范围：decode 18-75 / expedition 3-15 / pulse 60-245 / boss 3-12 / insight 120-595
|
||
- `loadWeeklyProgress` / `saveWeeklyProgress` / `addWeeklyProgress` / `claimWeeklyReward`
|
||
- `msUntilNextWeek(now)`
|
||
- `BEACON_WEEKLY_KEY = "echo-nexus-beacon-weekly-v1"`
|
||
|
||
**信标链（BEACON CHAIN）section**：
|
||
- `BeaconChainState` 接口（lastCompletedDateKey / currentStreak / longestStreak / totalCompletions / graceUsed / milestonesClaimed）
|
||
- `BEACON_CHAIN_KEY = "echo-nexus-beacon-chain-v1"`
|
||
- `BEACON_CHAIN_MILESTONES = [3, 7, 14, 30] as const`
|
||
- `BEACON_CHAIN_REWARDS`：4 个里程碑
|
||
- 3 天：+50 洞见 / +5 接触 / "三日谐振"
|
||
- 7 天：+120 洞见 / +12 接触 / "七日回响"
|
||
- 14 天：+280 洞见 / +28 接触 / "半月星潮"
|
||
- 30 天：+680 洞见 / +68 接触 / "满月飞升"
|
||
- `loadChainState` / `saveChainState`（每次返回新对象避免引用共享 bug）
|
||
- `recordChainCompletion(dateKey)` 核心逻辑：
|
||
- 同日重复完成 → 忽略
|
||
- 次日 → streak++
|
||
- 隔一天 miss 且 graceUsed<1 → 续命 streak++ graceUsed++
|
||
- 其他 → 断链 streak=1 graceUsed=0
|
||
- 返回 `{ state, newMilestones }`
|
||
- `claimChainMilestone(milestone)` / `getNextMilestone(streak)` / `getChainProgress(streak)`
|
||
- `dateKeyToTimestamp` / `dateKeyDiffDays` 工具
|
||
|
||
`BeaconScoreEntry` 新增可选 `isWeekly?: boolean` 字段，向后兼容。
|
||
|
||
### 2. gameStore.ts 集成
|
||
|
||
- import 扩展：新增 generateWeeklyChallenge / loadWeeklyProgress / loadChainState / addWeeklyProgress / recordChainCompletion / claimWeeklyReward / claimChainMilestone / getTodayKey + 类型
|
||
- `trackBeacon(type, delta)` 返回值从 `boolean` 升级为 `{ dailyJustCompleted, weeklyJustCompleted, newChainMilestones }`：
|
||
- 同时更新日挑战进度 + 周挑战进度
|
||
- 日挑战刚完成时调用 `recordChainCompletion(getTodayKey())`
|
||
- 所有 7 处调用点原本忽略返回值，向后兼容
|
||
- 新增 action `claimWeeklyBeacon()`：调用 claimWeeklyReward → 发放奖励到 state
|
||
- 新增 action `claimChainReward(milestone)`：前置校验 → claimChainMilestone → 发放奖励
|
||
- GameActions 接口同步扩展
|
||
|
||
### 3. BeaconPanel.tsx 重写（301 → 638 行）
|
||
|
||
- 头部 + 每日挑战卡片（v0.5 保留）+ 难度色按钮主题
|
||
- **周挑战区块**（fuchsia 主题）：标题 + weekKey + 倒计时 + 卡片（标签/标题/描述/进度/奖励/领取按钮 emerald）+ weekly-glow 动画
|
||
- **信标链区块**（amber→rose 渐变）：
|
||
- 标题"信标链 · CHAIN" + 大字号 streak（chain-streak-text 流动渐变动画）
|
||
- 今日完成状态徽章
|
||
- 4 个里程碑节点（w-12 h-12 圆形）：
|
||
- claimed: emerald 实心 + ✓
|
||
- reachable: rose 脉冲动画 + "领取"按钮
|
||
- inProgress (next milestone): amber 半亮
|
||
- 未到达: muted 灰
|
||
- 节点间连线：背景灰 + 已达成部分 amber→rose 渐变 + 辉光，基于 prev→next 插值定位
|
||
- 进度条 + 底部统计（最长链/累计完成/续命状态）
|
||
- 桌面端 lg:grid-cols-2 让周挑战 + 信标链并排，移动端单列
|
||
- 排行榜区分日/周：周挑战 entry 显示 "WEEK" 徽章 + fuchsia 高亮背景
|
||
- 4 个新 CSS 动画：weekly-glow / chain-milestone-pulse / chain-streak-flux
|
||
|
||
## QA 验证结果
|
||
|
||
### 1. lint
|
||
- `bun run lint` 零错误（每次修改后均验证）
|
||
|
||
### 2. dev 服务器
|
||
- dev.log 全程无错误，所有编译 < 300ms，HTTP 200
|
||
|
||
### 3. 信标链逻辑测试（bun 直接运行 TS，5 个场景全 PASS）
|
||
1. ✅ 昨日 streak=1 → 今日完成 → streak=2（normal increment）
|
||
2. ✅ 同日重复完成 → 忽略
|
||
3. ✅ 明日完成 → streak=3，无需 grace
|
||
4. ✅ 隔一天 miss（lastCompleted + 2 天）→ streak=4，graceUsed=1（续命触发）
|
||
5. ✅ 再次 miss（grace 已用）→ 断链 streak=1，graceUsed=0
|
||
|
||
### 4. UI 集成测试（agent-browser）
|
||
- localStorage 模拟设置 chain state（lastCompletedDateKey=yesterday, currentStreak=1）→ reload → UI 正确显示 streak=1
|
||
- 设置 streak=3 + milestonesClaimed=[] → milestone 3 节点显示 rose 脉冲动画 + "领取"按钮
|
||
- 点击"领取"→ milestonesClaimed=[3] + Toast "✦ 三日谐振 已领取 +50 洞见 · +5.0 接触" + 按钮消失 ✅
|
||
|
||
### 5. VLM 视觉评分（目标 ≥7/10）
|
||
- 首屏截图：**8/10**（四色一致、布局合理、信标链清晰）
|
||
- 里程碑可领取状态：**8/10**（amber→rose 渐变醒目、里程碑层次分明、fuchsia 主题清晰）
|
||
- 重置后干净状态：**8/10**（WEEKLY 字体对比度可优化，但整体可读性强）
|
||
|
||
## 修改的文件
|
||
|
||
1. `src/lib/game/beacon.ts` — 358 → 873 行（+515 行）
|
||
2. `src/store/gameStore.ts` — trackBeacon 升级 + 2 个新 action（+~80 行）
|
||
3. `src/components/game/BeaconPanel.tsx` — 301 → 638 行（+337 行，重写）
|
||
|
||
## 不破坏的现有功能
|
||
|
||
- 日挑战进度追踪与领奖流程
|
||
- 本地排行榜 Top20
|
||
- 现有 5 种挑战类型 + 3 档难度
|
||
- 现有 localStorage keys（echo-nexus-beacon-lb-v1 / echo-nexus-beacon-prog-v1）
|
||
|
||
## 新增的 localStorage keys
|
||
|
||
- `echo-nexus-beacon-weekly-v1`（周挑战进度）
|
||
- `echo-nexus-beacon-chain-v1`（信标链状态）
|
||
|
||
## 四色全息规范遵循
|
||
|
||
- 周挑战主题：**fuchsia** (#e879f9)
|
||
- 信标链主题：**amber → rose** 渐变 (#fbbf24 → #fb7185)
|
||
- 领取按钮：**emerald** (#34d399)
|
||
- 难度色：routine emerald / anomaly amber / singular rose
|
||
- **零蓝色/靛色违规**
|
||
|
||
## 截图资产
|
||
|
||
- `/home/z/my-project/agent-ctx/beacon-panel-v0.8.png` — 初次进入信标页
|
||
- `/home/z/my-project/agent-ctx/beacon-chain-streak1.png` — chain streak=1 状态
|
||
- `/home/z/my-project/agent-ctx/beacon-chain-milestone3.png` — chain streak=3 milestone 可领取
|
||
- `/home/z/my-project/agent-ctx/beacon-milestone3-claimable.png` — milestone 3 领取前
|
||
- `/home/z/my-project/agent-ctx/beacon-final-fresh.png` — 重置后干净状态
|