first commit

backend/app/application/admin/__init__.py

@@ -0,0 +1 @@
+"""Admin application services."""

backend/app/application/admin/activity.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any
+
+from app.repositories.directus.activity import DirectusActivityRepository
+from app.repositories.directus.variants import VariantRepository
+from app.repositories.directus.releases import ReleaseRepository
+
+ACTION_LABELS: dict[str, str] = {
+    "create": "建立",
+    "update": "更新",
+    "delete": "刪除",
+}
+
+COLLECTION_LABELS: dict[str, str] = {
+    "experiments": "實驗設定",
+    "variants": "變體",
+    "experiment_releases": "版本",
+    "variant_changes": "視覺變更",
+}
+
+
+class ActivityService:
+    def __init__(
+        self,
+        activity_repository: DirectusActivityRepository | None = None,
+        variant_repository: VariantRepository | None = None,
+        release_repository: ReleaseRepository | None = None,
+    ) -> None:
+        self.activity_repo = activity_repository or DirectusActivityRepository()
+        self.variant_repo = variant_repository or VariantRepository()
+        self.release_repo = release_repository or ReleaseRepository()
+
+    async def list_for_experiment(
+        self,
+        experiment_id: str,
+        access_token: str | None = None,
+    ) -> list[dict[str, Any]]:
+        # Collect all item IDs related to this experiment
+        item_ids: list[str] = [experiment_id]
+
+        variants = await self.variant_repo.list(
+            params={"filter[experiment_id][_eq]": experiment_id, "fields": "id"},
+            access_token=access_token,
+        )
+        variant_ids = [str(v["id"]) for v in variants]
+        item_ids.extend(variant_ids)
+
+        releases = await self.release_repo.list(
+            params={"filter[experiment_id][_eq]": experiment_id, "fields": "id"},
+            access_token=access_token,
+        )
+        release_ids = [str(r["id"]) for r in releases]
+        item_ids.extend(release_ids)
+
+        raw_entries = await self.activity_repo.list_for_items(
+            item_ids=item_ids,
+            access_token=access_token,
+        )
+
+        result = []
+        for entry in raw_entries:
+            action = str(entry.get("action", ""))
+            collection = str(entry.get("collection", ""))
+            user = entry.get("user") or {}
+            actor_email = user.get("email") if isinstance(user, dict) else None
+            actor_id = user.get("id") if isinstance(user, dict) else str(user) if user else None
+
+            result.append({
+                "id": entry.get("id"),
+                "action": action,
+                "action_label": ACTION_LABELS.get(action, action),
+                "collection": collection,
+                "collection_label": COLLECTION_LABELS.get(collection, collection),
+                "item": str(entry.get("item", "")),
+                "timestamp": entry.get("timestamp"),
+                "actor_email": actor_email,
+                "actor_id": actor_id,
+            })
+
+        return result

