# 2026-09-13 --- FRO / Qingtian 详细工作与讨论记录

## 1. 今日工作目标

延续 2026-09-12 尚未完成的 FileDrop Phase 5E Dashboard
Redesign，在不破坏现有 Share File、Receive File、Storage Guard 与
production data 的前提下，完成真实浏览器 E2E、UI polish，并建立 verified
freeze checkpoint。

## 2. IEI Server 意外 reboot 调查

今日 VS Code Remote SSH 曾无法连接 IEI Tailscale 地址，随后恢复。

已确认 FRO watchdog 由 systemd timer 定期执行
`/usr/local/bin/fro-watchdog.sh`，检查
`http://127.0.0.1:8000/dashboard`；连续失败后只执行
`docker restart remoteoffice`。它不会执行 host reboot、shutdown 或
poweroff。

检查中未发现明确的 kernel panic、OOM、disk I/O error、thermal shutdown
或 pstore crash record。因此根因暂不能定论，较可能方向包括 sudden
reset、power interruption、hardware-level watchdog 或 hardware
hang。今天决定不修改 FRO watchdog，把 host reboot 根因调查与 FileDrop
feature development 分开处理。

## 3. Phase 5E Dashboard Redesign

Dashboard 最终结构： - File Transfer 顶部 banner：Share File Admin Token
/ Unlock。 - Browse Files：NAS read-only browser、folder
navigation、checkbox selection、Preview。 - Create Share Link：folder /
selected file mode、expiry、Create Link。 - Receive File：expiry、Create
Receive Link。 - Share & Receive Management：Share Links、Receive
Links、Share Details、Client Download Activity。 - Working
Status：当前/global download activity。 - Maintenance
Tools：cleanup/history，保持 compact/collapsible。

## 4. Browser E2E --- Admin Unlock

打开 `http://100.117.100.85:8000/filedrop`，输入 Admin Token 后： -
顶部显示 Unlocked。 - Browse Files 成功加载 QNAP Share File 内容。 -
Share Management 成功加载旧记录。 - Receive Management 可访问。 - Admin
session 正常。

## 5. Browser E2E --- Preview 故障与修复

进入 `RMC_2026/jpeg/Untitled Export`，点击 JPG Preview
后，文件名、size/type metadata 正常，但图片本体破图。

Container log 显示： `NameError: name 'token' is not defined`

错误位于 `/app/app/filedrop.py` 的 `iter_preview()` streaming
generator。HTTP request 已开始返回 200，但 generator 在实际传输文件时
exception，因此浏览器显示 broken image。

比较 Host 与 Container 源码后，两边都已没有旧 token reference，说明
Uvicorn worker 仍运行先前载入的 Python code。执行
`docker compose restart remoteoffice` 后新代码生效，真实浏览器 Preview
恢复正常。

当前 admin preview fix 应保留：admin route 由 admin session dependency
认证，不应重新加入 recipient-link token validation；path
containment、MIME、Range、text preview limits 保持不变。

## 6. Browser E2E --- Checkbox / Share Target

多选 3 files 时： - Selected file mode 自动生效。 - UI 显示
`3 file(s) selected`。 - 因 backend 不支持 multi-file bundle，target
invalid。

单选 1 file 时： - Selected file mode 正常。 - `1 file(s) selected`。 -
Target 正确变成具体 file path。 - UI 显示
`One selected file will be shared.`

现有 backend target semantics： - 一个 Share Link = exactly one
file；或 - 一个 Share Link = exactly one whole folder。
不支持多个独立文件 bundle。

## 7. Real Share Link / Download E2E

实际创建单一文件 Share Link 后验证： - Create Share Link 成功。 - Public
link 可打开。 - Client 可以实际下载文件。

因此 Browse → Select → Target → Create Link → Public Link → Download
整条 Share File 主链路真实环境 PASS。

## 8. Final UI Polish

核心功能通过后，要求 Codex 只做窄范围 UI polish。最终只修改
`templates/filedrop.html`。

改动： - Create Share Link card 移除不必要的 vertical scrollbar。 -
Receive File card 移除不必要的 vertical scrollbar。 - Creation grid rows
改为自然 content-sized rows。 - Working Status bounded height 约
300px，减少无 activity 时空白；有数据时仍支持 horizontal + vertical
internal scrolling。 -
多选时提示改为：`N files selected — one file per Share Link. Please select only one file.` -
多选时 Create Share Link invalid/disabled。 - 不实现 multi-file
bundle，不改变 backend target semantics。 - Unified
Management、Share/Receive tabs、Share Details、Client Download
Activity、Preview、backend APIs 与 Storage Guard 均未重新设计或改变。

## 9. Final Validation

Codex validation： - Final polish exact file
changed：`templates/filedrop.html` - duplicate IDs：47 IDs / 0
duplicates - no runtime DOM reparenting - Targeted Phase 5E：4/4 PASS -
Relevant FileDrop/Receive：94/95 PASS - `/filedrop`：HTTP 200 - Storage
Guard：`configured-and-healthy`

唯一 remaining test failure：
`test_disconnect_exception_keeps_upload_resumable`

当前 backend error 为 `Receive storage I/O failure`，test 仍预期 message
包含 `resume`。此问题早于 Final UI Polish，且与 template-only Phase 5E
change 无关，因此没有为了让 test 变绿而改变 backend。

## 10. Final Browser Acceptance

Ctrl+F5 后视觉检查确认： - Share creation card scrollbar 消失。 -
Receive card scrollbar 消失。 - Working Status 明显变矮。 - Management
layout 正常。 - Page 无明显 horizontal overflow。

再次 Unlock 后确认： - Browse Files 加载 `RMC_2026`。 - Management
历史记录正常加载。 - Creation cards 维持 compact。 - Working Status 保持
compact。 - Management horizontal / vertical internal scrolling 保持。 -
Desktop three-column layout 正常。

最终 Browser Acceptance：PASS。

## 11. Phase 5E Freeze

建立 verified checkpoints： 1.
`templates/filedrop.html.checkpoint_20260913_receive_phase5e_verified`
2. `app/filedrop.py.checkpoint_20260913_receive_phase5e_verified` 3.
`tests/test_receive_management_ui.py.checkpoint_20260913_receive_phase5e_verified`

Freeze validation： - `cmp`：全部 identical - SHA-256：全部对应一致 -
Targeted tests：4/4 PASS - FileDrop/Receive：94/95 PASS - Python
syntax：PASS - HTML duplicate IDs：0 - `/filedrop` smoke：HTTP 200 -
Storage Guard：`configured-and-healthy` - Production data changed during
freeze：none - No commit/stage/reset/clean/container restart

最终状态：

**PHASE 5E VERIFIED AND FROZEN**

## 12. 后续原则与候选工作

Phase 5E 从现在开始视为稳定基线，不再直接在其 verified checkpoint
上堆叠未验证改动。

后续继续遵循： - 小范围修改 - risky changes 前 checkpoint - automated
validation - production-safe testing - browser E2E - verified freeze

下一步候选： - 开启后续 Receive / FileDrop 新 Phase。 - 独立处理已知
resumable disconnect test/message mismatch。 - 将 IEI unexpected reboot
根因调查作为独立 infrastructure task。