开发者指南

1. 分层约定

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

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 T4-1）。

5. 构建打包

scripts/builder/：

  • 入口：src/certflow/main.py

  • 配置：scripts/builder/build_config.yaml

  • 输出：dist/CertFlow

  • 工具：PyInstaller（默认）/ Nuitka（备选）

  • 依赖组：pyproject.toml 的 build 组

uv run python scripts/builder/build.py

6. 数据库四库模型

见 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. 待办与进度