商城类应用从 Android 迁移到 HarmonyOS NEXT：老用户账号体系怎么平滑打通？

核心思路是后端保持以手机号作为主唯一键，华为账号一键登录只作为一种新的登录渠道，不单独生成独立用户，通过手机号关联到已有账号，不要把华为 OpenId 当成主键，前端同时保留原有手机号密码登录入口给老用户，给你个示例吧。 后端用户表在原有字段之外新增渠道关联表，存储 openId、unionId、绑定手机号、渠道类型、绑定时间，登录流程分两条分支，走华为账号一键登录时拿到授权里的手机号，优先用这个手机号去用户主表匹配，如果已经存在就直接登录，同时在渠道绑定表里记录这条华为账号和该用户的绑定关系，如果手机号在主表不存在，再走新用户注册，老用户第一次打开鸿蒙版的时候默认展示原有手机号密码登录，也提供华为账号快捷登录按钮，在用户主动授权之后再自动完成绑定，不强制拉起华为授权，避免流程突兀。 账号合并和绑定流程上，优先采用被动绑定而不是后台自动合并，自动合并很容易踩重复账号、手机号换绑、第三方绑定丢失的坑，当用户用华为账号登录匹配到已有手机号账号时，弹窗提示当前华为账号将要绑定到这个已有商城账号，用户确认之后再写入渠道绑定记录，如果遇到一个华为账号匹配到多条同手机号脏数据，就进入人工校验或者让用户选择保留哪一条，第三方登录也要统一接入这套渠道绑定表，微信、QQ 这类第三方登录同样以手机号做关联，每个渠道的绑定关系独立存储，不会因为换端丢失，还要增加解绑入口，支持用户在账号安全页解除华为账号或者其他第三方渠道的绑定。 需要留意的坑点，华为账号授权拿到的手机号存在空值或者未核验的情况，不能直接信任，优先使用经过运营商实名的绑定手机号，还要做好手机号换绑同步，一旦用户在商城里更换手机号，后端同步更新所有渠道绑定记录对应的关联手机号，鸿蒙端和安卓端共用同一套登录鉴权体系，token、刷新机制保持一致，不用为鸿蒙单独设计一套会话，版本灰度阶段可以先让一部分存量用户试跑，埋点记录绑定失败、冲突弹窗的触发数据，后期再逐步引导更多用户使用华为一键登录，不直接下线原有的账号密码登录方式，完整的链路里主用户信息只维护一份，各个登录渠道只是登录凭证，所有端最终收敛到同一个手机号对应的用户数据。

// 简化的后端渠道绑定表结构示意
CREATE TABLE user_channel_bind (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id BIGINT NOT NULL,
  channel VARCHAR(32) NOT NULL,
  open_id VARCHAR(256) NOT NULL,
  union_id VARCHAR(256),
  bind_phone VARCHAR(32),
  create_time DATETIME,
  UNIQUE KEY uk_channel_openid (channel, open_id)
);

如果业务后续需要跨设备流转、华为账号相关权益打通，可以在绑定完成之后再额外拉取华为账号的基础信息补充到用户资料，但是订单、收货地址、资产这些核心数据全部依托主用户表，依托手机号做统一收敛，官方没有强制要求接入华为账号就必须新建账号，这套方案也是不少商城应用跨安卓、鸿蒙 NEXT 迁移账号的通用实践。

结论：Android 商城迁移到 HarmonyOS NEXT，不需要迁移或重建原有账号体系。最稳妥的是继续使用 Java 后端原有的 userId，将华为账号作为新增的登录方式，绑定到老用户账号上。

对于你的项目，我建议采用：

原有手机号密码登录 + 华为账号一键登录 + 首次登录账号绑定 + 服务端统一身份管理。

特别注意：不能仅因为华为账号返回的手机号与旧账号手机号相同，就无条件自动合并两个账号。 商城涉及订单、收货地址、余额、优惠券等用户资产，还应考虑手机号二次放号、账号归属争议和风险验证。

