仓库指南

项目结构与模块组织

SmartUp 主应用由 FastAPI 后端和 Vue 3/Vite 前端组成，并通过 Docker Compose 打包运行。后端代码位于 backend/app/：routers/ 定义 API 路由，services/ 放业务逻辑和上游集成，models/ 是 SQLAlchemy ORM，schemas/ 是 Pydantic 类型，utils/ 放通用工具。后端测试为 backend/test_*.py。

前端代码位于 frontend/src/：views/ 是页面，components/ 是复用组件，api/ 封装 Axios 请求，stores/ 管理 Pinia 状态，assets/ 存放样式和静态资源。data/ 存放本地 SQLite 数据库，视为运行时数据。

上下游网关与扩展目录

new-api/、nox-api/、sub2api/ 和 browser-extension/ 是 SmartUp 监控、同步和对接的上下游 API 网关或配套扩展，不是 Python 应用的一部分。其中 Go 项目有独立的 go.mod、README、Dockerfile 或本地 AGENTS.md，修改时优先遵循各自目录内说明。

当 Python 应用中关于上游/下游账号、密钥、分组、模型、额度、认证头或同步流程的逻辑不清楚时，应读取这些目录的源码来确认真实接口行为，不要只按后端字段名猜测协议。

构建、测试与开发命令

make up：使用现有镜像启动 Docker Compose 应用。
make up-build：依赖或镜像配置变化后重新构建并启动。
make log：查看 smartup 服务日志。
cd backend && pip install -r requirements.txt：安装后端依赖。
cd backend && uvicorn app.main:app --reload --port 8000：本地运行 API。
cd backend && pytest：运行后端测试。
cd frontend && npm install：安装前端依赖。
cd frontend && npm run dev：启动 Vite；npm run build 执行类型检查并构建。

编码风格与命名约定

Python 使用 4 空格缩进，模块名使用 snake_case，例如 finance_service.py、external_api_logs.py。路由处理函数应保持精简，将业务逻辑下沉到 services/。请求和响应边界使用 Pydantic schema。

前端使用 Vue SFC 和 <script setup lang="ts">，保持单引号、无分号风格。组件和页面使用 PascalCase，接口访问逻辑放在 frontend/src/api/。

测试规范

后端测试使用 pytest，文件命名为 backend/test_*.py。新增调度、上游、认证、财务、站点同步等行为时，应补充聚焦测试。前端暂无测试框架，修改 UI 后至少运行 npm run build，并记录关键页面的手动验证结果。

提交与 Pull Request 规范

历史提交混用 feat:、fix: 和祈使句摘要（如 Add ...、Improve ...）。建议使用简短祈使句；功能和修复类改动可使用 feat: 或 fix:。每个提交聚焦一个行为变化。

PR 应包含变更说明、关联 issue 或背景、已运行命令（如 pytest、npm run build、Docker 检查）、UI 变更截图，以及 .env 或数据库影响说明。不要提交 .env 密钥或 data/ 下的本地数据库文件。

3.0 KiB Raw Blame History Unescape Escape