eddy
ebc245da50
- 通过 127.0.0.1 打开 Tasks，避免受到 localhost 旧 Service Worker 和缓存影响 - 更新 Windows 开发服务器文档，使其与实际生成的访问地址一致
240 lines
8.4 KiB
Markdown
240 lines
8.4 KiB
Markdown
# 任务管理系统
|
||
|
||
一个基于浏览器运行的现代化任务管理系统，支持任务生命周期管理、团队协作、进度跟踪、数据备份和中英文界面。项目已从单体脚本重构为原生 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。
|
||
|
||
## 技术架构
|
||
|
||
### 技术栈
|
||
|
||
- **前端**：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/seed-data.js`：首次运行时的示例任务
|
||
- `src/js/i18n/`：中英文词典及插值逻辑
|
||
- `test/`：单元测试和旧版数据兼容性测试
|
||
|
||
## 本地存储
|
||
|
||
应用保留以下六个原有存储键：
|
||
|
||
- `tasks`
|
||
- `taskSortOrders`
|
||
- `showHiddenCompletedTasks`
|
||
- `showHiddenTodoTasks`
|
||
- `tasksInitialized`
|
||
- `tasksCorruptedBackup`
|
||
|
||
任务、排序和显示偏好使用 JSON 编码。若任务列表格式损坏，原始文本会保存到 `tasksCorruptedBackup`。当浏览器存储不可用或空间不足时，应用会在当前页面会话中继续运行，但刷新后内存中的改动会丢失。
|
||
|
||
## 备份格式
|
||
|
||
```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 月
|