ekwo-os 0.4.1

package/dist/assets/migrations/20260911121000_reporting.sql

@@ -0,0 +1,235 @@
+-- Ekwo OS — the reports the schema exists for.
+--
+-- Every one of them filters posted entries in the WHERE clause, never in a
+-- LEFT JOIN condition: a draft line that survives an outer join is how a
+-- trial balance silently stops tying out.
+
+-- ---------------------------------------------------------------------------
+-- trial_balance
+-- ---------------------------------------------------------------------------
+
+create or replace function trial_balance(
+  p_company_id uuid,
+  p_from       date,
+  p_to         date
+)
+returns table (
+  account_id       uuid,
+  account_code     text,
+  account_name     text,
+  account_type     account_type,
+  internal_group   text,
+  opening_balance  numeric,
+  debit            numeric,
+  credit           numeric,
+  closing_balance  numeric
+)
+language sql
+stable
+as $$
+  select a.id,
+         a.code,
+         a.name,
+         a.account_type,
+         a.internal_group,
+         coalesce(sum(l.balance) filter (where e.entry_date < p_from), 0)::numeric as opening_balance,
+         coalesce(sum(l.debit)   filter (where e.entry_date between p_from and p_to), 0)::numeric as debit,
+         coalesce(sum(l.credit)  filter (where e.entry_date between p_from and p_to), 0)::numeric as credit,
+         coalesce(sum(l.balance) filter (where e.entry_date <= p_to), 0)::numeric as closing_balance
+    from accounts a
+    left join entry_lines l on l.account_id = a.id
+    left join entries e on e.id = l.entry_id and e.state = 'posted'
+   where a.company_id = p_company_id
+     -- Kill the outer-join leak: a line whose entry is not posted is dropped.
+     and (l.id is null or e.id is not null)
+     and (e.id is null or e.entry_date <= p_to)
+   group by a.id, a.code, a.name, a.account_type, a.internal_group
+   order by a.code;
+$$;
+
+comment on function trial_balance(uuid, date, date) is
+  'Opening balance, movements of the period and closing balance per account, posted entries only.';
+
+-- ---------------------------------------------------------------------------
+-- general_ledger
+-- ---------------------------------------------------------------------------
+
+create or replace function general_ledger(
+  p_company_id uuid,
+  p_from       date,
+  p_to         date,
+  p_account_ids uuid[] default null
+)
+returns table (
+  account_id      uuid,
+  account_code    text,
+  account_name    text,
+  entry_line_id   uuid,
+  entry_id        uuid,
+  entry_number    text,
+  entry_date      date,
+  journal_code    text,
+  reference       text,
+  line_name       text,
+  contact_name    text,
+  debit           numeric,
+  credit          numeric,
+  matching_number text,
+  running_balance numeric
+)
+language sql
+stable
+as $$
+  with opening as (
+    select l.account_id, sum(l.balance) as balance
+      from entry_lines l
+      join entries e on e.id = l.entry_id
+     where l.company_id = p_company_id
+       and e.state = 'posted'
+       and e.entry_date < p_from
+     group by l.account_id
+  ),
+  movements as (
+    select l.id, l.account_id, l.entry_id, e.number, e.entry_date, j.code as journal_code,
+           e.reference, l.name, c.name as contact_name, l.debit, l.credit, l.balance,
+           l.matching_number, l.sequence
+      from entry_lines l
+      join entries e on e.id = l.entry_id
+      join journals j on j.id = e.journal_id
+      left join contacts c on c.id = l.contact_id
+     where l.company_id = p_company_id
+       and e.state = 'posted'
+       and e.entry_date between p_from and p_to
+  )
+  select a.id, a.code, a.name,
+         m.id, m.entry_id, m.number, m.entry_date, m.journal_code, m.reference,
+         m.name, m.contact_name, m.debit, m.credit, m.matching_number,
+         (coalesce(o.balance, 0)
+          + sum(m.balance) over (partition by a.id
+                                 order by m.entry_date, m.number, m.sequence, m.id
+                                 rows between unbounded preceding and current row))::numeric
+    from movements m
+    join accounts a on a.id = m.account_id
+    left join opening o on o.account_id = a.id
+   where p_account_ids is null or a.id = any (p_account_ids)
+   order by a.code, m.entry_date, m.number, m.sequence, m.id;
+$$;
+
+comment on function general_ledger(uuid, date, date, uuid[]) is
+  'Posted lines of a period per account, with the balance carried forward from before the period.';
+
+-- ---------------------------------------------------------------------------
+-- aged_balance
+--
+-- Read from the ledger and from what is still unmatched, not from documents.
+-- An aged balance built on invoices can never tie back to the balance sheet.
+-- ---------------------------------------------------------------------------
+
+create or replace function aged_balance(
+  p_company_id uuid,
+  p_at         date default current_date,
+  p_group      text default 'receivable'
+)
+returns table (
+  contact_id   uuid,
+  contact_name text,
+  account_id   uuid,
+  account_code text,
+  not_due      numeric,
+  days_1_30    numeric,
+  days_31_60   numeric,
+  days_61_90   numeric,
+  days_over_90 numeric,
+  total        numeric
+)
+language sql
+stable
+as $$
+  with open_lines as (
+    select l.contact_id,
+           l.account_id,
+           case when p_group = 'payable' then -l.balance else l.balance end
+             * (case when abs(l.balance) = 0 then 0
+                     else (abs(l.balance) - l.matched_amount) / abs(l.balance) end) as residual,
+           coalesce(l.date_maturity, e.entry_date) as due_date
+      from entry_lines l
+      join entries e on e.id = l.entry_id
+      join accounts a on a.id = l.account_id
+     where l.company_id = p_company_id
+       and e.state = 'posted'
+       and e.entry_date <= p_at
+       and a.reconcilable
+       and a.account_type = case when p_group = 'payable'
+                                 then 'liability_payable'::account_type
+                                 else 'asset_receivable'::account_type end
+       and abs(l.balance) - l.matched_amount > 0.005
+  )
+  select o.contact_id,
+         c.name,
+         o.account_id,
+         a.code,
+         round(sum(o.residual) filter (where o.due_date >= p_at), 2),
+         round(sum(o.residual) filter (where p_at - o.due_date between 1 and 30), 2),
+         round(sum(o.residual) filter (where p_at - o.due_date between 31 and 60), 2),
+         round(sum(o.residual) filter (where p_at - o.due_date between 61 and 90), 2),
+         round(sum(o.residual) filter (where p_at - o.due_date > 90), 2),
+         round(sum(o.residual), 2)
+    from open_lines o
+    left join contacts c on c.id = o.contact_id
+    join accounts a on a.id = o.account_id
+   group by o.contact_id, c.name, o.account_id, a.code
+   order by c.name nulls last;
+$$;
+
+comment on function aged_balance(uuid, date, text) is
+  'Open receivables (or payables) by age, from unmatched ledger lines. p_group is ''receivable'' or ''payable''.';
+
+-- ---------------------------------------------------------------------------
+-- vat_return
+--
+-- Aggregates whatever the tax postings wrote on the lines. No country rule
+-- lives here: boxes come from the data.
+--
+-- This function was published with the two balance boxes of the Belgian frame
+-- VI computed inline, behind a test on the company's fiscal country. That was
+-- the one country rule left in the core, and it was removed from this file on
+-- 12 September 2026 rather than only overridden later: no installation
+-- anywhere had run it, and a country literal in a published migration is a
+-- country literal in the repository. The totals now come from the declaration
+-- form of the country pack, in `20260912090407_tax_report_boxes`, which
+-- replaces this function.
+-- ---------------------------------------------------------------------------
+
+create or replace function vat_return(
+  p_company_id uuid,
+  p_from       date,
+  p_to         date
+)
+returns table (
+  box      text,
+  kind     text,
+  amount   numeric,
+  computed boolean
+)
+language sql
+stable
+as $$
+  with boxes as (
+    select l.declaration_box as box,
+           case when l.tax_line then 'tax' else 'base' end as kind,
+           round(sum(l.box_amount), 2) as amount
+      from entry_lines l
+      join entries e on e.id = l.entry_id
+     where l.company_id = p_company_id
+       and e.state = 'posted'
+       and e.entry_date between p_from and p_to
+       and l.declaration_box is not null
+     group by 1, 2
+    having round(sum(l.box_amount), 2) <> 0
+  )
+  select b.box, b.kind, b.amount, false from boxes b
+   order by 1, 2;
+$$;
+
+comment on function vat_return(uuid, date, date) is
+  'VAT return boxes for a period, summed from the declaration boxes written on the ledger lines.';

