# wzkris-mini
**Repository Path**: wzkris/wzkris-mini
## Basic Information
- **Project Name**: wzkris-mini
- **Description**: 微信小程序端
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-11
- **Last Updated**: 2025-12-11
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# wzkris-mini
这是一个基于微信小程序的企业级应用开发框架，使用 TypeScript 和 TDesign 组件库构建。项目提供了完整的认证体系、请求封装、状态管理等基础功能，适合快速搭建企业级小程序应用。
## 技术栈
- **开发语言**：TypeScript
- **样式预处理**：SCSS
- **UI 组件库**：TDesign Miniprogram (v1.11.2)
- **渲染引擎**：Skyline (微信小程序新渲染引擎)
- **组件框架**：Glass-easel
- **开发工具**：微信开发者工具
## 功能特性
### 核心功能
- **双认证体系**：支持客户（Customer）和租户（Tenant）两种认证类型，可同时管理多套 token
- **智能请求封装**：统一的请求拦截和响应拦截处理，自动 token 刷新，错误统一处理
- **数据字典**：支持字典数据缓存和请求缓存，提供便捷的数据转换工具
- **状态管理**：基于本地存储的状态管理，支持用户信息、token、租户信息等
- **环境适配**：自动识别开发、体验、生产环境，支持 API 地址动态配置
- **自定义导航栏**：自动计算胶囊按钮位置，统一页面布局适配
- **自定义 TabBar**：支持自定义底部导航栏样式和交互
### 页面功能
- **首页**：应用主页面
- **咨询**：咨询服务相关功能
- **我的**：个人中心，包含个人信息、钱包记录等
- **登录**：用户登录认证
- **租户管理**：租户中心、租户信息、成员管理、通知管理等
## 项目结构
```
wzkris-mini/
├── miniprogram/ # 小程序源码目录
│ ├── api/ # API 接口封装
│ │ ├── core/ # 核心 API（认证、客户、租户等）
│ │ ├── dictionary/ # 数据字典 API
│ │ ├── message/ # 消息通知 API
│ │ └── request.ts # 请求封装
│ ├── components/ # 自定义组件
│ │ └── navigation-bar/ # 导航栏组件
│ ├── custom-tab-bar/ # 自定义 TabBar
│ ├── pages/ # 页面目录
│ │ ├── home/ # 首页
│ │ ├── consult/ # 咨询页
│ │ ├── mine/ # 我的
│ │ │ ├── profile/ # 个人信息
│ │ │ └── wallet-records/ # 钱包记录
│ │ ├── login/ # 登录页
│ │ └── tenant/ # 租户相关
│ │ ├── center/ # 租户中心
│ │ ├── info/ # 租户信息
│ │ ├── member/ # 成员管理
│ │ └── notification/ # 通知管理
│ ├── store/ # 状态管理
│ │ ├── customer.ts # 客户状态
│ │ └── tenant.ts # 租户状态
│ ├── utils/ # 工具函数
│ │ └── dict.ts # 字典工具
│ ├── app.ts # 小程序入口
│ ├── app.json # 小程序配置
│ └── app.scss # 全局样式
├── env.ts # 环境配置
├── tsconfig.json # TypeScript 配置
├── package.json # 项目依赖
└── typings/ # 类型定义
```
## 安装说明
### 前置要求
- Node.js >= 14.0.0
- 微信开发者工具（最新版本）
- npm 或 yarn
### 安装步骤
1. **克隆仓库**：
```bash
git clone https://gitee.com/wzkris/wzkris-mini.git
cd wzkris-mini
```
2. **安装依赖**：
```bash
npm install
```
3. **配置环境**：
编辑 `env.ts` 文件，配置不同环境的 API 地址：
```typescript
const map: Record<'develop' | 'trial' | 'release', string> = {
develop: 'http://127.0.0.1:8080', // 开发环境
trial: 'http://127.0.0.1:8080', // 体验环境
release: 'http://127.0.0.1:8080' // 生产环境
}
```
4. **导入项目**：
- 打开微信开发者工具
- 选择"导入项目"
- 选择项目目录
- 填写 AppID（测试可使用测试号）
5. **构建 npm**：
- 在微信开发者工具中，点击"工具" -> "构建 npm"
- 确保 `miniprogram_npm` 目录生成成功
## 使用说明
### 请求封装
所有请求都在 `miniprogram/api/request.ts` 中进行封装，支持自动 token 注入、错误处理和 token 刷新。
```typescript
import { request } from '/api/request'
// 基础 GET 请求（使用客户认证）
const fetchData = async () => {
const data = await request({
url: '/api/data',
method: 'GET'
})
return data
}
// POST 请求
const createData = async (params: any) => {
const data = await request({
url: '/api/data',
method: 'POST',
data: params
})
return data
}
// 使用租户认证
const fetchTenantData = async () => {
const data = await request({
url: '/api/tenant/data',
method: 'GET',
auth_type: 'tenant' // 指定使用租户认证
})
return data
}
// 静默请求（不显示错误提示）
const silentRequest = async () => {
const data = await request({
url: '/api/data',
method: 'GET',
silent: true
})
return data
}
```
### 认证机制
项目支持客户和租户两种认证类型，token 会自动管理。
```typescript
import { customerStore } from '/store/customer'
import { tenantStore } from '/store/tenant'
import { AUTH_TYPE_CUSTOMER, AUTH_TYPE_TENANT } from '/api/core/auth'
// 客户认证相关
const customerToken = customerStore.getToken()
const customerInfo = customerStore.getUserInfo()
customerStore.setToken('token')
customerStore.logoutToLogin() // 退出登录并跳转到登录页
// 租户认证相关
const tenantToken = tenantStore.getToken()
const tenantInfo = tenantStore.getTenantInfo()
tenantStore.setToken('token')
tenantStore.clearAll() // 清除所有租户信息
```
### 数据字典
数据字典功能在 `miniprogram/utils/dict.ts` 中实现，支持数据缓存和转换。
```typescript
import { toOptions } from '/utils/dict'
// 将字典数据转换为选项格式
const dictData = [
{ code: '1', name: '选项1' },
{ code: '2', name: '选项2' }
]
const options = toOptions(dictData)
// 结果: [{ label: '选项1', value: '1' }, { label: '选项2', value: '2' }]
```
### 环境配置
项目支持三种环境自动切换：
- **develop**：开发环境
- **trial**：体验环境
- **release**：生产环境
环境会根据微信开发者工具中的版本自动识别，也可以通过本地存储覆盖：
```typescript
// 动态设置 API 地址（开发调试用）
wx.setStorageSync('API_BASE', 'http://192.168.1.100:8080')
```
### 自定义导航栏
项目已全局处理导航栏适配，所有页面自动计算胶囊按钮位置：
```typescript
Page({
data: {
// containerPaddingTop 会自动计算，无需手动设置
},
onShow() {
// 页面显示时自动更新 containerPaddingTop
}
})
```
在 WXML 中使用：
```xml
```
### 自定义 TabBar
项目使用自定义 TabBar，配置在 `miniprogram/custom-tab-bar/` 目录：
```typescript
import { switchTab } from '/custom-tab-bar/index'
// 切换 Tab
switchTab('home') // 切换到首页
switchTab('consult') // 切换到咨询页
switchTab('mine') // 切换到我的
```
## 开发指南
### 添加新页面
1. 在 `miniprogram/pages/` 目录下创建页面文件夹
2. 创建 `index.ts`、`index.wxml`、`index.scss`、`index.json` 文件
3. 在 `miniprogram/app.json` 的 `pages` 数组中添加页面路径
### 添加新 API
1. 在 `miniprogram/api/core/` 或相应目录下创建 API 文件
2. 使用 `request` 函数封装接口调用
3. 导出 API 函数供页面使用
### 使用 TDesign 组件
项目已集成 TDesign 组件库，可直接使用：
```json
// index.json
{
"usingComponents": {
"t-button": "tdesign-miniprogram/button/button",
"t-input": "tdesign-miniprogram/input/input"
}
}
```
```xml
按钮
```
### TypeScript 配置
项目使用严格的 TypeScript 配置，包括：
- 严格空值检查
- 禁止隐式 any
- 未使用变量检查
- 严格模式
## 常见问题
### 1. npm 构建失败
确保已执行 `npm install`，然后在微信开发者工具中重新构建 npm。
### 2. 请求失败或 token 过期
项目会自动处理 token 刷新，如果刷新失败会自动跳转到登录页。
### 3. 环境切换不生效
检查 `env.ts` 文件配置，或使用本地存储覆盖 API 地址。
## 贡献指南
欢迎贡献代码和改进文档。请遵循以下步骤：
1. Fork 仓库
2. 创建新分支 (`git checkout -b feature/new-feature`)
3. 提交更改 (`git commit -am 'Add new feature'`)
4. 推送分支 (`git push origin feature/new-feature`)
5. 创建 Pull Request
## 许可证
本项目采用 MIT 许可证。详情请查看 [LICENSE](LICENSE) 文件。