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”的拆分流程。
常用命令
安装依赖
uv sync
备用方式：
pip install -r requirements.txt
如果使用项目元数据方式安装测试依赖：
pip install -e .[dev]
本地运行
默认启动 Web UI：
python webui.py
指定监听地址和端口：
python webui.py --host 0.0.0.0 --port 8080
调试模式（同时启用文档路由）：
python webui.py --debug
也可以使用 pyproject.toml 中定义的入口：
codex-console
数据库初始化 / 维护
初始化数据库与默认设置：
python -m src.database.init_db
检查数据库连接：
python -m src.database.init_db --check
重置数据库（破坏性操作）：
python -m src.database.init_db --reset
测试
运行全部测试：
pytest
运行单个测试文件：
pytest tests/test_registration_engine.py
运行单个测试函数：
pytest tests/test_registration_engine.py::test_name
打包
Windows：
build.bat
Linux/macOS：
bash build.sh
Docker
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）做了特殊处理，修改资源路径逻辑时要特别小心。