backend/app/application/admin/experiments.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any
+
+from app.domain.keys import generate_experiment_key, generate_variant_key
+from app.domain.mappers import to_experiment
+from app.repositories.directus.experiments import ExperimentRepository
+from app.repositories.directus.variants import VariantRepository
+from app.schemas.admin import ExperimentCreate, ExperimentRead, ExperimentUpdate, experiment_to_read_model
+
+
+class ExperimentService:
+    """Application service for experiment use-cases.
+
+    This is where we will keep:
+    - validation
+    - permission checks
+    - state transitions
+    - orchestration before writing to Directus
+    """
+
+    def __init__(
+        self,
+        repository: ExperimentRepository | None = None,
+        variant_repository: VariantRepository | None = None,
+    ) -> None:
+        self.repository = repository or ExperimentRepository()
+        self.variant_repository = variant_repository or VariantRepository()
+
+    async def list_experiments(self, access_token: str | None = None) -> list[ExperimentRead]:
+        items = await self.repository.list(access_token=access_token)
+        return [experiment_to_read_model(to_experiment(item)) for item in items]
+
+    async def get_experiment(
+        self,
+        experiment_id: str,
+        access_token: str | None = None,
+    ) -> ExperimentRead | None:
+        item = await self.repository.get(experiment_id, access_token=access_token)
+        if not item:
+            return None
+        return experiment_to_read_model(to_experiment(item))
+
+    async def create_experiment(
+        self,
+        payload: ExperimentCreate,
+        access_token: str | None = None,
+    ) -> ExperimentRead:
+        data: dict[str, Any] = payload.model_dump(exclude_none=True)
+        data["experiment_key"] = generate_experiment_key()
+        item = await self.repository.create(data, access_token=access_token)
+        experiment = to_experiment(item)
+
+        # Auto-create 原始版本 (control) variant
+        await self.variant_repository.create(
+            {
+                "experiment_id": experiment.id,
+                "variant_key": generate_variant_key(),
+                "name": "原始版本",
+                "traffic_weight": 50,
+            },
+            access_token=access_token,
+        )
+
+        return experiment_to_read_model(experiment)
+
+    async def update_experiment(
+        self,
+        experiment_id: str,
+        payload: ExperimentUpdate,
+        access_token: str | None = None,
+    ) -> ExperimentRead | None:
+        data: dict[str, Any] = payload.model_dump(exclude_unset=True)
+        item = await self.repository.update(experiment_id, data, access_token=access_token)
+        if not item:
+            return None
+        return experiment_to_read_model(to_experiment(item))

backend/app/application/admin/goals.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+from app.domain.mappers import to_goal
+from app.repositories.directus.goals import GoalRepository
+from app.schemas.admin import GoalRead, goal_to_read_model
+
+
+class GoalService:
+    """Application service for experiment goal management."""
+
+    def __init__(self, repository: GoalRepository | None = None) -> None:
+        self.repository = repository or GoalRepository()
+
+    async def list_goals(
+        self,
+        site_id: str | None = None,
+        access_token: str | None = None,
+    ) -> list[GoalRead]:
+        params: dict[str, Any] | None = None
+        if site_id:
+            params = {"filter[site_id][_eq]": site_id}
+        items = await self.repository.list(params=params, access_token=access_token)
+        return [goal_to_read_model(to_goal(item)) for item in items]
+
+    async def get_goal(
+        self,
+        goal_id: str,
+        access_token: str | None = None,
+    ) -> GoalRead | None:
+        item = await self.repository.get(goal_id, access_token=access_token)
+        if not item:
+            return None
+        return goal_to_read_model(to_goal(item))

backend/app/application/admin/marketing_cards.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from app.repositories.directus.marketing_cards import MarketingCardRepository
+from app.schemas.marketing_card import MarketingCardRead
+
+
+class MarketingCardService:
+    """Application service for the current marketing-card module.
+
+    This keeps the legacy module reachable while frontend migration is in
+    progress. Later we can either map it into experiment/variant concepts or
+    retire it after the new module replaces it.
+    """
+
+    def __init__(self, repository: MarketingCardRepository | None = None) -> None:
+        self.repository = repository or MarketingCardRepository()
+
+    async def list_marketing_cards(self) -> list[MarketingCardRead]:
+        items = await self.repository.list()
+        return [MarketingCardRead.model_validate(item) for item in items]
+
+    async def get_marketing_card(self, card_id: str) -> MarketingCardRead | None:
+        item = await self.repository.get(card_id)
+        if not item:
+            return None
+        return MarketingCardRead.model_validate(item)
+

