CertFlow 开发总结文档

本文档记录了 CertFlow 项目的重要开发决策、配置方法和测试指南

目录

1. 文档系统配置

1.1 Sphinx 配置

项目使用 Sphinx 构建 API 文档，配置位于 docs/source/conf.py。

关键特性：

  • 支持 Markdown 文件（通过 myst_parser）

  • 模块模拟避免导入 GUI 库

  • 中文支持

  • 警告抑制配置

主要扩展：

extensions = [
    "sphinx.ext.autodoc",      # 自动生成文档
    "sphinx.ext.napoleon",     # 支持 Google 风格文档
    "sphinx.ext.viewcode",     # 添加源码链接
    "sphinx.ext.intersphinx",  # 链接到其他文档
    "myst_parser",             # Markdown 支持
]

1.2 文档构建脚本

使用 scripts/docs_helper.sh 管理文档构建：

# 构建文档
./scripts/docs_helper.sh build

# 实时预览（热重载）
./scripts/docs_helper.sh serve

# 清理生成文件
./scripts/docs_helper.sh clean

# 查看状态
./scripts/docs_helper.sh status

1.3 文档在线预览

# 启动本地服务器
cd docs/source/_build/html
python -m http.server 8000

# 访问 http://localhost:8000

2. 依赖管理

2.1 uv 依赖分组

项目使用 uv 的依赖组功能，实现依赖隔离：

[dependency-groups]
# 文档构建组（不污染主环境）
docs = [
    "sphinx>=7.0",
    "sphinx-rtd-theme>=2.0",
    "myst-parser>=3.0",
    "sphinx-autobuild>=2024.0",
    "sphinx-design>=0.5",
    "sphinx-copybutton>=0.5",
]

# 开发工具组
dev = [
    "pre-commit>=4.0.0",
    "pytest>=9.0.3",
    "pytest-cov>=7.1.0",
    "pyinstaller>=6.20.0",
]

2.2 环境切换

# 生产环境（仅主程序）
./scripts/setup_env.sh prod

# 开发环境（主程序 + 开发工具）
./scripts/setup_env.sh dev

# 文档构建环境
./scripts/setup_env.sh docs

# 完整环境
./scripts/setup_env.sh full

3. UI 配置驱动

3.1 配置文件

UI 配置已外部化为 config/ui.yaml，支持：

  • 主窗口尺寸和标题

  • 标题栏样式

  • 导航按钮配置

  • 页面布局配置

  • CSS 样式配置

3.2 UI 配置模块

src/certflow/config/ui_config.py 提供：

  • UIConfig 类：加载和解析配置

  • StyleBuilder 类：动态生成 CSS 样式

  • 配置热加载支持

3.3 常用文件记录

导入页面支持记录最近使用的文件：

# config/ui.yaml
import_page:
  recent_files:
    enabled: true
    max_count: 5
    auto_load_config: true
    auto_import: false

配置保存在 config/userconfig.yaml：

recent_import_files:
  - path: "D:/data/sales_plan.xlsx"
    name: "sales_plan.xlsx"
    last_used: "2026-05-30 15:30:00"
    config:
      sheet_name: 0
      header_row: 0
      data_start_row: 1
      column_mapping:
        产品型号: product_model
        订单号: order_no

4. 导入功能增强

4.1 重复统计

导入时会显示详细的重复统计：

✅ 导入完成！
📊 统计信息:
  总记录数: 618
  ✨ 新增记录: 580
  🔄 重复记录: 38
  📈 重复率: 6.1%

🔄 重复记录详情:
  1. JZH-00/φ1200*1.0 - ORD-2024-001
     原因: 已存在 (ID: 123)

4.2 去重策略

支持两种去重策略：

  • skip: 跳过重复记录

  • update: 更新已有记录

4.3 导入流程

选择文件 → 配置参数 → 保存配置 → 执行导入 → 显示结果
    ↓           ↓           ↓           ↓
  常用文件    列映射      历史记录    重复统计
  记录

5. 测试指南

5.1 运行测试

# 运行所有测试
uv run pytest tests/ -v

# 运行配置测试
uv run pytest tests/test_config.py -v

# 运行特定测试
# uv run pytest tests/test_excel_handler.py::
# TestExcelHandler::test_read_excel_basic -v
uv run pytest -k "TestExcelHandler and test_read_excel_basic" -v

