#1/#2: contribution categories + fund-attributed deposits

#1 Account-level ContributionCategory (Salary/Vouchers...) with add/rename/
remove (dup-name guard; remove blocked when a deposit references it). New
accounts seed Salary + Other. The 'From previous period' leftover is not a
contribution and keeps its own pseudo-category.

#2 Contribution is now an itemized entry (MemberId, CategoryId, FundId, Date,
Paid); deposits merge by (member, category, fund). A deposit raises the chosen
fund's balance (FundBalance adds attributed deposits, so fund balances now sum
to the expected closing). Edit/remove are by id; a user may only handle their
OWN contributions.

Serializer round-trips the new fields (back-compat defaults for old snapshots).
EF mapping + SQLite migration (MAUI). Server stores the body as opaque JSON, so
no Postgres change needed. Contributions UI reshaped: deposit form (category +
fund + amount + date), category chips with add/edit/remove, itemized own-editable
list. Localized the new strings (EN/BG). 101 tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: stoyan.s

src/FinApp.Contracts/AccountSnapshotSerializer.cs

@@ -34,7 +34,8 @@ public static string Serialize(Account account)
             account.Funds.Select(f => new FundNode(f.Id, f.Name, f.ParentId)).ToList(),
             account.Categories.Select(c => new CategoryNode(c.Id, c.Name, c.ParentId)).ToList(),
             account.SavingCategories.Select(s => new SavingCategoryNode(s.Id, s.Name, s.ParentId, s.GoalAmount, s.AlertThreshold, s.NotifyOnMilestone, s.InitialAmount)).ToList(),
-            account.Periods.Select(ToNode).ToList());
+            account.Periods.Select(ToNode).ToList(),
+            account.ContributionCategories.Select(c => new ContributionCategoryNode(c.Id, c.Name)).ToList());
         return JsonSerializer.Serialize(node, Json);
     }
 
@@ -64,6 +65,8 @@ public static Account Deserialize(string payload)
         SetField(account, "_funds", node.Funds.Select(f => Build(new Fund(f.Name, f.ParentId), f.Id)).ToList());
         SetField(account, "_categories", node.Categories.Select(c => Build(new Category(c.Name, c.ParentId), c.Id)).ToList());
         SetField(account, "_savingCategories", node.SavingCategories.Select(ToEntity).ToList());
+        SetField(account, "_contributionCategories",
+            (node.ContributionCategories ?? []).Select(c => Build(new ContributionCategory(c.Name), c.Id)).ToList());
         SetField(account, "_periods", node.Periods.Select(p => ToEntity(p, node.Currency)).ToList());
         return account;
     }
@@ -73,7 +76,7 @@ public static Account Deserialize(string payload)
     private static PeriodNode ToNode(Period p) => new(
         p.Id, p.Currency, p.From, p.To, p.Status, p.CarriedIn.Amount,
         p.InitialBalances.Select(b => new InitialBalanceNode(b.Id, b.FundId, b.Amount.Amount, b.Informative)).ToList(),
-        p.Contributions.Select(c => new ContributionNode(c.Id, c.MemberId, c.Paid.Amount)).ToList(),
+        p.Contributions.Select(c => new ContributionNode(c.Id, c.MemberId, c.Paid.Amount, c.CategoryId, c.FundId, c.Date)).ToList(),
         p.Budgets.Select(b => new BudgetNode(b.Id, b.CategoryId, b.Allocated.Amount, b.AlertThreshold, b.NotifyOnEveryExpense)).ToList(),
         p.Expenses.Select(e => new ExpenseNode(e.Id, e.CategoryId, e.Amount.Amount, e.Date, e.MemberId, e.FundId, e.Note, e.SourceSavingCategoryId)).ToList(),
         p.SavingAllocations.Select(a => new SavingAllocationNode(a.Id, a.SavingCategoryId, a.Amount.Amount, a.Date, a.Note, a.SourceExpenseId, a.BudgetCategoryId, a.TransferPairId)).ToList(),
@@ -103,7 +106,7 @@ private static Period ToEntity(PeriodNode n, string currency)
         if (n.Status == PeriodStatus.Closed) p.Close();
 
         SetField(p, "_initialBalances", n.InitialBalances.Select(b => Build(new InitialBalance(b.FundId, M(b.Amount), b.Informative), b.Id)).ToList());
-        SetField(p, "_contributions", n.Contributions.Where(c => c.MemberId != Period.CarryoverSource).Select(c => Build(new Contribution(c.MemberId, M(c.Paid)), c.Id)).ToList());
+        SetField(p, "_contributions", n.Contributions.Where(c => c.MemberId != Period.CarryoverSource).Select(c => Build(new Contribution(c.MemberId, M(c.Paid), c.CategoryId, c.FundId, c.Date), c.Id)).ToList());
         SetField(p, "_budgets", n.Budgets.Select(b => Build(new Budget(b.CategoryId, M(b.Allocated), b.AlertThreshold, b.NotifyOnEveryExpense), b.Id)).ToList());
         SetField(p, "_expenses", n.Expenses.Select(e => Build(new Expense(e.CategoryId, M(e.Amount), e.Date, e.MemberId, e.FundId, e.Note, e.SourceSavingCategoryId), e.Id)).ToList());
         SetField(p, "_savingAllocations", n.SavingAllocations.Select(a => Build(new SavingAllocation(a.SavingCategoryId, M(a.Amount), a.Date, a.Note, a.SourceExpenseId, a.BudgetCategoryId, a.TransferPairId), a.Id)).ToList());
@@ -142,9 +145,11 @@ private static FieldInfo FindField(Type? type, string name)
 
     private record AccountNode(Guid Id, string Name, string Currency, Guid OwnerUserId,
         List<MemberNode> Members, List<FundNode> Funds, List<CategoryNode> Categories,
-        List<SavingCategoryNode> SavingCategories, List<PeriodNode> Periods);
+        List<SavingCategoryNode> SavingCategories, List<PeriodNode> Periods,
+        List<ContributionCategoryNode>? ContributionCategories = null);
 
     private record MemberNode(Guid Id, Guid UserId, string DisplayName);
