文档
开发指南需求文档Building Public 打卡挑战系统设计文档

Building Public 打卡挑战系统设计文档

Building Public 21天打卡挑战系统的详细设计方案，包括现状分析、问题总结和改进计划

Building Public 打卡挑战系统设计文档

代码相关

📁 核心组件文件

主要页面组件

  • src/modules/dashboard/events/components/BuildingPublicPage.tsx
    • Building Public 活动的主页面
    • 包含活动信息、报名状态、打卡区域、社区动态
    • 布局：头部信息 → 报名/打卡区域 → 社区动态
  • src/modules/dashboard/events/components/BuildingPublicRegistration.tsx
    • 用户报名组件
    • 项目选择/创建、21天计划填写、押金设置
    • 用户资料完整性检查和建议

src/modules/dashboard/events/components/BuildingPublicCheckIn.tsx

  • 打卡功能组件
  • 新建打卡、编辑历史打卡、删除打卡
  • 打卡进度显示、分享功能
  • 历史打卡记录管理
  • src/modules/dashboard/events/components/BuildingPublicFeed.tsx
    • 社区动态展示组件
    • 打卡列表、参与者列表、统计数据
    • 筛选功能（按热度/最新、按用户）
    • 点赞、评论、分享功能

辅助组件

  • src/modules/dashboard/events/components/CheckInComments.tsx
    • 内联评论组件
    • 评论展示、提交、切换显示/隐藏
  • src/modules/dashboard/events/components/CertificateGallery.tsx
    • 证书展示组件（预留，当前未使用电子证书）

🔌 API 路由文件

主要 API 路由

  • src/server/routes/building-public.ts
    • 完整的 Building Public API 集合
    • 报名、打卡、获取数据、点赞、评论等所有功能

API 端点列表

// 报名相关 POST /events/:eventId/building-public/register GET /events/:eventId/building-public/registration

// 打卡相关
POST /events/:eventId/building-public/check-in GET /events/:eventId/building-public/check-ins GET /events/:eventId/building-public/my-check-ins PUT /building-public/check-ins/:checkInId DELETE /building-public/check-ins/:checkInId

// 参与者 GET /events/:eventId/building-public/participants

// 互动功能 POST /building-public/check-ins/:checkInId/like POST /building-public/check-ins/:checkInId/comments GET /building-public/check-ins/:checkInId/comments

🗄️ 数据库模型

Prisma Schema 相关表

  • BuildingConfig - Building Public 活动配置
  • BuildingRegistration - 用户报名记录
  • CheckInRecord - 打卡记录
  • CheckInLike - 打卡点赞
  • CheckInComment - 打卡评论
  • DepositTransaction - 押金交易记录

关键字段

// BuildingConfig duration: number // 挑战天数 (默认21天) requiredCheckIns: number // 最少打卡次数 depositAmount: number // 押金金额 enableVoting: boolean // 是否启用投票

// BuildingRegistration
plan21Days: string // 21天开发计划 visibilityLevel: enum // PUBLIC | PARTICIPANTS_ONLY checkInCount: number // 已打卡次数 isCompleted: boolean // 是否完成挑战

// CheckInRecord day: number // 第几天 title: string // 打卡标题
content: string // 打卡内容 likeCount: number // 点赞数 commentCount: number // 评论数

🎯 核心功能特性

  1. 报名系统
  • 作品关联（选择现有项目或创建新项目）
  • 21天开发计划制定（最少30字符）
  • 可见性设置（公开/仅参与者）
  • 押金设置（手动处理）
  • 用户资料完整性建议
  1. 打卡系统
  • 多次打卡：允许一天多次打卡
  • 历史编辑：可编辑和删除任何历史打卡
  • 内容要求：最少30字符
  • 自动标题：自动生成"第X天打卡"
  • 分享功能：一键复制分享内容
  1. 社区功能
  • 打卡动态：展示所有用户打卡
  • 参与者列表：显示报名用户和进度
  • 互动功能：点赞、内联评论
  • 筛选排序：按时间/热度，按用户筛选
  • 统计数据：参与者数、完成数、打卡数等
  1. 进度追踪
  • 打卡次数统计
  • 完成率计算
  • 进度条显示
  • 活跃贡献者排行

🔄 数据流

报名流程

用户 → BuildingPublicRegistration → API /register → 数据库 ↓ 检查项目所有权 → 创建报名记录 → 创建押金交易记录