# 带覆盖率
uv run pytest tests/ --cov=src/certflow --cov-report=term

# 生成 HTML 覆盖率报告
uv run pytest tests/ --cov=src/certflow --cov-report=html
start htmlcov/index.html

5.2 测试结果

当前测试状态（64 个测试全部通过）：

测试文件

数量

状态

test_config.py

41

✅

test_controller.py

1

✅

test_excel_handler.py

10

✅

test_import_dialog.py

5

✅

test_sale_plan_service.py

7

✅

5.3 测试 Fixtures

tests/conftest.py 提供：

@pytest.fixture
def sample_excel_file():
    """示例 Excel 文件"""

@pytest.fixture
def temp_db():
    """临时数据库"""

@pytest.fixture
def sample_sale_plan_record():
    """示例销售计划记录"""

5.4 覆盖率报告

当前总体覆盖率：51%

高覆盖率模块：

  • config/__init__.py: 100%

  • models/__init__.py: 100%

  • utils/logger.py: 90%

  • config/models.py: 99%

需要改进的模块：

  • main.py: 0%（GUI 启动逻辑）

  • views/report_view.py: 15%

  • services/report_service.py: 20%

  • controllers/*: 25-30%

5.5 测试命令速查

# 基础命令
uv run pytest                    # 运行所有测试
uv run pytest -v                 # 详细输出
uv run pytest -x                 # 首次失败停止
uv run pytest -k "test_name"     # 按名称匹配

# 覆盖率
uv run pytest --cov=src/certflow --cov-report=term-missing

# 调试
uv run pytest --pdb              # 失败时进入调试器
uv run pytest --tb=short         # 简短错误信息

6. 常见问题

6.1 文档构建警告

问题: 出现 duplicate object description 警告

解决: 已在 conf.py 中配置警告抑制：

suppress_warnings = [
    "ref.python.duplicate",
    "autodoc.duplicate",
    "toc.not_readable",
]

6.2 Windows 文件锁问题

问题: 测试时临时文件无法删除

解决: 在 fixture 中添加重试机制：

for _ in range(3):
    try:
        if file_path.exists():
            file_path.unlink()
        break
    except PermissionError:
        time.sleep(0.5)

6.3 Markdown 文件找不到

问题: Sphinx 找不到 .md 文件

解决: 在 docs/source/ 下创建软链接：

cd docs/source
ln -sf ../INSTALLATION.md .
ln -sf ../USER_GUIDE.md .

6.4 依赖安装问题

问题: 文档工具污染主环境

解决: 使用依赖组隔离：

# 只安装文档依赖
uv sync --group docs

# 使用文档组运行
uv run --group docs sphinx-build --version

附录

A. 项目结构

CertFlow-PySide6/
├── config/                 # 配置文件
│   ├── ui.yaml            # UI 配置
│   └── userconfig.yaml    # 用户配置
├── docs/                   # 文档
│   ├── source/            # Sphinx 源文件
│   └── deployment/        # 部署文档
├── scripts/               # 工具脚本
│   ├── docs_helper.sh     # 文档构建
│   └── setup_env.sh       # 环境切换
├── src/certflow/          # 源代码
│   ├── config/            # 配置模块
│   ├── controllers/       # 控制器
│   ├── handlers/          # 处理器
│   ├── models/            # 数据模型
│   ├── services/          # 业务服务
│   ├── utils/             # 工具函数
│   └── views/             # UI 视图
└── tests/                 # 测试
    ├── conftest.py        # pytest 配置
    ├── test_config.py     # 配置测试
    └── ...

B. 常用命令速查

操作

命令

构建文档

./scripts/docs_helper.sh build

预览文档

./scripts/docs_helper.sh serve

运行测试

uv run pytest tests/ -v

覆盖率报告

uv run pytest --cov=src/certflow --cov-report=html

切换开发环境

./scripts/setup_env.sh dev

切换文档环境

./scripts/setup_env.sh docs

C. 待开发功能

  • [ ] 销售计划查询界面（多条件级联查询）

  • [ ] 按销售订单号、生产令号、计划日期等筛选

  • [ ] 自制/外购渠道筛选

  • [ ] 是否发货/生产完毕状态筛选

  • [ ] 数据导出功能

  • [ ] 报表生成功能

最后更新: 2026-05-30