【生活娱乐】 寻古迹「足不出户，览尽天下」
生活娱乐
1.组队参赛介绍：
先给大家介绍一下我们吧！我们是2个在校的学生，平均年龄只有14岁，性格都比较开朗，我们的队长，也就是专攻代码的，现在13岁，使用TRAE已经有490多天了，可以说是TRAE的老用户了，对VibeCoding也非常了解，有不会的技术也可以问他。暑假里每日就坐在电脑桌前使用TRAE来编写程序，非常享受自己从0到1创建一个产品的过程。
接下来就是我们队伍中的“点子王”兼“勤咨询”，他的年龄有15岁，是刚接触VibeCoding的，在队长开发寻古迹时，有不会或者有疑问的方面就会联系她，当然在我们的完善功能时，他也可以找到朋友与老师们，咨询他们的意见，反馈给队长来完善产品。
「抖音」我们的团队简介 抖音观看点我
2. 产品简介：
一、寻古迹是什么？
寻古迹 是一款以"足不出户，览尽天下"为核心理念的 文化遗产沉浸式 Web 平台 ，将「看、听、写、聊、游」集成在一个网站，它不是又一个文化科普页，而是一个能对话、能生成个性化旅行路线、能记录足迹的完整交互产品。聚焦解决三大痛点：
- 物理门槛高 ：千里奔波才能一睹古迹真容，偏远地区人群、残障人士、海外华人难以实地探访；
- 文化看不懂 ：走马观花式游览，对古迹的历史背景、建筑美学、文化价值缺乏深度认知；
- 体验留不住 ：传统游览缺乏个性化记录与互动分享，参观记忆难以沉淀为文化自觉。
平台通过数字技术整合 80处中国（含特别行政区）古迹 的影像资料、历史数据与AI能力，打造"可看、可听、可写、可游、可社交"的全链路文化体验。
二、寻古迹面向谁呢?
-
文化爱好者：周末在家深度"云游"敦煌莫高窟、故宫，通过AI讲解了解壁画故事与建筑细节
-
中小学生群体：历史课配套学习，在平台上完成历史景点的支持了解与探索，提交写日迹作品作为作业
-
旅行规划者：出行前通过平台预览目的地古迹详情、生成AI旅行攻略，规划最优行程
-
海外华人/留学生：通过平台"云返乡"，探访祖国名胜古迹，缓解乡愁，传承文化认同
-
残障人士：行动不便但渴望了解中华文明，通过平台无障碍功能实现文化访问
三、寻古迹的完整功能
五大核心模块，形成闭环体验：
一、寻古迹
平台核心模块，整合80处中华 （含特别行政区）古迹的影像资料与历史数据。支持朝代、地区、类型多维筛选与关键词搜索，动态聚合34种朝代值。每处古迹配备独立详情页，含精选影像画廊、AI导游语音讲解、世界地图三级下钻。所有景点无需登录即可查看，真正实现文化资源全民可达。
二、AI中心
智能赋能模块，提供三大服务：生成旅行攻略（每日推荐不重复景点，支持多轮追问调整行程）、AI历史讲解（深度解读古迹背景，配套小米MiMo导游音色TTS语音合成）。每次使用实时扣费，普通用户每日10万tokens额度，管理员无限制，剩余额度实时显示。
三、写日迹
内容创作模块，支持富文本编辑、景点关联。日迹可设公开或私密，公开日迹在闲谈迹社区展示供互动。编辑过程自动保存草稿，防止丢失。以时间轴形式展示所有记录，按日期倒序排列，支持按景点筛选。每条日迹包含标题、正文、关联景点、公开状态，作者可编辑删除。
四、闲谈迹
轻量化社区模块，含帖子广场（五大分类：游记/攻略/问答/讨论/晒图，30秒自动刷新）、公开日迹、私信系统（关注关系限制发送权限，支持会话搜索）、用户主页（展示足迹勋章关注）。配套通知系统，被点赞/评论/关注/私信时右上角彩色边框通知5秒消失，15秒增量轮询拉取新消息。
五、看足迹
个人成就模块，将浏览行为可视化。在地图上标记已探索古迹位置，按时间着色形成探索轨迹。时间线展示所有足迹记录，支持按景点/日期筛选。套数据统计：总浏览数、覆盖省份、最爱朝代分析，激励持续探索。
四、寻古迹对比初赛的 Demo 新增了哪些变化呢？
| 维度 | 初赛 Demo | 复赛成品 |
|---|---|---|
| 古迹数据 | 约30处国内古迹，信息简略 | 80处 （含特别行政区），附精选影像、历史资料、多维度标签 |
| AI 能力 | 基础对话功能 | AI攻略生成 + AI历史讲解 + AI照片生成 + 小米MiMo导游音色TTS ，全员扣费系统 |
| 社交体系 | 无 | 完整轻量化社区：帖子广场/评论点赞/私信关注/用户主页/通知系统 |
| 内容创作 | 文字编译+AI 生成 | 「写日迹」功能：支持图文记录、时间轴展示、公开/私密切换 |
| 地图能力 | 简单列表 | 世界地图三级下钻 ：国家→区域→景点，支持高亮与交互 |
| 视觉体验 | 基础样式，寻古迹与故宫红 | 「寻古迹」宣纸风主题 + 「故宫红」+「青花瓷」主题任选 + 页面切换动画 + 自研加载引擎 |
| 性能优化 | 未进行针对性优化 | Nginx静态缓存 + SQLite WAL模式 + 页面加载引擎优化 + 图片懒加载 + 字体延迟加载 |
| 用户系统 | 手机号注册+密码登录 | UID唯一标识 + 手机/UID双登录 + 验证码 + 游客模式 + TRAE审核登录 |
| 用户激励 | 无 | 通过访问古迹、发布帖子、发布日记即可获得免费称号 |
| 纪念系统 | 无 | 游览古迹后通过验证即可获得纪念票 |
| 足迹验证 | 无 | 通过用户拍照小米 Mimo V2.5 识别验证 |
| 维度 | 初赛 Demo | 复赛成品 |
|---|---|---|
| 稳定性 | AI 中心/日记编辑器无 null 守卫，重复点击可连发，异常易白屏 | 1.写日迹编辑器 requireEl 守卫 + 5s 超时降级 textarea + 骨架屏 + 草稿自动恢复 2. AI 中心系统性 guardResultDiv 守卫 + 三态防重复锁（覆盖 onerror/ontimeout 全分支） |
| AI 能力 | 同步非流式输出、单文本讲解、无图片理解 | 1.SSE 流式输出 （ /api/ai/chat-stream ，打字机效果）2. AI 识古迹 （MiMo v2.5 全模态视觉）3.TTS 导游语音 + 章节目录跳转 4.AI 记忆系统 （跨会话偏好/习惯学习、计入云配额） |
| 加载性能 | fonts.css 860KB 同步阻塞、5 CSS + 6 JS 全同步，首屏卡顿 | 自研 加载引擎 XGJLoader v3 ：Critical CSS 内联 + 异步 CSS（preload→swap）+ whenIdle/afterPaint + 图片懒加载 + 分阶段调度 runLoadPlan （字体→当前页图→寻古迹图→日记→帖子）； XGJRouter SPA fetch 极速切换 + hover/touch 预取 + LRU 缓存 |
| AI 导游影像联动 | 详情页仅静态图文 | 画廊图片「AI 讲解此图」多模态识别 + 右下 FAB AI 问答抽屉 + 攻略/讲解 导出图片/PDF |
| 移动端适配 | 窄屏紧凑、无精确断点 | mobile.css 精确适配 6.1/6.4/6.7 英寸断点、导航胶囊、底部搜索横条、抽屉 fixed 定位修复、PWA「添加到桌面」引导（Android beforeinstallprompt / iOS 图文） |
| 基础设施 | 同步加载、单一 AI 线路 | AI 多线路主备降级 （Deepseek 主 / MiMo 备 + 健康检查状态机）、SQLite+JSON 双存储回退、 /images/ 兜底路由、Nginx 反向代理 |
3. 产品演示视频：
「抖音」【中长度 4min29s】 抖音查看点我
「抖音」【长视频 7min17s】 抖音查看点我
4. 产品创作历程:
我们的队员都是一群热爱历史文化的学生，想着可以通过哪种方式来宣传与发扬我们的家乡文化以及中华传统文化呢？
在一天晚上，我们的队长在抖音上看到了这样一条视频：TRAE创造力大赛现在已经开启，任何人都能来报名，队长是一位使用TRAE已经快500天的选手。
队员们与我想到每次去参观博物馆、古建筑、历史遗迹时，总想要记录下当时的心境和感悟，但市面上的旅行App大多偏重于攻略、美食、住宿，缺少一个专门聚焦于"文化古迹探访"这一垂直场景的记录工具。很多人逛完古迹拍了照片就存在手机里，当时的感动和思考很快就淡忘了，需要一个专门的地方来珍藏这些文化记忆。在当时就通知了队员我们要不要做一个历史宣传平台呢？
大家都说可以啊。于是，寻古迹这个项目就正式启动了。在当时，已经有了介绍景点的单站点，我们想，我们是否可以在此基础上优化呢？把涉及一次旅行的需要做的全部集成为一个产品呢？
我们的功能正式敲定了，他就是寻古迹、写日迹、闲谈迹、看足迹以及AI中心。后续，我们就开启了长达20多天的开发。
开发过程肯定不是一帆风顺的，我们就遇到了很多的问题，古迹怎么找呢？我们采用了TRAE Work来上网查询资料，TRAE CN来写产品的页面，这样就保证了古迹的准确性与完整性，但是古迹这么多，不可能让Agent一个页面一个页面去写吧，这时候，队长想起了HTML+Flask的HTML 页面模板，我们的古迹页面就是由一个模板+当前古迹的专属图片与介绍组成的。
接下来，我们还遇到了云资源我们未满18周岁，无法认证，我们到处寻找资源，服务器采用香港服务器，不用进行ICP备案，域名采用腾讯云，要求不严格，短信认证我们接入了阿里云，支持个体办理，我们的云资源就像一个“拼好饭”，动用了许多不同厂商的资源。
开发时，AI的审美有点丑，怎么改都不行，队长提议，先写一个基础的前端HTML+Css的网页，然后让Agent提取设计文档，再应用到寻古迹页面里面，我们说干就干，方法果然奏效，页面的美观程度上来一个台阶。
期间，我们还找了许多位老师，朋友，同学来“锐评”我们的作品 ，但大家几乎给了我们一个答案“不会评价、挺不错的”，于是我们搭建了一个自我评分的系统，我们就知道了哪些地方要改，哪些地方做的好可以保留等等。
在1个月后，寻古迹的复赛阶段终于完工了。
5.我们的技术栈
总技术栈
| 层级 | 技术 |
|---|---|
| 后端 | Python 3.10 + Flask + Gunicorn |
| 数据库 | SQLite 3 (WAL模式) + JSON文件存储 |
| 前端 | 原生 HTML5 + CSS3 + JavaScript (ES6) |
| 反向代理 | Nginx + 腾讯云CDN加速 |
| 部署 | Linux (宝塔面板) + systemd守护进程 |
后端
| 层 | 主语言 | 说明 |
|---|---|---|
| 语言 | Python 3.10 | 主语言 |
| Web 框架 | Flask | 单文件 app.py （7600+ 行，164 条路由），按注释分区组织 |
| 应用服务器 | Gunicorn 4 workers (sync) | 端口 「不便进行展示」，SIGHUP 热重载 |
| 数据存储 | SQLite (WAL 模式) | 兼容层 core/db.py ，KV 表 + 内存缓存 |
| 文件回退 | JSON 文件 | data/*.json （30+ 数据文件），DB 不可用时降级 |
| HTTP 客户端 | requests | 调用外部 AI / 短信 API |
| 图片处理 | Pillow (PIL) | 智能压缩、缩放、WebP/JPEG 转换 |
| 二维码 | qrcode | 分享码生成 |
| 验证码 | 自研滑块验证（PIL 绘制） | core/captcha.py |
| 短信 | 阿里云 dyPNS API | core/sms_service.py |
前端
| 维度 | 技术选型 | 说明 |
|---|---|---|
| 模板引擎 | Jinja2 | SSR 渲染 + window.DATA 数据注入，避免首屏空白 |
| 样式体系 | 原生 CSS + CSS 变量 | 三套主题（宣纸金、故宫红、青花瓷），按 base/components/pages/themes 模块化拆分 |
| 脚本 | 原生 JavaScript (ES5+) | 无构建步骤、无框架依赖，按 core/pages 拆分 |
| 图表 | ECharts | 足迹地图、数据看板（中国【含特别行政区】 GeoJSON 自绘） |
| 加载引擎 | XGJLoader v3 （自研） | 进度条 + CSS/JS 异步加载 + 首屏淡入，见 static/js/xgj-loader.js |
| 图标 | 内联 SVG | Feather 风格，支持 currentColor 动态着色 |
| 字体 | 自托管 webfont | 毛笔体（马善政）、宋体（Noto Serif SC）、站酷字体，按 unicode-range 分包 |
| PWA | manifest.webmanifest + install-prompt.js | 离线能力 + 「添加到桌面」弹窗（Android 用 beforeinstallprompt ，iOS 图文引导） |
| 响应式 | 媒体查询 + 移动端 mobile.css | 精确适配 6.1/6.4/6.7 英寸断点 |
AI 能力
| 线路 | 模型 | 用途 |
|---|---|---|
| 主线路 | Deepseek 深度求索 deepseek-v4-pro | 文本生成、JSON 格式 |
| 备用文本 | 小米 Mimo mimo-v2.5 | 文本生成 + 联网搜索（MIMO_TEXT_ENABLE_SEARCH=True ） |
| TTS 语音 | 小米 MiMo mimo-v2.5-tts-voicedesign | 导游语音合成 |
| 视觉 | 小米 MiMo Vision mimo-v2.5 | AI 识古迹（图片输入） |
基础设施
| 技术 | 说明 |
|---|---|
| Nginx | 反向代理（→ 127.0.0.1:5001），gzip 压缩，静态资源 30 天缓存，HTTP/2 + HTTP/3 |
| systemd | 守护进程（景点图片爬取器） |
| crontab | 每日 0:00 自动入库景点图片 |
| Wikimedia Commons API | 景点图片爬取，429 限流重试 |
| 组件 | 配置 |
|---|---|
| 操作系统 | Ubuntu 22.04 服务器 |
| 反向代理 | Nginx ：静态资源缓存、gzip、SSL， location /images/ alias 服务配图，转发 / → :5001 |
| 应用服务器 | Gunicorn 4 workers (sync)，端口 5001， debug=False 生产模式 |
| 进程管理 | Gunicorn SIGHUP 热重载， app.pid 跟踪 |
| 数据目录 | data/ （SQLite xunguji.db + WAL + 30+ JSON 文件） |
| 静态目录 | static/ （css/js/fonts/images）+ image/ （景点原图）+ imagespro/ （精选图）+ image_cache/ （压缩缓存） |
| 环境变量 | .env 管理阿里云 dyPNS、MiMo TTS 密钥 |
| 资源配额 | 用户每日 10 万 token AI 限额 / 管理员无限 / 游客 50 次；云存储配额含 AI 记忆体积 |
架构说明书
业务层调用
load_json('users')
│
▼
┌───────────────────────────────────────────┐
│ core/db.py 兼容层 │
│ │
│ 1. 内存缓存 (_cache, TTL 60s) ← 命中返回 │
│ 2. SQLite kv_store 表 ← 主查询 │
│ 3. data/*.json 文件 ← 回退兜底 │
└───────────────────────────────────────────┘
分层架构
┌─────────────────────────────────────────────────────────────┐
│ 用户浏览器 (Client) │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────┐ │
│ │ XGJLoader v3 │ │ 页面 JS/CSS │ │ SSR 注入数据 │ │
│ │ (加载引擎) │ │ (按页面拆分) │ │ window.__DATA__ │ │
│ └──────────────┘ └──────────────┘ └───────────────────┘ │
└───────────────────────────────┬─────────────────────────────┘
│ HTTPS
┌───────────────────────────────▼─────────────────────────────┐
│ Nginx (反向代理) │
│ 静态资源缓存 · gzip · SSL · 转发 / → :5001 │
└───────────────────────────────┬─────────────────────────────┘
│
┌───────────────────────────────▼─────────────────────────────┐
│ Gunicorn (4 workers, Flask app) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ app.py — 路由层 (164 routes) │ │
│ │ 页面路由 · API 路由 · 登录拦截装饰器 · CORS │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ 业务层 │ │
│ │ AI 中央调用 · 云空间配额 · 图片压缩 · XSS 净化 │ │
│ │ 访问日志 · 用户会话 · 收藏 · 足迹 · 社区 │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ 数据访问层 (core/db.py) │ │
│ │ load_json / save_json → SQLite(WAL) + 内存缓存 + 文件回退│ │
│ └──────────────────────────────────────────────────────┘ │
└───────┬───────────────────────┬───────────────────┬─────────┘
│ │ │
┌────▼────┐ ┌───────▼──────┐ ┌──────▼──────┐
│ data/ │ │ 外部 AI 线路 │ │ 阿里云短信 │
│SQLite │ │ Deepseek/MiMo │ │ dyPNS │
│+JSON │ └───────────────┘ └─────────────┘
└─────────┘
健康检查机制
┌─────────────────────────────────────┐
│ check_deepseek_health(force) │
└─────────────────────────────────────┘
冷却期内(fail_until>now)?──是──► 返回 False（直接用 MiMo）
│否
▼
最近成功过(last_success<30s)?──是──► 返回 True（跳过探测）
│否
▼
缓存有效(checked_at<30s)?──是──► 返回缓存结果
│否
▼
实际探测：POST /v1/chat/completions {max_tokens:1, "ping"}
│
┌───────┴───────┐
▼ ▼
200 OK 失败/超时
标记可用 标记失败
fail_until=0 fail_until=now+60s
页面切换过渡
点击站内链接时的过渡流程（`xgj-loader.js:111` + `base.html` 内联）：
```
用户点击站内 a 链接
│
▼
拦截 click（排除 ctrl/meta/shift/alt、target=_blank、外链、hash）
│
▼
进度条立即推到 40%（即时反馈）
│
▼
#page-transition-overlay 添加 .active（深色遮罩淡入 250ms）
同时 sessionStorage['xgj_transition'] = '1'
│
▼ 等待 250ms 确保遮罩完全覆盖
window.location.href = link.href ← 旧页面卸载，遮罩仍在屏
│
▼ 新页面 HTML 到达
内联 bootstrap 检测 sessionStorage → html.xgj-transitioning（遮罩立即可见）
│
▼ Critical CSS 解析、内容渲染
DOMContentLoaded → fadeOutOverlay()
│
▼ 双 rAF（确保遮罩先绘制一帧）
移除 .xgj-transitioning / .active → 遮罩淡出
.main-content 执行 xgj-enter 入场动画（opacity .5→1, translateY 8px→0）
部署拓扑
```
Internet ──HTTPS──► Nginx (443/80)
│ 反向代理 + 静态资源 + gzip + SSL
▼
Gunicorn (0.0.0.0:5001, 4 workers, sync)
│ preload_app=False, timeout=180s
│ max_requests=1000 + jitter=50（防内存泄漏）
▼
Flask app (app.py)
│
┌────┴────┐
▼ ▼
data/SQLite 外部 API
自研 XGJRouter v1 SPA 加载引擎
在 XGJLoader 整页过渡之外，进一步提供 **fetch 局部刷新**的极速切换：
```
用户点击站内 <a>
├─ 事件捕获：排除 ctrl/meta/shift/alt、target=_blank、外链、
│ /api/、/static/、/images/、/imagespro/、纯 hash
├─ shouldIntercept(href) 通过 且 非 data-no-spa
│ ▼
R.navigate(fullUrl)
│ ├─ 进度条 setProgress(30)（即时反馈）
│ ├─ fetchPage(url)：内存缓存 → 预取中 → fetch(credentials:same-origin)
│ │ 解析出 <title> + main-content + EXTRA_JS_BEGIN/END + EXTRA_CSS_BEGIN/END
│ ├─ replaceContent(data)：
│ │ 更新标题 → 淡出旧内容 → 清理上页专属 CSS(data-xgj-page-css)
│ │ → 注入新页 extra_css → 替换 main.innerHTML → 注入 extra_js
│ │ → evalScripts(main) → 入场动画 → 滚动置顶
│ │ → 派发 xgj:navigate / DOMContentLoaded 事件（各页面 JS 重新初始化）
│ │ → 重新 initLazyImages()
│ └─ history.pushState 更新 URL
└─ fetch 失败 → window.location.href 整页回退（优雅降级）
```
目录结构
```
xunguji/ # 寻古迹项目根目录
│
├── app.py # Flask 主应用（7600+ 行，164 路由，AI 中央调用）
├── start_flask.sh # 守护脚本（每 10s 探测，非 200 自动重启）
├── app.pid # Gunicorn 进程 PID
├── .env # 环境变量（阿里云短信/MiMo TTS 的 API Key）
├── .user.ini # open_basedir 限制配置
│
├── core/ # 后端核心模块
│ ├── db.py # 数据兼容层（SQLite+WAL+JSON回退+内存缓存）
│ ├── captcha.py # 滑块验证码（PIL 绘制 + token 校验）
│ ├── sms_service.py # 阿里云 dyPNS 短信（频率限制 + 验证）
│ ├── data/ # captcha 运行时数据目录
│ └── static/uploads/captcha/ # 验证码图片输出目录
│
├── templates/ # Jinja2 模板（30 个页面）
│ ├── base.html # 全局基座（导航/侧边栏/页脚/加载引擎/主题）
│ ├── index.html # 首页
│ ├── home_v2.html # 新首页（隐藏入口，见第 14 章）
│ ├── explore.html # 寻古迹列表（SSR 注入景点数据）
│ ├── explore-detail.html # 景点详情
│ ├── attraction-detail.html # 景点详情（备选模板）
│ ├── attractions-map.html # 古迹地图
│ ├── timeline.html # 历史长河
│ ├── compare.html # 景点对比
│ ├── diary.html # 日迹列表
│ ├── diary-edit.html # 日迹编辑（富文本）
│ ├── diary-detail.html # 日迹详情
│ ├── footprint.html # 看足迹
│ ├── footprints.html # 足迹地图
│ ├── topics.html # 帖子广场
│ ├── topic_detail.html # 帖子详情
│ ├── chat-trace.html # 闲谈迹（社区）
│ ├── chat-user.html # 用户主页/私信
│ ├── ai-center.html # AI 中心
│ ├── ai-guide.html（见 docs/archive） # AI 导游
│ ├── ai-photo.html（见 docs/archive） # AI 图片生成
│ ├── gugong.html # 故宫专题
│ ├── jiangkou.html # 江口沉银专题
│ ├── video-intro.html # 宣传视频
│ ├── profile.html # 个人中心
│ ├── favorites.html # 我的收藏
│ ├── dashboard.html # 数据看板
│ ├── admin.html # 管理后台
│ ├── login.html # 登录
│ ├── rate.html # TRAE 评分
│ ├── verify-images.html # 图片审核
│ ├── about.html # 关于我们
│ └── terms.html # 服务条款
│
├── static/ # 前端静态资源
│ ├── favicon.svg # 站点图标
│ ├── echarts.min.js # ECharts 可视化库
│ ├── china.json # 中国省份 GeoJSON 地图数据
│ ├── world.json # 世界地图数据
│ │
│ ├── js/
│ │ ├── xgj-loader.js # 加载引擎 XGJLoader v3（进度条+异步CSS+懒加载+过渡+runLoadPlan）
│ │ ├── core/ # 核心模块（跨页面复用，12 个）
│ │ │ ├── main.js # 全局主入口（事件绑定+初始化）
│ │ │ ├── xgj-spa.js # SPA 极速路由 XGJRouter（fetch 切换+预取+缓存）
│ │ │ ├── global-search.js # 全局搜索（搜索 Tab + AI 助手 Tab）
│ │ │ ├── user-sync.js # 用户状态同步（localStorage→导航栏）
│ │ │ ├── user-card.js # 用户简介卡片（data-user-card）
│ │ │ ├── tts.js # 语音合成（MiMo 导游音色 + 浏览器 TTS）
│ │ │ ├── read-aloud.js # 朗读模式（双击文字触发 TTS）
│ │ │ ├── captcha.js # 滑块验证码前端
│ │ │ ├── animations.js # 过渡与交互动画
│ │ │ ├── tracker.js # 用户行为追踪
│ │ │ └── install-prompt.js # 移动端「添加到桌面」引导（见第 13 章）
│ │ ├── components/ # 复用组件目录
│ │ └── pages/ # 页面级模块（按需加载，20 个）
│ │ ├── home.js # 首页逻辑
│ │ ├── explore.js # 寻古迹列表（渐进式渲染）
│ │ ├── explore-detail.js # 景点详情（77KB，最大页面脚本）
│ │ ├── diary.js / diary-detail.js / diary-edit.js # 日迹
│ │ ├── footprint.js / footprints.js # 足迹
│ │ ├── chat-trace.js # 闲谈迹（68KB，社区+私信）
│ │ ├── chat-user.js # 用户主页
│ │ ├── topics.js / topic_detail.js # 帖子
│ │ ├── ai-guide.js # AI 导游
│ │ ├── admin.js # 管理后台（54KB）
│ │ ├── profile.js # 个人中心（51KB）
│ │ ├── gugong.js / jiangkou.js / jiangkou-pro.js # 专题
│ │ ├── login.js # 登录
│ │ └── attraction-detail.js # 景点详情
│ │
│ ├── css/
│ │ ├── style.css # 全局样式（57KB）
│ │ ├── theme-porcelain.css # 青花瓷主题
│ │ ├── gugong.css # 故宫专题样式
│ │ ├── login.css # 登录页样式
│ │ ├── base/ # 基础层
│ │ │ ├── style.css # reset + 排版 + 颜色变量
│ │ │ ├── fonts.css # 字体（font-display: swap）
│ │ │ ├── accessibility.css # 无障碍 + 大字模式
│ │ │ ├── animations.css # @keyframes 全局动画
│ │ │ ├── mobile.css # 移动端适配（见第 13 章）
│ │ │ └── large-screen.css # 大屏适配
│ │ ├── components/ # 组件层
│ │ │ ├── ai-guide.css / captcha.css / compare.css / user-card.css
│ │ ├── pages/ # 页面层（按页面拆分）
│ │ │ ├── home.css / home-v2.css / explore.css / explore-detail.css / diary.css / diary-edit.css
│ │ │ ├── footprint.css / footprints.css / favorites.css
│ │ │ ├── gugong.css / jiangkou.css / jiangkou-pro.css
│ │ │ ├── admin.css / ai-center.css / ai-photo.css
│ │ │ ├── attraction-detail.css / chat-trace.css / timeline.css / topics.css
│ │ └── themes/ # 主题层
│ │ ├── theme-palace.css # 宫殿红主题
│ │ └── theme-porcelain.css # 青花瓷主题
│ │
│ ├── fonts/ # 自托管 Web 字体
│ ├── images/ # UI 图片资源
│ ├── img/ # 杂项图标（二维码、logo）
│ ├── maps/ # 地图辅助数据
│ └── uploads/ # 用户上传
│ ├── avatars/ # 用户头像
│ ├── ai-photos/ # AI 生成图
│ ├── diaries/ # 日记配图
│ └── captcha/ # 验证码图
│
├── image/ # 景点主图库（161 张 jpg/webp，/image/ 路由分发）
├── image_cache/ # 智能压缩缓存（自动生成，800px WebP）
├── images/ # 景点原图备库（分规格）
├── imagespro/ # 专题图片（江口沉银等，/imagespro/ 路由分发）
│
├── data/ # 数据存储目录
│ ├── xunguji.db # SQLite 主库
│ ├── xunguji.db-wal # WAL 预写日志
│ ├── xunguji.db-shm # 共享内存索引
│ ├── access_logs.json # 访问日志（截断 20000 条）
│ ├── users.json # 用户数据
│ ├── attractions.json # 景点数据（629KB）
│ ├── diaries.json / likes.json / comments.json # 日记相关
│ ├── topics.json / forum_*.json # 社区帖子/私信/通知
│ ├── footprints.json / user_footprints.json # 足迹
│ ├── daily_token_usage.json / guest_ai_quota.json # AI 配额
│ ├── captcha_store.json / verify_tokens.json / local_codes.json # 验证
│ ├── admin_config.json / admin_password.json / admin_login_ips.json# 后台
│ ├── qr_history.json / photo_generations.json # 历史记录
│ ├── user_contexts.json / user_favorites.json # 用户上下文/收藏
│ ├── scores.json / share_tokens.json # 评分/分享
│ ├── ip_location_cache.json / attraction_views.json # IP库/浏览量
│ ├── gallery_staging/ # 景点图片爬取暂存（90 个景点子目录）
│ ├── image_staging/ # 图片暂存（82 个子目录）
│ ├── crawler.log # 图片爬虫日志（8MB）
│ └── vendors.json / trae_login_config.json # 第三方/TRAE
│
├── scripts/ # 开发/运维脚本
│ ├── gunicorn_config.py # Gunicorn 部署配置（4 workers, timeout 180）
│ ├── crawler/ # 图片爬虫
│ │ ├── attraction_crawler.py # 景点信息爬取
│ │ ├── attraction_gallery_crawler.py # 景点图库爬取（每景点上限 50 张）
│ │ ├── ingest_daily_images.py # 每日 0:00 图片入库
│ │ └── setup_crawler.sh # 爬虫环境初始化
│ ├── data/ # 数据脚本
│ │ ├── add_sichuan_attractions.py # 添加四川景点
│ │ └── convert_type_to_chinese.py # 类型字段转中文
│ ├── enrich/ # 数据富化
│ │ ├── _enrich_gugong.py # 故宫数据富化
│ │ ├── _enrich_jiangkou.py # 江口沉银富化（3 个版本）
│ │ ├── _enrich_jiangkou_full.py
│ │ └── _enrich_jiangkou_more.py
│ ├── update/ # 数据更新
│ │ ├── update_attractions_data.py # 景点数据更新
│ │ ├── update_attraction_images.py # 景点图片更新
│ │ ├── _update_images.py
│ │ └── _update_local_images.py
│ ├── images/ # 图片下载
│ │ ├── download_images.py # 图片下载（3 个版本迭代）
│ │ ├── download_images_v2.py
│ │ ├── download_images_v3.py
│ │ ├── download_real_attraction_images.py
│ │ ├── download_real_images.py
│ │ └── generate_attraction_images.py
│ ├── download_attraction_images.py # 景点图片下载
│ ├── download_wiki_images.py # 维基百科图片下载
│ ├── fix_images.py # 图片修复（3 个版本）
│ ├── fix_images2.py
│ ├── fix_images3.py
│ ├── gen_featured_images.py # 精选图片生成
│ ├── get_correct_images.py # 正确图片筛选
│ └── tests/ # 短信测试脚本
│ ├── _test_check_sms.py
│ ├── _test_send_response.py
│ ├── _test_sms_debug.py
│ └── _test_verify_debug.py
│
├── docs/ # 项目文档
│ ├── 寻古迹架构说明书.md # 本架构说明书
│ ├── SPEC.md # 功能规格说明
│ ├── 功能详情.md # 功能详情
│ ├── 介绍.html # 项目介绍页
│ ├── 宣传视频拍摄.md # 宣传脚本
│ ├── 寻古迹配色.md / 青花瓷配色.md # 配色规范
│ ├── debug-qr-ai-favorite-errors.md # 调试记录
│ └── archive/ # 归档
│ ├── ai-guide.html # 归档的 AI 导游页
│ └── ai-photo.html # 归档的 AI 图片页
│
├── .trae/ # Trae 平台配置
│ ├── documents/ # 设计文档
│ │ ├── 云数据配额功能.md # 配额功能实施计划
│ │ ├── 加载引擎优化方案.md # 前端加载优化
│ │ ├── attraction-gallery-image-crawler.md # 图片爬虫技能
│ │ └── country-region-i18n.md # 国家地区国际化
│ └── skills/attraction-image-crawler/
│ └── SKILL.md # 景点图片爬取技能定义
│
├── skills/ # 独立技能脚本
│ └── trae-scoring-system.py # TRAE 评分系统
│
├── assets/ # 静态素材归档
│ ├── backups/ # 原图备份
│ │ ├── _original_backup_image/ # 单图备份
│ │ └── _original_backup_images/ # 多图备份（长城/三星堆/故宫等）
│ └── originals/ # 原始素材
│
├── logs/ # 日志归档
│ ├── app.log # 应用日志
│ └── flask*.log # Flask 历史日志
│
├── .well-known/ # SSL ACME 验证目录
├── .dbg/ # 调试环境配置
│ └── qr-ai-favorite-errors.env # 调试用环境变量
│
└── PROJECT_STRUCTURE.md # 目录结构速查（旧版简版说明）
```
6.商业化或社会价值分析
商业化计划：
I.联合景点官方推出定制化服务，通过与景点的签约来采样、推流、丰富详情页面等。
II.设置在线云售票，在寻古迹购票，寻古迹抽取 10%-15% 的提成。
III.用户使用 AI 的 Token Plan 订阅计划，或者 AI 使用次数的额度购买。
IV.接入景点官方的文创周边商城，抽取10%-15% 的提成。
社会价值分析：
我们以“足不出户，览尽中华”为核心理念，不是简单的古迹信息聚合，而是 文化遗产的全民转译实验 ，其社会价值锚定三维：
- 打破文化访问的物理门槛 ：覆盖近百余处古迹，通过沉浸式影像、AI智能讲解（带导游级语音）、虚拟导览，让偏远地区学子、残障人士、海外华人无需奔波千里，即可触碰敦煌壁画的笔触、故宫斗拱的逻辑，甚至读懂碑刻篆文背后的朝代故事——解决了实体古迹“看不懂、跑不动”的痛点，让文化资源真正全民可达。
- 激活文化参与的私人表达 ：通过「写日迹」「看足迹」「帖子广场」功能，把“看古迹”变成“做文化”：用户可记录专属文化足迹、分享攻略游记，让个人记忆成为集体文化的补充——比如中学生的故宫研学日迹，能成为同龄人学习明清历史的鲜活素材；海外华人的中国古迹足迹，能成为中外文化交流的民间纽带。
- 筑牢文化自信的生活载体 ：把宏大的“中华文明”拆解成可触摸的体验：AI生成专属旅行攻略、朝代筛选定位兴趣古迹、私信邀约同好共探，让文化从课本知识点，变成用户主动靠近的生活方式——尤其对Z世代而言，这种“沉浸式参与”比被动背书更能筑牢文化认同。
未来若联动AR实景、更多地方古迹，“寻古迹”有望成为 全民参与的文化数字基建 ，让千年文明在指尖延续。
7.产品迭代计划
核心定位升级：从「古迹浏览工具」→「全民文化沉浸基建」，以“内容提级+体验破圈+生态闭环”为路径，分三阶段落地：
- P1（0-3个月：补能提留存）
- 内容提级：为80处（含特别行政区）古迹自动生成15s竖屏微纪录片（整合现有图库+AI剪辑），替代失效的视频介绍页，适配移动端碎片化浏览；
- 社交激活：上线「朝代任务体系」，联动“看足迹”路径，完成5个不同朝代古迹足迹解锁专属文化勋章（如“清·故宫探路者”），勋章可展示于「闲谈迹」个人主页；
- 拉新机制：新增“邀请好友得AI Token”规则（每人周限2万），扩大AI中心的使用频次。
- P2（3-6个月：沉浸扩边界）
- WebAR落地：古迹详情页新增「AR复原」按钮，无需APP即可在浏览器查看故宫斗拱、敦煌壁画的虚拟复原（轻量框架实现）；
- 国际扩容：新增20处“一带一路”沿线古迹（吴哥窟、泰姬陵等），补充多语种AI讲解，服务海外华人文化需求；
- 教育端口：为中小学校提供专属入口，老师可发布「虚拟研学任务」，学生提交「写日迹」作品即完成作业（免费）。
- P3（6-12个月：生态提价值）
- UGC孵化：「古迹守护人」计划，用户上传高清实拍图经审核后替换平台低质图，获专属标识；
- AI个性化升级：针对学生/老人提供定制讲解口吻；
- 文旅数据输出：生成「全国文化兴趣热力图」，向地方文旅局提供数据参考，反哺实体古迹保护。
8. TRAE 实践过程:
1.TTS导游朗读语音的接入
SeccionID：.1106581134777257:cb91d02364d1c3c7b465499165ff4a8a_6a40c863bfcec1078c2f3943.6a662a7738a01c612694e519.6a662a768080ff2c1948796b:Trae CN.T(2026/7/26 23:40:39)
2.添加全局搜索框，AI生成水印，地图可视化等微调
SeccionID：.1106581134777257:9db08ecf3094aa0abe3333a5143eacb2_6a40c863bfcec1078c2f3943.6a64c76feede7fff1f21bf11.6a64c76ed0d26b4f59e01ded:Trae CN.T(2026/7/25 22:25:51)
3. 数据上云存储，从本地+上传备份改为一直有服务器提供
SeccionID：.1106581134777257:db11df5b3438b3a21fa06b01c615f0ea_6a40c863bfcec1078c2f3943.6a646805eede7fff1f21b4fb.6a646805b1ed57d26cda0adb:Trae CN.T(2026/7/25 15:38:45)
4. 创建闲谈迹页面
SeccionID：.1106581134777257:d6889ebf74379905ab713bff2b49f334_6a40c863bfcec1078c2f3943.6a64304beede7fff1f21a94e.6a64304a5107fb648673aeba:Trae CN.T(2026/7/25 11:40:59)
5. 闲谈迹界面优化、
SeccionID：.1106581134777257:99d8975f7618712c3683b7b7b0342a2f_6a40c863bfcec1078c2f3943.6a644f28eede7fff1f21afae.6a644f27b1ed57d26cda0ad3:Trae CN.T(2026/7/25 13:52:40)
6. 短信验证服务接入
SeccionID:.1106581134777257:3fce8c6338c7370f114a4421ede0d7de_6a40c863bfcec1078c2f3943.6a525978bce0fb1a80c3b219.6a525976ed00d52aa21302a2:Trae CN.T(2026/7/11 22:55:52)
7.创建管理员后台
SeccionID：.1106581134777257:3640dead1d0b2b4d611935537109d599_6a40c863bfcec1078c2f3943.6a4f7878632a894b0619d97d.6a4f78775cee6d7c151f49fa:Trae CN.T(2026/7/9 18:31:20)
8.丰富四川省份的景点
SeccionID：.1106581134777257:76b31da43eeb2dfe572fb7467b9002b9_6a40c863bfcec1078c2f3943.6a464e6a471c598ade62be42.6a464e6ac6b906bccad2c5a5:Trae CN.T(2026/7/2 19:41:30)
9.创建寻古迹项目
SessionID: .1106581134777257:ef54bf0d7872fa73bcacc249679cf7e4_6a3e178510c1cdebf2b86873.6a3e1b8610c1cdebf2b86875.6a3e1b868a410c5917e95165:Trae CN.T(2026/6/26 14:26:14)
注意：上述SeccionID与开发截图为从后往前（日期），当上述SeccionID 失效/无法核验，可以尝试解压缩下方额外材料，其中包含.docx 格式的 寻古迹 SeccionID 材料[寻古迹 不会写的Wang Seccion证明材料.docx]。如还是不行，可以通过赛事预留电话联系队长重新获取。
额外材料：寻古迹 SeccionID 材料.zip (4.3 MB)