+    private record ContributionCategoryNode(Guid Id, string Name);
     private record FundNode(Guid Id, string Name, Guid? ParentId);
     private record CategoryNode(Guid Id, string Name, Guid? ParentId);
     private record SavingCategoryNode(Guid Id, string Name, Guid? ParentId, decimal? GoalAmount, decimal AlertThreshold, bool NotifyOnMilestone, decimal InitialAmount);
@@ -155,7 +160,8 @@ private record PeriodNode(Guid Id, string Currency, DateOnly From, DateOnly To,
         List<ExternalTransferNode>? ExternalTransfers = null);
 
     private record InitialBalanceNode(Guid Id, Guid FundId, decimal Amount, bool Informative);
-    private record ContributionNode(Guid Id, Guid MemberId, decimal Paid);
+    private record ContributionNode(Guid Id, Guid MemberId, decimal Paid,
+        Guid CategoryId = default, Guid FundId = default, DateOnly Date = default);
     private record BudgetNode(Guid Id, Guid CategoryId, decimal Allocated, decimal AlertThreshold, bool NotifyOnEveryExpense);
     private record ExpenseNode(Guid Id, Guid CategoryId, decimal Amount, DateOnly Date, Guid MemberId, Guid FundId, string? Note, Guid? SourceSavingCategoryId);
     private record SavingAllocationNode(Guid Id, Guid SavingCategoryId, decimal Amount, DateOnly Date, string? Note, Guid? SourceExpenseId, Guid? BudgetCategoryId = null, Guid? TransferPairId = null);

src/FinApp.Domain/Accounts/Account.cs

@@ -15,6 +15,7 @@ public sealed class Account : Entity
     private readonly List<AccountMember> _members = [];
     private readonly List<Category> _categories = [];
     private readonly List<SavingCategory> _savingCategories = [];
+    private readonly List<ContributionCategory> _contributionCategories = [];
     private readonly List<Fund> _funds = [];
     private readonly List<Period> _periods = [];
 
@@ -36,6 +37,9 @@ public sealed class Account : Entity
     /// <summary>All savings buckets, flat.</summary>
     public IReadOnlyList<SavingCategory> SavingCategories => _savingCategories;
 
+    /// <summary>Account-level contribution categories (Salary, Vouchers…), referenced by id from deposits.</summary>
+    public IReadOnlyList<ContributionCategory> ContributionCategories => _contributionCategories;
+
     /// <summary>All funds (places money lives), flat. Referenced by id from expenses, opening balances and transfers.</summary>
     public IReadOnlyList<Fund> Funds => _funds;
 
@@ -198,6 +202,44 @@ public void RemoveSavingCategory(Guid savingCategoryId)
         _savingCategories.Remove(category);
     }
 
