数据流转文档¶

更新日期：2026-01-21

一、完整数据流程¶

阶段 1：导入销售计划¶

项目	内容
输入	Excel 文件（销售计划.xlsx）
处理	解析 Excel → 生成 unique_key → 去重 → 写入
输出	SalePlan 记录

阶段 2：生成合格证批次¶

项目	内容
输入	选中的 SalePlan 记录（按缓急排序）
处理	计算剩余数量 → 按批次分割（≤50台）→ 生成编号范围
输出	Certificate 记录（一条记录代表一个批次）

阶段 3：打印合格证¶

项目	内容
输入	选中的 Certificate 记录
处理	展开编号范围 → 每台生成 PrintLog → 调用打印机
输出	PrintLog 记录（一台一条）

阶段 4：同步到 Access（可选）¶

项目	内容
输入	PrintLog 记录
处理	连接 Access → 写入 SignTb 表
输出	Access 中的刻印记录

二、状态流转¶

Certificate 状态机¶

┌──────────┐    打印    ┌──────────┐    刻印    ┌──────────┐
│  待打印   │ ────────→ │  已打印   │ ────────→ │  已刻章   │
└──────────┘           └──────────┘           └──────────┘

PrintLog 状态机¶

┌──────────┐    打印    ┌──────────┐
│  pending │ ────────→ │  success │
└──────────┘           └──────────┘
      │                       ↑
      ↓ 打印失败               │ 重试
┌──────────┐    重试3次   ┌──────────┐
│  failed  │ ──────────→ │  retried │
└──────────┘             └──────────┘

三、编号生成规则¶

产品编号范围格式¶

V + YYYYMM + START + SUFFIX + "---" + END + SUFFIX

示例：V202606121XL---140XL

部分	示例	说明
前缀	V	固定为 V
年月	202606	4位或6位年月
起始序号	121	起始流水号
后缀	XL	可选后缀
分隔符	---	三横线
结束序号	140	结束流水号

序号补零规则¶

序号范围	格式	示例
< 1000	3位补零	001 → 999
≥ 1000	4位原样	1000 → 1000

四、关键接口¶

CertificateBatchService¶

class CertificateBatchService:
    """合格证批次生成服务"""

    def generate_batch_by_urgency(
        self,
        sale_plan_ids: List[int],
        max_batch_size: int = 50
    ) -> List[Certificate]:
        """
        根据缓急生成合格证批次

        Args:
            sale_plan_ids: 销售计划ID列表（已按缓急排序）
            max_batch_size: 单个批次最大数量

        Returns:
            生成的 Certificate 记录列表
        """
        pass

    def _get_next_seq_range(self, size: int) -> Tuple[int, int]:
        """获取下一个可用的序号范围"""
        pass

CertificatePrintService¶

class CertificatePrintService:
    """合格证打印服务"""

    def print_certificate_batch(
        self,
        certificate_id: int,
        printer_name: str = None
    ) -> List[PrintLog]:
        """
        打印批次合格证，生成 PrintLog

        Args:
            certificate_id: 合格证批次ID
            printer_name: 打印机名称

        Returns:
            生成的 PrintLog 记录列表（每台一条）
        """
        pass

    def _sync_to_access(self, print_logs: List[PrintLog]) -> None:
        """同步到 Access 铭牌刻印系统"""
        pass

AutoNumberService¶

class AutoNumberService:
    """自动编号服务"""

    def generate_numbers(self, session: Session, sale_plan_ids: List[int]) -> int:
        """为销售计划批量生成产品编号"""
        pass

五、错误处理¶

场景	处理方式
打印机缺纸	弹窗提示，等待用户补充纸张
打印机离线	弹窗提示，检查连接
打印失败	自动重试最多3次，间隔2秒
Access 连接失败	记录日志，不阻塞打印流程
数据库写入失败	事务回滚，记录错误日志

六、变更历史¶

版本	日期	变更内容
v7	2026-01-21	初始版本，定义四阶段数据流程