workbuddy-claude/2026gaokaozhiyuan

Files

T

变更摘要:
- [fix] 清理根目录 index.html 遗留代码（questionnaire-error + retryLoad 移除）
- [fix] 副标题同步更新为自估591分 + 候选志愿546条数据校准
- [fix] 页脚注入版本号 v1.0.0
- [fix] 部署版 index.html: 取消家长标签，统一 filler-tianheng
- [fix] Dashboard 文案修正（4份→2份线上问卷）
- [fix] 清理冗余部署脚本（v1-v4归档至 archived_scripts/）
- [fix] 等效位次工具纳入 deploy 目录
- [chore] .gitignore 初始化
- [init] Git 仓库初始化

2026-06-24 13:11:34 +08:00

14 KiB

Raw Blame History

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

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 移动端适配

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

3.4 颜色系统

--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 会自动更新家庭偏好参数）

14 KiB Raw Blame History Unescape Escape