File size: 6,564 Bytes
89419ea | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 | # 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`）做了特殊处理，修改资源路径逻辑时要特别小心。
|