NewSzxcn-Email/docs/ISSUE_LEDGER.md

NewSzxcn Email 问题台账

本文件是 NewSzxcn Email 的单一问题台账。所有问题保留唯一编号和完整历史，不重复建立“历史问题”副本。

管理模式

• 当前任务是唯一长期运行的 NewSzxcn 项目任务。
• 内部按项目总览、问题中心、前端、后端、邮件核心、部署运维、质量复核、文档发布分类管理。
• 用户提出问题后，默认在同一任务内完成分类、资料查询、代码/服务器调查、修复、测试、复核和发布门禁。
• 只有问题确实复杂且用户同意时，才临时开启专项任务。
• 用户明确说“先记录”“不要修改”“等问题多了一起处理”时，只登记和调查，不实施产品代码修改。

状态

允许状态：新反馈、待复现、待确认、待处理、处理中、待验收、已完成、已归档。

固定流程：收集问题 -> 复现 -> 用户确认批次 -> 实现 -> 回归 -> CI -> 全部镜像完成 -> Release -> 通知更新 -> 线上验收。

发布门禁：CI 未通过不得进入 Release；全部镜像未完成不得通知更新。

模块职责

分类	责任
项目总览	统一编号、状态流转、批次确认、冲突协调、发布门禁
问题中心	问题收集、复现证据、影响面、严重度、完整历史
前端	Web 页面、交互、批量操作、权限可见性、前端构建
后端	API、鉴权、数据库、业务校验、后台任务
邮件核心	IMAP/SMTP、Postfix、Dovecot、Rspamd、Maildir、投递与同步
部署运维	install.sh、Docker、Compose、Nginx、CI/CD、服务器调查
质量复核	独立复核、回归测试、风险确认、验收建议
文档发布	版本说明、部署说明、Release 文案、更新通知

问题列表

编号	日期	状态	模块	现象	严重度	目标版本	发布状态
NSX-20260804-001	2026-08-04	已完成	前端主责；后端、邮件核心协作	全部邮箱批量移动到自定义文件夹失败	S2	v1.2.14	随 v1.2.14 发布
NSX-20260804-002	2026-08-04	已完成	前端/UI/响应式布局	邮箱选择器展开后宽度变窄	S3	v1.2.14	随 v1.2.14 发布
NSX-20260805-003	2026-08-05	已完成	前端/UI/布局稳定性	邮箱页与设置页侧栏宽度/边框位置不一致	S3	v1.2.14	随 v1.2.14 发布
NSX-20260806-004	2026-08-06	已完成	前端/UI/响应式布局	“全部邮箱”选择器右侧存在复制按钮空白占位	S3	v1.2.15	随 v1.2.15 发布
NSX-20260806-005	2026-08-06	已完成	后端/通知；前端/设置；部署运维/CI	Telegram 私聊邮件通知与 Release 频道通知	S3	v1.2.16	随 v1.2.16 发布
NSX-20260806-006	2026-08-06	已完成	后端/通知；邮件核心；前端/设置；质量复核	Telegram 邮件通知安全、验证码复制和可靠性复核	S2	v1.2.17	随 v1.2.17 发布

NSX-20260804-001

字段	内容
编号	NSX-20260804-001
日期	2026-08-04
状态	已完成
模块	前端主责；后端、邮件核心协作；质量复核待后续介入
现象	全部邮箱批量移动到自定义文件夹失败
截图	待用户补充
复现步骤	待补充。已知描述：选择全部邮箱后，批量移动到自定义文件夹失败。
影响	影响批量整理邮件，用户可能只能逐封或分批移动；是否造成数据错位或丢失待复现确认。
严重度	S2
根因	全部邮箱视图中批量移动沿用单邮箱移动路径，目标自定义文件夹没有按消息所属邮箱分别解析/创建，跨邮箱消息会出现 failed to move message。
关联提交	未提交；关联工作区文件：apps/api/internal/app/mail_handlers.go、apps/web/src/pages/mail.tsx、apps/web/src/lib/api.ts、apps/api/internal/app/app_test.go。
目标版本	v1.2.14
测试结果	已完成 Go 全量测试、go vet、前端 check/build、安装脚本测试和 ShellCheck；批量移动回归测试覆盖跨邮箱、自定义文件夹及部分失败结果。
发布状态	随 v1.2.14 发布。

分派