+    // --- Contribution categories -----------------------------------------
+
+    public ContributionCategory AddContributionCategory(string name)
+    {
+        if (_contributionCategories.Any(c => NameEquals(c.Name, name)))
+            throw new InvalidOperationException($"A contribution category named “{name.Trim()}” already exists.");
+        var category = new ContributionCategory(name);
+        _contributionCategories.Add(category);
+        return category;
+    }
+
+    public ContributionCategory? FindContributionCategory(Guid id) => _contributionCategories.FirstOrDefault(c => c.Id == id);
+
+    public void RenameContributionCategory(Guid id, string name)
+    {
+        var category = FindContributionCategory(id) ?? throw new InvalidOperationException("Contribution category not found.");
+        if (_contributionCategories.Any(c => c.Id != id && NameEquals(c.Name, name)))
+            throw new InvalidOperationException($"A contribution category named “{name.Trim()}” already exists.");
+        category.Rename(name);
+    }
+
+    /// <summary>Why a contribution category can't be removed, or null when it can.</summary>
+    public string? ContributionCategoryRemovalBlocker(Guid id)
+    {
+        if (_periods.SelectMany(p => p.Contributions).Any(c => c.CategoryId == id))
+            return "deposits reference it";
+        return null;
+    }
+
+    public void RemoveContributionCategory(Guid id)
+    {
+        var blocker = ContributionCategoryRemovalBlocker(id);
+        if (blocker is not null)
+            throw new InvalidOperationException($"Cannot remove contribution category: {blocker}.");
+        var category = FindContributionCategory(id) ?? throw new InvalidOperationException("Contribution category not found.");
+        _contributionCategories.Remove(category);
+    }
+
     // --- Funds ------------------------------------------------------------
 
     /// <summary>Add a fund. Pass <paramref name="parentId"/> to nest it as an informational sub-fund.</summary>

src/FinApp.Domain/Periods/Contribution.cs

@@ -3,20 +3,28 @@
 namespace FinApp.Domain.Periods;
 
 /// <summary>
-/// A member's deposit into a period — how much they have actually put in. There are no pledges or
-/// due dates: deposits are recorded directly as money comes in.
+/// A member's deposit into a period — how much they have actually put in, classified by an optional
+/// contribution <see cref="CategoryId"/> (Salary, Vouchers…) and attributed to a <see cref="FundId"/>
+/// (the deposited money lands in that fund). Deposits with the same (member, category, fund) merge into
+/// one row; different combinations are separate rows. There are no pledges or due dates.
 /// </summary>
 public sealed class Contribution : Entity
 {
     public Guid MemberId { get; }
+    public Guid CategoryId { get; private set; }
+    public Guid FundId { get; private set; }
+    public DateOnly Date { get; private set; }
     public Money Paid { get; private set; }
 
-    public Contribution(Guid memberId, Money paid)
+    public Contribution(Guid memberId, Money paid, Guid categoryId = default, Guid fundId = default, DateOnly date = default)
     {
         if (paid.IsNegative)
             throw new ArgumentException("Deposited amount cannot be negative.", nameof(paid));
         MemberId = memberId;
         Paid = paid;
+        CategoryId = categoryId;
+        FundId = fundId;
+        Date = date;
     }
 
     public void RecordPayment(Money amount)
@@ -33,4 +41,13 @@ public void SetPaid(Money amount)
             throw new ArgumentException("Deposited amount cannot be negative.", nameof(amount));
         Paid = amount;
     }
+
+    /// <summary>Overwrite all editable fields of a deposit row.</summary>
+    public void Update(Money amount, Guid categoryId, Guid fundId, DateOnly date)
+    {
+        SetPaid(amount);
+        CategoryId = categoryId;
+        FundId = fundId;
+        Date = date;
+    }
 }

src/FinApp.Domain/Periods/ContributionCategory.cs

@@ -0,0 +1,27 @@
+using FinApp.Domain.Common;
+
+namespace FinApp.Domain.Periods;
+
+/// <summary>
+/// An account-level category for contributions/deposits (e.g. Salary, Vouchers, Rent share).
+/// Lets income be classified by source. The automatic "From previous period" leftover is not a
+/// contribution and keeps its own pseudo-category, so it's unaffected by these.
+/// </summary>
+public sealed class ContributionCategory : Entity
+{
+    public string Name { get; private set; }
+
+    public ContributionCategory(string name)
+    {
+        if (string.IsNullOrWhiteSpace(name))
+            throw new ArgumentException("Contribution category name is required.", nameof(name));
+        Name = name.Trim();
+    }
+
+    public void Rename(string name)
+    {
+        if (string.IsNullOrWhiteSpace(name))
+            throw new ArgumentException("Contribution category name is required.", nameof(name));
+        Name = name.Trim();
+    }
+}

src/FinApp.Domain/Periods/Period.cs

