# FineTune

**Repository Path**: vibe-coding-2026-3/fine-tune

## Basic Information

- **Project Name**: FineTune
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-04-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 诸葛菜 · 个人能效系统

一个基于 `FastAPI + H5` 的个人任务管理 Web App，用四象限方式组织任务，并把统计首页、任务象限页、新增任务页拆成清晰的独立页面。

## 当前形态

项目已经从早期的 Streamlit 单页应用重构为：

- `FastAPI` 后端提供页面入口和数据 API
- 原生 `HTML / CSS / JavaScript` 前端
- `SQLite` 持久化存储
- 多用户注册 / 登录 / 注销
- 基于 HttpOnly Cookie + 服务端 session 的鉴权
- 四象限拖拽改象限
- 任务截止时间、自动升级与重复任务生成
- 图表化统计首页

## 主要功能

### 1. 统计首页
- 首页即任务统计大盘
- 展示任务总数、Q1/Q2 数量、高重要任务数、高紧急任务数
- 展示四象限分布图表与分类分布图表
- 展示第二象限占比和最近更新任务
- 展示带 `🔄` 标记的重复任务与日程概览

### 2. 四象限任务页
- 任务列表拆分为独立页面
- 页面采用四象限展示方式
- 横轴表示重要度：越往右越重要
- 纵轴表示紧急度：越往上越紧急
- 支持拖拽任务卡片到不同象限，直接修改任务程度
- 支持按关键词和分类筛选
- 支持编辑 / 删除任务
- 支持单次删除某次重复任务而不影响整个系列

### 3. 独立新增任务页
- 新增任务不再放在侧边栏
- 使用完整页面创建任务
- 支持填写标题、描述、分类和四象限
- 支持配置重复规则：不重复 / 每天 / 每周 / 每月
- 支持复用已有分类，也支持新增自定义分类

### 4. 用户与鉴权
- 用户注册
- 用户登录 / 注销
- 密码使用 `PBKDF2-HMAC(SHA-256)` + 随机盐存储
- 用户数据按 `user_id` 隔离
- 使用服务端 `user_sessions` 表管理登录态

## 页面与路由

### 页面路由
- `/`：统计首页
- `/login`：登录 / 注册页
- `/tasks`：四象限任务页
- `/tasks/new`：新增任务页

### API 路由
- `POST /api/auth/register`
- `POST /api/auth/login`
- `POST /api/auth/logout`
- `GET /api/auth/me`
- `GET /api/categories`
- `GET /api/tasks`
- `POST /api/tasks`
- `GET /api/tasks/{task_id}`
- `PUT /api/tasks/{task_id}`
- `PATCH /api/tasks/{task_id}/quadrant`
- `DELETE /api/tasks/{task_id}`
- `GET /api/statistics/dashboard`

## 安装与运行

### 1. 安装依赖

项目约定统一使用 `uv`：

```bash
cd /home/dorian/Code/ProductivityManager
uv venv
uv pip install -r requirements.txt
```

### 2. 启动开发服务

```bash
uv run --with fastapi --with uvicorn uvicorn app:api --reload
```

默认访问地址：`http://127.0.0.1:8000`

## Docker 运行

项目根目录现已提供 `Dockerfile` 与 `.dockerignore`，可直接构建并启动容器：

```bash
docker build -t productivity-manager .
docker run --rm -p 8000:8000 productivity-manager
```

补充说明：

- 容器默认监听 `0.0.0.0:8000`
- 运行日志写入 `/app/logs/runtime/productivity_manager.log`
- 若需要持久化数据库，可先执行 `touch productivity_manager.db`，再用 `-v "$(pwd)/productivity_manager.db:/app/productivity_manager.db"` 挂载数据库文件
- 若不做数据库挂载，容器删除后数据不会保留
- 镜像健康检查使用 `GET /api/health`

## 自动部署脚本

项目根目录现已提供一键部署脚本 `deploy.sh`，会自动构建镜像、准备数据库与日志挂载目录、替换同名旧容器并后台启动新容器：

```bash
./deploy.sh
```

可选环境变量：

- `IMAGE_NAME`：默认 `productivity-manager`
- `CONTAINER_NAME`：默认 `productivity-manager`
- `HOST_PORT`：默认 `8000`
- `DB_PATH`：默认 `$PROJECT_ROOT/productivity_manager.db`
- `LOG_DIR`：默认 `$PROJECT_ROOT/logs/runtime`

示例：

```bash
HOST_PORT=18000 CONTAINER_NAME=pm-prod ./deploy.sh
```

## 测试

运行全部单元测试与 HTTP 回归测试：

```bash
uv run --with fastapi --with uvicorn --with httpx --with pytest pytest tests/unit tests/integration -q
```

本轮另外补充了 `tests/unit/test_docker_assets.py` 与 `tests/unit/test_deploy_assets.py`，用于校验 Docker 运行资产与自动部署脚本配置。

## 数据存储

数据存储在项目根目录的 `productivity_manager.db` 中，默认包含以下核心表：

- `users`
- `tasks`
- `task_recurrence_series`
- `task_recurrence_skips`
- `user_sessions`

说明：

- 任务按 `user_id` 绑定到具体用户
- 登录态通过 `user_sessions` 管理，而不是前端本地存储
- 项目保留了对历史无 `user_id` 任务的兼容绑定逻辑

## 项目结构

```text
ProductivityManager/
├── app.py                     # FastAPI 后端入口、数据访问与页面/API 路由
├── Dockerfile                 # 容器构建入口
├── .dockerignore              # Docker 构建上下文忽略规则
├── deploy.sh                  # 一键构建镜像并替换运行容器的自动部署脚本
├── service.py                 # 遗留纯函数业务逻辑（主要供测试覆盖）
├── static/
│   ├── index.html             # 统计首页
│   ├── tasks.html             # 四象限任务页
│   ├── task-form.html         # 新增任务页
│   ├── login.html             # 登录/注册页
│   ├── css/styles.css         # 全局样式
│   └── js/*.js                # 页面交互与 API 请求脚本
├── tests/unit/
│   ├── test_app_auth.py       # 用户与任务函数回归测试
│   ├── test_app_api.py        # FastAPI HTTP 接口回归测试
│   ├── test_deploy_assets.py  # 自动部署脚本配置测试
│   ├── test_app_pytest.py     # service.py 纯函数测试
│   └── test_docker_assets.py  # Dockerfile / .dockerignore 配置测试
├── PROJECT.md                 # 项目当前状态摘要
└── logs/                      # 迭代日志
```

## 说明

- `service.py` 仍保留旧版“优先级 + 状态”模型的纯函数逻辑，主要用于教学和测试，不是当前主应用前端的运行主线。
- 若后续继续迭代前端，建议直接围绕 `app.py + static/` 继续扩展。