# category Specification

## Purpose
The product category tree: localized names and the subtree-matching filter behavior used when browsing products by category.

## Requirements

### Requirement: Localized category content
Category names SHALL be stored as JSONB maps keyed by locale (`en`, `zh`). The API MUST return the full map; clients pick the display locale.

#### Scenario: bilingual round-trip
- **WHEN** an admin creates a category with name `{"en": "Mugs", "zh": "马克杯"}`
- **THEN** `GET /api/categories` returns the identical map for that category

### Requirement: Category subtree browse filtering
`GET /api/categories` SHALL return the full category tree as a flat list, each with `id`, `parent_id`, `name`, `slug`, and `position`, ordered by `position` then `slug`. When a product listing is filtered by `category_id`, the filter SHALL match that category **and every category beneath it** in the tree, so requesting a parent category returns products assigned to its child and grandchild categories.

#### Scenario: parent category includes descendant products
- **WHEN** a shopper requests products for a category that has child categories holding published products
- **THEN** the response contains the products assigned to those descendant categories, not only those assigned directly to the requested category