@@ -139,7 +139,8 @@ public Money FundBalance(Guid fundId)
         var transfersOut = Sum(_fundTransfers.Where(t => t.FromFundId == fundId).Select(t => t.Amount));
         var spent = Sum(_expenses.Where(e => e.FundId == fundId).Select(e => e.Amount));
         var sentOut = Sum(_externalTransfers.Where(t => t.FundId == fundId).Select(t => t.Amount));
-        return opening + transfersIn - transfersOut - spent - sentOut;
+        var depositsIn = Sum(_contributions.Where(c => c.MemberId != CarryoverSource && c.FundId == fundId).Select(c => c.Paid));
+        return opening + transfersIn + depositsIn - transfersOut - spent - sentOut;
     }
 
     // --- Transfers to other accounts --------------------------------------
@@ -171,36 +172,44 @@ public void RemoveExternalTransfer(Guid transferId)
 
     // --- Contributions ----------------------------------------------------
 
-    /// <summary>Record a member's deposit (creating their contribution on first deposit, adding to it after).</summary>
-    public Contribution Deposit(Guid memberId, Money amount)
+    /// <summary>
+    /// Record a member's deposit, classified by <paramref name="categoryId"/> and attributed to
+    /// <paramref name="fundId"/> (the money lands in that fund). Deposits with the same
+    /// (member, category, fund) merge into one row; different combinations are separate rows.
+    /// </summary>
+    public Contribution Deposit(Guid memberId, Money amount, Guid categoryId = default, Guid fundId = default, DateOnly date = default)
     {
         EnsureCurrency(amount);
-        var existing = _contributions.FirstOrDefault(c => c.MemberId == memberId);
+        var existing = _contributions.FirstOrDefault(c =>
+            c.MemberId == memberId && c.CategoryId == categoryId && c.FundId == fundId);
         if (existing is null)
         {
-            existing = new Contribution(memberId, Money.Zero(Currency));
+            existing = new Contribution(memberId, Money.Zero(Currency), categoryId, fundId, date);
             _contributions.Add(existing);
         }
         existing.RecordPayment(amount);
         return existing;
     }
 
-    /// <summary>Overwrite a member's deposited total (used when editing a deposit).</summary>
-    public void SetDeposit(Guid memberId, Money amount)
+    public Contribution? FindContribution(Guid contributionId) =>
+        _contributions.FirstOrDefault(c => c.Id == contributionId);
+
+    /// <summary>Overwrite a deposit row's amount/category/fund/date (used when editing a deposit).</summary>
+    public void EditContribution(Guid contributionId, Money amount, Guid categoryId, Guid fundId, DateOnly date)
     {
         EnsureCurrency(amount);
         EnsureOpen();
-        var contribution = _contributions.FirstOrDefault(c => c.MemberId == memberId)
-            ?? throw new InvalidOperationException("No contribution exists for this member.");
-        contribution.SetPaid(amount);
+        var contribution = FindContribution(contributionId)
+            ?? throw new InvalidOperationException("Contribution not found in this period.");
+        contribution.Update(amount, categoryId, fundId, date);
     }
 
-    /// <summary>Clear a member's deposit for this period.</summary>
-    public void RemoveDeposit(Guid memberId)
+    /// <summary>Remove a deposit row.</summary>
+    public void RemoveContribution(Guid contributionId)
     {
         EnsureOpen();
-        var contribution = _contributions.FirstOrDefault(c => c.MemberId == memberId)
-            ?? throw new InvalidOperationException("No contribution exists for this member.");
+        var contribution = FindContribution(contributionId)
+            ?? throw new InvalidOperationException("Contribution not found in this period.");
         _contributions.Remove(contribution);
     }
 

src/FinApp.Persistence/FinAppDbContext.cs

@@ -47,10 +47,18 @@ protected override void OnModelCreating(ModelBuilder b)
             OwnedList(a, x => x.Members);
             OwnedList(a, x => x.Categories);
             OwnedList(a, x => x.SavingCategories);
+            OwnedList(a, x => x.ContributionCategories);
             OwnedList(a, x => x.Funds);
             OwnedList(a, x => x.Periods);
         });
 
+        b.Entity<ContributionCategory>(c =>
+        {
+            c.ToTable("ContributionCategories");
+            Key(c);
+            c.Property(x => x.Name).IsRequired();
+        });
+
         b.Entity<Fund>(f =>
         {
             f.ToTable("Funds");
@@ -193,6 +201,9 @@ protected override void OnModelCreating(ModelBuilder b)
             c.ToTable("Contributions");
             Key(c);
             c.Property(x => x.MemberId);
+            c.Property(x => x.CategoryId);
+            c.Property(x => x.FundId);
+            c.Property(x => x.Date);
             c.Property(x => x.Paid).HasConversion(money).IsRequired();
         });