上传源代码版本

.trae/specs/dashboard_query_sql/spec.md

@@ -0,0 +1,67 @@
+# 数据看板查询逻辑分析 - MySQL语句分析
+
+## Overview
+- **Summary**: 分析数据看板查询的MySQL语句实现，包括标签替换请求的获取、过滤、分组和统计逻辑
+- **Purpose**: 帮助排查数据看板查询逻辑的问题，提供MySQL语句的等价实现
+- **Target Users**: 开发人员、数据库管理员
+
+## Goals
+- 分析数据看板查询的完整流程
+- 提供MySQL等价语句
+- 识别潜在的性能问题
+- 提供优化建议
+
+## Non-Goals (Out of Scope)
+- 不修改现有代码
+- 不涉及前端实现细节
+- 不处理权限和安全问题
+
+## Background & Context
+数据看板通过 `DashboardController.GetDashboardData` 接口获取数据，该接口调用 `LabelReplaceService.GetDashboardDataAsync` 方法。当前实现使用内存过滤和分组，可能在数据量较大时存在性能问题。
+
+## Functional Requirements
+- **FR-1**: 支持按提单号或大箱号查询
+- **FR-2**: 支持按客户ID过滤
+- **FR-3**: 支持按日期范围过滤
+- **FR-4**: 计算到货订单数量、无标签数据数量、已有标签率、换单完成数量、未换单完成数量
+- **FR-5**: 获取到货时间
+
+## Non-Functional Requirements
+- **NFR-1**: 性能优化，避免全表扫描
+- **NFR-2**: 代码可读性和可维护性
+- **NFR-3**: 数据准确性
+
+## Constraints
+- **Technical**: 使用MySQL数据库，SqlSugar ORM框架
+- **Business**: 无特殊业务约束
+- **Dependencies**: 依赖 `label_replace_requests`、`label_scan_history`、`arrival_handover_forms` 表
+
+## Assumptions
+- 数据库表结构已正确创建
+- 所有必要的索引已添加
+- 数据量在合理范围内
+
+## Acceptance Criteria
+
+### AC-1: 基本查询功能
+- **Given**: 提供查询参数（类型、提单号/大箱号、日期范围、客户ID）
+- **When**: 调用数据看板查询接口
+- **Then**: 返回正确的统计数据
+- **Verification**: `programmatic`
+
+### AC-2: 性能优化
+- **Given**: 数据量较大（如10万条记录）
+- **When**: 执行查询
+- **Then**: 查询响应时间在可接受范围内（<5秒）
+- **Verification**: `programmatic`
+
+### AC-3: 数据准确性
+- **Given**: 存在测试数据
+- **When**: 执行查询并与手动计算结果比较
+- **Then**: 统计数据与手动计算一致
+- **Verification**: `human-judgment`
+
+## Open Questions
+- [ ] 到货时间的获取逻辑是否完整？
+- [ ] 扫描记录的查询是否需要进一步优化？
+- [ ] 是否需要添加更多索引以提高性能？