eCourt-Doc-Edit/docs/plans/fr16-draft-generation-plan.md

# แผนงาน: ไฟล์ร่าง (draft) — generate docx จาก template โดยยังไม่สร้าง version (FR-16 / spec v8 / Phase 12)

> สถานะ: **implement แล้ว (2026-09-10)** — ติดตามผลที่ `officejs-implementation-plan.md` Phase 12 และ `acceptance-review.md` AC-19 (ค้าง manual บน Word จริง)
> แผนนี้เก็บไว้เป็นหลักฐานการตัดสินใจของ grill session — รายละเอียด decision เพิ่มที่ `docs/adr/0002-draft-stateless.md`

## Context

ปัจจุบันการสร้างเอกสารจาก template ผ่านเว็บ (`POST /api/documents/generate`, FR-10) สร้าง `Document` + field values + **v0 ฉบับตั้งต้น** ทันที แม้ผู้ใช้จะยังไม่เคยเปิดไฟล์ใน Word

Flow ใหม่: ฟอร์มเว็บกรอกค่า → กด "สร้างไฟล์ร่าง" → API คืน docx → เปิดใน Word → add-in เห็น untracked → กด Start Versioning → เกิด `Document` (ผูก template) + **v1** + field sync

**การทบทวน version numbering (ไม่ต้องแก้โค้ด):** `UploadVersion` คำนวณ `(max ?? 0) + 1` ที่ `backend/WordVersioning.Api/Controllers/DocumentsController.cs:140-144` — Document ใหม่ไม่มี version → `max = null` → **v1** อัตโนมัติ มี test เดิมยืนยันแล้ว · เพิ่ม test ยืนยันผ่าน TemplateLinkingTests (ด้านล่าง)

## Decisions (จาก grill session — final)

| # | หัวข้อ | การตัดสินใจ |
|---|---|---|
| 1 | การเก็บ draft | **Stateless** — POST คืน docx stream ตรงๆ ไม่สร้าง Document/version ไม่แตะ MinIO · เว็บ browser-download · ไม่มีปุ่ม "เปิดใน Word" (ms-word:ofe ต้องการ URL ซึ่ง draft ไม่มี) |
| 2 | Stamping | Stamp custom property **`TemplateId` เท่านั้น** — ไม่มี SavedByAddIn/DocumentTrackingId (กันสถานะ "tracking + history 404" ซึ่ง add-in จัดการไม่ได้ในปัจจุบัน) |
| 3 | กลไกผูก template ตอน Start Versioning | ขยาย `POST /api/documents/{documentId}/versions` เพิ่ม form field ทางเลือก `templateId` — ใช้เฉพาะตอน auto-create Document; document มีอยู่แล้ว → เฉย (validate ทุกครั้งที่ส่งมา) |
| 4 | Validation | upload: ไม่ใช่ GUID → 400 · ไม่พบ template → 400 · **deactivated → ผูกได้** · draft endpoint เอง: unknown → 404, deactivated → 400 ตามนโยบาย FR-10 (deactivated สร้างไฟล์ใหม่ไม่ได้ แต่ draft เก่าที่สร้างตอน active ผูกต่อได้) |
| 5 | Web UI | **คง flow v0** + เพิ่มปุ่ม "สร้างไฟล์ร่าง" บนฟอร์มเดิม · re-generate (FR-12) ใช้ v0 flow เดิม |
| 6 | ศัพท์ | **"ไฟล์ร่าง (draft)"** ทั้งระบบ (UI/spec/CONTEXT.md) |

## Endpoint design

**`POST /api/templates/{templateId:guid}/generate-draft`** (ใน TemplatesController — draft เป็น stateless function ของ template; controller นี้มี DI ครบและมี precedent sub-resource `{id}/documents` แล้ว)

- Request: `GenerateDraftRequest { [Required] JsonElement Values }` (ใน `Models/TemplateDtos.cs`) — ไม่มี `message` (ไม่มี version จึงไม่มี commit message)
- Response: **200** `FileContentResult` — `File(bytes, docxContentType, BuildGeneratedFileName(template.Name, now))` (ไม่ใช่ 201 — ไม่มีอะไรถูกสร้าง)
- Status: unknown template → 404 · `!IsActive` → 400 · values ผิด format/required/type → 400 (ข้อความเดิมของ Generate) · template file หายใน MinIO/corrupt → 502

## Implementation

### 1. Backend

