refactor: update development standards and enhance ProfilePage with emergency contact editing

2026-05-28 16:08:26 +08:00
parent 96a938e11b
commit 201f80811a
4 changed files with 724 additions and 412 deletions
--- a/docs/development-standards.md
+++ b/docs/development-standards.md
@@ -2,7 +2,7 @@

 > 适用于嵌入微信小程序 web-view 的 H5 应用
 > 技术栈：FastAPI + MongoDB (Beanie) + React 18 + React Router 7 + Vite 6
-> 认证完全依赖小程序侧 JWT
+> 认证：小程序传 openid → 后端调 CRMEB 接口获取用户信息 → 自动补齐昵称/头像

 ---

@@ -13,11 +13,11 @@
 | 层 | 技术 | 备注 |
 |---|------|------|
 | 前端 | React 18 + React Router 7 + Vite 6 | SPA，独立 basename |
-| UI 库 | 自选（MUI / shadcn/ui / TailwindCSS） | |
+| UI 库 | MUI 7 + shadcn/ui (Radix) + TailwindCSS 4 | |
 | 状态 | React Context + localStorage 持久化 | 无 Redux/Zustand |
 | 后端 | FastAPI + Uvicorn | |
 | 数据库 | MongoDB (Motor + Beanie ODM) | |
-| 认证 | JWT（外部传入，不验证签名） | python-jose |
+| 认证 | openid → 后端调 CRMEB 内部接口 | 无 JWT 签名验证 |

 ### 1.2 目录结构

@@ -29,7 +29,7 @@ project/
 │   │   ├── components/       # 通用组件
 │   │   ├── components/ui/    # 基础 UI 组件（shadcn/ui 风格）
 │   │   ├── context/          # React Context
-│   │   ├── services/         # API 服务
+│   │   ├── services/         # API 服务 + debug 工具
 │   │   └── data/             # 静态数据
 │   │   ├── routes.tsx        # 路由配置
 │   │   └── App.tsx           # 根组件
@@ -55,23 +55,14 @@ project/
 同一个 Nginx 下代理多个 H5 应用，每个应用独立后端进程：

 https://mp.yizhezhe.com/
-├── /app_03/           → 孕育无忧 H5
-│   ├── → index.html（前端 SPA，basename=/app_03）
-│   └── /api/          → proxy_pass localhost:8030
-├── /baby_food/        → 婴儿辅食 H5
-│   ├── → index.html（前端 SPA，basename=/baby_food）
-│   └── /api/          → proxy_pass localhost:8031
-└── /album/            → 宝宝相册 H5
-    ├── → index.html（前端 SPA，basename=/album）
-    └── /api/          → proxy_pass localhost:8032
+├── /app_03/           → 前端 SPA（basename=/app_03）
+│   └── /app_03/api/   → proxy_pass localhost:8030/api/
+├── /baby_food/        → 前端 SPA
+│   └── /baby_food/api/ → proxy_pass localhost:8031/api/
+└── /album/            → 前端 SPA
+    └── /album/api/    → proxy_pass localhost:8032/api/
 ```

-每个应用是一个独立项目（独立 repo 或独立目录），拥有自己的：
- 前端构建产物（`dist/`）
- 后端服务进程（不同端口）
- 数据库（不同 MongoDB database）
- `.env` 和环境变量
-
 ### 1.4 Nginx 配置模板

 ```nginx
