docs: 新增 CLAUDE.md 项目架构文档

2026-06-14 23:13:15 +08:00
parent 332808648d
commit 3d00309d56
1 changed files with 144 additions and 0 deletions
@@ -0,0 +1,144 @@
+# zhy-test — 产研部用户端微信小程序
+
+## 项目定位
+
+**湖南12301文旅专区**用户端微信小程序（C端），基于 uni-app + Vue 3 + TypeScript + Pinia。仅包含用户端功能，不含管理端。
+
+## 技术栈
+
+| 技术 | 版本 | 说明 |
+|------|------|------|
+| Vue | 3.5.x | 核心框架 |
+| uni-app | 3.0.0 | 跨平台框架（当前仅编译微信小程序） |
+| TypeScript | 5.x | 类型系统 |
+| Pinia | 3.x | 状态管理（仅 user store） |
+| Vite | 5.2.8 | 构建工具 |
+| @dcloudio/uni-ui | 1.5.12 | UI 组件库（easycom 自动导入） |
+
+## 微信小程序配置
+
+- **AppID**: `wx636bc46a6570e9fd`
+- **后端接口前缀**: `/mp-api`（对应后端 `RouteChannel.MP_API`）
+- **API 基础地址**: 由 `.env.*` 文件的 `VITE_API_BASE_URL` 控制
+
+## 目录结构
+
+```
+zhy-test/
+├── src/
+│   ├── api/                          # API 接口层
+│   │   ├── request.ts                # HTTP 封装（uni.request + Token 注入 + 401 处理）
+│   │   ├── types.ts                  # TypeScript 类型定义
+│   │   ├── user.ts                   # 微信登录 + 用户信息
+│   │   ├── card.ts                   # 年卡列表/详情/激活/绑定/入园码
+│   │   └── order.ts                  # 订单创建/支付/查询
+│   ├── components/                   # 公共组件
+│   │   ├── McGlass.vue               # 毛玻璃卡片
+│   │   ├── card-item.vue             # 年卡列表项
+│   │   └── empty-state.vue           # 空状态占位
+│   ├── config/
+│   │   └── index.ts                  # API_BASE / TOKEN_KEY / REFRESH_TOKEN_KEY
+│   ├── pages/                        # 主包页面
+│   │   ├── index/index.vue           # 首页（轮播 + 热门景区 + 精选活动）
+│   │   ├── login/login.vue           # 登录页（微信手机号授权登录）
+│   │   └── profile/index.vue         # 个人中心（tabBar）
+│   ├── packages/user/pages/card/     # 分包：年卡功能（减小主包体积）
+│   │   ├── list.vue                  # 年卡列表（搜索 + 分类筛选）
+│   │   ├── detail.vue                # 年卡详情（权益 + 景区 + 富文本）
+│   │   ├── buy.vue                   # 购买确认 + 模拟支付
+│   │   ├── activate.vue              # 实名激活（姓名 + 身份证 + 手机）
+│   │   ├── qrcode.vue                # 入园码（60秒自动刷新）
+│   │   └── bind.vue                  # 卡号绑定
+│   ├── static/                       # 静态资源（logo + tabBar 图标）
+│   ├── store/
+│   │   └── user.ts                   # 用户状态（token 持久化 + 登录判断）
+│   ├── utils/
+│   │   └── index.ts                  # 工具函数（showToast / navigateTo 等）
+│   ├── App.vue                       # 根组件（隐私协议检查 + 自动获取用户信息）
+│   ├── main.ts                       # 入口（createSSRApp + Pinia）
+│   ├── manifest.json                 # uni-app 配置（AppID）
+│   ├── pages.json                    # 路由 + tabBar + 分包 + easycom
+│   └── uni.scss                      # 全局 SCSS 变量
+├── .env.local                        # 本地开发环境
+├── .env.dev                          # 开发环境
+├── .env.uat                          # UAT 环境
+├── package.json
+├── vite.config.ts
+└── tsconfig.json
+```
+
+## 架构设计
+
+### 分层
+
+```
+页面(.vue) → API 层(api/*.ts) → HTTP 封装(request.ts) → uni.request → 后端
+                ↕
+          Store(store/user.ts) ← 仅管理 token + 登录状态
+```
+
+- **页面直接调用 API**，不经过 store（年卡、订单等模块）
+- **只有 user 模块使用 store**，因为需要跨页面共享 token 和登录状态
+- **request.ts** 统一处理 Token 注入、401 跳转、响应格式解析
+
+### 后端对接
+
+- 后端项目：`jxxx-dscp`（Spring Boot 2.7 + MyBatis-Plus）
+- 路由渠道：`RouteChannel.MP_API`（`/mp-api`）
+- 认证方式：Bearer Token（`Authorization: Bearer {accessToken}`）
+- 响应格式：`{ errcode, errmsg, data, traceid }`（框架自动包装 `ResDto`）
+- 用户表：`member` 表，`channel = 99`（Channel_CY，产研小程序）
+- Token 表：`system_oauth2_access_token`，`clientId = "mp-99"`
+
+### 微信登录流程
+
+```
+前端 button[open-type=getPhoneNumber]
+  → phoneCode + wx.login() → loginCode
+  → POST /mp-api/auth/wx-login { loginCode, phoneCode }
+  → 后端 jscode2session → openId
+  → 后端 getuserphonenumber → phoneNumber
+  → 查找/创建 member → 创建 token
+  → 返回 LoginResponse { accessToken, refreshToken, userId, openId, mobile }
+```
+
+## 运行命令
+
+```bash
+# 安装依赖
+pnpm install
+
+# 微信小程序开发构建
+pnpm run dev:mp-weixin
+
+# 微信小程序生产构建
+pnpm run build:mp-weixin
+
+# 构建产物目录
+dist/build/mp-weixin/   # 用微信开发者工具导入此目录
+```
+
+## 环境配置
+
+| 文件 | API 地址 | 用途 |
+|------|---------|------|
+| `.env.local` | `http://localhost:48080` | 本地开发（配合后端 `--spring.profiles.active=local`） |
+| `.env.dev` | `https://dscp-dev.hn12301.net` | 开发环境 |
+| `.env.uat` | UAT 环境地址 | UAT 测试 |
+
+## 数据库环境
+
+| 环境 | 地址 | 数据库 |
+|------|------|--------|
+| 本地（local profile） | `localhost:3306` | `dscp_business_dev` |
+| 开发（dev） | `120.26.254.65:3306` | `dscp_business_dev` |
+| UAT | `47.99.164.129:3306` | `dscp_business` |
+
+## 开发注意事项
+
+1. **API 前缀**：所有接口走 `/mp-api`（不是 `/manage-api`，那是管理后台）
+2. **Token 管理**：`app_token` / `app_refresh_token` 存在 `uni.storage` 中
+3. **分包策略**：年卡功能放分包（`packages/user`），首页/登录/个人中心在主包
+4. **条件编译**：`#ifdef MP-WEIXIN` 包裹微信特有逻辑
+5. **隐私协议**：`App.vue` 中 `wx.getPrivacySetting` 检查，未同意前不能调授权 API
+6. **微信开发者工具调试**：需勾选「不校验合法域名」才能请求 localhost