153 lines
5.0 KiB
Markdown
153 lines
5.0 KiB
Markdown
# 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/...`，后续不应再把这类后台摘要数据当源码提交。
|