@@ -86,8 +77,7 @@ server {
        try_files $uri $uri/ /app_03/index.html;
    }
    location /app_03/api/ {
-        rewrite ^/app_03(/api/.*)$ $1 break;
-        proxy_pass http://127.0.0.1:8030;
+        proxy_pass http://127.0.0.1:8030/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
@@ -99,26 +89,24 @@ server {
        try_files $uri $uri/ /baby_food/index.html;
    }
    location /baby_food/api/ {
-        rewrite ^/baby_food(/api/.*)$ $1 break;
-        proxy_pass http://127.0.0.1:8031;
+        proxy_pass http://127.0.0.1:8031/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
 }
 ```

-> location = /xxx 必须带，否则 /app_03 无尾随斜杠时返回 404。
+> `location = /app_03` 处理无尾随斜杠的 301 跳转。
+> `location /app_03/api/` proxy_pass 带尾斜杠 = 匹配部分被完整替换。

 ### 1.5 新建应用步骤

-1. 复制模板目录，重命名项目
-2. 修改 `backend/app/config.py` → `app_name`, `mongodb_db_name`, `port`
-3. 修改前端 basename（Vite `base` + React Router `basename`）
-4. 定义数据模型（`backend/app/models/`）
-5. 编写业务 API（`backend/app/routers/`）
-6. 编写前端页面 + 路由
-7. 添加 Nginx location 块
-8. 启动验证
+1. 定义项目标识（全小写 snake_case，如 `baby_food`）
+2. 复制模板 → 修改 `config.py` → `app_name`, `mongodb_db_name`, `port`
+3. 修改前端 basename：Vite `base` + React Router `basename` + `APP_BASE_URL`
+4. 添加 Nginx location 块（前端 + API 代理）
+5. 定义数据模型 → 编写 API → 编写前端页面
+6. 启动验证

 ---

@@ -127,113 +115,102 @@ server {
 ### 2.1 认证流程

 ```
-小程序 → {token(JWT)} → URL params → H5 LoginPage
-                                                ↓
-                                    decodeToken(JWT) 提取 uid/openid/phone
-                                                ↓
-                                    localStorage 存储 token + user_basic
-                                                ↓
-                                    后端 API 请求带 Authorization: Bearer
-                                                ↓
-                                    get_current_user 解码 JWT → 按 openid 查找/创建用户
+小程序 URL: ?openid=oauWC1zc7hVn3j60QwkuHyjGn03Y
+                    ↓
+H5 LoginPage → 前端无 token 处理
+                    ↓
+            POST /api/auth/openid-login { openid }
+                    ↓
+            app_03 后端 → GET CRMEB /api/internal/user-info?openid=xxx
+                    ↓                    ↓ (X-Internal-Key 验证)
+            { nickname, phone, avatar }
+                    ↓
+            创建/更新 User（MongoDB）
+                    ↓
+            返回自签 JWT token
+                    ↓
+            setTokenAndUser → fetchProfile → 跳转首页/引导页
 ```

-### 2.2 JWT 格式
+### 2.2 登录流程（LoginPage.tsx）

-**前端 decodeToken() 解析出的字段：**
 ```typescript
-interface TokenPayload {
-  uid: number;         // 小程序侧的用户 ID
-  openid: string;      // 微信 openid
-  phone: string;       // 手机号（可能为空）
-  exp: number;         // 过期时间戳
+const openidParam = params.get('openid');
+if (openidParam && openidParam.trim()) {
+  const res = await fetchApi("/auth/openid-login", {
+    method: "POST",
+    body: JSON.stringify({ openid: openidParam }),
+  });
+  setTokenAndUser(res.token, { id: res.user_id, openid: res.openid, phone: res.mobile });
+  // fetchProfile 自动拿到 name/avatar_url（已从 CRMEB 同步）
 }
 ```

-**后端自签 token（dev-login 兼容，同格式）：**
-```json
-{ "uid": "...", "openid": "...", "phone": "...", "exp": ..., "iss": "localhost" }
+**小程序端 URL 格式：**
+```javascript
+const url = 'https://mp.yizhezhe.com/app_03/?openid=' + encodeURIComponent(openid);
 ```

-### 2.3 认证中间件规则
+### 2.3 后端 openid-login 接口（routers/auth.py）

 ```python
-# middleware/auth.py
-async def get_current_user(credentials: HTTPAuthorizationCredentials) -> User:
-    payload = jwt.decode(token, None, options={"verify_signature": False, "verify_exp": False})
-    openid = payload.get("openid")  # 必须存在
-    # 手动验证 exp 过期
-    user = await User.find_one(User.openid == openid)
+@router.post("/openid-login")
+async def openid_login(req: OpenidRequest) -> TokenResponse:
+    # 1. 调 CRMEB 内部接口获取用户信息
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{settings.crmeb_base_url}/api/internal/user-info",
+            params={"openid": req.openid},
+            headers={"X-Internal-Key": settings.crmeb_api_key},
+        )
+    info = resp.json()["data"]
+
+    # 2. 查找或创建用户（昵称/手机号/头像自动同步）
+    user = await User.find_one(User.openid == req.openid)
    if not user:
-        user = User(openid=openid, phone=phone or None)
+        user = User(openid=req.openid, name=info["nickname"], ...)
        await user.insert()
    else:
-        # 有 phone 且变化时更新
+        user.name = info["nickname"]; user.phone = info["phone"]
+        await user.save()
+
+    return TokenResponse(token=_build_token(user), ...)
+```
+
+### 2.4 认证中间件（middleware/auth.py）
+
+```python
+async def get_current_user(credentials) -> User:
+    payload = jwt.decode(token, None,
+        options={"verify_signature": False, "verify_exp": False})
+    openid = payload.get("openid")
+    # 手动验证 exp
+    user = await User.find_one(User.openid == openid)
+    if not user: 创建 User(openid, phone)
+    else: 更新 phone 等
    return user
 ```

- 不验证 JWT 签名（`verify_signature: False`），信任小程序侧
+- 不验证 JWT 签名（`verify_signature: False`），信任自身生成或小程序传入的 token
 - 手动验证 `exp` 过期
- 提取 `openid` → 按 openid 查找/创建用户
- `create_access_token()` 保持原样，兼容旧逻辑
+- 按 openid 查找/创建用户

-### 2.4 DEV_MODE
+### 2.5 DEV_MODE

 - 环境变量 `DEV_MODE=1` 启用开发模式
- 仅 `/api/auth/dev-login` 受此控制
- 测试账号固定 openid，在浏览器开发时自动登录
+- 仅 `POST /api/auth/dev-login` 受此控制
+- 测试账号：openid=`dev_test_account_001`, phone=`13800000000`
 - 启动方式：`DEV_MODE=1 uvicorn app.main:app --port 8030 --reload`

-### 2.5 前端登录流程（LoginPage.tsx 模板）
-
-```typescript
-const params = new URLSearchParams(window.location.search);
-const tokenFromUrl = params.get('token');
-
-if (tokenFromUrl) {
-  const payload = decodeToken(tokenFromUrl);
-  setTokenAndUser(tokenFromUrl, {
-    id: String(payload.uid),
-    openid: payload.openid,
-    phone: payload.phone,
-  });
-  // 拉取用户数据 → 跳转首页或引导页
-  fetchProfile().then((dto) => {
-    navigate(dto?.is_onboarded ? "/home" : "/onboarding", { replace: true });
-  });
-} else if (isWechatMiniProgram()) {
-  // 通知小程序传递 token
-  window.wx?.miniProgram?.postMessage({ type: "NEED_TOKEN" });
-} else {
-  // 浏览器开发环境 → dev-login
-  devLogin().then(res => setTokenAndUser(res.token, { ... }));
-}
-```
-
 ---

 ## 三、前端规范

-### 3.1 API 调用
+### 3.1 API 调用（services/api.ts）

 ```typescript
-// services/api.ts
-const TOKEN_KEY = "auth_token";
-
-export function getToken(): string | null {
-  return localStorage.getItem(TOKEN_KEY);
-}
-
-export function setToken(token: string) {
-  localStorage.setItem(TOKEN_KEY, token);
-}
-
-export function clearToken() {
-  localStorage.removeItem(TOKEN_KEY);
-}
-
-/** 通用 API 请求封装 */
-async function fetchApi<T>(path: string, options: RequestInit = {}): Promise<T> {
+/** 通用 API 请求封装（已 export） */
+export async function fetchApi<T>(path: string, options: RequestInit = {}): Promise<T> {
  const token = getToken();
  const headers: Record<string, string> = { "Content-Type": "application/json" };
  if (token) headers["Authorization"] = `Bearer ${token}`;
@@ -247,22 +224,32 @@ async function fetchApi<T>(path: string, options: RequestInit = {}): Promise<T>

 **新增 API 的步骤：**
 1. 在 `api.ts` 定义接口（`export interface XxxResponse`）
-2. 定义函数（`export async function xxx(): Promise<T>`）
+2. 定义函数（`export async function xxx(): Promise<T>`），内部调 `fetchApi<T>()`
 3. 在页面中 import 调用

-### 3.2 路由与守卫
+### 3.2 调试模块（services/debug.ts）
+
+```typescript
+// VITE_DEBUG=true 时启用调试日志和面板
+export function isDebug(): boolean
+export function debugLog(msg: string): void        // 写入 localStorage
+export function getDebugLogs(): string[]           // 读取日志
+export function clearDebugLogs(): void
+```
+
+- 由 `.env` 中 `VITE_DEBUG=true` 控制
+- 开发环境默认开启，生产环境设为 false 关闭
+- LoginPage 自动记录登录流程
+- ProfilePage 显示「展开调试日志」按钮
+
+### 3.3 路由与守卫

 ```typescript
 // routes.tsx
 function ProtectedRoute() {
  const token = getToken();
-  const urlToken = new URLSearchParams(window.location.search).get('token');
-  if (urlToken) {
-    return <Navigate to={`/?token=${encodeURIComponent(urlToken)}`} replace />;
-  }
-  if (!token) {
-    return <Navigate to={`/?redirect=${encodeURIComponent(location.pathname)}`} replace />;
-  }
+  // 无 token → Navigate to /?redirect=当前路径
+  if (!token) return <Navigate to={`/?redirect=...`} replace />;
  return <MobileLayout />;
 }
 ```
@@ -275,100 +262,39 @@ function ProtectedRoute() {
 /xxx           → 其他业务页面（保护）
 ```

-### 3.3 状态管理（Context 模板）
+### 3.4 状态管理（UserContext）

 ```typescript
-// context/UserContext.tsx
-export interface BasicUserInfo {
+interface BasicUserInfo {
  id: string;
  openid: string;
  phone: string;
 }
-
-interface UserContextValue {
-  user: UserProfile;        // 由具体业务定义
-  token: string | null;
-  setTokenAndUser: (token: string, info: BasicUserInfo) => void;
-  fetchProfile: () => Promise<void>;
-  logout: () => void;
-  // + 业务自定义方法
-}
 ```

- `BasicUserInfo` (`id`/`openid`/`phone`) 持久化到 `localStorage['user_basic']`
- 用户业务数据持久化到各自 key
+- `BasicUserInfo` 持久化到 `localStorage['user_basic']`
 - 切换用户时自动清理旧数据

-### 3.4 组件规范
-
- 页面组件统一放在 `pages/`，命名 `XxxPage.tsx`
- 通用业务组件在 `components/`
- 基础 UI 组件在 `components/ui/`（shadcn/ui 风格，按需引入）
- 函数式组件 + Hooks，class 组件禁用
- `react-hooks/exhaustive-deps` 可 eslint-disable（mount-once 模式）
- 动画推荐 `framer-motion`（包名 `motion`），图标推荐 `lucide-react`
-
-### 3.5 编码风格
-
- 中文注释
- `// ─── Section ───` 大段视觉分隔
- 不需要过度的错误处理，完整 traceback 就是调试信息
- 复杂逻辑封装到工具类/服务层，页面保持精简
-
-### 3.6 前端路径规范（多应用部署）
-
-每个 H5 应用的 basename 由两部分确定：
+### 3.5 前端路径规范

 | 配置项 | 位置 | 值 |
 |--------|------|----|
-| Vite `base` | `frontend/vite.config.ts` | `'/app_03/'` |
-| React Router `basename` | `routes.tsx` → `createBrowserRouter(routes, {basename: '/app_03'})` | `'/app_03'` |
-| fetch API 前缀 | `api.ts` → `APP_BASE_URL` | `'/app_03'` |
+| Vite `base` | `vite.config.ts` | `'/app_03/'` |
+| React Router `basename` | `routes.tsx` | `'/app_03'` |
+| `VITE_API_PREFIX` | `.env` | `'/app_03/api'` |

-**basename 命名规范：** `/{项目标识}`，全小写 + 下划线（`snake_case`）。
-
-**配置示例（vite.config.ts）：**
-```typescript
-export default defineConfig({
-  base: '/app_03/',              // 构建产物路径前缀
-  plugins: [react()],
-  server: { port: 5173 },
-})
-```
-
-**配置示例（routes.tsx）：**
-```typescript
-const router = createBrowserRouter(routes, {
-  basename: '/app_03',
-});
-```
-
-**api.ts 中的 base URL 自动拼接：**
-```typescript
-const API_PREFIX = import.meta.env.VITE_API_PREFIX || "/api";
-// APP_BASE_URL = basename = 从 API_PREFIX 提取（"/app_03/api" → "/app_03"）
-const APP_BASE_URL = API_PREFIX.replace(/\/api\/?$/, '') || '/';
-
-function joinPrefix(prefix: string, path: string) {
-  const p = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
-  const s = path.startsWith('/') ? path : `/${path}`;
-  return `${p}${s}`;
-}
-// 最终请求: /app_03/api/xxx
-```
-
-**.env 配置：**
+**`.env` 配置：**
 ```ini
-# API_PREFIX 必须带 basename，开发和 Nginx 代理一致
 VITE_API_PREFIX=/app_03/api
+VITE_UPLOADS_PREFIX=/uploads
+VITE_DEBUG=true
 ```

-**Vite proxy 配置（开发环境）：**
+**Vite proxy（开发环境）：**
 ```typescript
-// vite.config.ts
 server: {
  proxy: {
-    [apiPrefix]: {              // "/app_03/api"
+    [apiPrefix]: {       // "/app_03/api"
      target: 'http://localhost:8030',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/app_03\/api/, '/api'),
@@ -377,229 +303,109 @@ server: {
 }
 ```

+### 3.6 组件规范
+
+- 页面组件 `pages/XxxPage.tsx`，业务组件 `components/`
+- 基础 UI 组件 `components/ui/`（shadcn/ui 风格）
+- 函数式组件 + Hooks，中文注释
+- 动画用 `motion`（framer-motion），图标用 `lucide-react`
+
 ---

 ## 四、后端规范

-### 4.1 路由与 API 前缀规范
+### 4.1 路由与 API 前缀

-每个应用的 API 通过 Nginx 统一代理，路径结构为 `/{basename}/api/*`。
+| 应用 | API 路径 | 后端端口 |
+|------|---------|---------|
+| 孕育无忧 | `/app_03/api/*` | 8030 |
+| 婴儿辅食 | `/baby_food/api/*` | 8031 |

-| 应用 | 前端路径 | API 路径 | 后端端口 |
-|------|---------|---------|---------|
-| 孕育无忧 | `/app_03/` | `/app_03/api/*` | 8030 |
-| 婴儿辅食 | `/baby_food/` | `/baby_food/api/*` | 8031 |
-| 宝宝相册 | `/album/` | `/album/api/*` | 8032 |
-
-**后端路由注册：**
+后端统一注册：
 ```python
-# config.py
-api_prefix: str = "/api"  # 后端内部的 API 前缀，与前端 APP_BASE_URL 一致
-
-# routers/__init__.py — 统一注册
+# routers/__init__.py
 router = APIRouter(prefix="/api")
-router.include_router(auth.router)  # auth.router 前缀: /api/auth/xxx
-router.include_router(user.router)  # user.router 前缀: /api/user/xxx
-
-# 单个路由模块定义（routers/user.py）
-router = APIRouter(prefix="/api/user", tags=["user"])
+router.include_router(auth.router)   # /api/auth/xxx
+router.include_router(user.router)   # /api/user/xxx
 ```

-> Nginx 的 `rewrite ^/app_03(/api/.*)$ $1 break` 会将 `/app_03/api/xxx` 剥离为 `/api/xxx` 转发到后端，所以后端不感知外部路径前缀。
+### 4.2 数据库命名

-**路由文件结构：**
-```python
-routers/
-├── __init__.py         # 统一注册所有路由
-├── auth.py             # 认证：exchange-code, dev-login
-├── user.py             # 用户 CRUD
-└── *.py                # 按业务模块拆分
+```
+app_03 / baby_food / album   # 全小写 snake_case = 项目标识
 ```

-### 4.2 数据库命名规范
+同一 MongoDB 实例下各应用数据库平级，不交叉。

-```python
-# config.py
-mongodb_db_name: str = "app_03"   # 数据库名 = 应用标识，与 basename 一致
-```
-
-| 应用 | 数据库名 | 说明 |
-|------|---------|------|
-| 孕育无忧 | `app_03` | 应用目录名 / 项目名 |
-| 婴儿辅食 | `baby_food` | 全小写 snake_case |
-| 宝宝相册 | `album` | 简短标识 |
-
-**规范：**
- 全小写 + 下划线（`snake_case`）
- 与前端 basename 保持一致（去掉首斜杠）
- 与项目目录名保持一致
- 避免用复数（`users` → ❌, `app_03` → ✅）
- 同一 MongoDB 实例下的所有应用数据库平级，无交叉数据
-
-**models 目录结构（每个应用独立）：**
-```python
-models/
-├── __init__.py     # 导出所有模型
-└── user.py         # User Document
-# 业务模型按需新增文件，不跨应用复用
-```
-
-### 4.3 数据模型（Beanie ODM 模板）
+### 4.3 数据模型

 ```python
 class User(Document):
-    openid: str = Field(..., unique=True)  # 微信 openid，用户唯一标识
-    session_key: Optional[str] = None
-    union_id: Optional[str] = None
+    openid: str = Field(..., unique=True)  # 用户唯一标识
    name: str = ""
    phone: Optional[str] = None
    avatar_url: Optional[str] = None
-    is_onboarded: bool = False              # 是否完成引导
-    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
-    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    is_onboarded: bool = False
 ```

-> **注意：** 业务模型按需新增，User 仅作为认证底座，业务数据可新建 Document 或嵌入 User。
+> User 仅作为认证底座。业务数据可新建 Document 或嵌入 User。

-### 4.4 API 响应格式
-
-```python
-# 成功 — 直接返回 Pydantic Model 或 dict
-# 错误 — HTTPException(status_code, detail="中文描述")
-```
-
-### 4.5 服务管理 (serv.sh)
-
-```bash
-# .env 中配置：
-APP_NAME=app_name
-APP_MODULE=app.main:app
-HOST=0.0.0.0
-PORT=8000
-DEV_MODE=1
-
-# 命令：
-./serv.sh start [--reload]     # 启动
-./serv.sh stop                 # 停止
-./serv.sh restart [--reload]   # 重启
-./serv.sh status               # 状态
-./serv.sh logs [YYYY-MM-DD]    # 日志
-```
-
---
-
-## 五、代码模板
-
-### 5.1 新增业务页面
-
-```typescript
-import { useEffect, useState } from "react";
-import { useNavigate } from "react-router";
-import { useUser } from "../context/UserContext";
-import { fetchApi } from "../services/api";
-
-export function XxxPage() {
-  const navigate = useNavigate();
-  const { user, token } = useUser();
-  const [data, setData] = useState(null);
-  const [error, setError] = useState("");
-
-  useEffect(() => {
-    fetchApi("/xxx").then(setData).catch(e => setError(e.message));
-  }, []);
-
-  if (error) return <div className="text-red-500 p-4">{error}</div>;
-  if (!data) return <div className="p-4">加载中...</div>;
-
-  return <div>{/* 业务内容 */}</div>;
-}
-```
-
-### 5.2 新增 API 接口
-
-```typescript
-// api.ts
-export interface XxxDTO {
-  id: string;
-  // ... 业务字段
-}
-
-export async function getXxxList(): Promise<XxxDTO[]> {
-  return fetchApi<XxxDTO[]>("/xxx");
-}
-
-export async function createXxx(data: Record<string, unknown>): Promise<XxxDTO> {
-  return fetchApi<XxxDTO>("/xxx", { method: "POST", body: JSON.stringify(data) });
-}
-```
-
-### 5.3 后端路由模板
-
-```python
-from fastapi import APIRouter, Depends
-from app.middleware.auth import get_current_user
-from app.models.user import User
-
-router = APIRouter(prefix="/api/xxx", tags=["xxx"])
-
-@router.get("/")
-async def list_items(user: User = Depends(get_current_user)):
-    # user.openid / user.id 可用
-    return {"items": [...]}
-
-@router.post("/")
-async def create_item(data: ..., user: User = Depends(get_current_user)):
-    return {"id": "...", ...}
-```
-
---
-
-## 六、安全注意事项
-
-1. JWT 不验证签名 — 信任链依赖于小程序的环境隔离，H5 本身不做额外验证
-2. DEV_MODE 仅控制 dev-login — 生产环境不设此变量
-3. CORS 配置 `cors_origins: *` — 开发环境宽松，生产应限制
-4. 微信 session_key 存入数据库但不对外暴露
-
---
-
-## 七、环境变量 (.env 模板)
+### 4.4 `.env` 完整配置

 ```ini
 # MongoDB
 MONGODB_URL=mongodb://localhost:27017
-MONGODB_DB_NAME=app_name
+MONGODB_DB_NAME=app_03_dev

 # JWT
 JWT_SECRET_KEY=change-this-secret-key
-JWT_ALGORITHM=HS256
-JWT_EXPIRE_MINUTES=10080

-# WeChat
-WECHAT_APP_ID=
-WECHAT_APP_SECRET=
+# CRMEB 内部接口
+CRMEB_BASE_URL=https://shop.douba.top
+CRMEB_API_KEY=sk_...

 # Server
 HOST=0.0.0.0
-PORT=8000
-DEBUG=true
+PORT=8030
 DEV_MODE=1
-
-# CORS
-CORS_ORIGINS=*
 ```

 ---

-## 八、初始化新应用 Checklist
+## 五、CRMEB 内部接口规范

- [ ] 定义项目标识（`app_03`/`baby_food`/`album` 等），保持一致
- [ ] 复制模板 → 修改 `backend/app/config.py` → `app_name`, `mongodb_db_name`, `port`
- [ ] 修改前端 basename：Vite `base` + React Router `basename` + `api.ts` 的 `APP_BASE_URL`
- [ ] 设置 WeChat AppID/Secret（生产环境）
- [ ] 更换 `JWT_SECRET_KEY`
- [ ] 定义业务数据模型（`backend/app/models/`）
- [ ] 编写业务 API 路由（`backend/app/routers/`）
- [ ] 创建前端页面 + 路由配置
- [ ] 添加 Nginx location 块（前端 SPA + API 代理）
- [ ] 启动验证：`DEV_MODE=1` → 浏览器访问 → dev-login → 首页
+### 5.1 接口定义
+
+```
+GET /api/internal/user-info?openid=xxx
+Header: X-Internal-Key: xxx
+```
+
+### 5.2 响应格式
+
+```json
+{
+  "code": 200,
+  "data": {
+    "uid": 7,
+    "nickname": "枫逸",
+    "phone": "13693687880",
+    "avatar": "https://..."
+  }
+}
+```
+
+### 5.3 认证方式
+
+服务间共享密钥，通过 `X-Internal-Key` Header 传递。密钥存入 CRMEB 配置文件或系统设置。
+
+---
+
+## 六、初始化新应用 Checklist
+
+- [ ] 定义项目标识，三处保持一致：Vite base / basename / 数据库名
+- [ ] 复制模板 → 修改 `config.py` → `app_name`、`mongodb_db_name`、`port`
+- [ ] 配置 `.env`：MongoDB / JWT / CRMEB（如果有）/ CORS
+- [ ] 添加 Nginx location 块（`location = /xxx` + `location /xxx/` + `location /xxx/api/`）
+- [ ] 定义业务数据模型 + 编写 API + 编写前端页面
+- [ ] 启动后端 → 构建前端 → 部署 → 验证