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

2026-04-15 01:54:13 +00:00
parent d95174a0c4
commit e91b58b079
5 changed files with 414 additions and 0 deletions
--- a/docs/CALENDAR.md
+++ b/docs/CALENDAR.md
@@ -0,0 +1,86 @@
+# 日历组件需求说明
+
+_位置：`frontend/index.html`  
+核心功能 ⭐ - 修改前必须阅读_
+
+---
+
+## 📋 功能列表
+
+| ID | 功能 | 描述 | 代码位置 |
+|----|------|------|----------|
+| C-01 | 月历视图 | 显示完整月历 | `renderCalendar()` |
+| C-02 | 星期标题 | 日一二三四五六 | `.calendar-day-header` |
+| C-03 | 今天高亮 | 当前日期特殊样式 | `.today` 类 |
+| C-04 | 日记标记 | 有日记的日期显示 📝 | `.has-diary` 类 |
+| C-05 | 点击日期 | 显示当天日记详情 | `selectDate()` |
+| C-06 | 日记详情 | 显示完整日记内容 | `#selected-diary` |
+| C-07 | 上月切换 | 显示上个月 | `prevMonth()` |
+| C-08 | 下月切换 | 显示下个月 | `nextMonth()` |
+| C-09 | 非当月日期 | 灰色显示 | `.other-month` 类 |
+
+---
+
+## 🎨 UI 结构
+
+```html
+<div class="calendar-container">
+    <div class="calendar-header">
+        <button onclick="prevMonth()">上月</button>
+        <h2 id="calendar-title">2026 年 4 月</h2>
+        <button onclick="nextMonth()">下月</button>
+    </div>
+    <div class="calendar-grid" id="calendar-grid">
+        <!-- 7 个星期标题 -->
+        <div class="calendar-day-header">日</div>
+        ...
+        <!-- 日期格子 -->
+        <div class="calendar-day today has-diary">15</div>
+        ...
+    </div>
+</div>
+<div id="selected-diary">点击日期后显示详情</div>
+```
+
+---
+
+## 🔧 修改指南
+
+### 可以修改的
+- ✅ 样式（颜色、大小、间距）
+- ✅ 按钮文字
+- ✅ 日期格式
+- ✅ 图标样式
+
+### 不能删除的
+- ❌ `renderCalendar()` 函数
+- ❌ `selectDate()` 函数
+- ❌ `prevMonth()` / `nextMonth()` 函数
+- ❌ `.calendar-day` 相关样式
+- ❌ `#calendar-grid` 元素
+- ❌ `#selected-diary` 元素
+
+### 添加新功能时
+1. 先查看现有函数
+2. 不要删除现有 DOM 元素
+3. 可以在现有结构上扩展
+4. 修改后运行 `test_frontend.py diary`
+
+---
+
+## 🧪 测试清单
+
+修改后必须验证：
+- [ ] 日历正常显示
+- [ ] 今天高亮
+- [ ] 有日记的日期有 📝 标记
+- [ ] 点击日期显示详情
+- [ ] 上月/下月切换正常
+
+```bash
+python3 test_frontend.py diary
+```
+
+---
+
+_此文档必须与代码一起维护，修改日历组件时先阅读_
--- a/docs/DIARY.md
+++ b/docs/DIARY.md
@@ -0,0 +1,93 @@
+# 日记模块需求说明
+
+_位置：`backend/diary/models.py`, `frontend/index.html`  
+核心功能 ⭐_
+
+---
+
+## 📋 后端模型
+
+### DiaryEntry 模型
+
+```python
+class DiaryEntry(models.Model):
+    date = DateField(unique=True)        # 日期（唯一）
+    title = CharField(max_length=200)    # 标题
+    completed_tasks = TextField()        # 完成的任务
+    learned = TextField()                # 学到的东西
+    problems = TextField()               # 遇到的问题
+    reflections = TextField()            # 想法和反思
+    improvements = TextField()           # 进步点
+    plans = TextField()                  # 明日计划
+    created_at = DateTimeField()         # 创建时间
+    updated_at = DateTimeField()         # 更新时间
+```
+
+---
+
+## 📋 API 接口
+
+| 接口 | 方法 | 描述 |
+|------|------|------|
+| `/api/entries/` | GET | 获取所有日记 |
+| `/api/entries/{id}/` | GET | 获取单条日记 |
+| `/api/entries/` | POST | 创建日记 |
+| `/api/entries/{id}/` | PUT | 更新日记 |
+| `/api/entries/today/` | GET | 获取今天日记 |
+| `/api/entries/recent/` | GET | 最近 7 天日记 |
+| `/api/entries/stats/` | GET | 统计信息 |
+
+---
+
+## 🎨 前端展示
+
+### 日历视图（主要）
+- 有日记的日期显示 📝 标记
+- 点击日期显示详情
+- 详情包含所有字段
+
+### 日记列表
+- 按日期倒序
+- 显示完整内容
+
+---
+
+## 🔧 修改指南
+
+### 可以修改的
+- ✅ 添加新字段
+- ✅ 修改样式
+- ✅ 修改 API 返回格式
+- ✅ 添加新的统计维度
+
+### 不能删除的
+- ❌ DiaryEntry 模型
+- ❌ `/api/entries/` 相关 API
+- ❌ 日历组件
+- ❌ 日记详情展示
+
+### 添加新字段时
+1. 修改 `models.py` 添加字段
+2. 运行 `makemigrations diary`
+3. 运行 `migrate`
+4. 更新 `serializers.py`
+5. 更新前端展示
+6. 运行 `test_frontend.py diary`
+
+---
+
+## 🧪 测试清单
+
+修改后必须验证：
+- [ ] 日历正常显示
+- [ ] 有日记的日期有 📝 标记
+- [ ] 点击日期显示详情
+- [ ] 所有字段正确显示
+
+```bash
+python3 test_frontend.py diary
+```
+
+---
+
+_此文档必须与代码一起维护_
--- a/docs/EXPERIENCE.md
+++ b/docs/EXPERIENCE.md
@@ -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
+```
+
+---
+
+_此文档必须与代码一起维护_
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,70 @@
+# 日记系统 - 模块文档索引
+
+_每个模块都有独立的需求说明，修改前先阅读对应文档_
+
+---
+
+## 📁 文档结构
+
+```
+docs/
+├── README.md           # 本文档（索引）
+├── CALENDAR.md         # 日历组件 ⭐ 核心功能
+├── DIARY.md            # 日记模块 ⭐ 核心功能
+├── EXPERIENCE.md       # 经验总结模块
+├── STATS.md            # 统计面板
+└── TASKS.md            # 任务管理（待创建）
+```
+
+---
+
+## 🔧 修改代码时的流程
+
+### 1. 确定修改的模块
+
+| 修改内容 | 阅读文档 | 测试命令 |
+|---------|---------|---------|
+| 日历样式 | `CALENDAR.md` | `test_frontend.py diary` |
+| 日记字段 | `DIARY.md` | `test_frontend.py diary` |
+| 经验总结 | `EXPERIENCE.md` | `test_frontend.py experience` |
+| 统计面板 | `STATS.md` | `test_frontend.py` |
+
+### 2. 阅读文档
+
+- 查看功能列表
+- 确认**不能删除**的部分
+- 了解修改指南
+
+### 3. 增量修改
+
+- 只添加，不覆盖
+- 只修改相关模块
+- 保持其他功能不变
+
+### 4. 针对性测试
+
+```bash
+python3 test_frontend.py <模块名>
+```
+
+---
+
+## ⚠️ 核心功能（除非用户明确要求，否则不动）
+
+1. **日历组件** (`CALENDAR.md`)
+   - 月历视图
+   - 点击日期显示日记
+   - 上月/下月切换
+
+2. **日记模块** (`DIARY.md`)
+   - 日记 CRUD
+   - 日历集成
+
+3. **Tab 切换**
+   - 工作任务
+   - 日记
+   - 经验总结
+
+---
+
+_修改任何代码前，先阅读对应模块文档_
--- a/docs/STATS.md
+++ b/docs/STATS.md
@@ -0,0 +1,57 @@
+# 统计面板需求说明
+
+_位置：`frontend/index.html`_
+
+---
+
+## 📋 统计卡片
+
+| 卡片 | 数据来源 | API |
+|------|---------|-----|
+| 总日记数 | `stats.total_entries` | `/api/entries/stats/` |
+| 总任务数 | `stats.total_tasks` | `/api/entries/stats/` |
+| 进行中 | `stats.progressing` | `/api/entries/stats/` |
+| 已完成 | `stats.completed` | `/api/entries/stats/` |
+| 完成率 | `stats.completion_rate` | `/api/entries/stats/` |
+| 经验数 | `experiences.length` | `/api/experiences/recent/` |
+
+---
+
+## 🎨 UI 结构
+
+```html
+<div class="stats">
+    <div class="stat-card">
+        <h3 id="stat-total-diaries">-</h3>
+        <p>总日记</p>
+    </div>
+    <div class="stat-card">
+        <h3 id="stat-total-tasks">-</h3>
+        <p>总任务</p>
+    </div>
+    ...
+</div>
+```
+
+---
+
+## 🔧 修改指南
+
+### 可以修改的
+- ✅ 添加新的统计卡片
+- ✅ 修改样式
+- ✅ 修改统计维度
+
+### 不能删除的
+- ❌ `.stats` 容器
+- ❌ `.stat-card` 样式
+- ❌ 统计 API 调用
+
+### 添加新统计时
+1. 后端 API 添加统计字段
+2. 前端添加新的统计卡片
+3. 更新数据绑定
+
+---
+
+_此文档必须与代码一起维护_