# Repository Guidelines

## 项目结构与模块组织

MailHub 是基于 Node.js ESM 的 Docker 化发信控制面板、SMTP Submission 服务和发送 API。服务端代码位于 `src/`：`server.js` 负责 HTTP 路由与运行配置，`db.js` 负责 SQLite 持久化，`mailer.js` 与 `submission.js` 处理发信链路，DKIM 与 DNS 能力拆分为独立模块。浏览器资源在 `public/`，测试在 `test/`，Docker 与 Postfix 相关文件在 `Dockerfile`、`docker-compose.yml` 和 `docker/postfix/`。运行期数据应保留在已忽略路径，如 `data/`、`.env` 和证书私钥文件。

## 构建、测试与开发命令

- `npm test`：使用 `node --test` 运行 Node 内置测试套件。
- `npm run dev`：以 `NODE_ENV=development` 启动 `src/server.js`。
- `npm start`：启动生产入口。
- `docker compose up -d --build`：构建并启动应用与 Postfix 服务。
- `docker compose logs -f app postfix`：部署或排障时跟踪服务日志。

Node.js 版本需满足 `package.json` 中的 `>=24.0.0`。

## 发布流程

发布前先确认工作区范围，避免把无关变更带上：`git status -sb`、`git log --oneline --decorate -5`。提交或部署前必须运行 `npm run build`、`npm test` 和 `git diff --check`；前端构建会更新 `public/` 下的静态资源，若 hash 变化应与源码一起提交。

本项目发布需要同步两个 Git 远端：`origin` 指向 `git.ss5.xyz`，用于远程服务器拉取部署；`github` 指向开源仓库，用于同步公开版本。若本地缺少 GitHub remote，先执行一次：

```bash
git remote add github git@github.com:chendeben/MailHub.git
```

确认提交后，先推送部署远端，再同步 GitHub：

```bash
git push origin master
git push github master
```

推送后可用 `git status -sb` 确认本地分支与 `origin/master` 对齐；如需确认 GitHub，也可运行 `git ls-remote github refs/heads/master` 对比本地 `git rev-parse HEAD`。

生产部署使用远程脚本：

```bash
MAILHUB_DEPLOY_REMOTE="root@192.227.215.183" MAILHUB_DEPLOY_DIR="/www/wwwroot/mail.ss5.xyz" npm run deploy:remote
```

部署脚本会让远程服务器从 `git.ss5.xyz` 拉取 `master` 并重建 Docker 服务。部署后需在远程目录检查代码版本、容器健康状态和登录页响应：

```bash
cd /www/wwwroot/mail.ss5.xyz
git rev-parse --short HEAD
docker compose ps
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3025/login
```

预期 `mailhub-app` 与 `mailhub-postfix` 均为 `healthy`，登录页返回 `200`。发布过程不得覆盖远程 `.env`、`data/`、证书私钥或其他运行期数据。

## 编码风格与命名规范

使用 ES modules，保持文件职责单一、实现直接。默认使用 `const`，仅在需要重新赋值时使用 `let`。遵循现有 JavaScript 风格：两空格缩进、保留分号、变量和函数使用描述性 camelCase，浏览器资源文件名使用 kebab-case。注释应简短且有价值，并与周围代码语言保持一致。

## 测试指南

测试使用 Node 内置 `node:test`。测试文件放在 `test/` 下，并使用 `*.test.js` 后缀，尽量对应被测模块，例如 `test/dkim.test.js`。修改数据库迁移、认证边界、DNS 服务商逻辑或邮件签名链路时，应补充相应覆盖。提交 PR 前运行 `npm test`。

## 提交与 Pull Request 规范

提交历史使用类似 Conventional Commits 的前缀，如 `feat:`、`fix:`、`docs:`、`test:`。提交标题应简洁、聚焦单一变更。PR 应包含变更摘要、验证步骤、关联 issue；涉及 UI 或 API 行为变化时，补充截图或请求示例。

## 安全与配置提示

不要提交 `.env`、SQLite 数据库、API Token、SMTP 密码或证书私钥。以 `.env.example` 为起点配置环境，替换默认管理员凭据，设置足够强的 `SESSION_SECRET`。生产发信前确认 SPF、DKIM、DMARC、PTR 以及云防火墙和系统防火墙规则。