分类	处理方式
项目总览	已纳入本批实施，当前状态待验收，未进入发布。
问题中心	已补充根因和实现证据；等待完整回归和用户线上验收。
前端	已接入批量移动接口并展示中文成功/失败明细。
后端	已实现批量移动接口，按消息所属邮箱隔离处理目标文件夹和权限。
邮件核心	已保持消息所属邮箱和文件夹映射隔离，完整运行回归待主任务执行。
部署运维	暂无服务器动作；涉及线上日志或容器状态时再介入。
质量复核	修复后独立复核批量移动、部分失败、权限边界、回归风险。
文档发布	进入版本批次后整理发布说明；全部镜像完成后才可通知更新。

历史

时间	记录
2026-08-04	用户指定切换为精简单任务模式，并要求“全部邮箱批量移动到自定义文件夹失败”继续只调查不修改，等待汇总更多问题。
2026-08-04	项目总控建立唯一问题编号 NSX-20260804-001，状态设为待复现。
2026-08-05	用户确认本批继续实施；已实现可靠批量移动接口并接入前端批量移动入口，状态流转为待验收。

NSX-20260804-002

字段	内容
编号	NSX-20260804-002
日期	2026-08-04
状态	已完成
模块	前端/UI/响应式布局；质量复核待后续介入
现象	左侧栏选择具体邮箱账号后，顶部邮箱选择器和展开菜单比“全部邮箱”状态明显变窄，邮箱地址显示为 crrhuawei@new...，下拉项也被过早截断。右侧复制按钮占位后，选择器宽度发生变化。
截图	/var/folders/wg/mx262rx107b8j614sq2mnmy00000gn/T/codex-clipboard-fadc6a64-ce13-4a5e-ae8f-5de7e7756e62.png
复现步骤	1. 打开邮箱左侧栏。 2. 从“全部邮箱”切换到具体邮箱账号。 3. 展开顶部邮箱选择器。 4. 观察选择器宽度、展开菜单宽度、邮箱地址截断和复制按钮出现后的布局变化。
影响	影响账号切换区域的可读性和稳定性；邮箱地址过早截断，复制按钮出现时造成布局跳变。
严重度	S3
根因	邮箱选择器右侧复制按钮只在具体邮箱状态占位，触发区域宽度随状态变化；下拉菜单宽度跟随被挤压后的触发区域，导致邮箱地址过早截断。
关联提交	未提交；关联工作区文件：apps/web/src/pages/mail.tsx。
目标版本	v1.2.14
测试结果	前端 check/build 通过；桌面浏览器验证“全部邮箱”和具体邮箱状态均保留复制按钮固定槽位，具体邮箱触发区宽 225px；390×844 移动端无横向溢出。
发布状态	随 v1.2.14 发布。

期望

邮箱选择器在“全部邮箱”和具体邮箱两种状态下保持原来的稳定长度；展开菜单宽度与选择区域协调，尽量完整显示邮箱地址；复制按钮出现时不能挤压选择器或造成布局跳变。

关联

与此前“全部邮箱选择器长度、复制按钮出现后布局变化”反馈关联；本条作为可复现回归继续保留，不合并归档。

分派

分类	处理方式
项目总览	已纳入本批实施，当前状态待验收，未进入发布。
问题中心	保留截图路径、现象、期望和关联背景；已补充根因和实现证据。
前端	已固定复制按钮占位和下拉菜单宽度，等待桌面/移动验收。
后端	暂无介入需求。
邮件核心	暂无介入需求。
部署运维	暂无介入需求。
质量复核	修复后复核“全部邮箱”和具体邮箱两种状态、展开菜单、长邮箱地址、复制按钮出现前后布局稳定性。
文档发布	进入版本批次后整理发布说明；全部镜像完成后才可通知更新。

历史

时间	记录
2026-08-04	用户新增“邮箱选择器展开后宽度变窄”待处理问题，要求只登记，不修改。
2026-08-04	项目总控建立唯一问题编号 NSX-20260804-002，状态设为待处理。
2026-08-05	用户确认本批继续实施；已固定复制按钮占位和下拉菜单宽度，状态流转为待验收。

NSX-20260805-003

