fix review issues

Author: Jeric-X

AGENTS.md

@@ -27,6 +27,24 @@ npm run test:coverage              # Jest with coverage
 npx jest <file> --no-coverage      # Run a single test file (e.g., src/__tests__/xxx.test.ts)
 ```
 
+## Required Validation
+
+Before considering a task complete, run every validation command that applies to the files
+changed in the task:
+
+- After modifying TypeScript or JavaScript files (`.ts`, `.tsx`, `.js`, or `.jsx`), run
+  `npm run lint:fix` and then `npm run type-check`. Run the type check after lint fixes so it
+  validates the final code.
+- After modifying Expo config plugin implementation files under `plugins/`, or their TypeScript
+  build configuration, run `npm run plugin:build` after linting.
+- After modifying application/runtime behavior or tests, run `npm run test`. This includes changes
+  to screens, hooks, services, stores, tasks, utilities, native-module JavaScript/TypeScript APIs,
+  and test files. Documentation-only, comment-only, and formatting-only changes do not require the
+  test suite.
+- After modifying Markdown or JSON files, run `npm run format-docs`.
+- If multiple rules apply, run all applicable commands. After any auto-fix, build, or formatting
+  command, inspect the diff and do not include unrelated generated or formatting changes.
+
 ## Architecture Overview
 
 This is a React Native clipboard synchronization app built with **Expo SDK 55**, using React Native 0.83 and React 19. It syncs clipboard content (text, images, files) between devices via SyncClipboard Server, WebDAV, or S3 backends.

App.tsx

@@ -14,33 +14,11 @@ import { useTheme } from './src/hooks/useTheme';
 import { setDynamicShortcuts } from 'shortcut';
 import { moveTaskToBack, setExcludeFromRecents } from 'native-util';
 import { networkAutoSwitchService } from './src/services/NetworkAutoSwitchService';
-
-const QUICK_UPLOAD_URL = 'syncclipboard://quick-upload';
-const QUICK_DOWNLOAD_URL = 'syncclipboard://quick-download';
-
-function parseQuickTileUrl(url: string | null): {
-  isQuickTile: boolean;
-  fromForeground: boolean;
-  direction: SyncDirection;
-} {
-  if (!url) return { isQuickTile: false, fromForeground: false, direction: SyncDirection.Download };
-  const fromForeground = url.includes('fg=1');
-  // Check upload first — its URL is a superset of the download prefix
-  if (url.startsWith(QUICK_UPLOAD_URL))
-    return { isQuickTile: true, fromForeground, direction: SyncDirection.Upload };
-  if (url.startsWith(QUICK_DOWNLOAD_URL))
-    return { isQuickTile: true, fromForeground, direction: SyncDirection.Download };
-  return { isQuickTile: false, fromForeground: false, direction: SyncDirection.Download };
-}
-
-function isShareIntentUrl(url: string | null): boolean {
-  if (!url) return false;
-  try {
-    return new URL(url).hostname === 'expo-sharing';
-  } catch {
-    return false;
-  }
-}
+import {
+  isShareIntentUrl,
+  parseQuickTileUrl,
+  shouldEnableAutoUpdateCheck,
+} from './src/utils/appLaunch';
 
 async function runOverlayNetworkPreflight(): Promise<void> {
   try {
@@ -54,6 +32,7 @@ type AppMode = 'checking' | 'home';
 
 export default function App() {
   const [appMode, setAppMode] = useState<AppMode>('checking');
+  const [autoUpdateCheckEnabled, setAutoUpdateCheckEnabled] = useState(false);
   // 快速操作覆盖层：始终以 overlay 形式显示，不卸载 AppNavigator/HomeScreen
   const [shareReceiveOverlay, setShareReceiveOverlay] = useState(false);
   const [quickActionOverlay, setQuickActionOverlay] = useState<{
@@ -112,6 +91,9 @@ export default function App() {
         await runOverlayNetworkPreflight();
         // fg=1 完成后留在 app，fg=0/无fg 完成后退出
         setQuickActionOverlay({ direction, exitAfterSync: !fromForeground });
+      } else if (shouldEnableAutoUpdateCheck(url)) {
+        // URL 解析完成且不是 overlay 冷启动，才允许首页自动检查更新。
+        setAutoUpdateCheckEnabled(true);
       }
     });
 
@@ -141,7 +123,9 @@ export default function App() {
       <ThemeProvider>
         <I18nProvider>
           <ThemedStatusBar />
-          {appMode === 'checking' ? null : <AppNavigator />}
+          {appMode === 'checking' ? null : (
+            <AppNavigator autoUpdateCheckEnabled={autoUpdateCheckEnabled} />
+          )}
           {shareReceiveOverlay && (
             <View style={StyleSheet.absoluteFill}>
               <ShareReceiveScreen

CLAUDE.md

@@ -27,6 +27,24 @@ npm run test:coverage              # Jest with coverage
 npx jest <file> --no-coverage      # Run a single test file (e.g., src/__tests__/xxx.test.ts)
 ```
 
