@autional/shared 0.1.0-rc.52 → 0.1.0-rc.53

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@autional/shared",
3
- "version": "0.1.0-rc.52",
3
+ "version": "0.1.0-rc.53",
4
4
  "description": "Autional shared layer — API client, auth, types, hooks, utils",
5
5
  "license": "AGPL-3.0",
6
6
  "main": "./src/index.ts",
@@ -17,8 +17,13 @@ interface RequireAuthProps {
17
17
  loadingFallback?: React.ReactNode;
18
18
  /** 确定性未知 slug(by-slug HTTP 404)时渲染的 404 页;缺省用内置极简 404 兜底 */
19
19
  notFound?: React.ReactNode;
20
+ /** 启动数据(权限/租户)加载失败或超时时的错误页;缺省用内置可恢复错误页兜底 */
21
+ bootstrapError?: React.ReactNode;
20
22
  }
21
23
 
24
+ /** 启动等待上限:超过即认定「卡住」,降级到可恢复错误页(P1-2)。 */
25
+ const BOOTSTRAP_TIMEOUT_MS = 10_000;
26
+
22
27
  /**
23
28
  * 内置极简 404(零依赖,供未注入 notFound 的站点兜底 —— shared 不能 import 各
24
29
  * app 的 not-found/page)。样式用 CSS 变量 var(--color-*),.dark 下自动反转。
@@ -96,18 +101,84 @@ function DefaultSignInRequired({ onSignIn }: { onSignIn: () => void }) {
96
101
  );
97
102
  }
98
103
 
104
+ /**
105
+ * P1-2(2026-11-08 线上复现):启动数据(权限/租户)加载失败或超时时,原实现
106
+ * 恒 render null ⇒ 后端任一 5xx 就让整站变成空白页(无提示、无重试、不跳登录)。
107
+ * 此组件给最小可恢复 UI:说明 + 重试(整页重载,重建查询与状态机)。
108
+ * 零依赖、CSS 变量主题;按钮固定 #2563eb(白字 5.17:1 过 AA),不引品牌色。
109
+ */
110
+ function DefaultBootstrapError({ onRetry }: { onRetry: () => void }) {
111
+ const zh =
112
+ typeof document !== 'undefined' &&
113
+ (document.documentElement.lang || '').toLowerCase().startsWith('zh');
114
+ return (
115
+ <div
116
+ role="alert"
117
+ style={{
118
+ display: 'flex',
119
+ flexDirection: 'column',
120
+ alignItems: 'center',
121
+ justifyContent: 'center',
122
+ minHeight: '40vh',
123
+ gap: '0.75rem',
124
+ width: '100%',
125
+ }}
126
+ >
127
+ <h1 style={{ fontSize: '1.25rem', fontWeight: 600, color: 'var(--color-text-primary)' }}>
128
+ {zh ? '加载失败' : 'Failed to load'}
129
+ </h1>
130
+ <p style={{ color: 'var(--color-text-secondary)', fontSize: '0.875rem', margin: 0 }}>
131
+ {zh ? '无法加载账号信息,请检查网络后重试' : 'Could not load your account. Check your connection and retry.'}
132
+ </p>
133
+ <button
134
+ type="button"
135
+ onClick={onRetry}
136
+ style={{
137
+ border: 0,
138
+ borderRadius: 6,
139
+ padding: '8px 18px',
140
+ fontSize: '0.875rem',
141
+ cursor: 'pointer',
142
+ background: '#2563eb',
143
+ color: '#fff',
144
+ }}
145
+ >
146
+ {zh ? '重试' : 'Retry'}
147
+ </button>
148
+ </div>
149
+ );
150
+ }
151
+
99
152
  export function RequireAuth({
100
153
  children,
101
154
  allowedRoles,
102
155
  fallback,
103
156
  loadingFallback,
104
157
  notFound,
158
+ bootstrapError,
105
159
  }: RequireAuthProps) {
106
160
  const machine = useAuthMachine();
107
161
  const tenantRoute = useTenantRoute();
108
162
  // 「停留」已选(被动登录跳转被用户取消)——渲染恢复态而非空白(AUTH-03)
109
163
  const [stayed, setStayed] = useState(false);
110
164
 
165
+ // P1-2:启动数据加载失败/卡住时不得 render null(整站白屏)。
166
+ // ① bootstrapState==='error'(两个查询都失败)立即给错误页;
167
+ // ② checking/bootstrap 超过 10s 视为卡住(单查询挂起等),同样降级。
168
+ const [bootstrapTimedOut, setBootstrapTimedOut] = useState(false);
169
+ const waitingBootstrap = machine.status === 'checking' || machine.status === 'bootstrap';
170
+ useEffect(() => {
171
+ if (!waitingBootstrap) {
172
+ setBootstrapTimedOut(false);
173
+ return;
174
+ }
175
+ const timer = setTimeout(() => setBootstrapTimedOut(true), BOOTSTRAP_TIMEOUT_MS);
176
+ return () => clearTimeout(timer);
177
+ }, [waitingBootstrap]);
178
+ const retryBootstrap = useCallback(() => {
179
+ if (typeof window !== 'undefined') window.location.reload();
180
+ }, []);
181
+
111
182
  // 登录跳转的单一出口:effect(进入未认证态)与恢复态「前往登录」按钮共用。
112
183
  // force=true 跳过 OAuth 10s 防重入窗口(用户显式重试)。
113
184
  const triggerLogin = useCallback(
@@ -179,6 +250,13 @@ export function RequireAuth({
179
250
  triggerLogin(false);
180
251
  }, [machine.status, tenantRoute, triggerLogin]);
181
252
 
253
+ // P1-2:启动数据失败 / 等待超时 → 可恢复错误页(不得空白)。
254
+ // 放在所有 status 分支之前:机器在 BOOTSTRAP_ERROR 时会降级到 ready,
255
+ // 此时仍是「启动失败」语义,不能直接放行子路由。
256
+ if (machine.bootstrapState === 'error' || bootstrapTimedOut) {
257
+ return bootstrapError ? <>{bootstrapError}</> : <DefaultBootstrapError onRetry={retryBootstrap} />;
258
+ }
259
+
182
260
  if (machine.status === 'checking' || machine.status === 'bootstrap') {
183
261
  return loadingFallback ? <>{loadingFallback}</> : null;
184
262
  }
@@ -0,0 +1,96 @@
1
+ // @vitest-environment jsdom
2
+ import '@testing-library/jest-dom/vitest';
3
+ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
4
+ import { render, screen, cleanup } from '@testing-library/react';
5
+
6
+ // ============================================================
7
+ // P1-2 回归锁(2026-11-08 用户门户线上复现)
8
+ // 后端 bootstrap 接口全 5xx 时,useBootstrap 曾返回 'loading' ⇒ 状态机永停
9
+ // bootstrap ⇒ RequireAuth 恒 render null ⇒ 整站白屏(无提示/无重试/不跳登录)。
10
+ // 修复后:bootstrapState==='error' 必须渲染可恢复错误页,且不得渲染子路由。
11
+ // ============================================================
12
+
13
+ const { mockState } = vi.hoisted(() => ({
14
+ mockState: {
15
+ machineStatus: 'ready' as string,
16
+ bootstrapState: 'error' as string,
17
+ tenantRoute: {
18
+ slug: 'acme-corp',
19
+ tenantId: 't1',
20
+ oauthClientId: null as string | null,
21
+ loading: false,
22
+ notFound: false,
23
+ unknownSlug: false,
24
+ },
25
+ },
26
+ }));
27
+
28
+ vi.mock('../../auth/auth-machine', () => ({
29
+ useAuthMachine: () => ({
30
+ status: mockState.machineStatus,
31
+ bootstrapState: mockState.bootstrapState,
32
+ }),
33
+ }));
34
+
35
+ vi.mock('../../auth/tenant-route-middleware', async (importOriginal) => ({
36
+ ...(await importOriginal<typeof import('../../auth/tenant-route-middleware')>()),
37
+ useTenantRoute: () => mockState.tenantRoute,
38
+ }));
39
+
40
+ vi.mock('../../auth/oauth-login', () => ({ initiateOAuthLogin: vi.fn() }));
41
+
42
+ vi.mock('../../auth/service', () => ({
43
+ AuthService: {
44
+ getAccessToken: () => 'token-xyz',
45
+ getCurrentRole: () => 'member',
46
+ getPermissions: () => ['user.read'],
47
+ },
48
+ setBootstrapLock: vi.fn(),
49
+ }));
50
+
51
+ import { RequireAuth } from '../RequireAuth';
52
+
53
+ describe('RequireAuth(P1-2 启动失败不得白屏)', () => {
54
+ beforeEach(() => {
55
+ mockState.machineStatus = 'ready';
56
+ mockState.bootstrapState = 'error';
57
+ document.documentElement.lang = 'zh-CN';
58
+ });
59
+
60
+ afterEach(() => cleanup());
61
+
62
+ it('bootstrapState=error → 渲染错误页 + 重试按钮,且不渲染子路由', () => {
63
+ render(
64
+ <RequireAuth>
65
+ <div data-testid="protected">受保护内容</div>
66
+ </RequireAuth>,
67
+ );
68
+
69
+ expect(screen.getByRole('alert')).toBeInTheDocument();
70
+ expect(screen.getByText('加载失败')).toBeInTheDocument();
71
+ expect(screen.getByRole('button', { name: '重试' })).toBeInTheDocument();
72
+ expect(screen.queryByTestId('protected')).not.toBeInTheDocument();
73
+ });
74
+
75
+ it('英文界面错误页文案(<html lang="en">)', () => {
76
+ document.documentElement.lang = 'en-US';
77
+ render(
78
+ <RequireAuth>
79
+ <div data-testid="protected">protected</div>
80
+ </RequireAuth>,
81
+ );
82
+ expect(screen.getByText('Failed to load')).toBeInTheDocument();
83
+ expect(screen.getByRole('button', { name: 'Retry' })).toBeInTheDocument();
84
+ });
85
+
86
+ it('bootstrapState=ready → 正常渲染子路由(修复不得误伤正常路径)', () => {
87
+ mockState.bootstrapState = 'ready';
88
+ render(
89
+ <RequireAuth>
90
+ <div data-testid="protected">受保护内容</div>
91
+ </RequireAuth>,
92
+ );
93
+ expect(screen.getByTestId('protected')).toBeInTheDocument();
94
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();
95
+ });
96
+ });
@@ -0,0 +1,83 @@
1
+ // @vitest-environment jsdom
2
+ import '@testing-library/jest-dom/vitest';
3
+ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
4
+ import { render, screen, cleanup } from '@testing-library/react';
5
+ import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
6
+
7
+ // ============================================================
8
+ // P1-2 集成回归锁:真实 useAuthMachine + useBootstrap 链路
9
+ // 两个 bootstrap 查询都失败 → 机器曾永停 bootstrap → RequireAuth 渲染 null → 白屏。
10
+ // 本用例不 mock 状态机,只 mock「查询返回错误」,验证端到端落到错误页。
11
+ // ============================================================
12
+
13
+ vi.mock('../../auth/auth-queries', () => ({
14
+ usePermissionsQuery: () => ({ data: undefined, isError: true, isError2: true }),
15
+ useTenantsQuery: () => ({ data: undefined, isError: true }),
16
+ }));
17
+
18
+ vi.mock('../../generated/api', () => ({ profileAvatar: vi.fn().mockResolvedValue({}) }));
19
+
20
+ vi.mock('../../auth/oauth-login', () => ({ initiateOAuthLogin: vi.fn() }));
21
+
22
+ vi.mock('../../auth/tenant-route-middleware', async (importOriginal) => ({
23
+ ...(await importOriginal<typeof import('../../auth/tenant-route-middleware')>()),
24
+ useTenantRoute: () => ({
25
+ slug: 'acme-corp',
26
+ tenantId: 't1',
27
+ oauthClientId: null,
28
+ loading: false,
29
+ notFound: false,
30
+ unknownSlug: false,
31
+ }),
32
+ }));
33
+
34
+ import { RequireAuth } from '../RequireAuth';
35
+ import { useAuthStore } from '../../auth/store';
36
+
37
+ const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
38
+ function wrapper({ children }: { children: React.ReactNode }) {
39
+ return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
40
+ }
41
+
42
+ describe('RequireAuth × useAuthMachine(bootstrap 失败链路)', () => {
43
+ beforeEach(() => {
44
+ document.documentElement.lang = 'zh-CN';
45
+ window.localStorage.clear();
46
+ useAuthStore.setState({
47
+ user: { id: 'u-1', username: 'demo', email: 'demo@example.com', status: 'active' },
48
+ accessToken: 'token-xyz',
49
+ refreshToken: 'refresh-xyz',
50
+ tenants: [],
51
+ currentTenantId: 't1',
52
+ permissions: [],
53
+ isAuthenticated: true,
54
+ });
55
+ });
56
+
57
+ afterEach(() => {
58
+ cleanup();
59
+ useAuthStore.setState({
60
+ user: null,
61
+ accessToken: null,
62
+ refreshToken: null,
63
+ tenants: [],
64
+ currentTenantId: null,
65
+ permissions: [],
66
+ isAuthenticated: false,
67
+ });
68
+ window.localStorage.clear();
69
+ });
70
+
71
+ it('权限/租户查询都失败 → 渲染「加载失败」而非空白,且不放行子路由', async () => {
72
+ render(
73
+ <RequireAuth>
74
+ <div data-testid="protected">受保护内容</div>
75
+ </RequireAuth>,
76
+ { wrapper },
77
+ );
78
+
79
+ expect(await screen.findByText('加载失败')).toBeInTheDocument();
80
+ expect(screen.getByRole('button', { name: '重试' })).toBeInTheDocument();
81
+ expect(screen.queryByTestId('protected')).not.toBeInTheDocument();
82
+ });
83
+ });
@@ -1,7 +1,7 @@
1
1
  // GENERATED FILE — DO NOT EDIT.
2
2
  // Source: contracts/errors.semantics.json(@autional/shared 仓内镜像,源 = service-core base/error/testdata/errors.semantics.json)
3
3
  // Regenerate: pnpm gen:errors · Verify: pnpm gen:errors:check
4
- // rows: 801 · source sha256: 812f1ec64dade2b940ae6f12af43fb170e9f0f7f658b707fc29f1f0fd48c50b5
4
+ // rows: 802 · source sha256: d1d69d0eedc43e211b89c0efa5ade53b95a0d2ff31ea706800ba29b04c97f20f
5
5
  //
6
6
  // 单一真源链:service-core/base/error/semantics.go(Go)→ errors.semantics.json → 本文件。
7
7
  // ⚠️ 禁止在本文件或页面里手抄错误码分支:请消费 ERROR_SEMANTICS / UNPROVISIONED_CODES。
@@ -393,6 +393,7 @@ export const ERROR_SEMANTICS: Readonly<Record<number, ErrorSemantics>> = {
393
393
  61000902: { code: 61000902, httpStatus: 410, class: 'gone', absence: '', uiObservation: 'expired', retryable: false, docsPath: '/errors/61000902' },
394
394
  61000903: { code: 61000903, httpStatus: 409, class: 'conflict', absence: '', uiObservation: 'conflict', retryable: false, docsPath: '/errors/61000903' },
395
395
  61000904: { code: 61000904, httpStatus: 400, class: 'invalid', absence: '', uiObservation: 'form_error', retryable: false, docsPath: '/errors/61000904' },
396
+ 61000905: { code: 61000905, httpStatus: 403, class: 'forbidden', absence: '', uiObservation: 'forbidden', name: 'QR_LOGIN_TENANT_MISMATCH', retryable: false, docsPath: '/errors/61000905' },
396
397
  61001001: { code: 61001001, httpStatus: 401, class: 'unauthorized', absence: '', uiObservation: 'session_expired', retryable: false, docsPath: '/errors/61001001' },
397
398
  61001002: { code: 61001002, httpStatus: 429, class: 'limit', absence: '', uiObservation: 'rate_limited', retryable: true, docsPath: '/errors/61001002' },
398
399
  61001003: { code: 61001003, httpStatus: 409, class: 'conflict', absence: '', uiObservation: 'conflict', retryable: false, docsPath: '/errors/61001003' },
@@ -862,8 +863,8 @@ export const UNPROVISIONED_CODES: ReadonlySet<number> = new Set([]);
862
863
  export const EMPTY_STATE_CODES: ReadonlySet<number> = new Set([]);
863
864
 
864
865
  export const ERROR_SEMANTICS_META = {
865
- rowCount: 801,
866
- sourceSha256: '812f1ec64dade2b940ae6f12af43fb170e9f0f7f658b707fc29f1f0fd48c50b5',
866
+ rowCount: 802,
867
+ sourceSha256: 'd1d69d0eedc43e211b89c0efa5ade53b95a0d2ff31ea706800ba29b04c97f20f',
867
868
  } as const;
868
869
 
869
870
  /** 具名错误码常量(契约 name → code)。页面只消费常量,不写数字字面量。 */
@@ -875,6 +876,7 @@ export const ERROR_CODES = {
875
876
  MFA_CODE_ALREADY_USED: 61000409,
876
877
  MFA_ATTEMPTS_THROTTLED: 61000410,
877
878
  MFA_AUTHENTICATOR_DISABLED: 61000411,
879
+ QR_LOGIN_TENANT_MISMATCH: 61000905,
878
880
  } as const;
879
881
 
880
882
  export type ErrorCodeName = keyof typeof ERROR_CODES;