HarmonyOS APP中@ohos.privacyManager、权限访问日志与合规性检查全攻略

📌 核心要点：权限审计是应用隐私合规的"行车记录仪"，通过 @ohos.privacyManager 追踪权限使用记录、监控敏感 API 调用、生成权限访问日志，确保应用在权限使用上透明可追溯，满足监管合规要求。

一、背景

你有没有想过，为什么现在的手机系统都在状态栏上显示"绿点"或"橙点"——当你使用相机或麦克风时，那个小圆点就会亮起来？

这就是权限审计的直观体现。它告诉用户："嘿，有个应用正在使用你的相机。"这种透明度机制，是现代操作系统的标配。

但权限审计远不止一个状态栏小圆点。在应用开发层面，权限审计意味着：

1. 记录你的应用使用了哪些权限——什么时候用的、用了多久、访问了什么数据
2. 追踪敏感 API 的调用链——从用户操作到数据访问的完整路径
3. 生成合规性报告——向监管证明你的应用没有滥用权限
4. 发现异常行为——如果某个权限被频繁使用，可能存在安全风险

打个比方：权限声明是"申请门禁卡"，动态申请是"刷卡进门"，而权限审计就是"门禁系统的日志记录"——谁进了哪个门、什么时候进的、待了多久，全部有据可查。

为什么权限审计越来越重要？ 因为全球隐私法规（GDPR、个人信息保护法等）都要求应用对用户数据的访问必须透明可追溯。如果你的应用无法证明"我没有滥用权限"，那在合规审查中就会处于被动。

二、核心原理

2.1 权限审计的体系架构

2.2 @ohos.privacyManager 核心 API

@ohos.privacyManager 是鸿蒙提供的隐私管理模块，核心方法如下：

2.3 权限使用记录的数据结构

// 权限使用记录查询选项
interface PermissionUsedRequest {
  tokenId?: number;              // 应用Token ID
  isRemote?: boolean;            // 是否为远程设备
  deviceId?: string;             // 设备ID
  bundleName?: string;           // 应用包名
  permissionNames?: string[];    // 权限名称列表
  beginTime?: number;            // 开始时间（毫秒时间戳）
  endTime?: number;              // 结束时间（毫秒时间戳）
  allFlag?: number;              // 查询标志：0=仅查询有记录的，1=查询所有
}

// 单条权限使用记录
interface PermissionUsedRecord {
  tokenId: number;               // 应用Token ID
  bundleName: string;            // 应用包名
  permissionName: string;        // 权限名称
  accessCount: number;           // 访问次数
  rejectCount: number;           // 拒绝次数
  lastAccessTime: number;        // 最后访问时间
  lastRejectTime: number;        // 最后拒绝时间
  lastAccessDuration: number;    // 最后访问持续时间
}

2.4 权限审计的三个层次

三、代码实战

示例1：权限使用记录管理器

封装一个完整的权限使用记录管理器，支持记录添加、查询、统计和导出：

