# 开发文档发布与防漂移机制

## 单一事实来源

框架契约、标准示例、仓库维护的知识文章和验证流程以 Git 中的 Markdown 为唯一事实来源。`scripts/generate-docs-page.mjs` 将这些文件确定性生成到 `worker/docs_page.js`。

官网为了保留后台预览、版本历史和回滚能力，公开 HTML/Markdown 路由会读取 D1 中的已发布快照。因此只部署 Worker 不会自动覆盖既有正文；发布者必须显式运行 `scripts/generate-docs-content-sync-sql.mjs`，把 Git 构建内容写入 D1 的草稿、已发布版本、修订记录和审计记录。脚本保留导航等附加字段，不删除自定义运营文章。

## 可追溯清单

生成器同时输出 `DOCS_MANIFEST`，公开部署后由 `/docs/manifest.json` 返回。清单包含：

- 框架版本和契约版本；
- 仓库地址与 `source_of_truth: git`；
- 每篇公开文档的 Git 单一或组成源路径、HTML 路由、Markdown 路由、实际公开正文 SHA-256 和证据等级。

具体 Git commit 由发布提交和部署记录关联，避免把 commit 写入被该 commit 自身包含的生成文件而产生自引用。发布记录必须登记部署所用 commit。

## 修改和发布流程

1. 修改 Markdown、共享示例源或运行时；
2. 运行 `pnpm run generate:amazon`（修改 Amazon 共享逻辑时）和 `pnpm run build:docs`；
3. 运行 `pnpm run verify`，生成文件必须与源一致；
4. 提交源文件和 `worker/docs_page.js`，在发布记录登记 commit；
5. 经产品负责人确认后部署 Worker；
6. 生成文档快照 SQL 和 D1 安全分片，例如 `node scripts/generate-docs-content-sync-sql.mjs --version 1.9.1 --output output/releases/1.9.1/docs-content-sync.sql --chunk-dir output/releases/1.9.1/docs-content-sync`；逐个以 `pnpm dlx wrangler d1 execute alexa_hub --remote --yes --file <分片>` 执行，避免合并 SQL 过大触发 D1 重置保护；
7. 运行 `pnpm run verify:docs-publication -- https://www.sellerfeeds.com`，逐篇比较线上清单与 Markdown 内容哈希；
8. 验证开发入口能继续读取示例和知识文章。

Git 管理的文档不能只在后台直接改 D1；下一次同步会以 Git 正文覆盖。要修改契约必须走 Git、测试、review、Worker 部署和 D1 快照同步。新增临时运营文章可使用 D1，但一旦纳入长期开发知识，应迁移到 Git 并进入清单。

## 失败处理

- 生成器 `--check` 或 `pnpm run verify` 失败：不发布；先重新生成并审查差异。
- 线上 manifest 版本/哈希不同：说明部署版本或缓存不一致，不宣称文档已同步。
- Markdown 哈希与 manifest 不同：通常是漏执行 D1 快照同步；停止 AI 验收，生成并执行同步 SQL后重新核对。
- 平台知识证据升级：同步更新知识文章的日期、证据等级、fixture/测试和预期结果，不能只改结论文字。