@npm.365xs.cn/vue-admin-framework 0.1.0 → 0.2.0

package/README.md

@@ -1,63 +1,91 @@
-# @shinesun/vue-admin-framework
-
-Vue 3 公共管理框架，提供 OAuth 2.0 Authorization Code + PKCE 客户端、登录回调页面、
-动态侧栏、顶部用户区和访问页签。
-
-消费应用负责提供 Vue Router、菜单树、用户资料、品牌配置和业务页面。包要求项目已安装
-Vue 3、Vue Router、Element Plus 和 `@element-plus/icons-vue`。
-
-## 安装
-
-```bash
-npm install @shinesun/vue-admin-framework
-```
-
-应用入口同时引入样式：
-
-```ts
-import '@shinesun/vue-admin-framework/style.css'
-```
-
-## 使用
-
-```vue
-<script setup lang="ts">
-import { AdminFrameworkLayout } from '@shinesun/vue-admin-framework'
-</script>
-
-<template>
-  <AdminFrameworkLayout
-    brand-name="示例系统"
-    :menus="menus"
-    :navigation-loaded="navigationLoaded"
-    :username="username"
-    :login-account="loginAccount"
-    :initials="initials"
-    tab-storage-key="example_visited_tabs"
-    @logout="logout"
-  />
-</template>
-```
-
-OAuth 客户端通过 `createOAuthPkceClient` 创建。每个应用必须提供独立的
-`storageNamespace`、`clientId`、`redirectUri` 和默认返回路径。
-
-菜单节点类型 `FrameworkMenuNode` 可携带 `menuDomain?: string | null`，表示该菜单
-所属应用的 Origin；未配置时为 `null`。框架保留此字段，不自动将其与相对 `route`
-拼接或执行跨域跳转。消费应用可按自身导航策略使用这两个字段构造跨应用地址。
-
-## 发布产物
-
-包只发布 ESM，并包含：
-
-- `dist/index.js`
-- `dist/index.d.ts`
-- `dist/style.css`
-- 组件和公共类型声明
-
-发布前运行：
-
-```bash
-npm run build
-npm pack --dry-run
-```
+# @npm.365xs.cn/vue-admin-framework
+
+向上集团 Vue 3 公共管理后台框架。包统一提供 OAuth 2.0 Authorization Code + PKCE、
+标准当前用户与全应用菜单读取、会话状态、动态侧栏、顶部用户区和访问页签。
+
+消费应用只负责业务 Router、`admin-resources.json`、Mock 数据、品牌配置和业务页面。项目
+需要安装 Vue 3、Vue Router、Element Plus 和 `@element-plus/icons-vue`。
+
+## 标准 Access API
+
+真实模式下由 `createAdminFrameworkSession` 内部统一调用：
+
+```http
+GET /api/current/me
+GET /api/me/menus
+Authorization: Bearer <application-access-token>
+```
+
+`/api/me/menus` 不带 `applicationCode`，必须返回 `applicationCode: null` 的全应用菜单。
+公共包统一处理 Bearer Header、有效 Token 获取、401 单次刷新、响应校验、菜单规范化、
+顶部用户信息和菜单加载状态。消费应用不得重复实现这两个标准客户端。
+
+## 安装
+
+```bash
+npm install @npm.365xs.cn/vue-admin-framework
+```
+
+应用入口同时引入样式：
+
+```ts
+import '@npm.365xs.cn/vue-admin-framework/style.css'
+```
+
+## Session 接入
+
+```ts
+import { defineStore } from 'pinia'
+import { createAdminFrameworkSession } from '@npm.365xs.cn/vue-admin-framework'
+import { oauthClient } from '@/services/auth'
+import { mockMenus, mockUser } from '@/config/resources'
+
+export const useSessionStore = defineStore('session', () =>
+  createAdminFrameworkSession({
+    oauthClient,
+    accessApiBaseUrl: import.meta.env.VITE_ACCESS_API_BASE_URL || '',
+    mockUser,
+    mockMenus,
+    defaultReturnUrl: '/admin/overview',
+    storageKeysToClear: ['admin_visited_tabs'],
+  }),
+)
+```
+
+路由守卫使用 `session.ensureAuthenticated()`、`session.login()` 和
+`session.ensureLoaded()`；布局直接绑定 `session.menus`、`session.username`、
+`session.loginAccount`、`session.initials`、`session.navigationLoaded` 和
+`session.navigationError`。
+
+## 跨应用单点登录
+
+每个应用必须使用独立 OAuth Client、PKCE、本地 Access Token 和 Audience。禁止复制或共享
+Access Token，也禁止把 Token 放入 URL、父域 Cookie 或跨应用共享存储。
+
+跨应用免重复输入密码依赖 OAuth Authority 的 HttpOnly SSO Cookie：目标应用没有本地 Token
+时仍进入标准 `/oauth2/authorize`，Authority 识别已有登录会话后直接签发目标应用授权码，
+目标应用再换取自己的 Token。显式切换账号或退出当前应用后重新登录时，框架使用
+`prompt=login` 强制展示登录页。
+
+## 菜单与跨应用导航
+
+菜单节点类型 `FrameworkMenuNode` 可携带 `menuDomain?: string | null`，表示所属应用 Origin。
+公共包保留并规范化该字段，但不会把外部菜单注册到本地 Router。消费应用应使用
+`createExternalMenuHrefResolver` 安全解析其他应用的 `menuDomain + route`，并通过整页跳转
+进入目标应用。
+
+## 发布产物
+
+包只发布 ESM，并包含：
+
+- `dist/index.js`
+- `dist/index.d.ts`
+- `dist/style.css`
+- 组件和公共类型声明
+
+发布前运行：
+
+```bash
+npm run build
+npm pack --dry-run
+```

