From 8c82f6a6dd71482fba38200460f2c4cc7817eefe Mon Sep 17 00:00:00 2001
From: zlwu <704541015@qq.com>
Date: Sun, 11 Oct 2026 09:59:51 +0800
Subject: [PATCH] docs: add mobile-h5 non-prod env banner design

Capture the approved homepage top-stripe approach so local/test
builds are visually distinct before WeChat upload.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/demos/mobile-h5-env-badge-demo.html      | 351 ++++++++++++++++++
 .../2026-10-11-mobile-h5-env-banner-design.md |  80 ++++
 2 files changed, 431 insertions(+)
 create mode 100644 docs/demos/mobile-h5-env-badge-demo.html
 create mode 100644 docs/superpowers/specs/2026-10-11-mobile-h5-env-banner-design.md

diff --git a/docs/demos/mobile-h5-env-badge-demo.html b/docs/demos/mobile-h5-env-badge-demo.html
new file mode 100644
index 00000000..ac86c877
--- /dev/null
+++ b/docs/demos/mobile-h5-env-badge-demo.html
@@ -0,0 +1,351 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>mobile-h5 环境标识 Demo</title>
+  <style>
+    :root {
+      --bg: #f1f5f9;
+      --card: #ffffff;
+      --text: #0f172a;
+      --muted: #64748b;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: "PingFang SC", "Helvetica Neue", system-ui, sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      padding: 28px 20px 48px;
+    }
+    h1 {
+      margin: 0 0 8px;
+      font-size: 22px;
+      text-align: center;
+    }
+    .subtitle {
+      text-align: center;
+      color: var(--muted);
+      font-size: 14px;
+      margin: 0 0 20px;
+    }
+    .env-toggle {
+      display: flex;
+      gap: 8px;
+      justify-content: center;
+      margin-bottom: 24px;
+    }
+    .env-toggle button {
+      border: 1px solid #cbd5e1;
+      background: #fff;
+      border-radius: 999px;
+      padding: 8px 16px;
+      font-size: 13px;
+      cursor: pointer;
+    }
+    .env-toggle button.active {
+      border-color: #059669;
+      background: #ecfdf5;
+      color: #065f46;
+      font-weight: 650;
+    }
+    .cards {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 20px;
+      justify-content: center;
+      max-width: 1100px;
+      margin: 0 auto;
+    }
+    .card {
+      width: 300px;
+      background: var(--card);
+      border-radius: 16px;
+      border: 1px solid #e2e8f0;
+      overflow: hidden;
+      box-shadow: 0 8px 24px rgba(15, 23, 42, 0.06);
+    }
+    .card-image {
+      padding: 16px;
+      background: #f8fafc;
+    }
+    .card-body {
+      padding: 14px 16px 18px;
+    }
+    .card-body h3 {
+      margin: 0 0 6px;
+      font-size: 15px;
+    }
+    .card-body p {
+      margin: 0;
+      font-size: 13px;
+      color: var(--muted);
+      line-height: 1.5;
+    }
+    .phone {
+      width: 100%;
+      border-radius: 28px;
+      overflow: hidden;
+      border: 2px solid #1e293b;
+      background: #f0fdf4;
+      box-shadow: 0 12px 32px rgba(15, 41, 30, 0.18);
+    }
+    .phone-rel { position: relative; }
+    .status-bar {
+      height: 28px;
+      background: linear-gradient(135deg, #10b981, #059669);
+    }
+    .header {
+      background: linear-gradient(135deg, #10b981 0%, #059669 100%);
+      color: #ecfdf5;
+      padding: 14px 16px 18px;
+    }
+    .brand-row {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 8px;
+      margin-bottom: 8px;
+    }
+    .brand {
+      font-size: 11px;
+      opacity: 0.78;
+      letter-spacing: 0.04em;
+    }
+    .hello {
+      font-size: 20px;
+      font-weight: 700;
+    }
+    .meta {
+      margin-top: 8px;
+      display: flex;
+      justify-content: space-between;
+      font-size: 11px;
+      opacity: 0.82;
+    }
+    .logout {
+      border: 1px solid rgba(6, 95, 70, 0.35);
+      border-radius: 6px;
+      padding: 2px 8px;
+      color: #065f46;
+      background: rgba(236, 253, 245, 0.35);
+    }
+    .body { padding: 12px; }
+    .banner {
+      height: 72px;
+      border-radius: 12px;
+      background: linear-gradient(120deg, #86efac, #34d399);
+      margin-bottom: 10px;
+    }
+    .panel {
+      background: #fff;
+      border-radius: 14px;
+      padding: 12px;
+      border: 1px solid #d1fae5;
+    }
+    .panel-title {
+      font-size: 13px;
+      font-weight: 650;
+      color: #0f291e;
+      margin-bottom: 10px;
+    }
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(4, 1fr);
+      gap: 8px;
+    }
+    .cell {
+      aspect-ratio: 1;
+      border-radius: 10px;
+      background: #ecfdf5;
+      border: 1px solid #bbf7d0;
+    }
+    .badge {
+      display: inline-flex;
+      align-items: center;
+      font-size: 10px;
+      font-weight: 700;
+      padding: 3px 8px;
+      border-radius: 999px;
+      line-height: 1.2;
+      white-space: nowrap;
+    }
+    .badge.local {
+      background: #fef3c7;
+      color: #92400e;
+      border: 1px solid #f59e0b;
+    }
+    .badge.test {
+      background: #dbeafe;
+      color: #1e40af;
+      border: 1px solid #3b82f6;
+    }
+    .stripe {
+      text-align: center;
+      font-size: 11px;
+      font-weight: 700;
+      padding: 6px 10px;
+      letter-spacing: 0.04em;
+    }
+    .stripe.local {
+      background: #f59e0b;
+      color: #451a03;
+    }
+    .stripe.test {
+      background: #3b82f6;
+      color: #eff6ff;
+    }
+    .float-badge {
+      position: absolute;
+      right: 10px;
+      bottom: 14px;
+      box-shadow: 0 4px 14px rgba(0,0,0,0.18);
+    }
+    .note {
+      max-width: 720px;
+      margin: 28px auto 0;
+      font-size: 13px;
+      color: var(--muted);
+      text-align: center;
+      line-height: 1.6;
+    }
+  </style>
+</head>
+<body>
+  <h1>mobile-h5 环境标识 Demo</h1>
+  <p class="subtitle">仅 local / test 显示；prod 完全无标识。可切换下方配色预览。</p>
+
+  <div class="env-toggle">
+    <button type="button" class="active" data-env="local" onclick="setDemoEnv('local')">本地 local</button>
+    <button type="button" data-env="test" onclick="setDemoEnv('test')">测试 test</button>
+  </div>
+
+  <div class="cards">
+    <div class="card">
+      <div class="card-image">
+        <div class="phone">
+          <div class="status-bar"></div>
+          <div class="header">
+            <div class="brand-row">
+              <div class="brand">中科兴皖 · 移动工作台</div>
+              <span class="badge local demo-env-badge">本地</span>
+            </div>
+            <div class="hello">您好，张三</div>
+            <div class="meta">
+              <span>市场经理 · 合肥</span>
+              <span class="logout">退出登录</span>
+            </div>
+          </div>
+          <div class="body">
+            <div class="banner"></div>
+            <div class="panel">
+              <div class="panel-title">功能菜单</div>
+              <div class="grid">
+                <div class="cell"></div><div class="cell"></div>
+                <div class="cell"></div><div class="cell"></div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+      <div class="card-body">
+        <h3>A · 首页标题旁角标</h3>
+        <p>只在首页绿头区右侧显示「本地/测试」。轻量；离开首页后看不到。</p>
+      </div>
+    </div>
+
+    <div class="card">
+      <div class="card-image">
+        <div class="phone">
+          <div class="status-bar"></div>
+          <div class="stripe local demo-env-stripe">⚠ 本地联调环境 · 勿上传正式版</div>
+          <div class="header">
+            <div class="brand-row">
+              <div class="brand">中科兴皖 · 移动工作台</div>
+            </div>
+            <div class="hello">您好，张三</div>
+            <div class="meta">
+              <span>市场经理 · 合肥</span>
+              <span class="logout">退出登录</span>
+            </div>
+          </div>
+          <div class="body">
+            <div class="banner"></div>
+            <div class="panel">
+              <div class="panel-title">功能菜单</div>
+              <div class="grid">
+                <div class="cell"></div><div class="cell"></div>
+                <div class="cell"></div><div class="cell"></div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+      <div class="card-body">
+        <h3>B · 顶部醒目色条（推荐）</h3>
+        <p>整页顶部固定色条 + 文案。一眼能辨认，上传前最不易漏看。</p>
+      </div>
+    </div>
+
+    <div class="card">
+      <div class="card-image">
+        <div class="phone phone-rel">
+          <div class="status-bar"></div>
+          <div class="header">
+            <div class="brand-row">
+              <div class="brand">中科兴皖 · 移动工作台</div>
+            </div>
+            <div class="hello">您好，张三</div>
+            <div class="meta">
+              <span>市场经理 · 合肥</span>
+              <span class="logout">退出登录</span>
+            </div>
+          </div>
+          <div class="body">
+            <div class="banner"></div>
+            <div class="panel">
+              <div class="panel-title">功能菜单</div>
+              <div class="grid">
+                <div class="cell"></div><div class="cell"></div>
+                <div class="cell"></div><div class="cell"></div>
+              </div>
+            </div>
+          </div>
+          <span class="badge local float-badge demo-env-badge">本地</span>
+        </div>
+      </div>
+      <div class="card-body">
+        <h3>C · 全局角落浮标</h3>
+        <p>所有页面右下角常驻小标签。跨页可见，但可能与底部按钮重叠。</p>
+      </div>
+    </div>
+  </div>
+
+  <p class="note">
+    配色约定：本地 = 琥珀橙；测试 = 蓝色；生产 = 不显示任何标识。<br />
+    打开交互版可选方案：<code>http://localhost:60039</code>
+  </p>
+
+  <script>
+    function setDemoEnv(env) {
+      document.querySelectorAll('.env-toggle button').forEach(function (btn) {
+        btn.classList.toggle('active', btn.getAttribute('data-env') === env)
+      })
+      var isLocal = env === 'local'
+      document.querySelectorAll('.demo-env-badge').forEach(function (el) {
+        el.classList.toggle('local', isLocal)
+        el.classList.toggle('test', !isLocal)
+        el.textContent = isLocal ? '本地' : '测试'
+      })
+      document.querySelectorAll('.demo-env-stripe').forEach(function (el) {
+        el.classList.toggle('local', isLocal)
+        el.classList.toggle('test', !isLocal)
+        el.textContent = isLocal
+          ? '⚠ 本地联调环境 · 勿上传正式版'
+          : '⚠ 测试环境 · 非生产'
+      })
+    }
+  </script>
+</body>
+</html>
diff --git a/docs/superpowers/specs/2026-10-11-mobile-h5-env-banner-design.md b/docs/superpowers/specs/2026-10-11-mobile-h5-env-banner-design.md
new file mode 100644
index 00000000..7bb26521
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-11-mobile-h5-env-banner-design.md
@@ -0,0 +1,80 @@
+# mobile-h5 非生产环境首页色条标识
+
+## 背景
+
+`mobile-h5/utils/config.js` 通过 `APP_ENV`（`local` | `test` | `prod`）切换 API / OA H5 等地址。开发者在本地、测试、生产之间切换后，容易在微信开发者工具中误上传非生产包。需要在界面上给出明确、一眼可辨的环境提示。
+
+## 目标
+
+- `APP_ENV` 为 `local` 或 `test` 时，首页顶部显示醒目色条，文案可区分环境。
+- `APP_ENV` 为 `prod` 时，不渲染任何环境标识，对正式用户零感知。
+- 实现改动面小，只依赖已有 `APP_ENV`，不引入构建脚本或上传拦截。
+
+## 非目标
+
+- 不在登录页或其他业务页显示标识。
+- 不做 sticky 吸顶。
+- 不改造微信上传/发布流程，不增加 CI 门禁。
+- 不自动改回 `APP_ENV`（仍由开发者手动切换）。
+
+## 方案（已确认）
+
+采用 **方案 B：首页顶部醒目色条**。
+
+| 项 | 约定 |
+| --- | --- |
+| 出现页面 | 仅首页 `pages/index/index.vue` |
+| 位置 | 绿头 Header **之上**，随页面滚动（非 sticky） |
+| local 文案 | `本地环境` |
+| test 文案 | `测试环境` |
+| local 配色 | 背景 `#f59e0b`，文字深琥珀（如 `#451a03`） |
+| test 配色 | 背景 `#3b82f6`，文字浅色（如 `#eff6ff`） |
+| prod | 不渲染节点 |
+
+## 数据与导出
+
+在 `mobile-h5/utils/config.js` 中基于 `APP_ENV` 导出只读描述，供首页使用，避免页面内重复分支：
+
+```js
+// 示意
+export const ENV_BANNER = {
+  show: APP_ENV === 'local' || APP_ENV === 'test',
+  label: APP_ENV === 'local' ? '本地环境' : APP_ENV === 'test' ? '测试环境' : '',
+  tone: APP_ENV === 'local' ? 'local' : APP_ENV === 'test' ? 'test' : ''
+}
+```
+
+首页仅读取 `ENV_BANNER`，不直接硬编码文案。
+
+## UI 结构
+
+首页模板在现有 `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>
+```
+
+样式要求：
+
+- 全宽、居中、字号偏小但加粗（约 22–24rpx），上下 padding 约 10–14rpx。
+- `tone=local` / `tone=test` 使用上表配色。
+- 不遮挡状态栏逻辑：色条在页面内容流内，仍由现有 `home-header` 的上 padding 处理安全区；色条本身不加额外 status-bar 占位（避免双重顶距）。
+
+## 验收标准
+
+1. `APP_ENV='local'`：打开首页可见橙色条，文案为「本地环境」。
+2. `APP_ENV='test'`：打开首页可见蓝色条，文案为「测试环境」。
+3. `APP_ENV='prod'`：首页 DOM/视觉中无环境色条。
+4. 进入其他页面（登录、OA 列表等）无此色条。
+5. 切换 `APP_ENV` 后重新编译/刷新，首页展示与配置一致。
+
+## 测试建议
+
+- 手动：分别将 `APP_ENV` 设为 `local` / `test` / `prod`，冷启动进首页核对。
+- 可选：对 `ENV_BANNER` 导出做极简单元测试（按 `APP_ENV` 映射 `show/label/tone`），若现有测试基建不便 mock 模块常量则可跳过，以手工验收为准。
+
+## 参考 Demo
+
+交互示意见 `docs/demos/mobile-h5-env-badge-demo.html` 中方案 B。