# H2b 首页 feed 真接入 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 把 `h5/home/index.html` 写死的 mock feed 换成真实 `/api/v1/meituan/*` 数据,三排序 tab 接通、「抢」拉起美团,对齐原生 `HomeViewModel`/`HomeScreen` 全功能。

**Architecture:** 纯前端 feed 模块(裸 `fetch` 同源相对 `/api/v1`)按 `CouponCard` 渲染进现有 `.feed-card` 标记;`rec`/`distance`→`/meituan/feed`,`sales`→`/meituan/top-sales`,「抢」→`/meituan/referral-link`→`SGBridge.openMeituan`。坐标由新增 `SGBridge.getLocation()` 提供(安卓取 FusedLocation,拿不到落北京默认)。后端零改动。

**Tech Stack:** 原生 ES5 风格 JS(对齐 home 现有写法)+ FastAPI StaticFiles + pytest(TestClient 内容冒烟)+ Kotlin(安卓 SGBridge / WebViewScreen)。

**测试说明(本仓约定):** 本仓**无 JS 单测框架**;H5 的既有测试是 `tests/test_h5_hosting.py` 的**服务端内容冒烟**(断言 StaticFiles 下发的 HTML/JS 含关键标记 + 响应头)。故本计划:① 用 pytest 内容冒烟做可自动化的回归护栏(test-first);② feed 的**运行时行为**(渲染/翻页/三态/抢)用**浏览器手动验证**步骤(无桥→mock 北京)逐项核对;③ 安卓改动用**编译 + 真机**验证。这是与本仓现状一致的取舍,非偷懒。

**参考源(原生权威实现):**
- `shaguabijia-app-android` `ui/home/HomeViewModel.kt`(tab 映射 / 翻页 / 缓存 / 竞态 / getReferralLink)
- `ui/home/HomeScreen.kt:1694`(`FeedCard` 渲染)、`:615`(抢点击)、`:421`(FusedLocation lastLocation)
- 后端 `app/api/v1/meituan.py` + `app/schemas/meituan.py`(`CouponCard` 字段)

---

## File Structure

| 文件 | 责任 | 改动 |
|---|---|---|
| `h5/shared/bridge.js` | SGBridge JS 桥 | 新增 `getLocation()`(查询类同步) |
| `h5/home/index.html` | 首页 H5 | 删 mock 静态卡;新增 feed 模块 `<script>`;替换排序 tab 处理器 |
| `tests/test_h5_hosting.py` | H5 托管冒烟 | 加 bridge `getLocation` + home feed 接线断言 |
| `…/ui/webview/SGBridge.kt`(安卓) | 原生桥 | 新增 `getLocation(): String` + 构造器 `locationProvider` |
| `…/ui/webview/WebViewScreen.kt`(安卓) | WebView 壳 | 取 FusedLocation lastLocation 缓存,注入 `locationProvider` |

---

## Task 1: bridge.js 新增 `getLocation()`

**Files:**
- Modify: `h5/shared/bridge.js`(查询类区 + `global.SGBridge` 导出)
- Test: `tests/test_h5_hosting.py`

- [ ] **Step 1: 写失败测试**

在 `tests/test_h5_hosting.py` 末尾追加:

```python
def test_h5_bridge_has_get_location(client) -> None:
    # H2b: 首页 feed 需经纬度, bridge 暴露同步 getLocation()(无桥 mock 北京)
    resp = client.get("/h5/shared/bridge.js")
    assert resp.status_code == 200
    body = resp.text
    assert "getLocation" in body
    assert "116.404" in body and "39.928" in body  # 浏览器 mock 北京兜底
```

- [ ] **Step 2: 跑测试确认失败**

Run: `pytest tests/test_h5_hosting.py::test_h5_bridge_has_get_location -q`
Expected: FAIL(`assert "getLocation" in body` —— 还没实现)

- [ ] **Step 3: 实现 `getLocation()`**

在 `h5/shared/bridge.js` 的 `isLocationGranted` 函数**之后**(约第 137 行 `}` 后)插入:

```javascript
  /** 取设备当前经纬度 → {longitude, latitude};原生拿不到(未授权/无缓存)返 null,浏览器无原生 mock 北京。
   *  原生侧同步返宿主缓存的 lastLocation(见 SGBridge.kt getLocation);H5 拿到 null 自行落默认坐标。 */
  function getLocation() {
    if (hasNative && native.getLocation) {
      var o = safeParse(native.getLocation(), null);
      if (o && typeof o.longitude === 'number' && typeof o.latitude === 'number') return o;
      return null;
    }
    return { longitude: 116.404, latitude: 39.928 };
  }
```

在 `global.SGBridge = { ... }` 的查询类导出里(`isLocationGranted: isLocationGranted,` 之后)加一行:

```javascript
    getLocation: getLocation,
```

- [ ] **Step 4: 跑测试确认通过**

Run: `pytest tests/test_h5_hosting.py::test_h5_bridge_has_get_location -q`
Expected: PASS

- [ ] **Step 5: 提交**

```bash
git add h5/shared/bridge.js tests/test_h5_hosting.py
git commit -m "feat(h5): SGBridge 新增 getLocation()(首页 feed 取经纬度;无桥 mock 北京)"
```

---

## Task 2: 安卓 `SGBridge.getLocation()` + WebView 注入 FusedLocation

> ⚠️ 在 **`shaguabijia-app-android`** 仓。该仓有独立分支/提交。本任务用编译 + 真机验证(无 JVM 单测,@JavascriptInterface 依赖 Android Context)。

**Files:**
- Modify: `app/src/main/java/com/jishisongfu/shaguabijia/ui/webview/SGBridge.kt`
- Modify: `app/src/main/java/com/jishisongfu/shaguabijia/ui/webview/WebViewScreen.kt`

- [ ] **Step 1: SGBridge 加构造器参数 + getLocation()**

`SGBridge.kt`:构造器**末尾**加参数(默认值保证其它调用点不破):

```kotlin
class SGBridge(
    private val context: Context,
    private val onClose: () -> Unit,
    private val onRequestLogin: () -> Unit,
    private val onNavigate: (String) -> Unit,
    private val onRequestLocation: () -> Unit,
    private val locationProvider: () -> Pair<Double, Double>? = { null },
) {
```

在 `isLocationGranted()` 之后加方法(并确保文件已 `import org.json.JSONObject` —— 已有 `import org.json.JSONArray`,补 JSONObject):

```kotlin
    /** 设备当前经纬度 JSON {longitude, latitude};宿主缓存的 lastLocation,拿不到/未授权返空串。
     *  @JavascriptInterface 同步、不能等异步 GPS,故宿主(WebViewScreen)预取 lastLocation 缓存后经
     *  locationProvider 注入;H5 SGBridge.getLocation() 据此取,空则落北京默认。 */
    @JavascriptInterface
    fun getLocation(): String {
        val loc = locationProvider() ?: return ""
        return JSONObject().put("longitude", loc.first).put("latitude", loc.second).toString()
    }
```

- [ ] **Step 2: WebViewScreen 取 lastLocation 缓存并注入**

`WebViewScreen.kt` 顶部补 import(若缺):

```kotlin
import android.Manifest
import android.content.pm.PackageManager
import android.location.Location
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.ui.platform.LocalContext
import androidx.core.content.ContextCompat
import com.google.android.gms.location.FusedLocationProviderClient
import com.google.android.gms.location.LocationServices
import kotlinx.coroutines.suspendCancellableCoroutine
import kotlinx.coroutines.withTimeoutOrNull
import kotlin.coroutines.resume
```

在 `WebViewScreen` 函数体内(`var loadError` 附近)加缓存 + 预取:

```kotlin
    val locContext = LocalContext.current
    val lastLocation = remember { mutableStateOf<Pair<Double, Double>?>(null) }
    LaunchedEffect(Unit) {
        val granted = ContextCompat.checkSelfPermission(locContext, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED ||
            ContextCompat.checkSelfPermission(locContext, Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED
        if (granted) {
            val fused = LocationServices.getFusedLocationProviderClient(locContext)
            val loc = withTimeoutOrNull(3_000L) { fused.awaitLastLocation() }
            if (loc != null) lastLocation.value = loc.longitude to loc.latitude
        }
    }
```

把工厂里的 `SGBridge(...)` 调用加上 `locationProvider`:

```kotlin
                            addJavascriptInterface(
                                SGBridge(
                                    context = ctx,
                                    onClose = onBack,
                                    onRequestLogin = onRequestLogin,
                                    onNavigate = onNavigate,
                                    onRequestLocation = onRequestLocation,
                                    locationProvider = { lastLocation.value },
                                ),
                                SGBridge.NAME,
                            )
```

文件末尾加 `awaitLastLocation` 扩展(镜像 `HomeScreen.kt:728`):

```kotlin
@SuppressLint("MissingPermission")
private suspend fun FusedLocationProviderClient.awaitLastLocation(): Location? =
    suspendCancellableCoroutine { cont ->
        lastLocation
            .addOnSuccessListener { cont.resume(it) }
            .addOnFailureListener { cont.resume(null) }
    }
```

- [ ] **Step 3: 编译**

Run(android 仓根):`./gradlew :app:compileDebugKotlin`
Expected: BUILD SUCCESSFUL(无未解析引用)

- [ ] **Step 4: 提交(android 仓)**

```bash
git add app/src/main/java/com/jishisongfu/shaguabijia/ui/webview/SGBridge.kt \
        app/src/main/java/com/jishisongfu/shaguabijia/ui/webview/WebViewScreen.kt
git commit -m "feat(webview): SGBridge.getLocation() 注入 FusedLocation lastLocation(首页 feed 距离最近用真实定位)"
```

---

## Task 3: home/index.html — feed 数据/渲染模块 + 替换排序处理器

**Files:**
- Modify: `h5/home/index.html`(删静态卡 @5047-5158;替换排序处理器 @6664-6686;新增 feed 模块 `<script>`)

- [ ] **Step 1: 清空 `.home-feed` 静态 mock 卡**

把 `<div class="home-feed">`(行 5046)与其闭合 `</div>` 之间的 **7 个 `<div class="feed-card">…</div>`**(行 5047–5158)全部删掉,只留空容器:

```html
            <div class="home-feed"></div>
            <div class="feed-end" style="display:none">已经到底了</div>
```

(原 `.feed-end` 行 5159 改成默认 `display:none`,由模块按 `hasNext` 控制。)

- [ ] **Step 2: 替换排序 tab 处理器**

把行 6664–6686 的整段 `document.addEventListener('click', function (e) { … feed-sort … });`(只切高亮 + asc/desc + scrollIntoView 那段)**整体替换**为下面这段(保留 scrollIntoView 体验,删 asc/desc,接真实切换):

```javascript
// ===== feed 排序 tab(智能推荐/距离最近/销量最高)→ 接真实数据(H2b) =====
document.addEventListener('click', function (e) {
  var item = e.target.closest('#home .feed-sort .fs-item');
  if (!item || item.classList.contains('active')) return;
  var group = item.closest('.feed-sort');
  group.querySelectorAll('.fs-item').forEach(function (o) { o.classList.remove('active'); });
  item.classList.add('active');
  // 未授权定位:只切高亮、不打接口(对齐原生 selectTabWithoutLoad);授权后由 applyLocationState 拉
  if (window.HomeFeed) {
    if (HomeFeed.locationGranted()) HomeFeed.switchTab(item.dataset.key);
    else HomeFeed.selectTabWithoutLoad(item.dataset.key);
  }
  var stickY = 82;
  if (group.getBoundingClientRect().top > stickY + 2) {
    group.scrollIntoView({ block: 'start', behavior: 'smooth' });
  }
});
```

- [ ] **Step 3: 新增 feed 模块 `<script>`**

