rmutr/docs/superpowers/specs/2026-08-05-income-budget-report-native-design.md

แทนที่ SyncFusion Spreadsheet ในรายงานงบประมาณเงินรายได้ ด้วยหน้าเว็บ native

บริบท

หน้า /app/income-budget-report-income1/add (และเมนูพี่น้องอีก 6 เมนู) ใช้ SyncFusion Spreadsheet (@syncfusion/ej2-angular-spreadsheet) เปิดไฟล์ .xlsx ที่ backend generate มาให้ ผู้ใช้แก้ไขในสเปรดชีตที่มองเห็นได้ทุกเซลล์อิสระ แล้ว "บันทึก" กลับเป็นไฟล์ .xlsx ใหม่เก็บไว้เป็นหลักฐาน (revenue_draft_committee_file)

ปัญหาที่ต้องแก้:

1. UX สเปรดชีตไม่เหมาะกับผู้ใช้ที่ไม่คุ้น Excel, formula/สูตรผูกกับ "สีเซลล์" ที่ซ่อนอยู่ในไฟล์ ตรวจสอบ/แก้ไขยาก
2. ไม่มีการล็อกข้อมูล — ตำแหน่ง/จำนวนอัตรา/รายการครุภัณฑ์ที่ควรมาจากฟอร์มต้นทาง (ร.2/ร.4/ร.5/ร.6) กลับแก้ไขได้อิสระในหน้านี้เหมือนตัวเลขเงิน เพราะสเปรดชีตไม่แยกเซลล์ locked/unlocked

7 เมนูที่ใช้ component เดียวกัน (income-budget-report.component.ts, แยกพฤติกรรมด้วย route data type) แท้จริงแบ่งเป็น 3 กลุ่มเอกสารที่โครงสร้างต่างกัน (ยืนยันด้วยการดาวน์โหลดไฟล์จริงจาก production มาตรวจ ไม่ใช่การเดา):

กลุ่ม	type_id	ชื่อเมนู	โครงสร้างไฟล์จริง
A — ร่างเงินรายได้	1→2→3	ร่างเงินรายได้ เพื่อประชุม คกก.ร่างเงินรายได้ / คกก.การเงิน / สภา	1 ชีท ("Page1"), tree เดียว รายการบุคลากร→งบบุคลากร/งบดำเนินงาน→แผนงาน→ผลผลิต→งบเงินอุดหนุน/งบลงทุน/งบรายจ่ายอื่นๆ ยืนยันไฟล์จริงทั้ง 3 type ตรงกัน
B — จัดสรร/ปรับแผนเงินรายได้	4→5→6	จัดสรรงบประมาณเงินรายได้ / ปรับแผนเงินรายได้ (ประมาณการรายจ่าย) / ปรับแผนเงินรายได้	workbook 5 ชีท แยกตาม "ผลผลิต" + สรุป มีช่องกรอกอิสระ ("ตำแหน่ง......(ระบุ)") แต่ ใช้ logic คำนวณผลรวมแบบเดียวกับกลุ่ม A (สีเซลล์ + สูตร SUM รูปแบบเดียวกัน) ยืนยันไฟล์จริง type 4,5 (type 6 ไม่มีข้อมูลจริงในระบบ อนุมานจาก chain ต่อจาก 5)
C — วิเคราะห์ค่าวัสดุการศึกษา	10	ตารางและรายงานคำนวณค่าวัสดุการศึกษา	matrix แยกตามพื้นที่วิทยาเขต ไม่ใช่ tree เลย

Root cause ของปัญหาที่ 2: ตำแหน่ง/รายการที่ควรมาจากฟอร์มต้นทางจริง ๆ ก็ดึงมาจากต้นทางอยู่แล้วในทางเทคนิค —

• ร.2 (คำชี้แจงงบบุคลากร) เก็บใน personnel_statement + personnel_statement_detail/_2 (rmutr-api/Modules/ReportSalary/Databases/Models/) ดึงผ่าน GET /api/report/personnel/hr/budget_expenditure_report_from_revenue_v3/{view} (Personnel.cs:2195)
• ร.4 (งบครุภัณฑ์) = invest_asset_request_information, ร.5 (งบที่ดิน/สิ่งก่อสร้าง) = invest_construct_request_information, ร.6 (เงินอุดหนุน) = request_budget_income — ทั้งสามดึงรวมกันแล้วผ่าน GET /api/budget_progress/budget_progress/summary_expense/{budget_year_uid}/{faculty_uid} (BudgetProgress.cs:409) ซึ่งมี tree renderer ต้นแบบอยู่แล้วที่ manage-budget-request-expense-list.component.html

