feat: Add "Exclude from reports" flag for categories

Adam · Adam · commit 48c6ba0d29b5 · 2026-05-02T01:16:02.000+01:00
Categories can now be marked as excluded from reports. Excluded
categories are hidden from budget analysis, spending reports,
dashboard totals, and budget alerts.

Useful for investment adjustments, internal bookkeeping, reimbursements,
or any category where transactions shouldn't count as real income
or expenses.

- New excluded_from_reports column on budget_categories (migration 059)
- Checkbox in category create/edit form
- Filtering in CategoryService, BudgetAlertService, ReportAggregator
diff --git a/budget/lib/Controller/CategoryController.php b/budget/lib/Controller/CategoryController.php
@@ -149,7 +149,8 @@ public function create(
         ?string $icon = null,
         ?string $color = null,
         ?float $budgetAmount = null,
-        int $sortOrder = 0
+        int $sortOrder = 0,
+        bool $excludedFromReports = false
     ): DataResponse {
         try {
             // Validate name (required)
@@ -190,7 +191,8 @@ public function create(
                 $icon,
                 $color,
                 $budgetAmount,
-                $sortOrder
+                $sortOrder,
+                $excludedFromReports
             );
             return new DataResponse($category, Http::STATUS_CREATED);
         } catch (\Exception $e) {
@@ -274,6 +276,9 @@ public function update(
             if ($sortOrder !== null) {
                 $updates['sortOrder'] = $sortOrder;
             }
+            if (array_key_exists('excludedFromReports', $params)) {
+                $updates['excludedFromReports'] = (bool) $params['excludedFromReports'];
+            }
 
             if (empty($updates)) {
                 return new DataResponse(['error' => $this->l->t('No valid fields to update')], Http::STATUS_BAD_REQUEST);
diff --git a/budget/lib/Db/Category.php b/budget/lib/Db/Category.php
@@ -32,6 +32,8 @@
  * @method void setCreatedAt(string $createdAt)
  * @method string|null getUpdatedAt()
  * @method void setUpdatedAt(string $updatedAt)
+ * @method bool|null getExcludedFromReports()
+ * @method void setExcludedFromReports(?bool $excludedFromReports)
  */
 class Category extends Entity implements JsonSerializable {
     protected $userId;
@@ -43,6 +45,7 @@ class Category extends Entity implements JsonSerializable {
     protected $budgetAmount;
     protected $budgetPeriod;  // monthly, weekly, yearly, quarterly
     protected $sortOrder;
+    protected $excludedFromReports;
     protected $createdAt;
     protected $updatedAt;
 
@@ -51,6 +54,7 @@ public function __construct() {
         $this->addType('parentId', 'integer');
         $this->addType('budgetAmount', 'float');
         $this->addType('sortOrder', 'integer');
+        $this->addType('excludedFromReports', 'boolean');
     }
 
     /**
@@ -69,6 +73,7 @@ public function jsonSerialize(): array {
             'budgetAmount' => $this->getBudgetAmount(),
             'budgetPeriod' => $this->getBudgetPeriod() ?? 'monthly',
             'sortOrder' => $this->getSortOrder(),
+            'excludedFromReports' => $this->getExcludedFromReports() ?? false,
             'createdAt' => $this->getCreatedAt(),
             'updatedAt' => $this->getUpdatedAt(),
         ];
diff --git a/budget/lib/Migration/Version001000059Date20260502.php b/budget/lib/Migration/Version001000059Date20260502.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\Budget\Migration;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+/**
+ * Add excluded_from_reports flag to budget_categories.
+ * Categories with this flag are excluded from budget calculations,
+ * spending reports, and dashboard totals.
+ */
+class Version001000059Date20260502 extends SimpleMigrationStep {
+    public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+        /** @var ISchemaWrapper $schema */
+        $schema = $schemaClosure();
+
+        $table = $schema->getTable('budget_categories');
+        if (!$table->hasColumn('excluded_from_reports')) {
+            $table->addColumn('excluded_from_reports', Types::BOOLEAN, [
+                'notnull' => false,
+                'default' => false,
+            ]);
+        }
+
+        return $schema;
+    }
+}
diff --git a/budget/lib/Service/BudgetAlertService.php b/budget/lib/Service/BudgetAlertService.php
@@ -47,9 +47,12 @@ public function getAlerts(string $userId): array {
         $currentMonth = date('Y-m');
         $snapshotOverrides = $this->budgetSnapshotMapper->findEffectiveBatch($userId, $currentMonth);
 
-        // Filter to categories with effective budgets > 0
+        // Filter to categories with effective budgets > 0 (excluding excluded categories)
         $categoriesWithBudgets = [];
         foreach ($categories as $category) {
+            if ($category->getExcludedFromReports()) {
+                continue;
+            }
             $catId = $category->getId();
             $amount = isset($snapshotOverrides[$catId])
                 ? (float) ($snapshotOverrides[$catId]['amount'] ?? 0)
@@ -137,9 +140,12 @@ public function getBudgetStatus(string $userId): array {
         $currentMonth = date('Y-m');
         $snapshotOverrides = $this->budgetSnapshotMapper->findEffectiveBatch($userId, $currentMonth);
 
-        // Filter to categories with effective budgets > 0
+        // Filter to categories with effective budgets > 0 (excluding excluded categories)
         $categoriesWithBudgets = [];
         foreach ($categories as $category) {
+            if ($category->getExcludedFromReports()) {
+                continue;
+            }
             $catId = $category->getId();
             $amount = isset($snapshotOverrides[$catId])
                 ? (float) ($snapshotOverrides[$catId]['amount'] ?? 0)
diff --git a/budget/lib/Service/CategoryService.php b/budget/lib/Service/CategoryService.php
@@ -64,7 +64,8 @@ public function create(
         ?string $icon = null,
         ?string $color = null,
         ?float $budgetAmount = null,
-        int $sortOrder = 0
+        int $sortOrder = 0,
+        bool $excludedFromReports = false
     ): Category {
         // Validate parent if provided
         if ($parentId !== null) {
@@ -85,6 +86,7 @@ public function create(
         $category->setColor($color ?: $this->generateRandomColor());
         $category->setBudgetAmount($budgetAmount);
         $category->setSortOrder($sortOrder);
+        $category->setExcludedFromReports($excludedFromReports);
         $this->setTimestamps($category, true);
 
         return $this->mapper->insert($category);
@@ -426,6 +428,9 @@ public function getBudgetAnalysis(string $userId, ?string $month = null): array
         $expenseCategoryIds = [];
         $incomeCategoryIds = [];
         foreach ($categories as $category) {
+            if ($category->getExcludedFromReports()) {
+                continue;
+            }
             $catId = $category->getId();
             $budget = $effectiveBudgets[$catId]['amount'] ?? 0;
             if ($budget > 0) {
@@ -448,6 +453,9 @@ public function getBudgetAnalysis(string $userId, ?string $month = null): array
 
         $analysis = [];
         foreach ($categories as $category) {
+            if ($category->getExcludedFromReports()) {
+                continue;
+            }
             $catId = $category->getId();
             $budget = (float) ($effectiveBudgets[$catId]['amount'] ?? 0);
             if ($budget > 0) {
diff --git a/budget/lib/Service/Report/ReportAggregator.php b/budget/lib/Service/Report/ReportAggregator.php
@@ -207,8 +207,8 @@ public function generateSummary(
 
         $excludeTransfers = $accountId === null;
 
-        // Get spending breakdown
-        $summary['spending'] = $this->transactionMapper->getSpendingSummary(
+        // Get spending breakdown (filter out excluded categories)
+        $spending = $this->transactionMapper->getSpendingSummary(
             $userId,
             $startDate,
             $endDate,
@@ -218,6 +218,20 @@ public function generateSummary(
             $excludeTransfers
         );
 
+        $allCategories = $this->categoryMapper->findAll($userId);
+        $excludedCategoryIds = [];
+        foreach ($allCategories as $cat) {
+            if ($cat->getExcludedFromReports()) {
+                $excludedCategoryIds[$cat->getId()] = true;
+            }
+        }
+        if (!empty($excludedCategoryIds)) {
+            $spending = array_values(array_filter($spending, function ($item) use ($excludedCategoryIds) {
+                return !isset($excludedCategoryIds[$item['categoryId'] ?? 0]);
+            }));
+        }
+        $summary['spending'] = $spending;
+
         // Generate trend data (with currency conversion for multi-account view)
         $summary['trends'] = $this->generateTrendData($userId, $accountId, $startDate, $endDate, $tagIds, $includeUntagged);
 
@@ -302,10 +316,13 @@ public function getBudgetReport(string $userId, string $startDate, string $endDa
         $reportMonth = substr($startDate, 0, 7); // YYYY-MM from startDate
         $snapshotOverrides = $this->budgetSnapshotMapper->findEffectiveBatch($userId, $reportMonth);
 
-        // Collect category IDs that have budgets (considering snapshots)
+        // Collect category IDs that have budgets (considering snapshots, excluding excluded)
         $categoryIds = [];
         $resolvedBudgets = [];
         foreach ($categories as $category) {
+            if ($category->getExcludedFromReports()) {
+                continue;
+            }
             $catId = $category->getId();
             $budgeted = isset($snapshotOverrides[$catId])
                 ? (float) ($snapshotOverrides[$catId]['amount'] ?? 0)
diff --git a/budget/src/modules/categories/CategoriesModule.js b/budget/src/modules/categories/CategoriesModule.js
@@ -948,6 +948,9 @@ export default class CategoriesModule {
 
         const colorInput = document.getElementById('category-color');
         if (colorInput) colorInput.value = '#3b82f6';
+
+        const excludedCheckbox = document.getElementById('category-excluded-from-reports');
+        if (excludedCheckbox) excludedCheckbox.checked = false;
     }
 
     loadCategoryData(category) {
@@ -957,6 +960,11 @@ export default class CategoriesModule {
         document.getElementById('category-parent').value = category.parentId || '';
         document.getElementById('category-color').value = category.color || '#3b82f6';
 
+        const excludedCheckbox = document.getElementById('category-excluded-from-reports');
+        if (excludedCheckbox) {
+            excludedCheckbox.checked = category.excludedFromReports || false;
+        }
+
         // Load tag sets for this category
         this.app.renderCategoryTagSetsUI(category.id);
     }
@@ -991,11 +999,14 @@ export default class CategoriesModule {
             return;
         }
 
+        const excludedFromReports = document.getElementById('category-excluded-from-reports')?.checked || false;
+
         const categoryData = {
             name,
             type,
             parentId: parentId ? parseInt(parentId) : null,
-            color
+            color,
+            excludedFromReports
         };
 
         try {
diff --git a/budget/templates/index.php b/budget/templates/index.php
@@ -5524,6 +5524,14 @@ class="app-navigation-search-clear icon-close"
                 <small id="category-color-help" class="form-text"><?php p($l->t('Color for charts and display')); ?></small>
             </div>
 
+            <div class="form-group">
+                <label class="checkbox-label">
+                    <input type="checkbox" id="category-excluded-from-reports">
+                    <?php p($l->t('Exclude from reports')); ?>
+                </label>
+                <small class="form-text"><?php p($l->t('Transactions in this category will not count toward budgets, spending reports, or dashboard totals.')); ?></small>
+            </div>
+
             <!-- Tag Sets Container -->
             <div id="category-tag-sets-container"></div>
 
