# JV データ取得・正規化 — 手順一本化（新本番 163.44.117.9）

**目的:** Windows のバッチと Linux スクリプトだけで、2019〜2023 の JV 生データを取り直し、正規化まで進める。

**根拠ログ:** 実際に大量取得できていたのは [ops_jv_ACTUAL_success_2026-05.md](./ops_jv_ACTUAL_success_2026-05.md) のとおり  
**Windows JVLinkServer:8765 + ssh -R 18765 + Linux 上の `fetch_jv_raw.py`** です。

---

## 0. いまの新本番の状態

| 項目 | 状態 |
|------|------|
| DB | **`jv_reset_for_full_refetch.sql` 実行済み**（業務テーブル・raw 空、tracks のみ残す） |
| 生データ取得 | `jv_wait_tunnel_and_fetch_raw.sh` → **`--all-stored`**（`from_datetime=20200101`・正規化なし） |
| phpMyAdmin | https://tools.kachiumaai.com/phpmyadmin/ （Web 門なし・MariaDB ログインのみ） |
| パス | `/var/www/html/tools.kachiumaai.com` |

---

## 1. 取得の進め方（正解を決めつけない）

**過去に「この形だけが正解」と書いて失敗した。** option / from / to は **試して結果を残してから**本番に進む。

| 段階 | スクリプト | 目的 |
|------|------------|------|
| 接続確認 | `jv_smoke_test.sh` | トンネル + 数十件 |
| パラメータ試行 | `jv_fetch_param_probe.sh 2020 30` | option 1/3/4 等を比較 → `docs/ops_jv_fetch_param_results.md` に追記 |
| 1年本番 | `jv_fetch_one_year.sh 2020` | 2020 だけ取得→増分正規化→`races` が ~3400 か判定 |
| 次の年 | 同上を 2021, 2022… | 前年が合格してから |

**完了判定:** `races`（JRA）が **年約 3,400 件前後**（JRA 公式の中央競馬レース数と照合）。raw 件数だけでは判断しない。

**インフラ（毎回共通）**

```
[Windows] JVLinkServer 8765 + ssh -R 18765（2窓開きっぱなし）
[Linux]   config/jv_local.env → JV_FETCH_EXTRA="--linux-tunnel-tcp ..."
```

試行結果の一覧: [ops_jv_fetch_param_results.md](./ops_jv_fetch_param_results.md)

**やらないこと（混同禁止）**

- `1-JV取得-2019から一括.bat` で **PC の .env が指す MySQL に直書き**する運用（新本番 DB に入らない設定のことが多い）
- 取得前に **`meet_year` 確認なし**で 2025/2026 削除スクリプトを実行
- `JV_FETCH_PAUSED` が残ったまま backfill を実行

---

## 2. Windows バッチ一覧（`scripts/windows/`）

### 初回だけ

| バッチ | 内容 |
|--------|------|
| `step00_first_setup.bat` | `setup_auto.bat` … `jv-windows.local.env` 作成 |
| `pc-copy-from-server\fetch-pc-env-from-server.bat` | サーバーから `.env` 雛形取得（任意） |

### 毎回の標準（番号順・推奨）

| 順 | バッチ | 内容 | 窓 |
|----|--------|------|-----|
| 1 | **`step01_start_tunnel.bat`** | JVLinkServer + SSH 逆トンネル | **2つとも開きっぱなし** |
| 2 | **`step02_check_new_server.bat`** | 新本番で `jv_link_tcp_healthcheck.py` | 閉じてよい |
| 3 | **`step03_jv_backfill_2019_on_linux.bat`** | SSH 経由で **`jv_backfill_years.sh`** | 数時間〜 |
| 4 | **`step04_server_normalize.bat`** | 正規化 + materialize + audit | 30分〜 |
| 5 | **`step05_server_repredict_p6.bat`** | p6_latest 再計算（任意） | 長時間 |

`step01` の中身は `restore_linux_fetch_flow.bat` と同じです。

### 日本語名バッチ（同じ役割）

| バッチ | 対応 |
|--------|------|
| `restore_linux_fetch_flow.bat` | ≒ step01 |
| `check-jv-link.bat` | JVLinkServer 8765 確認 |
| `1-JV取得-2019から一括.bat` | **PC 上**で fetch（新本番向けでない場合あり） |
| `fetch-jv-year.bat 2019` | 1年だけ PC 上で fetch |
| `2-本番で正規化.bat` | ≒ step04 |
| `3-本番で予想再実行-p6.bat` | ≒ step05 |

詳細メモ: サーバー上 `scripts/windows/0-最初に読む-手順.txt`

---

## 3. 設定ファイル（必須）

### PC: `scripts/windows/jv-windows.local.env`

（`jv-windows.local.env.example` をコピーして編集。**Git にコミットしない**）

```ini
REPO_ROOT=C:\work\ai-horse-race.maspis.com
PYTHON=py -3.11
JVLINK_SID=あなたのソフトウェアID
JVLINK_SERVER_HOST=127.0.0.1
JVLINK_SERVER_PORT=8765
SERVER_SSH=root@163.44.117.9
SERVER_PATH=/var/www/html/tools.kachiumaai.com
JV_BACKFILL_FROM_YEAR=2019
JV_BACKFILL_TO_YEAR=2023
```

