# 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`。

## 编码风格与命名规范

使用 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 以及云防火墙和系统防火墙规则。