# 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 变化应与源码一起提交。

本项目发布涉及两个本地仓库。当前仓库 `/Users/chendeben/Documents/MailSend` 的 `origin` 指向 `git.ss5.xyz`，用于远程服务器拉取部署；GitHub 开源仓库对应独立本地目录 `/Users/chendeben/Documents/MailHub-public.OlOeo0`，不得在当前仓库直接添加 GitHub remote 后推送。

确认提交后，先推送部署远端：

```bash
git push origin master
```

同步 GitHub 时，进入开源仓库目录，将当前仓库的代码、测试、构建产物和安全配置同步过去，但保留开源仓库的英文公开文档，不同步运行期数据和内部工作流说明：

```bash
cd /Users/chendeben/Documents/MailHub-public.OlOeo0
rsync -a --delete \
  --exclude='.git/' \
  --exclude='node_modules/' \
  --exclude='.env' \
  --exclude='.env.*' \
  --exclude='data/' \
  --exclude='tmp/' \
  --exclude='.cache/' \
  --exclude='.superpowers/' \
  --exclude='.worktrees/' \
  --exclude='certs/' \
  --exclude='docs/superpowers/' \
  --exclude='AGENTS.md' \
  --exclude='README.md' \
  --exclude='CHANGELOG.md' \
  --exclude='CODE_OF_CONDUCT.md' \
  --exclude='CONTRIBUTING.md' \
  --exclude='SECURITY.md' \
  --exclude='SUPPORT.md' \
  /Users/chendeben/Documents/MailSend/ \
  /Users/chendeben/Documents/MailHub-public.OlOeo0/
npm run build
npm test
git diff --check
git status -sb
git add -A
git commit
git push origin main
```

开源仓库提交信息同样使用 Conventional Commits 风格。推送后可用 `git status -sb` 确认 `main` 与 `origin/main` 对齐；如需确认 GitHub，也可运行 `git ls-remote origin refs/heads/main` 对比本地 `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 以及云防火墙和系统防火墙规则。
