# 开发规范 (CRITICAL)

## 包管理器

**必须使用 pnpm**，禁止使用 npm 或 yarn：

```bash
pnpm add <package>           # 安装生产依赖
pnpm add -D <package>        # 安装开发依赖
pnpm install                 # 安装所有依赖
pnpm remove <package>        # 移除依赖
```

## 图片与视频资源使用规范

**强制规则**：图片、视频等静态资源必须通过 TOS 对象存储管理，代码中使用 TOS 返回的 URL 引用。

1. **资源存储方式**：
   - 所有图片和视频资源必须上传到 TOS 对象存储，使用返回的 URL 在代码中引用
   - 需要上传功能时，必须加载 `storage` 技能获取 TOS 上传能力
   - 仅 TabBar 图标允许放在 `src/assets/tabbar/` 下（微信小程序 TabBar 强制要求本地 PNG），其余一律走 TOS

2. **禁止事项**：
   - 禁止将大图片、视频等资源直接打包到项目中（会导致包体积超限）
   - 禁止使用 `https://via.placeholder.com/` 等占位符服务
   - 禁止使用 `/images/placeholder.jpg` 等虚构路径
   - 禁止使用 `https://example.com/` 等示例域名

3. **正确实践**：

   ```tsx
   // ✅ 使用 TOS 对象存储返回的 URL
   <Image src={tosImageUrl} />

   // ❌ 禁止将图片打包到项目（TabBar 图标除外）
   <Image src="/assets/logo.png" />

   // ❌ 禁止使用占位符
   <Image src="https://via.placeholder.com/300" />
   ```

## Git 提交规范

项目使用 Commitlint 强制规范提交信息：

```bash
git commit -m "feat: 新增用户登录功能"
git commit -m "fix: 修复列表加载问题"
git commit -m "style: 优化首页样式"
```

## 命名规范

**命名规范**：

- **文件名**：使用 kebab-case，例如 `user-profile.tsx`
- **组件名**：使用 PascalCase，例如 `UserProfile`
- **变量/函数**：使用 camelCase，例如 `getUserInfo`
- **常量**：使用 UPPER_SNAKE_CASE，例如 `API_BASE_URL`
- **类型/接口**：使用 PascalCase，例如 `UserInfo`
- **CSS 类名**：使用 Tailwind css

## 组件库

Taro 版 shadcn/ui 组件库在 `@/components/ui` 路径下，使用 `ls src/components/ui` 可查看所有可用组件。你可以随意使用或修改这个目录下的组件源代码。

可用组件总览如下：

