# Βεβαίωση Οφειλών MS — Milestone 1 walkthrough

> **HISTORICAL (2026-08-06).** Describes `ms.beveosiofeilon` as it stood *before* the port
> into this repo — its own consumer, codec and dispatcher, none of which exist here. For the
> current picture see `docs/architecture.md` and `docs/rabbitmq-flow.md`.

*One-page tour of `ms.beveosiofeilon` (internal; the client-facing contract doc is
`docs/message-contract.md`).*

**What it is.** A headless Laravel 10 / PHP 8.1 microservice for ΕΚΕΦΕ Δημόκριτος. Their
React/BFF sends commands over RabbitMQ; we execute and reply over RabbitMQ. In M2 the
commands call the ΑΑΔΕ ΚΕΔ SOAP services to certify third-party debts at the ΔΟΥ,
replacing today's Excel-by-courier process. No frontend, no auth — both are Demokritos'.

```
React UI ──▶ BFF ──▶ [RabbitMQ] ──▶ ms.beveosiofeilon ──(M2: SOAP/WS-Security)──▶ ΚΕΔ (ΑΑΔΕ)
                         ▲                  │
                         └──── response ────┘
```

**M1 proves the left half end-to-end** (worker, contract, error handling, durability) with
the ΚΕΔ call stubbed — so Demokritos can sign off the message contract before we build
financial logic on top of a guessed envelope.

## One message through the code

| Step | File | What happens |
|---|---|---|
| Worker consumes | `app/Console/Commands/RabbitConsumeCommand.php` | Durable queue, 1 msg at a time. **Ack only after the reply is published** → crash = redelivery, never loss. Poison msg → rejected *without* requeue, worker never loops. Never replies onto its own queue. |
| Decode | `app/Messaging/MessageCodec.php` → `JsonMessageCodec` | **The key abstraction.** Their real wire format is a proprietary hash string from `egov/rabbitmq-classes` (internal GitLab, no access yet). It sits behind an interface: JSON codec for dev, `EgovHashMessageCodec` placeholder for their library. Swap = 1 class, `MS_CODEC=egov`. Nothing else may touch their namespace. |
| Dispatch | `app/Commands/CommandDispatcher.php` + `config/rabbit_commands.php` | Command pattern per their guide: config maps name → class. Never throws: unknown/crashing command becomes a structured ERROR response. |
| Execute | `app/Commands/General/PingCommand.php`, `app/Commands/Kede/SubmitBeveosiCommand.php` | Ping = handshake. SubmitBeveosi = full input validation + **stubbed** certification. Type discipline from the ΚΕΔ spec: ΑΦΜ/ΚΑΕ/ΔΟΥ are strings (leading zeros matter), money is a decimal *string* never a float, `atbNo` reaches 20 digits → string, not int64. |
| Respond | `app/Messaging/RabbitMQResponse.php` | Exact mirror of their guide's contract: always `data, type, status, messages, warnings, errors, extraData, pagination`; enums `SINGLE_ITEM/LIST`, `OK/ERROR`. A test pins the keys so the contract can't drift. |
| Test harness | `app/Console/Commands/BffPublishCommand.php` | `artisan bff:publish` impersonates their BFF: publish → wait on temp reply queue → print. Together with `docs/message-contract.md`, this is the M1 deliverable their BFF team reviews. |

## Built now, live in M2 (seams)

- `app/Ked/WsseSoapClient.php` — SOAP 1.1 + WS-Security UsernameToken, TLS 1.2 pinned; header injection unit-tested against PHP's real `SOAP-ENV` envelopes.
- `app/Ked/Progress/…` & `app/Ked/Delete/…` — one client per ΚΕΔ service (**separate credential pairs**, must never mix).
- `app/Ked/AuditRecordFactory.php` — audit block on every ΚΕΔ call; `auditProtocol` = our unique local id, ΚΕΔ's duplicate detector.
- Migrations: `beveosi_certifications` with **anti-duplicate locking columns** (hard ΚΕΔ rule, Παράρτημα Ζ — wrong = duplicate debts raised against real people) and `ked_call_log` (full SOAP audit trail). Schema now, logic in M2.

## Deliberate decisions worth defending

- **Laravel 10 / PHP 8.1** — matches Demokritos' guide; security trade-off known and accepted.
- **ΚΕΔ is SOAP, not REST** — their own confirmation doc says REST; it's wrong (corrected in writing).
- **Stateful (MySQL)** — forced by the anti-duplicate locking rule; "stateless?" question is settled.
- **The SOAP side is already de-risked** — a working Postman collection (pilot env) is the M2 oracle: replay through our client, match byte-for-byte.
- Sail/Docker is dev-only; production = their on-prem php-fpm + supervisor (stanza in README).

## Status & next

**Done:** 21 tests green; live loop verified incl. crash-redelivery and poison messages; contract doc + credential-stripped Postman collection shipped in-repo.
**Blocked on Demokritos:** the `egov/rabbitmq-classes` package or its format spec; queue/exchange topology; a real sample inbound message; token contents.
**Next:** M2 — the four `kedeProgress` calls live against the ΑΑΔΕ pilot + the locking logic. Demo: `sail up -d`, `sail artisan rabbit:consume`, then `sail artisan bff:publish ping`.
