📱 uni-app 总览
frontend/uniapp 是用户端移动端工程，技术栈为 uni-app Vue3 + TypeScript + Pinia，同一套源码编译到 H5、微信小程序与 App。
📐 技术栈
| 类型 | 依赖 |
|---|---|
| 框架 | @dcloudio/uni-app 3.x |
| Vue | ^3.5.13 |
| 状态 | Pinia ^2.3.1 |
| UI | uview-plus 3.7.36 |
| 分页 | src/uni_modules/z-paging |
| 构建 | DCloud Vite CLI、Vite 5.2.8 |
| 类型检查 | TypeScript、vue-tsc |
▶️ 运行入口
text
frontend/uniapp/src/main.ts启动流程：
- 创建 SSR App。
- 注册 Pinia。
- 注册 uview-plus。
- 引入 Bootstrap Icon 字体和全局样式。
- 初始化系统信息。
- 从本地缓存恢复登录态。
- 异步加载公开配置。
- 支持的平台尝试静默登录。
🧲 目录结构
text
src
├─ apis/system/ System 公共 API
├─ components/ 通用组件、基础组件、装修渲染组件
├─ composables/ 组合式函数
├─ constants/ 页面、缓存、请求、终端常量
├─ modules/ 模块目录
├─ pages/system/ System 页面
├─ static/ 静态资源
├─ stores/ Pinia store
├─ styles/ 全局样式
├─ types/ 类型定义
├─ uni_modules/z-paging/ 第三方分页插件
└─ utils/ 请求、路由、反馈、缓存、主题等工具📜 核心页面
| 页面 | 路径 |
|---|---|
| 首页 | pages/system/index/index |
| 我的 | pages/system/my/index |
| 登录 | pages/system/my/login |
| 个人资料 | pages/system/my/profile |
| 地址列表 / 编辑 | pages/system/my/address/* |
| 文章列表 / 详情 | pages/system/article/* |
| 搜索 | pages/system/search/index |
| 协议 | pages/system/public/agreement |
| WebView | pages/system/public/webView |
🧲 Easycom 自动注册
pages.json 中配置了 Easycom 规则，以下组件无需手动 import 即可在任意页面或模块中直接使用：
| 前缀 | 解析规则 | 示例 |
|---|---|---|
<base-*> | @/components/base/Base*.vue | <base-page> → BasePage.vue |
<u-*> | uview-plus 组件 | <u-button> |
<up-*> | uview-plus 组件（新前缀） | <up-button> |
autoscan: true 还会自动注册 src/components/ 下的所有组件。
基础组件清单
| 组件 | 用途 | 关键 Props |
|---|---|---|
<base-page> | 标准页面容器（导航栏 + 安全区） | title、navbar、showBack、safeTop、safeBottom、background |
<base-navbar> | 自定义导航栏 | title、showBack；slot: right |
<base-image> | 带兜底的图片 | src、fallback、mode |
<base-list> | 列表 / 空状态切换 | items、emptyText；default slot |
<base-empty> | 空状态占位 | text |
<base-loading> | 加载动画 | text |
<base-rich-text> | 富文本渲染 | html |
<base-safe-area> | 底部安全区占位 | 无 |
模块开发者应优先使用这些基础组件，无需重复实现页面骨架、导航栏或空状态。
完整用法与 Props 详见 uni-app 组件
🧩 组合式函数（Composables）
组合式函数统一从 @/composables 导入：
ts
import { usePaging, useFormData } from '@/composables'按用途可分为三类：
数据加载与分页
| 函数 | 用途 |
|---|---|
usePaging<T> | 滚动分页，提供 refresh() / loadMore()、finished 状态、page_no / page_size 参数 |
useZPaging<T> | z-paging 插件的 ref 式 API 封装 |
表单与上传
| 函数 | 用途 |
|---|---|
useFormData<T> | 响应式表单，提供 resetFormData()、setFormData()、getFormData() |
useUpload | 单张图片选择 + 上传，返回 UploadResult |
useDeferredUpload | 批量图片选择，提交时再统一上传 |
useAddressPicker | 地址列表加载、弹窗管理、表单回填 |
页面行为
| 函数 | 用途 |
|---|---|
useLogin | 登录表单状态、短信倒计时、密码 / 短信 / 微信登录流程 |
useRequireLoginPage | 每次 onShow 时校验登录状态 |
useShare | 从配置 Store 构建分享信息（标题、路径、图片） |
useLockFn | 防止异步函数重复执行，暴露 loading ref |
usePageTitle | 从页面 query 读取 title 并同步到导航栏 |
完整签名、返回值与用法示例详见 Composables
🧰 开发约定
- Vue 文件统一使用
<script lang="ts" setup>与组合式 API。 - 业务能力通过按需导入 API、组合式函数和 Pinia store 引入。
- 页面和组件直接按需导入具体 API 文件，不额外增加统一导出的 index.ts 中转层（即 barrel 文件），避免小程序环境下的包体积膨胀和 tree-shaking 失效。
src/uni_modules是第三方插件目录，检查业务源码时应排除。- 小程序 / App 环境的
VITE_APP_BASE_URL必须是完整域名。