Merge pull request #49 from kc3hack/feature/issue-45-jsonb-migration

Backend: SkillTree.tree_dataをJSON型からJSONB型に変更

Author: Inlet-back

.github/decisions/009-database-design-strategy.md

@@ -3,6 +3,7 @@
 ## ステータス
 
 - [x] **決定**
+- [x] **更新** (2026-02-19): JSON型 → JSONB型に変更（issue #45）
 
 ## コンテキスト (課題と背景)
 
@@ -28,12 +29,18 @@ issue #31で6テーブル（Profile, OAuthAccount, Badge, Quest, QuestProgress,
 ### 2. 型選択基準
 
 #### JSON型 vs JSONB型（PostgreSQL）
-- **基本方針**: JSON型を使用（JSONB型は不要）
-- **理由**:
-  - **SkillTree.tree_data**: AI生成のツリー構造を全体として保存・取得するだけ
-  - **JSON内部の検索が不要**: 全体を読むだけ、個別ノード検索はしない
-  - **SQLiteとPostgreSQLで互換性が高い**: JSON型はどちらでも使える
-- **JSONB型を検討すべきケース**: JSON内部の特定フィールドを検索する必要が出てきたら移行
+- **基本方針**: ~~JSON型を使用（JSONB型は不要）~~ **→ JSONB型に変更（2026-02-19、issue #45）**
+- **変更理由**:
+  - **Langchain/フロントエンドとの統一的な操作**: JSONB型（バイナリ形式）で一貫した扱いが必要
+  - **テスト環境の統一**: SQLite（BLOB型）/PostgreSQL（JSONB型）両対応
+  - **将来の拡張性**: JSON内部検索の可能性を考慮
+- **実装方針**:
+  - PostgreSQL: JSONB型として保存
+  - SQLite: BLOB型として保存（JSONBのバイナリ表現）
+  - SQLAlchemyの`JSON().with_variant(JSONB, "postgresql")`で両DB対応
+- **旧方針（参考）**:
+  - ~~JSON型を使用（JSONB型は不要）~~
+  - ~~理由: AI生成のツリー構造を全体として保存・取得するだけ、JSON内部の検索が不要~~
 
 #### Enum vs 整数
 - **基本方針**: Enumは文字列型、整数は数値演算が必要な場合
@@ -102,11 +109,14 @@ issue #31で6テーブル（Profile, OAuthAccount, Badge, Quest, QuestProgress,
 ### 2. JSONB型を優先（PostgreSQL）
 
 - **Good**: JSON内部の検索が高速、GINインデックスで最適化可能
-- **Bad**:
-  - **MVP段階ではJSON内部検索が不要**（全体を読むだけ）
-  - SQLiteとの互換性が低い（SQLiteはJSONB型をサポートしない）
+- **Bad（旧判断、2026-02-19に方針転換）**:
+  - ~~MVP段階ではJSON内部検索が不要（全体を読むだけ）~~
+  - ~~SQLiteとの互換性が低い（SQLiteはJSONB型をサポートしない）~~
   - 書き込みパフォーマンスが若干劣る
-  - **却下理由**: 現時点では過剰な最適化、互換性優先
+  - ~~**却下理由**: 現時点では過剰な最適化、互換性優先~~
+- **方針転換（2026-02-19、issue #45）**:
+  - Langchain/フロントエンドとの統一的な操作のため、JSONB型（BLOB型）を採用
+  - SQLiteではBLOB型として保存することで互換性を確保
 
 ### 3. NoSQL（MongoDB等）
 

backend/alembic/versions/0002_change_tree_data_to_jsonb.py

