一个帮助中国家庭规划博物馆参观的互动应用，让孩子爱上博物馆之旅。

在线访问： 微信/抖音/快手 让孩子爱上博物馆 小程序 https://博物馆打卡.cn/ https://museumcheck.cn/

无需安装，打开网页即可使用！支持手机和电脑访问。

博物馆专用页面： museum-checkin.html - 适合博物馆通过二维码引导访客使用

📚 完整文档： Wiki文档中心 - 详细使用指南、开发文档和项目信息

• 收录中国主要博物馆，覆盖全国各省市区：故宫博物院、中国国家博物馆、上海博物馆、秦始皇帝陵博物院、南京博物院、湖北省博物馆、陕西历史博物馆、中国科学技术馆、苏州博物馆、浙江省博物馆、广东省博物馆、四川博物院、河南博物院、辽宁省博物馆、山东博物馆、天津博物馆、中国美术馆、湖南省博物馆、西藏博物馆、新疆维吾尔自治区博物馆、云南省博物馆、内蒙古博物院、重庆中国三峡博物馆、青海省博物馆、黑龙江省博物馆、宁夏博物馆等
• 支持参观进度追踪，实时显示完成百分比
• 每个博物馆提供详细介绍和标签分类

支持三个年龄段的个性化内容：

• 3-6岁 (学龄前)：简单有趣的观察活动和游戏
• 7-12岁 (小学)：教育性强的探索任务和知识学习
• 13-18岁 (中学)：深度分析和学术研究项目

每个博物馆提供两套清单：

• 家长准备事项：参观前的准备工作和引导建议
• 孩子探索任务：年龄适宜的参观任务和学习目标

• 使用浏览器localStorage保存所有数据
• 无需注册账号，隐私友好
• 数据持久保存，支持多次访问

简化的数据管理策略，单一数据源保证内容一致性：

• KV Store (AWS Lambda)：唯一数据源，保证内容最新最准确
• 浏览器缓存 (localStorage)：7天过期策略，支持离线访问已浏览博物馆
• 元数据 (museums-meta.js)：轻量级首页列表（~50KB），快速加载

优势：

• 单一数据源，无需维护多个副本
• 按需加载，用户只下载访问过的博物馆数据
• 智能缓存，离线也能查看已访问的博物馆
• 成本友好，当前流量完全在 AWS 免费额度内
• 未来可扩展：流量增长时可引入 CDN 优化

详细说明：参见 简化架构文档

专为博物馆现场体验设计的独立页面：

• 二维码接入：博物馆可在烟花墙放置二维码，访客扫码即可使用
• 孩子任务专注：大卡片展示，适合儿童操作
• 渐进式UX：完成任务后自然引导家长了解更多功能
• 可嵌入：支持嵌入博物馆官网
• 编辑模式：博物馆工作人员可在线编辑任务内容
• 详细文档：Museum Check-in Documentation

• 完全免费：无需注册账号，打开即用
• 隐私安全：所有数据保存在您的浏览器本地
• 跨设备支持：手机、平板、电脑都能完美使用
• 中文界面：专为中国家庭设计

1. 点击上方链接打开应用：https://museumcheck.cn/
2. 选择您孩子的年龄段（3-6岁、7-12岁或13-18岁）
3. 浏览全国主要博物馆列表
4. 点击感兴趣的博物馆，查看详细的参观指南
5. 使用家长准备清单做好参观前准备
6. 带孩子完成探索任务，勾选完成的项目
7. 所有进度自动保存，下次打开继续使用

本应用旨在通过博物馆亲子游增进亲子关系，以下是完整的功能模块和用户交互流程：

• 博物馆列表展示：卡片式网格布局展示全国主要博物馆

  • 每张卡片显示：博物馆名称、位置、简介、特色标签
  • 访问状态标记：已参观的博物馆显示打勾标记
  • 点击卡片打开详细信息模态框

• 搜索功能：实时搜索博物馆名称、城市或标签

  • 搜索框带清除按钮
  • 显示搜索结果数量
  • 即时过滤，无需点击搜索按钮

• 进度追踪：顶部显示参观进度统计

  • 已参观数量 / 总数量
  • 完成百分比
  • 视觉化进度展示