1. `Services/AddInMetadata.cs` — เพิ่ม `TemplateIdPropertyName = "TemplateId"`
2. `Services/DocxGenerationService.cs` — แยก SDT-replace loop ของ `Generate` เป็น `private static ReplaceSdtValues(...)` ใช้ร่วม · เพิ่ม `byte[] GenerateDraft(Stream templateStream, IReadOnlyDictionary<string,string> values, Guid templateId)` (replace เหมือนเดิม + stamp **เฉพาะ** `TemplateId`) · ย้าย `BuildGeneratedFileName` จาก DocumentsController มาเป็น `public static` ที่นี่
3. `Services/TemplateFieldValidation.cs` (ไฟล์ใหม่) — ยก required/type validation block จาก `Generate` (~lines 260-285) มาเป็น `static string? Validate(IEnumerable<TemplateField>, IReadOnlyDictionary<string,string?>)` (ข้อความ error ไทยต้องเหมือนเดิมเป๊ะ — `GenerateTests` assert ไว้)
4. `Controllers/DocumentsController.cs`:
   - `Generate` เปลี่ยนไปใช้ validator + filename ที่แยกออกมาแล้ว
   - `UploadVersion`: early validation `request.TemplateId` (ไม่ใช่ GUID → 400) → หลัง doc lookup ถ้ามี templateId ให้ `db.Templates.AnyAsync` (ไม่พบ → 400; deactivated ผ่าน) → ใส่ `TemplateId = templateIdToLink` ใน auto-create initializer (~lines 105-111) **ก่อน** branch `doc.TemplateId is not null` (~line 120) ไม่งั้น field sync จะหลุดเป็น raw-map path
5. `Models/VersionDtos.cs` — `UploadVersionRequest` เพิ่ม `string? TemplateId`
6. `Controllers/TemplatesController.cs` — action ใหม่ `GenerateDraft(Guid id, [FromBody] GenerateDraftRequest, CancellationToken)`: load template (404/400) → load field defs → `FieldMapJson.TryNormalize` → `TemplateFieldValidation.Validate` → load template stream (502) → `GenerateDraft(...)` → log → `File(...)`
7. `Program.cs` — CORS เพิ่ม `.WithExposedHeaders("Content-Disposition")` (**จำเป็น** — draft download อ่านชื่อไฟล์ไทยจาก header นี้ผ่าน fetch; ปัจจุบันไม่ได้ expose ชื่อจะหายเงียบๆ — integration tests จับไม่ได้เพราะ same-origin)

### 2. Add-in

8. `addin/src/services/metadataService.ts` — `TEMPLATE_ID_PROPERTY` + `templateId?: string` ใน `TrackedDocumentProperties` + อ่านเป็น property ที่ 5 ใน `readTrackedProperties()` (Word.run เดิม)
9. `addin/src/services/versioningService.ts` — `uploadVersion(..., pdf?, templateId?)` (trailing param, caller เดิมไม่กระทบ) append form field เมื่อมีค่า
10. `addin/src/services/versionFlow.ts` — `startVersioning(message?, templateId?, onProgress?)` (แทรกก่อน callback — TS จะจับ call site เก่าทั้งหมดให้แก้) · `saveAndVersion` **ไม่ส่ง** templateId
11. `addin/src/taskpane/components/App.tsx` — state `documentTemplateId` · **restructure `detect()`** เป็น `readTrackedProperties()` ครั้งเดียวแล้ว derive tracked เอง (ถ้าคงเรียก `isTrackedDocument()` ก่อน ไฟล์ร่าง untracked จะไม่ได้อ่าน TemplateId เลย) · เคลียร์ state ตอน sign-out/detect ใหม่ · untracked phase แสดง hint เมื่อเป็นไฟล์ร่าง: "ไฟล์นี้เป็นไฟล์ร่างจาก template — กดเริ่มติดตามแล้วระบบจะผูกกับ template ต้นทางและ sync ค่า fields ให้อัตโนมัติ" · `handleStartVersioning` ส่ง `documentTemplateId ?? undefined`

### 3. Web

12. `web/app/composables/useApi.ts` — `downloadFile(path, fallbackName, init: RequestInit = {})` ส่ง init ต่อให้ `request` (รองรับ POST+JSON→blob; ปัจจุบัน GET-only และไม่มี caller — non-breaking)
13. `web/app/pages/documents/create/[templateId].vue` — state `draftSubmitting`/`draftNotice` · `submitDraft()`: validate ด้วย `validateFieldValues` เดิม → `downloadFile('/api/templates/{id}/generate-draft', fallback, { method:'POST', body: JSON.stringify({ values }) })` → notice แนะนำเปิดใน Word แล้วกด Start Versioning · **ฟอร์มอยู่ต่อ** (ไม่มี result card, ไม่มีปุ่มเปิดใน Word) · ปุ่มรอง "สร้างไฟล์ร่าง" (`type="button"`, disabled gating เดียวกับปุ่มหลักรวม `!detail.isActive`) · helper text ใต้ช่องคำอธิบาย "(ใช้กับการสร้างเอกสาร version 0 เท่านั้น — ไฟล์ร่างไม่มี version)" · `resetForm()` เคลียร์ `draftNotice`

### 4. Docs (repo rule: spec ก่อน แล้ว sync plan)

