# 📊 周报混合归档方案使用指南

## 🎯 方案概述

**混合方案 = Markdown 文件（完整内容）+ SQLite 数据库（元数据索引）**

```
每周周报生成
    │
    ├─→ Markdown 文件归档（weekly-reports/YYYY/）
    │   └─→ 人类可读、易编辑、Git 友好、长期保存
    │
    └─→ SQLite 数据库（weekly_reports.db）
        └─→ 快速查询、统计分析、月度/年度考核
```

---

## 📁 文件结构

```
weekly-reports/
├── README.md                      # 归档说明
├── 使用指南.md                    # 详细教程
├── 快速参考.md                    # 快速查阅
├── 混合方案指南.md                # 本文件
├── sync_reports_db.py             # 数据库同步脚本
├── summarize_reports.py           # Markdown 汇总工具
├── weekly_reports.db              # SQLite 数据库（自动生成）
├── 2026/
│   ├── 2026-W29.md               # Markdown 周报
│   ├── 2026-W31-周报.md
│   └── ...
└── ...
```

---

## 🚀 快速开始

### 1. 生成周报（每周五）

**方式一：通过对话（推荐）**
```
你：生成本周周报
我：自动完成 Markdown 归档 + 数据库同步
```

**方式二：手动运行脚本**
```bash
cd /home/yangxuan/.openclaw/workspace-resume

python3 send_weekly_report.py \
  --project G5 \
  --plain "项目名称：...\n主要任务：...\n..." \
  --html "<p>...</p>" \
  --date-range "2026-08-25 ~ 2026-08-29"
```

### 2. 同步到数据库

```bash
cd weekly-reports

# 同步所有周报
python3 sync_reports_db.py --all

# 同步单个文件
python3 sync_reports_db.py --file 2026/2026-W35-周报.md

# 同步指定周
python3 sync_reports_db.py --week 2026-W35
```

### 3. 查看统计信息

```bash
python3 sync_reports_db.py --stats
```

输出示例：
```
📊 周报统计信息

============================================================
📁 周报总数：52 周

📋 按项目统计:
  G5: 45 周，问题 8 周，平均字数 2800
  G6: 7 周，问题 1 周，平均字数 3200

📅 最近 5 周:
  ✅ 2026-W34 (2026-08-18~2026-08-22) G5 - 库存预警模块优化
  ⚠️ 2026-W33 (2026-08-11~2026-08-15) G5 - 生产领料功能测试
  ...

⚠️  存在问题周报：9 周
============================================================
```

---

## 📋 数据库查询示例

### 直接查询 SQLite

```bash
cd weekly-reports

# 进入 SQLite 命令行
sqlite3 weekly_reports.db
```

### 常用 SQL 查询

```sql
-- 1. 查询某年所有周报
SELECT * FROM weekly_reports 
WHERE year = 2026 
ORDER BY week_number;

-- 2. 查询某月所有周报
SELECT * FROM weekly_reports 
WHERE start_date >= '2026-08-01' 
  AND start_date <= '2026-08-31'
ORDER BY start_date;

-- 3. 统计某项目全年工作量
SELECT 
  project,
  COUNT(*) as weeks_count,
  SUM(word_count) as total_words,
  AVG(word_count) as avg_words
FROM weekly_reports 
WHERE year = 2026 
GROUP BY project;

-- 4. 查询存在问题的周报
SELECT year, week_number, start_date, end_date, main_task
FROM weekly_reports 
WHERE has_problems = 1
ORDER BY start_date DESC;

-- 5. 查询某周每日工作明细
SELECT d.work_date, d.day_of_week, d.work_items
FROM weekly_report_daily d
JOIN weekly_reports r ON d.report_id = r.id
WHERE r.year = 2026 AND r.week_number = 35
ORDER BY d.work_date;

-- 6. 月度统计（用于考核）
SELECT 
  strftime('%Y-%m', start_date) as month,
  project,
  COUNT(*) as weeks_count,
  SUM(has_problems) as problem_weeks,
  AVG(word_count) as avg_words
FROM weekly_reports
WHERE start_date >= '2026-08-01' 
  AND start_date <= '2026-08-31'
GROUP BY strftime('%Y-%m', start_date), project;

-- 7. 查询问题记录
SELECT p.problem_description, r.start_date, r.project
FROM weekly_report_problems p
JOIN weekly_reports r ON p.report_id = r.id
ORDER BY r.start_date DESC
LIMIT 10;
```

### 命令行一键查询

```bash
# 查询 8 月份所有周报
sqlite3 weekly_reports.db \
  "SELECT year, week_number, start_date, project, main_task \
   FROM weekly_reports \
   WHERE start_date >= '2026-08-01' AND start_date <= '2026-08-31';"

# 统计全年工作量
sqlite3 weekly_reports.db \
  "SELECT project, COUNT(*), SUM(word_count) \
   FROM weekly_reports \
   WHERE year = 2026 \
   GROUP BY project;"
```

---

## 🔍 两种查询方式对比

| 场景 | 推荐方式 | 原因 |
|------|---------|------|
| **查看完整周报** | Markdown 文件 | 人类可读，格式完整 |
| **快速统计** | SQLite 查询 | SQL 强大，秒出结果 |
| **生成考核报告** | 两者结合 | Markdown 提取内容 + SQL 统计数据 |
| **搜索关键词** | grep/Markdown | 简单直接 |
| **跨年度分析** | SQLite 查询 | 聚合分析方便 |
| **编辑修改** | Markdown 文件 | 直接编辑文本 |

