13 KiB
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 --noEmit0 错误,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_filesfallback 由 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):
git log --oneline -10定位问题提交 →git revert <hash>→node gitflow.js push重新触发 CI。- 生产 Docker 回退:
docker compose up -d前将镜像 tag 指回上一版本,或从备份还原 volume。 - 数据库回滚:优先使用部署前
.backup还原(WAL 模式下用sqlite3 .backup命令而非直接拷贝,DEPLOY.md 明确要求)。
文档完。范围与状态以 taskboard.js 实时看板为准,本计划为 V1.1 发布基线。