华为 Account Kit 已提供基于 OAuth 2.0 / OpenID Connect 的一键登录能力，可在获得授权后获取手机号及 UnionID/OpenID，用于关联应用已有账号。

一、推荐的账号体系设计

不要将手机号或华为 UnionID 直接作为商城用户主键，而应保留原有的内部 userId。

建议在原有用户表之外增加独立的第三方身份绑定表：

CREATE TABLE user_identity (
    id BIGINT PRIMARY KEY,
    user_id BIGINT NOT NULL,
    provider VARCHAR(32) NOT NULL,
    provider_subject VARCHAR(255) NOT NULL,
    created_at TIMESTAMP NOT NULL,
    UNIQUE (provider, provider_subject)
);

其中：

• user_id：现有商城用户主键。

• provider：例如 HUAWEI、WECHAT。

• provider_subject：经过验证的第三方用户身份标识。

对于华为账号，可以根据应用间共享身份的实际需求选择 UnionID/OpenID，并注意其所属应用及开发者范围。多环境或多身份提供方还应明确身份标识的命名空间。

这样用户无论从 Android 还是 HarmonyOS 登录，最终访问的都是同一个商城账号。

二、老用户首次使用鸿蒙端，应该怎么登录？

推荐采用以下流程：

具体建议区分三种情况：

对于第二种情况，可以设计为：

检测到该手机号已有商城账号，验证后即可同步历史订单、优惠券和会员权益。

用户可以通过原密码、有效短信验证等方式完成身份确认；涉及高价值资产或账号风险时，应增加更严格的验证手段。

华为官方也明确提示，获取经过验证的手机号后，应用仍应根据业务场景考虑二次放号风险并增加必要的安全验证。

三、Java 后端应该怎么实现？

推荐一个统一的接口：

POST /api/auth/huawei

请求：

{
  "authorizationCode": "授权临时凭证"
}

服务端处理逻辑：

public LoginResult loginWithHuawei(String code) {

    // 1. 服务端向华为验证授权码并取得身份信息
    HuaweiIdentity identity = huaweiAuthService.verify(code);

    // 2. 优先查已有华为账号绑定关系
    User user = identityService.findUser(
        "HUAWEI",
        identity.getUnionId()
    );

    if (user != null) {
        return tokenService.login(user);
    }

    // 3. 根据经过验证的手机号查询候选老账号
    User legacyUser = userService.findByPhone(
        identity.getVerifiedPhone()
    );

    if (legacyUser != null) {
        // 返回待绑定状态，不直接合并账号
        return LoginResult.requireBinding();
    }

    // 4. 根据业务策略进入新用户注册流程
    return LoginResult.requireRegistration();
}

以上为逻辑示例，HuaweiIdentity、HuaweiAuthService、LoginResult 都是业务自定义类，不是官方 Java SDK 类型。

华为现行服务端接口支持通过 Authorization Code 获取经过验证的 UnionID、OpenID 及手机号；其中 Client Secret 必须保留在服务端。授权码只能使用一次，应避免重放。

真正执行绑定时，还需要：

• 在数据库事务中写入 user_identity 绑定关系。

• 检查该华为身份是否已被其他用户绑定。

• 对并发绑定使用唯一索引防止重复。

• 记录绑定、解绑及账号合并审计日志。

• 不把两个已有账号的订单、余额等资产直接自动合并。

如果两个完整账号已经各自拥有资产，建议将“身份绑定”和“用户资产合并”作为两个独立业务流程。

四、老用户的第三方登录怎么处理？

不要要求老用户升级到 HarmonyOS NEXT 后必须改用华为账号。

建议保留能够在新平台合规接入的原有登录方式，特别是手机号密码登录。

