147 lines
3.2 KiB
Markdown
147 lines
3.2 KiB
Markdown
# 钢琴练习方案系统 - 开发规范
|
||
|
||
## 版本命名规范
|
||
|
||
### 语义化版本 (SemVer)
|
||
|
||
采用 `MAJOR.MINOR.PATCH` 格式：
|
||
|
||
- **MAJOR**: 不兼容的API变更
|
||
- **MINOR**: 向后兼容的功能新增
|
||
- **PATCH**: 向后兼容的问题修复
|
||
|
||
**示例**：
|
||
```
|
||
v1.0.0 - 初始版本
|
||
v1.1.0 - 新增功能（学员班级管理）
|
||
v1.1.1 - 修复bug
|
||
v2.0.0 - 重大重构（不兼容）
|
||
```
|
||
|
||
### 禁止的命名方式
|
||
|
||
❌ 禁止使用以下命名：
|
||
- `final`, `last_final`, `final_v2`
|
||
- `new`, `new2`, `new_final`
|
||
- `backup`, `backup2`
|
||
- `test`, `test2`
|
||
|
||
✅ 正确示例：
|
||
- `v1.2.0.tar` → `piano-plan-v1.2.0.tar`
|
||
- `docker镜像` → `piano-plan:v1.2.0`
|
||
|
||
---
|
||
|
||
## 文件组织规范
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
piano-plan/
|
||
├── app/ # Flask应用核心代码
|
||
├── config/ # 配置文件
|
||
├── data/ # 数据库（不提交git）
|
||
├── docs/ # 项目文档
|
||
├── releases/ # 部署包（版本化）
|
||
├── scripts/ # 临时调试脚本（开发用）
|
||
├── output/ # PDF输出（自动生成）
|
||
├── app/templates/ # 前端模板
|
||
├── app/routes/ # 路由
|
||
├── app/services/ # 业务逻辑
|
||
│
|
||
├── run.py # 应用入口
|
||
├── run.bat # Windows启动
|
||
├── deploy.sh # 部署脚本
|
||
├── docker-compose.yml
|
||
├── Dockerfile
|
||
├── requirements.txt
|
||
└── README.md
|
||
```
|
||
|
||
### 各类文件处理
|
||
|
||
| 类型 | 位置 | Git | 说明 |
|
||
|------|------|------|------|
|
||
| 核心代码 | `app/` | ✅ | 必须 |
|
||
| 配置文件 | `config/` | ✅ | API配置等 |
|
||
| 数据库 | `data/` | ❌ | 不提交 |
|
||
| 文档 | `docs/` | ✅ | 项目文档 |
|
||
| 部署包 | `releases/` | ❌ | 版本化后删除本地副本 |
|
||
| 临时脚本 | `scripts/` | ❌ | 开发调试用，完成后删除 |
|
||
| 输出文件 | `output/` | ❌ | 自动生成 |
|
||
| 依赖 | `venv/` | ❌ | 不提交 |
|
||
| tar包 | `releases/` | ❌ | 版本化命名 |
|
||
|
||
---
|
||
|
||
## 部署包规范
|
||
|
||
### 发布流程
|
||
|
||
1. **开发完成** → 本地测试通过
|
||
2. **构建镜像** → `docker build -t piano-plan:v1.2.0 .`
|
||
3. **打包部署文件** → 创建 `releases/v1.2.0/` 目录，放入：
|
||
- `piano-plan-v1.2.0.tar.gz` - Docker镜像
|
||
- `piano-nginx.conf` - Nginx配置（从服务器获取最新）
|
||
- `docker-compose.yml` - 部署编排
|
||
4. **上传** → 传到服务器 load 镜像
|
||
5. **部署** → docker-compose up -d
|
||
6. **清理** → 本地 tar 包可删除（git已管理版本）
|
||
|
||
### 版本化部署包命名
|
||
|
||
```
|
||
piano-plan-v1.2.0.tar.gz
|
||
```
|
||
|
||
格式：`{项目名}-v{版本}.tar.gz`
|
||
|
||
---
|
||
|
||
## 临时脚本规范
|
||
|
||
### scripts/ 目录
|
||
|
||
用于存放开发过程中的临时调试脚本：
|
||
|
||
- `check_*.py` - 数据库/配置检查
|
||
- `test_*.py` - API/功能测试
|
||
- `debug_*.py` - 调试用
|
||
|
||
**规则**：
|
||
1. 开发时放在 `scripts/`
|
||
2. 功能稳定后 **删除**
|
||
3. 不要提交到 git
|
||
|
||
---
|
||
|
||
## Git 提交规范
|
||
|
||
### Commit Message 格式
|
||
|
||
```
|
||
<type>: <subject>
|
||
|
||
<body>
|
||
```
|
||
|
||
**Type**:
|
||
- `feat`: 新功能
|
||
- `fix`: 修复bug
|
||
- `docs`: 文档
|
||
- `refactor`: 重构
|
||
- `deploy`: 部署
|
||
|
||
**示例**：
|
||
```
|
||
feat: 添加学员管理功能
|
||
|
||
fix: 修复移动端侧边栏遮挡问题
|
||
|
||
deploy: v1.2.0 生产环境部署
|
||
```
|
||
|
||
---
|
||
|
||
*最后更新：2026-04-21*
|