在 `<script src="../shared/bridge.js"></script>`(行 10179)**之后**新增一个 `<script>` 块,内容为完整 feed 模块:

```html
<script>
/* H2b 首页 feed:rec/distance→/meituan/feed,sales→/meituan/top-sales;触底翻页 + 每 tab 5min 缓存
   + loading/empty/degraded 三态 + 去重 + 切 tab 防竞态 + 未授权不打接口。对齐原生 HomeViewModel。 */
(function (global) {
  'use strict';
  var BEIJING = { longitude: 116.404, latitude: 39.928 };
  var ENDPOINT = { rec: 'feed', distance: 'feed', sales: 'top-sales' };
  var CACHE_TTL = 5 * 60 * 1000;
  var SCROLL_THRESHOLD = 400; // 距底 px 触发翻页

  var st = { tab: 'rec', page: 0, hasNext: true, loading: false, loadedOnce: false,
             items: [], seq: 0, coords: null, cache: {} };

  function $feed() { return document.querySelector('#home .home-feed'); }
  function $end() { return document.querySelector('#home .feed-end'); }
  function $scroll() { return document.querySelector('#home .home-scroll'); }

  function locationGranted() {
    try { if (global.SGBridge && SGBridge.isLocationGranted) return !!SGBridge.isLocationGranted(); } catch (e) {}
    return false;
  }
  function getCoords() {
    try {
      if (global.SGBridge && SGBridge.getLocation) {
        var c = SGBridge.getLocation();
        if (c && typeof c.longitude === 'number' && typeof c.latitude === 'number') return c;
      }
    } catch (e) {}
    return BEIJING;
  }
  function esc(s) {
    return String(s == null ? '' : s).replace(/[&<>"']/g, function (m) {
      return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[m];
    });
  }
  function splitPrice(p) {
    var s = String(p == null ? '' : p), i = s.indexOf('.');
    return i < 0 ? [s, ''] : [s.slice(0, i), s.slice(i)];
  }

  // CouponCard → .feed-card(1:1 照原生 FeedCard;feed-tag 只用 price_label/rank_label,不显示「比团购省」)
  function renderCard(card) {
    var isWaimai = card.platform === 1;
    var shop = card.brand_name
      ? '<span class="shop-name">' + esc(card.brand_name) + '</span><span class="title-sep">｜</span>' : '';
    var title = esc(card.name || '');
    if (card.available_poi_num) title += '｜' + card.available_poi_num + '店通用';
    var metaLeft = '';
    if (card.distance_text) metaLeft += esc(card.distance_text);
    if (card.poi_name) metaLeft += (metaLeft ? ' ' : '') + esc(card.poi_name);
    var saleVol = card.sale_volume ? '<span class="meta-right">' + esc(card.sale_volume) + '</span>' : '';
    var labels = [];
    if (card.price_label && card.price_label.trim()) labels.push(card.price_label.trim());
    if (card.rank_label && card.rank_label.trim()) labels.push(card.rank_label.trim());
    var tag = labels.length
      ? '<div class="feed-tag">' + esc(labels[Math.floor(Math.random() * labels.length)]) + '</div>' : '';
    var pr = splitPrice(card.sell_price);

    var el = document.createElement('div');
    el.className = 'feed-card';
    el.dataset.sign = card.product_view_sign || '';
    el.dataset.platform = card.platform;
    if (card.biz_line != null) el.dataset.bizLine = card.biz_line;
    el.innerHTML =
      '<div class="feed-img"><img src="' + esc(card.head_image_url || '') + '" alt="">' +
        '<span class="feed-cat-badge ' + (isWaimai ? 'cat-waimai">外卖' : 'cat-tuangou">团购') + '</span></div>' +
      '<div class="feed-body">' +
        '<div class="feed-title">' + shop + title + '</div>' +
        '<div class="feed-meta"><span class="meta-left">' + metaLeft + '</span>' + saleVol + '</div>' +
        tag +
        '<div class="feed-pricerow">' +
          '<div class="feed-price"><span class="yuan">¥</span><span class="num">' + esc(pr[0]) +
            (pr[1] ? '<small>' + esc(pr[1]) + '</small>' : '') + '</span></div>' +
          '<span class="feed-original">¥' + esc(card.original_price || '') + '</span>' +
        '</div>' +
      '</div>' +
      '<div class="feed-grab">抢</div>';
    return el;
  }

  function renderList(newItems, append) {
    var feed = $feed(); if (!feed) return;
    if (!append) feed.innerHTML = '';
    newItems.forEach(function (c) { feed.appendChild(renderCard(c)); });
    var end = $end();
    if (end) end.style.display = (!st.hasNext && st.items.length) ? '' : 'none';
  }

  function body(tab, page, coords) {
    return tab === 'sales'
      ? { page: page }
      : { longitude: coords.longitude, latitude: coords.latitude, page: page, tab: tab };
  }

  function loadPage(page, append) {
    var tab = st.tab, coords = getCoords(), mySeq = ++st.seq;
    st.coords = coords; st.loading = true;
    if (global.HomeFeedStates) HomeFeedStates(append ? 'loadingMore' : 'loading');
    fetch('/api/v1/meituan/' + ENDPOINT[tab], {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body(tab, page, coords)),
    }).then(function (r) { return r.ok ? r.json() : null; }).then(function (d) {
      if (mySeq !== st.seq) return;                 // 竞态:已切 tab/重载 → 丢弃旧响应
      st.loading = false; st.loadedOnce = true;
      if (!d) { if (global.HomeFeedStates) HomeFeedStates('degraded'); return; }
      var items = d.items || [];
      if (append) {
        var seen = {}; st.items.forEach(function (c) { seen[c.product_view_sign] = 1; });
        items = items.filter(function (c) { return c.product_view_sign && !seen[c.product_view_sign]; });
        st.items = st.items.concat(items);
      } else { st.items = items; }
      st.page = page; st.hasNext = !!d.has_next;
      st.cache[tab] = { items: st.items.slice(), page: st.page, hasNext: st.hasNext,
        loadedAt: (append && st.cache[tab]) ? st.cache[tab].loadedAt : Date.now() };
      renderList(append ? items : st.items, append);
      if (global.HomeFeedStates) HomeFeedStates(d.status === 'degraded' ? 'degraded' : (st.items.length ? 'ok' : 'empty'));
    }).catch(function () {
      if (mySeq !== st.seq) return;
      st.loading = false; st.loadedOnce = true;
      if (global.HomeFeedStates) HomeFeedStates('degraded');
    });
  }

  function loadFirst() { st.page = 0; st.hasNext = true; st.items = []; renderList([], false); loadPage(1, false); }
  function loadNext() { if (!st.hasNext || st.loading) return; loadPage(st.page + 1, true); }

  function switchTab(tab) {
    if (tab === st.tab) return;
    st.seq++;                                        // 作废旧 tab 在飞的请求
    st.tab = tab;
    var c = st.cache[tab];
    if (c && Date.now() - c.loadedAt < CACHE_TTL) {  // 命中新鲜缓存 → 直接恢复,不转圈
      st.items = c.items.slice(); st.page = c.page; st.hasNext = c.hasNext; st.loading = false;
      renderList(st.items, false);
      if (global.HomeFeedStates) HomeFeedStates(st.items.length ? 'ok' : 'empty');
    } else { loadFirst(); }
  }
  function selectTabWithoutLoad(tab) {            // 未授权:只切状态,不打接口
    if (tab === st.tab) return;
    st.seq++; st.tab = tab; st.page = 0; st.hasNext = true; st.items = []; renderList([], false);
  }

  // 坐标变化(rec/distance 依赖坐标)→ 清全部缓存并重拉当前 tab
  function refreshIfCoordsChanged() {
    var c = getCoords();
    if (st.coords && (st.coords.longitude !== c.longitude || st.coords.latitude !== c.latitude)) {
      st.cache = {};
      if (locationGranted()) loadFirst();
    }
  }

  // 触底翻页
  function bindScroll() {
    var sc = $scroll(); if (!sc || sc._feedBound) return; sc._feedBound = true;
    sc.addEventListener('scroll', function () {
      if (sc.scrollTop + sc.clientHeight >= sc.scrollHeight - SCROLL_THRESHOLD) loadNext();
    });
  }

  global.HomeFeed = {
    loadFirst: loadFirst, switchTab: switchTab, selectTabWithoutLoad: selectTabWithoutLoad,
    refreshIfCoordsChanged: refreshIfCoordsChanged, bindScroll: bindScroll,
    locationGranted: locationGranted, state: st,
  };
  document.addEventListener('DOMContentLoaded', bindScroll);
})(window);
</script>
```

