Development Record
Formosa ESG 2026
Formosa ESG 2026
白沙屯妈祖进香 GPS 追踪系统 — 项目开发记录
从概念验证到万人系统：简述开发历程
版本 1.0
涵盖期间：2026/03/23 —
更新日期：2026/04/07
Formosa ESG 项目团队
5
开发阶段
4
压力测试轮次
106+
已解决问题
4
支持语言
1. 项目概述
"Formosa ESG 2026 白沙屯妈祖进香 GPS 追踪系统"是一个结合 GPS 定位、碳足迹估算和社区互动的进香追踪服务。香客通过 LINE 登录，使用手机进行实时打卡，累积里程数，查看等级进度，并可生成并分享个人成就卡。系统还为管理员提供实时地图仪表板、推送通知、用户管理等后端功能。
技术架构采用 Astro（前端静态生成）+ Cloudflare Pages + Workers + D1（SQLite）+ KV（缓存和缓冲），结合 LINE LIFF SDK 进行登录和分享集成。系统设计可处理 10,000 并发用户。
活动日期
2026/04/12 出发
活动周期
~8-9 天（妈祖意愿）
容量目标
10,000 并发用户
支持语言
zh-Hant / en / ja / zh-Hans
前端框架
Astro + Cloudflare Pages
后端架构
Workers + D1 + KV
2. 开发阶段总览
| 阶段 | 日期 | 核心目标 | 状态 |
|---|---|---|---|
| 阶段 0 | 03/23 | PoC：EXIF GPS 读取、D1 写入可行性 | 完成 |
| 阶段 0.5 | 03/24 | MVP：16 问卷 + GPS 打卡 + 碳足迹 + 成就卡 + LINE webhook | 完成 |
| 阶段 1 | 03/25 | UX 优化：逐问设计卡 + 9 级等级 + LIFF + 分享卡 + 仪表板 | 完成 |
| 阶段 1.5 | 03/25–26 | 安全加固 + 仪表板 + LIFF 已发布 + Workers 付费升级 | 完成 |
| 阶段 2 | 03/25–26 | 4 轮压力测试 + D1 瓶颈分析 + KV 缓冲架构设计 | 完成 |
| 阶段 3 | 03/27–30 | GPS 管线修复 GP-1~GP-9 + 隐私机制 + 文档 + 高级功能 | 完成 |
| 阶段 4 | 03/31–04/07 | 问卷优化 Q16→Q10 + 权限系统 + 成本优化 Plan A + 预启动检查 | 完成 |
3. 逐日开发纪录
| 日期 | 阶段 | 交付内容 | 状态 |
|---|---|---|---|
| 03/23 第 1 天 |
阶段 0 | 项目页面框架（Astro SSG + Cloudflare Pages） | 完成 |
| 03/24 第 2 天 |
阶段 0.5 | 16 问 ESG 问卷（逐问设计卡工作流） | 完成 |
| 阶段 0.5 | GPS 打卡功能 + 碳足迹计算引擎 | 完成 | |
| 阶段 0.5 | 成就卡系统（打卡点位可视化） | 完成 | |
| 阶段 0.5 | LINE Bot webhook 集成（消息 API） | 完成 | |
| 阶段 0.5 | Cloudflare Workers CORS 修复 + 部署验证 | 完成 | |
| 03/25 第 3 天 |
阶段 1 | UX 优化：逐问设计 + 直线进度条 + 滑动动画 | 完成 |
| 阶段 1 | 9 级香客等级系统（修炼→飞升），双条件：km + 打卡数 | 完成 | |
| 阶段 1 | 9 张 AI 生成吉祥物图（替代表情图标） | 完成 | |
| 阶段 1 | LINE LIFF SDK 集成（登录频道 + 初始化） | 完成 | |
| 阶段 1 | 分享卡（纵向布局 + 地图 + 二维码 + 吉祥物 + 统计） | 完成 | |
| 阶段 2 | 压力测试 R1：HTTP 层 C-10K ~ C-100K 全部通过 | 完成 | |
| 03/26 第 4 天 |
阶段 1.5 | 仪表板：热力图 + 聚类标记 + 前后段 + 3 种模式切换 | 完成 |
| 阶段 1.5 | 安全加固：认证网关 + 管理 Token API 验证 | 完成 | |
| 阶段 2 | 压力测试 R2：800 VU 最优点确认（99.99% 成功率） | 完成 | |
| 阶段 2 | 压力测试 R3：D1 写入瓶颈验证（SQLite 单写者锁） | 完成 | |
| 阶段 2 | 压力测试 R4：真实场景模拟（CF-800 通过 / RW-500 数据 API 瓶颈） | 完成 | |
| 03/27–28 第 5–6 天 |
阶段 3 | 碳足迹每日报告前端 + 动态生成 OG 图片 | 完成 |
| 阶段 3 | 吉祥物图 4 倍分辨率升级 + 仪表板认证修复 | 完成 | |
| 阶段 3 | 7 项 UX 修复（照片缩略图 / FB 分享 / GPS 持久化等） | 完成 | |
| 阶段 3 | 功能盘点：23 项完成清单编制 | 完成 | |
| 03/29 第 7 天 |
阶段 3 | 隐私同意机制（P0）+ 暂停/完成状态 | 完成 |
| 阶段 3 | 碳足迹简化为 2 层结构（零排放 vs 机动交通） | 完成 | |
| 阶段 3 | 二维码替换为 NET-ZERO 徽标 + FB OG 图片修复 | 完成 | |
| 阶段 3 | 用户指南转换为网页（香客版 + 管理员版） | 完成 | |
| 阶段 3 | LINE Bot 指导链接集成 | 完成 | |
| 阶段 3 | 活动照片归档功能 + FB 分享 fbclid 修复 | 完成 | |
| 03/30 第 8 天 |
阶段 3 | 活动照片归档按钮 UX 改进（清晰保存按钮） | 完成 |
| 阶段 3 | 个性化 FB OG 图片实现 | 完成 | |
| 阶段 3 | 测试模式横幅 + 照片保存 bug 修复 | 完成 | |
| 03/31 第 9 天 |
阶段 3 | 完整 GPS 数据管线修复 GP-1 ~ GP-9（commit 8f08e5d） | 已部署 |
| 阶段 3 | KV 缓冲架构实现：打卡 → KV → Cron 批量插入 D1 | 已部署 | |
| 阶段 3 | 住宿碳系数更新：12.5 → 8.85 kgCO₂e/晚 | 完成 | |
| 04/01–02 第 10–11 天 |
阶段 4 | 问卷优化 Q16 → Q10（减少 6 问 + 重新编号） | 已部署 |
| 阶段 3 | 三层权限系统上线：拥有者 / 经理 / 义工 | 已部署 | |
| 阶段 3 | 仪表板访问日志（即发即弃 KV 日志） | 完成 | |
| 阶段 4 | 成就卡门槛：打卡 ≥3 次 + 完成问卷 + 留电话 | 完成 | |
| 04/03–04 第 12–13 天 |
阶段 3 | mazu.today 自有域名上线（Worker 路由 + DNS） | 已部署 |
| Ops | RFC #100：HealthAlert + Service Worker + 离线回退验证 | 已部署 | |
| Ops | Issue #99：8 项弹性改进（Promise.allSettled、localStorage 回退等） | 已部署 | |
| Ops | Issue #102：双认证系统对齐（KV 邀请码 + Worker 密钥统一） | 已部署 | |
| 阶段 3 | LIFF 频道 → 已发布（所有用户可用） | 已部署 | |
| 04/05 第 14 天 |
Ops | Issue #103：碳机动交通系数修正 0.47515 → 0.12013 kg CO₂e/人·km | 已部署 |
| Ops | Issue #105：推送支持图片 + 图片+文本格式（commit 35945cd） | 已部署 | |
| Ops | Issue #106：义工可视范围修正（仅隐藏推送 + 用户列表） | 已部署 | |
| Ops | Worker 全面部署确认（版本 342af8b0） | 已部署 | |
| 阶段 4 | Cloudflare 成本分析：$44.63/月，KV 操作占 84% | 完成 | |
| 04/06–07 第 15–16 天 |
阶段 4 | KV 成本优化 Plan A：移除 TICKER_KV.delete()（commit a4b6fd2） | 已部署 |
| 阶段 4 | 预启动检查清单生成（7 类别、34 项） | 完成 | |
| 阶段 4 | 完整技术文档清单 + 公开部署计划（/docs/ + /verification/） | 完成 | |
| 阶段 4 | mazu.today 重定向规则侦察完成（Cloudflare 仪表板方案确认） | 完成 |
4. 压力测试结果总结
使用 Grafana k6 进行了 4 轮压力测试（2026/03/25–26）以验证高并发下的系统性能。测试环境：MacBook Air 本地 + Cloudflare Workers 生产。
| 轮次 | 日期 | 测试重点 | VU 范围 | 关键结果 |
|---|---|---|---|---|
| R1 | 03/25 | HTTP 层限制 | 10K–100K | S-BURST / S-WAVE / S-EXTREME 全部通过；5,000 VU 91% 成功率 |
| R2 | 03/25 | 容量最优点 | 200–1,200 | 800 VU = 99.99% 成功率（最优点）；1,200+ 开始下降；恢复测试 54% |
| R3 | 03/26 | D1 写入瓶颈 | 500 | DI-500 确认 D1 SQLite 单写者锁；实时成功率 42%；延迟 +51% |
| R4 | 03/26 | 真实场景模拟 | 500–800 | CF-800（直接 D1 写）100% 通过；RW-500（混合负载）60% 失败 = 数据 API 瓶颈 |
根本原因与解决方案
R3-R4 测试确认根本原因是 D1 SQLite 的单写者锁，在高并发下造成序列化瓶颈。解决方案采用 KV 缓冲架构：
方案 1 — KV 缓冲
将打卡写入 KV（非 D1），key = gps:{ts}:{userId}:{randomId}
方案 2 — Cron 刷新
每 5 分钟批量刷新 KV → D1，INSERT OR IGNORE 防止重复
方案 3 — 数据 API 缓存
统计先检查 KV 缓存（TTL 60s），未命中再查 D1
所有三项方案已在 2026/03/29 部署并验证。
5. GPS 数据管线修复
2026/03/31 进行了完整的 GPS 数据管线修复（commit 8f08e5d），涵盖 9 项改进：
| 项目 | 修复项 | 说明 |
|---|---|---|
| GP-1 | 自动追踪持久化 | localStorage 状态跨会话保持 |
| GP-2 | 批量上传 | 离线累积打卡批量上传 |
| GP-3 | 同步端点 | 前端 ↔ Worker 数据同步 API |
| GP-4 | GPS 精度过滤 | 精度 > 阈值自动跳过 |
| GP-5 | 速度检测 | ≤15 km/h 零排放 / >15 km/h 机动交通 |
| GP-6 | 距离计算修复 | Haversine 公式 + 里程累积 |
| GP-7 | 时间戳标准化 | UTC → ISO 8601 统一格式 |
| GP-8 | 重复打卡保护 | 时间间隔 + 位置距离双重检查 |
| GP-9 | 错误恢复 | 网络中断自动重试 + 错误上报 |
6. 碳足迹模型
碳足迹使用 GPS 速度自动检测将进香运动分为零排放（步行/骑行）和机动交通。机动交通碳系数使用 ecoinvent"公交车市场"数据集进行学术修正。
零排放（≤15 km/h）
0 kg CO₂e / 人·km
机动交通（>15 km/h）
0.12013 kg CO₂e / 人·km
住宿碳排
8.85 kg CO₂e / 晚
数据来源
ecoinvent — 公交车（人·km）
碳数据包含"估算"标注和免责声明，作为用户参考提供，但并非官方碳会计。碳系数在 Issue #103 中修正（旧值 0.47515 kg CO₂e/km 是车·km 基础，语义不正确）。
7. 基础设施与运维
mazu.today 独立域名
2026/04/03–04 mazu.today 自有域名上线，通过 Cloudflare Workers 反向代理到 paulkuo.tw/projects/formosa-esg-2026/。涵盖 DNS 设置、Worker 路由、i18n 路径映射、webhook URL 迁移等。所有 LINE 推送链接现已使用 mazu.today。
权限系统
三层角色权限：拥有者（完整管理权限）、经理（推送 + 用户管理）、义工（仅查看仪表板地图和统计，无推送或用户列表）。通过 KV 邀请码机制分配邀请码，与 Worker 密钥统一验证。
运营成本结构
以下为系统开发与运营期间的实际成本。活动期间随用户规模增长，基础设施与推送费用会相应增加。
| 类别 | 项目 | 费用 | 说明 |
|---|---|---|---|
| AI 开发工具 | Claude Max 20x 订阅 | $200 USD/月 | 主要开发工具，涵盖程序编写、架构设计、文档产出 |
| Claude Extra Credits | 按量计费 | 高强度开发期间的额外用量，依开发节奏浮动 | |
| Claude 储值额度 | $250 USD | 预购额度，用于活动期间即时运维 | |
| 基础设施 | Cloudflare Workers Paid | $5 USD/月 | 解除 100K/天请求上限 |
| Cloudflare KV / D1 用量 | ~$40 USD/月 | KV 操作占 84%（开发期）；万人场景预估 ~$46/月，优化后 ~$27/月 | |
| mazu.today 域名 | — | 通过 Cloudflare Workers 反向代理，无额外费用 | |
| 用户通讯 | LINE OA 进阶版 | NT$1,200/月 | 活动期间升级至最高阶方案，含 6,000 则推送 |
| LINE 推送超额 | NT$0.2/则 | 超过 6,000 则后按量计费 |
上述费用为持续性支出，随开发阶段与活动状态动态变化。Cloudflare 费用优化已完成 Plan A（移除冗余 KV delete 操作），后续将视活动实际流量进一步调整。
8. 关键问题追踪
| Issue | 标题 | 风险 | 状态 |
|---|---|---|---|
| #99 | 8 项系统弹性改进（错误处理、Promise.allSettled、localStorage 回退） | L1 | 已部署 |
| #100 | RFC — HealthAlert + Service Worker + 离线回退 | L2 | 已部署 |
| #101 | _redirects 双域名重定向循环（紧急回退） | L3 | 已回退 |
| #102 | 双认证系统对齐（KV 邀请码 + Worker 密钥） | L2 | 已部署 |
| #103 | 碳机动交通系数修正（ecoinvent 人·km 基础） | L2 | 已部署 |
| #105 | 推送支持图片 + 图片+文本格式 | L1 | 已部署 |
| #106 | 义工可视范围修正 | L1 | 已部署 |
| #107 | /verification/ 验证页面 | L1 | 进行中 |
| #108 | /docs/ 文档中心 + Footer 扩展 | L1 | 进行中 |
9. 交付文档
| 文档名称 | 版本 | 目的 | 状态 |
|---|---|---|---|
| 香客用户指南 | v0.4 | 通用用户操作指南 | 已上线 |
| 管理员用户指南 | v0.5 | 仪表板操作 + 推送通知 + 用户管理 | 已上线 |
| 常见问题 | v1.0 | 用户自助故障排查 | 已上线 |
| 隐私政策 | v1.0 | 数据收集和隐私 | 已上线 |
| 预启动检查清单 | v1.0 | 合作伙伴 / 赞助商参考 | 完成 |
| 项目开发记录（本文档） | v1.0 | 完整开发历程记录 | 完成 |
| 义工用户指南 | — | 义工操作指南 | 规划中 |
10. 开发里程碑
03/23 — 项目启动
PoC 完成，EXIF GPS 读取 + D1 写入可行性确认
03/24 — MVP 上线
问卷 + GPS 打卡 + 碳足迹 + 成就卡 + LINE Bot，24 小时从零到功能
03/25 — 重大 UX 优化
逐问设计卡工作流、9 级等级系统、LIFF 集成、分享卡、仪表板地图。同日完成压力测试 R1
03/26 — 压力测试完成
R2-R4 完成，确认 D1 瓶颈和 KV 缓冲方案方向
03/29 — KV 缓冲验证
三项方案全部部署并验证：KV 缓冲、Cron 刷新、数据 API 缓存
03/31 — GPS 管线修复
GP-1 ~ GP-9，9 项修复部署，数据质量显著提升
04/03 — mazu.today 上线
独立域名上线，品牌认可度提升，所有 LINE 链接已迁移
04/05 — 全面部署
RFC #100 + Issues #99 / #102 / #103 / #105 / #106 一同部署。未解决问题已解决
04/07 — 预启动评审
检查清单完成、技术文档清单、成本优化 Plan A 部署。距离出发 5 天
04/12 — 出发日
从白沙屯宫庙出发。系统正式上线。