# H5 小程序嵌入式应用开发模板 v2

> 适用于嵌入微信小程序 web-view 的 H5 应用
> 技术栈：FastAPI + MongoDB (Beanie) + React 18 + React Router 7 + Vite 6
> 认证：小程序传 openid → 后端调 CRMEB 接口获取用户信息 → 自动补齐昵称/头像
>
> **v2 变更要点（实战沉淀）**
> 1. 前端资源改**相对路径**（Vite `base: './'`），适配二级目录与 web-view，避免白屏。
> 2. Nginx 无斜杠跳转**保留 query**，避免 `?openid` 丢失导致登录失败。
> 3. 二级目录三处一致规则细化（base / basename / API 前缀）。
> 4. 新增：小程序 web-view 接入要点、MongoDB 部署注意、时区统一、后台管理 + 访问埋点。

---

## 一、项目架构

### 1.1 技术栈

| 层 | 技术 | 备注 |
|---|------|------|
| 前端 | React 18 + React Router 7 + Vite 6 | SPA，二级目录部署，资源相对路径 |
| UI | TailwindCSS + 自研 SVG 图标（按需 MUI/shadcn）| 母婴等品牌建议自研图标，避免堆依赖 |
| 状态 | React Context + localStorage 持久化 | 无 Redux/Zustand |
| 后端 | FastAPI + Uvicorn（PM2 守护，`--interpreter none`）| |
| 数据库 | MongoDB（Motor + Beanie ODM）| localhost 绑定 + 鉴权 |
| 认证 | openid → 后端调 CRMEB 内部接口 | 无 JWT 签名验证 |

### 1.2 目录结构

```
project/
├── frontend/
│   ├── src/app/
│   │   ├── pages/            # 页面组件
│   │   ├── components/       # 通用组件（含自研 icons.tsx）
│   │   ├── context/          # React Context
│   │   ├── hooks/            # 自定义 hook（可独立测试）
│   │   ├── services/         # api / debug / analytics
│   │   ├── data/             # 静态数据表
│   │   ├── routes.tsx        # 路由 + 埋点 RootTracker
│   │   └── App.tsx
│   ├── .env / .env.production # 环境变量（生产关闭 debug）
│   └── dist/                 # 构建产物
├── backend/
│   ├── app/
│   │   ├── routers/          # auth/user/sessions/events/admin...
│   │   ├── models/           # Beanie 数据模型
│   │   ├── services/         # 业务逻辑 + jwt_util
│   │   ├── middleware/       # 认证（get_current_user / get_admin）
│   │   └── config.py
│   ├── tests/                # pytest（建议测试占比高）
│   ├── serv.sh / backup.sh
│   └── .env
├── deploy/
│   ├── nginx-<app>.conf
│   └── admin/index.html      # 独立后台（单文件，无需构建）
└── docs/
```

### 1.3 多应用同域名 / 二级目录部署

```
同一 Nginx 下多个 H5 应用，各自独立后端进程；前端按二级目录部署：

https://mp.example.com/
├── /app_03/            → 前端 SPA（部署在二级目录 /app_03/）
│   └── /app_03/api/    → proxy_pass 127.0.0.1:8030/api/
├── /baby_food/         → /baby_food/api/ → 8031
└── /admin/（可选）     → 独立后台静态页
```

---

## 二、前端路径规范（v2 核心，务必遵守）

H5 会被微信小程序 web-view 以二级目录地址打开（如 `…/app_03/?openid=xxx`）。
路径处理不当是 web-view **白屏**最常见原因。规则如下：

### 2.1 资源用相对路径（关键）

```ts
// vite.config.ts
export default defineConfig({
  base: "./",   // ✅ 相对路径：资源按文档所在二级目录解析
  // ❌ 不要用绝对 base: "/app_03/"（小程序/代理环境下易解析错导致白屏）
});
```

- `base: './'` 后，构建出的 `index.html` 引用为 `./assets/xxx.js`，无论挂在哪个二级目录都能正确加载。
- 单层路由（`/home`、`/count`）下，`./assets/` 从 `/app_03/home` 解析回 `/app_03/assets/`，正常。
- 如有**多层路由**，需改用 HashRouter 或加 `<base href>`，否则深层路由刷新会算错相对基准。

### 2.2 二级目录三处一致

