ekwo-os 0.4.1

package/dist/assets/migrations/20260911120000_core_companies.sql

@@ -0,0 +1,260 @@
+-- Ekwo OS — core: companies, membership, fiscal years.
+--
+-- One Ekwo instance belongs to one customer, so there is no `tenant_id`.
+-- Isolation inside an instance is carried by `company_id` plus row level
+-- security driven by `company_members`.
+
+-- gen_random_uuid() is in core Postgres since 13; no extension is needed.
+
+-- ---------------------------------------------------------------------------
+-- Shared helpers
+-- ---------------------------------------------------------------------------
+
+create or replace function set_updated_at()
+returns trigger
+language plpgsql
+as $$
+begin
+  new.updated_at := now();
+  return new;
+end;
+$$;
+
+comment on function set_updated_at() is
+  'Generic BEFORE UPDATE trigger keeping updated_at honest.';
+
+-- ---------------------------------------------------------------------------
+-- Enumerations
+-- ---------------------------------------------------------------------------
+
+create type member_role as enum ('owner', 'accountant', 'viewer');
+
+-- ---------------------------------------------------------------------------
+-- companies
+-- ---------------------------------------------------------------------------
+
+create table companies (
+  id                  uuid primary key default gen_random_uuid(),
+  name                text not null,
+  legal_name          text,
+  legal_form          text,
+  country             char(2) not null,
+  fiscal_country      char(2) not null,
+  vat_number          text,
+  registration_number text,
+  address_line1       text,
+  address_line2       text,
+  postal_code         text,
+  city                text,
+  email               text,
+  phone               text,
+  website             text,
+  currency_code       char(3) not null default 'EUR',
+  -- Period locks. No entry may be created, changed or deleted on or before
+  -- these dates. `tax_lock_date` additionally freezes anything carrying a
+  -- VAT declaration box.
+  lock_date           date,
+  tax_lock_date       date,
+  -- Default accounts, resolved by ROLE and never by code prefix.
+  -- Foreign keys are added once `accounts` exists.
+  receivable_account_id       uuid,
+  payable_account_id          uuid,
+  suspense_account_id         uuid,
+  rounding_account_id         uuid,
+  retained_earnings_account_id uuid,
+  sales_journal_id            uuid,
+  purchase_journal_id         uuid,
+  miscellaneous_journal_id    uuid,
+  created_at          timestamptz not null default now(),
+  updated_at          timestamptz not null default now(),
+  constraint companies_country_format check (country ~ '^[A-Z]{2}$'),
+  constraint companies_fiscal_country_format check (fiscal_country ~ '^[A-Z]{2}$'),
+  constraint companies_currency_format check (currency_code ~ '^[A-Z]{3}$')
+);
+
+comment on table companies is 'Legal entities kept in this instance. One instance may hold several.';
+comment on column companies.fiscal_country is 'Country whose VAT rules apply; differs from `country` for a foreign VAT registration.';
+comment on column companies.lock_date is 'Accounting lock: nothing may be booked on or before this date.';
+
+create trigger companies_set_updated_at
+  before update on companies
+  for each row execute function set_updated_at();
+
+-- ---------------------------------------------------------------------------
+-- company_members
+-- ---------------------------------------------------------------------------
+
+create table company_members (
+  company_id uuid not null references companies(id) on delete cascade,
+  user_id    uuid not null,
+  role       member_role not null default 'viewer',
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  primary key (company_id, user_id)
+);
+
+comment on table company_members is 'Who may read or write a company. `owner` administers, `accountant` books, `viewer` reads.';
+
+create index company_members_user_id_idx on company_members (user_id);
+
+create trigger company_members_set_updated_at
+  before update on company_members
+  for each row execute function set_updated_at();
+
+-- ---------------------------------------------------------------------------
+-- Access helpers
+--
+-- SECURITY DEFINER so that the policy on `company_members` itself does not
+-- recurse into the table it protects.
+-- ---------------------------------------------------------------------------
+
+create or replace function company_role(p_company_id uuid)
+returns member_role
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select m.role
+    from company_members m
+   where m.company_id = p_company_id
+     and m.user_id = auth.uid();
+$$;
+
+create or replace function is_company_member(p_company_id uuid)
+returns boolean
+language sql
+stable
+as $$
+  select company_role(p_company_id) is not null;
+$$;
+
+create or replace function can_write_company(p_company_id uuid)
+returns boolean
+language sql
+stable
+as $$
+  select company_role(p_company_id) in ('owner', 'accountant');
+$$;
+
+create or replace function is_company_owner(p_company_id uuid)
+returns boolean
+language sql
+stable
+as $$
+  select company_role(p_company_id) = 'owner';
+$$;
+
+comment on function company_role(uuid) is 'Role of the current user on a company, or NULL when they are not a member.';
+
+-- Bootstrap helper: the first member of a fresh company claims it. SECURITY
+-- DEFINER so the policy on company_members does not recurse into itself.
+create or replace function company_has_no_member(p_company_id uuid)
+returns boolean
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select not exists (select 1 from company_members m where m.company_id = p_company_id);
+$$;
+
+-- ---------------------------------------------------------------------------
+-- fiscal_years
+-- ---------------------------------------------------------------------------
+
+create table fiscal_years (
+  id           uuid primary key default gen_random_uuid(),
+  company_id   uuid not null references companies(id) on delete cascade,
+  name         text not null,
+  start_date   date not null,
+  end_date     date not null,
+  is_closed    boolean not null default false,
+  closed_at    timestamptz,
+  created_at   timestamptz not null default now(),
+  updated_at   timestamptz not null default now(),
+  constraint fiscal_years_dates check (end_date > start_date),
+  unique (company_id, start_date)
+);
+
+comment on table fiscal_years is 'Accounting periods. An exercise is an object, not two integers on the company.';
+
+create index fiscal_years_company_range_idx on fiscal_years (company_id, start_date, end_date);
+
+create trigger fiscal_years_set_updated_at
+  before update on fiscal_years
+  for each row execute function set_updated_at();
+
+-- Overlap guard. An exclusion constraint would need btree_gist, which is not
+-- available on every Postgres build (PGlite included), so this is a trigger.
+create or replace function fiscal_years_no_overlap()
+returns trigger
+language plpgsql
+as $$
+begin
+  if exists (
+    select 1
+      from fiscal_years f
+     where f.company_id = new.company_id
+       and f.id <> new.id
+       and f.start_date <= new.end_date
+       and f.end_date >= new.start_date
+  ) then
+    raise exception 'fiscal_year_overlap: % .. % overlaps an existing fiscal year of this company',
+      new.start_date, new.end_date
+      using errcode = '23505';
+  end if;
+  return new;
+end;
+$$;
+
+create trigger fiscal_years_no_overlap
+  before insert or update of start_date, end_date, company_id on fiscal_years
+  for each row execute function fiscal_years_no_overlap();
+
+create or replace function fiscal_year_at(p_company_id uuid, p_date date)
+returns uuid
+language sql
+stable
+as $$
+  select f.id
+    from fiscal_years f
+   where f.company_id = p_company_id
+     and p_date between f.start_date and f.end_date
+   limit 1;
+$$;
+
+comment on function fiscal_year_at(uuid, date) is 'Fiscal year covering a date, or NULL.';
+
+-- ---------------------------------------------------------------------------
+-- Row level security
+-- ---------------------------------------------------------------------------
+
+alter table companies       enable row level security;
+alter table company_members enable row level security;
+alter table fiscal_years    enable row level security;
+
+create policy companies_select on companies
+  for select using (is_company_member(id));
+create policy companies_insert on companies
+  for insert with check (auth.uid() is not null);
+create policy companies_update on companies
+  for update using (is_company_owner(id)) with check (is_company_owner(id));
+create policy companies_delete on companies
+  for delete using (is_company_owner(id));
+
+create policy company_members_select on company_members
+  for select using (user_id = auth.uid() or is_company_member(company_id));
+create policy company_members_insert on company_members
+  for insert with check (
+    is_company_owner(company_id) or company_has_no_member(company_id)
+  );
+create policy company_members_update on company_members
+  for update using (is_company_owner(company_id)) with check (is_company_owner(company_id));
+create policy company_members_delete on company_members
+  for delete using (is_company_owner(company_id));
+
+create policy fiscal_years_select on fiscal_years
+  for select using (is_company_member(company_id));
+create policy fiscal_years_write on fiscal_years
+  for all using (can_write_company(company_id)) with check (can_write_company(company_id));

