docs: 创建分模块需求文档(每个模块独立说明)

This commit is contained in:
maoshen
2026-04-15 01:54:13 +00:00
parent d95174a0c4
commit e91b58b079
5 changed files with 414 additions and 0 deletions

108
docs/EXPERIENCE.md Normal file
View File

@@ -0,0 +1,108 @@
# 经验总结模块需求说明
_位置:`backend/diary/models.py`, `frontend/index.html`_
---
## 📋 后端模型
### Experience 模型
```python
class Experience(models.Model):
title = CharField(max_length=200) # 标题
category = CharField(choices=CATEGORY_CHOICES) # 类别
problem = TextField() # 问题描述
solution = TextField() # 解决方案
lesson_learned = TextField() # 经验教训
date = DateField() # 日期
created_at = DateTimeField() # 创建时间
```
### 类别选项
- `deployment` - 📦 部署
- `development` - 💻 开发
- `database` - 🗄️ 数据库
- `permission` - 🔐 权限
- `network` - 🌐 网络
- `other` - 其他
---
## 📋 API 接口
| 接口 | 方法 | 描述 |
|------|------|------|
| `/api/experiences/` | GET | 获取所有经验 |
| `/api/experiences/{id}/` | GET | 获取单条经验 |
| `/api/experiences/` | POST | 创建经验 |
| `/api/experiences/{id}/` | PUT | 更新经验 |
| `/api/experiences/recent/` | GET | 最近 10 条 |
| `/api/experiences/by_category/` | GET | 按类别分组 |
---
## 🎨 前端展示
### UI 结构
```html
<div class="experience-item">
<div class="experience-header">
<span class="experience-title">标题</span>
<span class="experience-category">类别</span>
</div>
<div class="experience-problem">
<div class="experience-problem-title">🐛 问题</div>
<div>问题描述</div>
</div>
<div class="experience-solution">
<div class="experience-solution-title">✅ 解决方案</div>
<div>解决方案</div>
</div>
<div class="experience-lesson">
<div class="experience-lesson-title">📌 经验教训</div>
<div>经验教训</div>
</div>
</div>
```
---
## 🔧 修改指南
### 可以修改的
- ✅ 添加新的类别选项
- ✅ 修改样式
- ✅ 添加新字段
- ✅ 修改展示格式
### 不能删除的
- ❌ Experience 模型
-`/api/experiences/` 相关 API
- ❌ 经验总结 Tab
-`.experience-item` 样式
### 添加新功能时
1. 修改 `models.py` 添加字段
2. 运行 `makemigrations``migrate`
3. 更新 `serializers.py`
4. 更新前端展示
5. 运行 `test_frontend.py experience`
---
## 🧪 测试清单
修改后必须验证:
- [ ] 经验列表正常显示
- [ ] 分类标签正确
- [ ] 问题/解决方案格式正确
- [ ] 经验教训高亮显示
```bash
python3 test_frontend.py experience
```
---
_此文档必须与代码一起维护_