Color Walk V1 开发文档

来源：从 content/docs/PRD.md 提取并重组（仅保留 V1 开发相关内容）

1. V1 目标与边界

1.1 目标

• 验证“更丰富的打卡记录（照片 + 情绪）能否提升完成率与回访意愿”。

1.2 V1 功能范围

• 打卡流程支持可选图片上传（最多 9 张）。
• 打卡流程支持可选情绪标签（emoji + 英文文案）。
• 个人主页 My Color Walk 下新增 My Photos（个人照片墙）。
• 照片墙支持按时间倒序 + 按颜色筛选。
• 照片墙支持历史补传、单图删除、换图、删除整次 walk。

1.3 非范围（不在 V1）

• 社区广场、颜色社区筛选页、点赞（这些在 V1.5）。
• 批量删图（V1 仅支持单图删除和整次 walk 删除）。
• 前端可见性切换（V1 后端强制 private）。

2. 信息架构与页面

2.1 个人主页 IA（V1）

• 一级：My Color Walk / Setting
• 二级（左栏）：My Palette、My Photos
• 内容区：
  • My Palette：统计 + 色板
  • My Photos：按 walk 分组照片墙

2.2 照片墙展示模型

• 展示单位是“单次 walk 图组”，不是单图平铺。
• 默认按时间倒序（最新在前）。
• 支持按颜色筛选图组。
• 图组卡片信息：
  • 颜色色块 + 颜色名
  • 打卡时间
  • 该 walk 的多图拼贴预览（1-9）
  • N photos
  • 情绪（可空）

3. Check-in 内联面板（V1）

3.1 面板结构

• 颜色信息区
• 照片上传区
• 情绪标签区
• 操作区（Complete check-in / Cancel）

3.2 图片上传规则

• 最多 9 张。
• 单张上限 5MB，总计上限 45MB。
• 格式：jpg/jpeg/png/webp/heic/heif（不支持 gif/svg）。
• 支持文件选择 + 网页端拖拽。
• 不支持移动端直接拍照。

3.3 拖拽与提交约束

• 拖入超 9 张：整批拒绝并提示。
• 拖入文件夹：忽略并提示。
• 有文件上传中：禁用 Complete check-in。
• 有失败图片：允许删失败项后继续提交。
• 提交失败：面板不收起，保留已选图片和情绪。

3.4 媒体处理

• 客户端压缩：长边约 2048。
• JPEG 压缩参数固定：quality=0.82。
• heic/heif 统一转 jpeg。
• 去除 EXIF。
• 保留用户上传顺序。

3.5 情绪标签规则

• 可不选。
• 单选，可取消（再次点击已选项）。
• 存储枚举：
  • calm
  • excited
  • healed
  • grateful
  • lazy
  • melancholy
• 展示文案：
  • 😌 Calm
  • 🤩 Excited
  • 🫶 Healed
  • 🙏 Grateful
  • 😴 Lazy
  • 😔 Melancholy

4. My Photos 交互（V1）

4.1 查看

• 点击图组任意图进入 Lightbox 弹窗。
• 弹窗定位到被点击图片。
• 支持组内逐张切换（上一张/下一张）。
• 显示序号（如 2/6）。
• 展示元信息：颜色、时间、情绪（可空）。
• Esc 关闭，左右方向键切图。

4.2 编辑

• 历史补传：可追加图片到已有 walk。
• 单图删除：允许删到 0 张（walk 记录保留）。
• 换图：上传新图 + 删除旧图。
• 删除整次 walk：前端二次确认；提示“将删除该 walk 关联全部图片与记录”。
• 不支持批量删图。

5. 数据模型（V1）

5.1 checkins

• 必备字段：
  • id
  • user_id
  • color_id
  • created_at
  • has_photo
  • photo_count
  • emotion_tag（可空）
  • visibility（private|public）
• V1 规则：
  • 服务端强制 visibility=private
  • photo_count 默认 0
  • has_photo 与 photo_count 一致

5.2 checkin_photos（V1 新增）

• 建议字段：
  • id
  • checkin_id
  • user_id
  • object_key
  • url
  • sort_order
  • mime_type
  • size_bytes
  • width（可空）
  • height（可空）
  • created_at
  • updated_at
  • deleted_at（可空）
• 规则：
  • 图片二进制只在 R2，不入数据库。
  • 单图/整次删除后回写 photo_count 与 has_photo。
  • 删到 0 张时 has_photo=false。

6. 存储与可见性（R2）

6.1 存储策略

• 使用 Cloudflare R2。
• 复用现有 bucket，不新建 bucket。
• 路径隔离：
  • avatars/...
  • colorwalk/checkins/{userId}/{checkinId}/{photoId}.{ext}

6.2 可见性策略

• V1 全部 private（后端强制）。
• 用户始终可见自己的 private 图片。
• private 图片通过 Signed URL 访问：
  • TTL = 10 分钟
  • 过期后前端静默重签，用户无感知

6.3 去重策略

• Color Walk 上传不做去重（跨用户/跨 checkin/同 checkin 均不去重）。
• 每次上传生成独立对象 key，避免删除与权限耦合。

6.4 上传中断与回收

• 页面存在上传中/未提交变更时，离开前需提示未保存会丢失。
• 未绑定临时对象延迟清理：
  • 24 小时后清理
  • 清理任务每 6 小时执行一次

7. API Contract（V1）

7.1 接口清单

• POST /api/colorwalk/photos/upload
  • 上传图片到 R2，返回临时资源，不直接绑定 checkin。
• POST /api/colorwalk/checkin/complete
  • 完成打卡 + 绑定图片 + 写入情绪。
• GET /api/colorwalk/checkins/:checkinId/photos
  • 获取该 walk 图片（private 返回 Signed URL）。
• POST /api/colorwalk/checkins/:checkinId/photos
  • 历史补传（绑定临时图片）。
• DELETE /api/colorwalk/checkins/:checkinId/photos/:photoId
  • 删除单图并回写统计。
• DELETE /api/colorwalk/checkins/:checkinId
  • 删除整次 walk（级联删除 checkin + checkin_photos + R2 对象）。

7.2 核心请求字段

• 上传：files[]（multipart/form-data）
• 完成打卡：
  • checkinId
  • colorId
  • sessionId
  • emotionTag?
  • tempPhotoIds[]?
• 历史补传：tempPhotoIds[]

7.3 核心响应字段

• 上传：tempPhotos[]（tempId, objectKey, mimeType, sizeBytes, width, height）
• 完成打卡：stats, paletteCounts, photoCount, emotionTag
• 查询图片：photos[]（photoId, signedUrl, objectKey, sortOrder, mimeType, sizeBytes）

7.4 权限校验

• 补传/换图/删图/删 walk 仅允许 checkin 所属用户。
• 服务端必须校验 user_id + checkin_id。

8. 验收指标（V1）

• 有照片打卡占比 ≥ 30%
• 有情绪标签打卡占比 ≥ 40%
• 个人照片墙周访问率 ≥ 35%（活跃用户）

9. 建议开发顺序

1. 数据层：checkin_photos 与 checkins 字段收敛（含回写逻辑）。
2. 存储层：ColorWalk 专用上传接口（格式、压缩、转换、无去重）。
3. Check-in：内联面板上传 + 情绪 + complete 绑定。
4. My Photos：分组列表 + 筛选 + Lightbox。
5. 编辑能力：历史补传/单图删除/整次删除（二次确认）。
6. 私有访问：Signed URL + 静默重签。
7. 清理任务：未绑定临时对象回收（24h/6h）。