# 文件目录整理说明

## 需求确认

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

## 整理后的结构

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

Makefile 与 CI 使用相同打包流程：`out/package/Smail_<系统>_<架构>/smail/` 保存部署目录，`out/release/` 保存同名压缩包，校验回执独立保存在 `out/release-receipts/`。部署包固定包含三个程序和 `config/data/ssl/log` 四个空目录，完整说明见《插件构建与配置》。开发日志由 `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. 后续按用户要求将运行文件统一迁入根目录 `config/`；`backend/config/` 只保留配置管理源码、同包测试和说明文件。迁移不改写分区引用、不清空数据库、不重新生成密钥。根目录 `ssl/` 是人工证书输入，用途尚未确认的空数据库也保留，不凭文件名删除。具体范围见《运行文件目录迁移说明》。

## 构建与启动

```powershell
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` 为项目根目录，读取根目录 `config/`，不在 `out/` 下创建新账号库。插件工作目录保持原有 `backend/` 不变，配置初始化不再依赖工作目录。编译前应停止正在运行的同名二进制，停止前核对进程号和路径。正式部署仍需使用发行入口 `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 正式安装；未重新执行清库初始化流程，避免破坏用户现有账号与配置。