backend/app/application/admin/releases.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any
+
+from app.domain.editor import VariantChange
+from app.domain.editor_builder import build_runtime_payload_from_changes
+from app.domain.mappers import to_release
+from app.repositories.directus.releases import ReleaseRepository
+from app.repositories.directus.variant_changes import VariantChangeRepository
+from app.repositories.directus.variants import VariantRepository
+from app.schemas.admin import BuildReleaseRequest, ReleaseLifecycleResponse, ReleaseRead, release_to_read_model
+
+
+class ReleaseService:
+    """Application service for release and snapshot lifecycle."""
+
+    def __init__(
+        self,
+        repository: ReleaseRepository | None = None,
+        variant_repository: VariantRepository | None = None,
+        change_repository: VariantChangeRepository | None = None,
+    ) -> None:
+        self.repository = repository or ReleaseRepository()
+        self.variant_repository = variant_repository or VariantRepository()
+        self.change_repository = change_repository or VariantChangeRepository()
+
+    async def list_releases(
+        self,
+        experiment_id: str | None = None,
+        access_token: str | None = None,
+    ) -> list[ReleaseRead]:
+        params: dict[str, Any] | None = None
+        if experiment_id:
+            params = {"filter[experiment_id][_eq]": experiment_id}
+
+        items = await self.repository.list(params=params, access_token=access_token)
+        return [release_to_read_model(to_release(item)) for item in items]
+
+    async def get_release(
+        self,
+        release_id: str,
+        access_token: str | None = None,
+    ) -> ReleaseRead | None:
+        item = await self.repository.get(release_id, access_token=access_token)
+        if not item:
+            return None
+        return release_to_read_model(to_release(item))
+
+    async def build_release(
+        self,
+        payload: BuildReleaseRequest,
+        access_token: str | None = None,
+    ) -> ReleaseRead:
+        experiment_id = payload.experiment_id
+
+        # Fetch all variants for the experiment
+        variant_items = await self.variant_repository.list(
+            params={"filter[experiment_id][_eq]": experiment_id},
+            access_token=access_token,
+        )
+
+        # Build per-variant runtime payloads
+        variants_payload: list[dict[str, Any]] = []
+        for variant_item in variant_items:
+            variant_id = str(variant_item["id"])
+            change_items = await self.change_repository.list(
+                params={"filter[variant_id][_eq]": variant_id},
+                access_token=access_token,
+            )
+            changes = [
+                VariantChange(
+                    id=str(c["id"]),
+                    variant_id=variant_id,
+                    change_type=str(c.get("change_type", "")),
+                    selector_type=str(c.get("selector_type", "")),
+                    selector_value=str(c.get("selector_value", "")),
+                    sort_order=int(c.get("sort_order", 0)),
+                    payload=c.get("payload"),
+                )
+                for c in change_items
+            ]
+            runtime_payload = build_runtime_payload_from_changes(variant_id, changes)
+            variants_payload.append({
+                "variant_id": variant_id,
+                "variant_key": str(variant_item.get("variant_key", "")),
+                "traffic_weight": int(variant_item.get("traffic_weight", 0)),
+                "operations": [asdict(op) for op in runtime_payload.operations],
+            })
+
+        # Determine next version_no
+        existing = await self.repository.list(
+            params={"filter[experiment_id][_eq]": experiment_id, "sort": "-version_no", "limit": "1"},
+            access_token=access_token,
+        )
+        next_version = (int(existing[0]["version_no"]) + 1) if existing else 1
+
+        new_release = await self.repository.create(
+            {
+                "experiment_id": experiment_id,
+                "version_no": next_version,
+                "status": "draft",
+                "runtime_payload": {"variants": variants_payload},
+            },
+            access_token=access_token,
+        )
+        return release_to_read_model(to_release(new_release))
+
+    async def publish_release(
+        self,
+        release_id: str,
+        access_token: str | None = None,
+    ) -> ReleaseLifecycleResponse | None:
+        # Fetch the target release to get experiment_id
+        target = await self.repository.get(release_id, access_token=access_token)
+        if not target:
+            return None
+
+        experiment_id = str(target["experiment_id"])
+
+        # Demote any currently published release in this experiment to draft
+        currently_published = await self.repository.list(
+            params={
+                "filter[experiment_id][_eq]": experiment_id,
+                "filter[status][_eq]": "published",
+            },
+            access_token=access_token,
+        )
+        for other in currently_published:
+            if str(other["id"]) != release_id:
+                await self.repository.update(str(other["id"]), {"status": "draft"}, access_token=access_token)
+
+        item = await self.repository.update(release_id, {"status": "published"}, access_token=access_token)
+        if not item:
+            return None
+        return ReleaseLifecycleResponse(
+            id=str(item["id"]),
+            status=str(item["status"]),
+            version_no=int(item["version_no"]),
+        )
+
+    async def rollback_release(
+        self,
+        release_id: str,
+        access_token: str | None = None,
+    ) -> ReleaseLifecycleResponse | None:
+        # Fetch the target release to get experiment_id and version_no
+        target = await self.repository.get(release_id, access_token=access_token)
+        if not target:
+            return None
+
+        experiment_id = str(target["experiment_id"])
+        current_version_no = int(target["version_no"])
+
+        # Demote the current release back to draft
+        await self.repository.update(release_id, {"status": "draft"}, access_token=access_token)
+
+        # Find the most recent draft release with an earlier version_no to restore
+        previous_candidates = await self.repository.list(
+            params={
+                "filter[experiment_id][_eq]": experiment_id,
+                "filter[status][_eq]": "draft",
+                "filter[version_no][_lt]": str(current_version_no),
+                "sort": "-version_no",
+                "limit": "1",
+            },
+            access_token=access_token,
+        )
+
+        if previous_candidates:
+            restored = await self.repository.update(
+                str(previous_candidates[0]["id"]),
+                {"status": "published"},
+                access_token=access_token,
+            )
+            if restored:
+                return ReleaseLifecycleResponse(
+                    id=str(restored["id"]),
+                    status=str(restored["status"]),
+                    version_no=int(restored["version_no"]),
+                )
+
+        # No previous release to restore — return the now-drafted current release
+        updated = await self.repository.get(release_id, access_token=access_token)
+        if not updated:
+            return None
+        return ReleaseLifecycleResponse(
+            id=str(updated["id"]),
+            status=str(updated["status"]),
+            version_no=int(updated["version_no"]),
+        )
+
+    async def archive_release(
+        self,
+        release_id: str,
+        access_token: str | None = None,
+    ) -> ReleaseLifecycleResponse | None:
+        item = await self.repository.update(release_id, {"status": "archived"}, access_token=access_token)
+        if not item:
+            return None
+        return ReleaseLifecycleResponse(
+            id=str(item["id"]),
+            status=str(item["status"]),
+            version_no=int(item["version_no"]),
+        )