// utils/PermissionAuditManager.ets - 权限审计管理器
import { privacyManager, bundleManager, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 审计记录条目
interface AuditRecordEntry {
  permissionName: string;        // 权限名称
  bundleName: string;            // 应用包名
  accessCount: number;           // 访问次数
  rejectCount: number;           // 拒绝次数
  lastAccessTime: string;        // 最后访问时间（格式化）
  lastRejectTime: string;        // 最后拒绝时间（格式化）
  lastAccessDuration: string;    // 最后访问持续时间
  riskLevel: 'low' | 'medium' | 'high';  // 风险等级
}

// 审计统计摘要
interface AuditSummary {
  totalPermissions: number;      // 涉及权限总数
  totalAccessCount: number;      // 总访问次数
  totalRejectCount: number;      // 总拒绝次数
  highRiskCount: number;         // 高风险权限数
  mostUsedPermission: string;    // 最常用权限
  leastUsedPermission: string;   // 最少用权限
  auditPeriod: string;           // 审计时间段
}

// 合规检查结果
interface ComplianceCheckResult {
  isCompliant: boolean;          // 是否合规
  issues: Array<{
    permission: string;
    issue: string;
    severity: 'warning' | 'error';
    suggestion: string;
  }>;
  checkTime: string;
}

export class PermissionAuditManager {
  // 正在使用的权限追踪（用于计算使用时长）
  private activeUsageMap: Map<string, number> = new Map();

  /**
   * 记录权限使用开始
   * @param tokenId 应用Token ID
   * @param permission 权限名称
   */
  async startPermissionUsage(tokenId: number, permission: Permissions): Promise<void> {
    try {
      // 调用系统API标记权限使用开始
      await privacyManager.startUsingPermission(tokenId, permission);
      // 记录开始时间
      this.activeUsageMap.set(permission, Date.now());
      console.info(`[PermAudit] 开始使用权限: ${permission}`);
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[PermAudit] 记录权限使用开始失败: ${err.code} - ${err.message}`);
    }
  }

  /**
   * 记录权限使用结束
   * @param tokenId 应用Token ID
   * @param permission 权限名称
   */
  async stopPermissionUsage(tokenId: number, permission: Permissions): Promise<void> {
    try {
      // 调用系统API标记权限使用结束
      await privacyManager.stopUsingPermission(tokenId, permission);
      // 计算使用时长
      const startTime = this.activeUsageMap.get(permission);
      if (startTime) {
        const duration = Date.now() - startTime;
        this.activeUsageMap.delete(permission);
        console.info(`[PermAudit] 停止使用权限: ${permission}, 持续 ${duration}ms`);
      }
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[PermAudit] 记录权限使用结束失败: ${err.code} - ${err.message}`);
    }
  }

  /**
   * 添加权限使用记录
   * @param tokenId 应用Token ID
   * @param permission 权限名称
   * @param successCount 成功次数
   * @param failCount 失败次数
   */
  async addUsageRecord(
    tokenId: number,
    permission: Permissions,
    successCount: number,
    failCount: number
  ): Promise<void> {
    try {
      await privacyManager.addPermissionUsedRecord(
        tokenId,
        permission,
        successCount,
        failCount
      );
      console.info(`[PermAudit] 添加使用记录: ${permission}, 成功${successCount}次, 失败${failCount}次`);
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[PermAudit] 添加使用记录失败: ${err.code} - ${err.message}`);
    }
  }

  /**
   * 查询权限使用记录
   * @param queryOption 查询选项
   * @returns 审计记录列表
   */
  async queryUsageRecords(
    queryOption: privacyManager.PermissionUsedRequest
  ): Promise<AuditRecordEntry[]> {
    try {
      const result = await privacyManager.getPermissionUsedRecord(queryOption);
      const records: AuditRecordEntry[] = [];

      if (result && result.record) {
        for (const item of result.record) {
          // 计算风险等级
          const riskLevel = this.calculateRiskLevel(item);

          records.push({
            permissionName: item.permissionName,
            bundleName: item.bundleName || 'unknown',
            accessCount: item.accessCount,
            rejectCount: item.rejectCount,
            lastAccessTime: this.formatTimestamp(item.lastAccessTime),
            lastRejectTime: this.formatTimestamp(item.lastRejectTime),
            lastAccessDuration: this.formatDuration(item.lastAccessDuration),
            riskLevel
          });
        }
      }

      return records;
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[PermAudit] 查询使用记录失败: ${err.code} - ${err.message}`);
      return [];
    }
  }

  /**
   * 生成审计统计摘要
   * @param records 审计记录列表
   * @returns 统计摘要
   */
  generateSummary(records: AuditRecordEntry[]): AuditSummary {
    const totalAccessCount = records.reduce((sum, r) => sum + r.accessCount, 0);
    const totalRejectCount = records.reduce((sum, r) => sum + r.rejectCount, 0);
    const highRiskCount = records.filter(r => r.riskLevel === 'high').length;

    // 找出最常用和最少用的权限
    let mostUsed = records[0]?.permissionName || 'N/A';
    let leastUsed = records[0]?.permissionName || 'N/A';
    let maxAccess = 0;
    let minAccess = Infinity;

    for (const record of records) {
      if (record.accessCount > maxAccess) {
        maxAccess = record.accessCount;
        mostUsed = record.permissionName;
      }
      if (record.accessCount < minAccess) {
        minAccess = record.accessCount;
        leastUsed = record.permissionName;
      }
    }

    return {
      totalPermissions: records.length,
      totalAccessCount,
      totalRejectCount,
      highRiskCount,
      mostUsedPermission: mostUsed,
      leastUsedPermission: leastUsed,
      auditPeriod: `${records.length > 0 ? records[0].lastAccessTime : 'N/A'} ~ ${records.length > 0 ? records[records.length - 1].lastAccessTime : 'N/A'}`
    };
  }

  /**
   * 执行合规性检查
   * @param records 审计记录
   * @param declaredPermissions 已声明的权限列表
   * @returns 合规检查结果
   */
  performComplianceCheck(
    records: AuditRecordEntry[],
    declaredPermissions: string[]
  ): ComplianceCheckResult {
    const issues: ComplianceCheckResult['issues'] = [];

    // 检查1：是否有使用但未声明的权限
    for (const record of records) {
      if (!declaredPermissions.includes(record.permissionName)) {
        issues.push({
          permission: record.permissionName,
          issue: '权限被使用但未在module.json5中声明',
          severity: 'error',
          suggestion: '请在requestPermissions中声明该权限，或停止使用该权限'
        });
      }
    }

    // 检查2：拒绝率过高的权限
    for (const record of records) {
      const totalAttempts = record.accessCount + record.rejectCount;
      if (totalAttempts > 0) {
        const rejectRate = record.rejectCount / totalAttempts;
        if (rejectRate > 0.5) {
          issues.push({
            permission: record.permissionName,
            issue: `权限拒绝率过高 (${(rejectRate * 100).toFixed(1)}%)，用户可能不理解权限用途`,
            severity: 'warning',
            suggestion: '优化权限申请时机和rationale说明，确保用户理解权限用途'
          });
        }
      }
    }

    // 检查3：高风险权限的访问频率
    for (const record of records) {
      if (record.riskLevel === 'high' && record.accessCount > 100) {
        issues.push({
          permission: record.permissionName,
          issue: `高风险权限访问频率异常 (${record.accessCount}次)`,
          severity: 'warning',
          suggestion: '检查是否存在不必要的频繁权限访问，考虑缓存或批量处理'
        });
      }
    }

    // 检查4：声明但从未使用的权限
    const usedPermissions = records.map(r => r.permissionName);
    for (const declared of declaredPermissions) {
      if (!usedPermissions.includes(declared)) {
        issues.push({
          permission: declared,
          issue: '权限已声明但从未使用',
          severity: 'warning',
          suggestion: '移除未使用的权限声明，遵循最小权限原则'
        });
      }
    }

    return {
      isCompliant: issues.filter(i => i.severity === 'error').length === 0,
      issues,
      checkTime: new Date().toISOString()
    };
  }

  /**
   * 计算权限风险等级
   */
  private calculateRiskLevel(record: privacyManager.PermissionUsedRecord): 'low' | 'medium' | 'high' {
    // 高敏感权限列表
    const highSensitivePerms = [
      'ohos.permission.CAMERA',
      'ohos.permission.MICROPHONE',
      'ohos.permission.LOCATION',
      'ohos.permission.READ_CONTACTS',
      'ohos.permission.READ_CALENDAR'
    ];

    // 中敏感权限列表
    const mediumSensitivePerms = [
      'ohos.permission.READ_MEDIA',
      'ohos.permission.APPROXIMATELY_LOCATION',
      'ohos.permission.ACCESS_BLUETOOTH'
    ];

    if (highSensitivePerms.includes(record.permissionName)) {
      return 'high';
    } else if (mediumSensitivePerms.includes(record.permissionName)) {
      return 'medium';
    }
    return 'low';
  }

  /**
   * 格式化时间戳
   */
  private formatTimestamp(timestamp: number): string {
    if (timestamp === 0) return 'N/A';
    const date = new Date(timestamp);
    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')} ${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}:${String(date.getSeconds()).padStart(2, '0')}`;
  }

  /**
   * 格式化持续时间
   */
  private formatDuration(durationMs: number): string {
    if (durationMs === 0) return 'N/A';
    if (durationMs < 1000) return `${durationMs}ms`;
    if (durationMs < 60000) return `${(durationMs / 1000).toFixed(1)}s`;
    return `${(durationMs / 60000).toFixed(1)}min`;
  }
}