打卡流程

用户 → BuildingPublicCheckIn → API /check-in → 数据库 ↓ 计算天数 → 创建打卡记录 → 更新打卡计数 → 刷新UI

动态展示流程

BuildingPublicFeed → API /check-ins → 数据库查询 ↓ 排序筛选 → 加载点赞状态 → 展示列表 → 实时互动

🎨 UI/UX 特点

布局设计

  • 响应式布局：桌面端左右分栏，移动端纵向排列
  • 卡片设计：使用 shadcn/ui Card 组件
  • 现代风格：简洁、清晰的界面设计

交互体验

  • 实时反馈：Toast 提示、加载状态
  • 内联编辑：历史打卡可直接编辑
  • 智能表单：自动保存、验证、重置
  • 一键操作：分享复制、快速打卡

这个 Building Public 系统是一个完整的21天挑战平台，支持报名、多次打卡、历史管理、 社区互动等功能，为开发者提供了一个"公开构建"的协作环境。

1. 系统概述

1.1 核心理念

Building Public 是一个21天线上打卡挑战活动，旨在：

  • 帮助开发者公开分享项目开发进度
  • 通过社区互动和督促机制提高项目完成率
  • 建立开发者之间的学习和交流氛围
  • 通过押金机制增强参与者的完成动机

1.2 基本流程

作品关联 → 活动报名 → 审核通过 → 押金支付 → 开始打卡 → 社区互动 → 完成评估 → 押金结算

2. 现状分析

2.1 已实现的功能

✅ 数据库设计

  • BuildingConfig 活动配置表
  • BuildingRegistration 报名记录表
  • CheckInRecord 打卡记录表
  • 基础的点赞和评论表

✅ 页面结构

  • BuildingPublicPage 主页面组件
  • BuildingPublicRegistration 报名组件
  • BuildingPublicCheckIn 打卡组件
  • BuildingPublicFeed 动态组件

✅ API接口

  • 基础的报名、打卡、获取动态接口
  • 存放在 /src/server/routes/building-public.ts

2.2 存在的主要问题

问题一：报名流程设计不合理 🚨

当前问题：

  • 报名时可以快速创建项目，但只要求填写标题和描述
  • 没有引导用户完善项目的完整信息
  • 没有与 /app/projects/create 页面的项目创建流程关联

应该的设计：

  • 报名时必须关联已有项目或引导用户到项目创建页面
  • 项目必须包含：作品名称、一句话介绍、详细描述
  • 其他项目信息（产品链接等）引导用户到专门的项目管理页面完善

问题二：页面结构过于分散 🚨

当前问题：

  • 使用 Tabs 切换，分为：活动概览、立即报名、每日打卡、社区动态、我的证书
  • 信息分散，用户需要多次点击才能看到重要内容

应该的设计：

  • 一个页面平铺所有信息，按优先级排列：
    1. 活动介绍和吸引点
    2. 立即报名按钮（突出显示）
    3. 报名者列表和进度统计
    4. 打卡动态流（类似朋友圈）
    5. 相关说明信息

问题三：没有复用活动审核功能 🚨

当前问题：

  • Building Public 有独立的报名审核逻辑
  • 没有利用现有的 Event 表的 requireApproval 字段和审核流程

应该的设计：

  • 复用现有活动系统的审核机制
  • 审核通过后才能进行押金支付和打卡操作

问题四：打卡系统设计不符合预期 🚨

当前问题：

  • 当前叫"每日打卡"，但实际不是每日要求
  • 没有实现类似评论系统的点赞、回复功能
  • 缺乏一键分享功能

应该的设计：

  • 就叫"打卡"（不是每日）
  • 类似微信朋友圈的交互：可以点赞、评论、回复
  • 统计打卡次数，达到要求次数即算完成
  • 一键按格式分享到社交媒体

问题五：用户引导不完善 🚨

当前问题：

  • 没有检查用户个人信息完整性
  • 没有引导用户完善 profile 信息

应该的设计：

  • 报名前检查用户是否完善了基本信息
  • 如未完善，引导到 /app/profile 页面

3. 改进设计方案

创建活动

在创建活动/app/events/create页面选择 build in public 活动类型之后的设置内容

