# 任务管理系统

一个基于浏览器运行的现代化任务管理系统，支持任务生命周期管理、团队协作、进度跟踪、数据备份和中英文界面。项目已从单体脚本重构为原生 ES Modules，并兼容已有任务数据、偏好设置和 1.0 版 JSON 备份。

## 核心特性

### 任务管理

- **三状态管理**：待办事项、进行中、已完成
- **双重描述系统**：任务描述（目标要求）和任务进展（实时状态）
- **可视化进度**：使用 0–100% 进度条跟踪任务
- **优先级管理**：高、中、低三级优先级及颜色标识
- **截止日期**：支持到期提醒和过期任务标识
- **任务置顶**：重要任务在所有排序方式中优先显示

### 协作与记录

- **人员管理**：支持负责人和协作者
- **时间轴记录**：
  - 自动记录状态、进度、负责人、截止日期、优先级和进展内容变更
  - 支持手动添加、编辑和删除记录
  - 使用不同类型区分系统记录和手动记录；编辑系统记录会将其转为手动记录，并记在当前负责人名下
  - 编辑已有的手动记录只更新内容，原记录人保持不变
  - 记录按时间倒序展示，同一天内新增的记录也排在前面

### 搜索、排序与显示

- **13 种排序模式**：支持标题、数字、日期、优先级、进度和创建时间排序
- **实时搜索**：搜索标题、描述、进展、负责人、协作者、到期日期、优先级和时间轴内容，界面固定文字不参与匹配；无匹配结果时栏内给出提示
- **任务隐藏**：待办和已完成任务可单独隐藏，并可批量显示或隐藏
- **国际化**：支持中英文界面切换

### 数据与兼容性

- **本地存储**：基于 `localStorage`，无需后端服务
- **实时保存**：每次操作后自动持久化
- **导入导出**：支持 JSON 覆盖导入和合并导入
- **向后兼容**：保留原有存储键和 1.0 版备份格式
- **容错处理**：损坏的任务原始数据会备份；存储不可用时当前页面会继续以内存模式运行

## 快速开始

### 安装与运行

```bash
npm install
npm start
```

打开 `serve` 输出的地址即可使用。由于应用采用原生 ES Modules，必须通过 HTTP 服务器访问，不支持使用 `file://` 直接打开 `src/index.html`。

#### Windows 开发服务器脚本

Windows 用户可以使用项目根目录下的 `serve.py` 控制本地开发服务器。服务器默认在 `http://127.0.0.1:8000/` 提供 `src` 中的静态文件，并在启动成功后自动使用默认浏览器打开。

```bash
# 启动服务器
python serve.py start

# 查看运行状态
python serve.py status

# 停止服务器
python serve.py stop
```

如需使用其他端口，通过 `--port` 为每条命令指定相同端口：

```bash
python serve.py start --port 8080
python serve.py status --port 8080
python serve.py stop --port 8080
```

启动时，脚本会检查 `src/index.html`、`src/css` 和 `src/js` 是否存在。如果端口已被其他程序占用，脚本会显示占用进程，并在启动操作中询问是否将其关闭。

也可以使用其他静态服务器：

```bash
python -m http.server 8000 --directory src
# 或
npx http-server src
```

### 质量检查

```bash
npm run lint
npm run format:check
npm test
```

如需自动格式化：

```bash
npm run format
```

### 系统要求

- 支持原生 ES Modules 的现代浏览器
- 支持 `localStorage`（通常约 5–10 MB）
- 可访问 Bootstrap 和 Font Awesome 的 CDN 资源

## 使用指南

### 基本操作

1. **添加任务**：填写标题、描述、进展、优先级等信息。
2. **编辑任务**：点击任务卡片上的编辑按钮。
3. **状态管理**：编辑任务并更改状态。
4. **进度跟踪**：更新任务进度和进展内容，系统会自动生成时间轴记录。
5. **任务置顶**：点击图钉按钮，使重要任务优先显示。

### 任务隐藏

- **适用范围**：隐藏仅对待办和已完成任务生效；进行中任务即使被标记隐藏也会正常显示、正常排序。
- **单个隐藏**：编辑任务并勾选“隐藏此任务”，或点击卡片上的隐藏按钮。
- **批量查看**：待办栏和已完成栏的眼睛按钮可显示或隐藏被隐藏的任务。
- **排序规则**：被隐藏的待办和已完成任务在排序结果中自动排到非隐藏任务之后。
- **视觉区分**：显示隐藏任务时，卡片以半透明样式呈现。
- **数量统计**：栏目标题的计数与当前实际显示的卡片一致，会随搜索结果变化。

### 数据备份

- 导出的文件名格式为 `backup-tasks-yyyy-mm-dd.json`。
- 覆盖导入会替换任务及兼容的排序偏好。
- 合并导入会保留现有任务，并按 `title|status|createdDate` 跳过重复项；新导入任务会分配唯一 ID。

## 发布与缓存

Linux 服务器可使用 `deploy.sh` 一键下载并部署 `main` 分支的最新版本：

