cross-platform-products-ai-analyst/docs/TmallCrawlerResearch.md

# 天猫详情页与评论抓取研究

- 状态：Draft
- 更新时间：2026-04-03
- 关联任务：`S3-01`

## 结论

1. 天猫详情和评论链路已经可以明确到具体入口与 API，不再是“靠 DOM 碰运气”的问题。
2. 默认可交付路径应是“登录态页面状态解析 + 登录态模板回放”的组合，不是匿名直连。
3. 2026-04-03 的实测里，天猫详情和评论 API 在服务端匿名请求下都会回到带登录跳转的 `RGV587_ERROR`，因此当前必须把登录态作为前置依赖。
4. 详情页存在可稳定访问的 PC SSR 壳路由，适合做资源发现、版本跟踪和模板漂移观测；真正稳定可回放的详情数据来源则应优先落在登录态 HTML/SSR 内嵌状态，而不是继续依赖易漂移的详情 mtop。
5. 最新一轮已把天猫 `search` 主路径补到服务端：直接回放 `https://s.taobao.com/search?q=<query>&tab=mall` 的登录态 HTML，并优先解析内嵌 `g_page_config` / JSON 负载，必要时再从商品链接块回退提取候选。

## 已验证入口

### 1. 商品详情壳页

- 直接访问 `https://detail.tmall.com/item.htm?id=<itemId>`，当前会返回登录跳转页，并带 `x-sec-reason: FAIL_SYS_SESSION_EXPIRED`。
- 直接访问 `https://detail.tmall.com/wow/z/app/tbpc/pc-detail-ssr-2025/home?itemId=<itemId>`，可稳定拿到 SSR 壳页与资源清单。
- 2026-04-03 实测的资源版本为：
  - `https://g.alicdn.com/code/npm/@ali/tbpc-pc-detail-ssr-2025/0.0.54/js/data-loader.js`
  - `https://g.alicdn.com/code/npm/@ali/tbpc-pc-detail-ssr-2025/0.0.54/js/p_home.js`

### 2. 详情 API

`data-loader.js` 暴露了两条详情接口：

- `mtop.taobao.pcdetail.data.get`
- `mtop.taobao.pcdetail.business.data.get`

当前主链更像是：

1. 详情页 SSR 壳加载 `data-loader.js`
2. `data-loader.js` 组装 `data` 负载：
   - `id`
   - `detail_v: "3.3.2"`
   - `exParams.queryParams`
   - `exParams.domain`
   - `exParams.path_name`
   - `exParams.pcSource`
   - `exParams.logicVer`
   - `exParams.nonce`
3. 浏览器中的 `lib-mtop` 发起详情请求

### 3. 评论 API

`p_home.js` 暴露了两条评论接口：

- PC 评论：`mtop.alibaba.review.list.for.new.pc.detail`
- H5 评论兜底：`mtop.taobao.rate.detaillist.get`

实测与 bundle 还原出的关键参数如下。

PC 评论请求：

- `itemId`
- `bizCode`
  - 天猫为 `ali.china.tmall`
  - 淘宝为 `ali.china.taobao`
- `channel: "pc_detail"`
- `pageSize`
- `pageNum`
- 可选 `rateType`
- 可选 `orderType`

H5 评论请求：

- `auctionNumId`
- `pageNo`
- `pageSize`
- `showTrueCount: false`
- `rateSrc: "pc_rate_list"`
- 可选 `rateType`
- 可选 `orderType`
- 可选 `expression`

### 4. 2026-04-03 追加实机结论

- 当前真实商品页 `https://detail.tmall.com/item.htm?id=934454505228...` 的页面内详情请求稳定命中：
  - `mtop.tmall.kangaroo.core.service.route.aldlampservicefixedresv2`
- 该接口在已登录浏览器中的真实返回里，`data.resultValue["36500751"].data` 只暴露 `distinctId`、`dataSetId`、`resId` 等路由信息，本身不是最终商品详情快照。
- 同一页面的 SSR 内嵌脚本 `window.__ICE_APP_CONTEXT__` 已直接包含：
  - 标题
  - 店铺名 / 店铺链接 / 店铺类型
  - 主图
  - 当前展示价格 / 划线价
  - 已售文案
  - 评论总量与首屏评论摘要
- 结论：
  - 商品详情抓取应优先采用“登录态 HTML + `window.__ICE_APP_CONTEXT__` 解析”。
  - 评论抓取继续采用 `mtop.taobao.rate.detaillist.get` 更合适。
  - 服务端回放评论模板时，必须基于 Cookie 中 `_m_h5_tk` 重新计算 `t/sign`；仅替换 `data` 而不重签名会被 mtop 拒绝。

## 2026-04-03 实测结果

### 0. MCP 浏览器实时登录态闭环

