Phase 12: draft generation (FR-16)

ไฟล์ร่าง (draft) — generate docx จาก template แบบ stateless ไม่สร้าง
Document/version; stamp เฉพาะ custom property TemplateId เพื่อให้ add-in
เห็นเป็น untracked; Start Versioning ส่ง form field templateId ให้ backend
ผูก template ตอน auto-create — เอกสารเริ่มที่ v1 (ไม่มี v0) + field sync เต็มระบบ

- Backend: POST /api/templates/{id}/generate-draft (200 คืนไฟล์) +
  DocxGenerationService.GenerateDraft + แยก TemplateFieldValidation ใช้ร่วมกับ
  generate + UploadVersion รับ templateId (non-GUID/unknown → 400,
  deactivated → ผูกได้, document เดิม → เฉย) + CORS expose Content-Disposition
- Add-in: readTrackedProperties อ่าน TemplateId + ส่ง templateId เฉพาะ
  startVersioning + hint ไฟล์ร่างใน task pane
- Web: ปุ่ม "สร้างไฟล์ร่าง" บนฟอร์มเดิม + downloadFile รับ init (POST → blob)
- Docs: spec v8 (FR-16, AC-19) + Phase 12 + CONTEXT.md + ADR 0002 +
  acceptance-review AC-19
- Tests: backend 82 / add-in 66 / web 59 + build ครบ; QA reviewer PASS
  (2 rounds); ค้าง manual บน Word จริง

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

backend/WordVersioning.Api/Services/AddInMetadata.cs

@@ -9,4 +9,9 @@ public static class AddInMetadata
     public const string SavedByAddInPropertyName = "SavedByAddIn";
 
     public const string DocumentTrackingIdPropertyName = "DocumentTrackingId";
+
+    /// <summary>FR-16 — stamp ลงไฟล์ร่าง (draft) เท่านั้น: template ต้นทาง · ไม่ stamp
+    /// SavedByAddIn/DocumentTrackingId เพื่อให้ add-in มองไฟล์ร่างเป็น untracked
+    /// (ฝั่ง add-in ใช้ชื่อ TEMPLATE_ID_PROPERTY ค่าเดียวกันนี้ ส่งต่อเป็น form field ตอน Start Versioning)</summary>
+    public const string TemplateIdPropertyName = "TemplateId";
 }

backend/WordVersioning.Api/Services/DocxGenerationService.cs

@@ -16,6 +16,11 @@ public interface IDocxGenerationService
     /// <b>ที่ run level</b> (รักษา run properties/formatting ของ template) แล้ว stamp
     /// Custom Properties (SavedByAddIn + DocumentTrackingId) — คืนเป็น bytes ของไฟล์ใหม่</summary>
     byte[] Generate(Stream templateStream, IReadOnlyDictionary<string, string> values, Guid documentTrackingId);
+
+    /// <summary>FR-16 — ไฟล์ร่าง (draft): แทนที่ SDT เหมือน Generate แต่ stamp custom property
+    /// <b>เฉพาะ `TemplateId`</b> (GUID ของ template ต้นทาง) — ไม่ stamp SavedByAddIn/DocumentTrackingId
+    /// เพื่อให้ add-in มองไฟล์ร่างเป็น untracked จนกว่าผู้ใช้จะกด Start Versioning</summary>
+    byte[] GenerateDraft(Stream templateStream, IReadOnlyDictionary<string, string> values, Guid templateId);
 }
 
 /// <summary>จัดการ docx ด้วย OpenXML SDK — ใช้ทั้งตอน detect fields และตอน generate (FR-9, FR-10)</summary>
@@ -42,32 +47,67 @@ public class DocxGenerationService : IDocxGenerationService
 
     public byte[] Generate(Stream templateStream, IReadOnlyDictionary<string, string> values, Guid documentTrackingId)
     {
-        // ก๊อปเข้า memory ก่อน — MinIO stream ไม่ seek ได้ และ package จะเขียนกลับลง stream นี้ตอน dispose
-        var buffer = new MemoryStream();
-        templateStream.CopyTo(buffer);
-        buffer.Position = 0;
-
+        var buffer = CopyToMemory(templateStream);
         using (var doc = WordprocessingDocument.Open(buffer, true))
         {
-            foreach (var root in AllContentRoots(doc))
-            {
-                foreach (var tag in root.Descendants<Tag>().ToList())
-                {
-                    var key = tag.Val?.Value?.Trim();
-                    if (string.IsNullOrEmpty(key) || !values.TryGetValue(key, out var value))
-                        continue;
-                    ReplaceSdtContent(tag, value);
-                }
-            }
+            ReplaceSdtValues(doc, values);
 
             SetCustomProperty(doc, AddInMetadata.SavedByAddInPropertyName, AddInMetadata.AddInSignatureGuid);
             SetCustomProperty(doc, AddInMetadata.DocumentTrackingIdPropertyName, documentTrackingId.ToString());
         } // dispose เขียน package กลับลง buffer
 
-        buffer.Position = 0;
         return buffer.ToArray();
     }
 