backend/app/application/admin/sdk_configs.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from app.domain.mappers import to_sdk_config
+from app.repositories.directus.sdk_configs import SdkConfigRepository
+from app.schemas.admin import SdkConfigRead, sdk_config_to_read_model
+
+
+class SdkConfigService:
+    """Application service for SDK config management."""
+
+    def __init__(self, repository: SdkConfigRepository | None = None) -> None:
+        self.repository = repository or SdkConfigRepository()
+
+    async def list_sdk_configs(self, access_token: str | None = None) -> list[SdkConfigRead]:
+        items = await self.repository.list(access_token=access_token)
+        return [sdk_config_to_read_model(to_sdk_config(item)) for item in items]
+
+    async def get_sdk_config(
+        self,
+        sdk_config_id: str,
+        access_token: str | None = None,
+    ) -> SdkConfigRead | None:
+        item = await self.repository.get(sdk_config_id, access_token=access_token)
+        if not item:
+            return None
+        return sdk_config_to_read_model(to_sdk_config(item))

backend/app/application/admin/sites.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from app.domain.mappers import to_site
+from app.repositories.directus.sites import SiteRepository
+from app.schemas.admin import SiteRead, site_to_read_model
+
+
+class SiteService:
+    """Application service for site administration.
+
+    Site is a good example of a content-like resource:
+    FastAPI owns orchestration, while Directus remains the audited store.
+    """
+
+    def __init__(self, repository: SiteRepository | None = None) -> None:
+        self.repository = repository or SiteRepository()
+
+    async def list_sites(self, access_token: str | None = None) -> list[SiteRead]:
+        items = await self.repository.list(access_token=access_token)
+        return [site_to_read_model(to_site(item)) for item in items]
+
+    async def get_site(
+        self,
+        site_id: str,
+        access_token: str | None = None,
+    ) -> SiteRead | None:
+        item = await self.repository.get(site_id, access_token=access_token)
+        if not item:
+            return None
+        return site_to_read_model(to_site(item))