| 配置项 | 位置 | 值（以 app_03 为例）| 说明 |
|--------|------|------|------|
| Vite `base` | `vite.config.ts` | `'./'` | **相对**，不写死二级目录 |
| Router `basename` | `routes.tsx` | `'/app_03'` | 路由仍按二级目录（路径里编码二级目录）|
| `VITE_API_PREFIX` | `.env` | `'/app_03/api'` | 同源绝对路径，web-view 同源可用 |

> 资源相对、路由二级目录、API 同源绝对——三者配合：资源可移植，路由/接口仍锚定二级目录。

### 2.3 生产环境关闭调试

```ini
# .env.production
VITE_API_PREFIX=/app_03/api
VITE_DEBUG=false      # 生产关闭：避免无 openid 时自动 dev-login
```

`npm run build` 默认加载 `.env.production`。

### 2.4 Vite dev proxy

```ts
server: {
  proxy: {
    [apiPrefix]: {           // "/app_03/api"
      target: "http://localhost:8030",
      changeOrigin: true,
      rewrite: (p) => p.replace(/^\/app_03\/api/, "/api"),
    },
  },
}
```

---

## 三、小程序 web-view 接入要点（v2 新增）

1. **业务域名白名单**：小程序后台「业务域名」必须加入本 H5 域名（需 HTTPS、需下载校验文件放服务器）。否则 web-view 直接打不开。
2. **打开地址**：`https://mp.example.com/app_03/?openid=<openid>`，建议带尾斜杠。
3. **跳转保留参数**：无斜杠地址 `…/app_03?openid=xxx` 经 nginx 301 时**必须保留 query**，否则 openid 丢失、登录失败：
   ```nginx
   location = /app_03 { return 301 /app_03/$is_args$args; }   # ✅ 保留 ?openid
   # ❌ return 301 /app_03/;   会丢掉 ?openid
   ```
4. **openid 读取**：用 BrowserRouter 时 `useSearchParams()` 能读到 `?openid`。若改 HashRouter，`?openid` 在 `#` 之前不会被 router 读到，需 `new URLSearchParams(window.location.search)` 直接取。
5. **真机调试**：白屏先用 vConsole / 真机调试看是不是资源 404 或域名未白名单。

---

## 四、认证规范

### 4.1 流程

```
小程序 web-view → /app_03/?openid=xxx
  → LoginPage 读取 openid
  → POST /app_03/api/auth/openid-login { openid }
  → 后端 GET CRMEB /api/internal/user-info?openid=xxx (X-Internal-Key)
  → { nickname, phone, avatar } → 建/更新 User
  → 返回 token → setTokenAndUser → fetchProfile → 跳首页/引导页
```

### 4.2 关键约定

- 中间件 `get_current_user`：解 token（`verify_signature=False`），手动验 `exp`，按 openid 查/建用户。
- CRMEB 客户端**任何异常都优雅降级**（返回空昵称/头像，不阻断登录），并 `logger.warning` 记录，便于排查。
- `DEV_MODE=1` 才启用 `POST /api/auth/dev-login`，生产必须为 `0`。
- **CRMEB 匹配口径**：openid 按 appid 隔离。若 CRMEB 与小程序非同一 appid，应改用 **unionid** 匹配（小程序传 unionid，CRMEB 内部接口按 unionid 查；openid 仍作本系统主键）。
- **H5 端 openid 一致性检查**（分享场景必做）：当 H5 被其他用户分享的链接打开时，web-view 的 `localStorage` 可能残留原用户的 token。检查位置应在 **LoginPage 的 `useEffect` 最开头**（比路由守卫更早触发，覆盖 `/` 公开路由），比对 URL 中的 openid 与缓存 token 中的 openid，不一致或 token 解码失败时都清除缓存：
  ```tsx
  const urlOpenid = new URLSearchParams(window.location.search).get('openid');
  const cachedToken = getToken();
  if (urlOpenid && cachedToken) {
    try {
      const payload = decodeToken(cachedToken);
      if (payload.openid !== urlOpenid) clearToken();
    } catch (e) {
      clearToken();
    }
  }
  ```
  > 否则会出现：B 打开 A 分享的链接，web-view 的 localStorage 仍有 A 的 token，导致 H5 展示 A 的数据。

---

## 五、后端规范

### 5.1 路由注册

