CafeDaily
03 · ROADMAP

下一步:重构落地的分阶段计划

这份路线图把 CafeDaily 从 brew-guide 到品牌化产品的重构拆成六个阶段。P0 已完成——你正在浏览它的产物。往后的每一步都写明具体动作、依赖关系与风险量级,好让评审能一段一段地拍板推进。

当前阶段P0 完成 → P1 待决策
关键关口设计方向 · token 存储
时间口径相对里程碑 · 粗估为主

注:下文所有周期均为工程量粗估,非承诺排期,以「相对里程碑」串联,前一阶段的产出是后一阶段的入口。

P0 · 已完成

00 设计原型与评审站上线

  • 确立 Brew Lab / 冲煮实验台 视觉主题:精密仪器语言,espresso / paper / crema / sage / garnet 五色语义,Fraunces + Space Mono 双字体。
  • 产出静态评审站 design.cafedaily.top——即本站:原型、统计、账户、TRD、架构、路线图六页,共用 /assets/app.css 语义 token 与组件库。
  • 沉淀设计契约:语义变量、可复用组件类、明暗主题、无障碍与 prefers-reduced-motion 基线。
已交付 4 页 · 单一样式表
P1 · 决策关口

01 确认设计方向

  • 评审 Brew Lab 提案:色板(crema 作数据辉光、sage 表新鲜/欠萃、garnet 表陈化/过萃)是否成立,是否与咖啡语义直觉一致。
  • 评审字体:Fraunces 衬线仅用于少量标题、Space Mono 承载全部数字/参数/标签,中文正文走系统栈——确认可读性与品牌调性。
  • 评审刻度盘/仪表语言:分段冲煮计时、赏味期徽章(fresh/peak/stale)、风味评分的表达方式。
  • 形成一页「设计决议」:锁定通过项、标记待改项,作为 P2 的唯一输入基准。
阻塞后续所有阶段 建议 1 次集中评审
P2 · 约 2–3 周(估)

02 设计系统落地到 Next.js 生产

  • 在生产仓引入语义 token:从 @theme / globals.css 起步,先建立与本站一致的变量层(bg / surface / ink / line / accent 等)。
  • 替换全站 4572 处硬编码 neutral-*(散布 179 文件):优先做低风险级联——把 neutral 灰阶映射到语义 token,而非逐组件手改,减少回归面。
  • 统一品牌入口:登录 / 注册 / logo 视觉对齐 Brew Lab;计时器等关键组件启用 crema 强调辉光。
  • 严格约束:不改业务逻辑,仅换外观层;Zustand stores 与 PWA 行为保持不变(数据源的服务端化在 P5 单独处理)。
  • 回归:明暗双主题(next-themes class dark)与无障碍(对比度、focus-visible、reduced-motion)全量走查。
级联替换,风险可控 明暗 + 无障碍必须回归 ~150K LOC · 501 文件
P3 · 约 1–2 周(估)

03 后端与数据对齐

  • 修复 schema ↔ 路由漂移:beans.js 读写 roastery / is_favorite / purchase_date / tasting_notes / description,但 01-schema.sql 的 coffee_beans 仅有 origin/region/estate/variety/process/roast_level/roast_date/capacity/remaining/price/notes——二选一:补齐建表列,或改路由字段映射。
  • 厘清关联:flavor_ratings 外键是 note_id 而非 bean_id,但 beans.js 却用 bean_id 查询——需纠正查询或补关联。
  • 补 bean_images 的 sort_order 列(当前按不存在的列排序),或改为按 created_at 排序。
  • 端到端联调 beans / notes / equipment / methods / grinders 全套 CRUD,验证多租户 user_id 隔离、软删除 deleted_at、分页 page/limit(<=100)、beans 的 search + favorite 过滤。
阻塞同步迁移(P5) 明显未端到端联调
P4 · 约 1 周(估)

04 认证加固

  • 补列:users 增加 role 与 avatar_url——JWT payload 已含 role、/me 已选 avatar_url,但表中尚无对应列。
  • 决断 sessions 表用途:当前 JWT 无状态、该表(token_hash/expires_at/revoked)未被使用——要么实现刷新令牌 + 吊销,要么删表止损。
  • 移除 JWT_SECRET 的不安全默认值 'default-secret-change-in-production',改为启动时强制校验环境变量。
  • 评估 token 存储策略:当前存 localStorage(key cafedaily_token,有 XSS 风险),对比 httpOnly cookie 方案。
  • 为 /api/auth(register/login)加速率限制,缓解暴力破解。
安全:默认密钥 + 无速率限制 token 存储需拍板
P5 · 约 2–3 周(估)

05 移除本地存储 → 服务端权威

  • 方向变更(本次评审确定):放弃 local-first,PostgreSQL 成为唯一事实来源——所有读写一律经 /api/* 落 PG;前端退化为瘦客户端。
  • 下线遗留 src/lib/supabase(23 文件,含 realtime)与把 IndexedDB 当权威存储的路径;Zustand 仅保留 UI/会话态。为老用户提供一次性迁移:把本地/Supabase 数据回填到 PG。
  • 把数据访问改为 API-first:引入请求级缓存(SWR / 内存)+ 乐观更新,替代原本的本地即时读写体验。
  • 坦诚的取舍——离线能力下降:原来离线可用,现在依赖网络。缓解:断网提示、失败重试、只读请求缓存;未来可选做只读离线缓存层。
  • 处理 401 契约:apiClient 清 token 并派发 auth:unauthorized,保证登出/重登顺滑。
用户明确要求的方向 依赖 P3 后端对齐 离线体验回退需缓解
P6 · 约 1 周(估)

06 上线与回归

  • 构建静态导出(output:'export' → out/),部署到服务器 ten 的 /var/www/html,nginx 静态托管 + /api/ 反代 Docker cafedaily-api:3001。
  • PWA 更新提示:Workbox service worker 换版后引导用户刷新,保证离线可用不失效。
  • 多端回归:Capacitor(iOS/Android)与 Tauri(mac/win/linux)壳内验证同步、认证与主题一致。
  • 接入监控 / 日志:利用 Docker json 日志滚动 + /api/health healthcheck,确认 certbot 续期与 CORS(限 https://cafedaily.top)生效。
正式对外发布 多端逐一回归
决策关口 · 需要你拍板的事

1 · 设计方向(P1 前置)。Brew Lab 的色板与字体是否定稿?若要调,现在改成本最低——一旦进入 P2 的 4572 处替换,回退代价陡增。

2 · token 命名约定。生产 @theme 里语义变量的命名与分层(是否 1:1 沿用本站的 --bg/--surface/--ink/--accent,还是引入更细粒度的组件级 token)——决定 neutral-* 映射表怎么写。

3 · 后端迁移节奏(P5)。Supabase → 自建后端是「一次性硬切」还是「双写过渡期」?过渡期越长,数据一致性维护成本越高,但风险更平滑——需要你定权衡。

4 · token 存储策略(P4)。继续 localStorage(实现简单、XSS 暴露)还是迁移到 httpOnly cookie(更安全、需处理 CSRF 与跨端 Capacitor/Tauri 兼容)?这关系到 P5/P6 的多端认证实现。