7.2 KiB

Raw Blame History

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

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

1. 项目概述

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

核心功能模块

微信快捷授权与 WebView 承载 (pages/index/index)：
- 页面加载时自动调用 Taro.login() 获取微信授权 code（即 wxCode）。
- 将 code 作为 Query 参数拼接至特定业务 H5 URL（例如 mpCode=xxx），使用 <WebView> 组件进行全屏承载。
模拟微信原生支付 (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 依赖安装

pnpm install

3.2 微信小程序开发与编译

# 本地开发（带热更新监听）
pnpm dev:weapp

# 生产环境打包构建
pnpm build:weapp

提示：编译产物将默认输出至根目录下的 /dist 目录。在微信开发者工具中，应将项目根目录或指定小程序根目录指向该 /dist。

3.3 H5/Web 端开发与编译

# 本地 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. 目录结构解析

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 编写规范

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

5.2 样式规范

SCSS 与 BEM 命名法：

为避免多端渲染时的类名冲突，样式推荐采用传统的 BEM (Block-Element-Modifier) 规范进行书写。

示例：

.pay-page {
  .pay-card {
    &--success { color: green; }
    &--failed { color: red; }
  }
  .pay-row {
    &__label { font-weight: bold; }
    &__value { color: #333; }
  }
}

移动端自适应：
- 默认设计稿尺寸为 750px（在 config/index.ts 中设定了 designWidth: 750）。
- 在编写 CSS 时，所有尺寸可以直接编写 px，Taro 在编译时会根据配置自动将其转换为 rpx (小程序端) 或 rem (H5 端)。

5.3 多端兼容安全调用

在调用一些微信/小程序特有的原生 API（如 Taro.requestPayment）时，务必先通过环境判断确保执行安全：

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. 新增页面/组件工作流

新建页面目录：在 src/pages/ 下新建页面文件夹（如 src/pages/member/），并准备 index.tsx、index.scss、index.config.ts。

注册路由：在 src/app.config.ts 的 pages 数组中添加页面路径。

export default defineAppConfig({
  pages: [
    'pages/index/index',
    'pages/pay/index',
    'pages/member/index', // 新增
  ],
  // ...
})

保持状态与路由极简：对于非必要的全局状态，尽量维持页面局部 State，避免全局状态污染。

7.2 KiB Raw Blame History Unescape Escape