# 2026-04-19 domain-seo-external storage 收口说明 ## 背景 `domain-seo-external` 这套后台摘要原先把最新运行产物持续写到： - `code/public/_admin_templates/domain-seo-external/latest` - `code/public/_admin_templates/domain-seo-external/snapshot-runs` - `code/public/_admin_templates/domain-seo-external/snapshot-validate-runs` 这会带来两个直接问题： 1. 运行数据混进 `public`，容易污染 Git 待提交区 2. `latest/*.summary.json/html` 属于运行产物，不适合作为源码提交 --- ## 本次收口目标 把 `domain-seo-external` 的最新摘要与快照运行产物统一切到： - `code/storage/external-seo/latest` - `code/storage/external-seo/snapshot-runs` - `code/storage/external-seo/snapshot-validate-runs` 并确保管理端 / API 返回路径同步改成 `storage/...` 相对路径。 --- ## 本次实际修改 ### 1. 管理端 root 改到 storage 文件： - [Site.php](/www/wwwroot/VideoSource2/code/app/admin/controller/Site.php:1058) 调整： 1. `domainExternalSeoSummaryRoot()` 改到 `storage/external-seo/latest` 2. `domainExternalSeoSnapshotRunRoot()` 改到 `storage/external-seo/snapshot-runs` 3. `domainExternalSeoSnapshotValidateRunRoot()` 改到 `storage/external-seo/snapshot-validate-runs` 4. 新增 `storageRelativePath()`，供站外 SEO 这条链专门返回 `storage` 相对路径 ### 2. 管理端站外 SEO 摘要返回值改走 storage 路径 文件： - [Site.php](/www/wwwroot/VideoSource2/code/app/admin/controller/Site.php:2192) 覆盖范围： 1. `getDomainExternalSeoSummary` 2. `getDomainExternalSeoTrendSummary` 3. `getDomainExternalSeoRealSummary` 4. Search Console / 百度推送 / 爱站关键词 / site: probe 等摘要接口 5. `saveDomainExternalSeoSnapshots` 6. `validateDomainExternalSeoSnapshots` 7. 手工导入后返回的 `real_summary_*` 路径 结果： 这些接口现在返回的是： - `external-seo/latest/...` - `external-seo/snapshot-runs/...` - `external-seo/snapshot-validate-runs/...` 而不是 `public/_admin_templates/...` ### 3. API 推送入口改到 storage 文件： - [SeoCollector.php](/www/wwwroot/VideoSource2/code/app/api/controller/SeoCollector.php:35) 调整： 1. `summaryRoot()` 改到 `storage/external-seo/latest` 2. `snapshotRunRoot()` 改到 `storage/external-seo/snapshot-runs` 3. `snapshotValidateRunRoot()` 改到 `storage/external-seo/snapshot-validate-runs` 4. `saveSnapshots()` / `validateSnapshots()` 的返回路径统一改走 `storageRelativePath()` ### 4. snapshot run 索引 helper 也改走 storage 文件： - [DomainExternalSeoSnapshotRunIndexHelper.php](/www/wwwroot/VideoSource2/code/app/common/helper/DomainExternalSeoSnapshotRunIndexHelper.php:7) - [DomainExternalSeoSnapshotValidateRunIndexHelper.php](/www/wwwroot/VideoSource2/code/app/common/helper/DomainExternalSeoSnapshotValidateRunIndexHelper.php:7) 调整： 1. 原先 helper 内部只识别 `public` 2. 现在改为识别 `storage` 3. 避免列表接口继续吐绝对路径，或继续带旧 `public` 前缀 --- ## 兼容处理 为了避免切换后后台立刻读不到最近一次摘要，这次已把当前： - `code/public/_admin_templates/domain-seo-external/latest/*` 复制了一份到： - `code/storage/external-seo/latest/*` 这样下一次后台读 `storage` 时，至少已有一份最近摘要可用。 --- ## 已验证 已通过语法检查： ```bash php -l code/app/admin/controller/Site.php php -l code/app/api/controller/SeoCollector.php php -l code/app/common/helper/DomainExternalSeoSnapshotRunIndexHelper.php php -l code/app/common/helper/DomainExternalSeoSnapshotValidateRunIndexHelper.php ``` --- ## 当前仍需主线 Codex 注意 1. `code/public/_admin_templates/domain-seo-external/latest/*` 这批文件在仓库里当前仍是已跟踪文件 2. 本次收口已经阻止后续新运行继续写这条 `public` 路径 3. 但历史上已被 Git 跟踪的 `public` 运行产物，这次没有直接强删或批量移出版本库 4. 主线 Codex 提交前，建议明确把这批运行产物排除在提交之外 --- ## 建议提交范围 建议优先给主线 Codex 复核这几份代码： - [Site.php](/www/wwwroot/VideoSource2/code/app/admin/controller/Site.php:1058) - [SeoCollector.php](/www/wwwroot/VideoSource2/code/app/api/controller/SeoCollector.php:35) - [DomainExternalSeoSnapshotRunIndexHelper.php](/www/wwwroot/VideoSource2/code/app/common/helper/DomainExternalSeoSnapshotRunIndexHelper.php:7) - [DomainExternalSeoSnapshotValidateRunIndexHelper.php](/www/wwwroot/VideoSource2/code/app/common/helper/DomainExternalSeoSnapshotValidateRunIndexHelper.php:7) 这份说明文档： - [2026-04-19-domain-seo-external-storage收口说明.md](/www/wwwroot/VideoSource2/docs/2026-04-19-domain-seo-external-storage收口说明.md:1) --- ## 一句话结论 > 本次已经把 `domain-seo-external` 的 latest / snapshot 运行产物输出主链从 `public/_admin_templates/...` 收口到 `storage/external-seo/...`，后续不应再把这类后台摘要数据当源码提交。