字段	内容
编号	NSX-20260805-003
日期	2026-08-05
状态	已完成
模块	前端/UI/布局稳定性；质量复核待后续介入
现象	邮箱页面左侧栏明显更宽，设置页面侧栏变窄，垂直分隔边框与主内容起点改变；点击齿轮切换时产生页面左右跳动和“页面变来变去”的感觉。
截图	邮箱页：/var/folders/wg/mx262rx107b8j614sq2mnmy00000gn/T/codex-clipboard-e293b3f1-7797-49ec-b5f9-b7de08ba4c6c.png；设置页：/var/folders/wg/mx262rx107b8j614sq2mnmy00000gn/T/codex-clipboard-89b85640-d262-4b1c-8996-cd097036614e.png
复现步骤	1. 打开邮箱页面。 2. 观察左侧栏宽度、垂直分隔线、顶部栏高度和主内容起点。 3. 点击齿轮进入设置页面。 4. 对比设置页侧栏宽度、分隔线位置和主内容起点。 5. 返回邮箱页，观察页面是否左右跳动。
影响	影响应用壳层稳定性和页面切换体验；邮箱页与设置页布局不一致会造成明显跳动，并可能影响邮箱选择器可用宽度。
严重度	S3
根因	邮箱页和设置页分别使用独立侧栏宽度，设置页硬编码宽度小于邮箱页，导致切换时分隔线与主内容起点变化。
关联提交	未提交；关联工作区文件：apps/web/src/index.css、apps/web/src/pages/profile.tsx、apps/web/src/pages/mail.tsx。
目标版本	v1.2.14
测试结果	前端 check/build 通过；桌面浏览器实测邮箱页与设置页侧栏均为 288px，页面宽 1440px 且无横向溢出；390×844 移动端邮箱和设置页面均无横向溢出、遮挡或控制台错误。
发布状态	随 v1.2.14 发布。

期望

邮箱和设置页面使用统一的应用壳层尺寸；侧栏宽度、垂直分隔线、顶部栏高度和主内容起点保持一致，只替换内部导航内容。后续方案需核对桌面与移动端，不允许使用会挤压邮箱选择器的临时宽度。

批次关联

纳入即将给用户确认的前端/UI/布局稳定性候选批次。与 NSX-20260804-002 均涉及邮箱页左侧区域布局稳定性，但本条关注跨页面应用壳层尺寸一致性，保持独立编号。

分派

分类	处理方式
项目总览	已纳入本批实施，当前状态待验收，未进入发布。
问题中心	保留两张截图路径、现象、期望和验收注意事项；已补充根因和实现证据。
前端	已统一邮箱页与设置页应用壳层侧栏宽度变量，等待桌面/移动验收。
后端	暂无介入需求。
邮件核心	暂无介入需求。
部署运维	暂无介入需求。
质量复核	修复后独立复核桌面与移动端页面切换稳定性，确认不会挤压邮箱选择器或造成新的布局跳变。
文档发布	进入版本批次后整理发布说明；全部镜像完成后才可通知更新。

历史

时间	记录
2026-08-05	用户新增“邮箱页与设置页侧栏宽度/边框位置不一致”待处理问题，要求只登记并纳入即将确认的批次方案，现在不要修改。
2026-08-05	项目总控建立唯一问题编号 NSX-20260805-003，状态设为待处理。
2026-08-05	用户确认本批继续实施；已统一应用壳层侧栏宽度变量，状态流转为待验收。

NSX-20260806-004

字段	内容
编号	NSX-20260806-004
日期	2026-08-06
状态	已完成
模块	前端/UI/响应式布局
现象	“全部邮箱”状态没有复制按钮，但选择器右侧仍永久保留一列空白区域，箭头与侧栏边框之间出现明显空块。
截图	/var/folders/wg/mx262rx107b8j614sq2mnmy00000gn/T/codex-clipboard-ae8ada7f-ba00-4036-9103-8cb76b9496a2.png；/var/folders/wg/mx262rx107b8j614sq2mnmy00000gn/T/codex-clipboard-80fb1ec3-9e98-4159-a8fb-b79a0b0e9a32.png
根因	为避免具体邮箱状态出现复制按钮时选择器缩窄，旧实现始终保留 32px 复制按钮网格列；“全部邮箱”状态只是隐藏按钮，没有释放占位。
实现	选择器改为始终占满整行；只有具体邮箱状态才显示覆盖式复制按钮，并在选择器内容区预留图标空间。
目标版本	v1.2.15
测试结果	前端 check/build 通过；1280px 桌面端选择器宽度在两种状态下均为 263px；390×844 移动端侧栏选择器宽度均为 294px，页面无横向溢出；控制台无错误或警告。
发布状态	随 v1.2.15 发布。