package/dist/assets/migrations/20260911120100_accounts_journals.sql

@@ -0,0 +1,211 @@
+-- Ekwo OS — chart of accounts, journals, currencies.
+
+-- ---------------------------------------------------------------------------
+-- currencies (instance-wide reference data)
+-- ---------------------------------------------------------------------------
+
+create table currencies (
+  code           char(3) primary key,
+  name           text not null,
+  symbol         text,
+  decimal_places smallint not null default 2,
+  active         boolean not null default true,
+  constraint currencies_code_format check (code ~ '^[A-Z]{3}$'),
+  constraint currencies_decimals check (decimal_places between 0 and 6)
+);
+
+comment on table currencies is 'ISO 4217 currencies known to this instance.';
+
+create table currency_rates (
+  id            uuid primary key default gen_random_uuid(),
+  currency_code char(3) not null references currencies(code) on delete cascade,
+  rate_date     date not null,
+  -- Units of `currency_code` for one unit of the instance reference currency.
+  rate          numeric(18, 8) not null,
+  source        text,
+  created_at    timestamptz not null default now(),
+  unique (currency_code, rate_date),
+  constraint currency_rates_positive check (rate > 0)
+);
+
+comment on table currency_rates is 'Dated exchange rates. A document stores the rate it used; this table is the history.';
+
+-- ---------------------------------------------------------------------------
+-- accounts
+-- ---------------------------------------------------------------------------
+
+-- Eighteen account types. The prefix before the first underscore is the
+-- balance-sheet group, which is what makes the aged balance, reconcilability
+-- and the statement mapping computable instead of pattern-matched on codes.
+create type account_type as enum (
+  'asset_receivable',
+  'asset_cash',
+  'asset_current',
+  'asset_prepayments',
+  'asset_fixed',
+  'asset_non_current',
+  'liability_payable',
+  'liability_credit_card',
+  'liability_current',
+  'liability_non_current',
+  'equity',
+  'equity_retained',
+  'income',
+  'income_other',
+  'expense',
+  'expense_direct_cost',
+  'expense_depreciation',
+  'off_balance'
+);
+
+create table accounts (
+  id             uuid primary key default gen_random_uuid(),
+  company_id     uuid not null references companies(id) on delete cascade,
+  code           text not null,
+  name           text not null,
+  account_type   account_type not null,
+  internal_group text generated always as (
+    case
+      when account_type in ('asset_receivable', 'asset_cash', 'asset_current',
+                            'asset_prepayments', 'asset_fixed', 'asset_non_current')
+        then 'asset'
+      when account_type in ('liability_payable', 'liability_credit_card',
+                            'liability_current', 'liability_non_current')
+        then 'liability'
+      when account_type in ('equity', 'equity_retained') then 'equity'
+      when account_type in ('income', 'income_other') then 'income'
+      when account_type in ('expense', 'expense_direct_cost', 'expense_depreciation')
+        then 'expense'
+      else 'off_balance'
+    end
+  ) stored,
+  -- Balance-sheet accounts carry over from one fiscal year to the next.
+  carries_forward boolean generated always as (
+    account_type not in ('income', 'income_other', 'expense',
+                         'expense_direct_cost', 'expense_depreciation')
+  ) stored,
+  reconcilable   boolean not null default false,
+  currency_code  char(3) references currencies(code),
+  parent_id      uuid references accounts(id) on delete set null,
+  deprecated     boolean not null default false,
+  notes          text,
+  created_at     timestamptz not null default now(),
+  updated_at     timestamptz not null default now(),
+  unique (company_id, code),
+  -- A third-party account that cannot be matched makes the aged balance and
+  -- the FEC letters impossible. Refuse it at the door.
+  constraint accounts_third_party_reconcilable check (
+    account_type not in ('asset_receivable', 'liability_payable') or reconcilable
+  )
+);
+
+comment on table accounts is 'Chart of accounts, one per company.';
+comment on column accounts.internal_group is 'asset | liability | equity | income | expense | off_balance, derived from account_type.';
+comment on column accounts.reconcilable is 'Whether entry lines on this account may be matched against each other.';
+
+create index accounts_company_type_idx on accounts (company_id, account_type);
+create index accounts_parent_idx on accounts (parent_id);
+-- Composite target so children can inherit company_id by foreign key.
+create unique index accounts_id_company_idx on accounts (id, company_id);
+
+create trigger accounts_set_updated_at
+  before update on accounts
+  for each row execute function set_updated_at();
+
+-- ---------------------------------------------------------------------------
+-- journals
+-- ---------------------------------------------------------------------------
+
+create type journal_type as enum ('sales', 'purchase', 'bank', 'cash', 'general', 'opening');
+
+create table journals (
+  id                  uuid primary key default gen_random_uuid(),
+  company_id          uuid not null references companies(id) on delete cascade,
+  code                text not null,
+  name                text not null,
+  journal_type        journal_type not null,
+  default_account_id  uuid references accounts(id) on delete set null,
+  suspense_account_id uuid references accounts(id) on delete set null,
+  bank_account_id     uuid,
+  currency_code       char(3) references currencies(code),
+  active              boolean not null default true,
+  created_at          timestamptz not null default now(),
+  updated_at          timestamptz not null default now(),
+  unique (company_id, code),
+  constraint journals_code_format check (code ~ '^[A-Z0-9]{2,8}$')
+);
+
+comment on table journals is 'Books of entry. The code is the first segment of every entry number.';
+comment on column journals.suspense_account_id is 'Where a bank line lands before it is allocated.';
+
+create unique index journals_id_company_idx on journals (id, company_id);
+
+create trigger journals_set_updated_at
+  before update on journals
+  for each row execute function set_updated_at();
+
+-- Per journal AND per year counter. A single counter per journal would make
+-- the year in the number decorative; here the number means what it says.
+create table journal_sequences (
+  journal_id  uuid not null references journals(id) on delete cascade,
+  year        smallint not null,
+  last_number integer not null default 0,
+  primary key (journal_id, year),
+  constraint journal_sequences_positive check (last_number >= 0)
+);
+
+comment on table journal_sequences is 'Counter behind next_entry_number(). One row per journal and year.';
+
+-- ---------------------------------------------------------------------------
+-- Company default accounts and journals, now that the targets exist.
+-- ---------------------------------------------------------------------------
+
+alter table companies
+  add constraint companies_receivable_account_fkey
+    foreign key (receivable_account_id) references accounts(id) on delete set null,
+  add constraint companies_payable_account_fkey
+    foreign key (payable_account_id) references accounts(id) on delete set null,
+  add constraint companies_suspense_account_fkey
+    foreign key (suspense_account_id) references accounts(id) on delete set null,
+  add constraint companies_rounding_account_fkey
+    foreign key (rounding_account_id) references accounts(id) on delete set null,
+  add constraint companies_retained_earnings_account_fkey
+    foreign key (retained_earnings_account_id) references accounts(id) on delete set null,
+  add constraint companies_sales_journal_fkey
+    foreign key (sales_journal_id) references journals(id) on delete set null,
+  add constraint companies_purchase_journal_fkey
+    foreign key (purchase_journal_id) references journals(id) on delete set null,
+  add constraint companies_miscellaneous_journal_fkey
+    foreign key (miscellaneous_journal_id) references journals(id) on delete set null;
+
+-- ---------------------------------------------------------------------------
+-- Row level security
+-- ---------------------------------------------------------------------------
+
+alter table currencies        enable row level security;
+alter table currency_rates    enable row level security;
+alter table accounts          enable row level security;
+alter table journals          enable row level security;
+alter table journal_sequences enable row level security;
+
+-- Reference data: readable by anyone signed in, written by nobody through the
+-- API (seeds and migrations run as the table owner and bypass RLS).
+create policy currencies_select on currencies
+  for select using (auth.uid() is not null);
+create policy currency_rates_select on currency_rates
+  for select using (auth.uid() is not null);
+
+create policy accounts_select on accounts
+  for select using (is_company_member(company_id));
+create policy accounts_write on accounts
+  for all using (can_write_company(company_id)) with check (can_write_company(company_id));
+
+create policy journals_select on journals
+  for select using (is_company_member(company_id));
+create policy journals_write on journals
+  for all using (can_write_company(company_id)) with check (can_write_company(company_id));
+
+create policy journal_sequences_select on journal_sequences
+  for select using (
+    exists (select 1 from journals j where j.id = journal_id and is_company_member(j.company_id))
+  );

