docs: 新增 .qoder Repowiki 知识库文档

js/ota/file-handle.js

@@ -199,8 +199,15 @@ export async function resumePersistedFirmwareWithGesture(chip) {
       return false;
     }
     var file = await handle.getFile();
-    await applyRestoredFile(chip, handle, file, { silent: true });
+    var accepted = await applyRestoredFile(chip, handle, file, { silent: true });
     window._pendingFwHandles[chip] = null;
+    if (!accepted) {
+      /* 文件内容没过 GD32 身份校验（applyRestoredFile 已清句柄/共享槽/IDB）：
+       * 不得报成功，返回 false 让 pickFileViaFSAPI 继续弹文件选择框，
+       * 否则用户点了上传区只会反复恢复这个非法文件，永远选不了新文件 */
+      addLog('W', '文件', chip.toUpperCase() + ' 上次固件未通过校验，已放弃恢复，请重新选择文件');
+      return false;
+    }
     addLog('I', '文件', chip.toUpperCase() + ' 已重新授权并恢复: ' + file.name);
     showToast(chip.toUpperCase() + ' 已恢复上次固件', 'success');
     return true;
@@ -221,13 +228,28 @@ function applyRestoredFile(chip, handle, file, options) {
   if (window.sharedFirmwareFiles) {
     window.sharedFirmwareFiles[chip] = { file: file, handle: handle };
   }
-  /* 等 SHA 写入对应槽后再 sync BLE，避免二次重算 */
+  /* 等 SHA 写入对应槽后再 sync BLE，避免二次重算。
+   * GD32 文件可能被 processFile 身份校验拒绝（rejectGd32Identity 清掉 gd32File 但不抛异常）：
+   * 此时恢复必须视为失败——清干净窗口内句柄/共享槽/IDB 持久化，
+   * 否则句柄会一直复活这个非法文件（sync 会从共享槽把它重新绑进 BLE 会话），
+   * 且调用方误报"恢复成功"挡住文件选择框。 */
   return Promise.resolve(processFile(file, chip, Object.assign({ skipHandlePersist: true }, options || {})))
     .then(function () {
+      var accepted = !!(chip === 'esp32' ? window.esp32File : window.gd32File);
+      if (!accepted) {
+        if (chip === 'esp32') window.esp32FileHandle = null;
+        else window.gd32FileHandle = null;
+        window._pendingFwHandles[chip] = null;
+        if (window.sharedFirmwareFiles) {
+          window.sharedFirmwareFiles[chip] = { file: null, handle: null };
+        }
+        persistFileHandle(chip, null);
+      }
       if (typeof window.syncBleFileFromSelectedTarget === 'function') {
         window.syncBleFileFromSelectedTarget();
       }
       safeUpdateUploadButtonLabel();
+      return accepted;
     });
 }
 
@@ -275,9 +297,14 @@ export async function restorePersistedFirmwareSelection() {
       var perm = await queryHandlePermission(handle);
       if (perm === 'granted') {
         var file = await handle.getFile();
-        await applyRestoredFile(chip, handle, file, { silent: true, skipHandlePersist: true });
+        var accepted = await applyRestoredFile(chip, handle, file, { silent: true, skipHandlePersist: true });
         window._pendingFwHandles[chip] = null;
-        addLog('I', '文件', chip.toUpperCase() + ' 已恢复刷新前的固件: ' + file.name);
+        if (accepted) {
+          addLog('I', '文件', chip.toUpperCase() + ' 已恢复刷新前的固件: ' + file.name);
+        } else {
+          addLog('W', '文件', chip.toUpperCase() + ' 上次固件「' + file.name +
+            '」未通过 GD32 校验，已拒绝恢复，请重新选择文件');
+        }
         continue;
       }
       /* prompt/denied：不在此处 requestPermission（无用户手势会失败） */
@@ -371,6 +398,16 @@ export async function pickFileViaFSAPI(chip) {
       else window.gd32FileHandle = handle;
       window._pendingFwHandles[chip] = null;
       await processFile(file, chip);
+      /* GD32 身份校验拒绝时 processFile 只清文件不抛异常：
+       * 此时不能持久化句柄/元数据（否则刷新后 resume 会一直复活这个非法文件、
+       * 且 resume 返回 true 会挡住文件选择框），窗口内句柄也要清掉避免热重载读到它 */
+      var accepted = !!(chip === 'esp32' ? window.esp32File : window.gd32File);
+      if (!accepted) {
+        if (chip === 'esp32') window.esp32FileHandle = null;
+        else window.gd32FileHandle = null;
+        persistFileHandle(chip, null);
+        return false;
+      }
       persistFileHandle(chip, handle);
       persistFileMeta(chip, file);
       persistFlashTarget(chip);
@@ -560,6 +597,9 @@ function rejectGd32Identity(fileName, kind) {
   showToast(msg, 'error');
   window.gd32File = null;
   window._gd32FileSha256 = null;
+  /* 元数据一并清掉：processFile 入口已把本次（被拒）文件写进 meta，
+   * 不清的话下次刷新会拿这个非法文件名当"上次固件"展示 */
+  persistFileMeta('gd32', null);
   var info = document.getElementById('fileInfoGd32');
   if (info) info.classList.remove('show');
   safeUpdateUploadButtonLabel();
@@ -674,6 +714,7 @@ export function processFile(file, chip, options) {
       if (!silent) showToast('HEX 文件解析失败: ' + (err && err.message ? err.message : err), 'error');
       window.gd32File = null;
       window._gd32FileSha256 = null;
+      persistFileMeta(chip, null);
       var info = document.getElementById('fileInfo' + suffix);
       if (info) info.classList.remove('show');
       safeUpdateUploadButtonLabel();