diff --git a/docs/acceptance/qa-tracker.md b/docs/acceptance/qa-tracker.md index d6bd337..a450329 100644 --- a/docs/acceptance/qa-tracker.md +++ b/docs/acceptance/qa-tracker.md @@ -1140,3 +1140,25 @@ webkit/mobile 的 Tab 引擎差异取证法、`pollBoundingBox` 的二次读取 **视觉基线与"seed 内容"耦合** —— 重跑 `db:seed` 或改 CMS 文案后,内容型基线会失效, 必须按"内容变更 ⇒ 重采 + 只读复验"处理,不能把它读成样式回归。反过来, 将来若看到只有 `/contact`、`/news` 这类内容页整页红而组件裁图全绿,先查数据而不是查 CSS。 + +### 14.7 生产侧只读核对 + 迁移预演(发布前的最后一块证据) + +**只读核对(`scp` 生产 `data/prod.db` 到 /tmp,本地 `node:sqlite` 查询;未写生产任何东西)** + +| 项 | 生产实测 | +|---|---| +| `navigation` 行 | **旧 7 项 IA**:产品/解决方案/服务/案例/新闻动态/关于我们/联系我们,面板 `products,solutions,services` ⇒ 新代码每请求退回代码真源 | +| `ContentModel.fields`(product / service / standalone-product) | **均缺** `authorized` 与 `basis` ⇒ 后台填不出案例门槛字段 | +| 生产内容里的案例条目 | **0 条**(`case-study` 0 行;四个含 `caseStudies` 字段的模型逐行解析,数组全空) | +| ⇒ 只发代码的影响 | 站点可用(fail-closed 回退),**不隐藏任何内容**(0 案例;`dataProofs` 按裁定不套硬闸);代价是每请求一条回退日志 + 后台填不出门槛字段 | + +**迁移预演**:`scripts/ops/sync-cms-schema.ts`(默认 dry-run,`--apply` 才写,写后强制用真实 +`resolveNavigation` 复查)。在**生产库副本**上跑通: +`source=cms issues=0`;逐行 diff 证明变更范围 **3 个 ContentModel 行 + 1 个 ContentItem 行**, +其余 37 行内容、其余 13 个模型逐字节未变。 +关键约束写进 runbook:**服务器 Node v20 没有 `node:sqlite`** ⇒ 迁移必须本机对库副本执行再回传; +若改用 `npm run db:seed`,服务器上必须显式 `SEED_ALLOW_EXTERNAL_DB=1`(守卫会拦 `file:/app/data/prod.db`), +且 seed 会重写所有被覆盖的内容行 —— 因此**不推荐**。 + +发布步骤、发布后核对(页面状态码 / 回退日志计数 / 后台字段 / 视觉抽查)与三条回滚路径: +`docs/development/deploy-runbook.md`。**代码发布本身(合 main)仍由决策人显式发起**。 diff --git a/docs/development/deploy-runbook.md b/docs/development/deploy-runbook.md new file mode 100644 index 0000000..06ff108 --- /dev/null +++ b/docs/development/deploy-runbook.md @@ -0,0 +1,87 @@ +# 发布 runbook(对标语法批 dev → main,2026-10) + +> **本文件是操作清单,不是建议书。** 每一步都给出可复跑的判据;任何一步的读数不符预期就停在原地, +> 不要带着已知漂移往下走。生产侧的实测事实见 `reference-production-server-deploy` 记忆与 +> `docs/acceptance/qa-tracker.md` §12–§14。 + +## 0. 这次发布包含什么(dev tip `8799a965` 起) + +- §11 对标语法批(首页 8 段、双轴 IA、信任层零编造、tracer-bullet 详情页) +- §12 台账六项:DEC-N1/N2(证伪)/N3/N4/N5/N6 + AUTH-VISUAL + AUTH-NAV 核查 + GA4 首次真断言 +- §13/§14 治理与收口:全量功能 E2E **1068 passed / 0 failed**、`test:all` 0、 + `check:axe` 0、`lighthouse` 0、视觉 125/125;`case-publish-gate` 与 `seed` 沙盒守卫 + +## 1. 预检(已完成,发布前复核仍然成立即可) + +| 项 | 读数 | 复跑 | +|---|---|---| +| 生产库 `navigation` 行 | **旧 7 项 IA**(产品/解决方案/服务/案例/新闻动态/关于我们/联系我们 + panels products,solutions,services) | 见 §3 的只读检查 | +| 生产库 `ContentModel.fields`(3 个案例模型) | **缺** `authorized` 与 `basis` | 同上 | +| 生产库里的案例条目 | **0 条**(`case-study` 模型 0 行;product/service/standalone-product/solution 的 `caseStudies` 数组全空) | 同上 | +| ⇒ 只发代码、不做数据修复的后果 | 站点可用(导航 fail-closed 退回代码真源),但**每请求一条回退日志**,且后台填不出案例门槛字段 | — | +| ⇒ 这批代码会隐藏内容吗 | **不会**(案例 0 条;`dataProofs` 按 DEC-N4 的裁定不套 verified 硬闸) | — | + +## 2. 数据修复(只动 2 处,先备份、先 dry-run) + +工具:`scripts/ops/sync-cms-schema.ts`(默认 dry-run;`--apply` 才写;写后强制用真实 +`resolveNavigation` 复查,不通过即退出码 1)。 + +**关键约束:服务器 Node 是 v20,没有 `node:sqlite`** ⇒ 迁移**必须在本机**对下载下来的库副本执行, +再把库回传。不要试图在服务器上跑这个脚本。 + +```bash +# 2.1 备份(容器运行时 prod.db 是 WAL,先停容器再拷) +ssh root@139.155.109.62 'cd /home/novalon/docker-app/novalon-website \ + && docker stop novalon-website \ + && cp -av data/prod.db data/prod.db.bak.$(date +%Y%m%d_%H%M%S)' +# 2.2 下载副本、本机 dry-run(**先看计划**) +scp root@139.155.109.62:/home/novalon/docker-app/novalon-website/data/prod.db /tmp/prod.db +npx tsx scripts/ops/sync-cms-schema.ts --db /tmp/prod.db # 期望:3 个模型各 +authorized,+basis;navigation 7 项 → 4 项 +# 2.3 应用到副本并复查 +npx tsx scripts/ops/sync-cms-schema.ts --db /tmp/prod.db --apply # 期望:写后复查通过 +# 2.4 回传(覆盖前再确认备份存在) +scp /tmp/prod.db root@139.155.109.62:/home/novalon/docker-app/novalon-website/data/prod.db +ssh root@139.155.109.62 'cd /home/novalon/docker-app/novalon-website && ls -l data/ && chown 1001:1001 data/prod.db' +docker start novalon-website +``` + +已在本机对**生产库副本**预演通过(2026-10-19):`source=cms issues=0`, +变更范围经逐行比对为 **3 个 ContentModel 行 + 1 个 ContentItem 行(navigation)**, +其余 37 行内容与 13 个模型逐字节不变。 + +> 若不走 §2 而选择跑 `npm run db:seed`:它会把所有 seed 覆盖的内容行一并改回仓库版本, +> 且服务器上必须显式 `SEED_ALLOW_EXTERNAL_DB=1`(seed 沙盒守卫会拦住 `file:/app/data/prod.db`)。**不推荐。** + +## 3. 发布代码 + +- 合 `dev → main` 会触发 Jenkins 的「🚀 部署到生产环境」阶段(`when { branch 'main' }`)—— + 这是一次**无人值守线上发布**,必须由决策人显式发起。 +- 合并方式与 `#29` 一致:`main` 是 `dev` 的严格祖先时用 **fast-forward-only**,保住 sha 可引用。 +- 发布后产物要点:`dist/_next/static` 镜像必须存在(`deploy.sh` 步骤 1.5 会自动生成; + 缺它 = 全站 CSS/JS 404 而 HTML 全 200)。 + +## 4. 发布后核对(全部只读) + +```bash +# 4.1 页面健康 + 关键页面状态码 +for u in / /products /products/erp /solutions /solutions/manufacturing /services /insights /news /contact; do + curl -s -o /dev/null -w "%{http_code} $u\n" https://www.novalon.cn$u; done +# 4.2 服务端不再每请求回退(§2 做过就不该再有) +docker logs --since 10m novalon-website 2>&1 | grep -c '退回代码真源' # 期望 0 +# 4.3 后台能填案例门槛字段(super_admin 登录后看内容编辑表单) +# 期望:caseStudies 每条出现「客户授权展示」与「成果口径」两个字段 +# 4.4 视觉抽查:首页/关于/联系/产品详情各截一张,与 local 基线对比只有内容差异 +``` + +## 5. 回滚 + +- 静态:`dist_backup_`(保留最近 3 份)。 +- 服务端 + 静态:`deploy.sh` 的 `cmd_rollback`(`722f08a` 起会重建容器,避免"旧静态 + 新服务端")。 +- 数据库:`data/prod.db.bak.`;恢复时同样先停容器,再覆盖、再启。 + +## 6. 已知残留(发布不会消除) + +1. `check:motion` 与全站 axe 仍不在 `test:all`(CI 在 Jenkinsfile 单独阶段跑)。 +2. 本地 `core.hooksPath` 指向主检出的 `.husky`,那份仍是 644 ⇒ 本机提交不跑 lint-staged + (索引里已 100755,克隆/检出即生效)。 +3. 视觉基线虽已逐名清单化,但**逐张人工读图追认**仍需决策人分批完成。 diff --git a/scripts/ops/sync-cms-schema.ts b/scripts/ops/sync-cms-schema.ts new file mode 100644 index 0000000..84a6977 --- /dev/null +++ b/scripts/ops/sync-cms-schema.ts @@ -0,0 +1,173 @@ +#!/usr/bin/env node +/** + * CMS 两处数据漂移的最小迁移(默认 dry-run,`--apply` 才写)。 + * + * 为什么不用 `npm run db:seed` 在生产上修: + * seed 会把**所有**被 seed 覆盖的 ContentItem.data 重写回仓库版本, + * 生产里若有人在后台改过文案,会被一起覆盖。这里只动两处已确认的漂移: + * + * 1) `ContentModel.fields`:三处 caseStudies(product / service / standalone-product) + * 缺 `authorized` 与 `basis` 两个子字段 ⇒ 后台填不出来,case-publish-gate 会把所有案例闸住。 + * 口径以 `src/lib/cms/content-types.ts` 为唯一真源(从那里取字段定义,不手抄)。 + * 2) `ContentItem(modelCode='navigation').data`:仍是旧 7 项 IA(products/solutions/services 面板), + * 新代码会每请求「退回代码真源」并打日志。改写成由 `NAVIGATION_V2` + `MEGA_DROPDOWN_DATA` + * 派生出来的形状 —— 只动这一行,其它内容行不碰。 + * + * 自证:写完后用 **真实的 `resolveNavigation`** 跑一遍,要求 `source === 'cms'` 且 `issues` 为空; + * 不成立就退出码 1(绝不"写完就算成功")。dry-run 只打印计划。 + * + * 用法: + * npx tsx scripts/ops/sync-cms-schema.ts --db /path/to/prod.db # dry-run + * npx tsx scripts/ops/sync-cms-schema.ts --db /path/to/prod.db --apply + */ +// 说明:本仓的 @types/node 版本尚未带 `node:sqlite` 的类型声明(TS2307)。 +// 不用 `// @ts-expect-error`(将来类型补上后会因"未使用"反过来报错), +// 改为运行时 require + 本地最小接口 —— 这样既拿到参数化查询,又不需要模块解析。 +import { createRequire } from 'node:module'; +import { CONTENT_TYPE_CONFIGS } from '../../src/lib/cms/content-types'; +import { NAVIGATION_V2, MEGA_DROPDOWN_DATA } from '../../src/lib/constants/navigation'; +import { resolveNavigation } from '../../src/lib/navigation-resolution'; + +interface SqliteStatement { + all(...params: unknown[]): unknown[]; + get(...params: unknown[]): unknown; + run(...params: unknown[]): unknown; +} +interface SqliteDb { + prepare(sql: string): SqliteStatement; + exec(sql: string): void; +} +const nodeRequire = createRequire(import.meta.url); +const { DatabaseSync } = nodeRequire('node:sqlite') as { + DatabaseSync: new (path: string) => SqliteDb; +}; + +const args = process.argv.slice(2); +const dbArg = args[args.indexOf('--db') + 1]; +const apply = args.includes('--apply'); +if (!dbArg || dbArg.startsWith('--')) { + console.error('用法:sync-cms-schema.ts --db [--apply]'); + process.exit(2); +} + +const db = new DatabaseSync(dbArg); +const say = (...a: unknown[]) => console.log(...a); + +// ── 1) ContentModel.fields:补齐 caseStudies 的两个门槛子字段 ────────────── +type SubField = { name: string; [k: string]: unknown }; +const modelRows = db + .prepare(`select code, fields from ContentModel where code in ('product','service','standalone-product')`) + .all() as { code: string; fields: string }[]; + +const modelUpdates: { code: string; next: string; before: string[] }[] = []; +for (const row of modelRows) { + let fields: { name: string; fields?: SubField[] }[]; + try { + fields = JSON.parse(row.fields); + } catch { + console.error(`✗ ${row.code}: fields 不是合法 JSON,拒绝改写`); + process.exit(2); + } + const source = (CONTENT_TYPE_CONFIGS as unknown as Record)[row.code] + ?.model.fields.find((f) => f.name === 'caseStudies'); + if (!source?.fields) { + console.error(`✗ ${row.code}: 代码真源里找不到 caseStudies 定义,拒绝改写`); + process.exit(2); + } + const want = source.fields.filter((f) => f.name === 'authorized' || f.name === 'basis'); + if (want.length !== 2) { + console.error(`✗ ${row.code}: 真源里 caseStudies 缺 authorized/basis,先修 content-types.ts`); + process.exit(2); + } + const beforeNames: string[] = []; + let changed = false; + for (const f of fields) { + if (f.name !== 'caseStudies' || !Array.isArray(f.fields)) continue; + for (const w of want) { + const had = f.fields.some((x) => x.name === w.name); + if (!had) { + f.fields.push(w); + beforeNames.push(`+${w.name}`); + changed = true; + } + } + } + if (changed) modelUpdates.push({ code: row.code, next: JSON.stringify(fields), before: beforeNames }); +} + +// ── 2) navigation 行:改写成由代码真源派生的形状 ──────────────────────────── +const navRow = db + .prepare(`select id, data from ContentItem where modelCode = 'navigation' limit 1`) + .get() as { id: string; data: string } | undefined; + +const derivedNav = { + slug: 'default', + title: '导航菜单', + mainNav: NAVIGATION_V2, + megaDropdown: MEGA_DROPDOWN_DATA, +}; +let navUpdate: { id: string; next: string; beforeLabels: string[]; afterLabels: string[] } | null = null; +if (navRow) { + let before: { mainNav?: { label?: string }[] } = {}; + try { + before = JSON.parse(navRow.data); + } catch { + before = {}; + } + const beforeLabels = (before.mainNav ?? []).map((x) => String(x.label ?? '?')); + const afterLabels = NAVIGATION_V2.map((x) => x.label); + if (JSON.stringify(before) !== JSON.stringify(derivedNav)) { + navUpdate = { id: navRow.id, next: JSON.stringify(derivedNav), beforeLabels, afterLabels }; + } +} else { + say('· navigation 行不存在 ⇒ 跳过(不新建;代码真源已能供数)'); +} + +// ── 3) 自证:用真实解析器验收派生出来的形状 ──────────────────────────────── +const verdict = resolveNavigation(derivedNav); +say(`· 解析器验收:source=${verdict.source} issues=${verdict.issues.length}`); +if (verdict.source !== 'cms' || verdict.issues.length > 0) { + for (const i of verdict.issues) say(` ✗ ${i}`); + console.error('✗ 派生形状未通过 resolveNavigation ⇒ 本次中止(不写库)'); + process.exit(1); +} + +// ── 4) 计划 / 执行 ───────────────────────────────────────────────────────── +say(`· ContentModel 需补字段:${modelUpdates.length} 个(${modelUpdates.map((m) => m.code + ':' + m.before.join(',')).join(' | ') || '无'})`); +if (navUpdate) { + say(`· navigation 行需改写:${navUpdate.beforeLabels.join('/')} → ${navUpdate.afterLabels.join('/')}`); +} else { + say('· navigation 行已是目标形状'); +} + +if (!apply) { + say('\n[dry-run] 未写入。加 --apply 执行。'); + process.exit(0); +} + +const updateModel = db.prepare(`update ContentModel set fields = ?, updatedAt = CURRENT_TIMESTAMP where code = ?`); +const updateNav = db.prepare(`update ContentItem set data = ?, updatedAt = CURRENT_TIMESTAMP where id = ?`); +db.exec('begin'); +try { + for (const m of modelUpdates) updateModel.run(m.next, m.code); + if (navUpdate) updateNav.run(navUpdate.next, navUpdate.id); + db.exec('commit'); +} catch (e) { + db.exec('rollback'); + console.error('✗ 写入失败已回滚:', (e as Error).message); + process.exit(1); +} + +// 写后复查(不是"写完就算") +const checkNav = db.prepare(`select data from ContentItem where modelCode = 'navigation' limit 1`).get() as { data: string } | undefined; +const checkVerdict = checkNav ? resolveNavigation(JSON.parse(checkNav.data)) : verdict; +const checkModels = db + .prepare(`select code, fields from ContentModel where code in ('product','service','standalone-product')`) + .all() as { code: string; fields: string }[]; +const bad = checkModels.filter((r) => !/authorized/.test(r.fields) || !/basis/.test(r.fields)); +say(`\n[applied] models=${checkModels.length} 缺字段=${bad.length} · navigation source=${checkVerdict.source} issues=${checkVerdict.issues.length}`); +if (bad.length > 0 || checkVerdict.source !== 'cms' || checkVerdict.issues.length > 0) { + console.error('✗ 写后复查未通过'); + process.exit(1); +} +say('✓ 写后复查通过');