# Time-Capsule

**Repository Path**: caistudio/time-capsule

## Basic Information

- **Project Name**: Time-Capsule
- **Description**: 面向6-12岁小学生家庭的开学仪式感工具，通过可视化网页实现"父母寄语→孩子心愿→封存→学期末开启"的完整时光胶囊体验。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-02
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎁 新学期时光胶囊

一个面向6-12岁小学生的开学仪式感Web应用，通过可视化网页实现"父母寄语→孩子心愿→封存→学期末开启回顾"的完整时光胶囊体验。

## ✨ 核心功能

### 💌 父母创建胶囊
- **手绘主题选择** - 3个精美主题（星空🔭/花园🌱/城堡🏰）
- **父母寄语模板** - 12个精选模板快速创建温馨寄语
  - 鼓励类：成长期待、相信自己、努力加油
  - 成长类：快乐成长、全面发展、独立自主
  - 关爱类：温暖陪伴、珍惜时光、感恩之心
  - 未来类：梦想启航、探索发现、展望未来
- **自由编辑** - 可参考模板自由修改（10-500字）
- **学期选择** - 智能选择年级和学期，自动计算解锁时间
- **时间设定** - 下学期7月1日解锁，上学期次年2月1日
- **访问密码** - 可选的密码保护功能（4-20位）

### ⭐ 孩子填写心愿
- **查看寄语** - 打开胶囊查看父母的期望
- **心愿填写** - 填写3个新学期心愿（每个最多50字）
- **模板引导** - 4类9个心愿模板，一键填充
  - 学习类：阅读计划、提高成绩
  - 运动类：学习技能、每日运动
  - 才艺类：才艺练习、舞台表演
  - 品质类：帮助他人、勇敢尝试
- **胶囊封存** - 填写完成后封存，等待学期末开启
- **邮件通知** - 可选邮箱订阅，解锁时自动发送通知邮件

### 🎊 学末回顾成长
- **心愿回顾** - 查看学期初的心愿
- **完成勾选** - 勾选已完成的心愿
- **添加感悟** - 为每个心愿添加完成感悟
- **学期总结** - 写下学期末总总结
- **纪念卡片** - 生成精美的成长纪念卡片

### 🔒 安全与限制
- **时间锁定** - 必须到达设定时间才能回顾
- **实时倒计时** - 精美的倒计时显示（天/时/分/秒）
- **密码保护** - 可选的访问密码验证
- **设备限制** - 每台设备每天最多创建5个胶囊

## 🎨 主题设计

### 🔭 探索星空
- 宇宙主题，深邃蓝色调
- 星星、行星、火箭元素
- 激发探索和好奇心

### 🌱 魔法花园
- 自然主题，清新绿色调
- 花朵、树叶、蝴蝶元素
- 象征成长和生命力

### 🏰 梦想城堡
- 城堡主题，梦幻粉紫色调
- 城堡、皇冠、魔法元素
- 寓意梦想和公主王子

## 🛠️ 技术栈

- **前端框架**: Next.js 14 (App Router) + React 18 + TypeScript
- **样式方案**: Tailwind CSS
- **动画库**: Framer Motion
- **后端API**: Next.js API Routes
- **数据库**: SQLite (better-sqlite3)
- **数据验证**: Zod
- **音效系统**: React Context + Web Audio API
- **邮件服务**: Nodemailer (飞书SMTP)

## 📦 项目结构

```
time-capsule/
├── app/                          # Next.js App Router
│   ├── api/                      # API路由
│   │   ├── capsules/             # 胶囊相关API
│   │   │   ├── route.ts          # 创建胶囊
│   │   │   └── [id]/route.ts     # 获取/更新胶囊
│   │   ├── cron/                 # 定时任务API
│   │   │   └── send-unlock-emails/ # 邮件推送cron端点
│   │   └── parent-message-templates/ # 父母寄语模板
│   ├── capsule/                  # 胶囊页面
│   │   └── [id]/
│   │       ├── page.tsx          # 胶囊详情/心愿填写
│   │       ├── review/           # 学末回顾
│   │       └── card/             # 纪念卡片
│   ├── create/                   # 创建页面
│   │   └── page.tsx              # 父母寄语输入
│   ├── layout.tsx                # 根布局
│   └── page.tsx                  # 主题选择首页
├── components/                   # React组件
│   ├── capsule/                  # 胶囊相关组件
│   │   └── TemplateSelector.tsx  # 心愿模板选择器
│   └── animations/               # 动画组件
│       └── PageTransition.tsx    # 页面过渡动画
├── lib/                          # 工具库
│   ├── db.ts                     # 数据库操作
│   ├── email.ts                  # 邮件发送服务
│   ├── validations.ts            # Zod数据验证
│   ├── themes.ts                 # 主题配置
│   ├── sounds.tsx                # 音效系统（React Hook）
│   └── utils.ts                  # 工具函数
│       └── 学期计算功能
├── database/                     # 数据库
│   ├── schema.sql                # 数据库schema
│   └── capsules.db               # SQLite数据库文件
├── scripts/                      # 脚本
│   └── fix-status.ts             # 状态修复工具
└── public/                       # 静态资源
    └── sounds/                   # 音效文件
        ├── click.mp3             # 点击音效
        ├── success.mp3           # 成功音效
        ├── seal.mp3              # 封存音效
        ├── open.mp3              # 打开音效
        └── error.mp3             # 错误音效
```

