MailSend/AGENTS.md

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