8340d1dbbd
- 日程：单次/每日/每周/每月重复，JSON 存储，月历按优先级着色圆点 + 悬停提示 - 复盘页：可自定义折线图卡片(SVG) + 每日心得总览(按日期/任务展开) - Agent 接口：GET /api/agent/overview 读日程+进度，POST /api/agent/schedules 建日程(PPM_API_TOKEN Bearer 鉴权) - 导出/导入/统计纳入日程与图表；47 项测试全绿
52 lines
3.5 KiB
Markdown
52 lines
3.5 KiB
Markdown
# 进度台：个人进度监视系统
|
||
|
||
一个面向单用户、单 worker 的中文个人进度面板。任务、每日事实、修订快照和可重建月归档均以 JSON 保存，适合 Docker 部署在服务器上，并通过反向代理公开 HTTPS 访问。
|
||
|
||
## 快速开始
|
||
|
||
本机需要 Python 3.11+。在当前目录执行：
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
.\.venv\Scripts\Activate.ps1
|
||
pip install -r requirements.txt
|
||
uvicorn app.main:app --reload
|
||
```
|
||
|
||
浏览器打开 <http://127.0.0.1:8000>。不设置密码时为本机免登录模式；生产环境请在 `.env` 中设置 `PPM_PASSWORD_HASH`，或者临时设置 `PPM_PASSWORD`。
|
||
|
||
## Docker
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
docker compose up -d --build
|
||
```
|
||
|
||
默认只绑定 `127.0.0.1:8000`，建议由 Nginx/Caddy 终止 HTTPS 后反代到该端口。只有单副本、单 worker 受支持；JSON 仓储使用进程锁和同目录原子替换，数据卷请纳入主机备份。
|
||
|
||
## 数据与契约
|
||
|
||
`data/tasks/<taskId>.json` 保存当前任务，`data/revisions/<taskId>/<revision>.json` 保存每次属性修订，`data/daily/<year>/<date>.json` 保存不可移动的每日事实，`data/archive/<year>/<month>.json` 是可重建汇总。任务 ID 和指标 ID 稳定，改名不会破坏历史。
|
||
|
||
`data/schedules/<scheduleId>.json` 保存日程（支持单次与每日/每周/每月重复，`completions` 按日期记录完成情况），`data/schedule-revisions/<scheduleId>/<revision>.json` 保存日程修订快照。
|
||
|
||
顶栏「复盘」页提供每日完成趋势图和每日心得总览。图表保存在 `data/charts/<chartId>.json`，可按任务或指标配置天数；`/api/charts` 提供图表 CRUD，`/api/charts/<id>/data` 返回连续日期点列，`/api/review/notes` 返回日期倒序的心得记录。导出备份包含 `charts` 列表，旧备份缺省该字段时仍可导入。
|
||
|
||
`metrics[]` 可同时含 `checkin`、`quantity`、`duration`；周期支持 `day`、`week`、`month`、`lifetime`；`target: null` 表示无上限，时长统一用整数秒。首页与任务详情按 `config/layouts/home.json` 与 `task-detail.json` 中的组件顺序渲染；布局只允许白名单组件，且每个组件限定其所属页面/区域，非法布局会回退到内置默认值。
|
||
|
||
每日 0 点只关闭事实并重建归档，不删除原始记录。启动时会补跑遗漏日期；补录历史会触发对应月份重建。所有写接口带版本号冲突检测，任务删除默认为软删，后台可恢复或二次确认永久删除。
|
||
|
||
进度统计只读原始每日事实、绝不读可重建的月归档：`/api/summary` 汇总全部任务、`/api/tasks/<id>/summary` 汇总单个任务，均按各指标自身的周期窗口（日/周/月/累计）聚合，累计窗口的下界取任务开始日期。会话在服务端带 30 天 TTL，与登录 Cookie 的 `max_age` 一致。
|
||
|
||
日程 API 与任务同风格：`/api/schedules` 提供 CRUD、`/api/schedules/calendar?month=YYYY-MM` 月视图、`/api/schedules/today?date=` 当日日程（含重复展开与完成状态）；首页「日程安排」面板由 `schedule-board` 布局组件渲染。
|
||
|
||
机器接口：设置环境变量 `PPM_API_TOKEN` 后，可带 `Authorization: Bearer <token>` 访问 Agent 接口——`GET /api/agent/overview?date=` 读取「当日日程 + 任务进度」，`POST /api/agent/schedules` 新建日程；未配置 token 时这些接口返回 503（fail-secure）。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
pytest -q
|
||
```
|
||
|
||
路线图：备份恢复向导、多副本协调、跨进程压力测试和更丰富布局编辑器。
|