📅 打卡挑战设置 配置 Building Public 打卡挑战的参数

  • 挑战持续的总天数，默认 21 天（不过其实好像也不用设置，毕竟 活动 都有 开始时间和结束时间的设置 hmmm todo）
  • 完成挑战需要的最少打卡次数, 默认 7
  • 押金金额， 默认 0
  • 押金返回规则： 默认为空

不需要保留原来的"每日目标描述"， 活动描述之类的字段， 直接在活动描述中描述活动规则即可（已经有了）

3.1 新的页面结构设计

Building Public 活动页面
┌─────────────────────────────────────┐
│ 🎯 活动介绍区域                      │
│ - 活动标题和核心卖点                 │
│ - 21天挑战规则说明                   │
│ - 持续时间                   │
│ - 押金机制和退还规则                 │
│ - [立即报名] 按钮（突出显示）         │
├─────────────────────────────────────┤
│ ℹ️ 活动详细说明（可展开查看详情）     │
│ - 押金机制详情                      │
│ - 奖励和证书说明                     │
│ - 常见问题解答                      │
├─────────────────────────────────────┤
│ 📊 挑战进度统计                      │
│ - 总参与人数                        │
│ - 完成目标人数比例                   │
│ - 平均打卡次数                      │
├─────────────────────────────────────┤
│ 👥 参与者列表                        │
│ - 报名者头像和项目信息 / 个人打卡进度条                     │
├─────────────────────────────────────┤
│ 📱 打卡动态流（核心区域）             │
│ -  按打卡人的筛选按钮             │
│ - 类似朋友圈的时间线展示             │
│ - 每条打卡包含：                     │
│   * 用户信息和项目信息               │
│   * 打卡内容（进度+截图+链接）        │
│   * 点赞和评论数                     │
│   * 互动按钮（👍点赞、💬评论、📤分享）│
│ - 分页加载更多                      │
└─────────────────────────────────────┘

3.2 报名流程重设计

Building Public 报名流程
┌─────────────────────────────────────┐
│ 第一步：检查用户信息                 │
│ - 检查 profile 是否完整              │
│ - 如不完整，引导到 /app/profile      │
├─────────────────────────────────────┤
│ 第二步：作品关联                     │
│ - 显示用户已有项目列表               │
│ - 选择已有项目 OR                   │
│ - [创建新项目] → 引导到 /app/projects/create │
├─────────────────────────────────────┤
│ 第三步：制定21天计划                 │
│ - 选定项目后回到报名页面             │
│ - 填写21天开发计划和目标[一个markdown编辑器，一个输入框即可]             │
│ - 选择打卡内容可见性                 │
│    ○ 完全公开 ● 仅报名者可见            │
├─────────────────────────────────────┤
│ 第四步：提交报名                     │
│ - 复用活动系统的审核流程             │
│ - 如需审核，等待组织者审核           │
│ - 审核通过后，进入押金支付流程        │
├─────────────────────────────────────┤
│ 第五步：押金支付（可选）             │
│ - 显示押金金额和退还规则             │
│ - 支付成功后可开始打卡               │
└─────────────────────────────────────┘

3.3 打卡系统重设计

3.3.1 打卡提交界面

打卡提交页面
┌─────────────────────────────────────┐
│ 第 X 次打卡 - 项目名称               │
│ 📅 当前日期: 2024年3月23日（这个是系统自动显示的）           │
│ 🎯 打卡进度: X/7 次  （这个是系统自动显示的）               │
├─────────────────────────────────────┤
│ 📝 本次进展：                        │
│ 标题: [近期完成了什么...]            │
│ 详细描述: [Markdown编辑器]           │
├─────────────────────────────────────┤
│ 📋 下一步计划: [Markdown编辑器]          │
├─────────────────────────────────────┤
│ [提交打卡] [一键分享]                │
└─────────────────────────────────────┘

3.3.2 打卡动态展示

打卡动态卡片
┌─────────────────────────────────────┐
│ [头像] 张三（链接到 /zh/u/[id]） | AI写作助手（链接到 /zh/project/[id]）              │ 
│ 第5次打卡 · 2小时前                  │
├─────────────────────────────────────┤
│ 📝 完成了用户对话管理模块             │
│                                     │
│ 今天主要实现了用户会话的持久化存储... │
├─────────────────────────────────────┤
│ 👍 12人点赞 | 💬 3条评论 | 📤 分享    │
├─────────────────────────────────────┤
│ 💬 评论区域:                         │
│ [头像] 李四: 界面做得不错，什么技术栈？│
│ [头像] 王五: 期待演示！               │
│ [回复输入框]                         │
└─────────────────────────────────────┘

