# T15成熟系数迁移指南

## 1. 迁移目标

将当前工程的以下能力迁移到其他工程：

1. 从ODPS读取首层用户和裂变活跃记录；
2. 通过`rootSessionId`归因A0～A15裂变活跃；
3. 计算相对T0的T15成熟系数；
4. 生成小程序及公众号精确参数和分级回退参数；
5. 使用成熟系数预测长期裂变收入和ROI；
6. 保留可复算SQL、参数版本、中文数据表和审计能力。

迁移有两种模式：

| 模式 | 适用场景 | 迁移内容 |
|---|---|---|
| 只消费参数 | 新工程只计算日常ROI，不负责更新参数 | 参数CSV、参数加载和ROI公式 |
| 完整复算 | 新工程需要定期重算成熟参数 | ODPS查询、算法模块、运行入口、测试、文档和参数文件 |

推荐先按“只消费参数”接通ROI，再增加“完整复算”。

## 2. 当前参数版本

| 项目 | 当前值 |
|---|---|
| 参数版本 | `20260712_A0-A15_v1` |
| 首层cohort日期 | `20260712` |
| 观察截止日期 | `20260727` |
| 小程序实体 | 人群包 + 转化目标 |
| 公众号实体 | 合作方 + 公众号 |
| 小程序渠道回退系数 | `2.608491` |
| 公众号渠道回退系数 | `2.476153` |

当前参数文件：

- `outputs/小程序T15成熟系数_中文_20260712.csv`
- `outputs/公众号T15成熟系数_中文_20260712.csv`
- `outputs/T15分级回退系数_中文_20260712.csv`
- `outputs/最终T15成熟系数_中文_20260712.xlsx`

## 3. 需要迁移的文件

### 3.1 只消费参数

最低需要：

```text
outputs/小程序T15成熟系数_中文_20260712.csv
outputs/公众号T15成熟系数_中文_20260712.csv
outputs/T15分级回退系数_中文_20260712.csv
T15成熟系数计算说明.md
```

新工程需自行实现或迁移一个参数加载器，将中文字段映射为内部字段：

```text
人群包
转化目标
合作方
公众号
样本状态
T15成熟系数（相对T0）
```

### 3.2 完整复算

除上述文件外，还需迁移：

```text
cohort_dau.py
partner_cohort_dau.py
partner_cohort_fission.py
calculate_final_t15_coefficients.py
odps_module.py
tests/test_cohort_dau.py
tests/test_partner_cohort_dau.py
tests/test_final_t15_coefficients.py
```

保留本次完整执行SQL用于审计：

```text
outputs/小程序人群包转化目标_A0-A15_20260712.sql
outputs/公众号合作即转_A0-A15_20260712.sql
```

```text
outputs/企微合作方_A0-A15_20260712.sql
outputs/企微T15成熟系数_中文_20260712.csv
```

Python依赖至少包括：

```text
pandas
openpyxl
python-dotenv
pyodps
```

不要复制`.env`、AccessKey、飞书密钥或任何日志中的临时访问令牌。

## 4. ODPS数据依赖

### 4.1 `loghubods.opengid_base_data`

首层cohort所需字段：

| 字段 | 用途 |
|---|---|
| `dt` | 首层投放日期 |
| `channel` | 区分小程序投流和公众号合作即转 |
| `usersharedepth` | `0`定义首层 |
| `hotsencetype` | 排除`1167` |
| `videoid` | 沿用有效投放记录过滤 |
| `mid` | 首层去重用户 |
| `subsessionid` | 作为`rootSessionId`追踪后续裂变 |
| `包名` | 小程序人群包 |
| `广告优化目标` | 小程序转化目标 |
| `合作方名` | 公众号合作方或企微合作方 |
| `公众号名` | 公众号实体 |

渠道值：

```text
小程序投流-稳定
公众号合作-即转-稳定
群/企微合作-稳定
```

### 4.2 `loghubods.user_share_log`

裂变活跃所需字段：

