SEONexus/docs/2026-04-19-domain-seo-external-storage收口说明.md

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

调整：

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

覆盖范围：

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

调整：

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
• DomainExternalSeoSnapshotValidateRunIndexHelper.php

调整：

1. 原先 helper 内部只识别 public
2. 现在改为识别 storage
3. 避免列表接口继续吐绝对路径，或继续带旧 public 前缀

---

兼容处理

为了避免切换后后台立刻读不到最近一次摘要，这次已把当前：

• code/public/_admin_templates/domain-seo-external/latest/*

复制了一份到：

• code/storage/external-seo/latest/*

这样下一次后台读 storage 时，至少已有一份最近摘要可用。

---

已验证

已通过语法检查：

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
• SeoCollector.php
• DomainExternalSeoSnapshotRunIndexHelper.php
• DomainExternalSeoSnapshotValidateRunIndexHelper.php

这份说明文档：

• 2026-04-19-domain-seo-external-storage收口说明.md

---

一句话结论

本次已经把 domain-seo-external 的 latest / snapshot 运行产物输出主链从 public/_admin_templates/... 收口到 storage/external-seo/...，后续不应再把这类后台摘要数据当源码提交。