3.4 技术实现要点

3.4.1 与现有系统的集成

// 复用活动审核系统
interface BuildingPublicEvent extends Event {
  type: "BUILDING_PUBLIC"
  requireApproval: boolean // 复用活动审核
  buildingConfig: BuildingConfig
}

// 报名状态与活动注册状态统一
interface BuildingRegistration {
  eventRegistrationId: string // 关联到 EventRegistration
  projectId: string
  developmentPlan: string
  // ... 其他字段
}

3.4.2 数据库模型调整

-- 调整 BuildingRegistration 表
ALTER TABLE building_registration 
ADD COLUMN event_registration_id STRING REFERENCES event_registration(id);

-- 确保与活动注册表的关联
-- 复用 EventRegistration 的 status 字段进行审核状态管理

3.4.3 API 接口调整

// 统一报名接口
POST /api/events/{eventId}/register
{
  // 普通活动字段
  ticketTypeId?: string
  answers?: Array<{questionId: string, answer: string}>
  
  // Building Public 特有字段
  projectId?: string
  developmentPlan?: string
  visibilityLevel?: "PUBLIC" | "PARTICIPANTS_ONLY"
}

// 打卡接口优化
POST /api/events/{eventId}/check-ins
{
  title: string
  content: string
  nextPlan?: string
  imageUrls?: string[]
  demoUrl?: string
  isPublic: boolean
}

// 打卡互动接口
POST /api/check-ins/{checkInId}/like
POST /api/check-ins/{checkInId}/comments

4. 实现计划

4.1 阶段一：修复现有问题（1-2天）

  1. 重构页面结构

    • 移除 Tabs 组件，改为单页面平铺
    • 调整信息架构，突出报名入口

  2. 完善报名流程

    • 集成项目创建流程
    • 添加用户信息完整性检查
    • 复用活动审核系统

  3. 优化打卡系统

    • 重命名为"打卡"而非"每日打卡"
    • 实现类似朋友圈的交互界面

4.2 阶段二：增强功能（2-3天）

  1. 完善社交功能

    • 实现点赞、评论、回复功能
    • 添加一键分享功能
    • 优化动态流展示

  2. 改进用户体验

    • 添加进度统计和排行榜
    • 优化移动端体验
    • 添加消息通知

4.3 阶段三：系统集成（1天）

  1. 测试和优化
    • 端到端流程测试
    • 性能优化
    • 错误处理完善

5. 现有代码文件分析

5.1 需要重构的文件

src/modules/dashboard/events/components/
├── BuildingPublicPage.tsx          # 需要重构：移除 Tabs，改为单页面
├── BuildingPublicRegistration.tsx  # 需要重构：集成项目创建流程
├── BuildingPublicCheckIn.tsx       # 需要重构：优化打卡界面
└── BuildingPublicFeed.tsx          # 需要重构：实现朋友圈式交互

src/app/(public)/[locale]/events/[eventId]/
└── EventDetailsClient.tsx          # 需要调整：优化 Building Public 页面容器

src/server/routes/
└── building-public.ts              # 需要完善：API 接口优化

5.2 需要新增的文件

src/modules/dashboard/events/components/
├── BuildingPublicCheckInCard.tsx   # 新增：单个打卡内容卡片
├── BuildingPublicStats.tsx         # 新增：统计信息组件
└── BuildingPublicParticipants.tsx  # 新增：参与者列表组件

src/modules/dashboard/projects/components/
└── ProjectQuickCreate.tsx          # 新增：快速创建项目组件

6. 系统集成设计

6.1 徽章系统集成

使用现有的 Badge + UserBadge 系统：

  • Building Public 完成徽章 - 完成最少打卡次数的用户自动获得
  • 最受欢迎项目徽章 - 根据点赞数最多的项目颁发

自动颁发逻辑：

// 活动结束后检查完成情况
if (userCheckInCount >= requiredCheckIns) {
  // 自动颁发完成徽章
  await awardBadgeToUser(userId, 'building-public-completion');
}

// 根据点赞数颁发最受欢迎项目徽章
const topProject = await getTopLikedProject(eventId);
if (topProject) {
  await awardBadgeToUser(topProject.userId, 'building-public-popular');
}