@@ -0,0 +1,115 @@
+"""change_tree_data_to_jsonb (issue #45)
+
+Revision ID: 0002_change_tree_data_to_jsonb
+Revises: 0001_all_tables
+Create Date: 2026-02-19 14:07:37.523910
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+
+# revision identifiers, used by Alembic.
+revision: str = "0002_change_tree_data_to_jsonb"
+down_revision: Union[str, Sequence[str], None] = "0001_all_tables"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """SkillTree.tree_dataをJSON型からJSONB型(BLOB)に変更"""
+    bind = op.get_bind()
+
+    if bind.dialect.name == "postgresql":
+        # PostgreSQL: JSON型 → JSONB型に変更
+        op.alter_column(
+            "skill_trees",
+            "tree_data",
+            type_=JSONB,
+            existing_type=sa.JSON(),
+            existing_nullable=False,
+            postgresql_using="tree_data::jsonb",
+        )
+    elif bind.dialect.name == "sqlite":
+        # SQLite: JSON型(TEXT) → BLOB型に変更
+        # SQLiteではALTER COLUMNによる型変更が非対応のため、テーブル再作成が必要
+        op.execute("""
+            CREATE TABLE skill_trees_new (
+                id INTEGER NOT NULL,
+                user_id INTEGER NOT NULL,
+                category VARCHAR NOT NULL,
+                tree_data BLOB NOT NULL,
+                generated_at DATETIME,
+                PRIMARY KEY (id),
+                FOREIGN KEY(user_id) REFERENCES users (id),
+                CONSTRAINT uq_skill_tree_user_category UNIQUE (user_id, category)
+            )
+        """)
+
+        # データ移行（JSON文字列をBLOBに変換）
+        op.execute("""
+            INSERT INTO skill_trees_new (id, user_id, category, tree_data, generated_at)
+            SELECT id, user_id, category, tree_data, generated_at
+            FROM skill_trees
+        """)
+
+        # インデックスを削除
+        op.execute("DROP INDEX IF EXISTS ix_skill_trees_user_id")
+
+        # 旧テーブルを削除
+        op.execute("DROP TABLE skill_trees")
+
+        # 新テーブルをリネーム
+        op.execute("ALTER TABLE skill_trees_new RENAME TO skill_trees")
+
+        # インデックスを再作成
+        op.create_index(
+            "ix_skill_trees_user_id", "skill_trees", ["user_id"], unique=False
+        )
+
+
+def downgrade() -> None:
+    """JSONB型(BLOB)からJSON型に戻す"""
+    bind = op.get_bind()
+
+    if bind.dialect.name == "postgresql":
+        # PostgreSQL: JSONB型 → JSON型に戻す
+        op.alter_column(
+            "skill_trees",
+            "tree_data",
+            type_=sa.JSON(),
+            existing_type=JSONB,
+            existing_nullable=False,
+            postgresql_using="tree_data::json",
+        )
+    elif bind.dialect.name == "sqlite":
+        # SQLite: BLOB型 → JSON型(TEXT)に戻す
+        op.execute("""
+            CREATE TABLE skill_trees_old (
+                id INTEGER NOT NULL,
+                user_id INTEGER NOT NULL,
+                category VARCHAR NOT NULL,
+                tree_data JSON NOT NULL,
+                generated_at DATETIME,
+                PRIMARY KEY (id),
+                FOREIGN KEY(user_id) REFERENCES users (id),
+                CONSTRAINT uq_skill_tree_user_category UNIQUE (user_id, category)
+            )
+        """)
+
+        op.execute("""
+            INSERT INTO skill_trees_old (id, user_id, category, tree_data, generated_at)
+            SELECT id, user_id, category, tree_data, generated_at
+            FROM skill_trees
+        """)
+
+        op.execute("DROP INDEX IF EXISTS ix_skill_trees_user_id")
+        op.execute("DROP TABLE skill_trees")
+        op.execute("ALTER TABLE skill_trees_old RENAME TO skill_trees")
+        op.create_index(
+            "ix_skill_trees_user_id", "skill_trees", ["user_id"], unique=False
+        )

backend/app/models/skill_tree.py

@@ -9,6 +9,7 @@
     String,
     UniqueConstraint,
 )
+from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import relationship
 
 from app.db.base_class import Base
@@ -24,7 +25,8 @@ class SkillTree(Base):
     user_id = Column(Integer, ForeignKey("users.id"), nullable=False, index=True)
 
     category = Column(String, nullable=False)
-    tree_data = Column(JSON, nullable=False)
+    # SQLiteではBLOB型、PostgreSQLではJSONB型として保存（SQLAlchemyが自動変換）
+    tree_data = Column(JSON().with_variant(JSONB, "postgresql"), nullable=False)
     generated_at = Column(DateTime(timezone=True), nullable=True)
 
     user = relationship("User", back_populates="skill_trees")

backend/tests/test_crud/test_skill_tree.py

@@ -49,3 +49,44 @@ def test_update_skill_tree(db):
 
     assert updated.tree_data == tree_data
     assert updated.generated_at is not None
+
+
+def test_skill_tree_jsonb_data_persistence(db):
+    """JSONB型（PostgreSQL）/BLOB型（SQLite）でのデータ保存・取得テスト (issue #45)"""
+    user = create_user(db, UserCreate(username="jsonb_test_user"))
+
+    # 複雑なJSONデータを挿入
+    complex_tree_data = {
+        "nodes": [
+            {
+                "id": "react",
+                "name": "React",
+                "level": 5,
+                "skills": ["hooks", "context", "redux"],
+                "metadata": {"experience_years": 3, "certified": True},
+            },
+            {
+                "id": "typescript",
+                "name": "TypeScript",
+                "level": 4,
+                "skills": ["generics", "decorators"],
+                "metadata": {"experience_years": 2, "certified": False},
+            },
+        ],
+        "edges": [{"from": "typescript", "to": "react", "weight": 0.8}],
+        "statistics": {"total_nodes": 2, "max_level": 5, "avg_level": 4.5},
+    }
+
+    # データを挿入
+    updated = update_skill_tree(db, user.id, SkillCategory.WEB, complex_tree_data)
+    assert updated.tree_data == complex_tree_data
+
+    # データベースから再取得して確認（JSONB/BLOBの読み書きが正しく動作するか）
+    retrieved = get_skill_tree_by_user_category(db, user.id, SkillCategory.WEB)
+    assert retrieved is not None
+    assert retrieved.tree_data == complex_tree_data
+
+    # ネストされたデータの検証
+    assert retrieved.tree_data["nodes"][0]["metadata"]["experience_years"] == 3
+    assert retrieved.tree_data["nodes"][1]["skills"] == ["generics", "decorators"]
+    assert retrieved.tree_data["statistics"]["avg_level"] == 4.5