feat: 태그 HTTP API(BAT-004) 및 pfhub tag CLI + baseline 문서 갱신(BAT-005)

BAT-004 (REQ-004, REQ-005): - app/api/v1_tags.py: POST /v1/tags, GET /v1/tags, PATCH /v1/tags/{id}/deactivate - app/api/v1_portfolios.py: POST/DELETE /v1/portfolios/{id}/tags - app/api/v1_assets.py: POST/DELETE /v1/assets/{id}/tags 엔드포인트 추가 - app/schemas/v1.py: TagItem, TagCreateRequest, TagListResponse, TagApplyRequest/Response 추가 - app/repositories/portfolio_repository.py, postgres.py: append/remove_portfolio_tag_id 추가 - app/main.py: v1_portfolios_router, v1_tags_router 등록 - tests/test_tags_http_api.py: 22개 HTTP API 테스트 BAT-005 (REQ-007, REQ-008): - app/cli/commands/tag.py: pfhub tag create/list/deactivate/apply/remove 7개 커맨드 신규 - app/cli/main.py: tag_app 등록 - app/cli/commands/portfolio.py: pfhub portfolio tag add/list/remove 완전 제거(breaking change) - app/cli/core/utils.py: print_tag_table + list[Tag] render 분기 추가 - tests/test_tags_cli.py: REQ-007 AC-1~9 커버 24개 CLI 테스트 신규 - tests/test_cli.py: 제거된 portfolio tag 테스트 2개 삭제 - docs/data-model.md, interface-contract.md, project-structure.md, runtime-flows.md: 태그 모델 baseline 갱신(REQ-008) - docs/batches/: BAT-004, BAT-005 전체 산출물(release-candidate) 247 passed Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-20 01:16:13 +00:00
parent 158929b2d9
commit d4b841bc37
29 changed files with 2216 additions and 89 deletions
@@ -16,6 +16,8 @@ from app.schemas.v1 import (
    AssetCatalogUpdateRequest,
    AssetItem,
    AssetsResponse,
+    TagApplyRequest,
+    TagApplyResponse,
    TagRefItem,
 )

