编码规范¶

CertFlow-PySide6 的编码规范，基于 PEP 8 并扩展项目特定约定。

概述¶

基础规范: 遵循 PEP 8 代码风格
类型注解: 所有函数和方法必须使用类型注解
文档字符串: 使用自定义的中文文档字符串格式
Python版本: Python 3.10+

代码风格¶

缩进与行长度¶

# 使用4个空格缩进，不使用Tab
# 每行最多120个字符
# 长行使用括号进行隐式续行

result = some_function(
    arg1="very_long_value",
    arg2="another_long_value",
    arg3="third_long_value"
)

命名约定¶

类型	命名规则	示例
模块/包	小写 + 下划线	`sale_plan_service.py`
类	PascalCase	`SalePlanService`, `DataCleaner`
函数/方法	小写 + 下划线	`generate_certificate_number()`
私有方法	单下划线前缀	`_build_group_key()`
变量	小写 + 下划线	`sale_plan_id`, `certificate_no`
常量	大写 + 下划线	`SORT_KEYS`, `REQUIRED_FIELDS`
信号	小写 + 下划线 + `_requested`	`print_requested`, `generate_requested`

导入顺序¶

# 1. 标准库导入
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional

# 2. 第三方库导入
import pandas as pd
from loguru import logger
from PySide6.QtCore import Qt, Signal
from PySide6.QtWidgets import QWidget, QVBoxLayout
from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import Session

# 3. 本地模块导入
from certflow.config.settings import APP_NAME
from certflow.models.base import Base
from certflow.utils.database import DatabaseManager

文档字符串规范¶

模块文档字符串¶

"""模块简短描述

模块详细描述，说明功能和主要用途。
可以多行描述。

Examples:
    >>> from certflow.services import SalePlanService
    >>> service = SalePlanService(session)
    >>> result = service.get_all_sale_plans()
"""

类文档字符串¶

class SalePlanService:
    """类简短描述

    详细描述类的功能、职责和使用场景。

    Attributes:
        session: 数据库会话对象
        excel_handler: Excel文件处理器实例

    Examples:
        >>> service = SalePlanService(session)
        >>> service.import_from_excel("data.xlsx")
    """

方法文档字符串¶

def generate_certificate_number(
    self, sale_plan_id: int, rule_code: str = "certificate"
    ) -> str:
    """生成合格证编号

    根据销售计划ID和编号规则生成唯一的合格证编号。

    Args:
        sale_plan_id: 销售计划ID
        rule_code: 编号规则编码，默认为"certificate"

    Returns:
        str: 生成的合格证编号

    Raises:
        ValueError: 当销售计划不存在或规则未启用时抛出

    Examples:
        >>> service = AutoNumberService(session)
        >>> number = service.generate_certificate_number(100)
        >>> print(number)
        "CF-20241215-0001"
    """

文档字符串格式要点¶

使用三重双引号 """
使用中文编写，但避免使用中文标点符号(使用英文标点)
第一行简要描述，空一行后写详细描述
使用 Args:、Returns:、Raises:、Examples: 等标记
参数类型和返回值类型已在类型注解中声明，文档中可不重复

类型注解规范¶

基本类型¶

from typing import Any, Dict, List, Optional, Tuple, Union

def process_data(
    data: List[Dict[str, Any]], limit: int = 100
    ) -> Optional[Dict[str, Any]]:
    ...

使用现代类型语法(Python 3.10+)¶

# 推荐使用
def get_items(ids: list[int]) -> dict[str, Any]:
    ...

# 而不是
def get_items(ids: List[int]) -> Dict[str, Any]:
    ...

类型别名¶

# 复杂类型定义别名
Filters = Dict[str, Union[str, int, bool, None]]
ResultDict = Dict[str, Union[bool, str, int, List]]

def search(filters: Filters) -> ResultDict:
    ...

错误处理¶

异常捕获¶

try:
    result = self.session.query(SalePlan).filter_by(id=plan_id).first()
except SQLAlchemyError as e:
    logger.error(f"数据库查询失败: {e}")
    self.session.rollback()
    raise

日志记录¶

# 使用 loguru
from loguru import logger

logger.debug("调试信息")
logger.info("一般信息")
logger.warning("警告信息")
logger.error(f"错误信息: {e}")

Qt 信号与槽¶

信号定义¶

from PySide6.QtCore import QObject, Signal

class CertificateView(QWidget):
    # 信号命名使用小写 + 下划线 + _requested/_changed 后缀
    print_requested = Signal(list)      # 带参数
    data_changed = Signal()              # 无参数

槽函数命名¶

def on_print_clicked(self) -> None:
    """打印按钮点击槽函数"""
    ...

def on_filter_changed(self) -> None:
    """筛选条件变化槽函数"""
    ...

def _do_search(self) -> None:
    """内部槽函数使用下划线前缀"""
    ...

数据库模型规范¶

模型定义¶

from sqlalchemy import Column, Integer, String
from certflow.models.base import Base

class SalePlan(Base):
    """销售计划模型"""

    __tablename__ = "sale_plans"

    id = Column(Integer, primary_key=True, autoincrement=True)
    product_model = Column(String(200), nullable=False, comment="产品型号")

    def __repr__(self) -> str:
        return f"<SalePlan(id={self.id}, product={self.product_model})>"

字段注释¶

所有字段必须添加 comment 参数
关系字段需要说明关联关系

配置文件规范¶

YAML配置注释¶

# 应用配置
app:
  name: "CertFlow"           # 应用程序名称
  version: "2.0.0"           # 版本号
  debug: false               # 调试模式(生产环境设为false)

配置读取¶

# 使用 settings.py 中的常量
from certflow.config.settings import APP_NAME, SORT_KEYS

# 避免直接调用 _cfg()

视图开发规范¶

UI布局¶

def setup_ui(self) -> None:
    """设置界面 - 在构造函数中调用"""
    layout = QVBoxLayout(self)

    # 按功能分组创建区域
    self.setup_filter_section(layout)
    self.setup_result_table(layout)
    self.setup_button_bar(layout)

信号连接¶

def _connect_signals(self) -> None:
    """连接信号与槽 - 在setup_ui后调用"""
    self.search_btn.clicked.connect(self.on_search_clicked)
    self.table.itemSelectionChanged.connect(self.on_selection_changed)

提交前检查清单¶

[ ] 代码符合 PEP 8 规范
[ ] 所有函数有类型注解
[ ] 公共类和方法有文档字符串
[ ] 异常有适当的日志记录
[ ] 无硬编码的路径或配置值(使用 settings)
[ ] 数据库会话正确关闭
[ ] Qt对象正确设置父对象(避免内存泄漏)

待补充¶

单元测试规范
代码审查流程
Git提交消息格式
CI/CD配置规范