Chris Chen
1612 lines
63 KiB
Markdown
1612 lines
63 KiB
Markdown
# 1099 Recipient Tracking (Sub-Project B) 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 the church identify independent-contractor/vendor payees, store their W-9/TIN securely, map expense categories to 1099 boxes, and produce a cash-basis year-end 1099-NEC aggregation report plus a printable recipient Copy B PDF and filing CSV.
|
||
|
||
**Architecture:** Mirror the proven sub-project-A "data-driven mapping" approach — a `Form1099Box` catalog + nullable `Form1099BoxId` FKs on `ExpenseSubCategory`/`ExpenseCategoryGroup` (effective box = sub ?? group ?? null), a `Payee1099` master with an optional `MemberId` link and a nullable `Expense.PayeeId`, and a read-only `Form1099ReportService` peer of `Form990ReportService`. TIN is encrypted with the ASP.NET Data Protection API behind a small `ITinProtector` wrapper. Frontend follows existing Kendo/Tailwind admin-page conventions.
|
||
|
||
**Tech Stack:** C# / .NET, EF Core + PostgreSQL (EF InMemory for tests), xUnit + Moq, Angular + Kendo UI v20 + Tailwind v4, DevExpress.Document.Processor for PDF.
|
||
|
||
**Spec:** `docs/superpowers/specs/2026-06-25-1099-recipient-tracking-design.md`
|
||
|
||
**Build/test note** ([[project-build-run-env]]): VS locks `bin/Debug`; run CLI builds/tests with `-c Release`. Backend tests live in `API/ROLAC.API.Tests`.
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
**Backend (create):**
|
||
- `API/ROLAC.API/Entities/Payee1099.cs` — recipient master entity
|
||
- `API/ROLAC.API/Entities/Form1099Box.cs` — 1099 box catalog entity
|
||
- `API/ROLAC.API/Services/Security/ITinProtector.cs` + `TinProtector.cs` — TIN encrypt/decrypt + last-4
|
||
- `API/ROLAC.API/Services/IPayee1099Service.cs` + `Payee1099Service.cs` — recipient CRUD
|
||
- `API/ROLAC.API/Services/IForm1099ReportService.cs` + `Form1099ReportService.cs` — aggregation
|
||
- `API/ROLAC.API/Services/Form1099/I1099FormService.cs` + `Form1099FormService.cs` — Copy B PDF + CSV
|
||
- `API/ROLAC.API/DTOs/Finance/Form1099ReportDtos.cs` — report + box DTOs
|
||
- `API/ROLAC.API/DTOs/Payee/Payee1099Dtos.cs` — recipient DTOs
|
||
- `API/ROLAC.API/Controllers/Payee1099Controller.cs`, `Controllers/Form1099ReportController.cs`
|
||
- `API/ROLAC.API/Entities/Form1099.cs` — static constants (threshold, box codes, W9 statuses)
|
||
- Migration under `API/ROLAC.API/Migrations/`
|
||
- Tests: `API/ROLAC.API.Tests/Services/{TinProtectorTests,Payee1099ServiceTests,Form1099ReportServiceTests}.cs`
|
||
|
||
**Backend (modify):**
|
||
- `API/ROLAC.API/Entities/Expense.cs` — add `PayeeId`
|
||
- `API/ROLAC.API/Entities/ExpenseSubCategory.cs`, `ExpenseCategoryGroup.cs` — add `Form1099BoxId`
|
||
- `API/ROLAC.API/Data/AppDbContext.cs` — DbSets + entity config
|
||
- `API/ROLAC.API/Data/DbSeeder.cs` — box catalog + mapping seed
|
||
- `API/ROLAC.API/Authorization/Modules.cs` — add `Form1099`
|
||
- `API/ROLAC.API/Program.cs` — DI registrations + `AddDataProtection`
|
||
- `API/ROLAC.API/DTOs/Expense/ExpenseDtos.cs` — add `PayeeId` to requests/DTOs; box id to category DTOs
|
||
- `API/ROLAC.API/Services/ExpenseService.cs` — persist `PayeeId`
|
||
- `docs/DB_SCHEMA.md` — document new tables/columns
|
||
|
||
**Frontend (create/modify):**
|
||
- `APP/src/app/features/payee1099/` — models, api service, recipients page
|
||
- `APP/src/app/features/finance-report/pages/form1099-report-page/` — report page
|
||
- `expense-categories-page` — add 1099-box dropdowns
|
||
- `expense-form-dialog` — add payee picker
|
||
- `app.routes.ts`, `user-portal.component.ts`, `core/models/permission.model.ts`
|
||
|
||
---
|
||
|
||
## Task 1: `Form1099` constants
|
||
|
||
**Files:**
|
||
- Create: `API/ROLAC.API/Entities/Form1099.cs`
|
||
|
||
- [ ] **Step 1: Create the constants file**
|
||
|
||
```csharp
|
||
namespace ROLAC.API.Entities;
|
||
|
||
/// <summary>Shared 1099 constants. Box codes match Form1099Box.BoxCode seed values.</summary>
|
||
public static class Form1099
|
||
{
|
||
/// <summary>IRS reporting threshold (USD) per box, per recipient, per calendar year.</summary>
|
||
public const decimal ReportingThreshold = 600m;
|
||
|
||
public const string BoxNec1 = "NEC-1"; // Nonemployee compensation
|
||
public const string BoxMisc1 = "MISC-1"; // Rents
|
||
|
||
public static class W9Status
|
||
{
|
||
public const string Missing = "Missing";
|
||
public const string Requested = "Requested";
|
||
public const string OnFile = "OnFile";
|
||
public const string Expired = "Expired";
|
||
public static readonly IReadOnlyList<string> All = [Missing, Requested, OnFile, Expired];
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Build to verify it compiles**
|
||
|
||
Run: `dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release`
|
||
Expected: Build succeeded.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add API/ROLAC.API/Entities/Form1099.cs
|
||
git commit -m "feat(1099): add Form1099 constants (threshold, box codes, W9 statuses)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 2: `Form1099Box` catalog entity
|
||
|
||
**Files:**
|
||
- Create: `API/ROLAC.API/Entities/Form1099Box.cs`
|
||
|
||
- [ ] **Step 1: Create the entity (mirrors Form990ExpenseLine)**
|
||
|
||
```csharp
|
||
using ROLAC.API.Entities.Base;
|
||
namespace ROLAC.API.Entities;
|
||
|
||
/// <summary>A 1099 reporting box, e.g. "NEC-1 — Nonemployee compensation".</summary>
|
||
public class Form1099Box : AuditableEntity, IAuditable
|
||
{
|
||
public int Id { get; set; }
|
||
public string BoxCode { get; set; } = null!; // "NEC-1", "MISC-1"
|
||
public string Name_en { get; set; } = null!;
|
||
public string? Name_zh { get; set; }
|
||
public string FormType { get; set; } = "1099-NEC"; // "1099-NEC" | "1099-MISC"
|
||
public int SortOrder { get; set; }
|
||
public bool IsActive { get; set; } = true;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Build**
|
||
|
||
Run: `dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release`
|
||
Expected: Build succeeded.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add API/ROLAC.API/Entities/Form1099Box.cs
|
||
git commit -m "feat(1099): add Form1099Box catalog entity"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 3: `Payee1099` recipient master entity
|
||
|
||
**Files:**
|
||
- Create: `API/ROLAC.API/Entities/Payee1099.cs`
|
||
|
||
- [ ] **Step 1: Create the entity**
|
||
|
||
```csharp
|
||
using ROLAC.API.Entities.Base;
|
||
namespace ROLAC.API.Entities;
|
||
|
||
/// <summary>
|
||
/// A 1099 recipient (independent contractor / vendor). Holds W-9 data and an encrypted TIN.
|
||
/// Optionally linked to a Member (e.g. a part-time co-worker paid as a contractor).
|
||
/// </summary>
|
||
public class Payee1099 : SoftDeleteEntity, IAuditable
|
||
{
|
||
public int Id { get; set; }
|
||
public string LegalName { get; set; } = null!; // name on the W-9
|
||
public string? DisplayName { get; set; } // friendly / DBA
|
||
public int? MemberId { get; set; }
|
||
public Member? Member { get; set; }
|
||
public string TaxClassification { get; set; } = "Individual"; // drives Is1099Tracked default
|
||
public bool Is1099Tracked { get; set; } = true;
|
||
public string? TinType { get; set; } // "SSN" | "EIN"
|
||
public string? TinEncrypted { get; set; } // Data-Protection ciphertext
|
||
public string? TinLast4 { get; set; }
|
||
public string? AddressLine1 { get; set; }
|
||
public string? AddressLine2 { get; set; }
|
||
public string? City { get; set; }
|
||
public string? State { get; set; }
|
||
public string? Zip { get; set; }
|
||
public string? Email { get; set; }
|
||
public string? Phone { get; set; }
|
||
public string W9Status { get; set; } = Form1099.W9Status.Missing;
|
||
public DateOnly? W9ReceivedDate { get; set; }
|
||
public string? W9BlobPath { get; set; }
|
||
public bool IsActive { get; set; } = true;
|
||
public string? Notes { get; set; }
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Build**
|
||
|
||
Run: `dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release`
|
||
Expected: Build succeeded.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add API/ROLAC.API/Entities/Payee1099.cs
|
||
git commit -m "feat(1099): add Payee1099 recipient master entity"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 4: Mapping FK fields on category entities + Expense.PayeeId
|
||
|
||
**Files:**
|
||
- Modify: `API/ROLAC.API/Entities/ExpenseSubCategory.cs`, `ExpenseCategoryGroup.cs`, `Expense.cs`
|
||
|
||
- [ ] **Step 1: Add `Form1099BoxId` to ExpenseSubCategory**
|
||
|
||
Add these properties next to the existing `Form990LineId`/`Form990Line` pair:
|
||
|
||
```csharp
|
||
public int? Form1099BoxId { get; set; } // null = not 1099-reportable
|
||
public Form1099Box? Form1099Box { get; set; }
|
||
```
|
||
|
||
- [ ] **Step 2: Add `Form1099BoxId` to ExpenseCategoryGroup**
|
||
|
||
Same two properties (group-level fallback), next to its `Form990LineId`/`Form990Line` pair.
|
||
|
||
- [ ] **Step 3: Add `PayeeId` to Expense**
|
||
|
||
Add next to the existing `MemberId`/`Member` properties:
|
||
|
||
```csharp
|
||
public int? PayeeId { get; set; } // 1099 recipient attribution (header-level)
|
||
public Payee1099? Payee { get; set; }
|
||
```
|
||
|
||
- [ ] **Step 4: Build**
|
||
|
||
Run: `dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release`
|
||
Expected: Build succeeded.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add API/ROLAC.API/Entities/ExpenseSubCategory.cs API/ROLAC.API/Entities/ExpenseCategoryGroup.cs API/ROLAC.API/Entities/Expense.cs
|
||
git commit -m "feat(1099): add Form1099BoxId mapping FKs and Expense.PayeeId"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 5: DbContext configuration
|
||
|
||
**Files:**
|
||
- Modify: `API/ROLAC.API/Data/AppDbContext.cs`
|
||
|
||
- [ ] **Step 1: Add DbSets**
|
||
|
||
Near the other expense/Form990 DbSets:
|
||
|
||
```csharp
|
||
public DbSet<Payee1099> Payee1099s => Set<Payee1099>();
|
||
public DbSet<Form1099Box> Form1099Boxes => Set<Form1099Box>();
|
||
```
|
||
|
||
- [ ] **Step 2: Configure Form1099Box (mirror Form990ExpenseLine config)**
|
||
|
||
In `OnModelCreating`, beside the Form990ExpenseLine block:
|
||
|
||
```csharp
|
||
modelBuilder.Entity<Form1099Box>(entity =>
|
||
{
|
||
entity.Property(e => e.BoxCode).HasMaxLength(10).IsRequired();
|
||
entity.Property(e => e.Name_en).HasMaxLength(200).IsRequired();
|
||
entity.Property(e => e.Name_zh).HasMaxLength(200);
|
||
entity.Property(e => e.FormType).HasMaxLength(20).IsRequired();
|
||
entity.HasIndex(e => e.BoxCode).IsUnique();
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 3: Configure Payee1099**
|
||
|
||
```csharp
|
||
modelBuilder.Entity<Payee1099>(entity =>
|
||
{
|
||
entity.HasQueryFilter(p => !p.IsDeleted);
|
||
entity.Property(e => e.LegalName).HasMaxLength(200).IsRequired();
|
||
entity.Property(e => e.DisplayName).HasMaxLength(200);
|
||
entity.Property(e => e.TaxClassification).HasMaxLength(40).IsRequired();
|
||
entity.Property(e => e.TinType).HasMaxLength(10);
|
||
entity.Property(e => e.TinLast4).HasMaxLength(4);
|
||
entity.Property(e => e.State).HasMaxLength(2);
|
||
entity.Property(e => e.Zip).HasMaxLength(10);
|
||
entity.Property(e => e.W9Status).HasMaxLength(20).HasDefaultValue(Form1099.W9Status.Missing);
|
||
entity.HasOne(e => e.Member).WithMany()
|
||
.HasForeignKey(e => e.MemberId).OnDelete(DeleteBehavior.SetNull);
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 4: Add the mapping FK relationships + Expense.Payee**
|
||
|
||
Inside the existing `ExpenseSubCategory` config block add:
|
||
|
||
```csharp
|
||
entity.HasOne(e => e.Form1099Box).WithMany()
|
||
.HasForeignKey(e => e.Form1099BoxId).OnDelete(DeleteBehavior.SetNull);
|
||
```
|
||
|
||
Inside `ExpenseCategoryGroup` config add the same (for its `Form1099Box`). Inside the `Expense` config block add:
|
||
|
||
```csharp
|
||
entity.HasOne(e => e.Payee).WithMany()
|
||
.HasForeignKey(e => e.PayeeId).OnDelete(DeleteBehavior.SetNull);
|
||
```
|
||
|
||
- [ ] **Step 5: Build**
|
||
|
||
Run: `dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release`
|
||
Expected: Build succeeded.
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add API/ROLAC.API/Data/AppDbContext.cs
|
||
git commit -m "feat(1099): configure Payee1099, Form1099Box, and mapping FKs in DbContext"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 6: `ITinProtector` (TIN encryption) — TDD
|
||
|
||
**Files:**
|
||
- Create: `API/ROLAC.API/Services/Security/ITinProtector.cs`, `TinProtector.cs`
|
||
- Test: `API/ROLAC.API.Tests/Services/TinProtectorTests.cs`
|
||
|
||
- [ ] **Step 1: Write the failing test**
|
||
|
||
```csharp
|
||
using Microsoft.AspNetCore.DataProtection;
|
||
using ROLAC.API.Services.Security;
|
||
using Xunit;
|
||
|
||
namespace ROLAC.API.Tests.Services;
|
||
|
||
public class TinProtectorTests
|
||
{
|
||
private static TinProtector Build() =>
|
||
new TinProtector(DataProtectionProvider.Create("ROLAC.Tests"));
|
||
|
||
[Fact]
|
||
public void Protect_then_Unprotect_round_trips()
|
||
{
|
||
var p = Build();
|
||
var cipher = p.Protect("123-45-6789");
|
||
Assert.NotEqual("123-45-6789", cipher);
|
||
Assert.Equal("123-45-6789", p.Unprotect(cipher));
|
||
}
|
||
|
||
[Theory]
|
||
[InlineData("123-45-6789", "6789")]
|
||
[InlineData("12-3456789", "6789")]
|
||
[InlineData("7", "7")]
|
||
public void Last4_keeps_only_trailing_digits(string raw, string expected)
|
||
=> Assert.Equal(expected, TinProtector.Last4(raw));
|
||
|
||
[Fact]
|
||
public void Last4_of_null_is_null() => Assert.Null(TinProtector.Last4(null));
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Run test to verify it fails**
|
||
|
||
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter TinProtectorTests`
|
||
Expected: FAIL — `TinProtector` does not exist.
|
||
|
||
- [ ] **Step 3: Implement the interface and class**
|
||
|
||
`ITinProtector.cs`:
|
||
|
||
```csharp
|
||
namespace ROLAC.API.Services.Security;
|
||
|
||
/// <summary>Reversible protection for taxpayer identification numbers (SSN/EIN).</summary>
|
||
public interface ITinProtector
|
||
{
|
||
string Protect(string plaintext);
|
||
string Unprotect(string ciphertext);
|
||
}
|
||
```
|
||
|
||
`TinProtector.cs`:
|
||
|
||
```csharp
|
||
using Microsoft.AspNetCore.DataProtection;
|
||
|
||
namespace ROLAC.API.Services.Security;
|
||
|
||
public class TinProtector : ITinProtector
|
||
{
|
||
private readonly IDataProtector _protector;
|
||
public TinProtector(IDataProtectionProvider provider)
|
||
=> _protector = provider.CreateProtector("Payee1099.Tin");
|
||
|
||
public string Protect(string plaintext) => _protector.Protect(plaintext);
|
||
public string Unprotect(string ciphertext) => _protector.Unprotect(ciphertext);
|
||
|
||
/// <summary>Last four digits of a TIN (ignoring dashes/spaces); null/empty in → null.</summary>
|
||
public static string? Last4(string? raw)
|
||
{
|
||
if (string.IsNullOrWhiteSpace(raw)) return null;
|
||
var digits = new string(raw.Where(char.IsDigit).ToArray());
|
||
return digits.Length <= 4 ? digits : digits[^4..];
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Run test to verify it passes**
|
||
|
||
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter TinProtectorTests`
|
||
Expected: PASS (4 tests).
|
||
|
||
- [ ] **Step 5: Register in DI**
|
||
|
||
In `API/ROLAC.API/Program.cs`, near the other `AddScoped` finance services:
|
||
|
||
```csharp
|
||
builder.Services.AddDataProtection();
|
||
builder.Services.AddScoped<ITinProtector, TinProtector>();
|
||
```
|
||
|
||
(Add `using ROLAC.API.Services.Security;` if needed.)
|
||
|
||
- [ ] **Step 6: Build + commit**
|
||
|
||
```bash
|
||
dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release
|
||
git add API/ROLAC.API/Services/Security API/ROLAC.API.Tests/Services/TinProtectorTests.cs API/ROLAC.API/Program.cs
|
||
git commit -m "feat(1099): add ITinProtector with Data Protection encryption + last-4 helper"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 7: Report + recipient DTOs
|
||
|
||
**Files:**
|
||
- Create: `API/ROLAC.API/DTOs/Finance/Form1099ReportDtos.cs`, `API/ROLAC.API/DTOs/Payee/Payee1099Dtos.cs`
|
||
|
||
- [ ] **Step 1: Create report DTOs**
|
||
|
||
`Form1099ReportDtos.cs`:
|
||
|
||
```csharp
|
||
namespace ROLAC.API.DTOs.Finance;
|
||
|
||
public class Form1099BoxDto
|
||
{
|
||
public int Id { get; set; }
|
||
public string BoxCode { get; set; } = "";
|
||
public string Name_en { get; set; } = "";
|
||
public string? Name_zh { get; set; }
|
||
public string FormType { get; set; } = "";
|
||
public int SortOrder { get; set; }
|
||
}
|
||
|
||
public class Form1099RecipientRowDto
|
||
{
|
||
public int PayeeId { get; set; }
|
||
public string LegalName { get; set; } = "";
|
||
public string? TinLast4 { get; set; }
|
||
public string W9Status { get; set; } = "";
|
||
public decimal NecTotal { get; set; }
|
||
public decimal RentsTotal { get; set; }
|
||
public decimal GrandTotal { get; set; }
|
||
public bool MeetsThreshold { get; set; }
|
||
public bool W9Missing { get; set; }
|
||
}
|
||
|
||
public class Form1099SummaryDto
|
||
{
|
||
public int TaxYear { get; set; }
|
||
public List<Form1099RecipientRowDto> Rows { get; set; } = [];
|
||
public decimal TotalReportable { get; set; }
|
||
public int RecipientsAtThreshold { get; set; }
|
||
public int RecipientsMissingW9 { get; set; }
|
||
}
|
||
|
||
public class Form1099PaymentDto
|
||
{
|
||
public string PaidDate { get; set; } = "";
|
||
public string Description { get; set; } = "";
|
||
public string CategoryName { get; set; } = "";
|
||
public string BoxCode { get; set; } = "";
|
||
public decimal Amount { get; set; }
|
||
}
|
||
|
||
public class Form1099RecipientDetailDto
|
||
{
|
||
public int PayeeId { get; set; }
|
||
public string LegalName { get; set; } = "";
|
||
public string? TinLast4 { get; set; }
|
||
public string W9Status { get; set; } = "";
|
||
public int TaxYear { get; set; }
|
||
public List<Form1099PaymentDto> Payments { get; set; } = [];
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Create recipient DTOs**
|
||
|
||
`Payee1099Dtos.cs`:
|
||
|
||
```csharp
|
||
using System.ComponentModel.DataAnnotations;
|
||
namespace ROLAC.API.DTOs.Payee;
|
||
|
||
public class Payee1099ListItemDto
|
||
{
|
||
public int Id { get; set; }
|
||
public string LegalName { get; set; } = "";
|
||
public string? DisplayName { get; set; }
|
||
public int? MemberId { get; set; }
|
||
public string? MemberName { get; set; }
|
||
public string TaxClassification { get; set; } = "";
|
||
public bool Is1099Tracked { get; set; }
|
||
public string? TinType { get; set; }
|
||
public string? TinLast4 { get; set; }
|
||
public string W9Status { get; set; } = "";
|
||
public bool IsActive { get; set; }
|
||
}
|
||
|
||
public class Payee1099Dto : Payee1099ListItemDto
|
||
{
|
||
public string? AddressLine1 { get; set; }
|
||
public string? AddressLine2 { get; set; }
|
||
public string? City { get; set; }
|
||
public string? State { get; set; }
|
||
public string? Zip { get; set; }
|
||
public string? Email { get; set; }
|
||
public string? Phone { get; set; }
|
||
public string? W9ReceivedDate { get; set; }
|
||
public bool HasW9Document { get; set; }
|
||
public string? Notes { get; set; }
|
||
}
|
||
|
||
public class SavePayee1099Request
|
||
{
|
||
[Required, MaxLength(200)] public string LegalName { get; set; } = "";
|
||
[MaxLength(200)] public string? DisplayName { get; set; }
|
||
public int? MemberId { get; set; }
|
||
[Required, MaxLength(40)] public string TaxClassification { get; set; } = "Individual";
|
||
public bool Is1099Tracked { get; set; } = true;
|
||
[MaxLength(10)] public string? TinType { get; set; }
|
||
/// <summary>Plain TIN; null = leave unchanged on update. Encrypted server-side.</summary>
|
||
public string? Tin { get; set; }
|
||
[MaxLength(100)] public string? AddressLine1 { get; set; }
|
||
[MaxLength(100)] public string? AddressLine2 { get; set; }
|
||
[MaxLength(60)] public string? City { get; set; }
|
||
[MaxLength(2)] public string? State { get; set; }
|
||
[MaxLength(10)] public string? Zip { get; set; }
|
||
[MaxLength(120)] public string? Email { get; set; }
|
||
[MaxLength(40)] public string? Phone { get; set; }
|
||
[MaxLength(20)] public string W9Status { get; set; } = "Missing";
|
||
public DateOnly? W9ReceivedDate { get; set; }
|
||
public bool IsActive { get; set; } = true;
|
||
public string? Notes { get; set; }
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Build + commit**
|
||
|
||
```bash
|
||
dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release
|
||
git add API/ROLAC.API/DTOs/Finance/Form1099ReportDtos.cs API/ROLAC.API/DTOs/Payee/Payee1099Dtos.cs
|
||
git commit -m "feat(1099): add report and recipient DTOs"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 8: `Form1099ReportService` aggregation — TDD
|
||
|
||
**Files:**
|
||
- Create: `API/ROLAC.API/Services/IForm1099ReportService.cs`, `Form1099ReportService.cs`
|
||
- Test: `API/ROLAC.API.Tests/Services/Form1099ReportServiceTests.cs`
|
||
|
||
- [ ] **Step 1: Write the interface**
|
||
|
||
```csharp
|
||
using ROLAC.API.DTOs.Finance;
|
||
namespace ROLAC.API.Services;
|
||
|
||
public interface IForm1099ReportService
|
||
{
|
||
Task<List<Form1099BoxDto>> GetBoxesAsync();
|
||
Task<Form1099SummaryDto> GetAnnualSummaryAsync(int taxYear);
|
||
Task<Form1099RecipientDetailDto?> GetRecipientDetailAsync(int payeeId, int taxYear);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Write the failing tests**
|
||
|
||
```csharp
|
||
using Microsoft.EntityFrameworkCore;
|
||
using ROLAC.API.Data;
|
||
using ROLAC.API.Entities;
|
||
using ROLAC.API.Services;
|
||
using Xunit;
|
||
|
||
namespace ROLAC.API.Tests.Services;
|
||
|
||
public class Form1099ReportServiceTests
|
||
{
|
||
private static AppDbContext NewDb() =>
|
||
new(new DbContextOptionsBuilder<AppDbContext>()
|
||
.UseInMemoryDatabase(Guid.NewGuid().ToString()).Options);
|
||
|
||
// Seeds: ministry; a Personnel>Contract Labor sub mapped to NEC-1; a Facility>Rent sub
|
||
// mapped to MISC-1; an unmapped Salary sub. Returns the db.
|
||
private static AppDbContext Seeded(out int necSubId, out int rentSubId, out int salarySubId)
|
||
{
|
||
var db = NewDb();
|
||
db.Ministries.Add(new Ministry { Id = 1, Name_en = "Admin", DefaultFunctionalClass = "Program" });
|
||
var nec = new Form1099Box { Id = 1, BoxCode = Form1099.BoxNec1, Name_en = "NEC", FormType = "1099-NEC", SortOrder = 1 };
|
||
var rent = new Form1099Box { Id = 2, BoxCode = Form1099.BoxMisc1, Name_en = "Rent", FormType = "1099-MISC", SortOrder = 2 };
|
||
db.Form1099Boxes.AddRange(nec, rent);
|
||
db.ExpenseCategoryGroups.Add(new ExpenseCategoryGroup { Id = 1, Name_en = "Personnel" });
|
||
db.ExpenseCategoryGroups.Add(new ExpenseCategoryGroup { Id = 2, Name_en = "Facility" });
|
||
db.ExpenseSubCategories.Add(new ExpenseSubCategory { Id = 1, GroupId = 1, Name_en = "Contract Labor", Form1099BoxId = 1 });
|
||
db.ExpenseSubCategories.Add(new ExpenseSubCategory { Id = 2, GroupId = 2, Name_en = "Rent", Form1099BoxId = 2 });
|
||
db.ExpenseSubCategories.Add(new ExpenseSubCategory { Id = 3, GroupId = 1, Name_en = "Salary & Wages", Form1099BoxId = null });
|
||
db.SaveChanges();
|
||
necSubId = 1; rentSubId = 2; salarySubId = 3;
|
||
return db;
|
||
}
|
||
|
||
private static void AddPaidExpense(AppDbContext db, int payeeId, int subId, int groupId, decimal amount, DateOnly paidOn)
|
||
{
|
||
var e = new Expense
|
||
{
|
||
MinistryId = 1, Type = "VendorPayment", Status = "Paid", PayeeId = payeeId,
|
||
Amount = amount, Description = "x", ExpenseDate = paidOn,
|
||
PaidAt = new DateTimeOffset(paidOn.ToDateTime(TimeOnly.MinValue), TimeSpan.Zero),
|
||
Lines = [ new ExpenseLine { CategoryGroupId = groupId, SubCategoryId = subId, Amount = amount } ],
|
||
};
|
||
db.Expenses.Add(e);
|
||
db.SaveChanges();
|
||
}
|
||
|
||
[Fact]
|
||
public async Task Sums_tracked_recipient_by_box_and_flags_threshold_and_w9()
|
||
{
|
||
var db = Seeded(out var necSub, out var rentSub, out _);
|
||
db.Payee1099s.Add(new Payee1099 { Id = 10, LegalName = "Pat Player", Is1099Tracked = true, W9Status = "Missing" });
|
||
db.SaveChanges();
|
||
AddPaidExpense(db, 10, necSub, 1, 700m, new DateOnly(2026, 3, 1));
|
||
AddPaidExpense(db, 10, rentSub, 2, 500m, new DateOnly(2026, 4, 1));
|
||
|
||
var svc = new Form1099ReportService(db);
|
||
var sum = await svc.GetAnnualSummaryAsync(2026);
|
||
|
||
var row = Assert.Single(sum.Rows);
|
||
Assert.Equal(700m, row.NecTotal);
|
||
Assert.Equal(500m, row.RentsTotal);
|
||
Assert.Equal(1200m, row.GrandTotal);
|
||
Assert.True(row.MeetsThreshold); // NEC 700 >= 600
|
||
Assert.True(row.W9Missing);
|
||
Assert.Equal(1, sum.RecipientsAtThreshold);
|
||
Assert.Equal(1, sum.RecipientsMissingW9);
|
||
}
|
||
|
||
[Fact]
|
||
public async Task Excludes_untracked_recipients_and_unmapped_and_wrong_year()
|
||
{
|
||
var db = Seeded(out var necSub, out _, out var salarySub);
|
||
db.Payee1099s.Add(new Payee1099 { Id = 10, LegalName = "Tracked Tim", Is1099Tracked = true, W9Status = "OnFile" });
|
||
db.Payee1099s.Add(new Payee1099 { Id = 11, LegalName = "Corp Inc", Is1099Tracked = false, W9Status = "OnFile" });
|
||
db.SaveChanges();
|
||
AddPaidExpense(db, 11, necSub, 1, 5000m, new DateOnly(2026, 5, 1)); // untracked -> excluded
|
||
AddPaidExpense(db, 10, salarySub, 1, 5000m, new DateOnly(2026, 6, 1)); // unmapped box -> excluded
|
||
AddPaidExpense(db, 10, necSub, 1, 5000m, new DateOnly(2025, 6, 1)); // wrong year -> excluded
|
||
|
||
var svc = new Form1099ReportService(db);
|
||
var sum = await svc.GetAnnualSummaryAsync(2026);
|
||
|
||
Assert.Empty(sum.Rows);
|
||
}
|
||
|
||
[Fact]
|
||
public async Task Threshold_flag_is_false_below_600()
|
||
{
|
||
var db = Seeded(out var necSub, out _, out _);
|
||
db.Payee1099s.Add(new Payee1099 { Id = 10, LegalName = "Small Sam", Is1099Tracked = true, W9Status = "OnFile" });
|
||
db.SaveChanges();
|
||
AddPaidExpense(db, 10, necSub, 1, 599.99m, new DateOnly(2026, 7, 1));
|
||
|
||
var sum = await new Form1099ReportService(db).GetAnnualSummaryAsync(2026);
|
||
var row = Assert.Single(sum.Rows);
|
||
Assert.False(row.MeetsThreshold);
|
||
Assert.False(row.W9Missing);
|
||
Assert.Equal(0, sum.RecipientsAtThreshold);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Run tests to verify they fail**
|
||
|
||
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter Form1099ReportServiceTests`
|
||
Expected: FAIL — `Form1099ReportService` does not exist.
|
||
|
||
- [ ] **Step 4: Implement the service**
|
||
|
||
```csharp
|
||
using Microsoft.EntityFrameworkCore;
|
||
using ROLAC.API.Data;
|
||
using ROLAC.API.DTOs.Finance;
|
||
using ROLAC.API.Entities;
|
||
|
||
namespace ROLAC.API.Services;
|
||
|
||
/// <summary>
|
||
/// Read-only aggregation producing the year-end 1099 recipient summary. CASH BASIS:
|
||
/// only Paid expenses whose PaidAt falls in the tax year, attributed to a tracked payee,
|
||
/// on a line whose category maps to a 1099 box (sub ?? group). Unmapped lines are excluded.
|
||
/// </summary>
|
||
public class Form1099ReportService : IForm1099ReportService
|
||
{
|
||
private readonly AppDbContext _db;
|
||
public Form1099ReportService(AppDbContext db) => _db = db;
|
||
|
||
public async Task<List<Form1099BoxDto>> GetBoxesAsync() =>
|
||
await _db.Form1099Boxes.AsNoTracking().Where(b => b.IsActive)
|
||
.OrderBy(b => b.SortOrder)
|
||
.Select(b => new Form1099BoxDto
|
||
{
|
||
Id = b.Id, BoxCode = b.BoxCode, Name_en = b.Name_en,
|
||
Name_zh = b.Name_zh, FormType = b.FormType, SortOrder = b.SortOrder,
|
||
}).ToListAsync();
|
||
|
||
private IQueryable<PaidLine> ReportableLines(int taxYear) =>
|
||
from e in _db.Expenses.Where(e => e.Status == "Paid" && e.PaidAt != null
|
||
&& e.PaidAt.Value.Year == taxYear && e.PayeeId != null)
|
||
join p in _db.Payee1099s.Where(p => p.Is1099Tracked) on e.PayeeId equals p.Id
|
||
join l in _db.ExpenseLines on e.Id equals l.ExpenseId
|
||
join sub in _db.ExpenseSubCategories on l.SubCategoryId equals sub.Id
|
||
join grp in _db.ExpenseCategoryGroups on l.CategoryGroupId equals grp.Id
|
||
select new PaidLine
|
||
{
|
||
PayeeId = p.Id,
|
||
LegalName = p.LegalName,
|
||
TinLast4 = p.TinLast4,
|
||
W9Status = p.W9Status,
|
||
PaidAt = e.PaidAt!.Value,
|
||
Description = e.Description,
|
||
CategoryName = grp.Name_en + " / " + sub.Name_en,
|
||
Amount = l.Amount,
|
||
BoxId = sub.Form1099BoxId ?? grp.Form1099BoxId,
|
||
};
|
||
|
||
public async Task<Form1099SummaryDto> GetAnnualSummaryAsync(int taxYear)
|
||
{
|
||
var boxes = await _db.Form1099Boxes.AsNoTracking().ToDictionaryAsync(b => b.Id, b => b.BoxCode);
|
||
var lines = await ReportableLines(taxYear).Where(x => x.BoxId != null).ToListAsync();
|
||
|
||
var dto = new Form1099SummaryDto { TaxYear = taxYear };
|
||
foreach (var g in lines.GroupBy(x => x.PayeeId))
|
||
{
|
||
var first = g.First();
|
||
var nec = g.Where(x => boxes.GetValueOrDefault(x.BoxId!.Value) == Form1099.BoxNec1).Sum(x => x.Amount);
|
||
var rents = g.Where(x => boxes.GetValueOrDefault(x.BoxId!.Value) == Form1099.BoxMisc1).Sum(x => x.Amount);
|
||
var w9Missing = first.W9Status != Form1099.W9Status.OnFile;
|
||
var meets = nec >= Form1099.ReportingThreshold || rents >= Form1099.ReportingThreshold;
|
||
dto.Rows.Add(new Form1099RecipientRowDto
|
||
{
|
||
PayeeId = first.PayeeId, LegalName = first.LegalName, TinLast4 = first.TinLast4,
|
||
W9Status = first.W9Status, NecTotal = nec, RentsTotal = rents,
|
||
GrandTotal = nec + rents, MeetsThreshold = meets, W9Missing = w9Missing,
|
||
});
|
||
}
|
||
dto.Rows = dto.Rows.OrderByDescending(r => r.GrandTotal).ToList();
|
||
dto.TotalReportable = dto.Rows.Sum(r => r.GrandTotal);
|
||
dto.RecipientsAtThreshold = dto.Rows.Count(r => r.MeetsThreshold);
|
||
dto.RecipientsMissingW9 = dto.Rows.Count(r => r.W9Missing);
|
||
return dto;
|
||
}
|
||
|
||
public async Task<Form1099RecipientDetailDto?> GetRecipientDetailAsync(int payeeId, int taxYear)
|
||
{
|
||
var payee = await _db.Payee1099s.AsNoTracking().FirstOrDefaultAsync(p => p.Id == payeeId);
|
||
if (payee is null) return null;
|
||
var boxes = await _db.Form1099Boxes.AsNoTracking().ToDictionaryAsync(b => b.Id, b => b.BoxCode);
|
||
var lines = await ReportableLines(taxYear).Where(x => x.PayeeId == payeeId && x.BoxId != null).ToListAsync();
|
||
|
||
return new Form1099RecipientDetailDto
|
||
{
|
||
PayeeId = payee.Id, LegalName = payee.LegalName, TinLast4 = payee.TinLast4,
|
||
W9Status = payee.W9Status, TaxYear = taxYear,
|
||
Payments = lines.OrderBy(x => x.PaidAt).Select(x => new Form1099PaymentDto
|
||
{
|
||
PaidDate = DateOnly.FromDateTime(x.PaidAt.Date).ToString("yyyy-MM-dd"),
|
||
Description = x.Description, CategoryName = x.CategoryName,
|
||
BoxCode = boxes.GetValueOrDefault(x.BoxId!.Value) ?? "", Amount = x.Amount,
|
||
}).ToList(),
|
||
};
|
||
}
|
||
|
||
private sealed class PaidLine
|
||
{
|
||
public int PayeeId; public string LegalName = ""; public string? TinLast4; public string W9Status = "";
|
||
public DateTimeOffset PaidAt; public string Description = ""; public string CategoryName = "";
|
||
public decimal Amount; public int? BoxId;
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: Run tests to verify they pass**
|
||
|
||
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter Form1099ReportServiceTests`
|
||
Expected: PASS (3 tests).
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add API/ROLAC.API/Services/IForm1099ReportService.cs API/ROLAC.API/Services/Form1099ReportService.cs API/ROLAC.API.Tests/Services/Form1099ReportServiceTests.cs
|
||
git commit -m "feat(1099): add Form1099ReportService cash-basis annual aggregation"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 9: `Payee1099Service` (recipient CRUD) — TDD
|
||
|
||
**Files:**
|
||
- Create: `API/ROLAC.API/Services/IPayee1099Service.cs`, `Payee1099Service.cs`
|
||
- Test: `API/ROLAC.API.Tests/Services/Payee1099ServiceTests.cs`
|
||
|
||
- [ ] **Step 1: Write the interface**
|
||
|
||
```csharp
|
||
using ROLAC.API.DTOs.Payee;
|
||
namespace ROLAC.API.Services;
|
||
|
||
public interface IPayee1099Service
|
||
{
|
||
Task<List<Payee1099ListItemDto>> GetAllAsync(bool includeInactive);
|
||
Task<Payee1099Dto?> GetByIdAsync(int id);
|
||
Task<int> CreateAsync(SavePayee1099Request r);
|
||
Task UpdateAsync(int id, SavePayee1099Request r);
|
||
Task DeleteAsync(int id);
|
||
/// <summary>Full decrypted TIN. Caller must be authorized (gated at controller).</summary>
|
||
Task<string?> RevealTinAsync(int id);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Write the failing tests**
|
||
|
||
```csharp
|
||
using Microsoft.AspNetCore.DataProtection;
|
||
using Microsoft.EntityFrameworkCore;
|
||
using ROLAC.API.Data;
|
||
using ROLAC.API.DTOs.Payee;
|
||
using ROLAC.API.Entities;
|
||
using ROLAC.API.Services;
|
||
using ROLAC.API.Services.Security;
|
||
using Xunit;
|
||
|
||
namespace ROLAC.API.Tests.Services;
|
||
|
||
public class Payee1099ServiceTests
|
||
{
|
||
private static (Payee1099Service svc, AppDbContext db) Build()
|
||
{
|
||
var db = new AppDbContext(new DbContextOptionsBuilder<AppDbContext>()
|
||
.UseInMemoryDatabase(Guid.NewGuid().ToString()).Options);
|
||
var tin = new TinProtector(DataProtectionProvider.Create("ROLAC.Tests"));
|
||
return (new Payee1099Service(db, tin), db);
|
||
}
|
||
|
||
[Fact]
|
||
public async Task Create_encrypts_tin_and_stores_last4_only_in_clear()
|
||
{
|
||
var (svc, db) = Build();
|
||
var id = await svc.CreateAsync(new SavePayee1099Request
|
||
{ LegalName = "Pat Player", TinType = "SSN", Tin = "123-45-6789", W9Status = "OnFile" });
|
||
|
||
var saved = await db.Payee1099s.FindAsync(id);
|
||
Assert.NotNull(saved);
|
||
Assert.Equal("6789", saved!.TinLast4);
|
||
Assert.NotNull(saved.TinEncrypted);
|
||
Assert.DoesNotContain("123-45-6789", saved.TinEncrypted!);
|
||
Assert.Equal("123-45-6789", await svc.RevealTinAsync(id));
|
||
}
|
||
|
||
[Fact]
|
||
public async Task Update_with_null_tin_keeps_existing_ciphertext()
|
||
{
|
||
var (svc, db) = Build();
|
||
var id = await svc.CreateAsync(new SavePayee1099Request { LegalName = "X", Tin = "11-2223333" });
|
||
var before = (await db.Payee1099s.FindAsync(id))!.TinEncrypted;
|
||
|
||
await svc.UpdateAsync(id, new SavePayee1099Request { LegalName = "X renamed", Tin = null });
|
||
|
||
var after = await db.Payee1099s.FindAsync(id);
|
||
Assert.Equal("X renamed", after!.LegalName);
|
||
Assert.Equal(before, after.TinEncrypted);
|
||
Assert.Equal("3333", after.TinLast4);
|
||
}
|
||
|
||
[Fact]
|
||
public async Task List_dto_masks_tin_to_last4()
|
||
{
|
||
var (svc, _) = Build();
|
||
await svc.CreateAsync(new SavePayee1099Request { LegalName = "Y", Tin = "999-88-7777" });
|
||
var list = await svc.GetAllAsync(includeInactive: true);
|
||
var item = Assert.Single(list);
|
||
Assert.Equal("7777", item.TinLast4);
|
||
}
|
||
|
||
[Fact]
|
||
public async Task Delete_is_soft_and_hides_from_list()
|
||
{
|
||
var (svc, _) = Build();
|
||
var id = await svc.CreateAsync(new SavePayee1099Request { LegalName = "Z" });
|
||
await svc.DeleteAsync(id);
|
||
Assert.Empty(await svc.GetAllAsync(includeInactive: true));
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Run tests to verify they fail**
|
||
|
||
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter Payee1099ServiceTests`
|
||
Expected: FAIL — `Payee1099Service` does not exist.
|
||
|
||
- [ ] **Step 4: Implement the service**
|
||
|
||
```csharp
|
||
using Microsoft.EntityFrameworkCore;
|
||
using ROLAC.API.Data;
|
||
using ROLAC.API.DTOs.Payee;
|
||
using ROLAC.API.Entities;
|
||
using ROLAC.API.Services.Security;
|
||
|
||
namespace ROLAC.API.Services;
|
||
|
||
public class Payee1099Service : IPayee1099Service
|
||
{
|
||
private readonly AppDbContext _db;
|
||
private readonly ITinProtector _tin;
|
||
public Payee1099Service(AppDbContext db, ITinProtector tin) { _db = db; _tin = tin; }
|
||
|
||
public async Task<List<Payee1099ListItemDto>> GetAllAsync(bool includeInactive)
|
||
{
|
||
var q = _db.Payee1099s.AsNoTracking().Include(p => p.Member).AsQueryable();
|
||
if (!includeInactive) q = q.Where(p => p.IsActive);
|
||
return await q.OrderBy(p => p.LegalName).Select(p => new Payee1099ListItemDto
|
||
{
|
||
Id = p.Id, LegalName = p.LegalName, DisplayName = p.DisplayName,
|
||
MemberId = p.MemberId,
|
||
MemberName = p.Member != null ? p.Member.LastName_zh + p.Member.FirstName_zh : null,
|
||
TaxClassification = p.TaxClassification, Is1099Tracked = p.Is1099Tracked,
|
||
TinType = p.TinType, TinLast4 = p.TinLast4, W9Status = p.W9Status, IsActive = p.IsActive,
|
||
}).ToListAsync();
|
||
}
|
||
|
||
public async Task<Payee1099Dto?> GetByIdAsync(int id)
|
||
{
|
||
var p = await _db.Payee1099s.AsNoTracking().Include(x => x.Member).FirstOrDefaultAsync(x => x.Id == id);
|
||
if (p is null) return null;
|
||
return new Payee1099Dto
|
||
{
|
||
Id = p.Id, LegalName = p.LegalName, DisplayName = p.DisplayName, MemberId = p.MemberId,
|
||
MemberName = p.Member != null ? p.Member.LastName_zh + p.Member.FirstName_zh : null,
|
||
TaxClassification = p.TaxClassification, Is1099Tracked = p.Is1099Tracked,
|
||
TinType = p.TinType, TinLast4 = p.TinLast4, W9Status = p.W9Status, IsActive = p.IsActive,
|
||
AddressLine1 = p.AddressLine1, AddressLine2 = p.AddressLine2, City = p.City,
|
||
State = p.State, Zip = p.Zip, Email = p.Email, Phone = p.Phone,
|
||
W9ReceivedDate = p.W9ReceivedDate?.ToString("yyyy-MM-dd"),
|
||
HasW9Document = p.W9BlobPath != null, Notes = p.Notes,
|
||
};
|
||
}
|
||
|
||
public async Task<int> CreateAsync(SavePayee1099Request r)
|
||
{
|
||
var p = new Payee1099();
|
||
Apply(p, r);
|
||
_db.Payee1099s.Add(p);
|
||
await _db.SaveChangesAsync();
|
||
return p.Id;
|
||
}
|
||
|
||
public async Task UpdateAsync(int id, SavePayee1099Request r)
|
||
{
|
||
var p = await _db.Payee1099s.FirstOrDefaultAsync(x => x.Id == id)
|
||
?? throw new KeyNotFoundException($"Payee1099 {id} not found.");
|
||
Apply(p, r);
|
||
await _db.SaveChangesAsync();
|
||
}
|
||
|
||
public async Task DeleteAsync(int id)
|
||
{
|
||
var p = await _db.Payee1099s.FirstOrDefaultAsync(x => x.Id == id)
|
||
?? throw new KeyNotFoundException($"Payee1099 {id} not found.");
|
||
p.IsDeleted = true;
|
||
p.DeletedAt = DateTimeOffset.UtcNow;
|
||
await _db.SaveChangesAsync();
|
||
}
|
||
|
||
public async Task<string?> RevealTinAsync(int id)
|
||
{
|
||
var p = await _db.Payee1099s.AsNoTracking().FirstOrDefaultAsync(x => x.Id == id);
|
||
return p?.TinEncrypted is null ? null : _tin.Unprotect(p.TinEncrypted);
|
||
}
|
||
|
||
// Maps request -> entity. A null Tin leaves the existing ciphertext untouched (update case).
|
||
private void Apply(Payee1099 p, SavePayee1099Request r)
|
||
{
|
||
p.LegalName = r.LegalName; p.DisplayName = r.DisplayName; p.MemberId = r.MemberId;
|
||
p.TaxClassification = r.TaxClassification; p.Is1099Tracked = r.Is1099Tracked;
|
||
p.TinType = r.TinType;
|
||
p.AddressLine1 = r.AddressLine1; p.AddressLine2 = r.AddressLine2; p.City = r.City;
|
||
p.State = r.State; p.Zip = r.Zip; p.Email = r.Email; p.Phone = r.Phone;
|
||
p.W9Status = r.W9Status; p.W9ReceivedDate = r.W9ReceivedDate;
|
||
p.IsActive = r.IsActive; p.Notes = r.Notes;
|
||
if (!string.IsNullOrWhiteSpace(r.Tin))
|
||
{
|
||
p.TinEncrypted = _tin.Protect(r.Tin);
|
||
p.TinLast4 = TinProtector.Last4(r.Tin);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> NOTE: confirm the `Member` display-name properties (`LastName_zh`/`FirstName_zh`) match the real `Member` entity; adjust the two `MemberName` expressions if the fields differ.
|
||
|
||
- [ ] **Step 5: Run tests to verify they pass**
|
||
|
||
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter Payee1099ServiceTests`
|
||
Expected: PASS (4 tests).
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add API/ROLAC.API/Services/IPayee1099Service.cs API/ROLAC.API/Services/Payee1099Service.cs API/ROLAC.API.Tests/Services/Payee1099ServiceTests.cs
|
||
git commit -m "feat(1099): add Payee1099Service recipient CRUD with TIN protection"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 10: Permission module + DI registration
|
||
|
||
**Files:**
|
||
- Modify: `API/ROLAC.API/Authorization/Modules.cs`, `API/ROLAC.API/Program.cs`
|
||
|
||
- [ ] **Step 1: Add the `Form1099` module constant**
|
||
|
||
In `Modules.cs` add the constant after `Form990Report`:
|
||
|
||
```csharp
|
||
public const string Form1099 = "Form1099";
|
||
```
|
||
|
||
And insert `Form1099,` into the `All` list immediately after `Form990Report,`.
|
||
|
||
- [ ] **Step 2: Register services in Program.cs**
|
||
|
||
Beside `AddScoped<IForm990ReportService, Form990ReportService>()`:
|
||
|
||
```csharp
|
||
builder.Services.AddScoped<IForm1099ReportService, Form1099ReportService>();
|
||
builder.Services.AddScoped<IPayee1099Service, Payee1099Service>();
|
||
```
|
||
|
||
- [ ] **Step 3: Build + commit**
|
||
|
||
```bash
|
||
dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release
|
||
git add API/ROLAC.API/Authorization/Modules.cs API/ROLAC.API/Program.cs
|
||
git commit -m "feat(1099): register Form1099 permission module and services"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 11: Controllers
|
||
|
||
**Files:**
|
||
- Create: `API/ROLAC.API/Controllers/Payee1099Controller.cs`, `Controllers/Form1099ReportController.cs`
|
||
|
||
- [ ] **Step 1: Create the recipient controller**
|
||
|
||
```csharp
|
||
using Microsoft.AspNetCore.Mvc;
|
||
using ROLAC.API.Authorization;
|
||
using ROLAC.API.DTOs.Payee;
|
||
using ROLAC.API.Services;
|
||
|
||
namespace ROLAC.API.Controllers;
|
||
|
||
[ApiController]
|
||
[Route("api/payee-1099")]
|
||
[HasPermission(Modules.Form1099, PermissionActions.Read)]
|
||
public class Payee1099Controller : ControllerBase
|
||
{
|
||
private readonly IPayee1099Service _svc;
|
||
public Payee1099Controller(IPayee1099Service svc) => _svc = svc;
|
||
|
||
[HttpGet]
|
||
public async Task<IActionResult> GetAll([FromQuery] bool includeInactive = false)
|
||
=> Ok(await _svc.GetAllAsync(includeInactive));
|
||
|
||
[HttpGet("{id:int}")]
|
||
public async Task<IActionResult> GetById(int id)
|
||
=> await _svc.GetByIdAsync(id) is { } dto ? Ok(dto) : NotFound();
|
||
|
||
[HttpPost]
|
||
[HasPermission(Modules.Form1099, PermissionActions.Write)]
|
||
public async Task<IActionResult> Create([FromBody] SavePayee1099Request r)
|
||
=> Ok(new { id = await _svc.CreateAsync(r) });
|
||
|
||
[HttpPut("{id:int}")]
|
||
[HasPermission(Modules.Form1099, PermissionActions.Write)]
|
||
public async Task<IActionResult> Update(int id, [FromBody] SavePayee1099Request r)
|
||
{ await _svc.UpdateAsync(id, r); return NoContent(); }
|
||
|
||
[HttpDelete("{id:int}")]
|
||
[HasPermission(Modules.Form1099, PermissionActions.Delete)]
|
||
public async Task<IActionResult> Delete(int id)
|
||
{ await _svc.DeleteAsync(id); return NoContent(); }
|
||
|
||
// Full TIN reveal is gated on Write (a stronger right than Read).
|
||
[HttpGet("{id:int}/tin")]
|
||
[HasPermission(Modules.Form1099, PermissionActions.Write)]
|
||
public async Task<IActionResult> RevealTin(int id)
|
||
=> Ok(new { tin = await _svc.RevealTinAsync(id) });
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Create the report controller**
|
||
|
||
```csharp
|
||
using Microsoft.AspNetCore.Mvc;
|
||
using ROLAC.API.Authorization;
|
||
using ROLAC.API.Services;
|
||
|
||
namespace ROLAC.API.Controllers;
|
||
|
||
[ApiController]
|
||
[Route("api/form1099-report")]
|
||
[HasPermission(Modules.Form1099, PermissionActions.Read)]
|
||
public class Form1099ReportController : ControllerBase
|
||
{
|
||
private readonly IForm1099ReportService _svc;
|
||
public Form1099ReportController(IForm1099ReportService svc) => _svc = svc;
|
||
|
||
[HttpGet("boxes")]
|
||
public async Task<IActionResult> Boxes() => Ok(await _svc.GetBoxesAsync());
|
||
|
||
[HttpGet("summary")]
|
||
public async Task<IActionResult> Summary([FromQuery] int taxYear)
|
||
=> Ok(await _svc.GetAnnualSummaryAsync(taxYear));
|
||
|
||
[HttpGet("recipient/{payeeId:int}")]
|
||
public async Task<IActionResult> Recipient(int payeeId, [FromQuery] int taxYear)
|
||
=> await _svc.GetRecipientDetailAsync(payeeId, taxYear) is { } d ? Ok(d) : NotFound();
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Build + commit**
|
||
|
||
```bash
|
||
dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release
|
||
git add API/ROLAC.API/Controllers/Payee1099Controller.cs API/ROLAC.API/Controllers/Form1099ReportController.cs
|
||
git commit -m "feat(1099): add recipient and report controllers"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 12: Persist `PayeeId` through the expense flow
|
||
|
||
**Files:**
|
||
- Modify: `API/ROLAC.API/DTOs/Expense/ExpenseDtos.cs`, `API/ROLAC.API/Services/ExpenseService.cs`
|
||
|
||
- [ ] **Step 1: Add `PayeeId` to request + DTOs**
|
||
|
||
In `ExpenseDtos.cs`: add `public int? PayeeId { get; set; }` to `CreateExpenseRequest` and to `ExpenseListItemDto` (so the form can round-trip the selection).
|
||
|
||
- [ ] **Step 2: Persist on create and update**
|
||
|
||
In `ExpenseService.CreateAsync`, set `PayeeId = r.PayeeId` on the new `Expense`. In `UpdateAsync`, set `e.PayeeId = r.PayeeId;`. In the projection that builds `ExpenseListItemDto`/`ExpenseDto`, map `PayeeId = e.PayeeId`.
|
||
|
||
- [ ] **Step 3: Run the existing expense tests (regression)**
|
||
|
||
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release --filter ExpenseServiceTests`
|
||
Expected: PASS (unchanged count).
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add API/ROLAC.API/DTOs/Expense/ExpenseDtos.cs API/ROLAC.API/Services/ExpenseService.cs
|
||
git commit -m "feat(1099): carry PayeeId through expense create/update/read"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 13: Seed the box catalog + default mappings
|
||
|
||
**Files:**
|
||
- Modify: `API/ROLAC.API/Data/DbSeeder.cs`
|
||
|
||
- [ ] **Step 1: Add seed data arrays**
|
||
|
||
Near `Form990LineSeed`/`Form990SubMappingSeed`, add:
|
||
|
||
```csharp
|
||
private static readonly (string Code, string En, string Zh, string FormType, int Sort)[] Form1099BoxSeed =
|
||
[
|
||
(Form1099.BoxNec1, "Nonemployee compensation", "非員工報酬", "1099-NEC", 1),
|
||
(Form1099.BoxMisc1, "Rents", "租金", "1099-MISC", 2),
|
||
];
|
||
|
||
// Only service/rent subcategories get a box. Everything else stays unmapped (not reportable).
|
||
private static readonly (string GroupEn, string SubEn, string Code)[] Form1099SubMappingSeed =
|
||
[
|
||
("Personnel", "Honorarium", Form1099.BoxNec1),
|
||
("Personnel", "Contract Labor", Form1099.BoxNec1),
|
||
("Professional Services", "Legal", Form1099.BoxNec1),
|
||
("Professional Services", "Accounting & Audit", Form1099.BoxNec1),
|
||
("Professional Services", "Other Professional", Form1099.BoxNec1),
|
||
("Facility", "Rent", Form1099.BoxMisc1),
|
||
];
|
||
```
|
||
|
||
- [ ] **Step 2: Add the seeder method (mirrors SeedForm990ExpenseLinesAsync; null-fill only)**
|
||
|
||
```csharp
|
||
public static async Task SeedForm1099BoxesAsync(AppDbContext db)
|
||
{
|
||
foreach (var (code, en, zh, formType, sort) in Form1099BoxSeed)
|
||
if (!await db.Form1099Boxes.AnyAsync(b => b.BoxCode == code))
|
||
db.Form1099Boxes.Add(new Form1099Box
|
||
{ BoxCode = code, Name_en = en, Name_zh = zh, FormType = formType, SortOrder = sort, IsActive = true });
|
||
await db.SaveChangesAsync();
|
||
|
||
var boxesByCode = await db.Form1099Boxes.ToDictionaryAsync(b => b.BoxCode, b => b.Id);
|
||
var subs = await db.ExpenseSubCategories.Include(s => s.Group).ToListAsync();
|
||
foreach (var (groupEn, subEn, code) in Form1099SubMappingSeed)
|
||
{
|
||
var sub = subs.FirstOrDefault(s => s.Group!.Name_en == groupEn && s.Name_en == subEn);
|
||
if (sub is not null && sub.Form1099BoxId is null && boxesByCode.TryGetValue(code, out var boxId))
|
||
sub.Form1099BoxId = boxId;
|
||
}
|
||
await db.SaveChangesAsync();
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Call it from `SeedAsync`**
|
||
|
||
After `await SeedForm990ExpenseLinesAsync(db);` add:
|
||
|
||
```csharp
|
||
await SeedForm1099BoxesAsync(db);
|
||
```
|
||
|
||
- [ ] **Step 4: Build + commit**
|
||
|
||
```bash
|
||
dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release
|
||
git add API/ROLAC.API/Data/DbSeeder.cs
|
||
git commit -m "feat(1099): seed Form1099Box catalog and default subcategory mappings"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 14: EF migration
|
||
|
||
**Files:**
|
||
- Create: migration under `API/ROLAC.API/Migrations/`
|
||
|
||
- [ ] **Step 1: Add the migration**
|
||
|
||
Run (per [[project-build-run-env]], use a separate output to avoid the VS bin lock):
|
||
|
||
```bash
|
||
dotnet ef migrations add AddForm1099RecipientTracking --project API/ROLAC.API/ROLAC.API.csproj
|
||
```
|
||
|
||
- [ ] **Step 2: Inspect the generated migration**
|
||
|
||
Open the new `*_AddForm1099RecipientTracking.cs`. Confirm it: creates `Form1099Boxes` and `Payee1099s` tables; adds `Form1099BoxId` to `ExpenseSubCategories` and `ExpenseCategoryGroups`; adds `PayeeId` to `Expenses`; and creates the three FKs with `ReferentialAction.SetNull`. No data backfill is required (all new columns are nullable).
|
||
|
||
- [ ] **Step 3: Apply to the dev DB**
|
||
|
||
```bash
|
||
dotnet ef database update --project API/ROLAC.API/ROLAC.API.csproj
|
||
```
|
||
Expected: migration applies cleanly; seeding runs on next API start.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add API/ROLAC.API/Migrations/
|
||
git commit -m "feat(1099): EF migration for Payee1099, Form1099Box, mapping columns"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 15: Copy B PDF + filing CSV service
|
||
|
||
**Files:**
|
||
- Create: `API/ROLAC.API/Services/Form1099/I1099FormService.cs`, `Form1099FormService.cs`
|
||
- Modify: `Form1099ReportController.cs` (two download endpoints)
|
||
|
||
> Reuse the DevExpress document pipeline already used by check printing ([[project-devexpress-check-printing]]); read the church payer info from `ChurchProfile`. Inspect `ICheckPrintService`/`Form1099`'s sibling `CheckPrintService` for the exact DevExpress API in use and mirror it.
|
||
|
||
- [ ] **Step 1: Define the interface**
|
||
|
||
```csharp
|
||
namespace ROLAC.API.Services.Form1099;
|
||
|
||
public interface I1099FormService
|
||
{
|
||
/// <summary>Recipient Copy B 1099-NEC PDF for one payee/year (plain paper).</summary>
|
||
Task<(Stream stream, string contentType, string fileName)> RenderCopyBAsync(int payeeId, int taxYear);
|
||
|
||
/// <summary>Filing-data CSV (one row per reportable recipient) for IRIS/accountant.</summary>
|
||
Task<(Stream stream, string contentType, string fileName)> ExportFilingCsvAsync(int taxYear);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Implement the CSV first (no DevExpress dependency — easy to verify)**
|
||
|
||
```csharp
|
||
using System.Globalization;
|
||
using System.Text;
|
||
using ROLAC.API.Services; // IForm1099ReportService
|
||
|
||
namespace ROLAC.API.Services.Form1099;
|
||
|
||
public partial class Form1099FormService : I1099FormService
|
||
{
|
||
private readonly IForm1099ReportService _report;
|
||
public Form1099FormService(IForm1099ReportService report /*, + ChurchProfile + DevExpress deps */)
|
||
=> _report = report;
|
||
|
||
public async Task<(Stream, string, string)> ExportFilingCsvAsync(int taxYear)
|
||
{
|
||
var sum = await _report.GetAnnualSummaryAsync(taxYear);
|
||
var sb = new StringBuilder();
|
||
sb.AppendLine("LegalName,TinLast4,W9Status,Box1_NEC,Box1_Rents,Total,MeetsThreshold");
|
||
foreach (var r in sum.Rows)
|
||
sb.AppendLine(string.Join(",",
|
||
Csv(r.LegalName), Csv(r.TinLast4 ?? ""), Csv(r.W9Status),
|
||
r.NecTotal.ToString(CultureInfo.InvariantCulture),
|
||
r.RentsTotal.ToString(CultureInfo.InvariantCulture),
|
||
r.GrandTotal.ToString(CultureInfo.InvariantCulture),
|
||
r.MeetsThreshold ? "Y" : "N"));
|
||
var bytes = Encoding.UTF8.GetBytes(sb.ToString());
|
||
return (new MemoryStream(bytes), "text/csv", $"1099-filing-{taxYear}.csv");
|
||
|
||
static string Csv(string v) => v.Contains(',') || v.Contains('"')
|
||
? "\"" + v.Replace("\"", "\"\"") + "\"" : v;
|
||
}
|
||
|
||
// RenderCopyBAsync implemented in the DevExpress partial (Step 3).
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Implement Copy B PDF (DevExpress partial)**
|
||
|
||
Create `Form1099FormService.Pdf.cs` mirroring `CheckPrintService`'s `DevExpress.Document.Processor` usage: load/compose the 1099-NEC Copy B layout, fill payer (ChurchProfile), recipient (Payee1099 — legal name, address, masked TIN), and box 1 = NEC total for the year (from `GetRecipientDetailAsync`). Return the rendered PDF stream. (Copy B is plain-paper; no official red form needed.)
|
||
|
||
- [ ] **Step 4: Register + add endpoints**
|
||
|
||
In `Program.cs`: `builder.Services.AddScoped<I1099FormService, Form1099FormService>();`
|
||
|
||
In `Form1099ReportController` add (Read-gated downloads):
|
||
|
||
```csharp
|
||
[HttpGet("recipient/{payeeId:int}/copy-b")]
|
||
public async Task<IActionResult> CopyB(int payeeId, [FromQuery] int taxYear)
|
||
{ var (s, ct, fn) = await _form.RenderCopyBAsync(payeeId, taxYear); return File(s, ct, fn); }
|
||
|
||
[HttpGet("export-csv")]
|
||
public async Task<IActionResult> ExportCsv([FromQuery] int taxYear)
|
||
{ var (s, ct, fn) = await _form.ExportFilingCsvAsync(taxYear); return File(s, ct, fn); }
|
||
```
|
||
|
||
(Inject `I1099FormService _form` into the controller constructor.)
|
||
|
||
- [ ] **Step 5: Build + commit**
|
||
|
||
```bash
|
||
dotnet build API/ROLAC.API/ROLAC.API.csproj -c Release
|
||
git add API/ROLAC.API/Services/Form1099 API/ROLAC.API/Controllers/Form1099ReportController.cs API/ROLAC.API/Program.cs
|
||
git commit -m "feat(1099): Copy B PDF + filing CSV service and download endpoints"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 16: Frontend — models + API services
|
||
|
||
**Files:**
|
||
- Create: `APP/src/app/features/payee1099/models/payee1099.model.ts`, `services/payee1099-api.service.ts`, `services/form1099-report-api.service.ts`
|
||
|
||
- [ ] **Step 1: Models**
|
||
|
||
```typescript
|
||
export interface Payee1099ListItem {
|
||
id: number; legalName: string; displayName?: string;
|
||
memberId?: number; memberName?: string; taxClassification: string;
|
||
is1099Tracked: boolean; tinType?: string; tinLast4?: string;
|
||
w9Status: string; isActive: boolean;
|
||
}
|
||
export interface Payee1099 extends Payee1099ListItem {
|
||
addressLine1?: string; addressLine2?: string; city?: string; state?: string; zip?: string;
|
||
email?: string; phone?: string; w9ReceivedDate?: string; hasW9Document: boolean; notes?: string;
|
||
}
|
||
export interface SavePayee1099Request {
|
||
legalName: string; displayName?: string; memberId?: number | null;
|
||
taxClassification: string; is1099Tracked: boolean;
|
||
tinType?: string; tin?: string | null;
|
||
addressLine1?: string; addressLine2?: string; city?: string; state?: string; zip?: string;
|
||
email?: string; phone?: string; w9Status: string; w9ReceivedDate?: string | null;
|
||
isActive: boolean; notes?: string;
|
||
}
|
||
export interface Form1099Box { id: number; boxCode: string; name_en: string; name_zh?: string; formType: string; sortOrder: number; }
|
||
export interface Form1099RecipientRow {
|
||
payeeId: number; legalName: string; tinLast4?: string; w9Status: string;
|
||
necTotal: number; rentsTotal: number; grandTotal: number; meetsThreshold: boolean; w9Missing: boolean;
|
||
}
|
||
export interface Form1099Summary {
|
||
taxYear: number; rows: Form1099RecipientRow[];
|
||
totalReportable: number; recipientsAtThreshold: number; recipientsMissingW9: number;
|
||
}
|
||
export interface Form1099Payment { paidDate: string; description: string; categoryName: string; boxCode: string; amount: number; }
|
||
export interface Form1099RecipientDetail { payeeId: number; legalName: string; tinLast4?: string; w9Status: string; taxYear: number; payments: Form1099Payment[]; }
|
||
```
|
||
|
||
- [ ] **Step 2: API services (mirror `expense-snapshot-api.service.ts` style)**
|
||
|
||
`payee1099-api.service.ts`: `getAll(includeInactive)`, `getById(id)`, `create(req)`, `update(id, req)`, `delete(id)`, `revealTin(id)` against `api/payee-1099`.
|
||
|
||
`form1099-report-api.service.ts`: `getBoxes()`, `getSummary(taxYear)`, `getRecipient(payeeId, taxYear)`, and URL builders `copyBUrl(payeeId, taxYear)` / `exportCsvUrl(taxYear)` against `api/form1099-report`.
|
||
|
||
- [ ] **Step 3: Build + commit**
|
||
|
||
```bash
|
||
git add APP/src/app/features/payee1099/models APP/src/app/features/payee1099/services
|
||
git commit -m "feat(1099): frontend models and API services"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 17: Frontend — permission module + nav + routes
|
||
|
||
**Files:**
|
||
- Modify: `APP/src/app/core/models/permission.model.ts`, `APP/src/app/portals/user-portal/user-portal.component.ts`, `APP/src/app/app.routes.ts`
|
||
|
||
- [ ] **Step 1: Add to `PermissionModules`**
|
||
|
||
```typescript
|
||
Form1099: 'Form1099',
|
||
```
|
||
|
||
- [ ] **Step 2: Add finance nav items** (in the Expenses finance group, mirroring the Form990/Disbursements items)
|
||
|
||
```typescript
|
||
{ text: '1099 Recipients', icon: <existingOutlineIcon>, path: '/user-portal/finance/payee-1099',
|
||
permission: { module: PermissionModules.Form1099, action: 'read' } },
|
||
{ text: '1099 Report', icon: <existingOutlineIcon>, path: '/user-portal/finance/form1099-report',
|
||
permission: { module: PermissionModules.Form1099, action: 'read' } },
|
||
```
|
||
|
||
- [ ] **Step 3: Add routes** (mirror the Form990 report route block)
|
||
|
||
```typescript
|
||
{
|
||
path: 'finance/payee-1099',
|
||
loadComponent: () => import('./features/payee1099/pages/payee-1099-page/payee-1099-page.component').then(m => m.Payee1099PageComponent),
|
||
canActivate: [PermissionGuard],
|
||
data: { permission: { module: PermissionModules.Form1099, action: 'read' },
|
||
title: '1099 Recipients', titleZh: '1099 收款人', section: 'Finance' },
|
||
},
|
||
{
|
||
path: 'finance/form1099-report',
|
||
loadComponent: () => import('./features/finance-report/pages/form1099-report-page/form1099-report-page.component').then(m => m.Form1099ReportPageComponent),
|
||
canActivate: [PermissionGuard],
|
||
data: { permission: { module: PermissionModules.Form1099, action: 'read' },
|
||
title: '1099 Year-End Report', titleZh: '1099 年度報表', section: 'Finance' },
|
||
},
|
||
```
|
||
|
||
- [ ] **Step 4: Commit** (won't build until Task 18/19 create the components — commit after those, or stub the components first)
|
||
|
||
```bash
|
||
git add APP/src/app/core/models/permission.model.ts APP/src/app/portals/user-portal/user-portal.component.ts APP/src/app/app.routes.ts
|
||
git commit -m "feat(1099): frontend permission module, nav items, routes"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 18: Frontend — 1099 Recipients master page
|
||
|
||
**Files:**
|
||
- Create: `APP/src/app/features/payee1099/pages/payee-1099-page/payee-1099-page.component.ts`
|
||
|
||
- [ ] **Step 1: Build the component modeled on `expense-categories-page`**
|
||
|
||
Standalone component (inline template per [[project-frontend-test-runner]] if unit-tested), with:
|
||
- Kendo Grid (desktop, `hidden md:block`) columns: LegalName, MemberName, TaxClassification, `tinLast4` shown as `***-**-{{last4}}`, W9Status badge, Is1099Tracked (Yes/No), IsActive. Right-click context menu → Edit / Deactivate ([[feedback-kendo-table-actions-context-menu]]). Primary column click opens edit ([[feedback-kendo-table-select-via-row-click]]).
|
||
- Mobile card list (`md:hidden flex flex-col gap-3`) — never set `display` in SCSS ([[feedback-scss-display-defeats-md-hidden]]).
|
||
- Edit dialog: Tailwind `grid grid-cols-1 md:grid-cols-2` ([[feedback-form-layout-tailwind]]) with LegalName, DisplayName, Member picker (DropdownList, `[valuePrimitive]="true"` — [[feedback-kendo-value-primitive]]), TaxClassification dropdown, Is1099Tracked switch, TinType + Tin (entry field; on edit show placeholder `***-**-{{last4}}`, blank = unchanged), address fields, W9Status dropdown, W9ReceivedDate datepicker (local Y/M/D, never `toISOString()` — [[feedback-date-only-local-format]]), Notes.
|
||
- Save calls `create` or `update`; header "New Recipient" action via `appPageHeaderActions` ([[project-unified-system-header]]).
|
||
|
||
- [ ] **Step 2: Verify build**
|
||
|
||
Run: `npm --prefix APP run build`
|
||
Expected: build succeeds.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add APP/src/app/features/payee1099/pages/payee-1099-page
|
||
git commit -m "feat(1099): recipients master page"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 19: Frontend — 1099 Year-End Report page
|
||
|
||
**Files:**
|
||
- Create: `APP/src/app/features/finance-report/pages/form1099-report-page/form1099-report-page.component.ts`
|
||
|
||
- [ ] **Step 1: Build the component modeled on `form990-report-page`**
|
||
|
||
- Year selector (NumericTextBox or dropdown of recent years), "Load" action.
|
||
- Summary chips: TotalReportable, RecipientsAtThreshold, RecipientsMissingW9.
|
||
- Desktop Kendo Grid (`hidden md:block`): LegalName, `***-**-{{tinLast4}}`, W9Status (highlight when `w9Missing`), NecTotal, RentsTotal, GrandTotal (currency), MeetsThreshold badge. Row click → recipient detail (drill-in dialog listing `payments`).
|
||
- Mobile cards (`md:hidden`).
|
||
- Header actions (`appPageHeaderActions`): "Export filing CSV" → `exportCsvUrl(year)`; per-recipient "Copy B PDF" → `copyBUrl(payeeId, year)` (open in new tab).
|
||
|
||
- [ ] **Step 2: Verify build**
|
||
|
||
Run: `npm --prefix APP run build`
|
||
Expected: build succeeds.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add APP/src/app/features/finance-report/pages/form1099-report-page
|
||
git commit -m "feat(1099): year-end 1099 report page with drill-in, CSV, Copy B"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 20: Frontend — category→box mapping + expense payee picker
|
||
|
||
**Files:**
|
||
- Modify: `expense-categories-page` component, `expense-form-dialog` component (+ its category/expense models)
|
||
|
||
- [ ] **Step 1: Add `form1099BoxId` to category models + DTOs**
|
||
|
||
Add `form1099BoxId?: number | null` to the group and subcategory frontend models, and (backend) to the category DTOs/save requests + `ExpenseCategoryService` mapping so the value round-trips. Load boxes via `form1099-report-api.getBoxes()`.
|
||
|
||
- [ ] **Step 2: Add the "1099 Box" dropdown**
|
||
|
||
In the group and subcategory edit dialogs of `expense-categories-page`, add a Kendo DropdownList bound to `form1099BoxId` (data = boxes, `textField="name_en"`, `valueField="id"`, `[valuePrimitive]="true"`, a "— none —" default), beside the existing 990-line dropdown.
|
||
|
||
- [ ] **Step 3: Add the payee picker to the expense form**
|
||
|
||
In `expense-form-dialog`, add an optional "1099 Recipient" DropdownList (data from `payee1099-api.getAll(false)`, `textField="legalName"`, `valueField="id"`, `[valuePrimitive]="true"`, nullable default), bound to the new `payeeId` field; include `payeeId` in the create/update payload.
|
||
|
||
- [ ] **Step 4: Verify build + commit**
|
||
|
||
```bash
|
||
npm --prefix APP run build
|
||
git add APP/src/app/features/expense
|
||
git commit -m "feat(1099): category->box mapping dropdowns and expense payee picker"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 21: Docs + permission seeding
|
||
|
||
**Files:**
|
||
- Modify: `docs/DB_SCHEMA.md`, `API/ROLAC.API/Data/DbSeeder.cs` (role permissions, if finance role is seeded there)
|
||
|
||
- [ ] **Step 1: Document new tables/columns in `docs/DB_SCHEMA.md`**
|
||
|
||
Add `Payee1099s` and `Form1099Boxes` tables (fields + notes: TIN is encrypted, only last-4 in clear), and the new columns `Expenses.PayeeId`, `ExpenseSubCategories.Form1099BoxId`, `ExpenseCategoryGroups.Form1099BoxId`.
|
||
|
||
- [ ] **Step 2: Seed finance-role permissions for `Form1099`**
|
||
|
||
If `SeedRolePermissionsAsync` grants finance roles per module, add `Form1099` (Read/Write/Delete) to the finance role grants so the menu/pages appear without manual matrix edits. (super_admin auto-bypasses.)
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add docs/DB_SCHEMA.md API/ROLAC.API/Data/DbSeeder.cs
|
||
git commit -m "docs(1099): document schema; seed Form1099 finance-role permissions"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 22: Full verification pass
|
||
|
||
- [ ] **Step 1: Backend — full test suite (Release)**
|
||
|
||
Run: `dotnet test API/ROLAC.API.Tests/ROLAC.API.Tests.csproj -c Release`
|
||
Expected: all pass, including `TinProtectorTests`, `Form1099ReportServiceTests`, `Payee1099ServiceTests`, and unchanged `ExpenseServiceTests`.
|
||
|
||
- [ ] **Step 2: API smoke** (run API standalone per [[project-build-run-env]])
|
||
|
||
1. POST `api/payee-1099` → create "Pat Player" (SSN, W9Status=OnFile, Is1099Tracked=true). Confirm GET list shows `tinLast4` only.
|
||
2. Create a VendorPayment expense (Personnel ▸ Contract Labor, $700, this year), set its `payeeId`, approve, and Pay it (sets PaidAt this year).
|
||
3. GET `api/form1099-report/summary?taxYear=<year>` → Pat appears, NecTotal 700, MeetsThreshold true.
|
||
4. GET `api/form1099-report/recipient/{id}/copy-b?taxYear=<year>` → PDF renders with no DevExpress watermark ([[project-devexpress-check-printing]]).
|
||
5. GET `api/form1099-report/export-csv?taxYear=<year>` → CSV downloads with Pat's row.
|
||
6. GET `api/payee-1099/{id}/tin` with Write permission → full TIN; with Read-only token → 403.
|
||
|
||
- [ ] **Step 3: Frontend**
|
||
|
||
Run: `npm --prefix APP run build` (expect success). Scoped unit tests for any inline-template component via `--include` with Edge `CHROME_BIN` ([[project-frontend-test-runner]]). Manually load the recipients page and report page on desktop and a ~375px mobile width: grid on desktop, cards on mobile; drill-in works; CSV + Copy B download.
|
||
|
||
- [ ] **Step 4: Update the project memory**
|
||
|
||
After merge, update `project_form990_audit_readiness.md` to mark sub-project B implemented (commits, what shipped) and note the known follow-ups (no VendorName→master backfill; Copy A/1096 + IRIS e-file deferred; threshold is a constant).
|
||
|
||
---
|
||
|
||
## Self-Review notes (addressed)
|
||
- **Spec coverage:** entities (T2–T4), TIN encryption (T6), report cash-basis + flags (T8), recipient CRUD + masking (T9), permissions (T10), controllers + TIN reveal gate (T11), expense PayeeId (T12), seeding null-fill (T13), migration (T14), Copy B + CSV (T15), all four frontend surfaces (T16–T20), docs/schema (T21), verification (T22) — every spec §2–§11 item maps to a task.
|
||
- **Type consistency:** box codes flow from `Form1099` constants (T1) through seed (T13), service (T8), and DTOs (T7); `SavePayee1099Request.Tin` null-means-unchanged is honored in `Apply` (T9) and tested (T9 Step 2).
|
||
- **Open confirm-on-implement:** `Member` display-name fields in `Payee1099Service` (flagged in T9); exact DevExpress API mirrored from `CheckPrintService` (T15); whether finance roles are seeded per-module (T21).
|
||
```
|