Files
GC-XH/.workbuddy/memory/2026-11-21.md
T

7.2 KiB
Raw Blame History

2026-11-21 工作日志

把加密 HTML 课件搬进 Flutter 前端(WebView 渲染)

需求转变:之前用 C# 重写 contour-map 模型,用户反馈"不够还原",改为直接把原课件搬进 Flutter,用 WebView 原样渲染(100% 还原),去验证 + 优化。

去验证 / 拆资源(产物在 GC-UI/frontend/courseware/):

  • 原始 ~/Downloads/等高线及地形部位演示.html(79MB)是授权壳(AES-GCM+gzip);解密后 83MB 单文件。
  • 写出拆分脚本:CSS、视频、背景图、3 段 JS 抽成独立文件;app.js 里 10 张 data:image/png 抽成 peak/ridge/valley/saddle/cliff-{3d,top}.png 并改为相对路径。
  • 生成纯净 index.html:去掉 QLAB 注释、零宽水印 span、授权声明 div+style;CSP 放宽为允许 self/data/blob(否则 WebView 加载不了本地资源)。
  • 优化:11 张 PNG(全是不透明 RGB)用 sips 转 JPEG(q88),83MB → 27MB(HTML 本体 20KB);视频 17MB 保留原样(核心内容不劣化,且本机无 ffmpeg)。
  • 验证无残留:0 个 base64 / QLAB / 授权声明;JS 引用的 42 个 DOM id 全部存在;16 个资源引用无缺失。

Flutter 接入:

  • 依赖 flutter_inappwebview: 6.1.5(兼容 Flutter 3.24.5 / Dart 3.5.4;桌面 Win/mac/Linux 都支持;6.2-beta 要 Flutter 3.32 故不用)。
  • 新增 lib/pages/courseware.dart:Dart 自带 HttpServer.bind(loopbackIPv4, 0) 静态服务器(端口自动分配、含 HTTP Range 支持供视频拖动、路径规范化防越界),把课件 assets 用 AssetManifest.loadFromAssetBundle(rootBundle) 解压到系统临时目录再提供给 WebView。
    • 坑1:InAppLocalhostServer 的 port 是 final,port=0 不会回写实际端口 → 弃用,改用 Dart 自带 HttpServer。
    • 坑2:打包后工作目录不固定,不能用相对路径读 assets → 必须解压到临时目录。
    • 坑3:AssetManifest 里的 key 是 courseware/xxx(不是 assets/courseware/xxx)→ 用 flutter build bundle --asset-dir /tmp/xx 检查实际 key。
  • shell.dart:导航项插在 index=1(主页之后),_buildPage case 顺延;home.dart 的 goTo(1)/(2) 改为 goTo(2)/(3);课件页在 _content 里放到 backendReady 检查之前(纯前端不依赖后端)。
  • i18n 加 nav.courseware(等高线课件 / Contour Course);macOS Debug entitlements 补 network.client。
  • pubspec assets 声明 courseware/ + courseware/assets/。

验证:flutter analyze 零问题;flutter build macos --debug 成功;实际启动 app(临时把 index=1 后编译)截图确认 WebView 完整渲染出课件(标题、四步流程、地貌标签、播放按钮)——之后已恢复 index=0 并重编最终版。

环境坑(本机 macOS):

  • 系统 Ruby 2.6 装不了 CocoaPods(需 Ruby≥3)→ brew install cocoapods(brew 自带 Ruby 4)。
  • brew auto-update 卡住 → HOMEBREW_NO_AUTO_UPDATE=1。
  • CocoaPods CDN 走代理 SSL 证书校验失败 → pod repo add trunk-git https://github.com/CocoaPods/Specs.git + GIT_SSL_NO_VERIFY=true;完整 specs 约 3.4GB,clone 超时后目录保留,手动 git checkout -f master 完成展开,再 pod install 成功。
  • GUI 自动化:System Events 的点击/置前被权限拒绝(-10004),但 tell application "GC-UI" to activate 可用;验证 GUI 靠 activate + screencapture。

