# 时间记录助手

**Repository Path**: qiaoyukeji/time_record

## Basic Information

- **Project Name**: 时间记录助手
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-05
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 时间记忆助手

一个记录重要时刻的时间管理应用，帮助您记录生活中的重要事件，计算已过去的时间或距离未来事件的天数。

---

## ✨ 功能特性

### 📁 目录管理
- 创建、编辑、删除时间目录
- 支持自定义颜色和描述
- 可为目录设置密码保护

### 📝 事项管理
- 在目录中添加过去事件、未来事件和待办事项
- 支持事项置顶与取消置顶
- 支持按类型（全部/过去/未来/待办）筛选
- 支持按时间排序（从早到晚/从晚到早）

### 📊 时间计算
- 自动计算事件已过去的天数（过去事项）
- 自动计算距离事件的天数（未来事项）
- 显示事项的完整日期和星期

### 📱 响应式设计
- 完美适配桌面端和移动端
- 移动端优化的布局和交互

### 📤 数据管理
- 支持JSON格式数据备份和恢复
- 一键导出所有数据
- 一键导入数据文件

### 🔗 分享功能
- 生成分享链接
- 支持分享目录或事项
- 分享页面无需登录即可查看

---

## 🛠 技术栈

| 分类 | 技术 | 版本 |
|------|------|------|
| 前端框架 | React | 18.x |
| 编程语言 | TypeScript | 5.x |
| 构建工具 | Vite | 6.x |
| 样式框架 | Tailwind CSS | 3.x |
| 图标库 | Lucide React | 0.x |
| 路由管理 | React Router DOM | 7.x |
| 后端框架 | Express | 4.x |
| 数据存储 | JSON文件 | - |

---

## 🚀 快速开始

### 环境要求

- Node.js >= 18.x
- npm >= 9.x

### 安装依赖

```bash
npm install
```

### 开发模式

```bash
# 启动后端服务（端口 3001）
npm run server

# 启动前端开发服务器（端口 5173）
npm run dev
```

访问地址：http://localhost:5173/

### 生产构建

```bash
# 构建前端
npm run build

# 启动生产环境服务
npm run start:prod
```

---

## 📦 项目结构

```
time_how_long/
├── server/                 # 后端服务
│   ├── index.ts           # 入口文件，配置Express服务
│   ├── routes.ts          # API路由定义
│   ├── types.ts           # 后端类型定义
│   ├── utils.ts           # 工具函数（文件读写、ID生成）
│   └── data/              # 数据存储目录
│       ├── events.json    # 事项数据
│       └── directories.json # 目录数据
├── src/                   # 前端源码
│   ├── components/        # 可复用组件
│   │   ├── DirectoryCard.tsx   # 目录卡片组件
│   │   ├── DirectoryForm.tsx   # 目录表单组件
│   │   ├── Empty.tsx           # 空状态组件
│   │   ├── EventCard.tsx       # 事项卡片组件
│   │   ├── EventForm.tsx       # 事项表单组件
│   │   ├── EventList.tsx       # 事项列表组件
│   │   └── Header.tsx          # 页头组件
│   ├── pages/             # 页面组件
│   │   ├── Home.tsx            # 首页
│   │   ├── DirectoryDetail.tsx # 目录详情页
│   │   ├── EventDetail.tsx     # 事项详情页
│   │   └── SharePage.tsx       # 分享页面
│   ├── types/             # TypeScript类型定义
│   │   └── index.ts
│   ├── utils/             # 工具函数
│   │   ├── api.ts         # API调用封装
│   │   └── date.ts        # 日期计算工具
│   ├── lib/               # 库函数
│   │   └── utils.ts       # 通用工具函数
│   ├── App.tsx            # 应用入口组件
│   ├── main.tsx           # React入口文件
│   └── index.css          # 全局样式
├── scripts/               # 部署脚本
│   ├── deploy.sh          # 一键部署脚本
│   └── start.sh           # 启动脚本
├── ecosystem.config.js    # PM2进程管理配置
├── package.json           # 项目依赖配置
├── vite.config.ts         # Vite构建配置
├── tsconfig.json          # TypeScript配置
├── tailwind.config.js     # Tailwind CSS配置
├── postcss.config.js      # PostCSS配置
└── .env.example           # 环境变量示例
```

---

## 📡 API 接口文档

### 事项接口（Events）

| 方法 | 路径 | 描述 | 参数 |
|------|------|------|------|
| GET | `/api/events` | 获取所有事项 | `includeDeleted`: 是否包含已删除 |
| GET | `/api/events/:id` | 获取单个事项 | `id`: 事项ID |
| POST | `/api/events` | 创建事项 | `name`, `date`, `type`, `directoryId`, `completed` |
| PUT | `/api/events/:id` | 更新事项 | `name`, `date`, `type`, `directoryId`, `order` |
| DELETE | `/api/events/:id` | 删除事项（软删除） | `id`: 事项ID |
| POST | `/api/events/:id/toggle` | 切换完成状态 | `id`: 事项ID |
| POST | `/api/events/:id/pin` | 切换置顶状态 | `id`: 事项ID |
| POST | `/api/events/:id/records` | 添加记录 | `content`: 记录内容 |
| DELETE | `/api/events/:id/records/:recordId` | 删除记录 | `id`, `recordId` |

