ekwo-os 0.4.1

package/dist/assets/migrations/20260913084847_company_profile.sql

@@ -0,0 +1,261 @@
+-- Ekwo OS — a company has a face, and an invoice has to print it.
+--
+-- The core knew a company's name, its legal name, its address, its two
+-- identifiers and its currency. An invoice needs more than that, and every
+-- one of the missing pieces is a thing a renderer would otherwise have to be
+-- configured with separately — which is the same fact written twice, in a
+-- place the books cannot see.
+--
+-- **What is added, and why each one is a column rather than a setting.**
+-- `trade_name` because a company trades under a name that is not its
+-- statutory one and the invoice carries both. `logo_url` because a renderer
+-- needs to find the image — a URL or a storage path, never the file: the core
+-- keeps books, not binaries. `share_capital` with its own currency because
+-- several European legal forms must state it on every document.
+-- `activity_code` with the scheme it is written in, because NACE, APE and SIC
+-- are different registers and a bare code is unreadable without the one it
+-- came from. `default_bank_account_id` because an invoice without an IBAN
+-- cannot be paid. `document_template` because a company that has chosen a
+-- layout has chosen it once, not per invoice.
+--
+-- **What is deliberately not added.** No `registry_reference`:
+-- `companies.registration_number` is already the number the commercial
+-- register holds — a BCE number in Belgium, an RCS or SIRET in France — and a
+-- second column for it would be two answers to one question, which is the one
+-- thing this schema will not do.
+--
+-- **No literal default anywhere.** `share_capital_currency` falls back to the
+-- company's own currency, in a trigger, and never to a currency written into
+-- this file.
+
+alter table companies
+  add column if not exists trade_name              text,
+  add column if not exists logo_url                text,
+  add column if not exists share_capital           numeric(16, 2),
+  add column if not exists share_capital_currency  char(3) references currencies(code),
+  add column if not exists activity_code           text,
+  add column if not exists activity_scheme         text,
+  add column if not exists default_bank_account_id uuid,
+  add column if not exists document_template       text;
+
+comment on column companies.trade_name is
+  'The name the company trades under, when it is not the statutory one. A renderer shows this and keeps legal_name for the footer.';
+comment on column companies.logo_url is
+  'Where the logo is, as a URL or a storage path. The core stores no file: an accounting schema that held binaries would be backing up images with the ledger.';
+comment on column companies.share_capital is
+  'Capital to be stated on documents where the law requires it. Null where it does not, which is not zero.';
+comment on column companies.share_capital_currency is
+  'Currency the capital is expressed in. Filled with the company''s own currency when it is left empty, and never with a currency written into the schema.';
+comment on column companies.activity_code is
+  'The company''s activity in the register of its country — NACE, APE, SIC. Text, because the registers are not numbers and not the same length.';
+comment on column companies.activity_scheme is
+  'Which register activity_code belongs to. A code without its scheme cannot be looked up.';
+comment on column companies.default_bank_account_id is
+  'The account a customer is asked to pay into. It fills documents.payee_iban (BT-84) when a sales document names none.';
+comment on column companies.document_template is
+  'A code the renderer interprets. The core never reads it: what a document looks like is not an accounting question.';
+
+alter table companies
+  add constraint companies_share_capital_positive
+    check (share_capital is null or share_capital >= 0),
+  add constraint companies_share_capital_has_currency
+    check (share_capital is null or share_capital_currency is not null),
+  add constraint companies_default_bank_account_fkey
+    foreign key (default_bank_account_id) references bank_accounts(id) on delete set null;
+
+-- The account also has to belong to this company, and that is a trigger
+-- rather than the composite key `(default_bank_account_id, id) references
+-- bank_accounts(id, company_id)` that says it in one line. The composite key
+-- works and its `on delete set null` does not: PostgreSQL nulls *every*
+-- referencing column, so deleting a bank account would try to null
+-- `companies.id`. A plain key keeps the friendly behaviour — withdrawing an
+-- account clears the default instead of refusing the delete — and the trigger
+-- keeps the guarantee.
+
+create or replace function companies_default_bank_account_is_ours()
+returns trigger
+language plpgsql
+as $$
+begin
+  if new.default_bank_account_id is not null
+     and not exists (select 1 from bank_accounts b
+                      where b.id = new.default_bank_account_id
+                        and b.company_id = new.id) then
+    raise exception 'foreign_bank_account: that bank account belongs to another company'
+      using errcode = '23503';
+  end if;
+  return new;
+end;
+$$;
+
+create trigger companies_default_bank_account_is_ours
+  before insert or update of default_bank_account_id on companies
+  for each row execute function companies_default_bank_account_is_ours();
+
+-- ---------------------------------------------------------------------------
+-- The currency of the capital, when nobody said
+-- ---------------------------------------------------------------------------
+
+create or replace function companies_default_capital_currency()
+returns trigger
+language plpgsql
+as $$
+begin
+  if new.share_capital is not null and new.share_capital_currency is null then
+    new.share_capital_currency := new.currency_code;
+  end if;
+  return new;
+end;
+$$;
+
+create trigger companies_default_capital_currency
+  before insert or update of share_capital, share_capital_currency, currency_code on companies
+  for each row execute function companies_default_capital_currency();
+
+comment on function companies_default_capital_currency() is
+  'A capital stated with no currency is stated in the company''s own. The alternative was a literal in the schema, which is one country''s answer given to every country.';
+
+-- ---------------------------------------------------------------------------
+-- The IBAN a sales document carries
+--
+-- A trigger and not a default on the column, for the reason the account of a
+-- document line is resolved in a trigger: every client that inserts a
+-- document has to get the same answer, and a client that did not know about
+-- the company default would produce an invoice nobody can pay.
+--
+-- Only on what the company issues. On a purchase invoice the payee is the
+-- supplier, and filling our own IBAN in there would be writing the wrong
+-- fact — worse than an empty column, because it looks right.
+-- ---------------------------------------------------------------------------
+
+create or replace function documents_default_payee_iban()
+returns trigger
+language plpgsql
+as $$
+declare
+  v_iban text;
+begin
+  if new.payee_iban is null and new.doc_type::text like 'sale%' then
+    select b.iban into v_iban
+      from companies c
+      join bank_accounts b on b.id = c.default_bank_account_id
+     where c.id = new.company_id;
+    new.payee_iban := v_iban;
+  end if;
+  return new;
+end;
+$$;
+
+create trigger documents_default_payee_iban
+  before insert on documents
+  for each row execute function documents_default_payee_iban();
+
+comment on function documents_default_payee_iban() is
+  'A sales document with no payee IBAN takes the company''s default bank account. A purchase document never does: the payee there is somebody else.';
+
+-- ---------------------------------------------------------------------------
+-- document_header — everything a renderer needs, in one read
+--
+-- The lines are `document_line_items`, the sentences are
+-- `document_legal_mentions`, and the third read a renderer had to invent for
+-- itself was the header: who issues, who receives, what is owed, where it is
+-- paid, and what the country of the document requires of it. Three views,
+-- three selects, and no client holding a copy of the company's letterhead.
+--
+-- `security_invoker`, like the other two: what a person may see through it is
+-- what they may see under it.
+-- ---------------------------------------------------------------------------
+
+create or replace view document_header
+  with (security_invoker = true) as
+  select d.id                             as document_id,
+         d.company_id,
+         d.doc_type,
+         d.state,
+         d.payment_state,
+         d.number,
+         d.supplier_reference,
+         d.document_date,
+         d.accounting_date,
+         d.due_date,
+         d.delivery_date,
+         d.currency_code,
+         d.amount_untaxed,
+         d.amount_tax,
+         d.amount_total,
+         d.amount_paid,
+         d.amount_residual,
+         d.payment_terms,
+         d.payment_means_code,
+         d.payment_reference,
+         d.buyer_reference,
+         d.order_reference,
+         d.contract_reference,
+         d.project_reference,
+         d.note,
+         -- BT-84: what the document says, else what the company's default
+         -- bank account says. The trigger fills it on the way in, so the
+         -- coalesce is what keeps a document written before this migration
+         -- true as well.
+         coalesce(d.payee_iban, seller_bank.iban) as payee_iban,
+         seller_bank.bic                          as payee_bic,
+
+         -- The seller: this company.
+         coalesce(c.trade_name, c.name)   as seller_name,
+         c.legal_name                     as seller_legal_name,
+         c.legal_form                     as seller_legal_form,
+         c.vat_number                     as seller_vat_number,
+         c.registration_number            as seller_registration_number,
+         c.address_line1                  as seller_address_line1,
+         c.address_line2                  as seller_address_line2,
+         c.postal_code                    as seller_postal_code,
+         c.city                           as seller_city,
+         c.country                        as seller_country,
+         c.region                         as seller_region,
+         c.email                          as seller_email,
+         c.phone                          as seller_phone,
+         c.website                        as seller_website,
+         c.logo_url                       as seller_logo_url,
+         c.share_capital                  as seller_share_capital,
+         c.share_capital_currency         as seller_share_capital_currency,
+         c.activity_code                  as seller_activity_code,
+         c.activity_scheme                as seller_activity_scheme,
+         c.document_template,
+
+         -- The buyer: the contact the document is written against.
+         ct.id                            as buyer_id,
+         ct.name                          as buyer_name,
+         ct.vat_number                    as buyer_vat_number,
+         ct.registration_number           as buyer_registration_number,
+         ct.address_line1                 as buyer_address_line1,
+         ct.address_line2                 as buyer_address_line2,
+         ct.postal_code                   as buyer_postal_code,
+         ct.city                          as buyer_city,
+         ct.country                       as buyer_country,
+         ct.region                        as buyer_region,
+         ct.email                         as buyer_email,
+
+         -- What the country of the document requires. Its country is the
+         -- company's fiscal_country — the country whose VAT rules apply — and
+         -- not its address, which is the same distinction
+         -- document_legal_mentions makes.
+         c.fiscal_country                 as country,
+         cd.number_format,
+         cd.numbering_gapless,
+         cd.legal_payment_days,
+         cd.late_payment_reference,
+         cd.tax_point_rule,
+         cd.einvoice_profile,
+         cd.einvoice_mandatory_from,
+         cd.party_scheme,
+         cd.vat_scheme
+    from documents d
+    join companies c                on c.id = d.company_id
+    join contacts ct                on ct.id = d.contact_id
+    left join bank_accounts seller_bank on seller_bank.id = c.default_bank_account_id
+    left join country_defaults cd   on cd.country = c.fiscal_country;
+
+comment on view document_header is
+  'One document with everything printed above its lines: the seller, the buyer, the amounts, where it is paid and what its country requires. The lines are document_line_items and the sentences are document_legal_mentions.';
+
+revoke execute on all functions in schema public from public;