backend/app/application/admin/variants.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException
+
+from app.domain.keys import generate_variant_key
+from app.domain.mappers import to_variant
+from app.repositories.directus.variants import VariantRepository
+from app.schemas.admin import VariantCreate, VariantRead, VariantUpdate, variant_to_read_model
+
+
+class VariantService:
+    """Application service for variant management."""
+
+    def __init__(self, repository: VariantRepository | None = None) -> None:
+        self.repository = repository or VariantRepository()
+
+    async def _assert_weights_sum_100(
+        self,
+        experiment_id: str,
+        new_weight: int,
+        exclude_variant_id: str | None = None,
+        access_token: str | None = None,
+    ) -> None:
+        items = await self.repository.list(
+            params={"filter[experiment_id][_eq]": experiment_id},
+            access_token=access_token,
+        )
+        existing_sum = sum(
+            int(item.get("traffic_weight", 0))
+            for item in items
+            if str(item["id"]) != exclude_variant_id
+        )
+        if existing_sum + new_weight != 100:
+            raise HTTPException(
+                status_code=400,
+                detail=f"所有變體的流量權重加總必須等於 100（目前其他變體合計 {existing_sum}，本次輸入 {new_weight}）",
+            )
+
+    async def list_variants(
+        self,
+        experiment_id: str | None = None,
+        access_token: str | None = None,
+    ) -> list[VariantRead]:
+        params: dict[str, Any] | None = None
+        if experiment_id:
+            params = {"filter[experiment_id][_eq]": experiment_id}
+
+        items = await self.repository.list(params=params, access_token=access_token)
+        return [variant_to_read_model(to_variant(item)) for item in items]
+
+    async def get_variant(
+        self,
+        variant_id: str,
+        access_token: str | None = None,
+    ) -> VariantRead | None:
+        item = await self.repository.get(variant_id, access_token=access_token)
+        if not item:
+            return None
+        return variant_to_read_model(to_variant(item))
+
+    async def create_variant(
+        self,
+        payload: VariantCreate,
+        access_token: str | None = None,
+    ) -> VariantRead:
+        await self._assert_weights_sum_100(
+            experiment_id=payload.experiment_id,
+            new_weight=payload.traffic_weight,
+            access_token=access_token,
+        )
+        data: dict[str, Any] = payload.model_dump(exclude_none=True)
+        data["variant_key"] = generate_variant_key()
+        item = await self.repository.create(data, access_token=access_token)
+        return variant_to_read_model(to_variant(item))
+
+    async def update_variant(
+        self,
+        variant_id: str,
+        payload: VariantUpdate,
+        access_token: str | None = None,
+    ) -> VariantRead | None:
+        data: dict[str, Any] = payload.model_dump(exclude_unset=True)
+        if "traffic_weight" in data:
+            existing = await self.repository.get(variant_id, access_token=access_token)
+            if existing:
+                await self._assert_weights_sum_100(
+                    experiment_id=str(existing["experiment_id"]),
+                    new_weight=data["traffic_weight"],
+                    exclude_variant_id=variant_id,
+                    access_token=access_token,
+                )
+        item = await self.repository.update(variant_id, data, access_token=access_token)
+        if not item:
+            return None
+        return variant_to_read_model(to_variant(item))