| # CLAUDE.md |
|
|
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
|
|
| ## 项目概览 |
|
|
| 这个仓库是一个基于 Python 3.10+ 与 FastAPI 的 Web 应用，用于通过 Web UI 和带鉴权的外部 API 管理注册任务流程。默认使用 SQLite 持久化运行时状态，也支持 PostgreSQL。 |
|
|
| 当前分支是一个持续维护的修复版，重点是让注册、登录、获取 token 这些链路继续适配近期上游行为变化，包括 Sentinel POW 处理，以及“先注册、再单独登录拿 token”的拆分流程。 |
|
|
| ## 常用命令 |
|
|
| ### 安装依赖 |
|
|
| ```bash |
| uv sync |
| ``` |
|
|
| 备用方式： |
|
|
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| 如果使用项目元数据方式安装测试依赖： |
|
|
| ```bash |
| pip install -e .[dev] |
| ``` |
|
|
| ### 本地运行 |
|
|
| 默认启动 Web UI： |
|
|
| ```bash |
| python webui.py |
| ``` |
|
|
| 指定监听地址和端口： |
|
|
| ```bash |
| python webui.py --host 0.0.0.0 --port 8080 |
| ``` |
|
|
| 调试模式（同时启用文档路由）： |
|
|
| ```bash |
| python webui.py --debug |
| ``` |
|
|
| 也可以使用 `pyproject.toml` 中定义的入口： |
|
|
| ```bash |
| codex-console |
| ``` |
|
|
| ### 数据库初始化 / 维护 |
|
|
| 初始化数据库与默认设置： |
|
|
| ```bash |
| python -m src.database.init_db |
| ``` |
|
|
| 检查数据库连接： |
|
|
| ```bash |
| python -m src.database.init_db --check |
| ``` |
|
|
| 重置数据库（破坏性操作）： |
|
|
| ```bash |
| python -m src.database.init_db --reset |
| ``` |
|
|
| ### 测试 |
|
|
| 运行全部测试： |
|
|
| ```bash |
| pytest |
| ``` |
|
|
| 运行单个测试文件： |
|
|
| ```bash |
| pytest tests/test_registration_engine.py |
| ``` |
|
|
| 运行单个测试函数： |
|
|
| ```bash |
| pytest tests/test_registration_engine.py::test_name |
| ``` |
|
|
| ### 打包 |
|
|
| Windows： |
|
|
| ```bash |
| build.bat |
| ``` |
|
|
| Linux/macOS： |
|
|
| ```bash |
| bash build.sh |
| ``` |
|
|
| ### Docker |
|
|
| ```bash |
| docker-compose up -d |
| ``` |
|
|
| ## 配置模型 |
|
|
| - 运行时配置主要通过 `src/config/settings.py` 存在数据库中，而不是静态配置文件。 |
| - `webui.py` 启动时仍会读取 `.env` 和命令行参数，然后把生效值写回数据库配置，再启动应用。 |
| - 从 README 和启动逻辑看，优先级是：命令行参数 > 环境变量 /.env > 数据库设置 > 代码默认值。 |
| - 本地默认数据库是 `data/database.db` 下的 SQLite；PostgreSQL 连接串会在 `src/database/session.py` 中做标准化处理。 |
|
|
| ## 高层架构 |
|
|
| ### 入口层 |
|
|
| - `webui.py` 是主进程入口，负责准备 `data/` 与 `logs/`、初始化数据库、重载设置、配置日志并启动 Uvicorn。 |
| - `src/web/app.py` 负责创建 FastAPI 应用、挂载静态资源和模板、注册 API 与 WebSocket 路由，并处理基于 Cookie 的简易 Web UI 登录。 |
|
|
| ### Web 层 |
|
|
| - `src/web/routes/__init__.py` 统一组装 API： |
| - `/api/registration`：单任务和批量注册 |
| - `/api/accounts`、`/api/email-services`、`/api/settings`、`/api/payment` |
| - `/api/upload/*`：CPA / Sub2API / Team Manager 上传集成 |
| - `/api/external/*`：给第三方系统调用的外部批次接口 |
| - `src/web/routes/external/registration.py` 提供外部批次 API，鉴权由 `src/web/deps/external_auth.py` 中的 `X-API-Key` 逻辑控制。 |
| - `src/web/routes/websocket.py` 与 `src/web/task_manager.py` 负责向 Web UI 实时推送任务日志和状态。 |
|
|
| ### 注册主流程 |
|
|
| - `src/web/routes/registration.py` 是用户触发注册任务的编排层，负责邮箱服务选择、代理来源解析、任务记录，以及注册后的可选上传动作。 |
| - `src/core/register.py` 中的 `RegistrationEngine` 是核心流程引擎，负责邮箱创建、OAuth / session 初始化、Sentinel 处理、注册/登录推进、token 获取和日志/result 汇总。 |
| - `src/core/openai/` 放的是与协议细节强相关的模块，例如 OAuth、浏览器/设备指纹、Sentinel POW、支付相关逻辑、token 刷新。 |
| - `src/core/http_client.py` 统一封装注册流程所需的 HTTP 会话行为。 |
|
|
| ### 邮箱服务模型 |
|
|
| - `src/services/base.py` 定义了所有邮箱服务都要实现的抽象接口。 |
| - 具体实现位于 `src/services/`。 |
| - Outlook 相关逻辑明显更复杂，集中在 `src/services/outlook/`，里面包括 provider 实现、token 管理、邮件解析和健康检查。 |
| - 批量任务中的服务选择逻辑位于 `src/core/service_selection.py`。其中 Outlook 有专门限制，避免同一个已配置邮箱在多条批次任务里被静默复用。 |
|
|
| ### 外部批次 API |
|
|
| - 外部 API 不是另一套独立实现，而是对现有注册能力的封装。 |
| - `src/core/external_batches/service.py` 会先持久化批次、预先计算邮箱/上传目标分配、为每个 item 创建一个 `RegistrationTask`，然后复用常规注册路由里的 `run_registration_task` 来执行。 |
| - 批次状态通过 `ExternalRegistrationBatch` 和 `ExternalRegistrationBatchItem` 持久化，服务重启后的恢复入口挂在 `src/web/app.py` 的 startup 逻辑里。 |
| - 第三方接入说明文档在 `docs/temp-mail-external-api.md`、`docs/external-api-examples.md`、`docs/external-api-quickstart.md`。 |
|
|
| ### 持久化层 |
|
|
| - ORM 模型定义在 `src/database/models.py`。 |
| - 本地核心实体主要包括 `Account`、`RegistrationTask`、`EmailService`、`Setting`、`Proxy` 以及各类上传目标配置表。 |
| - 外部 API 批次状态使用 `ExternalRegistrationBatch` 与 `ExternalRegistrationBatchItem` 两层结构。 |
| - `src/database/crud.py` 承担大部分业务 CRUD；`src/database/external_batch_crud.py` 处理批次相关持久化。 |
| - `src/database/session.py` 负责 engine / session 生命周期，也会在启动时执行轻量级 SQLite 自动迁移。 |
|
|
| ### 上传集成 |
|
|
| - `src/core/registration_upload.py` 是注册完成后的上传分发入口。 |
| - 不同上传渠道的实现位于 `src/core/upload/`。 |
| - 上传目标选择和邮箱分配逻辑都收敛在 `src/core/service_selection.py`。 |
|
|
| ## 这个仓库里特别重要的开发说明 |
|
|
| - `tests/` 下有比较完整的 pytest 测试，适合验证路由行为、任务/WebSocket 状态推送、服务选择逻辑和注册辅助函数。 |
| - 仓库根目录里没有发现专门的 lint/format/type-check 配置（如 `ruff`、`flake8`、`black`、`mypy` 等），不要默认认为存在固定的格式化或静态检查命令，除非后续显式加入。 |
| - `tests/conftest.py` 在 Windows 下 monkeypatch 了 `socket.socketpair`，这是为了让测试在该平台正常运行。 |
| - 打包使用的是 `codex_register.spec` + PyInstaller；`webui.py` 和 `src/web/app.py` 都对冻结环境（`sys.frozen` / `sys._MEIPASS`）做了特殊处理，修改资源路径逻辑时要特别小心。 |
|
|