package/dist/assets/migrations/20260911121100_country_templates.sql

@@ -0,0 +1,226 @@
+-- Ekwo OS — country templates.
+--
+-- The chart of accounts, the journals and the taxes of a country are
+-- reference data, not code. `install_country_template()` copies them into a
+-- company. Seeds fill the templates; nothing here is country specific.
+
+create table account_templates (
+  id           uuid primary key default gen_random_uuid(),
+  country      char(2) not null,
+  code         text not null,
+  name         text not null,
+  account_type account_type not null,
+  reconcilable boolean not null default false,
+  parent_code  text,
+  sequence     integer not null default 10,
+  unique (country, code),
+  constraint account_templates_country_format check (country ~ '^[A-Z]{2}$'),
+  constraint account_templates_third_party_reconcilable check (
+    account_type not in ('asset_receivable', 'liability_payable') or reconcilable
+  )
+);
+
+comment on table account_templates is 'Reference charts of accounts, one set per country.';
+
+create table journal_templates (
+  id           uuid primary key default gen_random_uuid(),
+  country      char(2) not null,
+  code         text not null,
+  name         text not null,
+  journal_type journal_type not null,
+  sequence     integer not null default 10,
+  unique (country, code)
+);
+
+create table tax_templates (
+  id              uuid primary key default gen_random_uuid(),
+  country         char(2) not null,
+  code            text not null,
+  name            text not null,
+  description     text,
+  amount_type     tax_amount_type not null default 'percent',
+  amount          numeric(12, 4) not null default 0,
+  applies_to      tax_scope not null default 'both',
+  treatment       tax_treatment not null default 'domestic',
+  valid_from      date not null default date '1970-01-01',
+  valid_to        date,
+  legal_reference text,
+  vat_category    char(2),
+  exemption_code  text,
+  sequence        integer not null default 10,
+  unique (country, code)
+);
+
+comment on table tax_templates is 'Reference taxes per country, with their period of validity.';
+
+create table tax_posting_templates (
+  id                 uuid primary key default gen_random_uuid(),
+  tax_template_id    uuid not null references tax_templates(id) on delete cascade,
+  document_kind      tax_document_kind not null default 'invoice',
+  posting_type       tax_posting_type not null,
+  factor_percent     numeric(7, 3) not null default 100,
+  account_code       text,
+  declaration_box    text,
+  box_factor_percent numeric(7, 3) not null default 100,
+  sequence           integer not null default 10,
+  constraint tax_posting_templates_base_has_no_account check (
+    posting_type <> 'base' or account_code is null
+  ),
+  constraint tax_posting_templates_tax_has_account check (
+    posting_type <> 'tax' or account_code is not null
+  )
+);
+
+create unique index tax_posting_templates_one_base_idx
+  on tax_posting_templates (tax_template_id, document_kind) where posting_type = 'base';
+
+create table country_defaults (
+  country                 char(2) primary key,
+  name                    text not null,
+  currency_code           char(3) not null default 'EUR',
+  receivable_code         text not null,
+  payable_code            text not null,
+  suspense_code           text,
+  rounding_code           text,
+  retained_earnings_code  text,
+  sales_account_code      text,
+  purchase_account_code   text,
+  bank_account_code       text,
+  sales_journal_code      text not null default 'SAL',
+  purchase_journal_code   text not null default 'PUR',
+  misc_journal_code       text not null default 'MISC'
+);
+
+comment on table country_defaults is 'Which template account plays which role, per country.';
+
+-- ---------------------------------------------------------------------------
+-- Helpers
+-- ---------------------------------------------------------------------------
+
+create or replace function account_id_by_code(p_company_id uuid, p_code text)
+returns uuid
+language sql
+stable
+as $$
+  select id from accounts where company_id = p_company_id and code = p_code;
+$$;
+
+comment on function account_id_by_code(uuid, text) is 'Account of a company by its code, or NULL.';
+
+-- ---------------------------------------------------------------------------
+-- install_country_template
+-- ---------------------------------------------------------------------------
+
+create or replace function install_country_template(
+  p_company_id uuid,
+  p_country    char(2)
+)
+returns void
+language plpgsql
+as $$
+declare
+  v_defaults country_defaults%rowtype;
+  r          record;
+  v_tax_id   uuid;
+begin
+  if not exists (select 1 from companies where id = p_company_id) then
+    raise exception 'unknown_company: %', p_company_id;
+  end if;
+  if not exists (select 1 from account_templates where country = p_country) then
+    raise exception 'unknown_country_template: no chart of accounts seeded for %', p_country;
+  end if;
+
+  -- 1. Accounts, without the hierarchy.
+  insert into accounts (company_id, code, name, account_type, reconcilable)
+  select p_company_id, t.code, t.name, t.account_type, t.reconcilable
+    from account_templates t
+   where t.country = p_country
+  on conflict (company_id, code) do nothing;
+
+  -- 2. Hierarchy, now that every code exists.
+  update accounts a
+     set parent_id = p.id
+    from account_templates t
+    join accounts p on p.company_id = p_company_id and p.code = t.parent_code
+   where a.company_id = p_company_id
+     and a.code = t.code
+     and t.country = p_country
+     and t.parent_code is not null
+     and a.parent_id is null;
+
+  -- 3. Journals.
+  insert into journals (company_id, code, name, journal_type)
+  select p_company_id, t.code, t.name, t.journal_type
+    from journal_templates t
+   where t.country = p_country
+  on conflict (company_id, code) do nothing;
+
+  -- 4. Taxes and their postings.
+  for r in
+    select * from tax_templates where country = p_country order by sequence, code
+  loop
+    v_tax_id := null;
+    insert into taxes (company_id, code, name, description, amount_type, amount,
+                       applies_to, treatment, country, valid_from, valid_to,
+                       legal_reference, vat_category, exemption_code, sequence)
+    values (p_company_id, r.code, r.name, r.description, r.amount_type, r.amount,
+            r.applies_to, r.treatment, p_country, r.valid_from, r.valid_to,
+            r.legal_reference, r.vat_category, r.exemption_code, r.sequence)
+    on conflict (company_id, code) do nothing
+    returning id into v_tax_id;
+
+    if v_tax_id is null then
+      continue;
+    end if;
+
+    insert into tax_postings (tax_id, company_id, document_kind, posting_type,
+                              factor_percent, account_id, declaration_box,
+                              box_factor_percent, sequence)
+    select v_tax_id, p_company_id, tp.document_kind, tp.posting_type,
+           tp.factor_percent, account_id_by_code(p_company_id, tp.account_code),
+           tp.declaration_box, tp.box_factor_percent, tp.sequence
+      from tax_posting_templates tp
+     where tp.tax_template_id = r.id
+     order by tp.sequence;
+  end loop;
+
+  -- 5. Roles.
+  select * into v_defaults from country_defaults where country = p_country;
+  if found then
+    update companies c
+       set receivable_account_id       = coalesce(c.receivable_account_id, account_id_by_code(p_company_id, v_defaults.receivable_code)),
+           payable_account_id          = coalesce(c.payable_account_id, account_id_by_code(p_company_id, v_defaults.payable_code)),
+           suspense_account_id         = coalesce(c.suspense_account_id, account_id_by_code(p_company_id, v_defaults.suspense_code)),
+           rounding_account_id         = coalesce(c.rounding_account_id, account_id_by_code(p_company_id, v_defaults.rounding_code)),
+           retained_earnings_account_id = coalesce(c.retained_earnings_account_id, account_id_by_code(p_company_id, v_defaults.retained_earnings_code)),
+           sales_journal_id            = coalesce(c.sales_journal_id, (select id from journals where company_id = p_company_id and code = v_defaults.sales_journal_code)),
+           purchase_journal_id         = coalesce(c.purchase_journal_id, (select id from journals where company_id = p_company_id and code = v_defaults.purchase_journal_code)),
+           miscellaneous_journal_id    = coalesce(c.miscellaneous_journal_id, (select id from journals where company_id = p_company_id and code = v_defaults.misc_journal_code))
+     where c.id = p_company_id;
+  end if;
+end;
+$$;
+
+comment on function install_country_template(uuid, char) is
+  'Copies a country chart of accounts, journals and taxes into a company and wires the default roles.';
+
+-- ---------------------------------------------------------------------------
+-- Row level security
+-- ---------------------------------------------------------------------------
+
+alter table account_templates      enable row level security;
+alter table journal_templates      enable row level security;
+alter table tax_templates          enable row level security;
+alter table tax_posting_templates  enable row level security;
+alter table country_defaults       enable row level security;
+
+create policy account_templates_select on account_templates
+  for select using (auth.uid() is not null);
+create policy journal_templates_select on journal_templates
+  for select using (auth.uid() is not null);
+create policy tax_templates_select on tax_templates
+  for select using (auth.uid() is not null);
+create policy tax_posting_templates_select on tax_posting_templates
+  for select using (auth.uid() is not null);
+create policy country_defaults_select on country_defaults
+  for select using (auth.uid() is not null);

