🌐 uni-app 请求与登录

uni-app 的 HTTP 请求、登录态管理和文件上传由统一封装层处理。业务代码只需调用 request.get() / request.post()，无需关心 Token 注入、响应解包、错误提示和网络重试。

封装位于 frontend/uniapp/src/utils/request.ts，配置常量在 frontend/uniapp/src/constants/config.ts。

⛓️ URL 拼接

请求发出时，封装层会自动拼接完整 URL：

{VITE_APP_BASE_URL}/api/{url}

例如：

request.get({ url: 'system/user/info' })

H5 默认可以使用：

# H5 与后端同域部署时可使用相对根路径
VITE_APP_BASE_URL=/

小程序和 App 必须使用完整域名：

# 小程序和 App 需要填写可访问的完整接口域名
VITE_APP_BASE_URL=https://example.com/

否则 uni.request 无法发起相对路径请求，封装层会直接抛出配置错误。

🎛️ 请求选项

选项	默认	说明
url	必填	不包含 api 前缀的业务路径
params	-	GET 参数，或 POST 默认数据
data	-	POST / PUT / DELETE 数据
header	-	额外请求头
withToken	true	是否携带 token
transform	true	是否把统一响应转换成 data
showError	true	是否自动提示错误
showSuccess	true	是否自动提示成功
retryCount	1	网络错误重试次数

📓 登录 Store

登录态由 Pinia Store 集中管理（frontend/uniapp/src/stores/user.ts），启动时会自动从本地缓存恢复 Token。核心方法：

方法	说明
restoreAuthInfo()	从本地缓存恢复 token 和用户信息
setAuthInfo()	同步写入内存和本地缓存
login()	调用登录接口并保存登录态
refreshUserInfo()	拉取用户资料
logout()	调用退出接口并清理状态
trySilentLogin()	微信小程序下使用 uni.login 静默登录

🔑 登录接口

接口	说明
POST /api/system/login/account	账号密码 / 短信登录
GET /api/system/login/logout	退出登录

前端调用入口在 frontend/uniapp/src/apis/system/user.ts 和 auth.ts。

请求头中的终端标识区分不同客户端：

值	终端
1	微信小程序
2	微信公众号
3	H5

📁 API 文件组织

System 模块的公共 API 集中在 frontend/uniapp/src/apis/system/：

文件	说明
app.ts	首页、配置、协议、搜索、短信、微信 OAuth
article.ts	文章列表、详情、装修文章
user.ts	登录、退出、用户信息、地址
upload.ts	上传与上传规则
auth.ts	登录、退出导出兼容

可安装业务模块的私有 API 放在模块目录，例如：

frontend/uniapp/src/modules/{module}/apis

只有跨模块复用的 API 才上提到 frontend/uniapp/src/apis。

🔄 响应处理

请求封装默认对统一响应 { code, message, data } 做自动解包，业务代码直接拿到 data：

// transform: true（默认）时，返回值就是 data
const list = await request.get({ url: 'system/article/list/index', params })

设置 transform: false 可拿到完整响应体：

const res = await request.get({ url: 'some/path', transform: false })
// res = { code: 200, message: '', data: {} }

📡 自动请求头

请求封装会自动附加以下请求头，无需手动设置：

请求头	来源	说明
Authorization	本地缓存的 Token	withToken: false 时跳过
X-Language	uni.getStorageSync('language')	后端多语言识别
version	appConfig.version	客户端版本号

🔁 网络重试

网络层失败（非业务错误）默认重试 1 次，可通过 retryCount 调整：

request.get({ url: 'some/path', retryCount: 2 })

业务错误（code !== 200）不触发重试。

🚧 登录拦截

页面登录规则定义在 pages.json。页面默认需要登录，页面项声明 guest: true 时允许游客访问。跳转需要登录的页面时：

1. 如果已有 token，直接进入。
2. 如果没有 token，微信小程序先尝试静默登录。
3. 静默登录失败则跳转登录页，并带 redirect。

接口返回 10002 或 HTTP 401 时，请求封装会：

1. 展示登录失效提示。
2. 清理本地登录态。
3. 通过 toRouter('login', { mode: 'reLaunch' }) 重启到登录页。

📎 上传

文件上传通过 useUpload（单张）或 useDeferredUpload（批量提交时上传）组合式函数调用，底层走以下接口：

type	说明
image	图片
video	视频
file	普通文件

后端大小和扩展名限制在 config/sunadmin.php 的 upload 中维护。