| 字段 | 用途 |
|---|---|
| `dt` | A0～A15观察日 |
| `rootsessionid` | 关联首层root |
| `topic` | 只保留`click` |
| `machinecode` | 裂变活跃用户去重 |
| `usersharedepth` | 只保留`>0`裂变层 |

迁移前必须确认新环境能读取上述核心表，并验证企微首层归因覆盖率。

企微首层归因需要先用 `opengid_base_data.subsessionid + mid` 关联
`user_share_log.subsessionid + machinecode`，以取得 `user_share_log.rootsessionid`。

### 4.3 `loghubods.ods_user_active_log_info_day`

企微裂变活跃还需左关联 `loghubods.ods_user_active_log_info_day`，并排除其中
同一 `machinecode + subsessionid` 且 `user_share_depth=0` 的首层活跃记录。

## 5. 算法口径

### 5.1 首层cohort

```text
首层用户 = 投放日usersharedepth=0的去重mid
root集合 = 首层记录的去重subsessionid
```

小程序归属：

```text
人群包：包名为空或字符串null时记为“泛人群”
转化目标：为空或字符串null时记为“未知”
```

公众号归属：

```text
合作方名 + 公众号名
```

### 5.2 裂变活跃

对投放日`S`：

```text
Ak活跃裂变UV
= 首层root在S+k日产生的裂变层click用户数
```

过滤：

```text
topic='click'
usersharedepth>0
machinecode非空
```

去重和归因：

- 同一实体、同一自然日按`machinecode`去重；
- 同一用户隔日再次进入重新计入；
- 排除原首层cohort用户；
- 当前不做跨实体、跨cohort的全平台全局去重。

### 5.3 成熟系数

```text
T1～T15相对T0尾部系数
= SUM(A1..A15活跃裂变UV) / A0活跃裂变UV

T15成熟系数（相对T0）
= SUM(A0..A15活跃裂变UV) / A0活跃裂变UV
= 1 + 尾部系数
```

T15成熟系数已经包含A0当天。

## 6. 参数门槛和回退

精确实体可用门槛：

```text
首层UV >= 500
且 A0活跃裂变UV >= 200
```

小程序：

```text
人群包+转化目标精确值
→ 人群包A0加权值
→ 转化目标A0加权值
→ 小程序渠道A0加权值
```

公众号：

```text
合作方+公众号精确值
→ 合作方A0加权值
→ 公众号合作即转渠道A0加权值
```

所有回退值必须使用总量比：

```text
SUM(A0～A15累计裂变活跃人次) / SUM(A0活跃裂变UV)
```

禁止对各实体成熟系数直接求算术平均。

## 7. ROI接入

日常ROI所需输入：

```text
首层实际效率收入
T0实际裂变收入
投放成本
实体维度字段
```

公式：

```text
预测裂变总收入
= T0实际裂变收入 × T15成熟系数

预测总收入
= 首层实际效率收入
 + T0实际裂变收入 × T15成熟系数

预测ROI
= 预测总收入 / 投放成本
```

禁止写成：

```text
T0实际裂变收入 + T0实际裂变收入 × T15成熟系数
```

因为成熟系数已经包含T0。

小程序日常数据必须提供`转化目标`才能命中最精确参数；如果暂时没有该字段，必须明确回退到人群包系数，不能把缺失目标默认匹配为“关键页面访问次数”。

## 8. 推荐的工程结构

```text
new_project/
├── config/
│   └── maturity_version.py
├── data/
│   └── maturity/
│       ├── 小程序T15成熟系数_中文_20260712.csv
│       ├── 公众号T15成熟系数_中文_20260712.csv
│       └── T15分级回退系数_中文_20260712.csv
├── src/
│   ├── maturity_query.py
│   ├── maturity_loader.py
│   └── roi_predictor.py
├── sql/
│   ├── 小程序人群包转化目标_A0-A15_20260712.sql
│   └── 公众号合作即转_A0-A15_20260712.sql
├── tests/
│   ├── test_maturity_query.py
│   ├── test_maturity_loader.py
│   └── test_roi_predictor.py
└── docs/
    └── T15成熟系数迁移指南.md
```

参数版本建议集中配置：

