DEV_GUIDE.md

# 日记系统 - 开发规范

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

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

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

---

## 📋 修改代码前的必须步骤

### 1. 查看当前功能清单
```bash
# 查看 git 历史了解功能演进
git log --oneline -20

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

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

### 2. 备份当前版本
```bash
# 创建备份分支
git branch backup-$(date +%Y%m%d-%H%M)

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

### 3. 使用分支开发
```bash
# 创建功能分支
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_
_创建原因：防止再次丢失已有功能_