示例2：敏感API调用追踪装饰器

使用装饰器模式，自动追踪敏感 API 的调用，记录调用上下文、参数和耗时：

// utils/SensitiveApiTracker.ets - 敏感API调用追踪器
import { common } from '@kit.AbilityKit';

// API调用记录
interface ApiCallRecord {
  apiName: string;               // API名称
  permission: string;            // 关联的权限
  timestamp: string;             // 调用时间
  duration: number;              // 调用耗时(ms)
  success: boolean;              // 是否成功
  errorMessage?: string;         // 错误信息
  callerInfo: string;            // 调用者信息
}

// 敏感API配置
interface SensitiveApiConfig {
  apiName: string;               // API名称
  permission: string;            // 关联的权限
  description: string;           // API描述
  riskLevel: 'low' | 'medium' | 'high';  // 风险等级
}

export class SensitiveApiTracker {
  // 调用记录存储
  private static records: ApiCallRecord[] = [];
  // 最大记录数
  private static readonly MAX_RECORDS = 1000;

  // 敏感API配置表
  private static readonly API_CONFIGS: SensitiveApiConfig[] = [
    {
      apiName: 'camera.takePhoto',
      permission: 'ohos.permission.CAMERA',
      description: '拍摄照片',
      riskLevel: 'high'
    },
    {
      apiName: 'geolocation.getCurrentLocation',
      permission: 'ohos.permission.LOCATION',
      description: '获取当前位置',
      riskLevel: 'high'
    },
    {
      apiName: 'media.readMedia',
      permission: 'ohos.permission.READ_MEDIA',
      description: '读取媒体文件',
      riskLevel: 'medium'
    },
    {
      apiName: 'contacts.queryContacts',
      permission: 'ohos.permission.READ_CONTACTS',
      description: '查询联系人',
      riskLevel: 'high'
    },
    {
      apiName: 'microphone.startRecording',
      permission: 'ohos.permission.MICROPHONE',
      description: '开始录音',
      riskLevel: 'high'
    }
  ];

