天体视运动实验室：完整开发逻辑与维护说明

版本基准：sky-motion-lab-cloudflare-article-refined.zip。编写日期：2026年10月6日，北京时间。

本文描述当前实际实现，并解释每个关键设计的目的。它是一份开发与交接文档；《学习指南》面向学生的操作任务，《项目介绍与地理模型说明》面向使用者的项目特点、计算依据和模型限制，三者用途不同。

1. 项目目标与规划顺序

项目把传统依赖 Flash 的太阳视运动演示，扩展为浏览器即可访问的天体运动实验室。学生应能改变地点、日期或时刻，同时看到天空位置、轨迹和读数的响应，不需要安装插件。

开发首先确定教学概念和时间标准，再建立计算模型，最后设计交互与视觉表现。界面不能通过动画掩盖模型含义，也不能把示意比例表现成真实比例。

开发遵循以下顺序：

1. 确定观察任务：一天内运动、相同时间跨日期比较、纬度与季节比较、月相、日影、日晷、日行迹、行星伴月。
2. 为每项任务确定改变的变量、保持的变量、输出结果及特殊情况。
3. 明确太阳与月球的时间控制和状态边界。
4. 建立统一时间换算、天空坐标及科学计算方法。
5. 让不同视图消费同一组结果，避免各图独立估算造成矛盾。
6. 建立画面、常用时间控制、参数菜单三个稳定区域。
7. 增加动画、主题、欢迎页和独立说明页面。
8. 验证边界情况、触屏交互、页面跳转、响应式布局及打包产物。

现有功能覆盖常见太阳视运动教学任务，并增加月球、行星和生活装置演示。但没有原始“小黄鸭”程序的完整源码与逐项验收基准，不能把这种功能扩展等同于已证明与原程序百分之百一致。

2. 技术方案与运行边界

项目是静态多页面网站：HTML、CSS、原生 JavaScript、Canvas 2D，以及本地分发的 Astronomy Engine 2.1.19。页面生成工具使用 Python。

没有必需的后端服务、数据库、登录系统或实时星历 API。浏览器直接计算天体位置。Canvas 中的三维天球和装置，是三维坐标经过数学投影后绘制的二维画面，当前没有使用 WebGL 或 Three.js 渲染器。

界面采用 Material Design 的表面层级、主色容器、圆角、选中态、展开态和焦点反馈；没有引入完整 Material 组件库，不能称为经过全部 Material 规范认证的组件实现。

资源使用相对路径，适合 Cloudflare Pages 静态托管。核心脚本、样式和纹理在交付包内，不依赖外部字体加载。当前没有 Service Worker，不能承诺首次断网打开或安装为离线应用。

3. 页面与信息架构

全局导航保持“欢迎页、实验台、学习指南、关联图解”。日晷和日行迹属于太阳相关专题，放入太阳的菜单层级，不占用月球模式的全局导航空间。

太阳关联图解包括直射点与昼夜、全天高度曲线、日出日落和地轴与地平面。月球关联图解包括月相与关系、逐日照明比例、月出月落和行星伴月。切换天体后，无法用于该天体的图解会退回有效的默认图解。

4. 当前文件职责

现有脚本采用传统全局作用域和有顺序的 script 加载，不是 ES Modules。大量功能通过 DOM ID 和共享函数连接，因此改名、删除节点或调整加载顺序必须检查所有引用。

5. 数据、界面与绘图的关系

科学状态决定精确读数，视觉插值改善过渡。插值不覆盖实际选择的日期、时刻或地点。学生读到的科学参数不能随着缓动随意变化。

6. 太阳与月球的状态逻辑

modeStates.sun 和 modeStates.moon 各自保存状态，state 指向当前天体的状态。两者共用坐标和星历工具，但拥有独立的演示更新函数及参数。

共同字段包括纬度、经度、日期、观测时刻、视图、相机和轨迹开关。太阳使用赤纬、理想／日期模式、杆高、日影倍率、逐日模式及日行迹相关字段；月球使用按日／按时刻播放、行星伴月和行星选择等字段。

切换到月球，不会强制让太阳的逐日播放设置成为月球的一天内播放设置。切回太阳，也不应把月球地点与时间写入太阳。

有一个刻意设置的例外：在太阳界面叠加月球时，月球位置使用当前太阳实验的地点、日期与时刻，便于同一物理时刻比较。它不改写独立月球实验的状态。

独立日晷和日行迹页面使用太阳状态的副本，保存时把有关字段写回太阳状态。日行迹的每日观测时刻由 analemmaClock 保存，避免与主实验台的一天内时刻混淆。

