存储套件新增全片擦除维护路径恢复容量，文档订正容量满值与恢复方法

test/storage_test.h

@@ -50,6 +50,16 @@ void storage_test_run(void);
  * 恢复完成后建议重新注释并编译正常构建。 */
 //#define ENABLE_STORAGE_RECOVERY_TESTS  /* 台架已跑过一次恢复（2026-09-20 BBT 回出厂态），保持注释 */
 
+/* 恢复模式的扩展（默认关闭，需与上面 ENABLE_STORAGE_RECOVERY_TESTS 同时打开）：
+ * 把 dhara 可见区**整片擦净**（连 journal checkpoint 一起），用于**把被扣掉的容量恢复回来**。
+ * 原理（2026-09-21 读码 + 台架实证）：dhara 把坏块计数持久化在 checkpoint 头里
+ * （journal.c `hdr_set_bb_current/bb_last`），而 `dhara_journal_clear()` 只是
+ * `bb_last = bb_current`（**不归零**）——所以 `nand_ftl_format()` 恢复不了容量（95200 卡住）；
+ * 只有让下次启动 `dhara_map_resume` 失败、走 `dhara_map_clear` 的**全新初始化**分支
+ * （此时 bb_last = bb_current = 0）才能回满。2026-09-21 台架实测：95200 → **96064**（健康满值 ✓）。
+ * 代价：卷内容全失（启动时 FatFs 自动重建）、约 2044 次块擦除（数十秒）。 */
+//#define STORAGE_RECOVERY_FULL_WIPE
+
 #ifdef __cplusplus
 }
 #endif

test/storage_test_task.c

@@ -543,19 +543,66 @@ void storage_test_run(void)
 }
 
 #ifdef ENABLE_STORAGE_RECOVERY_TESTS
-/* TC-STO-04: 重建 BBT + 重新格式化（恢复 TC-STO-03 注入的坏块）
+
+#ifdef STORAGE_RECOVERY_FULL_WIPE
+/*
+ * 函数功能：擦净 dhara 可见区全部块（容量恢复用）
+ * 入口参数：无
+ * 返回值：无
+ * 限定条件：SPI/驱动已初始化；调用期间无其它存储访问（测试构建下单写者）
+ * 函数说明：逐块擦除 [0, gd5f_get_usable_blocks())，跳过 BBT 记录的坏块，
+ *           保留块池（BBT 存储区）不动。擦净后 journal checkpoint 不复存在，
+ *           下次启动 dhara_map_resume 失败 → dhara_map_clear 全新初始化
+ *           （bb_last = bb_current = 0）→ 容量回满。
+ *           注意：擦净后**不能**再调 nand_ftl_format()（会把内存中仍带旧坏块
+ *           计数的 journal 状态重新落盘，容量又被扣掉）。
+ */
+static void storage_test_wipe_visible(void)
+{
+    uint32_t usable = gd5f_get_usable_blocks();
+    uint32_t done = 0;
+    uint32_t skipped = 0;
+    uint32_t b;
+
+    for (b = 0; b < usable; b++) {
+        if (gd5f2gq5ue_is_block_bad(b) != 0) {
+            skipped++;
+            continue;
+        }
+        if (gd5f_block_erase(b) == GD5F_OK) {
+            done++;
+        } else {
+            DBG_ERROR("  block %lu erase failed", (unsigned long)b);
+        }
+        if ((b % 256U) == 0U) {
+            DBG_INFO("  wipe progress: %lu/%lu", (unsigned long)b, (unsigned long)usable);
+        }
+    }
+
+    DBG_INFO("  wiped %lu blocks (%lu skipped as bad, %lu visible)",
+             (unsigned long)done, (unsigned long)skipped, (unsigned long)usable);
+    STORAGE_TEST_CHECK(done > 0U, "TC-STO-04 full wipe (%lu blocks erased)",
+                       (unsigned long)done);
+}
+#endif /* STORAGE_RECOVERY_FULL_WIPE */
+
+/* TC-STO-04: 维护模式（恢复 = 重建 BBT + 重新格式化；叠加全片擦除 = 容量恢复）
  * 仅在启用 ENABLE_STORAGE_RECOVERY_TESTS 时编译运行；运行一次即可把设备
  * 恢复到干净出厂态（清除运行时注入坏块并清空 dhara map）。
  */
 static void storage_test_recover(void)
 {
-    DBG_INFO("=== Storage Test: TC-STO-04 BBT rebuild + format (recovery) ===");
+    DBG_INFO("=== Storage Test: TC-STO-04 maintenance (recovery / full wipe) ===");
 
     int r = gd5f2gq5ue_bbt_rebuild();
     STORAGE_TEST_CHECK(r == GD5F_OK, "TC-STO-04 bbt rebuild");
 
+#ifdef STORAGE_RECOVERY_FULL_WIPE
+    storage_test_wipe_visible();
+#else
     nand_ftl_format();
     STORAGE_TEST_CHECK(1, "TC-STO-04 nand_ftl_format done");
+#endif
 
     uint8_t fb[GD5F_TOTAL_BLOCKS / 8];
     uint32_t ver = 0;
@@ -565,6 +612,11 @@ static void storage_test_recover(void)
         STORAGE_TEST_CHECK(0, "TC-STO-04 dump_flash failed");
     }
 
+#ifdef STORAGE_RECOVERY_FULL_WIPE
+    DBG_INFO("TC-STO-04 full wipe complete; power-cycle to rebuild fresh "
+             "(capacity expected back to full)");
+#else
     DBG_INFO("TC-STO-04 recovery complete; recommend power-cycle to re-init cleanly");
+#endif
 }
 #endif