docs: add Invoice Hub UI roadmap designs

Author: if16888

docs/design/2026-06-21-invoice-hub-0.1.5-settings-mailbox-design.md

@@ -0,0 +1,257 @@
+# Invoice Hub 0.1.5 设置中心与邮箱闭环设计
+
+## 目标
+
+把当前分散且尺寸偏小的设置对话框升级为桌面工作型设置中心，使办公人员能够在一个稳定入口中查看、添加、编辑、启停、测试和删除多个邮箱账户，同时不破坏既有账户身份、扫描范围和授权码隐私语义。
+
+0.1.5 只完成设置中心框架与邮箱接入闭环。AI 配置保留当前可用入口，但完整信息架构和体验升级归入 0.1.6。
+
+## 设计原则
+
+1. 延续 0.1.4 的白底、浅灰边框、蓝色主操作和紧凑桌面密度。
+2. `email_accounts` 是邮箱配置主数据源；legacy `email`、`imap`、`search` 只是兼容投影。
+3. `mailbox_key` 是已保存账户的稳定身份，不随 provider、邮箱地址或显示名称改变而重新生成。
+4. 已保存账户与新建草稿是两种状态：已保存账户不得被静默改写，未保存草稿才允许 provider 后缀辅助修正。
+5. 授权码只进入系统凭据存储，不回显、不写配置、不进入日志或错误摘要。
+6. Outlook、Hotmail、Live 和 Microsoft 365 继续明确提示需要 OAuth2/XOAUTH2；0.1.5 不伪装成普通 IMAP 可用。
+7. 删除邮箱配置不删除已经导入的发票、附件、报销组或历史记录。
+
+## 方案选择
+
+- 方案 A：邮箱、AI、系统设置分别使用独立弹窗。改动较小，但入口分散且组件重复。
+- 方案 B：统一设置中心，邮箱和 AI 使用独立页面与向导。信息边界清楚、组件可复用，采用此方案。
+- 方案 C：把设置全部放进主窗口导航。空间充足，但会打断审核主路径并扩大 0.1.5 范围。
+
+## 版本边界
+
+### 包含
+
+- 统一设置中心工作对话框。
+- 邮箱账户列表、空状态、启用/禁用、编辑和删除。
+- 三步邮箱接入向导。
+- 账户级扫描范围、IMAP 参数、连接测试和保存门禁。
+- 保存账户与新建草稿的明确状态边界。
+- 授权码安全状态、错误分类和可恢复操作。
+- 0.1.4 通用组件在设置场景中的复用和扩展。
+
+### 不包含
+
+- Outlook OAuth2/XOAUTH2 实现。
+- 新邮件协议、云端账户系统或服务器端同步平台。
+- 定时任务调度器；“同步频率”仅在存在真实调度能力后加入。
+- 邮件识别规则编辑器。
+- AI 配置中心重构。
+- 删除已导入业务数据。
+
+## 统一设置中心框架
+
+### 尺寸
+
+主设计基准仍为 1920×1080，设置中心使用 1120×720 工作型模态对话框：
+
+| 区域 | 尺寸 |
+|---|---:|
+| 标题栏 | 56 px 高 |
+| 左侧设置导航 | 184 px 宽 |
+| 内容区 | 自适应，最小 760 px 宽 |
+| 固定底栏 | 64 px 高 |
+| 内容边距 | 20 px |
+| 列表行 | 64–72 px 高 |
+
+设置中心不是传统小表单。左侧导航、右侧内容和固定底栏同时可见，内容区内部按页面独立滚动，整个对话框不得出现横向滚动。
+
+### 导航
+
+0.1.5 只显示真实可用入口：
+
+```text
+邮箱账户
+AI 配置（保留当前能力，标记“将在 0.1.6 优化”）
+系统设置（保留现有字段）
+数据与备份（仅在现有能力可用时显示）
+关于
+```
+
+不得为了视觉完整加入没有内容或没有保存闭环的页面。
+
+### 固定底栏
+
+- 左侧：当前页面安全提示或“恢复默认设置”，仅在当前页面有对应能力时显示。
+- 右侧：取消、保存并关闭。
+- 页面内部已即时保存的账户操作不重复依赖全局保存；存在未保存向导草稿时，关闭设置中心必须提示保存、放弃或取消。
+
+## 邮箱账户页
+
+### 页面结构
+
+```text
+页面标题 + 说明                         新增邮箱账户
+账户状态摘要：启用 N / 已配置 N / 需要处理 N
+邮箱账户列表
+安全与隐私说明
+```
+
+账户状态摘要只显示数量，不使用营销式大卡片。
+
+### 账户行
+
+每个 `ConfigListRow` 显示：
+
+- 账户显示名称与掩码邮箱地址。
+- provider 徽章。
+- 启用/禁用状态。
+- 扫描范围，例如“最近 3 个月”。
+- 凭据状态：已安全保存、未配置、需要重新验证。
+- 最近同步时间；没有真实时间时显示“尚未同步”，不伪造成功状态。
+- 主要动作：编辑。
+- 次要菜单：启用/禁用、删除。
+
+列表默认按启用账户优先、最近编辑时间次序排列。账户数量较多时只滚动列表，不分页。
+
+### 空状态
+
+无账户时显示支持的 provider、授权码安全说明和“新增邮箱账户”。不显示空表格，也不自动创建占位账户。
+
+### 启用与禁用
+
+- 至少保留一个可扫描的启用账户；禁用最后一个启用账户必须阻止并说明原因。
+- Outlook-like 保存记录不计入“可扫描启用账户”。
+- 切换成功后立即更新 legacy 投影到第一个可扫描启用账户。
+- 失败时恢复开关原状态并显示具体原因。
+
+### 删除
+
+删除确认必须明确：删除账户配置、系统凭据和扫描状态，但保留已导入发票、附件和报销数据。删除后如果还有启用账户，重新选择第一个可扫描账户作为兼容投影。
+
+## 三步邮箱接入向导
+
+向导使用 760×560 `WizardDialog`。步骤头 52 px、主体自适应、底栏 64 px，三步高度保持稳定。
+
+### 第一步：选择邮箱并填写账户信息
+
+provider：QQ、163、126、Gmail、Outlook、自定义 IMAP。
+
+字段：
+
+- 账户显示名称。
+- 完整邮箱地址。
+- 扫描范围：最近 1、3、6、12 个月。
+- 自定义 IMAP 时显示 server、port、SSL。
+
+交互规则：
+
+- 新建草稿可以根据 provider 辅助改写已输入的已知邮箱后缀。
+- 一旦加载已保存账户，provider 切换不得静默改写邮箱地址。
+- 已保存账户始终按 `mailbox_key` 编辑，即使 provider 或地址被用户显式修改。
+- 已知 provider 与邮箱域不一致时禁止下一步，并建议修改地址或使用自定义 IMAP。
+- Outlook-like 选择后显示 OAuth2 能力边界，禁用下一步和普通 IMAP 测试。
+
+### 第二步：授权码与连接测试
+
+字段和状态：
+
+- `SecureInput`：未配置、已安全保存、重新输入将覆盖。
+- 授权码帮助入口，说明“不是邮箱登录密码”。
+- 连接测试结果区。
+
+连接测试顺序：
+
+1. 校验 provider、邮箱域、自定义服务器和端口。
+2. 确认新授权码或可用的已保存凭据。
+3. 建立 IMAP 连接并验证身份。
+4. 验证目标文件夹可读取。
+5. 返回成功或可操作错误，不显示原始异常和敏感连接参数。
+
+地址、provider、server、port 或 SSL 改变后进入 `dirty-sensitive`，之前的测试成功立即失效。只有重新测试成功后才允许保存这些敏感变更。
+
+### 第三步：复核并保存
+
+复核内容：账户名称、掩码地址、provider、IMAP 主机、扫描范围、凭据状态和测试时间。
+
+动作：
+
+- 上一步。
+- 取消。
+- 保存账户。
+- 保存后立即同步，仅在真实同步入口可调用时显示，并默认不勾选。
+
+保存成功后清空授权码输入，回到账户列表并高亮该 `mailbox_key`。
+
+## 账户状态机
+
+| 状态 | 含义 | 允许动作 |
+|---|---|---|
+| `new-draft` | 未绑定已保存账户 | provider 辅助、测试、取消 |
+| `saved-clean` | 已加载且未修改 | 测试、启停、删除 |
+| `saved-dirty-safe` | 只改名称或扫描范围 | 直接保存、取消 |
+| `saved-dirty-sensitive` | 地址、provider 或 IMAP 参数改变 | 重新输入凭据、重新测试、取消 |
+| `testing` | 正在连接 | 取消测试，不允许重复提交 |
+| `tested-ok` | 当前敏感字段测试成功 | 保存 |
+| `test-failed` | 测试失败 | 修改、重试、取消 |
+| `unsupported` | Outlook/OAuth2 边界 | 查看说明、返回 |
+
+测试结果必须绑定字段指纹；字段变化后不得继续复用旧测试成功状态。
+
+## 错误与反馈
+
+| 类型 | 文案目标 | 恢复动作 |
+|---|---|---|
+| 域名不一致 | 指明邮箱类型与后缀不一致 | 修改地址 / 选自定义 IMAP |
+| 服务器缺失 | 指明缺少 server 或无效端口 | 聚焦对应字段 |
+| 网络不可达 | 说明无法连接主机 | 检查网络 / 重试 |
+| 认证失败 | 说明授权码或 IMAP 权限可能无效 | 重新输入授权码 / 查看帮助 |
+| OAuth2 必需 | 明确不是普通密码错误 | 返回 / 查看支持说明 |
+| 敏感变更未重测 | 说明哪些字段变化导致测试失效 | 重新测试 |
+| 保存失败 | 保留草稿和输入 | 重试 / 取消 |
+
+Toast 只用于成功和无需决策的短反馈；认证、删除、未保存草稿和不可逆操作使用页面错误或确认对话框。
+
+## 安全与隐私
+
+- 已保存授权码永不回填；只显示枚举状态。
+- Secret 输入禁止复制和剪切，允许粘贴。
+- 配置保存必须剥离 `auth_code`、`password`、`token` 和 `api_key`。
+- 错误、日志、测试摘要和剪贴板不得包含 secret。
+- 账户地址可以掩码展示，但编辑时显示完整地址；绝对路径和系统凭据标识不显示。
+
+## 通用组件复用
+
+复用 0.1.4：`DialogShell`、`ActionButton`、`StatusBadge`、`SectionCard`、`StatePanel`、`ToastHost`。
+
+0.1.5 新增：
+
+| 组件 | 稳定职责 |
+|---|---|
+| `SettingsLayout` | 设置导航、内容区和固定底栏 |
+| `ConfigListRow` | 配置主信息、状态、辅助信息和动作 |
+| `WizardDialog` | 稳定步骤头、主体和底栏 |
+| `SecureInput` | Secret 输入、安全状态和覆盖语义 |
+| `SafetyNotice` | 安全、隐私和不可逆操作说明 |
+
+组件只接收 view state 和发出用户意图，不直接读写配置、凭据或数据库。
+
+## 键盘与可访问性
+
+- `Tab` 顺序：设置导航 → 页面标题动作 → 列表 → 页面底栏。
+- 向导中 `Enter` 只触发当前可用的下一步或测试，不越过校验；`Esc` 先处理未保存草稿。
+- 状态不能只靠颜色，必须有文字和图标。
+- 焦点边框清晰，Secret 的安全限制不能阻止键盘粘贴。
+- 125% 和 150% Windows 缩放下不得裁切字段、按钮或错误说明。
+
+## 响应式规则
+
+- 1920×1080：1120×720 完整展开。
+- 1440×900：对话框最大化到可用区域，左导航可压缩到 160 px。
+- 1366×768：对话框使用屏幕可用区域，导航折叠为图标加 tooltip，辅助说明可折叠；不得横向滚动。
+- 小尺寸只压缩间距和辅助说明，不隐藏保存、取消、测试、编辑和删除等关键动作。
+
+## 验收标准
+
+1. 多账户按 `mailbox_key` 精确编辑，provider 改变不会产生重复身份。
+2. 已保存账户不会被 provider 切换静默改写地址；只有新草稿允许后缀辅助。
+3. 敏感字段改变后必须重新输入可用凭据并测试成功。
+4. Outlook-like 账户在下一步、测试、保存和同步入口均保持一致阻断。
+5. 授权码不出现在配置、日志、错误、摘要或剪贴板中。
+6. 禁用最后一个可扫描账户被阻止；删除账户不影响已导入业务数据。
+7. 1920×1080、1440×900 和 1366×768 均能完成新增、编辑、测试、启停和删除。
+8. 设置中心无空壳页面、无横向滚动、无依赖颜色的唯一状态表达。