14. `specs/spec-officejs.md` — v8 header note · `### FR-16: ไฟล์ร่าง (draft) — สร้าง .docx จาก template โดยไม่สร้าง Document (เพิ่มเติม v8)` · section 8 metadata table เพิ่มแถว `TemplateId` · AC-19 · section เพิ่มเติม v8
15. `docs/plans/officejs-implementation-plan.md` — append `## Phase 12: ไฟล์ร่าง (draft) — FR-16 (เพิ่มทีหลัง, v8)` ท้ายไฟล์ (รูปแบบเดียวกับ Phase 11: ตาราง mapping + checklist + DoD)
16. `CONTEXT.md` — glossary เพิ่ม: `- **ไฟล์ร่าง (draft)**: ไฟล์ .docx ที่สร้างจาก template แบบ stateless — ยังไม่มี Document/version ในระบบ; ระบุ template ต้นทางผ่าน custom property TemplateId และเริ่ม track จริงตอนกด Start Versioning ใน Word (version 1)`
17. `docs/adr/0002-draft-stateless.md` (ไฟล์ใหม่ — format ตาม ADR 0001): Decision (stateless endpoint, stamp TemplateId ตัวเดียว, ผูก template ทีหลังผ่าน form field) + Alternatives rejected (สร้าง Document สถานะร่าง + lifecycle/cleanup / stamp tracked props เต็มชุด = สถานะ "tracking + 404" พัง / ปุ่ม "เปิดใน Word" สำหรับ draft) + Consequences (draft หาย = ไม่มีของค้างในระบบ, v1 ไม่มี v0, field sync เริ่ม v1, ต้อง expose Content-Disposition)
18. `docs/acceptance-review.md` — แถว AC-19 · `CLAUDE.md` — sync สถานะ (FR-1–16, AC 1–19, Phase 0–12) + ย่อหน้าสถาปัตยกรรมสั้นๆ หลัง section FR-15

## Tests

**Backend (integration — Testcontainers, `[Collection(IntegrationTestCollection.Name)]`):**
- `DraftTests.cs` (ใหม่): happy path 200 + ค่า SDT ครบ (ใช้ `TestDocx.ReadSdtText`) + `ReadCustomProperty("TemplateId")` ตรง + `SavedByAddIn`/`DocumentTrackingId` เป็น null + **DB ไม่เกิด Document/version ใดๆ** · missing-required 400 · wrong-type 400 · unknown template 404 · deactivated 400 · extra keys ignored
- `TemplateLinkingTests.cs` (ใหม่): upload ใหม่ + templateId → 201 **VersionNumber=1**, `doc.TemplateId` ชัด, `AddInSignature=""`, `DocumentFieldValue` ครบ (SourceVersionId/UpdatedByUserId ถูก), snapshot non-null · upload ครั้งสอง (ไม่ส่ง) → v2 · ไม่ใช่ GUID → 400 · unknown GUID → 400 · deactivated → ผูกได้ · document เดิม + templateId → เฉย (TemplateId คงเดิม) · document เดิม + templateId เสีย → 400
- `TestDtos.cs` — `VersionForm` เพิ่ม optional `templateId` ต่อท้าย (caller เดิมไม่กระทบ) · `AuthTests.cs` — เพิ่ม `[InlineData("POST", "api/templates/{0}/generate-draft")]`

**Add-in (jest):** metadataService อ่าน templateId ได้ (ปรับ expectation `toEqual` ของ `readTrackedProperties` เดิม) · versionFlow ส่ง templateId เฉพาะ startVersioning ไม่ใช่ saveAndVersion · versioningService append form field

**Web (vitest):** `web/test/useApi.spec.ts` (ใหม่ — pattern ตาม `useVersionOpen.spec.ts`): POST init ส่งถึง fetch + Bearer · 401 retry ครั้งเดียว · ชื่อไฟล์ `filename*` UTF-8 ไทย ไปอยู่ที่ anchor download · !ok → ApiError พร้อมข้อความจาก backend

## Verification (DoD)

```bash
cd backend && dotnet test                    # เขียวทั้งชุด (รวม suite เดิมที่ไม่ถูกแตะ)
cd addin && npm test
cd web && npm test && npm run build
```

Manual บน Word for Mac: สร้างไฟล์ร่างจากเว็บ → ได้ .docx ชื่อไทยถูกต้อง → เปิดใน Word → task pane แสดง untracked + hint ไฟล์ร่าง → กด Start Versioning → ได้ v1 + หน้า document detail บนเว็บแสดง template และค่า fields · Save & Version ถัดไป → v2

## Risks

- **Content-Disposition ไม่ถูก CORS-expose** — จับไม่ได้ด้วย integration tests (same-origin) ครอบด้วย useApi.spec + manual check
- ลำดับแทรกใน UploadVersion สำคัญ (TemplateId ต้อง set ก่อน field-sync branch) — TemplateLinkingTests คุมไว้
- `startVersioning` เปลี่ยน positional signature — TS จับ call site ทั้งหมด แก้ให้ครบใน commit เดียวกัน
- ไม่มี DB migration ใดๆ (ไม่แตะ schema — `UploadVersionRequest.TemplateId` เป็น form field, คอลัมน์ `Document.TemplateId` มีอยู่แล้ว)