# ms.gov_ked — Βεβαίωση Οφειλών (module `beveosi_ofeilwn`)

Headless Laravel 10 / PHP 8.1 microservice for ΕΚΕΦΕ Δημόκριτος. It certifies third-party
debts (βεβαίωση οφειλών τρίτων) at the ΔΟΥ through the ΑΑΔΕ ΚΕΔ SOAP web services.

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

No frontend and no authentication live here — both belong to Demokritos. The service is
reached only over RabbitMQ, using Demokritos' own `egov/rabbitmq-classes` package for the
consumer, the command dispatch and the response object. Our code is the domain layer.

## Where things are

| Path | What |
|---|---|
| `app/Ked/` | SOAP layer + domain: `WsseSoapClient`, `KedeProgressClient` (+ fake), `CertificationService`, `ReconciliationService` |
| `app/Commands/Kede/` | The nine commands the BFF calls |
| `app/Bff/` | `RpcPublisher` — dev-only, shared by `bff:publish` and the HTTP bridge |
| `app/Console/Commands/` | `bff:publish` (fake BFF), `ked:smoke` (drive ΚΕΔ by hand), `ked:reconcile` |
| `config/ked.php` | ΚΕΔ endpoints, credentials (two separate pairs), driver, quota knobs |
| `config/rabbit_commands.php` | Command registry read by their dispatcher |
| `database/migrations/` | Certifications + debtors/δόσεις/ΚΑΕ, signers, lookups, call log |
| `frontend/` | Sample React app; `src/lib/fields.ts` is the fields spec for the BFF team |
| `tests/` | XML builders, parser, services, every command, the bridge |

## State of play

**Milestone 2 — done.** Real ΚΕΔ calls, the Παράρτημα Ζ state machine, the full command
surface, a scheduled reconciler and a sample React app that drives the whole chain.

**M3 payments — done.** `retrievePayProgress` / `retrievePaymentData` ship as
`get_payment_progress` / `get_payment_data` (read-only, fetch-on-demand, nothing stored), and
the sample app tracks εισπράξεις through a per-row «Πορεία» action on the βεβαιώσεις table
(keyed on each summary's `taftotites`) plus a tracking page with the seven balances, the
movements table and server-side totals — the separate Εισπράξεις landing was folded into the
table (2026-10). The two calls have no Postman wire sample anywhere, so their first live pilot
answers still need calibrating — `ked:smoke --payId=…` against a Τ.Ο. from an earlier run is
the tool.

`KED_DRIVER=fake` (the default) replays canned pilot responses and never touches the network,
so a fresh checkout is demoable with no ΑΑΔΕ credentials. Real βεβαιώσεις have run against
the ΑΑΔΕ pilot (`test.gsis.gr`, 2026-08-07) and were accepted; that needs the ΚΕΔ
username/password in `.env` and `KED_DRIVER=soap`. Start with `artisan ked:smoke`, which
refuses the certifying call without `--write`. What the pilot run left unresolved:
`docs/internal/open-points.md`.

**M4 — delete service — done.** `deleteKedeAmount` / `deleteKedeProgress` / `deleteKedeComplete`
ship as `submit_reduction` / `get_reduction_progress` / (internal, via `get_reduction_status`
and the `ked:reduction-reconcile` sweep). A Μείωση/Διαγραφή is its own entity, `afek_records` +
`afek_kae_lines`, referencing an already-certified `beveosi_debtors` row rather than a new
`CertificationStatus` case — `certified` stays terminal. Single-shot: `submit_reduction`
creates and sends in one call, there is no draft stage. `kedeDeleteService` has its own WSDL,
namespace and credential pair (`KED_DELETE_*`), never mixed with the progress service's. The
delete-service spec gives no Παράρτημα Ζ-style locking guide at all — the locking/guard scheme
on `afek_records` is designed by analogy to the progress service's, not derived from spec text.
Calibration note (2026-11-04): the delete-service chain has been observed live end to end —
`deleteKedeAmount` minted ΑΦΕΚ no. 1 and `deleteKedeComplete` returned the definitive ΑΒΚΤ
(404946). The one calibration finding: certifications with only 5-digit ΚΑΕ must submit
`afekType=2` (ΚΕΔ guidance; `1` is rejected for such debts).

**Local attachments — done (2026-10).** `set_beveosi_attachments` replaces a βεβαίωση's
`{title, filepath}` list (the Φορέας' MinIO paths) at **any** status — purely local metadata,
never sent to ΚΕΔ, so the Παράρτημα Ζ lock does not apply. The form field «Όνομα πατρός» became
«Τηλέφωνο επικοινωνίας» (`debtorPhone`), also local-only. Contract:
`docs/message-contract.md`.

### The thing that surprises everyone

`retrieveKedeAmount` returns ΔΟΥ, ΧΚ and γραμμή but **never the ΑΤΒ** — that exists only once
the ΔΟΥ closes the day. So `submit_beveosi` answers `certified_pending_closeday`, and the
Αριθμός Τριπλότυπου Βεβαίωσης plus one Ταυτότητα Οφειλής **per ΑΦΜ** arrive later, via the
scheduler or `get_beveosi_status`. Design the UI around that, not around a synchronous reply.

## Getting started

1. Every command you need to type, from a fresh checkout to a βεβαίωση in the browser:
   **`docs/runbook.md`**.
2. How the pieces fit: **`docs/architecture.md`**.
3. The six ΚΕΔ operations, what each one asks and where it acts (the confusable pairs,
   with the flow diagram): **`docs/ked-operations.md`**.
4. What travels on the queue, byte for byte: **`docs/message-contract.md`**.
4. Who does what in the two-terminal demo, and how to prove the library is theirs:
   **`docs/rabbitmq-flow.md`**.

The runbook is the single source of truth for commands — the four services `sail up` starts,
why `migrate --seed` is not optional, how to kill the worker properly, and how to check the
scheduler. Nothing answers on the queue unless the worker is running.

## Two things to know before you commit

- **This repo has two remotes.** `origin` is our private mirror; `demokritos` is the
  client's GitLab — push tested `main` there when there is something to deliver.
- **Credentials are in `docs/source_docs/credentials/`** so you can run against the ΑΑΔΕ
  pilot immediately. Fill them into your local `.env` by hand; never copy the values into
  code, tests, fixtures or `.env.example`.

Working conventions and the domain facts that are easy to get wrong: `CLAUDE.local.md`.

## History

Milestone 1 was built in a separate repository, `ms.beveosiofeilon`, during the period when
we had no access to `egov/rabbitmq-classes`. It was ported here on 2026-08-06; that repo is
now a frozen archive. Documents under `docs/plans/` that describe it are historical.
