Add Reports feature documentation

[rodrigogsn]

Summary

This PR adds documentation for the Stellar Disbursement Platform (SDP) Reports feature: Admin Guide content for the Reports UI and API reference for the two PDF export endpoints (wallet statement and payment transaction notice). It also documents the optional Reports feature flag and reorders the API Reference sidebar.

Branch: sdp-report-generation

Screen.Recording.2026-02-13.at.17.37.42.mov

---

1. Admin Guide — Reports UI

New file: docs/platforms/stellar-disbursement-platform/admin-guide/user-interface/reports.mdx

• New page under User Interface describing the Reports screen.
• Overview: Reports page for exporting PDFs — wallet statement (date range) and individual transaction notice (single payment).
• Feature flag: Info block explaining that the Reports menu item and /reports route are optional and disabled by default. Organization owners can enable it from the Settings page using the "Enable Reports" toggle. This sets the reporting_enabled flag on the organization (stored in the database), which is served via the /app-config endpoint. When disabled, the Reports entry is hidden from the sidebar and the /reports route returns 404.
• Wallet Statement: Preset period (This month, Last month, QTD, YTD), custom From/To dates, Download Statement, example filename statement_YYYYMMDD-YYYYMMDD.pdf.
• Individual Transaction Notice: Search by SDP Transaction ID or Payment ID, result table (Transaction ID, Payment ID, Date, Disbursement Name), radio selection, optional Notes (up to 500 chars), Download Notice, example filename transaction_notice_{paymentID}.pdf.
• Wallet Statement PDF layout: Header (logo, name, Operated by, Generated on), statement period, wallet address (Stellar Expert link), account summary table (per-currency Beginning Balance, Total Credits, Total Debits, Ending Balance), transactions table (Date, Transaction ID, Payment ID, Counterparty, Debits, Credits, Balance).
• Transaction Notice PDF layout: Header, title and Stellar Transaction ID (Stellar Expert link), transaction summary (Amount, Currency, Status, Payment ID, Status Update At), transaction details (Sender / Recipient), disbursement details (Disbursement ID, Name).
• Info: Transaction and wallet links in PDFs open in Stellar Expert; network (testnet/public) is set by backend STELLAR_EXPERT_URL (default testnet if unset).

New assets:

• static/assets/SDP/SDP49.1.png — Reports page overview (Wallet Statement + Individual Transaction Notice).
• static/assets/SDP/SDP49.2.png — Sample Wallet Statement PDF (account summary and transactions).
• static/assets/SDP/SDP49.3.png — Sample Transaction Notice PDF (summary and details).

---

2. API Reference — Reports

New file: docs/platforms/stellar-disbursement-platform/api-reference/reports.tag.mdx

• Reports tag index page: short intro (PDFs via gofpdf, A4, statement = multi-page ledger, notice = single-page per payment) and DocCardList for the Reports endpoints.

New file: docs/platforms/stellar-disbursement-platform/api-reference/get-statement-export.api.mdx

• Endpoint: GET /reports/statement.
• Summary: Ledger-style PDF for the tenant’s distribution account over a date range (gofpdf, multi-page, A4). Stellar (non-Circle) only; 400 if not Stellar.
• Parameters (from OpenAPI): from_date, to_date (required), asset_code (optional), base_url (optional).
• "Fields in the generated PDF": Tables grouped by source (Request, Context, Calculated, DB, Horizon) with code-style names (from_date, to_date, ending_balance, total_credits, Organizations, Payment.status_history, ReceiverWallet.Receiver, Payment, Assets, Horizon GetBalances, etc.).
• Request: Statement period (from_date, to_date).
• Context: Wallet address, Account (summary).
• Calculated: Beginning balance, Total credits/debits, Ending balance, Running balance (with variable names in backticks).
• DB: Organization name/logo, Transaction line Updated at, Counterparty name, External payment ID, Asset list (non-native).
• Horizon: Transaction line ID, Created at, Type, Amount, Counterparty address, Asset list.
• Request/response and status codes sections (from OpenAPI).

New file: docs/platforms/stellar-disbursement-platform/api-reference/get-payment-export.api.mdx

• Endpoint: GET /reports/payment/{id}.
• Summary: Single-page Transaction Notice PDF for a payment; optional internal_notes (max 500 chars); gofpdf, A4, payment/disbursement/org branding.
• Parameters: id (path), internal_notes (query, optional), base_url (query, optional).
• "Fields in the generated PDF": Tables by source (Request, Context, DB, Horizon) with code-style names (internal_notes, Organizations, Payment, Payment.Asset, Payment.status_history, ReceiverWallet.StellarMemo, ReceiverWallet.Receiver, ReceiverWallet, ReceiverWallet.Wallet, Payment.Disbursement, Disbursement.status_history, AuthManager.GetUsersByID, TransactionDetail.Memo, TransactionDetail.FeeCharged, FeeCharged, stroops, status labels DRAFT → Created, STARTED → Approved).
• Request/response and status codes sections (from OpenAPI).