• 三个年龄段选择：3-6岁、7-12岁、13-18岁
  • 单选按钮形式，默认选中3-6岁
  • 切换年龄段后，所有内容自动调整
  • 不同年龄段显示不同难度的任务和内容

打开任何博物馆卡片后，显示包含以下内容的全屏模态框：

• 标签式导航：

  • "专家指导"标签：显示权威的亲子参观建议和互动技巧
  • "家长准备"标签：参观前准备事项清单
  • "孩子任务"标签：适龄的探索任务清单
  • "亲子测评"标签：完成参观后的亲子关系评估问卷

• 清单功能：

  • 复选框形式，可勾选完成的项目
  • 进度自动保存到本地存储
  • 按年龄段显示不同的任务内容

• 快捷操作：

  • 标记博物馆为"已参观"
  • 强制签到功能（即使未完成任务也可标记）
  • 关闭按钮返回列表

• 成就获得条件：

  • 参观第1个博物馆："启程"成就
  • 参观第5个博物馆："探索者"成就
  • 参观第10个博物馆："收藏家"成就
  • 参观第20个博物馆："专家"成就
  • 参观第50个博物馆："大师"成就
  • 完成100%博物馆："传奇"成就

• 成就展示：

  • 成就按钮显示已获得成就数量
  • 点击打开成就模态框，展示所有成就
  • 每个成就显示图标、名称、描述和获得状态

• 成就海报生成：

  • 一键生成个性化成就海报
  • 包含参观统计、成就列表、二维码
  • 可下载保存到手机相册
  • 用于社交媒体分享

• 测评入口：

  • 在博物馆详情页"亲子测评"标签中
  • 从首页"测评历史"按钮进入

• 测评流程：

  • 家长问卷：5题关于家长与孩子互动的问题
  • 孩子问卷：5题关于孩子与家长互动的问题
  • 每题4个选项，评分0-3分

• 测评结果：

  • 总体得分（满分60分）
  • 各维度详细分析
  • 改善建议和具体行动指引
  • 历史得分趋势对比

• 测评历史：

  • 按时间倒序展示历史测评记录
  • 显示平均得分、最新得分
  • 按博物馆过滤查看
  • 导出测评数据（JSON格式）

• 烟花触发：

  • 完成孩子任务后自动放烟花庆祝
  • 烟花动画在页面上方爆炸展示

• 烟花墙展示：

  • 点击烟花按钮打开烟花墙模态框
  • 左侧：实时烟花动画区域
  • 右侧：成就卡片列表
  • 显示每个博物馆的完成成就

• 烟花设置：

  • 11种烟花类型可选：爱心、星形、螺旋、蝴蝶、玫瑰等
  • 烟花留存时间设置：1分钟到1天
  • 按博物馆过滤查看烟花
  • 手动放烟花演示功能

点击左上角设置图标打开设置模态框：

• 孩子信息：

  • 输入孩子昵称（最多10个字符）
  • 显示当前年龄组
  • 切换年龄组（立即生效）

• 烟花设置：

  • 调整烟花留存时间（滑块控件）
  • 选择烟花类型（下拉列表）

• 应用信息：

  • 显示博物馆总数量
  • 版本信息和更新日志

• 本地存储：

  • 所有数据保存在浏览器localStorage
  • 无需注册账号，隐私友好
  • 包括：参观记录、清单进度、成就、测评结果、设置偏好

• 清空数据：

  • 清空所有数据按钮（垃圾桶图标）
  • 二次确认对话框防止误操作
  • 清空后重置所有进度

• 数据导出：

  • 导出测评历史为JSON文件
  • 包含所有测评记录和元数据
  • 用于数据备份或迁移

• 跨设备适配：

  • 手机、平板、电脑完美适配
  • 触摸友好的大按钮设计
  • 模态框自动调整大小

• 交互反馈：

  • 按钮悬停效果
  • 卡片点击缩放动画
  • 操作成功提示通知
  • 加载状态指示器

1. 打开应用，看到博物馆列表
2. 选择孩子年龄段（3-6岁、7-12岁或13-18岁）
3. 浏览博物馆卡片，点击感兴趣的博物馆
4. 阅读"专家指导"了解如何进行亲子互动
5. 查看"家长准备"清单，勾选完成的准备事项
6. 查看"孩子任务"清单，了解参观时的探索任务
7. 完成参观后，勾选已完成的任务
8. 标记博物馆为"已参观"，触发烟花动画
9. 完成"亲子测评"，获得关系评估反馈
10. 查看获得的成就