| 组件名称       | 导入路径                          | 典型使用场景                       | 选型提示                             |
| -------------- | --------------------------------- | ---------------------------------- | ------------------------------------ |
| Accordion      | `@/components/ui/accordion`       | FAQ、设置分组、折叠内容列表        | 适合分段展开/收起内容                |
| Alert          | `@/components/ui/alert`           | 页面内提示、风险提醒、状态说明     | 纯展示型提示，不承载强交互           |
| AlertDialog    | `@/components/ui/alert-dialog`    | 删除确认、危险操作二次确认         | 比普通 Dialog 更适合高风险确认       |
| AspectRatio    | `@/components/ui/aspect-ratio`    | 图片卡片、视频封面、媒体占位       | 需要固定宽高比时优先使用             |
| Avatar         | `@/components/ui/avatar`          | 用户头像、群组头像、评论区身份展示 | 支持图片与 fallback 文本             |
| Badge          | `@/components/ui/badge`           | 状态标签、分类标记、数量标识       | 适合轻量状态标识，不替代按钮         |
| Breadcrumb     | `@/components/ui/breadcrumb`      | 层级导航、路径回溯                 | 适合多层信息架构或管理后台           |
| Button         | `@/components/ui/button`          | 提交、确认、取消、主次操作入口     | 所有通用按钮优先用它，不手搓         |
| ButtonGroup    | `@/components/ui/button-group`    | 连续操作按钮、分组操作栏           | 适合同一语义下的多个并列操作         |
| Calendar       | `@/components/ui/calendar`        | 日期选择、签到、行程安排           | 需要可视化日期面板时使用             |
| Card           | `@/components/ui/card`            | 信息卡片、列表项容器、模块分组     | 页面块级容器优先考虑它               |
| Carousel       | `@/components/ui/carousel`        | 轮播图、引导页、Banner 展示        | 多张内容横向切换时使用               |
| Checkbox       | `@/components/ui/checkbox`        | 多选表单、协议勾选、批量选择       | 多项可同时选中时用 Checkbox          |
| CodeBlock      | `@/components/ui/code-block`      | 代码展示、命令示例、技术说明       | 展示代码片段时优先复用               |
| Collapsible    | `@/components/ui/collapsible`     | 展开更多、收起详情、简化视图       | 单块内容折叠比 Accordion 更轻        |
| Command        | `@/components/ui/command`         | 命令面板、搜索动作入口、快捷操作   | 适合“搜索 + 选择动作”交互            |
| ContextMenu    | `@/components/ui/context-menu`    | 长按菜单、上下文操作菜单           | 适合局部对象的附加操作               |
| Dialog         | `@/components/ui/dialog`          | 普通弹窗、表单弹层、信息确认       | 非危险弹窗默认优先用 Dialog          |
| Drawer         | `@/components/ui/drawer`          | 底部抽屉、移动端筛选面板           | 更适合移动端从边缘滑出的层           |
| DropdownMenu   | `@/components/ui/dropdown-menu`   | 更多操作、头像菜单、筛选菜单       | 适合触发后展示短菜单列表             |
| Field          | `@/components/ui/field`           | 表单项布局、标签与控件对齐         | 统一表单结构时优先使用               |
| HoverCard      | `@/components/ui/hover-card`      | 预览卡片、悬停详情、补充信息       | 适合轻量预览，不适合关键流程         |
| Input          | `@/components/ui/input`           | 单行输入、搜索框、账号密码输入     | 通用单行输入必须优先使用             |
| InputGroup     | `@/components/ui/input-group`     | 带前后缀输入框、搜索栏、金额输入   | 输入框需嵌入图标/按钮时使用          |
| InputOTP       | `@/components/ui/input-otp`       | 验证码、短信口令、一次性密码输入   | OTP 场景不要自行拆格手搓             |
| Label          | `@/components/ui/label`           | 表单标签、字段说明、输入关联文本   | 与 Input/Checkbox 等配合使用         |
| Menubar        | `@/components/ui/menubar`         | 顶部菜单栏、桌面式功能菜单         | 适合较复杂的菜单层级                 |
| NavigationMenu | `@/components/ui/navigation-menu` | 导航入口、站点级菜单、分栏导航     | 用于页面级或模块级导航               |
| Pagination     | `@/components/ui/pagination`      | 分页列表、表格翻页、结果页码导航   | 数据量大需分页时优先使用             |
| Popover        | `@/components/ui/popover`         | 浮层说明、轻量表单、局部附加内容   | 比 Dialog 更轻，比 Tooltip 更丰富    |
| Portal         | `@/components/ui/portal`          | 浮层挂载、顶层渲染容器             | 一般作为底层能力，业务少直接使用     |
| Progress       | `@/components/ui/progress`        | 上传进度、任务进度、完成度展示     | 线性进度反馈优先用它                 |
| RadioGroup     | `@/components/ui/radio-group`     | 单选题、规格选择、互斥选项         | 互斥选择不要用 Checkbox 替代         |
| Resizable      | `@/components/ui/resizable`       | 可拖拽分栏、面板尺寸调整           | 适合复杂布局或工作台场景             |
| ScrollArea     | `@/components/ui/scroll-area`     | 自定义滚动区域、长列表容器         | 局部滚动区域优先考虑它               |
| Select         | `@/components/ui/select`          | 下拉选择、选项筛选、单项选择器     | 标准选项选择器优先用 Select          |
| Separator      | `@/components/ui/separator`       | 分割线、内容区块分隔               | 视觉分隔优先用它，不手写边框线       |
| Sheet          | `@/components/ui/sheet`           | 侧边栏、抽屉面板、配置面板         | 适合从边缘滑出的补充面板             |
| Skeleton       | `@/components/ui/skeleton`        | 加载骨架屏、列表占位、页面预加载   | 加载态优先用 Skeleton，不写灰块假 UI |
| Slider         | `@/components/ui/slider`          | 音量、价格区间、数值拖动调节       | 连续数值输入优先用 Slider            |
| Sonner         | `@/components/ui/sonner`          | 轻提示、操作反馈、全局消息提醒     | 偏轻量 toast 通知能力                |
| Switch         | `@/components/ui/switch`          | 开关设置、布尔状态切换             | 开/关场景优先用 Switch               |
| Table          | `@/components/ui/table`           | 数据表格、对账列表、结构化信息展示 | 表格型数据不要用 View 手搓           |
| Tabs           | `@/components/ui/tabs`            | 分段切换、内容分类、频道页         | 标签切换场景优先用 Tabs              |
| Textarea       | `@/components/ui/textarea`        | 多行输入、备注、评论、反馈内容     | 多行文本输入必须优先使用             |
| Toast          | `@/components/ui/toast`           | 操作结果提示、失败提醒、短时反馈   | 适合局部或系统级短反馈               |
| Toggle         | `@/components/ui/toggle`          | 单个开关按钮、格式切换、选中态按钮 | 适合按钮式开/关选择                  |
| ToggleGroup    | `@/components/ui/toggle-group`    | 多个切换按钮组合、视图模式选择     | 适合按钮组式互斥/多选切换            |
| Tooltip        | `@/components/ui/tooltip`         | 图标说明、补充提示、悬停解释       | 只放简短解释，不承载复杂内容         |