package/dist/assets/migrations/20260913085436_numbering_reads_the_pack.sql

@@ -0,0 +1,235 @@
+-- Ekwo OS — the number a country asked for, instead of the one we built.
+--
+-- P0-7 put `number_format` and `numbering_gapless` on the country model and
+-- said, in as many words, that `next_entry_number()` did not read them: "a
+-- numbering engine that consumes a format is its own piece of work, and both
+-- packs declare exactly the pattern the engine already produces, so nothing
+-- moves under anybody's feet the day it lands." This is that piece of work.
+--
+-- **The grammar is the one already published**, in the comment on the column
+-- and in `packs/schema/pack.1.json`, and it is not reinvented here:
+--
+--   {CODE}   the journal code
+--   {YYYY}   the year, four digits — {YY} for two
+--   {MM}     the month, two digits
+--   {NNNN}   the counter, padded to as many N as are written
+--
+-- **There is no fallback.** A pack that declares no format gets
+-- `no_number_format`, naming `documents.number_format` — the field it has to
+-- fill — rather than `CODE/YYYY/NNNN`, which is Belgium's and France's answer
+-- handed to a country that has not spoken. It is the same rule `closing_style`
+-- and `fiscal_year_default` already keep, and the reason is the one P0-8 gave:
+-- a default is one country's law given to every country that has not said.
+--
+-- **The counter follows the pattern.** A pattern that carries the year
+-- restarts with it, which is what the four numbering styles of the pack
+-- format compile to; a pattern that carries none counts on for the life of
+-- the journal, and that series is kept under year 0 in `journal_sequences` —
+-- the counter is keyed by journal and period, and 0 is the period that is not
+-- a year. A `{MM}` in the pattern **prints** the month and does not restart
+-- the counter: a monthly series is a fifth style, no pack declares one, and
+-- inventing the behaviour before a pack asks for it is how a guess becomes a
+-- rule.
+--
+-- **`numbering_gapless` gets its reader too**, and it is `post_entry()`: where
+-- the law forbids a hole in the sequence, an entry may not be posted with a
+-- number chosen by hand, because a number that skips the counter is exactly
+-- how a hole appears. The core has no path that imports entries under their
+-- old numbers — an opening balance is a trial balance, not a journal — so
+-- nothing that exists is refused by this. The day such an import is written,
+-- this is the rule it will have to argue with.
+
+-- ---------------------------------------------------------------------------
+-- One reader for both columns
+-- ---------------------------------------------------------------------------
+
+create or replace function numbering_rules(
+  p_company_id uuid,
+  out number_format text,
+  out numbering_gapless boolean
+)
+language sql
+stable
+as $$
+  select d.number_format, coalesce(d.numbering_gapless, false)
+    from companies c
+    left join country_defaults d on d.country = c.fiscal_country
+   where c.id = p_company_id;
+$$;
+
+comment on function numbering_rules(uuid) is
+  'What the country of a company says about its document numbers: the pattern, and whether the law forbids a hole. The only function that reads either column.';
+
+-- ---------------------------------------------------------------------------
+-- Rendering one number
+--
+-- Separate from `next_entry_number()` so that the pattern can be tested
+-- without burning a counter, and so a document series of its own — which is
+-- not in this release — has the same renderer rather than a second one.
+-- ---------------------------------------------------------------------------
+
+create or replace function format_number(p_format text, p_code text, p_date date, p_number integer)
+returns text
+language plpgsql
+immutable
+as $$
+declare
+  v_out   text := p_format;
+  v_token text;
+  v_width integer;
+  v_digits text := p_number::text;
+  v_left  text;
+begin
+  if p_format is null or p_format = '' then
+    raise exception 'no_number_format: this country declares no documents.number_format, and there is no default to fall back on';
+  end if;
+
+  v_out := replace(v_out, '{CODE}', coalesce(p_code, ''));
+  v_out := replace(v_out, '{YYYY}', to_char(p_date, 'YYYY'));
+  v_out := replace(v_out, '{YY}',   to_char(p_date, 'YY'));
+  v_out := replace(v_out, '{MM}',   to_char(p_date, 'MM'));
+
+  v_token := (regexp_match(v_out, '\{N+\}'))[1];
+  if v_token is null then
+    raise exception 'number_format_without_counter: % carries no {N...} counter, so every document would be numbered the same', p_format;
+  end if;
+
+  -- Padded to the width the pattern asks for, and never truncated to it: a
+  -- counter that has outgrown its padding is a longer number, not a wrong one.
+  v_width := length(v_token) - 2;
+  v_out := replace(v_out, v_token,
+                   case when length(v_digits) >= v_width then v_digits
+                        else lpad(v_digits, v_width, '0') end);
+
+  v_left := (regexp_match(v_out, '\{[^}]*\}'))[1];
+  if v_left is not null then
+    raise exception 'unknown_number_token: % is not a token of the number format grammar ({CODE}, {YYYY}, {YY}, {MM}, {N...})', v_left;
+  end if;
+
+  return v_out;
+end;
+$$;
+
+comment on function format_number(text, text, date, integer) is
+  'One document number, rendered from the pattern the country pack declares. Raises rather than guessing at a token it does not know.';
+
+-- ---------------------------------------------------------------------------
+-- next_entry_number, on the pattern
+-- ---------------------------------------------------------------------------
+
+create or replace function next_entry_number(p_journal_id uuid, p_date date)
+returns text
+language plpgsql
+security definer
+set search_path = public, pg_temp
+as $$
+declare
+  v_code    text;
+  v_company uuid;
+  v_format  text;
+  v_period  smallint;
+  v_number  integer;
+begin
+  select j.code, j.company_id into v_code, v_company from journals j where j.id = p_journal_id;
+  if v_code is null then
+    raise exception 'unknown_journal: journal % does not exist', p_journal_id;
+  end if;
+
+  if auth.uid() is not null and not has_capability(v_company, 'entries.post') then
+    raise exception 'not_allowed: drawing a number in this company needs entries.post'
+      using errcode = '42501';
+  end if;
+
+  select number_format into v_format from numbering_rules(v_company);
+  if v_format is null or v_format = '' then
+    raise exception 'no_number_format: the country pack of this company declares no documents.number_format, and there is no default to fall back on';
+  end if;
+
+  -- A pattern that carries the year restarts with it; one that does not is a
+  -- single series, kept under the period that is not a year.
+  v_period := case when v_format ~ '\{(YYYY|YY)\}'
+                   then extract(year from p_date)::smallint
+                   else 0::smallint end;
+
+  insert into journal_sequences (journal_id, year, last_number)
+  values (p_journal_id, v_period, 1)
+  on conflict (journal_id, year)
+    do update set last_number = journal_sequences.last_number + 1
+  returning last_number into v_number;
+
+  return format_number(v_format, v_code, p_date, v_number);
+end;
+$$;
+
+comment on function next_entry_number(uuid, date) is
+  'Next number for a journal, on the pattern the country pack declares. Atomic: the counter row is locked, not the journal. Definer, because the counter is infrastructure and nobody writes it by hand.';
+
+comment on column journal_sequences.year is
+  'The period the counter belongs to: the year where the pattern carries one, and 0 where it does not and the series runs on.';
+
+-- ---------------------------------------------------------------------------
+-- post_entry, reading numbering_gapless
+--
+-- Unchanged but for the guard: everything else is the function as published.
+-- ---------------------------------------------------------------------------
+
+create or replace function post_entry(p_entry_id uuid)
+returns entries
+language plpgsql
+as $$
+declare
+  v_entry   entries%rowtype;
+  v_lines   integer;
+  v_gapless boolean;
+begin
+  select * into v_entry from entries where id = p_entry_id for update;
+  if not found then
+    raise exception 'unknown_entry: entry % does not exist', p_entry_id;
+  end if;
+  if v_entry.state = 'posted' then
+    return v_entry;
+  end if;
+  if v_entry.state = 'cancelled' then
+    raise exception 'entry_cancelled: entry % cannot be posted', p_entry_id;
+  end if;
+
+  select count(*) into v_lines from entry_lines where entry_id = p_entry_id;
+  if v_lines = 0 then
+    raise exception 'entry_empty: entry % has no lines', p_entry_id;
+  end if;
+
+  -- Re-read the totals maintained by the line trigger.
+  select * into v_entry from entries where id = p_entry_id;
+  if v_entry.total_debit <> v_entry.total_credit then
+    raise exception 'entry_unbalanced: entry % has debit % and credit %',
+      p_entry_id, v_entry.total_debit, v_entry.total_credit;
+  end if;
+
+  -- Where the law forbids a hole, the number comes from the counter and from
+  -- nowhere else. A number chosen by hand is how a sequence acquires one.
+  if v_entry.number is not null then
+    select numbering_gapless into v_gapless from numbering_rules(v_entry.company_id);
+    if v_gapless then
+      raise exception 'numbering_gapless: this country forbids a hole in the sequence, so entry % may not be posted under a number chosen by hand. Leave entries.number empty and the journal counter draws it',
+        p_entry_id;
+    end if;
+  end if;
+
+  perform assert_period_open(v_entry.company_id, v_entry.entry_date, true);
+
+  update entries
+     set number = coalesce(number, next_entry_number(journal_id, entry_date)),
+         fiscal_year_id = coalesce(fiscal_year_id, fiscal_year_at(company_id, entry_date)),
+         state = 'posted',
+         posted_at = now()
+   where id = p_entry_id
+  returning * into v_entry;
+
+  return v_entry;
+end;
+$$;
+
+comment on function post_entry(uuid) is
+  'Validates, numbers and posts an entry. Raises rather than warning: a swallowed error is a missing entry. Where the country forbids a hole in the sequence, it refuses a number chosen by hand.';
+
+revoke execute on all functions in schema public from public;