1. 使用搜索功能查找目标城市的博物馆
2. 逐个点击查看博物馆详情和任务清单
3. 根据"家长准备"清单提前做功课
4. 下载成就海报分享到家庭群

1. 定期查看参观进度和成就
2. 查看测评历史，观察亲子关系变化趋势
3. 调整互动方式，持续改善亲子关系
4. 生成成就海报记录成长历程

• 纯前端应用：HTML + CSS + JavaScript，无后端依赖
• 零延迟加载：所有数据内置，无需网络请求
• 离线可用：下载后可完全离线使用
• 隐私保护：数据仅存储在用户本地，不上传服务器
• 性能优化：快速渲染，流畅动画，低内存占用

• 中国风配色：传统文化色彩（故宫红、青花蓝）
• 扁平化风格：现代简洁的界面设计
• 图标化导航：emoji图标增强识别性
• 亲子友好：大字体、高对比度、易读易用
• 沉浸式体验：全屏模态框，专注内容

这个应用的设计理念是通过游戏化和任务化的方式，解决"孩子不喜欢逛博物馆"的问题。通过年龄分层的内容设计和互动清单，让博物馆参观变成一个有趣的探险游戏，增进家庭互动，培养孩子对文化和历史的兴趣。

项目现在拥有完整的Wiki文档系统，包含：

• 用户指南 - 详细的使用说明和最佳实践
• 功能详解 - 完整的功能介绍和使用方法
• 常见问题 - 问题解答和疑难排解
• 开发环境设置 - 本地开发环境配置
• 项目架构 - 技术架构和代码结构
• 贡献指南 - 如何参与项目开发
• 博物馆列表 - 完整的博物馆信息
• 更新日志 - 详细的版本历史
• 路线图 - 未来发展规划

访问 Wiki首页 获取完整导航。

项目支持两种博物馆数据管理方式：

• 集中管理模式 (推荐) - 所有博物馆数据（包括工作流）集中在单个文件中

  • 示例：museums/pinghu-museum.js（平湖博物馆）
  • 优势：易于维护，内容创作更高效
  • 详见 CENTRALIZED_DATA_PATTERN.md 完整说明

• 分离管理模式 (兼容) - 工作流数据在 workflows-data.js 中统一管理

  • 适用于已有的博物馆
  • 系统自动兼容两种模式

该项目使用集中式版本管理系统：

• 所有版本信息存储在 script.js 的 RECENT_CHANGES 对象中
• HTML 文件只包含占位符，由 JavaScript 动态更新
• 使用 validate-version.js 脚本验证版本一致性

更新版本时：

1. 编辑 script.js 中的 RECENT_CHANGES 对象
2. 运行 node validate-version.js 验证一致性
3. 详见 VERSION_MANAGEMENT.md 完整指南

# 启动本地服务器
python3 -m http.server 8000

# 验证版本一致性
node validate-version.js

# 运行单元测试
npm test

# 访问应用
# http://localhost:8000

项目提供了 MCP 服务器，使 GitHub Copilot 能够在开发时访问中国官方博物馆数据库：

# 安装依赖
npm install

# 启动 MCP 服务器
npm run mcp:start

# 测试博物馆搜索 API
node tools/test-mcp-museum-search.js

功能特性：

• 搜索中国官方博物馆数据库（search_official_museums 工具）
• 获取真实的博物馆统计数据（藏品数量、参观人数、质量等级等）
• 与 GitHub Copilot 无缝集成，辅助开发过程

详细文档： 参见 MCP_SETUP.md 了解配置和使用方法

从 KV Store 导出静态文件：

# 导出所有博物馆数据到静态文件
npm run export:kvstore

# 预览将导出哪些博物馆（不实际写入文件）
npm run export:kvstore:dry-run

# 强制覆盖现有文件
npm run export:kvstore:force

# 导出特定博物馆
node tools/export-kvstore-to-static.js --museum forbidden-city

# 详细文档
# 参见 tools/README_EXPORT_KVSTORE.md

开发新博物馆内容：

1. 在 museum-data-manager.html 中编辑和上传到 KV Store
2. 在开发模式中测试验证
3. 使用 npm run export:kvstore 导出为静态文件
4. 提交静态文件到版本控制

