docs: 添加功能清单和开发规范（防止丢失功能的措施）
This commit is contained in:
maoshen
112
DEV_GUIDE.md
Normal file
112
DEV_GUIDE.md
Normal file
@@ -0,0 +1,112 @@
|
|||||||
|
# 日记系统 - 开发规范
|
||||||
|
|
||||||
|
## ⚠️ 血泪教训（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_
|
||||||
|
_创建原因：防止再次丢失已有功能_
|
||||||
142
FEATURES.md
Normal file
142
FEATURES.md
Normal file
@@ -0,0 +1,142 @@
|
|||||||
|
# 日记系统 - 功能清单
|
||||||
|
|
||||||
|
_最后更新：2026-04-15_
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ 已实现功能
|
||||||
|
|
||||||
|
### 后端 API
|
||||||
|
|
||||||
|
#### 日记模块 (`/api/entries/`)
|
||||||
|
- [x] `GET /` - 获取所有日记
|
||||||
|
- [x] `GET /{id}/` - 获取单条日记
|
||||||
|
- [x] `POST /` - 创建日记
|
||||||
|
- [x] `PUT /{id}/` - 更新日记
|
||||||
|
- [x] `DELETE /{id}/` - 删除日记
|
||||||
|
- [x] `GET /today/` - 获取今天的日记
|
||||||
|
- [x] `GET /recent/` - 获取最近 7 天的日记
|
||||||
|
- [x] `GET /stats/` - 获取统计信息
|
||||||
|
|
||||||
|
#### 经验总结模块 (`/api/experiences/`)
|
||||||
|
- [x] `GET /` - 获取所有经验
|
||||||
|
- [x] `GET /{id}/` - 获取单条经验
|
||||||
|
- [x] `POST /` - 创建经验
|
||||||
|
- [x] `PUT /{id}/` - 更新经验
|
||||||
|
- [x] `DELETE /{id}/` - 删除经验
|
||||||
|
- [x] `GET /recent/` - 获取最近 10 条经验
|
||||||
|
- [x] `GET /by_category/` - 按类别分组
|
||||||
|
|
||||||
|
#### 进度追踪模块 (`/api/progress/`)
|
||||||
|
- [x] `GET /` - 获取所有进度
|
||||||
|
- [x] `GET /{id}/` - 获取单条进度
|
||||||
|
- [x] `POST /` - 创建进度
|
||||||
|
- [x] `PUT /{id}/` - 更新进度
|
||||||
|
- [x] `DELETE /{id}/` - 删除进度
|
||||||
|
|
||||||
|
### 前端页面
|
||||||
|
|
||||||
|
#### 统计面板
|
||||||
|
- [x] 总日记数
|
||||||
|
- [x] 总任务数
|
||||||
|
- [x] 进行中任务
|
||||||
|
- [x] 已完成任务
|
||||||
|
- [x] 完成率
|
||||||
|
- [x] 经验总结数
|
||||||
|
|
||||||
|
#### 日历组件 ⭐
|
||||||
|
- [x] 月历视图
|
||||||
|
- [x] 有日记的日期标记 📝
|
||||||
|
- [x] 今天高亮显示
|
||||||
|
- [x] 点击日期查看详情
|
||||||
|
- [x] 上月/下月切换
|
||||||
|
- [x] 星期标题
|
||||||
|
|
||||||
|
#### Tab 切换
|
||||||
|
- [x] 工作任务 Tab
|
||||||
|
- [x] 日记 Tab
|
||||||
|
- [x] 经验总结 Tab
|
||||||
|
|
||||||
|
#### 日记展示
|
||||||
|
- [x] 日历视图（主视图）
|
||||||
|
- [x] 列表视图
|
||||||
|
- [x] 详情展示
|
||||||
|
- [x] 日期选择
|
||||||
|
|
||||||
|
#### 经验总结展示
|
||||||
|
- [x] 列表展示
|
||||||
|
- [x] 分类标签
|
||||||
|
- [x] 问题/解决方案格式
|
||||||
|
- [x] 经验教训高亮
|
||||||
|
|
||||||
|
### 数据模型
|
||||||
|
|
||||||
|
#### DiaryEntry
|
||||||
|
- [x] date - 日期
|
||||||
|
- [x] title - 标题
|
||||||
|
- [x] completed_tasks - 完成的任务
|
||||||
|
- [x] learned - 学到的东西
|
||||||
|
- [x] problems - 遇到的问题
|
||||||
|
- [x] reflections - 想法和反思
|
||||||
|
- [x] improvements - 进步点
|
||||||
|
- [x] plans - 明日计划
|
||||||
|
- [x] created_at - 创建时间
|
||||||
|
- [x] updated_at - 更新时间
|
||||||
|
|
||||||
|
#### Experience
|
||||||
|
- [x] title - 标题
|
||||||
|
- [x] category - 类别（deployment/development/database/permission/network/other）
|
||||||
|
- [x] problem - 问题描述
|
||||||
|
- [x] solution - 解决方案
|
||||||
|
- [x] lesson_learned - 经验教训
|
||||||
|
- [x] date - 日期
|
||||||
|
- [x] created_at - 创建时间
|
||||||
|
|
||||||
|
#### DailyProgress
|
||||||
|
- [x] entry - 关联日记
|
||||||
|
- [x] category - 类别
|
||||||
|
- [x] description - 描述
|
||||||
|
- [x] progress_percent - 进度百分比
|
||||||
|
- [x] created_at - 创建时间
|
||||||
|
|
||||||
|
### 部署
|
||||||
|
|
||||||
|
#### 本地部署
|
||||||
|
- [x] Gunicorn 服务（端口 8002）
|
||||||
|
- [x] Nginx 反向代理（端口 8001）
|
||||||
|
- [x] PostgreSQL 数据库
|
||||||
|
|
||||||
|
#### 云服务器部署
|
||||||
|
- [x] Gunicorn systemd 服务
|
||||||
|
- [x] Nginx 反向代理
|
||||||
|
- [x] SQLite 数据库
|
||||||
|
- [x] 访问地址：http://cssc.datalibstar.com:8001/
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚧 计划功能
|
||||||
|
|
||||||
|
- [ ] 日记创建/编辑表单
|
||||||
|
- [ ] 经验总结创建表单
|
||||||
|
- [ ] 搜索功能
|
||||||
|
- [ ] 数据导出（Markdown）
|
||||||
|
- [ ] 用户认证
|
||||||
|
- [ ] 数据备份
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 修改检查清单
|
||||||
|
|
||||||
|
每次修改代码前，对照此清单确保不丢失功能：
|
||||||
|
|
||||||
|
- [ ] 日历组件是否正常
|
||||||
|
- [ ] 统计面板数据是否正确
|
||||||
|
- [ ] Tab 切换是否正常
|
||||||
|
- [ ] 日记列表是否显示
|
||||||
|
- [ ] 经验总结是否显示
|
||||||
|
- [ ] API 接口是否可用
|
||||||
|
- [ ] 云服务器是否同步更新
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
_此文档必须在每次功能变更后更新_
|
||||||
Reference in New Issue
Block a user