# 2026-04-19 私有运行产物存储与发布公共规则

这份文档属于全项目公共规则。

适用范围：

1. `SEONexus`
2. `SEONexusAdmin`
3. GPT 模板
4. 老模板
5. 以后新增模板或新增后台工作台

目标只有一个：

> 所有运行时生成的私有数据、中间文件、工作台快照、调试结果、异步任务产物，默认放 `storage`，不要再放 `public`。

---

## 一句话规则

默认判断口径：

1. 只要这个文件不是源码，不需要被公网直接访问，就不要放 `public`
2. 只要这个文件会反复覆盖、每天新增、按任务生成、按用户生成、按批次生成，就优先放 `storage`
3. 只要这个文件包含后台专用信息、运行日志、调试快照、工作台临时结果、导入导出中间态，就必须放 `storage`
4. Vue 后台如果要打开 `storage` 文件，走后台鉴权预览接口，不要直接拼公网 URL

---

## 哪些必须放 storage

下面这些，默认都属于 `storage`：

1. 蜘蛛日志分析产物
2. SEO 观察面板运行快照
3. `latest.summary.json/html` 这类后台摘要文件
4. 视频元数据缺失工作台中间结果
5. AI 队列任务产物
6. 导入新域名后的扫描中间文件
7. 手工导入 / 批量导入后的临时文件
8. 任务池运行日志
9. 异步任务进度文件
10. 一键生成后的批次目录
11. 调试 JSON
12. 人工排障时导出的临时报告
13. 只给后台使用的 HTML 片段、JSON 片段、Markdown 片段

判断技巧：

- 会不会每天新增很多份
- 会不会经常被覆盖
- 会不会只在后台看
- 会不会不适合进 Git

只要答案偏向“会”，就应该进 `storage`。

---

## 哪些才允许放 public

只有真正需要公网直接访问、并且可以视为发布资产的内容，才允许放 `public`。

典型例子：

1. 前台页面真正要引用的静态资源
2. 模板正式发布资源
3. 已确认要对外发布的 SEO 静态页产物
4. 前台运行必须直接访问的 js / css / image / font
5. 明确设计为公网 URL 的最终发布文件

注意：

- `public` 是发布区，不是工作台缓存区
- `public` 不是临时文件夹
- `public` 不是后台调试目录
- `public` 不是“先放一下后面再整理”的地方

---

## Git 提交规则

所有 Codex 和人工协作者，默认遵守下面 6 条：

1. 提交前先看有没有运行产物混进变更区
2. `latest/*.json`、`latest/*.html` 这类文件先怀疑是运行产物，不要直接提交
3. 工作台目录如果只是本地运行结果，要加忽略规则，不要入库
4. 私有批次目录如果只是中间产物，不要提交
5. 真正需要同步的，是代码、配置、文档、模板，不是运行结果
6. 看到 `public/_admin_templates/...` 下面不断新增批次文件时，先怀疑设计跑偏

---

## 后台查看规则

如果文件放在 `storage`，后台仍然可以看，但方式要改成：

1. PHP 提供受后台登录保护的预览接口
2. Vue 后台通过接口读取或打开
3. 不要直接把 `storage` 文件暴露成匿名公网链接
4. 不要因为“后台想看方便”就把文件搬回 `public`

当前已经确认的正确方向：

1. 私有运行产物留在 `storage`
2. 后台通过鉴权接口预览
3. 前端只拿相对路径或任务标识，不直接拼公开文件 URL

---

## 这条规则为什么重要

如果不这么做，会反复出现这些问题：

1. Git 工作区天天脏
2. 提交时误把私有数据推到仓库
3. 同一类运行产物被多台机器重复覆盖
4. 后台临时文件被当成正式发布资源
5. 新接手 Codex 看见 `public` 里的数据，误以为那是源码或正式模板
6. 公网可直接访问到本不该公开的后台产物

---

## 历史兼容处理

如果历史上已经有一批运行产物放在 `public`，处理顺序是：

1. 先改代码，新运行不再写旧路径
2. 再把后台读取链路改到 `storage`
3. 再评估历史文件是否保留、迁移或移出版本库
4. 不要一边继续往旧 `public` 目录写，一边说后面再收口

---

## 新 Codex 接手必须先记住

后续任何新的 Codex 会话，看到下面几类需求时，默认先套这条规则：

1. “后台生成一个报告”
2. “异步任务跑完留个结果”
3. “导入后先产出一份中间 JSON”
4. “工作台保存当前批次”
5. “任务日志保留给后台看”
6. “批量生成 Markdown / HTML / JSON”

默认答案：

- 如果不是公网发布资产，就放 `storage`

---

## 当前项目已明确的新增统一口径

1. 所有后台运行产物、工作台快照、手工导入中间文件默认落 `storage`
2. Vue 后台打开 `storage` 产物时，走后台鉴权预览入口
3. 不要再直接拼 `public` URL 作为后台查看方式
4. 后续如新增“私有数据目录”，也应以 `storage` 为第一落点，而不是在 `public` 新建隐藏角落

---

## 给后续协作者的最终提醒

如果某条旧规则、旧目录、旧习惯，开始限制 SEO、后台治理、协作效率，或者明显增加误提交风险，不能因为“以前这么干”就继续保留。

先保证：

1. 数据边界清晰
2. Git 边界清晰
3. 公网发布边界清晰
4. 后台查看链路清晰

然后再谈兼容和迁移。