CYBER ✦ STAR

虚拟偶像 Top12 出道企划 · 投票网页

技术栈

层	选型
框架	Next.js 16（App Router）· React 19 · TypeScript
样式	Tailwind CSS v4（CSS-first `@theme`）· Framer Motion
字体	Megrim / Audiowide / Cinzel / Inter（全部 SIL OFL 商用免费）
数据库	MySQL 8 · Prisma 6 ORM
缓存 / 限流	Redis（`ioredis`，未配置时降级内存）
身份	Auth.js v5（手机号 OTP · 可扩展微信 / QQ）
校验	Zod
部署	火山引擎 ECS · 火山引擎 TOS（对象存储）

本地启动

pnpm install            # 安装依赖（自动 prisma generate）
cp .env.example .env    # 配置环境变量（首次）
pnpm dev                # http://localhost:3000

未配置数据库时，前端页面会回退到 src/lib/mock-data.ts 的 35 位艺人 mock 数据，UI 完全可用。

数据库初始化（部署时）

# 1. 创建 MySQL 库 + 在 .env 设置 DATABASE_URL
# 2. 推送 schema 到数据库
pnpm db:push

# 3. 灌入 35 位艺人 + 活动配置
pnpm db:seed

# 可视化管理（可选）
pnpm db:studio

关键脚本

命令	说明
`pnpm dev`	开发服务器（Turbopack）
`pnpm build`	生产构建（先 prisma generate）
`pnpm start`	生产服务器
`pnpm lint`	ESLint
`pnpm db:push`	把 schema 推到数据库
`pnpm db:migrate`	生成迁移脚本
`pnpm db:seed`	灌入种子数据
`pnpm db:studio`	Prisma Studio（GUI）

项目结构

prisma/
  schema.prisma         # 数据库 schema（10 个模型）
  seed.ts               # 初始化 35 位艺人

src/
  app/
    layout.tsx          # 根布局（含氛围装饰层）
    page.tsx            # 首页（Hero PV + Top12 + 35 卡片）
    artist/[id]/        # 艺人详情页
    ranking/            # 排行榜（Top3 podium + 出道线 + 候补区）
    me/                 # 个人中心
    login/              # 登录页（手机号 OTP）
    api/
      artists/          # GET 艺人列表 / 单个详情
      ranking/          # GET 实时排名
      vote/             # POST 投票（含风控限流 + 事务）
      me/               # GET 当前用户 / POST 签到
      auth/             # NextAuth handlers + send-otp
  components/
    Logo / Navigation / Footer / NavLinks
    HeroBanner / Top12Bar / ArtistFilters
    VoteModal / FloatingVoteButton / LiveBadge
    ui/                 # Button / Countdown
    cards/              # ArtistCard / ArtistPortrait
    artist/             # 详情页组件（视频 / 画廊 / 排名卡等）
    ranking/            # 排行榜组件
    me/                 # 个人中心组件
  hooks/
    useRanking.ts       # 实时排名轮询 hook
  lib/
    prisma / redis / rate-limit
    auth / current-user / api-response
    cn / mock-data / mock-user
  types/
    artist.ts

设计资料

交互原型：../交互原型线框图.html
视觉规范：../视觉规范.html · v1.1 紫调主导
需求文档：../需求分析文档.md
参考视觉：../参考图.png

团队需配置的外部服务

服务	用途	环境变量
MySQL（火山 RDS）	主数据库	`DATABASE_URL`
Redis（火山实例）	限流 / OTP 缓存 / 实时聚合	`REDIS_URL`
TOS（火山对象存储）	立绘 / 视频 / 头像	`TOS_*`
短信网关	手机号 OTP	`SMS_*`
微信开放平台	微信扫码登录	`WECHAT_APP_ID` `WECHAT_APP_SECRET`
hCaptcha	反作弊验证码	`HCAPTCHA_*`

详见 .env.example。所有这些都用 TODO 注释标记在代码中，可灰度配置 —— 没配置时功能自动降级。

开发态便利

登录：/login 页面下，开发环境接受万能验证码 123456
mock 用户 ：API 调用前自动落到 cs_user_id cookie，可在开发面板设置
mock 数据 ：未配 DB 时前端自动使用 mock-data.ts 的 35 位艺人
实时排名 ：API 不可用时静默回退到 mock 数据

设计原则

参考 ../视觉规范.html 的 16 个章节，核心：

紫罗兰为主调色（不是蓝），承担 CTA / 激活态 / 描边
装饰星标 ✦ 用于 Logo 中间，体现品牌签
TOP12 头像方形圆角（不是圆形）— "明星卡片"质感
VOTE NOW 紫色侧栏面板（不是普通按钮）— 视觉锚点
背景始终在深紫黑系，星点 + 紫雾装饰层
投票交互必须有动画仪式感

4.4 KiB Raw Blame History Unescape Escape

CYBER ✦ STAR

技术栈

本地启动

数据库初始化（部署时）

关键脚本

项目结构

设计资料

团队需配置的外部服务

开发态便利

设计原则

4.4 KiB

Raw Blame History