# 投票系统重构 · 完整方案

## 核心规则变更

| 维度 | 旧 | 新 |
|---|---|---|
| 单用户额度 | 每日 10/12 票(跨日重置) | **终身 12 票**(永不重置) |
| 单艺人上限 | 不限 | **每位艺人最多 1 票** |
| 单次投票数 | 可选 1/3/5/ALL | **固定 1 票** |
| 时间窗 | 有 startAt/endAt 倒计时 | **无时间限制** |
| 用户最终行为 | 累积投出 N 票 | **必须选出 12 个不同艺人** |
| 可撤销 | — | **不可撤销** |

## 设计决策(已拍板默认值)

- **A. Hero 进度条**: 12 格点亮式(已投亮紫, 未投暗紫边框, 横向排开)
- **B. VoteModal 确认按钮文案**: `投出我的一票`
- **C. 已投艺人卡片角标**: 右上角紫色 ✓ 圆角标(20px), 阴影柔和
- **D. 持久化**: zustand persist + localStorage(仅 `votedArtists` 字段)

## 本 loop 执行范围

**只动前端**(Store + Hooks + 组件 + 新组件)。
**后端 API/Schema 不动** —— 风险大需要单独迁移, 留给后续 commit。
前端 Store 强制阻止重复投票, API 即使旧的也能正常工作。

---

## 阶段 1 · Store 重构(单文件改重)

### `src/lib/store.ts`

- 删 `DAILY_VOTE_QUOTA = 10` 常量
- 新增 `export const TOTAL_VOTE_QUOTA = 12` 常量
- 删 `usedToday`, `quotaDate` 字段
- `myVotesByArtist: Record<string, number>` → `votedArtists: string[]`
- `MySupport` 接口删 `votedCount` 字段, 只留 `artist`
- `vote(id, count)` → `vote(id): { ok: boolean; reason?: "already" | "exhausted" }`
- `selectRemaining` = `TOTAL_VOTE_QUOTA - votedArtists.length`
- 新增 `selectHasVoted(id)` 高阶函数, 返回 `(s: VoteStore) => boolean`
- 新增 `selectIsExhausted(s) => votedArtists.length >= 12`
- 删 `todayKey()` 函数
- 重写 `selectMySupports` 基于 `votedArtists` 派生
- **加 persist 中间件**:
  - `import { persist } from "zustand/middleware"`
  - 仅持久化 `votedArtists`(partialize)
  - storage key: `cyber-star-vote`

---

## 阶段 2 · 交互闭环

### `src/hooks/useVoteAction.ts`

- import 改用 `TOTAL_VOTE_QUOTA` + `selectHasVoted`
- 接口 `confirmVote(artist, count)` → `confirmVote(artist)`(去 count)
- `openVote` 新增检查: `selectHasVoted(artist.id)` → toast `"你已为 ${artist.name} 投过票"` + abort
- `openVote` `remaining <= 0` 时 toast 改 `"你的 12 票已用完, 感谢支持"`
- `confirmVote` 调用 store.vote 不传 count
- API POST body 去掉 count(`{ artistId }`)
- 成功 toast: `"已为 ${artist.name} 投票 · 剩余 X 票"`
- 第 12 票投完瞬间额外 toast: `"完成!你的 12 票已全部投出"`(里程碑)

### `src/components/VoteModal.tsx`

- 删 `VOTE_OPTIONS` 数组 / `defaultOption` / `resolveCount` / `selected` state
- 删 1/3/5/ALL 选择 grid 整块
- props 去掉 `remaining` 依赖(保留显示用), `dailyQuota` 字段名保留语义改为 totalQuota
- 标题保留 "为 X 投票"
- 副标题保留 `No.${no} · Current Rank #${rank}`
- **新增警示文案**: `"投出后不可撤销, 每位艺人仅能投 1 票"`
- 显示 "剩余 X / 12 票"
- 确认按钮: **`投出我的一票`** (loading 时显示 spinner)
- 已投态(打开时若 hasVoted=true): 标题改 "你已为 TA 投过票了" + 关闭按钮唯一
- 用完态(remaining=0): 标题改 "12 票已用完 · 感谢支持"

---

## 阶段 3 · 已投态 UI(可 sub-agent 并行 3-4 个文件)

### `src/components/cards/ArtistCard.tsx`

- import `selectHasVoted`
- `const hasVoted = useVoteStore(selectHasVoted(artist.id))`
- 投票按钮已投态: `✓ 已投票`, 灰禁用 (`bg-elevated text-white/45 border border-white/10`)
- 卡片右上角加紫色 ✓ 角标(20×20px, `bg-purple-500 rounded-full shadow-purple-glow`), `absolute top-2 right-2 z-10`

### `src/components/ranking/RankingRow.tsx`

- import `selectHasVoted`
- 同样的 hasVoted 判断
- 按钮已投态: `✓ 已投`, 灰禁用
- **顺便修复**: 移除非 Top12 的 `opacity-[0.78]` 暗化(用户已要求过)

### `src/components/artist/ArtistDetailContent.tsx`

- HeroPanel 内的投票按钮: hasVoted → 文案 `✓ 已投票`, `disabled` prop, 紫色淡化
- 头像下方加 ✓ 角标(同 ArtistCard 风格)

### `src/components/FloatingVoteButton.tsx`

