格 格物 初一理科 · 3D 讲解
搜索知识点、公式、定律… 建议 · 愿望单 游客态 · 已存本地
系统架构图
v2.1 · 按 7 项新要求重绘
一句话:内容全部编译成静态文件,放在 CDN 上;浏览器只负责渲染和请求 3D; 「谁看过什么」才走云端。没有任何一台自家服务器在内容路径上 —— 这是抗攻击、抗并发、抗运维疲劳的根本。

● 游客(默认,占绝大多数)

打开就能看全部 517 条知识点与 92 个 3D 场景,不弹登录框。收藏与播放进度写 localStorage。

零鉴权 localStorage 兜底 可选升级为账号

● 登录用户

邮箱 + 6 位验证码登录,只买一件事:跨设备记住收藏、历史和看到第几拍第几秒。

httpOnly Cookie 登录后合并本地记录

● 搜索引擎 / AI 生成引擎

拿到与用户完全相同、但已是服务端渲染好的 HTML:完整正文、面包屑、JSON-LD、hreflang。

SSG 静态页 JSON-LD + sitemap llms.txt
1
边缘与安全层
唯一暴露在公网上的东西:一个静态 CDN,没有可打的后端
静态托管 / CDN
Cloudflare Pages 或 Vercel。全站 HTML + JS + GLB + mp3,无源站、无数据库直连。
安全响应头
CSP 只允许 self;X-Content-Type-Options、Referrer-Policy、Permissions-Policy 全开。
限流与反滥用
只对 3 个动态接口(验证码 / 反馈 / 收藏)限流;表单加无感验证码。静态资源零成本抗压。
缓存与预算
HTML 短缓存 + 版本化文件名;three.min.js 687KB、单 GLB < 2MB,均 immutable 一年。
2
静态内容层(构建产物)
这一层是"死"的:内容是死文件,所以 SEO、GEO、抗攻击三件事一次解决
137 个节 · 静态详情页
每节一个真实 URL(/math/7a/01/05/),首屏即有完整正文、面包屑、重点难点,不依赖 JS。
结构化数据
每页注入 LearningResource + BreadcrumbList + FAQPage,让搜索与 AI 直接引用。
多语言前缀
/zh/… 与 /en/… 并行,互挂 hreflang,缺译文时自动回退中文并标注。
发现类文件
sitemap.xml、robots.txt、llms.txt、RSS —— 全部由构建脚本生成,不手写。
3
3D 交互层
两套引擎,一个生命周期契约;同样是纯静态资源,零外网依赖
轻量线 · 手写 WebGL
数轴、天平、等高线这类"算得出来"的形状。单场景 < 150KB,当前 68 个可跑场景里绝大多数走这条。
精细线 · three.js + Blender
细胞、器官这类"雕得出来"的结构。GLB 由无头 Blender 脚本产出,可复现、可进版本控制。
统一挂载契约
mount / scrub(beat, t) / setLanguage / destroy。页面只认这四个方法,不认引擎。
时间即真相
所有形态是 t 的纯函数,可任意拖拽停顿;拍长由 mp3 真实时长反推,不手写常量。
4
状态层(唯一有后端的地方)
刻意做薄:三张表、四个接口。内容永远不经过这里
游客:localStorage
收藏、历史、第几拍第几秒全在本机。换设备就没了 —— 这是"不登录"的已知代价,页面上直说。
账号:托管 BaaS
Supabase 或 Firebase:users / favorites / history 三表,自带邮箱 OTP,不自建服务器。
反馈与愿望单
第 4 张表 feedback:纠错 / 想看的知识点 / 体验建议。投票直接回流排期。
合并与隐私
登录瞬间把本地记录并入云端,不丢;只存邮箱与进度,不埋点、不进排行榜、可一键删除。
内容构建管线 · 改 Markdown,全站更新
严格单源:01~03 总纲是唯一真值
① 真值源

output/01~03_知识点总纲.md
加 data/scenes.yaml(92 场景)
加 locales/*.json

② 校验

空节 / 空知识点 / 重复 ID 立即 exit(1);场景未挂节数必须为 0;公式噪声白名单

③ 编译

build_data.py → curriculum.js
同时生成 137 个静态 HTML、sitemap、JSON-LD、llms.txt

④ 门禁

一条 python tools/check_all.py 跑完 16 项检查,退出码即结论;CI 可直接接

⑤ 发布

产物目录整体上传 CDN,原子切换;回滚 = 换回上一个产物版本

7 项要求的落地位置
每条要求都能指到架构里的某一层,而不是一句口号
01 · 易维护扩展
层与层之间只有数据契约

内容 / 编译 / 渲染 / 状态四层单向依赖;加一节内容只改 Markdown,加一个场景只加一个文件 + 一条 yaml。

02 · 简洁易读
一个部件一个文件

色板字号全在 ds.css 的变量里;文案全部进数据,场景代码里不出现大段教学文本。

03 · SEO / GEO
内容在 HTML 里,不在 Canvas 里

137 个真实 URL + JSON-LD + 语义正文;3D 只是增强,爬虫拿到的和用户读到的是同一份文字。

04 · 多语言
URL 带语言前缀

/zh/ 与 /en/ 并列,hreflang 互指;译文缺失自动回退并标注,不阻塞上线。

05 · 游客可用
内容路径上没有鉴权

登录只解锁"跨设备记住"。全站任何一个 URL 都不存在登录墙;本地记录登录后可合并。

06 · 反馈与愿望单
反馈直接长在内容旁边

详情页每节都有"这节没讲清"入口;愿望单列出 52 节尚无 3D 的内容供投票,票数回流排期。

07 · 安全抗攻击
没有可打的目标

内容全静态,CDN 吸收流量;只有 3 个动态接口,全限流 + 验证码;CSP 禁一切第三方脚本。

代价
写这份架构要放弃什么

不做服务端个性化推荐、不做实时协作、不做评论区。孩子来这里是学知识,不是来社交。

六条不可违反的架构不变量(详见 AGENTS.md)

I1内容只从 Markdown 单一真值源生成,生成物禁止手改
I2形态变化必须是时间 t 的纯函数,禁止 dt 累积状态
I3运行期零第三方 CDN、零网络请求、零 webfont
I4内容路径上永不出现登录墙或鉴权判断
I5中文字一律 DOM 投屏,不做 3D 文字网格
I6单帧 draw call ≤ 160,超了先减面不是先调阈值
格物 · 初一理科 3D 讲解 · 系统架构图 v2.1 配套:AGENTS.md(不变量与门禁) | 页面设计稿见 01~09