# GEMINI.md - 项目开发规范与上下文指南

本文件是 `corp-mp` 项目的基础开发规范与指令上下文，用于指导未来 AI 助手及团队成员的高效协作。

---

## 1. 项目概述

`corp-mp` 是一个基于 **Taro 4.2.0** 跨端开发框架构建的移动端/小程序项目，核心技术栈为 **React 18 + TypeScript + SCSS + Vite**。

### 核心功能模块
1. **微信快捷授权与 WebView 承载 (`pages/index/index`)**：
   - 页面加载时自动调用 `Taro.login()` 获取微信授权 `code`（即 `wxCode`）。
   - 将 `code` 作为 Query 参数拼接至特定业务 H5 URL（例如 `mpCode=xxx`），使用 `<WebView>` 组件进行全屏承载。
2. **模拟微信原生支付 (`pages/pay/index`)**：
   - 接收后端支付预订单数据。
   - 在微信小程序环境下安全调用 `Taro.requestPayment` 发起微信官方原生支付。
   - 提供优雅的支付状态管理（准备、支付中、支付成功、取消、失败等）和完备的异常捕获与友好提示。

---

## 2. 环境依赖与包管理

- **包管理器**：推荐且必须使用 **`pnpm`**（根目录下存在 `pnpm-lock.yaml`）。
- **Node.js 版本**：建议使用 Node.js v18 或更高版本。
- **运行框架**：Taro 4.2.0。
- **构建编译工具**：Vite 4.x (`@tarojs/vite-runner`)。

---

## 3. 核心命令指南

在执行命令前，请确保已全局安装了 `pnpm`。

### 3.1 依赖安装
```bash
pnpm install
```

### 3.2 微信小程序开发与编译
```bash
# 本地开发（带热更新监听）
pnpm dev:weapp

# 生产环境打包构建
pnpm build:weapp
```
> **提示**：编译产物将默认输出至根目录下的 `/dist` 目录。在微信开发者工具中，应将项目根目录或指定小程序根目录指向该 `/dist`。

### 3.3 H5/Web 端开发与编译
```bash
# 本地 H5 开发
pnpm dev:h5

# 生产 H5 打包
pnpm build:h5
```

### 3.4 其它跨端支持
项目同样提供了对百度小程序 (`swan`)、支付宝小程序 (`alipay`)、字节小程序 (`tt`)、QQ 小程序 (`qq`)、京东小程序 (`jd`)、React Native (`rn`)、鸿蒙 Hybrid (`harmony-hybrid`) 等多端编译指令，其格式均为 `pnpm dev:<platform>` 或 `pnpm build:<platform>`。

---

## 4. 目录结构解析

```text
D:\frontendProject\corp-mp\
├───config\                      # Taro 编译配置文件目录
│   ├───dev.ts                   # 开发环境特定配置
│   ├───index.ts                 # 公共基础配置（Vite 编译器、设计稿尺寸等）
│   └───prod.ts                  # 生产环境特定配置
├───dist\                        # 编译后的输出目录（不可提交至 Git）
├───src\                         # 源代码主体目录
│   ├───app.config.ts            # 小程序全局应用配置（包括页面路由 pages、window 样式等）
│   ├───app.scss                 # 全局公共样式文件
│   ├───app.ts                   # 小程序生命周期与应用入口
│   ├───index.html               # H5 编译使用的 HTML 模版
│   └───pages\                   # 页面模块目录
│       ├───index\               # 授权 WebView 页面
│       │   ├───index.config.ts  # 页面特定配置
│       │   ├───index.scss       # 页面样式（BEM 命名）
│       │   └───index.tsx        # 页面逻辑代码
│       └───pay\                 # 微信支付页面
│           ├───index.config.ts
│           ├───index.scss
│           └───index.tsx
├───types\                       # TypeScript 全局声明目录
│   └───global.d.ts              # Taro 相关的全局补丁与自定义声明
├───.env.development             # 开发环境变量（如 TARO_APP_ID、BASE_URL）
├───.env.production              # 生产环境变量
├───.env.test                    # 测试环境变量
├───project.config.json          # 微信开发者工具项目配置文件
├───tsconfig.json                # TypeScript 配置
├───.eslintrc                    # ESLint 配置（继承 taro/react）
├───stylelint.config.mjs         # Stylelint CSS/SCSS 样式规范配置
└───commitlint.config.mjs        # Git Commit 规范约束配置
```

---

## 5. 开发与编码守则

### 5.1 React 18 编写规范
1. **函数式组件优先**：所有页面和组件均采用 Function Component 与 React Hooks 风格。
2. **Taro 专属生命周期 Hooks**：
   - 页面加载逻辑使用 `useLoad`（而非普通的 `useEffect`），用于准确捕获页面入参和执行初始化。
   - 应用启动钩子使用 `useLaunch`。
3. **状态声明与操作**：
   - 保持 state 尽量扁平，避免无谓的深层嵌套。
   - 在进行非安全型异步操作（如接口请求、支付拉起）时，务必伴随 `loading` 状态的管理，防止用户重复触发。

### 5.2 样式规范
1. **SCSS 与 BEM 命名法**：
   - 为避免多端渲染时的类名冲突，样式推荐采用传统的 **BEM (Block-Element-Modifier)** 规范进行书写。
   - 示例：
     ```scss
     .pay-page {
       .pay-card {
         &--success { color: green; }
         &--failed { color: red; }
       }
       .pay-row {
         &__label { font-weight: bold; }
         &__value { color: #333; }
       }
     }
     ```
2. **移动端自适应**：
   - 默认设计稿尺寸为 `750px`（在 `config/index.ts` 中设定了 `designWidth: 750`）。
   - 在编写 CSS 时，所有尺寸可以直接编写 `px`，Taro 在编译时会根据配置自动将其转换为 `rpx` (小程序端) 或 `rem` (H5 端)。

### 5.3 多端兼容安全调用
在调用一些微信/小程序特有的原生 API（如 `Taro.requestPayment`）时，务必先通过环境判断确保执行安全：
```typescript
if (Taro.getEnv() === Taro.ENV_TYPE.WEAPP) {
  // 仅在微信小程序环境下执行
  await Taro.requestPayment(...)
} else {
  // 其它环境降级或模拟逻辑
}
```

### 5.4 代码校验与规范化
项目配置了严苛的 Lint 和 Git 提交约束，提交前请确保代码不报错：
- **ESLint 校验**：继承自 `taro/react`，并在其中免除了 `react-in-jsx-scope` 限制（允许不显式 `import React`）。
- **Stylelint 校验**：保持 SCSS 代码的整洁性。
- **Commit 规范**：使用 Husky + Commitlint。在进行 Git 提交时，Commit 消息必须严格遵守 Conventional Commits 规范（如 `feat: 新增支付渠道`, `fix: 修复支付状态未更新` 等），否则会导致提交失败。

---

## 6. 新增页面/组件工作流

1. **新建页面目录**：在 `src/pages/` 下新建页面文件夹（如 `src/pages/member/`），并准备 `index.tsx`、`index.scss`、`index.config.ts`。
2. **注册路由**：在 `src/app.config.ts` 的 `pages` 数组中添加页面路径。
   ```typescript
   export default defineAppConfig({
     pages: [
       'pages/index/index',
       'pages/pay/index',
       'pages/member/index', // 新增
     ],
     // ...
   })
   ```
3. **保持状态与路由极简**：对于非必要的全局状态，尽量维持页面局部 State，避免全局状态污染。