# CLAUDE.md

## What This Repo Does

自动选优 Cloudflare 优选域名/IP，写入运行时文件供 Sub-Store 等下游消费。

两种独立运行模式：

| 模式 | 数据源 | 配置 | 输出目录 | Git 自动化 |
|------|--------|------|----------|-----------|
| Server | 远程 API | `config.server.json` | `runtime/` | `runtime-state` 分支 |
| Router (Python) | 本地 `cfst` | `config.local.json` | `cfip_runtime/` | 无 |
| Router (BusyBox) | 本地 `cfst` | `config_router.conf` | 由配置决定 | 无 |

## File Map

```
scripts/
├── domain_updater.py          # 顶层外观门面（Facade，100% 向后兼容 CLI 与 API）
├── rotator/                   # 核心领域高内聚模块子包
│   ├── config.py              # 配置校验、路径解析与输出设定
│   ├── filter.py              # 域名清洗、正则匹配与黑名单过滤
│   ├── sources.py             # 远程 API 与本地 cfst 数据源适配
│   ├── scoring.py             # 评分排名、平局决胜、迟滞防抖与候选构建
│   ├── storage.py             # 原子落盘写入与状态读写
│   ├── notify.py              # 通知命令执行与超时防护
│   └── main.py                # 主轮换工作流编排与 CLI 参数解析
├── run_update_and_commit.sh   # Server 模式调度器 + Git 自动提交与滚动修剪（模式 A）
├── router_local_update.sh     # BusyBox 路由器：运行 cfst 并写输出
├── router_local_http.sh       # BusyBox 路由器：httpd 提供运行时文件
├── install_debian.sh          # systemd timer/service 安装
└── uninstall_debian.sh        # systemd 卸载

substore/
└── operator_template.js       # Sub-Store 脚本操作符，消费运行时 JSON

tests/
├── test_domain_updater.py     # Python 核心选优、极性、回退、配置校验及 Facade 完整性
├── test_shell_lifecycle.py    # Shell 部署、发布安全、凭证保护及 Git 历史滚动修剪
├── test_router_scripts.py     # 路由器 BusyBox 脚本文件原子性、测速过滤及 SSOT 打包同步
└── test_substore_operator.py  # Sub-Store 算子类型安全与时效降级

build_router_package.sh        # 打包路由器部署 tarball → vmess.tar.gz（支持 --sync-from-config）
config.server.json             # Server 模式完整配置
config.local.json              # Python 本地 cfst 模式配置
config_router.conf             # BusyBox shell 模式配置
```

## Common Commands

### 语法校验

```bash
env PYTHONPYCACHEPREFIX=/tmp/pycache python3 -m py_compile scripts/domain_updater.py
bash -n scripts/run_update_and_commit.sh
bash -n scripts/install_debian.sh
bash -n scripts/uninstall_debian.sh
sh -n scripts/router_local_update.sh
sh -n scripts/router_local_http.sh
```

### 自动化测试

```bash
# 运行全套测试（覆盖 Python 核心、Shell 部署、路由器脚本及 Sub-Store 算子）
python3 -m unittest discover tests -v
```

### 运行

```bash
# Server 模式单次运行
python3 scripts/domain_updater.py --config config.server.json

# 本地 cfst 模式单次运行
python3 scripts/domain_updater.py --config config.local.json

# 查看解析后的输出路径（不执行更新）
python3 scripts/domain_updater.py --config config.server.json --print-output-settings

# Server 调度器入口
bash scripts/run_update_and_commit.sh config.server.json

# 强制提交
bash scripts/run_update_and_commit.sh --force-commit config.server.json

# BusyBox 路由器
sh scripts/router_local_update.sh ./config_router.conf
sh scripts/router_local_http.sh ./config_router.conf

# 打包路由器部署包（默认打包现有 config_router.conf）
./build_router_package.sh

# 打包路由器部署包（SSOT 单源模式：自动从 config.local.json 投影同步测速与输出参数）
./build_router_package.sh --sync-from-config config.local.json
```

### systemd 安装/卸载

```bash
sudo bash scripts/install_debian.sh --config config.server.json
sudo bash scripts/uninstall_debian.sh
```

`install_debian.sh --help` 查看完整参数（peak/offpeak 间隔、时区等）。

## Testing

- **全套自动化回归测试**：运行 `python3 -m unittest discover tests -v`（覆盖 4 大模块 21 项用例，秒级执行，零第三方依赖）。
- **语法校验**：使用 `py_compile` 与 `bash -n` / `sh -n` 快速检查语法。
- **路径解析验证**：`python3 scripts/domain_updater.py --config config.server.json --print-output-settings`。
- **本地测试服务器端时，仅运行 `python3 scripts/domain_updater.py --config config.server.json` 进行输出验证，严禁直接运行 `run_update_and_commit.sh` 调度/Git 推送脚本。**

## Key Constraints

- `config.json` / `config.example.json` 已废弃，不要重新引入。
- 输出路径由配置驱动，不要硬编码 `runtime/current_domain.txt` 之类的路径。
- `runtime/` 和 `cfip_runtime/` 在 `main` 分支被 gitignore。
- 只有 Server 模式向 `runtime-state` 分支提交。
- `state.json` 用于 fallback（保存上次正常值），两种模式都依赖它。
- `substore_vars.json` 是给下游消费者的轻量契约，不要把完整运行时数据塞进去。
- BusyBox shell 脚本需兼容 POSIX sh，不能用 bash 特性。
- `router_local_http.sh` 使用配置中的 BusyBox 二进制的 httpd applet，不使用系统 httpd。
- SubStore 脚本的 `$arguments.domain` 参数为最高优先级覆盖，`$arguments.domain_override` 控制开关，不受任何模式和策略影响。

## Where to Look

- 想了解架构终审与缺陷复现清单 → `ARCHITECTURE_REVIEW_UNIFIED.md`
- 想了解自动化测试用例 → `tests/`
- 想了解配置字段含义 → 直接读对应的 config JSON/conf 文件，字段名即文档
- 想了解评分/筛选逻辑 → `scripts/domain_updater.py`
- 想了解 git 提交/推送流程 → `scripts/run_update_and_commit.sh`
- 想了解 systemd 部署细节 → `scripts/install_debian.sh`
- 想了解下游消费方式 → `substore/operator_template.js`
- 想了解完整工作流图 → `workflow.md`（Mermaid 流程图）
- 想了解用户文档 → `README.md`