IMPORTANT: 优先使用 `@/components/ui` 下的组件，只对必要情况（如组件库缺失组件，或者 View、Text、Camera、Canvas 等无需封装的组件）才能直接使用 `@tarojs/components` 原生组件。

CRITICAL（执行约束）：

- 只要涉及“通用 UI 组件”（按钮/输入框/弹窗/表单控件/菜单/提示/卡片/表格/标签页等），必须先在 `src/components/ui` 查找并优先使用；存在即从 `@/components/ui/*` 导入使用。
- 禁止用 `View/Text` + Tailwind 手搓上述通用组件的外观与交互，除非组件库确实缺失且你已按下条补齐或说明理由。
- 组件库缺失时，优先把组件补齐到 `src/components/ui`（可复用、可维护），再在页面中引用；不要在页面/业务组件里临时造轮子。
- 页面实现前必须先判断：按钮、输入框、卡片、标签、Tabs、弹窗、Toast、Skeleton 等是否已有 `@/components/ui/*` 可复用；能用组件库的地方，不要退回原生组件或单独写样式。
- 若最终没有使用 `@/components/ui/*` 中已存在的通用组件，必须先自查并改回；不要把“赶时间”当作例外理由。
- 以上规则以页面级 ESLint 作为兜底；若页面中直接使用原生 `Input`，或用 `View/Text` 手搓通用 UI，`pnpm validate` 会报错。

示例：

```tsx
// ✅ 优先使用 ui 组件
import { Button } from '@/components/ui/button'
import { Card, CardContent } from '@/components/ui/card'
import { Text } from '@tarojs/components'

<Card>
  <CardContent className="p-4">
    <Button onClick={() => {}}>
      <Text>提交</Text>
    </Button>
  </CardContent>
</Card>
```

```tsx
// ❌ 不要手搓“按钮/弹窗/输入框”等通用组件（除非组件库缺失）
import { View, Text } from '@tarojs/components'

<View className="px-4 py-2 rounded bg-primary">
  <Text className="text-primary-foreground">提交</Text>
</View>
```

## 样式开发

IMPORTANT：样式默认优先使用 Tailwind。凡是 Tailwind 能表达的样式，都不要退回 `style` 或 `.css`；只有动画、关键帧、复杂选择器、第三方组件覆盖、框架级兼容处理等场景，才允许少量使用 CSS。

CRITICAL：

- 默认先写 `className`，再考虑 `style`。
- 颜色、间距、圆角、边框、阴影、排版、flex/grid、宽高等常规样式必须收敛在 Tailwind 类名中。
- 禁止使用 `w-[340px]`、`text-[14px]`、`p-[16px]` 这类带 `px` 的 Tailwind 任意值。
- 禁止使用 `style={{ width: '200px' }}`、`fontSize: '14px'` 这类硬编码尺寸。
- Taro 会通过 `pxtransform` 将尺寸转换为跨端单位（小程序 `rpx`、H5 `rem`），业务代码里直接写 `px` 容易导致不同端显示不一致。
- `style` 只允许用于少量跨端兼容修正；`.css` 只用于 Tailwind 明显不适合的场景，且范围必须最小。
- 若页面主要样式本可用 Tailwind 表达，却仍主要来自 `style={{ ... }}` 或 `.css` 文件，视为不合规实现。

> 项目已集成 Tailwind CSS 4 + weapp-tailwindcss，支持跨端原子化样式：

```tsx
<View className="flex flex-col h-full">
  <Text className="text-2xl font-bold text-blue-600 mb-4">标题</Text>
  <View className="w-full px-4">
    <Button className="w-full bg-blue-500 text-white rounded-lg py-3">
      按钮
    </Button>
  </View>
</View>
```

