docs: add portfolio tagging SRS requirement

2026-04-10 14:45:03 +00:00
parent 3b9c2010ce
commit b69d2faba8
3 changed files with 130 additions and 1 deletions
@@ -0,0 +1,125 @@
+# REQ-002: 포트폴리오 태깅 및 태그 기반 검색 지원
+
+- Status: Proposed
+- Type: Interface
+- Priority: Medium
+- Owner: Justin
+
+## Intent
+- 사용자가 각 `portfolio`에 의미 있는 태그를 부여하고, 특정 태그가 포함된 포트폴리오를 빠르게 검색할 수 있도록 한다.
+- API와 CLI에서 동일한 태깅 계약을 제공하여 운용 자동화와 수동 조회 흐름을 모두 지원한다.
+
+## Requirement
+- 시스템은 각 포트폴리오에 대해 하나 이상의 태그를 추가하고 제거할 수 있어야 한다.
+- 시스템은 HTTP API와 CLI를 통해 동일한 포트폴리오 태깅 기능을 제공해야 한다.
+- 시스템은 둘 이상의 태그를 조건으로 포트폴리오를 검색할 수 있어야 하며, 검색 요청에서 `AND` 또는 `OR` 매칭 방식을 선택할 수 있어야 한다.
+- 시스템은 공백만으로 이루어지지 않은 태그 문자열을 추가 대상으로 받아들여야 한다.
+- 시스템은 동일 포트폴리오에 이미 연결된 동일한 태그 문자열을 다시 추가하려는 요청에 대해 `409 Conflict` 또는 이에 대응하는 CLI 오류를 반환해야 하며, 기존 태그 상태를 변경하지 않아야 한다.
+- 시스템은 태그 추가·삭제·검색 요청에 대해 기존 포트폴리오 접근 권한 정책을 적용해야 하며, 인증 실패 또는 권한 부족 시 기존 인증 오류 계약에 따라 요청을 거부해야 한다.
+- 시스템은 존재하지 않는 `portfolio_id`를 대상으로 한 태그 추가·삭제 요청에 대해 Not Found 오류를 반환해야 한다.
+- 시스템은 태그 검색 결과에서 각 포트폴리오를 중복 없이 한 번만 반환해야 한다.
+- 시스템은 태그 문자열 길이 또는 포트폴리오당 태그 개수에 대해 애플리케이션 정의 최대 제한만을 이유로 요청을 거부하지 않아야 한다.
+
+## Acceptance Criteria
+1. Given 기존 포트폴리오가 존재하고 권한이 있는 사용자가 API 또는 CLI로 새 태그를 추가할 때, When 공백만으로 이루어지지 않은 태그 문자열을 제출하면, Then 시스템은 해당 포트폴리오에 태그를 연결하고 후속 조회에서 그 태그가 포함된 상태를 반환해야 한다.
+2. Given 특정 포트폴리오에 이미 연결된 태그가 있을 때, When 사용자가 API 또는 CLI로 해당 태그를 제거하면, Then 시스템은 성공 응답을 반환하고 후속 조회 및 태그 검색 결과에서 그 연결을 노출하지 않아야 한다.
+3. Given 여러 포트폴리오에 서로 다른 태그 조합이 연결되어 있을 때, When 사용자가 API 또는 CLI로 둘 이상의 태그와 `AND` 모드를 지정해 검색하면, Then 시스템은 요청한 모든 태그를 포함한 포트폴리오만 반환해야 한다.
+4. Given 여러 포트폴리오에 서로 다른 태그 조합이 연결되어 있을 때, When 사용자가 API 또는 CLI로 둘 이상의 태그와 `OR` 모드를 지정해 검색하면, Then 시스템은 요청한 태그 중 하나 이상을 포함한 포트폴리오를 반환해야 한다.
+5. Given 동일 포트폴리오에 이미 동일한 태그 문자열이 존재할 때, When 사용자가 API 또는 CLI로 같은 태그를 다시 추가하면, Then 시스템은 `409 Conflict` 응답 또는 이에 대응하는 CLI 오류를 반환하고 중복 태그 연결을 생성하지 않아야 한다.
+6. Given 인증되지 않았거나 해당 포트폴리오에 접근 권한이 없는 사용자가 API 또는 CLI로 태그 추가·삭제·검색을 시도할 때, When 요청을 전송하면, Then 시스템은 기존 인증/인가 계약에 따라 `401` 또는 `403` 응답을 반환하고 태그 상태를 변경하지 않아야 한다.
+7. Given 존재하지 않는 `portfolio_id`가 요청에 포함될 때, When 사용자가 API 또는 CLI로 태그 추가 또는 삭제를 시도하면, Then 시스템은 `404` 응답 또는 이에 대응하는 CLI 오류를 반환하고 어떤 태그 연결도 생성·변경하지 않아야 한다.
+8. Given 포트폴리오에 이미 여러 태그가 연결되어 있고 사용자가 긴 태그 문자열을 추가할 때, When API 또는 CLI로 태그 추가를 요청하면, Then 시스템은 애플리케이션 정의 최대 길이 제한 또는 최대 개수 제한만을 이유로 요청을 거부하지 않아야 한다.
+9. Given `OR` 모드의 다중 태그 검색에서 하나의 포트폴리오가 두 개 이상의 요청 태그와 동시에 일치할 때, When 사용자가 검색을 수행하면, Then 시스템은 해당 포트폴리오를 결과에 한 번만 반환해야 한다.
+
+## Impacted Area
+- Docs: `docs/portfoliohub-spec.md`, `docs/api-examples.md`, `docs/db-schema-spec.md`, `docs/SRS/index.md`, `docs/SRS/traceability-matrix.md`
+- Modules: `app/api/portfolios.py`, `app/cli/commands/portfolio.py`, `app/schemas/portfolio.py`, `app/services/portfolio_service.py`, `app/repositories/portfolio_repository.py`, `app/repositories/postgres.py`, `app/domain/models.py`, `migrations/versions/*`
+- Tests: `tests/test_app.py`, `tests/test_cli.py`, `tests/test_domain_services.py`
+
+## Notes
+- 본 requirement의 검색 범위는 다중 태그 검색을 포함하며, 호출자는 `AND` 또는 `OR` 모드를 선택할 수 있다.
+- 태그 최대 길이와 포트폴리오당 최대 태그 개수에 대한 애플리케이션 정의 상한은 두지 않는다.
+- 동일 포트폴리오에 같은 태그 문자열을 다시 추가하는 요청은 `409 Conflict` 또는 이에 대응하는 CLI 오류로 처리한다.
+
+## Change Log
+
+### CHG-20260410-02
+- Date: 2026-04-10
+- Author: GitHub Copilot
+
+#### Change Summary
+- 다중 태그 `AND`/`OR` 검색, 중복 추가 시 `409 Conflict`, 태그 길이/개수 상한 없음 계약을 REQ-002에 반영했다.
+
+#### Intent
+- 검토 피드백과 owner 결정을 반영해 모호한 인터페이스 계약을 test 가능하게 확정하기 위함이다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - 다중 태그 `AND` 검색 결과 규칙
+  - 다중 태그 `OR` 검색 결과 규칙
+  - 중복 태그 추가 시 `409 Conflict` 처리
+  - 태그 길이/개수 상한 없음 검증 기준
+- Updated:
+  - 태그 입력 유효성 표현을 공백이 아닌 문자열 기준으로 명확화
+  - `Impacted Area` 경로 표기를 repository-relative path로 정리
+- Removed:
+  - 단일 태그 검색 assumption
+
+#### Impacted Area Delta
+- Docs:
+  - `docs/SRS/Interface/REQ-002_portfolio-tagging-and-search.md`
+  - `docs/SRS/index.md`
+  - `docs/SRS/traceability-matrix.md`
+- Modules:
+  - 없음
+- Tests:
+  - 추후 API/CLI 다중 태그 검색 및 중복 충돌 테스트 추가 필요
+
+#### Validation Plan
+- 문서 리뷰 시 다중 태그 `AND`/`OR` 검색, 중복 추가 `409 Conflict`, 태그 길이/개수 상한 없음 조건이 각각 독립 테스트로 매핑 가능한지 확인한다.
+
+### CHG-20260410-01
+- Date: 2026-04-10
+- Author: GitHub Copilot
+
+#### Change Summary
+- 포트폴리오 태깅 및 태그 기반 검색 기능에 대한 신규 SRS requirement 초안을 작성했다.
+
+#### Intent
+- 사용자 관찰 가능한 API/CLI 계약과 검색 동작을 명확히 정의하기 위함이다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - API/CLI를 통한 태그 추가 및 제거 요구
+  - 특정 태그 기반 포트폴리오 검색 요구
+  - 중복 태그 방지, 권한 검증, Not Found 오류 처리 요구
+- Updated:
+  - 없음
+- Removed:
+  - 없음
+
+#### Impacted Area Delta
+- Docs:
+  - portfoliohub-spec.md
+  - api-examples.md
+  - db-schema-spec.md
+  - index.md
+  - traceability-matrix.md
+- Modules:
+  - portfolios.py
+  - portfolio.py
+  - portfolio.py
+  - portfolio_service.py
+  - portfolio_repository.py
+  - postgres.py
+  - models.py
+  - `migrations/versions/*`
+- Tests:
+  - test_app.py
+  - test_cli.py
+  - test_domain_services.py
+
+#### Validation Plan
+- API 테스트로 태그 추가/삭제 및 태그 기반 검색 계약을 검증한다.
+- CLI 테스트로 동일 기능의 입력/출력 계약을 검증한다.
+- 저장소 및 서비스 테스트로 중복 태그 방지와 포트폴리오별 태그 연결 일관성을 검증한다.
@@ -15,15 +15,18 @@
 - 최근 변경 요약은 최신 항목을 위에 두고 최대 5건만 유지한다.

 ## Next Requirement ID