---

## 📊 月度/年度考核流程

### 月度考核（以 8 月为例）

**步骤 1：SQL 统计概览**
```bash
cd weekly-reports

sqlite3 weekly_reports.db <<EOF
SELECT 
  project,
  COUNT(*) as weeks,
  GROUP_CONCAT(main_task, '; ') as tasks
FROM weekly_reports 
WHERE start_date >= '2026-08-01' 
  AND start_date <= '2026-08-31'
GROUP BY project;
EOF
```

**步骤 2：Markdown 汇总详细内容**
```bash
python3 summarize_reports.py --month 2026-08
# 生成 summary_20260831_174000.md
```

**步骤 3：整理考核报告**
- 使用 SQL 统计数据（工作量、周数等）
- 使用 Markdown 汇总的工作内容详情
- 组合成完整的月度考核报告

### 年度考核

```bash
# SQL 统计全年概览
sqlite3 weekly_reports.db <<EOF
SELECT 
  project,
  COUNT(*) as total_weeks,
  SUM(has_problems) as problem_weeks,
  AVG(word_count) as avg_words,
  SUM(word_count) as total_words
FROM weekly_reports 
WHERE year = 2026 
GROUP BY project;
EOF

# Markdown 汇总详细内容
python3 summarize_reports.py --year 2026
```

---

## 🔄 数据库备份

### 自动备份

SQLite 数据库文件很小（通常 < 100KB），可以随工作空间一起备份：

```bash
# 手动备份
cp weekly-reports/weekly_reports.db \
   weekly-reports/weekly_reports_$(date +%Y%m%d).db

# 或加入 git 版本控制
cd /home/yangxuan/.openclaw/workspace-resume
git add weekly-reports/weekly_reports.db
git commit -m "备份周报数据库"
```

### 导出为 SQL

```bash
# 导出整个数据库
sqlite3 weekly_reports.db .dump > weekly_reports_backup.sql

# 只导出元数据表
sqlite3 weekly_reports.db \
  ".dump weekly_reports" > weekly_reports_meta.sql
```

### 恢复数据库

```bash
# 从备份恢复
sqlite3 weekly_reports.db < weekly_reports_backup.sql

# 或重新同步所有 Markdown 文件
python3 sync_reports_db.py --all
```

---

## 📈 高级用法

### 1. 自动同步（集成到周报脚本）

修改 `send_weekly_report.py`，在归档后自动调用同步脚本：

```python
# 在 archive_report() 函数末尾添加
import subprocess
subprocess.run(['python3', 'weekly-reports/sync_reports_db.py', 
                '--file', str(filepath)], 
               cwd='/home/yangxuan/.openclaw/workspace-resume')
```

### 2. 生成可视化报表

使用 Python + matplotlib 生成工作量趋势图：

```python
import sqlite3
import matplotlib.pyplot as plt

conn = sqlite3.connect('weekly_reports.db')
cursor = conn.cursor()

cursor.execute('''
SELECT start_date, word_count 
FROM weekly_reports 
WHERE year = 2026 
ORDER BY start_date
''')

dates, counts = zip(*cursor.fetchall())

plt.figure(figsize=(12, 6))
plt.plot(dates, counts, marker='o')
plt.title('2026 年周报字数趋势')
plt.xlabel('日期')
plt.ylabel('字数')
plt.xticks(rotation=45)
plt.tight_layout()
plt.savefig('workload_trend.png')
```

### 3. 导出为 Excel

```python
import sqlite3
import pandas as pd

conn = sqlite3.connect('weekly_reports.db')

# 导出周报元数据
df = pd.read_sql_query('''
SELECT year, week_number, start_date, end_date, 
       project, main_task, has_problems, word_count
FROM weekly_reports 
WHERE year = 2026
ORDER BY week_number
''', conn)

df.to_excel('2026 年周报汇总.xlsx', index=False)
```

---

## ❓ 常见问题

### Q: 为什么用 SQLite 而不是 MySQL？
A: 
- ✅ SQLite 无需服务器，开箱即用
- ✅ 文件小（< 100KB），易于备份
- ✅ 足够支持个人周报查询需求
- ✅ 未来可轻松迁移到 MySQL（表结构相同）

### Q: 数据库和 Markdown 内容不一致怎么办？
A: 重新同步即可：
```bash
python3 sync_reports_db.py --all
```

### Q: 可以删除数据库吗？
A: 可以。数据库只是索引，删除后可从 Markdown 文件重新生成：
```bash
rm weekly_reports.db
python3 sync_reports_db.py --all
```

### Q: 如何迁移到 MySQL？
A: 当 MariaDB 服务恢复后：
1. 创建表结构：`mysql -u root -p resume < db/weekly_reports_schema.sql`
2. 使用 MySQL 版本的同步脚本：`sync_reports_to_db.py`

---

## 📞 需要帮助？

直接告诉我：
- "生成本周周报"
- "查看 8 月份统计"
- "汇总第三季度工作"
- "生成年终考核报告"

我会帮你处理！

---

*最后更新：2026-08-27*  
*数据库位置：`weekly-reports/weekly_reports.db`*