package/dist/assets/migrations/20260911121200_fec.sql

@@ -0,0 +1,71 @@
+-- Ekwo OS — the French FEC, as a query.
+--
+-- Eighteen columns fixed by the arrete du 29 juillet 2013 (art. A. 47 A-1 du
+-- LPF). The schema was shaped so this needs no application logic: the letter
+-- comes from `reconciliations`, the sub-ledger code from
+-- `contacts.auxiliary_code`, the validation date from `entries.posted_at`.
+
+create or replace function fec_lines(
+  p_company_id uuid,
+  p_from       date,
+  p_to         date
+)
+returns table (
+  journal_code   text,
+  journal_lib    text,
+  ecriture_num   text,
+  ecriture_date  date,
+  compte_num     text,
+  compte_lib     text,
+  comp_aux_num   text,
+  comp_aux_lib   text,
+  piece_ref      text,
+  piece_date     date,
+  ecriture_lib   text,
+  debit          numeric,
+  credit         numeric,
+  ecriture_let   text,
+  date_let       date,
+  valid_date     date,
+  montant_devise numeric,
+  idevise        text
+)
+language sql
+stable
+as $$
+  select j.code,
+         j.name,
+         e.number,
+         e.entry_date,
+         a.code,
+         a.name,
+         c.auxiliary_code,
+         case when c.auxiliary_code is not null then c.name end,
+         coalesce(d.number, d.supplier_reference, e.reference, e.number),
+         coalesce(d.document_date, e.entry_date),
+         coalesce(nullif(l.name, ''), e.description, a.name),
+         l.debit,
+         l.credit,
+         l.matching_number,
+         (select max(r.matched_at) from reconciliations r
+           where r.debit_line_id = l.id or r.credit_line_id = l.id),
+         coalesce(e.posted_at::date, e.entry_date),
+         case when l.currency_code is not null and l.currency_code <> co.currency_code
+              then l.amount_currency end,
+         case when l.currency_code is not null and l.currency_code <> co.currency_code
+              then l.currency_code end
+    from entry_lines l
+    join entries e   on e.id = l.entry_id
+    join journals j  on j.id = e.journal_id
+    join accounts a  on a.id = l.account_id
+    join companies co on co.id = l.company_id
+    left join contacts c on c.id = l.contact_id
+    left join documents d on d.id = e.document_id
+   where l.company_id = p_company_id
+     and e.state = 'posted'
+     and e.entry_date between p_from and p_to
+   order by e.entry_date, e.number, l.sequence, l.id;
+$$;
+
+comment on function fec_lines(uuid, date, date) is
+  'The eighteen columns of the French FEC for a period, in chronological order.';