会话使用 sessionStorage 的 skyLabSession 保存，不是服务器账户，也不是永久同步。点击页面链接及离开页面时保存状态。恢复时不会自动恢复正在播放的状态。

7. 时间标准与日期处理

主实验台采用当地真太阳时；720分钟为12:00，1440分钟为24:00。它不是北京时间或手机时区时间。

太阳时角目标为：

H = (t − 720) / 4，单位为度

solarNoonUTC() 以经度和太阳赤经寻找当地太阳过中天的 UTC 时刻；instantUTC() 再通过时角迭代，把所选当地真太阳时转换为物理 UTC 时间。太阳、月球和行星必须使用同一个换算结果。

日期处理使用显式 UTC 日期构造，防止宿主时区改变日期。主界面允许的日期范围是1900—2100年；这只是界面范围，不代表对范围内每一天都进行了精度验证。

一天内播放改变时刻；固定时刻逐日播放改变日期，保留时刻。月球默认的教学核心是按日期比较月相，也允许切换到一天内的天空位置变化。

太阳逐日模式遇到24:00时，先推进日期并归零时刻，再刷新赤纬。年末、闰年、月份末尾和日期上下界分别处理。日期不参与理想太阳模型，界面应明确禁用或说明这一点。

日行迹还提供固定钟表时：以指定 UTC 偏移换算每天的观测时刻。当前偏移固定，不自动处理夏令时。

8. 坐标与太阳计算

本地天空方向使用单位向量：x向东、y向上、z向北。高度角为 asin(y)，方位角由 atan2(x,z) 转换到0°—360°；正北0°、正东90°、正南180°、正西270°。

太阳有两条计算路径。

真实日期观测：用 Astronomy Engine、地点和 UTC 计算站心赤道坐标，再转换成未计折射的地平坐标。界面赤纬和地球昼夜图使用相应的太阳赤道信息。

理想实验：固定赤纬δ，使用纬度φ和时角H分析自转、纬度与季节的几何关系：

sin(高度角) = sinφ sinδ + cosφ cosδ cosH

理想实验可用于赤纬0°、±23.44°等比较，但不能把固定赤纬结果说成某日期完整真实星历。

直射点由太阳赤纬和地球恒星时关系确定。昼夜分界使用地面法向量与太阳方向的点积。世界平面图采用经纬度等距展开，会产生面积与形状变形。

分至日按钮通过当前年份的太阳黄经事件搜索得到当地日期。按钮与对比线名称沿用北半球称呼；南半球季节相反。

9. 升落与时长计算

真实日期下，全天首先每5分钟采样，然后在候选区间进一步求最高／最低位置和高度角0°的穿越时刻。

日出、日落、月出、月落统一采用天体几何中心穿越理想地平线的标准。全天在地平线上方、全天在下方、没有某项升落事件、理想模型中的相切，以及极点临界状态，分别输出相应提示，不能强行构造普通升落时刻。

实际时长按这些区间对应的 UTC 时间差统计，而不是直接把真太阳时刻度差当作精确经过时间。

时长标签旁的可展开说明明确：未计大气折射、天体视半径和地形遮挡；月球地平视差已计入天空位置。真实观测时刻会不同，不能用统一的“提前／推迟5分钟”修正所有地点与日期。

极点的方位以及天顶附近的方位应提示定义不唯一或不适合判读，避免输出一个看似精确的数字作为唯一答案。

10. 月相与月面朝向

月球位置与月相分开计算：天空位置是站心位置，照明比例使用地心视月相近似。月相名称根据月相角及主要相位附近区间生成；“附近”不表示精确相位发生时刻。

月相图展示地球所见圆盘的亮面比例，不能将它解释成月球整体受光面积；月相也不是地球影子遮挡造成的。

当前有两种月面显示：

• 月相原理图和普通空间轨迹图使用固定朝向，明确标注为示意。
• 仰望天空根据当地天空几何方向转动亮边，不采用“南纬直接左右翻转”。

后一种做法取月球方向单位向量m和太阳方向s，计算朝向太阳的切向分量：

tangent = s − (s · m)m

再将这一切向方向经过当前天空投影，求屏幕上的角度并旋转月相图。地点、时间和视图方向都通过向量及投影参与结果。圆盘仍是放大示意，不模拟月面纹理、天平动或食的遮挡；新月／满月附近亮边朝向也不易辨认。

11. 轨迹连续性与视图投影

太阳与月球轨迹最终采用同一方向坐标体系，分别计算样本。空间视图、俯视、方位—高度图和仰望天空通过不同投影展示它们。

