diff --git a/docs/2026-04-19-私有运行产物存储与发布公共规则.md b/docs/2026-04-19-私有运行产物存储与发布公共规则.md new file mode 100644 index 0000000..7ed05ef --- /dev/null +++ b/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. 后台查看链路清晰 + +然后再谈兼容和迁移。 diff --git a/docs/Codex启动提示词模板.md b/docs/Codex启动提示词模板.md index 5eaf736..c4cb89f 100644 --- a/docs/Codex启动提示词模板.md +++ b/docs/Codex启动提示词模板.md @@ -182,11 +182,15 @@ 1. 先看 `/www/wwwroot/diff-maccms/SEONexus/docs/README.md` 2. 再看 `/www/wwwroot/diff-maccms/SEONexus/docs/2026-04-18-AI文案与视频元数据公共规则主线.md` 3. 再看 `/www/wwwroot/diff-maccms/SEONexus/docs/2026-04-18-视频元数据缺失处理公共执行规则.md` -4. 如果任务涉及多人协作或老时间线，再看： +4. 再看 `/www/wwwroot/diff-maccms/SEONexus/docs/2026-04-19-私有运行产物存储与发布公共规则.md` +5. 如果任务涉及多人协作或老时间线，再看： `/www/wwwroot/diff-maccms/SEONexus/docs/1270-SEONexus-Codex多版本协作交接总文档.md` 先记住： - `AI文案规则` 和 `视频元数据缺失处理规则` 现在属于全项目公共规则 +- 所有后台运行产物、工作台快照、调试结果、中间文件默认放 `storage` +- 只要不是公网发布资产，就不要放 `public` +- Vue 后台打开私有产物时，走后台鉴权预览接口，不要直接拼 `public` URL - 结构化字段不能靠 AI 猜 - 文案型字段只能在真实性边界内补空 - 所有补齐结果优先写回视频库 diff --git a/docs/README.md b/docs/README.md index c459ad7..d962e05 100644 --- a/docs/README.md +++ b/docs/README.md @@ -49,6 +49,7 @@ - [2026-04-18-PHP与Vue收口交付总结.md](/www/wwwroot/diff-maccms/SEONexus/docs/2026-04-18-PHP与Vue收口交付总结.md) - [2026-04-18-其它服务器更新操作单-PHP加Vue.md](/www/wwwroot/diff-maccms/SEONexus/docs/2026-04-18-其它服务器更新操作单-PHP加Vue.md) +- [2026-04-19-私有运行产物存储与发布公共规则.md](/www/wwwroot/diff-maccms/SEONexus/docs/2026-04-19-私有运行产物存储与发布公共规则.md) 适用场景： @@ -58,6 +59,7 @@ 4. 需要同步今天补上的 `Spider MD 异步任务消费器`、`GitHub 推送`、`主表一键复制MD` 这些后台能力 5. 需要同步“所有后台运行产物、工作台快照、手工导入中间文件默认落 `storage`，不要再放 `public`”这条新口径 6. 需要同步“Vue 后台打开 `storage` 产物时，走后台鉴权预览入口，不要再直接拼 `public` URL”这条新口径 +7. 需要同步“只要不是公网发布资产，就默认进 `storage`，不要用 `public` 充当私有运行数据目录”这条公共规则 ### 1.3 AI文案与视频元数据公共规则