215 lines
4.7 KiB
Markdown
215 lines
4.7 KiB
Markdown
# 🚀 快速开始指南
|
||
|
||
## 📦 前置条件
|
||
|
||
**已完成的设置：**
|
||
- ✅ 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测试脚本
|
||
|
||
---
|
||
|
||
**现在就开始使用吧！🎉**
|