Fix Gitea seed recovery and workflow guards

2026-06-21 22:33:30 +09:00
parent 0cec44a0e1
commit a95198cf8c
6 changed files with 299 additions and 14 deletions
@@ -0,0 +1,70 @@
+# Gitea Variables Failure Analysis Guide
+
+Use this when a Gitea Actions run fails after the `vars` migration.
+
+## Decision tree
+
+### 1. Workflow never starts
+
+Likely causes:
+
+- workflow file not committed
+- runner offline
+- dispatch permission issue
+
+Empirical note:
+
+- A direct API dispatch probe to the workflow endpoint returned `401 Unauthorized` in this workspace, which means API-triggered execution still needs a valid repository token.
+- With `GITEA_TOKEN_HOME`, dispatch succeeds and creates a queued run, so the remaining bottleneck can be runner capacity rather than API auth.
+
+Observed root cause for `run 161`:
+
+- `Checkout Code` failed because the checked-out commit did not contain `GatherTradingData.json`.
+- The job log shows `::error::GatherTradingData.json 없음 — canonical seed snapshot이 필요합니다.`
+- `git ls-tree --name-only -r HEAD -- GatherTradingData.json` in this workspace returned no tracked file, so the file exists locally but is not part of the repository tree used by the runner.
+
+Current workflow correction:
+
+- A dedicated `Prepare Raw Seed Snapshot` step now checks for `GatherTradingData.json` first.
+- If JSON is missing but `GatherTradingData.xlsx` exists, the workflow regenerates JSON with `tools/convert_xlsx_to_json.py`.
+- If both are missing and `.clasprc.json` is present, the workflow attempts to download `GatherTradingData.xlsx` from Google Drive and then regenerate JSON.
+- If both are missing and no download credential is available, the workflow emits explicit recovery instructions instead of failing with a generic checkout error.
+
+### 2. Step fails with `missing or empty`
+
+Likely causes:
+
+- repo variable not created
+- variable name typo
+- variable value is blank
+
+### 3. Python fails with `environment variables not found`
+
+Likely causes:
+
+- workflow maps the wrong name into the env block
+- repo variable scope is wrong
+- runner executed an older checkout
+
+### 4. Collector starts but no DB/report is written
+
+Likely causes:
+
+- `GatherTradingData.json` missing
+- `.clasprc.json` missing or Google Drive export denied
+- KIS connectivity/auth issue
+- target path permissions on the runner
+
+## What to inspect first
+
+1. The exact failing step name.
+2. The first shell error line.
+3. Whether the workflow job log shows `vars.KIS_APP_*` in the YAML revision used by the run.
+4. Whether the output files were created before failure.
+
+## Expected healthy signature
+
+- Credential validation step passes.
+- Collector step passes.
+- `Temp/kis_data_collection_v1.json` exists.
+- `outputs/kis_data_collection/kis_data_collection.db` exists.