From 0d658191d1e356c89945fa647de42a2e659e24a4 Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Fri, 10 Apr 2026 15:09:43 +0000 Subject: [PATCH] docs: add portfolio field schema requirement --- .../Data/REQ-003_portfolio-required-fields.md | 115 ++++++++++++++++++ docs/SRS/index.md | 7 +- docs/SRS/traceability-matrix.md | 1 + 3 files changed, 120 insertions(+), 3 deletions(-) create mode 100644 docs/SRS/Data/REQ-003_portfolio-required-fields.md diff --git a/docs/SRS/Data/REQ-003_portfolio-required-fields.md b/docs/SRS/Data/REQ-003_portfolio-required-fields.md new file mode 100644 index 0000000..b67e658 --- /dev/null +++ b/docs/SRS/Data/REQ-003_portfolio-required-fields.md @@ -0,0 +1,115 @@ +# REQ-003: 포트폴리오 필수 필드 및 거래소/시장 데이터 정의 + +- Status: Proposed +- Type: Data +- Priority: Medium +- Owner: Justin + +## Intent +- `portfolio` 데이터가 운용 및 검색 맥락에서 일관되게 해석될 수 있도록 필수 필드와 저장 규칙을 명확히 정의한다. +- 종목 이름, 심볼, 거래소, 시장 정보를 표준화된 스키마로 관리하여 API, CLI, DB 간 데이터 계약 불일치를 줄인다. + +## Requirement +- 시스템은 신규로 생성되거나 수정되는 각 `portfolio` 레코드에 대해 `name`, `symbol`, `exchange`, `market` 필드를 데이터 계약상 포함해야 한다. +- 시스템은 `name`과 `symbol`을 각 포트폴리오의 식별 및 표시를 위한 기본 필드로 유지해야 한다. +- 시스템은 `exchange` 필드에서 하나 이상의 거래소 문자열을 표현할 수 있어야 하며, 단일 포트폴리오에 복수 거래소가 연결될 수 있어야 한다. +- 시스템은 `exchange` 값을 특정 enum으로 제한하지 않아야 하며, 공백이 아닌 임의 문자열 값을 저장할 수 있어야 한다. +- 시스템은 `market` 값을 특정 enum으로 제한하지 않아야 하며, 공백이 아닌 임의 문자열 값을 저장할 수 있어야 한다. +- 시스템은 복수 거래소 지원을 위해 `exchange`를 복수 문자열을 표현할 수 있는 데이터 구조로 저장해야 한다. +- 시스템은 기존 `portfolio` 레코드에 `exchange` 또는 `market` 값이 누락되어 있더라도 마이그레이션 과정에서 `NULL` 또는 빈 문자열(`""`)로 보정할 수 있어야 한다. +- 시스템은 필수 필드 계약이 추가된 이후에도 기존 레코드 조회가 실패하지 않도록 하위 호환성을 유지해야 한다. + +## Acceptance Criteria +1. Given 새 포트폴리오 레코드가 생성되거나 기존 포트폴리오가 수정될 때, When 시스템이 데이터를 저장하면, Then 해당 레코드는 `name`, `symbol`, `exchange`, `market` 필드를 포함하는 구조로 저장되거나 반환되어야 한다. +2. Given 하나의 포트폴리오가 `KRX`, `NXT`, `SOR`와 같은 여러 거래소 문자열을 가질 때, When 시스템이 해당 포트폴리오를 저장하거나 조회하면, Then `exchange` 필드는 복수 문자열을 보존할 수 있어야 한다. +3. Given 사용자가 enum에 없는 새로운 거래소 문자열 또는 시장 문자열을 제공할 때, When 시스템이 이를 저장하면, Then 시스템은 값 목록 제한만을 이유로 해당 값을 거부하지 않아야 한다. +4. Given 기존 포트폴리오 레코드에 `exchange` 또는 `market` 값이 없는 상태에서 스키마가 적용될 때, When 마이그레이션 또는 후속 조회가 수행되면, Then 시스템은 누락 값을 `NULL` 또는 빈 문자열(`""`)로 처리하고 레코드 조회를 실패시키지 않아야 한다. +5. Given 기존 포트폴리오 레코드가 이미 `name`과 `symbol`을 포함하고 있을 때, When 새 필드 계약이 적용된 후 데이터를 조회하면, Then 기존 `name`과 `symbol` 값은 변경되지 않고 그대로 반환되어야 한다. + +## Impacted Area +- Docs: `docs/db-schema-spec.md`, `docs/portfoliohub-spec.md`, `docs/api-examples.md`, `docs/SRS/index.md`, `docs/SRS/traceability-matrix.md` +- Modules: `app/domain/models.py`, `app/schemas/portfolio.py`, `app/repositories/portfolio_repository.py`, `app/repositories/postgres.py`, `app/services/portfolio_service.py`, `migrations/versions/*` +- Tests: `tests/test_app.py`, `tests/test_domain_services.py` + +## Notes +- Assumption: 복수 거래소 지원은 별도 정규화 테이블보다 `exchange` 배열 컬럼이 현재 범위에 더 단순하고 적합한 권장 방식이다. +- 신규 생성/수정 계약에서는 `name`, `symbol`, `exchange`, `market` 필드를 모두 포함하되, 기존 데이터 호환성을 위해 레거시 레코드의 누락 신규 필드는 `NULL` 또는 `""`로 허용한다. +- `exchange`와 `market`은 허용값 enum을 두지 않고 자유 문자열로 저장한다. + +## Change Log + +### CHG-20260410-02 +- Date: 2026-04-10 +- Author: GitHub Copilot + +#### Change Summary +- `REQ-003`에 신규 입력 계약과 레거시 호환성 규칙을 분리해 명확화하고, impacted path 표기를 정리했다. + +#### Intent +- requirement 검토 피드백을 반영해 필수 필드 의미와 하위 호환성 범위를 test 가능하게 구분하기 위함이다. + +#### Acceptance Criteria Delta +- Added: + - 신규 생성/수정 시 필드 포함 요구를 명확히 한 저장 기준 +- Updated: + - `exchange` 저장 표현을 복수 문자열 데이터 구조 기준으로 일반화 + - `Impacted Area` 경로를 repository-relative path로 정리 + - 레거시 레코드의 `NULL`/`""` 허용 범위를 하위 호환성 규칙으로 명시 +- Removed: + - 없음 + +#### Impacted Area Delta +- Docs: + - `docs/SRS/Data/REQ-003_portfolio-required-fields.md` + - `docs/SRS/index.md` + - `docs/SRS/traceability-matrix.md` +- Modules: + - 없음 +- Tests: + - 추후 schema compatibility 및 migration regression 테스트 추가 필요 + +#### Validation Plan +- 문서 리뷰 시 신규 생성/수정 계약과 레거시 호환성 계약이 각각 독립 acceptance criterion으로 추적 가능한지 확인한다. + +### CHG-20260410-01 +- Date: 2026-04-10 +- Author: GitHub Copilot + +#### Change Summary +- 포트폴리오 필수 필드와 복수 거래소/시장 데이터 계약에 대한 신규 SRS requirement 초안을 작성했다. + +#### Intent +- `portfolio` 데이터 구조에 대한 필수 필드와 하위 호환성 기준을 명확히 정의하기 위함이다. + +#### Acceptance Criteria Delta +- Added: + - `name`, `symbol`, `exchange`, `market` 필드 정의 요구 + - 복수 거래소 저장 요구 + - 자유 문자열 허용 요구 + - 기존 레코드의 `NULL`/`""` 보정 및 조회 호환성 요구 +- Updated: + - 없음 +- Removed: + - 없음 + +#### Impacted Area Delta +- Docs: + - db-schema-spec.md + - portfoliohub-spec.md + - api-examples.md + - index.md + - traceability-matrix.md +- Modules: + - models.py + - portfolio.py + - portfolio_repository.py + - postgres.py + - portfolio_service.py + - `migrations/versions/*` +- Tests: + - test_app.py + - test_domain_services.py + +#### Validation Plan +- 스키마 리뷰 시 `exchange` 복수 값 저장 방식과 `market` 자유 문자열 저장 규칙이 문서와 구현 테스트에 직접 매핑되는지 확인한다. +- 마이그레이션 검토 시 기존 레코드의 누락 필드가 `NULL` 또는 `""` 처리로 조회 호환성을 유지하는지 확인한다. \ No newline at end of file diff --git a/docs/SRS/index.md b/docs/SRS/index.md index 03619b4..78f3898 100644 --- a/docs/SRS/index.md +++ b/docs/SRS/index.md @@ -15,7 +15,7 @@ - 최근 변경 요약은 최신 항목을 위에 두고 최대 5건만 유지한다. ## Next Requirement ID -- `REQ-003` +- `REQ-004` ## Requirement Register @@ -23,13 +23,14 @@ |---|---|---|---|---|---|---| | 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` | +| REQ-003 | 포트폴리오 필수 필드 및 거래소/시장 데이터 정의 | Data | Proposed | Medium | Justin | `docs/SRS/Data/REQ-003_portfolio-required-fields.md` | ## Recent Change Log Summary +- 2026-04-10 — `REQ-003`에 신규 입력 계약과 레거시 호환성 규칙을 분리해 반영했다. +- 2026-04-10 — `REQ-003` 초안을 추가해 포트폴리오 필수 필드와 거래소/시장 데이터 계약을 정의했다. - 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 계약과 별도 테이블 저장 요구를 정의했다. ## Status Transition Evidence - `Proposed` → `Approved`: Owner가 지정되고 requirement 문서 리뷰가 완료되며 acceptance criteria가 누락 없이 검토되어야 한다. diff --git a/docs/SRS/traceability-matrix.md b/docs/SRS/traceability-matrix.md index 4096fdc..c5f0978 100644 --- a/docs/SRS/traceability-matrix.md +++ b/docs/SRS/traceability-matrix.md @@ -13,6 +13,7 @@ |---|---|---|---|---|---|---|---|---| | 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 | +| REQ-003 | AC1, AC2, AC3, AC4, AC5 | `docs/SRS/Data/REQ-003_portfolio-required-fields.md` | TBD | TBD | TBD | Proposed | Planned | 2026-04-10 | ## Update Rules - REQ ID must exactly match the SRS requirement file prefix.