相机「激活」功能全链路解析
与「去掉激活」的最小改动方案（含改动前后逻辑对照）

1 · 结论先行

2 · 三个「激活状态」与状态机

排查/改造激活时最容易踩的坑：代码里存在三份互相独立的「是否已激活」，日志里必须区分打印，判断也必须按「或/与」关系组合。

连接流程状态机（PTCameraConnectMode）

enum PTCameraConnectMode: Equatable, Hashable {
    case empty
    case searching
    case connect(PTCameraConnectStep)
    case connectCompleted(PTCameraConnectError?)
    case activateState(PTCameraActivateState)   // ← 激活态独立成一档
    case setPwd(passwordType)
    case setPwdCompleted
    case upgradeSuccess
    case upgradeFail
    case locked
}

enum PTCameraActivateState: Equatable, Hashable {
    case activating
    case success
    case failed(PTCameraActivateFailure)
}

源码：Momenta/Biz/Camera/Connection/Definitions/PTCameraConnectDefines.swift · 466 行（枚举在 250 行与 365 行）

失败类型（10 种，决定 UI 分流）

enum PTCameraActivateFailedType {
    case networkUnavailable                        // 网络不可用
    case notLoggedIn                               // 未登录 → 弹强制登录层
    case activationFailed                           // 服务端业务失败
    case firmwareVersionInvalid                     // 四路固件版本空/不一致 → 引导升级
    case firmwareVersionInvalidNetworkUnavailable
    case firmwareVersionInvalidAndLowBattery
    case deviceAlreadyActivated                     // 服务端已激活（错误码 500 + "已激活"）
    case snEmpty                                    // SN 未同步完成
    case activateWIFIFailed
    case other, unknown
}

源码：PTCameraConnectDefines.swift:376-388（shouldAccumulateFailureCount 决定是否计入「激活失败次数」提示）

3 · 激活流程逐步拆解（含代码）

3.1四个入口

3.2主流程：activateDevice()

四个前置检查按顺序短路，任一失败即进入 .activateState(.failed)：

func activateDevice() {
    trackActivationStartEvent()
    updateConnectMode(.activateState(.activating))

    guard PTNetworkReachability.shared.isMobileDataAvailable else { // ① 网络（注意：判的是"移动数据"）
        updateConnectMode(.activateState(.failed(...networkUnavailable...))); return }
    guard PTUserDataManager.shared.isLoggedIn else {              // ② 登录
        updateConnectMode(.activateState(.failed(...notLoggedIn...))); return }
    guard !sn.isEmpty else { ...snEmpty...; return }                       // ③ 设备 SN
    if isActivationFirmwareVersionInvalid() { ...引导升级...; return }         // ④ 四路固件版本一致且不在强制升级清单

    // —— 服务端：先查后激活 ——
    let (isSuccess, isActivated, error) = await networkInterceptor.queryServiceActivateStatus()
    if !isActivated {
        let (ok, err) = await networkInterceptor.activateDevice(sn, mac: nil)   // POST /activate/activateDevice
        // 特殊分支：错误码 500 且 message 含"已激活" → deviceAlreadyActivated
    }
    // —— 设备侧：绑定 + 激活（这两条决定了相机内部状态）——
    let (_, isCameraLocked, isBindUser) = await userInterceptor.sendUserId(PTUserDataManager.shared.getAccountId())
    PTCameraModel.shared.isbindUser = isBindUser; PTCameraModel.shared.isCameraLocked = isCameraLocked

    if !PTCameraModel.shared.isActivated {
        let (ok, err) = await systemInterceptor.activateWIFI(PTUserDataManager.shared.getAccountId())
        // 设备回 "camera is already activated,do not need to activate again" 时按成功处理
    }
    PTCameraModel.shared.cacheServiceActivatedStatus(true)
    updateConnectMode(.activateState(.success)); trackActivationSuccessEvent()
}

源码：Momenta/Biz/Camera/Connection/Strategy/PTCameraSearchStrategySD2402+Activation.swift · 312 行（主流程 12-190 行）

3.3网络层：两个服务端调用

