191 lines
13 KiB
Markdown
191 lines
13 KiB
Markdown
# 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 发布基线。*
|