refactor: improve template notes readability

code/app/common/helper/DomainBatchImportTemplateHelper.php

@@ -10,6 +10,13 @@ use PhpOffice\PhpSpreadsheet\Writer\Xlsx;
 
 class DomainBatchImportTemplateHelper
 {
+    public static function buildNoteDisplayLabel(string $field): string
+    {
+        $label = self::getHeaderLabels()[$field] ?? $field;
+
+        return $label . '（' . $field . '）';
+    }
+
     public static function getHeaderLabels(): array
     {
         return [
@@ -120,11 +127,13 @@ class DomainBatchImportTemplateHelper
 
         $notesSheet = $spreadsheet->createSheet();
         $notesSheet->setTitle('notes');
-        $notesSheet->setCellValue('A1', 'column');
-        $notesSheet->setCellValue('B1', 'note');
+        $notesSheet->setCellValue('A1', '字段');
+        $notesSheet->setCellValue('B1', '说明');
         $notesSheet->getStyle('A1:B1')->getFont()->setBold(true);
-        $notesSheet->getColumnDimension('A')->setWidth(28);
-        $notesSheet->getColumnDimension('B')->setWidth(80);
+        $notesSheet->getColumnDimension('A')->setWidth(42);
+        $notesSheet->getColumnDimension('B')->setWidth(120);
+        $notesSheet->getStyle('A:B')->getAlignment()->setWrapText(true);
+        $notesSheet->getStyle('A:B')->getAlignment()->setVertical(\PhpOffice\PhpSpreadsheet\Style\Alignment::VERTICAL_TOP);
 
         $rowNo = 2;
         foreach ($columnNotes as $column => $note) {
@@ -172,26 +181,26 @@ class DomainBatchImportTemplateHelper
         return [
             'd_domain' => '必填。填写站点正式域名，不要带 https:// 。示例：jingxifa.com。只有做泛域名时，才填 *.example.com。',
             'd_name' => '必填。填写站点前台展示名称，会用于页头、页脚和基础 SEO 文案。示例：鲸溪发影视。',
-            't_id' => '通常直接填 1。只有明确知道要换模板时才改；不确定就不要改。',
+            't_id' => "通常直接填 1。\n可选值说明：\n- 1：当前默认模板。绝大多数 GPT 模板站都填这个。\n- 其他数字：代表后台另外配置过的模板 ID，只有你明确知道该站要切到别的模板时才改。\n不会判断时就保持 1，不要猜。",
             'd_index_title' => '建议填写。首页给搜索引擎看的标题，尽量自然，不要堆词。建议 28 到 40 字。',
             'd_index_keywords' => '建议填写。首页核心关键词，多个词用逗号分隔。示例：短剧推荐,热播短剧,高清短剧。',
             'd_index_description' => '建议填写。首页一句话简介，建议 40 到 80 字，写自然一点。',
-            'strategy_profile' => '通常不用改，默认 standard。只有明确知道要做流量型、扩展型站点时，才改成 traffic 或 expand。',
+            'strategy_profile' => "SEO 策略档位，默认 standard。\n可选值说明：\n- standard：标准站，最常用默认值。普通内容站、普通影视站、先求稳定收录时选它。\n- traffic：流量型。更强调关键词覆盖、流量页铺量，适合明确要做流量词扩展的站。\n- expand：扩展型。更适合泛域名、子站扩展、批量铺设场景。\n- closed：收缩/关闭型。通常用于不再继续扩张或只保留最小发布动作的站。\n不确定就填 standard。",
             'd_keywords' => '可选。不填也能跑；如要补充站点级关键词，可填在这里。',
             'd_description' => '可选。不填时系统会按站点名称自动兜底一版简介。',
             'd_baidu_token' => '可选。只有需要百度主动推送时才填写。',
-            'd_match_type' => '可选。默认 exact。普通单域名站保持默认即可；只有泛域名场景才需要改。',
-            'd_parent_domain' => '只有 wildcard 泛域名场景才需要填根域名。普通单域名站留空即可。',
-            'd_seed_scope' => '可选。默认 domain。普通单域名站不用改；只有特殊 host 级种子策略才改。',
+            'd_match_type' => "域名匹配方式，默认 exact。\n可选值说明：\n- exact：精确匹配。普通单域名站使用这个，例如 jingxifa.com。\n- wildcard：泛匹配。只有泛域名场景才用，例如 *.example.com。\n如果你填的是普通单域名，就保持 exact。",
+            'd_parent_domain' => "父域名只在 wildcard 泛域名场景下填写。\n填写规则：\n- 如果 d_domain 是 *.example.com，这里填 example.com。\n- 如果 d_domain 是普通单域名，例如 jingxifa.com，这里留空。\n不要把 https:// 或路径带进来。",
+            'd_seed_scope' => "种子范围，默认 domain。\n可选值说明：\n- domain：按整域名范围处理，普通站点默认用这个。\n- host：按具体 host 处理，常见于泛域名、子站单独铺设的场景。\n不确定就用 domain。",
             'd_statis' => '可选。统计代码区，运营通常不用填。',
-            'd_logo_type' => '通常填 0。普通站点不用改；如果是纯图片 LOGO 再按技术要求调整。',
+            'd_logo_type' => "LOGO 类型，通常填 0。\n可选值说明：\n- 0：文字 LOGO 优先。最常用，普通站点直接用这个。\n- 1：图片 LOGO 优先。只有明确要展示图片 LOGO，且 d_img_logo 已准备好时才用。\n不确定就填 0。",
             'd_text_logo' => '可选。填写前台显示的文字 LOGO；不填时可按站点名称兜底。',
             'd_img_logo' => '可选。只有要使用图片 LOGO 时才填写。',
-            'd_content_encode' => '通常填 0。普通运营不用改。',
-            'info_id' => '通常填 0。普通运营不用改。',
-            'd_seo_cfg' => '可选。高级配置区，通常给技术同学使用。运营不需要填写；只有明确要覆盖默认 SEO 策略时再填 JSON。',
-            'tkd_mode' => '可选。一般不用填。留空时系统会根据首页三要素是否导入自动选择模式。',
-            'tkd_provider' => '可选。一般保持 local，不需要运营修改。',
+            'd_content_encode' => "内容编码，通常填 0。\n可选值说明：\n- 0：默认编码方式。普通站直接用这个。\n- 其他值：特殊历史兼容场景才会用，运营不要自行改。\n不会判断就填 0。",
+            'info_id' => "信息 ID，通常填 0。\n可选值说明：\n- 0：默认即可。\n- 其他数字：通常是历史数据联动或特殊资源绑定才会用。\n普通新站不要改。",
+            'd_seo_cfg' => "高级 SEO 配置 JSON。普通运营通常留空。\n适用场景：\n- 要覆盖默认 SEO 行为\n- 要补结构化数据\n- 要定制 forge / route_group 等技术项\n注意：必须填写合法 JSON，例如 {\"forge\":{\"route_group\":\"film\"}}。\n如果看不懂，就留空。",
+            'tkd_mode' => "TKD 模式。一般可留空，由系统自动判断。\n常见可选值说明：\n- 留空：推荐。系统按当前导入内容自动选择。\n- 1：偏向使用导入内容/现成内容。\n- 2：偏向使用系统生成或增强策略。\n不同环境里数字语义可能有历史兼容差异，所以运营不建议手改；只有技术明确要求时再填。",
+            'tkd_provider' => "TKD 来源。一般保持 local 或留空。\n可选值说明：\n- local：本地默认来源，最稳，常规就用它。\n- openai：走 AI 生成或 AI 优化链路，只有明确开了这套能力时才填。\n- 其他值：属于技术兼容项，不建议运营手填。\n不确定就留空或填 local。",
         ];
     }
 
@@ -317,7 +326,7 @@ class DomainBatchImportTemplateHelper
         );
         $displayNotes = [];
         foreach (self::getColumnNotes() as $field => $note) {
-            $displayNotes[$headerLabels[$field] ?? $field] = $note;
+            $displayNotes[self::buildNoteDisplayLabel($field)] = $note;
         }
 
         self::writeWorkbook(

code/app/common/helper/DomainSupplyBatchTemplateHelper.php

@@ -128,11 +128,11 @@ class DomainSupplyBatchTemplateHelper
         return [
             'host' => '必填。填写站点正式域名，不要带 https:// 。示例：jingxifa.com。只有做泛域名时，才填 *.example.com。',
             'site_name' => '必填。填写站点前台展示名称，会用于页头、页脚和基础 SEO 文案。示例：鲸溪发影视。',
-            'template_id' => '通常直接填 1。只有确认要换模板时才改；不确定就不要改。',
+            'template_id' => "通常直接填 1。\n可选值说明：\n- 1：当前默认 GPT 模板。绝大多数站都用这个。\n- 其他数字：代表后台另有模板配置，只有技术明确指定时才改。\n不确定就填 1。",
             'site_index_title' => '建议填写。首页给搜索引擎看的标题，尽量自然，不要堆词。建议 28 到 40 字。',
             'site_index_keywords' => '建议填写。首页核心关键词，多个词用逗号分隔。示例：短剧推荐,热播短剧,高清短剧。',
             'site_index_description' => '建议填写。首页一句话简介，建议 40 到 80 字，写自然一点。',
-            'strategy_profile' => '通常不用改，默认 standard。只有明确知道要做流量型、扩展型站点时，才改成 traffic 或 expand。',
+            'strategy_profile' => "SEO 策略档位，默认 standard。\n可选值说明：\n- standard：标准站，最常用默认值，先求稳定收录和正常运营时选它。\n- traffic：流量型，更偏向做关键词覆盖和流量页扩展。\n- expand：扩展型，更适合泛域名、子站批量扩展。\n- closed：收缩/关闭型，通常用于只保留最小更新动作的站。\n不确定就填 standard。",
             'detail_id' => '通常不用手填。站点部署成功后，系统会优先通过自动样本发现，从当前站点可用内容里自动提取。只有域名还没部署成功、当前只是试跑库、或自动发现失败时，才人工补填真实详情视频 ID。',
             'detail_slug' => '通常不用手填。会和详情样本 ID 一起自动获取。若人工填写，必须和详情样本 ID 对应，不能乱配。',
             'search_keyword' => '通常不用手填。系统会优先从站点名称、视频 SEO 词、视频标题里自动挑一个可搜索关键词。只有自动发现失败时，再人工填写一个能搜出结果的词。',
@@ -141,13 +141,13 @@ class DomainSupplyBatchTemplateHelper
             'site_keywords' => '可选。不填也能跑；如要补充站点级关键词，可填在这里。',
             'site_description' => '可选。不填时系统会按站点名称自动兜底一版简介。',
             'baidu_token' => '可选。只有需要百度主动推送时才填写。',
-            'match_type' => '可选。默认 exact。普通单域名站保持默认即可；只有泛域名场景才需要改。',
-            'parent_domain' => '只有 wildcard 泛域名场景才需要填根域名。普通单域名站留空即可。',
-            'seed_scope' => '可选。默认 domain。普通单域名站不用改；只有特殊 host 级种子策略才改。',
-            'play_type' => '可选。默认 douban。自动样本发现成功时通常也能自动带出，不需要运营关心。',
-            'play_index' => '可选。默认 1。通常不用改。',
-            'forge_index' => '可选。默认 1。通常不用改。',
-            'rank_slug' => '可选。默认 daily。通常不用改。',
+            'match_type' => "域名匹配方式，默认 exact。\n可选值说明：\n- exact：精确匹配。普通单域名站使用这个，例如 jingxifa.com。\n- wildcard：泛匹配。只有泛域名场景才用，例如 *.example.com。\n不确定就保持 exact。",
+            'parent_domain' => "父域名只在 wildcard 泛域名场景下填写。\n填写规则：\n- host 是 *.example.com 时，这里填 example.com。\n- host 是普通单域名时留空。\n不要填协议、路径或 www。",
+            'seed_scope' => "种子范围，默认 domain。\n可选值说明：\n- domain：按整域名范围处理，普通站点默认用这个。\n- host：按具体 host 处理，常见于泛域名、子站拆分运营场景。\n不确定就填 domain。",
+            'play_type' => "播放类型。通常可留空，自动样本成功时系统会自动带出。\n常见可选值说明：\n- douban：常见默认线路，绝大多数站留空后最终也会落到它。\n- youzhi：另一种播放线路标识，只有样本明确属于这条线路时才填。\n- 其他值：必须与站内真实播放线路一致，不能凭感觉乱写。\n不确定就留空，优先让系统自动发现。",
+            'play_index' => "播放序号，默认 1。\n可选值说明：\n- 1：第一条播放线路下的第一集/第一入口，最常用。\n- 2、3、4...：只有你明确知道该样本要绑定到第几集或第几个入口时才改。\n不确定就填 1 或留空。",
+            'forge_index' => "锻造序号，默认 1。\n可选值说明：\n- 1：默认主锻造位，绝大多数站都用这个。\n- 其他数字：只有技术明确安排了多锻造位时才改。\n运营通常保持 1 即可。",
+            'rank_slug' => "榜单 slug，默认 daily。\n可选值说明：\n- daily：日榜，最常用默认值。\n- weekly：周榜，只有明确要挂周榜时才用。\n- monthly：月榜，只有明确要挂月榜时才用。\n- 其他 slug：必须后台已有对应榜单配置，否则不要乱填。\n不确定就填 daily。",
             'base_url' => '可选。默认自动按 https://域名 生成。只有特殊环境才手填。',
             'bundle_name' => '可选。一般留空，系统会按域名自动生成 bundle 目录名。',
             'seo_cfg_json' => '可选。高级配置区，通常给技术同学使用。运营不需要填写；只有明确要覆盖默认 SEO 策略时再填 JSON。',
@@ -305,7 +305,7 @@ class DomainSupplyBatchTemplateHelper
         );
         $displayNotes = [];
         foreach (self::getColumnNotes() as $field => $note) {
-            $displayNotes[$headerLabels[$field] ?? $field] = $note;
+            $displayNotes[DomainBatchImportTemplateHelper::buildNoteDisplayLabel($field)] = $note;
         }
 
         DomainBatchImportTemplateHelper::writeWorkbook(