# 🚀 快速开始指南

## 📦 前置条件

**已完成的设置：**
- ✅ Excel数据已导入（191条家庭教育档案）
- ✅ 数据库已初始化（支持天数标签分类）
- ✅ API端点已添加（指导周期统计）
- ✅ 前端界面已更新（指导周期分析面板）

## 🎯 使用步骤（3步）

### 1️⃣ 启动服务器

```bash
cd /Users/inkling/Desktop/dmp
node server.js
```

输出应该看起来是这样的：
```
🚀 DMP 服务启动: http://localhost:3456
📡 导入 API:  POST /api/import/users
📡 标签 API:  POST /api/import/user-tags
📡 计算 API:  POST /api/compute
```

### 2️⃣ 打开浏览器

访问：`http://localhost:3456`

你会看到：
- 左侧：标签卡片看板
  - **指导周期** 分类（黄色）
  - 60天课程：187人
  - 180天课程：1人

### 3️⃣ 查看指导周期分析

**方式A：通过导航栏按钮**
- 点击顶部导航栏的"📊 指导周期分析"按钮
- 右侧面板显示详细的周期分析数据

**方式B：通过标签筛选**
- 在左侧卡片看板中点击"60天课程"或"180天课程"
- 顶部会显示该周期的人数和占比
- 底部右侧栏会更新统计数据

## 📊 数据说明

### 导入的数据内容

每条档案包含以下信息：
```json
{
  "fileName": "聊天记录101",          // 档案编号
  "childName": "笑笑",                // 孩子姓名
  "guardian1Name": "马晓娜",          // 监护人1姓名
  "childAge": 16,                     // 孩子年龄
  "grade": "高一",                    // 年级
  "learningScore": "优秀",            // 学习成绩
  "familyAddress": "...",             // 家庭地址
  "questionnaireSummary": "...",      // 问卷评估
  "duration": "60天"                  // ⭐ 指导周期
}
```

### 统计数据

| 指导周期 | 人数 | 占比 |
|---------|------|------|
| 60天课程 | 187 | 97.91% |
| 180天课程 | 1 | 0.52% |
| **合计** | **188** | **98.43%** |

*注：存在3条记录未指定周期*

## 🔄 完整工作流

```
Excel档案
   ↓
导入脚本 (scripts/import-excel.js)
   ↓
SQLite数据库
   ↓
后端API (GET /api/duration-stats)
   ↓
前端面板 (指导周期分析)
   ↓
用户查看分析数据
```

## 🛠️ 常见任务

### 导入新的档案Excel

```bash
# 准备新的Excel文件（格式同原文件）
# 将最后一列（天数）填入"60天"或"180天"或其他周期

# 运行导入脚本
node scripts/import-excel.js /path/to/新档案文件.xlsx
```

### 通过API获取统计数据

```bash
curl http://localhost:3456/api/duration-stats

# 返回
{
  "totalUsers": 191,
  "durationBreakdown": [
    {
      "id": 1,
      "key": "duration_60",
      "name": "60天课程",
      "count": 187,
      "rate": 97.91
    },
    ...
  ]
}
```

### 筛选特定周期的用户

通过前端：
1. 点击"60天课程"标签
2. 看板更新，显示该周期的相关分析

通过API：
```bash
curl -X POST http://localhost:3456/api/compute \
  -H "Content-Type: application/json" \
  -d '{
    "selected": [
      {"tagId": 1, "mode": "include"}
    ]
  }'
```

## 📈 功能亮点

✨ **实时计算**
- 点击标签卡片时实时计算交集
- 防抖处理，避免频繁请求
- 350ms延迟时间

🎨 **可视化**
- 进度条展示各周期占比
- 颜色编码区分标签分类
- 柔滑过渡动画

📊 **详细统计**
- 展示每个周期的绝对数和百分比
- 用户样本快速预览
- 导出就地分析

## ⚙️ 技术栈

| 组件 | 选择 | 优势 |
|------|------|------|
| 数据库 | SQLite | 轻量级，支持WAL并发 |
| 缓存 | 内存LRU | 5分钟TTL，防止重复计算 |
| 交叉计算 | SQL INTERSECT | O(n log n) 复杂度，原生支持 |
| 前端 | 原生JS | 无依赖，快速响应 |

## 💡 扩展建议

后续可以考虑：
- 🎯 增加更多阶段（30天、90天、365天等）
- 📉 生成周期相关的报告
- 🔍 按周期分析用户的学习进度
- 📱 移动端优化
- 🔐 用户认证和权限管理

## 🆘 故障排除

**问题：数据库被锁定**
```bash
# 删除锁文件并重启
rm /Users/inkling/Desktop/dmp/dmp.db-wal
rm /Users/inkling/Desktop/dmp/dmp.db-shm
node server.js
```

**问题：API返回HTML而不是JSON**
```bash
# 检查服务器是否正常启动
ps aux | grep "node server"

# 重启服务器
pkill -f "node server"
node server.js
```

**问题：导入脚本找不到Excel文件**
```bash
# 指定完整路径
node scripts/import-excel.js /Users/inkling/Desktop/dmp/家庭教育档案-天数.xlsx
```

## 📞 支持

如需帮助，请检查：
- `/tmp/dmp_server.log` - 服务器日志
- `IMPLEMENTATION_SUMMARY.md` - 实现细节
- `test-api.sh` - API测试脚本

---

**现在就开始使用吧！🎉**