แต่เพราะ SyncFusion เปิดให้แก้ทุกเซลล์อิสระ ข้อมูลที่ดึงมาจึง ไม่ถูกล็อก อีกต่อไปหลังโหลดเข้าสเปรดชีต — นี่คือรากของปัญหา ไม่ใช่การขาดต้นทางข้อมูล

ขอบเขต

• แทนที่ SyncFusion Spreadsheet ด้วย native Angular tree component สำหรับ กลุ่ม A และ B (ใช้ "เครื่องยนต์" เดียวกัน — ดูเหตุผลในหัวข้อสถาปัตยกรรม)
• กลุ่ม C (type 10) แยก component matrix ต่างหาก ใช้ style/token ชุดเดียวกันเพื่อความสม่ำเสมอ แต่ไม่ใช้ tree schema/engine เดียวกับ A/B
• เปลี่ยนการเก็บข้อมูลจาก "ไฟล์ .xlsx เป็นหลักฐาน" → "ข้อมูลโครงสร้างใน DB เป็นหลัก, .xlsx generate ตอนดาวน์โหลดเท่านั้น"
• Routing เดิมทั้ง 7 เมนูไม่เปลี่ยน (income-budget-report-income1/2/3, allocate-income-budget, income-expense-estimates(-02), educational-materials) — เปลี่ยนแค่เนื้อในของ component ที่ render
• ไม่แตะ ฟอร์มต้นทาง ร.2/ร.4/ร.5/ร.6 เอง (estimated-income-form, statement-invest-asset, statement-invest-construct, statement-request) — หน้านี้อ่านข้อมูลจากตารางเหล่านั้นเท่านั้น ไม่เขียนกลับ

สถาปัตยกรรม

ต้นทางข้อมูล (อ่านอย่างเดียว)              หน้ารายงานใหม่ (native web)
─────────────────────────                ──────────────────────────
ร.2 personnel_statement           ──┐
ร.4 invest_asset_request_info     ──┤     Backend: endpoint รวบรวมใหม่
ร.5 invest_construct_request_info ──┼───▶  (ต่อยอด summary_expense เดิม
ร.6 request_budget_income         ──┘      + เพิ่ม ร.2)
                                                   │
                                                   ▼
                                         income_budget_report (ใหม่)
                                         + income_budget_report_line
                                                   │
                                                   ▼
                                         Angular: tree component ใช้ร่วม
                                         กลุ่ม A (1 ต้นไม้ใหญ่) + กลุ่ม B (5 แท็บ)

หน้ารายงานนี้เปลี่ยนบทบาทจาก "ฟอร์มกรอกข้อมูล" เป็น "หน้ารวบรวม+ทบทวนตัวเลข" — ตำแหน่ง/รายการครุภัณฑ์/โครงการ แสดง read-only จากฟอร์มต้นทาง ส่วนที่แก้ไขได้จริงคือ "จำนวนเงินที่คณะกรรมการปรับ" ต่อรายการ เก็บแยกเป็น snapshot ของตัวเอง ไม่เขียนทับข้อมูลต้นทาง

โครงสร้าง tree (รายการบุคลากร→งบบุคลากร→...) เป็น config คงที่ต่อ type_id (ไฟล์ TypeScript ฝั่ง frontend + ค่าคู่กันฝั่ง backend สำหรับคำนวณตอน export) ไม่ใช่ตารางใน DB — เพราะเป็นแบบฟอร์มราชการที่แทบไม่เปลี่ยนโครงสร้าง ถ้าในอนาคตต้องการให้แก้ schema ผ่าน UI ได้ ค่อยย้ายเป็น DB-driven ทีหลัง (YAGNI)

Data Model

income_budget_report                          income_budget_report_line
──────────────────────                        ──────────────────────────
income_budget_report_uid (PK)                 income_budget_report_line_uid (PK)
type_id (1-6, 10)                             income_budget_report_uid (FK)
budget_year_uid                               node_key  เช่น "pb-temp-old", "out1-invest-equip"
faculty_uid, budget_location_uid              source_type: personnel_detail | personnel_detail_2 |
sector_name_th                                             invest_asset | invest_construct |
parent_uid  ← report รอบก่อนหน้า (1→2→3, 4→5→6)              request_budget_income | manual
status_id                                     source_uid  (uid ต้นทาง, null = รายการพิมพ์เอง)
+ audit fields มาตรฐาน (base_table)            label_th (snapshot ชื่อรายการตอนดึงมา)
                                               amount        ← แก้ไขได้ที่นี่เท่านั้น
                                               original_amount (ค่าตอนดึงมา, ไว้เทียบ/audit)
                                               sequence_no

