add docs/SRS/Interface/REQ-001_portfolio-comment-history.md

docs/SRS/Interface/REQ-001_portfolio-comment-history.md

@@ -0,0 +1,149 @@
+# REQ-001: 포트폴리오 댓글형 메모 이력 지원
+
+- Status: Approved
+- Type: Interface
+- Priority: Medium
+- Owner: Justin
+
+## Intent
+- 사용자가 각 `portfolio`에 대해 사람이 읽고 쓰는 메모를 이력 형태로 남기고 열람할 수 있도록 한다.
+- 단일 `note` 필드가 아니라 여러 건의 댓글형 기록을 지원하여 운용 맥락과 판단 근거를 보존한다.
+
+## Requirement
+- 시스템은 각 포트폴리오에 대해 댓글형 메모 이력을 저장·조회·수정·삭제할 수 있어야 한다.
+- 시스템은 포트폴리오 메모 이력을 메인 포트폴리오 레코드와 분리된 **별도 테이블**에 저장해야 한다.
+- 시스템은 HTTP API와 CLI를 통해 동일한 포트폴리오 메모 이력 기능을 제공해야 한다.
+- 각 메모 이력 항목은 최소한 고유 식별자, 연결된 `portfolio_id`, 본문 내용, 생성 시각, 수정 시각을 포함해야 한다.
+- 시스템은 특정 포트폴리오의 메모 이력을 다른 포트폴리오와 구분하여 조회해야 하며, 조회 결과는 최신 생성 시각 기준 내림차순으로 반환되어야 한다.
+- 시스템은 메모 생성·수정·삭제 요청에 대해 기존 포트폴리오 접근 권한 정책을 적용해야 하며, 인증 실패 또는 권한 부족 시 기존 인증 오류 계약에 따라 요청을 거부해야 한다.
+- 시스템은 사용자가 입력한 메모 본문에 대해 애플리케이션 정의 최대 길이 제한으로 입력을 차단하지 않아야 하며, 일반적인 다중 라인 텍스트를 저장·조회할 수 있어야 한다.
+- 시스템은 존재하지 않는 `portfolio_id` 또는 `comment_id`를 대상으로 한 요청에 대해 Not Found 오류를 반환해야 한다.
+- 시스템은 메모 삭제 후 해당 항목이 후속 조회 결과에 더 이상 노출되지 않도록 해야 한다.
+
+## Acceptance Criteria
+1. Given 기존 포트폴리오가 존재하고 권한이 있는 사용자가 API 또는 CLI로 메모를 생성할 때, When 메모 본문을 제출하면, Then 시스템은 별도 포트폴리오 메모 테이블에 새 항목을 저장하고 생성된 메모의 식별자와 타임스탬프를 포함한 결과를 반환해야 한다.
+2. Given 특정 포트폴리오에 메모가 2건 이상 존재할 때, When 사용자가 API 또는 CLI로 메모 이력을 조회하면, Then 시스템은 해당 포트폴리오에 속한 메모만 반환해야 하며 각 항목의 `id`, `content`, `created_at`, `updated_at`를 포함하고 최신 생성 시각 기준으로 정렬되어야 한다.
+3. Given 기존 메모 항목이 존재할 때, When 사용자가 API 또는 CLI로 메모 본문을 수정하면, Then 시스템은 동일한 메모 식별자를 유지한 채 본문과 `updated_at`를 갱신하고 후속 조회에서 수정된 내용을 반환해야 한다.
+4. Given 기존 메모 항목이 존재할 때, When 사용자가 API 또는 CLI로 해당 메모를 삭제하면, Then 시스템은 성공 응답을 반환하고 이후 동일 포트폴리오 메모 이력 조회 결과에서 해당 항목을 노출하지 않아야 한다.
+5. Given 사용자가 장문의 다중 라인 텍스트 메모를 입력할 때, When API 또는 CLI를 통해 생성 또는 수정을 요청하면, Then 시스템은 애플리케이션 정의 최대 길이 제한 오류 없이 해당 내용을 저장하고 조회 시 동일 텍스트를 반환해야 한다.
+6. Given 인증되지 않았거나 해당 포트폴리오 메모에 접근 권한이 없는 사용자가 API 또는 CLI로 조회·생성·수정·삭제를 시도할 때, When 요청을 전송하면, Then 시스템은 기존 인증/인가 계약에 따라 `401` 또는 `403` 응답을 반환하고 메모 데이터를 변경하지 않아야 한다.
+7. Given 존재하지 않는 `portfolio_id` 또는 `comment_id`가 요청에 포함될 때, When 사용자가 API 또는 CLI로 조회·수정·삭제를 시도하면, Then 시스템은 `404` 응답 또는 이에 대응하는 CLI 오류를 반환하고 새로운 메모를 생성하거나 기존 데이터를 변경하지 않아야 한다.
+
+## Impacted Area
+- Docs: `docs/portfoliohub-spec.md`, `docs/api-examples.md`, `docs/db-schema-spec.md`, `docs/SRS/index.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`, `migrations/versions/*`
+- Tests: `tests/test_app.py`, `tests/test_cli.py`, `tests/test_domain_services.py`
+
+## Notes
+- 본 초안은 메모가 **사용자가 기록하고 열람하는 용도**임을 전제로 한다.
+- 조회/생성/수정/삭제 권한은 기존 포트폴리오 접근 권한 정책을 재사용한다.
+- 삭제의 내부 구현은 hard delete 또는 soft delete 중 선택 가능하되, 외부 계약상 삭제된 메모는 후속 조회에 노출되지 않아야 한다.
+
+## Change Log
+
+### CHG-20260410-03
+- Date: 2026-04-10
+- Author: GitHub Copilot
+
+#### Change Summary
+- Owner 지정과 문서 리뷰 완료를 근거로 `REQ-001` 상태를 `Approved`로 전환했다.
+
+#### Intent
+- 구현 착수 전 기준 requirement로 승인 상태를 명확히 하기 위함이다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - 없음
+- Updated:
+  - 없음
+- Removed:
+  - 없음
+
+#### Impacted Area Delta
+- Docs:
+  - `docs/SRS/Interface/REQ-001_portfolio-comment-history.md`
+  - `docs/SRS/index.md`
+  - `docs/SRS/traceability-matrix.md`
+- Modules:
+  - 없음
+- Tests:
+  - 없음
+
+#### Validation Plan
+- SRS index와 traceability matrix에서 `REQ-001` 상태가 `Approved`로 일치하는지 확인한다.
+
+### CHG-20260410-02
+- Date: 2026-04-10
+- Author: GitHub Copilot
+
+#### Change Summary
+- requirement 품질 검토 결과를 반영해 권한, 오류 응답, 정렬 규칙, 경로 표기를 구체화했다.
+
+#### Intent
+- acceptance criteria를 더 test 가능하게 만들고 모호한 표현을 줄이기 위함이다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - 인증/인가 실패 시 거부 동작
+  - 존재하지 않는 포트폴리오/메모에 대한 오류 응답
+  - 조회 정렬 규칙
+- Updated:
+  - 메모 길이 제한 표현을 애플리케이션 정의 제한 기준으로 명확화
+- Removed:
+  - 없음
+
+#### Impacted Area Delta
+- Docs:
+  - `docs/SRS/Interface/REQ-001_portfolio-comment-history.md`
+- Modules:
+  - 없음
+- Tests:
+  - 추후 API/CLI 권한 및 오류 케이스 테스트 추가 필요
+
+#### Validation Plan
+- REQ 문서 리뷰 시 각 acceptance criterion이 단일 테스트 케이스로 변환 가능한지 확인한다.
+- 권한/오류/정렬 규칙이 구현 테스트 항목으로 직접 추적 가능한지 확인한다.
+
+### CHG-20260410-01
+- Date: 2026-04-10
+- Author: GitHub Copilot
+
+#### Change Summary
+- 포트폴리오별 댓글형 메모 이력 기능에 대한 신규 SRS requirement 초안을 작성했다.
+
+#### Intent
+- 사용자 관찰 가능한 API/CLI 계약과 데이터 저장 요구를 명확히 정의하기 위함이다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - API/CLI를 통한 메모 생성, 조회, 수정, 삭제 요구
+  - 별도 테이블 저장 요구
+  - 애플리케이션 레벨 길이 제한 없음 요구
+- Updated:
+  - 없음
+- Removed:
+  - 없음
+
+#### Impacted Area Delta
+- Docs:
+  - portfoliohub-spec.md
+  - api-examples.md
+  - db-schema-spec.md
+  - `docs/SRS/index.md`
+- Modules:
+  - portfolios.py
+  - portfolio.py
+  - portfolio.py
+  - portfolio_service.py
+  - portfolio_repository.py
+  - postgres.py
+  - `migrations/versions/*`
+- Tests:
+  - test_app.py
+  - test_cli.py
+  - test_domain_services.py
+
+#### Validation Plan
+- API 테스트로 메모 CRUD 및 포트폴리오별 조회 격리를 검증한다.
+- CLI 테스트로 동일 기능의 입력/출력 계약을 검증한다.
+- DB 마이그레이션 및 저장소 테스트로 별도 테이블 저장과 조회 일관성을 검증한다.

