# AdTest

**Repository Path**: WangDKB/ad-test

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 业务模块代码地图 (Code Map)

本目录是亚马逊广告系统核心业务模块的**代码地图知识库**,沉淀各模块的调用链、关键类、数据流与坑点。

## 为什么需要这个知识库

这个系统有 34 个项目、大量 Producer/Consumer 阶梯式管道、双中心(GZ/HK)部署、新老架构并存。
散落在代码里的业务逻辑难以快速理解。本知识库把"入口在哪、怎么流转、落到哪、有什么坑"沉淀成文档。

## 目录结构

| 文档 | 模块 | 入口 Producer |
|------|------|---------------|
| [00-架构骨架.md](./00-架构骨架.md) | **通用架构**(必读) | Producer→MQ→Consumer→ApiService→SDK 整体模式 |
| [01-调价-AdjustPriceV2.md](./01-调价-AdjustPriceV2.md) | 调价 | `AdjustPriceV2Producer_Job_Service` |
| [02-实体下载-SpEntity.md](./02-实体下载-SpEntity.md) | SP 实体下载 | `GetSpTopEntityProducer_Job_Service` / `GetSpSecondaryEntityProducer_Job_Service` |
| [03-报告下载-Report.md](./03-报告下载-Report.md) | 业务报告下载 | `GetSdTargetReportId_Job_Service` / `ReportIdProducer_Job_Service` |
| [04-自动策略-AutoCreate.md](./04-自动策略-AutoCreate.md) | SP 自动广告策略 | `AutoCreateProducer_Job_Service` |
| [05-手动策略-SpManualV2.md](./05-手动策略-SpManualV2.md) | SP 手动广告策略 | `SPMACCreateProducerV2_Job_Service` |
| [06-监控告警-MonitorAlarm.md](./06-监控告警-MonitorAlarm.md) | 监控告警(跨业务横向) | `MonitorAlarmProducer_Job_Service` |

### 🧪 测试交付指南(给测试人员用,独立子库)

代码图谱讲"代码怎么写",`test-guide/` 讲"**这个模块怎么测、用 UAT 哪些现成数据、查哪张表看结果**"。两套配套但分离,交付测试时只发 test-guide/ 这一套。

| 文档 | 模块 | 内容 |
|------|------|------|
| [test-guide/README.md](./test-guide/README.md) | **测试指南总索引** | 怎么用这套文档 |
| [test-guide/00-测试通则.md](./test-guide/00-测试通则.md) | **必读前置** | 环境/鉴权/连通性/固定ID全集/验证SQL规范/编码约定 |
| [test-guide/01-调价-测试指南.md](./test-guide/01-调价-测试指南.md) ~ [06-监控告警-测试指南.md](./test-guide/06-监控告警-测试指南.md) | 6 模块测试指南 | 每篇:怎么触发 + 测试场景表 + 验证查询SQL + 已知不稳定点 |

### 📋 待收录模块(2026-07-27 扫描发现的高价值未收录模块)

以下模块经侦察确认为独立业务模块,按建议优先级排列。需要时说"梳理 XX 模块"即可生成。

| 建议编号 | 模块 | 入口 Producer | 价值 | 状态 |
|----------|------|---------------|------|------|
| ~~06-监控告警~~ | ~~MonitorAlarm~~ | ~~`MonitorAlarmProducer_Job_Service`~~ | ~~跨调价/自动/手动的告警聚合层,2 表 + Api,运维核心~~ | ✅ **2026-07-27 已收录**(见上表) |
| 07-SD手动策略 | SdManualAutoCreate | `SdManualAutoCreateProducer_Job_Service` | **高**:与 05-SP手动完全对称(16 表 + 5 Consumer + Web/WebApi),不收录会让"手动策略"只覆盖 SP 一半 | 待收录 |
| 08-批量操作 | BatchOperation | `BOTQueueProducer_Job_Service` | **中-高**:11 个 Consumer,批量调价/预算/启停,横跨 SP/SB/SD,运营高频入口 | 待收录 |

**已并入现有篇的子模块**(不需单独成篇):
- `ReportCenterEntityExport` / `ReportExportForPerformance` → 属 03-报告下载 的"报告中心导出"子节
- `PushDataToOtherSystem` → 属 03-报告下载 的"对外推送"子节
- `AdjustPriceV2Recovery` → 属 01-调价(已在恢复链路描述)
- `TaskQueue` → 通用任务调度底座,建议并入 00-架构骨架
- `ClearMongoDB` → 纯运维,00-架构骨架带过
- `SpManual_AutoCreate_Producer` → **已废弃**,被 05 的 V2 取代

## 每篇图谱的统一结构

```
0. 一句话定位 / 模块边界
1. 整体数据流图（ASCII）
2. Producer 层（做什么、查什么、推哪个队列）
3. Consumer 层（分阶段流转表）
4. ApiService 层（HTTP 代理 / SDK 调用点）
5. 数据落地（MongoDB / MySQL / Redis）
6. 关键类清单表
7. 难点与坑点
```

## 使用方式

- **接手某模块**:先读 [00-架构骨架](./00-架构骨架.md),再读对应模块篇。
- **排查问题**:看各篇"难点与坑点"+ 关键类清单表定位文件:行号。
- **新增功能**:参照同模块的兄弟实现(skill `extend-by-copying-sibling`),命名遵循既有约定。

