feat(home-page): 首页返回登录用户门店身份

- 登录访问首页时复用或创建门店客户关系，并返回 hdId 与邀请绑定结果
- 在无效 hd 上下文下按 account 恢复门店与 mainId，保证首页配置可正常组装

API: get-home 响应新增 hdId、inviteBound 字段，并接受 inviterCustomId 参与首次关系绑定
Database: 登录用户首次访问门店首页时可能创建 xhCustom、xhHd 及分销关系数据

app-mall/controllers/HomePageConfigController.php

@@ -2,17 +2,22 @@
 
 namespace mall\controllers;
 
+use biz\shop\classes\ShopClass;
+use bizHd\custom\classes\CustomClass;
 use bizHd\homePageConfig\classes\HomePageConfigClass;
 use bizHd\homePageConfig\classes\HomePageDisplayClass;
 use bizHd\homePageConfig\classes\HomePageModuleClass;
+use bizMall\hd\classes\HdClass;
 use common\components\util;
 use mall\models\homePageConfig\GetSectionGoodsForm;
+use Yii;
 
 /**
  * 商城端首页配置读取接口
  * mallApp 通过 account(shopId) 获取配置，与 hd 管理端共用 Redis。
  * 具体的格式化/真实商品解析逻辑统一收敛在 HomePageDisplayClass，
  * 保证与 app-hd 的预览接口返回结构完全一致。
+ * 登录态会解析/创建顾客与门店的 hd 绑定，把 hdId 带回给 mallApp 缓存并拼到跳转链接。
  */
 class HomePageConfigController extends BaseController
 {
@@ -29,19 +34,44 @@ class HomePageConfigController extends BaseController
     ];
 
     /**
-     * 一次拉取首页全部模块配置，便于 mallApp 首页组装
+     * 一次拉取首页全部模块配置，便于 mallApp 首页组装。
+     * 已登录情况下，会解析当前门店的 hd 绑定：已有则直接返回 hdId，没有则建客建 hd。
      */
     public function actionGetHome()
     {
-        $mainId = intval($this->mainId);
         $shopId = intval($this->shopId);
         if ($shopId <= 0) {
             util::fail('shopId不存在');
         }
+
+        $shop = $this->shop;
+        if (empty($shop)) {
+            // BaseController 在请求 hdId 与当前用户不匹配时会清空 shop，这里按 account 重新取门店
+            $shop = ShopClass::getById($shopId, true);
+        }
+        if (empty($shop)) {
+            util::fail('无效门店');
+        }
+        $mainId = intval($this->mainId);
+        if ($mainId <= 0) {
+            $mainId = intval($shop->mainId);
+        }
         if ($mainId <= 0) {
             util::fail('mainId不存在');
         }
-        util::success(HomePageDisplayClass::buildHome($this->requireMainId(), $this->requireShopId()));
+
+        $hdId = 0;
+        $inviteBound = 0;
+        if (intval($this->userId) > 0) {
+            $resolved = $this->resolveLoggedInHd($shop, $shopId);
+            $hdId = $resolved['hdId'];
+            $inviteBound = $resolved['inviteBound'];
+        }
+
+        $re = HomePageDisplayClass::buildHome($mainId, $shopId);
+        $re['hdId'] = $hdId;
+        $re['inviteBound'] = $inviteBound;
+        util::success($re);
     }
 
     public function actionGetBanner()
@@ -96,6 +126,48 @@ class HomePageConfigController extends BaseController
         ));
     }
 
+    /**
+     * 登录态解析当前门店 hdId。
+     * 已有 xhHd（门店已绑定该顾客）则直接取 id；没有则走 CustomClass::buildRelation，
+     * 与 ShopController::actionInfo 在无 hdId 时的建客路径一致，避免首页先建客却漏掉分享拉新。
+     * @param object|null $shop 门店对象，建客时必须有
+     * @param int $shopId 门店 id（xhShop.id）
+     * @return array{hdId:int,inviteBound:int}
+     * @throws \yii\db\IntegrityException
+     */
+    private function resolveLoggedInHd($shop, $shopId)
+    {
+        $hd = HdClass::getByCondition(
+            ['shopId' => $shopId, 'userId' => $this->userId],
+            false,
+            null,
+            'id, customId'
+        );
+        if (!empty($hd)) {
+            return [
+                'hdId' => intval($hd['id']),
+                'inviteBound' => 0,
+            ];
+        }
+
+        $user = $this->user;
+        if (empty($shop) || empty($user)) {
+            return ['hdId' => 0, 'inviteBound' => 0];
+        }
+
+        $inviterCustomId = (int)Yii::$app->request->get('inviterCustomId', 0);
+        $respond = CustomClass::buildRelation($shop, $user, $inviterCustomId);
+        if (empty($respond) || empty($respond['hd'])) {
+            return ['hdId' => 0, 'inviteBound' => 0];
+        }
+
+        $hd = $respond['hd'];
+        return [
+            'hdId' => intval(is_object($hd) ? $hd->id : ($hd['id'] ?? 0)),
+            'inviteBound' => !empty($respond['inviteBound']) ? (int)$respond['inviteBound'] : 0,
+        ];
+    }
+
     private function requireMainId()
     {
         $mainId = intval($this->mainId);

biz-hd/homePageConfig/classes/HomePageDisplayClass.php

@@ -19,10 +19,10 @@ class HomePageDisplayClass
 {
     /**
      * 一次性组装首页全部模块的展示数据
-     *
      * @param int $mainId
      * @param int $shopId
      * @return array
+     * @throws \Exception
      */
     public static function buildHome($mainId, $shopId)
     {
@@ -44,10 +44,10 @@ class HomePageDisplayClass
 
     /**
      * 格式化顶部导航：门店名称不落 Redis，实时取 xhShop.merchantName
-     *
      * @param int $shopId 门店 id（xhShop.id，即 mall account）
      * @param array $data HomePageConfigClass::getTopNav 返回值
      * @return array
+     * @throws \Exception
      */
     public static function formatTopNav($shopId, $data)
     {