解决一个擦除的bug

AGENTS.md

@@ -143,8 +143,15 @@ HAL_Init() → SystemClock_Config() → MX_GPIO_Init() → MX_USART1_UART_Init()
 - SPI Mode 0（CPOL=0, CPHA=0），时钟 42MHz
 - 初始化必须按顺序：复位 → 读 ID → 使能 ECC（B0h=10h）→ 解除块保护（A0h=00h）
 - SET_FEATURE 命令前必须先发写使能（06h）
-- 块擦除（D8h）参数是字节地址（块编号 × 128KB），不是块编号
+- 块擦除（D8h）参数是块首页地址（块编号 × 64），不是字节地址（旧版错误）
 - 读取 ID（9Fh）返回 3 字节，第 0 字节无意义，第 1 字节 MID，第 2 字节 DID
+- **BBT 扫描必须在 ECC 禁用时完成**（`gd5f_bbt_scan()`），ECC 使能后 reading spare area 会被 ECC 引擎干扰
+- **运行时坏块标记只来源于真实擦除/编程失败**，不要在 ECC 使能后调用 `gd5f2gq5ue_bbt_rescan()` 重建 BBT
+- **BBT 厂标坏块不可清除**：`gd5f_bbt_scan()` 在 ECC 禁用时扫到的 786 个坏块是真实厂标标记（保守标记，最坏条件）。验证擦除+编程通过不代表不是坏块。初始 BBT 必须保留，只追加运行时损坏块
+- **Block 0 有特殊行为**："Factory good block0" / "Power on Read"。大量相邻块操作后 block 0 数据可能被擦除，避免将其用于跨大批量操作的持久化存储
+- **ECC 校验码生成不可靠**：`PROGRAM LOAD 02h + PROGRAM EXEC 10h` 在 ECC 开启时可能不生成有效 ECC 校验码（ECCS=2）。应用层应使用独立数据校验（CRC/Checksum），不可依赖 chip 内部 ECC 状态位
+- **写验证**：以擦除/编程状态位（E_FAIL/P_FAIL）为准，不要回读数据确认（ECCS 不可靠，block 0 不可靠）
+- 详细陷阱记录见 `docs/GD5F2GQ5UE_Trap_Records.md`
 
 ## Flash 分区规划（256MB GD5F2GQ5UE）
 
@@ -210,9 +217,9 @@ HAL_Init() → SystemClock_Config() → MX_GPIO_Init() → MX_USART1_UART_Init()
 
 ## 陷阱记录
 
-详细陷阱记录（含根因分析、解决方案、发现时间）见 `docs/CH395F_Trap_Records.md`。
+详细陷阱记录（含根因分析、解决方案、发现时间）见 `docs/CH395F_Trap_Records.md` 和 `docs/GD5F2GQ5UE_Trap_Records.md`。
 
-当前已记录陷阱：
+当前已记录陷阱（CH395F）：
 - **Trap 01** Socket 4~7 自动分配不到（初始化顺序）
 - **Trap 02** 数据 Socket 缓冲区重叠
 - **Trap 03** DHCP 包 xid 偏移错误
@@ -221,3 +228,6 @@ HAL_Init() → SystemClock_Config() → MX_GPIO_Init() → MX_USART1_UART_Init()
 - **Trap 06** TCP KeepAlive 参数非 500ms 倍数
 - **Trap 07** TCP 关闭误用 disconnect 导致 FIN_WAIT_2
 - **Trap 08** RECV 中断电平触发无限循环
+
+当前已记录陷阱（GD5F2GQ5UE）：
+- **Trap 01** 块擦除地址错误（`byte_addr → page_addr`），导致先前所有实验结论无效。详见 `docs/GD5F2GQ5UE_Trap_Records.md`