// ① 提交激活：PTDeviceNetWorkService.swift:427
func activateDevice(sn: String, mac: String? = nil, completion: ...) {
    let token = userDataManager.getUserToken()
    guard !token.isEmpty else { completion(.failure(.invalidToken)); return }   // 需要登录 token
    httpService.post(activateDeviceUrl, parameters: params, headers: jsonHeaders(withToken: token)) { ... }
}

// ② 查询激活态：PTDeviceNetWorkService.swift:729（含三级回落）
func queryServiceActivateStatus(completion: @escaping (Bool, String?) -> Void) {
    if !PTNetworkReachability.shared.hasInternetAccess {        // 无网 → 本地缓存 → 设备端状态 → toast
        if let cached = PTCameraModel.shared.cachedServiceActivatedStatus() { completion(cached, nil) }
        else if !PTCameraModel.shared.currentSyncDeviceInfo.info.sn.isEmpty { completion(PTCameraModel.shared.isActivated, nil) }
        else { completion(false, "当前网络异常，请稍后重试。") }
        return
    }
    let sn = resolveActivationQuerySN()                            // SN 未同步完成则不发请求（防 404 误报）
    queryActivateStatus(sn: sn) { ... PTCameraModel.shared.cacheServiceActivatedStatus(isActivated) ... }
}

源码：Momenta/DeviceManager/NetWork/PTDeviceNetWorkService.swift · 786 行（URL 常量 236-250 行）

3.4连接成功后的分流（决定「能不能进拍摄页」）

func performActivationStatusCheck(completion: @escaping (PTCameraFirmwareActivationCheckResult) -> Void) {
    PTDeviceNetWorkService.shared.queryServiceActivateStatus { isActivate, errorMessage in
        if let errorMessage { ...showToast(errorMessage); completion(.flowHandled); return }
        let mismatch = !PTCameraModel.shared.isActivated || (bleActivated == false)
        if isActivate {
            if mismatch, !PTUserDataManager.shared.isLoggedIn { completion(.activationRequired); return }  // 强制登录
            if mismatch { silentActivationSyncCoordinator?.startIfNeeded() }                            // 静默补激活
            completion(.readyForCapture)                                                                       // ← 放行
        } else {
            completion(.activationRequired)   // ← 未激活：弹 PTCameraSearchView(.connectCompleted(nil))
        }
    }
}

源码：Momenta/Biz/Camera/Connection/Managers/PTCameraConnectionFlowManager.swift · 551 行（分流结果枚举在同文件 13-22 行）

4 · 谁在消费「已激活」——门禁清单

// PTCameraSearchView.swift:959
if PTDebugToolsManager.shared.isShowActivate == false {
    logInfoEx("PTCameraSearchView：相机连接成功，调试工具设置为不显示激活界面，按相册权限决定去向")
    navigateAfterCameraConnected()
    return
}

5 · 涉及文件清单

6 · 固件侧结论：为什么不用改

固件（sd2402/qcs8550/leaptic_app @ release-1.4.0.0，实际构建入口在 sd2402/manifest：leaptic_app → qcs8550/src/quectel-app/Zhuimi_Application/src/）里，激活相关字段是纯状态上报：

// mobile/src/UserCenter.cpp:344-384（启动归一化 + 上报口径）
if (is_actived == 0) {   // 工厂态：插入/重置默认行
    INSERT OR REPLACE INTO UserInfo(ID, userid, password, is_bind, is_first_connect, is_lock, is_active, lock_time)
      VALUES(1, 'default_user', '', 0, 1, 0, 0, '');
}
...
LOG_INFO("userinfo.is_active is :%d", userinfo.is_active);
if (userinfo.is_active == 0 || userinfo.is_active == 1) {
    CameraSettingInfo::getInstance().is_activated = true;   // ← 工厂态(0)也按"已激活"上报
} else {
    CameraSettingInfo::getInstance().is_activated = false;
}

