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 <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed
1 parent
8c82f6a6dd
commit
f5c999f633
1 file changed
+218
@@ -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: 模板插入色条**
|
||||
|
||||
在 `<view class="page-shell">` 内、`<view class="home-header">` **之前**插入：
|
||||
|
||||
```html
|
||||
<view
|
||||
v-if="envBanner.show"
|
||||
class="env-banner"
|
||||
:class="'env-banner--' + envBanner.tone"
|
||||
>
|
||||
<text class="env-banner__text">{{ envBanner.label }}</text>
|
||||
</view>
|
||||
```
|
||||
|
||||
- [ ] **Step 2: script 引入并挂到 data/computed**
|
||||
|
||||
在 script 顶部增加：
|
||||
|
||||
```js
|
||||
import { ENV_BANNER } from '../../utils/config.js'
|
||||
```
|
||||
|
||||
在 `data()` 中增加（或使用 computed，二选一；推荐 data 常量即可）：
|
||||
|
||||
```js
|
||||
envBanner: ENV_BANNER,
|
||||
```
|
||||
|
||||
- [ ] **Step 3: scoped 样式**
|
||||
|
||||
在现有 `<style lang="scss" scoped>` 中追加：
|
||||
|
||||
```scss
|
||||
.env-banner {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
width: 100%;
|
||||
padding: 12rpx 24rpx;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
.env-banner__text {
|
||||
font-size: 22rpx;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.04em;
|
||||
line-height: 1.3;
|
||||
}
|
||||
|
||||
.env-banner--local {
|
||||
background: #f59e0b;
|
||||
color: #451a03;
|
||||
}
|
||||
|
||||
.env-banner--test {
|
||||
background: #3b82f6;
|
||||
color: #eff6ff;
|
||||
}
|
||||
```
|
||||
|
||||
色条不加 status-bar 额外占位；安全区仍由现有 `.home-header` padding 处理。
|
||||
|
||||
- [ ] **Step 4: 手工验收清单**
|
||||
|
||||
1. `APP_ENV='local'` → 首页顶栏橙色「本地环境」
|
||||
2. `APP_ENV='test'` → 首页顶栏蓝色「测试环境」
|
||||
3. `APP_ENV='prod'` → 无色条
|
||||
4. 登录页 / OA 列表无色条
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add mobile-h5/pages/index/index.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(mobile-h5): show non-prod env stripe on home
|
||||
|
||||
Render a short local/test banner above the green header
|
||||
so the active APP_ENV is obvious before WeChat upload.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Spec coverage check
|
||||
|
||||
| Spec 要求 | Task |
|
||||
| --- | --- |
|
||||
| local/test 显示、prod 不显示 | Task 1 + 2 |
|
||||
| 仅首页、Header 之上、非 sticky | Task 2 |
|
||||
| 文案「本地环境」「测试环境」 | Task 1 |
|
||||
| 配色琥珀 / 蓝 | Task 2 |
|
||||
| `ENV_BANNER` 导出、页面不硬编码文案 | Task 1 + 2 |
|
||||
| 不加 status-bar 双重顶距 | Task 2 样式说明 |
|
||||
| 单测映射 | Task 1 |
|
||||
Reference in new issue
Block a user