- [ ] **Step 4: 浏览器手动验证(无桥→mock 北京)**

Run:`uvicorn app.main:app --port 8770`(或 `./run.sh`),浏览器开 `http://localhost:8770/h5/home/`
临时在 console 执行 `HomeFeed.loadFirst()`(Task 4 接 applyLocationState 后会自动触发)。
Expected:`.home-feed` 出现真实券卡(头图/店名/价格/标签);滚到底自动追加下一页;点「智能推荐/距离最近/销量最高」切换列表;再切回 1s 内命中缓存不转圈。

- [ ] **Step 5: 提交**

```bash
git add h5/home/index.html
git commit -m "feat(h5): 首页 feed 接 /meituan/feed+top-sales(渲染/翻页/缓存/切 tab/防竞态;删 mock 静态卡)"
```

---

## Task 4: 接定位状态(applyLocationState 联动)+ 三态 UI + 抢按钮

**Files:**
- Modify: `h5/home/index.html`(`applyLocationState` @9135;新增 `HomeFeedStates` + 抢委托)

- [ ] **Step 1: 新增 `HomeFeedStates`(loading/empty/degraded → 复用 H2a 容器)**

在 Task 3 的 feed 模块 `<script>` **之后**再加一个 `<script>`:

```html
<script>
/* H2b feed 三态:loading 首次转圈 / empty 复用「附近暂无…去比价」/ degraded 服务繁忙。
   与 H2a applyLocationState 协作:未授权时 applyLocationState 已把 feed 区切「去授权」空态,这里只管已授权后的态。 */
(function (global) {
  'use strict';
  function el(id) { return document.getElementById(id); }
  global.HomeFeedStates = function (kind) {
    var feed = document.querySelector('#home .home-feed');
    var noDeal = el('homeFeedNoDealEmpty');
    var loading = el('homeFeedLoading');
    var degraded = el('homeFeedDegraded');
    var loaded = global.HomeFeed && HomeFeed.state.loadedOnce;
    var hasItems = global.HomeFeed && HomeFeed.state.items.length;
    // 仅在已授权(未授权由 applyLocationState 管)时切这些态
    if (feed) feed.style.display = (kind === 'ok' || (kind === 'loadingMore')) && hasItems ? '' : (hasItems ? '' : 'none');
    if (loading) loading.style.display = (kind === 'loading' && !hasItems) ? 'flex' : 'none';
    if (noDeal) noDeal.style.display = (kind === 'empty' && loaded) ? 'flex' : 'none';
    if (degraded) degraded.style.display = (kind === 'degraded' && !hasItems) ? 'flex' : 'none';
  };
})(window);
</script>
```

