Update README and project cleanup

2026-04-08 14:52:09 +08:00
commit fafd267288
71 changed files with 14865 additions and 0 deletions
--- a/QUICK_START.md
+++ b/QUICK_START.md
@@ -0,0 +1,214 @@
+# 🚀 快速开始指南
+
+## 📦 前置条件
+
+**已完成的设置：**
+- ✅ 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测试脚本
+
+---
+
+**现在就开始使用吧！🎉**