blog-demo · 运维与踩坑

仓库维护与发布

Git 保留边界、内容维护、验证强度和版本发布规则。

状态
维护中
最后核对
源码修订
e0d3baa2

仓库维护与发布

什么应该进入 Git

保留 原因
src/、studio/、维护中的 scripts/ 网站与本地编辑器的实现
Markdown 与压缩后的内容图片 发布内容的原始输入，可追溯和恢复
package.json、package-lock.json、.nvmrc 依赖可复现，Node 主版本与 CI 一致
tests/visual/baseline/ 经审阅的视觉期望，不是随手截图
src/fonts/paper-serif.woff2、subset.txt、许可 下载失败时也能构建；生成字体及其字表一起维护
src/data/stocks.json、market.json 上游不可用时可读取的已保存快照，必须保留真实时间和状态
public/ 的图标、分享图片 生产页面使用的资源
项目设计约定和维护文档 供未来开发者及工具理解项目

.gitignore 排除依赖、dist/、.astro/、实际截图、测试报告、日志、.env、机器上的编辑器配置和本地工具目录。 CHANGELOG.md 由 Git 历史生成，不再追踪。需要临时实验时使用仓库外目录或已忽略的 local-tools/，不要把硬编码机器路径的脚本塞进公共工具目录。

不要因为文件是二进制或由工具生成就一概删除。字体子集和视觉基线是刻意保留的构建输入；完整字体缓存和本次截图结果才是本地产物。

旧版一次性截图脚本已由 scripts/visual-shot.mjs 覆盖。早期架构决策保存在 docs/archive/，标明历史状态，当前字段以代码和内容指南为准。

修改与提交

日常协作与验证顺序见开发工作流。

  1. UI 修改先读根目录 .better-web-ui.md，设计默认值变化时同步 AGENTS.md 的设计上下文。
  2. 源码沿用 Astro 与原生 CSS；内部链接使用 import.meta.env.BASE_URL，不要写死根路径。
  3. ClientRouter 下的页面脚本使用 src/scripts/init.ts 的 onPageReady / markReady，避免重复监听，离开页面时释放需要清理的资源。
  4. 用 git status --short、git diff 审查改动，再按具体文件暂存。内容、功能、修复、测试、仓库维护与文档分别使用有意义的提交。
  5. 提交前检查 git diff --cached 与 git diff --check。推荐现有的 content:、feat:、fix:、test:、chore:、docs: 前缀。

Studio 的“提交”只处理 src/content/、src/data/editorial.json 与 src/data/now.json，不会夹带其他已暂存代码。“版本与推送”只把已提交版本推到 main，不构建生产制品，也不查询或改变线上状态。

验证与部署

日常改动按影响验证，不默认运行完整发布套件。普通 main 推送只由 CI 执行 npm ci、npm run check 和 npm run test:unit；纯维护文档没有命中构建输入时不触发 CI。

版本可以在 prepare 阶段经历多轮方案评审和局部检查。只有作者明确批准开始全面复核后，才冻结稳定 SemVer 候选并运行完整生产门禁；获批后若范围变化，退回 prepare 重新评审。

SITE_URL=https://www.doyouhang.live SITE_BASE=/ npm run build
SITE_URL=https://www.doyouhang.live SITE_BASE=/ SMOKE_PORT=4351 npm run test:smoke
npm run test:studio -- --capture-only
npm run test:collections

UI 版本另补视觉回归或截图取证。浏览器默认使用 Microsoft Edge；需要覆盖自动发现路径时按根目录 README 设置 BROWSER_PATH。

git push origin main 不发布网站。版本工作流只接受稳定标签，校验 package.json 与 docs/releases/vX.Y.Z.md 后运行完整门禁并生成 ECS 制品；它不会连接服务器。制品经人工审阅后按ECS 运维手册部署。不要提交 dist/、Release 归档或镜像包。

轻量 CI 失败时修复后新建提交；发布门禁失败时不得部署该版本，修复后使用新提交重新冻结标签。若确需恢复源码变更，使用经审阅的反向提交，保留历史，不通过强推重写 main。

行情数据

npm run fetch:all 依次调用市场与自选股抓取脚本；构建和 Release 工作流都不会自动抓行情。

  • 自选清单在 src/data/stocks.watchlist.json，按现有 secid、代码和名称结构维护。增删后失败回退也会按清单重排。
  • 指数配置在 scripts/fetch-market.mjs，板块清单在 src/data/sectors.list.json；需要时手动运行 npm run refresh:sectors。刷新脚本会拒绝覆盖不完整清单。
  • 行情使用东方财富接口；脚本重试失败后使用保存的数据并标记状态，没有可用记录时使用明确标识的占位。指数和板块分别处理失败。
  • 页面分别标注自选、指数、板块保存时间，超过 72 小时提示数据年龄；这不是交易日或收盘时刻判断。
  • “水温”来自上涨板块占上涨与下跌板块的比例，不是全市场个股涨跌家数。
  • 生产版本只使用仓库内已经核验并提交的快照，确保版本可重建；不能把旧快照描述为刚刚刷新。

手动确认快照质量后可以专门提交数据更新。不要为了让状态看起来更新而改日期；更稳定的供应商和多来源回退仍是后续工作。现有 Probe quote sources 手动工作流用于诊断 runner 的来源可达性，不发布网站。

常用工具

命令 用途
npm run fonts 更新字体子集，构建前也会执行
npm run fetch:all 更新本地行情快照
npm run refresh:sectors 手动维护板块清单
npm run changelog 生成本地变更记录
npm run test:unit 内容、数据、编辑器及提交隔离测试
npm run test:smoke 已构建站点的交互与跨页检查
npm run test:visual 比对 32 组视觉基线
npm run test:visual:update 保存经审阅的新基线

分享图片配置在 src/consts.ts；scripts/gen-assets.mjs 是图标与分享资源生成工具，运行前检查其输出位置和浏览器设置，生成的生产资源需要审阅后提交。