对于旧有第三方登录，应确认对应服务商是否提供 HarmonyOS NEXT 原生 SDK 或标准 OAuth 接入方式。不要直接假设 Android SDK 可以在 ArkTS 中运行。

原有绑定关系应继续存储在 Java 后端，而不是迁移到设备本地。用户进入鸿蒙端后，通过任意一种已绑定且可验证的方式登录，都应回到原来的 userId。

五、华为账号一键登录需要哪些条件？

这是当前接入前必须确认的内容：

• 华为账号普通登录：获取 UnionID/OpenID 的能力不需要额外申请一键登录权限。

• 华为账号一键登录：获取经过验证的手机号和 UnionID/OpenID，需要企业开发者申请相关权限。

• 该一键登录能力目前有应用类别、用户地域和服务端部署地域等限制，特别是获取绑定手机号的服务器需要部署在中国境内。

如果暂时没有获得一键登录权限，也可以先接入普通华为账号登录，通过已获授权的身份标识完成账号绑定，并保留原手机号登录。

六、商城迁移最容易踩的坑

官方参考

• 华为账号一键登录（手机号与 UnionID）

• 华为账号登录按钮接入

• 服务端通过授权码获取华为账号信息

最终建议：商城跨平台迁移应该迁移登录入口，而不是迁移用户账号。

保持 Java 后端 userId 不变，新增华为账号身份绑定表；老用户第一次通过华为账号进入时，先匹配已有账号并完成安全验证，之后就可以一键登录原账号，历史订单、购物车、会员权益都不需要重新迁移。

你这场景的核心就一件事：鸿蒙端用华为账号一键登录拿到手机号，去你现有用户表里匹配，匹配到就绑定 UnionID，匹配不到就新建。官方文档把这套流程叫"关联应用已有用户"，华为账号一键登录开发指南里有完整时序图。

问题 1：手机号打通怎么做

你的用户表以手机号为唯一标识，这就好办了。鸿蒙端一键登录能同时拿到明文手机号和 UnionID/OpenID，服务端拿手机号去用户表查，查到就在那条记录上补一个 harmony_union_id 字段，下次这个用户再打开 App 走静默登录就行，不用再弹授权。

关键一点：官方明确推荐用 UnionID/OpenID 做主标识，手机号做关联，因为华为账号可以换绑手机号。如果你只拿手机号当主键，用户换绑后就会变成"新用户"。所以你的用户表要加一个 harmony_union_id 列，登录逻辑变成：先查 UnionID → 命中则直接登录；未命中则查手机号 → 命中则绑定 UnionID；都未命中则新建。

注意一键登录只对企业开发者开放，个人开发者只能走华为账号登录 + 静默登录，见登录方式概述。

问题 2：合并流程和踩坑点

推荐的老用户首次进入鸿蒙端流程：

1. 打开 App → 预取号拿匿名手机号展示在页面上（用户看到"138***5678"就知道是自己的号，不会懵）
2. 用户点一键登录 → 拿到 Authorization Code → 传给服务端
3. 服务端用 Code 调 /oauth2/v6/quickLogin/getPhoneNumber 换取明文手机号 + UnionID
4. 查用户表：手机号命中 → 绑定 UnionID，返回 session；未命中 → 新建账号
5. 后续访问走静默登录，用 UnionID 匹配即可，用户无感

踩坑点：

• 账号绑定/解绑是你们服务端的业务逻辑，华为不管。官方 FAQ 说得很清楚：获取手机号后是否绑定由开发者自行控制
• 第三方登录绑定关系丢失的问题：你服务端需要维护一张 user_third_party_bind 表，迁移时如果用户是通过微信登录注册的，在鸿蒙端首次用华为账号登录匹配到同一手机号后，要把华为 UnionID 也绑到这条用户记录上，原有的第三方绑定不要删
• 手机号二次放号：一键登录文档里专门提了这个问题，建议在业务层加额外验证（比如让用户补填注册时留的收货地址或支付密码片段）
• 合并发并发：服务端做 UnionID 绑定时要加分布式锁，防止同一手机号在多端同时触发创建导致重复记录，跨平台账号割裂 FAQ 里有类似场景的处理方案

