---
## 🎯 功能特�
- **🎨 现代�UI/UX 设计**
- 精美的动ç”?Logo，æµç•…过渡效æž? - 毛玻璃å¡ç‰‡ä¸ŽèƒŒæ™¯æ¨¡ç³Šç‰¹æ•ˆ
- Framer Motion 驱动的ä¸æ»‘动ç”? - 色彩编ç 的任务统计（è“色ã€æ©™è‰²ã€ç»¿è‰²ï¼‰
- **🌓 主题支æŒ**
- 浅色模å¼ï¼Œé²œè‰³æ¸å? - 深色模å¼ï¼Œä¸“业美å? - 系统主题自动检æµ? - æ— ç¼ä¸»é¢˜åˆ‡æ¢
- **📱 å“应å¼è®¾è®?*
- æ¡Œé¢ç«¯ä¼˜åŒ–çš„é¡¶éƒ¨å¯¼èˆªæ ‡ç¾
- 移动端å‹å¥½çš„底部导航æ ? - 触摸优化的交互元ç´? - 所有å±å¹•å°ºå¯¸çš„自适应布局
- **âš™ï¸ ä¸ªæ€§åŒ–å®šåˆ¶**
- 多è¯è¨€æ”¯æŒï¼ˆä¸æ–‡å’Œè‹±æ–‡ï¼? - å¯è‡ªå®šä¹‰ Logo æ–‡å—
- 时区选择
- 主题模å¼å好设置
- **📊 任务管ç†**
- 创建ã€å®Œæˆå’Œåˆ 除任务
- 任务创建和完æˆæ—¶é—´æˆ³
- è½¯åˆ é™¤ï¼ˆé€»è¾‘åˆ é™¤ï¼Œä¿ç•™æ•°æ®ï¼‰
- 按状æ€ç›é€‰ä»»åŠ¡ï¼ˆå…¨éƒ¨ã€è¿›è¡Œä¸ã€å·²å®Œæˆï¼?
- **📊 交互å¼æ•°æ®åˆ†æžä»ªè¡¨ç›˜**
- æ¯æ—¥åŠ¨æ€è¶‹åŠ¿å›¾ï¼ˆåˆ›å»?vs 完æˆï¼? - 任务完æˆæ—¶é—´è½´ï¼ˆç”˜ç‰¹å›¾è§†è§‰æ•ˆæžœï¼‰
- 实时 KPI æŒ‡æ ‡ç»Ÿè®¡ï¼ˆæ€»æ•°ã€å®Œæˆæ•°ã€æˆåŠŸçŽ‡ï¼? - çµæ´»çš„时间范围选择ï¼?天ã€ä¸€ä¸ªæœˆã€æ‰€æœ‰æ—¶é—´ï¼‰
- **🔠访问控制**
- 密ç ä¿æŠ¤çš„任务æ“ä½œï¼ˆæ·»åŠ ã€ç¼–辑ã€åˆ 除）
- 客户端认è¯çŠ¶æ€æŒä¹…化
- å¯é€šè¿‡çŽ¯å¢ƒå˜é‡é…置密ç
- **💾 æ•°æ®æŒä¹…åŒ?*
- 本地 JSON å˜å‚¨ï¼ˆæ— 需数æ®åº“）
- æ•°æ®åœ¨åº”用é‡å¯åŽä¿ç•™
- 完全å¯è¿½æº¯çš„任务历å²
## 🚀 快速开�
### 环境è¦æ±‚
- Node.js 18+ (本地开å?
- Docker (å¯é€‰ï¼Œç”¨äºŽå®¹å™¨åŒ–部ç½?
### 方案一：本地开å‘（推èï¼?
1. **克隆仓库**
```bash
git clone https://github.com/yourusername/stark-todo-list.git
cd stark-todo-list
```
2. **安装ä¾èµ–**
```bash
npm install
# � pnpm install
```
3. **å¯åŠ¨å¼€å‘æœåŠ¡å™¨**
```bash
npm run dev
# � pnpm dev
```
4. **打开æµè§ˆå™?*
```
http://localhost:2333
```
### 方案二：使用管ç†è„šæœ¬
æ供了便æ·çš„ Shell 脚本用于轻æ¾ç®¡ç†ï¼?
```bash
# å¯åŠ¨åº”用
./run.sh start
# åœæ¢åº”用
./run.sh stop
# é‡å¯å¹¶æ¸…ç†ç¼“å?./run.sh restart
# 查看日志
./run.sh logs
# 检查状�./run.sh status
```
### 方案三：Docker 部署
1. **使用 Docker å¯åŠ¨è„šæœ¬ï¼ˆæŽ¨è）**
```bash
./docker-start.sh
```
脚本会自动：
- 构建并å¯åŠ?Docker 容器
- 自动显示åŽç«¯æ—¥å¿—
- 使用 Docker å·è¿›è¡Œæ•°æ®æŒä¹…化
2. **快速更新（é‡æ–°æž„建并é‡å¯ï¼‰**
```bash
./docker-update.sh
```
æ¤è„šæœ¬ä¼šï¼? - åœæ¢å½“å‰å®¹å™¨
- 拉å–最新代ç （如果æ˜?Git 仓库ï¼? - é‡æ–°æž„建 Docker é•œåƒï¼ˆæ— 缓å˜ï¼? - å¯åŠ¨æ–°å®¹å™? - 自动显示日志
3. **é…置访问密ç （å¯é€‰ï¼‰**
```bash
# 通过环境å˜é‡è®¾ç½®è‡ªå®šä¹‰å¯†ç ? export AUTH_PASSWORD=your_custom_password
# 或创�.env 文件
echo "AUTH_PASSWORD=your_custom_password" > .env
```
> 如未é…置，默认密ç 为 `stark123`ã€?
4. **或手动使�Docker Compose**
```bash
# 使用 Docker Compose å¯åŠ¨
docker compose up -d --build
# 查看日志
docker compose logs -f
```
5. **访问应用**
```
http://localhost:4000
```
4. **管ç†å‘½ä»¤**
```bash
# åœæ¢å®¹å™¨
docker compose down
# é‡å¯å®¹å™¨
docker compose restart
# 查看日志
docker compose logs -f
# 快速更新（é‡æ–°æž„建所有内容）
./docker-update.sh
```
5. **æ•°æ®æŒä¹…化与安全更新**
- æ•°æ®å˜å‚¨åœ¨åä¸?`todos-data` çš?Docker å·ä¸ï¼ŒæŒä¹…化å˜å‚¨ `todos.json` å’?`stats.json`ã€? - **é‡è¦æ示**：在更新容器时，请务必使ç”?`./docker-update.sh`。ä¸è¦æ‰‹åŠ¨è¿è¡?`docker compose down -v`ï¼Œå› ä¸?`-v` å‚æ•°ä¼šæ°¸ä¹…åˆ é™¤æ‚¨çš„æ‰€æœ‰æ•°æ®å·ã€? - 备份数æ®ï¼? ```bash
docker run --rm -v stark-todo-list_todos-data:/data -v $(pwd):/backup alpine tar czf /backup/todos-backup.tar.gz -C /data .
```
- æ¢å¤æ•°æ®ï¼? ```bash
docker run --rm -v stark-todo-list_todos-data:/data -v $(pwd):/backup alpine tar xzf /backup/todos-backup.tar.gz -C /data
```
6. **清ç†ï¼ˆä¼šåˆ 除数æ®ï¼?*
```bash
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` ä¸ï¼Œæ ¼å¼å¦‚下ï¼?
```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 密钥ï¼?
```bash
# æ–¹å¼ä¸€ï¼š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**
```bash
curl https://your-domain/api/todos
```
**POST /api/todos**
```bash
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**
```bash
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**
```bash
curl -X DELETE "https://your-domain/api/todos?id=uuid" \
-H "X-API-Key: stark123"
```
#### åˆ†ç»„æŽ¥å£ (`/api/groups`)
| 方法 | è®¤è¯ | æè¿° |
|------|------|------|
| GET | â?| 获å–所有分ç»?|
| POST | �| 创建新分�|
| DELETE | âœ?| åˆ é™¤åˆ†ç»„ |
**GET /api/groups**
```bash
curl https://your-domain/api/groups
```
**POST /api/groups**
```bash
curl -X POST https://your-domain/api/groups \
-H "Content-Type: application/json" \
-H "X-API-Key: stark123" \
-d '{"name": "工作"}'
```
**DELETE /api/groups**
```bash
curl -X DELETE "https://your-domain/api/groups?id=uuid" \
-H "X-API-Key: stark123"
```
#### ç»Ÿè®¡æŽ¥å£ (`/api/stats`)
| 方法 | è®¤è¯ | æè¿° |
|------|------|------|
| GET | â?| èŽ·å– PV/UV 统计 |
| POST | â?| 更新访问统计 |
**GET /api/stats**
```bash
curl https://your-domain/api/stats
```
#### 认è¯æŽ¥å£ (`/api/auth`)
| 方法 | è®¤è¯ | æè¿° |
|------|------|------|
| POST | â?| 验è¯å¯†ç |
**POST /api/auth**
```bash
curl -X POST https://your-domain/api/auth \
-H "Content-Type: application/json" \
-d '{"password": "stark123"}'
```
## 🤠贡献
欢迎贡献ï¼è¯·éšæ—¶æ交 Pull Requestã€?
1. Fork 本仓�2. 创建您的特性分�(`git checkout -b feature/AmazingFeature`)
3. æ交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推é€åˆ°åˆ†æ”¯ (`git push origin feature/AmazingFeature`)
5. 打开一�Pull Request
更多详情请查çœ?[贡献指å—](CONTRIBUTING.md)ã€?
## 📄 许å¯è¯?
本项目采ç”?MIT 许å¯è¯?- è¯¦è§ [LICENSE](LICENSE) 文件ã€?
## 🙠致谢
- 基于 [Next.js](https://nextjs.org/) 构建
- UI 设计çµæ„Ÿæ¥è‡ªçŽ°ä»£æžç®€ä¸»ä¹‰
- ç”?STARK ç”?â¤ï¸ 打é€?
---
**[�返回顶部](#-stark-todo-list)**
ç”?STARK ç”?â¤ï¸ 制作 | 基于 Next.js
**基于 Next.js 构建的æžç®€ã€çŽ°ä»£ã€é«˜åº¦ç²¾è‡´çš„待办事项应用**
[English](README.md) | [简体ä¸æ–‡](README.zh-CN.md)
[STARK Todo List 预览](https://todo.unistark.dpdns.org/)