+## Required Validation
+
+Before considering a task complete, run every validation command that applies to the files
+changed in the task:
+
+- After modifying TypeScript or JavaScript files (`.ts`, `.tsx`, `.js`, or `.jsx`), run
+  `npm run lint:fix` and then `npm run type-check`. Run the type check after lint fixes so it
+  validates the final code.
+- After modifying Expo config plugin implementation files under `plugins/`, or their TypeScript
+  build configuration, run `npm run plugin:build` after linting.
+- After modifying application/runtime behavior or tests, run `npm run test`. This includes changes
+  to screens, hooks, services, stores, tasks, utilities, native-module JavaScript/TypeScript APIs,
+  and test files. Documentation-only, comment-only, and formatting-only changes do not require the
+  test suite.
+- After modifying Markdown or JSON files, run `npm run format-docs`.
+- If multiple rules apply, run all applicable commands. After any auto-fix, build, or formatting
+  command, inspect the diff and do not include unrelated generated or formatting changes.
+
 ## Architecture Overview
 
 This is a React Native clipboard synchronization app built with **Expo SDK 55**, using React Native 0.83 and React 19. It syncs clipboard content (text, images, files) between devices via SyncClipboard Server, WebDAV, or S3 backends.

src/__tests__/UpdateService.test.ts

@@ -33,6 +33,7 @@ function createDependencies(
     download: jest.fn(async () => 'file:///update.apk'),
     install: jest.fn(async () => {}),
     getToday: jest.fn(() => '2026-08-23'),
+    isAndroid: jest.fn(() => true),
     ...overrides,
   };
 }
@@ -66,6 +67,19 @@ describe('UpdateService', () => {
     });
   });
 
