166 lines
7.2 KiB
Markdown
166 lines
7.2 KiB
Markdown
# 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，避免全局状态污染。
|