docs(sp37): document canonical submit-batch flow

RUNBOOK gets a 'Submitting claims (canonical)' section with both CLI
and HTTP examples, the shared cyclone.submission.submit_file helper,
and a 'submit-batch vs resubmit-rejected-claims' decision rule.
CLAUDE.md gets a pointer to cyclone/submission/ in the 'Backend at a
glance' subpackage list.
This commit is contained in:
Nora
2026-07-07 12:02:33 -06:00
parent 4c85166734
commit 7cb0278be0
2 changed files with 47 additions and 1 deletions
+46
View File
@@ -187,6 +187,52 @@ absent.)
`processed_inbound_files` are skipped automatically — to re-process,
delete the row first (`DELETE FROM processed_inbound_files WHERE name = ...`).
### Submitting claims (canonical — SP37)
For 837P files generated upstream (dzinesco) that you want cyclone to
**track in the DB** before uploading, use the canonical submit path.
This is the preferred outbound path going forward — it captures the
batch's `transaction_set_control_number` (the ST02 control number that
999 acks reference in AK201) so future 999 ack links resolve instead
of becoming orphans.
```bash
cd /home/tyler/dev/cyclone/backend
# 1. Lay out files in batch-*-claims subdirs under your ingest dir:
# ingest/batch-2026-07-08-claims/claim-001.x12
# ingest/batch-2026-07-08-claims/claim-002.x12
# ...
# 2. CLI — walks ingest/, parses, writes to DB, then SFTP-uploads.
.venv/bin/python -m cyclone submit-batch \
--ingest-dir /home/tyler/dev/cyclone/ingest \
--actor cli-submit-batch
# Or via HTTP (auth-gated by matrix_gate):
curl -s -X POST http://localhost:8000/api/submit-batch \
-H 'Content-Type: application/json' \
-d '{"ingest_dir": "/home/tyler/dev/cyclone/ingest", "actor": "api-submit-batch"}'
```
Both surfaces share `cyclone.submission.submit_file` for the
parse → DB-write → SFTP-upload chain (DB-first, upload-second
invariant). The walker pattern is identical: `batch-*-claims/*.x12`,
sorted, with `._*` AppleDouble files skipped.
**When to use `submit-batch` vs `resubmit-rejected-claims`:**
- `submit-batch` — canonical path for fresh 837s from dzinesco (or any
source) that should be tracked in the DB before upload. Default choice.
- `resubmit-rejected-claims` — one-off path for cases where you do NOT
want a DB row (e.g., dzinesco-generated fixes not ready for canonical
tracking). Legacy, retained for backward compat.
**Status codes / exit codes:**
- HTTP 200 on completed runs (per-file failures live in the JSON body);
401 unauthenticated; 404 no clearhouse; 409 stub mode; 422 validation.
- CLI exit 0 on completed runs (per-file failures counted, not bumped);
2 on config-level failures (no clearhouse / stub mode / missing dir).
### Note on per-file parse CLIs
`parse-837` and `parse-835` exist as CLIs but only emit JSON files to