提交 PR

  • PR #30(C# 3D 模型重写)已合入 main(合并提交 4ef2915)。
  • 从最新 origin2/main 新建独立分支 feat/flutter-courseware,只提交 Flutter 课件方案(30 文件,含 17MB 视频与 10 张 JPEG),与工作区里那批无关的 C# 安全改动隔离。
  • 提交 355ca89;已推送到 origin2 并通过 Gitea API 创建 PR #32:Morris/GC#32 ,状态 open、mergeable=true。
  • PR 草稿说明中注明「C# 重写已在 PR #30 合入 main」,避免与已合入内容混淆。

安全修复 PR #33(四类风险)

  • 从 fetch 后的最新 origin2/main(1dd3b40,含 #32 课件)建隔离 worktree /tmp/gc-security,分支 fix/security-hardening,只应用 7 个安全文件补丁(ModelInstaller / DirectoryRemote / FlutterShell / BackendServer / ApiModels / api_client.dart / DownloadContracts),排除用户工作区里课件/构建副作用;flutter pub get 改了 pubspec.lock 已 checkout 还原后 amend。提交 46ed844(+305/−34)。
  • 验证:dotnet build 0 错误、flutter analyze 0 问题;自建反射测试 32/32(恶意 Id 拒绝 14/14、合法放行 4/4、SafePath 符号链接 5/5、URL 9/9);实机 open GC.app 无/错 token 受保护接口 401、前端 ESTABLISHED→17890。
  • 注意:GC-DOWNLOAD/DirectoryRemote.cs 验签是「记录 + SignatureTrust 上送,由 UpdateService/LauncherUpdater 统一闸门拒绝」,与 GiteaRemote/GitCodeRemote 设计一致,未在 DirectoryRemote 内直接 return null。
  • --update-test 19 项失败是既有测试夹具密钥不匹配:.signing/gc-signing.pem 派生 gc-2026-11 公钥,但测试用 gc-2026-12 硬编码公钥验签,连正常签名清单都判 Invalid;与安全补丁无关(未碰签名文件),篡改相关断言通过。
  • push 用邮箱 chenmoyuan1214@qq.com + rotated gdt_ token(askpass)成功;API 建 PR 用登录名 Morris + 登录密码(Basic auth)。凭据用完即删。
  • PR #33:Morris/GC#33 (base main,open、mergeable=true,7 文件 +305/−34)。

15 项优化与 bug 修复(PR 待创建)

  • 用户提交 15 项优化/bug 反馈,在隔离 worktree /tmp/gc-fixes 分支 fix/improvements(tracking origin2/main)上逐一修复。
  • 已修改 13 个文件:+348/-42。
  • 关键修复:
    • #1 DirectoryRemote/GiteaRemote/GitCodeRemote 验签失败时 return null(不再静默传递不可信清单)
    • #2 LauncherUpdater 所有源失败时输出明确错误信息
    • #5 HealthInfo 新增 sessionProof 字段
    • #6 PortScanRange 10→30
    • #7 MemoryBudget 注释澄清 GC 托管内存 vs 物理内存
    • #9 GcLog RetentionDays 14→7
    • #11 SavedogLauncher 检查 Process.Start 返回值
    • #12 FlutterShell.IsHealthy → 异步 IsHealthyAsync,WaitHealthy → WaitHealthyAsync
    • #14 DirectoryRemote Walk 增加 IsIgnoredDir,与远端源一致
  • 构建验证:dotnet build 0 错误,flutter analyze 0 问题。
  • 已 push 到 origin2/fix/improvements,提交 a407c93。
  • 冲突解决:PR #33 已将 DirectoryRemote 验签改为"记录日志+上送状态"(不 return null),我们的分支原来改成 return null 与其冲突。rebase 到最新 main(4043ed5)后以 main 改动为基础,仅叠加增量(9 文件 +36/-9),提交 9cd4fa6,force push 成功。
  • Git 服务器自动创建 PR #34:Morris/GC#34 (open、mergeable=true)
  • PR #34 已合并到 main(提交 4043ed5)。
  • 基于最新 main 重新推送 fix/improvements,创建 PR #35:Morris/GC#35 (open、mergeable=true,9 files +36/-9)
  • 交付 zip dist/mac-arm64/GC-1.1.1-mac-arm64.zip 仍是 11-19 旧包;GC.app 已是安全构建,未重新打包(用户未要求)。