# 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 条(#1~5、7~14、19~20),文档交付 8 条(#6、15~18、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 --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 --pass/--fail`,状态进入 `approved` / `rejected`(不合格自动生成 Bug,如 BUG-112)。 ### 步骤 2:自动提交(Release-Manager 管道) - `auto-commit.js` 常驻轮询,检测到新 `approved` 任务后执行 `git add -A` + `git commit -m "[验收通过] <标题>"`(RELEASE-PIPELINE §3)。 - 提交记录入 `auto-commit.log`;工作区无改动则跳过,不产生空提交。 ### 步骤 3:推送 master(人工闸门,GitOps 工程师) ```bash 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 ` → `node gitflow.js push` 重新触发 CI。 2. 生产 Docker 回退:`docker compose up -d` 前将镜像 tag 指回上一版本,或从备份还原 volume。 3. 数据库回滚:优先使用部署前 `.backup` 还原(WAL 模式下用 `sqlite3 .backup` 命令而非直接拷贝,DEPLOY.md 明确要求)。 --- *文档完。范围与状态以 taskboard.js 实时看板为准,本计划为 V1.1 发布基线。*