```python
# routers/__init__.py
router = APIRouter(prefix="/api")
router.include_router(auth.router)      # /api/auth/*
router.include_router(user.router)      # /api/user/*
router.include_router(sessions.router)  # /api/sessions/*
router.include_router(events.router)    # /api/events  （埋点上报）
router.include_router(admin.router)      # /api/admin/* （后台）
```

> 注意路由顺序：`/sessions/stats` 必须声明在 `/sessions/{id}` 之前，否则 `stats` 被当作 id。

### 5.2 配置（pydantic-settings）

```ini
# .env
MONGODB_URL=mongodb://user:pwd@127.0.0.1:27017/app_03?authSource=admin
MONGODB_DB_NAME=app_03
JWT_SECRET_KEY=...
JWT_EXPIRE_DAYS=30
CRMEB_BASE_URL=https://shop.example.com
CRMEB_API_KEY=sk_...
HOST=0.0.0.0
PORT=8030
DEV_MODE=0
ADMIN_USER=admin
ADMIN_PASS=<强密码>        # 后台登录，生产务必改默认
CORS_ORIGINS=https://mp.example.com   # 生产收紧，勿用 *
```

### 5.3 时区统一（v2 新增，重要）

- 数据库统一存 **UTC**（`datetime.now(timezone.utc)`）。
- 一切「按天分组 / 今天 / 日期反推」统一按**目标时区**（国内=北京 UTC+8）换算，前后端一致：
  - 后端聚合按天：把 `created_at` `astimezone(UTC+8)` 再取 `.date()`。
  - 前端分组：`new Date(iso).toLocaleDateString('zh-CN')`（设备本地=北京）。
  - 由 UTC 存储反推业务日期时，先转北京再比较，避免凌晨跨日差一天。

### 5.4 数据模型

```python
class User(Document):
    openid: str = Field(..., unique=True)
    name: str = ""
    phone: Optional[str] = None
    avatar_url: Optional[str] = None
    is_onboarded: bool = False
    created_at: datetime
    class Settings:
        name = "users"
        indexes = [IndexModel("openid", unique=True)]
```

> 业务集合自定义；为常用查询建复合索引（如 `[(openid,1),(created_at,-1)]`）。

---

## 六、后台管理 + 访问埋点（v2 新增）

### 6.1 管理员鉴权

```python
def build_admin_token():  # jwt {"admin": True, exp}
def get_admin(credentials):  # 校验 payload["admin"]，否则 401/403
```

- `POST /api/admin/login {username,password}` 校验 `.env` 的 ADMIN_USER/PASS → 发 admin token。
- 后台接口统一 `Depends(get_admin)`。

### 6.2 独立后台页

- **单文件静态页**（`deploy/admin/index.html`，纯 HTML+CSS+JS，无需构建），nginx 独立 location 服务：
  ```nginx
  location /admin/ { alias /opt/<app>/admin/; try_files $uri $uri/ /admin/index.html; }
  ```
- 同域调 `/app_03/api/admin/*`，token 存 localStorage。

### 6.3 访问埋点

- 模型 `PageView { openid, visit_id, path, duration_ms, created_at }`。
- 上报：`POST /api/events {visit_id, path, duration_ms}`（带用户 token）。
- 前端 `RootTracker`（包裹路由）监听 `useLocation` 变化与 `visibilitychange`，上报上一页停留时长；`visit_id` 用 `sessionStorage`（一次打开=一次访问）。仅登录后、停留 >0.2s 才上报。
- 后台聚合：按 openid 出「访问次数/总时长/最近活跃」，按 visit 还原「访问路径 + 每页时长」。

---

## 七、Nginx 配置模板（v2）

