feat: 년 판매현황 엑셀 최상단에 지역/범위·단위·출력일 제목 블록 추가

- export_excel_2003_xml 에 헤더 위 제목행(topRows) 옵션 추가(하위호환)
- 년판매 export: '시도 구군 / 범위', '(단위 : 매/원)', '연도 판매현황 · 대행소', '출력일' 표기

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

app/Controllers/Admin/SalesReport.php

@@ -1284,6 +1284,30 @@ class SalesReport extends BaseController
 
         if ($export) {
             $headers = array_merge(['품목', '구분'], array_map(static fn (array $c): string => (string) ($c['label'] ?? ''), $built['colSpec']));
+            $colCount = count($headers);
+
+            // 최상단 제목 블록: (지역/범위) ……… (단위 : 매/원) / (제목) ……… 출력일
+            $region = trim(
+                (string) ($lgRow->lg_sido ?? '') . ' ' . (string) ($lgRow->lg_gugun ?? '')
+            );
+            if ($region === '') {
+                $region = $lgName;
+            }
+            $makeTopRow = static function (string $left, string $right) use ($colCount): array {
+                $row = array_fill(0, max($colCount, 1), '');
+                $row[0] = $left;
+                if ($right !== '') {
+                    $row[max($colCount - 1, 0)] = $right;
+                }
+
+                return $row;
+            };
+            $topRows = [
+                $makeTopRow($region . ' / ' . $gugunLabel, '(단위 : 매/원)'),
+                $makeTopRow($year . '년 판매현황 · 대행소: ' . $agencyLabel, '출력일: ' . date('Y-m-d')),
+                array_fill(0, max($colCount, 1), ''), // 구분용 빈 줄
+            ];
+
             $exportRows = [];
             foreach ($built['itemBlocks'] as $block) {
                 foreach ($block['lines'] as $li) {
@@ -1306,7 +1330,8 @@ class SalesReport extends BaseController
                 '년판매현황_' . $year . '_' . $exportStamp,
                 $year . '년판매',
                 $headers,
-                $exportRows
+                $exportRows,
+                $topRows
             );
         }
 

app/Helpers/export_helper.php

@@ -76,8 +76,9 @@ if (! function_exists('export_excel_2003_xml')) {
      * @param string   $sheetName  시트 이름(Excel 제한: 길이·일부 문자)
      * @param string[] $headers    컬럼 헤더
      * @param array    $rows       데이터 행(각 행은 배열, 값은 문자열로 출력)
+     * @param array    $topRows    헤더 위에 추가할 제목/부제 행(각 행은 배열). 비우면 없음.
      */
-    function export_excel_2003_xml(string $filename, string $sheetName, array $headers, array $rows): void
+    function export_excel_2003_xml(string $filename, string $sheetName, array $headers, array $rows, array $topRows = []): void
     {
         $filename = preg_replace('/\.[^.]+$/u', '', $filename) . '.xls';
 
@@ -97,6 +98,15 @@ if (! function_exists('export_excel_2003_xml')) {
         $parts[] = '<Worksheet ss:Name="' . $esc($safeSheet) . '">';
         $parts[] = '<Table>';
 
+        // 상단 제목/부제 행(있을 때만)
+        foreach ($topRows as $topRow) {
+            $parts[] = '<Row>';
+            foreach (array_values((array) $topRow) as $cell) {
+                $parts[] = '<Cell><Data ss:Type="String">' . $esc($cell) . '</Data></Cell>';
+            }
+            $parts[] = '</Row>';
+        }
+
         $parts[] = '<Row>';
         foreach ($headers as $h) {
             $parts[] = '<Cell><Data ss:Type="String">' . $esc($h) . '</Data></Cell>';