打卡契约 / ClockInPact

社交监督式打卡与 PK 系统，帮助小团体（2-6人）坚持完成长期目标。

功能

• 用户注册 - 支持用户名、密码、昵称，昵称按中文=1/英文数字=0.5计长
• 用户登录 - 支持"记住我"功能（7天免登录）
• 创建小组 - 名称2-20字符（中文=1，英文/数字=0.5），支持选择时区（默认UTC+8），自动生成5个一次性邀请码
• 加入小组 - 通过邀请码加入，支持挑战者/监督者角色，最多6人；加入时自动处理待确认目标的确认请求和待开始/进行中目标的参与
• 创建目标 - 支持目标名称、类别、达标条件、日期范围、奖惩规则、证据要求；时长阶梯校验
• 目标确认 - 全员确认机制，开始日期前需全员同意 + 至少1挑战者 + 1监督者
• 目标状态流转 - 待确认 → 待开始 → 进行中，定时任务自动作废未确认目标、自动激活待开始目标
• 修改/取消目标 - 任意成员发起修改或取消请求，全员24小时内投票确认；支持请求过期、拒绝、目标状态变更自动作废等边界处理
• 打卡记录 - 挑战者提交打卡数值和证据截图（1-5张，每张≤5MB），支持补卡（目标开始日期至今）；打卡记录提交后不可修改/删除
• 打卡审核 - 监督者审核打卡记录（确认/质疑），全体监督者确认后打卡生效；任一监督者质疑则标记为争议，需填写理由；超过3天未审核自动通过
• 进度查看 - 挑战者查看个人累计数值、完成百分比、剩余数值/天数；全员排行榜按完成百分比排名；类GitHub贡献图按天展示打卡数值，区分已确认/待审核/质疑状态
• 动态流 - 支持小组动态页面，按时间倒序展示并支持分页；已接入小组创建、成员加入、目标创建/确认、目标修改/取消请求发起与投票、请求结果、打卡提交、审核、打卡确认/自动通过、目标状态变更、自动同意、新挑战者自动参与、结算完成、时长阶梯解锁等动态
• 结算与归档 - 目标结束日期到达后自动进入待结算状态；监督者确认结算后系统判定各挑战者达标情况；达标者自动解锁更长周期（时长阶梯）；结算结果公示含完成数值、百分比、达标状态与奖惩规则；目标归档后历史记录可查

技术栈

• 框架: Nuxt 4 + Vue 3
• 数据库: PostgreSQL 16 + Prisma 7
• 样式: Tailwind CSS
• 认证: nuxt-auth-utils
• 文件存储: 本地文件系统（开发/测试）+ 腾讯云 COS（生产）
• 定时任务: node-cron
• 测试: Vitest

快速开始

1. 启动数据库

docker compose up -d

2. 配置环境变量

cp .env.example .env

编辑 .env，设置 NUXT_SESSION_PASSWORD（至少 32 位随机字符串）。

文件存储默认策略：

• NODE_ENV=production 时默认使用 COS
• 其他环境默认使用本地文件系统（public/uploads）
• 可通过 STORAGE_TYPE=local|cos 显式覆盖
• COS 模式默认按“私有桶 + 签名 URL”访问证据图片

生产环境最少需要配置：

• COS_SECRET_ID
• COS_SECRET_KEY
• COS_BUCKET（需包含 APPID，如 bucket-1250000000）
• COS_REGION（如 ap-shanghai）

可选配置：

• COS_SIGNED_URL_EXPIRES_IN_SECONDS：签名 URL 过期秒数（默认 900）

备案号展示（登录页和登录后首页底部中间）：

• NUXT_PUBLIC_SHOW_ICP_FILING：是否显示备案号（true/false）
• NUXT_PUBLIC_ICP_FILING_TEXT：备案号文本（例如：粤ICP备xxxxxxx号-1）
• NUXT_PUBLIC_ICP_FILING_LINK：备案链接（默认 https://beian.miit.gov.cn/）

3. 安装依赖

pnpm install

4. 初始化数据库

pnpm prisma migrate dev

5. 启动开发服务器

pnpm dev

访问 http://localhost:3000

常用命令

命令	说明
pnpm dev	启动开发服务器
pnpm build	构建生产版本
pnpm preview	预览生产构建
pnpm test	运行测试
pnpm prisma studio	打开数据库管理界面

文档

• 技术架构
• 开发指南