package/dist/assets/migrations/20260911120200_contacts.sql

@@ -0,0 +1,90 @@
+-- Ekwo OS — contacts (customers, suppliers, employees).
+
+create type contact_type as enum ('customer', 'supplier', 'both', 'employee', 'other');
+
+create table contacts (
+  id                   uuid primary key default gen_random_uuid(),
+  company_id           uuid not null references companies(id) on delete cascade,
+  name                 text not null,
+  contact_type         contact_type not null default 'customer',
+  is_company           boolean not null default true,
+  -- The entity actually invoiced, when this contact is a site or a person of
+  -- a larger group. Postings use the root of the chain.
+  parent_id            uuid references contacts(id) on delete set null,
+  vat_number           text,
+  registration_number  text,
+  -- Sub-ledger code. This is `CompAuxNum` of the French FEC.
+  auxiliary_code       text,
+  email                text,
+  phone                text,
+  address_line1        text,
+  address_line2        text,
+  postal_code          text,
+  city                 text,
+  country              char(2),
+  language             char(2),
+  currency_code        char(3) references currencies(code),
+  payment_terms_days   smallint not null default 30,
+  receivable_account_id uuid references accounts(id) on delete set null,
+  payable_account_id    uuid references accounts(id) on delete set null,
+  iban                 text,
+  bic                  text,
+  -- Peppol participant identifier, e.g. scheme 0208 + Belgian enterprise number.
+  peppol_scheme        text,
+  peppol_identifier    text,
+  active               boolean not null default true,
+  notes                text,
+  created_at           timestamptz not null default now(),
+  updated_at           timestamptz not null default now(),
+  constraint contacts_country_format check (country is null or country ~ '^[A-Z]{2}$'),
+  constraint contacts_payment_terms check (payment_terms_days >= 0),
+  constraint contacts_not_own_parent check (parent_id is null or parent_id <> id)
+);
+
+comment on table contacts is 'Third parties. `contact_type` is explicit rather than two hidden counters.';
+comment on column contacts.auxiliary_code is 'Sub-ledger code, exported as CompAuxNum in the FEC.';
+comment on column contacts.parent_id is 'Billing parent; commercial_entity() walks to the root.';
+
+create unique index contacts_company_auxiliary_code_idx
+  on contacts (company_id, auxiliary_code)
+  where auxiliary_code is not null;
+create index contacts_company_name_idx on contacts (company_id, name);
+create index contacts_parent_idx on contacts (parent_id);
+create unique index contacts_id_company_idx on contacts (id, company_id);
+
+create trigger contacts_set_updated_at
+  before update on contacts
+  for each row execute function set_updated_at();
+
+-- The billable entity: the root of the parent chain.
+create or replace function commercial_entity(p_contact_id uuid)
+returns uuid
+language plpgsql
+stable
+as $$
+declare
+  v_id     uuid := p_contact_id;
+  v_parent uuid;
+  v_guard  int := 0;
+begin
+  loop
+    select parent_id into v_parent from contacts where id = v_id;
+    exit when v_parent is null;
+    v_id := v_parent;
+    v_guard := v_guard + 1;
+    if v_guard > 32 then
+      raise exception 'contact_parent_cycle: contact % has a cyclic or too deep parent chain', p_contact_id;
+    end if;
+  end loop;
+  return v_id;
+end;
+$$;
+
+comment on function commercial_entity(uuid) is 'Root of the contact parent chain; the entity a document is booked against.';
+
+alter table contacts enable row level security;
+
+create policy contacts_select on contacts
+  for select using (is_company_member(company_id));
+create policy contacts_write on contacts
+  for all using (can_write_company(company_id)) with check (can_write_company(company_id));