From 05d35aa0c5416172ccb19b90fbda55fa04ae4fc6 Mon Sep 17 00:00:00 2001 From: Darko Gjorgjijoski Date: Mon, 28 Sep 2026 15:38:24 +0200 Subject: [PATCH] Consolidate module guides and unreleased purchasing documentation --- README.md | 13 + content-review.json | 83 +++++- docs.json | 13 + docs/v3/guide/ai-assistant-module.md | 80 ++++++ docs/v3/guide/ai-assistants.md | 4 +- docs/v3/guide/modules.md | 15 +- docs/v3/guide/tasks-projects.md | 86 +++++++ drafts/README.md | 15 ++ drafts/v3/guide/purchasing.md | 236 ++++++++++++++++++ .../guide-consolidation-2026-09-28.md | 36 +++ 10 files changed, 574 insertions(+), 7 deletions(-) create mode 100644 docs/v3/guide/ai-assistant-module.md create mode 100644 docs/v3/guide/tasks-projects.md create mode 100644 drafts/README.md create mode 100644 drafts/v3/guide/purchasing.md create mode 100644 verification/guide-consolidation-2026-09-28.md diff --git a/README.md b/README.md index f99a5e5..38e216b 100644 --- a/README.md +++ b/README.md @@ -70,3 +70,16 @@ text, screenshots and the catalog baseline together when reviewing another relea PRs run the website's canonical parser exported into `.github/validator/`, with its source revision and checksum in `source.json`. It includes only the parser and public Composer dependencies, so contributors need no access to the private website repo. Refresh it with `php artisan docs:export-validator ../docs/.github/validator` from website, then update its Composer lock when dependencies change. Validated pushes to `master` request an import by exact commit SHA and wait for publication. Failed imports preserve the previous revision. Embeddings are queued separately; ordinary docs and search continue during provider outages. Configure `CI_DOCS_TOKEN` as a GitHub Actions secret with the same dedicated value in the website deployment. The token authorizes docs imports only. Initial rollout requires the website implementation and worker before this workflow is enabled. Operations, rollback, AI budgets and the old-host cutover are documented in the website's `docs/operations.md`. + +## Canonical guide ownership + +Keep user-facing guides in this repository. The v3 book includes official-module +usage under **Optional modules**; modules still need to be installed separately. +The AI Assistant module guide is distinct from the core MCP connection guide. + +Features ahead of the published release belong in [`drafts/`](drafts/README.md). +Drafts are stored for review but are outside the website importer and AI corpus. +See [the consolidation inventory](verification/guide-consolidation-2026-09-28.md) +for source locations and remaining publication work. Repository READMEs may keep +short introductions and installation pointers. Architecture decisions, contributor +instructions, and private deployment runbooks stay with the code they describe. diff --git a/content-review.json b/content-review.json index be531fa..d3aca6d 100644 --- a/content-review.json +++ b/content-review.json @@ -1293,7 +1293,8 @@ "release": "3.0.0-alpha.10", "source_commit": "c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7", "review_sources": [ - "release source and settled application screen" + "release source and settled application screen", + "Cross-links to the source-reviewed official module guides; existing release screenshots retained." ], "screenshots": [ { @@ -1308,7 +1309,8 @@ } ], "status": "rewritten", - "legacy_anchors": [] + "legacy_anchors": [], + "review_date": "2026-09-28" }, "installation": { "title": "Installation", @@ -1551,7 +1553,8 @@ "review_sources": [ "config/mcp.php", "app/Platform/Mcp", - "MCP settings screen" + "MCP settings screen", + "Cross-links to the source-reviewed official module guides; existing release screenshots retained." ], "screenshots": [ { @@ -1569,8 +1572,80 @@ "legacy_anchors": [ "requirements", "safety" - ] + ], + "review_date": "2026-09-28" + }, + "guide/tasks-projects": { + "title": "Tasks and projects", + "release": "3.0.0-alpha.10", + "source_commit": "c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7", + "review_date": "2026-09-28", + "review_sources": [ + "InvoiceShelf/InvoiceShelf@c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7: resources/scripts/extensions/runtime.ts, composer.lock", + "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: README.md", + "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: module.json", + "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: resources/js/registrations/projects.ts", + "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: resources/js/registrations/tasks.ts", + "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: resources/js/registrations/billing.ts", + "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: resources/js/registrations/reports.ts", + "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: app/Support/ModuleRegistration.php", + "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: app/Application/TimerService.php", + "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: app/Application/TimeEntryService.php" + ], + "module": { + "repository": "InvoiceShelf/module-tasks-projects", + "version": "0.2.1", + "source_commit": "94d3e51a2fe4b5c09a350aa8808d4631d6573068" + }, + "screenshots": [], + "status": "source-reviewed", + "browser_review": "pending; no connected browser in this session", + "legacy_anchors": [] + }, + "guide/ai-assistant-module": { + "title": "AI Assistant module", + "release": "3.0.0-alpha.10", + "source_commit": "c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7", + "review_date": "2026-09-28", + "review_sources": [ + "InvoiceShelf/InvoiceShelf@c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7: resources/scripts/extensions/runtime.ts, composer.lock", + "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: README.md", + "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: module.json", + "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: resources/js/init.ts", + "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: resources/js/pages/AiConfigurationPage.vue", + "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: app/Providers/AiAssistantServiceProvider.php", + "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: app/Application/AiToolRegistry.php" + ], + "module": { + "repository": "InvoiceShelf/module-ai-assistant", + "version": "1.0.0", + "source_commit": "bed8f7a9c23354ca052121cabd9a87745b5e48ef" + }, + "screenshots": [], + "status": "source-reviewed", + "browser_review": "pending; no connected browser in this session", + "legacy_anchors": [] + } + } + }, + "consolidation": { + "date": "2026-09-28", + "scope": "User-facing guides; engineering specifications and operational runbooks remain with their owning repositories.", + "unreleased": [ + { + "path": "drafts/v3/guide/purchasing.md", + "source_repository": "InvoiceShelf/InvoiceShelf", + "source_commit": "9fba5b7a6753f95a2cedd1d92947c7570aeff184", + "pull_request": 903, + "published": false } + ], + "version_exclusions": { + "2": [ + "guide/tasks-projects", + "guide/ai-assistant-module", + "guide/purchasing" + ] } } } diff --git a/docs.json b/docs.json index 50e48fa..a258087 100644 --- a/docs.json +++ b/docs.json @@ -234,6 +234,19 @@ } ] }, + { + "title": "Optional modules", + "items": [ + { + "title": "Tasks and projects", + "slug": "guide/tasks-projects" + }, + { + "title": "AI Assistant", + "slug": "guide/ai-assistant-module" + } + ] + }, { "title": "Company & account", "items": [ diff --git a/docs/v3/guide/ai-assistant-module.md b/docs/v3/guide/ai-assistant-module.md new file mode 100644 index 0000000..4c9ddee --- /dev/null +++ b/docs/v3/guide/ai-assistant-module.md @@ -0,0 +1,80 @@ +--- +versions: ['3'] +reviewed_against: c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7 +reviewed_hash: b11535291ef5c593e374da5bfbab4cc7feff767decd4f9356e5a5a37175c1a08 +--- + +# AI Assistant module + +**AI Assistant** is an optional official module for InvoiceShelf 3. This guide +covers module **1.0.0** with the v3 host described by this book. It adds a chat drawer +and writing assistance inside InvoiceShelf. + +This is separate from [external assistants connected through MCP](./ai-assistants.md) +and from **Ask AI** on the documentation website. The module's business-data tools +are read-only; an MCP connection may have separately approved write access, while +documentation answers do not access company records. + +## Install and connect a provider + +1. A super administrator installs and enables **AI Assistant** in + **Administration → Modules**. See [Modules](./modules.md). +2. Open **Administration → Settings → AI Assistant**. +3. Enable **AI Assistant**, select **OpenRouter**, and enter the provider API key. +4. Enable the capabilities you want to offer and select a model for each one. +5. Select **Save settings**, then **Test connection**. The test control is shown + when AI Assistant is enabled. + +Your administrator supplies and funds the OpenRouter account. The module does not +include provider credit or a shared API key. Keep keys out of screenshots, +documents, and support messages. + +## Choose capabilities + +- **Assistant chat** makes the conversational drawer available on company pages. + Use the AI header action to open it. Start a new conversation when changing topics. +- **Editor text generation** adds writing tools to supported rich-text editors. + Review suggested text before using it in a document or email. + +The capabilities can be enabled independently. If a control is missing, check the +module state, provider configuration, enabled capabilities, and your company access. + +## Company-specific configuration + +The administrator's configuration is the default. A company owner can open +**Company Settings → AI Assistant**, enable **Use a company-specific AI configuration**, +and choose a different provider configuration or models for that company. + +Leaving that setting off uses the global configuration. Replacing a key updates the +stored key; leaving its masked value unchanged retains it. + +## Data and permissions + +Prompts and any business data requested through the module's read-only tools are +sent to OpenRouter and the selected model provider. Enable the module only with +provider and model choices appropriate for your business data. + +Tools operate in the active company and respect the signed-in user's InvoiceShelf +permissions. The module cannot create or change invoices, expenses, customers, +payments, or other business records. Verify amounts and document details in the +application before acting on an answer. + +API keys are encrypted at rest and masked in settings. An assistant response is not +a reason to share an administrator password or increase another user's permissions. + +## Troubleshooting + +If the connection test fails, check the provider key, available provider credit, +selected model, and provider URL. After changing settings, save and test again. + +If chat cannot access a record, check the active company and your normal permission +to view that record. If only writing tools are missing, confirm **Editor text +generation** is enabled separately from chat. + +## Disable or remove the module + +Disabling hides the module's controls and routes but retains its configuration and +conversations. Uninstalling removes the package. Selecting **Remove module data** +also removes stored module settings and conversations; this is permanent. + +See [Backups](./backups.md) before removing stored data. diff --git a/docs/v3/guide/ai-assistants.md b/docs/v3/guide/ai-assistants.md index 9cd8b1e..2a6e3c1 100644 --- a/docs/v3/guide/ai-assistants.md +++ b/docs/v3/guide/ai-assistants.md @@ -1,7 +1,7 @@ --- versions: ['3'] reviewed_against: c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7 -reviewed_hash: d3680360e46bb80cce274cb499f2a51afc4f121ac10c6791b49ef995c6732cc5 +reviewed_hash: 0f7761676adeac9a316a343d179f234fadc6615f6b016a17704b96fe97eba9dc anchor_aliases: requirements: redirect-domains safety: ai-assistants-mcp @@ -9,7 +9,7 @@ anchor_aliases: # AI assistants (MCP) -InvoiceShelf 3 includes an MCP server so a compatible assistant can work with your company’s data through authorized application tools. This is separate from **Ask AI in these docs**, which answers documentation questions and does not access your invoices. +InvoiceShelf 3 includes an MCP server so a compatible assistant can work with your company’s data through authorized application tools. This is separate from the optional [AI Assistant module](./ai-assistant-module.md) inside InvoiceShelf and from **Ask AI in these docs**, which answers documentation questions and does not access your invoices. ## Switching it on diff --git a/docs/v3/guide/modules.md b/docs/v3/guide/modules.md index 798b2de..161ed2c 100644 --- a/docs/v3/guide/modules.md +++ b/docs/v3/guide/modules.md @@ -1,7 +1,7 @@ --- versions: ['3'] reviewed_against: c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7 -reviewed_hash: d72256251aa028f63c168ed41341fe1c538dbe5034a26ba939c34e45e53cdf01 +reviewed_hash: a147389d5088bb1bd1b5db2949100769d8b9f45badb4833108648abad96cdb05 --- # Modules @@ -23,3 +23,16 @@ Installation and activation are administrator tasks. Within a company, **Setting ![InvoiceShelf 3 company module settings](/images/v3/modules.webp) If access changes on the website, reconnect or refresh the installation as the interface instructs. Do not share marketplace tokens or approval codes in screenshots or support messages. + +## Official module guides + +Optional module workflows have their own guides: + +- [Tasks and projects](./tasks-projects.md): projects, task views, timers, + timesheets, and preparing invoices from tracked work. +- [AI Assistant](./ai-assistant-module.md): provider configuration, chat, writing + tools, and access to company data. + +Install a compatible package first. A module guide does not mean that module is +bundled or enabled in your installation. For connecting an external assistant, +use [AI assistants (MCP)](./ai-assistants.md). diff --git a/docs/v3/guide/tasks-projects.md b/docs/v3/guide/tasks-projects.md new file mode 100644 index 0000000..7b77f82 --- /dev/null +++ b/docs/v3/guide/tasks-projects.md @@ -0,0 +1,86 @@ +--- +versions: ['3'] +reviewed_against: c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7 +reviewed_hash: a4eb7814a2da8658ac9de56406720cbe6c52b127e9c22c3861c3a7a8091a184c +--- + +# Tasks and projects + +**Tasks and Projects** is an optional official module for InvoiceShelf 3. This guide +covers module **0.2.1** with the v3 host described by this book. Install a compatible +module package before looking for these screens; they are not enabled by default. + +## Install and configure + +A super administrator installs and enables **Tasks and Projects** through +**Administration → Modules**. See [Modules](./modules.md) for marketplace pairing +and package compatibility. + +Open **Company Settings → Tasks and Projects** to set the default hourly rate, +time-rounding rules, first day of the week, and whether members may see each +other's time. Settings also control starting a timer when a task is created, +locking invoiced tasks, hiding invoiced tasks from the board, and which task/time +information appears on invoice lines. + +The module adds **Projects** and **Tasks** to the menu. If either is missing, check +that the module is enabled and that your company role permits viewing it. + +## Organize work in projects + +Create a project with a name, optional customer, status, and description. Set a +billable rate, budget, and due date when needed. A project without a customer is +internal work and is not available for customer invoicing. + +Use a project's tabs to review its overview, tasks, time, and members. Members can +have project-specific hourly rates. Check the customer and currency before +starting work that will be billed. + +## Choose a task view + +Open **Tasks** and use the view selector: + +- **List** shows sortable task rows. +- **Board** groups tasks by the company's task statuses and supports drag ordering. +- **Week** shows the timesheet for the selected week. + +Project, member, and status filters stay in the URL when switching views. Open a +task to see its details and time log. + +## Track time + +Start or stop a timer from a task row, board card, task page, or the floating timer +control. The header shows the elapsed time and links to the running task. Only one +timer can run per user in each company; starting another offers to stop the first. + +You can also enter time manually. Review its start, end, duration, description, +billable flag, and member. Rounding follows the company's module settings. + +Rates are resolved from the task, then the member's project rate, the project +rate, and finally the company default. The rate is saved with the time entry so a +later rate change does not rewrite past work. + +## Turn work into an invoice + +Select **Invoice** from a task, a selection of tasks, or a project to prepare a +**draft invoice**. The draft opens in InvoiceShelf's invoice editor with one line +per task. Review the dates, descriptions, tax, and totals before sending it. + +A selection spanning different customers or currencies is refused. Use separate +invoices for those groups. + +The **Unbilled time** page, linked from Reports and the Projects header, brings +uninvoiced time together across projects. Use it to review what is ready to bill +and leave individual entries out when necessary. + +Once an entry is on an invoice, its time, billable flag, and task cannot be changed. +Its description remains editable. Your role needs the module's invoicing permission +and InvoiceShelf's create/edit-invoice permissions to use this workflow. + +## Disable or remove the module + +Disabling the module hides its screens and routes while retaining data. +Uninstalling removes the package. Selecting **Remove module data** also removes +the module's settings and stored project/task/time records; this is permanent. + +Back up the installation before removal and review invoices already created from +tracked work. See [Backups](./backups.md). diff --git a/drafts/README.md b/drafts/README.md new file mode 100644 index 0000000..21ad008 --- /dev/null +++ b/drafts/README.md @@ -0,0 +1,15 @@ +# Unreleased documentation + +This directory holds user guides for features that are not included in the +published books' pinned releases. The website importer reads only `docs/`, so +these drafts do not enter published navigation, keyword search, or AI answers. + +| Draft | Application work | Publication condition | +|---|---|---| +| [Bills and supplier payments](./v3/guide/purchasing.md) | [InvoiceShelf PR #903](https://github.com/InvoiceShelf/InvoiceShelf/pull/903) | Review against the release that includes purchasing. | + +To publish a draft, verify the final implementation and UI against the target +release, move it into the appropriate versioned book, add navigation, and record +its real source review and hash. Update the book's baseline and screenshots when +advancing the release. Never label unreleased behavior as available in the current +book merely to pass validation. diff --git a/drafts/v3/guide/purchasing.md b/drafts/v3/guide/purchasing.md new file mode 100644 index 0000000..2a21ab0 --- /dev/null +++ b/drafts/v3/guide/purchasing.md @@ -0,0 +1,236 @@ +--- +status: unreleased +target_version: '3' +source_repository: InvoiceShelf/InvoiceShelf +source_commit: 9fba5b7a6753f95a2cedd1d92947c7570aeff184 +source_path: docs/features/purchasing.md +pull_request: https://github.com/InvoiceShelf/InvoiceShelf/pull/903 +--- + +# Bills and supplier payments + +**Unreleased:** this guide describes the current purchasing work in app PR #903, +not InvoiceShelf 3.0.0-alpha.10. It is excluded from the published books, search, +and AI indexing. Verify it against the release that includes purchasing before +promoting it into `docs/v3/guide/`. + +## Navigation + +The Purchases menu contains **Suppliers**, **Bills**, **Expenses**, and **Payments**. Use the view selector in each list header: + +- Bills offers **Bills** and **Credits** views. +- Payments offers **Payments** and **Refunds** views. + +The info icon beside a page or report-section title opens its explanation. The same +control is used across the business screens, including sales, customers, items, and reports. + +Sales and Purchases both use **Payments** in their menus. Their section headings, +collapsed-sidebar tooltips, and search results identify which side a payment belongs to. + +The available views follow the user's permissions. Existing links to credits and +refunds still open the corresponding screen. + +## Choosing a record + +Use **Expenses** for a purchase already paid. Use **Purchases → Bills** when a supplier +invoice needs a balance and payment history. Paying a bill creates a supplier payment; +it does not create a second expense. + +Choose a supplier from the searchable card, or use **New supplier** inside the picker. +The inline form has the same fields as the Suppliers screen, including addresses and +purchase defaults. Its currency, payment terms, and expense category prefill new +purchases. Editing the selected supplier updates the card without changing amounts +or dates already entered. Suppliers have no customer portal login. Existing expenses +can be associated with a supplier without converting them into bills; the supplier +remains optional for expenses. + +Category, payment-method, and purchase-tax selectors offer inline creation when the +user has permission. Saving selects the new record in the field that opened the dialog; +a new tax is added to the line's existing selection. Cancelling keeps the purchase +draft intact. A supplier's default category can also be created inside its form. +Settled bills and linked credits keep their supplier fixed. Refunds display the supplier belonging to the chosen source. + +## Custom fields + +In **Settings → Custom Fields**, choose **Supplier** or **Bill** to add internal +fields such as a supplier account number, purchase-order number, or department. +Configured fields appear alongside the standard fields; the supplier's inline +dialog and standalone form use the same definitions. Answers are visible on the +record's detail screen. Supplier answers stay with the supplier and are not +automatically copied onto bills. + +Users who can work with the relevant records can fill in their fields without +access to custom-field Settings. Required fields and configured constraints are +validated when saving. Paid or credited bills still allow custom-field edits under +the bill-edit permission, while their financial details remain locked. Void bills +remain read-only. + +This support is for supplier and bill records. It does not add fields to bill lines, +credits, payments or refunds, and these internal fields do not print on PDFs. + +## Recording a bill + +Choose the supplier, supplier reference, document date, due date, and currency. Each +line has a description, quantity, unit price, category, optional percentage discount, +and purchase taxes. Choose whether prices include tax. Save as Draft while preparing +it, or Recorded when it should contribute to payables and purchase reporting. Bills, +supplier credits, payments and refunds are numbered per company, like invoices +(`BILL-000001`, `SC-000001`, `SP-000001`, `SR-000001`); the company settings +`bill_number_format`, `supplier_credit_number_format`, `supplier_payment_number_format` +and `supplier_refund_number_format` take the same placeholders as invoice numbers. Attach the +original PDF or image; downloads require company access and the document's permission. + +Use **New supplier payment** for money already sent. Enter its actual date, amount, method, +and reference. A payment can cover several bills from the same supplier in the same +currency. The unapplied remainder is an advance available for later bills. + +On a supplier payment, **Manage allocations** changes which bills it settles. Zero +releases an allocation, reopening that bill. Payment creation and allocation updates +are separate permissions. Supplier details link to the supplier's bills, payments, +credits and refunds, with balances grouped by currency. + +## Credits and refunds + +A supplier credit reduces purchase cost. A refund records money returned. Creating or +applying a credit does not itself move cash. + +From a bill, **More → New supplier credit** retains the original prices and tax snapshots. Enter +returned quantities; partial credits together cannot exceed the original quantities. +A paid bill can be credited. Its payment history remains, while the new credit can be +applied to another bill or refunded. A standalone supplier credit is also supported. +From an expense assigned to a supplier, **New supplier credit** accepts the amount credited. + +On a supplier credit or payment with an available balance, **More → New supplier refund** records +money actually returned. Allocated funds must first be released before a payment can +be refunded. A refund cannot exceed the available balance. + +**More → Void** corrects an entry made in error and requires a reason. It is not a substitute +for recording returned cash. A bill cannot be voided while settlements or active linked +credits remain; credits cannot be voided while allocations or active refunds remain; +payments cannot be voided while active refunds remain. A void keeps its reason on the +record. + +## Not yet available + +Recurring bills and recurring paid expenses are planned as a follow-up, built on +a scheduler shared with recurring invoices rather than a second engine. Until then, +recurring supplier charges are entered as they arrive. + +## Reports + +**Reports → Purchases** offers a period picker, an optional supplier filter, and a +PDF download of the same figures. The supplier selector is available to users with +supplier-view permission; financial-report permission is required for the report +and its PDF. Existing `/admin/reports/purchases` links open the Purchases tab. + +- Cash movement uses expense and supplier payment/refund dates. Advances are included. +- Purchase costs use expense, open-bill, and supplier-credit document dates. Settlement + records do not add further costs. Purchase tax uses the saved document tax breakdown. +- Current payables show outstanding bills, overdue balances, due within 30 days, and due + later. The screen and PDF label the balance date in the company's timezone. These + are current balances, independent of the selected period. Unapplied advances and + unused credits are separate until explicitly allocated. +- Company totals use stored base-currency amounts. Supplier balances retain their own + currency; allocations between different currencies are not supported. + +The existing cash dashboard and cash profit/loss report include supplier payments and +refunds. The profit/loss PDF explicitly labels its cash basis and includes advances. +The dashboard also displays current payables for users with bill-view permission. + +**Reports → Taxes** is unchanged: bills and supplier credits are not part of it yet. +They join it in a follow-up that moves both sides of that report to document dates. + +The Expenses report continues to cover direct expenses. Historical payables and +custom-field filtering/grouping are not provided by this reporting pass. + +## API + +All endpoints require staff authentication and the `company` header. The generated +OpenAPI document describes the resource inputs and responses. Money uses the host's +integer minor-unit convention (100 represents 1.00). + +New resources: `/api/v1/suppliers`, `/bills`, `/supplier-payments`, `/supplier-credits`, +and `/supplier-refunds`. Existing `/api/v1/payments` remains the customer-receipt API. + +Example bill body: + +```json +{ + "supplier_id": 1, + "currency_id": 142, + "exchange_rate": 1, + "document_date": "2026-09-01", + "due_date": "2026-09-30", + "status": "OPEN", + "reference": "SUPPLIER-123", + "tax_included": false, + "items": [{ + "description": "Hosting", + "expense_category_id": 1, + "quantity": 1, + "price": 100000, + "discount": 0, + "tax_type_ids": [] + }] +} +``` + +Use IDs returned by the installation's reference endpoints, not the example IDs. +`GET /api/v1/purchase-options` supplies currencies, categories, purchase taxes, and +manual payment methods without requiring access to customer payment settings. + +`GET /api/v1/reports/purchases` accepts `from_date`, `to_date`, and optional +`supplier_id`. Its `supplier` identifies the selected supplier (or is `null`), and +`payables.as_of_date` identifies the current balance date. The dashboard exposes the +same dated payables summary only to users with bill-view permission. +`GET /reports/purchases/{hash}` accepts the same filters and supports the existing +`preview` and `download` flags. The hash identifies the company; authentication, +report permission, and company membership are still required. + +Pass `custom_field_model=Supplier` or `custom_field_model=Bill` to also receive +the corresponding definitions in `data.custom_fields`. This request uses the +relevant record permissions. + +Supplier and bill writes accept `customFields: [{"id": 1, "value": "PO-123"}]`; +their responses expose stored answers as `fields` using the existing custom-field +resource format. IDs must belong to the active company and the correct model. +Creation applies definition defaults. Updates preserve omitted answers; an +explicit `null` clears an optional answer. Required fields are checked against +the resulting values, including defaults and preserved answers. + +Payment creation accepts `allocations: [{"bill_id": 1, "amount": 100000}]` and may leave +an unapplied balance. `PUT /supplier-payments/{id}/allocations` and +`PUT /supplier-credits/{id}/allocations` replace the entire allocation set; an empty +array releases every allocation. + +Credits use the bill's item shape. For a linked credit, provide `source_bill_id` and +`source_bill_item_id` on each line; quantity determines the credit and supplied prices +are replaced with source snapshots. For an expense credit, provide `source_expense_id` +and `source_amount`, with the expense already assigned to the supplier. + +Refund creation accepts exactly one of `supplier_payment_id` or `supplier_credit_id`, +plus `amount`, `payment_date`, and `exchange_rate`. Optional fields are +`payment_method_id`, `reference`, and `notes`. + +`POST /{resource}/{id}/actions` accepts `open`/`void` for bills and `void` for monetary +records. A void requires `reason`. + +## Upgrade + +Back up the database and storage. Pause writers and workers during migration, deploy +the matching application code, run migrations, then restart workers and clear cached +configuration/authorization data through the application's normal upgrade process. + +The migration renames `payments` to `customer_payments` and `payment_allocations` to +`customer_payment_allocations`. It changes the persisted morph aliases `payment` and +`payment_allocation` to `customer_payment` and `customer_payment_allocation` in media, +email logs, custom-field values, and authorization/type-bearing columns. Record IDs, +foreign-key column names, receipt URLs, and public v1 discriminator strings remain. +A module that queries `payments` or `payment_allocations` directly must switch to +`customer_payments` and `customer_payment_allocations`; one that goes through the +`Payment` model or the API is unaffected. +Historical migrations are retained. A new migration synchronizes owner role grants. + +The new purchasing tables are additive. Historical expenses are not converted and +suppliers are not inferred. New PHP model namespaces remain canonical; no class aliases +or duplicate legacy models are introduced. diff --git a/verification/guide-consolidation-2026-09-28.md b/verification/guide-consolidation-2026-09-28.md new file mode 100644 index 0000000..90d25ec --- /dev/null +++ b/verification/guide-consolidation-2026-09-28.md @@ -0,0 +1,36 @@ +# User-guide consolidation — 2026-09-28 + +The documentation source PR [#31](https://github.com/InvoiceShelf/docs/pull/31) +merged into `master`. The local starting tree matches merged commit +`b7c1584e7048357f7b9cd72d75382c663670c6f8`. Git fetch was unavailable during this +pass; the tree identity was verified through the GitHub API. + +The website renderer lives in a separate PR, +[website #54](https://github.com/InvoiceShelf/website/pull/54), which was still open +when checked. Content merge, website deployment, and public-site cutover are +separate steps; none is inferred from another. + +| Source | Canonical guide | Treatment | +|---|---|---| +| Existing v2/v3 documents | `docs/v2/`, `docs/v3/` | Already present in the merged source repository; preserved. | +| Tasks & Projects README usage | `docs/v3/guide/tasks-projects.md` | Reviewed against module 0.2.1 source and the alpha.10 extension runtime. | +| AI Assistant README usage | `docs/v3/guide/ai-assistant-module.md` | Reviewed against module 1.0.0 source; corrected setup order so the enabled-only Test connection control is described accurately. | +| App `docs/features/purchasing.md` | `drafts/v3/guide/purchasing.md` | Consolidated as unreleased content from current app PR commit `9fba5b7a`; not advertised in alpha.10. | +| App `mobile/README.md` | `docs/v3/mobile.md` | User-facing access/connection coverage already exists; native build and packaging details remain in the application README. | +| Website `docs/operations.md`, billing/domain launch notes | Website repository | Operational runbooks; outside user-guide consolidation. | +| App architecture decisions, module contributor guides, private specs/research | Owning repositories | Engineering documentation; retained with its source. | + +The v2 book has no Tasks & Projects or AI Assistant module page because these +packages require v3. Both published release baselines are unchanged. No new +screenshots were introduced or relabelled; the existing captures retain their +release provenance. New module pages were reviewed from source. Browser review +of the new rendered pages remains required before marking visual QA complete. + +The module READMEs and app development guide remain available as release/source +context. Cross-repository link-only replacements can follow after this docs change +lands, so published packages never point at missing guide URLs. + +The purchasing draft was imported from the latest PR source rather than the older +local app checkout. In that source, recurring supplier costs and changes to the +existing Tax report are follow-ups, so the draft does not claim those features +are included.