用户服务（@uniboot/admin）
封装 admin-service 的账号域与用户 / 角色管理域 API，并提供 composable 与页面组件。个人中心、忘记密码、修改初始密码 从页面角度说明 Auth 模板如何接入，均由本包驱动。
| 能力域 | 说明 | 页面 |
|---|---|---|
| 账号域 | 当前用户、验证码、忘记密码、改密、初始改密、换邮箱、基础资料 | AdminForgetPage、AdminInitialPage、AdminProfilePage（由安装入口内部懒加载） |
| 用户 / 角色管理 | 用户增删启停、重置解锁、角色 CRUD、权限树 | AdminUserManagePage、AdminRoleManagePage、AdminRoleAddPage、AdminRoleDetailPage（主入口导出） |
与 @uniboot/auth 的分工：auth 负责登录鉴权；admin 负责登录之后的账号与 RBAC。peerDependencies：uniboot-ui、@uniboot/icons-vue、@uniboot/utils、vue、vue-i18n、vue-router。
推荐接入
Auth 模板只需两步。三服务地址均需配置：
| 环境变量 | 含义 | 谁用 |
|---|---|---|
APP_PUBLIC_API_URL | 业务系统后端 | 默认 request |
APP_PUBLIC_AUTH_SERVICE_URL | 授权服务 | Bundle → authHttp |
APP_PUBLIC_ADMIN_SERVICE_URL | 用户服务（admin-service） | Bundle → adminHttp（账号域 + RBAC） |
ts
// 1. src/utils/request.ts
import { createUnibootAdminHttpBundle } from '@uniboot/admin'
import { createHttpClient } from '@uniboot/request'
const request = createHttpClient({
baseURL: configs.baseUrl, // APP_PUBLIC_API_URL
...httpCommonOptions,
})
export const { adminApi, userApi, roleApi, authHttp, adminHttp } =
createUnibootAdminHttpBundle({
authServiceUrl: configs.authServiceUrl,
adminServiceUrl: configs.adminServiceUrl,
http: httpCommonOptions,
})
export default requestts
// 2. install 插件（createRouter 之后、app.use(router) 之前；Pinia / i18n 需已就绪）
import { setupUnibootAdmin } from '@uniboot/admin'
setupUnibootAdmin(app, {
router,
i18n,
layout: LAYOUT,
adminApi,
userApi,
roleApi,
resolveRoleType: () => /* 当前用户可用角色类型 */,
liveUser: () => useUserStore().userInfo,
user: {
snapshot: () => useUserStore().userInfo,
logout: () => useUserStore().logout(),
refreshUser: () => useUserStore().getUserInfo(),
},
appRuntime: {
getLogo: () => appStore.config?.web_logo,
getLightLogo: () => appStore.config?.web_logo_light,
productTitle: config.title,
},
paths: {
forget: PageEnum.FORGET,
initialPassword: PageEnum.MODIFY_INIT_PWD,
profile: PageEnum.PROFILE,
},
defaultAvatarSrc: '',
profileMetaTitle: () => t('userCenter'),
setLocale: setI18nLanguage,
supportedLocales: [...SUPPORTED_LOCALES],
})用户 / 角色管理页不自动挂路由，在菜单里直接引用包内组件即可（userApi / roleApi 已由 setupUnibootAdmin provide）：
ts
component: () =>
import('@uniboot/admin').then((m) => ({ default: m.AdminUserManagePage }))菜单 component 支持字符串路径或懒加载函数，见 路由和菜单。
createUnibootAdminHttpBundle
创建 authHttp / adminHttp，以及一律绑定 adminHttp 的 adminApi / userApi / roleApi。
参数
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| authServiceUrl | 授权服务地址（APP_PUBLIC_AUTH_SERVICE_URL） | string | — |
| adminServiceUrl | 用户服务地址（APP_PUBLIC_ADMIN_SERVICE_URL） | string | — |
| http | 除 baseURL 外与 createHttpClient 一致，应用到所有 client | object | — |
返回值
| 名称 | 说明 | 类型 |
|---|---|---|
| adminApi | 账号域 API | object |
| userApi | 用户管理域 API | object |
| roleApi | 角色管理域 API | object |
| authHttp | 授权域 HTTP 客户端 | object |
| adminHttp | 用户服务 HTTP 客户端 | object |
setupUnibootAdmin
推荐安装入口：provide → 注册账号域路由 → 可选清理多余 locale。内部调用 initUnibootAdmin，账户页固定 recoverEmailStyle: 'admin'、submitStyle: 'adminPatch'。
参数
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| router | Router 实例（需 addRoute / hasRoute） | object | — |
| i18n | vue-i18n 实例 | object | — |
| layout | 个人中心复用的布局组件 | object | — |
| adminApi | 账号域 API | object | — |
| userApi | 用户管理域 API；传入则全局 provide | object | — |
| roleApi | 角色管理域 API；传入则全局 provide | object | — |
| resolveRoleType | 当前用户可用角色类型（新增角色页） | function | — |
| liveUser | 个人中心实时用户 getter（与 Pinia 同步） | function | — |
| displayTimeZone | 可选 IANA 时区 getter | function | — |
| supportedLocales | locale 白名单；传入则合并文案后删掉白名单外 key | array | — |
| paths | 覆盖忘记密码 / 初始改密 / 个人中心路径 | object | /forget、/change-initial-password、/profile |
| user.snapshot | 路由匹配时的用户快照 | function | — |
| user.logout | 登出（忘记密码返回、初始改密返回/提交后会调用） | function | — |
| user.refreshUser | 改密 / 换邮箱 / 改资料后刷新本地用户 | function | — |
| appRuntime.getLogo | 普通 Logo；深色页未传 getLightLogo 时回退 | function | — |
| appRuntime.getLightLogo | 深色页（忘记密码 / 初始改密）浅色 Logo | function | — |
| appRuntime.productTitle | 初始改密页副标题插值 | string | 'App' |
| defaultAvatarSrc | 个人中心默认头像 | string | — |
| profileMetaTitle | 个人中心 meta.title | string / function | — |
| changeEmailEnabled | 是否允许修改邮箱 | boolean | true |
| showBasicEditButton | 「基本信息」是否显示编辑按钮 | boolean | false |
| basicEditDialogWidth | 修改基本信息弹窗宽度 | string / number | 由内置面板决定 |
| setLocale | 语言切换回调 | function | — |
| reloadAfterLocaleChange | 切语言后是否整页刷新 | boolean | true |
包内已合并 60+ 语言；宿主通常传 supportedLocales 即可。若不用安装入口、只要文案，可单独调用 mergeUnibootAdminLocales(i18n)。
createAdminApi
账号域 API（一般由 Bundle 创建）。
参数
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| http | HTTP 客户端 | object | — |
| paths | 部分覆盖 defaultAdminApiPaths | object | defaultAdminApiPaths |
| verifyCodeStyle | 验证码响应风格 | enum | 'json' |
方法
| 名称 | 路径 | 说明 |
|---|---|---|
getCurrentUser() | GET /users/current | 当前登录用户 |
getVerifyCode() / getVerifyCodeBlob() | GET /account/verifycode | 图形验证码（JSON base64 / blob） |
sendRecoverEmailCode() / sendRecoverEmailCodeGateway() | POST /account/email-code | 忘记密码发信 |
passwordRecover() | POST /account/password-recover | 忘记密码重置 |
changePassword() | PATCH /account/password | 已登录改密 |
updateInitPasswordLoggedIn() / updateInitPasswordWithUserId() / postInitialPasswordLegacy() | PATCH /account/init-password[/:userId] | 初始改密 |
sendEmailCode() / checkEmailCode() / sendNewEmailCode() / updateEmail() | /account/email-code/*、/account/email | 换绑邮箱 |
updateUserInfo() | PATCH /account/info | 昵称 / 性别 / 生日 |
createUserApi / createRoleApi
固定基于 adminHttp。枚举：AdminUserStatus、AdminUserLocked、AdminRoleClass。
| 名称 | 说明 |
|---|---|
userApi.listUsers / createUser / deleteUser / setUserStatus / resetUser / unlockUser | 用户列表与写操作（resetUser 返回新密码明文） |
roleApi.listRoles / listAllRoles / getRoleDetail / createRole / updateRole / deleteRole / getMenuTree | 角色与权限树 |
composable
均通过 options.api 注入，不依赖宿主 Pinia / 路由：
| composable | 对接 | 职责 |
|---|---|---|
useForgetAccount | ForgetPage | 验证码、发信、重置密码 |
useInitialPassword | InitialPage | 按场景提交新密码 |
useProfileAccount | ProfilePage | 换邮箱、改密、改资料；另导出 mapProfileEditToUserUpdate、sexToGenderLabel、formatBirthdayForProfile |
useAdminUserManage | AdminUserManagePage | 用户分页与写操作 |
useAdminRoleManage | AdminRoleManagePage | 角色分页与删除 |
useAdminRoleForm | AdminRoleAddPage / AdminRoleDetailPage | 权限树与提交 |
进阶：initUnibootAdmin
仅合并文案并注册账号域三条路由，不 provide。日常请用 setupUnibootAdmin；仅在需要自行控制注入时使用：
ts
app.provide(UNIBOOT_ADMIN_PROFILE_LIVE_USER, () => useUserStore().userInfo)
app.provide(ADMIN_USER_API_KEY, userApi)
app.provide(ADMIN_ROLE_API_KEY, roleApi)
app.provide(ADMIN_RESOLVE_ROLE_TYPE_KEY, resolveRoleType)
initUnibootAdmin({
router,
i18n,
layout,
adminApi,
user,
// 其余选项同 setupUnibootAdmin 中的路由 / 用户 / 文案字段（不含 liveUser、userApi、roleApi、supportedLocales 等安装扩展项）
})注入 key：UNIBOOT_ADMIN_PROFILE_LIVE_USER、UNIBOOT_ADMIN_DISPLAY_TIME_ZONE、ADMIN_USER_API_KEY、ADMIN_ROLE_API_KEY、ADMIN_RESOLVE_ROLE_TYPE_KEY。个人中心需 liveUser provide，否则页面无法随 Pinia 实时更新。