[CLAUDE] Phase2: Form Engine MVP + docs (gotchas, skill, handoff)

Backend Forms:
- Domain/Forms: ContractTemplate (FormCode, Name, ContractType, FileName, StoragePath, Format, FieldSpec JSON, IsActive) + ContractClause
- EF config voi unique FormCode + query filter IsDeleted
- DbSets + IApplicationDbContext update
- Migration AddForms (bang 14 total)
- Packages: DocumentFormat.OpenXml 3.x + ClosedXML 0.105+
- Application/Forms:
  - IFormRenderer interface + RenderResult record
  - FormFeatures.cs: List/Get/Render CQRS
  - IWebHostEnvironmentLocator (abstract IWebHostEnvironment)
- Infrastructure/Forms:
  - DocxRenderer: OpenXml-based placeholder {{field}} replace, handle split runs (gom text tat ca <w:t> trong paragraph, replace, gan lai text dau + clear rest)
  - XlsxRenderer: ClosedXML cell value replace
  - FormRenderer router theo format docx/xlsx
- Api:
  - FormsController: GET /templates (filter type, onlyActive), GET /templates/{id}, POST /templates/{id}/render (return file)
  - WebHostEnvironmentLocator impl
- DbInitializer SeedContractTemplatesAsync: seed 8 template metadata, IsActive=true chi khi file ton tai

Templates vat ly:
- Copy 5 .docx/.xlsx tu FORM/ sang wwwroot/templates/
- 3 .doc (FO-002.02/03/06) chua convert: IsActive=false (Word COM bi stuck luc test, can retry voi DisplayAlerts=0 hoac LibreOffice)
- scripts/convert-doc-to-docx.ps1 (Word COM automation)

Frontend fe-admin:
- types/forms.ts: ContractTemplate + ContractTypeLabel
- pages/forms/FormsPage.tsx: list templates + Render dialog (paste JSON data → download .docx/.xlsx)
- Route /forms them vao App.tsx

Bug fix:
- SpaceProcessingModeValues namespace: wrap EnumValue<> full path
- SaveAs2($path, 16) thay vi SaveAs([ref], [ref]) — PowerShell type issue
- Word COM stuck: kill process, skip .doc cho MVP

Docs (theo yeu cau user):
- docs/gotchas.md MOI: 17 pitfalls nhom theo tech stack / EF Core / OpenXml / JSON / dev workflow
- .claude/skills/form-engine/SKILL.md: placeholder → full spec (algorithm + code pointers + API + limitations)
- .claude/skills/permission-matrix/SKILL.md: placeholder → full spec (BE policy + FE guard + seed + pitfalls)
- docs/HANDOFF.md MOI: brief 5 phut cho session sau (run quickstart + where we are + next steps + file tree + gotchas ref)
- docs/STATUS.md: update cumulative stats + next up Phase 3
- docs/changelog/migration-todos.md: tick Phase 2 iteration 1 items + add iteration 2 list
- docs/changelog/sessions/2026-04-21-1200-phase2-form-engine.md: session log
- CLAUDE.md root: them reference den gotchas + HANDOFF

E2E verified:
- GET /api/forms/templates (onlyActive=false) → 8 templates
- POST /api/forms/templates/{FO-002.05}/render voi data dict → HTTP 200 + file .docx 482KB (Microsoft Word 2007+ OK)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/Backend/SolutionErp.Application/Common/Interfaces/IApplicationDbContext.cs

@@ -1,4 +1,5 @@
 using Microsoft.EntityFrameworkCore;
+using SolutionErp.Domain.Forms;
 using SolutionErp.Domain.Identity;
 using SolutionErp.Domain.Master;
 
@@ -11,6 +12,8 @@ public interface IApplicationDbContext
     DbSet<Department> Departments { get; }
     DbSet<MenuItem> MenuItems { get; }
     DbSet<Permission> Permissions { get; }
+    DbSet<ContractTemplate> ContractTemplates { get; }
+    DbSet<ContractClause> ContractClauses { get; }
 
     Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
 }

src/Backend/SolutionErp.Application/Forms/FormFeatures.cs

