# CLAUDE.md

本项目是数据仓库工程 `poyee-data-warehouse`，当前处于**从老项目 `tendata-warehouse-release` 原地渐进式重构**的阶段。

## 开始任何任务前必读

1. **先读 `kb/README.md`** —— 这是项目的权威知识库入口，包含项目现状、文档分组、阅读路径
2. **冷启动重点文档**：
   - `kb/README.md` —— 项目现状速读（老新项目共存、launch-pad 定位、当前进度）
   - `kb/00-项目架构.md` —— 目标态目录结构、模块职责、执行时序
   - `kb/90-重构路线.md` —— P0-P3 重构清单与硬编码清单
   - `kb/92-重构进度.md` —— 重构任务 checklist 与当前状态
3. **写建表 SQL / DataX ini 前必读**：`kb/21-命名规范.md`（五段式命名、业务域代码、字段词根字典）
4. **写加工 SQL 前必读**：`kb/20-数仓分层与建模.md` + `kb/00-项目架构.md` §9 样板 job 结构

## 项目关键事实

- **项目根目录 = 本文件所在目录**。`kb/` 是文档，其余大部分目录（`tendata/`、`launch-pad/`、`bin/`、`publish.sh` 等）都是**老项目代码**
- **重构模式**：原地改造，不是新建空目录
- **`launch-pad/` 不做业务迁移**：里面是**上个项目**（与当前业务无关）的历史代码，仅作样板 SQL / DataX ini 写法的参考，新业务 SQL 全部从零开发，完成后 `launch-pad/` 整体删除
- **`tendata/` → `dw_base/`**：核心模块重命名，涉及模块改名 + 所有 `from tendata ...` import + SQL 中的 `ADD FILE tendata/...` + `tendata.zip` 打包命令的全局替换
- **DDL 与计算 SQL 物理分离，DDL 单一来源**：`manual/ddl/` 是**所有 DDL 的唯一来源**（首次建表 + 后续 ALTER），采用 migration 模式 —— 每次 DDL 操作是一个不可变文件，**绝不回头改老文件**。`jobs/` 只写 `INSERT OVERWRITE`，不写 CREATE TABLE。**不存在第二个 ddl 目录**（不要建顶层 `ddl/`）。详见 `kb/00-项目架构.md` §9.1 / §9.6
- **存储格式**：所有分层一律 `STORED AS ORC` + `orc.compress=NONE`（不压缩）
- **raw 层契约**：全字段 STRING，同步任务不做类型转换，类型化交给 ods 层（详见 `kb/20-数仓分层与建模.md` §8）。一次性历史导入用 `his` 快照类型 + `o` 周期，表名形如 `raw_xxx_his_o`，不分区，CTAS 一步建表（详见 `kb/00-项目架构.md` §9.3 / §9.3.1）
- **部署**：项目仓库名 = 部署目录名 = `poyee-data-warehouse`，部署路径 `/home/bigdata/release/poyee-data-warehouse/`，部署用户 `bigdata`
- **敏感数据源配置**：不入仓库，由运维维护在 `/home/bigdata/release/datasource/{db_type}/{instance}.ini`

## 协作约定

- **不要擅自创建新目录**
- **不要迁移 launch-pad/ 的内容**：它的业务与新项目完全无关
- **所有建表、字段、文件命名**必须符合 `kb/21-命名规范.md`，没有例外
- **所有重构操作前**先查 `kb/92-重构进度.md`，避免重复做已完成的工作或越过未完成的前置任务
- **修改 kb/ 文档时**同步更新 `kb/README.md` 的索引和 `kb/92-重构进度.md` 的状态