## 🚀 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 初始化数据库

```bash
# 数据库会在首次运行时自动初始化
npm run dev
```

### 3. 启动开发服务器

```bash
npm run dev
```

打开 [http://localhost:3000](http://localhost:3000) 查看应用。

### 4. 构建生产版本

```bash
npm run build
npm start
```

## 📚 可用脚本

| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm run build` | 构建生产版本 |
| `npm start` | 启动生产服务器 |
| `npm run lint` | 运行 ESLint |

## ⚙️ 邮件推送配置

### Cron Job设置

为了自动发送解锁通知邮件，需要设置定时任务调用 `/api/cron/send-unlock-emails` 端点。

**Linux Cron设置示例**：
```bash
# 每小时检查一次并发送邮件
0 * * * * curl https://your-domain.com/api/cron/send-unlock-emails
```

**Windows Task Scheduler**：
```powershell
# 创建每小时运行一次的任务
schtasks /create /tn "时光胶囊邮件推送" /tr "curl https://your-domain.com/api/cron/send-unlock-emails" /sc hourly
```

**Vercel Cron Jobs** (vercel.json)：
```json
{
  "crons": [
    {
      "path": "/api/cron/send-unlock-emails",
      "schedule": "0 * * * *"
    }
  ]
}
```

### 环境变量配置

创建 `.env.local` 文件配置以下变量：

```env
# 应用URL（用于邮件中的链接）
NEXT_PUBLIC_APP_URL=https://your-domain.com

# Cron密钥（可选，用于保护cron端点）
CRON_SECRET_KEY=your-secret-key
```

邮件服务器配置已内置在 `lib/email.ts` 中（飞书SMTP）。

## 🌟 特色设计

### 🎯 用户体验
- **手绘风格** - 温暖可爱的插画风格，适合6-12岁儿童
- **流畅动画** - Framer Motion驱动的页面过渡和交互动画
- **音效反馈** - 关键操作音效增强沉浸感
- **响应式设计** - 完美支持手机、平板、电脑

### 🔐 安全机制
- **设备限制** - 每台设备每天最多创建5个胶囊
- **时间锁定** - 封存后必须到设定时间才能回顾
- **密码保护** - 可选的访问密码保护隐私

### 📚 智能辅助
- **学期选择** - 小学1-6年级上下学期智能选择
- **自动计算** - 根据学期自动设置合理的解锁时间
- **模板引导** - 9个精选心愿模板，降低填写难度
- **实时验证** - 表单输入实时验证和提示

## 📊 数据模型

### 胶囊状态流转
```
created (已创建)
    ↓ 孩子填写心愿并封存
sealed (已封存)
    ↓ 等待解锁时间
opened (已解锁)
    ↓ 完成回顾
completed (已完成)
```

### 学期解锁规则
- **下学期** (spring) → 当年7月1日 9:00 解锁
- **上学期** (fall) → 次年2月1日 9:00 解锁

## 🎯 开发路线

### ✅ Phase 1 - MVP (100%)
- [x] 项目初始化和配置
- [x] 数据库设计和实现
- [x] 主题选择页面
- [x] 父母寄语输入
- [x] 创建API

### ✅ Phase 2 - 核心流程 (100%)
- [x] 孩子打开胶囊
- [x] 心愿填写（含模板）
- [x] 胶囊封存功能
- [x] 解锁验证系统

### ✅ Phase 3 - 完整体验 (100%)
- [x] 学末回顾功能
- [x] 纪念卡片生成
- [x] 完整动画效果

### ✅ Phase 4 - 优化增强 (100%)
- [x] 性能优化
- [x] 学期选择功能（智能推荐）
- [x] 父母寄语模板（12个精选模板）
- [x] 实时倒计时（天/时/分/秒）
- [x] 音效系统
- [x] 设备限制
- [x] Bug修复（孩子填写心愿问题）
- [ ] SEO优化
- [ ] 无障碍访问

## 🐛 已知问题

暂无已知问题。

## 📄 许可证

本项目采用 MIT 许可证。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📮 联系方式

项目地址: [https://gitee.com/littlejcai/time-capsule](https://gitee.com/littlejcai/time-capsule)

---

**🎉 让我们一起为孩子创造有意义的开学仪式！**