hmo/piano-plan

Fork 0

Files

T

hmo 6abdd49c04 更新：models/routes/services/templates/docs

2026-04-26 18:02:36 +08:00

5.2 KiB

Raw Blame History

钢琴练习方案系统 - 开发规范

版本命名规范

语义化版本 (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/`	❌	版本化命名

部署包规范

发布流程

开发完成 → 本地测试通过
构建镜像 → docker build -t piano-plan:latest .
打包部署文件 → 创建 releases/v1.2.0/ 目录，放入：
- piano-plan.tar - Docker镜像
上传 → scp 到服务器 /opt/piano-plan/
部署 → 按照 DEPLOYMENT_SOP.md 执行
清理 → 本地 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 - 调试用

规则：

开发时放在 scripts/
功能稳定后删除
不要提交到 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 提取规范

创建 Fragment 文件：app/templates/fragments/{component_name}.html

通过 data 属性传递上下文：

<!-- 学员详情用 -->
<div id="assignGoalModal" data-student-id="{{ student.id }}">

<!-- 班级管理用 -->
<div id="assignGoalModal" data-class-id="{{ class.id }}">

JavaScript 读取 data 属性决定行为：

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

5.2 KiB Raw Blame History Unescape Escape