```bash
bash <(curl -fsSL https://gitea.tohub.top/Share/Tasks/raw/branch/main/deploy.sh) deploy
```

- 保留 `deploy` 参数，以便下载脚本后直接执行部署，而不是进入交互菜单。
- 脚本需要使用 `root` 权限运行，并依赖 `curl`、`tar` 和 `find` 命令。
- 网站文件默认部署到 `/root/data/docker_data/Nginx/html/tasks`。
- 每次部署都会先清空目标目录，再将仓库中的 `src` 静态文件复制到该目录；请勿在目标目录中存放其他文件。
- 部署完成后，如果浏览器仍显示旧版本，请执行强制刷新或清除浏览器缓存。

## 技术架构

### 技术栈

- **前端**：HTML5、CSS3、JavaScript（ES Modules）
- **UI 框架**：Bootstrap 5.3.3
- **图标**：Font Awesome 6.7.2
- **存储**：`localStorage`
- **测试**：Vitest + jsdom
- **代码质量**：ESLint + Prettier
- **部署方式**：纯静态部署

### 项目结构

- `src/index.html`：应用页面和模态框结构
- `src/css/styles.css`：应用样式和响应式布局
- `src/js/main.js`：初始化和委托事件处理
- `src/js/config.js`：状态、排序选项、存储键和共享常量
- `src/js/utils.js`：ID、日期、到期状态和 HTML 转义工具
- `src/js/task-model.js`：任务和偏好数据标准化
- `src/js/store.js`：应用状态及持久化变更
- `src/js/storage.js`：唯一直接访问 `localStorage` 的应用模块
- `src/js/sort.js`：任务比较器和 13 种排序模式
- `src/js/render.js`：任务、时间轴、计数和排序选项渲染
- `src/js/modal.js`：任务表单填充和保存
- `src/js/timeline.js`：手动及系统时间轴记录
- `src/js/import-export.js`：1.0 版备份验证、导入和导出
- `src/js/notify.js`：通知和截止日期提醒
- `src/js/i18n/`：中英文词典及插值逻辑
- `test/`：单元测试和旧版数据兼容性测试

## 本地存储

应用保留以下六个原有存储键：

- `tasks`
- `taskSortOrders`
- `showHiddenCompletedTasks`
- `showHiddenTodoTasks`
- `tasksInitialized`（历史兼容标记）
- `tasksCorruptedBackup`

首次运行时任务列表为空，并会写入 `tasks: []` 与 `tasksInitialized` 标记。`tasksInitialized` 仅作历史兼容用途：读取时用于判断是否需要为旧版安装补写，写入则是为了在回退到含示例任务的旧版本时能识别出已初始化状态。从含示例任务的旧版本升级后，已有本地数据保持不变；仅全新安装（本地尚无 `tasks` 键）时以空列表开始。

任务、排序和显示偏好使用 JSON 编码。若任务列表格式损坏，原始文本会保存到 `tasksCorruptedBackup`。当浏览器存储不可用时，应用会在当前页面会话中继续运行而不尝试写入，改动在刷新后丢失；当存储可用但空间不足时，首次初始化若写入失败则不会设置 `tasksInitialized`，下次访问会重试写入。

## 备份格式

```json
{
  "version": "1.0",
  "exportDate": "2026-07-20T00:00:00.000Z",
  "localDate": "2026-07-20",
  "taskCount": 1,
  "data": {
    "tasks": [],
    "sortOrders": {
      "todo": "default",
      "inProgress": "default",
      "completed": "default"
    }
  }
}
```

## 任务数据结构

```javascript
{
  id: Number,             // 唯一标识
  title: String,          // 任务标题
  description: String,    // 任务描述
  progressNotes: String,  // 任务进展
  status: String,         // todo | inProgress | completed
  progress: Number,       // 0–100
  assignee: String,       // 负责人
  collaborators: Array,   // 协作者
  dueDate: String,        // 截止日期
  priority: String,       // low | medium | high
  language: String,       // zh | en
  isPinned: Boolean,      // 是否置顶
  isHidden: Boolean,      // 是否隐藏
  createdDate: String,    // 创建时间
  timeline: Array         // 时间轴记录
}
```

## 故障排除

- **页面无法直接打开**：请使用 HTTP 服务器运行，原生 ES Modules 不支持 `file://` 加载。
- **数据丢失**：检查浏览器是否允许 `localStorage`，并定期导出备份。
- **导入失败**：确认文件为 1.0 版 JSON 备份，并检查任务字段和日期格式。
- **界面异常**：检查 Bootstrap 和 Font Awesome CDN 是否可访问，并尝试清空缓存。
- **性能问题**：任务数量较多时，建议归档已完成任务并清理不必要的时间轴记录。

## 贡献指南

欢迎提交 Issue 和 Pull Request。

- **问题反馈**：请详细描述问题场景和复现步骤。
- **功能建议**：请说明需求和使用场景。
- **代码贡献**：遵循现有代码风格，并运行 lint、格式检查和测试。

## 许可证

MIT License

---

- **版本**：v1.0.0
- **重构日期**：2026 年 7 月