Changelog
All notable changes to Foresi are documented in this file.
The format is based on Keep a Changelog, and Foresi adheres to Semantic Versioning.
[Unreleased]
Section titled “[Unreleased]”Planned as 0.5.0: the first release with invoices.
Upgrading
Section titled “Upgrading”- Saved views: run
bin/console doctrine:migrations:migrate, which adds thesaved_viewtable, and thenbin/console app:views:syncon every deploy and install. The command stores the views the installed modules ship, such as the tabs of the invoice lists, and leaves alone a view someone edited or hid; running it again changes nothing. Until it runs, the lists show their default views as declared. - Breaking: the modules move from the PHP namespace
App\toForesi\(App\Work\is nowForesi\Work\, the kernelForesi\Kernel, the testsForesi\Tests\), before the first release, as ADR 0034 decided. Code that uses a module class must change its imports, andKERNEL_CLASSin.env.testbecomesForesi\Kernel. Stop the workers and let the queues drain before you deploy: a message still waiting names the old classes and cannot be read afterwards, so it goes to the failed transport. Then runcomposer installandbin/console doctrine:migrations:migrate, which renames the class names stored in the audit log. Signed-in users sign in again. - Breaking for modules: ports that another module serves collect their providers by tag instead of an alias in
config/services.yaml, so a module runs when the one behind its port is absent (ADR 0034, rule 3).Foresi\Work\Application\InvoiceNumbersmoves toForesi\Work\Contract\InvoiceNumbersandForesi\Party\Application\BankAccountUsagetoForesi\Party\Contract\BankAccountUsage. A class that implements one of them, orBilledWork,BilledWorkRelease,PaymentSourceRelease,ZoneFallback,CompanyRegistryorVatPayerReliability, is now one provider among others: it is tagged by autoconfiguration and needs no alias. - Run
bin/console doctrine:migrations:migrate. The new tables hold series, number counters, invoices, their lines and the numbers an edit gave up. - Install the PHP extensions
gd(the QR code and images),dom(the ISDOC file) andzip(the bulk download), which are now required, and runcomposer installto get the new PDF library,tecnickcom/tc-lib-pdf(LGPL-3.0-or-later). The PDF fonts (Inter, SIL Open Font License) are part of the repository. - Images of a firm are kept in the
firm-imagesdirectory of the application’s share directory (var/share/<env>/firm-images), set by the new parameterapp.firm_image_dir. They are outside the web root and outside the database, so include the directory in backups. - SQLite must be 3.35 or newer.
- Sending by e-mail adds
symfony/mailerandsymfony/scheduler, and requires the PHP extensionsodium. SetMAIL_SECRET_KEYS(keys that seal the firms’ mail server passwords) andDEFAULT_URI(the public https address that links in mail lead to). See docs/sending.md. - The worker command is now
messenger:consume scheduler_foresi mail async registry --memory-limit=256M --time-limit=3600: it delivers mail and runs the timed jobs. Update your systemd or supervisor unit. - PDFs as sent are kept in
var/share/<env>/sent-documents. Include that directory in backups, together with the database. - Recurring invoices and reminders run in the same worker, from the
scheduler_foresitransport; no new process is needed. Their day follows the organisation’s time zone, by default the zone of its first active firm’s country. Set another withAPP_TIMEZONE(see below). - The tests of the PDF and of the ISDOC file use veraPDF, Poppler and the ISDOC schema when they are installed (see CONTRIBUTING.md); CI requires them.
- A firm’s bank accounts move from the list on the firm into records of their own. The migration keeps their order and makes the first one the primary account. The list held no currency, so each account gets the home currency of the firm’s country: CZK in Czechia, EUR in a euro-area country and USD in the United States. A firm in any other country gets CZK. Check the currency of each account in the firm’s bank settings, and correct it for an account kept in another currency.
- Breaking for country modules: the public interface
InvoicingCountryhas a new method,settlementLimit(Currency $currency): ?int, the most minor units a firm of the country may write off on an invoice in the currency, or null for none. A third-party country module must implement it; return null to keep small differences unsettled. - Payments and bank pairing add
zbateson/mail-mime-parser(BSD-2-Clause), which reads bank e-mail, anddirectorytree/imapengine(MIT), which polls the bank inbox; runcomposer install. The worker command is unchanged. - Bank e-mail is off until it is set up. The new environment variables are all empty by default:
BANK_INBOX_ADDRESS(the address template with{token}, such asbank+{token}@example.com; the mailbox must deliver plus addresses),BANK_INBOX_TRUSTED_AUTHSERV(the authserv-id of the inbox’s own receiving server, which must addAuthentication-Resultsat the top of every message),BANK_INBOX_TRUSTED_ARC(trusted ARC sealers),BANK_INBOX_HOST,BANK_INBOX_PORT(993),BANK_INBOX_ENCRYPTION(sslorstarttls),BANK_INBOX_USER,BANK_INBOX_PASSWORD,BANK_INBOX_FOLDER(INBOX) andINBOUND_WEBHOOK_SECRET(the bearer secret of the optional webhookPOST /inbound/mail). Inbound addresses are sealed withMAIL_SECRET_KEYS. See docs/bank-pairing.md. - Raw bank e-mails are kept in
var/share/<env>/inbound-mail, as the evidence of the payments recorded from them. Include that directory in backups, together with the database. - Advances add columns to
invoice,invoice_lineandfirm_reminders; run the migrations. Every stored document stays an invoice. A firm gets the standard series of advance invoices (Z9{YYYY}{NNNN}) and of tax documents on payment (D8{YYYY}{NNNN}) on first use; set up others under the firm’s invoicing settings before the first advance if you number differently. - Corrective tax documents add columns to
invoiceandpayment; run the migrations. Every stored payment is incoming. A firm gets the standard series of corrective tax documents (O7{YYYY}{NNNN}) on first use. - The export state adds the columns
exported_atandchanged_after_export_attoinvoice, and the month filter an index on a firm’s documents by tax point; run the migrations. Every stored document starts as not exported, so the first pack of a month takes all its documents. - Projects and tasks add the tables
project,project_status,project_section,task,task_watcher,task_labelandlabel; run the migrations. - Received documents add the tables
received_document,evidence_series,evidence_counterandexchange_rate; run the migrations. Original files are attachments in theattachmentsdirectory of the share directory, which the backups already include. The worker must reachwww.cnb.czto fetch the ČNB rates daily (the jobexchange-rates, after 14:35 Prague time); without it a rate has to be typed by hand. See docs/operations.md and docs/purchasing.md. - Comments and attachments add the tables
task_comment,comment_mentionandattachment; run the migrations. Attached files are kept invar/share/<env>/attachments, outside the web root and the database: include that directory in backups, together with the database (ops/backup.shalready covers the share directory). - People add the table
invitationand the columndisabled_attomembership; run the migrations. Every existing membership stays active. Invitations are mailed through the system mail (SYSTEM_MAILER_DSN,SYSTEM_MAIL_FROM); without it the owner passes the link on. - The roles are now owner, team member and guest: the migrations turn every client and subcontractor membership into a guest one, who sees only what is shared with them.
app:user:createtakesowner,memberorguest, a guest with--contact=<id>. - The move from iDoklad adds tables for the iDoklad keys, the downloaded snapshot, the jobs, the links of imported records and the reports of checks and imports, and columns for the import source, run and original PDF of documents and payments; run the migrations. Its PDFs are kept in
var/share/<env>/idoklad-documentsand the originals of imported documents invar/share/<env>/original-documents; include both directories in backups. The jobs run on theasynctransport of the existing worker, and the iDoklad keys are sealed withMAIL_SECRET_KEYS. See docs/idoklad.md. - System mail of the installation, such as invitations, goes through its own mailer, never a firm’s server. Set
SYSTEM_MAILER_DSNandSYSTEM_MAIL_FROM(such asForesi <noreply@example.com>) and check them withbin/console app:ops:test-mail <to>. The mail is queued on the existingmailtransport, so the worker command is unchanged. While either is empty,/healthreports the new checksystem_mailas degraded. See docs/operations.md. - The REST API and the MCP server add the table for personal API tokens and an
api_token_idcolumn on audit entries; run the migrations. The MCP endpoint at/mcpanswers only for the hosts in the newMCP_ALLOWED_HOSTS(defaultlocalhost,127.0.0.1): set it to the public host, such asapp.example.com. Streamable HTTP sessions are kept invar/share/<env>/mcp-sessions, which works on one machine only. See docs/api.md, docs/mcp.md and docs/operations.md. - Every module directory under
src/now has its owncomposer.jsonmanifest and is installed as a Composer path package (vendor/foresi/<id>links tosrc/<Module>). Runcomposer installfrom a full checkout; nothing else changes at runtime. See docs/adr/0029-module-registry.md. - API writes add the table
api_idempotency_key; run the migrations. The worker prunes keys older than 24 hours every hour, so the worker command is unchanged.app:api-token:issuenow requires--scope, such as--scope=reador--scope=contacts:write: update scripts that issue tokens without it. Tokens issued before keep their scopes, and awritetoken now also reads. See docs/adr/0032-api-writes.md. - Cash flow adds the tables
cash_flow_planned_item,cash_flow_checkpoint,cash_flow_expected_dateandcash_flow_minimum_balance; run the migrations. API tokens need the new scopecashflow:readorcashflow:writeto use it. - Payments of received documents add the table
received_document_payment; run the migrations. Every stored received document starts with no payment, so a recorded one shows as unpaid until its payments are recorded. - One instance per customer (ADR 0035) starts: the core module Tenancy is now
foresi/instance(App\Instance\); runcomposer install. A new migration stops the upgrade when the database holds more than one tenant: move each tenant but one into an instance of its own first. A fresh database passes. Stop the workers before the deploy (the deploy script does) so no queued message names an oldApp\Tenancy\class. - The time zone of the instance is the new environment variable
APP_TIMEZONE, a canonical name of the tz database such asEurope/Prague; a wrong one stops the instance at start. Empty (the default) changes nothing: a zone stored withapp:tenant:timezonestill wins, then the country of the first active firm, then UTC. If you set a zone withapp:tenant:timezone, put the same one inAPP_TIMEZONE: the stored zone goes away in a later release. See docs/operations.md. - The tables of cash flow, purchasing, the timesheet and the iDoklad move lose their tenant column; their unique and lookup indexes keep their names on the remaining columns. Take a backup before you migrate: going back down works only while these tables are empty. New iDoklad PDFs are kept directly in the iDoklad files directory, no longer in a subdirectory per tenant; files already pulled stay where they are and still read.
- The tables of the webhooks, the event log, the audit log and the attachments lose their tenant column; the indexes that led with it keep their names on the remaining columns, except
idx_webhook_endpoint_tenant_active, nowidx_webhook_endpoint_active, andidx_event_log_tenant_position, which goes. Take a backup before you migrate: going back down works only while these tables are empty. New attachments are kept directly in the attachments directory, no longer in a subdirectory per tenant; files already uploaded stay where they are and still read. The audit log no longer needs an active tenant to be written. - The tables of banking and work lose their tenant column the same way, with the same backup advice. New raw bank mail is kept directly in the inbound mail directory, no longer in a subdirectory per tenant; mail already received stays where it is and still reads.
- The tables of invoicing lose their tenant column the same way, with the same backup advice. Sent and original PDFs are now stored as
{id}.pdfin the directory itself, no longer in a subdirectory per tenant; those stored before are kept where they are and still read. - The tables of the contacts and firms, the people, invitations and API tokens, and the imports lose their tenant column, and so does the primary key of
api_idempotency_key; the indexes that led with it keep their names on the remaining columns, exceptuniq_membership_tenant_user, nowuniq_membership_user: a person has one membership. Take a backup before you migrate: going back down works only while these tables are empty. - The organisation switcher is gone (
/organisation/choose,/organisation/switch/{tenantId}and the user menu item): a signed-in person works in the one organisation of the instance. - Breaking:
GET /api/v1/meand the MCP toolforesi_whoamino longer returntenant; the response hasuserandtokenonly. Clients that readtenant.idortenant.namemust stop doing so. - Breaking for operators:
app:api-token:issueandapp:api-token:listno longer take--tenant, and the list has no organisation column;app:user:createtakes the e-mail and the role only (app:user:create owner@example.com owner), no organisation name. Update scripts that pass them. - The last step of one instance per customer: the
tenanttable and the tenant column ofscheduled_job_rungo, so no table has a tenant column any more; each timed job now has one row and runs once per period. Take a backup before you migrate: going back down works only whilescheduled_job_runis empty. The organisation’s name shown in the app and in mail is now that of the first active firm (before the first firm, “Foresi”); the time zone isAPP_TIMEZONE, else the first active firm’s country, else UTC. - Breaking for operators:
app:tenant:timezoneis removed. A zone stored with it is not carried over: if you set one, put it inAPP_TIMEZONEbefore you migrate.
-
Settings > API and MCP is the one place for API and MCP access: its Connect tab shows the address of the MCP server and a copy-ready setup for Claude Code, claude.ai and Claude Desktop, Cursor, VS Code and other clients, a first prompt that checks the connection, what the access of a token means and how to keep it safe. The window of a new token shows the Claude Code command with that token in it. The account menu no longer has an entry of its own.
-
Saved views on the four invoice lists (invoices, advances, tax documents on payment and corrective documents): the tabs are now shared default views, at most six as tabs with All first, the rest and the lists of advances missing a tax document and of tax documents waiting for a correction in a “More views” menu. A view is named by
?view=(?view=paid); the old?tab=and?month=addresses still open the same documents. The Month filter also offers This month, Last month, This quarter and This year, which resolve on the day the list opens in the instance’s time zone, so a link to Last month stays right after the month turns. Search stays on top of every view. Underneath is a shared model for every list: a module declares the fields a list can be filtered by, and conditions{match: all, conditions: [{field, op, value}]}with relative dates are checked and compiled to its SQL. -
Received documents over the REST API and MCP, with the scopes
received_documents:readandreceived_documents:write:GET /api/v1/received-documentswith the filtersfirm_id,supplier_id,state,unpaid,due_beforeandtrashed, the detail with its VAT recap and payments, and the writes record from fields (no file needed; the original can be added later), trash, add a payment, mark as paid and remove a payment recorded by mistake. The tools areforesi_search_received_documents,foresi_get_received_document,foresi_list_received_document_payments,foresi_record_received_document,foresi_trash_received_document,foresi_add_received_document_payment,foresi_mark_received_document_paidandforesi_remove_received_document_payment. See docs/api.md and docs/purchasing.md -
Payments of received documents: the day, the amount in the document’s currency, the method (
bank_transfer,card,cashorother) and an optional bank movement, several per document and never more than its total. What is paid and what remains are derived, never stored. Mark as paid pays all that remains, dated today in the organisation’s time zone. Purchasing records the eventspurchasing.received_document.recorded(a document recorded for the first time) andpurchasing.received_document.paid(the payment that leaves nothing to pay), for the feed and webhooks -
Contact writes over the REST API and MCP: create, update (only the fields sent;
nullclears), archive, restore, and link or unlink a contact person, under/api/v1/contactsand as the toolsforesi_create_contact,foresi_update_contact,foresi_archive_contact,foresi_restore_contact,foresi_link_contact_personandforesi_unlink_contact_person. They follow the rules of the address book screens and answer the contact detail; a registration number or VAT id the organisation has already is refused with409 duplicateand the ids it matched. The address book records the eventsparty.contact.created,.updated,.archivedand.restored, for the feed and webhooks. See docs/api.md and ADR 32 -
Scopes per resource for API tokens:
contacts,invoices,payments,eventsandwebhooks, each to read or to change, next toreadandwrite. Settings > API access issues tokens with any of them, behind two-factor sign-in, and an MCP connection lists only the tools its token may call. See docs/api.md -
Idempotency-Keyon every REST write andidempotency_keyon every MCP write tool: a retry with the same key answers the saved result and acts once. See docs/api.md -
A write budget of 120 writes in 10 minutes per token, next to the shared 600 requests
-
A read-only REST API under
/api/v1: invoices, contacts and payments, each as a list and a detail, andGET /api/v1/me. Lists use cursor paging, errors are RFC 9457 problem documents with stable codes, every token has a rate limit of 600 requests in 10 minutes withRateLimit-*headers, and the OpenAPI document is at/api/v1/openapi.json. See docs/api.md and ADR 27 -
An MCP server for assistants, read-only: tools to look up the signed-in person and the firms, and to search and show invoices, contacts and payments, over stdio (
bin/console mcp:server, the token inFORESI_API_TOKEN) and Streamable HTTP at/mcp. Text written by other people is returned as data with a notice that says so. See docs/mcp.md -
Module contracts and integrations: a module that uses another one only when it is installed lists it in
extra.foresi.optionaland keeps that code insrc/<Module>/Integration/<Other>/, which the kernel registers only when the other module is installed.bin/console app:modulesandforesi_list_moduleslist the integrations and whether each is loaded. The generated Deptrac configuration lets integration code use only the other module’sContractnamespace. See ADR 33. -
Cash flow, a new optional module (
cash-flow, scopecashflow): planned items (one-off or recurring, money in or out, with a category, an optional counterparty, an included switch, skipped occurrences and a match rule kept for bank pairing), bank balance checkpoints per firm account, the expected payment day of a document and a minimum balance per firm.GET /api/v1/cash-flow/forecastand the toolforesi_cash_flow_forecastanswer the forecast of a firm in CZK at today’s ČNB rate, by ISO weeks until the end of next month and then by months, 12 months by default: opening, inflows and outflows by category, closing and the items of each period, overdue items in the first period, the lowest point, the first day below the minimum, a warning when the balance is older than 7 days and the sources that failed. Other modules add their flows through theCashFlowSourceandBalanceSourcecontracts. The planned items record the eventscash-flow.planned_item.created,.changed,.occurrence_skipped,.endedand.deleted. See docs/cash-flow.md. -
The cash-flow forecast reads the modules installed with it: unpaid invoices and advances, the coming occurrences of recurring invoices, unpaid received documents (on the received day with
no_due_datewhen they have no due date), and the bank movements booked after a checkpoint for the balance. A planned occurrence is left out when its counterparty’s document falls in its period (a recurring item) or a bank movement meets its match rule. A token withoutinvoices:readorreceived_documents:readsees those sources as totals only, inhidden_itemsof each period andrestricted_sources. Banking records the new eventbanking.movement.recorded. See docs/cash-flow.md. -
A module registry:
bin/console app:moduleslists the installed modules, their required and optional modules and the known problems of the dependency graph (--format=jsonfor scripts), and the MCP toolforesi_list_modulesreturns the same. A Deptrac configuration generated from the manifests (bin/console app:modules:deptrac) fails the quality gate on a dependency a manifest does not declare. See ADR 29. -
Personal API tokens: a person with two-factor sign-in issues a token under Settings > API access, with a name and an expiry of 30, 90 or 365 days. The token is shown once and only its hash is stored. An owner sees and revokes the tokens of the other people. Every token action is its own actor in the audit log. Operators have
app:api-token:issue,app:api-token:listandapp:api-token:revoke -
Settings > API access, reached also from the user menu, lists your tokens with their last use and state
-
Received documents under Money, Costs: supplier invoices, simplified receipts, foreign invoices, credit notes, advance requests and other documents in one list beside the original file, for owners and team members and never for guests. A PDF or image uploaded from the page header becomes a draft to complete; a document can also be typed in at once. Recording gives it the firm’s own evidence number (
R{YYYY}{NNNN}by default), kept in the trash too, apart from the supplier’s number the control statement reports. Each document has a VAT treatment (domestic, domestic reverse charge, service from the EU, service from outside the EU, not a VAT document, non-deductible) and a VAT recap per rate, from which the VAT in CZK, the first month of the deduction and the latest day to deduct are computed on every save. Foreign currencies convert at the ČNB rate of the tax point, fetched daily by the worker (bin/console app:exchange-rate:fetchfetches a date by hand); a rate typed by hand always wins and is kept as typed. Warnings never block a save: the same file or the same supplier’s number twice, a deduction deadline passed or near, a simplified receipt above 10,000 CZK. A trash with a reason and a restore, a history, and two people editing the same document cannot overwrite each other. See docs/purchasing.md and ADR 0028. -
Projects and tasks: projects for a client or internal, with sections and a workflow of statuses of your own (each with a fixed type), tasks with subtasks, a responsible person, watchers, due dates, priorities, labels and an activity history; a list with quick add, a board with drag and drop and a move menu, a personal My tasks page and project settings. Only the owner and the team members see them. See docs/projects.md and ADR 26
-
Discussion and attachments on tasks: one timeline of comments and history, oldest first, with filters; comments are internal by default, with
@mentions, a safe Markdown subset with preview and toolbar, edit and delete (the author, and an owner for moderation); files up to 50 MB on a task, pasted or dropped into the editors as Markdown, with image and PDF viewing in a dialog, inline video and download for other types. See docs/projects.md -
People: the owner invites team members and guests (who represent a contact of any kind) by e-mail, with a link that works once for seven days, or copies the link when the installation has no system mail. The people screen under Settings lists team members and guests with an initials avatar, their role, contact and two-factor sign-in, and the pending invitations to send again or revoke; the owner changes roles and contacts, deactivates and reactivates people and resets their two-factor sign-in. The last active owner stays. See docs/people.md.
-
System mail of the installation: a port for mail the installation sends itself, such as invitations, queued on the
mailtransport and sent throughSYSTEM_MAILER_DSNin a plain layout with the product name and the footer “Sent by Foresi on behalf of” the organisation, in Czech or English; the commandapp:ops:test-mail <to>; and the health checksystem_mail. -
The move from iDoklad: a wizard per firm under the list of imports connects an iDoklad account with its API keys (the Oblíbený or Prémiový tariff), downloads it into a snapshot (page by page, the PDFs in batches, later only what changed) through a read-only allow-list of GET paths, shows the API requests used this month, and checks the import as a run that is rolled back. The report counts what would be created, matched, refused or differs by area, sums documents by year in iDoklad and in Foresi, and lists each refused record with its reason and each document whose totals differ with both amounts. The import brings contacts, number series that count on from iDoklad’s last number, issued and advance invoices priced again with the Czech VAT rates of their day back to 2013 and kept with iDoklad’s PDF as their original, payments with their tax documents and the deductions of advances, and recurring invoices as paused templates; it sets the day reminders start from. An import can be undone for 30 days while nothing done in Foresi stands on it. See docs/idoklad.md and docs/adr/0024-idoklad-import.md.
-
An operations guide, docs/operations.md: requirements, environment variables, a release layout for zero-downtime deploys, the worker, scheduled jobs, the web server, upgrades, monitoring, backups and restores, and a go-live checklist. With it, scripts in
ops/:deploy.shandrollback.sh(releases with acurrentsymlink), a Ploi deploy script,backup.sh(restic: database dump and data directories, kept ten years),restore-check.sh(restores the newest snapshot into a scratch database and checks row counts and the hashes of sent documents),restore.sh, and systemd units for the worker, the backup and the restore check. -
Advance invoices, tax documents on received payment and their settlement on the final invoice. A payment of an advance, by hand or from the bank, gets its tax document in the same step when VAT arises on it; one that cannot be issued waits in a list with its deadline. A final invoice deducts the customer’s tax documents with negative lines per rate, each once, and may reach zero or less. Each document shows its chain of links. See docs/invoicing.md and docs/adr/0021-advances-and-tax-documents-on-payment.md.
-
Corrective tax documents: a credit or debit note from the row menu of an issued invoice, with its reason, its type (a change or an error) and its decisive date, at the invoice’s rates, capped per rate under a lock. Corrections lower or raise what is left to pay; an invoice paid above that is to refund, and a refund is recorded by hand or paired by a person from an outgoing bank movement. A cancelled or refunded advance payment corrects its delivered tax document by itself. ISDOC types 2, 3 and 6 name the original document. Corrections have their own list, series
O7{YYYY}{NNNN}and mail template. See docs/invoicing.md and docs/adr/0022-corrective-tax-documents.md. -
Series have a document kind, with a default series per kind and firm.
-
Reminders can take advance invoices too, with a switch of their own.
-
Recurring templates can issue advance invoices.
-
Invoices. An invoice is issued by one firm to one customer, with lines, VAT per rate, the reverse charge with its supply code, a form without VAT for a firm that is not a VAT payer, and a total rounded to a whole crown if the firm chooses so. The amounts are calculated when the invoice is saved and stored; the screen, the PDF and the ISDOC file all show what is stored. See docs/adr/0014-invoice-amounts-rounding-and-concurrent-edits.md. The tax rules are subject to professional tax and legal review.
-
Two people editing the same invoice cannot overwrite each other: a save from a form opened before another save is refused with a message, and every change takes a lock on the invoice, on SQLite and on PostgreSQL.
-
PDF of an invoice, conforming to PDF/A-3a, with the ISDOC 6.0.2 file attached, a QR Platba+F code and the firm’s logo, stamp and signature. Every invoice is drawn with one layout, the panel. See docs/adr/0012-invoice-pdf-and-isdoc.md.
-
The pack for the accountant: one firm and one month in a ZIP, with a folder per kind, each document as a PDF/A-3 with its ISDOC file beside it, named by issue date, customer, amount and variable symbol, and
seznam.xlsxwith the documents and a VAT recap per treatment and rate. Tax documents count by tax point, advance invoices by issue date. By default it takes only what is not yet exported or changed after export, and the page shows how many documents of each kind it holds before the download. If a document cannot be drawn there is no ZIP, and the form names the document. See docs/invoicing.md and docs/adr/0023-accountant-pack-and-export-state.md. -
The export state of each document, as iDoklad keeps it: not exported, exported or changed after export, with the time. A finished pack marks its documents; edits stay allowed and mark a document changed. The invoice lists show it in an Export column, filter by it, and offer “Clear export state” in the row menu of an exported document.
-
A month filter on every document list, and the sums of what the list shows over all its pages under it: count, base, VAT and total, and a line per treatment and rate, in crowns at each document’s own exchange rate.
-
Export of a document list as it is shown, over all its pages, to CSV or XLSX, from the Export menu of the list.
-
The start page shows the invoicing of one firm or all: invoiced and output VAT this month and last month, unpaid and overdue with overdue amounts by age, the five largest debtors, and a reminder when last month has documents the accountant has not received yet, with a link to its pack.
-
docs/invoicing.md: what the invoices support in this release, the ISDOC producer statement and the limits.
-
The invoice list with the tabs All, Overdue and Trash, search, a firm filter and row actions. A deletion asks for a reason, the trash shows who deleted a document, when and why, and each invoice has a history of who changed what, its lines included.
-
Copying an invoice: the form opens unsaved with the customer as the contact reads now, today’s dates and the next number, and says when the lines hold a date or when the firm, series or customer can no longer be used.
-
The invoice, advance, correction and recurring forms share one layout, as iDoklad: labels beside the fields (above them on a phone), two bands of details, the lines and totals, and an action bar; the payment details show the account, its number and IBAN once.
-
The invoice form: save issues the document, with live totals from the server, a customer picker per firm, reverse charge with its supply code, and a form without VAT for a non-payer firm.
-
Any active contact can be invoiced, whatever its role; contacts archived for the firm cannot. Customers come first in the picker, and a saved invoice makes the contact a customer of that firm.
-
A contact created with the plus on the invoice form comes back picked, with its defaults, while the form keeps what was typed.
-
Numbers in the line fields are grouped as you type. The fields and the server read
1 000,50,1000.5and1,000.50. -
Every invoice shows one status on the list, the form and the history: issued, delivered, overdue or in the trash.
-
Number series per firm under the new Invoicing tab of a firm: format with date tokens and one sequence, default series, next number. A number is never used twice, the sequence restarts each year when the format has a year, and the format locks once the series has numbers. Deleted invoices go to a trash that keeps their number, and a number an edit gave up stays taken. See docs/adr/0013-invoice-numbers-and-trash.md.
-
Invoicing settings per firm: rounding of the total, constant symbol, texts above and below the items, and the contact printed on invoices.
-
A logo and an image with stamp and signature on the firm form. PNG or JPEG in RGB, up to 1 MB and 3000 x 3000 pixels. Both stay outside the web root in
var/share/prod/firm-images, so include that directory in backups. -
Sending invoices by e-mail as a link to the PDF, through each firm’s own SMTP server: a send dialog with the contact’s invoicing addresses, a copy to the sender and the text filled in from the firm’s template in the document’s language; “Send and save” on the form; retries with a visible failure; a public link page with the document and its payment details; read state; marks on the invoice list, sends on the invoice’s history with the PDF as sent, a send log under Sales, and notices for failed and waiting sends. See docs/sending.md, docs/adr/0015-sending-and-public-links.md and docs/adr/0016-scheduled-jobs.md.
-
E-mail settings of a firm: templates per document language with readable variables, the mail server and a test e-mail.
-
Timed jobs per organisation on one schedule, run by the worker.
-
Recurring invoices under Sales: a template with the invoice’s fields, a schedule (daily to yearly, every 1 to 99, the last day of the month, tax point on the issue date or the month’s last day, due days, an end rule) and period variables with offsets,
{document_number}among them. A preview shows the next five issues. A template can start from an invoice, and be paused, resumed, ended, deleted before its first issue and issued now. See docs/recurring.md. -
A daily run from 05:00 in the organisation’s time zone issues each due occurrence exactly once, catches up after downtime, sends the invoice to the customer with a copy to the firm, or holds it under the new To send tab of the invoice list; one more than 3 days late is held. A template saved or resumed after the day’s run is issued at once. Failures are recorded on the template, shown in a notice and mailed to the firm once per run. See docs/adr/0018-recurring-occurrences.md.
-
Automatic reminders of overdue invoices: per firm a switch, the days to the first and to each next reminder, a minimum amount and up to 10 reminders; a Reminder template per language; a Send reminders flag per contact; reminders by hand from the row menu; reminders in the history and the send log with a type filter. What an invoice still owes comes from the recorded payments: an invoice paid in full is never reminded, by hand or by the run, nor listed in the settings’ preview, and a part-paid one is reminded of what is left to pay, in the text, in the PDF, whose payment box then says Left to pay, in its QR code and in the preview. While reminders are off, the settings show which reminders they would send if they were switched on today. A reminder whose invoice was paid or trashed meanwhile is cancelled before it leaves. See docs/reminders.md.
-
The time zone of an organisation for its daily work, set with
app:tenant:timezone. -
Payments. “Pay” in the row menu of the invoice list records a payment in a dialog: date, amount (what is left, prefilled), method and note; a part payment is allowed, and an overpayment after a warning. One payment can be split over several invoices. The invoice shows paid, partly paid or overpaid, derived from its payments and never stored, lists its payments with Remove, and its history shows each payment and removal. See docs/adr/0019-payments-and-allocations.md.
-
Bank pairing from Komerční banka payment notifications. Each bank account gets a secret inbound address; Foresi takes the mail from one operator mailbox over IMAP, or from a relay through a webhook, records the movements and pays the matching invoice by the variable symbol and the amount when the rules leave exactly one answer. Only a message the inbox’s own receiving server verified by DMARC pays anything by itself; an unverified one is recorded with suggestions, and a forged one is rejected. Every pairing can be undone. See docs/bank-pairing.md and docs/adr/0020-bank-notification-mail.md.
-
A Bank tab on each firm, with the accounts and their currency, the inbound addresses with setup steps for MojeBanka Business and KB+, and the switches automatic pairing (on) and small-difference settlement (off; up to 0,99 Kč in CZK).
-
Bank in the navigation: incoming and outgoing movements, the unmatched queue with suggestions, pairing by hand over one or more invoices with Undo, unpairing, and the bank e-mails with Show, Try again, Record anyway and Dismiss. A message waiting for over an hour shows as stuck. Failed bank e-mails are read again every hour when a newer parser can read them.
-
Outgoing refunds pair by themselves under the incoming rules: a verified notice, the variable symbol of exactly one invoice with something to refund, and exactly what it has to refund. Anything else waits on the new Outgoing unmatched tab of the bank screen, with the reason (a new one: the amount is not what is to refund) and suggestions, among them the invoices an earlier payment from the same account paid. Outgoing movements now get the possible-duplicate and own-transfer checks too. One that no refund fits, a supplier or salary payment, is recorded only and queued for no one.
Changed
Section titled “Changed”- A dialog asked for while the page under it was loading again (right after the window of a new API token closed, say) no longer locks the dialogs and sheets until a full reload.
- Every page title runs from the specific to the general: the page, the section of the navigation it belongs to, and the product, as “Fix the login · Projects · Foresi”. A list page names its section once, the login page has no section, and the public document pages keep the issuer instead of the product.
- On phones (below 900 px): the menu opens full screen with its own close button; search and the account menu sit in a sticky top bar; text fields, selects and text areas use 16 px text so iOS Safari no longer zooms in on focus (pinch zoom stays on); menu, tab, sort and row-checkbox targets are at least 44 px; the content runs edge to edge; dialogs, sheets and bottom bars keep clear of the notch and the home indicator (
viewport-fit=cover,env(safe-area-inset-*)); page heights use dynamic viewport units. - Breaking for cash-flow sources:
App\CashFlow\Contract\CashFlowSourcehas a new method,mayReadDetails(): bool, whether the caller may read the documents behind the flows. A third-party source must implement it; return true to keep its items visible. Sources with actuals implement the newActualFlowSource. - The recurrence of recurring invoices (
Recurrence,RecurrenceUnit,RecurrenceEnd,RecurringSchedule,InvalidRecurrence) moved fromApp\Invoicing\DomaintoApp\Shared\Domain\Schedule, so other modules can schedule with it. Behaviour and stored data are unchanged; code that imported the old names must use the new namespace. - SQLite 3.35 or newer is required, for the atomic counter of number series.
- The firm sections of the contact form are replaced by a scope per panel. With two or more active firms, the panels for roles, document defaults, invoicing e-mails and archive state have a dropdown: all firms, or one firm. A firm can use the shared values or have its own, for example a supplier for one firm and a customer for the other. Everything is saved with the form. A contact archived for all firms stays archived for every firm. The address book list stays on the shared values.
- The sidebar is grouped around documents and settings. Invoices are under Sales (Prodej), the address book under Contacts (Adresář), and Settings at the bottom holds Firms and the new item Import and export, which opens the history of imports. A group without items is not shown. The firm page has two tabs, Details and Invoicing, in place of a button; the invoicing tab holds the settings and the series. All addresses stay as they were.
- The daily runs send as the system: they skip the per-user minute limit and use at most 80% of a firm’s daily budget.
- Firms is now My firms (Moje firmy) in the interface, and its empty text says these are your own companies that issue documents.
- An error about the firm links to the firm’s settings in a new tab, and a firm without a bank account says so in the payment section before the save. Every link in the error list lands on a field that takes the focus.
- The lines of the invoice form: a discount is a sub-row of its line with its own deduction, moving and removing a line are in a row menu, and the total reads with VAT for a payer. Amounts on screen show Kč for CZK.
- A Czech document writes crowns as Kč in its PDF, on its link page and in its mail; an English one keeps CZK, and ISDOC keeps the ISO code.
- The order number and the description moved into More details, which opens when it holds something other than the defaults, or a mistake.
- An identified person cannot issue invoices yet; the save is refused until the rules for it are reviewed.
- Text that the PDF font cannot print is refused when an invoice is saved, with the field and the characters named, so that the PDF and the ISDOC file never differ. Text in scripts such as Chinese or Arabic cannot be used in invoices yet.
- All firms now edits the document defaults, invoicing e-mails and archive state a contact shares, which the form did not offer before.
- A firm’s bank accounts are records: each has a currency and a label, one is the primary account that new invoices get, and an account is archived instead of deleted, so documents keep it. The firm form no longer lists them.
- The status of an invoice includes the payment states, in the order trash, overpaid, paid, overdue, partly paid, delivered, issued. A paid invoice is not overdue. The invoice list has the tabs All, Paid, Unpaid, Overdue and Trash.
- An invoice with a payment cannot go to the trash; remove the payments first.
- The public link page of a paid invoice says Paid and shows no way to pay it again. After a part payment it shows what is left to pay, without the QR code.
- A plain overpayment is now to refund: the refund in the payment panel and in the bank’s pair dialog accepts it, and the invoice list has a To refund tab of invoices paid above what is due. A paid advance no final invoice deducts is now offered as a refund in the pair dialog too. Unpairing a refund leaves its movement unmatched, never paired by itself again, instead of recorded.
[0.4.0] - 2026-11-01
Section titled “[0.4.0] - 2026-11-01”Breaking release: every record gets a new kind of identifier. Read the upgrade notes before updating.
Upgrading
Section titled “Upgrading”- Finish or cancel imports that are in progress, because their queued work cannot be read after the upgrade. Then stop the web server and cron (
app:import:health,app:import:purge). - Let the workers drain the
asyncandregistryqueues, untilbin/console messenger:statsshows those two empty. Thefailedqueue may hold messages. A message left inasyncorregistrycannot be read afterwards; it is moved tofailed, not lost, but its work has to be started again. - Stop the workers.
- Back up the database and the
var/importsdirectory. - Deploy the code and clear the cache (
bin/console cache:clear). - Run the migrations with
bin/console doctrine:migrations:migrate. The identifier migration cannot be reverted and cannot be rehearsed with--dry-runor--write-sql; the application refuses both. Run it throughbin/console, not through a standalonedoctrine-migrationsbinary, which does not have that protection. - Start the web server, cron and the workers.
Signed-in users stay signed in: a session from before the upgrade still loads, the user is refreshed from the database by e-mail address, and the organisation chosen in it stays chosen, because organisation identifiers do not change. Old URLs stop working (see below).
- Several firms in one organisation. The owner lists, adds, edits and archives them under Settings, with the register lookup of the contact form. A registration number is unique among the active firms of an organisation; an archived firm cannot be restored, and the number can be added again. The last active firm cannot be archived.
- Per-firm contact settings. With two or more active firms, the contact form has a section per firm for the due period, currency, document language, payment method and reverse charge. A firm without settings for a contact falls back to the contact’s own defaults.
- Every audit entry records the aggregate root it belongs to, so the whole history of a contact is one query, including parts removed since. A contact link is recorded under the company only.
- Architecture decision records 9 to 11 on identifiers, several firms in one organisation, and audit roots and retention. The retention position is subject to professional tax and legal review.
- Cross-tenant references are refused when a record is written.
Changed
Section titled “Changed”- Breaking: every entity is identified by a UUIDv7 instead of a whole number. A migration converts existing data and cannot be reversed, so back up the database first.
- Breaking: old contact and import URLs stop working, because they contain the old numbers. Open the records again from the lists.
- Breaking: a file exported earlier has an
idcolumn of whole numbers. A row with such a value is a row error on import; match by registration number, VAT ID or e-mail address instead. Files exported after the upgrade carry the new identifiers and can be imported again. - Messages that cannot be decoded go to the failed transport instead of being discarded.
[0.3.1] - 2026-10-31
Section titled “[0.3.1] - 2026-10-31”Changed
Section titled “Changed”- The column matching step says once where the proposals come from and marks only columns matched by a similar name.
- Help texts under fields fit on one line, and a test keeps them at 60 characters or fewer.
[0.3.0] - 2026-10-31
Section titled “[0.3.0] - 2026-10-31”- Generic import and export. Import CSV and XLSX files in the background: encoding, delimiter and header row are detected, columns are mapped with remembered mappings, a dry-run check lists every row error (downloadable as an error file), and three modes are offered (add missing, update existing, full replace, which archives records missing from the file and needs the number of records typed as confirmation). An import can be undone for 30 days, also one that failed after it started writing, and a failed undo can be started again. Contacts are the first target, with a preset for the iDoklad contact export. Files up to 50 MB and 200,000 rows; files and staged rows are deleted 30 days after an import ended. Documented in
docs/import.md. - Commands
app:import:purge(deletes old files and staged rows) andapp:import:health(fails imports that stopped moving and starts the next queued one); run both from cron. - UI components for the import screens (stepper, progress bar, radio cards, mapping row) and notices in the app shell when an import ends.
- Contacts have a website and a mobile phone.
- Audit entries carry an optional correlation id that groups the changes of one operation.
- Architecture decision records for the audit correlation id and the asynchronous import pipeline.
- A floating action bar holds the primary action of every form and wizard step, so it stays in reach on long pages.
- Closed design token scales for radius, control height, type, borders and shadows, shown in the component catalogue and enforced by a test.
Changed
Section titled “Changed”Upgrading: run the database migrations (bin/console doctrine:migrations:migrate); they add the import tables, the audit correlation id, the e-mail comparison key and the contact fields. Start a background worker (messenger:consume async registry, one worker on SQLite) and schedule the two import commands; see docs/import.md. Set upload_max_filesize and post_max_size to at least 50M.
- The address book has import and export actions in its header; the CSV export is now an export menu with CSV and XLSX, and it exports the filtered list.
- Contact roles and kinds accept their translated names when imported.
- Background messages run inside the tenant they were sent from; the default
flocklock works on a single host, useLOCK_DSNfor several. - Every response forbids content type sniffing (
X-Content-Type-Options: nosniff). - Forms are validated on submit: every invalid field is marked with its message, the input is kept, focus moves to the first invalid field and the page title starts with “Error”. Primary buttons are never disabled for validation.
- Control borders meet 3:1 non-text contrast, and fields side by side line up whatever text sits under them.
- The register lookup names the rate limit (HTTP 429) instead of a generic failure.
[0.2.1] - 2026-10-30
Section titled “[0.2.1] - 2026-10-30”- Choice chips component; contact roles are chosen with it.
- Description list component for label and value rows, and an actions slot in the card header; the contact overview uses both.
- The command palette and the user menu appear above the page panel, and the user menu can be wider than the sidebar.
- Organisation and user names in the sidebar wrap to two lines instead of being cut; a user without a name sees the e-mail once.
- The command palette input no longer shows the global focus outline.
- Browser autofill no longer paints form fields blue.
[0.2.0] - 2026-10-30
Section titled “[0.2.0] - 2026-10-30”- Design system: Twig components built on Symfony UX and Tailwind design tokens (buttons, inputs, badges, tabs, cards, data table with selection and bulk actions, pagination, KPI strip, facts grid, timeline, empty states and a command palette), with a development component catalogue.
- App shell: sidebar navigation, user menu, active tenant choice and a styled login screen in Czech and English.
- Address book: list with search, views, sorting and paging, detail with overview, contact persons, addresses, bank accounts and history, create and edit forms, archive and restore, bulk archive and CSV export.
- Parties: roles, billing and delivery addresses, persons linked as contact persons, bank accounts and document defaults.
- Registry lookups: Czech business register (ARES) autofill, EU VAT number check (VIES) and the Czech unreliable VAT payer register, with rate limiting.
- End-to-end tests with Playwright covering accessibility (axe), keyboard use and layout on desktop and mobile for the sign-in screen, the address book and the component catalogue. Screenshot comparison specs exist for the sign-in screen and the address book; they run locally against macOS baselines and are not part of CI yet.
- A language preference per user and a language switch in the user menu.
- Architecture decision record for the server-rendered user interface.
Changed
Section titled “Changed”Upgrading from 0.1.0: run the database migrations (bin/console doctrine:migrations:migrate). Several of them drop columns after moving their data, and their down() steps cannot restore everything (for example a party with several e-mail addresses), so back up the database first.
- Breaking: the party e-mail column is gone. E-mail addresses live in the new
party_emailtable and existing addresses are moved there.Party::email()is removed. - Breaking: the embedded party address (street, city, postal code, country) is gone. It is moved to a billing address in the new
party_addresstable.Party::address()is removed. - Breaking: the
is_customerandis_supplierflags are replaced by roles (Party::roles(),hasRole(),assignRoles()).isCustomer()andisSupplier()are removed. - Breaking: the
is_primarycolumn ofparty_bank_accountis dropped; the primary account is now stored as a separate flag with a unique index. - Breaking: the
Partyconstructor no longer takes an address or an e-mail address and takes the roles instead. Names, identifiers, phone, roles, note and defaults are changed through methods such asrename()andchangeIdentifiers(). - Registry results (VIES, unreliable payer and the published bank accounts) belong to a VAT ID: changing or removing it clears them until the next check.
- Search and sorting by name ignore the case of letters with diacritics on SQLite too.
- Logout is a POST request protected by a CSRF token.
- The session is migrated when the active tenant changes.
[0.1.0] - 2026-10-29
Section titled “[0.1.0] - 2026-10-29”- Symfony 7.4 application skeleton with Doctrine ORM, Security, Twig, Validator and UID.
- Community files: licence, contributing guide, code of conduct, security policy and contributor licence agreement.
- Architecture decision records for the decision log, the modular monolith, row-level tenancy, money as integer minor units and the append-only audit log.
- Quality gate: PHPStan at maximum level, Deptrac layer rules, Rector, PHP CS Fixer and Infection mutation testing.
- Money: an exact
Moneyvalue object with allocation that never loses or gains a minor unit. - Tenancy: row-level tenant isolation with a fail-closed Doctrine filter, a tenant context and a scalar-only bypass for cross-tenant lookups.
- Parties: legal entities and parties with registration numbers, VAT IDs and IBANs; Czech registration number validation as the first country module.
- Identity: users, tenant memberships with roles, form login with CSRF protection and throttling, a tenant switch application service and the
app:user:createcommand. - Audit: an append-only audit log for audited entities.
- Tested on SQLite and PostgreSQL 17.