# Xianyu Item Link Normalization — 2026-05

## Context

BOSS reported that generated Xianyu/Goofish candidate links were not reliably clickable from Feishu/mobile messages. Existing data often stored desktop links like:

```text
https://www.goofish.com/item?id=<id>&categoryId=<category>
```

These can return HTTP 200 in curl but may not deep-link well from messaging clients. Mobile item links are more reliable for user-facing reports/notifications:

```text
https://h5.m.goofish.com/item?id=<id>
```

## Implemented pattern

Add/use `lib/links.mjs`:

- `normalizeItemId(value)` extracts item IDs from `id`, `itemId`, full item URLs, IM URLs, and raw text.
- `buildItemLinks(itemOrId)` returns desktop and mobile URLs.
- `enrichItemLinks(item)` preserves original URL in `originalHref`, stores desktop URL in `webHref`, mobile URL in `mobileHref`, and sets user-facing `href` to the mobile URL.

Integration points:

- `lib/search.mjs`: after scraping desktop card href/category, call `enrichItemLinks(item)` before returning results.
- `lib/filter.mjs`: after merging detail fields, call `enrichItemLinks({ ...product, ...detail })` so fine-filtered candidates keep clickable mobile links.
- `lib/task.mjs`: normalize products during load/serialize/persist so existing `data/tasks.json` records become compatible without manual migration.
- `lib/analyzer.mjs`, `lib/notifier.mjs`, `tools/hermes_report.mjs`: use `buildItemLinks(item).primaryUrl` when rendering reports and notifications.

## Verification commands

```bash
cd /Users/chick/.Hermes/workspace/research/xianyu-hunter
node --check lib/links.mjs && node --check lib/search.mjs && node --check lib/filter.mjs && node --check lib/task.mjs && node --check lib/analyzer.mjs && node --check lib/notifier.mjs && node --check tools/hermes_report.mjs

node --input-type=module - <<'NODE'
import { buildItemLinks, enrichItemLinks } from './lib/links.mjs';
console.log(buildItemLinks({ id: '1017096975429', href: 'https://www.goofish.com/item?id=1017096975429&categoryId=126856267' }));
console.log(enrichItemLinks({ href: '/item?id=1039232668094&categoryId=126856522' }));
NODE

node tools/hermes_report.mjs --task <task_id> --limit 3 --out /tmp/xianyu-link-test.md
sed -n '1,80p' /tmp/xianyu-link-test.md
```

Expected user-facing links in reports/notifications:

```text
https://h5.m.goofish.com/item?id=<id>
```

## Pitfall

Do not replace `chatUrl` with mobile item links. Seller chat still needs desktop IM URLs such as:

```text
https://www.goofish.com/im?itemId=<id>&peerUserId=<sellerId>
```

Only user-facing product links should prefer h5 mobile URLs.