3.2 KiB
3.2 KiB
钢琴练习方案系统 - 开发规范
版本命名规范
语义化版本 (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_v2new,new2,new_finalbackup,backup2test,test2
✅ 正确示例：
v1.2.0.tar→piano-plan-v1.2.0.tardocker镜像→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/ |
❌ | 版本化命名 |
部署包规范
发布流程
- 开发完成 → 本地测试通过
- 构建镜像 →
docker build -t piano-plan:v1.2.0 . - 打包部署文件 → 创建
releases/v1.2.0/目录，放入：piano-plan-v1.2.0.tar.gz- Docker镜像piano-nginx.conf- Nginx配置（从服务器获取最新）docker-compose.yml- 部署编排
- 上传 → 传到服务器 load 镜像
- 部署 → docker-compose up -d
- 清理 → 本地 tar 包可删除（git已管理版本）
版本化部署包命名
piano-plan-v1.2.0.tar.gz
格式：{项目名}-v{版本}.tar.gz
临时脚本规范
scripts/ 目录
用于存放开发过程中的临时调试脚本：
check_*.py- 数据库/配置检查test_*.py- API/功能测试debug_*.py- 调试用
规则：
- 开发时放在
scripts/ - 功能稳定后 删除
- 不要提交到 git
Git 提交规范
Commit Message 格式
<type>: <subject>
<body>
Type:
feat: 新功能fix: 修复bugdocs: 文档refactor: 重构deploy: 部署
示例：
feat: 添加学员管理功能
fix: 修复移动端侧边栏遮挡问题
deploy: v1.2.0 生产环境部署
最后更新：2026-04-21