docs/SRS/index.md

@@ -0,0 +1,39 @@
+# PortfolioHub SRS Index
+
+이 문서는 `docs/SRS/` 하위 requirement 문서의 운영 기준과 등록 현황을 관리한다.
+
+## Requirement 작성 규칙
+- Requirement 하나당 문서 하나를 사용한다.
+- 새 requirement ID의 source of truth는 이 문서의 `Next Requirement ID`다.
+- Type 분류는 주된 사용자/외부 계약을 기준으로 결정한다.
+  - `Interface`: API, CLI, UI 등 사용자가 직접 조작하거나 호출하는 방식
+  - `Data`: 저장 구조, 스키마, 데이터 형식 자체가 핵심 제약인 경우
+  - `Exception & Error Handling`: 오류 응답, 복구, 재시도 전략이 핵심인 경우
+  - 그 외는 관련 운영 기준에 따라 적절한 Type을 선택한다.
+- 각 requirement는 최소한 `Status`, `Type`, `Priority`, `Owner`, `Intent`, `Requirement`, `Acceptance Criteria`, `Impacted Area`, `Change Log`를 포함해야 한다.
+- 새 requirement가 추가되면 `Requirement Register`와 `Next Requirement ID`를 함께 갱신한다.
+- 최근 변경 요약은 최신 항목을 위에 두고 최대 5건만 유지한다.
+
+## Next Requirement ID
+- `REQ-002`
+
+## 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` |
+
+## Recent Change Log Summary
+- 2026-04-10 — `REQ-001` 상태를 `Approved`로 전환했다.
+- 2026-04-10 — `REQ-001`에 권한, 오류 응답, 정렬 규칙, testable acceptance criteria를 보강했다.
+- 2026-04-10 — `REQ-001` 초안을 추가해 포트폴리오 댓글형 메모 이력의 API/CLI 계약과 별도 테이블 저장 요구를 정의했다.
+
+## Status Transition Evidence
+- `Proposed` → `Approved`: Owner가 지정되고 requirement 문서 리뷰가 완료되며 acceptance criteria가 누락 없이 검토되어야 한다.
+- `Approved` → `Implemented`: 구현 코드가 병합되고 관련 문서 및 테스트 경로가 requirement 또는 traceability matrix에 연결되어야 한다.
+- `Implemented` → `Verified`: 자동 테스트 또는 수동 검증 evidence가 확인되어야 한다.
+- `Verified` → `Released`: 배포 또는 릴리스 노트 반영 evidence가 확인되어야 한다.
+
+## Related Documents
+- Requirement files: `docs/SRS/<Type>/REQ-XXX_<slug>.md`
+- Traceability matrix: `docs/SRS/traceability-matrix.md`

docs/SRS/traceability-matrix.md

@@ -0,0 +1,20 @@
+# SRS Traceability Matrix
+
+## Status Definition
+- Planned: Requirement is defined but not yet implemented.
+- In Progress: Implementation issue/PR exists and work is ongoing.
+- Implemented: Code is merged and mapped acceptance criteria are complete.
+- Verified: Required tests and manual checks are completed.
+- Released: Included in a released version.
+
+## Matrix
+
+| 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 |
+
+## Update Rules
+- REQ ID must exactly match the SRS requirement file prefix.
+- AC Mapping should reference concrete IDs such as `AC1`, `AC2`.
+- Test Evidence should point to executable artifacts such as test file paths, CI runs, or manual verification notes.
+- Use `TBD` where implementation or verification evidence does not yet exist.