```nginx
server {
    listen 80;
    server_name mp.example.com;
    location /.well-known/acme-challenge/ { root /opt/app_03/frontend/dist; }
    location / { return 301 https://$host$request_uri; }
}
server {
    listen 443 ssl;
    server_name mp.example.com;
    ssl_certificate     /etc/letsencrypt/live/mp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mp.example.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # 独立后台（可选，放在 catch-all 之前）
    location /admin/ { alias /opt/app_03/admin/; try_files $uri $uri/ /admin/index.html; }

    # 无斜杠跳转：保留 query（避免丢 openid）
    location = /app_03 { return 301 /app_03/$is_args$args; }

    # 前端 SPA（相对资源 + history 回退）
    location /app_03/ {
        alias /opt/app_03/frontend/dist/;
        try_files $uri $uri/ /app_03/index.html;

        # index.html 不缓存（每次从服务器拉最新，确保 JS hash 更新）
        location = /app_03/index.html {
            add_header Cache-Control "no-cache, must-revalidate";
        }

        # 带 hash 的静态资源可长期缓存
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }

    # API 代理（proxy_pass 带尾 /api/，前缀被替换）
    location /app_03/api/ {
        proxy_pass http://127.0.0.1:8030/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

> 证书用 `certbot certonly --webroot -w <dist目录> -d <域名>` 现签（复用已有 ACME 账号，无需邮箱）。

---

## 八、MongoDB 部署注意（v2 新增）

国内服务器优先**原生安装**，比 Docker 拉镜像稳：

- Docker Hub / 常见镜像源拉 `mongo` 大层常**卡死/0 速**（验证：`docker pull` 长时间无进度）。若必须 Docker，确认有可用国内 registry-mirror 且能拉 blob。
- **推荐原生 apt 装**（清华源稳）：
  ```bash
  echo "deb [trusted=yes] https://mirrors.tuna.tsinghua.edu.cn/mongodb/apt/ubuntu <codename>/mongodb-org/8.0 multiverse" \
    > /etc/apt/sources.list.d/mongodb-org-8.0.list
  apt-get update && apt-get install -y mongodb-org   # 注意 codename 与版本匹配（如 noble→8.0）
  ```
- **安全基线**：`bindIp: 127.0.0.1`（仅本地）+ `security.authorization: enabled`，建 root 用户；连接串带 `?authSource=admin`。
- **每日备份**：`mongodump --gzip --archive` + cron，保留最近 N 份。

---

## 九、部署与运维

- 后端 PM2：`pm2 start .venv/bin/uvicorn --name <app> --interpreter none --cwd <backend> -- app.main:app --host 127.0.0.1 --port <port>`（`--interpreter none` 让 PM2 用 Python shebang，否则会当 Node 跑报错）；`pm2 save` 持久化。
- 后端绑 `127.0.0.1`，由 nginx 反代，不对公网直接暴露端口。
- pip 用阿里源加速：`pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt`。
- 前端：`npm run build` → `rsync dist/` 到 `/opt/<app>/frontend/dist/`（nginx 直接服务静态，无需 reload）。

---

## 十、新建应用 Checklist（v2）

- [ ] 项目标识 snake_case；二级目录三处一致：Vite `base:'./'` / Router `basename:'/xxx'` / `VITE_API_PREFIX:'/xxx/api'`
- [ ] 生产 `.env.production` 设 `VITE_DEBUG=false`
- [ ] 后端 `.env`：MongoDB(带 authSource) / JWT / CRMEB / `DEV_MODE=0` / `ADMIN_PASS` 改默认 / `CORS_ORIGINS` 收紧
- [ ] 全站时区：UTC 存储 + 北京(UTC+8)分组/反推，前后端一致
- [ ] Nginx：`location = /xxx` 跳转**保留 query**；`/xxx/` 相对资源 + try_files；`/xxx/api/` 代理；（可选）`/admin/`
- [ ] MongoDB：原生安装 + localhost + 鉴权 + 每日备份 cron
- [ ] PM2 `--interpreter none` 启动后端 + `pm2 save`
- [ ] 小程序：业务域名白名单 + HTTPS + `/xxx/?openid=` 打开
- [ ] 后台 `/admin/` 可登录；前端埋点上报通；CRMEB openid/unionid 口径确认
- [ ] 真机 web-view 实测打开（带/不带斜杠都不丢 openid）

---

## 十一、从零起一个新应用 · 命令级 step-by-step

下面以新应用 `app_03`、端口 `8030`、域名 `mp.example.com`、二级目录 `/app_03/` 为例。
先定义变量（本地和服务器都可复用）：

```bash
APP=app_03            # 应用标识（全小写 snake_case）
PORT=8030             # 后端端口（确认未占用）
DOMAIN=mp.example.com # 访问域名（已解析、能签 HTTPS）
DBNAME=$APP           # Mongo 库名
SERVER=root@1.2.3.4   # 目标服务器
```

### 0. 本地建仓

```bash
mkdir -p ~/work/$APP && cd ~/work/$APP
git init -b main
printf "node_modules/\ndist/\n__pycache__/\n*.pyc\n.env\n.venv/\ntsconfig.tsbuildinfo\n" > .gitignore
mkdir -p backend/app/{routers,models,services,middleware} backend/tests frontend deploy/admin docs
```

### 1. 后端骨架

```bash
cd ~/work/$APP/backend
cat > requirements.txt <<'EOF'
fastapi==0.115.*
uvicorn[standard]==0.32.*
motor==3.6.*
beanie==1.27.*
pydantic-settings==2.6.*
PyJWT==2.10.*
httpx==0.27.*
pytest==8.3.*
pytest-asyncio==0.24.*
mongomock-motor==0.0.34
EOF

