# 钢琴练习方案系统 - 开发规范 ## 版本命名规范 ### 语义化版本 (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:latest .` 3. **打包部署文件** → 创建 `releases/v1.2.0/` 目录，放入： - `piano-plan.tar` - Docker镜像 4. **上传** → scp 到服务器 `/opt/piano-plan/` 5. **部署** → 按照 DEPLOYMENT_SOP.md 执行 6. **清理** → 本地 tar 包可删除（git已管理版本） > ⚠️ Nginx 配置在服务器上：`/srv/nginx/conf/conf.d/piano.yoin.fun.conf` ### 版本化部署包命名 ``` 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**: - `feat`: 新功能 - `fix`: 修复bug - `docs`: 文档 - `refactor`: 重构 - `deploy`: 部署 **示例**： ``` feat: 添加学员管理功能 fix: 修复移动端侧边栏遮挡问题 deploy: v1.2.0 生产环境部署 ``` --- ## 版本历史 | 版本 | 日期 | 说明 | |------|------|------| | V1.0 | 2026-04-17 | 初始版本：学员管理、问题记录、方案生成 | | V1.1 | 2026-04-17 | 添加用户登录认证系统 | | V1.2 | 2026-04-18 | 添加用户管理、角色权限、班级管理 | | V1.2.0 | 2026-04-23 | 问题迁移到数据库；URL导航改造；侧边栏统一 | --- *最后更新：2026-04-23*