DanDing1Todo_Web/README.zh-CN.md

<div align="center">

# <20><>?STARK Todo List

<img src="https://img.shields.io/badge/Next.js-15.1.2-black?style=flat-square&logo=next.js" alt="Next.js">
<img src="https://img.shields.io/badge/React-19.0-61DAFB?style=flat-square&logo=react" alt="React">
<img src="https://img.shields.io/badge/TypeScript-5.0-3178C6?style=flat-square&logo=typescript" alt="TypeScript">
<img src="https://img.shields.io/badge/Tailwind_CSS-3.4-38B2AC?style=flat-square&logo=tailwind-css" alt="Tailwind CSS">
<img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="License">

**基于 Next.js 构建的极简、现代、高度精致的待办事项应用**

[English](README.md) | [简体中文](README.zh-CN.md)

[STARK Todo List 预览](https://todo.unistark.dpdns.org/)

</div>

---

## 🎯 功能特<E883BD><E789B9>?
- **🎨 现代<E78EB0><E4BBA3>?UI/UX 设计**
  - 精美的动<E79A84><E58AA8>?Logo，流畅过渡效<E6B8A1><E69588>?  - 毛玻璃卡片与背景模糊特效
  - Framer Motion 驱动的丝滑动<E6BB91><E58AA8>?  - 色彩编码的任务统计（蓝色、橙色、绿色）

- **🌓 主题支持**
  - 浅色模式，鲜艳渐<E889B3><E6B890>?  - 深色模式，专业美<E4B89A><E7BE8E>?  - 系统主题自动检<E58AA8><E6A380>?  - 无缝主题切换

- **📱 响应式设<E5BC8F><E8AEBE>?*
  - 桌面端优化的顶部导航标签
  - 移动端友好的底部导航<E5AFBC><E888AA>?  - 触摸优化的交互元<E4BA92><E58583>?  - 所有屏幕尺寸的自适应布局

- **⚙️ 个性化定制**
  - 多语言支持（中文和英文<E88BB1><E69687>?  - 可自定义 Logo 文字
  - 时区选择
  - 主题模式偏好设置

- **📊 任务管理**
  - 创建、完成和删除任务
  - 任务创建和完成时间戳
  - 软删除（逻辑删除，保留数据）
  - 按状态筛选任务（全部、进行中、已完成<E5AE8C><E68890>?
- **📊 交互式数据分析仪表盘**
  - 每日动态趋势图（创<EFBC88><E5889B>?vs 完成<E5AE8C><E68890>?  - 任务完成时间轴（甘特图视觉效果）
  - 实时 KPI 指标统计（总数、完成数、成功率<E58A9F><E78E87>?  - 灵活的时间范围选择<E98089><E68BA9>?天、一个月、所有时间）

- **🔐 访问控制**
  - 密码保护的任务操作（添加、编辑、删除）
  - 客户端认证状态持久化
  - 可通过环境变量配置密码

- **💾 数据持久<E68C81><E4B985>?*
  - 本地 JSON 存储（无需数据库）
  - 数据在应用重启后保留
  - 完全可追溯的任务历史

## 🚀 快速开<E9809F><E5BC80>?
### 环境要求

- Node.js 18+ (本地开<E59CB0><E5BC80>?
- Docker (可选，用于容器化部<E58C96><E983A8>?

### 方案一：本地开发（推荐<E68EA8><E88D90>?
1. **克隆仓库**
   ```bash
   git clone https://github.com/yourusername/stark-todo-list.git
   cd stark-todo-list
   ```

2. **安装依赖**
   ```bash
   npm install
   # <20><>?   pnpm install
   ```

3. **启动开发服务器**
   ```bash
   npm run dev
   # <20><>?   pnpm dev
   ```

4. **打开浏览<E6B58F><E8A788>?*
   ```
   http://localhost:2333
   ```

### 方案二：使用管理脚本

提供了便捷的 Shell 脚本用于轻松管理<E7AEA1><E79086>?
```bash
# 启动应用
./run.sh start

# 停止应用
./run.sh stop

# 重启并清理缓<E79086><E7BC93>?./run.sh restart

# 查看日志
./run.sh logs

# 检查状<E69FA5><E78AB6>?./run.sh status
```

### 方案三：Docker 部署

1. **使用 Docker 启动脚本（推荐）**
   ```bash
   ./docker-start.sh
   ```
   脚本会自动：
   - 构建并启<E5B9B6><E590AF>?Docker 容器
   - 自动显示后端日志
   - 使用 Docker 卷进行数据持久化

2. **快速更新（重新构建并重启）**
   ```bash
   ./docker-update.sh
   ```
   此脚本会<E69CAC><E4BC9A>?   - 停止当前容器
   - 拉取最新代码（如果<E5A682><E69E9C>?Git 仓库<E4BB93><E5BA93>?   - 重新构建 Docker 镜像（无缓存<E7BC93><E5AD98>?   - 启动新容<E696B0><E5AEB9>?   - 自动显示日志

3. **配置访问密码（可选）**
   ```bash
   # 通过环境变量设置自定义密<E4B989><E5AF86>?   export AUTH_PASSWORD=your_custom_password
   
   # 或创<E68896><E5889B>?.env 文件
   echo "AUTH_PASSWORD=your_custom_password" > .env
   ```
   > 如未配置，默认密码为 `stark123`<60><>?
4. **或手动使<E58AA8><E4BDBF>?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. **数据持久化与安全更新**
   - 数据存储在名<E59CA8><E5908D>?`todos-data` <20><>?Docker 卷中，持久化存储 `todos.json` <20><>?`stats.json`<60><>?   - **重要提示**：在更新容器时，请务必使<E5BF85><E4BDBF>?`./docker-update.sh`。不要手动运<E58AA8><E8BF90>?`docker compose down -v`，因<EFBC8C><E59BA0>?`-v` 参数会永久删除您的所有数据卷<E68DAE><E58DB7>?   - 备份数据<E695B0><E68DAE>?     ```bash
     docker run --rm -v stark-todo-list_todos-data:/data -v $(pwd):/backup alpine tar czf /backup/todos-backup.tar.gz -C /data .
     ```
   - 恢复数据<E695B0><E68DAE>?     ```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. **清理（会删除数据<E695B0><E68DAE>?*
   ```bash
   docker compose down -v
   ```

## 📂 项目结构

```
stark-todo-list/
├── src/
<EFBFBD><EFBFBD>?  ├── app/                    # Next.js App Router
<EFBFBD><EFBFBD>?  <20><>?  ├── api/               # API 路由
<EFBFBD><EFBFBD>?  <20><>?  <20><>?  └── todos/         # Todo CRUD 端点
<EFBFBD><EFBFBD>?  <20><>?  ├── analytics/         # 数据分析与图表页<E8A1A8><E9A1B5>?<3F><>?  <20><>?  ├── settings/          # 设置页面
<EFBFBD><EFBFBD>?  <20><>?  ├── page.tsx           # 主页<E4B8BB><E9A1B5>?<3F><>?  <20><>?  ├── layout.tsx         # 根布局
<EFBFBD><EFBFBD>?  <20><>?  └── globals.css        # 全局样式
<EFBFBD><EFBFBD>?  ├── components/            # React 组件
<EFBFBD><EFBFBD>?  <20><>?  ├── StarkLogo.tsx      # 动画 Logo
<EFBFBD><EFBFBD>?  <20><>?  └── AnalyticsDashboard.tsx # 数据可视化组<E58C96><E7BB84>?<3F><>?  ├── contexts/              # React 上下<E4B88A><E4B88B>?<3F><>?  <20><>?  └── SettingsContext.tsx
<EFBFBD><EFBFBD>?  ├── lib/                   # 工具函数
<EFBFBD><EFBFBD>?  <20><>?  ├── storage.ts         # JSON 文件操作
<EFBFBD><EFBFBD>?  <20><>?  ├── translations.ts    # 国际化翻<E58C96><E7BFBB>?<3F><>?  <20><>?  └── timezones.ts       # 时区数据
<EFBFBD><EFBFBD>?  └── ...
├── public/                    # 静态资<E68081><E8B584>?├── scripts/
<EFBFBD><EFBFBD>?  ├── generate-icons.js      # 图标生成脚本
<EFBFBD><EFBFBD>?  └── generate-mock-data.js  # 演示数据生成脚本
├── docker-compose.yml         # Docker Compose 配置
├── Dockerfile                 # Docker 镜像配置
├── run.sh                     # 管理脚本
├── docker-start.sh            # Docker 启动脚本
├── todos.json                 # 数据存储文件
└── package.json               # 项目依赖
```

## 🛠<><F09F9BA0>?技术栈

- **框架**: Next.js 15 (App Router)
- **语言**: TypeScript 5
- **样式**: Tailwind CSS 3.4
- **动画**: Framer Motion
- **图表**: Recharts
- **图标**: Lucide React
- **容器<E5AEB9><E599A8>?*: Docker & Docker Compose

## 📝 数据格式

任务存储<EFBFBD><EFBFBD>?`todos.json` 中，格式如下<E5A682><E4B88B>?
```json
[
  {
    "id": "uuid",
    "text": "任务描述",
    "completed": false,
    "createdAt": 1705392000000,
    "completedAt": null,
    "deleted": false,
    "deletedAt": null,
    "groupId": "default",
    "priority": "P2"
  }
]
```

## 🔌 API 接口文档

应用提供 RESTful API 用于程序化访问。在浏览器中访问 `/api-docs` 可查看交互式 API 文档<E69687><E6A1A3>?
### 认证方式

受保护的端点需要在请求头中提供 API 密钥<E5AF86><E992A5>?
```bash
# 方式一：X-API-Key 请求<E8AFB7><E6B182>?-H "X-API-Key: your_password"

# 方式二：Authorization Bearer 请求<E8AFB7><E6B182>?-H "Authorization: Bearer your_password"
```

> 默认密码<E5AF86><E7A081>?`stark123`。可通过 `AUTH_PASSWORD` 环境变量配置<E9858D><E7BDAE>?
### 接口列表

#### 任务接口 (`/api/todos`)

| 方法 | 认证 | 描述 |
|------|------|------|
| GET | <20><>?| 获取所有活跃任<E8B783><E4BBBB>?|
| POST | <20><>?| 创建新任<E696B0><E4BBBB>?|
| PUT | <20><>?| 更新现有任务 |
| DELETE | <20><>?| 软删除任<E999A4><E4BBBB>?|

**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": "新任<E696B0><E4BBBB>?, "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 | <20><>?| 获取所有分<E69C89><E58886>?|
| POST | <20><>?| 创建新分<E696B0><E58886>?|
| DELETE | <20><>?| 删除分组 |

**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 | <20><>?| 获取 PV/UV 统计 |
| POST | <20><>?| 更新访问统计 |

**GET /api/stats**
```bash
curl https://your-domain/api/stats
```

#### 认证接口 (`/api/auth`)

| 方法 | 认证 | 描述 |
|------|------|------|
| POST | <20><>?| 验证密码 |

**POST /api/auth**
```bash
curl -X POST https://your-domain/api/auth \
  -H "Content-Type: application/json" \
  -d '{"password": "stark123"}'
```

## 🤝 贡献

欢迎贡献！请随时提交 Pull Request<73><74>?
1. Fork 本仓<E69CAC><E4BB93>?2. 创建您的特性分<E680A7><E58886>?(`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一<E5BC80><E4B880>?Pull Request

更多详情请查<EFBFBD><EFBFBD>?[贡献指南](CONTRIBUTING.md)<29><>?
## 📄 许可<E8AEB8><E58FAF>?
本项目采<EFBFBD><EFBFBD>?MIT 许可<E8AEB8><E58FAF>?- 详见 [LICENSE](LICENSE) 文件<E69687><E4BBB6>?
## 🙏 致谢

- 基于 [Next.js](https://nextjs.org/) 构建
- UI 设计灵感来自现代极简主义
- <20><>?STARK <20><>?❤️ 打<><E68993>?
---

<div align="center">

**[<EFBFBD><EFBFBD>?返回顶部](#-stark-todo-list)**

<EFBFBD><EFBFBD>?STARK <20><>?❤️ 制作 | 基于 Next.js

</div>