@jiangood/open-admin 3.1.10 → 3.1.12

package/src/framework/config/layoutConfig.ts

@@ -4,29 +4,64 @@ export type LayoutMode = 'tabs' | 'single';
 
 const LAYOUT_MODE_KEY = 'oa-layout-tabs';
 
+/** 页签模式（多页签）/ 单页模式 */
 export const DEFAULT_LAYOUT_MODE: LayoutMode = 'tabs';
 
 const LAYOUT_MODES: LayoutMode[] = ['tabs', 'single'];
 
-function readStoredLayoutMode(): LayoutMode {
-    if (typeof window === 'undefined') return DEFAULT_LAYOUT_MODE;
+function readStoredLayoutMode(): LayoutMode | null {
+    if (typeof window === 'undefined') return null;
     try {
         const mode = localStorage.getItem(LAYOUT_MODE_KEY);
         if (mode && LAYOUT_MODES.includes(mode as LayoutMode)) return mode as LayoutMode;
     } catch {
         // 隐私模式下 localStorage 不可用，忽略
     }
-    return DEFAULT_LAYOUT_MODE;
+    return null;
 }
 
-let currentLayoutMode: LayoutMode = readStoredLayoutMode();
+/** 用户是否在本地自定义过页签模式 */
+export function hasStoredLayoutMode(): boolean {
+    return readStoredLayoutMode() !== null;
+}
+
+function removeStoredLayoutMode() {
+    if (typeof window === 'undefined') return;
+    try {
+        localStorage.removeItem(LAYOUT_MODE_KEY);
+    } catch {
+        // 忽略
+    }
+}
+
+/** 全局默认布局（来自参数设置，未自定义用户使用） */
+let defaultLayoutMode: LayoutMode = DEFAULT_LAYOUT_MODE;
+
+let currentLayoutMode: LayoutMode = readStoredLayoutMode() ?? DEFAULT_LAYOUT_MODE;
 
-/** 当前布局模式：'tabs' 多标签页 / 'single' 单页 */
+/** 当前页签模式：'tabs' 多页签 / 'single' 单页 */
 export function getLayoutMode(): LayoutMode {
     return currentLayoutMode;
 }
 
-/** 设置布局模式，持久化并广播 layoutChange 供管理布局重渲染 */
+export function getDefaultLayoutMode(): LayoutMode {
+    return defaultLayoutMode;
+}
+
+/**
+ * 应用参数设置下发的全局默认页签模式。
+ * 仅在用户本地没有自定义时生效；已自定义用户保持个人选择。
+ */
+export function setDefaultLayoutMode(mode: LayoutMode) {
+    if (!LAYOUT_MODES.includes(mode)) return;
+    defaultLayoutMode = mode;
+    if (hasStoredLayoutMode() || currentLayoutMode === mode) return;
+
+    currentLayoutMode = mode;
+    EventBus.emit('layoutChange', mode);
+}
+
+/** 设置页签模式，持久化并广播 layoutChange 供管理布局重渲染 */
 export function setLayoutMode(mode: LayoutMode) {
     if (!LAYOUT_MODES.includes(mode) || currentLayoutMode === mode) return;
     currentLayoutMode = mode;
@@ -46,7 +81,11 @@ export function toggleLayoutMode(): LayoutMode {
     return next;
 }
 
-/** 恢复默认布局（多标签页） */
+/** 恢复默认页签模式：清除本地覆盖，回到参数设置的全局默认 */
 export function resetLayoutMode() {
-    setLayoutMode(DEFAULT_LAYOUT_MODE);
+    removeStoredLayoutMode();
+    if (currentLayoutMode === defaultLayoutMode) return;
+
+    currentLayoutMode = defaultLayoutMode;
+    EventBus.emit('layoutChange', currentLayoutMode);
 }

package/src/framework/config/themeConfig.ts

@@ -92,7 +92,10 @@ export const RADIUS_PRESETS: ThemeRadiusPreset[] = [
 
 export const DEFAULT_RADIUS_KEY: ThemeRadius = 'default';
 
-/** 可选主题预设；antd 预设不做任何颜色覆盖，保持 100% 原生观感 */
+/**
+ * 可选主题预设；antd 预设不做任何颜色覆盖，保持 100% 原生观感。
+ * 按色相环顺序排列：蓝 → 蓝灰 → 靛蓝 → 紫 → 粉 → 红 → 橙 → 绿 → 青，便于用户按相近色比较选择。
+ */
 export const THEME_PRESETS: ThemePreset[] = [
     {
         key: 'antd',
@@ -100,24 +103,24 @@ export const THEME_PRESETS: ThemePreset[] = [
         colors: {},
     },
     {
-        key: 'cyan',
-        name: '青碧',
+        key: 'graphite',
+        name: '石墨灰',
         colors: {
-            colorPrimary: '#13c2c2',
-            siderBg: '#0C2E2E',
-            siderSubBg: '#0C2E2E',
-            siderTriggerBg: '#082222',
+            colorPrimary: '#2f3542',
+            siderBg: '#1B2026',
+            siderSubBg: '#1B2026',
+            siderTriggerBg: '#141A20',
             siderHoverBg: 'rgba(255,255,255,0.06)',
         },
     },
     {
-        key: 'green',
-        name: '翠竹',
+        key: 'indigo',
+        name: '靛蓝',
         colors: {
-            colorPrimary: '#389e0d',
-            siderBg: '#10291A',
-            siderSubBg: '#10291A',
-            siderTriggerBg: '#0B1E13',
+            colorPrimary: '#4f46e5',
+            siderBg: '#1E1B4B',
+            siderSubBg: '#1E1B4B',
+            siderTriggerBg: '#17143C',
             siderHoverBg: 'rgba(255,255,255,0.06)',
         },
     },
@@ -132,6 +135,17 @@ export const THEME_PRESETS: ThemePreset[] = [
             siderHoverBg: 'rgba(255,255,255,0.06)',
         },
     },
+    {
+        key: 'pink',
+        name: '樱花粉',
+        colors: {
+            colorPrimary: '#eb2f96',
+            siderBg: '#2B1024',
+            siderSubBg: '#2B1024',
+            siderTriggerBg: '#200B1A',
+            siderHoverBg: 'rgba(255,255,255,0.06)',
+        },
+    },
     {
         key: 'red',
         name: '中国红',
@@ -155,13 +169,24 @@ export const THEME_PRESETS: ThemePreset[] = [
         },
     },
     {
-        key: 'graphite',
-        name: '石墨灰',
+        key: 'green',
+        name: '翠竹',
         colors: {
-            colorPrimary: '#2f3542',
-            siderBg: '#1B2026',
-            siderSubBg: '#1B2026',
-            siderTriggerBg: '#141A20',
+            colorPrimary: '#389e0d',
+            siderBg: '#10291A',
+            siderSubBg: '#10291A',
+            siderTriggerBg: '#0B1E13',
+            siderHoverBg: 'rgba(255,255,255,0.06)',
+        },
+    },
+    {
+        key: 'cyan',
+        name: '青碧',
+        colors: {
+            colorPrimary: '#13c2c2',
+            siderBg: '#0C2E2E',
+            siderSubBg: '#0C2E2E',
+            siderTriggerBg: '#082222',
             siderHoverBg: 'rgba(255,255,255,0.06)',
         },
     },
@@ -174,6 +199,8 @@ const THEME_RADIUS_KEY = 'oa-theme-radius';
 
 /** 业务侧传入的颜色基线（由 setThemeColors 设置） */
 let businessColors: Partial<ThemeColors> | null = null;
+/** 全局默认预设 key（来自参数设置，未自定义用户使用） */
+let defaultPresetKey: string = DEFAULT_PRESET_KEY;
 /** 用户选择的预设 key（持久化到 localStorage） */
 let presetKey: string = readStoredPreset();
 let densityKey: ThemeDensity = readStoredDensity();
@@ -192,15 +219,24 @@ function readStoredMode(): ThemeMode {
     }
 }
 
-function readStoredPreset(): string {
-    if (typeof window === 'undefined') return DEFAULT_PRESET_KEY;
+function readStoredPresetKey(): string | null {
+    if (typeof window === 'undefined') return null;
     try {
         const key = localStorage.getItem(THEME_PRESET_KEY);
         if (key && THEME_PRESETS.some(p => p.key === key)) return key;
     } catch {
         // 隐私模式下 localStorage 不可用，忽略
     }
-    return DEFAULT_PRESET_KEY;
+    return null;
+}
+
+function readStoredPreset(): string {
+    return readStoredPresetKey() ?? DEFAULT_PRESET_KEY;
+}
+
+/** 用户是否在本地自定义过主题色预设 */
+export function hasStoredPreset(): boolean {
+    return readStoredPresetKey() !== null;
 }
 
 function persistPreset(key: string) {
@@ -243,6 +279,15 @@ function writeStored(key: string, value: string) {
     }
 }
 
+function removeStored(key: string) {
+    if (typeof window === 'undefined') return;
+    try {
+        localStorage.removeItem(key);
+    } catch {
+        // 忽略
+    }
+}
+
 function getActiveDensity(): ThemeDensityPreset | undefined {
     return DENSITY_PRESETS.find(p => p.key === densityKey);
 }
@@ -454,6 +499,26 @@ export function getActivePresetKey(): string {
     return presetKey;
 }
 
+export function getDefaultPresetKey(): string {
+    return defaultPresetKey;
+}
+
+/**
+ * 应用参数设置下发的全局默认主题色。
+ * 仅在用户本地没有自定义预设时生效；已自定义用户保持个人选择，
+ * 但其「恢复默认」会回到这里设置的值。
+ */
+export function setDefaultThemePreset(key: string) {
+    if (!THEME_PRESETS.some(p => p.key === key)) return;
+    defaultPresetKey = key;
+    if (hasStoredPreset() || presetKey === key) return;
+
+    presetKey = key;
+    invalidate();
+    syncCssVars(getToken());
+    EventBus.emit('themeChange', currentMode);
+}
+
 /** 应用界面密度预设，持久化并广播 themeChange */
 export function applyDensityPreset(key: ThemeDensity) {
     if (!DENSITY_PRESETS.some(p => p.key === key)) return;
@@ -482,13 +547,16 @@ export function getActiveRadiusKey(): ThemeRadius {
     return radiusKey;
 }
 
-/** 恢复默认：颜色 / 密度 / 圆角 / 明暗 全部复位（不影响布局，布局由 resetAllSettings 统一处理） */
+/**
+ * 恢复默认：主题色回到参数设置的全局默认，密度 / 圆角 / 明暗复位（不影响布局，布局由 resetAllSettings 统一处理）。
+ * 主题色会同时清除本地覆盖，之后管理员调整全局默认值时重新生效。
+ */
 export function resetUserTheme() {
-    presetKey = DEFAULT_PRESET_KEY;
+    presetKey = defaultPresetKey;
     densityKey = DEFAULT_DENSITY_KEY;
     radiusKey = DEFAULT_RADIUS_KEY;
     currentMode = 'light';
-    persistPreset(presetKey);
+    removeStored(THEME_PRESET_KEY);
     writeStored(THEME_DENSITY_KEY, densityKey);
     writeStored(THEME_RADIUS_KEY, radiusKey);
     writeStored(THEME_MODE_KEY, currentMode);

package/src/framework/config/uiDefaults.ts

@@ -0,0 +1,26 @@
+import { setDefaultThemePreset } from './themeConfig';
+import { setDefaultLayoutMode } from './layoutConfig';
+
+/** 参数设置中「默认界面」分组的配置键 */
+export const UI_THEME_PRESET_KEY = 'sys.ui.theme-preset';
+export const UI_TABS_ENABLED_KEY = 'sys.ui.tabs-enabled';
+
+/**
+ * 应用后端下发的全局默认界面配置（来自 site-info.config）。
+ *
+ * 只对未在本地自定义过的用户生效；已自定义用户保持个人设置，
+ * 其「恢复默认」会回到这里设置的全局默认值。
+ */
+export function applyServerUiDefaults(config?: Record<string, unknown> | null) {
+    if (!config) return;
+
+    const preset = config[UI_THEME_PRESET_KEY];
+    if (typeof preset === 'string') {
+        setDefaultThemePreset(preset);
+    }
+
+    const tabsEnabled = config[UI_TABS_ENABLED_KEY];
+    if (typeof tabsEnabled === 'boolean') {
+        setDefaultLayoutMode(tabsEnabled ? 'tabs' : 'single');
+    }
+}

package/src/framework/fields/FieldEditor/index.tsx

@@ -35,7 +35,7 @@ export class FieldEditor extends React.Component<FieldEditorProps, {loading: boo
     render() {
         const {loading} = this.state;
         const isPublic = this.props.isPublic ?? true;
-        const uploadUrl = UrlUtils.contextPath('/admin/sysFile/upload') + '?isPublic=' + isPublic;
+        const uploadUrl = UrlUtils.contextPath('/admin/sys-file/upload') + '?isPublic=' + isPublic;
         const jsUrl = UrlUtils.contextPath('/admin/tinymce/tinymce.min.js');
         const {value, onChange, height} = this.props;
         const editorHeight = height || 300;

package/src/framework/fields/FieldUploadFile/index.tsx

@@ -149,7 +149,7 @@ export class FieldUploadFile extends React.Component<FieldUploadFileProps, Field
         const {accept, fileList, maxCount} = this.state;
 
         return <Upload
-            action={UrlUtils.contextPath('/admin/sysFile/upload')}
+            action={UrlUtils.contextPath('/admin/sys-file/upload')}
             data={{isPublic: this.state.isPublic}}
             listType={this.props.listType || 'picture-card'}
             fileList={fileList}

package/src/framework/fields/FieldUploadImage/index.tsx

@@ -16,6 +16,14 @@ export interface FieldUploadImageProps extends FieldProps<string> {
     isPublic?: boolean;
     /** 接受的文件类型 */
     accept?: string;
+    /** 进入裁切工具时的默认裁切比例，默认 4:3；传 null 表示自由裁切 */
+    defaultCropRatio?: Dims | null;
+    /** 缩略图与触发按钮形状，圆形用于头像类场景，默认方形 */
+    shape?: 'square' | 'circle';
+    /** 缩略图与触发按钮的尺寸（px），默认 80 */
+    size?: number;
+    /** 触发按钮的提示文案，默认不显示提示 */
+    triggerTitle?: string;
 }
 
 interface Dims {
@@ -167,6 +175,7 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
     constructor(props: FieldUploadImageProps) {
         super(props);
         ObjectUtils.copyPropertyIfPresent(props, this.state);
+        if (props.defaultCropRatio !== undefined) this.state.cropRatio = props.defaultCropRatio;
         if (props.value) this.state.objectNames = props.value.split(',');
     }
 
@@ -363,7 +372,7 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
             fd.append('file', this.state.preview.cFile);
             fd.append('thumb', tFile);
             fd.append('isPublic', String(this.state.isPublic));
-            const rs = await HttpClient.post('admin/sysFile/uploadImage', fd, null, {toastError: false});
+            const rs = await HttpClient.post('admin/sys-file/upload-image', fd, null, {toastError: false});
             this.setState(
                 (prevState) => ({objectNames: [...prevState.objectNames, rs.data.objectName]}),
                 () => this.props.onChange?.(this.state.objectNames.join(','))
@@ -395,6 +404,9 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
 
     render() {
         const {objectNames, accept, compressWidth, compressSize, cropRatio, cropperReady, fullPreviewUrl, maxCount, modalOpen, originalUrl, preview, tool, uploading} = this.state;
+        const {shape = 'square', size = 80, triggerTitle} = this.props;
+        const round = shape === 'circle';
+        const boxRadius = round ? '50%' : 4;
 
         // 画布当前显示的图片
         const canvasImg = preview
@@ -412,8 +424,8 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
                 <div>
                     {objectNames.map((name) => (
                         <div key={name} style={{
-                            position: 'relative', display: 'inline-block', marginRight: 8, verticalAlign: 'top',
-                            width: 80, height: 80, borderRadius: 4, overflow: 'hidden', cursor: 'pointer',
+                            position: 'relative', display: 'inline-block', marginRight: round ? 0 : 8, verticalAlign: 'top',
+                            width: size, height: size, borderRadius: boxRadius, overflow: 'hidden', cursor: 'pointer',
                         }}
                             onMouseEnter={(e) => {
                                 const mask = e.currentTarget.querySelector('.oa-field-upload-img-mask') as HTMLElement;
@@ -432,14 +444,14 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
                         >
                             <img
                                 src={UrlUtils.contextPath(`/file/${name}?thumb=1`)}
-                                width={80}
-                                height={80}
-                                style={{objectFit: 'cover', borderRadius: 4, display: 'block'}}
+                                width={size}
+                                height={size}
+                                style={{objectFit: 'cover', borderRadius: boxRadius, display: 'block'}}
                                 alt={name}
                             />
                             <div style={{
                                 position: 'absolute', inset: 0, display: 'flex', alignItems: 'center', justifyContent: 'center',
-                                background: 'rgba(0,0,0,0.45)', opacity: 0, transition: 'opacity .3s', borderRadius: 4,
+                                background: 'rgba(0,0,0,0.45)', opacity: 0, transition: 'opacity .3s', borderRadius: boxRadius,
                                 pointerEvents: 'none',
                             }} className="oa-field-upload-img-mask">
                                 <Space size={12}>
@@ -462,9 +474,29 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
                         </div>
                     ))}
                     {objectNames.length < maxCount && (
-                        <Upload accept={accept} showUploadList={false} beforeUpload={this.handleBeforeUpload} multiple={false}>
-                            <Button icon={<PlusOutlined/>}>选择图片</Button>
-                        </Upload>
+                        round ? (
+                            <Upload accept={accept} showUploadList={false} beforeUpload={this.handleBeforeUpload} multiple={false}>
+                                <button type="button"
+                                        title={triggerTitle}
+                                        aria-label={triggerTitle || '选择图片'}
+                                        style={{
+                                            width: size, height: size, padding: 0, boxSizing: 'border-box',
+                                            border: '2px dashed var(--oa-color-border, #d9d9d9)',
+                                            borderRadius: '50%',
+                                            background: 'var(--oa-color-fill-quaternary, #fafafa)',
+                                            color: 'var(--oa-color-text-secondary, rgba(0, 0, 0, 0.65))',
+                                            cursor: 'pointer', lineHeight: 0,
+                                            display: 'inline-flex', alignItems: 'center', justifyContent: 'center',
+                                            fontSize: 18,
+                                        }}>
+                                    <PlusOutlined/>
+                                </button>
+                            </Upload>
+                        ) : (
+                            <Upload accept={accept} showUploadList={false} beforeUpload={this.handleBeforeUpload} multiple={false}>
+                                <Button icon={<PlusOutlined/>}>选择图片</Button>
+                            </Upload>
+                        )
                     )}
                 </div>
 

package/src/framework/fields/FieldUserPicker/index.tsx

@@ -14,9 +14,9 @@ export interface FieldUserPickerProps extends FieldProps<string[]> {
     placeholder?: string;
     /** 弹窗标题 */
     title?: string;
-    /** 分页数据源地址，默认 admin/sysUser/page */
+    /** 分页数据源地址，默认 admin/sys-user/page */
     requestUrl?: string;
-    /** 按 id 查询用户详情地址（用于回显），默认 admin/sysUser/by-ids */
+    /** 按 id 查询用户详情地址（用于回显），默认 admin/sys-user/by-ids */
     usersUrl?: string;
 }
 
@@ -52,7 +52,7 @@ export class FieldUserPicker extends React.Component<FieldUserPickerProps, Field
         }
     }
 
-    getUsersUrl = () => this.props.usersUrl || 'admin/sysUser/by-ids';
+    getUsersUrl = () => this.props.usersUrl || 'admin/sys-user/by-ids';
 
     // 根据 value(ids) 拉取并补全用户详情，按 ids 顺序展示
     syncUsers = () => {

package/src/framework/fields/orgTree.ts

@@ -1,3 +1,3 @@
 export function orgTreeUrl(type: string): string {
-    return type === 'dept' ? '/admin/sysOrg/dept-tree' : '/admin/sysOrg/unit-tree';
+    return type === 'dept' ? '/admin/sys-org/dept-tree' : '/admin/sys-org/unit-tree';
 }

package/src/framework/router/index.ts

@@ -1,4 +1,5 @@
 export {history} from './history';
 export {registerRoutes, matchRoute} from './matcher';
+export type {PageLayout, PageMeta, RouteDef, MatchResult} from './matcher';
 export {PageFrame} from './PageFrame';
 export {Link} from './Link';

package/src/framework/router/matcher.ts

@@ -4,9 +4,23 @@ function safeDecodeURIComponent(s: string): string {
     try { return decodeURIComponent(s); } catch { return s; }
 }
 
+/** 页面布局：admin = 后台菜单布局；blank = 仅渲染页面内容 */
+export type PageLayout = 'admin' | 'blank';
+
+/** 页面元信息：页面文件通过 export const pageMeta 声明，由 vite 插件写入路由表 */
+export interface PageMeta {
+    /** 页面标题：用于页签标题和浏览器标题；未设置时回退到后端菜单名 */
+    title?: string;
+    /** 是否需要登录，默认 true */
+    requiresAuth?: boolean;
+    /** 页面布局，默认 admin */
+    layout?: PageLayout;
+}
+
 export interface RouteDef {
     path: string;
     component: ComponentType<unknown>;
+    meta?: PageMeta;
 }
 
 interface InternalRoute extends RouteDef {
@@ -16,6 +30,7 @@ interface InternalRoute extends RouteDef {
 export interface MatchResult {
     component: ComponentType<unknown>;
     params: Record<string, string>;
+    meta?: PageMeta;
 }
 
 const routes: InternalRoute[] = [];
@@ -27,8 +42,8 @@ function compile(path: string): InternalRoute['segments'] {
 }
 
 export function registerRoutes(defs: RouteDef[]): void {
-    for (const {path, component} of defs) {
-        routes.push({path, component, segments: compile(path)});
+    for (const {path, component, meta} of defs) {
+        routes.push({path, component, meta, segments: compile(path)});
     }
 }
 
@@ -51,8 +66,8 @@ export function matchRoute(pathname: string): MatchResult | null {
             }
         }
         if (!ok) continue;
-        if (!dynamic) return {component: route.component, params};
-        if (!best) best = {component: route.component, params};
+        if (!dynamic) return {component: route.component, params, meta: route.meta};
+        if (!best) best = {component: route.component, params, meta: route.meta};
     }
     return best;
 }

package/src/framework/utils/AvatarUtils.ts

@@ -0,0 +1,64 @@
+import {UrlUtils} from './UrlUtils';
+
+/** 内置头像标识前缀，数据库中存 preset:avatar-1 这类值 */
+const PRESET_PREFIX = 'preset:';
+
+/** 内置头像文件命名规则，需与后端 AvatarPresets 保持一致 */
+const PRESET_PATTERN = /^preset:avatar-(?:[1-9]|1[0-2])$/;
+
+/** 十二生肖头像名称，需与后端 AvatarPresets 保持一致 */
+const ZODIAC_LABELS = ['鼠', '牛', '虎', '兔', '龙', '蛇', '马', '羊', '猴', '鸡', '狗', '猪'];
+
+export interface AvatarPreset {
+    key: string;
+    label: string;
+    url: string;
+}
+
+/**
+ * 默认头像已移除。头像为空时返回空串，由 AntD Avatar 的 icon 兜底显示人形占位。
+ *
+ * @deprecated 不再提供默认头像图片，保留该导出仅为兼容旧引用
+ */
+export const DEFAULT_AVATAR_URL = '';
+
+function presetUrl(key: string): string | null {
+    if (!PRESET_PATTERN.test(key)) {
+        return null;
+    }
+    return UrlUtils.contextPath(`/avatars/${key.substring(PRESET_PREFIX.length)}.svg`);
+}
+
+/**
+ * 接口不可用时的兜底列表，与后端 AvatarPresets 保持一致。
+ * 正常使用时优先读取 admin/public/avatar-presets 返回的数据。
+ */
+export const FALLBACK_AVATAR_PRESETS: AvatarPreset[] = [
+    ...ZODIAC_LABELS.map((label, index) => {
+        const key = `${PRESET_PREFIX}avatar-${index + 1}`;
+        return {
+            key,
+            label,
+            url: presetUrl(key) as string,
+        };
+    }),
+];
+
+export class AvatarUtils {
+
+    /** 是否为内置头像标识 */
+    static isPreset(avatar?: string | null): boolean {
+        return !!avatar && avatar.startsWith(PRESET_PREFIX);
+    }
+
+    /** 将数据库中的头像值转换为可访问的图片地址；为空或无效时返回空串，由调用方兜底占位 */
+    static resolve(avatar?: string | null): string {
+        if (!avatar) {
+            return '';
+        }
+        if (AvatarUtils.isPreset(avatar)) {
+            return presetUrl(avatar) || '';
+        }
+        return UrlUtils.contextPath(`/file/${avatar}?thumb=1`);
+    }
+}