diff --git a/docs/SRS/Interface/REQ-002_portfolio-tagging-and-search.md b/docs/SRS/Interface/REQ-002_portfolio-tagging-and-search.md new file mode 100644 index 0000000..2607df1 --- /dev/null +++ b/docs/SRS/Interface/REQ-002_portfolio-tagging-and-search.md @@ -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 테스트로 동일 기능의 입력/출력 계약을 검증한다. +- 저장소 및 서비스 테스트로 중복 태그 방지와 포트폴리오별 태그 연결 일관성을 검증한다. \ No newline at end of file diff --git a/docs/SRS/index.md b/docs/SRS/index.md index 851fb49..03619b4 100644 --- a/docs/SRS/index.md +++ b/docs/SRS/index.md @@ -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 계약과 별도 테이블 저장 요구를 정의했다. diff --git a/docs/SRS/traceability-matrix.md b/docs/SRS/traceability-matrix.md index bf086e6..4096fdc 100644 --- a/docs/SRS/traceability-matrix.md +++ b/docs/SRS/traceability-matrix.md @@ -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.