package/dist/assets/migrations/20260911130000_instance.sql

@@ -0,0 +1,77 @@
+-- Ekwo OS — the instance itself.
+--
+-- One installation belongs to one customer, so the installation is a fact
+-- worth recording: who it belongs to, which country's rules it was set up
+-- for, which edition it runs, and which schema version it was installed at.
+-- Exactly one row, forever. There is no `tenant_id` anywhere in this schema
+-- and this table is the reason: the instance IS the tenant.
+--
+-- Registration with Ekwo is an opt-in. `contact_email` and `registered_at`
+-- are empty on a fresh install, nothing writes them without the operator
+-- asking, and nothing in the software checks them. Community works
+-- unregistered, forever.
+
+-- The instance-level role. A new enum value cannot be used in the same
+-- transaction that adds it, so the table that constrains it lives in the
+-- next migration.
+alter type member_role add value if not exists 'instance_admin';
+
+create type instance_edition as enum ('community', 'cloud');
+
+-- The schema version this release ships. Bumped by a migration at each
+-- release; `ekwo migrate` writes it back onto the instance row.
+create or replace function ekwo_schema_version()
+returns text
+language sql
+immutable
+as $$
+  select '0.1.0'::text;
+$$;
+
+comment on function ekwo_schema_version() is
+  'Schema version of the installed release. Bumped by a migration, never by hand.';
+
+create table instance (
+  -- Singleton. The primary key and the check together make a second row
+  -- impossible, rather than merely unusual.
+  id                smallint primary key default 1,
+  instance_id       uuid not null unique default gen_random_uuid(),
+  organization_name text not null,
+  country           char(2) not null,
+  edition           instance_edition not null default 'community',
+  schema_version    text not null default ekwo_schema_version(),
+  installed_at      timestamptz not null default now(),
+  -- Opt-in registration with Ekwo. Empty by default, never a condition of
+  -- use, never checked by anything in this repository.
+  contact_email     text,
+  registered_at     timestamptz,
+  updated_at        timestamptz not null default now(),
+  constraint instance_singleton check (id = 1),
+  constraint instance_country_format check (country ~ '^[A-Z]{2}$'),
+  constraint instance_registration_needs_an_address check (
+    registered_at is null or contact_email is not null
+  )
+);
+
+comment on table instance is
+  'The installation itself. Exactly one row. Registration with Ekwo is optional and empty by default.';
+comment on column instance.instance_id is
+  'Stable identifier of this installation, generated locally. Never a licence key.';
+comment on column instance.edition is
+  'community when you run it yourself, cloud when Ekwo operates it. Gates nothing in this repository.';
+comment on column instance.schema_version is
+  'Version of the schema at install, updated by migrations.';
+comment on column instance.contact_email is
+  'Opt-in only: an address to reach the operator. Empty unless they asked to register.';
+comment on column instance.registered_at is
+  'Opt-in only: when the operator registered with Ekwo. Empty means not registered, which is a supported state.';
+
+create trigger instance_set_updated_at
+  before update on instance
+  for each row execute function set_updated_at();
+
+alter table instance enable row level security;
+
+-- Anyone signed into this installation may see which installation it is.
+create policy instance_select on instance
+  for select using (auth.uid() is not null);