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>

docs/interface-contract.md

@@ -4,8 +4,8 @@
 - Baseline Seed: .stagepilot/bootstrap/baseline.yaml
 - Status: confirmed
 - Owner: repository-maintainers
-- Last Updated (KST): 2026-05-13 00:00
-- Source Discovery / Batch: bootstrap-baseline, bat-001, bat-006, bat-008, bat-010
+- Last Updated (KST): 2026-05-20 00:00
+- Source Discovery / Batch: bootstrap-baseline, bat-001, bat-006, bat-008, bat-010, bat-003, bat-004, bat-005
 - Primary Runtime: mixed
 
 ## Project Summary
@@ -69,10 +69,11 @@
 
 ### Inputs
 
-- pfhub subcommands :: include user, portfolio, strategy, service-token, daemon, credential, health-check, init-db, and migrate-db command families
+- pfhub subcommands :: include user, portfolio, strategy, tag, service-token, daemon, credential, health-check, init-db, and migrate-db command families
 - Flags and options :: include --format table|json, --force confirmations, and operation-specific mutation arguments
 - Environment configuration :: app/core/config.py resolves PORTFOLIOHUB_* and TIMESCALEDB_* values before command execution
-- Portfolio identification (bat-006) :: all portfolio mutation commands accept `<name>` (positional) + `--user <username>` instead of raw portfolio_id; `comment` and `tag` sub-commands still accept portfolio_id (UUID) directly
+- Portfolio identification (bat-006) :: all portfolio mutation commands accept `<name>` (positional) + `--user <username>` instead of raw portfolio_id; `comment` sub-commands accept portfolio_id (UUID) directly
+- Tag commands (bat-005) :: `pfhub tag create/list/deactivate/apply/remove` operate on the tags master table; `pfhub portfolio tag add/list/remove` has been removed (breaking change)
 
 ### Outputs
 
@@ -274,6 +275,72 @@
 - After BAT-006, all `asset_id` values in GET /v1/assets responses change from TEXT to UUID format.
 - trex-basic consumers must handle UUID-format asset_id before the coordinated deployment is completed.
 
+## Interface: `Tag Management API (BAT-004)`
+
+- Type: http-api
+- Consumers / Producers: authenticated operators and admin services
+- Purpose: manage tag master records and apply/remove tags on assets and portfolios
+- Stability: internal (versioned under /v1)
+
+### Authentication
+
+- All /v1/tags, /v1/assets/{id}/tags, /v1/portfolios/{id}/tags endpoints require `Authorization: Bearer <token>`.
+- Token must be DB-issued (`token_source="db"`); env tokens rejected with HTTP 403.
+
+### Endpoint: `POST /v1/tags`
+
+- Auth: DB token required; trade-write or admin permission
+- Body: `{"name": "<str>"}` (min_length=1; normalized to lowercase + stripped)
+- Response: HTTP 201 `TagItem` `{"tag_id": "<uuid>", "name": "<str>", "is_admin_tag": <bool>, "is_active": true, "created_at": "<ISO8601|null>"}`
+- is_admin_tag is set to true when caller has admin permission; false for trade-write
+- Error: HTTP 409 if tag name already exists; HTTP 403 if env token
+
+### Endpoint: `GET /v1/tags`
+
+- Auth: DB token required; read permission
+- Query Params: `?include_inactive=true` (default false — returns only active tags)
+- Response: HTTP 200 `TagListResponse` `{"tags": [TagItem], "total": <int>}`
+- Error: HTTP 403 if env token
+
+### Endpoint: `PATCH /v1/tags/{tag_id}/deactivate`
+
+- Auth: DB token required; read permission (admin or tag creator)
+- Path Param: `tag_id` — must be a valid tag UUID
+- Body: none
+- Response: HTTP 200 `TagItem` with `is_active=false`; idempotent (already-inactive returns 200 immediately)
+- Error: HTTP 404 if tag not found; HTTP 403 if caller is not admin and not tag creator
+
+### Endpoint: `POST /v1/assets/{asset_id}/tags`
+
+- Auth: DB token required; admin permission
+- Path Param: `asset_id` — maps to portfolio_id (v1 convention: asset_id = portfolio_id)
+- Body: `{"tag_id": "<uuid>"}`
+- Response: HTTP 200 `TagApplyResponse` `{"tag_id": "<uuid>", "status": "applied"}`
+- Policy: tag must have is_admin_tag=true AND is_active=true; non-admin-tag → HTTP 403; inactive → HTTP 403
+- Error: HTTP 404 if asset or tag not found; HTTP 403 if policy violation or env token
+
+### Endpoint: `DELETE /v1/assets/{asset_id}/tags/{tag_id}`
+
+- Auth: DB token required; admin permission
+- Body: none
+- Response: HTTP 200 `TagApplyResponse` `{"tag_id": "<uuid>", "status": "removed"}`
+- Error: HTTP 404 if asset not found; HTTP 403 if not admin or env token
+
+### Endpoint: `POST /v1/portfolios/{portfolio_id}/tags`
+
+- Auth: DB token required; trade-write or admin permission
+- Body: `{"tag_id": "<uuid>"}`
+- Response: HTTP 200 `TagApplyResponse` `{"tag_id": "<uuid>", "status": "applied"}`
+- Policy: tag must have is_active=true; caller must be portfolio owner or admin; non-admin non-owner-created tag → HTTP 403
+- Error: HTTP 404 if portfolio or tag not found; HTTP 403 if policy violation or env token
+
+### Endpoint: `DELETE /v1/portfolios/{portfolio_id}/tags/{tag_id}`
+
+- Auth: DB token required; trade-write or admin permission
+- Body: none
+- Response: HTTP 200 `TagApplyResponse` `{"tag_id": "<uuid>", "status": "removed"}`
+- Error: HTTP 404 if portfolio not found; HTTP 403 if caller is not owner or admin
+
 ## Shared Constraints
 
 - Token permission levels gate both HTTP and CLI mutations consistently.
@@ -294,6 +361,7 @@
 
 ## Change Log
 
+- 2026-05-20 KST: bat-005 — REQ-008 AC-2: added Tag Management API section (POST/GET/PATCH /v1/tags, POST/DELETE /v1/assets/{id}/tags, POST/DELETE /v1/portfolios/{id}/tags); updated CLI surface (pfhub tag, removed pfhub portfolio tag); updated CLI inputs.
 - 2026-05-19 KST: bat-002 — REQ-010/012/013/015: added admin catalog endpoints (POST/PATCH /v1/assets, PATCH /v1/assets/{id}/deactivate); rewrote GET /v1/assets authentication to support service/user/admin token branching; added market filter param; removed market field from AssetItem; added AssetCatalogResponse schema.
 - 2026-05-13 KST: bat-010 — REQ-006/007/008/011/023: added daemon authorization model section; updated GET /v1/assets (daemon-scoped filter, NULL 403); updated GET /v1/user_info (daemon_id field, NULL runtime_id → 200+null diagnostic); updated POST /v1/assets/{asset_id}/ledger/trades (daemon assignment authorization, fail-closed policy); added daemon CLI subcommand to CLI surface; updated v1 purpose and source discovery.
 - 2026-05-11 KST: bat-008 — REQ-011 AC-1: expanded v1 Consumer API section with authentication contract, detailed request/response schemas for GET /v1/assets, GET /v1/user_info, POST /v1/assets/{asset_id}/ledger/trades; updated GET /health response schema (REQ-004); added idempotency contract.