python3 -m venv .venv && . .venv/bin/activate
pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt
printf "[pytest]\nasyncio_mode = auto\npythonpath = .\n" > pytest.ini

# .env（按需改密钥）
cat > .env <<EOF
MONGODB_URL=mongodb://127.0.0.1:27017
MONGODB_DB_NAME=${DBNAME}_dev
JWT_SECRET_KEY=$(openssl rand -hex 32)
JWT_EXPIRE_DAYS=30
CRMEB_BASE_URL=https://shop.example.com
CRMEB_API_KEY=sk_change_me
HOST=0.0.0.0
PORT=${PORT}
DEV_MODE=1
ADMIN_USER=admin
ADMIN_PASS=admin888
CORS_ORIGINS=*
EOF
```

> 然后按第二~六节写 `config.py / db.py / models / routers / main.py`（可直接复制模板应用改标识）。
> 最小可跑：`main.py` 注册 `router`，`GET /api/health` 返回 `{"status":"ok"}`。

本地起后端（开发）：

```bash
DEV_MODE=1 .venv/bin/uvicorn app.main:app --host 0.0.0.0 --port $PORT --reload
# 另开终端验证
curl -s localhost:$PORT/api/health   # {"status":"ok"}
pytest -q                            # 跑测试
```

### 2. 前端骨架

```bash
cd ~/work/$APP/frontend
npm create vite@latest . -- --template react-ts   # 或手动建
npm i react-router-dom framer-motion recharts
npm i -D tailwindcss@3 postcss autoprefixer jsdom @testing-library/react vitest
npx tailwindcss init -p
```

关键配置（三处一致 + 相对资源）：

```bash
# vite.config.ts: base: "./"，dev proxy 见第 2.4 节
# routes.tsx:    createBrowserRouter([...], { basename: "/app_03" })
# .env
printf "VITE_API_PREFIX=/app_03/api\nVITE_DEBUG=true\n" > .env
# .env.production（生产关调试）
printf "VITE_API_PREFIX=/app_03/api\nVITE_DEBUG=false\n" > .env.production
```

本地开发 / 构建：

```bash
npm run dev       # 代理到后端 $PORT
npm run build     # 产出 dist/（资源为 ./assets/...）
grep assets dist/index.html   # 确认是 ./assets（相对）
```

### 3. 服务器：MongoDB（原生，首次装一次）

```bash
ssh $SERVER
CODENAME=$(. /etc/os-release; echo $VERSION_CODENAME)   # 如 noble
echo "deb [trusted=yes] https://mirrors.tuna.tsinghua.edu.cn/mongodb/apt/ubuntu $CODENAME/mongodb-org/8.0 multiverse" \
  > /etc/apt/sources.list.d/mongodb-org-8.0.list
apt-get update && apt-get install -y mongodb-org
systemctl enable --now mongod

# 建用户 + 开鉴权
MPWD=$(openssl rand -hex 24); echo "MONGO_PWD=$MPWD"   # 记下来
mongosh --quiet --eval "db.getSiblingDB('admin').createUser({user:'$APP',pwd:'$MPWD',roles:[{role:'root',db:'admin'}]})"
grep -q 'authorization: enabled' /etc/mongod.conf || printf '\nsecurity:\n  authorization: enabled\n' >> /etc/mongod.conf
systemctl restart mongod
```

### 4. 部署代码到服务器

```bash
# 本地：同步代码 + 构建产物
cd ~/work/$APP
rsync -az --exclude node_modules --exclude .venv --exclude __pycache__ --exclude dist \
  backend deploy docs $SERVER:/opt/$APP/
rsync -az --delete frontend/dist/ $SERVER:/opt/$APP/frontend/dist/

