# 高考志愿家庭门户 — 群晖 NAS Docker 部署指南

## 架构概览

```
浏览器 ──→ NAS_IP:8080 ──→ Nginx (静态文件 + API反代) ──→ Flask (问卷后端 + SQLite)
```

| 组件 | 容器名 | 端口 | 作用 |
|------|--------|------|------|
| Nginx | gaokao-nginx | 8080→80 | 托管6份HTML报告 + 导航首页 + API反向代理 |
| Flask | gaokao-backend | 5000（内部） | 问卷API：创建/填写/汇总 |


## 部署步骤（群晖 Container Manager）

### 第一步：上传文件到 NAS

1. 打开群晖 File Station
2. 在 `docker/` 目录下创建文件夹 `gaokao-portal/`
3. 将整个 `deploy/` 目录下的内容（这个文件夹）上传到 `docker/gaokao-portal/`

最终目录结构：
```
docker/gaokao-portal/
├── docker-compose.yml
├── nginx/
│   ├── nginx.conf
│   └── html/
│       ├── index.html
│       ├── questionnaire.html
│       ├── results.html
│       ├── css/style.css
│       └── reports/
│           ├── 志愿填报预备报告.html
│           ├── 高考预测报告.html
│           ├── 高考后-志愿填报行动方案.html
│           ├── 中外合作办学专题分析报告.html
│           ├── 2026年浙江招生计划深度分析报告.html
│           └── 数字媒体技术院校深度调研报告.html
└── backend/
    ├── Dockerfile
    ├── requirements.txt
    ├── app.py
    ├── seed_data.py
    └── data/          ← SQLite 数据库文件（启动后自动创建）
```

### 第二步：启动容器

1. 打开群晖 **Container Manager**（Docker套件）
2. 左侧菜单 → **项目** → 点击 **新增**
3. 项目名称：`gaokao-portal`
4. 路径：选择 `docker/gaokao-portal/`
5. 来源：选择 **设置路径**（使用已有的 docker-compose.yml）
6. 点击 **下一步** → **完成**

系统会自动拉取镜像并构建启动。首次启动约需 2~5 分钟（含镜像下载）。

### 第三步：验证部署

浏览器访问：`http://<NAS的局域网IP>:8080`

你应该看到：
- 顶部横幅 "天恒高考志愿 · 家庭门户"
- 6张报告卡片（点击可查看完整报告）
- 3张问卷卡片（填写/查看汇总按钮）

## 使用指南

### 查看报告
首页点击任意报告卡片 → 浏览器直接打开完整报告（仅需 Nginx，无需后端）。

### 填写问卷
1. 首页点击问卷卡片的 **📝 填写问卷** 按钮
2. 输入您的称呼（如：爸爸、妈妈、天恒）
3. 逐题作答，点击 **✅ 提交答卷**

### 查看汇总
1. 首页点击问卷卡片的 **📊 查看汇总** 按钮
2. 横向对比所有家人的答案
3. 橙色高亮的行 = 家人之间观点不一致的题目

### 问卷内容说明

| # | 问卷 | 题数 | 类型 | 用时 |
|---|------|------|------|------|
| 1 | Holland 职业兴趣快速评估 | 20题 | 5级自评 | ~5分钟 |
| 2 | 院校偏好问卷 | 10题 | 单选/多选 | ~5分钟 |
| 3 | 家庭期望对齐问卷 | 8题 | 混合 | ~5分钟 |

> **建议填写顺序**：天恒先填 Holland 评估 → 父母各自填 → 全家人一起填院校偏好和期望对齐 → 查看汇总讨论差异。

## 常见问题

### Q: 浏览器打不开 8080 端口？
A: 检查群晖防火墙 → 允许局域网访问 8080 端口；确认容器在 Container Manager 中显示"运行中"。

### Q: 问卷加载不出来（卡片显示"无法连接后端服务"）？
A: 等 Flask 容器完全启动（首次构建 ~2分钟），刷新页面。

### Q: 数据存在哪里？换台电脑数据还在吗？
A: 数据存在 NAS 的 `backend/data/gaokao.db`（SQLite），容器重启/更新不会丢失。所有接入同一局域网的设备（手机/平板/电脑）都能访问同一份数据。

### Q: 怎么更新报告内容？
A: 替换 `nginx/html/reports/` 下的 HTML 文件，然后重启 Nginx 容器即可。无需重建。

### Q: 怎么导出问卷数据？
A: 在 Container Manager 中进入 `gaokao-backend` 容器的终端，执行：
```bash
sqlite3 /app/data/gaokao.db ".mode json" "SELECT * FROM responses;" > /app/data/export.json
```

## 安全说明

- 本服务仅供局域网使用，不暴露到公网
- 不涉及任何第三方云服务，数据完全在 NAS 本地
- 无用户密码认证（基于信任的局域网环境）
- 如需加强安全，可在群晖防火墙设置仅允许特定设备 IP 访问 8080 端口