**推荐做法**：优先使用 Tailwind 预设类名或相对单位，避免硬编码 `px`。

```tsx
// ❌ 错误：硬编码 px 值，跨端显示不一致
<View className="w-[340px] h-[200px] p-[16px]">
  <Text className="text-[14px]">内容</Text>
</View>

// ✅ 正确：使用 Tailwind 预设类名
<View className="w-full max-w-sm h-48 p-4">
  <Text className="text-sm">内容</Text>
</View>
```

## 图标库 (lucide-react-taro)

项目使用 `lucide-react-taro` 作为图标库，这是 Lucide 图标的 Taro 适配版本，已经进行预安装。

### 渲染原理（微信小程序端）

每个 icon 不是用 `<svg />` 渲染，而是把 SVG 字符串编码成 `data:image/svg+xml,...`，再用 `@tarojs/components` 的 `<Image />` 渲染。

这带来一个关键结论：`className` 只作用在 `<Image />` 本身（布局/外边距/对齐等），不会作用到 SVG 内部的 `stroke/fill`，也不会从父级继承 `currentColor`。

### 用法示例

✅ 正确示例（优先用 `color/size/strokeWidth`，避免再额外写尺寸样式）

```tsx
import { House, Settings, Camera } from 'lucide-react-taro'

<House />
<Settings size={32} />
<Camera color="#ff0000" />
<Camera size={48} color="#1890ff" strokeWidth={1.5} />

<House className="mr-2" size={18} color="#1890ff" />
```

❌ 错误示例（`className` 的 `text-*` 不会改变 icon 的 `stroke/fill`；它只是 `<Image />` 的 class）

```tsx
import { House } from 'lucide-react-taro'

<House className="text-red-500 w-8 h-8" />
```

### 查找可用图标

图标命名与 Lucide 官方一致（PascalCase），完整列表可使用命令查询：

```bash
npx taro-lucide-find --list
```

推荐在生成代码前，使用 `--json` 参数批量验证图标是否存在：

```bash
npx taro-lucide-find arrow-up user settings arw --json
```

## 网络请求规范 (Network Request Guidelines)

### 1. 全局路由前缀

项目后端入口 `main.ts` 中已配置 `app.setGlobalPrefix('api')`，所有路由会自动加上 `/api` 前缀。

**严格约束**：

后端响应状态码：在编写 NestJS 后端接口时，我会显式处理 HTTP 状态码，确保所有成功的请求（包括通常默认返回 201 的 POST 请求）统一返回 HTTP 200 OK。

在编写 NestJS Controller 代码时，**绝对禁止**在 `@Controller()` 或 `@Get()`/`@Post()` 等路由装饰器的路径中手动添加 `api` 字样。

**示例**：

- ✅ 正确：`@Controller('users')` (实际路由: `/api/users`)
- ❌ 错误：`@Controller('api/users')` (实际路由: `/api/api/users`)

### 2. 发送请求

Network 是对 Taro.request、Taro.uploadFile、Taro.downloadFile 的封装，自动添加项目域名前缀，参数与 Taro 一致。

IMPORTANT: 禁止直接使用 Taro.request、Taro.uploadFile、Taro.downloadFile，使用 Network.request、Network.uploadFile、Network.downloadFile 替代。

IMPORTANT: 禁止自己封装 Network 类/库/文件，必须使用预先封装好的 Network `import { Network } from '@/network'`

IMPORTANT: 如无必要，禁止修改 `@/network` 中的文件，即使遇到 tsc 类型报错，也不能修改

✅ 正确使用方式

```typescript
import { Network } from '@/network'

// GET 请求
const data = await Network.request({
  url: '/api/hello'
})

// POST 请求
const result = await Network.request({
  url: '/api/user/login',
  method: 'POST',
  data: { username, password }
})

// 文件上传
await Network.uploadFile({
  url: '/api/upload',
  filePath: tempFilePath,
  name: 'file'
})

// 文件下载
await Network.downloadFile({
  url: '/api/download/file.pdf'
})
```

❌ 错误用法

```typescript
import Taro from '@tarojs/taro'

// ❌ 会导致自动域名拼接无法生效，除非是特殊指定域名
const data = await Network.request({
  url: 'http://localhost/api/hello'
})

// ❌ 不要直接使用 Taro.request
await Taro.request({ url: '/api/hello' })

// ❌ 不要直接使用 Taro.uploadFile
await Taro.uploadFile({ url: '/api/upload', filePath, name: 'file' })
```

