From f5c999f633925da7bb7898cf8cd411f863160ed8 Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Sun, 11 Oct 2026 10:00:33 +0800 Subject: [PATCH] docs: plan mobile-h5 non-prod env banner implementation Break the approved homepage stripe into TDD tasks for config mapping and the index page UI. Co-authored-by: Cursor --- .../plans/2026-10-11-mobile-h5-env-banner.md | 218 ++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-11-mobile-h5-env-banner.md diff --git a/docs/superpowers/plans/2026-10-11-mobile-h5-env-banner.md b/docs/superpowers/plans/2026-10-11-mobile-h5-env-banner.md new file mode 100644 index 00000000..b35ef640 --- /dev/null +++ b/docs/superpowers/plans/2026-10-11-mobile-h5-env-banner.md @@ -0,0 +1,218 @@ +# mobile-h5 非生产环境首页色条 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 当 `APP_ENV` 为 `local` / `test` 时，在 mobile-h5 首页顶部显示醒目色条，避免误上传非生产包；`prod` 不显示。 + +**Architecture:** 在 `utils/config.js` 抽出纯函数 `buildEnvBanner(appEnv)` 并导出 `ENV_BANNER`；首页 `pages/index/index.vue` 在绿头 Header 之上条件渲染色条。不改其他页面、不做 sticky、不改上传流程。 + +**Tech Stack:** uni-app Vue（mobile-h5）、Node `assert` 单测（与现有 `utils/*.test.js` 一致） + +**Spec:** `docs/superpowers/specs/2026-10-11-mobile-h5-env-banner-design.md` + +--- + +## File structure + +| 文件 | 职责 | +| --- | --- | +| `mobile-h5/utils/config.js` | 增加 `buildEnvBanner`、导出 `ENV_BANNER`；保留现有 `APP_ENV` / presets | +| `mobile-h5/utils/env-banner.test.js` | 覆盖 local / test / prod / 未知值映射 | +| `mobile-h5/pages/index/index.vue` | 条件渲染色条 + scoped 样式 | + +--- + +### Task 1: `buildEnvBanner` 纯函数与单测 + +**Files:** +- Modify: `mobile-h5/utils/config.js` +- Create: `mobile-h5/utils/env-banner.test.js` + +- [ ] **Step 1: 先写失败单测** + +创建 `mobile-h5/utils/env-banner.test.js`： + +```js +import assert from 'node:assert/strict' +import { buildEnvBanner } from './config.js' + +assert.deepEqual(buildEnvBanner('local'), { + show: true, + label: '本地环境', + tone: 'local' +}) +assert.deepEqual(buildEnvBanner('test'), { + show: true, + label: '测试环境', + tone: 'test' +}) +assert.deepEqual(buildEnvBanner('prod'), { + show: false, + label: '', + tone: '' +}) +assert.deepEqual(buildEnvBanner('unknown'), { + show: false, + label: '', + tone: '' +}) + +console.log('env-banner.test.js: ok') +``` + +- [ ] **Step 2: 跑测试确认失败** + +Run: + +```bash +cd mobile-h5 && node utils/env-banner.test.js +``` + +Expected: FAIL（`buildEnvBanner` 未导出 / 未定义） + +- [ ] **Step 3: 实现 `buildEnvBanner` 与 `ENV_BANNER`** + +在 `mobile-h5/utils/config.js` 末尾（现有导出之后）增加： + +```js +/** 首页非生产环境色条描述（prod / 未知值不展示） */ +export function buildEnvBanner(appEnv) { + if (appEnv === 'local') { + return { show: true, label: '本地环境', tone: 'local' } + } + if (appEnv === 'test') { + return { show: true, label: '测试环境', tone: 'test' } + } + return { show: false, label: '', tone: '' } +} + +export const ENV_BANNER = buildEnvBanner(APP_ENV) +``` + +不要改动 `ENV_PRESETS` 与现有 URL 导出逻辑。若当前 `APP_ENV` 为本地联调值可保持不动（本任务不强制改回 `prod`）。 + +- [ ] **Step 4: 跑测试确认通过** + +Run: + +```bash +cd mobile-h5 && node utils/env-banner.test.js +``` + +Expected: 打印 `env-banner.test.js: ok`，exit code 0 + +- [ ] **Step 5: Commit** + +```bash +git add mobile-h5/utils/config.js mobile-h5/utils/env-banner.test.js +git commit -m "$(cat <<'EOF' +feat(mobile-h5): export ENV_BANNER from APP_ENV + +Add buildEnvBanner so the homepage can show a non-prod +stripe without hardcoding environment labels. +EOF +)" +``` + +--- + +### Task 2: 首页顶部色条 UI + +**Files:** +- Modify: `mobile-h5/pages/index/index.vue` + +- [ ] **Step 1: 模板插入色条** + +在 `` 内、`` **之前**插入： + +```html + + {{ envBanner.label }} + +``` + +- [ ] **Step 2: script 引入并挂到 data/computed** + +在 script 顶部增加： + +```js + import { ENV_BANNER } from '../../utils/config.js' +``` + +在 `data()` 中增加（或使用 computed，二选一；推荐 data 常量即可）： + +```js + envBanner: ENV_BANNER, +``` + +- [ ] **Step 3: scoped 样式** + +在现有 `