10 KiB
10 KiB
🎯 功能特性
-
🎨 现代化 UI/UX 设计
- 精美的动画 Logo，流畅过渡效果
- 毛玻璃卡片与背景模糊特效
- Framer Motion 驱动的丝滑动画
- 色彩编码的任务统计（蓝色、橙色、绿色）
-
🌓 主题支持
- 浅色模式，鲜艳渐变
- 深色模式，专业美学
- 系统主题自动检测
- 无缝主题切换
-
📱 响应式设计
- 桌面端优化的顶部导航标签
- 移动端友好的底部导航栏
- 触摸优化的交互元素
- 所有屏幕尺寸的自适应布局
-
⚙️ 个性化定制
- 多语言支持（中文和英文）
- 可自定义 Logo 文字
- 时区选择
- 主题模式偏好设置
-
📊 任务管理
- 创建、完成和删除任务
- 任务创建和完成时间戳
- 软删除（逻辑删除，保留数据）
- 按状态筛选任务（全部、进行中、已完成）
-
📊 交互式数据分析仪表盘
- 每日动态趋势图（创建 vs 完成）
- 任务完成时间轴（甘特图视觉效果）
- 实时 KPI 指标统计（总数、完成数、成功率）
- 灵活的时间范围选择（7天、一个月、所有时间）
-
🔐 访问控制
- 密码保护的任务操作（添加、编辑、删除）
- 客户端认证状态持久化
- 可通过环境变量配置密码
-
💾 数据持久化
- 本地 JSON 存储（无需数据库）
- 数据在应用重启后保留
- 完全可追溯的任务历史
🚀 快速开始
环境要求
- Node.js 18+ (本地开发)
- Docker (可选，用于容器化部署)
方案一：本地开发（推荐）
-
克隆仓库
git clone https://github.com/yourusername/stark-todo-list.git cd stark-todo-list -
安装依赖
npm install # 或 pnpm install -
启动开发服务器
npm run dev # 或 pnpm dev -
打开浏览器
http://localhost:3000
方案二：使用管理脚本
提供了便捷的 Shell 脚本用于轻松管理：
# 启动应用
./run.sh start
# 停止应用
./run.sh stop
# 重启并清理缓存
./run.sh restart
# 查看日志
./run.sh logs
# 检查状态
./run.sh status
方案三：Docker 部署
-
使用 Docker 启动脚本（推荐）
./docker-start.sh脚本会自动：
- 构建并启动 Docker 容器
- 自动显示后端日志
- 使用 Docker 卷进行数据持久化
-
快速更新（重新构建并重启）
./docker-update.sh此脚本会：
- 停止当前容器
- 拉取最新代码（如果是 Git 仓库）
- 重新构建 Docker 镜像（无缓存）
- 启动新容器
- 自动显示日志
-
配置访问密码（可选）
# 通过环境变量设置自定义密码 export AUTH_PASSWORD=your_custom_password # 或创建 .env 文件 echo "AUTH_PASSWORD=your_custom_password" > .env如未配置，默认密码为
stark123。 -
或手动使用 Docker Compose
# 使用 Docker Compose 启动 docker compose up -d --build # 查看日志 docker compose logs -f -
访问应用
http://localhost:4000 -
管理命令
# 停止容器 docker compose down # 重启容器 docker compose restart # 查看日志 docker compose logs -f # 快速更新（重新构建所有内容） ./docker-update.sh -
数据持久化与安全更新
- 数据存储在名为
todos-data的 Docker 卷中，持久化存储todos.json和stats.json。 - 重要提示：在更新容器时，请务必使用
./docker-update.sh。不要手动运行docker compose down -v，因为-v参数会永久删除您的所有数据卷。 - 备份数据：
docker run --rm -v stark-todo-list_todos-data:/data -v $(pwd):/backup alpine tar czf /backup/todos-backup.tar.gz -C /data . - 恢复数据：
docker run --rm -v stark-todo-list_todos-data:/data -v $(pwd):/backup alpine tar xzf /backup/todos-backup.tar.gz -C /data
- 数据存储在名为
-
清理（会删除数据）
docker compose down -v
📂 项目结构
stark-todo-list/
├── src/
│ ├── app/ # Next.js App Router
│ │ ├── api/ # API 路由
│ │ │ └── todos/ # Todo CRUD 端点
│ │ ├── analytics/ # 数据分析与图表页面
│ │ ├── settings/ # 设置页面
│ │ ├── page.tsx # 主页面
│ │ ├── layout.tsx # 根布局
│ │ └── globals.css # 全局样式
│ ├── components/ # React 组件
│ │ ├── StarkLogo.tsx # 动画 Logo
│ │ └── AnalyticsDashboard.tsx # 数据可视化组件
│ ├── contexts/ # React 上下文
│ │ └── SettingsContext.tsx
│ ├── lib/ # 工具函数
│ │ ├── storage.ts # JSON 文件操作
│ │ ├── translations.ts # 国际化翻译
│ │ └── timezones.ts # 时区数据
│ └── ...
├── public/ # 静态资源
├── scripts/
│ ├── generate-icons.js # 图标生成脚本
│ └── generate-mock-data.js # 演示数据生成脚本
├── docker-compose.yml # Docker Compose 配置
├── Dockerfile # Docker 镜像配置
├── run.sh # 管理脚本
├── docker-start.sh # Docker 启动脚本
├── todos.json # 数据存储文件
└── package.json # 项目依赖
🛠️ 技术栈
- 框架: Next.js 15 (App Router)
- 语言: TypeScript 5
- 样式: Tailwind CSS 3.4
- 动画: Framer Motion
- 图表: Recharts
- 图标: Lucide React
- 容器化: Docker & Docker Compose
📝 数据格式
任务存储在 todos.json 中，格式如下：
[
{
"id": "uuid",
"text": "任务描述",
"completed": false,
"createdAt": 1705392000000,
"completedAt": null,
"deleted": false,
"deletedAt": null,
"groupId": "default",
"priority": "P2"
}
]
🔌 API 接口文档
应用提供 RESTful API 用于程序化访问。在浏览器中访问 /api-docs 可查看交互式 API 文档。
认证方式
受保护的端点需要在请求头中提供 API 密钥：
# 方式一：X-API-Key 请求头
-H "X-API-Key: your_password"
# 方式二：Authorization Bearer 请求头
-H "Authorization: Bearer your_password"
默认密码为
stark123。可通过AUTH_PASSWORD环境变量配置。
接口列表
任务接口 (/api/todos)
| 方法 | 认证 | 描述 |
|---|---|---|
| GET | ❌ | 获取所有活跃任务 |
| POST | ✅ | 创建新任务 |
| PUT | ✅ | 更新现有任务 |
| DELETE | ✅ | 软删除任务 |
GET /api/todos
curl https://your-domain/api/todos
POST /api/todos
curl -X POST https://your-domain/api/todos \
-H "Content-Type: application/json" \
-H "X-API-Key: stark123" \
-d '{"text": "新任务", "groupId": "default", "priority": "P1"}'
PUT /api/todos
curl -X PUT https://your-domain/api/todos \
-H "Content-Type: application/json" \
-H "X-API-Key: stark123" \
-d '{"id": "uuid", "completed": true, "text": "更新后的文本"}'
DELETE /api/todos
curl -X DELETE "https://your-domain/api/todos?id=uuid" \
-H "X-API-Key: stark123"
分组接口 (/api/groups)
| 方法 | 认证 | 描述 |
|---|---|---|
| GET | ❌ | 获取所有分组 |
| POST | ✅ | 创建新分组 |
| DELETE | ✅ | 删除分组 |
GET /api/groups
curl https://your-domain/api/groups
POST /api/groups
curl -X POST https://your-domain/api/groups \
-H "Content-Type: application/json" \
-H "X-API-Key: stark123" \
-d '{"name": "工作"}'
DELETE /api/groups
curl -X DELETE "https://your-domain/api/groups?id=uuid" \
-H "X-API-Key: stark123"
统计接口 (/api/stats)
| 方法 | 认证 | 描述 |
|---|---|---|
| GET | ❌ | 获取 PV/UV 统计 |
| POST | ❌ | 更新访问统计 |
GET /api/stats
curl https://your-domain/api/stats
认证接口 (/api/auth)
| 方法 | 认证 | 描述 |
|---|---|---|
| POST | ❌ | 验证密码 |
POST /api/auth
curl -X POST https://your-domain/api/auth \
-H "Content-Type: application/json" \
-d '{"password": "stark123"}'
🤝 贡献
欢迎贡献！请随时提交 Pull Request。
- Fork 本仓库
- 创建您的特性分支 (
git checkout -b feature/AmazingFeature) - 提交您的更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 打开一个 Pull Request
更多详情请查看 贡献指南。
📄 许可证
本项目采用 MIT 许可证 - 详见 LICENSE 文件。
🙏 致谢
- 基于 Next.js 构建
- UI 设计灵感来自现代极简主义
- 由 STARK 用 ❤️ 打造
由 STARK 用 ❤️ 制作 | 基于 Next.js