# 仓库指南

## 项目结构与模块组织

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/` 下的本地数据库文件。