+  it('iOS 自动检查静默跳过且不会进入 APK 下载流程', async () => {
+    const dependencies = createDependencies({ isAndroid: jest.fn(() => false) });
+    const service = new UpdateService(dependencies);
+
+    await expect(service.checkAutomatically()).resolves.toBeNull();
+    expect(dependencies.check).not.toHaveBeenCalled();
+    await expect(
+      service.downloadAndInstall('github', updateResult.latestVersion, updateResult.assets)
+    ).rejects.toThrow();
+    expect(dependencies.download).not.toHaveBeenCalled();
+    expect(dependencies.install).not.toHaveBeenCalled();
+  });
+
   it('下载时持续发布进度并在完成后调用安装器', async () => {
     const dependencies = createDependencies({
       download: jest.fn(async (options) => {
@@ -83,4 +97,57 @@ describe('UpdateService', () => {
     expect(dependencies.install).toHaveBeenCalledWith('file:///update.apk');
     expect(service.getState()).toMatchObject({ isDownloading: false, downloadProgress: 0 });
   });
+
+  it('取消尚未退出的下载时保持互斥，阻止立即重试覆盖同一缓存文件', async () => {
+    const dependencies = createDependencies({
+      download: jest.fn(
+        (options) =>
+          new Promise<string>((_resolve, reject) => {
+            options.signal?.addEventListener('abort', () => {
+              reject(new DOMException('Aborted', 'AbortError'));
+            });
+          })
+      ),
+    });
+    const service = new UpdateService(dependencies);
+    const firstDownload = service.downloadAndInstall(
+      'github',
+      updateResult.latestVersion,
+      updateResult.assets
+    );
+    await Promise.resolve();
+    await Promise.resolve();
+
+    service.cancelDownload();
+    const retry = service.downloadAndInstall(
+      'github',
+      updateResult.latestVersion,
+      updateResult.assets
+    );
+
+    expect(service.getState().isDownloading).toBe(true);
+    expect(dependencies.download).toHaveBeenCalledTimes(1);
+    await expect(retry).resolves.toBeUndefined();
+    await expect(firstDownload).rejects.toMatchObject({ name: 'AbortError' });
+    expect(service.getState().isDownloading).toBe(false);
+  });
+
+  it('安装器启动失败时保留可重试的更新状态', async () => {
+    const dependencies = createDependencies({
+      install: jest.fn(async () => {
+        throw new Error('installer unavailable');
+      }),
+    });
+    const service = new UpdateService(dependencies);
+    await service.checkForUpdates();
+
+    await expect(
+      service.downloadAndInstall('github', updateResult.latestVersion, updateResult.assets)
+    ).rejects.toThrow('installer unavailable');
+    expect(service.getState()).toMatchObject({
+      updateAvailable: true,
+      latestVersion: updateResult.latestVersion,
+      assets: updateResult.assets,
+    });
+  });
 });

src/__tests__/appLaunch.test.ts

@@ -0,0 +1,17 @@
+import { shouldEnableAutoUpdateCheck } from '@/utils/appLaunch';
+
+describe('shouldEnableAutoUpdateCheck', () => {
+  it.each([
+    'syncclipboard://quick-upload',
+    'syncclipboard://quick-upload?fg=1',
+    'syncclipboard://quick-download',
+    'syncclipboard://quick-download?fg=1',
+    'syncclipboard://expo-sharing',
+  ])('overlay 冷启动 %s 跳过更新检查', (url) => {
+    expect(shouldEnableAutoUpdateCheck(url)).toBe(false);
+  });
+
+  it.each([null, 'syncclipboard://home', 'https://example.com'])('普通启动 %s 允许检查', (url) => {
+    expect(shouldEnableAutoUpdateCheck(url)).toBe(true);
+  });
+});

src/hooks/useUpdateDialog.ts

@@ -1,5 +1,5 @@
 import { useCallback } from 'react';
-import { Alert } from 'react-native';
+import { Alert, Platform } from 'react-native';
 import { useTranslation } from 'react-i18next';
 import { APP_VERSION } from '@/constants';
 import { updateService } from '@/services/update';
@@ -35,6 +35,15 @@ export function useUpdateDialog(showMessage: ShowMessage): {
 
   const showUpdateDialog = useCallback(
     (version: string, assets: ReleaseAssetInfo[], releaseNotes?: string) => {
+      if (Platform.OS !== 'android') {
+        Alert.alert(
+          t('settings.updateNotSupportedTitle'),
+          t('settings.updateNotSupportedMessage'),
+          [{ text: t('common.confirm') }]
+        );
+        return;
+      }
+
       const channelName = channel === 'github' ? 'GitHub' : 'Gitee';
       const body = releaseNotes
         ? t('settings.newVersionMessageWithChannel', {

src/i18n/locales/en.ts

@@ -362,6 +362,9 @@ const en: DeepString<typeof zh> = {
     downloadGitee: 'Download from Gitee',
     downloadGitHub: 'Download from GitHub',
     updateNow: 'Update Now',
+    updateNotSupportedTitle: 'In-app updates unavailable',
+    updateNotSupportedMessage:
+      'Downloading and installing updates in the app is not supported on this platform.',
     noSuitableApk: 'No suitable APK found for this device',
     downloadCanceled: 'Download canceled',
     autoCheckUpdate: 'Auto-check for updates',

src/i18n/locales/zh.ts

@@ -351,6 +351,8 @@ const zh = {
     downloadGitee: 'Gitee 下载',
     downloadGitHub: 'GitHub 下载',
     updateNow: '立即更新',
+    updateNotSupportedTitle: '暂不支持应用内更新',
+    updateNotSupportedMessage: '当前平台暂不支持应用内下载和安装更新。',
     noSuitableApk: '找不到适合当前设备的 APK',
     downloadCanceled: '已取消下载',
     autoCheckUpdate: '自动检查更新',

src/navigation/AppNavigator.tsx

@@ -78,7 +78,11 @@ const SettingsStackNavigator = () => {
   );
 };
 
-export const AppNavigator = () => {
+interface AppNavigatorProps {
+  autoUpdateCheckEnabled: boolean;
+}
+
+export const AppNavigator = ({ autoUpdateCheckEnabled }: AppNavigatorProps) => {
   const { theme } = useTheme();
   const { t } = useTranslation();
 
@@ -147,7 +151,9 @@ export const AppNavigator = () => {
           },
         })}
       >
-        <Tab.Screen name="Home" component={HomeScreen} options={{ title: t('nav.home') }} />
+        <Tab.Screen name="Home" options={{ title: t('nav.home') }}>
+          {() => <HomeScreen autoUpdateCheckEnabled={autoUpdateCheckEnabled} />}
+        </Tab.Screen>
         <Tab.Screen
           name="History"
           component={HistoryScreen}

src/screens/HomeScreen.tsx

@@ -37,7 +37,11 @@ import { longRunningTaskManager } from '@/longRunningTask/LongRunningTaskManager
 import { updateService } from '@/services/update';
 import { useUpdateDialog } from '@/hooks/useUpdateDialog';
 
-export function HomeScreen() {
+interface HomeScreenProps {
+  autoUpdateCheckEnabled: boolean;
+}
+
+export function HomeScreen({ autoUpdateCheckEnabled }: HomeScreenProps) {
   const { theme } = useTheme();
   const { t } = useTranslation();
   const navigation = useNavigation();
@@ -68,7 +72,7 @@ export function HomeScreen() {
 
   // 首页首次挂载后自动检查更新（默认每天一次）。
   useEffect(() => {
-    if (!isLoaded) return;
+    if (!isLoaded || !autoUpdateCheckEnabled) return;
     updateService
       .checkAutomatically()
       .then((result) => {
@@ -81,7 +85,7 @@ export function HomeScreen() {
           console.warn('[HomeScreen] Auto update check failed:', error);
         }
       });
-  }, [isLoaded, showUpdateDialog]);
+  }, [autoUpdateCheckEnabled, isLoaded, showUpdateDialog]);
 
   // 启动所有后台任务（先加载字体，再启动后台任务，避免后台繁重任务导致导航栏图标加载缓慢）
   useEffect(() => {