package/dist/access.d.ts

@@ -0,0 +1,43 @@
+import type { FrameworkMenuNode } from './menu';
+import type { OAuthPkceClient } from './oauth';
+export interface FrameworkRelationSummary {
+    id: string;
+    name: string;
+    code?: string;
+}
+export interface FrameworkCurrentUser {
+    userId: string;
+    displayName: string;
+    username: string;
+    loginAccount: string;
+    employeeNo: string;
+    mobile: string;
+    email: string;
+    status: string;
+    organizations: FrameworkRelationSummary[];
+    roles: FrameworkRelationSummary[];
+    lastLoginAt: string;
+    createdAt: string;
+}
+export interface VisibleMenusResponse {
+    applicationCode: null;
+    menus: FrameworkMenuNode[];
+    tokenExpiresAt: string;
+}
+export interface AdminAccessClientOptions {
+    oauthClient: OAuthPkceClient;
+    baseUrl: string;
+    fetcher?: typeof fetch;
+}
+export interface AdminAccessClient {
+    getCurrentUser(): Promise<FrameworkCurrentUser>;
+    getCurrentMenus(): Promise<FrameworkMenuNode[]>;
+}
+export declare class AdminAccessError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string;
+    constructor(message: string, status: number, code?: string, requestId?: string);
+}
+export declare function createAdminAccessClient(options: AdminAccessClientOptions): AdminAccessClient;
+export declare function normalizeCurrentUser(value: unknown): FrameworkCurrentUser;

package/dist/components/AdminFrameworkLayout.vue.d.ts

@@ -24,12 +24,12 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {
     onSettings?: (() => any) | undefined;
     onNotifications?: (() => any) | undefined;
 }>, {
+    username: string;
+    loginAccount: string;
     resolveExternalMenuHref: (item: FrameworkMenuNode) => string | null;
     brandSubtitle: string;
     consoleName: string;
     navigationError: string;
-    username: string;
-    loginAccount: string;
     initials: string;
     tabStorageKey: string;
     maxTabs: number;

package/dist/index.d.ts

@@ -1,10 +1,14 @@
 export { default as AdminFrameworkLayout } from './components/AdminFrameworkLayout.vue';
 export { default as FrameworkMenuItem } from './components/FrameworkMenuItem.vue';
 export { default as OAuthCallbackView } from './views/OAuthCallbackView.vue';
+export { AdminAccessError, createAdminAccessClient, normalizeCurrentUser, } from './access';
+export type { AdminAccessClient, AdminAccessClientOptions, FrameworkCurrentUser, FrameworkRelationSummary, VisibleMenusResponse, } from './access';
 export type { FrameworkMenuNode } from './menu';
-export { findMenuByRoute, findMenuTrail, flattenRoutableMenus, } from './navigation';
+export { createExternalMenuHrefResolver, findMenuByRoute, findMenuTrail, flattenRoutableMenus, hasPageAccess, normalizeFrameworkMenus, } from './navigation';
 export { createOAuthPkceClient, sanitizeReturnUrl, } from './oauth';
-export type { OAuthLocation, OAuthPkceClient, OAuthPkceClientOptions, OAuthSession, } from './oauth';
+export type { OAuthLocation, OAuthLoginOptions, OAuthPkceClient, OAuthPkceClientOptions, OAuthSession, } from './oauth';
+export { createAdminFrameworkSession, } from './session';
+export type { AdminFrameworkSession, AdminFrameworkSessionOptions, } from './session';
 export { sha256 } from './sha256';
 export { closeVisitedTab, normalizeVisitedTabs, retainActiveTab, upsertVisitedTab, } from './tabs';
 export type { ClosedTabResult, FrameworkTab, } from './tabs';