DriftLedger/docs/design/ui-redesign-p7-plan.md

P7：权限快捷引导 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (- [x]) syntax. 不执行任何 git 操作（用户要求，改动留工作区）。不创建额外任务清单。

Goal: 引导页权限步骤从纯文字改可操作状态清单；automation 页补齐通知监听/短信/存储三项权限的状态检测与快速跳转按钮。不新增原生权限，只加 UI 入口和一座通知监听状态检测 bridge 方法。

---

背景决策

• 不新增权限。所有权限已在 AndroidManifest 中声明（通过 Config Plugin），P7 只加 UI 入口。
• 通知监听状态检测需要一个原生 bridge 方法（isNotificationListenerEnabled），因为 RN 侧无法直接检查。用 NotificationManager.getEnabledListenerPackages()。
• 短信 + 存储用 React Native 内置 PermissionsAndroid API。
• 引导页 UI 沿用现有 Card + Button 组件，与 P1-P5 设计系统一致。

---

Task 1: 新增桥接方法 isNotificationListenerEnabled

Files:

• Modify: plugins/accessibility/android/AccessibilityBridgeModule.kt

• Modify: src/services/accessibilityBridge.ts

• Step 1: AccessibilityBridgeModule.kt 加方法

@ReactMethod
fun isNotificationListenerEnabled(promise: Promise) {
    try {
        val pm = reactContext.packageManager
        val enabledListeners = android.app.NotificationManager::class.java
            .getMethod("getEnabledListenerPackages")
            .invoke(reactContext.getSystemService(Context.NOTIFICATION_SERVICE)) as? List<String>
        val myPkg = reactContext.packageName
        promise.resolve(enabledListeners?.any { it.startsWith(myPkg) } == true)
    } catch (e: Exception) {
        promise.resolve(false)
    }
}

注意：getEnabledListenerPackages() 在 Android 11+ 需 isNotificationListenerEnabled(ComponentName)；优先用反射避免 API level lint 错误，反射失败返回 false。

• Step 2: JS 侧 bridge 接口

NativeAccessibilityBridge 加 isNotificationListenerEnabled(): Promise<boolean>;

• Step 3: 编译验证

cd android && ./gradlew :app:compileDebugKotlin → BUILD SUCCESSFUL

---

Task 2: 引导页权限步骤（_onboarding.tsx 重写 permissions 步骤）

Files:

• Modify: src/app/_onboarding.tsx

• Modify: src/i18n/zh.ts、src/i18n/en.ts（少量新键）

• Step 1: i18n 新键（zh/en 对等）

在 onboarding section 加：

permAccessibility    无障碍服务 / Accessibility Service
permNotification     通知监听 / Notification Listener
permOverlay          悬浮窗 / Overlay
permSms              短信读取 / SMS
permStorage          相册/存储 / Photos & Storage
permGranted          已授权 / Granted
permNotGranted       未授权 / Not Granted
permOpenSettings     前往设置 / Open Settings
permRequest          请求权限 / Request

• Step 2: 重写 permissions 步骤

替换 _onboarding.tsx:48 的 key: 'permissions' 步骤内容。在当前 description 下方加权限状态清单（Card 包裹，每行：图标 + 名称 + 状态点 + 操作按钮）。

权限列表：

1. 无障碍服务（BIND_ACCESSIBILITY_SERVICE）—— 最核心。检测 serviceRunning（从 getAccessibilityBridge().isServiceRunning() 异步取）。未授权 → 跳转 ACCESSIBILITY_SETTINGS
2. 通知监听（BIND_NOTIFICATION_LISTENER_SERVICE）—— 检测 bridge.isNotificationListenerEnabled()。未授权 → 跳转 ACTION_NOTIFICATION_LISTENER_SETTINGS
3. 短信（RECEIVE_SMS）—— PermissionsAndroid.check()。未授权 → PermissionsAndroid.request()
4. 存储（READ_MEDIA_IMAGES，Android 13+ 用 READ_MEDIA_IMAGES，否则 READ_EXTERNAL_STORAGE）—— 同上

实现细节：

• const [permStates, setPermStates] = useState<Record<string, boolean | null>>({}) —— null = 加载中
• useEffect(() => { checkAllPermissions(); }, []) —— 步骤切到 permissions 时触发
• checkAllPermissions：调 PermissionsAndroid.check() 检查短信和存储；调 bridge 检查无障碍和通知监听
• 每行渲染：Ionicons 图标 + permLabel + 右侧状态文字（绿「已授权」/ 灰「未授权」）+ 未授权时显示操作按钮
• 「全部已授权」时显示一个大绿色勾 + 提示文字，按钮不显示

