# Đóng góp một deck vào Memcard Deck Library

Cảm ơn bạn muốn chia sẻ bộ flashcard! Quy trình theo mô hình Homebrew: bạn gửi một Pull Request thêm/ cập nhật một **manifest**, CI sẽ tự kiểm tra.

## Điều kiện nội dung

- Bạn **có quyền chia sẻ** nội dung này (tự soạn, hoặc nguồn cho phép phân phối lại). Không upload nội dung vi phạm bản quyền.
- License phải nằm trong danh sách cho phép: `CC0-1.0`, `CC-BY-4.0`, `CC-BY-SA-4.0`, `MIT`, `public-domain`.
- Không nội dung rác, quảng cáo trá hình, hoặc nội dung độc hại/không phù hợp.

## Các bước

### 1. Chuẩn bị nội dung deck
Export deck từ app Memcard ra `deck.json` (đúng schema Memcard: `schema_version`, `collection`, `cards[]`). Đưa file này vào **một repo riêng** của bạn (hoặc trong tổ chức `memcard-community`), ví dụ `github.com/<bạn>/<Ten-Deck>/deck.json`.

### 2. Tính checksum và kích thước
```bash
shasum -a 256 deck.json      # lấy content_sha256
wc -c < deck.json            # lấy content_size_bytes
```

### 3. Tạo manifest
Thêm file `manifests/<id>.json` trong repo này. Tên file **phải** trùng `id`. Xem `manifests/minna-no-nihongo-i.json` làm mẫu và `schema/manifest.schema.json` cho đầy đủ ràng buộc.

Các trường bắt buộc: `manifest_version`, `id` (kebab-case, không đổi), `name`, `version` (semver), `description`, `author`, `language` (`front`/`back`, mã ISO), `category`, `tags`, `card_count`, `license`, `content_url` (raw URL tới `deck.json`), `content_sha256`, `content_size_bytes`, `min_app_version`, `created_at`, `updated_at`.

Trường tùy chọn: `source_repo`, và `short_description` — mô tả một dòng (≤150 ký tự) dùng cho danh sách deck, nên trùng với `collection.short_description` trong `deck.json`. Thiếu thì client tự rút gọn từ `description`.

#### Category
Mỗi deck thuộc **đúng một** `category` (dùng `tags` cho phân loại chi tiết hơn). Giá trị hợp lệ:

| `category` | Nội dung |
| --- | --- |
| `languages` | Ngôn ngữ, từ vựng, ngữ pháp |
| `arts-literature` | Nghệ thuật, văn học |
| `maths-science` | Toán và khoa học |
| `the-natural-world` | Thế giới tự nhiên, động thực vật |
| `history-geography` | Lịch sử, địa lý |
| `memory-training` | Luyện trí nhớ |
| `professional-and-careers` | Nghề nghiệp, chuyên môn |
| `standardised-tests` | Thi chuẩn hóa (SAT, IELTS, JLPT…) |
| `trivia` | Kiến thức tổng hợp, đố vui |
| `entertainment` | Giải trí, phim ảnh, game, thể thao |

### 4. Sinh lại index
```bash
python3 scripts/build_index.py
```
Commit cả `manifests/<id>.json` và `index.json`.

### 5. Kiểm tra trước khi gửi
```bash
pip install jsonschema requests
python3 scripts/validate.py
```

### 6. Mở Pull Request
CI (`.github/workflows/validate.yml`) sẽ chạy: schema, id duy nhất, index đồng bộ, tải `content_url`, khớp SHA-256 + size, sanitize nội dung. Tất cả xanh thì maintainer review license + nội dung rồi merge.

## Cập nhật deck đã có
Tăng `version` (semver), cập nhật `content_sha256`, `content_size_bytes`, `card_count`, `updated_at`, rồi chạy lại `build_index.py`. **Không đổi `id`.**

## Gỡ deck (takedown)
Nếu có khiếu nại bản quyền hợp lệ, mở issue với nhãn `takedown`; deck sẽ được gỡ khỏi index.