a1354013-alt/plateau-breaker

# PlateauBreaker PlateauBreaker 是一个小型的全栈应用，用于记录每日健康指标并检测体重停滞期。 - Backend: FastAPI + SQLModel (SQLite) - Frontend: Vue 3 + PrimeVue + Pinia + Chart.js ## 核心功能 - 记录每日指标：体重、睡眠、卡路里、蛋白质、运动、步数、备注 - Dashboard KPI（7 天平均值）+ 趋势图表（7/14/30 天） - 停滞期分析（基于最近 7 天评估规则） - 原因分析（基于最近 7 天评估主要因素） ## 仓库布局 - `backend/`: FastAPI 服务（提供 `/api/...`） - `backend/data/`: 用于开发/运行时数据的默认本地 SQLite 位置；不属于发布产物的一部分 - `backend/alembic/` + `backend/alembic.ini`: schema 变更的迁移入口 - `frontend/`: Vue 应用（Vite 开发服务器 + 生产构建） - `PlateauBreaker_Technical_Guide.md`: API + 规则 + 数据流 ## 前置条件 - Node.js + npm（用于前端） - Python 3.11（用于后端；CI 使用 3.11） ### Node 版本（用于可复现安装的必需项） - 本仓库通过 `.nvmrc` 锁定 Node 版本（`20.19.0`）。 - 如果你使用 asdf，可以使用 `.tool-versions`。 - 前端还在 `frontend/package.json` 中声明了 `engines.node`。 - 使用 Node 20.19+ 以避免 lockfile 偏移，并确保 `npm ci` 在干净环境中正常工作。 - 前端通过 `frontend/.npmrc`（`engine-strict=true`）强制执行此要求，因此 `npm ci` 会在 Node 版本错误时快速失败。 #### 示例 (nvm) ``` nvm install 20.19.0 nvm use 20.19.0 node -v ``` ## 快速开始（本地） ### 1) Backend ``` cd backend python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -r requirements.txt -c constraints.txt python -m pip install -r requirements-dev.txt -c constraints.txt uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 ``` ### 2) Frontend ``` cd frontend npm ci npm run dev ``` 默认情况下，前端调用 `/api`（参见 `frontend/src/services/api.ts`）。 - 在开发环境中，Vite 将 `/api` 代理到 `http://localhost:8000`（参见 `frontend/vite.config.ts`）。 - 在生产环境中，你可以通过 `VITE_API_BASE_URL` 覆盖 API 基础路径（参见 `.env.example`）。 ## 生产构建（前端） ``` cd frontend npm ci npm run build ``` 构建输出位于 `frontend/dist/`。 注意：前端附带 `frontend/.npmrc`，用于将 npm 缓存保留在 `frontend/.npm-cache` 中。这避免了在受限环境中依赖全局用户缓存；该缓存可以安全删除，并且不包含在提交/发布中。 ## 测试 ### Backend ``` cd backend python -m pip install -r requirements.txt -c constraints.txt python -m pip install -r requirements-dev.txt -c constraints.txt pytest -q ``` ### Frontend ``` cd frontend npm ci npm test ``` ## CI（推荐） - GitHub Actions workflow: `.github/workflows/ci.yml` - Frontend 任务运行 `npm ci`、`npm test -- --run`、`npm run build`，然后进行发布打包冒烟测试： - `python scripts/make_release_zip.py --out-dir release` - `python scripts/validate_release_zip.py --out-dir release` - Backend 任务使用 `constraints.txt` 中的锁定依赖集在 Python 3.11 上运行 `pytest -q`。 ## 种子数据（可选） 如果你希望在本地 SQLite 数据库中包含示例记录： ``` cd backend .\.venv\Scripts\Activate.ps1 python seed_data.py ``` 如果数据库已有记录，种子脚本将在不修改数据的情况下退出。 ## 没有数据时会发生什么？ - Dashboard 显示空状态，提示你添加记录。 - 分析需要 **在过去 7 个日历日（截至今天）内至少有 5 天的记录** 才能返回有意义的结果。 - 如果你最近的记录 **超过 7 天**，Dashboard 将显示 **过期** 警告，以避免对“最新”指标的误导性解读。 ## KPI 定义（快速参考） - `weight_change_7d`: 仅当你有 **今天** 和 **正好 7 天前** 的记录时才可用；否则为 `null`。 ## 配置（环境变量） 参见 `.env.example` 作为起点。 ### Backend - `PLATEAUBREAKER_DB_PATH` - 可选。 - 绝对路径，或相对于 `backend/` 的路径（例如：`data/plateaubreaker.sqlite3`）。 - 默认值：`backend/data/plateaubreaker.sqlite3`。 - `backend/data/` 是本地运行时数据目录，不是可部署资产。发布 zip 不得包含它。 - `CORS_ORIGINS` - 可选。 - 允许的源列表，以逗号分隔。 - 默认值：`http://localhost:5173,http://127.0.0.1:5173`。 ## 打包干净的交付 zip 本仓库包含一个辅助脚本，用于创建干净的发布 zip。 发布内容（可部署）： - `backend/`（源代码，排除 `backend/tests` 和本地 `backend/data`） - `frontend/dist/`（生产构建输出） - `README.md` ``` # Optional: clean local build artifacts first powershell -ExecutionPolicy Bypass -File .\scripts\clean_artifacts.ps1 powershell -ExecutionPolicy Bypass -File .\scripts\clean_artifacts.ps1 -All # Build frontend first (required for packaging) cd frontend npm ci npm run build cd .. powershell -ExecutionPolicy Bypass -File .\scripts\make_release_zip.ps1 ``` zip 文件创建在 `release/` 下。 跨平台替代方案（适用于 Linux/macOS/Windows）： ``` python scripts/make_release_zip.py --out-dir release python scripts/validate_release_zip.py --out-dir release ``` ### 源码包 vs 发布包 - **源码包**（用于开发备份/审查）：包含仓库源代码树。如果必须将其打包，请运行 `scripts/clean_artifacts.ps1 -All` 并排除工作目录痕迹，如 `.git`、`node_modules/`、`dist/`、`.npm-cache/`、`__pycache__/`、IDE 文件夹和本地数据库。 - 工作区/源码 zip 可能仍包含仅供审查或机器本地的痕迹，例如 `.git`、`.vscode`、本地 SQLite 数据和其他开发者上下文。将其视为源材料，而非正式交付物。 - **发布包**（正式交付/部署）：使用上述脚本生成的发布 zip。它有意保持严格，仅包含 可部署内容（`backend/` 源代码，包括 Alembic 迁移文件 + `frontend/dist/` + `README.md`）。 - 正式交接、部署和外部共享应始终使用 `release/` 下生成的发布 zip，而不是临时的源码 zip。 ## 部署说明（最低要求） - 提供前端（静态 `dist/`）并运行后端 API。 - 确保后端对 SQLite 路径具有写入权限（或设置 `PLATEAUBREAKER_DB_PATH`）。 - 为你部署的前端域名配置 `CORS_ORIGINS`。 ### 部署前端（SPA history 模式） 路由器使用 HTML5 history 模式（`createWebHistory`）。你的静态主机必须将未知路由重写为 `index.html`， 否则刷新 `/analysis` 或 `/records` 将导致 404。 示例 (Nginx): ``` location / { try_files $uri $uri/ /index.html; } ``` ## 数据库迁移（后端） 本项目在 `backend/alembic/` 下包含一个最小化的 Alembic 设置，用于 schema 演进。 **责任规则（重要）：** - **全新/空白环境**（尚无 SQLite 文件，或数据库没有表）：API 服务器将在启动时自动引导创建表，以便于使用。 - **现有环境**（数据库已有表）：服务器 **从不** 应用 schema 变更；请使用 **Alembic 迁移**。 - **生产部署**：在启动 API 服务器 **之前** 运行 `alembic upgrade head`。 - `backend/data/` 仅是 SQLite 的默认本地存储位置。它被排除在发布 zip 之外，并在运行时根据需要重新创建。 ``` cd backend .\.venv\Scripts\Activate.ps1 python -m pip install -r requirements-dev.txt -c constraints.txt alembic upgrade head ``` 服务器引导（`create_db_and_tables`）仅在数据库为空时运行。它不是一个迁移系统。

标签：AV绕过, Chart.js, FastAPI, KPI指标, Pinia, PrimeVue, SQLite, SQLModel, Vite, Vue 3, 个人健康, 云计算, 代码示例, 仪表盘, 体重追踪, 健康管理, 健身日志, 全栈应用, 减肥助手, 后端开发, 平台期检测, 数据分析, 规则引擎, 趋势图, 逆向工具