related_items: expose each variant axis separately instead of one unlabelled axis

未关闭
  • 哪里不对？
#201 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
15/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
活跃
技术栈
php
领域
api, backend

调研方向

This is a design change to the related_items response of GET /api/v2/items?include=related_items, not a small fix. Start by working out which axes the existing one-axis grouping uses, and whether size, grade, manufacturer and type on each item record are enough to build the others. Settle the labelled shape (by_size, by_grade, by_color, set_items) with the maintainers before writing code. Done means each applicable axis is returned separately and labelled, and the sweep numbers in the issue reproduce.

由索引模型根据 Issue 内容生成。

描述

enhancement

The ask

related_items.variant_items groups items that are identical except along one attribute. Which attribute it is changes from product to product, nothing in the payload says which, and the other axes aren't reachable at all.

Three items, same payload shape, three different meanings:

item size grade variant_items contains axis
Frost-Star SL 0 C Winter-Star SL (size 0, grade D) grade
M4A Cannon 2 A M5A–M9A Cannon (sizes 3-7, all grade A) size
ADP Arms Grey 1 — 23 × ADP Arms * (same size, no grade) colour

These are not exotic relations. M4A Cannon's variants are the size ladder, and Frost-Star SL's are the grade ladder. The API already produces both kinds. What it doesn't do is produce more than one per product, or say which one you got, so a consumer can't tell them apart without refetching every member and diffing the attributes itself.

We'd like related_items to expose each applicable axis separately and label it, rather than returning one unlabelled axis chosen per product:

"related_items": {
  "by_size":   [ ... ],   // same line and grade, other sizes
  "by_grade":  [ ... ],   // same line and size, other grades
  "by_color":  [ ... ],   // identical, other colours
  "set_items": [ ... ]    // same set, other slots (already present)
}

The attributes this needs are already on every item record (size, grade, manufacturer, type), and the API already performs exactly this grouping for one axis. Doing it for the others is the same operation. Doing it once here also avoids every downstream client reimplementing the grouping and drifting from each other.

The grouping itself is sound

Worth saying plainly, because this is a request to extend the model rather than to fix it. Across 12,331 items there are zero base_item chains that fail to self-terminate, zero is_base_variant flags contradicting base_item, and zero base items carrying two different set_names. Of 1,306 groups with more than one member (7,150 items), 99.6% vary along exactly one axis:

group shape count share
size and grade both fixed (colour variants) 1,168 89.4%
grade varies, size fixed 78 6.0%
size varies, grade fixed 55 4.2%
both vary 5 0.4%

The 5 exceptions are all radars, e.g. Denning grouping Abetti (size 1, grade A), Agrippa (size 2, grade A) and Backlund (size 1, grade B). Those look like genuine errors rather than a design choice.

Where a product varies along two axes, only one is reachable

The three items above each vary along a single axis, so returning one is enough. J-Span coolers vary along two, and the naming encodes both:

S0 S1 S2 S3
grade B Cryo-Star SL Cryo-Star Cryo-Star EX Cryo-Star XL
grade C Frost-Star SL Frost-Star Frost-Star EX Frost-Star XL
grade D Winter-Star SL Winter-Star Winter-Star EX Winter-Star XL

related_items returns the column — other grades at the same size, the upgrade path. The row, the same product at other sizes, isn't available at all, despite being visible in the naming and in class_name (COOL_JSPN_S0*_FrostStar*). Nothing indicates a second axis exists.

Three further problems with related_items are independent of this request and cheaper to fix, so they're filed separately:

  • set_name populated from the manufacturer, category or a class identifier — #202
  • items missing grouping data while their own variants are grouped without them — #203
  • cosmetic variant families split across several base_item groups — #204
Reproducing these numbers

Full sweep on 18 September 2026 — the list endpoint accepts the include, so no per-UUID fetching is needed:

GET /api/v2/items?limit=200&page=N&include=related_items&locale=en_EN

62 pages, 12,331 items, no duplicate UUIDs.

count share
set_name present 6,098 49.5%
base_item present 7,150 58.0%
variant_items non-empty 6,773
set_items non-empty 1,755
no grouping data at all 5,053 41.0%

Every item name above links to its record at /api/v2/items/<uuid>?include=related_items&locale=en_EN.

Happy to share the sweep script and resulting items.jsonl, or to re-run it after a change.

主要语言
PHP
星标
58
派生
15
30 天内没有已合并 PR

环境准备

  • 提供 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 没有贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

StarCitizenWiki/API 的其他 Issue

查看 StarCitizenWiki/API 的全部 Issue

相似的 Issue

更多 PHP Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。