- 使用 MCP Playwright 浏览器直接打开真实商品页 `https://detail.tmall.com/item.htm?id=934454505228`，页面可在登录态下稳定打开。
- 通过 `page.context().cookies()` 抽取当前 `*.tmall.com` 与 `detail.tmall.com` Cookie，回灌到 `POST /api/platforms/tmall/live-session` 后，`GET /api/platforms/tmall/live-product-preview?itemId=934454505228&commentCount=20&page=1&maxPages=2` 已实机返回 200。
- 实机返回中已包含：
  - 商品详情：标题、店铺、主图、价格、评论总量。
  - 评论结果：标签、分页信息，以及 20 条真实评论样本。
- 本轮还暴露并修复了一个真实问题：`mtop.taobao.rate.detaillist.get` 返回的是 JSONP，服务端解析器此前未先解包 `mtopjsonp(...)`，导致“请求成功但评论为空”。该问题已在 `apps/api` 修复并补齐回归测试。

### 1. 详情 API

匿名服务端请求 `mtop.taobao.pcdetail.data.get` 时，返回：

- `ret: ["RGV587_ERROR::SM::..."]`
- `data.url` 指向 `https://login.taobao.com/member/login.jhtml?...`

结论：

- 详情 API 当前必须依赖登录态 Cookie。
- 仅靠匿名 `_m_h5_tk` / H5 签名不足以形成稳定交付链路。

### 2. 评论 API

匿名服务端请求：

- `mtop.alibaba.review.list.for.new.pc.detail`
- `mtop.taobao.rate.detaillist.get`

同样返回：

- `ret: ["RGV587_ERROR::SM::..."]`
- `data.url` / `data.h5url` 指向淘宝登录页

结论：

- 评论接口虽然前端代码里标记为 `needLogin: false`，但当前实测依然被服务端登录门槛或风控前置拦住。
- 对项目来说，评论抓取和详情抓取一样，都要走“先登录、后回放”。

## 已落库的工程推进

本轮已在 `apps/api` 补了天猫 live-session 与任务主链骨架：

- `apps/api/src/platforms/tmall/live-session.ts`
- `apps/api/src/platforms/tmall/parsers.ts`
- `apps/api/src/platforms/tmall/types.ts`
- `apps/api/src/platforms/tmall/utils.ts`

当前能力包括：

1. 导入天猫 `cookieHeader`
2. 导入评论模板 URL，并保留详情模板 URL 作为漂移观测输入
3. 登录态搜索页改为 `s.taobao.com/search?...&tab=mall` HTML 拉取，并解析内嵌状态与候选链接
4. 商品详情改为登录态详情页 HTML 拉取，并解析 `window.__ICE_APP_CONTEXT__` 的 SSR 内嵌状态
5. 评论模板按新 `itemId`、页码、每页数量改写请求参数
6. 评论回放前基于 `_m_h5_tk` 按真实 mtop 公式重算 `t/sign`
7. 评论多页回放后做去重聚合
8. 对登录跳转响应统一抛出 `409`，可直接接入 `NeedLogin` / `Blocked`
9. 暴露 `live-search-preview` / `live-detail-preview` / `live-reviews-preview` / `live-product-preview` 预览入口
10. 把天猫实时 `search/detail/reviews` 接入任务执行主链，并新增 JD + 天猫双平台 live 主回归、`Blocked -> retry success` 报告升版回归、`Blocked -> retry blocked -> report unchanged` 稳定性回归，以及 `SearchBlocked` 恢复后二次确认只补跑新恢复平台的回归

## 下一步建议

1. 用真实登录态继续固化搜索页、评论模板与样本响应，验证 `apps/api` 的 preview 接口：
   - `GET /api/platforms/tmall/live-search-preview`
   - `POST /api/platforms/tmall/live-session`
   - `GET /api/platforms/tmall/live-detail-preview`
   - `GET /api/platforms/tmall/live-reviews-preview`
   - `GET /api/platforms/tmall/live-product-preview`
2. 抓一轮真实任务闭环：
   - 导入 live session
   - 创建任务并选中带 `itemId` 的天猫候选
   - 验证报告证据是否落到真实 `search/detail/reviews` 回放
3. 固化第一批真实 fixture / HAR，补齐 `S0-02`
4. 继续扩大双平台主回归包覆盖面；`SearchBlocked` / `NoResult` / `Blocked` 组合、`Blocked -> retry success` 升版、`Blocked -> retry blocked -> report unchanged`，以及 `SearchBlocked` 恢复后二次确认不重复执行已完成平台已覆盖，后续补更多失败/恢复组合与真实 fixture 驱动回归
5. 如果模板漂移频繁，再补 `L2` 模板刷新与 `L3` 登录恢复

## 参考链接

- <https://www.tmall.com/robots.txt>
- <https://list.tmall.com/robots.txt>
- <https://detail.tmall.com/wow/z/app/tbpc/pc-detail-ssr-2025/home?itemId=833444005595>
- <https://g.alicdn.com/code/npm/@ali/tbpc-pc-detail-ssr-2025/0.0.54/js/data-loader.js>
- <https://g.alicdn.com/code/npm/@ali/tbpc-pc-detail-ssr-2025/0.0.54/js/p_home.js>