Files
perler-lab/docs/RELEASE-V1.1.md
T

13 KiB
Raw Blame History

PERLER LAB V1.1 发布计划(RELEASE-V1.1)

版本: v1.0 · 文档编号: RELEASE-V1.1 · 关联任务: T-111 角色: Release-Manager · 日期: 2026-08-14 上游依据: RELEASE-PIPELINE.md(发布流水线)、LAUNCH.md(SEO/上线)、NAV-ALIGNMENT.md(导航对齐)、ROADMAP.md(V1.1 增长版)、CI-GATES.md(质量门禁)、DEPLOY.md(部署) 当前基线: V1.0 已发布(70 任务验收通过),V1.1 批次 T-091~T-111 共 21 个任务 + BUG-112 并行开发中


0. 结论速览

维度 结果
V1.1 主题 导航对齐(NAV-ALIGNMENT P0/P1)+ 色号表 SEO 页 + Showcase + 图纸库 + 帮助中心 + 评估类文档
范围条目数 22 条(21 任务 + BUG-112),其中代码交付 14 条、文档交付 8 条
里程碑 M1 前端页面 → M2 后端接口 → M3 集成联调 → M4 发布(M1/M2 可并行)
发布方式 沿用 RELEASE-PIPELINE.md:验收 → auto-commit 自动提交 → gitflow.js push master → CI(deploy.yml)→ 部署
阻塞点 T-096 不合格 → BUG-112 修复中;T-110 部署核对、T-109 CI 门禁为发布前置
回滚手段 git revert 重新推送;Docker 镜像回退上一版本;SQLite 备份还原

1. V1.1 范围清单

交付类型标注:[代码] = 源码/构建/CI 交付(进 git 与生产),[文档] = 决策/评估/文案文档交付(进 docs/,作为代码交付的依据或内容源)。

# 工作项 关联任务 交付类型 当前状态 说明
1 色号表页:六品牌页面组件实现 T-091 [代码] 待验收 ColorChartPage.tsx + CSS,tab 切换 + 表格 + URL 品牌段 + i18n + 响应式
2 色号表页:数据层接入 T-092 [代码] 待验收 color-chart-data.ts,六品牌聚合(221/174/103/92/18/30 色)
3 色号表页:路由注册 T-093 [代码] 待验收 /color-chart 与 /color-chart/:brand,未知品牌回退 MARD
4 色号表页:JSON-LD 结构化数据 T-094 [代码] 待验收 GET /api/color-chart/:brand,CollectionPage+ItemList schema
5 色号表页:内链与导航入口 T-095 [代码] 开发中 首页/页脚内链 + 导航入口,吃「拼豆色号表」长尾词
6 色号表页:SEO 标题与描述 T-096 [文档] 不合格 → BUG-112 修复中 SEO-COLORCHARTS.md 六品牌 zh+en title/description,BUG-112 重做
7 Showcase:作品展示页路由与布局 T-097 [代码] 待验收 /showcase 路由 + 响应式卡片网格(4/3/2/1 列)
8 Showcase:作品卡片与标签筛选 T-098 [代码] 待验收 WorkCard 组件 + 分类筛选,种子数据 lib/showcase.ts
9 Showcase:发布保存接口 T-099 [代码] 待验收 POST /api/showcase/works,showcase_works 表 + 校验(DB schema 变更)
10 Showcase:列表查询接口 T-100 [代码] 待验收 GET /api/showcase/works 分页 + 标签/来源筛选
11 Showcase:SEO 元数据接口 T-101 [代码] 待验收 GET /api/showcase/meta,title/description/ogImage/jsonLd
12 Showcase:发布流程前端接入 T-102 [代码] 待验收 ChibiPage 发布入口 + publishShowcaseWork
13 图纸库:列表页组件与路由 T-108 [代码] 待验收 /library 路由,复用 showcase 数据源,空态兜底
14 帮助中心:FAQ 页面组件 T-106 [代码] 开发中 /help 路由,单页 FAQ 区块
15 帮助中心:FAQ 数据整理 T-107 [文档] 验收通过 FAQ-DATA.md 35 条双语言,供 T-106 渲染
16 PWA 接入评估 T-105 [文档] 开发中 manifest 与离线缓存方案评估,产出评估结论供 V2.0 立项
17 i18n 扩展评估(zh-tw/ja) T-103 [文档] 待验收 I18N-ROI.md:zh-tw 建议落地、ja 建议暂缓
18 商业模式细化文档 T-104 [文档] 待验收 BUSINESS-MODEL.md:免费 12 项 / 付费 9 项边界
19 CI 门禁:新页面构建检查 T-109 [代码] 开发中 deploy.yml 覆盖色号表/Showcase/图纸库/帮助路由构建
20 部署核对:路由与静态资源 T-110 [代码] 开发中 nginx SPA fallback + 静态资源部署配置核对
21 发布计划:V1.1 里程碑 T-111 [文档] 开发中(本文档) 里程碑/范围/门禁/发布步骤/回滚
22 BUG 修复:色号表 SEO 元数据 BUG-112 [文档] 开发中 T-096 验收不合格的返工任务

