━━━━━━ 开发日记 ━━━━━━
加固、封版、收手
v3.8.0 是这个系统的终章
员工轨迹地图系统 v3.8.0 正式封版
2026年03月25日
昨天，v3.8.0 完成了代码清理和连锁 Bug 的修复，带着一身”Clean Release”的名号上了线。今天的目标只有一件事：把这个版本做到无懈可击，然后封版。
一个稳定运行的系统，不需要频繁更新。今天的每一处改动，都是为了让它能安安静静地跑下去，不用再动它。
🔧 第一章：三处安静的修复
━━━━━━━━━━━━━━━━━━━━━━
今天上午，在正式封版之前，发现并修复了三处遗漏的问题。它们都不显眼，但每一处都会在某个时刻让人困惑。
修复①数据更新时间显示错误
页面右上角显示的”数据更新时间”，原来每次打开都是当前时间——其实是用 new Date() 临时生成的，根本不是真实的钉钉拉取时间。修复后改为读取 data/index.json 里的 lastUpdate 字段，显示的才是系统真正最后一次同步钉钉数据的时间。
修复②缓存策略：从”完全不缓存”到”按需缓存”
之前 v3.7.1 测试阶段为了方便调试，所有响应都加了 no-cache, no-store。正式版本里忘记改回来了，导致每次打开地图都要重新请求所有数据。修复后区分场景：JS/CSS 文件缓存 1 小时（URL 带版本号，改了自动失效）；当前月轨迹数据缓存 5 分钟；历史月数据缓存 1 小时；月份列表缓存 5 分钟。
修复③数据分析模块重复请求
打开数据分析弹窗时，四个图表函数各自独立去请求 trajectory_data.json，同一份数据被请求了十几次。加了一个前端内存缓存层 fetchTrajectoryData(month)，同月数据只真正请求一次，后续直接从内存返回。
🔐 第二章：登录功能的诞生
━━━━━━━━━━━━━━━━━━━━━━
今天最重要的新功能，是给系统加上了密码访问控制。
这个系统部署在公网上，员工的打卡轨迹是敏感数据，不应该谁都能看。加密码这件事，早就该做了。
登录方案：服务端签名 Cookie
没有引入任何额外的 npm 包，用 Node.js 内置的 crypto 模块实现 HMAC-SHA256 签名。密码正确后写入一个签名 Cookie，有效期 8 小时。Cookie 被伪造或篡改时验证直接失败，无法绕过。
整个认证流程只有四步：
①访问任何页面 → 检查 Cookie 中的签名 token
②token 不存在或过期 → 返回登录页
③输入密码 → POST /login → 写入签名 Cookie
④携带有效 Cookie 访问 → 验证通过 → 正常显示地图
一个意外插曲：Apache 拦截了 401
登录页做好后，无痕模式打开却看不到登录框——空白页。排查后发现：Apache 反向代理会拦截 Node.js 返回的 HTTP 401 响应，登录页 HTML 根本没有透传到浏览器。
解决方案很简单：改变状态码语义——HTML 页面返回 200（让 Apache 放行），数据接口未授权时返回 403（避免浏览器弹出系统级密码框）。一行改动，彻底绕过了 Apache 对 401 的特殊处理。
登录页的三次迭代
登录页的视觉效果，也经历了三轮细节打磨：
第一版：基础样式，可用。
第二版：间距太松，整体太宽，卡片 padding 和各区块间距压缩约 20%。
第三版：错误提示从”输入框上方”移到”输入框正下方”，更符合表单交互习惯；无错误时完全不占空间，布局更干净。
📦 第三章：正式封版前的最后清理
━━━━━━━━━━━━━━━━━━━━━━
发布前做了最后一轮系统性检查，处理了三件小事：
清理①删掉了无用的 chart.js CDN — index.html 里引入了 chart.js，但 app.js 里没有任何一行用到它。直接删掉，减少一次无效网络请求。
清理②echarts 本地化 — echarts 是实际在用的图表库，从 CDN 引用改为本地文件（1001KB），断网环境下也能正常加载数据分析图表。
清理③清理历史版本注释 — app.js 里还有 v3.4.0 之前的功能、v3.7.1 新增功能代码结束 这类标记。正式版里不应该有版本痕迹，全部改为语义化注释。
v3.8.0 正式封版
发布包：release_v3.8.0_20260325
2026年03月25日 12:22
💬 第四章：关于这个系统
━━━━━━━━━━━━━━━━━━━━━━
从最初的 v1.0 静态地图，到今天的 v3.8.0，这个系统大概经历了：
v1 → v2从静态页面到 Node.js 服务端，接入钉钉 API 实现自动拉取
v2 → v3引入 Leaflet 地图，轨迹可视化，支持多员工切换
v3.5修复月份选择、竞态条件、移动端兼容等核心稳定性问题
v3.7新增数据分析弹窗，ECharts 图表，多维度统计
v3.8代码全面清理，竞态彻底修复，登录鉴权，资源本地化，封版
这是一个小系统，服务 9 名员工，每小时自动同步一次数据。它现在能做到：
✅ 随时查看任意员工的当日/历史打卡轨迹
✅ 可视化路线连线，点击查看详细打卡信息
✅ 月度数据统计，出勤天数、打卡次数、行驶里程
✅ 密码保护，签名 Cookie 鉴权，8 小时有效
✅ 全部资源本地化，断网不影响基本功能
短时间内能走到这一步，主要靠的是一条朴素的工作原则：每次发布前先清理，清理后再测试，测试通过再发布。听起来很简单，但真正能执行到位，就是质量。
━━━━━━━━━━━━━━━━━━━━━━
这个系统后续没有必要就不再更新了。
好的软件，不在于更新了多少次，在于稳定运行了多久。
v3.8.0，收工。
━━━━━━ END ━━━━━━
员工市场开发轨迹可视化平台