# 服务器：建 venv + 写生产 .env（MONGODB_URL 用上一步的 MPWD）
ssh $SERVER bash -lc "
  cd /opt/$APP/backend && python3 -m venv .venv &&
  .venv/bin/pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt &&
  sed -i 's#^MONGODB_URL=.*#MONGODB_URL=mongodb://$APP:<MPWD>@127.0.0.1:27017/$DBNAME?authSource=admin#;
          s#^MONGODB_DB_NAME=.*#MONGODB_DB_NAME=$DBNAME#;
          s#^DEV_MODE=.*#DEV_MODE=0#;
          s#^CORS_ORIGINS=.*#CORS_ORIGINS=https://$DOMAIN#' .env
"
```

### 5. 服务器：PM2 起后端

```bash
ssh $SERVER bash -lc "
  cd /opt/$APP/backend &&
  pm2 start .venv/bin/uvicorn --name $APP --interpreter none --cwd /opt/$APP/backend -- app.main:app --host 127.0.0.1 --port $PORT &&
  pm2 save &&
  sleep 3 && curl -s localhost:$PORT/api/health
"
```

> `--interpreter none` 必加，否则 PM2 当 Node 跑 uvicorn 会报 ESM 错。

### 6. 服务器：Nginx + HTTPS

```bash
ssh $SERVER bash -lc "
  # 先放一个 HTTP server 块（含 acme 与 /$APP/）做证书校验，再签证书
  certbot certonly --webroot -w /opt/$APP/frontend/dist -d $DOMAIN --non-interactive --agree-tos --keep-until-expiring
"
# 然后写第七节的完整 vhost（含 location = /$APP 保留 query、/$APP/ 相对资源、/$APP/api/ 代理、可选 /admin/）
ssh $SERVER bash -lc "ln -sf /etc/nginx/sites-available/$APP /etc/nginx/sites-enabled/$APP && nginx -t && systemctl reload nginx"
```

### 7. 小程序接入

- 小程序后台「业务域名」加入 `https://$DOMAIN`（下载校验文件放到 dist 根，nginx 可访问）。
- web-view 打开：`https://$DOMAIN/$APP/?openid=<openid>`。

### 8. 上线验证（一键自检）

```bash
B=https://$DOMAIN
curl -s -o /dev/null -w "http跳转: %{http_code}\n"  http://$DOMAIN/$APP/
curl -s -o /dev/null -w "首页: %{http_code}\n"       $B/$APP/
curl -s $B/$APP/ | grep -o './assets/[^"]*\.js' | head -1          # 相对资源
curl -s -I "$B/$APP?openid=t1" | grep -i location                 # 应保留 ?openid=t1
curl -s $B/$APP/api/health                                         # {"status":"ok"}
# 走一遍登录
TOK=$(curl -s -X POST $B/$APP/api/auth/openid-login -H 'Content-Type: application/json' -d '{"openid":"t1"}' | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
curl -s $B/$APP/api/user/profile -H "Authorization: Bearer $TOK"
```

### 9. 每日备份 cron（可选但推荐）

```bash
ssh $SERVER bash -lc "
cat > /opt/$APP/backup.sh <<'EOS'
#!/usr/bin/env bash
set -e; TS=\$(date +%Y%m%d-%H%M); OUT=/opt/$APP/backups; mkdir -p \$OUT
mongodump --uri='mongodb://$APP:<MPWD>@127.0.0.1:27017/$DBNAME?authSource=admin' --gzip --archive=\"\$OUT/$APP-\$TS.gz\"
ls -1t \$OUT/$APP-*.gz | tail -n +15 | xargs -r rm -f
EOS
chmod +x /opt/$APP/backup.sh
( crontab -l 2>/dev/null | grep -v $APP/backup.sh; echo '30 3 * * * /opt/$APP/backup.sh >> /var/log/$APP-backup.log 2>&1' ) | crontab -
"
```

### 日常更新（改完代码再次发布）

```bash
# 后端改动
rsync -az --exclude __pycache__ backend/app $SERVER:/opt/$APP/backend/
ssh $SERVER "pm2 restart $APP"
# 前端改动
npm run build && rsync -az --delete frontend/dist/ $SERVER:/opt/$APP/frontend/dist/
```

---

## 十二、WebView Bridge：分享 & 复制链接（v2 新增）

H5 页面在微信小程序 `<web-view>` 中运行，无法直接调用微信原生分享 API 或系统剪贴板。
需通过 **Mini Program Bridge** 模式实现：H5 发 `postMessage` → 小程序 `@message` 事件监听 → 小程序调用原生 API。