统计:代码交付 14 条(#15、714、1920),文档交付 8 条(#6、1518、21~22)。

1.1 范围边界(本批次不含)

  • T-065 BFS 杂色清理、T-085 leafer.js 渲染引擎评估:V1.0 遗留/独立评估任务,不在 T-091~T-111 发布闸门内,不阻塞 V1.1 发布。
  • 导航对齐 P2 项(/chibi?cat= 深链、帮助子页化):NAV-ALIGNMENT 定义为 P2 按需,V1.1 不承诺交付,随数据进入后续版本。
  • 客户端(apps)、拼豆创作独立页:NAV-ALIGNMENT 决策为「不做 / 暂缓」,不在范围内。
  • 批量生成、导出优化、埋点看板、历史记录:ROADMAP V1.1 远期功能,未进入本批次,后续迭代。

2. 里程碑阶段划分

M1/M2 互不依赖可并行;M3 依赖 M1+M2 基本就绪;M4 依赖 M3 全绿。

M1 前端页面(对应 NAV-ALIGNMENT P0/P1 页面跟上)

任务 交付物
T-091/T-092/T-093 色号表页组件 + 数据层 + 路由
T-095 色号表内链与导航入口
T-097/T-098 Showcase 页面 + 作品卡片
T-106 帮助中心 FAQ 页面
T-108 图纸库页面

出口条件:五个新路由(/color-chart、/showcase、/library、/help + 品牌子路由)全部可达;导航 7 项真实跳转,无「建设中」占位残留(NAV-ALIGNMENT §3.3 P1 撤下占位)。

M2 后端接口

任务 交付物
T-094 JSON-LD 结构化数据接口
T-099 Showcase 发布保存接口(含 schema 变更)
T-100 Showcase 列表查询接口
T-101 Showcase SEO 元数据接口

出口条件:4 个新端点契约对齐;showcase_works 表迁移对旧库平滑(新增表不影响既有表);npm test 全绿。

M3 集成联调

任务 交付物
T-102 Showcase 发布流程前端接入(端到端:发布 → 落库 → 列表展示)
T-109 CI 门禁覆盖新页面构建检查
T-110 部署核对:路由 fallback + 静态资源
文档类 T-096/BUG-112、T-103、T-104、T-105、T-107 全部验收通过

出口条件:发布→列表全链路可用;本地 npm run build + npm run typecheck + npm test 全绿;node taskboard.js list 无 V1.1 任务处于「不合格」状态。

M4 发布

动作 负责人
全量验收复核 QA-Tester-Agent
推送 master 触发 CI GitOps-Engineer
部署与健康检查 DevOps-Engineer
线上冒烟(新页面可达 + 导航跳转) 主代理 / QA
版本号与文档归档 Release-Manager(T-111)

3. 验收门禁(QA 验收条件)

每任务经 node taskboard.js test <id> --pass/--fail 验收;下述条件为 V1.1 放行闸门,全部满足才进入 M4。门禁细则以 CI-GATES.md G1~G9 为准。

G-API 代码门禁

  • typecheck:npm run typecheck(perler-lab 与 perler-lab-server 两端),tsc --noEmit 0 错误,strict 开启(CI-GATES G3)。
  • 单测:npm test 前后端全部通过,退出码 0(CI-GATES G1/G2,基线前端 147+ 后端 121+,当前批注实测前端 176/后端 156 用例全过)。
  • 构建:npm run build(vite build)产出 dist/ 成功(CI-GATES G4)。
  • CI 冒烟:T-109 落地后,push 触发 deploy.yml 三阶段(test → build → deploy)全程绿(G7 并发保护、G8 超时、G9 YAML 有效)。

G-PAGE 页面可达门禁

  • 五个新路由 HTTP 可达,SPA 刷新/直链不 404(nginx try_files fallback 由 T-110 核对)。
  • 导航 7 项点击均落在真实页面(NAV-ALIGNMENT §5 教训:不允许「字典有、页面无」的悬空链接)。
  • 移动端 <1024px 抽屉含「工具」组且无横向溢出;底部固定 CTA 保留可见。
  • JSON-LD:/color-chart 与 /showcase 源码含 application/ld+json 脚本(CollectionPage/WebPage schema)。
  • 未知品牌路由回退 MARD 不白屏;Showcase 空态兜底正常。

G-DOC 文档门禁

  • SEO-COLORCHARTS.md(BUG-112):六品牌 zh+en title/description 全量覆盖、长度合规、URL slug 无冲突。
  • I18N-ROI.md、BUSINESS-MODEL.md、PWA 评估(T-105)结论明确且与 PRD/LAUNCH 定价无冲突。
  • FAQ-DATA.md 与 /help 页面渲染文案一致。

4. 发布步骤(git flow,沿用 RELEASE-PIPELINE.md)

验收通过 ──▶ auto-commit.js 自动提交 ──▶ gitflow.js push master ──▶ CI(deploy.yml) ──▶ 部署验证
  (test --pass)     (git add -A + commit)      (人工闸门)            (test→build→deploy)

步骤 1:验收

  • QA 对 22 条任务逐条 node taskboard.js test <id> --pass/--fail,状态进入 approved / rejected(不合格自动生成 Bug,如 BUG-112)。

步骤 2:自动提交(Release-Manager 管道)

  • auto-commit.js 常驻轮询,检测到新 approved 任务后执行 git add -A + git commit -m "[验收通过] <id> <标题>"(RELEASE-PIPELINE §3)。
  • 提交记录入 auto-commit.log;工作区无改动则跳过,不产生空提交。

步骤 3:推送 master(人工闸门,GitOps 工程师)

node gitflow.js push        # 或 git push -u origin master
  • ⚠️ push 是对外发布动作,必须人工确认后执行(RELEASE-PIPELINE §4)。确认项:auto-commit.log 无失败重试、git status 无遗漏改动、V1.1 无不合格任务残留。

步骤 4:CI(push 触发,自动)

  • push 触发 .github/workflows/deploy.yml:test(前端+后端矩阵)→ build(Docker 镜像)→ deploy(SSH,需 Secrets 已配置,未配置自动跳过)。
  • 任一 job 失败:查看 Actions 日志 → 修复 → 重新推送(CI-GATES §7 故障处理)。

步骤 5:部署与验证(DevOps 工程师)

  • 生产 docker compose -f perler-lab-server/docker-compose.yml up -d --build,健康检查 3 次失败自动重启兜底(DEPLOY.md)。
  • 线上冒烟:/color-chart、/showcase、/library、/help 直达 200;导航 7 项逐一点击;生成→发布→列表主链路走一遍。
  • 数据库:showcase_works 新表自动建表成功(无迁移脚本残留),既有数据完好。

步骤 6:归档

  • 更新 ROADMAP.md 状态;auto-commit.log 存档;确认 V1.1 全部任务 approved,无遗留 in_progress。

5. 风险与回滚

# 风险 等级 对策 回滚手段
1 新路由 SPA 直链 404(nginx fallback 未配) 高 T-110 部署核对前置,压测直链刷新 revert fallback 配置提交并重新部署
2 showcase_works 建表失败 / schema 冲突 高 M2 验收含旧库兼容测试,T-099 单测覆盖建表 保留部署前 SQLite 备份(DEPLOY.md 备份机制),还原后重启
3 色号表 SEO 质量不达标(T-096 已返工) 中 BUG-112 全量重做六品牌 zh/en,QA 按长度/覆盖度复核 本项为文档交付,不影响代码,延后合入不阻塞构建
4 CI 门禁新增后构建炸裂 中 T-109 本地先验证 deploy.yml,push 前 npm run build 自检 git revert 该提交 → 重新 push,Docker 回退上一镜像版本
5 i18n 新 key 缺失致 Messages 类型错误 低 en.ts 受类型约束强制键全等(编译期拦截,NAV-ALIGNMENT P0-2) typecheck 阶段即拦截,不会进生产
6 Showcase 发布接口被滥用(base64 注入) 中 T-099 已做长度/格式/标签白名单校验 + 频控 线上观察 publish 失败率,超阈值关停入口,回滚提交
7 导航改造回归(占位残留 / 移动端溢出) 中 M1 出口条件强制检查 7 项真实跳转 + 抽屉无溢出 保留导航改造前提交点,revert 后重新推送

通用回滚流程(RELEASE-PIPELINE §5/§7):

  1. git log --oneline -10 定位问题提交 → git revert <hash> → node gitflow.js push 重新触发 CI。
  2. 生产 Docker 回退:docker compose up -d 前将镜像 tag 指回上一版本,或从备份还原 volume。
  3. 数据库回滚:优先使用部署前 .backup 还原(WAL 模式下用 sqlite3 .backup 命令而非直接拷贝,DEPLOY.md 明确要求)。

文档完。范围与状态以 taskboard.js 实时看板为准,本计划为 V1.1 发布基线。