完整文档：

• 三级数据管理系统
• 导出工具使用指南
• 数据管理界面

MuseumCheck 采用动态优先的两级数据架构，已移除对 Tier 3（museums-data.js）运行时依赖：

Tier 2: 远程存储 (KV Store)  ← 优先
  ↓
Tier 1: 静态文件 (/museums/{museum-id}.json)  ← 回退/发布路径

首页列表使用 museums-meta.js 轻量元数据；博物馆详情始终通过数据加载器按 Tier 2 → Tier 1 获取，缺失时提示网络问题而不再回退到单体数据文件。

• 用途：已验证、稳定的博物馆数据
• 位置：/museums/{museum-id}.json
• 优势：快速加载、版本控制友好、可缓存
• 示例：

  # 创建新的博物馆静态文件
  cat > museums/example-museum.json << 'EOF'
  {
    "id": "example-museum",
    "name": "示例博物馆",
    "location": "北京",
    "description": "这是一个示例博物馆",
    "tags": ["历史", "文化"],
    "checklists": { ... }
  }
  EOF

• 用途：开发中的博物馆数据、A/B 测试、快速迭代
• 位置：云端 KV 存储（AWS Lambda + DynamoDB）
• 优势：无需部署即可更新、支持在线编辑
• 管理界面：访问 museum-data-manager.html
• 操作：
  1. 点击设置 → 管理远程数据
  2. 上传/编辑/删除博物馆数据
  3. 设置过期时间（开发数据建议 1-7 天）

• 状态：museums-data.js 已移除运行时依赖，仅保留为历史产物，后续将删除
• 替代：首页用 museums-meta.js，详情用 Tier 2 → Tier 1 加载；离线场景会提示网络问题而非回退到陈旧数据

优先级固定为 远程存储 → 静态文件（Tier 2 → Tier 1）。

• 设置里即使选择包含 tier3，加载器也会自动过滤，确保不回退到过时的单体数据。
• 离线场景：首页可凭 museums-meta.js 显示列表，但详情会提示检查网络或使用已缓存的数据。

# 步骤 1：在远程存储中创建草稿（开发调试）
# 访问 museum-data-manager.html，上传新博物馆数据，设置过期时间为 7 天

# 步骤 2：验证内容
# 在设置中切换到"开发模式"，测试新博物馆数据

# 步骤 3：稳定后发布为静态文件
# 将数据导出为 JSON 文件，保存到 /museums/ 目录

# 步骤 4：如需发布，导出静态文件并提交 /museums/{id}.json；不再更新 museums-data.js

# 步骤 1：在远程存储中更新
# 使用管理界面编辑博物馆数据

# 步骤 2：验证更新
# 测试确认更新正确

# 步骤 3：同步到静态文件
# 更新对应的 JSON 文件

# 步骤 4：无需更新 museums-data.js；保持 Tier 2 → Tier 1 流程

// 获取数据加载器实例
const loader = window.museumDataLoader;

// 加载单个博物馆（按优先级自动选择数据源）
const museum = await loader.loadMuseum('forbidden-city');

// 加载所有博物馆列表
const museums = await loader.loadAllMuseums();

// 更改优先级
loader.updatePrioritySettings(['tier2', 'tier1', 'tier3']);

// 保存数据到远程存储
await loader.saveToKVStore('museum-id', museumData, expireTimestamp);

// 删除远程数据
await loader.deleteFromKVStore('museum-id');

// 清除缓存
loader.clearCache(); // 清除所有缓存
loader.clearCache('museum-id'); // 清除特定博物馆缓存

# 运行单元测试
npm test

# 运行数据加载器测试
npm test -- tests/museum-data-loader.test.js

# 测试覆盖率
npm run test:coverage

问题：博物馆数据未更新

• 检查数据源优先级设置
• 清除浏览器缓存：museumDataLoader.clearCache()
• 检查远程存储是否有新数据
• 验证 JSON 文件格式是否正确

问题：远程数据加载失败

• 检查网络连接
• 验证 KV Store API 是否可访问
• 查看浏览器控制台错误信息
• 确认数据未过期

问题：静态文件 404

• 确认文件路径：/museums/{museum-id}.json
• 检查文件命名是否匹配博物馆 ID
• 验证 HTTP 服务器配置

