Chris Chen
1360 lines
55 KiB
Markdown
1360 lines
55 KiB
Markdown
# Vendor Payment Snapshot Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Let finance save a vendor payment as a reusable named "snapshot" and re-apply it later, pre-filling every field except the Expense Date, to speed up entry of recurring fixed bills (rent, internet, fixed meal cost).
|
|
|
|
**Architecture:** A new `ExpenseSnapshot` aggregate (header + owned `ExpenseSnapshotLine` rows) mirrors the existing `Expense`/`ExpenseLine` shape minus `ExpenseDate`/receipt/`MemberId`. A thin service + controller (`api/expense-snapshots`) exposes list/get/create/update/delete, gated on the existing `Expenses:Write` permission. The Angular vendor-payment form gains a "Load from snapshot" picker and a "Save as snapshot" action; a new management page lists snapshots with rename/delete. Snapshots are shared church-wide and tagged with their creator (resolved at read time, like `ReviewedByName`).
|
|
|
|
**Tech Stack:** C# / EF Core (PostgreSQL) / ASP.NET controllers / xUnit + Moq + EF InMemory; Angular standalone components / Kendo UI / Tailwind v4 / Jasmine-Karma.
|
|
|
|
**Spec:** `docs/superpowers/specs/2026-06-25-vendor-payment-snapshot-design.md`
|
|
|
|
**Conventions verified from the codebase:**
|
|
- `CreatedBy`/`CreatedAt`/`UpdatedBy`/`UpdatedAt` are auto-stamped by `AuditSaveChangesInterceptor` for any `AuditableEntity` (which `SoftDeleteEntity` extends). Do NOT set them manually.
|
|
- Soft delete = set `IsDeleted = true` + `DeletedAt`; a `HasQueryFilter(e => !e.IsDeleted)` hides them.
|
|
- Owned lines are replaced wholesale on update (`RemoveRange` then rebuild), exactly like `ExpenseService.UpdateAsync`.
|
|
- Build/test under `-c Release` (Visual Studio locks `bin/Debug`). EF commands take `--configuration Release` for the same reason.
|
|
- Frontend unit-tested files: scope `ng test` with `--include` and run under Edge via `CHROME_BIN` (full `ng test` is pre-existing broken; the esbuild runner has no `.html` loader, so only test plain services, not templated components).
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
**Backend (create):**
|
|
- `API/ROLAC.API/Entities/ExpenseSnapshot.cs` — snapshot header entity
|
|
- `API/ROLAC.API/Entities/ExpenseSnapshotLine.cs` — snapshot line entity
|
|
- `API/ROLAC.API/DTOs/Expense/ExpenseSnapshotDtos.cs` — request/response DTOs
|
|
- `API/ROLAC.API/Services/IExpenseSnapshotService.cs` — service contract
|
|
- `API/ROLAC.API/Services/ExpenseSnapshotService.cs` — service implementation
|
|
- `API/ROLAC.API/Controllers/ExpenseSnapshotsController.cs` — REST endpoints
|
|
- `API/ROLAC.API.Tests/Services/ExpenseSnapshotServiceTests.cs` — service unit tests
|
|
- `API/ROLAC.API/Migrations/*_AddExpenseSnapshots.cs` — generated migration
|
|
|
|
**Backend (modify):**
|
|
- `API/ROLAC.API/Data/AppDbContext.cs` — register DbSets + entity config
|
|
- `API/ROLAC.API/Program.cs` — register `IExpenseSnapshotService`
|
|
|
|
**Frontend (create):**
|
|
- `APP/src/app/features/expense/models/expense-snapshot.model.ts` — TS interfaces
|
|
- `APP/src/app/features/expense/services/expense-snapshot-api.service.ts` — HTTP client
|
|
- `APP/src/app/features/expense/services/expense-snapshot-api.service.spec.ts` — service tests
|
|
- `APP/src/app/features/expense/pages/expense-snapshots-page/expense-snapshots-page.component.ts` — management page
|
|
- `APP/src/app/features/expense/pages/expense-snapshots-page/expense-snapshots-page.component.html`
|
|
- `APP/src/app/features/expense/pages/expense-snapshots-page/expense-snapshots-page.component.scss`
|
|
|
|
**Frontend (modify):**
|
|
- `APP/src/app/features/expense/components/expense-form-dialog/expense-form-dialog.component.ts` — load/save snapshot logic
|
|
- `APP/src/app/features/expense/components/expense-form-dialog/expense-form-dialog.component.html` — picker + save button + name prompt
|
|
- `APP/src/app/app.routes.ts` — route for the management page
|
|
- `APP/src/app/portals/user-portal/user-portal.component.ts` — sidebar nav item
|
|
|
|
---
|
|
|
|
## Task 1: Snapshot entities
|
|
|
|
**Files:**
|
|
- Create: `API/ROLAC.API/Entities/ExpenseSnapshot.cs`
|
|
- Create: `API/ROLAC.API/Entities/ExpenseSnapshotLine.cs`
|
|
|
|
- [ ] **Step 1: Create the header entity**
|
|
|
|
Create `API/ROLAC.API/Entities/ExpenseSnapshot.cs`:
|
|
|
|
```csharp
|
|
using ROLAC.API.Entities.Base;
|
|
namespace ROLAC.API.Entities;
|
|
|
|
/// <summary>
|
|
/// A reusable template of a vendor payment. Lets finance save a recurring fixed expense
|
|
/// (rent, internet, a fixed catered-meal cost) and re-apply it later, pre-filling everything
|
|
/// except the ExpenseDate. Shared church-wide; the creator is the auditable CreatedBy.
|
|
/// Lines are wholly owned by the header (replaced as a set on update, like ExpenseLine).
|
|
/// </summary>
|
|
public class ExpenseSnapshot : SoftDeleteEntity
|
|
{
|
|
public int Id { get; set; }
|
|
public string Name { get; set; } = null!; // user label, e.g. "Monthly Rent — Landlord X"
|
|
public int MinistryId { get; set; }
|
|
public string Description { get; set; } = null!;
|
|
public string? VendorName { get; set; }
|
|
public string? CheckNumber { get; set; }
|
|
public string? Notes { get; set; }
|
|
|
|
public Ministry? Ministry { get; set; }
|
|
public List<ExpenseSnapshotLine> Lines { get; set; } = new();
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Create the line entity**
|
|
|
|
Create `API/ROLAC.API/Entities/ExpenseSnapshotLine.cs`:
|
|
|
|
```csharp
|
|
using ROLAC.API.Entities.Base;
|
|
namespace ROLAC.API.Entities;
|
|
|
|
/// <summary>One category line of an <see cref="ExpenseSnapshot"/>, mirroring <see cref="ExpenseLine"/>.</summary>
|
|
public class ExpenseSnapshotLine : AuditableEntity
|
|
{
|
|
public int Id { get; set; }
|
|
public int SnapshotId { get; set; }
|
|
public int CategoryGroupId { get; set; }
|
|
public int SubCategoryId { get; set; }
|
|
public string? FunctionalClass { get; set; } // null = inherit Ministry.DefaultFunctionalClass
|
|
public decimal Amount { get; set; }
|
|
public string? Description { get; set; }
|
|
|
|
public ExpenseSnapshot? Snapshot { get; set; }
|
|
public ExpenseCategoryGroup? CategoryGroup { get; set; }
|
|
public ExpenseSubCategory? SubCategory { get; set; }
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add API/ROLAC.API/Entities/ExpenseSnapshot.cs API/ROLAC.API/Entities/ExpenseSnapshotLine.cs
|
|
git commit -m "feat(expense-snapshot): add ExpenseSnapshot + ExpenseSnapshotLine entities"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 2: Register entities in DbContext + migration
|
|
|
|
**Files:**
|
|
- Modify: `API/ROLAC.API/Data/AppDbContext.cs:25` (DbSets) and `:293` (after ExpenseLine config block)
|
|
|
|
- [ ] **Step 1: Add the DbSets**
|
|
|
|
In `API/ROLAC.API/Data/AppDbContext.cs`, after the `ExpenseLines` DbSet (line 25), add:
|
|
|
|
```csharp
|
|
public DbSet<ExpenseSnapshot> ExpenseSnapshots => Set<ExpenseSnapshot>();
|
|
public DbSet<ExpenseSnapshotLine> ExpenseSnapshotLines => Set<ExpenseSnapshotLine>();
|
|
```
|
|
|
|
- [ ] **Step 2: Add entity configuration**
|
|
|
|
In `OnModelCreating`, immediately after the closing `});` of the `ExpenseLine` configuration block (ends at line 293, just before the `ChurchProfile` block), add:
|
|
|
|
```csharp
|
|
// ── ExpenseSnapshot (reusable vendor-payment template) ───────────────
|
|
builder.Entity<ExpenseSnapshot>(entity =>
|
|
{
|
|
entity.HasQueryFilter(s => !s.IsDeleted);
|
|
|
|
entity.Property(e => e.Name).HasMaxLength(150).IsRequired();
|
|
entity.Property(e => e.Description).HasMaxLength(500).IsRequired();
|
|
entity.Property(e => e.VendorName).HasMaxLength(200);
|
|
entity.Property(e => e.CheckNumber).HasMaxLength(50);
|
|
entity.Property(e => e.CreatedBy).HasMaxLength(450);
|
|
entity.Property(e => e.UpdatedBy).HasMaxLength(450);
|
|
entity.Property(e => e.DeletedBy).HasMaxLength(450);
|
|
|
|
entity.HasIndex(e => e.CreatedAt);
|
|
|
|
entity.HasOne(e => e.Ministry).WithMany()
|
|
.HasForeignKey(e => e.MinistryId).OnDelete(DeleteBehavior.Restrict);
|
|
});
|
|
|
|
// ── ExpenseSnapshotLine (category breakdown of one snapshot) ─────────
|
|
builder.Entity<ExpenseSnapshotLine>(entity =>
|
|
{
|
|
// Mirror the parent snapshot's soft-delete filter (required relationship).
|
|
entity.HasQueryFilter(l => !l.Snapshot!.IsDeleted);
|
|
|
|
entity.Property(e => e.FunctionalClass).HasMaxLength(20);
|
|
entity.Property(e => e.Amount).HasColumnType("decimal(18,2)");
|
|
entity.Property(e => e.Description).HasMaxLength(500);
|
|
entity.Property(e => e.CreatedBy).HasMaxLength(450);
|
|
entity.Property(e => e.UpdatedBy).HasMaxLength(450);
|
|
|
|
entity.HasIndex(e => e.SnapshotId);
|
|
|
|
entity.HasOne(e => e.Snapshot).WithMany(x => x.Lines)
|
|
.HasForeignKey(e => e.SnapshotId).OnDelete(DeleteBehavior.Cascade);
|
|
entity.HasOne(e => e.CategoryGroup).WithMany()
|
|
.HasForeignKey(e => e.CategoryGroupId).OnDelete(DeleteBehavior.Restrict);
|
|
entity.HasOne(e => e.SubCategory).WithMany()
|
|
.HasForeignKey(e => e.SubCategoryId).OnDelete(DeleteBehavior.Restrict);
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 3: Verify it compiles**
|
|
|
|
Run: `dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release`
|
|
Expected: Build succeeded, 0 errors.
|
|
|
|
- [ ] **Step 4: Generate the migration**
|
|
|
|
Run from the repo root:
|
|
`dotnet ef migrations add AddExpenseSnapshots --project API/ROLAC.API --configuration Release`
|
|
Expected: creates `API/ROLAC.API/Migrations/<timestamp>_AddExpenseSnapshots.cs` creating two tables (`ExpenseSnapshots`, `ExpenseSnapshotLines`). Open the file and confirm both `CreateTable` calls are present and the down-migration drops both.
|
|
|
|
(If `dotnet ef` is not installed: `dotnet tool install --global dotnet-ef` first.)
|
|
|
|
- [ ] **Step 5: Apply the migration**
|
|
|
|
Run: `dotnet ef database update --project API/ROLAC.API --configuration Release`
|
|
Expected: "Done." and the two tables exist in the dev database.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add API/ROLAC.API/Data/AppDbContext.cs API/ROLAC.API/Migrations/
|
|
git commit -m "feat(expense-snapshot): register snapshot tables + EF migration"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 3: DTOs
|
|
|
|
**Files:**
|
|
- Create: `API/ROLAC.API/DTOs/Expense/ExpenseSnapshotDtos.cs`
|
|
|
|
- [ ] **Step 1: Create the DTO file**
|
|
|
|
Note: `ExpenseLineInput` is reused from `ExpenseDtos.cs` (same namespace `ROLAC.API.DTOs.Expense`), so snapshot lines share the expense line validation.
|
|
|
|
Create `API/ROLAC.API/DTOs/Expense/ExpenseSnapshotDtos.cs`:
|
|
|
|
```csharp
|
|
using System.ComponentModel.DataAnnotations;
|
|
namespace ROLAC.API.DTOs.Expense;
|
|
|
|
public class ExpenseSnapshotLineDto
|
|
{
|
|
public int CategoryGroupId { get; set; }
|
|
public string CategoryGroupName { get; set; } = "";
|
|
public int SubCategoryId { get; set; }
|
|
public string SubCategoryName { get; set; } = "";
|
|
public string? FunctionalClass { get; set; }
|
|
public decimal Amount { get; set; }
|
|
public string? Description { get; set; }
|
|
}
|
|
|
|
public class ExpenseSnapshotDto
|
|
{
|
|
public int Id { get; set; }
|
|
public string Name { get; set; } = "";
|
|
public int MinistryId { get; set; }
|
|
public string MinistryName { get; set; } = "";
|
|
public string Description { get; set; } = "";
|
|
public string? VendorName { get; set; }
|
|
public string? CheckNumber { get; set; }
|
|
public string? Notes { get; set; }
|
|
public decimal TotalAmount { get; set; } // sum of line amounts (list hint)
|
|
public int LineCount { get; set; }
|
|
public string? CreatedByName { get; set; } // resolved Member full name, email fallback
|
|
public DateTimeOffset CreatedAt { get; set; }
|
|
public List<ExpenseSnapshotLineDto> Lines { get; set; } = new();
|
|
}
|
|
|
|
public class CreateExpenseSnapshotRequest
|
|
{
|
|
[Required, MaxLength(150)] public string Name { get; set; } = "";
|
|
[Required] public int MinistryId { get; set; }
|
|
[Required, MinLength(1)] public List<ExpenseLineInput> Lines { get; set; } = new();
|
|
[Required, MaxLength(500)] public string Description { get; set; } = "";
|
|
[MaxLength(200)] public string? VendorName { get; set; }
|
|
[MaxLength(50)] public string? CheckNumber { get; set; }
|
|
public string? Notes { get; set; }
|
|
}
|
|
public class UpdateExpenseSnapshotRequest : CreateExpenseSnapshotRequest { }
|
|
```
|
|
|
|
- [ ] **Step 2: Verify it compiles**
|
|
|
|
Run: `dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release`
|
|
Expected: Build succeeded, 0 errors.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add API/ROLAC.API/DTOs/Expense/ExpenseSnapshotDtos.cs
|
|
git commit -m "feat(expense-snapshot): add snapshot DTOs"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 4: Service (TDD)
|
|
|
|
**Files:**
|
|
- Create: `API/ROLAC.API/Services/IExpenseSnapshotService.cs`
|
|
- Create: `API/ROLAC.API/Services/ExpenseSnapshotService.cs`
|
|
- Test: `API/ROLAC.API.Tests/Services/ExpenseSnapshotServiceTests.cs`
|
|
|
|
- [ ] **Step 1: Write the service contract**
|
|
|
|
Create `API/ROLAC.API/Services/IExpenseSnapshotService.cs`:
|
|
|
|
```csharp
|
|
using ROLAC.API.DTOs.Expense;
|
|
namespace ROLAC.API.Services;
|
|
|
|
public interface IExpenseSnapshotService
|
|
{
|
|
Task<List<ExpenseSnapshotDto>> GetAllAsync();
|
|
Task<ExpenseSnapshotDto?> GetByIdAsync(int id);
|
|
Task<int> CreateAsync(CreateExpenseSnapshotRequest r);
|
|
Task UpdateAsync(int id, UpdateExpenseSnapshotRequest r);
|
|
Task DeleteAsync(int id);
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Write the failing tests**
|
|
|
|
Create `API/ROLAC.API.Tests/Services/ExpenseSnapshotServiceTests.cs`:
|
|
|
|
```csharp
|
|
using System.Security.Claims;
|
|
using Microsoft.AspNetCore.Http;
|
|
using Microsoft.EntityFrameworkCore;
|
|
using Moq;
|
|
using ROLAC.API.Data;
|
|
using ROLAC.API.Data.Interceptors;
|
|
using ROLAC.API.DTOs.Expense;
|
|
using ROLAC.API.Entities;
|
|
using ROLAC.API.Services;
|
|
using ROLAC.API.Services.Logging;
|
|
using Xunit;
|
|
|
|
namespace ROLAC.API.Tests.Services;
|
|
|
|
public class ExpenseSnapshotServiceTests
|
|
{
|
|
// DbContext whose CreatedBy/CreatedAt are stamped from the given user id (via the audit interceptor),
|
|
// mirroring the production wiring used in ExpenseServiceTests.
|
|
private static AppDbContext BuildDb(string userId)
|
|
{
|
|
var claims = new[] { new Claim(ClaimTypes.NameIdentifier, userId) };
|
|
var ctx = new DefaultHttpContext { User = new(new ClaimsIdentity(claims)) };
|
|
var mock = new Mock<IHttpContextAccessor>();
|
|
mock.Setup(x => x.HttpContext).Returns(ctx);
|
|
return new AppDbContext(new DbContextOptionsBuilder<AppDbContext>()
|
|
.UseInMemoryDatabase(Guid.NewGuid().ToString())
|
|
.AddInterceptors(new AuditSaveChangesInterceptor(new CurrentUserAccessor(mock.Object))).Options);
|
|
}
|
|
|
|
private static (ExpenseSnapshotService svc, AppDbContext db) Build(string userId = "u1")
|
|
{
|
|
var db = BuildDb(userId);
|
|
db.Ministries.Add(new Ministry { Id = 1, Name_en = "Worship", Name_zh = "敬拜" });
|
|
db.ExpenseCategoryGroups.Add(new ExpenseCategoryGroup { Id = 1, Name_en = "Facilities" });
|
|
db.ExpenseSubCategories.Add(new ExpenseSubCategory { Id = 1, GroupId = 1, Name_en = "Rent" });
|
|
db.SaveChanges();
|
|
return (new ExpenseSnapshotService(db), db);
|
|
}
|
|
|
|
private static CreateExpenseSnapshotRequest Rent() => new()
|
|
{
|
|
Name = "Monthly Rent", MinistryId = 1, Description = "Office rent", VendorName = "Landlord X",
|
|
CheckNumber = "1001",
|
|
Lines = { new ExpenseLineInput { CategoryGroupId = 1, SubCategoryId = 1, Amount = 1200m } },
|
|
};
|
|
|
|
[Fact]
|
|
public async Task Create_PersistsHeaderAndLines_StampsCreator()
|
|
{
|
|
var (svc, db) = Build("creator-1");
|
|
var id = await svc.CreateAsync(Rent());
|
|
|
|
var saved = await db.ExpenseSnapshots.FindAsync(id);
|
|
Assert.Equal("Monthly Rent", saved!.Name);
|
|
Assert.Equal("creator-1", saved.CreatedBy);
|
|
Assert.Equal(1, await db.ExpenseSnapshotLines.CountAsync(l => l.SnapshotId == id));
|
|
}
|
|
|
|
[Fact]
|
|
public async Task Create_WithNoLines_Throws()
|
|
{
|
|
var (svc, _) = Build();
|
|
var r = Rent(); r.Lines.Clear();
|
|
await Assert.ThrowsAsync<InvalidOperationException>(() => svc.CreateAsync(r));
|
|
}
|
|
|
|
[Fact]
|
|
public async Task GetById_ReturnsLines_TotalsAndCreatorName()
|
|
{
|
|
var (svc, db) = Build("creator-1");
|
|
db.Members.Add(new Member { Id = 5, FirstName_en = "Joy", LastName_en = "Wong" });
|
|
db.Users.Add(new AppUser { Id = "creator-1", MemberId = 5 });
|
|
await db.SaveChangesAsync();
|
|
|
|
var id = await svc.CreateAsync(Rent());
|
|
var dto = await svc.GetByIdAsync(id);
|
|
|
|
Assert.NotNull(dto);
|
|
Assert.Equal(1200m, dto!.TotalAmount);
|
|
Assert.Equal(1, dto.LineCount);
|
|
Assert.Equal("Rent", dto.Lines.Single().SubCategoryName);
|
|
Assert.Equal("Joy Wong", dto.CreatedByName);
|
|
}
|
|
|
|
[Fact]
|
|
public async Task GetAll_ReturnsNewestFirst()
|
|
{
|
|
var (svc, _) = Build();
|
|
var first = await svc.CreateAsync(Rent());
|
|
var second = await svc.CreateAsync(Rent());
|
|
|
|
var all = await svc.GetAllAsync();
|
|
|
|
Assert.Equal(2, all.Count);
|
|
Assert.Equal(second, all[0].Id); // CreatedAt desc, then Id desc
|
|
Assert.Equal(first, all[1].Id);
|
|
}
|
|
|
|
[Fact]
|
|
public async Task Update_RenamesAndReplacesLines()
|
|
{
|
|
var (svc, db) = Build();
|
|
db.ExpenseCategoryGroups.Add(new ExpenseCategoryGroup { Id = 2, Name_en = "Utilities" });
|
|
db.ExpenseSubCategories.Add(new ExpenseSubCategory { Id = 2, GroupId = 2, Name_en = "Internet" });
|
|
await db.SaveChangesAsync();
|
|
|
|
var id = await svc.CreateAsync(Rent());
|
|
await svc.UpdateAsync(id, new UpdateExpenseSnapshotRequest
|
|
{
|
|
Name = "Monthly Internet", MinistryId = 1, Description = "ISP",
|
|
Lines = { new ExpenseLineInput { CategoryGroupId = 2, SubCategoryId = 2, Amount = 80m } },
|
|
});
|
|
|
|
var dto = await svc.GetByIdAsync(id);
|
|
Assert.Equal("Monthly Internet", dto!.Name);
|
|
Assert.Equal(80m, dto.TotalAmount);
|
|
Assert.Equal("Internet", dto.Lines.Single().SubCategoryName);
|
|
Assert.Equal(1, await db.ExpenseSnapshotLines.CountAsync(l => l.SnapshotId == id));
|
|
}
|
|
|
|
[Fact]
|
|
public async Task Update_MissingId_Throws()
|
|
{
|
|
var (svc, _) = Build();
|
|
await Assert.ThrowsAsync<KeyNotFoundException>(() => svc.UpdateAsync(999, new UpdateExpenseSnapshotRequest
|
|
{
|
|
Name = "x", MinistryId = 1, Description = "x",
|
|
Lines = { new ExpenseLineInput { CategoryGroupId = 1, SubCategoryId = 1, Amount = 1m } },
|
|
}));
|
|
}
|
|
|
|
[Fact]
|
|
public async Task Delete_SoftDeletes_HidesFromQueries()
|
|
{
|
|
var (svc, db) = Build();
|
|
var id = await svc.CreateAsync(Rent());
|
|
|
|
await svc.DeleteAsync(id);
|
|
|
|
Assert.Empty(await svc.GetAllAsync());
|
|
Assert.Null(await db.ExpenseSnapshots.FirstOrDefaultAsync(s => s.Id == id));
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 3: Run the tests to verify they fail to compile**
|
|
|
|
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter FullyQualifiedName~ExpenseSnapshotServiceTests`
|
|
Expected: FAILS to compile — `ExpenseSnapshotService` does not exist yet.
|
|
|
|
- [ ] **Step 4: Implement the service**
|
|
|
|
Create `API/ROLAC.API/Services/ExpenseSnapshotService.cs`:
|
|
|
|
```csharp
|
|
using Microsoft.EntityFrameworkCore;
|
|
using ROLAC.API.Data;
|
|
using ROLAC.API.DTOs.Expense;
|
|
using ROLAC.API.Entities;
|
|
|
|
namespace ROLAC.API.Services;
|
|
|
|
public class ExpenseSnapshotService : IExpenseSnapshotService
|
|
{
|
|
private readonly AppDbContext _db;
|
|
public ExpenseSnapshotService(AppDbContext db) => _db = db;
|
|
|
|
public async Task<List<ExpenseSnapshotDto>> GetAllAsync()
|
|
{
|
|
var snaps = await _db.ExpenseSnapshots.AsNoTracking()
|
|
.OrderByDescending(s => s.CreatedAt).ThenByDescending(s => s.Id)
|
|
.ToListAsync();
|
|
if (snaps.Count == 0) return new();
|
|
|
|
var ids = snaps.Select(s => s.Id).ToList();
|
|
var lines = await _db.ExpenseSnapshotLines.AsNoTracking()
|
|
.Where(l => ids.Contains(l.SnapshotId)).ToListAsync();
|
|
var linesBySnapshot = lines.GroupBy(l => l.SnapshotId).ToDictionary(g => g.Key, g => g.ToList());
|
|
|
|
var minNames = await _db.Ministries.AsNoTracking().ToDictionaryAsync(m => m.Id, m => $"{m.Name_en} / {m.Name_zh}");
|
|
var creatorNames = await ResolveUserNamesAsync(snaps.Select(s => s.CreatedBy));
|
|
|
|
return snaps.Select(s =>
|
|
{
|
|
linesBySnapshot.TryGetValue(s.Id, out var ls);
|
|
return new ExpenseSnapshotDto
|
|
{
|
|
Id = s.Id, Name = s.Name, MinistryId = s.MinistryId,
|
|
MinistryName = minNames.GetValueOrDefault(s.MinistryId, ""),
|
|
Description = s.Description, VendorName = s.VendorName,
|
|
CheckNumber = s.CheckNumber, Notes = s.Notes,
|
|
TotalAmount = ls?.Sum(l => l.Amount) ?? 0,
|
|
LineCount = ls?.Count ?? 0,
|
|
CreatedByName = creatorNames.GetValueOrDefault(s.CreatedBy),
|
|
CreatedAt = s.CreatedAt,
|
|
};
|
|
}).ToList();
|
|
}
|
|
|
|
public async Task<ExpenseSnapshotDto?> GetByIdAsync(int id)
|
|
{
|
|
var s = await _db.ExpenseSnapshots.AsNoTracking().FirstOrDefaultAsync(x => x.Id == id);
|
|
if (s is null) return null;
|
|
|
|
var lines = await _db.ExpenseSnapshotLines.AsNoTracking()
|
|
.Where(l => l.SnapshotId == id).OrderBy(l => l.Id).ToListAsync();
|
|
var minName = await _db.Ministries.Where(m => m.Id == s.MinistryId).Select(m => m.Name_en).FirstOrDefaultAsync() ?? "";
|
|
var grpNames = await _db.ExpenseCategoryGroups.AsNoTracking().ToDictionaryAsync(g => g.Id, g => g.Name_en);
|
|
var subNames = await _db.ExpenseSubCategories.AsNoTracking().ToDictionaryAsync(x => x.Id, x => x.Name_en);
|
|
var creatorName = (await ResolveUserNamesAsync(new[] { s.CreatedBy })).GetValueOrDefault(s.CreatedBy);
|
|
|
|
return new ExpenseSnapshotDto
|
|
{
|
|
Id = s.Id, Name = s.Name, MinistryId = s.MinistryId, MinistryName = minName,
|
|
Description = s.Description, VendorName = s.VendorName, CheckNumber = s.CheckNumber, Notes = s.Notes,
|
|
TotalAmount = lines.Sum(l => l.Amount), LineCount = lines.Count,
|
|
CreatedByName = creatorName, CreatedAt = s.CreatedAt,
|
|
Lines = lines.Select(l => new ExpenseSnapshotLineDto
|
|
{
|
|
CategoryGroupId = l.CategoryGroupId, CategoryGroupName = grpNames.GetValueOrDefault(l.CategoryGroupId, ""),
|
|
SubCategoryId = l.SubCategoryId, SubCategoryName = subNames.GetValueOrDefault(l.SubCategoryId, ""),
|
|
FunctionalClass = l.FunctionalClass, Amount = l.Amount, Description = l.Description,
|
|
}).ToList(),
|
|
};
|
|
}
|
|
|
|
public async Task<int> CreateAsync(CreateExpenseSnapshotRequest r)
|
|
{
|
|
ValidateLines(r.Lines);
|
|
var s = new ExpenseSnapshot
|
|
{
|
|
Name = r.Name.Trim(), MinistryId = r.MinistryId, Description = r.Description,
|
|
VendorName = r.VendorName, CheckNumber = r.CheckNumber, Notes = r.Notes,
|
|
Lines = BuildLines(r.Lines),
|
|
};
|
|
_db.ExpenseSnapshots.Add(s);
|
|
await _db.SaveChangesAsync();
|
|
return s.Id;
|
|
}
|
|
|
|
public async Task UpdateAsync(int id, UpdateExpenseSnapshotRequest r)
|
|
{
|
|
ValidateLines(r.Lines);
|
|
// FirstOrDefaultAsync (not FindAsync) so the soft-delete query filter applies.
|
|
var s = await _db.ExpenseSnapshots.Include(x => x.Lines).FirstOrDefaultAsync(x => x.Id == id)
|
|
?? throw new KeyNotFoundException($"Snapshot {id} not found.");
|
|
|
|
s.Name = r.Name.Trim(); s.MinistryId = r.MinistryId; s.Description = r.Description;
|
|
s.VendorName = r.VendorName; s.CheckNumber = r.CheckNumber; s.Notes = r.Notes;
|
|
|
|
// Replace the line set wholesale (lines are owned by the header).
|
|
_db.ExpenseSnapshotLines.RemoveRange(s.Lines);
|
|
s.Lines = BuildLines(r.Lines);
|
|
await _db.SaveChangesAsync();
|
|
}
|
|
|
|
public async Task DeleteAsync(int id)
|
|
{
|
|
var s = await _db.ExpenseSnapshots.FirstOrDefaultAsync(x => x.Id == id)
|
|
?? throw new KeyNotFoundException($"Snapshot {id} not found.");
|
|
s.IsDeleted = true; s.DeletedAt = DateTimeOffset.UtcNow;
|
|
await _db.SaveChangesAsync();
|
|
}
|
|
|
|
private static void ValidateLines(List<ExpenseLineInput> lines)
|
|
{
|
|
if (lines is null || lines.Count == 0)
|
|
throw new InvalidOperationException("A snapshot must have at least one line.");
|
|
foreach (var l in lines)
|
|
{
|
|
if (l.CategoryGroupId <= 0 || l.SubCategoryId <= 0)
|
|
throw new InvalidOperationException("Each snapshot line needs a category group and subcategory.");
|
|
if (l.Amount <= 0)
|
|
throw new InvalidOperationException("Each snapshot line amount must be greater than zero.");
|
|
}
|
|
}
|
|
|
|
private static List<ExpenseSnapshotLine> BuildLines(List<ExpenseLineInput> inputs) =>
|
|
inputs.Select(l => new ExpenseSnapshotLine
|
|
{
|
|
CategoryGroupId = l.CategoryGroupId, SubCategoryId = l.SubCategoryId,
|
|
FunctionalClass = l.FunctionalClass, Amount = l.Amount, Description = l.Description,
|
|
}).ToList();
|
|
|
|
// Resolve actor user ids (AppUser.Id, stored in CreatedBy) to a display name: the linked
|
|
// Member's full name when present, otherwise the account email. Mirrors ExpenseService.
|
|
private async Task<Dictionary<string, string>> ResolveUserNamesAsync(IEnumerable<string?> userIds)
|
|
{
|
|
var ids = userIds.Where(id => !string.IsNullOrEmpty(id)).Select(id => id!).Distinct().ToList();
|
|
if (ids.Count == 0) return new();
|
|
|
|
var users = await _db.Users.AsNoTracking()
|
|
.Where(u => ids.Contains(u.Id))
|
|
.Select(u => new { u.Id, u.Email, u.MemberId })
|
|
.ToListAsync();
|
|
|
|
var memberIds = users.Where(u => u.MemberId != null).Select(u => u.MemberId!.Value).ToHashSet();
|
|
var memberNames = await _db.Members.AsNoTracking()
|
|
.Where(m => memberIds.Contains(m.Id))
|
|
.ToDictionaryAsync(m => m.Id, m => $"{m.FirstName_en} {m.LastName_en}".Trim());
|
|
|
|
return users.ToDictionary(
|
|
u => u.Id,
|
|
u => u.MemberId != null && memberNames.TryGetValue(u.MemberId.Value, out var name) && name.Length > 0
|
|
? name
|
|
: (u.Email ?? u.Id));
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 5: Run the tests to verify they pass**
|
|
|
|
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter FullyQualifiedName~ExpenseSnapshotServiceTests`
|
|
Expected: PASS — 7 passed.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add API/ROLAC.API/Services/IExpenseSnapshotService.cs API/ROLAC.API/Services/ExpenseSnapshotService.cs API/ROLAC.API.Tests/Services/ExpenseSnapshotServiceTests.cs
|
|
git commit -m "feat(expense-snapshot): snapshot service with creator-name resolution + tests"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 5: Controller + DI registration
|
|
|
|
**Files:**
|
|
- Create: `API/ROLAC.API/Controllers/ExpenseSnapshotsController.cs`
|
|
- Modify: `API/ROLAC.API/Program.cs:155`
|
|
|
|
- [ ] **Step 1: Create the controller**
|
|
|
|
Authorization mirrors `ExpensesController`: snapshots are a finance-only vendor-payment tool, so every endpoint is gated on `Expenses:Write` (super_admin bypasses). Create `API/ROLAC.API/Controllers/ExpenseSnapshotsController.cs`:
|
|
|
|
```csharp
|
|
using Microsoft.AspNetCore.Authorization;
|
|
using Microsoft.AspNetCore.Mvc;
|
|
using ROLAC.API.Authorization;
|
|
using ROLAC.API.DTOs.Expense;
|
|
using ROLAC.API.Services;
|
|
|
|
namespace ROLAC.API.Controllers;
|
|
|
|
// Snapshots are reusable vendor-payment templates — a finance tool. Every action requires
|
|
// Expenses:Write (super_admin bypasses), matching who can create vendor payments.
|
|
[ApiController]
|
|
[Route("api/expense-snapshots")]
|
|
[Authorize]
|
|
public class ExpenseSnapshotsController : ControllerBase
|
|
{
|
|
private readonly IExpenseSnapshotService _svc;
|
|
private readonly IPermissionService _perms;
|
|
public ExpenseSnapshotsController(IExpenseSnapshotService svc, IPermissionService perms)
|
|
{
|
|
_svc = svc;
|
|
_perms = perms;
|
|
}
|
|
|
|
private List<string> Roles() => User.FindAll("role").Select(claim => claim.Value).ToList();
|
|
private bool IsSuperAdmin() => User.IsInRole(PermissionAuthorizationHandler.SuperAdminRole);
|
|
private async Task<bool> CanManageAsync() =>
|
|
IsSuperAdmin() || await _perms.HasPermissionAsync(Roles(), Modules.Expenses, PermissionActions.Write);
|
|
|
|
[HttpGet]
|
|
public async Task<IActionResult> GetAll()
|
|
{
|
|
if (!await CanManageAsync()) return Forbid();
|
|
return Ok(await _svc.GetAllAsync());
|
|
}
|
|
|
|
[HttpGet("{id:int}")]
|
|
public async Task<IActionResult> GetById(int id)
|
|
{
|
|
if (!await CanManageAsync()) return Forbid();
|
|
var dto = await _svc.GetByIdAsync(id);
|
|
return dto is null ? NotFound() : Ok(dto);
|
|
}
|
|
|
|
[HttpPost]
|
|
public async Task<IActionResult> Create([FromBody] CreateExpenseSnapshotRequest r)
|
|
{
|
|
if (!await CanManageAsync()) return Forbid();
|
|
try { return Ok(new { id = await _svc.CreateAsync(r) }); }
|
|
catch (InvalidOperationException ex) { return Conflict(new { message = ex.Message }); }
|
|
}
|
|
|
|
[HttpPut("{id:int}")]
|
|
public async Task<IActionResult> Update(int id, [FromBody] UpdateExpenseSnapshotRequest r)
|
|
{
|
|
if (!await CanManageAsync()) return Forbid();
|
|
try { await _svc.UpdateAsync(id, r); return NoContent(); }
|
|
catch (KeyNotFoundException) { return NotFound(); }
|
|
catch (InvalidOperationException ex) { return Conflict(new { message = ex.Message }); }
|
|
}
|
|
|
|
[HttpDelete("{id:int}")]
|
|
public async Task<IActionResult> Delete(int id)
|
|
{
|
|
if (!await CanManageAsync()) return Forbid();
|
|
try { await _svc.DeleteAsync(id); return NoContent(); }
|
|
catch (KeyNotFoundException) { return NotFound(); }
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Register the service in DI**
|
|
|
|
In `API/ROLAC.API/Program.cs`, immediately after line 155 (`builder.Services.AddScoped<IExpenseService, ExpenseService>();`), add:
|
|
|
|
```csharp
|
|
builder.Services.AddScoped<IExpenseSnapshotService, ExpenseSnapshotService>();
|
|
```
|
|
|
|
- [ ] **Step 3: Verify build + full test suite still green**
|
|
|
|
Run: `dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release`
|
|
Expected: Build succeeded, 0 errors.
|
|
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter FullyQualifiedName~ExpenseSnapshotServiceTests`
|
|
Expected: PASS — 7 passed.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add API/ROLAC.API/Controllers/ExpenseSnapshotsController.cs API/ROLAC.API/Program.cs
|
|
git commit -m "feat(expense-snapshot): REST controller + DI registration"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 6: Frontend model + service (TDD)
|
|
|
|
**Files:**
|
|
- Create: `APP/src/app/features/expense/models/expense-snapshot.model.ts`
|
|
- Create: `APP/src/app/features/expense/services/expense-snapshot-api.service.ts`
|
|
- Test: `APP/src/app/features/expense/services/expense-snapshot-api.service.spec.ts`
|
|
|
|
- [ ] **Step 1: Create the model**
|
|
|
|
Create `APP/src/app/features/expense/models/expense-snapshot.model.ts`:
|
|
|
|
```typescript
|
|
import { ExpenseLineInput, FunctionalClass } from './expense.model';
|
|
|
|
export interface ExpenseSnapshotLineDto {
|
|
categoryGroupId: number; categoryGroupName: string;
|
|
subCategoryId: number; subCategoryName: string;
|
|
functionalClass: FunctionalClass | null; amount: number; description: string | null;
|
|
}
|
|
|
|
export interface ExpenseSnapshotDto {
|
|
id: number; name: string; ministryId: number; ministryName: string;
|
|
description: string; vendorName: string | null; checkNumber: string | null; notes: string | null;
|
|
totalAmount: number; lineCount: number;
|
|
createdByName: string | null; createdAt: string;
|
|
lines: ExpenseSnapshotLineDto[];
|
|
}
|
|
|
|
export interface CreateExpenseSnapshotRequest {
|
|
name: string; ministryId: number; lines: ExpenseLineInput[];
|
|
description: string; vendorName: string | null; checkNumber: string | null; notes: string | null;
|
|
}
|
|
export type UpdateExpenseSnapshotRequest = CreateExpenseSnapshotRequest;
|
|
```
|
|
|
|
- [ ] **Step 2: Create the service**
|
|
|
|
Create `APP/src/app/features/expense/services/expense-snapshot-api.service.ts`:
|
|
|
|
```typescript
|
|
import { Injectable } from '@angular/core';
|
|
import { HttpClient } from '@angular/common/http';
|
|
import { Observable } from 'rxjs';
|
|
import { ApiConfigService } from '../../../core/services/api-config.service';
|
|
import {
|
|
ExpenseSnapshotDto, CreateExpenseSnapshotRequest, UpdateExpenseSnapshotRequest,
|
|
} from '../models/expense-snapshot.model';
|
|
|
|
@Injectable({ providedIn: 'root' })
|
|
export class ExpenseSnapshotApiService {
|
|
private readonly endpoint: string;
|
|
constructor(private http: HttpClient, apiConfig: ApiConfigService) {
|
|
this.endpoint = apiConfig.getApiUrl('expense-snapshots');
|
|
}
|
|
getAll(): Observable<ExpenseSnapshotDto[]> {
|
|
return this.http.get<ExpenseSnapshotDto[]>(this.endpoint);
|
|
}
|
|
getById(id: number): Observable<ExpenseSnapshotDto> {
|
|
return this.http.get<ExpenseSnapshotDto>(`${this.endpoint}/${id}`);
|
|
}
|
|
create(r: CreateExpenseSnapshotRequest): Observable<{ id: number }> {
|
|
return this.http.post<{ id: number }>(this.endpoint, r);
|
|
}
|
|
update(id: number, r: UpdateExpenseSnapshotRequest): Observable<void> {
|
|
return this.http.put<void>(`${this.endpoint}/${id}`, r);
|
|
}
|
|
delete(id: number): Observable<void> {
|
|
return this.http.delete<void>(`${this.endpoint}/${id}`);
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 3: Write the failing test**
|
|
|
|
Create `APP/src/app/features/expense/services/expense-snapshot-api.service.spec.ts`:
|
|
|
|
```typescript
|
|
import { TestBed } from '@angular/core/testing';
|
|
import { HttpClientTestingModule, HttpTestingController } from '@angular/common/http/testing';
|
|
import { ExpenseSnapshotApiService } from './expense-snapshot-api.service';
|
|
import { ApiConfigService } from '../../../core/services/api-config.service';
|
|
import { CreateExpenseSnapshotRequest } from '../models/expense-snapshot.model';
|
|
|
|
describe('ExpenseSnapshotApiService', () => {
|
|
let service: ExpenseSnapshotApiService;
|
|
let httpMock: HttpTestingController;
|
|
const base = 'http://test/api/expense-snapshots';
|
|
|
|
beforeEach(() => {
|
|
TestBed.configureTestingModule({
|
|
imports: [HttpClientTestingModule],
|
|
providers: [
|
|
ExpenseSnapshotApiService,
|
|
{ provide: ApiConfigService, useValue: { getApiUrl: () => base } },
|
|
],
|
|
});
|
|
service = TestBed.inject(ExpenseSnapshotApiService);
|
|
httpMock = TestBed.inject(HttpTestingController);
|
|
});
|
|
|
|
afterEach(() => httpMock.verify());
|
|
|
|
it('getAll() GETs the collection endpoint', () => {
|
|
service.getAll().subscribe();
|
|
const req = httpMock.expectOne(base);
|
|
expect(req.request.method).toBe('GET');
|
|
req.flush([]);
|
|
});
|
|
|
|
it('create() POSTs the request body', () => {
|
|
const body: CreateExpenseSnapshotRequest = {
|
|
name: 'Rent', ministryId: 1, description: 'Office rent',
|
|
vendorName: 'Landlord X', checkNumber: null, notes: null,
|
|
lines: [{ categoryGroupId: 1, subCategoryId: 1, amount: 1200, functionalClass: null, description: null }],
|
|
};
|
|
service.create(body).subscribe();
|
|
const req = httpMock.expectOne(base);
|
|
expect(req.request.method).toBe('POST');
|
|
expect(req.request.body.name).toBe('Rent');
|
|
req.flush({ id: 7 });
|
|
});
|
|
|
|
it('delete() DELETEs by id', () => {
|
|
service.delete(9).subscribe();
|
|
const req = httpMock.expectOne(`${base}/9`);
|
|
expect(req.request.method).toBe('DELETE');
|
|
req.flush(null);
|
|
});
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 4: Run the test**
|
|
|
|
Run from `APP/`:
|
|
```powershell
|
|
$env:CHROME_BIN = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
|
|
npx ng test --include="**/expense-snapshot-api.service.spec.ts" --watch=false --browsers=ChromeHeadless
|
|
```
|
|
Expected: PASS — 3 specs, 0 failures. (If the Edge path differs on this machine, point `CHROME_BIN` at the local `msedge.exe`.)
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add APP/src/app/features/expense/models/expense-snapshot.model.ts APP/src/app/features/expense/services/expense-snapshot-api.service.ts APP/src/app/features/expense/services/expense-snapshot-api.service.spec.ts
|
|
git commit -m "feat(expense-snapshot): frontend model + api service with tests"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 7: Form dialog — load + save snapshot (vendor mode)
|
|
|
|
**Files:**
|
|
- Modify: `APP/src/app/features/expense/components/expense-form-dialog/expense-form-dialog.component.ts`
|
|
- Modify: `APP/src/app/features/expense/components/expense-form-dialog/expense-form-dialog.component.html`
|
|
|
|
- [ ] **Step 1: Add the snapshot imports + state to the component**
|
|
|
|
In `expense-form-dialog.component.ts`, add to the imports near the other service imports (after line 12, `import { ExpenseApiService } ...`):
|
|
|
|
```typescript
|
|
import { ExpenseSnapshotApiService } from '../../services/expense-snapshot-api.service';
|
|
import { ExpenseSnapshotDto, CreateExpenseSnapshotRequest } from '../../models/expense-snapshot.model';
|
|
```
|
|
|
|
Inside the class, after the `groups` field (line 65), add:
|
|
|
|
```typescript
|
|
/** Saved snapshots (vendor mode only) for the "Load from snapshot" picker. */
|
|
snapshots: ExpenseSnapshotDto[] = [];
|
|
/** Picker binding; reset to null after each apply so the same snapshot can be re-picked. */
|
|
selectedSnapshotId: number | null = null;
|
|
|
|
/** "Save as snapshot" name-prompt state. */
|
|
showSnapshotNamePrompt = false;
|
|
snapshotName = '';
|
|
snapshotSaving = false;
|
|
|
|
/** Snapshot tools (load/save) are a vendor-payment feature only. */
|
|
get showSnapshotTools(): boolean { return this.mode === 'vendor'; }
|
|
```
|
|
|
|
- [ ] **Step 2: Inject the snapshot service**
|
|
|
|
In the constructor (line 114-121), add the parameter:
|
|
|
|
```typescript
|
|
private snapshotApi: ExpenseSnapshotApiService,
|
|
```
|
|
|
|
(Place it after `private expenseApi: ExpenseApiService,`.)
|
|
|
|
- [ ] **Step 3: Load snapshots on init (vendor mode)**
|
|
|
|
In `ngOnInit()`, after the `this.ministryApi.getAll()...` line (line 124), add:
|
|
|
|
```typescript
|
|
if (this.showSnapshotTools) this.loadSnapshots();
|
|
```
|
|
|
|
- [ ] **Step 4: Add the load/save methods**
|
|
|
|
Add these methods to the class (e.g. just before `get isValid()` at line 318):
|
|
|
|
```typescript
|
|
private loadSnapshots(): void {
|
|
this.snapshotApi.getAll().subscribe(list => (this.snapshots = list));
|
|
}
|
|
|
|
/** Apply a saved snapshot: prefill header + lines, but keep today's Expense Date. */
|
|
applySnapshot(snapshotId: number | null): void {
|
|
if (snapshotId == null) return;
|
|
this.snapshotApi.getById(snapshotId).subscribe(s => {
|
|
this.form.ministryId = s.ministryId;
|
|
this.form.description = s.description;
|
|
this.form.vendorName = s.vendorName ?? '';
|
|
this.form.checkNumber = s.checkNumber ?? '';
|
|
// Expense Date is intentionally NOT taken from the snapshot — leave it as-is (today).
|
|
this.lines = s.lines.map(line => ({
|
|
categoryGroupId: line.categoryGroupId,
|
|
subCategoryId: line.subCategoryId,
|
|
amount: line.amount,
|
|
description: line.description ?? '',
|
|
functionalClass: line.functionalClass,
|
|
subs: this.groups.find(g => g.id === line.categoryGroupId)?.subCategories ?? [],
|
|
}));
|
|
if (this.lines.length === 0) this.lines = [this.emptyLine()];
|
|
this.selectedSnapshotId = null;
|
|
});
|
|
}
|
|
|
|
/** Open the name prompt for saving the current form as a snapshot (requires a valid form). */
|
|
openSnapshotPrompt(): void {
|
|
if (!this.isValid) return;
|
|
this.snapshotName = '';
|
|
this.showSnapshotNamePrompt = true;
|
|
}
|
|
|
|
cancelSnapshotPrompt(): void { this.showSnapshotNamePrompt = false; }
|
|
|
|
/** Save the current header + lines as a named snapshot (Expense Date is not stored). */
|
|
saveSnapshot(): void {
|
|
const name = this.snapshotName.trim();
|
|
if (!name || this.snapshotSaving) return;
|
|
const request: CreateExpenseSnapshotRequest = {
|
|
name,
|
|
ministryId: this.form.ministryId!,
|
|
lines: this.lines.map(l => ({
|
|
categoryGroupId: l.categoryGroupId!,
|
|
subCategoryId: l.subCategoryId!,
|
|
amount: l.amount,
|
|
functionalClass: l.functionalClass,
|
|
description: l.description.trim() || null,
|
|
})),
|
|
description: this.form.description.trim(),
|
|
vendorName: this.form.vendorName || null,
|
|
checkNumber: this.form.checkNumber || null,
|
|
notes: null,
|
|
};
|
|
this.snapshotSaving = true;
|
|
this.snapshotApi.create(request).subscribe({
|
|
next: () => {
|
|
this.snapshotSaving = false;
|
|
this.showSnapshotNamePrompt = false;
|
|
this.loadSnapshots();
|
|
},
|
|
error: () => { this.snapshotSaving = false; },
|
|
});
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 5: Add the picker + save button to the template**
|
|
|
|
In `expense-form-dialog.component.html`, insert this block right after the opening `<div class="flex-1 min-w-0 ...">` (after line 6), as the first child of the left form column:
|
|
|
|
```html
|
|
<!-- Snapshot tools (vendor mode): quick-load a saved template, or save the current form -->
|
|
<div *ngIf="showSnapshotTools" class="md:col-span-2 flex flex-wrap items-end gap-2 rounded border border-gray-200 bg-gray-50 p-2">
|
|
<label class="flex flex-1 min-w-[14rem] flex-col gap-1">範本 / Load from snapshot
|
|
<kendo-dropdownlist [data]="snapshots" textField="name" valueField="id" [valuePrimitive]="true"
|
|
[(ngModel)]="selectedSnapshotId" (valueChange)="applySnapshot($event)"
|
|
[defaultItem]="{ id: null, name: '-- 選擇範本 / Select a saved snapshot --' }">
|
|
</kendo-dropdownlist>
|
|
</label>
|
|
<button kendoButton fillMode="outline" themeColor="primary" type="button"
|
|
[disabled]="!isValid" (click)="openSnapshotPrompt()"
|
|
title="Save the current form as a reusable snapshot / 儲存為範本">💾 存為範本 / Save as snapshot</button>
|
|
</div>
|
|
```
|
|
|
|
Then add the name-prompt dialog as a sibling of the main `<kendo-dialog>`, immediately after its closing `</kendo-dialog>` (after line 213):
|
|
|
|
```html
|
|
<!-- Save-as-snapshot name prompt -->
|
|
<kendo-dialog *ngIf="showSnapshotNamePrompt" title="存為範本 / Save as Snapshot" [width]="420" [maxWidth]="'95vw'"
|
|
(close)="cancelSnapshotPrompt()">
|
|
<div class="flex flex-col gap-2 p-2">
|
|
<label class="flex flex-col gap-1">名稱 / Name
|
|
<kendo-textbox [(ngModel)]="snapshotName" placeholder="e.g. Monthly Rent — Landlord X"></kendo-textbox>
|
|
</label>
|
|
<p class="text-xs text-gray-500">費用日期不會存入範本 / The Expense Date is not saved in a snapshot.</p>
|
|
</div>
|
|
<kendo-dialog-actions>
|
|
<button kendoButton (click)="cancelSnapshotPrompt()">Cancel</button>
|
|
<button kendoButton themeColor="primary" [disabled]="!snapshotName.trim() || snapshotSaving"
|
|
(click)="saveSnapshot()">{{ snapshotSaving ? '儲存中… / Saving…' : 'Save' }}</button>
|
|
</kendo-dialog-actions>
|
|
</kendo-dialog>
|
|
```
|
|
|
|
- [ ] **Step 6: Verify the build compiles**
|
|
|
|
Run from `APP/`: `npx ng build --configuration development`
|
|
Expected: build completes with no errors referencing `expense-form-dialog`.
|
|
|
|
- [ ] **Step 7: Commit**
|
|
|
|
```bash
|
|
git add APP/src/app/features/expense/components/expense-form-dialog/
|
|
git commit -m "feat(expense-snapshot): load/save snapshot in vendor payment form"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 8: Management page
|
|
|
|
**Files:**
|
|
- Create: `APP/src/app/features/expense/pages/expense-snapshots-page/expense-snapshots-page.component.ts`
|
|
- Create: `APP/src/app/features/expense/pages/expense-snapshots-page/expense-snapshots-page.component.html`
|
|
- Create: `APP/src/app/features/expense/pages/expense-snapshots-page/expense-snapshots-page.component.scss`
|
|
|
|
- [ ] **Step 1: Create the component class**
|
|
|
|
Rename re-uses the `update` endpoint: the page fetches the full snapshot, swaps `name`, and PUTs it back (the line set is preserved). Create `expense-snapshots-page.component.ts`:
|
|
|
|
```typescript
|
|
import { Component, OnInit } from '@angular/core';
|
|
import { CommonModule } from '@angular/common';
|
|
import { FormsModule } from '@angular/forms';
|
|
import { GridModule } from '@progress/kendo-angular-grid';
|
|
import { ButtonsModule } from '@progress/kendo-angular-buttons';
|
|
import { InputsModule } from '@progress/kendo-angular-inputs';
|
|
import { DialogsModule } from '@progress/kendo-angular-dialog';
|
|
import { ExpenseSnapshotApiService } from '../../services/expense-snapshot-api.service';
|
|
import { ExpenseSnapshotDto } from '../../models/expense-snapshot.model';
|
|
import { switchMap } from 'rxjs';
|
|
|
|
@Component({
|
|
selector: 'app-expense-snapshots-page',
|
|
standalone: true,
|
|
imports: [CommonModule, FormsModule, GridModule, ButtonsModule, InputsModule, DialogsModule],
|
|
templateUrl: './expense-snapshots-page.component.html',
|
|
styleUrls: ['./expense-snapshots-page.component.scss'],
|
|
})
|
|
export class ExpenseSnapshotsPageComponent implements OnInit {
|
|
rows: ExpenseSnapshotDto[] = [];
|
|
loading = false;
|
|
|
|
/** Row being renamed (drives the rename dialog); null when closed. */
|
|
renameRow: ExpenseSnapshotDto | null = null;
|
|
renameValue = '';
|
|
renameSaving = false;
|
|
|
|
/** Row pending delete confirmation. */
|
|
deleteRow: ExpenseSnapshotDto | null = null;
|
|
|
|
constructor(private api: ExpenseSnapshotApiService) {}
|
|
|
|
ngOnInit(): void { this.load(); }
|
|
|
|
load(): void {
|
|
this.loading = true;
|
|
this.api.getAll().subscribe({
|
|
next: list => { this.rows = list; this.loading = false; },
|
|
error: () => { this.loading = false; },
|
|
});
|
|
}
|
|
|
|
openRename(row: ExpenseSnapshotDto): void {
|
|
this.renameRow = row;
|
|
this.renameValue = row.name;
|
|
}
|
|
cancelRename(): void { this.renameRow = null; }
|
|
|
|
confirmRename(): void {
|
|
const row = this.renameRow;
|
|
const name = this.renameValue.trim();
|
|
if (!row || !name || this.renameSaving) return;
|
|
this.renameSaving = true;
|
|
// Fetch the full snapshot, swap the name, PUT it back (lines/fields preserved).
|
|
this.api.getById(row.id).pipe(
|
|
switchMap(full => this.api.update(row.id, {
|
|
name,
|
|
ministryId: full.ministryId,
|
|
description: full.description,
|
|
vendorName: full.vendorName,
|
|
checkNumber: full.checkNumber,
|
|
notes: full.notes,
|
|
lines: full.lines.map(l => ({
|
|
categoryGroupId: l.categoryGroupId,
|
|
subCategoryId: l.subCategoryId,
|
|
amount: l.amount,
|
|
functionalClass: l.functionalClass,
|
|
description: l.description,
|
|
})),
|
|
})),
|
|
).subscribe({
|
|
next: () => { this.renameSaving = false; this.renameRow = null; this.load(); },
|
|
error: () => { this.renameSaving = false; },
|
|
});
|
|
}
|
|
|
|
openDelete(row: ExpenseSnapshotDto): void { this.deleteRow = row; }
|
|
cancelDelete(): void { this.deleteRow = null; }
|
|
|
|
confirmDelete(): void {
|
|
if (!this.deleteRow) return;
|
|
this.api.delete(this.deleteRow.id).subscribe(() => { this.deleteRow = null; this.load(); });
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Create the template (mobile-friendly: desktop grid + card list)**
|
|
|
|
Per house rule, desktop uses `hidden md:block`, mobile uses a `md:hidden` card list, and the card list's flex layout lives in Tailwind utilities (never component SCSS). Create `expense-snapshots-page.component.html`:
|
|
|
|
```html
|
|
<div class="page">
|
|
<p class="mb-4 text-sm text-gray-600">
|
|
儲存常用的固定費用（房租、網路、餐費…）為範本，下次可快速套用。費用日期不會儲存。<br>
|
|
Save recurring fixed expenses as snapshots to quickly re-use them. The Expense Date is never saved.
|
|
</p>
|
|
|
|
<!-- Desktop: grid -->
|
|
<div class="hidden md:block">
|
|
<kendo-grid [data]="rows" [loading]="loading">
|
|
<kendo-grid-column field="name" title="Snapshot / 範本" [width]="240"></kendo-grid-column>
|
|
<kendo-grid-column field="vendorName" title="Vendor / 廠商" [width]="180">
|
|
<ng-template kendoGridCellTemplate let-dataItem>{{ dataItem.vendorName || '—' }}</ng-template>
|
|
</kendo-grid-column>
|
|
<kendo-grid-column field="ministryName" title="Ministry / 事工"></kendo-grid-column>
|
|
<kendo-grid-column field="totalAmount" title="Amount / 金額" [width]="120" format="c2"></kendo-grid-column>
|
|
<kendo-grid-column title="Created by / 建立者" [width]="200">
|
|
<ng-template kendoGridCellTemplate let-dataItem>
|
|
{{ dataItem.createdByName || '—' }}<br>
|
|
<span class="text-xs text-gray-500">{{ dataItem.createdAt | date:'yyyy-MM-dd' }}</span>
|
|
</ng-template>
|
|
</kendo-grid-column>
|
|
<kendo-grid-column title="Actions" [width]="160">
|
|
<ng-template kendoGridCellTemplate let-dataItem>
|
|
<button kendoButton fillMode="flat" (click)="openRename(dataItem)">Rename</button>
|
|
<button kendoButton fillMode="flat" themeColor="error" (click)="openDelete(dataItem)">Delete</button>
|
|
</ng-template>
|
|
</kendo-grid-column>
|
|
</kendo-grid>
|
|
</div>
|
|
|
|
<!-- Mobile: card list -->
|
|
<div class="md:hidden flex flex-col gap-3">
|
|
<div *ngFor="let row of rows" class="rounded border border-gray-200 p-3 flex flex-col gap-1">
|
|
<div class="flex items-center justify-between">
|
|
<span class="font-semibold">{{ row.name }}</span>
|
|
<span class="tabular-nums">{{ row.totalAmount | currency }}</span>
|
|
</div>
|
|
<div class="text-sm text-gray-600">{{ row.vendorName || '—' }} · {{ row.ministryName }}</div>
|
|
<div class="text-xs text-gray-500">{{ row.createdByName || '—' }} · {{ row.createdAt | date:'yyyy-MM-dd' }}</div>
|
|
<div class="flex gap-2 pt-1">
|
|
<button kendoButton size="small" fillMode="outline" (click)="openRename(row)">Rename</button>
|
|
<button kendoButton size="small" fillMode="outline" themeColor="error" (click)="openDelete(row)">Delete</button>
|
|
</div>
|
|
</div>
|
|
<p *ngIf="!loading && rows.length === 0" class="text-sm text-gray-500">尚無範本 / No snapshots yet.</p>
|
|
</div>
|
|
|
|
<!-- Rename dialog -->
|
|
<kendo-dialog *ngIf="renameRow" title="重新命名 / Rename Snapshot" [width]="420" [maxWidth]="'95vw'" (close)="cancelRename()">
|
|
<label class="flex flex-col gap-1 p-2">名稱 / Name
|
|
<kendo-textbox [(ngModel)]="renameValue"></kendo-textbox>
|
|
</label>
|
|
<kendo-dialog-actions>
|
|
<button kendoButton (click)="cancelRename()">Cancel</button>
|
|
<button kendoButton themeColor="primary" [disabled]="!renameValue.trim() || renameSaving"
|
|
(click)="confirmRename()">{{ renameSaving ? 'Saving…' : 'Save' }}</button>
|
|
</kendo-dialog-actions>
|
|
</kendo-dialog>
|
|
|
|
<!-- Delete confirm dialog -->
|
|
<kendo-dialog *ngIf="deleteRow" title="刪除 / Delete Snapshot" [width]="420" [maxWidth]="'95vw'" (close)="cancelDelete()">
|
|
<p class="p-2">確定刪除「{{ deleteRow.name }}」？ / Delete "{{ deleteRow.name }}"?</p>
|
|
<kendo-dialog-actions>
|
|
<button kendoButton (click)="cancelDelete()">Cancel</button>
|
|
<button kendoButton themeColor="error" (click)="confirmDelete()">Delete</button>
|
|
</kendo-dialog-actions>
|
|
</kendo-dialog>
|
|
</div>
|
|
```
|
|
|
|
- [ ] **Step 3: Create a minimal SCSS file**
|
|
|
|
Per house rule, do NOT put `display` rules here. Create `expense-snapshots-page.component.scss`:
|
|
|
|
```scss
|
|
.page {
|
|
padding: 0.5rem 0;
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Verify the build compiles**
|
|
|
|
Run from `APP/`: `npx ng build --configuration development`
|
|
Expected: build completes with no errors referencing `expense-snapshots-page`.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add APP/src/app/features/expense/pages/expense-snapshots-page/
|
|
git commit -m "feat(expense-snapshot): snapshot management page (rename/delete)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 9: Route + sidebar nav
|
|
|
|
**Files:**
|
|
- Modify: `APP/src/app/app.routes.ts` (finance routes block, near line 192)
|
|
- Modify: `APP/src/app/portals/user-portal/user-portal.component.ts:139` (Expenses nav group)
|
|
|
|
- [ ] **Step 1: Import the page component in the routes file**
|
|
|
|
In `APP/src/app/app.routes.ts`, add an import alongside the other expense page imports (e.g. near the `ExpensesPageComponent` import):
|
|
|
|
```typescript
|
|
import { ExpenseSnapshotsPageComponent } from './features/expense/pages/expense-snapshots-page/expense-snapshots-page.component';
|
|
```
|
|
|
|
(Confirm the exact relative path matches the other expense page imports in that file; they live under `./features/expense/pages/...`.)
|
|
|
|
- [ ] **Step 2: Add the route**
|
|
|
|
In `app.routes.ts`, immediately after the `finance/expenses` route object (closes at line 164), add:
|
|
|
|
```typescript
|
|
{
|
|
path: 'finance/expense-snapshots',
|
|
component: ExpenseSnapshotsPageComponent,
|
|
canActivate: [PermissionGuard],
|
|
data: {
|
|
permission: { module: PermissionModules.Expenses, action: 'read' },
|
|
title: 'Expense Snapshots', titleZh: '費用範本', section: 'Finance',
|
|
},
|
|
},
|
|
```
|
|
|
|
- [ ] **Step 3: Add the sidebar nav item**
|
|
|
|
In `APP/src/app/portals/user-portal/user-portal.component.ts`, inside the `Expenses` finance group's `items` array, after the `Expense Categories` item (line 133-134), add:
|
|
|
|
```typescript
|
|
{ text: 'Expense Snapshots', icon: categorizeIcon, path: '/user-portal/finance/expense-snapshots',
|
|
permission: { module: PermissionModules.Expenses, action: 'read' } },
|
|
```
|
|
|
|
(`categorizeIcon` is already imported and used in this file.)
|
|
|
|
- [ ] **Step 4: Verify the build compiles**
|
|
|
|
Run from `APP/`: `npx ng build --configuration development`
|
|
Expected: build completes, 0 errors.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add APP/src/app/app.routes.ts APP/src/app/portals/user-portal/user-portal.component.ts
|
|
git commit -m "feat(expense-snapshot): route + sidebar nav for snapshot management"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 10: End-to-end verification
|
|
|
|
**Files:** none (manual + automated verification)
|
|
|
|
- [ ] **Step 1: Backend — full build + targeted tests green**
|
|
|
|
Run: `dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release` → Build succeeded.
|
|
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter FullyQualifiedName~ExpenseSnapshotServiceTests` → 7 passed.
|
|
|
|
- [ ] **Step 2: Frontend — service tests + build green**
|
|
|
|
Run from `APP/`:
|
|
```powershell
|
|
$env:CHROME_BIN = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
|
|
npx ng test --include="**/expense-snapshot-api.service.spec.ts" --watch=false --browsers=ChromeHeadless
|
|
npx ng build --configuration development
|
|
```
|
|
Expected: 3 specs pass; build succeeds.
|
|
|
|
- [ ] **Step 3: Manual smoke test**
|
|
|
|
Start the API and the frontend (see the Build/Run env memory). As a finance user:
|
|
1. Finance → Expenses → **+ Vendor Payment**. Fill ministry, description, vendor, one line with an amount. Click **存為範本 / Save as snapshot**, name it "Smoke Rent", Save. Confirm no error.
|
|
2. Close the dialog, reopen **+ Vendor Payment**. In **Load from snapshot**, pick "Smoke Rent". Confirm ministry/description/vendor/line all prefill and **Expense Date stays today** (not blank/altered).
|
|
3. Finance → **Expense Snapshots**. Confirm "Smoke Rent" appears with vendor, amount, and your name as creator. **Rename** it → confirm the new name shows. **Delete** it → confirm it disappears.
|
|
4. Resize the browser to mobile width on the Expense Snapshots page → confirm the card list shows (not the grid) and actions work.
|
|
|
|
- [ ] **Step 4: Final commit (if any manual-fix tweaks were needed)**
|
|
|
|
```bash
|
|
git add -A
|
|
git commit -m "test(expense-snapshot): verification fixes"
|
|
```
|
|
|
|
(Skip if nothing changed.)
|
|
|
|
---
|
|
|
|
## Self-Review Notes
|
|
|
|
- **Spec coverage:** capture fields (Task 1/3), shared + creator tag resolved at read (Task 4 `ResolveUserNamesAsync` + `GetByIdName` test), exclude ExpenseDate/receipt/MemberId (entities omit them; Task 7 `applySnapshot` keeps today's date), save-from-form (Task 7), quick picker + management page both present (Tasks 7 & 8 — spec Q4=C), rename + delete (Task 8), `Expenses:Write` gating (Task 5), mobile-friendly management page (Task 8). All covered.
|
|
- **CheckNumber:** captured and editable per spec; no special handling needed.
|
|
- **Type consistency:** `CreateExpenseSnapshotRequest`/`UpdateExpenseSnapshotRequest`, `ExpenseSnapshotDto`, `ExpenseSnapshotLineDto`, `ExpenseLineInput` names match across backend DTOs (Task 3), service (Task 4), frontend model (Task 6), and consumers (Tasks 7-8). Service method names (`getAll/getById/create/update/delete`) are identical across interface, service, and Angular service.
|