  /**
   * 记录API调用
   * @param apiName API名称
   * @param permission 关联权限
   * @param success 是否成功
   * @param duration 耗时
   * @param errorMessage 错误信息
   */
  static recordCall(
    apiName: string,
    permission: string,
    success: boolean,
    duration: number,
    errorMessage?: string
  ): void {
    const record: ApiCallRecord = {
      apiName,
      permission,
      timestamp: new Date().toISOString(),
      duration,
      success,
      errorMessage,
      callerInfo: SensitiveApiTracker.getCallerInfo()
    };

    // 添加记录
    SensitiveApiTracker.records.push(record);

    // 超过最大记录数时，移除最旧的记录
    if (SensitiveApiTracker.records.length > SensitiveApiTracker.MAX_RECORDS) {
      SensitiveApiTracker.records.shift();
    }

    // 实时日志输出
    const statusIcon = success ? '✅' : '❌';
    console.info(
      `[ApiTracker] ${statusIcon} ${apiName} | 权限: ${permission} | 耗时: ${duration}ms${errorMessage ? ' | 错误: ' + errorMessage : ''}`
    );
  }

  /**
   * 获取所有调用记录
   */
  static getRecords(): ApiCallRecord[] {
    return [...SensitiveApiTracker.records];
  }

  /**
   * 按API名称筛选记录
   */
  static getRecordsByApi(apiName: string): ApiCallRecord[] {
    return SensitiveApiTracker.records.filter(r => r.apiName === apiName);
  }

  /**
   * 按权限筛选记录
   */
  static getRecordsByPermission(permission: string): ApiCallRecord[] {
    return SensitiveApiTracker.records.filter(r => r.permission === permission);
  }

  /**
   * 获取API调用统计
   */
  static getStatistics(): Array<{
    apiName: string;
    totalCalls: number;
    successCalls: number;
    failCalls: number;
    avgDuration: number;
    successRate: number;
  }> {
    const apiMap = new Map<string, { total: number; success: number; fail: number; totalDuration: number }>();

    for (const record of SensitiveApiTracker.records) {
      if (!apiMap.has(record.apiName)) {
        apiMap.set(record.apiName, { total: 0, success: 0, fail: 0, totalDuration: 0 });
      }
      const stats = apiMap.get(record.apiName)!;
      stats.total++;
      stats.totalDuration += record.duration;
      if (record.success) {
        stats.success++;
      } else {
        stats.fail++;
      }
    }

    const results: Array<{
      apiName: string;
      totalCalls: number;
      successCalls: number;
      failCalls: number;
      avgDuration: number;
      successRate: number;
    }> = [];

    for (const [apiName, stats] of apiMap) {
      results.push({
        apiName,
        totalCalls: stats.total,
        successCalls: stats.success,
        failCalls: stats.fail,
        avgDuration: stats.total > 0 ? Math.round(stats.totalDuration / stats.total) : 0,
        successRate: stats.total > 0 ? Math.round((stats.success / stats.total) * 100) : 0
      });
    }

    return results;
  }

  /**
   * 获取敏感API配置
   */
  static getApiConfigs(): SensitiveApiConfig[] {
    return [...SensitiveApiTracker.API_CONFIGS];
  }

  /**
   * 清除所有记录
   */
  static clearRecords(): void {
    SensitiveApiTracker.records = [];
  }

  /**
   * 获取调用者信息（简化版）
   */
  private static getCallerInfo(): string {
    // 在实际应用中，可以通过 Error.stack 获取调用栈
    return 'app_component';
  }
}

/**
 * 敏感API调用追踪包装函数
 * 用于包装需要追踪的API调用
 * @param apiName API名称
 * @param permission 关联权限
 * @param apiCall 实际的API调用函数
 * @returns API调用结果
 */
export async function trackSensitiveApi<T>(
  apiName: string,
  permission: string,
  apiCall: () => Promise<T>
): Promise<T> {
  const startTime = Date.now();
  let success = false;
  let errorMessage: string | undefined;

  try {
    const result = await apiCall();
    success = true;
    return result;
  } catch (error) {
    const err = error as BusinessError;
    errorMessage = `${err.code}: ${err.message}`;
    throw error;
  } finally {
    const duration = Date.now() - startTime;
    SensitiveApiTracker.recordCall(apiName, permission, success, duration, errorMessage);
  }
}

使用追踪包装函数的示例：

// 在业务代码中使用追踪包装
import { trackSensitiveApi } from '../utils/SensitiveApiTracker';
import { geoLocationManager } from '@kit.LocationKit';
import { camera } from '@kit.CameraKit';

// 追踪位置获取
async function getTrackedLocation() {
  return trackSensitiveApi(
    'geolocation.getCurrentLocation',
    'ohos.permission.LOCATION',
    async () => {
      const locationManager = geoLocationManager.getSystemLocationManager();
      const location = await locationManager.getCurrentLocation({
        priority: geoLocationManager.LocationRequestPriority.FIRST_FIX,
        scenario: geoLocationManager.LocationRequestScenario.UNSET
      });
      return location;
    }
  );
}

示例3：权限审计仪表盘页面

创建一个可视化的权限审计仪表盘，展示权限使用记录、合规检查结果和敏感API统计：