- [ ] **Step 2: 加 loading / degraded 两个空态容器**

在 `#homeFeedNoDealEmpty`(行 5041 那个 div)**之后**插入两个容器(复用其样式骨架):

```html
            <!-- feed 首次加载中 -->
            <div class="home-feed-empty" id="homeFeedLoading" style="display:none;flex-direction:column;align-items:center;justify-content:flex-start;background:#fff;padding:32px 24px;text-align:center;">
              <div style="font-size:14px;color:#999;">加载中…</div>
            </div>
            <!-- feed 服务繁忙(degraded) -->
            <div class="home-feed-empty" id="homeFeedDegraded" style="display:none;flex-direction:column;align-items:center;justify-content:flex-start;background:#fff;padding:18px 24px 24px;text-align:center;">
              <div style="font-size:14px;color:#999;line-height:1.5;">服务繁忙,下拉重试～</div>
              <button onclick="HomeFeed.loadFirst()" style="margin-top:12px;height:32px;padding:0 20px;border:none;border-radius:18px;font-size:13px;font-weight:600;background:linear-gradient(180deg,#FFE066 0%,#FFC400 100%);color:#1A1A1A;cursor:pointer;">重试</button>
            </div>
```

- [ ] **Step 3: applyLocationState 接 feed 加载**

