diary-system/DEV_GUIDE.md

日记系统 - 开发规范

⚠️ 血泪教训（2026-04-15）

问题：修改前端时丢失了已有的日历功能

原因：

1. 没有先查看现有代码
2. 没有功能清单对照
3. 直接在 main 分支修改
4. 修改后没有验证所有功能

---

📋 修改代码前的必须步骤

1. 查看当前功能清单

# 查看 git 历史了解功能演进
git log --oneline -20

# 查看当前有哪些文件
git ls-files

# 查看最近的改动
git diff HEAD~5

2. 备份当前版本

# 创建备份分支
git branch backup-$(date +%Y%m%d-%H%M)

# 或者至少复制关键文件
cp frontend/index.html frontend/index.html.bak

3. 使用分支开发

# 创建功能分支
git checkout -b feature/xxx

# 开发完成后合并
git checkout main
git merge feature/xxx

4. 修改后验证清单

• 日历组件是否正常
• 统计面板数据是否正确
• Tab 切换是否正常
• API 接口是否可用
• 云服务器是否同步

---

📁 必须维护的文档

1. FEATURES.md - 功能清单

记录所有已实现的功能，每次修改前对照检查。

2. CHANGELOG.md - 变更日志

记录每次修改的内容，便于回滚。

3. API.md - 接口文档

记录所有 API 接口，避免删除后端接口。

---

🔄 标准开发流程

1. 查看功能清单 (FEATURES.md)
   ↓
2. 创建备份分支
   ↓
3. 创建功能分支开发
   ↓
4. 本地测试所有功能
   ↓
5. 同步到测试环境验证
   ↓
6. 合并到 main
   ↓
7. 部署到生产环境
   ↓
8. 更新功能清单

---

🛑 禁止操作

• ❌ 直接覆盖 index.html 而不查看原有内容
• ❌ 在 main 分支直接开发新功能
• ❌ 修改后不验证就部署
• ❌ 删除文件前不确认是否还在使用

---

✅ 推荐操作

• ✅ 小步迭代，每次只改一个功能
• ✅ 使用 git diff 查看改动
• ✅ 修改前后截图对比
• ✅ 保持向后兼容
• ✅ 不确定时先问用户

---

最后更新：2026-04-15 创建原因：防止再次丢失已有功能