// pages/PermissionAuditPage.ets - 权限审计仪表盘
import { privacyManager, bundleManager, Permissions } from '@kit.AbilityKit';
import { PermissionAuditManager, AuditRecordEntry, ComplianceCheckResult } from '../utils/PermissionAuditManager';
import { SensitiveApiTracker } from '../utils/SensitiveApiTracker';

@Entry
@Component
struct PermissionAuditPage {
  // 审计管理器
  private auditManager: PermissionAuditManager = new PermissionAuditManager();
  // 审计记录
  @State auditRecords: AuditRecordEntry[] = [];
  // 合规检查结果
  @State complianceResult: ComplianceCheckResult | null = null;
  // API调用统计
  @State apiStatistics: Array<{
    apiName: string;
    totalCalls: number;
    successCalls: number;
    failCalls: number;
    avgDuration: number;
    successRate: number;
  }> = [];
  // 加载状态
  @State isLoading: boolean = true;
  // 当前选中的Tab
  @State currentTab: number = 0;
  // 已声明权限列表
  private declaredPermissions: string[] = [
    'ohos.permission.INTERNET',
    'ohos.permission.CAMERA',
    'ohos.permission.LOCATION',
    'ohos.permission.APPROXIMATELY_LOCATION',
    'ohos.permission.READ_MEDIA',
    'ohos.permission.MICROPHONE'
  ];

  async aboutToAppear() {
    await this.loadAuditData();
  }

  /**
   * 加载审计数据
   */
  private async loadAuditData(): Promise<void> {
    try {
      // 获取本应用的Token ID
      const bundleInfo = await bundleManager.getBundleInfoForSelf(
        bundleManager.BundleFlag.GET_BUNDLE_INFO_DEFAULT
      );
      const tokenId = bundleInfo.appInfo.accessTokenId;

      // 查询权限使用记录
      const queryOption: privacyManager.PermissionUsedRequest = {
        tokenId: tokenId,
        allFlag: 1  // 查询所有记录
      };

      this.auditRecords = await this.auditManager.queryUsageRecords(queryOption);

      // 执行合规性检查
      this.complianceResult = this.auditManager.performComplianceCheck(
        this.auditRecords,
        this.declaredPermissions
      );

      // 获取API调用统计
      this.apiStatistics = SensitiveApiTracker.getStatistics();

      this.isLoading = false;
    } catch (error) {
      console.error('[AuditPage] 加载审计数据失败: ' + JSON.stringify(error));
      this.isLoading = false;
    }
  }

  build() {
    Column() {
      // 标题
      Text('权限审计仪表盘')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 20, bottom: 16 })

      // Tab切换
      Tabs({ index: this.currentTab }) {
        TabContent() {
          this.RecordsTab()
        }.tabBar('使用记录')

        TabContent() {
          this.ComplianceTab()
        }.tabBar('合规检查')

        TabContent() {
          this.ApiStatsTab()
        }.tabBar('API统计')
      }
      .width('100%')
      .layoutWeight(1)
      .barMode(BarMode.Fixed)
      .onChange((index: number) => {
        this.currentTab = index;
      })