### 12.1 架构图

```
H5 (React SPA)                        小程序 (uni-app web-view)         微信原生
┌─────────────────┐                   ┌────────────────────┐         ┌─────────┐
│ 用户点"分享好友"  │                   │                     │         │         │
│ bridge.share()   │──postMessage────→│  @message           │──调用──→ │ 分享面板 │
│ wx.miniProgram   │                   │  handleMessage()    │         │         │
│ .postMessage()   │                   │  uni.share()        │         └─────────┘
│                  │                   │                     │         ┌─────────┐
│ 用户点"复制链接"  │──postMessage────→│  @message           │──调用──→ │ 剪贴板  │
│ bridge.copyLink()│                   │  handleMessage()    │         │         │
│                  │                   │  uni.setClipboard() │         └─────────┘
└─────────────────┘                   └────────────────────┘
```

### 12.2 小程序侧：web-view 组件配置

在 `<web-view>` 上声明 `@message` 事件监听：

```html
<web-view :src="url" @message="handleMessage"></web-view>
```

实现 `handleMessage` 方法（uni-app / Vue 2 语法）：

```javascript
handleMessage(e) {
  const data = e.detail && e.detail.data ? e.detail.data[0] : null
  if (!data) return

  switch (data.action) {
    case 'share':
      uni.share({
        provider: 'weixin',
        scene: data.scene || 'WXSceneSession',
        type: data.type || 0,
        title: data.title || '',
        href: data.href || this.url,
        imageUrl: data.imageUrl || '',
        summary: data.summary || '',
      })
      break

    case 'copyLink':
      uni.setClipboardData({
        data: data.href || this.url,
        success() { uni.showToast({ title: '链接已复制', icon: 'success' }) },
        fail(err) { console.warn('[webview] 复制失败:', err) }
      })
      break

    case 'setTitle':
      if (data.title) uni.setNavigationBarTitle({ title: data.title })
      break
  }
}
```

### 12.3 小程序侧：原生"..."菜单分享

web-view 页面的右上角"..."菜单默认显示"转发/分享"为灰色不可点。
需要实现以下两个生命周期钩子使其可用：

```javascript
// 在 onLoad 中主动显示分享菜单
onLoad(option) {
  // #ifdef MP
  uni.showShareMenu({
    menus: ['shareAppMessage', 'shareTimeline']
  });
  // #endif
}

// 处理转发给朋友
onShareAppMessage() {
  return {
    title: '页面标题',
    path: '/pages/web-view-path?url=' + encodeURIComponent(this.url),
  }
}

// 处理分享到朋友圈（微信限制：web-view 不支持，此钩子不会被触发）
onShareTimeline() {
  return {
    title: '页面标题',
    query: 'url=' + encodeURIComponent(this.url)
  }
}
```

> **已知限制**：`onShareTimeline`（分享到朋友圈）在 `<web-view>` 页面中**不支持**，微信 SDK 将其永久灰化。
> 替代方案：使用「生成分享图片 → 保存到相册 → 手动发朋友圈」。

### 12.4 H5 侧：bridge.ts 工具

在新应用的 `src/app/services/` 下创建 `bridge.ts`：

```typescript
/**
 * 小程序 WebView 桥接工具
 */
declare const wx: any

function getMiniProgram() {
  try {
    if (typeof wx !== 'undefined' && wx.miniProgram) {
      return wx.miniProgram
    }
  } catch { /* ignore */ }
  return null
}

const bridge = {
  postMessage(data: Record<string, any>) {
    const mp = getMiniProgram()
    if (mp) {
      mp.postMessage({ data })
    } else {
      console.warn('[bridge] 不在小程序 web-view 环境中')
    }
  },

  /** 分享给微信好友 / 朋友圈 */
  share(opts: {
    title: string
    href?: string
    summary?: string
    imageUrl?: string
    scene?: 'WXSceneSession' | 'WXSceneTimeline'
  }) {
    this.postMessage({
      action: 'share',
      title: opts.title || '',
      href: opts.href || window.location.href,
      summary: opts.summary || '',
      imageUrl: opts.imageUrl || '',
      scene: opts.scene || 'WXSceneSession',
    })
  },

  /** 复制链接到剪贴板（通过 bridge 兜底） */
  copyLink(link?: string) {
    this.postMessage({
      action: 'copyLink',
      href: link || window.location.href,
    })
  },

  /** 设置小程序导航栏标题 */
  setTitle(title: string) {
    if (!title) return
    this.postMessage({ action: 'setTitle', title })
  },
}

export default bridge
```