最小可运行示例（鸿蒙端核心登录逻辑）：

import { authentication } from '@kit.AccountKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { LoginWithHuaweiIDButton } from '@kit.AccountKit';

@Entry
@Component
struct LoginPage {
  @State anonymousPhone: string = '';
  private authController: authentication.AuthenticationController =
    new authentication.AuthenticationController();

  aboutToAppear(): void {
    this.preFetchAnonymousPhone();
  }

  private preFetchAnonymousPhone(): void {
    const request: authentication.AuthorizationWithHuaweiIDRequest =
      new authentication.AuthorizationWithHuaweiIDRequest();
    request.scopes = ['quickLoginAnonymousPhone'];
    request.forceAuthorization = false;

    this.authController.executeRequest(request).then((response: authentication.AuthorizationWithHuaweiIDResponse) => {
      if (response.quickLoginAnonymousPhone) {
        this.anonymousPhone = response.quickLoginAnonymousPhone;
      } else {
        hilog.info(0x0001, 'Login', 'anonymous phone is empty, show other login methods');
      }
    }).catch((error: BusinessError) => {
      hilog.error(0x0001, 'Login', `preFetch failed: ${error.code} - ${error.message}`);
    });
  }

  build() {
    Column({ space: 20 }) {
      if (this.anonymousPhone) {
        Text(`${this.anonymousPhone}`)
          .fontSize(18)
          .margin({ top: 60 })

        LoginWithHuaweiIDButton({
          style: authentication.LoginWithHuaweiIDButtonStyle.BUTTON_CUSTOM,
          borderRadius: 24,
          backgroundColor: Color.Black,
          fontColor: Color.White
        })
          .onClickLoginWithHuaweiIDButton((err: BusinessError, credential: authentication.HuaweiIDCredential) => {
            if (err) {
              hilog.error(0x0001, 'Login', `login failed: ${err.code}`);
              return;
            }
            const authCode: string = credential.authorizationCode;
            this.sendCodeToBackend(authCode);
          })
          .setAgreementStatus(authentication.AgreementStatus.NOT_ACCEPTED)
      } else {
        Text('手机号登录')
          .fontSize(18)
        // 展示手机号+密码的 fallback 登录方式
      }
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }

  private sendCodeToBackend(authCode: string): void {
    // 将 Authorization Code 发给服务端
    // 服务端调用 /oauth2/v6/quickLogin/getPhoneNumber 换取手机号 + UnionID
    // 服务端逻辑：
    //   1. 查 user 表手机号 → 命中 → 更新 harmony_union_id → 返回 session
    //   2. 未命中 → 新建用户 → 返回 session
    hilog.info(0x0001, 'Login', `send authCode to backend`);
  }
}

服务端伪逻辑（Java）：

// 用 Authorization Code 换取手机号和 UnionID
// POST https://oauth-login.cloud.huawei.com/oauth2/v6/quickLogin/getPhoneNumber
PhoneInfoResponse phoneInfo = huaweiAccountService.getPhoneByAuthCode(authCode);
String phone = phoneInfo.getMobileNumber();
String unionId = phoneInfo.getUnionID();

User user = userRepository.findByPhone(phone);
if (user != null) {
    // 老用户，绑定 UnionID
    user.setHarmonyUnionId(unionId);
    userRepository.save(user);
    return createSession(user);
} else {
    // 新用户
    User newUser = new User();
    newUser.setPhone(phone);
    newUser.setHarmonyUnionId(unionId);
    userRepository.save(newUser);
    return createSession(newUser);
}

总结一下：手机号是桥梁，UnionID 是锚点。首次用手机号匹配老用户并绑定 UnionID，之后全靠 UnionID 做无感登录，这套是官方推荐的模式，别反着来。

1 楼的「手机号做锚、unionID 做索引、首登即绑定」总体设计是对的，但「申请获取手机号权限后拿到手机号」这一步在商城类应用上有一个权限口径的硬门槛，另外还有一个 1 楼和 2 楼都没提、官方文档点名要防的风险：二次放号。

一、纠权限口径：商城类应用申请的是「华为账号一键登录」，不是「获取您的手机号」
1 楼写「申请获取手机号权限后，用户点一键登录你会拿到 unionID 和手机号」——Account Kit 里这是两个不同的权限：「获取您的手机号」权限按官方《申请账号权限》自检表「仅支持游戏类应用申请，其他类型应用暂不开放」，你们商城类应用申请不到；能申请的是「华为账号一键登录」权限，官方描述「支持应用获取用户的Union ID、Open ID和华为账号绑定的手机号」，适用「非游戏类应用、非银行类应用」。另一个前提和 2 楼说的一致并有原句支撑：「华为账号一键登录、获取您的手机号……仅支持企业开发者申请，不支持个人开发者申请」，且「权限申请入口目前仅对企业开发者开放，个人开发者不可见」——个人开发者只能用「华为账号登录或静默登录实现登录」，拿不到手机号，方案里的手机号映射就不成立，这点在排期时就要确认资质。

二、首登即绑定的体验预期要修正：90 天验证机制会插入短信验证
官方《华为账号一键登录(获取手机号和UnionID/OpenID)》的手机号验证机制原句：「用户点击一键登录按钮后，结合华为账号使用过程中账号所绑定的手机号短信验证记录，90天内有验证通过的记录，则返回该华为账号绑定的手机号；若90天内没有验证通过的记录，则触发Account Kit默认提供的短信验证流程（Account Kit提供的验证页，暂不可自定义），确保返回的手机号经过验证」。也就是说「点一下就拿到手机号」不是 100% 无感，部分老用户首登会被拉进一段默认短信验证页，服务端映射流程和 UI 都要兼容这个中断分支；顺带两条约束：应用需「满足《常见类型移动互联网应用程序必要个人信息范围规定》中使用手机号的必要业务场景」（网上购物类的必要业务场景是购买商品，商城满足），以及儿童账号会触发家长验密流程。

三、必须补的防呆：二次放号会把新机主映射进老账号
你们的用户表「以手机号为唯一标识」，而一键登录返回的也是华为账号绑定的手机号——一旦某个手机号被运营商二次放号给新用户，新用户用自己的华为账号一键登录，拿到的手机号会精确命中你们库里那位老用户的账号，直接登录成别人。这不是推测，官方同一页有对应要求：「应用在用户同意后获取到手机号，需要根据自身业务场景判断使用的方式，必要时增加其他安全验证手段，比如对二次放号的判断」。落到 1 楼的表设计上：user_huawei_bind 表之外，手机号命中的老账号首登不要直接发登录态，先走一次轻量校验（短信验证码或密码），校验通过再补绑 unionID；老用户找回入口（1 楼第五点）同理，验证码就是天然的二次放号防线。

四、对 1 楼方案其余部分的确认
unionID 跨应用唯一、openID 应用级、绑定幂等、冲突走人工、第三方绑定关系留在服务端——这些与官方语义一致，不重复。补充一点：一键登录「设备登录华为账号（该账号已绑定手机号）后……可不依赖设备插SIM卡」，老用户换机/无 SIM 场景可用。

说明：以上均为官方文档原文引用，未实测；权限申请审核口径以华为后台实际反馈为准。依据：《申请账号权限》 https://device.harmonyos.com/cn/docs/apiref/harmonyos-guides/account-config-permissions ；《华为账号一键登录(获取手机号和UnionID/OpenID)》 https://device.harmonyos.com/cn/docs/apiref/harmonyos-guides/account-phone-unionid-login