      // 底部刷新按钮
      Button('🔄 刷新数据')
        .width('80%')
        .height(44)
        .fontSize(16)
        .backgroundColor('#4CAF50')
        .fontColor(Color.White)
        .borderRadius(22)
        .margin({ top: 12, bottom: 20 })
        .onClick(() => {
          this.isLoading = true;
          this.loadAuditData();
        })
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }

  /**
   * 使用记录Tab
   */
  @Builder
  RecordsTab() {
    if (this.isLoading) {
      LoadingProgress().width(48).height(48).color('#4CAF50')
    } else if (this.auditRecords.length === 0) {
      Column() {
        Text('📋 暂无权限使用记录')
          .fontSize(16)
          .fontColor('#999999')
          .margin({ top: 60 })
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Start)
    } else {
      List({ space: 10 }) {
        ForEach(this.auditRecords, (record: AuditRecordEntry) => {
          ListItem() {
            this.RecordCardBuilder(record)
          }
        }, (record: AuditRecordEntry) => record.permissionName)

        // 统计摘要
        ListItem() {
          this.SummaryCardBuilder()
        }
      }
      .width('100%')
      .padding({ left: 16, right: 16, top: 12 })
    }
  }

  /**
   * 单条记录卡片
   */
  @Builder
  RecordCardBuilder(record: AuditRecordEntry) {
    Column() {
      Row() {
        // 风险等级指示器
        Circle({ width: 10, height: 10 })
          .fill(record.riskLevel === 'high' ? '#F44336' : record.riskLevel === 'medium' ? '#FF9800' : '#4CAF50')
          .margin({ right: 8 })

        // 权限名称
        Text(record.permissionName.replace('ohos.permission.', ''))
          .fontSize(15)
          .fontWeight(FontWeight.Medium)
          .layoutWeight(1)

        // 风险标签
        Text(record.riskLevel === 'high' ? '高风险' : record.riskLevel === 'medium' ? '中风险' : '低风险')
          .fontSize(11)
          .fontColor(Color.White)
          .backgroundColor(record.riskLevel === 'high' ? '#F44336' : record.riskLevel === 'medium' ? '#FF9800' : '#4CAF50')
          .borderRadius(4)
          .padding({ left: 6, right: 6, top: 2, bottom: 2 })
      }

      // 详细数据
      Row({ space: 16 }) {
        Column() {
          Text('访问次数')
            .fontSize(11)
            .fontColor('#999999')
          Text(`${record.accessCount}`)
            .fontSize(16)
            .fontWeight(FontWeight.Bold)
            .fontColor('#4CAF50')
        }

        Column() {
          Text('拒绝次数')
            .fontSize(11)
            .fontColor('#999999')
          Text(`${record.rejectCount}`)
            .fontSize(16)
            .fontWeight(FontWeight.Bold)
            .fontColor('#F44336')
        }

        Column() {
          Text('最近访问')
            .fontSize(11)
            .fontColor('#999999')
          Text(record.lastAccessTime.split(' ')[1] || 'N/A')
            .fontSize(13)
            .fontColor('#333333')
        }

        Column() {
          Text('持续时长')
            .fontSize(11)
            .fontColor('#999999')
          Text(record.lastAccessDuration)
            .fontSize(13)
            .fontColor('#333333')
        }
      }
      .width('100%')
      .margin({ top: 12 })
    }
    .width('100%')
    .padding(16)
    .backgroundColor(Color.White)
    .borderRadius(12)
    .shadow({ radius: 2, color: '#1A000000', offsetY: 1 })
  }

  /**
   * 统计摘要卡片
   */
  @Builder
  SummaryCardBuilder() {
    Column() {
      Text('📊 审计摘要')
        .fontSize(16)
        .fontWeight(FontWeight.Medium)
        .margin({ bottom: 12 })

      const summary = this.auditManager.generateSummary(this.auditRecords);

      Row({ space: 12 }) {
        this.SummaryItemBuilder('权限总数', `${summary.totalPermissions}`, '#2196F3')
        this.SummaryItemBuilder('总访问', `${summary.totalAccessCount}`, '#4CAF50')
        this.SummaryItemBuilder('总拒绝', `${summary.totalRejectCount}`, '#F44336')
        this.SummaryItemBuilder('高风险', `${summary.highRiskCount}`, '#FF9800')
      }
      .width('100%')
    }
    .width('100%')
    .padding(16)
    .backgroundColor(Color.White)
    .borderRadius(12)
    .shadow({ radius: 2, color: '#1A000000', offsetY: 1 })
  }

  @Builder
  SummaryItemBuilder(label: string, value: string, color: string) {
    Column() {
      Text(value)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .fontColor(color)
      Text(label)
        .fontSize(11)
        .fontColor('#999999')
        .margin({ top: 4 })
    }
    .layoutWeight(1)
    .alignItems(HorizontalAlign.Center)
  }

  /**
   * 合规检查Tab
   */
  @Builder
  ComplianceTab() {
    if (!this.complianceResult) {
      Column() {
        Text('⏳ 等待合规检查...')
          .fontSize(16)
          .fontColor('#999999')
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    } else {
      Scroll() {
        Column({ space: 12 }) {
          // 合规状态大卡片
          Column() {
            Text(this.complianceResult.isCompliant ? '✅ 合规通过' : '⚠️ 存在合规风险')
              .fontSize(22)
              .fontWeight(FontWeight.Bold)
              .fontColor(this.complianceResult.isCompliant ? '#4CAF50' : '#F44336')
              .margin({ bottom: 8 })

            Text(`检查时间: ${this.complianceResult.checkTime}`)
              .fontSize(13)
              .fontColor('#999999')

            Text(`发现问题: ${this.complianceResult.issues.length} 项`)
              .fontSize(14)
              .fontColor('#333333')
              .margin({ top: 8 })
          }
          .width('100%')
          .padding(20)
          .backgroundColor(Color.White)
          .borderRadius(12)
          .shadow({ radius: 2, color: '#1A000000', offsetY: 1 })

          // 问题列表
          if (this.complianceResult.issues.length > 0) {
            Text('问题详情')
              .fontSize(16)
              .fontWeight(FontWeight.Medium)
              .margin({ top: 8 })

            ForEach(this.complianceResult.issues, (issue: ComplianceCheckResult['issues'][0], index: number) => {
              Column() {
                Row() {
                  Text(issue.severity === 'error' ? '🔴' : '🟡')
                    .fontSize(16)
                    .margin({ right: 8 })

                  Text(issue.permission.replace('ohos.permission.', ''))
                    .fontSize(14)
                    .fontWeight(FontWeight.Medium)
                    .layoutWeight(1)

                  Text(issue.severity === 'error' ? '严重' : '警告')
                    .fontSize(11)
                    .fontColor(Color.White)
                    .backgroundColor(issue.severity === 'error' ? '#F44336' : '#FF9800')
                    .borderRadius(4)
                    .padding({ left: 6, right: 6, top: 2, bottom: 2 })
                }

                Text(issue.issue)
                  .fontSize(13)
                  .fontColor('#333333')
                  .margin({ top: 8, left: 24 })

                Row() {
                  Text('💡 建议: ')
                    .fontSize(12)
                    .fontColor('#666666')
                  Text(issue.suggestion)
                    .fontSize(12)
                    .fontColor('#2196F3')
                    .layoutWeight(1)
                }
                .margin({ top: 6, left: 24 })
              }
              .width('100%')
              .padding(14)
              .backgroundColor(Color.White)
              .borderRadius(10)
              .shadow({ radius: 1, color: '#1A000000', offsetY: 1 })
            }, (issue: ComplianceCheckResult['issues'][0], index: number) => `${index}`)
          } else {
            Column() {
              Text('🎉 没有发现合规问题')
                .fontSize(16)
                .fontColor('#4CAF50')
            }
            .width('100%')
            .padding(20)
            .backgroundColor(Color.White)
            .borderRadius(12)
          }
        }
        .padding({ left: 16, right: 16, top: 12 })
      }
    }
  }

  /**
   * API统计Tab
   */
  @Builder
  ApiStatsTab() {
    if (this.apiStatistics.length === 0) {
      Column() {
        Text('📊 暂无API调用统计')
          .fontSize(16)
          .fontColor('#999999')
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    } else {
      List({ space: 10 }) {
        ForEach(this.apiStatistics, (stat: typeof this.apiStatistics[0]) => {
          ListItem() {
            Column() {
              Row() {
                Text(stat.apiName)
                  .fontSize(15)
                  .fontWeight(FontWeight.Medium)
                  .layoutWeight(1)

                Text(`成功率 ${stat.successRate}%`)
                  .fontSize(13)
                  .fontColor(stat.successRate >= 90 ? '#4CAF50' : stat.successRate >= 70 ? '#FF9800' : '#F44336')
              }

              // 统计数据行
              Row({ space: 20 }) {
                Column() {
                  Text('总调用')
                    .fontSize(11)
                    .fontColor('#999999')
                  Text(`${stat.totalCalls}`)
                    .fontSize(15)
                    .fontWeight(FontWeight.Bold)
                }

                Column() {
                  Text('成功')
                    .fontSize(11)
                    .fontColor('#999999')
                  Text(`${stat.successCalls}`)
                    .fontSize(15)
                    .fontWeight(FontWeight.Bold)
                    .fontColor('#4CAF50')
                }

                Column() {
                  Text('失败')
                    .fontSize(11)
                    .fontColor('#999999')
                  Text(`${stat.failCalls}`)
                    .fontSize(15)
                    .fontWeight(FontWeight.Bold)
                    .fontColor('#F44336')
                }

                Column() {
                  Text('平均耗时')
                    .fontSize(11)
                    .fontColor('#999999')
                  Text(`${stat.avgDuration}ms`)
                    .fontSize(15)
                    .fontWeight(FontWeight.Bold)
                    .fontColor('#2196F3')
                }
              }
              .width('100%')
              .margin({ top: 10 })
            }
            .width('100%')
            .padding(14)
            .backgroundColor(Color.White)
            .borderRadius(10)
            .shadow({ radius: 1, color: '#1A000000', offsetY: 1 })
          }
        }, (stat: typeof this.apiStatistics[0]) => stat.apiName)
      }
      .width('100%')
      .padding({ left: 16, right: 16, top: 12 })
    }
  }
}

四、踩坑与注意事项

坑1：privacyManager API 权限要求

现象：调用 getPermissionUsedRecord 时抛出权限不足错误。

原因：@ohos.privacyManager 的部分 API 需要系统签名或特殊权限才能调用。普通三方应用可能无法直接使用所有方法。

解决方案：

• addPermissionUsedRecord：应用可自行调用，记录自己的权限使用
• getPermissionUsedRecord：需要系统签名，三方应用只能查询自己的记录
• startUsingPermission / stopUsingPermission：应用可自行调用

坑2：权限使用记录的时间范围限制

现象：查询权限使用记录时，返回的结果为空，明明应用使用过权限。

原因：系统对权限使用记录有保留期限，超过一定时间（通常7天）的记录会被自动清除。

解决方案：如果需要长期保存审计记录，应该在获取到记录后自行持久化存储（如数据库或文件）。

坑3：startUsingPermission 和 stopUsingPermission 必须配对

现象：调用了 startUsingPermission 但忘记调用 stopUsingPermission，导致系统认为权限一直在使用，状态栏指示灯一直亮着。

原因：这两个方法必须严格配对调用，就像文件打开后必须关闭一样。

解决方案：使用 try-finally 确保配对调用：

// ✅ 正确：使用 try-finally 确保配对
async function usePermissionSafely(tokenId: number, permission: Permissions) {
  await privacyManager.startUsingPermission(tokenId, permission);
  try {
    // 执行需要权限的操作
    await doSomethingWithPermission();
  } finally {
    // 无论成功还是失败，都要停止使用
    await privacyManager.stopUsingPermission(tokenId, permission);
  }
}

坑4：审计日志的性能影响

现象：在频繁调用敏感 API 的场景下，每次调用都记录审计日志，导致性能明显下降。

原因：审计日志的写入是 IO 操作，高频调用会产生性能开销。

解决方案：

• 对于高频操作，采用批量记录策略，积累一定数量后一次性写入
• 使用内存缓存 + 定时刷盘的策略
• 在 Release 模式下降低审计频率，Debug 模式下全量审计

// 批量记录策略
class BatchAuditRecorder {
  private buffer: ApiCallRecord[] = [];
  private readonly FLUSH_THRESHOLD = 50; // 50条记录刷盘一次

  record(record: ApiCallRecord): void {
    this.buffer.push(record);
    if (this.buffer.length >= this.FLUSH_THRESHOLD) {
      this.flush();
    }
  }

  flush(): void {
    if (this.buffer.length === 0) return;
    // 批量写入
    const records = [...this.buffer];
    this.buffer = [];
    // 写入持久化存储...
  }
}

坑5：合规检查的"已声明但未使用"误判

现象：合规检查报告说某个权限"已声明但从未使用"，但实际上该权限是功能必需的，只是用户还没触发相关功能。

原因：合规检查基于历史使用记录，如果用户从未使用过相关功能，记录中自然没有该权限的使用数据。

解决方案：合规检查结果需要结合业务场景判断。"已声明但未使用"只是一个提示，不代表一定要移除。对于功能必需但使用频率低的权限，可以在合规报告中添加备注说明。

五、HarmonyOS 6 适配

5.1 权限审计能力增强

5.2 新增 API

// HarmonyOS 6 新增的权限审计API

// 实时权限访问监控
privacyManager.on('permissionAccess', (data: PermissionAccessData) => {
  console.info(`权限 ${data.permissionName} 被 ${data.bundleName} 访问`);
  console.info(`访问类型: ${data.accessType}`);  // read / write / execute
  console.info(`访问时间: ${data.timestamp}`);
});

// 自动生成合规报告
const report = await privacyManager.generateComplianceReport({
  bundleName: 'com.example.myapp',
  period: 'monthly',  // daily / weekly / monthly
  includeSuggestions: true
});

// 跨设备审计记录同步
const remoteRecords = await privacyManager.getPermissionUsedRecord({
  isRemote: true,
  deviceId: 'remote_device_id',
  bundleName: 'com.example.myapp'
});

5.3 迁移建议

1. 为关键权限操作添加 startUsingPermission / stopUsingPermission 配对调用
2. 实现权限使用记录的本地持久化，避免系统记录过期后丢失
3. 集成合规性检查到 CI/CD 流程，在发布前自动检查
4. 使用 trackSensitiveApi 包装器追踪所有敏感 API 调用
5. 为 HarmonyOS 6 准备实时权限访问监控的接入

六、总结

权限审计知识图谱
├── 核心 API
│   ├── @ohos.privacyManager
│   │   ├── addPermissionUsedRecord() → 添加使用记录
│   │   ├── getPermissionUsedRecord() → 查询使用记录
│   │   ├── startUsingPermission() → 标记开始使用
│   │   ├── stopUsingPermission() → 标记停止使用
│   │   └── on('permissionStateChange') → 监听状态变化
│   └── 自定义追踪
│       ├── SensitiveApiTracker → API调用追踪
│       └── trackSensitiveApi() → 追踪包装函数
├── 审计层次
│   ├── 系统级 → 系统自动记录
│   ├── 应用级 → 自定义日志框架
│   └── API级 → 装饰器/拦截器
├── 合规检查
│   ├── 使用但未声明 → error级别
│   ├── 拒绝率过高 → warning级别
│   ├── 高频访问异常 → warning级别
│   └── 声明但未使用 → warning级别
├── 最佳实践
│   ├── start/stop 配对调用
│   ├── try-finally 确保配对
│   ├── 批量记录减少IO
│   ├── 本地持久化防丢失
│   └── CI/CD 集成自动检查
└── HarmonyOS 6 新增
    ├── API级别审计
    ├── 可配置保留期限
    ├── 实时访问监控
    ├── 自动合规报告
    └── 跨设备审计同步

核心记忆口诀：

1. 有借有还，start必stop——startUsingPermission 和 stopUsingPermission 必须配对
2. 记录在案，有据可查——所有权限使用都要留下审计记录
3. 合规先行，发布必检——每次发布前都要做合规性检查
4. 批量记录，性能优先——高频场景用批量策略减少 IO 开销
5. 本地持久，防丢防漏——系统记录有过期机制，重要数据要自己存
6. 追踪到底，链路清晰——敏感 API 调用要有完整的调用链追踪

权限审计是应用隐私保护的"最后一公里"。声明了权限、申请了权限、使用了权限，但如果没有审计记录来证明"我用得合理、用得安全"，那在用户和监管面前，你的应用依然缺乏可信度。做好权限审计，让你的应用不仅安全，而且"看起来就安全"。