## 📊 数据表清单(全量,每张表标注流程角色与作用)

每个模块涉及的**所有** MySQL 表 / MongoDB 集合 / Redis 键都已梳理,见各篇第 5 节"数据落地"。约定:**实体类名 = 数据库表名**(`Aad_*` 是 MySQL 表,`*Collection` 是 MongoDB 集合)。

### 怎么快速搜表

**① 知道表名,想知道它属于哪个模块、干什么** → 全目录搜表名:
```bash
# 在 Git Bash 里(注意只搜文档,不搜代码,避免编码问题)
grep -rln "Aad_AdjustPrice_Recovery" docs/codemap/
```
搜到哪个文档就知道属于哪个模块,再进该文档第5节看流程角色。

**② 想看某模块的全部表** → 直接打开对应模块文档第5节:
| 模块 | 表数量级 | 跳转 |
|------|----------|------|
| 调价 | 策略配置8 + 执行记录6 + 恢复1 + 实体表(SP 主/Common/Sales×多类型;**SB/SD未实现**) | [01 第5节](./01-调价-AdjustPriceV2.md#5-数据落地全量表集合缓存键清单) |
| 实体下载 | 实体表(主/Common/Sales×7类实体)+ 执行记录3 + Mongo 2 | [02 第5节](./02-实体下载-SpEntity.md#5-数据落地全量表集合缓存键清单) |
| 报告下载 | reportId表(V2细分26+V3聚合3)+ 下载中枢2 + 原始数据(99,按维度分表)+ 报告中心4 | [03 第5节](./03-报告下载-Report.md#5-数据落地全量表集合缓存键清单) |
| 自动策略 | 策略配置7 + 执行记录9 + 实体表(Campaign系列)+ Mongo 2 | [04 第5节](./04-自动策略-AutoCreate.md#5-数据落地与状态机全量表集合缓存键清单) |
| 手动策略 | 策略配置9 + 执行记录(全量6+成功3)+ 实体表 + Mongo 8 | [05 第5节](./05-手动策略-SpManualV2.md#5-数据落地全量表集合缓存键清单) |

### 表命名速查(找表用)

| 前缀/特征 | 含义 | 所属目录 |
|-----------|------|----------|
| `Aad_AdjustPrice_*` | 调价模块表 | Models/AdjustPrice/ |
| `Aad_AutoCreate_*` | 自动策略表(注意:含否定词/批量建实体等边界外子模块) | Models/AutoCreate/ |
| `Aad_SpManual_AutoCreate_*_V2` | 手动策略V2表 | Models/SpManualAutoCreateV2/ |
| `Aad_Report_*` | 报告原始数据/reportId/下载中枢 | Models/Report/ |
| `Aad_ReportCenter*` | 报告中心(对外查询导出) | Models/ReportCenter/ |
| `Aad_Campaign*` | 广告实体主表(被多个模块读写的公共实体) | Models/Campaign/ |
| `*_Common` | FBA 维度副本(活动名以B0开头的数据) | Models/CampaignCommon/ |
| `*_Sales` | 销售调整副本(活动名以"销售调整"结尾) | Models/CampaignSales/ |
| `*Collection` | MongoDB 集合(任务进度/状态机/大对象中转) | MongoModels/ |

### 重要:共享实体表的"多写"机制
`Aad_Campaign`、`Aad_Campaign_AdGroup`、`Aad_Campaign_ProductAd`、`Aad_Campaign_AdGroup_BiddableKeyword`、`Aad_Campaign_TargetingClause` 这几张广告实体表被**调价、实体下载、自动策略、手动策略**四个模块共同写入(各自标记 CreateFlag/来源)。每张都有配套的 `_Common`(FBA)和 `_Sales`(销售调整)副本表。排查实体数据来源时,看记录的 CreateFlag / BuildType 字段可区分是哪个模块写的。

---

## ⚠️ 重要约定(阅读代码前必看)

1. **`.cs` 文件是 UTF-8 with BOM 编码**。在 Git Bash 里用 `cat`/`grep` 读取会乱码(`%TSD-Header` 头)。
   - ✅ 用 IDE / Read 类工具读源码
   - ✅ `grep -rln`(仅列文件名)是安全的,可用于定位
   - ❌ `grep -rn`/`cat`/`sed` 对 .cs 内容会乱码或漏匹配
2. **部分大文件是 %TSD 自定义压缩编码**(`BaseJobService.cs`、`ApiClientService.cs` 等),必须用 IDE/Read 工具读,grep 完全无效。
3. **文件引用格式**:本知识库统一用 `相对路径:行号`(相对项目根目录)。

## 维护机制

- **日常增量**:改完某模块/接到需求时,重扫并只更新对应那篇(快、省)。
- **定期兜底**:**每 8 天早晨 6:00** 由定时任务全量重扫所有模块,防止图谱过时。
- 更新时遵循各篇统一结构,保持"文件:行号"引用最新。

> ⏰ **数据新鲜度提示**:本知识库由定时任务**每 8 天早晨 6:00** 自动刷新一次。文档页面顶部会显示最近更新日期;若某篇提示"已 N 天未更新",说明可能滞后于最新源码,行号引用请以实际代码为准。

## 生成信息

- 首版生成时间:2026-07-23