// mobile/src/Subtask.cpp:103-182（App 下发 userId 即完成"激活"）
json SubtaskHandler::handle_activate(json request) {
    ...
    userinfo.is_active = 1;
    persistActivateWithRetry(userinfo, ACTIVATE_IMMEDIATE_RETRY_MAX, dbError);  // 只落本地 sqlite
    fdclient->send_active_status(userinfo.is_active, &msg_bt);                 // 通知 App
    CameraSettingInfo::getInstance().is_activated = true;
    CAMERA_ACTIVATE(1, app_ver.c_str());                                       // 埋点
}

附：固件里唯一与云相关的默认地址是 mobile/src/cloud/https_client.cpp:1351-1353 的 https://photon-test.leaptic.tech/photon-server（云存功能的控制面基址，凭据由 App 下发），与激活无关，属需求 R1 的范围。

7 · 改动方法（逐点 before / after）

总体思路：一个开关 + 四处短路 + 保留设备侧指令。开关形态建议编译期宏（正式线零影响、可一键回滚），并提供运行时覆盖便于真机调试。

7.0新增文件：Momenta/Biz/Camera/Activation/PTActivationBypass.swift

import Foundation

/// 去激活开关：开启后 App 不再要求「相机激活」，也不访问服务端激活接口。
/// 编译期：Build Settings 里为对应 Configuration 增加 SWIFT_ACTIVE_COMPILATION_CONDITIONS = PT_ACTIVATION_BYPASS
/// 运行时：启动参数 -PTActivationBypass 或 UserDefaults.standard.bool(forKey: "PTActivationBypass")（便于真机开关调试）
enum PTActivationBypass {
    static var isEnabled: Bool {
        #if PT_ACTIVATION_BYPASS
        return true
        #else
        return ProcessInfo.processInfo.arguments.contains("-PTActivationBypass")
            || UserDefaults.standard.bool(forKey: "PTActivationBypass")
        #endif
    }
    /// 设备侧激活使用的账号（内置用户），见 R1 的本地账号 fixture
    static var builtinAccountId: String {
        PTUserDataManager.shared.getAccountId()   // 未登录时由内置用户提供
    }
}

7.1改动一：激活主流程顶部短路（+Activation.swift:12）

跳过 4 项前置检查与两个服务端调用，但保留设备侧 sendUserId + activateWIFI，让相机内部绑定态与现状一致。

// BEFORE
func activateDevice() {
    trackActivationStartEvent()
    updateConnectMode(.activateState(.activating))
    guard PTNetworkReachability.shared.isMobileDataAvailable else { ... }
    guard PTUserDataManager.shared.isLoggedIn else { ... }
    ...
}

// AFTER
func activateDevice() {
    if PTActivationBypass.isEnabled {
        performBypassActivation()      // 新增：直接走成功态 + 设备侧对齐
        return
    }
    trackActivationStartEvent()
    ...
}

/// 去激活模式：不查云端、不提交激活，只做设备侧绑定/激活
private func performBypassActivation() {
    updateConnectMode(.activateState(.activating))
    Task { [weak self] in guard let self else { return }
        let account = PTActivationBypass.builtinAccountId
        let userInterceptor = PTSDKFactory.createUserCommand()
        let systemInterceptor = PTSDKFactory.createSystemCommand()
        if let (ok, locked, bound) = try? await userInterceptor.sendUserId(account), ok {
            await MainActor.run {
                PTCameraModel.shared.isbindUser = bound
                PTCameraModel.shared.isCameraLocked = locked
            }
        }
        _ = try? await systemInterceptor.activateWIFI(account)   // 相机侧 is_active=1 / is_bind=1
        await MainActor.run {
            PTCameraModel.shared.setActivatedManually(true)
            self.updateConnectMode(.activateState(.success))
        }
    }
}

7.2改动二：服务端激活状态查询短路（PTDeviceNetWorkService.swift:729）