欢迎贡献新的博物馆数据！请遵循以下流程：

1. Fork 本仓库
2. 创建功能分支
3. 使用远程存储测试新数据
4. 验证通过后创建静态文件
5. 提交 Pull Request
6. 参与代码审查

详见 wiki/Contributing.md

/workspaces/MuseumCheck/
├── 📱 核心应用（根目录 - 用户可访问）
│   ├── index.html              # 主应用首页
│   ├── script.js               # 主应用逻辑
│   ├── style.css               # 应用样式
│   ├── museum-checkin.html     # 博物馆签到页面
│   ├── achievements.html       # 用户成就页面
│   ├── treasures.html          # 镇馆之宝展示页面
│   ├── settings.html           # 设置页面
│   ├── event-wall.html         # 事件墙/社区页面
│   └── fireworks-wall.html     # 烟花墙页面
│
├── 🛠️ /admin/                   # 管理后台（不需搜索引擎索引）
│   ├── index.html              # 管理后台首页（导航卡片菜单）
│   ├── museum-data-manager.html # 博物馆数据管理工具
│   ├── admin-everyone-achievements.html # 成就管理
│   ├── admin-leaderboard.html  # 排行榜管理
│   ├── admin-fireworks.html    # 烟花墙管理
│   └── admin-treasure-reports.html # 镇馆之宝报告
│
├── 📚 /js/                      # JavaScript模块
│   ├── museum-data-loader.js   # 数据加载器（KV Store）
│   ├── wikimedia-image-search.js # 维基百科图片搜索
│   ├── baidu-image-search.js   # 百度图片搜索
│   ├── image-upload-util.js    # 图片上传工具
│   └── ... 其他模块
│
├── 🎨 /css/                     # 样式文件
│   ├── style.css               # 主样式
│   └── ... 其他主题
│
├── 🔧 /core/                    # 核心数据管理层
│   ├── data-manager.js         # 统一数据管理器
│   ├── multi-cloud-config.js   # 多云配置
│   └── storage/                # 存储适配器
│
├── 🧪 /tests/                   # 测试文件
│   └── pages/                  # 测试页面
│
├── 📜 /scripts/                 # 构建/部署脚本
│   ├── migrate.sh              # 数据迁移脚本
│   └── setup-tech-spec-and-testing.sh # 环境配置脚本
│
├── 🔨 /tools/                   # 开发工具
│   ├── batch-process-museums.js # 批量处理博物馆
│   └── ... 其他工具
│
├── 📚 /docs/                    # 文档（已整理）
│   ├── SIMPLIFIED_ARCHITECTURE.md # 架构文档
│   ├── api/                    # API文档
│   └── guides/                 # 开发指南
│
├── 📊 /data/                    # 数据文件
│   └── museums-meta.json       # 博物馆元数据
│
├── 📦 /backup/                  # 备份文件
│   └── archive-2026-01-14.tar.gz # 历史备份（压缩）
│
├── 📋 package.json             # 项目依赖配置
├── 📋 robots.txt               # 搜索引擎爬虫规则
└── 🤖 CNAME                     # GitHub Pages自定义域名

✅ 已完成的重构：

1. 统一AWS KV端点：所有配置默认使用AWS Lambda KV Store，保留多云架构能力
2. 创建/admin/目录：所有管理后台页面集中到 /admin/ 目录，robots.txt屏蔽索引
3. 重设计数据管理器：修复脚本路径，简化为KV-Only架构，移除Tier 1/3遗留代码
4. 整理根目录：脚本移至 scripts/，工具移至 tools/，测试页面移至 tests/pages/
5. 压缩备份：历史JSON文件压缩为 archive-2026-01-14.tar.gz
6. 添加多云文档：在 core/README.md 添加多云配置说明
7. 更新robots.txt：屏蔽 /admin/ 目录，防止搜索引擎索引管理后台

📋 项目结构优化：

• 根目录精简：仅保留用户应用文件和配置文件
• 后台文件集中：所有管理工具统一在 /admin/ 目录
• 开发文件规整：脚本、工具、测试分别放在对应目录
• 访问权限明确：通过目录结构和robots.txt明确界定公开和私有内容

1. http://nb.ncha.gov.cn/museum.html