---

3. API Reference — Sidebar

Modified: docs/platforms/stellar-disbursement-platform/api-reference/sidebar.ts

• New category "Reports" (with link to reports doc), containing:
  • Get Statement (PDF) — get-statement-export
  • Get Payment Transaction Notice (PDF) — get-payment-export
• Reorder: Category order in the sidebar was adjusted (e.g. Reports and possibly other groups) so the sidebar order is consistent with the rest of the API reference.

---

4. OpenAPI

Modified: openapi/stellar-disbursement-platform/main.yaml

• New tag: Reports with description for PDF endpoints (gofpdf, A4, statement vs notice).
• New path: GET /reports/statement
  • Parameters: from_date, to_date (required, date), asset_code (optional), base_url (optional).
  • Responses: 200 (PDF, Content-Disposition, Content-Type: application/pdf), 400, 401, 403, 404 (e.g. asset not found).
  • Security: BearerAuth.
• New path: GET /reports/payment/{id}
  • Parameters: id (path), internal_notes (query, optional, maxLength 500), base_url (optional).
  • Responses: 200 (PDF), 401, 403, 404 (payment not found).
  • Security: BearerAuth.

Modified: openapi/stellar-disbursement-platform/bundled.yaml

• Same Reports tag and paths as in main.yaml (bundled spec updated so generated docs and tooling use the new endpoints).

---

File list

Change	Path
A	docs/platforms/stellar-disbursement-platform/admin-guide/user-interface/reports.mdx
A	docs/platforms/stellar-disbursement-platform/api-reference/get-payment-export.api.mdx
A	docs/platforms/stellar-disbursement-platform/api-reference/get-statement-export.api.mdx
A	docs/platforms/stellar-disbursement-platform/api-reference/reports.tag.mdx
M	docs/platforms/stellar-disbursement-platform/api-reference/sidebar.ts
M	openapi/stellar-disbursement-platform/bundled.yaml
M	openapi/stellar-disbursement-platform/main.yaml
A	static/assets/SDP/SDP49.1.png
A	static/assets/SDP/SDP49.2.png
A	static/assets/SDP/SDP49.3.png

---

Commits (in order)

1. docs(admin-guide): add Reports UI page and screenshots — Adds Reports UI page and three screenshots (SDP49.1–SDP49.3).
2. docs(api-reference): add Reports API (statement and payment PDF exports) — Adds OpenAPI Reports tag/paths, Reports tag doc, two endpoint docs with "Fields in the generated PDF" tables by source and code-style names, and Reports sidebar category.
3. docs: reorder API Reference sidebar — Adjusts API Reference sidebar category order.
4. docs(admin-guide): add feature flag info in Reports UI — Documents the reporting_enabled organization flag (toggled from Settings, served via /app-config) and when Reports is hidden.

---

Testing / checks

• npm run check:mdx (or equivalent) in stellar-docs should pass.
• Confirm in the built site: Admin Guide → User Interface → Reports, and API Reference → Reports → Get Statement (PDF) / Get Payment Transaction Notice (PDF).
• Confirm sidebar shows the new Reports category and the updated order.

[Copilot]

Pull request overview

Adds end-user and API documentation for the SDP “Reports” feature (PDF exports), including new OpenAPI definitions and Docusaurus API reference navigation updates.

Changes:

• Added Admin Guide page documenting the Reports UI and feature-flag behavior.
• Added OpenAPI Reports tag plus two PDF export endpoints (/reports/statement, /reports/payment/{id}) and corresponding API reference pages.
• Updated the API Reference sidebar to include a new “Reports” section.

Reviewed changes

Copilot reviewed 6 out of 10 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
docs/platforms/stellar-disbursement-platform/admin-guide/user-interface/reports.mdx	New Admin Guide page describing Reports UI, feature flag, and PDF layouts.
docs/platforms/stellar-disbursement-platform/api-reference/reports.tag.mdx	New “Reports” tag landing page for the API reference.
docs/platforms/stellar-disbursement-platform/api-reference/get-statement-export.api.mdx	New API reference page for statement PDF export.
docs/platforms/stellar-disbursement-platform/api-reference/get-payment-export.api.mdx	New API reference page for payment transaction notice PDF export.
docs/platforms/stellar-disbursement-platform/api-reference/sidebar.ts	Adds “Reports” category and links to the new endpoints.
openapi/stellar-disbursement-platform/main.yaml	Adds Reports tag + two new report paths (and applies substantial formatting updates).
openapi/stellar-disbursement-platform/bundled.yaml	Mirrors the Reports tag/paths in the bundled spec used by docs/tooling.
static/assets/SDP/SDP49.1.png	New screenshot asset for Reports UI.
static/assets/SDP/SDP49.2.png	New screenshot asset for statement PDF example.
static/assets/SDP/SDP49.3.png	New screenshot asset for transaction notice PDF example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.