// BEFORE
func queryServiceActivateStatus(completion: @escaping (Bool, String?) -> Void) {
    logInfoEx("查询服务器端设备是否已激活，是否有网络：\(PTNetworkReachability.shared.hasInternetAccess)")
    if !PTNetworkReachability.shared.hasInternetAccess { ... }
    ...

// AFTER（第 1 行插入）
func queryServiceActivateStatus(completion: @escaping (Bool, String?) -> Void) {
    if PTActivationBypass.isEnabled {            // 去激活：不再请求 /device/isActivated/
        completion(true, nil)
        return
    }
    logInfoEx(...)
}

连带效果：`/device/isActivated/{sn}` 不再被调用；无网时的「缓存 / 设备态 / toast」三级回落全部不再触发（也就不再有"网络异常"toast）。

7.3改动三：门禁变量恒真（PTCameraModel.swift:1454）

// BEFORE（设备信息同步时按 BLE 上报写入）
self.isActivated = info.isActivated

// AFTER
self.isActivated = PTActivationBypass.isEnabled ? true : info.isActivated

这一处是全 App 门禁的总闸：PTCameraRouter/PTFlutterCameraBridge（快速预览放行）、PTMomentDataManager（相机素材纳入）、PTCameraConnectionFlowManager（静默同步不再启动）、以及下发给 Flutter 的 isActivated 字段，全部随之变为「已激活」。PTCameraModel.setActivatedManually(_:)（同文件 :1511）是既有的手动置位接口，无需新增机制。

7.4改动四：连 WiFi 前的预查短路（PTCameraSearchStrategySD2402.swift:139）

// BEFORE
case .connect(.tryToConnectWifi):
    if !PTCameraModel.shared.isActivated {
        PTDeviceNetWorkService.shared.queryServiceActivateStatus { isActivated, errorMessage in
            // 查询失败 → 直接把连接流打成 .activateState(.failed(.networkUnavailable))
        }
    }

// AFTER（改动三之后其实已不可达，仍建议显式短路，避免"隐式依赖"）
case .connect(.tryToConnectWifi):
    if !PTActivationBypass.isEnabled, !PTCameraModel.shared.isActivated { ...原逻辑... }

7.5不改的部分（保持最小 diff）

• UI：PTCameraActivateFailedView/UnLoginView/FailCounter/PTUnActivate* 全部保留——短路后这些分支不可达，删除只会扩大回归面。
• 枚举与文案：PTCameraActivateFailedType、L10n.connectActiveFailed 等保留。
• 埋点：PTActivationAnalytics 的激活漏斗事件保留代码（去激活模式不再产生事件；如需继续观测可后续再加本地上报）。
• 设备侧两条指令的调用点签名（PTUserService.sendUserId / PTSystemService.activateWIFI）不动。

8 · 改动后的逻辑（时序对照）

对照要点：网络请求少 1～2 次（每次连接成功省一次 /isActivated/，未激活时再省一次 /activate/activateDevice）；设备侧指令一条不少，因此相机内部状态、后续"忘记密码/解绑/换绑"等依赖绑定态的流程行为与现状一致。

9 · 影响面、风险与验证清单

验证清单（建议按序执行）

1. 编译：开启 PT_ACTIVATION_BYPASS 的配置能出包；关闭时 diff 行为为零（同一提交两个产物对比）。
2. 模拟器：进连接页不发起 /isActivated/、/activate/activateDevice（抓包或日志确认）。
3. 真机·未激活相机：连接成功后直接进预览/拍摄；不出现激活页/强制登录层；日志应出现 [PTCameraConnectionFlowManager] 相机已激活，可以跳转拍摄页面。
4. 设备侧副作用：连上后相机设置页能看到绑定账号=内置账号；is_bind/is_active 为真（BLE 上报或调试页确认）。
5. 存量已激活相机：行为与改动前一致（不回归）。
6. 断网场景：飞行模式/无网下连接相机，不再出现"网络异常"toast，也不卡在激活页。
7. Moment/相册：连接相机后 PTMomentDataManager 是否纳入相机素材（预期纳入）。

10 · 判断与待确认

待确认（发版前需要用户决定）

1. 生效范围：仅离线版（开关控制）还是所有版本（直接改逻辑）？
2. 未激活先升级：整条去掉，还是保留（新逻辑下不可达）并在设置页提供升级入口？
3. 埋点：激活漏斗是否需要在去激活模式下换成"本地日志/替代事件"？
4. 内置账号：确认使用"内置用户"的账号 ID 与昵称（用于相机侧绑定展示）。