### 3. URL 构建规范 (CRITICAL)

**禁止硬编码 localhost 或域名到请求 URL 中**

在使用 `Network.request`、`Network.uploadFile`、`Network.downloadFile` 等 API 时，**严禁**硬编码完整的域名或 localhost 地址。

**错误示范**：

```typescript
// ❌ 错误：硬编码 localhost 地址
await fetch('http://localhost:3000/api/knowledge/chat', {
  method: 'POST',
  body: JSON.stringify({ message })
})

// ❌ 错误：硬编码域名
await Network.request({
  url: 'http://example.com/api/hello'
})
```

**正确做法**：

```typescript
// ✅ 正确：使用相对路径，让 Network 自动处理
await Network.request({
  url: '/api/knowledge/chat',
  method: 'POST',
  data: { message }
})

// ✅ 正确：如果需要使用外部域名，显式判断
const isExternalUrl = url.startsWith('http://') || url.startsWith('https://')
if (isExternalUrl) {
  // 使用完整 URL
  await Network.request({ url })
} else {
  // 使用相对路径，Network 会自动添加 PROJECT_DOMAIN
  await Network.request({ url: '/api/...' })
}
```

**工作原理**：

1. **开发环境（H5）**：使用 `/api/xxx` 相对路径，Vite 的 proxy 会自动将其代理到后端；后端端口读取 `SERVER_PORT`，未设置时使用模板默认端口 `<%= serverPort %>`
2. **生产环境**：如果配置了 `PROJECT_DOMAIN` 环境变量，Network 会自动拼接为 `${PROJECT_DOMAIN}/api/xxx`
3. **小程序端**：同样会根据 `PROJECT_DOMAIN` 配置使用正确的域名

**Vite 代理配置**（已在项目中配置，无需修改）：

```typescript
// config/index.ts
const serverPort = Number(process.env.SERVER_PORT) || <%= serverPort %>

export default {
  h5: {
    devServer: {
      proxy: {
        '/api': {
          target: `http://localhost:${serverPort}`,
          changeOrigin: true
        }
      }
    }
  }
}
```

**关键原则**：

- ✅ 始终使用 `/api/xxx` 形式的相对路径
- ✅ 让 Network 自动处理域名拼接
- ✅ 在 H5 开发环境中依赖 Vite proxy
- ❌ 禁止硬编码 `http://localhost:3000`
- ❌ 禁止在业务代码中使用 `fetch` 直接调用 API

### 4. 接口数据解包与防御性编程 (API Response Handling & Unwrapping)

**警惕 "嵌套 Data" 陷阱 (Critical: The Double Data Trap)**
在处理前后端交互时，必须敏锐识别数据结构的嵌套层级：

1. **第一层 (`res.data`)**：`Taro.request` 返回的对象包含 `statusCode`, `header`, `data`。这里的 `data` 是 HTTP 响应体。
2. **第二层 (`res.data.data`)**：现代后端（NestJS）通常遵循 "Envelope Pattern"（信封模式），将业务数据再次封装在 JSON 的 `data` 字段中（如 `{ code: 200, msg: "success", data: { ... } }`）。

**严格执行以下约束：**
- **先打印，后访问**：在编写数据处理逻辑前，必须先 `console.log(res.data)` 确认后端返回的 JSON 结构。
- **拒绝盲目直连**：禁止想当然地认为 `res.data` 就是业务对象。
- **防御性取值**：优先使用可选链 (`?.`) 或编写明确的解包逻辑。
- **TypeScript 强类型**：如果可能，应定义通用的 `ApiResponse<T>` 接口来强制提示数据层级。

