mirror of
https://github.com/ringhyacinth/Star-Office-UI
synced 2026-04-21 13:27:19 +00:00
d9fe21efd2
- Add detailed update report for all 8 commits (CDN fix, fetchStatus fix, async generation, mobile drawer, join key expiration) - Update README section 9.G with changelog summary - Update SKILL.md section 10.7 with stability fixes
100 lines
5 KiB
Markdown
100 lines
5 KiB
Markdown
# 更新报告 — 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 行
|
||
```
|