task p-4.5

2026-06-29 16:07:03 +07:00
parent aa73b9aed2
commit a1cac84e2b
19 changed files with 4812 additions and 413 deletions
--- a/docs/implementation/pdf-audit-report.json
+++ b/docs/implementation/pdf-audit-report.json
@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-29T07:31:39.763Z",
+  "generatedAt": "2026-06-29T08:13:58.800Z",
  "overallStatus": "PASS",
  "quotationCode": "QT2606-1122",
  "expectedFixtureCode": "QT-H5-AUDIT",
@@ -8,54 +8,23 @@
    "version": "1.0",
    "versionId": "6c375f16-3f89-4987-88b0-c8ebe48aeb89",
    "fieldCount": 44,
-    "previousVersion": null,
-    "deletedFields": [],
-    "newFields": [
-      "Please_do_not",
-      "app1",
-      "app1_position",
-      "app2",
-      "app2_position",
-      "app3",
-      "app3_position",
-      "att_label",
-      "colon",
-      "colon copy",
-      "colon_att",
-      "colon_email",
-      "colon_fax",
-      "colon_project",
-      "colon_site",
-      "colon_tel",
-      "company1",
-      "company2",
-      "company_addr1",
-      "company_addr2",
-      "company_email",
-      "company_tax",
-      "company_tel",
-      "customer_addr",
-      "customer_att",
-      "customer_email",
-      "customer_name",
-      "customer_tel",
-      "data_topic",
-      "dear_sirs",
-      "email_label",
-      "line",
-      "project_label",
-      "project_name",
-      "quotation_code_data",
-      "quotation_code_lable",
-      "quotation_date_data",
-      "quotation_date_labe",
-      "quotation_price_data",
-      "site_label",
-      "site_location",
-      "tel_label",
-      "topic",
-      "yours_faithfuly"
+    "previousVersion": "2.0",
+    "deletedFields": [
+      "__section_role__customer",
+      "__section_role__product_items",
+      "__section_role__signature",
+      "__section_role__topics",
+      "items_table",
+      "product_items_currency_value",
+      "product_items_footer_note",
+      "product_items_line_168",
+      "product_items_line_35",
+      "product_items_subtitle",
+      "product_items_title",
+      "product_items_total_label",
+      "product_items_total_value"
    ],
+    "newFields": [],
    "duplicateFields": [],
    "unknownFields": [],
    "classifications": [
--- a/docs/implementation/pdf-audit-report.md
+++ b/docs/implementation/pdf-audit-report.md
@@ -1,10 +1,10 @@
 # PDF Audit Report

- Generated At: 2026-06-29T07:31:39.763Z
+- Generated At: 2026-06-29T08:13:58.800Z
 - Overall Status: PASS
 - Quotation Code: QT2606-1122
 - Template: ALLA Quotation Standard v1.0
- Previous Version: None
+- Previous Version: 2.0

 ## Metrics

--- a/docs/implementation/task-p.4.5-verification-report.md
+++ b/docs/implementation/task-p.4.5-verification-report.md
@@ -0,0 +1,147 @@
+# Task P.4.5 Verification Report
+
+## Scope
+
+This report verifies implementation for [task-p.4.5.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/plans/task-p.4.5.md).
+
+Confirmed goals:
+
+- create new Product Item PDFMe template versions without modifying legacy `*_fainal3.json`
+- insert Product Item page between customer page and topic/signature page
+- support explicit section markers and `items_table`
+- keep legacy template version `1.0` working unchanged
+
+---
+
+## Deliverables Verified
+
+New template files created:
+
+- [src/pdfme_template/ALLA_template_pdfme_product_v1.json](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/pdfme_template/ALLA_template_pdfme_product_v1.json)
+- [src/pdfme_template/ONVALLA_template_pdfme_product_v1.json](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/pdfme_template/ONVALLA_template_pdfme_product_v1.json)
+
+Legacy files preserved:
+
+- [src/pdfme_template/ALLA_template_pdfme_fainal3.json](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/pdfme_template/ALLA_template_pdfme_fainal3.json)
+- [src/pdfme_template/ONVALLA_template_pdfme_fainal3.json](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/pdfme_template/ONVALLA_template_pdfme_fainal3.json)
+
+Runtime and seed support updated in:
+
+- [src/features/crm/quotations/document/server/template-compatibility-adapter.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/template-compatibility-adapter.ts)
+- [src/features/crm/quotations/document/server/render-context.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/render-context.ts)
+- [src/features/crm/quotations/document/server/quotation-pdf-runtime.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/quotation-pdf-runtime.ts)
+- [scripts/reseed-pdf-template-version.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/scripts/reseed-pdf-template-version.ts)
+- [scripts/pdf-audit-utils.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/scripts/pdf-audit-utils.ts)
+
+---
+
+## Functional Verification
+
+### 1. Section marker support
+
+Verified runtime accepts both:
+
+- legacy `__page_role__*`
+- new `__section_role__*`
+
+This allows new template versions to use explicit page roles while preserving old template inference behavior.
+
+### 2. Product Item page placement
+
+Verified new template structure:
+
+- page 1 = customer
+- page 2 = product_items
+- page 3 = topics + signature
+
+Runtime no longer depends on fixed topic page index for the new template path.
+
+### 3. `items_table` runtime contract
+
+Verified Product Item section injects `items_table` into `templateInput` using Product Item Engine output, not raw ad hoc mapping.
+
+Verified row shape uses seven columns:
+
+1. Item
+2. Description
+3. Qty
+4. Unit
+5. Unit Price
+6. Discount
+7. Total
+
+### 4. Render policy behavior
+
+Verified `product_items` section is enabled only when resolved template pages actually contain a Product Item page marker. Legacy templates therefore remain valid without requiring a new page.
+
+---
+
+## Regression Verification
+
+Commands executed:
+
+```bash
+npm exec tsc --noEmit
+npm exec tsx --test src/features/crm/quotations/document/server/product-item-engine.test.ts
+npm exec tsx --test src/features/crm/quotations/document/server/quotation-pdf-runtime.test.ts
+node --experimental-strip-types scripts/reseed-pdf-template-version.ts --template-variant=product-v1 --activate
+npm run audit:pdf
+node --experimental-strip-types scripts/reseed-pdf-template-version.ts
+npm run audit:pdf
+```
+
+Results:
+
+- `npm exec tsc --noEmit` = PASS
+- `product-item-engine.test.ts` = PASS
+- `quotation-pdf-runtime.test.ts` = PASS
+- product template variant reseed and activation = PASS
+- PDF audit with product template active = PASS
+- legacy template restore = PASS
+- PDF audit with legacy template restored = PASS
+
+---
+
+## Audit Outcome
+
+Verified audit tooling now understands Product Item template versions:
+
+- product section marker validation
+- `items_table` presence
+- `items_table` row shape
+- version integrity against actual `file_path`
+- placeholder integrity excluding explicit section marker fields
+
+This keeps both template families auditable:
+
+- legacy `1.0`
+- product template `product-v1` / `2.0` path
+
+---
+
+## Database Activation Status
+
+Important final state after verification:
+
+- Product template version was activated temporarily for audit
+- database active template version was restored back to legacy `1.0`
+
+This means verification completed without leaving production-like runtime on the new template version by default.
+
+---
+
+## Acceptance Summary
+
+Acceptance criteria status:
+
+- new product template JSON files created = PASS
+- existing production template JSON files unchanged = PASS
+- Product Item page inserted between customer and topic/signature pages = PASS
+- `items_table` uses official PDFMe table schema = PASS
+- repeated headers and page breaks supported by PDFMe table path = PASS
+- new template version can be seeded/reseeded = PASS
+- new template version can be activated = PASS
+- legacy template version still passes audit = PASS
+- product template version passes audit = PASS
+- runtime audit remains PASS = PASS
+- no approved artifact regeneration required = PASS