การสร้าง/ต่อรอบ:

• รอบแรก (type 1, 4): backend query ร.2/4/5/6 ตาม faculty_uid + budget_year_uid (ต่อยอด summary_expense + budget_expenditure_report_from_revenue_v3) → generate income_budget_report_line ให้อัตโนมัติ, amount = original_amount = ค่าจากต้นทาง, จับคู่ node_key ตาม config ของ type นั้น
• ต่อรอบ (type 2,3 / 5,6): clone header+lines จากรอบก่อนหน้าตรงๆ (ตามที่ยืนยัน) — ไม่ query ต้นทางซ้ำ เพราะรอบถัดไปคือ "แก้ต่อจากมติที่ประชุมรอบก่อน" ไม่ใช่ดึงข้อมูลสดใหม่ ถ้าต้นทาง (ร.2/4/5/6) ถูกแก้ไขหลังจาก snapshot ไปแล้ว จะไม่ไหลย้อนกลับมาอัตโนมัติ — เป็นการตัดสินใจโดยตั้งใจเพื่อความนิ่งของมติที่ประชุมแต่ละรอบ ต้องมี UI แจ้งผู้ใช้ให้ชัดเจน
• รายการที่ source_uid = null (เช่น "อัตราใหม่" ที่ยังไม่มีใน ร.2 จริง, หรือช่องกรอกอิสระ "ระบุ..." ในกลุ่ม B) → แก้ไขได้ทั้งชื่อและจำนวนเงิน
• รายการที่มี source_uid → ชื่อ/ตำแหน่ง/จำนวนอัตรา ล็อกเป็น read-only แก้ได้แค่ amount

กลุ่ม C (type 10) โครงสร้างเป็น matrix ไม่ใช่ tree — ใช้ตารางแยก material_cost_report เรียบง่ายกว่า ไม่ผูกกับ schema ข้างต้น (รายละเอียดโครงสร้างกลุ่ม C จะออกแบบในรอบถัดไปเมื่อเริ่มลงมือ เพราะเป็น sub-project ที่ independent จาก A/B)

Backend API (เพิ่มใหม่)

ต่อยอด pattern BaseUidController<T,V> มาตรฐานของระบบ:

GET    /api/setting/income_budget_report/{uid}                  → โหลด report + lines (BaseUidController มาตรฐาน)
POST   /api/setting/income_budget_report/create_draft           → สร้างรอบแรก (type 1,4): query ร.2/4/5/6
                                                                    ตาม faculty+ปี → generate lines
POST   /api/setting/income_budget_report/{uid}/clone_next_round → สร้างรอบถัดไป (type 2,3,5,6): clone
                                                                    header+lines จาก uid เดิม, type_id+1
PUT    /api/setting/income_budget_report/lines                  → บันทึกจำนวนเงินที่แก้ (batch update amount)
GET    /api/setting/income_budget_report/{uid}/export/xlsx      → generate .xlsx ตอนดาวน์โหลด (EPPlus/
                                                                    ClosedXML จาก tree config + ข้อมูลจริงใน DB)

