Add Invoice flow docs and refresh billing concept and reference for 3.1 - #79
Add Invoice flow docs and refresh billing concept and reference for 3.1#79gauritejusa wants to merge 3 commits into
Conversation
Add ten flow documents for the Invoice resource under flows/billing/invoice: view, create, edit details, edit items, issue, print, record payment, mark as balanced, lock and unlock, and cancel. Register them in the 3.1 sidebar with Billing and Invoice categories. Correct the concept page: a lock applies at any status rather than only after issue, it hides the totals, and it needs Can Manage Locked Invoice even to read. Document the free-cancel period that decides whether cancelling needs Can Write Invoice or Can Destroy Invoice, and add the permitted status transitions. Extend the reference page with the API endpoints and custom actions, filtering and ordering, the permission matrix with roles, the status transition rules, and the INVOICE_FREE_CANCEL_PERIOD_MINUTES setting. Correct the claim that invoice numbers are generated only for return invoices; they are generated on every create when the client does not supply one.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Generated by Docs Reviewer for #79 · opus50 · 104.5 AIC · ⌖ 15.8 AIC · ⊞ 11K
Reorders sections to What it represents -> Lifecycle -> Refunds -> Locking -> How it connects -> Permissions -> Related, and simplifies the Lifecycle section by replacing the status-transition table and duplicate cancel-permission paragraph with a single terse prose paragraph, matching the Encounter concept page's style.
Deploying coredocs with
|
| Latest commit: |
32a9016
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://632fbf9b.coredocs.pages.dev |
| Branch Preview URL: | https://docs-invoice-flows.coredocs.pages.dev |
On the account screen (facility:account:show scope), i creates an invoice and c adds credit. The doc incorrectly said c; corrected to i, matching care_fe/src/config/keyboardShortcuts.json.
There was a problem hiding this comment.
Generated by Docs Reviewer for #79 · opus50 · 154.9 AIC · ⌖ 17 AIC · ⊞ 11K
Comments that could not be inline-anchored
versioned_sidebars/version-3.1-sidebars.json:84
Mirroring (checklist 11). This whole change lands in version-3.1 only. The shared conventions require versioned_docs/version-3.0 and version-3.1 to stay byte-identical, so the ten new flows, both _category_.json files, and the edits to concepts/billing/invoice.mdx and references/billing/invoice.mdx must be mirrored to versioned_docs/version-3.0/..., and this sidebar block added to versioned_sidebars/version-3.0-sidebars.json too. Without the 3.0 copies the flows are invisibl…
versioned_docs/version-3.1/concepts/billing/invoice.mdx:40
Permissions in plain words (checklist 5). A concept must not carry a permission slug in prose: can_manage_locked_invoice should read "a role with the permission to manage locked invoices". The slug belongs in the reference doc. The same applies to the sentence in the Locking section as a whole.
versioned_docs/version-3.1/flows/billing/invoice/issue-invoice.mdx:69
Display labels, not raw values (checklist 4), and layer discipline (checklist 3). A flow is strictly user-facing, so a "Stored value" column exposing draft / entered_in_error is reference-doc content. Drop the stored-value column and keep only the display labels, or drop the table and link the reference instead. The same table is repeated in mark-invoice-as-balanced.mdx (line 77) and lock-and-unlock-invoice.mdx (line 77) — remove it there too.
versioned_docs/version-3.1/flows/billing/invoice/issue-invoice.mdx:86
Layer discipline (checklist 3). "Call the cancel invoice API to cancel the invoice" is a backend error string naming an API — a flow must not mention API endpoints. Rewrite as user-facing guidance: "You cannot cancel an invoice with a status change. Use the cancel action — see Cancel an invoice." The same string appears in cancel-invoice.mdx line 90.
versioned_docs/version-3.1/flows/billing/invoice/lock-and-unlock-invoice.mdx:64
Template conformance (checklist 8). The flow template's sections are Overview, Pre-requisites, Permissions, Steps, Expected Outcome, Related — in that order. ## Lock rules is an invented section between Expected Outcome and Related. Fold these rules into the relevant steps or into Expected Outcome. Same issue for ## Status rules in issue-invoice.mdx (line 65) and mark-invoice-as-balanced.mdx (line 71), and ## Validation messages in record-invoice-payment.mdx (line 79).
versioned_docs/version-3.1/flows/billing/invoice/record-invoice-payment.mdx:231
Unverified as written: "Only a record that is active and complete counts towards the totals" describes internal record state, which is reference-layer detail (checklist 3) and is not visible to the user in this flow. Either drop it here and cover it in references/billing/payment-reconciliation.mdx, or cite where in ohcnetwork/care this filter is applied.
versioned_docs/version-3.1/flows/billing/invoice/record-invoice-payment.mdx:96
(Re-anchoring my previous note to the right line.) "Care creates a payment reconciliation record. Only a record that is active and complete counts towards the totals" is internal record state — reference-layer content per checklist 3, and not something the user sees in this flow. Drop it here, or cite the place in ohcnetwork/care where the filter is applied.
versioned_docs/version-3.1/flows/billing/invoice/record-invoice-payment.mdx:17
The Permissions table lists only Can Read Invoice and Can Manage Locked Invoice, so a reader cannot tell what permission actually lets them record the payment — the note below defers to another reference. Name the payment reconciliation write permission here in its display form (per checklist 5 and the flow template), traced from the payment reconciliation viewset's authorize methods in ohcnetwork/care.
versioned_docs/version-3.1/flows/billing/invoice/view-invoices.mdx:2
Review summary (my consolidated review body was submitted empty; posting it here).
A substantial, well-researched addition. Every keyboard shortcut I checked (i, b, r, p, o, e, Enter, Esc) matches care_fe/src/config/keyboardShortcuts.json. The flow sidebar was correctly updated by hand, slugs are kebab-case verb phrases, H1s are sentence case, and I found no corruption markers, {#...} ids or bare braces.
Main findings, each raised inline: (1) the whole change lands in …
1 participant
What this does
Documents the Invoice resource in the billing and accounts area for version 3.1: ten new flow documents, plus corrections and additions to the existing concept and reference pages.
Everything here is grounded in the code —
care/emr/models/invoice.py,care/emr/resources/invoice/,care/emr/api/viewsets/invoice.py,care/security/permissions/invoice.pyon the backend, andsrc/pages/Facility/billing/invoice/,src/components/Billing/Invoice/,src/types/billing/invoice/on the frontend. Display labels were resolved throughpublic/locale/en.jsonrather than guessed.New flow documents
Under
versioned_docs/version-3.1/flows/billing/invoice/, ordered as a user meets them:Registered in
versioned_sidebars/version-3.1-sidebars.jsonunder a new Billing → Invoice category, with matching_category_.jsonfiles. Without the sidebar entry the pages build but stay invisible.Corrections to existing pages
Concept page. The Locking section was wrong. It said an issued invoice can be locked to freeze it against edits. In fact a lock applies at any status, does not change the status, hides the money (net and gross are reported as zero to every reader), and requires
can_manage_locked_invoiceeven to open the invoice. Also added the permitted status transitions and clarified that the permission needed to cancel depends on the free-cancel period.Reference page. It claimed invoice numbers are auto-generated "for return invoices". They are generated on every create when the client does not supply one. Corrected, and added the API endpoints with all six custom actions, filtering and ordering, the permission matrix with system roles, the status transition rules, and the
INVOICE_FREE_CANCEL_PERIOD_MINUTESsetting.A note on permissions in the UI
The invoice screens do no permission gating —
InvoiceShow.tsxnever callsusePermissions, so Lock, Unlock and Cancel are shown to every user and only the server refuses. The docs describe what the server permits and deliberately do not claim the interface hides anything. The only real interface conditions are status-based: Edit Details, Edit Items, Add Charge Item and Issue Invoice appear only for a draft; Mark as balanced and Record Payment only for an issued invoice; Create Invoice only when the account is active and billable.Scope
Version 3.1 only, by explicit decision. Version 3.0 is untouched. Refund invoices are excluded: they are generated automatically when a supply delivery return order completes, and have no user-facing flow.
Validation
npm run buildpasses for both locales, generatingbuildandbuild/ml. All ten pages render in each.versioned_docsis clean: no tool-call leakage, no{#anchor}heading ids..mdxlinks across the twelve touched documents resolve to files on disk: 0 broken.Code issues found while researching, not fixed here
care/emr/resources/invoice/sync_items.py.attach_account_to_invoicehas no frontend caller and looks like dead code./billing/invoice/:invoiceId/printand/billing/invoices/:invoiceIds/print.