# 高考志愿家庭门户 — 设计文档

## 1. 项目定位

为天恒高考志愿填报，在群晖 NAS 上部署一个**仅限局域网访问**的家庭门户，承载：
- 6 份分析报告的在线浏览（取代微信来回传文件）
- 3 份家庭问卷的独立填写 + 多成员结果汇总对比（取代腾讯文档外链）
- 出分后（6/26）可快速替换更新的报告

---

## 2. 技术选型决策

### 2.1 为什么是 Nginx + Flask + SQLite（而非纯静态 / WordPress / 其他）

| 方案 | 评估 |
|------|------|
| 纯静态 HTML（方案A） | 报告浏览可以，但问卷无法跨设备汇总 → **不满足需求** |
| 腾讯文档外链 | 数据不在自己手里，且家人反馈"腾讯文档交互不够好" → 排除 |
| Nginx + Flask + SQLite（当前） | 报告=纯静态直出（快），问卷=轻量API（灵活），SQLite=零配置数据库 |
| Nginx + PHP + MySQL | 过度复杂，PHP镜像大，MySQL占用内存多 → 不适合轻量场景 |
| 前端框架（React/Vue） | 增加构建复杂度，纯HTML+原生JS完全够用 → 不需要 |

### 2.2 镜像选择理由

| 组件 | 镜像 | 大小 | 理由 |
|------|------|------|------|
| Nginx | `nginx:alpine` | ~5MB | 最小化，群晖低配也能跑 |
| Flask | `python:3.11-alpine` | ~50MB | Alpine 体积小，pip 安装快 |

### 2.3 为什么不用 gunicorn

Flask 开发服务器 (`app.run`) 在并发请求量 ≤ 5 的家庭场景下完全足够。gunicorn 会额外增加 30MB 镜像体积和配置复杂度，收益为零。

### 2.4 数据持久化策略

```
宿主机: ./backend/data/gaokao.db  ←─ 挂载卷
容器内: /app/data/gaokao.db       ←─ Flask 读写
```

- `docker-compose down` 不会删除数据
- 备份：直接复制 `gaokao.db` 文件即可
- 恢复：替换文件后重启容器

---

## 3. UI 设计规范

### 3.1 设计原则
- **移动优先**：家人在手机上填问卷的比例远高于电脑
- **无学习成本**：打开浏览器输 IP:8080 即可，不需要注册/登录/下载 App
- **信息层级扁平**：首页 = 所有入口，不设深层导航

### 3.2 页面清单

#### 页面 1：首页 (`index.html`)

```
┌──────────────────────────────────────┐
│  🎓 天恒高考志愿 · 家庭门户          │
│  2026 浙江高考 | 物化生 | 自估算591  │
│  6月26日出分 | 约6月29~30日填报      │
├──────────────────────────────────────┤
│  📊 分析报告                         │
│  ┌─────────┐ ┌─────────┐ ┌───────┐  │
│  │📋预备报告│ │🎮数媒院校│ │📈招生 │  │
│  │ v3.7     │ │ 6.23最新│ │ 6.21  │  │
│  └─────────┘ └─────────┘ └───────┘  │
│  ┌─────────┐ ┌─────────┐ ┌───────┐  │
│  │🔮预测报告│ │🌍中外合作│ │🗓️行动 │  │
│  │ v5       │ │ 6.3     │ │ 6.10  │  │
│  └─────────┘ └─────────┘ └───────┘  │
├──────────────────────────────────────┤
│  📝 家庭问卷（请每位成员独立填写）    │
│  ┌───────────┐ ┌─────────┐ ┌──────┐ │
│  │Holland评估 │ │院校偏好  │ │期望  │ │
│  │📝填写 📊看│ │📝 📊    │ │📝 📊 │ │
│  │ 1份答卷   │ │ 2份答卷  │ │0份   │ │
│  └───────────┘ └─────────┘ └──────┘ │
├──────────────────────────────────────┤
│  仅供家庭内部使用 · 数据存储在本地NAS│
└──────────────────────────────────────┘
```

**关键细节**：每个问卷卡片显示实时答卷数量（如"Holland评估 — 1份答卷"），家人一眼就能看到谁还没填。

#### 页面 2：问卷填写页 (`questionnaire.html`)

```
┌──────────────────────────────────────┐
│  ← 返回首页                          │
├──────────────────────────────────────┤
│  🎨 Holland 职业兴趣快速评估           │
│  20题 · 5级自评 · 约5分钟             │
├──────────────────────────────────────┤
│  👤 您的称呼: [爸爸________]          │
├──────────────────────────────────────┤
│  第 1 题 / 共 20 题                   │
│  我喜欢修理电器或组装东西             │
│  ○ 非常不符合（1分）                  │
│  ○ 比较不符合（2分）                  │
│  ○ 一般（3分）                        │
│  ● 比较符合（4分）                    │
│  ○ 非常符合（5分）                    │
│  ───────────────────────────────────  │
│  第 2 题 / 共 20 题                   │
│  ...                                  │
├──────────────────────────────────────┤
│          [✅ 提交答卷]                 │
└──────────────────────────────────────┘
```