历史

时间	记录
2026-08-06	用户反馈“全部邮箱”右侧存在空白块并要求修改。
2026-08-06	已移除永久占位列，改为具体邮箱状态覆盖显示复制按钮，状态流转为待验收。

NSX-20260806-005

字段	内容
编号	NSX-20260806-005
日期	2026-08-06
状态	已完成
模块	后端/通知；前端/设置；部署运维/CI；质量复核
需求	后台配置 Telegram 机器人，将新邮件排版后发送到管理员私聊；GitHub Release 成功后统一向版本频道发送一次更新通知。
边界	邮件通知由各部署实例独立配置；版本通知只由 GitHub Release 工作流发送，不依赖已部署邮局是否更新。
实现	新增 Telegram 通知设置、私聊 Chat ID 自动获取、测试发送、正文模式、持久化通知队列、去重与失败重试；Release 工作流在全部镜像和 Release 成功后发送频道消息。
安全	Bot Token 不通过设置查询接口返回，不写入仓库；频道密钥使用 GitHub Actions Secrets；Telegram 失败不阻塞收件或版本发布。
兼容性	数据库只新增表和设置项；默认关闭；现有配置、邮件、证书和在线更新方式不变。
目标版本	v1.2.16
测试结果	Go 全量测试和 vet、前端 check/build、安装脚本语法/ShellCheck/回归、工作流 YAML、密钥扫描、桌面和移动端页面检查均通过。
发布状态	随 v1.2.16 发布。

历史

时间	记录
2026-08-06	用户确认后台只保留机器人私聊邮件通知，版本频道通知交由 GitHub Release 工作流统一发送。
2026-08-06	已配置仓库频道通知密钥并完成频道实发测试；真实 Bot Token 未写入源码。
2026-08-06	完成密钥隐藏、网络错误脱敏、通知失败隔离和 Release 重跑去重复核，状态流转为已完成。
2026-08-06	v1.2.16 检查、六个 Docker 镜像、GitHub Release 和 Telegram 频道通知全部成功。

NSX-20260806-006

字段	内容
编号	NSX-20260806-006
日期	2026-08-06
状态	已完成
模块	后端/通知；邮件核心；前端/设置；质量复核
现象	原自动获取 Chat ID 可能匹配错误私聊；通知范围默认覆盖全部本地邮箱；关闭后重开可能补发旧任务；收件邮箱、正文编码、长度预算、错误重试和验证码复制不完整。
根因	通知功能首版只覆盖基础发送，没有建立安全配对、显式邮箱范围、发送租约、Telegram 错误分类和统一的 MIME/正文规范化流程。
实现	使用 10 分钟一次性绑定码；通知范围改为显式邮箱和未知收件选择；目的地或范围变化时事务清理旧任务；增加发送租约、Telegram 消息编号、送达后正文清除、400 纯文本降级、429 retry_after、401/403 停止重试；新增验证码评分与 copy_text 按钮、全消息长度预算、附件清理、GBK 等正文字符集解码和伪 HTML 清理。
收件链路	修正实际收件地址解析；本地互发、未知收件和后续外部 IMAP 新邮件统一通知；首次外部 IMAP 历史导入不通知；收信规则先执行，垃圾邮件和已删除邮件不通知。
兼容性	数据库仅增加可空闲迁移列和设置项；现有 Bot Token 保留且不回传；升级后管理员邮箱自动成为默认通知范围，已开启通知的实例继续包含未知收件。
目标版本	v1.2.17
测试结果	Telegram 专项测试、Go 全量测试、go vet、竞态检测、前端 shadcn 检查和生产构建通过；桌面端与移动端页面视觉验收通过。
发布状态	随 v1.2.17 发布。

历史

时间	记录
2026-08-06	完成通知全链路复核，确认安全绑定、旧队列、收件地址、来源覆盖、长度预算、错误分类和 MIME 处理问题。
2026-08-06	用户确认继续修改，并明确保留现有机器人 Token。
2026-08-06	完成实现和自动化回归，状态流转为待验收。
2026-08-06	完成桌面端与移动端页面验收及最终回归，状态流转为已完成。