6.2 边界情况处理

活动结束状态：

  • 活动进行中: 正常显示打卡界面
  • 活动结束: 显示"活动已结束"状态，禁止新打卡
  • 完成用户: 显示获得的徽章和完成统计
  • 未完成用户: 显示未完成提示
  • 押金处理: 显示相关说明，实际处理由管理员人工操作

6.3 配置简化

移除重复字段：

  • 移除 challengeDays 字段，直接使用活动 startTime 和 endTime 计算
  • 移除 dailyGoal 字段，在活动描述中说明即可
  • 保留 requiredCheckIns、depositAmount、refundRate 核心配置

7. 相关代码文件

7.1 需要修改的现有文件

前端组件：

  • /src/modules/dashboard/events/components/EventCreateForm.tsx - 简化 Building Public 配置
  • /src/modules/dashboard/events/components/BuildingPublicPage.tsx - 重构为单页面布局
  • /src/modules/dashboard/events/components/BuildingPublicRegistration.tsx - 作品关联流程
  • /src/modules/dashboard/events/components/BuildingPublicCheckIn.tsx - 简化打卡界面
  • /src/modules/dashboard/events/components/BuildingPublicFeed.tsx - 朋友圈式交互

数据库操作：

  • /src/lib/database/prisma/queries/events.ts - 移除重复字段处理
  • /src/lib/database/prisma/schema.prisma - 调整 BuildingConfig 模型

API 路由：

  • /src/server/routes/building-public.ts - 完善 API 接口
  • /src/server/routes/events.ts - 活动创建逻辑调整

7.2 需要新增的文件

组件文件：

  • /src/modules/dashboard/events/components/BuildingPublicStats.tsx - 统计信息组件
  • /src/modules/dashboard/events/components/BuildingPublicParticipants.tsx - 参与者列表
  • /src/modules/dashboard/events/components/BuildingPublicCheckInCard.tsx - 打卡卡片组件
  • /src/modules/dashboard/projects/components/ProjectQuickCreate.tsx - 快速创建项目

徽章相关：

  • 在现有 Badge 表中添加 Building Public 相关徽章数据
  • 完善徽章自动颁发逻辑

8. 实现优先级

Phase 1: 基础优化 (1-2天)

  1. ✅ 移除重复的 challengeDays 字段，使用活动时间计算
  2. ✅ 简化 EventCreateForm 的 Building Public 配置
  3. ✅ 重构 BuildingPublicPage 为单页面布局

Phase 2: 功能完善 (2-3天)

  1. ✅ 实现活动结束边界处理
  2. ✅ 集成徽章系统（完成徽章 + 最受欢迎项目徽章）
  3. ✅ 优化报名流程（用户信息检查 + 作品关联）

Phase 3: 交互增强 (1-2天)

  1. ✅ 实现打卡内容的点赞、评论、回复功能
  2. ✅ 实现打卡统计和按人筛选功能
  3. ✅ 实现打卡内容导出分享功能

结论

经过讨论确认的优化方案重点：

  1. 简化配置 - 使用活动时间，移除重复字段
  2. 徽章集成 - 两个简单徽章（完成 + 最受欢迎）
  3. 边界处理 - 活动结束显示状态，人工处理押金
  4. 系统集成 - 深度集成现有的项目、用户、徽章系统

这个方案在保持功能完整性的同时，避免了过度复杂的设计，确保与现有系统的良好集成。

  • 社区认可机制

6.3 内容质量

  • 优质打卡内容推荐
  • 项目展示优化
  • 知识分享机制

结论

现有的 Building Public 实现在技术架构上基本正确，但在用户体验和业务流程设计上存在较大偏差。主要问题集中在：

  1. 页面结构分散 - 需要整合为单页面体验
  2. 报名流程不完善 - 需要与项目系统深度集成
  3. 打卡系统功能单薄 - 需要增强社交互动功能
  4. 没有复用现有审核机制 - 需要与活动系统统一

建议按照上述改进方案，优先解决用户体验问题，再逐步完善功能细节。这样可以确保系统既符合原始设计意图，又能提供良好的用户体验。

活动通信系统

Previous Page

社区三种活动模板系统开发需求文档

社区需要建立三种固定活动类型的标准化模板系统，以提高活动组织效率和参与体验