================================================================================
diggermail v1.0.0 — 安装与自检
================================================================================

这是 GoldDigger 的邮件营销工具（diggermail）。名单、模板、发送记录、统计全部
留在你自己的机器上；发送通道是你自己的 MTA 或你自己付费的邮件服务商。

我们只提供工具与实施：不售 token、不代理挖客、不代发信、不转售发送额度。

--------------------------------------------------------------------------------
0. 先读这一段：验收口径
--------------------------------------------------------------------------------
「多租户」在这里 = 单实例多域名多通道：
一个实例管多个发信域名，每个域名 = 一份 provider 事实 + 一套凭据文件 +
一条发送通道（SPF include / DKIM selector / 发件人 / 凭据 / 预热桶按域名独立）。

它不是 SaaS 级的租户隔离 —— 没有按租户分区的鉴权、数据隔离或计费。
同一个实例里的所有域名共用同一个 API Key、同一个 SQLite、同一个运维边界。
请按「单实例多域名多通道」验收，不要按 SaaS 预期验收。

--------------------------------------------------------------------------------
1. 依赖
--------------------------------------------------------------------------------
* Python 3.9 或更高（本包在 3.11 上开发与验证）
* **零第三方依赖**：只用标准库（sqlite3 / http.server / smtplib / socket DNS 客户端）
* 一个可写的数据目录（默认 /var/lib/diggermail，可用 --data-dir 或
  DIGGERMAIL_DATA_DIR 改）
* 发送通道二选一：客户自己的 MTA（标准 SMTP），或客户自选的邮件服务商 API
  （工具不捆绑任何 MTA 发行版）

不需要 pip install，不需要联网装包。

--------------------------------------------------------------------------------
2. 解压
--------------------------------------------------------------------------------
    unzip diggermail-v1.0.0.zip
    cd diggermail          # 解压出来的目录名以压缩包内结构为准

包内结构：
    app/            主程序（12 个模块 + upgrade/ 自升级引擎）
    scripts/        dm_deliverability.py —— 可独立跑的 DNS 校验入口
    docs/           dns-records.md —— 发信域 DNS 配置（客户版）
    tests/          111 个用例，可本地复跑
    README.md       完整说明
    INSTALL.txt     本文件

--------------------------------------------------------------------------------
3. 自检（30 秒，确认这份包在你机器上真的能跑）
--------------------------------------------------------------------------------
    cd <解压出来的目录>
    python3 -m app.cli --help          # 命令行入口能起来
    python3 -m app.cli doctor          # 自检：数据库/Key/通道/域名状态
    python3 -m app.cli demo --mock     # 走一遍 联系人→名单→campaign→发送
    python3 -m unittest discover -s tests -t .   # 全量测试（110 passed, 1 skipped）

doctor 的退出码回答一个问题：「这个实例能不能开 API？」
（数据库正常且至少有一个 API Key → 0）。通道没配、域名没写 selector 这类缺项
会列在输出里的 "problems" 里，不影响退出码。

--------------------------------------------------------------------------------
4. 第一次配置
--------------------------------------------------------------------------------
4.1 数据目录与 API Key
    export DIGGERMAIL_DATA_DIR=/var/lib/diggermail   # 可选，默认就是这个
    python3 -m app.cli doctor 2>/dev/null || python3 -m app.cli keygen
    # keygen 会打印一次原始 Key（只显示一次，库里只存哈希）

4.2 登记发送通道（密钥只走环境变量，不进命令行、不进数据库）
    # 用你自己的 MTA
    export MY_SMTP_PASSWORD=...
    python3 -m app.cli sender add --domain mail.example.com --type smtp \
        --host smtp.your-provider.net --port 587 --starttls \
        --username your-account --password-env MY_SMTP_PASSWORD \
        --from-email sales@mail.example.com

    # 或用你自己付费的邮件服务商 API
    export MY_RELAY_KEY=...
    python3 -m app.cli sender add --domain mail.example.com --type relay \
        --base-url https://your-provider.example/api \
        --api-key-env MY_RELAY_KEY --from-email sales@mail.example.com

    凭据落在 <数据目录>/credentials/sender-<id>.json（0600，仅本人可读）；
    数据库里只留一条引用，不存密钥。

4.3 写下这个域名自己的 provider 事实
    python3 -m app.cli domain set --domain mail.example.com \
        --provider <你的邮件服务商> \
        --spf-include include:<服务商给你的 include> \
        --dkim-selector <服务商给你的 selector> \
        --from-email sales@mail.example.com

    selector 是服务商给的随机后缀（形如 qcloudhk2048），务必照抄。

4.4 用这个域名自己的配置现场核 DNS
    python3 -m app.cli domain check --domain mail.example.com

    退出码：0 全过 / 1 有记录没过（改 DNS）/ 2 查不到（查网络，不是记录问题）

    详细的记录怎么填，见 docs/dns-records.md。

--------------------------------------------------------------------------------
5. 跑起来
--------------------------------------------------------------------------------
    python3 -m app.cli serve          # 预留 API，默认 127.0.0.1:8742
    python3 -m app.cli verify          # 检查发送通道连不连得通

    API Key 用 Authorization: Bearer <key> 或 X-API-KEY: <key> 传入，
    scope 默认 mail。这套 Key 与云端 diggerkit 的 Key 互不通用。

--------------------------------------------------------------------------------
6. 一个实例管多个发信域名
--------------------------------------------------------------------------------
每个域名各登记一次 sender add + domain set，然后发信时指定域名：

    python3 -m app.cli demo --domain a.example --mock
    python3 -m app.cli demo --domain b.example --mock

各域名的通道、凭据、DNS 事实、预热桶互相独立。
预热按域名按日聚合（50 / 100 / 300 / 800 / 1500），调用方只能调低不能抬高。

--------------------------------------------------------------------------------
7. 干跑（--mock）不会发信
--------------------------------------------------------------------------------
短路点在通道选择层：即使该域名已登记自己的通道，mock 运行也不会去连真 MTA
或真中继 API。测试里有断言守着这条（mock 模式下对真实上游的调用数 == 0）。

--------------------------------------------------------------------------------
8. 升级
--------------------------------------------------------------------------------
app/upgrade/ 是与 diggermedia 共用同一引擎的独立副本（机器守卫逐字节比对）。
本包不含 MTA 发行版，也不替你改 DNS。

--------------------------------------------------------------------------------
9. 边界（务必一起读）
--------------------------------------------------------------------------------
* 只提供工具与实施 —— 不售 token、不代理挖客、不代发信、不转售发送额度。
* 发送通道是客户自己的；凭据只在客户机器上。
* DNS 校验器只读公开 DNS，不发信、不碰你的凭据。
* 开放/点击的 webhook 回收尚未实现 —— stats 里的 delivered/open/click/bounce
  目前靠调用方写入（统计口径与幂等键已就绪）。
* 网关频控是单进程内存计数（默认每 Key 每分钟 120 次，DIGGERMAIL_RATE_LIMIT 可调），
  重启即清零，不是分布式限流。
* 尚无 Vue 管理面板，命令行与预留 API 是当前的操作界面。
