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

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/technical/api-contracts.md, docs/technical/persistence-and-migrations.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-20260413-04

• Date: 2026-04-13
• Author: GitHub Copilot

Change Summary

• 삭제 예정인 상위 docs 경로를 technical 문서 경로로 정리했다.

Intent

• 구현 추적 문서가 삭제 후에도 유효한 참조를 유지하도록 하기 위함이다.

Acceptance Criteria Delta

• Added:
  • 없음
• Updated:
  • Impacted Area의 docs 경로를 docs/technical/ 기준으로 갱신
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/SRS/Interface/REQ-001_portfolio-comment-history.md
  • docs/technical/api-contracts.md
  • docs/technical/persistence-and-migrations.md
• Modules:
  • 없음
• Tests:
  • 없음

Validation Plan

• 삭제 대상 문서 제거 후에도 REQ-001의 구현 추적 문서 링크가 모두 유효한지 확인한다.

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:
  • docs/technical/api-contracts.md
  • docs/technical/persistence-and-migrations.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 마이그레이션 및 저장소 테스트로 별도 테이블 저장과 조회 일관성을 검증한다.