docs: add private runtime storage rules

docs/2026-04-19-私有运行产物存储与发布公共规则.md

@@ -0,0 +1,171 @@
+# 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. 后台查看链路清晰
+
+然后再谈兼容和迁移。