在 `applyLocationState`(行 9135)函数体**末尾 `}` 之前**加:已授权则首次拉/刷新坐标,未授权则清 feed 三态由 H2a 空态接管:

```javascript
  // H2b: 已授权 → 拉当前 tab(首次)或按坐标变化刷新;未授权 → 关 feed 三态(H2a 去授权空态接管)
  if (locationGranted) {
    if (window.HomeFeed) {
      if (!HomeFeed.state.loadedOnce) HomeFeed.loadFirst();
      else HomeFeed.refreshIfCoordsChanged();
    }
  } else {
    ['homeFeedLoading', 'homeFeedDegraded', 'homeFeedNoDealEmpty'].forEach(function (id) {
      var n = document.getElementById(id); if (n) n.style.display = 'none';
    });
  }
```

- [ ] **Step 4: 抢按钮 → referral-link → openMeituan(事件委托)**

在 `HomeFeedStates` 的 `<script>` 里(IIFE 内,`global.HomeFeedStates = …` 之后)加抢委托:

```javascript
  // 抢:换链(linkTypeList=[1,3])→ deeplink 优先, 退 h5 → SGBridge.openMeituan
  document.addEventListener('click', function (e) {
    var grab = e.target.closest('#home .feed-card .feed-grab');
    if (!grab) return;
    var card = grab.closest('.feed-card');
    if (!card || card._grabbing) return;
    card._grabbing = true;
    var prev = grab.textContent; grab.textContent = '…';
    fetch('/api/v1/meituan/referral-link', {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        product_view_sign: card.dataset.sign,
        platform: Number(card.dataset.platform) || 1,
        biz_line: card.dataset.bizLine != null ? Number(card.dataset.bizLine) : null,
        link_type_list: [1, 3],
      }),
    }).then(function (r) { return r.ok ? r.json() : null; }).then(function (d) {
      var map = (d && d.link_map) || {};
      var uri = map['3'] || map['1'] || (d && d.link) || '';
      if (uri && global.SGBridge && SGBridge.openMeituan) SGBridge.openMeituan(uri);
      else if (global.SGBridge && SGBridge.toast) SGBridge.toast('暂时无法跳转,请稍后再试');
      else console.log('[抢] openMeituan →', uri);
    }).catch(function () {
      if (global.SGBridge && SGBridge.toast) SGBridge.toast('暂时无法跳转,请稍后再试');
    }).then(function () { grab.textContent = prev; card._grabbing = false; });
  });
```

- [ ] **Step 5: 浏览器手动验证**

浏览器开 `http://localhost:8770/h5/home/`(无桥 → `isLocationGranted` mock 返 true → 自动 `loadFirst`):
Expected:首屏自动出 feed(不需手动调);切 tab 正常;命中空数据显示「附近暂无…去比价」;断网/后端返 degraded 显示「服务繁忙」+重试;点「抢」console 打印 `openMeituan → <link>`(无桥 mock)。

- [ ] **Step 6: 提交**

```bash
git add h5/home/index.html
git commit -m "feat(h5): 首页 feed 接定位态联动 + loading/empty/degraded 三态 + 抢按钮换链拉起美团"
```

---

## Task 5: home feed 接线冒烟测试(pytest 内容护栏)

