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

オープン
  • 何か問題がありますか？
#201 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
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 ファイルあり
  • プルリクエストのテンプレートなし
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

StarCitizenWiki/API のほかの issue

StarCitizenWiki/API の issue をすべて見る

似ている issue

PHP の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。