- **`JV_BACKFILL_TO_YEAR=2023`** … 2024 以降は取らない（今回の整理方針）
- SSH 鍵: `%USERPROFILE%\.ssh\keiba_tools`（`setup_ssh_key.bat` で作成可）

### 新本番: `config/jv_local.env`（既にサーバー側）

```ini
JVLINK_SERVER_HOST=127.0.0.1
JVLINK_SERVER_PORT=18765
JVLINK_LINUX_TUNNEL_TCP=1
JV_FETCH_EXTRA="--linux-tunnel-tcp --host 127.0.0.1 --port 18765"
```

---

## 4. 再取得の手順（2019〜2023 だけ）

### 4-1. 取得停止フラグを外す（新本番 SSH）

```bash
cd /var/www/html/tools.kachiumaai.com
rm -f config/JV_FETCH_PAUSED
# cron で週次取得を戻すのは、2019〜2023 が終わってからでよい
```

### 4-2. Windows

1. **`step01_start_tunnel.bat`** をダブルクリック  
   - 窓1: JVLinkServer（8765）  
   - 窓2: `ssh -R 18765:...`（何も出なくて正常）
2. **`step02_check_new_server.bat`**  
   - `[OK]` が出るまで step1 を直す

### 4-3. バックフィル（新本番で実行・step03 が SSH で起動）

```bash
# 手動で SSH する場合（step03 と同じ）
cd /var/www/html/tools.kachiumaai.com
JV_BACKFILL_FROM_YEAR=2019 JV_BACKFILL_TO_YEAR=2023 ./scripts/jv_backfill_years.sh
```

**ログ（進捗）**

```bash
tail -f /var/www/html/tools.kachiumaai.com/logs/jv_backfill_years.*.log
```

**中身（年ごと）**

1. `fetch_jv_raw.py` … `--from-datetime YYYY0101` … `RACE --option 1`
2. `fetch_jv_raw.py` … `--weekly-odds`（前年末〜）
3. 最後に **全件正規化**（`normalize_jv_raw.py` → `materialize` → `audit`）

数時間〜1日以上かかることがあります。**step01 の2窓は最後まで閉じない。**

### 4-4. 取得後の確認（削除する前に必ず）

phpMyAdmin または SSH + mysql:

```sql
SELECT JSON_UNQUOTE(JSON_EXTRACT(payload_json,'$.meet_year')) AS y, COUNT(*) c
FROM jv_raw_records
GROUP BY y
ORDER BY y;
```

**2019〜2023 に件数があること**を確認してから、2025/2026 削除などを考える。

### 4-5. 正規化（2019〜2023 だけ残したい場合）

backfill 内蔵の正規化で足りない・業務テーブルを空にしたい場合:

```bash
cd /var/www/html/tools.kachiumaai.com
JV_NORMALIZE_MAX_YEAR=2023 JV_NORMALIZE_TRUNCATE_BUSINESS=1 \
  ./scripts/jv_normalize_past_years.sh
```

または Windows から **`step04_server_normalize.bat`**（全 raw 対象・`--max-year` なし）。

### 4-6. 予想（任意）

**`step05_server_repredict_p6.bat`**

---

## 5. 削除・整理スクリプト（注意）

| スクリプト | 危険 |
|------------|------|
| `jv_delete_raw_years.sh` | JSON の **`meet_year`** が 2025/2026 の行だけ削除。**2019〜2023 が 0 件なら実質全削除** |
| `jv_solidify_2019_2023.sh` | 上記削除 → 業務削除 → 正規化を一括 |
| `db/jv_reset_for_full_refetch.sql` | **全 TRUNCATE** |

**削除前の必須 SQL**（上記 4-4 と同じ）

---

## 6. 取得を止める・再開する

| 操作 | コマンド / ファイル |
|------|---------------------|
| 停止 | `./scripts/jv_stop_fetch_cron.sh` → `config/JV_FETCH_PAUSED` 作成 |
| 再開 | `rm config/JV_FETCH_PAUSED` + crontab に `jv_weekly_refresh` を戻す |

`jv_weekly_refresh.sh` は **`JV_FETCH_PAUSED` があると即終了**します。

---

## 7. ログの場所

| 場所 | 内容 |
|------|------|
| PC `%REPO_ROOT%\logs\jv_backfill_win_*.log` | `1-JV取得-2019から一括.bat` 用 |
| 新本番 `logs/jv_backfill_years.*.log` | 年単位 backfill |
| 新本番 `logs/jv_normalize_past_years.*.log` | 過去年正規化 |
| 新本番 `logs/jv_delete_raw_years.log` | 年別 raw 削除 |

---

## 8. トラブル

| 症状 | 対処 |
|------|------|
| `Connection refused` 18765 | step01 の2窓を開き直す |
| `JVLinkServer is not running` | `jvlink_start.bat` / SID 確認 |
| `JV_FETCH_PAUSED` で何も動かない | `rm config/JV_FETCH_PAUSED` |
| ディスク 100% | raw 削除後 `OPTIMIZE` / 空き確保してから SQL |
| worker unreachable | `docs/ops_jv_link_windows_fetch.md` / `fix_sid_and_start_jvlink.bat` |

---

## 9. 参照

- [ops_jv_ACTUAL_success_2026-05.md](./ops_jv_ACTUAL_success_2026-05.md) … 5/28-29 成功ログ
- `scripts/windows/START_HERE.txt` … バッチ索引
- phpMyAdmin … https://tools.kachiumaai.com/phpmyadmin/