feat: 初始提交 v1.2.0 - 钢琴练习方案生成系统

2026-04-21 20:00:33 +08:00
commit fd593bddf4
44 changed files with 10936 additions and 0 deletions
@@ -0,0 +1,146 @@
+# 钢琴练习方案系统 - 开发规范
+
+## 版本命名规范
+
+### 语义化版本 (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*