**设计决策**：
- 所有题目在同一页（非分页），方便快速浏览和修改
- 点击选项整行即可选中（大触控区域，手机友好）
- 提交后自动跳转到汇总页

#### 页面 3：汇总对比页 (`results.html`)

```
┌──────────────────────────────────────┐
│  ← 返回首页                          │
├──────────────────────────────────────┤
│  📊 Holland 评估汇总 — 3份答卷        │
├──────────────────────────────────────┤
│  ┌─────────────────────────────────┐ │
│  │  （雷达图：R/I/A/S/E/C 六维）   │ │
│  │   ── 天恒  ── 爸爸  ── 妈妈    │ │
│  └─────────────────────────────────┘ │
├──────────────────────────────────────┤
│  逐题对比：                          │
│  ┌─────────┬──────┬──────┬──────┐   │
│  │ 题目    │ 天恒 │ 爸爸 │ 妈妈 │   │
│  ├─────────┼──────┼──────┼──────┤   │
│  │ 修理电器│  4   │  3   │  1   │⚠️ │
│  │ 艺术创作│  5   │  2   │  4   │⚠️ │
│  │ 领导团队│  5   │  5   │  5   │✅ │
│  └─────────┴──────┴──────┴──────┘   │
│                                      │
│  ⚠️ = 家人之间差异 ≥ 2 分的题目      │
│  ✅ = 全家一致的题目                  │
└──────────────────────────────────────┘
```

**设计决策**：
- 差异高亮（≥2分用橙色标注）——直接暴露认知差异，不需要人工对比
- 雷达图用 Chart.js（已有 CDN 引用，不新增依赖）

### 3.3 移动端适配

```css
/* 断点 */
@media (max-width: 768px) {
  .card-grid { grid-template-columns: 1fr; }  /* 单列 */
  .hero h1 { font-size: 1.2rem; }
  .option-list li { padding: 12px; }           /* 更大的触控区域 */
}
```

### 3.4 颜色系统

```css
--blue:   #3B82F6   /* 主色：链接、按钮 */
--purple: #8B5CF6   /* 强调：数媒方向卡片 */
--green:  #10B981   /* 成功状态 */
--amber:  #F59E0B   /* 警告：差异高亮 */
--red:    #EF4444   /* 错误状态 */
```

---

## 4. 已完成 vs 待补充

### ✅ 已完成（17个文件，无需改动）

| 组件 | 文件 |
|------|------|
| Docker编排 | `docker-compose.yml` |
| Nginx配置 | `nginx/nginx.conf` |
| Flask后端 | `backend/app.py`, `Dockerfile`, `requirements.txt` |
| 问卷种子数据 | `backend/seed_data.py` |
| 导航首页 | `nginx/html/index.html` |
| 问卷填写页 | `nginx/html/questionnaire.html` |
| 汇总查看页 | `nginx/html/results.html` |
| CSS样式 | `nginx/html/css/style.css` |
| 6份报告 | `nginx/html/reports/*.html` |
| 部署指南 | `README.md` |

### ⚠️ 待补充（取决于你的确认）

| 需求 | 工作量 | 依赖确认问题 |
|------|--------|-------------|
| Holland 雷达图可视化 | ~2h | Q6 |
| 问卷结论自动生成 | ~3h | Q12~Q15 |
| 结论流入分析模块 | ~2h | Q16 |
| 家庭密码页（简单token） | ~1h | Q7 |
| 出分后报告自动更新脚本 | ~1h | Q8 |
| HTTPS 自签证书 | ~0.5h | Q9 |
| 数据定时备份 cron | ~0.5h | Q10 |
| 问卷内容微调 | ~1h | Q11 |
| 移动端响应式优化 | ~1h | 基线需求 |

---

## 5. 部署任务计划（共6步）

### 阶段一：环境确认（阻塞解除后，10分钟）

```
Task 1.1  确认群晖型号+DSM版本 → 验证 docker-compose 兼容性
Task 1.2  确认 Container Manager 已安装
Task 1.3  确认部署目标路径（建议 /volume1/docker/gaokao-portal/）
Task 1.4  确认 8080 端口未被占用 → 如冲突则改用 8088/9090
```

### 阶段二：本地验证（在 Windows 上先跑通，1小时）