绘制时在实际几何地平线处插入边界顶点，地平线上方用实线，下方用虚线。方位展开跨越北向0°／360°时拆分线段，在两侧边缘正确结束和开始，避免从一侧横穿全图。

月球当天轨迹覆盖00:00—24:00。月球在一天内沿轨道移动，前后位置通常不同；因此不强制把两端闭合，并在可显示位置标明端点。这个真实开口不能当成渲染断裂去补线。

太阳与月球叠加时，共用时间、地点与投影。单位天球轨迹与地面的米制影长使用不同的明确标注尺度，不能混作同一物理距离。

12. 日影、影尖轨迹与全年观察

水平地面上的竖直立杆高为h，太阳方向为 (sx, sy, sz) 时：

影尖 x = −h × sx / sy
影尖 z = −h × sz / sy
影长 = sqrt(x² + z²) = h / tan(太阳高度角)

只在太阳高于地平线时产生有限直射日影。太阳位于天顶时影长为零，贴近地平线时影长趋于无穷，低于地平线时不画直射日影。

日影倍率只改变显示的地面范围，不改变科学影长。当前倍率1、2、4、8、16，对应地面圆半径 6.25 / 倍率 米。超出范围的当前影尖用箭头表示；影迹线段真正裁切到圆内，不能把所有越界点硬压到圆周制造虚假轨迹。

全天影尖轨迹按一天采样，记录同一立杆在不同时刻的影尖。固定时刻逐日模式记录不同日期同一当地真太阳时的太阳位置及影尖；两者分别对应“一天”和“一年”，界面不能混淆。

13. 两种互动日晷

日晷与前面的竖直杆不同：晷针与地轴平行。

水平日晷的晷面水平，晷针指向所在半球的天极，仰角为纬度绝对值。其时刻线通常不等距；赤道处经典水平日晷退化，需要给出无法读时的说明。

赤道日晷的盘面平行赤道面，针垂直盘面，相邻整点线相差15°。太阳赤纬改变会使受光面切换，两面刻度应镜像。光线平行或接近平行盘面时，读时和影尖具有特殊限制。

模型通过太阳方向与晷面求光线交点，得到真实影子；立体装置和盘面安装视图使用同一模型。可调针长，点击刻度或拖动影子调时，也可播放一天。

当前类型的“晷上读时”位于参数区顶部，类型切换同时切换读数、画布和对应说明。夜间、水平晷退化、光线平行赤道晷面分别显示相应状态，不能继续输出貌似可实测的时刻。

日晷读当地真太阳时；对照钟表用固定 UTC 偏移计算。地点经度和均时差会造成两者差异。

14. 日行迹与“8”字成因

日行迹是在同一地点、不同日期、同一观测时间定义下的太阳位置集合。首先确定时间依据，再生成全年样本，不能直接复用某一天的轨迹。

固定钟表时通常形成经典“8”字：地轴倾斜使赤纬随年变化，倾斜与轨道偏心共同影响均时差和时角。固定当地真太阳时的太阳时角基本固定，不形成同样的经典“8”字。

项目提供三维天球正投影、方位—高度展开、时角—赤纬原理图，并可比较09:00、12:00、15:00。改变时间后保持相机，不用自动换相机掩盖轨迹位置变化。时角—赤纬图的自动缩放仍需由提示说明，不能要求每个视图都表现成相机拍摄的天空图。

高级理想模型允许分别改变地轴倾角和轨道偏心率。轨道位置通过求解开普勒方程建立，逐项改变参数用于分析成因；它不替换其他真实天体的星历。

dome视图的画布接管双向触屏手势，参数区独立滚动。拖动改相机，点击轨迹或日期滑块改观察日期，改变钟表时只改日行迹自己的观测时间。

15. 行星伴月与仰望天空

行星伴月支持水星、金星、火星、木星和土星。月球与行星在同一物理时刻计算，球面角距为：

角距 = acos(clamp(月球单位方向 · 行星单位方向, −1, 1))

未来搜索逐日检查未来最多30天、每天相同观测时刻，选择角距最小的一天。它不是全天连续寻优，也不是精确合相时刻。

界面同时给出高度与地平线条件。白天、暮光、月相、天气与地形都会影响实际可见性，不能把“角距小”直接标成“肉眼一定能看到”。

仰望天空使用观察者前方半球的正投影，地平面在下方。只有地平线上方、位于前方的天体绘入天空；身后或地平线下的天体通过列表说明。转向改变观察方向，时间滑块改变天体位置，两个控制都必须能直接操作。

