# 帳票設計書 8-User Data Export

## 概要

本ドキュメントは、Wikipedia iOSアプリケーションにおける「User Data Export」帳票の設計仕様を定義する。この帳票はユーザーの読書リストと設定をエクスポートするためのデータ構造を提供する。

### 本帳票の処理概要

本帳票は、ユーザーがWikipediaアプリで保存した読書リスト、その中の記事エントリ、およびアプリ設定をJSON形式でエクスポートするためのデータ構造を定義する。GDPR等のデータポータビリティ要件に対応するための機能である。

**業務上の目的・背景**：ユーザーがアプリ内で作成・管理しているデータ（読書リスト、保存記事など）を外部に書き出し、他のサービスへの移行やバックアップを可能にする。GDPRのデータポータビリティ権に対応し、ユーザーが自身のデータを管理できるようにする。

**帳票の利用シーン**：設定画面やヘルプ画面から「データエクスポート」機能を選択した場合に使用される。ユーザーは自身の読書リスト一覧、各リストに含まれる記事、同期設定などをJSON形式でエクスポートできる。

**主要な出力内容**：
1. サーバー上の読書リスト（APIReadingList配列）
2. 読書リストエントリ（APIReadingListEntry配列）
3. 同期設定（保存記事・リストの同期ON/OFF）
4. デフォルトリスト表示設定

**帳票の出力タイミング**：ユーザーがデータエクスポートを要求した時点でデータが収集・構造化される。

**帳票の利用者**：Wikipediaアプリのログインユーザー（読書リスト機能を利用しているユーザー）

## 帳票種別

データエクスポート（JSON構造体）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | Help / Settings | HelpViewController | データエクスポートリクエスト |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON |
| 文字コード | UTF-8 |
| エンコーディング | Codable |

### 出力データ構造

```json
{
  "serverReadingLists": [...],
  "serverReadingListEntries": [...],
  "appSettingsSyncSavedArticlesAndLists": true,
  "appSettingsShowSavedReadingList": false
}
```

## 帳票レイアウト

### UserDataExportSyncInfo構造

```swift
public struct UserDataExportSyncInfo: Codable {
    public let serverReadingLists: [APIReadingList]
    public let serverReadingListEntries: [APIReadingListEntry]
    public let appSettingsSyncSavedArticlesAndLists: Bool
    public let appSettingsShowSavedReadingList: Bool
}
```

### フィールド一覧

| No | フィールド名 | 型 | 説明 | 必須 |
|----|-------------|-----|------|-----|
| 1 | serverReadingLists | [APIReadingList] | サーバー上の読書リスト | Yes |
| 2 | serverReadingListEntries | [APIReadingListEntry] | 読書リストエントリ | Yes |
| 3 | appSettingsSyncSavedArticlesAndLists | Bool | 保存記事・リスト同期設定 | Yes |
| 4 | appSettingsShowSavedReadingList | Bool | 保存済み読書リスト表示設定 | Yes |

### APIReadingList構造（参考）

| フィールド | 型 | 説明 |
|-----------|-----|------|
| id | Int64 | リストID |
| name | String | リスト名 |
| description | String? | リスト説明 |
| created | Date | 作成日時 |
| updated | Date | 更新日時 |
| isDefault | Bool | デフォルトリストフラグ |

### APIReadingListEntry構造（参考）

| フィールド | 型 | 説明 |
|-----------|-----|------|
| id | Int64 | エントリID |
| listId | Int64 | 所属リストID |
| project | String | プロジェクト（言語版） |
| title | String | 記事タイトル |
| created | Date | 追加日時 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| ログイン状態 | ユーザーがログインしていること | Yes |
| サーバー同期 | サーバーとの読書リスト同期が有効 | No |

### データ取得元

| データ | 取得元 | 備考 |
|--------|-------|------|
| serverReadingLists | MediaWiki API | 読書リスト一覧 |
| serverReadingListEntries | MediaWiki API | エントリ一覧 |
| appSettingsSyncSavedArticlesAndLists | UserDefaults/アプリ設定 | 同期設定 |
| appSettingsShowSavedReadingList | UserDefaults/アプリ設定 | 表示設定 |

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| ReadingList (Core Data) | ローカル読書リスト | - |
| ReadingListEntry (Core Data) | ローカルエントリ | readingListKey |

### API参照

| エンドポイント | 用途 |
|---------------|------|
| /api/rest_v1/data/lists | 読書リスト取得 |
| /api/rest_v1/data/lists/{id}/entries | エントリ取得 |

## 計算仕様

