# 开发者指南

## 1. 分层约定

依赖方向严格单向（由 `scripts/check_layer_purity.py` 门禁强制）：

```text
views/ → controllers/ → services/ → models/
widgets/ ↘            ↗
handlers/ → services/（handlers 可依赖 services）
actions/ 纯 Python，无 Qt 依赖（便于单测）
config/  配置模型，全层可用
utils/   工具函数，全层可用
```

**禁止**：下层（services/models）import 上层的 Qt 组件。`services/` 设计为无 Qt 依赖，可在 CLI/测试中直接调用。

## 2. 扩展点

### 2.1 新增 CLI 命令

1. 在 `src/certflow/cli/commands/` 新建 `xxx.py`
2. 用 `@click.command("xxx")` 装饰函数
3. 在 `src/certflow/cli/__init__.py` 注册到命令组
4. 通过 `base_command.get_cli_session()` 获取会话

### 2.2 新增 UI action

1. 在 `ui.yaml` 声明 `action: <name>`
2. 在 `actions/registry.py` 的 `register_many([...])` 加 `ActionSpec(name, method)`
3. 在目标 View 实现 `method`
4. 若 action 名带前缀（如 `set_status_xxx`），可复用通用前缀 action（`set_status`），无需单独注册

### 2.3 新增配置项

1. 在 `config/<domain>.yaml` 添加字段（支持 `${ENV_VAR}` 占位符）
2. 在 `config/models.py` 定义 pydantic 字段
3. 通过 `from certflow.config.settings import cfg` 访问
4. 若需本地覆盖，用 `paths.local.yaml` 模式

### 2.4 新增数据模型

1. 在 `src/certflow/models/` 新建 `xxx.py`，继承 `Base`（`models/base.py`）
2. 在 `models/__init__.py` 导出
3. `DatabaseManager.init_db(create_tables=True)` 自动建表

### 2.5 新增基础字典视图

参考现有 `*_manager_view.py`，继承 `views/bases/` 中的基类，绑定对应 Controller/Service/Model。

## 3. 测试

| 类型 | 标记 | 运行 |
|------|------|------|
| 单元（无 Qt） | `unit` | `uv run pytest tests/unit -m "not qt"` |
| Qt 测试 | `qt` | 需 `QT_QPA_PLATFORM=offscreen` |
| 集成 | `integration` | `uv run pytest -m integration` |
| 慢测试 | `slow` | `uv run pytest -m "not slow"` |

配置见 `pyproject.toml` 的 `[tool.pytest.ini_options]`：

- `testpaths = ["tests"]`
- 覆盖率：`--cov=src/certflow`
- 超时：300s

无头测试（CI 一致口径）：`start.sh --headless-test` 使用 `QT_QPA_PLATFORM=offscreen`。

## 4. 代码质量

| 工具 | 配置 | 说明 |
|------|------|------|
| ruff | `pyproject.toml:[tool.ruff]` | 行长度 100，忽略 E501/N803/N806 |
| pyright | `pyproject.toml:[tool.pyright]` | basic 模式，python 3.13 |
| mypy | `mypy.ini` | 类型检查 |
| pre-commit | `.pre-commit-config.yaml` | start.sh 阶段7.5 自动安装 |

复杂度豁免（C901）见 `pyproject.toml:193-213`，长期需收敛（见 [`08-todo.md`](./08-todo.md) T4-1）。

## 5. 构建打包

`scripts/builder/`：

- 入口：`src/certflow/main.py`
- 配置：`scripts/builder/build_config.yaml`
- 输出：`dist/CertFlow`
- 工具：PyInstaller（默认）/ Nuitka（备选）
- 依赖组：`pyproject.toml` 的 `build` 组

```bash
uv run python scripts/builder/build.py
```

## 6. 数据库四库模型

见 [`02-architecture.md`](./02-architecture.md) §6。开发者注意：

- 调试用 B 库（`database/debug/certflow-debug.db`）由 `start.sh` 自动从 C/D 重建
- 生产用 A 库（`database/certflow.db`）路径由配置驱动
- 不要手动编辑 C（私有基线）或 D（LFS 匿名基线）

## 7. action 注册表实现细节

`actions/registry.py`：

- `REGISTRY: dict[str, ActionSpec]` 单一信源
- `dispatch(view, action_name, item=None) -> bool`：解析 `REGISTRY[action].method` → `getattr(view, method)` → 调用
- 前缀通用处理：`set_status_xxx` → 回落到 `set_status` action
- 签名适配：声明 `item` / `action_name` 形参的方法自动注入对应值

## 8. 待办与进度

- 实现进度：[`07-progress.md`](./07-progress.md)
- 待办事项：[`08-todo.md`](./08-todo.md)