**Files:**
- Test: `tests/test_h5_hosting.py`

- [ ] **Step 1: 写测试(此时应已通过 —— 作回归护栏)**

追加:

```python
def test_h5_home_feed_wired(client) -> None:
    # H2b: 首页 feed 接真实美团端点 + 抢换链;mock 静态卡已移除
    resp = client.get("/h5/home/index.html")
    assert resp.status_code == 200
    body = resp.text
    assert "/api/v1/meituan/feed" in body          # rec/distance
    assert "/api/v1/meituan/top-sales" in body     # 销量最高
    assert "/api/v1/meituan/referral-link" in body  # 抢
    assert "HomeFeed" in body                        # feed 模块已挂
    assert "比团购省" not in body                     # 随原生:不显示「比团购省」(mock 卡已删)
    assert "chabaidao.png" not in body               # 写死的 mock 头图已移除
```

- [ ] **Step 2: 跑测试**

Run: `pytest tests/test_h5_hosting.py -q`
Expected: PASS(全绿;若 `比团购省`/`chabaidao.png` 仍在,回 Task 3 Step 1 确认静态卡删净)

- [ ] **Step 3: 提交**

```bash
git add tests/test_h5_hosting.py
git commit -m "test(h5): 首页 feed 接线冒烟(meituan 端点 + 抢 + mock 卡清零)"
```

---

## Task 6: 端到端验证 + 收尾

**Files:** 无(验证 + 分支收尾)

- [ ] **Step 1: 后端全量回归**

Run: `pytest -q`
Expected: 全绿(本计划不改后端;H5 冒烟新增项通过)

- [ ] **Step 2: Lint**

Run: `ruff check .`
Expected: 无新增告警(仅改了 `tests/test_h5_hosting.py`;H5/JS 不在 ruff 范围)

- [ ] **Step 3: 浏览器端到端走查**

开 `http://localhost:8770/h5/home/`,逐项核对(对照原生 `HomeScreen` feed):
- 三 tab 各自拉到数据、卡片渲染对(头图/外卖团购徽章/店名橙色/距离·店名/销量/标签/现价原价/抢)。
- 触底翻页累加且无重复;切 tab→切回命中缓存不转圈;距离最近一次性到底(不再翻页)。
- 「抢」console 打印 `openMeituan`;空数据/降级态文案正确。

- [ ] **Step 4: 真机走查(需 Task 2 安卓包)**

装含 Task 2 改动的 debug 包,进首页:
- 已授权定位:距离最近按真实位置由近及远;rec/sales 正常;点抢拉起美团 App/H5。
- 未授权:三 tab 均「去授权」空态,切 tab 不打接口;授权回前台自动出 feed。

- [ ] **Step 5: 收尾**

调用 superpowers:finishing-a-development-branch 决定合并/PR;两仓分别提交(app-server `feat/h5-sgbridge-gk`;android 自有分支)。

---

## Self-Review

- **Spec coverage:** §2 范围→Task 1/2/3/4/5;§4 tab 映射→Task 3(`ENDPOINT`);§5 定位→Task 1+2+Task3 `getCoords`+Task4 `refreshIfCoordsChanged`;§6 渲染→Task 3 `renderCard`;§7 列表行为(翻页/缓存/三态/竞态/未授权)→Task 3+4;§8 抢→Task 4 Step 4;§9 裸 fetch→Task 3/4;§10 验收→Task 5/6。无遗漏。
- **Placeholder scan:** 无 TBD/TODO;每步含实际代码/命令/期望。
- **Type consistency:** `HomeFeed.{loadFirst,switchTab,selectTabWithoutLoad,refreshIfCoordsChanged,bindScroll,locationGranted,state}` 与 `HomeFeedStates(kind)` 在 Task 3/4 定义并被排序处理器 / applyLocationState 一致引用;`SGBridge.getLocation()`(Task1 JS / Task2 Kotlin)签名一致(同步,JSON/对象 ↔ null/空串)。
