# UWF Workflow Pitfalls for nantong-lease-audit

**Last updated**: 2026-06-30

## Pitfall 1: File Name Collision — Multiple Contracts per Campus

The `nantong-lease-audit` workflow writes output to:
```
/tmp/nantong-lease-audit/{{ campus }}-row-data.json
```

When a campus has **multiple contracts** (e.g., 租赁 + 物业), running both contracts through the workflow causes the second to **overwrite** the first's JSON file.

**Discovered**: 通州金鹰 — 租赁合同 wrote `通州金鹰-row-data.json`, then 物业合同 overwrote it.

**Fix**: When running multiple contracts for the same campus:
1. Run them sequentially (not in parallel) — OR —
2. After each workflow completes, rename/copy the output before starting the next:
   ```bash
   # After lease contract workflow completes:
   cp /tmp/nantong-lease-audit/通州金鹰-row-data.json \
      /tmp/nantong-lease-audit/通州金鹰-租赁-row-data.json
   # Then run property contract workflow (will overwrite 通州金鹰-row-data.json)
   ```
3. When building the xlsx, read both JSON files separately

**Current workaround used**: Read the lease contract data from CAS step output (`uwf step show <hash>`) if the JSON was overwritten, then manually reconstruct the property contract data.

## Pitfall 2: Workflow Prompt Variable Not Passed

The classifier role's moderator instruction shows empty values:
```
分类合同。OCR文本路径：，校区：，原始文件名：
```

This happens when the `ocr_path`, `campus`, and `filename` variables are not properly interpolated from the thread start prompt. The classifier still works because the OCR path is in the task context, but the moderator prompt looks incomplete.

**Root cause**: The thread start prompt uses Chinese colons `：` which may not match the YAML template variable syntax. Current workaround: the classifier reads the OCR path from the task context anyway.

## Pitfall 3: Workflow v1 → v2 Hash Change

When the workflow YAML is updated and re-registered:
- Old hash: `7KZ5BWT12R5RJ` (v1, no format templates)
- New hash: `C77579MQ9QPKE` (v2, with H/K/L format templates + reference loading)

Threads started before the update continue using the old hash. Always verify which hash is active:
```bash
uwf workflow show nantong-lease-audit  # Shows current hash
```

## Pitfall 4: Background Exec Returns "Step 1 running"

When using `uwf thread exec <id> --count 20 --background`, the foreground output may show only:
```
Step 1  classifier → running
```

This does NOT mean only step 1 ran. The background worker continues processing all steps. Check actual progress with:
```bash
uwf step list <thread-id>
uwf thread show <thread-id>
```

Expected progression: classifier → template-diff → rule-analyzer → data-extractor → end.
Total time: ~15-20 minutes for all 4 steps.