Development Record
Formosa ESG 2026
Formosa ESG 2026
白沙屯妈祖进香 GPS 追踪系统 — 项目开发记录
从概念验证到万人系统：26 天完整开发历程（含活动期运维）
版本 1.2
涵盖期间：2026/03/23 — 2026/04/17
更新日期：2026/04/17
Formosa ESG 项目团队
26
开发+运维天数
6
开发阶段
5
Pre-Launch Audit 轮次
179+
已解决问题
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 + 预启动检查 | 完成 |
| 阶段 5 | 04/08–11 | Pre-Launch Audit 五轮完成 + 分众推播 + Issue #155 自动同步仪表板 | 完成 |
| 活动期 | 04/12– | 启程上线运维：热修 #168/#171/#172 + 治理 v4.8→v4.12 + post-event branch 隔离 | 进行中 |
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 仪表板方案确认） | 完成 | |
| 04/08–09 第 17–18 天 |
阶段 4 | Issue #141：分众推送 + LIFF OA 引导 + Secrets 盘点 | 已部署 |
| 阶段 4 | Issue #120：推送图片上传（R2 存储）+ Wiki Phase 3–4A | 已部署 | |
| Ops | 仪表板迁移至 GitHub Issue #155 + sync-dashboard Action 自动同步 | 完成 | |
| 04/10 第 19 天 |
Ops | Pre-Launch Audit R3：数据质量 + 防御韧性（computeFilteredKm + VALID_SOURCES 修复，Worker deploy 174bace0） | 已部署 |
| Ops | Issue #162：今日善足迹 API 验证通过 | 完成 | |
| Ops | CI/CD 盘查 + 治理框架 Phase 1–2.5 完成（Dashboard + API + KV seed） | 已部署 | |
| 04/11 第 20 天 |
Ops | Pre-Launch Audit R4：用户旅程 + 边界人物 + 运维韧性（P0=0, P1=4 全修, Worker deploy 876dddbd） | 已部署 |
| Ops | Issue #163：GPS 漂移 + 直线轨迹修复（speed outlier filter + accuracy 过滤） | 已部署 | |
| Ops | Issue #161：分享足迹链接修复（race condition — lineUserId 在 LIFF async 前为 null） | 已部署 | |
| Ops | Pre-Launch Audit R5：全面代码健康检查 + 修复完成（P0×2 + P1×6 全修，commit 9fa6c9d） | 完成 | |
| Ops | 五轮 Pre-Launch Audit 全部完成 ✅ — 核心打卡路径稳固、离线机制完整、无死路由 | 完成 | |
| 04/12 第 21 天 — 启程 |
Ops | 🎉 白沙屯拱天宫启程，系统正式上线运行（Worker 版本 8148bac5） | 已部署 |
| Ops | 启程日清场：D1 测试数据全清（users 143→0, gps 1140→0, surveys 20→0）+ KV gps: buffer 9,255 key 批量删除 | 完成 | |
| Ops | Feedback 治理 Phase A 完成：formosa-feedback skill 新增 Step 6.5 exit gate + session-handoff v4.4 reconciliation + 7 笔旧 triaging 全部 PATCH fixed | 已部署 | |
| Ops | Phase B batch-update.yml 上线：file-based trigger 方案（Chat 研究→Cowork 说帖→Code 实现→Cowork 验收），commit 57024b2 | 已部署 | |
| 04/13 第 22 天 |
Ops | Issue #168 GPS 幽灵里程修复（commit 9160a69）— /track/sync 加 geofence + WHERE source != 'remote' 过滤；催生护栏 #13（新 endpoint 防护继承）、session-handoff 升级 v4.8 | 已部署 |
| 04/14 第 23 天 |
Ops | Issue #170 pushHours 幽灵部署事故：跨 repo 真相验证失误；催生护栏 #14 + Code 完成三态宣告规范，session-handoff 升级 v4.9 | 完成 |
| Ops | Issue #171 个人足迹页碳字段修复（commit 93fb621）— 绑错 carbon_kg 字段，已部署待 LIFF 实测 | 已部署 | |
| Ops | 治理框架 Code-First 审计落地：session-handoff v4.9 整并 Code / Cowork 三态宣告、延迟触发行为验证 | 完成 | |
| 04/15 第 24 天 |
Ops | Issue #172 网页版/LINE 双等级不同步修复（commit a389dd6）— 根因：localStorage 跨浏览器隔离 + Stats API fallback 陷阱（Math.max(len, 1) 对空数组回 1）；衍生 #174 AuthGate bypass + #175 auto-close.yml injection | 已部署 |
| Ops | Feedback 三笔直接回报分流：#177 GPS 彰化以南未记录 / #178 LIFF 常驻影响 LINE 群+来电 / #179 拍照入口+我的相簿 — 全部 post-event label；确立活动期原则：静默修复优于警示、部署门槛 = 纯后台且零体感副作用才动 | 排程中 | |
| 04/16 第 25 天 |
Ops | Cowork 巡查 + Code Formosa post-event batch fix：Batch 1 (#175 auto-close.yml injection) 进 main (0aeb496)；Batch 2+3 (#177/#178/#173/#174/#179) 于 fix/formosa-post-event branch 隔离，待活动后 merge+deploy | 隔离中 |
| Ops | Impact Fence（活动期代码围栏）建立：🟢 Safe Zone（CI/CD）直接进 main / 🔴 Live Zone（前端+Worker）fix/formosa-post-event 隔离 | 完成 | |
| 04/17 第 26 天 |
Ops | CI race condition 系统性修复（commit 70173b2）：seo-index.yml + ai-ready-opt.yml 加 concurrency group + 3-retry pull --rebase loop，根治 workflow_run 串联自我 race | 已部署 |
| Ops | Cowork 治理 v4.12 落地：仪表板载体正名（Apple Notes→Issue #155 单一载体）；新增 Phase 版本沿革 v4.7→v4.12 + 护栏 #12–#14 沿革 | 完成 |
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 密钥统一验证。
Cloudflare 成本分析
月度成本（03/05–04/04）
$44.63 USD
最大项目
KV 操作占 84%
10K 用户预估
~$46/月（可控）
优化后预估
~$27/月（Plan A 移除删除操作）
其他基础设施
Workers 付费计划升级（$5/月），移除 100K/天请求限制。LIFF 频道已发布。LINE OA 升级至中等级（3,000 消息/月）。仪表板推送支持文本、模板和图片格式。
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 | 已部署 |
| #120 | 推送图片上传（R2 存储） | L1 | 已部署 |
| #141 | 分众推送 + LIFF OA 引导 | L2 | 已部署 |
| #161 | 分享足迹链接 race condition 修复 | L2 | 已部署 |
| #162 | 今日善足迹 API 验证 | L1 | 完成 |
| #163 | GPS 漂移 + 直线轨迹修复 | L2 | 已部署 |
| #168 | GPS 幽灵里程（静止用户累积假 km）— geofence + source filter | L2 | 已部署 |
| #170 | pushHours 幽灵部署事故 — 跨 repo 真相验证（催生护栏 #14） | L2 | 完成 |
| #171 | 个人足迹页 carbon_kg 字段绑错修复 | L1 | 已部署 |
| #172 | 网页版／LINE 双等级不同步（localStorage 隔离 + fallback 陷阱） | L2 | 已部署 |
| #173 | Dashboard 妈祖定位缺席 | L1 | post-event branch |
| #174 | AuthGate bypass 疑似 | L2 | post-event branch |
| #175 | auto-close.yml Expression injection — gh api 取代 shell heredoc | L1 | 已部署 |
| #177 | GPS 彰化以南未记录（Vivo OriginOS 节电策略假说） | L1 | post-event branch |
| #178 | LIFF 常驻影响 LINE 群+来电 | L1 | post-event branch |
| #179 | 照片上传找不到拍照入口 + 缺少我的相簿 | L1 | post-event branch |
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/08–09 — 功能完善 + 治理框架
分众推送上线、推送图片 R2 存储、仪表板迁移至 GitHub Issue #155 自动同步
04/10 — R3 审计 + 修复
数据质量 + 防御韧性审计，computeFilteredKm + VALID_SOURCES 修复部署，治理框架上线
04/11 — 五轮审计全部完成 ✅
R4 + R5 审计 + 修复完成，Issue #161/#163 关闭。核心路径稳固，距离出发 1 天
04/12 — 出发日
从白沙屯宫庙出发。系统正式上线（Worker 版本 8148bac5）。同日完成起程清场（D1 + KV 归零）与 Feedback 治理 Phase A + B。
04/13 — Issue #168 GPS 幽灵里程修复
静止用户累积假 km 修复（geofence + source filter），催生护栏 #13、skill 升至 v4.8
04/14 — Issue #170 事故与治理升级
pushHours 幽灵部署事故，催生护栏 #14「跨 repo 真相验证」+ Code 三态宣告；session-handoff 升至 v4.9
04/15 — Issue #172 双等级根因厘清
localStorage 跨浏览器隔离 + fallback 陷阱修复；确立活动期两条原则（静默修复优于警示、部署门槛 = 纯后台零体感副作用）
04/16 — post-event branch 隔离
Impact Fence 建立：🟢 Safe Zone 直接 main / 🔴 Live Zone 于 fix/formosa-post-event 隔离五项修复（#173/#174/#177/#178/#179）
04/17 — 活动期运维稳定
CI race condition 系统性修复（concurrency group + pull --rebase retry）；Cowork 治理 v4.12 落地，仪表板载体正名为 Issue #155 单一事实来源