Metadata-Version: 2.4
Name: live-data-sync
Version: 0.2.0
Summary: Two-step MySQL sync CLI for live streaming data
Author: yanxiao
License: MIT
Requires-Python: >=3.9
Requires-Dist: pymysql==1.1.2
Description-Content-Type: text/markdown

# live-data-sync (`lds`)

> MySQL 两步式直播数据同步 CLI ─ 把指定主播在某段时间内的直播间数据从源库同步到目标库。

[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org)
[![Version](https://img.shields.io/badge/version-0.2.0-green.svg)](./pyproject.toml)
[![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](./pyproject.toml)

## 功能简介

按 `platform_account_id` + `live_begin_time` 范围筛选，分两步把数据同步到目标库：

1. **第一步**：同步 `live_custom_room_info` 表的命中行，并收集所有 `live_custom_room_info_id`
2. **第二步**：基于上一步收集的 ID 集合，分批 `IN` 查询并同步 `live_platform_room_info` 表

整个过程幂等：以主键去重，已存在的记录不会被覆盖或重复插入。

---

## 目录

- [快速开始](#快速开始)
- [安装](#安装)
- [配置](#配置)
- [使用](#使用)
- [卸载](#卸载)
- [日志](#日志)
- [从旧 config.ini 迁移](#从旧-configini-迁移)
- [发布到-pypi](#发布到-pypi维护者)
- [项目结构](#项目结构)

---

## 快速开始

```bash
git clone https://git.ywwl.com/live/live-data-sync.git
cd live-data-sync
bash setup.sh

# 编辑配置文件，填入数据库连接信息
$EDITOR ~/.lds.json

# 执行同步
lds sync 1442088036 2026-04-21 2026-04-27
```

---

## 安装

### 一键安装（推荐）

`setup.sh` 自动检查 Python、安装 CLI、生成配置模板：

```bash
git clone https://git.ywwl.com/live/live-data-sync.git
cd live-data-sync

bash setup.sh                # 完整流程：检查 Python 3.9+ → pip install -e . → lds init
bash setup.sh --skip-config  # 已有 ~/.lds.json 时跳过模板初始化
```

### 从 PyPI 安装

```bash
pip install live-data-sync
```

### 本地开发安装（editable）

```bash
git clone https://git.ywwl.com/live/live-data-sync.git
cd live-data-sync
pip install -e .
```

代码改动即时生效，适合贡献者开发。

### 不安装直接运行

```bash
pip install -r requirements.txt
python -m lds --help
```

---

## 配置

配置文件硬编码在 `~/.lds.json`，权限 `0600`。

### 生成模板

```bash
lds init                # 文件不存在时生成模板；已存在则报错
lds init --force        # 强制覆盖已有配置
```

### 字段说明

```json
{
  "source_database": {
    "host": "源库 host",
    "port": 3306,
    "database": "源库 database 名",
    "user": "用户名",
    "password": "密码",
    "pool_size": 5
  },
  "target_database": {
    "host": "目标库 host",
    "port": 3306,
    "database": "目标库 database 名",
    "user": "用户名",
    "password": "密码",
    "pool_size": 5
  },
  "sync": {
    "batch_size": 1000,
    "log_dir": "~/.lds/logs"
  }
}
```

| 字段 | 说明 | 默认 |
| --- | --- | --- |
| `source_database.*` | 数据来源库连接信息 | — |
| `target_database.*` | 数据接收库连接信息 | — |
| `sync.batch_size` | `IN` 查询与 `INSERT` 的分批大小 | `1000` |
| `sync.log_dir` | 日志目录（支持 `~`） | `~/.lds/logs` |

---

## 使用

### 命令总览

```
lds [-h] [--version] {sync,init} ...

子命令:
  sync   执行同步
  init   生成 ~/.lds.json 模板
```

### `lds sync`

```bash
lds sync <account-id> <start-date> <end-date>
```

参数：

| 位置参数      | 说明                                  |
| ------------- | ------------------------------------- |
| `account-id`  | 主播账号 ID（`platform_account_id`）  |
| `start-date`  | 起始日期 `YYYY-MM-DD`，取当天 `00:00:00` |
| `end-date`    | 结束日期 `YYYY-MM-DD`，取当天 `23:59:59` |

示例：

```bash
# 同步主播 1442088036 在 2026-04-21 至 2026-04-27 的直播数据
lds sync 1442088036 2026-04-21 2026-04-27
```

退出码：

- `0`：同步成功
- `1`：失败（配置缺失、参数错误、数据库异常等）

### `lds init`

```bash
lds init             # 在 ~/.lds.json 写入默认模板
lds init --force     # 已存在时覆盖
```

---

## 卸载

### 一键卸载（推荐）

```bash
bash setup.sh --uninstall
```

三步交互流程：

1. **移除 CLI** — `pip uninstall live-data-sync`
2. **清理配置** — 提示是否删除 `~/.lds.json`（默认 `N`，含明文密码建议清理）
3. **清理日志** — 提示是否删除 `~/.lds/`（默认 `N`，保留历史日志）

### 手动卸载

```bash
pip uninstall live-data-sync   # 移除 CLI
rm -f ~/.lds.json              # 删配置（含明文密码，建议清理）
rm -rf ~/.lds/                 # 删日志目录（如不需保留历史日志）
```

---

## 日志

每次 `lds sync` 会同时输出到 stdout 与日志文件：

- 路径：`<log_dir>/sync_YYYY-MM-DD.log`（默认 `~/.lds/logs/sync_YYYY-MM-DD.log`）
- 编码：UTF-8
- 切分：按天切分（同一天的多次运行追加）

输出格式示例：

```
2026-04-27 20:33:14 - lds.cli       - INFO - [cli.py:57]  - 初始化数据库连接...
2026-04-27 20:33:15 - lds.sync      - INFO - [sync.py:48] - ===== 开始第一步：同步 live_custom_room_info 表 =====
2026-04-27 20:33:15 - lds.sync      - INFO - [sync.py:77] - 第一步同步完成 - 源表符合条件: 4, 新增记录: 4
2026-04-27 20:33:15 - lds.sync      - INFO - [sync.py:129]- 第二步同步完成 - 源表符合条件: 4, 新增记录: 4
2026-04-27 20:33:15 - lds.cli       - INFO - [cli.py:81] - 总新增: 8
```

---

## 从旧 `config.ini` 迁移

| `config.ini`                      | `~/.lds.json`                       |
| --------------------------------- | ----------------------------------- |
| `[source_database] host/port/...` | `source_database.host/port/...`     |
| `[target_database] host/port/...` | `target_database.host/port/...`     |
| `[sync] batch_size`               | `sync.batch_size`                   |
| `[sync] log_file`（已废弃）       | `sync.log_dir`（目录，按天切分）    |

迁移步骤：

```bash
lds init                # 生成新模板
$EDITOR ~/.lds.json     # 把旧字段填入对应位置
```

---

## 发布到 PyPI（维护者）

```bash
python -m pip install --upgrade build twine
python -m build              # 生成 dist/*.whl 与 *.tar.gz
python -m twine upload dist/*
```

发布前先确认 PyPI 上 `live-data-sync` 包名未被占用；如已被占用，改 `pyproject.toml` 中的 `[project] name`（如 `live-data-sync-cli`）。

版本管理：

```bash
# 1) 修改 pyproject.toml [project] version 与 lds/__init__.py __version__
# 2) 提交并打 tag
git commit -am "chore: bump version to X.Y.Z"
git tag -a vX.Y.Z -m "release X.Y.Z"
git push origin main --tags
```

---

## 项目结构

```
live-data-sync/
├── pyproject.toml          # hatchling 构建配置
├── setup.sh                # 一键安装脚本
├── requirements.txt        # 运行时依赖（pymysql）
├── README.md
├── lds/
│   ├── __init__.py         # 版本号
│   ├── __main__.py         # python -m lds 入口
│   ├── cli.py              # CLI（sync / init 子命令）
│   ├── config.py           # ~/.lds.json 加载与模板写入
│   ├── database.py         # 连接池
│   └── sync.py             # 两步式同步核心
└── docs/
    └── superpowers/
        ├── specs/          # 设计文档
        └── plans/          # 实现计划
```

---

## 调用方式对照

`lds` 支持三种等价调用路径：

| 场景            | 命令                                         | 前置条件                                |
| --------------- | -------------------------------------------- | --------------------------------------- |
| PyPI 安装       | `lds sync ...`                               | `pip install live-data-sync`            |
| 本地 editable   | `lds sync ...`                               | `pip install -e .`                      |
| 源码直跑（无安装）| `python -m lds sync ...`                     | `pip install -r requirements.txt`       |

---

## License

MIT
