feat: phase a1 - EDI data model, X12 parsing, guide validation, TA1/997/999 #5

2026-10-14T01:31:32Z

KofTwentyTwo commented

2026-10-14 01:31:32 +00:00

(Migrated from github.com)

Summary

Phase (a), part 1 of the approved design (docs/DESIGN.md):

Tables (21, edi_*): partners, identities, agreements, agreement documents, control numbers, transports (typed settings, slug validation), certificates, guides (segments, elements, rules), code lists, interchanges, functional groups, documents, validation errors, events, exceptions, inbox, payloads. Record screens, PVS, joins, child lists, full-name permissions (edi.<entity>.*); runtime tables read-only to people. docs/ddl/edi-postgres.sql.
X12: StAEDI-based streaming envelope reader (multi-interchange payloads, separator detection, envelope findings mapped to TA1/AK9/AK5 codes, segment bounds) and a writer with fixed-width ISA.
Guides as data: in-house baseline guides (850 004010/005010, 997 004010/005010, 999 005010X231A1) as JSON resources, loader with revisions into the tables, guide validator (order, loops, usage, repeats, types, lengths, code lists, syntax notes P/R/E/C/L) and the rule language for situational rules. docs/GUIDE-FORMAT.md.
Acks: TA1, 997 and 999 builders at GROUP_ONLY / ALL_TRANSACTIONS / ERRORS_ONLY; inbound ack reader.
Control numbers: atomic compare-and-set allocation (RC.5 UpdateInput has no conditional filter, so parameterized SQL through the RDBMS connection in a short transaction); duplicate detection for interchanges, groups, transaction sets.
Payloads: AES-256-GCM envelope encryption (per-payload data key wrapped by QQQ_EDI_PAYLOAD_KEY, rotation via _PREVIOUS) into edi_payload; no local files.

Deviation from the spec, updated in DESIGN 6 and 7.2: the guide engine validates the StAEDI-tokenized segments directly instead of compiling guides into StAEDI schemas.

Next: a2 (inbox and worker, routing, maps and apply, gateway intake, exceptions, app home, record actions).

Test plan

./mvnw verify: 69 tests, Checkstyle, JaCoCo (95.6% instructions, 100% classes)
Exact 997/999/TA1 outputs; every rule type; 8-thread control-number allocation on H2; encryption tamper and rotation; no temp files
CircleCI test_only

🤖 Generated with Claude Code

## Summary Phase (a), part 1 of the approved design (`docs/DESIGN.md`): - **Tables (21, `edi_*`):** partners, identities, agreements, agreement documents, control numbers, transports (typed settings, slug validation), certificates, guides (segments, elements, rules), code lists, interchanges, functional groups, documents, validation errors, events, exceptions, inbox, payloads. Record screens, PVS, joins, child lists, full-name permissions (`edi.<entity>.*`); runtime tables read-only to people. `docs/ddl/edi-postgres.sql`. - **X12:** StAEDI-based streaming envelope reader (multi-interchange payloads, separator detection, envelope findings mapped to TA1/AK9/AK5 codes, segment bounds) and a writer with fixed-width ISA. - **Guides as data:** in-house baseline guides (850 004010/005010, 997 004010/005010, 999 005010X231A1) as JSON resources, loader with revisions into the tables, guide validator (order, loops, usage, repeats, types, lengths, code lists, syntax notes P/R/E/C/L) and the rule language for situational rules. `docs/GUIDE-FORMAT.md`. - **Acks:** TA1, 997 and 999 builders at GROUP_ONLY / ALL_TRANSACTIONS / ERRORS_ONLY; inbound ack reader. - **Control numbers:** atomic compare-and-set allocation (RC.5 `UpdateInput` has no conditional filter, so parameterized SQL through the RDBMS connection in a short transaction); duplicate detection for interchanges, groups, transaction sets. - **Payloads:** AES-256-GCM envelope encryption (per-payload data key wrapped by `QQQ_EDI_PAYLOAD_KEY`, rotation via `_PREVIOUS`) into `edi_payload`; no local files. Deviation from the spec, updated in DESIGN 6 and 7.2: the guide engine validates the StAEDI-tokenized segments directly instead of compiling guides into StAEDI schemas. Next: a2 (inbox and worker, routing, maps and apply, gateway intake, exceptions, app home, record actions). ## Test plan - [x] `./mvnw verify`: 69 tests, Checkstyle, JaCoCo (95.6% instructions, 100% classes) - [x] Exact 997/999/TA1 outputs; every rule type; 8-thread control-number allocation on H2; encryption tamper and rotation; no temp files - [ ] CircleCI `test_only` 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qbit-edi#5