# cosmo_data_agent

**Repository Path**: vax52/cosmo_data_agent

## Basic Information

- **Project Name**: cosmo_data_agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-29
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业经营数据对话分析智能应用（NL2SQL）数据集

本仓库为「企业经营数据对话分析智能应用（NL2SQL）」赛题构建一套可复用的关系型模拟数据集，
覆盖 5 个业务模块（销售 / 生产 / 质量 / 能耗 / 交付），总记录 9.7 万条，并提供可控"剧本式异常"用于归因分析。

## 一、快速开始

```bash
# 1. 进入脚本目录（脚本均以仓库根为基准写数据）
cd scripts

# 2. 依次执行：生成维度 → 生成事实 → 植入异常 → 导出SQL → 自检 → 评测集
python seed_dimensions.py
python seed_facts.py
python inject_anomalies.py
python export_sql.py
python verify_dataset.py
python seed_evaluation.py
```

所有脚本使用固定随机种子（`scripts/config.py`），每次运行生成完全一致的数据。

## 二、目录结构

```
cosmo_data_agent/
├── docs/                        # 方案与参考文档
├── data/
│   ├── schema/                  # 建库 DDL（SQLite + MySQL）+ SQLite 导入语句
│   ├── raw/                     # 生成的 CSV 数据文件（11 张表 + 缺陷字典）
│   ├── log/anomaly_seed_log.json# 异常埋点清单
│   └── evaluation/              # NL2SQL 评测集（单轮 + 多轮）
└── scripts/                     # 生成 / 注入 / 导出 / 校验 / 评测脚本
```

## 三、数据规模

| 表 | 行数 | 说明 |
|----|-----|------|
| `dim_product` | 200 | 产品维度 |
| `dim_customer` | 300 | 客户维度 |
| `dim_region` | 27 | 地区维度 |
| `dim_production_line` | 12 | 产线维度 |
| `dim_team` | 24 | 班组维度 |
| `dim_calendar` | 1095 | 日历维度（3 年） |
| `fact_sales_order` | 30,000 | 销售订单 |
| `fact_production_order` | 20,000 | 生产工单 |
| `fact_quality_check` | 15,000 | 质检记录 |
| `fact_energy` | 12,000 | 能耗计量 |
| `fact_delivery` | 20,000 | 交付记录 |

分析维度（去重）≥17 个：产品、客户、地区、产线、班组、品类、行业、信用等级、班次、缺陷类型、物流方式、订单状态、年份、月份、季度、假日标记、工厂。

## 四、字段字典

### 维度表

| 表 | 关键字段 |
|----|---------|
| `dim_product` | product_id, product_name, category, unit_cost, unit_price, beat_rate, is_seasonal |
| `dim_customer` | customer_id, customer_name, industry, credit_level |
| `dim_region` | region_id, country, zone, province, city |
| `dim_production_line` | line_id, factory, line_name, equipment |
| `dim_team` | team_id, shift, supervisor |
| `dim_calendar` | date, year, month, week, quarter, is_weekend, is_holiday |

### 事实表

| 表 | 关键字段 |
|----|---------|
| `fact_sales_order` | order_id, order_date, product_id, customer_id, region_id, quantity, unit_price, amount, cost, gross_profit, order_status |
| `fact_production_order` | work_order_id, plan_date, product_id, line_id, team_id, planned_quantity, actual_quantity, qualified_quantity, defect_quantity, work_hours |
| `fact_quality_check` | check_id, check_date, product_id, line_id, team_id, batch_no, sample_quantity, defect_quantity, defect_type, is_qualified |
| `fact_energy` | energy_id, record_date, line_id, shift, electricity_kwh, gas_m3, output_quantity, unit_energy |
| `fact_delivery` | delivery_id, ship_date, order_id, customer_id, region_id, promise_date, actual_date, delay_days, is_on_time, logistics |

外键关系：`fact_sales_order`→产品/客户/地区；`fact_production_order`→产品/产线/班组；`fact_quality_check`→产品/产线/班组；`fact_energy`→产线；`fact_delivery`→订单/客户/地区。

## 五、业务口径（NL2SQL prompt 必须一致）

| 概念 | 定义 |
|------|------|
| 毛利 | (单品售价 − 单位成本) × 销量 |
| 毛利率 | 毛利 ÷ 销售额 |
| 良品率 | 合格数 ÷ 实际产量 |
| 不良率 | 不良数 ÷ 实际产量 |
| 单位能耗 | 电耗 ÷ 产量（kWh/件） |
| 交付准时率 | 按时交付订单数 ÷ 总订单数 |
| 退货率 | 退货金额 ÷ 销售额 |
| 同比 / 环比 | 与去年同期 / 上一周期比较 |

## 六、剧本式异常（归因分析素材）

埋点清单见 `data/log/anomaly_seed_log.json`，共 5 类：

| 编号 | 异常 | 目标维度 |
|------|------|---------|
| A1 | 产品良品率被人为拉低 | 产品、时间 |
| A2 | 产线特定班次单位能耗抬升 | 产线、班次 |
| A3 | 地区物流改为慢速致延迟 | 地区、物流 |
| A4 | 品类叠加季节性销量波动 | 品类、月份 |
| A5 | 班组近 2 个月缺陷集中 | 班组、缺陷类型 |

## 七、入库方式

- **SQLite**：执行 `data/schema/schema_sqlite.sql` 建库，再用 `data/schema/import_sqlite.sql`（需先在 sqlite3 中 `.mode csv`）导入 CSV。
- **MySQL**：执行 `data/schema/schema_mysql.sql` 建库，CSV 可用 `LOAD DATA LOCAL INFILE` 导入。

## 八、自检

运行 `python verify_dataset.py` 输出自检报告，覆盖：行数达标、外键无孤立、口径计算无 NaN/负值、维度数 ≥10。

---

*维护人：cosmo_data_agent 项目 ｜ 日期：2026-09-29*