refactor: store mail flags in sparse relation table

vitepress-docs/docs/en/guide/feature/mail-api.md

@@ -21,7 +21,7 @@ res = requests.get(
 
 ## Mail State API
 
-After enabling `ENABLE_MAIL_FLAGS` and running the database migration, each mail response includes the boolean field `unread`. The backend owns storage, historical `NULL` compatibility, and state calculation.
+After enabling `ENABLE_MAIL_FLAGS` and running the database migration, each mail response includes the boolean field `unread`. Mail states live in a separate sparse relation table without changing `raw_mails`; historical mail without a state record is read by default, and the backend owns all state calculation.
 
 With an Address JWT, use `GET /api/mail-states` to retrieve the currently available system states. This endpoint is the extension point for future address-specific custom states. The frontend uses each returned `value` directly for filtering and moving, and displays its `label_key` or `label`.
 

vitepress-docs/docs/en/guide/worker-vars.md

@@ -102,7 +102,7 @@
 | `REMOVE_EXCEED_SIZE_ATTACHMENT` | Text/JSON | If attachment exceeds 2MB, remove it, email may lose some information due to parsing                                   | `true`                     |
 | `REMOVE_ALL_ATTACHMENT`         | Text/JSON | Remove all attachments, email may lose some information due to parsing                                                 | `true`                     |
 | `ENABLE_MAIL_GZIP`             | Text/JSON | When enabled, new emails are gzip-compressed and stored in `raw_blob` column to save D1 database space. Existing plaintext `raw` data is automatically compatible for reading. **Run database migration first (`Admin -> Quick Setup -> Database -> Migrate Database` or `POST /admin/db_migration`) to ensure the `raw_blob` column exists before enabling. This feature adds compression/decompression CPU overhead, so enabling it on a paid Cloudflare Worker plan is recommended.** | `true`                     |
-| `ENABLE_MAIL_FLAGS`            | Text/JSON | Enables per-message state in the web inbox. New mail starts unread and can be opened to mark read, toggled manually, filtered by state, or marked read for the current page. Historical `NULL`/`0` values are treated as read. **Run the database migration first so `raw_mails.flags` exists before enabling this option.** | `true`                     |
+| `ENABLE_MAIL_FLAGS`            | Text/JSON | Enables per-message state in the web inbox. New mail starts unread and can be opened to mark read, toggled manually, filtered by state, or marked read for the current page. State is stored in a separate sparse relation table without changing `raw_mails`; historical mail without a relation is read by default. **Run the database migration first so the `mail_flags` table exists.** | `true`                     |
 | `CLEANUP_BATCH_SIZE`           | Number    | Per-run limit for mail, sent-mail, and creation/activity-based address cleanup. Defaults to `3000`, valid range `1-5000`. Smaller values reduce per-run D1 pressure; larger values clear backlogs faster | `3000` |
 
 > [!NOTE]

vitepress-docs/docs/zh/guide/feature/mail-api.md

@@ -21,7 +21,7 @@ res = requests.get(
 
 ## 邮件状态 API
 
-启用 `ENABLE_MAIL_FLAGS` 并完成数据库迁移后，邮件响应会包含布尔字段 `unread`。数据库存储、历史 `NULL` 兼容和状态计算全部由后端处理。
+启用 `ENABLE_MAIL_FLAGS` 并完成数据库迁移后，邮件响应会包含布尔字段 `unread`。邮件状态保存在独立的稀疏关联表中，不修改 `raw_mails`；没有状态记录的历史邮件默认已读，状态计算全部由后端处理。
 
 地址 JWT 使用 `GET /api/mail-states` 获取当前可用的系统状态；该接口也是未来扩展地址自定义状态的入口。前端直接使用其中的 `value` 作为筛选和移动参数，并使用 `label_key` 或 `label` 显示名称。
 

vitepress-docs/docs/zh/guide/worker-vars.md

@@ -97,7 +97,7 @@
 | `REMOVE_EXCEED_SIZE_ATTACHMENT` | 文本/JSON | 如果附件大小超过 2MB，则删除附件，邮件可能由于解析而丢失一些信息           | `true`                     |
 | `REMOVE_ALL_ATTACHMENT`         | 文本/JSON | 移除所有附件，邮件可能由于解析而丢失一些信息                               | `true`                     |
 | `ENABLE_MAIL_GZIP`             | 文本/JSON | 启用后新邮件将 Gzip 压缩存储到 `raw_blob` 字段，可节省 D1 数据库空间。已有明文 `raw` 数据自动兼容读取。**启用前请先执行数据库迁移（`Admin -> 快速设置 -> 数据库 -> 升级数据库 Schema` 或 `POST /admin/db_migration`），确保 `raw_blob` 列已创建。该功能会增加压缩/解压 CPU 开销，建议使用 Cloudflare Worker 付费 Plan 再开启。** | `true`                     |
-| `ENABLE_MAIL_FLAGS`            | 文本/JSON | 启用网页邮件状态功能。新邮件默认未读，支持打开自动已读、手动切换、按状态筛选及本页全部已读。历史邮件的 `NULL`/`0` 状态默认按已读处理。**启用前必须先执行数据库迁移，确保 `raw_mails.flags` 列已创建。** | `true`                     |
+| `ENABLE_MAIL_FLAGS`            | 文本/JSON | 启用网页邮件状态功能。新邮件默认未读，支持打开自动已读、手动切换、按状态筛选及本页全部已读。状态存储在独立的稀疏关联表中，不修改 `raw_mails`，无关联记录的历史邮件默认已读。**启用前必须先执行数据库迁移，确保 `mail_flags` 表已创建。** | `true`                     |
 | `CLEANUP_BATCH_SIZE`           | 数字      | 邮件、发件箱及按创建/活跃时间清理地址时的单次处理上限，默认 `3000`，有效范围 `1-5000`。较小值可降低单次 D1 压力，较大值可加快积压数据清理 | `3000` |
 
 > [!NOTE]