Smail/docs/文件目录整理说明.md

文件目录整理说明

需求确认

按本次要求将独立测试代码、脚本集中到 test/，测试记录集中到 test-log/，编译输出集中到 out/；不改动真实配置、账号库、证书或业务逻辑。

整理后的结构

Smail/
├── frontend/                 # 前端源码与依赖
├── backend/                  # 后端源码、必要的同包测试与运行配置
├── plugins/                  # 插件源码与文档
├── deploy/                   # 构建、开发启动及正式部署工具
├── test/                     # 独立测试源码、脚本和统一测试入口
│   ├── frontend/
│   ├── manual/
│   ├── plugins/
│   └── tools/
├── test-log/                 # 本地证据，不进入版本库
│   ├── archive/              # 历史日志、浏览器数据、配置备份
│   ├── fixtures/             # 历史初始化测试数据
│   ├── reports/              # 审查报告和移动、清理清单
│   ├── runtime/              # 前后端开发日志
│   └── screenshots/          # 截图及测试 Logo 图
├── out/                      # 编译输出，不进入版本库
│   ├── frontend/
│   ├── backend/
│   ├── plugins/
│   ├── test-tools/
│   └── archive/              # 尚需保留的旧编译产物
└── docs/                     # 项目文档

out/package/ 和 out/release/ 分别供 Makefile 打包及 CI 发布使用。开发日志由 deploy/start-dev.ps1 写入 test-log/runtime/，测试入口为 node test/run.mjs all。

必须保留的例外

1. Go 同包测试保留在 backend/：依赖包私有符号，直接搬离会破坏测试，统一入口负责集中执行。
2. backend/listen/http_server/dist/ 和 Telegram 插件的 hook/dist/ 是 Go 嵌入中间目录：Go 不允许跨模块向上嵌入，不能直接指向 out/。前端正式输出在 out/，构建后自动同步必需的嵌入文件。
3. 运行 Logo、文档图片、源代码静态资源、依赖目录、模型及训练工具不属于测试垃圾。
4. backend/config/ 是现有服务的数据根目录，配置、SQLite、密钥及迁移备份原位保留。根目录 ssl/ 和用途尚未确认的空数据库也保留，不凭文件名删除。

构建与启动

Set-Location D:\Desktop\Smail
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/build.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/start-dev.ps1 -Service backend
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/start-dev.ps1 -Service frontend

开发后端为 out/backend/smail-dev.exe。脚本固定 SMAIL_ROOT=backend/，不在 out/ 下创建新账号库。编译前应停止正在运行的同名二进制，停止前核对进程号和路径。正式部署仍需使用发行入口 cmd/smail，保留本机管理员恢复通道的权限保护。

两个新增 PowerShell 脚本使用 UTF-8 BOM，使 Windows PowerShell 5 正确解析中文；其他源文件沿用其原编码。没有用脚本替换中文文字。

清理与安全边界

• 历史 artifacts/ 中的记录、浏览器资料和配置备份移入 test-log/archive/artifacts/，二进制另归档到 out/archive/。
• 历史测试资料中的配置引用不自动重写；目录变更后它们只作为证据保留，不保证能够直接重放。
• 清理候选仅限已确认的空目录和校验哈希相同的重复归档编译文件，至少保留一份。本次删除命令被执行环境策略拦截，未执行物理删除；文件已集中归档，并保存待清理清单，不绕过策略。
• make clean 不再直接递归删除文件，必须先审查清单。
• 构建打包不复制本机真实配置、证书或密钥，首次正式部署应使用初始化流程。
• test-log/ 可能含浏览器 Cookie、测试凭据和配置备份，不能公开上传或提交；out/ 和历史工具归档同样不提交。

本轮任务点和实际验证结果见本文件末尾的验收记录；未做真实发信、模型运行或跨平台部署的项目，不算验收通过。

本次验收记录

• [✓] 前端自动测试、独立密码检查工具、SMTP 和模型测试脚本已迁入 test/；178 个 Go 同包测试原位保留。
• [✓] 历史日志、截图、测试数据库及配置备份完成归档，移动记录位于 test-log/reports/organization-moves.csv。
• [✓] 前端及后端开发程序、管理和配置工具输出到 out/；Telegram 前端及 Windows 插件构建通过。
• [✓] 归档期间 backend/config/ 下 79 个文件逐一哈希校验未改变，未清空数据库。
• [✓] node test/run.mjs all -- -count=1 ./... 通过，Go 测试未使用结果缓存；随后新增构建路径约束测试，最终前端及构建约束共 19 项全部通过。
• [✓] 从新目录启动前后端，443 和 15173 监听正常；后端与前端代理探活返回 200。
• [✓] 浏览器 MCP 忽略缓存刷新后仍显示收件箱，无登录框或错误提示；配置状态、基础配置、备份、审计读取均返回 200。
• [✓] 新脚本语法及 YAML 解析检查通过，out/、test-log/ 和历史脚本归档均被 Git 忽略。
• [✓] Windows 正式入口程序及微信、垃圾邮件和 Telegram 插件均成功编译到 out/，未启动正式服务或执行插件业务操作。
• [!] 物理删除未完成：发现 2 个哈希完全相同的重复二进制候选，约 201.75 MiB；文件仍保留，见 duplicate-binaries-retained.csv，空目录清单见 empty-directories-retained.csv。
• [!] 本次未验收模型推断、真实 SMTP 发信、全平台发布或 Linux/Windows 正式安装；未重新执行清库初始化流程，避免破坏用户现有账号与配置。