LabelChange-server/.trae/specs/dashboard_refactor/spec.md

数据看板查询逻辑重构 - 产品需求文档

Overview

• Summary: 重构 batch_query.html 中的数据看板查询逻辑，从到货交接单的数据开始，以到货交接单的交接单号去匹配提单号和主包号，从而统计到货情况
• Purpose: 优化数据看板的查询逻辑，使其更加准确地反映到货情况
• Target Users: 物流操作人员、数据分析师

Goals

• 从到货交接单的数据开始，以交接单号匹配提单号和主包号
• 保持现有的两个模块：提单号预报和大箱号预报
• 确保统计数据的准确性
• 优化查询性能

Non-Goals (Out of Scope)

• 不修改现有的UI结构
• 不修改其他模块的功能
• 不涉及数据库结构变更

Background & Context

当前数据看板的查询逻辑是从标签替换请求表开始，直接按提单号或大箱号分组统计。这种方式可能会导致统计结果不准确，因为它没有考虑到到货交接单的实际情况。

Functional Requirements

• FR-1: 保持现有的两个模块结构（提单号预报和大箱号预报）
• FR-2: 修改查询逻辑，从到货交接单的数据开始
• FR-3: 以到货交接单的交接单号去匹配提单号和主包号
• FR-4: 统计到货订单数量、无标签数据数量、已有标签率等指标
• FR-5: 支持按客户ID、日期范围等条件过滤

Non-Functional Requirements

• NFR-1: 性能优化，避免全表扫描
• NFR-2: 代码可读性和可维护性
• NFR-3: 数据准确性

Constraints

• Technical: 使用现有的API架构
• Business: 无特殊业务约束
• Dependencies: 依赖 arrival_handover_forms 表和 label_replace_requests 表

Assumptions

• 数据库表结构已正确创建
• 所有必要的索引已添加
• 数据量在合理范围内

Acceptance Criteria

AC-1: 基本查询功能

• Given: 存在到货交接单记录
• When: 执行提单号预报查询
• Then: 从到货交接单开始，以交接单号匹配提单号统计
• Verification: programmatic

AC-2: 大箱号查询功能

• Given: 存在到货交接单记录
• When: 执行大箱号预报查询
• Then: 从到货交接单开始，以交接单号匹配主包号统计
• Verification: programmatic

AC-3: 数据准确性

• Given: 存在测试数据
• When: 执行查询并与手动计算结果比较
• Then: 统计数据与手动计算一致
• Verification: human-judgment

AC-4: 性能优化

• Given: 数据量较大（如10万条记录）
• When: 执行查询
• Then: 查询响应时间在可接受范围内（<5秒）
• Verification: programmatic

Open Questions

• 如何处理一个到货交接单对应多个提单号或主包号的情况？
• 是否需要修改后端API，还是只需要修改前端逻辑？