权限 API 版本适配：

• PermissionsAndroid.PERMISSIONS 里 Android 13+ 是 READ_MEDIA_IMAGES，低版本用 READ_EXTERNAL_STORAGE

• 统一用 Platform.Version >= 33 ? 'android.permission.READ_MEDIA_IMAGES' : 'android.permission.READ_EXTERNAL_STORAGE'

• Step 3: 验证

Run: npm run typecheck && npm test → 全绿 Run: grep -rn "onboarding.perm" src/i18n/zh.ts src/i18n/en.ts → 确认键对等

---

Task 3: automation 页补齐权限入口

Files:

• Modify: src/app/automation/index.tsx

• Modify: src/i18n/zh.ts、src/i18n/en.ts（少量新键）

• Step 1: i18n 新键

在 automation section 加：

notificationTitle       通知监听服务 / Notification Listener
notificationEnabled     已启用 / Enabled
notificationDisabled    未启用 / Disabled
notificationOpenSettings 前往系统设置 / Open Settings
smsPermissionTitle      短信读取权限 / SMS Permission
smsPermissionGranted    已授权 / Granted
smsPermissionRequest    请求权限 / Request
storagePermissionTitle  存储权限 / Storage Permission
storagePermissionGranted 已授权 / Granted
storagePermissionRequest 请求权限 / Request

• Step 2: automation 页加权限卡片

在现有「无障碍服务状态与控制」Card 之后加一个新 Card：<Card title={t('automation.otherPermissions')}>。

内容三行：

1. 通知监听：异步 bridge.isNotificationListenerEnabled() → 状态文字 + 未启用时「前往系统设置」按钮（Linking.sendIntent('android.settings.ACTION_NOTIFICATION_LISTENER_SETTINGS')）
2. 短信：PermissionsAndroid.check('android.permission.RECEIVE_SMS') + PermissionsAndroid.request()
3. 存储：PermissionsAndroid.check(StoragePermission) + PermissionsAndroid.request()

实现模式：

const [notifEnabled, setNotifEnabled] = useState(false);
const [smsGranted, setSmsGranted] = useState(false);
const [storageGranted, setStorageGranted] = useState(false);
useEffect(() => {
  // 异步获取各权限状态
  checkNotif(); checkSms(); checkStorage();
}, []);

每行渲染：Ionicons 图标 + 权限名称 + 状态文字 + 未授权时的按钮。

• Step 3: 验证

Run: npm run typecheck && npm test → 全绿

---

Task 4: 编译 + 测试 + 终审

• Step 1: 编译验证

cd android && ./gradlew :app:compileDebugKotlin → BUILD SUCCESSFUL

• Step 2: 全量测试

npm test → 全绿；npm run typecheck → 0 错误

• Step 3: 审计

grep -rn "#[0-9A-Fa-f]\{6\}" src/ --include="*.ts" --include="*.tsx" | grep -v "theme/presets.ts\|theme/palette.ts"   # 无输出
grep -rn "fontFamily" src/app/_onboarding.tsx src/app/automation/index.tsx                                               # 无输出
grep -rnE "📊|💰|💸|📝|🔄|🎉|✨|⚠|📌|🌟" src/i18n/ src/app/_onboarding.tsx src/app/automation/index.tsx              # 无输出（预存 i18n fallbackWarn ⚠ 除外）

• Step 4: 手工走查（需设备）

1. 清数据 → 启动应用 → 引导页第 5 步（权限）→ 看到 4 个权限状态
2. 点未授权的无障碍 → 跳系统无障碍设置 → 返回看到状态已变
3. 点未授权的通知监听 → 跳系统通知设置
4. 点短信 → 弹出系统权限对话框
5. 引导页全部完成后 → 进入 automation 页 → 看到新增的权限卡片

---

终审修订（已实施，以实际代码为准）

终审日期：2026-07-22，审计 598 测试全绿、typecheck 干净、Kotlin BUILD SUCCESSFUL。

#	级别	问题	处理
—	—	无 Critical / Important 发现	—

偏差说明：

1. onboarding.permOverlay（悬浮窗）未加入引导页——计划 Task 2 决策列为可选项，实际未实现。不影响核心功能（sideload 自动授予 + 无障碍运行时浮窗走 ACCESSIBILITY_OVERLAY 不依赖此权限）。
2. T3 中 Platform.Version >= 33 改为 Number(Platform.Version) >= 33——React Native 的 Platform.Version 类型为 string | number，直接比较会 TS 报错。
3. T1 的 isNotificationListenerEnabled 使用反射而非 enabledListenerPackages 属性——minSdk=24 < API 27，反射是兼容方案。