@@ -0,0 +1,96 @@
+using FluentValidation;
+using MediatR;
+using Microsoft.EntityFrameworkCore;
+using SolutionErp.Application.Common.Exceptions;
+using SolutionErp.Application.Common.Interfaces;
+using SolutionErp.Application.Forms.Services;
+using SolutionErp.Domain.Contracts;
+
+namespace SolutionErp.Application.Forms;
+
+public record ContractTemplateDto(
+    Guid Id,
+    string FormCode,
+    string Name,
+    ContractType? ContractType,
+    string FileName,
+    string Format,
+    string? FieldSpec,
+    string? Description,
+    bool IsActive);
+
+// ========== List templates ==========
+public record ListContractTemplatesQuery(ContractType? ContractType = null, bool OnlyActive = true)
+    : IRequest<List<ContractTemplateDto>>;
+
+public class ListContractTemplatesQueryHandler(IApplicationDbContext db)
+    : IRequestHandler<ListContractTemplatesQuery, List<ContractTemplateDto>>
+{
+    public async Task<List<ContractTemplateDto>> Handle(ListContractTemplatesQuery request, CancellationToken ct)
+    {
+        var query = db.ContractTemplates.AsNoTracking();
+        if (request.OnlyActive) query = query.Where(x => x.IsActive);
+        if (request.ContractType is not null) query = query.Where(x => x.ContractType == request.ContractType);
+
+        return await query
+            .OrderBy(x => x.FormCode)
+            .Select(x => new ContractTemplateDto(
+                x.Id, x.FormCode, x.Name, x.ContractType, x.FileName, x.Format, x.FieldSpec, x.Description, x.IsActive))
+            .ToListAsync(ct);
+    }
+}
+
+// ========== Get one ==========
+public record GetContractTemplateQuery(Guid Id) : IRequest<ContractTemplateDto>;
+
+public class GetContractTemplateQueryHandler(IApplicationDbContext db)
+    : IRequestHandler<GetContractTemplateQuery, ContractTemplateDto>
+{
+    public async Task<ContractTemplateDto> Handle(GetContractTemplateQuery request, CancellationToken ct)
+    {
+        var x = await db.ContractTemplates.AsNoTracking().FirstOrDefaultAsync(t => t.Id == request.Id, ct)
+            ?? throw new NotFoundException("ContractTemplate", request.Id);
+        return new ContractTemplateDto(
+            x.Id, x.FormCode, x.Name, x.ContractType, x.FileName, x.Format, x.FieldSpec, x.Description, x.IsActive);
+    }
+}
+
+// ========== Render ==========
+public record RenderTemplateCommand(Guid TemplateId, Dictionary<string, string?> Data)
+    : IRequest<RenderResult>;
+
+public class RenderTemplateCommandValidator : AbstractValidator<RenderTemplateCommand>
+{
+    public RenderTemplateCommandValidator()
+    {
+        RuleFor(x => x.TemplateId).NotEmpty();
+        RuleFor(x => x.Data).NotNull();
+    }
+}
+
+public class RenderTemplateCommandHandler(
+    IApplicationDbContext db,
+    IFormRenderer renderer,
+    IWebHostEnvironmentLocator envLocator) : IRequestHandler<RenderTemplateCommand, RenderResult>
+{
+    public async Task<RenderResult> Handle(RenderTemplateCommand request, CancellationToken ct)
+    {
+        var tpl = await db.ContractTemplates.AsNoTracking()
+            .FirstOrDefaultAsync(t => t.Id == request.TemplateId, ct)
+            ?? throw new NotFoundException("ContractTemplate", request.TemplateId);
+
+        var absPath = Path.Combine(envLocator.WebRootPath, tpl.StoragePath);
+        if (!File.Exists(absPath))
+            throw new NotFoundException($"File template không tồn tại: {tpl.StoragePath}");
+
+        var outName = $"{tpl.FormCode}_preview.{tpl.Format}";
+        return await renderer.RenderAsync(absPath, tpl.Format, request.Data, outName, ct);
+    }
+}
+
+// Abstraction nhỏ cho webRootPath — để Application không phụ thuộc IWebHostEnvironment
+public interface IWebHostEnvironmentLocator
+{
+    string WebRootPath { get; }
+    string ContentRootPath { get; }
+}

src/Backend/SolutionErp.Application/Forms/Services/IFormRenderer.cs

@@ -0,0 +1,15 @@
+namespace SolutionErp.Application.Forms.Services;
+
+public record RenderResult(byte[] Content, string FileName, string ContentType);
+
+public interface IFormRenderer
+{
+    // Render template file (.docx hoặc .xlsx) với placeholder {{field}} replace bằng data.
+    // data values: string (kể cả number/date đã format). Null → replace bằng rỗng.
+    Task<RenderResult> RenderAsync(
+        string templateAbsolutePath,
+        string format,  // "docx" | "xlsx"
+        IReadOnlyDictionary<string, string?> data,
+        string outputFileName,
+        CancellationToken ct = default);
+}