# 运行文件目录迁移说明

## 需求确认

运行配置统一放在 `D:\Desktop\Smail\config`；`backend/config` 是 Go 配置管理源码包，不整体重命名或删除。运行日志继续放在 `test-log/runtime`，编译输出继续放在 `out`。

## 文件归属

```text
Smail/
├── config/                   # 忽略 Git 的本机运行文件
│   ├── config.json           # 当前启动使用的分区根配置
│   ├── smtp.json             # SMTP 分区
│   ├── email.json            # 邮箱策略分区
│   ├── ssl.json              # 证书引用分区
│   ├── plugins.json          # 插件配置分区
│   ├── config.dev.json       # 历史 dev 模式配置，不是当前启动配置
│   ├── config_mysql.json     # 保留的另一份配置，不自动启用
│   ├── config.json.legacy    # 历史配置原始备份
│   ├── smail_temp.db         # 当前账号及邮件数据库
│   ├── smail.db              # 另一份已有 SQLite 数据库，保留
│   ├── credential.key       # 凭据加密主密钥
│   ├── external-email-*.key  # 外部邮箱加密和指纹密钥
│   ├── dkim/                # DKIM 密钥及备份
│   ├── ssl/                 # TLS 证书、私钥及 ACME 资料
│   ├── migration-backups/   # 配置格式迁移备份
│   ├── backups-v2/          # 分区配置备份
│   └── transaction/         # 配置事务工作目录
└── backend/config/          # Go 源码、同包测试和原有说明文档
```

## 启动约定

- `deploy/start-dev.ps1` 设置 `SMAIL_ROOT=D:\Desktop\Smail`。程序使用 `SMAIL_ROOT/config` 读取和生成运行文件，不能把环境变量设置成 `config` 自身。
- 当前启动继续使用 `--dev-disable-admin-reset`，读取 `config/config.json`，不切换到 `config.dev.json` 或另一份数据库。
- 为保持已有插件安装路径，子进程工作目录仍是 `backend/`。初始化目录已改为基于 `SMAIL_ROOT`，不再向工作目录写入 `./config`。
- 直接运行编译程序或 `go run` 时也需要显式设置 `SMAIL_ROOT`。独立正式部署保留原有环境变量优先、可执行文件目录回退规则。
- 如果 `backend/config` 仍存在旧配置、主密钥或 SQLite 文件，开发启动脚本停止并提示先迁移，防止误初始化第二份账号库。

## 迁移和保护边界

1. 修改前提交中文检查点并推送，真实运行文件不进入 Git。
2. 停止并核实当前项目后端进程，前端保持运行。
3. 迁移前记录源码及运行文件清单和 SHA-256；运行文件另存一份本地回退副本到 `test-log/archive`。
4. 只迁移明确的运行文件，目标存在同名文件时拒绝覆盖；保留 Go 源码及说明文档，不删除旧空目录。
5. JSON、数据库、密钥及证书保持原始字节；分区配置的摘要和相对路径无需更改。
6. 迁移后逐一校验哈希，再启动后端并核对运行根目录、数据库及探活结果。
7. 根目录 `ssl/` 的人工输入证书、`backend/smail.db` 的原有空文件、历史测试配置不属于当前活动配置，不删除，也不冒充当前数据源。

本次是保留数据的目录迁移，不进行清库初始化。自动测试使用 `test-log` 下独立临时数据库；业务数据库仅做只读完整性和账号摘要校验。进程启动后的正常任务可能更新业务数据库，迁移字节校验应在重启前完成。

## 任务清单

- [✓] 核实运行文件、活动数据库与源码边界。
- [✓] 修改前检查点已提交并推送。
- [✓] 开发启动指向项目根目录，并拒绝旧目录残留运行文件；脚本语法、编码及路径约束测试通过。
- [✓] 初始化目录与工作目录解耦；异工作目录、重复初始化、文件保留和目录冲突回归通过。
- [✓] 停服备份并迁移 24 个运行文件，重启前逐一哈希一致；55 个源码及说明文件保持不变。
- [✓] 三个后端程序重新编译，前端 19 项自动测试、Go 全量测试及静态检查通过。
- [✓] 从新目录恢复后端，两份 SQLite 完整性及迁移前表记录数一致，账号记录在重启前后均未改变；前后端探活正常。
- [!] 符号链接拒绝测试在当前 Windows 普通账户下因缺少创建符号链接权限而跳过，未提升权限，也未据此宣称该分支实测通过。

## 本次验收记录

2026-09-05 本地迁移结果：

- 修改前检查点：`3c455186b70289238167a19432431ace74ee79e4`，已核对与远端 `smail/main` 一致；后续本轮代码改动保留在工作区。
- 停止的旧后端进程编号为 `23136`；新进程编号为 `45920`，可执行文件位于 `out/backend/smail-dev.exe`。进程编号仅代表验收当时状态。
- 新启动日志显示 `Env Root Path: D:\Desktop\Smail/`，当前配置仍是 `config/config.json`，数据库仍由 `localRef=smail_temp.db` 指定，分区代次保持 `1`。
- 两个 SQLite 文件各有 20 张表；保留库 `smail.db` 有 0 个账号，活动库 `smail_temp.db` 有 1 个账号。校验不输出账号、密码哈希或密钥内容。
- 重启后 23 个非活动数据库运行文件及 55 个源码说明文件哈希仍一致；活动数据库仅允许正常运行写入，账号完整记录与备份比较一致。
- `https://127.0.0.1/api/ping` 和 `http://127.0.0.1:15173/api/ping` 均返回 HTTP 200、`errorNo=0`、`pong`；前端页面返回 200。
- `https://127.0.0.1/config/credential.key` 返回 404，没有把新运行目录当作静态资源公开。自签名证书探活使用跳过本机证书信任验证参数，不代表公开 CA 信任验收。
- `node test/run.mjs all -- -count=1 -p 2 ./...` 通过；随后单独复跑 `TestDirInit`，三个用例通过、符号链接用例跳过。
- `go -C backend vet -p 2 ./...`、PowerShell 语法检查、`git diff --check` 和 Go 格式检查通过；启动脚本仍保留 Windows PowerShell 5 需要的 UTF-8 BOM。
- Git 忽略规则确认根目录配置、密钥、数据库、回退副本、日志和编译产物不会进入提交。

本地回退副本：`test-log/archive/runtime-config-20260905-202201/`。目录包含密钥和数据库，仅留在本机，不上传。

检查证据：

- `test-log/reports/runtime-config-migration-20260905-202201.json`：完整移动、哈希和源码保留清单。
- `test-log/reports/runtime-config-sqlite-before-start.json`：重启前数据库完整性、记录数及账号一致性。
- `test-log/reports/runtime-config-after-start.json`：重启后路径、运行文件与账号一致性。
- `test-log/reports/runtime-config-build-20260905.log`：本次后端及管理工具构建记录。
- `test-log/run-2026-09-05T12-20-49-905Z-23176/`：完整自动测试记录。
- `test-log/run-2026-09-05T12-24-16-351Z-24952/`：初始化目录专项回归记录。

真实邮件收发、浏览器全部流程和 Linux/Windows 正式安装不在本次迁移验收范围内，不能以探活成功代替这些验收。