Star-Office-UI/docs/UPDATE_REPORT_2026-03-05.md

更新报告 — 2026-03-05

本次更新覆盖 8 个 commit，聚焦「稳定性修复 + 移动端体验 + 安全收尾」。

---

变更概览

#	Commit	分类	说明
1	878793d	🐛 fix	修复 CDN 缓存 404 导致页面无法加载
2	cc22403	🐛 fix	修复 fetchStatus() 中多余的 else 块导致 JS 语法错误
3	103f944	🐛 fix	生图接口改为异步任务模式，避免 Cloudflare 524 超时
4	ee141de	🧹 chore	清理本地测试时意外提交的文件
5	83e61ff	🧹 chore	将 join-keys.json 加入 .gitignore（运行时数据不入库）
6	899f27e	🐛 fix	移动端/iPad 侧边栏修复（遮罩层 + body 滚动锁定 + 100dvh）
7	5aef430	🐛 fix	移动端 drawer 关闭时完全移出屏幕（right: -100vw）
8	02a731e	✨ feat	新增 join key 级别过期时间 + 并发上限支持

---

详细说明

1. 修复 CDN 缓存 404（878793d）

问题：/static/ 路径下的所有响应（含 404）都被设置了一年长缓存头。Cloudflare 缓存了 phaser.js 的 404 响应长达 2.7 天，导致 office.hyacinth.im 完全无法加载。

修复：

• add_no_cache_headers 仅对 2xx 响应设置长缓存，非 2xx 响应设为 no-cache
• 给 phaser.js 的 <script> 标签添加 ?v={{VERSION_TIMESTAMP}} 缓存破坏参数

2. 修复 fetchStatus JS 语法错误（cc22403）

问题：fetchStatus() 函数内 try/catch 之间存在一个孤立的 } else { ... } 块，破坏了 JS 语法结构，导致浏览器报 Missing catch or finally after try，整个页面卡在 loading。

修复：移除多余的 else 块（其中的打字机逻辑已被前面的 if/else 分支覆盖）。

⚠️ 此 bug 是 GitHub 上 PR #49、#51、#52 同时在修的问题，三个 PR 现在可以关闭。

3. 生图接口异步化（103f944）

问题：POST /assets/generate-rpg-background 是同步的，生图通常需要 30~120 秒。Cloudflare 的代理超时限制为 100 秒（HTTP 524），导致公网用户频繁触发超时。

修复：

• 后端：拆分为 _bg_generate_worker（后台线程）+ POST /assets/generate-rpg-background（返回 task_id）+ GET /assets/generate-rpg-background/poll（轮询结果）
• 前端：新增 _startAndPollGeneration() 函数，提交任务后每 3 秒轮询，显示实时等待进度
• 同时抽取了 _handleGenError() 统一错误处理（DRY 优化）
• 防重入：如果已有生图任务在跑，直接返回已有 task_id

4-5. 清理与 gitignore（ee141de + 83e61ff）

• 清理了测试时意外提交的文件
• 将 join-keys.json 加入 .gitignore（包含密钥数据，不应入库）

6-7. 移动端侧边栏修复（899f27e + 5aef430）

问题：移动端/iPad 打开资产侧边栏时，背后的页面仍可滚动；关闭侧边栏后 drawer 只偏移 -320px，在宽屏移动设备上仍可见。

修复：

• 新增 #asset-drawer-backdrop 遮罩层，点击即关闭 drawer
• 打开 drawer 时 body 加 drawer-open class（overflow:hidden; position:fixed; touch-action:none）
• 关闭时恢复 scrollY 位置（避免跳顶部）
• Drawer 关闭状态改为 right: -100vw（完全移出视口）
• 使用 100dvh 适配移动端 dynamic viewport
• 添加 overscroll-behavior: contain 防止 drawer 内滚动穿透

8. Join Key 级别过期时间（02a731e）

新增功能：

• join-keys.json 中每个 key 支持 expiresAt 字段（ISO 8601 时间戳）
• join-agent 和 agent-push 两个端点在执行前都会检查 key 是否过期
• 过期后返回友好提示："该接入密钥已过期，活动已结束 🎉"
• 支持 maxConcurrent 字段控制同一个 key 的并发在线数

---

潜在风险评估

风险点	等级	说明
异步任务内存泄漏	🟡 低	_bg_tasks 在任务完成并被 poll 消费后会清理；但如果前端从未 poll（如用户关闭页面），任务对象会残留。当前风险极低（生图频率低），后续可加定期清理。
join-keys.json 历史泄露	🟢 已解决	已加入 .gitignore，但如果之前有 commit 包含此文件，历史中仍存在。建议确认远端历史是否干净。
前端 fetchStatus 修复	🟢 已验证	修复后的 try/catch 结构完整，本地运行正常。
移动端 drawer position:fixed	🟢 低	iOS Safari 下 position:fixed + 100dvh 的组合偶有兼容问题，但已是业界最佳实践。

结论：无新增 bug 风险，可以安全推送。

---

文件变更统计

.gitignore                    |   1 +
backend/app.py                | 166 ++++++++++++++++++------
frontend/index.html           | 162 ++++++++++++++++--------
frontend/join-office-skill.md | 102 +++++++++------
frontend/office-agent-push.py | 286 ++++++++++++++++++++++++++++++++++++++++++
office-agent-push.py          |   2 +-
共 6 个文件，+589 行，-130 行