@@ -206,6 +208,65 @@ def deactivate_catalog_asset(
    return _asset_response(asset)


+@router.post("/assets/{asset_id}/tags", response_model=TagApplyResponse)
+def apply_asset_tag(
+    asset_id: str,
+    body: TagApplyRequest,
+    auth: AuthContext = Depends(require_admin),
+) -> TagApplyResponse:
+    if auth.token_source != "db":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="DB token required")
+    repo = _get_repo()
+    try:
+        try:
+            repo.get(asset_id)
+        except ValueError:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"asset을 찾을 수 없습니다: {asset_id}")
+
+        tag = repo.get_tag_by_id(body.tag_id)
+        if tag is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"태그를 찾을 수 없습니다: {body.tag_id}")
+        if not tag.is_admin_tag:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="admin 생성 태그만 asset에 적용할 수 있습니다")
+        if not tag.is_active:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="비활성화된 태그는 적용할 수 없습니다")
+
+        repo.append_portfolio_tag_id(asset_id, body.tag_id)
+    except HTTPException:
+        raise
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+    finally:
+        if callable(getattr(type(repo), "close", None)):
+            repo.close()
+    return TagApplyResponse(tag_id=body.tag_id, status="applied")
+
+
+@router.delete("/assets/{asset_id}/tags/{tag_id}", response_model=TagApplyResponse)
+def remove_asset_tag(
+    asset_id: str,
+    tag_id: str,
+    auth: AuthContext = Depends(require_admin),
+) -> TagApplyResponse:
+    if auth.token_source != "db":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="DB token required")
+    repo = _get_repo()
+    try:
+        try:
+            repo.get(asset_id)
+        except ValueError:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"asset을 찾을 수 없습니다: {asset_id}")
+        repo.remove_portfolio_tag_id(asset_id, tag_id)
+    except HTTPException:
+        raise
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+    finally:
+        if callable(getattr(type(repo), "close", None)):
+            repo.close()
+    return TagApplyResponse(tag_id=tag_id, status="removed")
+
+
@router.patch("/assets/{asset_id}", response_model=AssetCatalogResponse)
 def update_catalog_asset(
    asset_id: str,
@@ -0,0 +1,93 @@
+"""v1 portfolio tag endpoints — apply and remove tags (REQ-005)."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from app.core.auth import AuthContext, Permission, require_trade_write
+from app.repositories.factory import get_portfolio_repository_from_settings
+from app.schemas.v1 import TagApplyRequest, TagApplyResponse
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/v1/portfolios", tags=["v1"])
+
+
+def _get_repo(settings=None):
+    from app.core.config import get_settings
+    return get_portfolio_repository_from_settings(settings or get_settings())
+
+
+def _close_repo(repo) -> None:
+    if callable(getattr(type(repo), "close", None)):
+        repo.close()
+
+
+@router.post("/{portfolio_id}/tags", response_model=TagApplyResponse)
+def apply_portfolio_tag(
+    portfolio_id: str,
+    body: TagApplyRequest,
+    auth: AuthContext = Depends(require_trade_write),
+) -> TagApplyResponse:
+    if auth.token_source != "db":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="DB token required")
+    repo = _get_repo()
+    try:
+        try:
+            portfolio = repo.get(portfolio_id)
+        except ValueError:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"portfolio를 찾을 수 없습니다: {portfolio_id}")
+
+        is_admin = auth.permission == Permission.ADMIN
+        is_owner = portfolio.owner_user_id == auth.user_id
+        if not is_admin and not is_owner:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Portfolio ownership mismatch")
+
+        tag = repo.get_tag_by_id(body.tag_id)
+        if tag is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"태그를 찾을 수 없습니다: {body.tag_id}")
+
+        if not tag.is_active:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="비활성화된 태그는 적용할 수 없습니다")
+        if not is_admin and not tag.is_admin_tag and tag.created_by_user_id != portfolio.owner_user_id:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="태그 적용 정책을 위반했습니다")
+
+        repo.append_portfolio_tag_id(portfolio_id, body.tag_id)
+    except HTTPException:
+        raise
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+    finally:
+        _close_repo(repo)
+    return TagApplyResponse(tag_id=body.tag_id, status="applied")
+
+
+@router.delete("/{portfolio_id}/tags/{tag_id}", response_model=TagApplyResponse)
+def remove_portfolio_tag(
+    portfolio_id: str,
+    tag_id: str,
+    auth: AuthContext = Depends(require_trade_write),
+) -> TagApplyResponse:
+    if auth.token_source != "db":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="DB token required")
+    repo = _get_repo()
+    try:
+        try:
+            portfolio = repo.get(portfolio_id)
+        except ValueError:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"portfolio를 찾을 수 없습니다: {portfolio_id}")
+
+        is_admin = auth.permission == Permission.ADMIN
+        is_owner = portfolio.owner_user_id == auth.user_id
+        if not is_admin and not is_owner:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Portfolio ownership mismatch")
+
+        repo.remove_portfolio_tag_id(portfolio_id, tag_id)
+    except HTTPException:
+        raise
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+    finally:
+        _close_repo(repo)
+    return TagApplyResponse(tag_id=tag_id, status="removed")
@@ -0,0 +1,108 @@
+"""v1 tag master endpoints — create, list, deactivate (REQ-004)."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app.core.auth import AuthContext, Permission, require_read, require_trade_write
+from app.repositories.factory import get_portfolio_repository_from_settings
+from app.schemas.v1 import TagCreateRequest, TagItem, TagListResponse
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/v1", tags=["v1"])
+
+
+def _get_repo(settings=None):
+    from app.core.config import get_settings
+    return get_portfolio_repository_from_settings(settings or get_settings())
+
+
+def _close_repo(repo) -> None:
+    if callable(getattr(type(repo), "close", None)):
+        repo.close()
+
+
+def _tag_to_item(tag) -> TagItem:
+    return TagItem(
+        tag_id=str(tag.tag_id),
+        name=tag.name,
+        is_admin_tag=tag.is_admin_tag,
+        is_active=tag.is_active,
+        created_at=tag.created_at,
+    )
+
+
+@router.post("/tags", response_model=TagItem, status_code=201)
+def create_tag(
+    body: TagCreateRequest,
+    auth: AuthContext = Depends(require_trade_write),
+) -> TagItem:
+    if auth.token_source != "db":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="DB token required")
+    if auth.user_id is None:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="user_id required")
+    repo = _get_repo()
+    try:
+        name = body.name.strip().lower()
+        is_admin_tag = auth.permission == Permission.ADMIN
+        tag = repo.create_tag(name=name, created_by_user_id=auth.user_id, is_admin_tag=is_admin_tag)
+    except ValueError as exc:
+        if "이미 존재하는 태그 이름입니다" in str(exc):
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(exc)) from exc
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+    finally:
+        _close_repo(repo)
+    return _tag_to_item(tag)
+
+
+@router.get("/tags", response_model=TagListResponse)
+def list_tags(
+    is_active: bool | None = Query(default=None),
+    auth: AuthContext = Depends(require_read),
+) -> TagListResponse:
+    if auth.token_source != "db":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="DB token required")
+    repo = _get_repo()
+    try:
+        if is_active is False:
+            all_tags = repo.list_tags_master(include_inactive=True)
+            tags = [t for t in all_tags if not t.is_active]
+        else:
+            tags = repo.list_tags_master(include_inactive=False)
+    finally:
+        _close_repo(repo)
+    items = [_tag_to_item(t) for t in tags]
+    return TagListResponse(tags=items, total=len(items))
+
+
+@router.patch("/tags/{tag_id}/deactivate", response_model=TagItem)
+def deactivate_tag(
+    tag_id: str,
+    auth: AuthContext = Depends(require_read),
+) -> TagItem:
+    if auth.token_source != "db":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="DB token required")
+    repo = _get_repo()
+    try:
+        tag = repo.get_tag_by_id(tag_id)
+        if tag is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"태그를 찾을 수 없습니다: {tag_id}",
+            )
+        is_admin = auth.permission == Permission.ADMIN
+        is_creator = tag.created_by_user_id == auth.user_id
+        if not is_admin and not is_creator:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="권한이 없습니다")
+        if not tag.is_active:
+            return _tag_to_item(tag)
+        result = repo.deactivate_tag(tag_id)
+    except HTTPException:
+        raise
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+    finally:
+        _close_repo(repo)
+    return _tag_to_item(result)