16. 完整更新与动画调度

用户操作一般执行：停止有关播放、更新字段、调用 schedule()。schedule() 置更新标志，并请求主要 requestAnimationFrame 调度。多个相邻操作可以合并到下一帧。

当前一次完整 render() 的顺序是：

准备太阳跨日与联动状态
→ 同步视觉过渡目标
→ 更新工作区布局
→ 太阳或月球读数与控件
→ 菜单、日影、叠加、伴月、观察者、逐日、日行迹、日晷
→ 时间工作台
→ 最终页面可见性
→ drawMotionCanvases()

完整更新的 UI 函数不再启动第二轮绘图。最终绘图入口依据天体及可见性绘制天空、图表、地球、月相、升落方位、日行迹和日晷。

普通连续播放可在多数动画帧只更新画面，按约100毫秒间隔更新需要的完整 UI；按日推进或有新的用户输入时触发完整更新。相机和相邻日期位置使用缓动，精确科学状态与过渡画面分离。

IntersectionObserver 跟踪画布可见性，ResizeObserver 跟踪容器尺寸；隐藏画布不做无意义的实际绘制。实验画布像素比限制到2，欢迎页限制到1.5，控制高分辨率设备的负担。

页面进入后台时暂停发起动画帧，返回时重置帧时间，避免把后台停留时间当成一个巨大的播放步长。尊重减少动态效果偏好，降低或取消非必要过渡。

17. 路由、链接与浏览器历史

普通页面使用真实 HTML 链接。关联图解页另外使用 hash 标识当前图，例如：

diagrams.html#riseSetPanel
diagrams.html#chartPanel

初次加载读取 hash。点击同页菜单时，hashchange 将地址同步到选中图解；点击顶部标签时，pushState 建立历史记录并更新选中项；前进后退通过 popstate 恢复画面。

改变当前天体后，再校验该天体允许的图解。伴月图解在月球模式下启用相应内容。链接、标签、可见画布和详情应在一次完整更新中保持一致。

验收不能只看地址改变：还必须检查正确画布可见、标签选中正确、时刻和日期仍可调、浏览器前进后退与刷新有效。

18. 多端布局与交互原则

宽屏使用左侧参数区，右侧图形和其下的时间条。手机竖屏按图形、时间条、参数区排列。短横屏恢复左右结构，以保留画面高度。

实验页面固定在视口内，参数区内部滚动。图形与时间条使用独立网格区域，避免悬浮时间台盖住画面。常用时刻、日期和观察方向优先放在可见控制区；低频参数放在分层折叠菜单中。

用统一的卡片宽度、边界与表面颜色区分结果和输入；展开菜单与收起菜单有不同背景、文字及箭头颜色。焦点状态可见，原生 details 可用键盘展开，时长说明也采用可展开结构。

触屏操作的画布和滑块必须按目的设置 touch-action：三维旋转不能保留浏览器的纵向滚动接管，参数阅读区域则应正常滚动。通过单一事件更新状态，不能先展示临时选中态再由旧状态覆盖回来。

欢迎页三个角落链接使用等宽布局。星空玩具是虚构互动，不连接真实星座数据，也不改变实验状态。联系页面展示作者邮箱与具体反馈要求。

19. 当前初始化和生成方式

实验页加载基础样式和公共 HTML，再按有序 script 定义科学、交互与动画函数。app.js 建立默认状态并初始化旧公共节点；之后 page-navigation.js 恢复会话、选择专属页面的太阳状态、重组节点为当前工作区，调用同步与完整更新。

实验页面生成时已排除欢迎页和作者联系弹窗，欢迎页只保留星空互动与原生跳转；联系内容用于独立联系页。完整开发文档通过项目介绍中的入口进入独立阅读页，也提供Markdown下载。其他旧实验结构仍有共享初始化依赖，清理前需检查引用。

执行页面生成：

python3 sunlab/tools/build-pages.py
python3 sunlab/tools/build-development-guide.py

这会从公共模板生成实验、日晷、日行迹、图解、欢迎、学习指南、联系和404页面。学习指南有独立源文件。项目介绍从 tools/project-guide.html 复制到dist，新增说明应整合到相关章节。JavaScript、CSS和资源由对应文件维护。

目前没有统一的 npm 构建链。修改共享结构时应改模板并重新生成；修改学习指南时应改其源文件；修改运行脚本和样式时直接维护 dist 内相应文件。项目说明源HTML与导出的Markdown需要保持一致；按钮使用明确的前景与背景色，避免通用链接颜色覆盖按钮文字。

