207 lines
5.2 KiB
Markdown
207 lines
5.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: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>: <subject>
|
||
|
||
<body>
|
||
```
|
||
|
||
**Type**:
|
||
- `feat`: 新功能
|
||
- `fix`: 修复bug
|
||
- `docs`: 文档
|
||
- `refactor`: 重构
|
||
- `deploy`: 部署
|
||
|
||
**示例**：
|
||
```
|
||
feat: 添加学员管理功能
|
||
|
||
fix: 修复移动端侧边栏遮挡问题
|
||
|
||
deploy: v1.2.0 生产环境部署
|
||
```
|
||
|
||
---
|
||
|
||
## 代码复用规范（铁律）
|
||
|
||
### DRY 原则（Don't Repeat Yourself）
|
||
|
||
> **复制粘贴代码是严重的 Code Smell。任何重复代码必须提取为可复用组件。**
|
||
|
||
### 前端模板复用
|
||
|
||
| 场景 | 复用方式 |
|
||
|------|---------|
|
||
| 多个页面共用 Modal | 提取为 `app/templates/fragments/` 下的 Fragment，用 `{% include %}` 引用 |
|
||
| 多个页面共用样式 | 在 `base.html` 或页面级别 `<style>` 中定义 |
|
||
| 多个页面共用 JavaScript 函数 | 提取到 `base.html` 的 `<script>` 或单独 JS 文件 |
|
||
|
||
### Fragment 提取规范
|
||
|
||
1. **创建 Fragment 文件**：`app/templates/fragments/{component_name}.html`
|
||
2. **通过 data 属性传递上下文**：
|
||
```html
|
||
<!-- 学员详情用 -->
|
||
<div id="assignGoalModal" data-student-id="{{ student.id }}">
|
||
|
||
<!-- 班级管理用 -->
|
||
<div id="assignGoalModal" data-class-id="{{ class.id }}">
|
||
```
|
||
3. **JavaScript 读取 data 属性决定行为**：
|
||
```javascript
|
||
const studentId = modalElement.dataset.studentId;
|
||
const classId = modalElement.dataset.classId;
|
||
```
|
||
|
||
### 检查清单
|
||
|
||
新增代码前，先问：
|
||
- [ ] 这个 UI 组件是否在其他页面也存在？
|
||
- [ ] 这段 JavaScript 函数是否已有类似实现？
|
||
- [ ] 这个 HTML 结构是否可以直接复用？
|
||
|
||
如果答案是"是"，**先提取复用组件，再使用**。
|
||
|
||
### 禁止的行为
|
||
|
||
❌ 直接复制粘贴另一个页面的 Modal HTML
|
||
❌ 复制粘贴另一个页面的 JavaScript 函数
|
||
❌ 在不同文件里写功能完全相同的函数，仅变量名不同
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| V1.0 | 2026-04-17 | 初始版本：学员管理、问题记录、方案生成 |
|
||
| V1.1 | 2026-04-17 | 添加用户登录认证系统 |
|
||
| V1.2 | 2026-04-18 | 添加用户管理、角色权限、班级管理 |
|
||
| V1.2.0 | 2026-04-23 | 问题迁移到数据库；URL导航改造；侧边栏统一 |
|
||
| V1.3 | 2026-04-25 | 目标管理模块上线；班级级别属性；{student_goals}参数；提示词预览 |
|
||
|
||
---
|
||
|
||
*最后更新：2026-04-25*
|