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

191 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <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 工程师)
```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 <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 发布基线。*