```python
MATURITY_VERSION = "20260712_A0-A15_v1"
COHORT_DATE = "20260712"
HORIZON = 15
```

不要在日常ROI任务中临时重新计算cohort参数。参数应离线重算、验证、版本化后再发布。

## 9. 迁移步骤

### 阶段一：复制参数并接入ROI

1. 复制3个中文CSV和本说明；
2. 实现参数加载和分级回退；
3. 接入`首层收入 + T0裂变收入 × 成熟系数`；
4. 用固定样例验证没有重复计算T0；
5. 与原工程对比同一批输入的逐实体系数和预测ROI。

### 阶段二：迁移完整复算

1. 复制查询生成器、运行入口和测试；
2. 在新工程配置ODPS环境变量；
3. 先运行SQL生成测试，不访问生产数据；
4. 再运行一次固定`20260712`复算；
5. 对比原工程40行小程序、110行公众号结果；
6. 公式恒等式和回退系数全部通过后，才允许发布新参数。

### 阶段三：建立参数发布流程

1. 选择已完整成熟的cohort日期；
2. 生成SQL、CSV、Excel和参数摘要；
3. 人工审计异常系数和样本状态；
4. 发布新版本，保留旧版本可回滚；
5. 日常ROI任务仅切换明确的参数版本。

## 10. 验收清单

- [ ] 所有输出表头为中文；
- [ ] 所有记录的首层投放日期一致；
- [ ] 观察截止日等于首层日期加15天；
- [ ] `A0-A15累计裂变活跃人次=SUM(A0..A15)`；
- [ ] `T15成熟系数=累计活跃人次/A0活跃裂变UV`；
- [ ] 尾部系数等于成熟系数减1；
- [ ] 转化目标只出现明确值或“未知”；
- [ ] 小程序精确、公众号精确和回退匹配率已输出；
- [ ] 样本不足实体不会使用自身不稳定系数；
- [ ] ROI没有重复增加T0收入；
- [ ] 新旧工程使用相同输入时结果一致；
- [ ] 参数文件、SQL和代码中不存在凭据。

## 11. 当前遗留问题

1. **单cohort波动**：当前正式参数只取`20260712`一个投放日，可能受当天人群结构影响；后续可评估多个成熟cohort按总量合并。
2. **T15以后长尾**：历史对比显示T16～T30会使裂变收入部分增加约10%；当前按用户决定固定T15，因此属于明确接受的低估。
3. **尾部ARPU假设**：当前默认T1～T15裂变用户ARPU与T0裂变ARPU一致，尚未按cohort年龄单独估算ARPU。
4. **跨实体重复**：当前实体内部按用户日去重，但不做跨人群包、跨转化目标或跨公众号的全平台去重；汇总不能直接视为全平台严格DAU。
5. **转化目标接入**：当前日常ROI旧流程尚未加载“人群包+转化目标”新参数，迁移工程必须确认日常数据是否包含转化目标。
6. **收入边界**：接入前必须再次确认“首层实际效率收入”不包含准备单独放大的T0裂变收入，避免收入重复。
7. **公众号新账号**：首层UV不超过500的公众号不会进入精确参数查询；应使用合作方或渠道回退。
8. **企微渠道**：企微T0裂变口径仍待复核；当前已发布版本不包含企微正式传播裂变系数，日级ROI默认使用参考系数2.5。新版本完成企微文件校验和合作方参数发布后优先使用SQL计算结果；企微不设渠道聚合回退，合作方未匹配或样本不足时继续使用默认2.5，且口径审计完成前仍不进入阈值和调控。
9. **源表稳定性**：`opengid_base_data`与`user_share_log`生产逻辑变更时，需要重新做字段血缘和归因覆盖验证。

## 12. 回滚方案

每次发布新参数必须保留：

```text
参数CSV
完整SQL
生成日期
cohort日期
观察截止日期
代码版本
渠道回退系数
行数和可用行数
```

如果新工程出现系数匹配率下降、ROI异常抬升或收入重复，应立即切回上一参数版本，而不是在线修改参数值。