### 12.5 H5 侧：复制链接的正确方案

微信 web-view 中 `navigator.clipboard.writeText()` **不支持**，
需用 `document.execCommand('copy')` 作为主方案，bridge `postMessage` 作为兜底：

```typescript
async function handleCopyLink(url: string) {
  let copied = false
  const textArea = document.createElement('textarea')
  textArea.value = url
  textArea.style.position = 'fixed'
  textArea.style.left = '-999999px'
  textArea.style.top = '-999999px'
  textArea.style.opacity = '0'
  document.body.appendChild(textArea)
  textArea.focus()
  textArea.select()

  try {
    copied = document.execCommand('copy')
  } catch (e) {
    console.warn('[copy] execCommand failed:', e)
  }
  document.body.removeChild(textArea)

  if (copied) {
    setLinkCopied(true)
    setTimeout(() => setLinkCopied(false), 2000)
  } else {
    // 兜底：通过 bridge postMessage（消息在页面离开时才触发）
    bridge.copyLink(url)
    // 乐观提示用户
    setLinkCopied(true)
    setTimeout(() => setLinkCopied(false), 2000)
  }
}
```

### 12.6 postMessage 时序限制

| 问题 | 说明 |
|------|------|
| `wx.miniProgram.postMessage()` 消息不会立即送达 | 仅在**页面跳转/导航离开**时才会触发小程序的 `@message` 事件 |
| 不适合"立即复制"场景 | 点完按钮希望"立即复制到剪贴板"时，postMessage 无法实时响应 |
| **最终方案** | `execCommand('copy')` 做实时复制（主方案），postMessage 做兜底（用户离开页面时最终确认） |

### 12.7 微信 web-view 分享限制

| 分享方式 | 支持 | 备注 |
|---------|:----:|------|
| 转发给朋友（"..."菜单） | ✅ | 需实现 `onShareAppMessage` + `uni.showShareMenu()` |
| 分享到朋友圈（"..."菜单） | ❌ | **微信平台限制**，所有 web-view 页面均不支持 |
| H5 内部"分享给好友"按钮 | ✅ | 通过 `bridge.share()` → postMessage → `uni.share()` |
| H5 内部复制链接 | ✅ | `document.execCommand('copy')` 主方案 + bridge 兜底 |
| 生成分享图→存相册→手动发圈 | ✅ | 替代方案，需 `html-to-image` 等截图库 |


| 分享方式 | 支持 | 备注 |
|---------|:----:|------|
| 转发给朋友（"..."菜单） | ✅ | 需实现 `onShareAppMessage` + `uni.showShareMenu()` |
| 分享到朋友圈（"..."菜单） | ❌ | **微信平台限制**，所有 web-view 页面均不支持 |
| H5 内部"分享给好友"按钮 | ✅ | 通过 `bridge.share()` → postMessage → `uni.share()` |
| H5 内部复制链接 | ✅ | `document.execCommand('copy')` 主方案 + bridge 兜底 |
| 生成分享图→存相册→手动发圈 | ✅ | 替代方案，需 `html-to-image` 等截图库 |

---

## 十三、新建应用 Checklist 补充（v2）

在原有 Checklist（第十节）基础上增加以下项：

- [ ] WebView Bridge: 小程序 web-view 加 `@message` + `handleMessage` 方法
- [ ] WebView Bridge: 实现 `onShareAppMessage()` + `uni.showShareMenu()` 启用原生"..."分享
- [ ] WebView Bridge: H5 端创建 `src/app/services/bridge.ts` 桥接工具
- [ ] WebView Bridge: H5 复制链接优先用 `document.execCommand('copy')`，bridge 兜底
- [ ] WebView Bridge: 确认微信 JS-SDK 已加载（`jweixin-1.2.0.js`），否则 `wx.miniProgram` 不可用
- [ ] WebView Bridge: 生成分享图片场景使用 `html-to-image` 等截图库
- [ ] H5 身份一致性: LoginPage 的 useEffect 中比对 URL openid 与缓存 token openid，不一致或解码失败时清除缓存重新登录

- [ ] Nginx: /app_03/index.html 设 `Cache-Control: no-cache`，静态资源设 far-future cache