# 项目约定

## 目录结构

```
data_analysis/
├── lib/                    # 核心库
│   └── odps_module.py      # ODPS 客户端
├── tasks/                  # 分析任务
│   ├── 00_表的洞察/        # 表结构探索（按表名建子目录）
│   ├── archive/            # 归档的旧任务
│   ├── 头部/               # 头部相关分析
│   ├── 承接/               # 承接相关分析
│   └── 其他分类.../        # 按主题分类
│       └── 任务名/
│           ├── query.sql
│           └── output/
├── fetch_daily.py          # 按天增量获取数据（并发）
└── run_sql.py              # SQL 执行入口脚本（日期范围）
```

## 命名规范

- 任务目录：中文表意，按主题分类存放
- SQL 文件：统一用 `query.sql`
- 输出目录：统一用 `output/`
- 归档：旧任务移至 `archive/`

## SQL 变量

### run_sql.py（日期范围查询）
- `${start}` - dt 分区起始日期
- `${end}` - dt 分区结束日期
- 默认值：最近 7 天（T-7 ~ T-1）
- 输出：`output/{start}_{end}.csv`

### fetch_daily.py（按天增量获取）
- `${dt}` - 单天日期
- 支持并发，自动跳过已有数据
- 输出：`output/SQL文件名/{dt}.csv`

## 运行任务

### 日期范围查询
```bash
python run_sql.py tasks/xxx/query.sql
```

### 按天增量获取
```bash
python fetch_daily.py tasks/xxx/query.sql                    # 最近7天
python fetch_daily.py tasks/xxx/query.sql --days 30          # 最近30天
python fetch_daily.py tasks/xxx/query.sql --start 20260101 --end 20260107
python fetch_daily.py tasks/xxx/query.sql --date 20260105    # 单天
python fetch_daily.py tasks/xxx/query.sql --force            # 强制重新获取
python fetch_daily.py tasks/xxx/query.sql --workers 10       # 设置并发数
```

## 新建任务

1. 在对应分类目录下创建任务目录，如 `tasks/头部/任务名/`
2. 编写 `query.sql`，日期变量根据脚本选择：
   - run_sql.py → `${start}` 和 `${end}`
   - fetch_daily.py → `${dt}`
3. 运行对应脚本获取数据