+    public byte[] GenerateDraft(Stream templateStream, IReadOnlyDictionary<string, string> values, Guid templateId)
+    {
+        var buffer = CopyToMemory(templateStream);
+        using (var doc = WordprocessingDocument.Open(buffer, true))
+        {
+            ReplaceSdtValues(doc, values);
+
+            // stamp ตัวเดียว (FR-16) — ไฟล์ร่างต้องเป็น untracked ในสายตา add-in
+            SetCustomProperty(doc, AddInMetadata.TemplateIdPropertyName, templateId.ToString());
+        }
+
+        return buffer.ToArray();
+    }
+
+    /// <summary>ก๊อปเข้า memory ก่อน — MinIO stream ไม่ seek ได้ และ package จะเขียนกลับลง stream นี้ตอน dispose</summary>
+    private static MemoryStream CopyToMemory(Stream stream)
+    {
+        var buffer = new MemoryStream();
+        stream.CopyTo(buffer);
+        buffer.Position = 0;
+        return buffer;
+    }
+
+    /// <summary>ชื่อไฟล์ของเอกสาร/ไฟล์ร่างที่ generate จาก template: ชื่อ template + timestamp
+    /// — ตัดอักขระที่ filename ใช้ไม่ได้ออก (ใช้ร่วมทั้ง generate และ generate-draft)</summary>
+    public static string BuildGeneratedFileName(string templateName, DateTimeOffset now)
+    {
+        var invalid = Path.GetInvalidFileNameChars();
+        var clean = new string(templateName.Select(c => invalid.Contains(c) ? '_' : c).ToArray()).Trim();
+        if (clean.Length == 0)
+            clean = "document";
+        return $"{clean}_{now:yyyyMMdd-HHmmss}.docx";
+    }
+
+    /// <summary>แทนที่ค่าใน SDT ทุกตัวที่ tag ตรง key ใน values (ใช้ร่วมทั้ง Generate และ GenerateDraft)</summary>
+    private static void ReplaceSdtValues(WordprocessingDocument doc, IReadOnlyDictionary<string, string> values)
+    {
+        foreach (var root in AllContentRoots(doc))
+        {
+            foreach (var tag in root.Descendants<Tag>().ToList())
+            {
+                var key = tag.Val?.Value?.Trim();
+                if (string.IsNullOrEmpty(key) || !values.TryGetValue(key, out var value))
+                    continue;
+                ReplaceSdtContent(tag, value);
+            }
+        }
+    }
+
     /// <summary>แทนที่ข้อความใน SDT ที่ <b>run level</b> — เก็บ Run เดิมไว้ตัวแรก (formatting ตาม template)
     /// แล้วลบ Text ที่เหลือ ไม่ทับทั้ง paragraph (spec ส่วน 9 เพิ่มเติม v2)</summary>
     private static void ReplaceSdtContent(Tag tag, string value)

backend/WordVersioning.Api/Services/TemplateFieldValidation.cs

@@ -0,0 +1,38 @@
+using System.Globalization;
+using WordVersioning.Api.Models;
+
+namespace WordVersioning.Api.Services;
+
+/// <summary>FR-10/FR-16 — validate required + type ของค่าที่กรอก (ใช้ร่วมทั้ง generate และ generate-draft)
+/// field ที่ส่งเกินนิยาม ignore ตาม policy เดียวกับ FR-11</summary>
+public static class TemplateFieldValidation
+{
+    /// <summary>null = ผ่าน; ไม่ null = ข้อความ error สำหรับ BadRequest (รูปแบบเดียวกับที่เคยอยู่ใน Generate)</summary>
+    public static string? Validate(IEnumerable<TemplateField> fieldDefs, IReadOnlyDictionary<string, string?> values)
+    {
+        var missingRequired = fieldDefs
+            .Where(f => f.IsRequired && (!values.TryGetValue(f.Key, out var v) || string.IsNullOrWhiteSpace(v ?? string.Empty)))
+            .Select(f => f.Key)
+            .ToList();
+        if (missingRequired.Count > 0)
+            return $"กรอก required fields ให้ครบ: {string.Join(", ", missingRequired)}";
+
+        var typeErrors = new List<string>();
+        foreach (var def in fieldDefs)
+        {
+            if (!values.TryGetValue(def.Key, out var v) || string.IsNullOrWhiteSpace(v))
+                continue;
+            var valid = def.Type switch
+            {
+                "number" => decimal.TryParse(v, NumberStyles.Number, CultureInfo.InvariantCulture, out _),
+                "date" => DateTimeOffset.TryParse(v, CultureInfo.InvariantCulture, DateTimeStyles.None, out _),
+                _ => true,
+            };
+            if (!valid)
+                typeErrors.Add(def.Type == "number"
+                    ? $"`{def.Key}` ต้องเป็นตัวเลข"
+                    : $"`{def.Key}` ต้องเป็นวันที่ที่ parse ได้ (ISO-8601 เช่น 2026-08-19)");
+        }
+        return typeErrors.Count > 0 ? string.Join("; ", typeErrors) : null;
+    }
+}