2026-09-25 18:00:10 +08:00

491 lines
18 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/**
* 用户相关接口(登录 / 注册 / 用户信息 / 退出)
*
* 与 new3(Web 端)的 `src/api/user/user.ts` 保持一致:
* 所有请求都打到同一个 /system 网关,业务方法由 query 的 `method` 指定。
*/
import request from '@/utils/request'
import type { BizResponse } from '@/utils/request'
import { SYSTEM_URL, gatewayParams } from '@/utils/gateway'
// ────────────────────────────── 类型 ──────────────────────────────
/** 账号密码登录入参 */
export interface UserLoginParams {
username: string
password: string
/** 端标记,后端用于区分会话来源(小程序端固定 mobile) */
device?: string
}
/** 注册入参(字段与 new3 一致) */
export interface UserRegisterParams {
username: string
email: string
real_name: string
password: string
}
export interface UserLoginResult {
token: string
[key: string]: any
}
/** 切换身份(角色 / 仓库)入参 */
export interface UserChangeRoleParams {
/** 目标身份 ID = `user.info` 的 `employees[].id` */
roleId: number
/** 端标记,小程序端固定 mobile */
device?: string
}
/** 切换身份返回:后端可能换发 token 并回传 user(与 new3 一致) */
export interface UserChangeRoleResult {
token?: string
user?: UserInfoResult
[key: string]: any
}
/**
* 员工身份 —— `user.info` 返回的 `data.employees[]`
*
* 一个账号可能同时属于多个货主 / 仓库,每个身份一条记录。
* 切换身份时把 `id` 作为 `roleId` 传给 `user.changeRole`(见《页面渲染框架》§4.2)。
*/
export interface EmployeeInfo {
/** 员工身份 ID(切换身份用) */
id: number
/** 所属货主 / 仓库 ID */
store_id: number
/** 所属货主 / 仓库名称 */
store_name: string
/** 该身份下的真实姓名 */
real_name: string
/** 是否主身份:1 = 是 */
is_primary?: number | string
/** 授权到期日;null / 空 表示长期有效 */
auth_end?: string | null
/** 身份类型:warehouse(仓库)/ store(货主)等 */
role_type?: string
[key: string]: any
}
/**
* 获取用户信息入参(`user.info`)
*/
export interface UserInfoParams {
/** 端标记,后端用于区分会话来源(小程序端固定 mobile) */
device?: string
/**
* 小程序 AppID(**字符串**,形如 `wx3xxxxx`)
*
* 与 `wechat.loginByCode` 的 `appid` 同源:本项目作为开放平台第三方平台模板发布,
* 各仓库授权后 AppID 不同且**运行时才确定**(`wx.getAccountInfoSync()`),
* 上报后由后端 `resolveWechatApp()` 反查 `wms_wechat_app` 授权记录。
*
* ⚠️ 是 AppID 字符串,**不是** `wms_wechat_app.id`(整数主键)。
*/
wechat_appId?: string
[key: string]: any
}
/** 用户信息:后端字段随业务扩展,此处只声明稳定字段,其余用索引签名兜住 */
export interface UserInfoResult {
employees_id?: number
employees_name?: string
/**
* 是否已绑定真实账号
*
* **仅微信登录态中间层会下发**:未绑定微信登录(token 里 `id=0`)时后端返回
* `is_bound: false` + 微信层信息(openid / unionid / oauth_id),**不返回 401**。
* 正常账号登录的信息里没有该字段(`undefined`)。
*/
is_bound?: boolean
/** 该账号的全部可用身份 */
employees?: EmployeeInfo[]
permissions?: string[]
/** 后端菜单树,供后续「页面渲染框架」生成路由使用 */
menus?: any[]
[key: string]: any
}
/**
* 微信小程序登录入参(`wechat.loginByCode`)
*
* `app_id` / `appid` **二选一,至少传一个**:
* - `app_id`:`wms_wechat_app.id`(整数主键)—— PC 端后台等已知业务库的场景
* - `appid` :小程序真实 AppID(`wx.getAccountInfoSync().miniProgram.appId`)
* —— **本项目用这个**:代码作为开放平台模板发布给多个仓库,
* 各仓库 AppID 不同且运行时才确定,构建期无法写死
*/
export interface WechatLoginParams {
/** `uni.login` 取得的临时 code(一次性,5 分钟有效) */
code: string
/** `wms_wechat_app.id`(整数主键) */
app_id?: number | string
/** 小程序真实 AppID(字符串,非主键);后端反查授权记录 */
appid?: string
}
/** 微信登录 / 绑定返回的用户信息 */
export interface WechatUserInfo {
/** WMS 账号 ID;**0 = 该微信尚未绑定 WMS 账号**(仅有微信登录态) */
id: number
/** `wms_user_oauth.id`:微信登录态主键,绑定接口靠它定位记录 */
oauth_id: number
openid?: string
unionid?: string
nickname?: string
headimgurl?: string
username?: string
real_name?: string
phone?: string
[key: string]: any
}
/** 微信登录 / 绑定的返回结构(参考 `auth.login`) */
export interface WechatLoginResult {
token: string
user: WechatUserInfo
}
/**
* 更新微信账号资料入参(`wechat.updateInfo`)
*
* 后端语义:**仅未绑定真实用户的微信账号**可调用(已绑定账号不支持修改),
* 字段**可部分更新** —— 传哪个改哪个。
*/
export interface WechatUpdateInfoParams {
/** 昵称(≤255 字符) */
nickname?: string
/** 头像 URL(≤500 字符),一般由 `wechat.uploadHeadimg` 回写后带回 */
headimgurl?: string
}
/** 微信账号资料(`wechat.updateInfo` / `wechat.uploadHeadimg` 的返回) */
export interface WechatProfileResult {
/** `wms_user_oauth.id` */
oauth_id: number
/** 更新后的昵称 */
nickname?: string
/** 更新后的头像 URL */
headimgurl?: string
/** 仅 `wechat.uploadHeadimg` 返回,值与 `headimgurl` 相同 */
url?: string
}
/**
* 我的登录码响应(`wechat.getMyLoginCode`)
*
* ⚠️ 实测响应是**扁平**的 —— 业务字段与 `flag/code/message` **同级**,**没有 `data` 包裹**:
* ```json
* { "flag":"success","code":1,"message":"获取成功",
* "login_code":"eyJ1dWlkIjoiMl82NTU5MzIiLCJmb3JtIjoid2VjaGF0In0=","oauth_id":2,"timestamp":1790065001 }
* ```
* (`login_code` 解码后为 `{"uuid":"2_655932","form":"wechat"}`)
*
* 故下面的字段声明的是**响应顶层**字段;调用方(store)按顶层取值,
* 并兼容将来被包进 `data` 的情况。
*/
export interface WechatLoginCodeResult {
/** 登录码:`uuid={id}_{6位随机}`、`form=wechat` 的 JSON base64 */
login_code?: string
/** `wms_user_oauth.id` */
oauth_id?: number
[key: string]: any
}
/**
* 用户须知(`wechat.getUserAgreement` / `wechat.getUserAgreementText` 的返回)
*/
export interface WechatAgreementResult {
/** 小程序 AppID */
appid: string
/**
* 用户须知**富文本**内容
*
* 后端存的是 longText 富文本,实际可能是 HTML,也可能是纯文本;
* 渲染侧自行判断(见 `login-panel.vue` 的 `isRichAgreement`)。
*/
text: string
/** 小程序名称(仅 `getUserAgreement` 返回) */
nickname?: string
/** 是否命中后端缓存(仅 `getUserAgreementText` 返回,后端 Redis 缓存 24h) */
from_cache?: boolean
}
/** 按 AppID 取用户须知的入参(`wechat.getUserAgreementText`) */
export interface WechatAgreementTextParams {
/** 小程序 AppID(`wx.getAccountInfoSync().miniProgram.appId`,**字符串**) */
appId: string
}
// ────────────────────────────── 接口 ──────────────────────────────
/** 账号密码登录 */
export function login(data: UserLoginParams): Promise<BizResponse<UserLoginResult>> {
return request<UserLoginResult>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('user.login'),
data
})
}
/** 注册账号(注册成功后需再登录,与 new3 行为一致) */
export function register(data: UserRegisterParams): Promise<BizResponse<any>> {
return request({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('user.register'),
data
})
}
/**
* 获取用户信息(含权限点与菜单)
*
* 也是**微信登录态的探测接口**:未绑定的微信登录(token 里 `id=0`)调用它不会 401,
* 而是返回 `is_bound: false` + 微信层信息。
*
* @param data 入参:`device`、**`wechat_appId`**(小程序运行时真实 AppID)
* @param token 显式指定 token —— 微信登录未绑定时 token 只存内存、未落地,需手工带上
*/
export function getInfo(
data: UserInfoParams = {},
token?: string
): Promise<BizResponse<UserInfoResult>> {
return request<UserInfoResult>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('user.info'),
data,
// 需要登录:未登录时连请求都不发,直接弹登录抽屉(省一次无意义的 401 往返)
auth: true,
...(token ? { header: { Authorization: `Bearer ${token}` } } : {})
})
}
/**
* 切换当前身份(角色 / 仓库)
*
* 入参 `roleId` = `user.info` 的 `employees[].id`(已确认,见《页面渲染框架》§4.2)。
* 返回可能包含换发后的 `token` 与 `user`;**调用方需重调 `user.info`** 刷新菜单 / 权限。
*/
export function changeRole(
data: UserChangeRoleParams
): Promise<BizResponse<UserChangeRoleResult>> {
return request<UserChangeRoleResult>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('user.changeRole'),
data,
auth: true
})
}
/** 退出登录 */
export function logout(data: Record<string, any> = {}): Promise<BizResponse<any>> {
return request({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('user.logout'),
data,
auth: true
})
}
/**
* 微信小程序一键登录(**免登录接口**)
*
* `uni.login` 的 code → 后端 `jscode2session` 换 openid/session_key → 查/建 `wms_user_oauth`
* → 签发 token。
*
* ⚠️ 该接口**不代表业务登录成功**:微信首次登录时后端返回的 token 里 `id = 0`
* (尚未绑定 WMS 账号),此时需再调 `wechatBindUser` 完成绑定。
*/
export function wechatLogin(
data: WechatLoginParams
): Promise<BizResponse<WechatLoginResult>> {
return request<WechatLoginResult>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('wechat.loginByCode'),
data
})
}
/**
* 绑定 WMS 账号(微信登录态中间层接口,未绑定也可访问)
*
* 后端从**请求头里的 token** 取 `oauth_id` 定位 `wms_user_oauth` 记录;
* 该 token 在微信登录时已写入本地存储,`request` 会自动带上,一般无需传 `token`。
* 绑定成功后返回换发的正式 token(`user.id` 为真实账号 ID)。
*
* @param data 账号密码
* @param token 可选:显式指定微信登录 token(缺省用本地存储里的)
*/
export function wechatBindUser(
data: { username: string; password: string },
token?: string
): Promise<BizResponse<WechatLoginResult>> {
return request<WechatLoginResult>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('wechat.bindUser'),
data,
// 微信登录态失效时后端用业务码 401 表达:不要跟着全局逻辑清登录态 + 跳登录页,
// 否则用户会被踢出页面、输入丢失 —— 只 toast「微信登录态不存在」由用户重新微信登录
redirectOn401: false,
...(token ? { header: { Authorization: `Bearer ${token}` } } : {})
})
}
/**
* 确认登录码(**需登录**,扫码登录链路的「小程序侧确认」)
*
* 后端语义(见 `D:\wms\app\service\systems\wechat.js` 的 `pushLoginCode`):
* 用**当前鉴权用户**标记登录码为 success,展示该码的一方(PC / 工作台)
* 轮询取回后即登录为本账号。
*
* 入参 `code` = 二维码里 spm 的第 3 段(6 位数字登录码)。
* ⚠️ 登录码有 TTL(生成 300s / 确认后 120s),过期后需重新出码。
*/
export function wechatPushLoginCode(data: {
code: string
}): Promise<BizResponse<{ code: string; status: string }>> {
return request<{ code: string; status: string }>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('wechat.pushLoginCode'),
data,
// 需要**业务登录**:未登录时不发请求,直接弹登录抽屉
auth: true,
// 未登录时后端返回业务码 401,这里只提示、不触发全局跳登录(由调用方引导登录)
redirectOn401: false
})
}
/**
* 更新微信账号资料(**微信登录态中间层**:带微信登录态 token 即可,未绑定真实用户也可调用)
*
* 用途:小程序端「未绑定 WMS 账号」时,让用户补全自己的**微信昵称 / 头像**。
* 微信自 2022-10 回收了 `getUserProfile`,头像昵称必须由用户主动提供
* (`<button open-type="chooseAvatar">` + `<input type="nickname">`),
* 拿到后经本接口落到 `wms_user_oauth`。
*
* ⚠️ **已绑定 WMS 账号的微信登录态不支持修改**(后端直接返回失败)——
* 调用方应只在「未绑定」态给出入口(见 `userStore.canEditWechatProfile`)。
*/
export function wechatUpdateInfo(
data: WechatUpdateInfoParams
): Promise<BizResponse<WechatProfileResult>> {
return request<WechatProfileResult>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('wechat.updateInfo'),
data,
auth: true,
// 微信登录态失效时后端用 401 表达:只提示,不清登录态、不跳登录页
redirectOn401: false
})
}
/**
* 上传微信账号头像(**微信登录态中间层**:至少微信登录即可,未绑定也可)
*
* 入参 `image` = **PNG 的 base64**(支持 `data:image/png;base64,` 前缀),**限制 < 500K**;
* 后端校验 PNG 魔数后传 COS,并回写 `wms_user_oauth.headimgurl`,返回可访问 URL。
*
* ⚠️ 微信 `chooseAvatar` 给的是**临时文件路径**且不保证是 PNG,
* 必须先经 `utils/avatar.ts` 的 `avatarFileToPngBase64()` 裁剪 / 转码 / 压体积,
* **不要**直接把它塞进来。
*/
export function wechatUploadHeadimg(data: {
image: string
}): Promise<BizResponse<WechatProfileResult>> {
return request<WechatProfileResult>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('wechat.uploadHeadimg'),
data,
auth: true,
// base64 体积大(上限 500K 图片 → base64 约 680K 字符),比默认 15s 放宽
timeout: 30000,
redirectOn401: false
})
}
/**
* 获取「我的登录码」(**微信登录态中间层**,无入参)
*
* 用途:**电脑端登录** —— 小程序把码展示给用户,电脑端凭它走 `user.loginByCode`
* (ye4s 登录码链路)直接登录为本账号,无需在电脑上输密码。
*
* 后端语义:取当前微信用户 `wms_user_oauth.login_code`,**没有才生成**
* (`uuid={id}_{6位随机}`、`form=wechat` 的 JSON base64)并落库,已有则原样返回
* ⇒ 同一微信账号拿到的码是**稳定的**(不是一次性),可反复展示。
*
* ⚠️ 响应**没有 `data` 包裹**(业务字段在顶层),详见 `WechatLoginCodeResult`。
* ⚠️ **只认微信登录态 token**(JWT 含 `oauth_id`):账号密码登录的 token 会被拒,
* 故界面需按 `userStore.canGetMyLoginCode` 控制入口。
*/
export function wechatGetMyLoginCode(): Promise<BizResponse<WechatLoginCodeResult>> {
return request<WechatLoginCodeResult>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('wechat.getMyLoginCode'),
data: {},
auth: true,
// 登录态失效 / 非微信登录态时后端用 401 表达:只提示,不清登录态、不跳登录页
redirectOn401: false
})
}
/**
* 获取**当前登录仓库**小程序的用户须知(**需登录**,带仓库上下文)
*
* 后端按 `ctx.user.store_id` 取仓库启用的 `wms_wechat_app`,返回其 `user_agreement` 富文本;
* 仓库未绑定小程序时返回「无小程序,需要先绑定」。
*
* ⚠️ 需要**业务登录**(未绑定的微信登录态没有仓库上下文)——
* 未登录 / 未绑定时请用免登录的 `wechatGetUserAgreementText()`。
*
* ⚠️ `toastError: false`:须知属于「锦上添花」的展示内容,拉不到就用本地兜底文案,
* 不应给用户弹错误提示(更不能因此阻断登录)。
*/
export function wechatGetUserAgreement(): Promise<BizResponse<WechatAgreementResult>> {
return request<WechatAgreementResult>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('wechat.getUserAgreement'),
data: {},
auth: true,
// 拉须知失败不能把用户踢去登录(登录前就要看须知才是常态)
redirectOn401: false,
toastError: false
})
}
/**
* 获取**指定小程序 AppID** 的用户须知(**免登录**)
*
* 后端按 `appid` 查 `wms_wechat_app.user_agreement`,Redis 缓存 24h(返回 `from_cache`)。
* 小程序端**登录前**就要展示《用户须知》(登录抽屉里勾选),
* 所以这条免登录接口才是主链路,`getUserAgreement` 用于已登录时的仓库维度取值。
*
* ⚠️ 同样 `toastError: false`:失败静默,调用方回退本地兜底文案。
*/
export function wechatGetUserAgreementText(
data: WechatAgreementTextParams
): Promise<BizResponse<WechatAgreementResult>> {
return request<WechatAgreementResult>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('wechat.getUserAgreementText'),
data,
toastError: false
})
}