# 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` — 重置后干净状态