### 目录接口（Directories）

| 方法 | 路径 | 描述 | 参数 |
|------|------|------|------|
| GET | `/api/directories` | 获取所有目录 | `includeDeleted`: 是否包含已删除 |
| GET | `/api/directories/:id` | 获取单个目录 | `id`: 目录ID, `password`: 密码 |
| POST | `/api/directories` | 创建目录 | `name`, `description`, `color`, `password` |
| PUT | `/api/directories/:id` | 更新目录 | `name`, `description`, `color`, `password` |
| DELETE | `/api/directories/:id` | 删除目录（软删除） | `id`: 目录ID |
| POST | `/api/directories/:id/verify` | 验证密码 | `password`: 密码 |

### 数据接口（Data）

| 方法 | 路径 | 描述 | 参数 |
|------|------|------|------|
| GET | `/api/export` | 导出所有数据 | - |
| POST | `/api/import` | 导入数据 | `events`, `directories` |

---

## 📊 数据模型

### EventItem（事项）

```typescript
interface EventItem {
  id: string;                    // 唯一标识
  name: string;                  // 事项名称
  date: string;                  // 日期（ISO格式）
  type: 'past' | 'future' | 'todo'; // 类型
  createdAt: number;             // 创建时间戳
  records: RecordItem[];         // 记录列表
  directoryId?: string | null;   // 所属目录ID
  deleted?: boolean;             // 是否已删除
  completed?: boolean;           // 是否已完成
  order?: number;                // 排序优先级（置顶用）
}
```

### RecordItem（记录）

```typescript
interface RecordItem {
  id: string;        // 唯一标识
  content: string;   // 记录内容
  createdAt: number; // 创建时间戳
}
```

### DirectoryItem（目录）

```typescript
interface DirectoryItem {
  id: string;         // 唯一标识
  name: string;       // 目录名称
  description: string; // 描述
  createdAt: number;  // 创建时间戳
  color: string;      // 颜色代码
  password?: string;  // 密码（可选）
  hasPassword?: boolean; // 是否有密码
  deleted?: boolean;  // 是否已删除
}
```

---

## 🌐 部署

### PM2部署（推荐）

```bash
# 安装PM2
npm install -g pm2

# 启动服务
npm run pm2:start

# 查看状态
npm run pm2:status

# 查看日志
npm run pm2:logs

# 重启服务
npm run pm2:restart

# 停止服务
npm run pm2:stop
```

### 一键部署脚本

```bash
npm run deploy
```

### Docker部署（推荐）

#### 使用 docker-compose（推荐）

```bash
# 构建并启动容器
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 重启服务
docker-compose restart
```

#### 使用 Docker 命令

```bash
# 构建镜像
docker build -t time-record .

# 启动容器（数据文件挂载到宿主机）
docker run -d \
  -p 3001:3001 \
  -v /path/to/host/data:/app/server/data \
  --name time_record_app \
  time-record

# 查看日志
docker logs -f time_record_app

# 停止容器
docker stop time_record_app

# 删除容器
docker rm time_record_app
```

#### 数据持久化

数据文件存储在容器内的 `/app/server/data/` 目录，通过以下方式实现持久化：

1. **Docker Volume（推荐）**：使用 docker-compose 时自动创建 named volume
2. **宿主机挂载**：通过 `-v /host/path:/app/server/data` 指定宿主机目录

#### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| NODE_ENV | production | 运行环境 |
| PORT | 3001 | 服务端口 |

### Nginx反向代理配置

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_cache_bypass $http_upgrade;
    }

    # 如果需要HTTPS
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
}
```

---

## 📖 使用说明

### 创建目录

1. 点击首页的"新建目录"按钮
2. 填写目录名称和描述
3. 选择目录颜色
4. 可选：设置密码保护

### 创建事项

1. 在首页或目录详情页点击"添加事项"
2. 填写事项名称
3. 选择日期和类型（过去/未来/待办）
4. 点击确定保存

### 置顶事项

1. 在事项卡片上点击置顶图标
2. 置顶的事项会显示在列表顶部
3. 再次点击可取消置顶

### 筛选和排序

1. 在目录详情页顶部选择筛选条件
2. 选择排序方式（从早到晚/从晚到早）

### 分享功能

1. 点击事项卡片上的分享图标
2. 复制生成的分享链接
3. 发送给他人即可查看

### 数据备份

1. 点击页面右上角的菜单按钮
2. 选择"导出数据"下载备份文件
3. 需要恢复时选择"导入数据"上传文件

---

## 🐛 常见问题

### Q: 数据存储在哪里？

A: 数据存储在服务器端的 JSON 文件中，位于 `server/data/` 目录下。

### Q: 如何重置数据？

A: 删除 `server/data/events.json` 和 `server/data/directories.json` 文件即可。

### Q: 跨域问题如何解决？

A: 后端已配置 CORS，开发模式下前端通过 Vite 代理访问后端。

### Q: 密码保护是否安全？

A: 密码以明文形式存储在 JSON 文件中，仅适用于基本隐私保护，不建议存储敏感信息。

---

## 📄 许可证

MIT License

---

## 📞 联系方式

- 项目地址：[https://gitee.com/qiaoyukeji/time_record](https://gitee.com/qiaoyukeji/time_record)
- 版权所有：© 2026 qiaoyukeji.cn