20. 测试和验收逻辑

每次修改按影响范围选择检查，不以“页面能打开”作为唯一通过标准。

已经完成的近期验证包括：

• 7种纬度、4个日期、3个时刻，共84组月面亮边方向公式对照，以及4个旋转方向的实际像素明暗检查。
• 春分附近与跨年推进日期后，立即更新赤纬。
• 日晷两种类型在600、900、0分钟的读数、说明及夜间状态。
• 图解四个太阳菜单链接、浏览器前进后退、刷新与月球伴月切换。
• Chromium移动触屏纵向拖动产生连续 pointermove 与 pointerup，没有 pointercancel。
• 对真实画布绘制入口计数，每个可见画布在一次完整更新中绘制一次。
• 320×568、390×667、844×390、1280×720的视图、滑块、菜单和独立页面回归。
• 8组内部科学回归：最大高度对照差约0.00125°，升落时刻对照差约0.00030分钟。

这些数值是特定样本的内部一致性结果，不是与独立观测台对照得到的全范围精度认证。当前实际浏览器验证使用 Chromium；没有完成 Safari、Firefox、所有真实手机或低端设备性能测量。

近期验证脚本存在开发环境的临时目录，尚未全部整理成仓库内可重复运行的测试套件。后续正式交接应固定依赖、输入样本、断言和测试命令。

21. Cloudflare 打包与发布

本地预览可用任意静态服务器，例如：

python3 -m http.server 8000 --directory sunlab/dist

浏览器访问 http://localhost:8000/。用静态服务器预览比直接打开 file 地址更接近托管环境。

打包必须让 index.html 位于 ZIP 根目录，同时包含全部 HTML、JS、CSS、图片、图标和版权信息，不能把整个项目目录再包成一层顶级文件夹。当前交付包还附带学习指南与项目说明的 Markdown。

根目录包含404.html，使Cloudflare Pages对不存在的路径采用404响应而非首页SPA回退；404源文件通过生成脚本复制到dist。上线后需检查未知.js路径的实际HTTP状态。

Cloudflare Pages采用静态资源直接上传方式，解包后直接提供 dist 内容，不需要在生产环境运行 Python 或 Node。发布后再次检查首页、实验台、全部专题、资源加载、深链接及移动操作，尤其避免浏览器缓存使新旧脚本混用。

ZIP完成代表交付产物完成，不代表已经替换公开网站。当前最新版交付文件为 sky-motion-lab-cloudflare-article-refined.zip，上传到站点后才会更新公开版本。

22. 已修复事项与后续维护边界

本版已修复日晷读数遗漏及说明联动、图解Hash与画面脱节、日行迹三维触屏手势冲突、时间工作台冗余绘图，并保留此前月面朝向、时长解释及跨日状态修正。

已额外修复无效地点选项的安全回退、零尺寸欢迎画布保护、重复的无保护位置标签赋值、键盘俯仰方向不一致；清理欢迎及联系死DOM和旧单页过渡逻辑，并增加根目录404页。还应继续维护的项目包括：清理其他旧实验DOM依赖、将临时测试归档、真实Safari／Firefox与低端设备测试，以及发布后的缓存和404状态核验。它们不能在没有实际检查的情况下写成“全部已解决”。

目前没有实现大气折射与视半径的完整观测升落模型、地形遮挡、海拔调整、食的真实遮挡、月面纹理与天平动、自动夏令时、精确连续合相搜索、真实星座数据库和离线安装支持。

资源归属保留在 credits.txt 中：Astronomy Engine 2.1.19由Don Cross提供，MIT许可；地球纹理来源于three.js示例资源，当前代码不因此等同于使用three.js渲染。分发时保留已有版权与许可说明。

23. 后续增加功能的标准流程

新增功能先写清变量、时间依据、物理输出和边界条件，再决定入口属于太阳、月球、公共观察或独立专题。不能先增加一个开关，再寻找它的科学含义。

把新的科学计算写成可独立调用的模型函数；读数、图解和轨迹消费同一结果；在对应天体状态中添加字段，并更新会话保存与恢复。先做输入和可用性处理，再接入完整更新，最后接入统一绘图与需要的视觉过渡。

交互必须说明拖动会改变日期、时刻、方向还是相机；菜单层级聚焦任务，避免重复日期控件。多端验收时实际拖动控制，而不是只检查截图尺寸。

完成验证后，学生操作更新到学习指南，模型限制和项目特点更新到项目说明，实现细节和验收记录更新到开发文档与内部记录。最后生成页面、核对资源、打包、发布并验证公开版本。