特に計算処理はなし。データの収集と構造化のみ。

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[データエクスポートリクエスト] --> B{ログイン状態確認}
    B -->|未ログイン| C[エラー: ログイン必要]
    B -->|ログイン済み| D[サーバーから読書リスト取得]
    D --> E[サーバーからエントリ取得]
    E --> F[アプリ設定取得]
    F --> G[UserDataExportSyncInfo構築]
    G --> H[JSONエンコード]
    H --> I[出力完了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 未ログイン | ログイン状態でない | ログイン必要 | ログイン画面へ誘導 |
| ネットワークエラー | API通信失敗 | 通信エラー | リトライ促進 |
| エンコードエラー | JSON変換失敗 | エクスポート失敗 | ログ記録 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数百〜数千件（リスト+エントリ） |
| 目標出力時間 | 数秒〜10秒程度 |
| 同時出力数上限 | 1件 |

## セキュリティ考慮事項

- 個人情報：ユーザーの読書履歴・嗜好情報を含む
- 認証：ログイン状態でのみエクスポート可能
- データ保護：ユーザー自身のデータのみアクセス可能
- 暗号化：HTTPSでの通信、ローカルでの暗号化は任意

## 備考

- Codableプロトコルでシリアライズ/デシリアライズ対応
- 将来的にインポート機能への拡張も想定される構造
- サーバー同期が無効の場合はローカルデータのみエクスポート

---

## コードリーディングガイド

本帳票を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、プログラム間で受け渡されるデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | UserDataExportCache.swift | `Wikipedia/Code/UserDataExportCache.swift` | UserDataExportSyncInfo構造体を理解 |

**読解のコツ**: Codableプロトコルに準拠した構造体で、JSONエンコード/デコードが可能。4つのプロパティの役割を把握する。

#### Step 2: データ構造の詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | UserDataExportCache.swift | `Wikipedia/Code/UserDataExportCache.swift` 行1-17 | 構造体定義とイニシャライザ |

**主要処理フロー**:
- **行5**: public struct UserDataExportSyncInfo: Codable宣言
- **行6**: serverReadingLists - APIReadingList配列
- **行7**: serverReadingListEntries - APIReadingListEntry配列
- **行8**: appSettingsSyncSavedArticlesAndLists - 同期設定
- **行9**: appSettingsShowSavedReadingList - 表示設定
- **行11-16**: public init - 全フィールドを引数とするイニシャライザ

### プログラム呼び出し階層図

```
HelpViewController / SettingsViewController
    │
    ├─ データエクスポートリクエスト
    │
    ├─ ReadingListsSyncOperation (参考)
    │      │
    │      ├─ API呼び出し
    │      │     ├─ /api/rest_v1/data/lists
    │      │     └─ /api/rest_v1/data/lists/{id}/entries
    │      │
    │      └─ APIReadingList, APIReadingListEntry取得
    │
    ├─ アプリ設定取得
    │      ├─ syncSavedArticlesAndLists
    │      └─ showSavedReadingList
    │
    ├─ UserDataExportSyncInfo構築
    │      │
    │      └─ init(serverReadingLists:serverReadingListEntries:
    │             appSettingsSyncSavedArticlesAndLists:
    │             appSettingsShowSavedReadingList:)
    │
    └─ JSONEncoder.encode()
           │
           └─ JSON Data出力
```

### データフロー図

```
[入力]                     [処理]                           [出力]

MediaWiki API ──────────▶ データ収集                      JSON Data
  │                            │
  ├─ /data/lists               │
  │     └─ APIReadingList[]    │
  │                            │
  └─ /data/lists/{id}/entries  │
        └─ APIReadingListEntry[]
                               │
UserDefaults ──────────────────┤
  │                            │
  ├─ syncSavedArticlesAndLists │
  └─ showSavedReadingList      │
                               ▼
                    UserDataExportSyncInfo
                               │
                               ├─ serverReadingLists
                               ├─ serverReadingListEntries
                               ├─ appSettingsSyncSavedArticlesAndLists
                               └─ appSettingsShowSavedReadingList
                                    │
                                    ▼
                              JSONEncoder
                                    │
                                    ▼
                              JSON Data
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| UserDataExportCache.swift | `Wikipedia/Code/` | ソース | エクスポートデータ構造定義 |
| ReadingList+JSON.swift | `WMF Framework/` | ソース | APIReadingList定義（参考） |
| ReadingListEntry+JSON.swift | `WMF Framework/` | ソース | APIReadingListEntry定義（参考） |
| HelpViewController.swift | `Wikipedia/Code/` | ソース | エクスポート機能呼び出し元 |
