# 服务端代码插入流程（LoggerConsumer + LogBus2）

## 架构说明

服务端 SDK 推荐 LoggerConsumer + LogBus2 架构：

```
服务端代码 → LoggerConsumer → 本地日志文件（/data/ta_log/）
                                    ↓
                              LogBus2 进程 → AE 后台
```

**注意：LogBus v1 已过时，统一使用 LogBus2。**

官方文档：
- 使用指南：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
- 下载地址在官方文档「二、下载 LogBus2」章节中

优势：
- 数据可靠（本地日志持久化，不怕网络抖动）
- 异步上报（不阻塞业务逻辑）
- 批量上传（网络效率高）
- 可控重试（LogBus2 配置重试策略）

---

## Stage 0: Wiki

1. 读 `references/sdk-index.md` 找到服务端 SDK 的 wiki 路径
2. 读 wiki 主文档（初始化、LoggerConsumer 配置）
3. 读 wiki 进阶指南（用户属性、批量上报等）

### Stage 0.5: SDK 集成确认（Stage 0 完成后必须执行）

根据选择的 SDK，识别需要使用哪种依赖管理方式（Maven / pip / go get / npm / composer 等），向用户确认：

**需要代码改动的集成方式（Maven / pip / go get / npm / composer 等）**：

```
检测到服务端使用 <语言> SDK，需要修改依赖配置。

是否需要我直接修改配置文件添加 SDK 依赖？
- yes → Edit 修改配置文件（如 pom.xml / requirements.txt / go.mod / package.json / composer.json 等），完成后进入 Stage 1
- no → 参考以下文档完成 SDK 引入，完成后回答 yes 继续

文档：<wiki 文档路径>
```

- 用户 `yes` → 执行 Edit 修改配置文件，完成后进入 Stage 1
- 用户 `no` → 显示文档路径，暂停等待用户完成

**无需代码改动的集成方式（如需手动下载 JAR / 放置文件等）**：

```
请参考以下文档完成 SDK 引入，完成后回答 yes 继续。

文档：<wiki 文档路径>
```

等待用户确认完成后，进入 Stage 1。

---

## Stage 1: Explore

1. Grep 入口：`src/main.*`、`App.*`、`Application.*`（Java）、`main.go`（Go）
2. Grep 现有埋点：`TaAnalytics|TDAnalytics|thinkingdata|// @tracking`
3. Grep 业务逻辑位置：`(createOrder|handlePayment|userRegister)` 等（根据 plan 事件）
4. 确认日志目录：建议 `/data/ta_log/` 或 `/var/log/ae-tracking/`

---

## Stage 2: Insertion Plan（markdown 表格）

**平台过滤**：
- xlsx "采集端" 值为 `服务端` / `server` → `platform: "server"`（仅服务端采集）
- xlsx "采集端" 值为 `客户端,服务端` / `client,server` → `platform: "both"`（两端都采集）
- xlsx "采集端" 值为 `客户端` / `client` → `platform: "client"`（仅客户端采集，不在服务端生成）
- 只插入 `platform === "server"` 或 `platform === "both"` 的事件

```
## SDK 初始化（LoggerConsumer）
- 文件: <path>:<line>
- 代码: TaAnalytics.init(new LoggerConsumer("/data/ta_log/"))

## 公共事件属性
- 文件: <path>:<line>
- setSuperProperties({...})

## 用户属性
- 文件: <path>:<line>
- user_set / user_setOnce / user_add

## 事件组: <tag>
- <event_name>: <file>:<symbol> 或 SKIP (already present)
- ...

## LogBus2 配置
- 文件: <项目外的固定位置> `.ae-tracking/output/daemon.json`
```

展示后问用户 `ok` 进入 Stage 3，或 "回到事件 X 改映射"。

---

## Stage 3: 分批 Edit

### Batch 1: SDK init（LoggerConsumer）

```java
// Java 示例
TaAnalytics.init(new LoggerConsumer("/data/ta_log/")
    .setRotateMode(LoggerConsumer.RotateMode.DAILY)
    .setRotateSize(1024 * 1024 * 100)); // 100MB
```

写入位置：入口文件静态块 / main 函数开头

### Batch 2: 公共属性 + 用户属性

根据 `meta.user_identity` 生成：
- `user_set` / `user_setOnce`：用户属性上报
- `login()` 调用：用户登录时

### Batch 3..N: 按 event_tag 分组的事件

每个事件在对应业务逻辑位置插入 track 调用。

每批用 Edit 工具；写完打印文件清单 + 新增行数，问 `ok / undo`。

---

## Stage 4: LogBus2 配置生成

额外生成 `.ae-tracking/output/daemon.json`（不写入用户项目）：

```json
{
  "datasource": [
    {
      "type": "file",
      "file_patterns": [
        "/data/ta_log/*.log"
      ],
      "app_id": "<appId>",
      "unit_remove": "day",
      "offset_remove": 7
    }
  ],
  "push_url": "<SERVER_URL>"
}
```

**同步提供官方文档**（方便客户下载和部署）：

```
LogBus2 官方文档：
- 使用指南：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
- 下载地址在官方文档「二、下载 LogBus2」章节中

注意：LogBus v1 已过时，请使用 LogBus2。
```

---

## Stage 5: 汇总

- 打印所有改过的文件 + 每文件新增的事件列表
- 打印 LogBus2 配置文件路径（daemon.json）
- **同步提供 LogBus2 官方文档链接**
- 提示用户启动 LogBus2：
  1. 将 `daemon.json` 复制到 LogBus2 的 `conf/` 目录
  2. 执行 `./logbus start`
- 提示用户考虑跑 debug 模式验证

---

## 代码风格

- LoggerConsumer 单例：新建 `src/lib/TeTracking.java`（若不存在）
- 每个 track 调用前加 `// @tracking <event_name>` 注释
- 日志路径：`/data/ta_log/`（Linux）或 `C:\ta_log\`（Windows）
- 不加 try/catch（LoggerConsumer 本身容错）
- 事件名 / 属性名严格来自 plan，不改

---

## 前置检查

- `git status --porcelain` 非空 → 拒绝，提示用户先 commit/stash

---

## 不同语言的 LoggerConsumer 配置

| 语言 | LoggerConsumer 类 | 日志格式 |
|---|---|---|
| Java | `LoggerConsumer` | JSON line |
| Python | `TaLoggerConsumer` | JSON line |
| Go | `LoggerConsumer` | JSON line |
| Node.js | `LoggerConsumer` | JSON line |
| PHP | `TE_LoggerConsumer` | JSON line |

详见 wiki 对应 SDK 文档。