IncomeBudgetReportRollupService (C# ใหม่) เดินตาม tree config เดียวกับฝั่ง frontend สรุปยอดแต่ละ node จาก children — ใช้ทั้งตอน export Excel และตอนส่งข้อมูลกลับให้ Angular แสดง แทนที่ logic เดิมที่ไล่หาสีเซลล์ (Personnel.cs:6089-6363, endpoint /report/personnel/calcurate) ทั้งหมด

Frontend Component Structure

shared/components/budget-report-tree/          generic recursive tree (ต่อยอดจาก mockup ที่อนุมัติแล้ว)
  budget-report-tree-node.component.ts            รับ @Input node config + data, render เอง + เรียกตัวเองซ้ำ
                                                    คำนวณ sum ฝั่ง client แบบ real-time เหมือน mockup

feature/income/report-config/                  config คงที่ต่อ type (TypeScript const)
  income-report-type1.config.ts                   tree schema กลุ่ม A
  income-report-type4.config.ts                   tree schema กลุ่ม B (5 sub-tree ตามผลผลิต)

feature/income/draft/income-budget-report1/    แทนที่เนื้อในของ component เดิมทั้งไฟล์
  income-budget-report.component.ts                โหลด config ตาม type_id (route data), โหลด/สร้าง/clone
                                                    report, bind เข้า budget-report-tree, ปุ่มบันทึก/ส่งออก
                                                    (กลุ่ม B ครอบด้วย mat-tab-group 5 แท็บตามผลผลิต)

feature/income/material-cost-report/           กลุ่ม C แยกต่างหาก (matrix component ใหม่ทั้งหมด)

Routing เดิมไม่เปลี่ยน — component เดิมยังถูกเรียกจากทั้ง 7 เมนูเหมือนเดิม แค่เนื้อในเปลี่ยนจาก SyncFusion เป็น tree component (กลุ่ม A/B) หรือ matrix component ใหม่ (กลุ่ม C, educational-materials type=10)

Data Flow

1. เปิดหน้า /add → เช็คว่ามี report ของ หน่วยงาน+ปี+type นี้อยู่แล้วหรือยัง ถ้ายัง → กด "สร้างรายงาน" → create_draft
2. แก้จำนวนเงินที่ปรับได้ → คำนวณยอดรวมสดฝั่ง client (เหมือน mockup) → กด "บันทึก" → PUT lines แบบ batch
3. ประชุมรอบนี้เสร็จ → กด "ส่งต่อรอบถัดไป" → clone_next_round → เปิดหน้า type ถัดไปพร้อมข้อมูล clone มาแล้ว
4. กด "ส่งออก Excel" ได้ทุกจุด → generate ไฟล์ตามข้อมูล ณ ขณะนั้น

Error Handling

• ยังไม่มีข้อมูลจาก ร.2/4/5/6 เลย → โชว์ tree เปล่าพร้อมข้อความ "ยังไม่มีข้อมูลจาก ร.2 กรุณากรอกฟอร์มก่อน" ลิงก์ไปหน้านั้น
• กัน "ส่งต่อรอบถัดไป" ซ้ำซ้อน — เช็คว่ามี report ที่ parent_uid ชี้มาที่ตัวปัจจุบันอยู่แล้วหรือยังก่อนอนุญาตให้ clone อีกครั้ง
• แก้ ร.2/4/5/6 ต้นทางหลัง snapshot ไปแล้ว ไม่ไหลย้อนกลับอัตโนมัติ (ดูหัวข้อ Data Model) — ต้องมี UI แจ้งชัดเจน

Testing

ระบบนี้ไม่มี automated test (ตรวจสอบด้วยมือทั้งระบบตาม convention เดิม) — verify โดยเทียบยอดรวมกับไฟล์ Excel จริงที่ดาวน์โหลดมาตรวจสอบแล้วระหว่างขั้นตอนออกแบบ (มี type 1,2,3,4,5,10 อยู่ในมือ) ให้ตัวเลขตรงกันทุก node ก่อนถือว่าใช้ได้

Rollout

ระบบ production ที่ใช้งานจริงกับการประชุมจริงของมหาวิทยาลัย — deploy เป็นฟีเจอร์คู่ขนาน ไม่ทับของเดิมทันที: ทดสอบกับ 1 หน่วยงานจริงก่อน 1 รอบประชุม เทียบผลกับของเดิมให้ตรงกัน ก่อนค่อยเปิดใช้แทนของเดิมทั้งระบบ

จุดที่ยังไม่ชัด / ต้องตรวจเพิ่มตอน implementation

• ร.7: หาไม่เจอในระบบเลยทั้ง frontend/backend ไม่ทราบว่าเคยมีหรือถูกยุบรวมกับฟอร์มอื่น — ไม่กระทบ scope นี้เพราะไม่มีข้อมูลอ้างอิงในไฟล์ Excel เดิมที่ตรวจแล้ว
• budget_progress_id == 2 ใน GetSummaryExpense (BudgetProgress.cs:419) ความหมายจริงยังไม่ยืนยัน (draft/submitted?) กระทบว่าจะดึงข้อมูลสถานะไหนมาแสดง
• request_budget_income ใน GetSummaryExpense ไม่ได้ filter type_id (ต่างจาก Request.cs:651 ที่ filter type_id == 1) — อาจดึงมาทั้ง "งบเงินอุดหนุน" และ "งบรายจ่ายอื่นๆ" ปนกัน ต้อง filter เพิ่มถ้าต้องการเฉพาะ ร.6
• โครงสร้าง tree schema ของ type 2,3,5,6 (chain ต่อจาก 1,4) ยังไม่ได้ตรวจไฟล์จริงเทียบเท่า type 1,4 — type 3 ยืนยันแล้วว่าตรงกับ type 1/2, type 5 ยืนยันแล้วว่าตรงกับ type 4, type 6 ไม่มีข้อมูลจริงในระบบให้ตรวจ อนุมานจาก chain เท่านั้น ต้องระวังตอน implement
• กลุ่ม C (type 10) ยังไม่ได้ออกแบบ data model โดยละเอียด (matrix by campus) — เป็น sub-project แยกที่จะ spec เพิ่มเมื่อเริ่มลงมือ