- props 新增 `disabled?: boolean`
- disabled=true: Heart 改 Check, 文案改 `已投`, 样式灰
- 调用方 ArtistDetailContent: 透传 `disabled={hasVoted}`

---

## 阶段 4 · 新建 HeroVoteProgress 替换倒计时

### 新建 `src/components/HeroVoteProgress.tsx`

视觉: 12 个小圆点 / 方块横排, 已投亮紫(`bg-purple-500 shadow-purple-glow`), 未投暗紫(`bg-purple-500/15 border border-purple-500/40`)。

```
你的投票  ·  5 / 12
● ● ● ● ● ○ ○ ○ ○ ○ ○ ○
```

状态机:
- 未登录: `登录后开始投票` + 点击触发 LoginModal(用 useLoginModalStore)
- 已投 0/12: 显示标题 "你的投票 · 0 / 12" + 12 格全暗
- 投票中(1-11): 标题 + 进度格子 + 副文案 "还可投 X 位艺人"
- 已投满 12/12: 标题 + 12 格全亮 + ✓ 图标 + 文案 "12 票全部投出 · 感谢支持"

样式约束:
- 紧凑模式, 高度 ≤ 80px(替换原 Countdown 位置)
- 半透明背景 + backdrop-blur(与原 Countdown 视觉一致)
- 文字白色, 进度紫色

### `src/components/HeroBanner.tsx`

- 删 `endTime` prop 和接口字段
- 删 `import Countdown`
- 删右上角倒计时整块
- 替换为 `<HeroVoteProgress />` (位置不变, 右上角)
- 不要删 Countdown.tsx 文件(可能其他场景用)

### `src/app/page.tsx`

- 删 `import { getActivityEndTime }` 和 `const endTime` 行
- `<HeroBanner>` 调用去掉 `endTime` 属性

---

## 阶段 5 · /me 页 + Badge

### `src/components/auth/RemainingVotesBadge.tsx`

- 文案 `今日剩余 X / 10` → `剩余 X / 12`
- 注释 "今日剩余票数" → "剩余票数"
- 未登录显示 `0 / 12`

### `src/components/me/QuotaCard.tsx`

- 标题 `今日剩余票数` → `剩余票数`
- 删 `明日 00:00 重置为 X 票` 整行
- 副文案改 `共 12 票 · 用满完成投票`(已投完则 `12 票全部投出 · 感谢支持`)
- props `dailyQuota` 保留(语义改为 totalQuota, 不重命名避免大面积改动)

### `src/components/me/StatsGrid.tsx`

- 新规则下 "累计投票" 和 "应援艺人" 永远相等 → 删一个
- 改为单 stat 组合: `已投 X / 12 票` + `剩余 12-X 票`(两格)
- 图标 Sparkles → Check(已投), Star → Heart(剩余)

### `src/components/me/MyFanSupport.tsx`

- 移除 `votedCount` 引用
- "已投 X 票" → 紫色 ✓ 徽章 + 文案 "已投票"
- 空态文案: `还没有应援的艺人` → `还没有投过票 · 去为你喜欢的艺人投出第一票`

### `src/app/me/MeContent.tsx`

- `myVotesByArtist` 引用全改 `votedArtists`
- supports useMemo 派生逻辑改为遍历 `votedArtists`
- `myTotalVotes` 改 `votedArtists.length` 或直接删, 用 `.length`
- 传 StatsGrid 的 props 改: `voted={N}` `remaining={12-N}`

---

## 阶段 6 · 验证

### 浏览器手动验证

1. 首页 Hero 区域显示 HeroVoteProgress, 12 格状态正确
2. 点首页某艺人 "投票" → 弹窗显示新文案, 点 "投出我的一票" → toast 成功 + Hero 进度 +1
3. 再点同一艺人 → toast "你已为 TA 投过票", 弹窗不打开
4. 进入 /me 页 → QuotaCard 不显示 "明日重置", StatsGrid 显示新统计, MyFanSupport 显示 ✓ 徽章
5. 投满 12 票 → 触发里程碑 toast, 所有未投艺人按钮变灰禁用
6. 浏览器硬刷新 → votedArtists 从 localStorage 恢复, 已投态保持
7. 排行榜页 → 已投艺人按钮变灰, 未投可点
8. 详情页 HeroPanel 按钮 + FloatingVoteButton 都正确响应 hasVoted

### 编译验证

- dev server 已在 3000 跑着, 改一个文件就 hot-reload 一次, 不要重启
- 检查 dev server log 没有红色 ERROR
- 没有任何 TypeScript 错误(`grep -E "Type error|TS\d+" dev-server.log`)

---

## 阶段 7 · 收尾报告

完成后写报告 `docs/todo/voting-refactor-完成报告.md`, 列:

1. 改了哪些文件(完整列表)
2. 新建了哪些文件
3. 哪些功能验证通过, 哪些边界没测
4. 后续 backend 改动清单(schema unique 约束 / API 检查重投 / API 检查总额度)
5. 已知风险或 TODO

---

## 硬禁区(loop 必须遵守)

- 不要 git push 任何分支
- 不要动 `src/app/api/*` 任何 API route
- 不要动 `prisma/schema.prisma`
- 不要重启 dev server(3000 已经在跑, hot-reload 就行)
- 不要动 TOS 上传 / 视频文件 / 任何资源文件
- 不要碰 `package.json` / `next.config.js`