```
Task 2.1  安装 Docker Desktop 并启动
Task 2.2  docker-compose up → 验证 nginx+flask 均正常启动
Task 2.3  浏览器访问 localhost:8080 → 首页加载
Task 2.4  填写 Holland 问卷 → 提交 → 查看汇总
Task 2.5  移动端模拟（Chrome DevTools）验证响应式
Task 2.6  修复任何环境差异问题
```

### 阶段三：功能增强（根据确认，1~3小时）

```
Task 3.1  Holland 雷达图（如果 Q6 = 是）
Task 3.2  家庭密码页（如果 Q7 = 是）
Task 3.3  问卷内容微调（如果 Q11 = 有调整）
Task 3.4  移动端触控优化
```

### 阶段四：打包与上传（30分钟）

```
Task 4.1  清理开发残留文件
Task 4.2  将 deploy/ 目录打包为 gaokao-portal.tar.gz
Task 4.3  通过 SMB 或 File Station 上传到群晖目标路径
Task 4.4  解压并确认目录结构完整
```

### 阶段五：群晖部署（30分钟）

```
Task 5.1  Container Manager → 项目 → 新增 → 选择路径
Task 5.2  等待镜像拉取+构建（约2~5分钟）
Task 5.3  浏览器访问 http://NAS_IP:8080 → 验证
Task 5.4  手机/平板访问验证
```

### 阶段六：验收（15分钟）

```
Task 6.1  6份报告全部可打开
Task 6.2  3份问卷可填写+提交
Task 6.3  汇总页正确显示多人答卷
Task 6.4  差异高亮功能正常
Task 6.5  手机端触控/排版正常
```

---

## 6. 风险与预案

| 风险 | 概率 | 影响 | 预案 |
|------|------|------|------|
| 群晖 DSM 6.x 不支持 docker-compose v3.8 | 中 | 阻塞 | 降级到 v2 格式重写 |
| 8080 端口被占用 | 高 | 阻塞 | 改用 8088 端口 |
| 群晖 ARM 架构（如 DS220j）不兼容 x86 镜像 | 低 | 阻塞 | 需要确认型号后验证 |
| Alpine 镜像首次 pull 超时（网络慢） | 中 | 延迟 | 手动下载镜像或配置国内镜像源 |
| 出分后报告更新导致家人看到旧数据 | 中 | 体验 | 首页顶部醒目显示"数据截至 X月X日" |

---

## 7. 需要你逐条回复的确认清单

**请在以下每个问题后回复你的选择：**

> **Q1（阻塞）**: 群晖具体型号是？DSM 大版本是 6 还是 7？
>
> **Q2（阻塞）**: Container Manager（或 Docker 套件）是否已安装？
>
> **Q3（阻塞）**: 部署路径用 `/volume1/docker/gaokao-portal/` 可以吗？
>
> **Q4（阻塞）**: 8080 端口是否空闲？（不确定的话：群晖 → 控制面板 → 网络 → 端口占用查看）
>
> **Q5（重要）**: 部署操作是你手动在 DSM 界面操作，还是给我 SSH 权限远程执行？
>
> **Q6（重要）**: Holland 评估是否需要雷达图可视化？
>
> **Q7（重要）**: 是否需要家庭密码页？（任何连上 WiFi 的人都能看到，需要保护吗？）
>
> **Q8（重要）**: 出分后报告更新，你手动替换 HTML 文件即可，还是需要自动化脚本？
>
> **Q9（可延后）**: 是否需要 HTTPS？
>
> **Q10（可延后）**: 是否需要定时备份问卷数据？
>
> **Q11（可延后）**: 三份问卷内容是否需要调整？（当前是快速生成的，需要你审核）
>
> ---
> **问卷闭环逻辑确认（Q12~Q16）：**
>
> **Q12（关键）**: Holland 评估提交后，是否需要**自动生成个人职业兴趣报告**？（包含六维得分、职业方向推荐、适配专业建议）
>
> **Q13（关键）**: 多位成员完成 Holland 评估后，是否需要**自动生成家庭差异分析报告**？（标注家庭成员之间的RIASEC轮廓差异，给出沟通建议）
>
> **Q14（关键）**: 院校偏好问卷提交后，是否需要**自动生成志愿优先级矩阵**？（城市/层次/费用的权重排序，直接可用于80志愿排序）
>
> **Q15（关键）**: 家庭期望对齐问卷提交后，是否需要**自动生成"对齐度评分"和行动建议**？（1~5分，差异大的题目给出具体沟通话术）
>
> **Q16（关键）**: 以上自动生成的报告，是否需要**同步更新到 MEMORY.md 文件**，作为后续分析模块（如80志愿方案编制）的输入？（意味着每次填写问卷后，MEMORY.md 会自动更新家庭偏好参数）