**错误示范 (Don't do this)**：

```typescript
// ❌ 假设后端直接返回了用户对象，实际上后端返回的是包裹后的 JSON
const { avatar_url } = res.data; // 报错或 undefined
```

## H5/小程序跨端兼容性（CRITICAL）

### 跨端规则速查表

- Taro 原生 Text 换行/白屏：小程序 block 正常，H5 inline 白屏 → 垂直 Text 添加 `block` 类 + 平台检 测直接判断
- Taro 原生 Input 样式：H5 端 inline 导致样式失效 → View 包裹，样式放外层
- Taro 原生 Input/Button Flex：H5 不支持 flex → View 包装，flex 放 View 上
- Fixed + Flex：H5 Tailwind 失效 → 必须 `style={{ position: 'fixed', display: 'flex' }}`
- 底部 TabBar 重叠 → 底部固定元素 `bottom: 50`+，列表加底部内边距
- 原生组件：H5 不可用 → `Taro.getEnv() === WEAPP` + H5 降级
- RecorderManager：H5 报错 → 检测平台 + useEffect 初始化 + H5 降级
- 文件上传：H5 readFile 报错 → 用 `Network.uploadFile(tempFilePath)`
- 后端文件读取：小程序 file.path / H5 file.buffer → 同时支持两种方式
- H5 上传图片偶发裂开：Coze 平台 SW 拦截 blob fetch → H5 端取原始 File 对象手动构建 FormData 上传，绕过 Taro uploadFile

### 一、强制规范与代码模板

平台检测直接判断，禁止 useState + useEffect 设置平台（会导致状态延迟、H5 白屏）

```tsx
// ✅ 正确
const isWeapp = Taro.getEnv() === Taro.ENV_TYPE.WEAPP
// ❌ 错误：状态延迟导致初始渲染错误
const [isWeapp, setIsWeapp] = useState(false)
useEffect(() => { setIsWeapp(Taro.getEnv() === Taro.ENV_TYPE.WEAPP) }, [])
```

**Taro 原生 Text 换行**：所有垂直排列的 Text 必须添加 `block`

```tsx
<Text className="block text-lg font-semibold">标题</Text>
<Text className="block text-sm text-gray-500">说明</Text>
```

**Taro 原生 Input/Textarea 样式**：必须 View 包裹，样式放 View 上（H5 端 Input 是 inline 元素）

```tsx
// ✅ 正确：View 包裹
<View className="bg-gray-50 rounded-xl px-4 py-3">
  <Input className="w-full bg-transparent" placeholder="请输入内容" />
</View>
// ❌ 错误：H5 端样式不生效
<Input className="bg-gray-50 rounded-xl px-4 py-3 w-full" />

// ✅ Textarea 同理
<View className="bg-gray-50 rounded-2xl p-4 mb-4">
  <Textarea style={{ width: '100%', minHeight: '100px', backgroundColor: 'transparent' }} placeholder="请输入详细描述..." maxlength={500} />
</View>
```

**Taro 原生 Input + Button Flex 布局**：flex 放 View，Input 用 `width: 100%`

```tsx
// ✅ 正确：View 包装 + inline style
<View style={{ display: 'flex', flexDirection: 'row', gap: '8px', padding: '12px' }}>
  <View style={{ flex: 1, backgroundColor: '#f5f5f5', borderRadius: '20px', padding: '8px 12px' }}>
    <Input style={{ width: '100%', fontSize: '14px' }} placeholder="输入消息..." />
  </View>
  <View style={{ flexShrink: 0 }}>
    <Button size="mini" type="primary">发送</Button>
  </View>
</View>
// ❌ 错误：H5 端 Input 不支持 flex
<View style={{ display: 'flex', flexDirection: 'row', gap: '8px' }}>
  <Input style={{ flex: 1 }} placeholder="输入消息..." />
  <Button>发送</Button>
</View>
```

**Fixed + Flex 布局**：必须 inline style（Tailwind fixed+flex 在 H5 失效），`bottom: 50` 避开 TabBar

```tsx
// ✅ 正确：inline style + 避开 TabBar
<View style={{
  position: 'fixed', bottom: 50, left: 0, right: 0,
  display: 'flex', flexDirection: 'row', gap: '12px',
  padding: '12px', backgroundColor: '#fff', borderTop: '1px solid #e5e5e5', zIndex: 100
}}>
  <View style={{ flex: 1 }}><Button>取消</Button></View>
  <View style={{ flex: 1 }}><Button>确认</Button></View>
</View>
// ❌ 错误：Tailwind fixed+flex H5 失效，bottom-0 被 TabBar 遮挡
<View className="fixed bottom-0 left-0 right-0 flex flex-row gap-3 p-4 bg-white z-50">
  <Button className="flex-1">取消</Button>
</View>
```

### 二、原生组件平台检测

**需检测组件**: Camera, Map, Canvas, Video, RecorderManager

```tsx
{Taro.getEnv() === Taro.ENV_TYPE.WEAPP ? (
  <Camera className="w-full h-96" devicePosition="back" />
) : (
  <View className="flex items-center justify-center h-96 bg-gray-100 rounded-lg">
    <Text className="block text-gray-500 text-center">
      相机功能仅在小程序中可用{'\n'}请在微信小程序中打开体验完整功能
    </Text>
  </View>
)}
```