- `REQ-002`
+- `REQ-003`

 ## Requirement Register

 | REQ ID | Title | Type | Status | Priority | Owner | File |
 |---|---|---|---|---|---|---|
 | REQ-001 | 포트폴리오 댓글형 메모 이력 지원 | Interface | Approved | Medium | Justin | `docs/SRS/Interface/REQ-001_portfolio-comment-history.md` |
+| REQ-002 | 포트폴리오 태깅 및 태그 기반 검색 지원 | Interface | Proposed | Medium | Justin | `docs/SRS/Interface/REQ-002_portfolio-tagging-and-search.md` |

 ## Recent Change Log Summary
+- 2026-04-10 — `REQ-002`에 다중 태그 `AND`/`OR` 검색, 중복 추가 `409 Conflict`, 태그 길이/개수 상한 없음 계약을 반영했다.
+- 2026-04-10 — `REQ-002` 초안을 추가해 포트폴리오 태깅과 태그 기반 검색의 API/CLI 계약을 정의했다.
 - 2026-04-10 — `REQ-001` 상태를 `Approved`로 전환했다.
 - 2026-04-10 — `REQ-001`에 권한, 오류 응답, 정렬 규칙, testable acceptance criteria를 보강했다.
 - 2026-04-10 — `REQ-001` 초안을 추가해 포트폴리오 댓글형 메모 이력의 API/CLI 계약과 별도 테이블 저장 요구를 정의했다.
@@ -12,6 +12,7 @@
 | REQ ID | AC Mapping | Requirement File | Implementation Issue | PR | Test Evidence | Requirement Status | Delivery Status | Last Updated |
 |---|---|---|---|---|---|---|---|---|
 | REQ-001 | AC1, AC2, AC3, AC4, AC5, AC6, AC7 | `docs/SRS/Interface/REQ-001_portfolio-comment-history.md` | #2 | TBD | TBD | Approved | In Progress | 2026-04-10 |
+| REQ-002 | AC1, AC2, AC3, AC4, AC5, AC6, AC7, AC8, AC9 | `docs/SRS/Interface/REQ-002_portfolio-tagging-and-search.md` | TBD | TBD | TBD | Proposed | Planned | 2026-04-10 |

 ## Update Rules
 - REQ ID must exactly match the SRS requirement file prefix.