原始项目使用 ADT 构建，没有 Gradle 支持。首先需要让项目能编译：

1. 创建 Gradle 构建配置（AGP 3.0.1 + Gradle 4.1）
2. 解决 ActionBarSherlock 兼容性（禁用 AAPT2）
3. 解决 support-v4 版本冲突（降级到 25.4.0）

1. 替换 ActionBarSherlock 为 AppCompat
2. 执行 AndroidX 迁移（Refactor → Migrate to AndroidX）
3. 升级到现代工具链（AGP 8.2.2 + Gradle 8.5 + JDK 17 + compileSdk 34）

症状：菜单图标在 ActionBar 上不显示

AppCompat 使用自己的 namespace 解析 showAsAction 属性。如果用 =android:showAsAction=，AppCompat 会静默忽略，图标不显示但不报错。

<item android:showAsAction="ifRoom" />


<item app:showAsAction="ifRoom"
    xmlns:app="http://schemas.android.com/apk/res-auto" />

**影响范围**：项目中 8 个菜单 XML 文件全部需要修改。只修了一个文件时，其他界面（capture 保存按钮、节点操作按钮等）的图标依然消失。

教训：迁移框架后要全局搜索同类问题，不要只修一个文件就以为搞定了。

症状：CannotPostForegroundServiceNotificationException: Bad notification for startForeground

Android 8.0（API 26）引入了 NotificationChannel。Android 13（API 33）进一步强化——如果 notification 引用的 channel 不存在，直接抛异常崩溃。

原始代码通过反射创建 channel（因为当时 compileSdk 是 23），但反射异常被静默吞掉了。Channel 没创建成功，notification 引用了一个不存在的 channel，崩溃。

try {
    Class<?> channelClass = Class.forName("android.app.NotificationChannel");
    } catch (Exception e) {
    }

NotificationChannel channel = new NotificationChannel(channelId, name,
    NotificationManager.IMPORTANCE_LOW);
nm.createNotificationChannel(channel);

同时，所有 NotificationCompat.Builder 构造函数都必须传 CHANNEL_ID：

new NotificationCompat.Builder(context)

new NotificationCompat.Builder(context, CHANNEL_ID)

**影响范围**：6 处 Builder 调用点，涉及 SyncService、TimeclockService、SynchronizerNotification、SynchronizerNotificationCompat。

症状：CalendarSyncService 启动时 SecurityException 崩溃

Android 6.0（API 23）引入了运行时权限。=READ_CALENDAR= 和 WRITE_CALENDAR 是危险权限，光在 Manifest 声明不够，必须运行时请求。

if (!hasCalendarPermission()) {
    stopSelf();      return;
}

**影响范围**：CalendarSyncService 的 onCreate() 和 onStartCommand() 都需要加权限检查。

症状：修复权限检查后，CalendarSyncService.onDestroy() 抛 NullPointerException

修复坑 3 加了 early return 后，=sharedPreferences= 没有被初始化，但 Android 仍然会调用 onDestroy()=，里面直接调了 =unregisterOnSharedPreferenceChangeListener(sharedPreferences...) 导致 NPE。

@Override
public void onDestroy() {
    if (sharedPreferences != null) {
        sharedPreferences.unregisterOnSharedPreferenceChangeListener(this);
    }
    super.onDestroy();
}

教训：在 onCreate() / onStartCommand() 中加 early return（比如权限检查失败后 stopSelf()=）时，=onDestroy() 仍会被 Android 调用。所有在 onDestroy() 中使用的字段都必须做空检查。

症状：SSH Connection failed: android.os.NetworkOnMainThreadException

Android 3.0 开始禁止主线程网络操作。但 SyncService.getSynchronizer() 在主线程调用 new SSHSynchronizer()=，而 SSHSynchronizer 的构造函数调了 =connect() 做网络连接。

public SSHSynchronizer(Context context) {
        this.connect();  }

public SSHSynchronizer(Context context) {
    }

后台线程的 getRemoteFile() 已经有重连逻辑，会自动在正确的线程上建立连接。

症状：同步后变更计数不刷新，同步动画不显示，但同步本身是成功的

这是最隐蔽的一个问题。=OrgUtils.announceSyncDone()= 通过 sendBroadcast() 发送隐式广播通知 UI 刷新。但 targetSdk 34 的设备上，隐式广播可能不被 RECEIVER_NOT_EXPORTED 的 receiver 接收。

Intent intent = new Intent(Synchronizer.SYNC_UPDATE);
context.sendBroadcast(intent);

Intent intent = new Intent(Synchronizer.SYNC_UPDATE);
intent.setPackage(context.getPackageName());  context.sendBroadcast(intent);

这个问题的影响面很大：变更计数不刷新、同步动画不显示、编辑后列表不更新——全部因为广播没送达。但不会报任何错误，就是功能静默失效。

教训：targetSdk 升级后，最危险的不是崩溃，而是功能静默失效。崩溃至少有日志，静默失效只能靠用户反馈。

症状：点击 Setup Wizard 直接退回到大纲界面

XML Preference 中用隐式 intent 打开 Activity：

<Preference android:title="Setup Wizard">
    <intent android:action="com.matburt.mobileorg.Settings.SETUP_WIZARD" />
</Preference>


<Preference android:title="Setup Wizard">
    <intent
        android:targetPackage="com.matburt.mobileorg"
        android:targetClass="com.matburt.mobileorg.Gui.Wizard.WizardActivity" />
</Preference>

症状：同步图标的旋转动画不显示

先 startAnimation() 再 =setActionView()=，此时 view 还没挂载到 window，动画被静默忽略。

refreshView.startAnimation(rotate);  synchronizerMenuItem.setActionView(refreshView);

synchronizerMenuItem.setActionView(refreshView);
refreshView.post(() -> refreshView.startAnimation(rotate));

症状：Setup Wizard 完成后，OutlineActivity 崩溃 NullPointerException

之前修改 Wizard 完成后的导航逻辑，使用 FLAG_ACTIVITY_SINGLE_TOP 回到已有的 OutlineActivity：

Intent outlineIntent = new Intent(context, OutlineActivity.class);
outlineIntent.setFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_SINGLE_TOP);
context.startActivity(outlineIntent);

由于 FLAG_ACTIVITY_SINGLE_TOP=，Android 不会创建新实例，而是调用已有实例的 =onNewIntent()=。但这个 Intent 没有设 action，所以 =getAction() 返回 null：

if (intent.getAction().equals(SYNC_FAILED)) { ... }

if (SYNC_FAILED.equals(intent.getAction())) { ... }

教训：=Intent.getAction()= 可以为 null。使用 FLAG_ACTIVITY_SINGLE_TOP 导航回已有 Activity 时，=onNewIntent()= 收到的 Intent 可能没有 action。养成 CONSTANT.equals(variable) 的习惯可以避免此类 NPE。