53 lines
2.9 KiB
Markdown
53 lines
2.9 KiB
Markdown
# 仓库指南
|
||
|
||
## 语言约定
|
||
项目文档、日志、错误提示以及对外返回的文字信息统一使用 **中文**。前端 UI 默认展示中文，若需多语言支持请在相应模块实现。
|
||
|
||
## 项目结构 \& 模块组织
|
||
```
|
||
backend/ # FastAPI 后端（Python）
|
||
├─ main.py # API 入口
|
||
├─ llm.py # LLM 包装工具
|
||
├─ prompt.py # Prompt 构建辅助
|
||
└─ tests/ # pytest 测试套件
|
||
public/ # 前端静态资源
|
||
src/ # 前端源码（Vite + React）
|
||
dist/ # 构建产出（生成文件）
|
||
```
|
||
生产代码主要位于 `backend/`（Python）和 `src/`（JS/TS）。测试文件与被测模块并置。
|
||
|
||
## 构建、测试、开发命令
|
||
| 命令 | 说明 |
|
||
|----------------------------------------------|--------------------------------------------------|
|
||
| `npm install` | 安装前端依赖 |
|
||
| `npm run dev` | 启动 Vite 开发服务器 |
|
||
| `uvicorn backend.main:app --reload` | 本地运行 FastAPI 服务 |
|
||
| `pytest` | 运行 Python 测试套件 |
|
||
| `npm run build` | 生成生产环境构建产物至 `dist/` |
|
||
|
||
## 编码风格 \& 命名约定
|
||
- **Python**：使用 4 空格缩进，`snake_case` 命名函数/变量，`PascalCase` 命名类。提交前请使用 `ruff`/`black` 格式化。
|
||
- **JavaScript/TypeScript**：使用 2 空格缩进，`camelCase` 命名变量/函数，`PascalCase` 命名 React 组件。使用 `eslint` 与 `prettier` 检查。
|
||
- 文件名采用全小写加短横线，例如 `my-module.py`、`my-component.tsx`。
|
||
|
||
## 测试指南
|
||
- 后端使用 **pytest**，测试文件放在对应模块目录下，命名为 `test_<module>.py`。
|
||
- 目标覆盖率 ≥ 80%（`pytest --cov=backend`）。
|
||
- 在虚拟环境中运行：`pip install -r backend/requirements.txt && pytest`。
|
||
|
||
## 提交 \& Pull Request 规范
|
||
- 提交信息遵循 **Conventional Commits**：`feat:` 新功能、`fix:` 修复、`docs:` 文档、`refactor:` 重构等。
|
||
- PR 必须包含：
|
||
- 与提交信息匹配的标题。
|
||
- 关联的 Issue（如 `Fixes #123`）。
|
||
- UI 变更或 API 示例的截图/示例。
|
||
- 所有 CI 检查（代码检查、测试、类型检查）均通过。
|
||
|
||
## 安全 \& 配置建议
|
||
- 敏感信息请放入 `.env` 并确保已在 `.gitignore` 中。
|
||
- 按照 `backend/main.py` 中的实现，对上传文件的大小和类型进行校验，防止滥用。
|
||
- 定期审计依赖安全（`npm audit`、`pip-audit`）。
|
||
|
||
---
|
||
以上指南旨在保持贡献一致性并维护代码库健康，欢迎通过 Pull Request 提出改进。
|