fix: resolve SRS conflicts from batch verification analysis (CONFLICT-1~4)

Conflict Resolutions: - CONFLICT-1 (High): Fix REQ-006 ownership scope — implement owner_user_id filtering * Change app/api/v1_assets.py: owner_user_id=None → owner_user_id=auth.user_id * Update docs/runtime-flows.md to reflect service-token owner-scoped portfolio filtering * Add regression test in tests/test_v1.py for ownership boundary - CONFLICT-2 (Medium): Transition REQ-001/002/003 to Implemented * REQ-001: local-db-validation-scenarios (via confirm-req-implemented bat-007) * REQ-002: alembic-runtime-schema-ownership (via confirm-req-implemented bat-007) * REQ-003: local-db-operations-runbook-and-baseline-updates (via confirm-req-implemented bat-007) * Update docs/srs/index.md with status transitions - CONFLICT-3 (Low): Document REQ-012 rotate lifecycle * Add rotate lifecycle notes to REQ-012 (change-req req-012) * Clarify runtime_id change behavior and trex-basic reconnection requirements - CONFLICT-4 (Low): Clarify REQ-005 AC-2 endpoint path * Change REQ-005 AC-2: 'POST /auth/tokens or equivalent' → 'POST /auth/service-tokens' * Update docs/srs/index.md change log with change-req entries Documentation Updates: - Update BAT-001 verification status with conflict resolution evidence - Update release rel-001 with verified status confirmation - Add change log entries for all conflict resolutions with dates and references Testing: - Add ownership boundary test to test_v1.py - Verify filter works with auth.user_id context
2026-05-11 11:57:21 +00:00
parent 829629fa8f
commit a5b5e7a93c
12 changed files with 251 additions and 24 deletions
@@ -1,6 +1,6 @@
 # req-003: 로컬 DB 운영 runbook 및 baseline 문서 갱신

- Status: Approved
+- Status: Implemented
 - Type: Documentation
 - Priority: Medium
 - Owner: repository-maintainers
@@ -29,6 +29,35 @@

 ## Change Log

+### CHG-20260511-01
+- Date: 2026-05-11
+- Author: repository-maintainers
+
+#### Change Summary
+- Implemented 전환 — BAT-007 verification passed, confirm-req-implemented 게이트 통과
+
+#### Intent
+- BAT-007 verification.md AC-1~3 모두 PASS. Blocking Issues 없음. README.md "Local DB Validation Runbook"(rollback 판단 기준, release gate criteria 포함), docs/project-structure.md "Schema Ownership Boundary", docs/runtime-flows.md 흐름 갱신 evidence 연결 확인 완료.
+
+#### Acceptance Criteria Delta
+- none
+
+#### Impacted Area Delta
+- none
+
+#### Delivery Trace Delta
+- Batches: BAT-007 (release-candidate)
+- Releases: none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: implemented
+- Follow-up Action: draft-release (BAT-007)
+
+#### Validation Plan
+- BAT-007 verification.md AC-1~3 evidence 연결 확인 완료
+
 ### CHG-20260430-02
 - Date: 2026-04-30
 - Author: GitHub Copilot
@@ -16,7 +16,7 @@

 ## Acceptance Criteria
 1. Given `pfhub service-token issue <name> --user <username>` 실행 시, When 발급이 성공하면, Then 출력에 token 문자열과 runtime_id가 모두 포함되어야 한다.
-2. Given API 엔드포인트(POST /auth/tokens 또는 동등 경로)로 service-token 발급 시, When 성공 응답을 받으면, Then 응답 JSON에 token과 runtime_id가 포함되어야 한다.
+2. Given API 엔드포인트(POST /auth/service-tokens)로 service-token 발급 시, When 성공 응답을 받으면, Then 응답 JSON에 token과 runtime_id가 포함되어야 한다.
 3. Given runtime_id가 발급된 service-token으로 GET /v1/user_info를 호출하면, Then 응답의 runtime_id가 발급 시 생성된 값과 동일해야 한다.
 4. Given 동일 사용자에 대해 두 번의 service-token 발급을 수행하면, Then 각각 다른 runtime_id가 반환되어야 한다.
 5. Given auth_tokens 테이블을 직접 조회하면, Then 발급된 service-token 행에 runtime_id 값이 저장되어 있어야 한다.
@@ -34,6 +34,47 @@

 ## Change Log

+### CHG-20260511-02
+- Date: 2026-05-11
+- Author: repository-maintainers
+
+#### Change Summary
+- REQ-005 AC-2의 API 경로를 실제 구현 경로인 `POST /auth/service-tokens`로 명확화
+
+#### Intent
+- CONFLICT-4 분석 결과를 반영해 "POST /auth/tokens 또는 동등 경로"라는 모호한 표현을 제거하고, BAT-001 verification과 runtime flow에 이미 반영된 실제 엔드포인트로 REQ를 정렬한다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - none
+- Updated:
+  - AC-2: API 발급 경로를 `POST /auth/service-tokens`로 구체화
+- Removed:
+  - none
+
+#### Impacted Area Delta
+- Docs:
+  - `docs/srs/Interface/req-005_service-token-runtime-id-issuance.md`: AC-2 경로 문구 명확화
+- Modules:
+  - none
+- Tests:
+  - none
+
+#### Delivery Trace Delta
+- Batches:
+  - BAT-001 (release-candidate) — verification evidence는 이미 `POST /auth/service-tokens` 기준으로 정렬되어 있어 추가 재검증은 불필요
+- Releases:
+  - REL-001 (draft) — release scope 문서도 동일 경로를 사용 중이라 추가 수정 없음
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: none
+
+#### Validation Plan
+- REQ-005 AC-2, BAT-001 verification evidence, runtime-flows.md의 API 경로가 모두 `POST /auth/service-tokens`로 일치하는지 코드 리뷰로 확인
+
 ### CHG-20260511-01
 - Date: 2026-05-11
 - Author: repository-maintainers
@@ -10,13 +10,13 @@
 - asset_id는 기존 portfolio_id를 그대로 사용하며 별도 식별자 체계를 만들지 않는다(A-3).

 ## Requirement
- GET /v1/assets는 service-token bearer 인증으로 토큰 소유자의 portfolio 목록을 asset_id, symbol, market, status, cash, quantity, broker_type, strategy_id, strategy_type, strategy_params, updated_at 필드로 반환해야 한다.
+- GET /v1/assets는 service-token bearer 인증으로 토큰 소유자의 portfolio 목록만 asset_id, symbol, market, status, cash, quantity, broker_type, strategy_id, strategy_type, strategy_params, updated_at 필드로 반환해야 한다. 다른 사용자 소유 portfolio는 응답에 포함되면 안 된다.
 - status=active 쿼리 파라미터로 필터링이 가능해야 한다.
 - strategy_params는 해당 portfolio의 active_strategy_id로 조회한 StrategySet.config에서 파생한다. strategy_id는 허용값 검증 없이 그대로 반환한다(OQ-1 Answered).
 - strategy_type은 해당 portfolio의 active_strategy_id로 조회한 StrategySet.name을 반환한다. active_strategy_id가 없거나 StrategySet 조회 실패 시 null을 반환한다.

 ## Acceptance Criteria
-1. Given 유효한 service-token bearer 인증으로 GET /v1/assets 요청 시, When 토큰이 유효하면, Then HTTP 200과 해당 사용자 소유 portfolio 목록이 반환되어야 한다.
+1. Given 유효한 service-token bearer 인증으로 GET /v1/assets 요청 시, When 토큰이 유효하면, Then HTTP 200과 해당 사용자 소유 portfolio 목록만 반환되어야 하며 다른 사용자 소유 portfolio는 포함되면 안 된다.
 2. Given GET /v1/assets?status=active 요청 시, Then status가 active인 항목만 반환되어야 한다.
 3. Given 응답의 각 항목을 확인하면, Then asset_id, symbol, market, status, cash, quantity, broker_type, strategy_id, strategy_type, strategy_params, updated_at 필드가 모두 포함되어야 한다.
 4. Given portfolio에 연결된 StrategySet이 있을 때, When strategy_params를 확인하면, Then StrategySet.config 값에서 파생된 JSON 객체여야 한다.
@@ -29,7 +29,7 @@
 ## Impacted Area
 - Docs: docs/interface-contract.md (REQ-011에서 갱신 예정), docs/project-structure.md (신규 라우터 파일 반영 필요)
 - Modules: app/api/v1_assets.py (신규), app/services/ (assets 조회 서비스 메서드 추가), app/schemas/ (v1 assets 응답 스키마 추가), app/repositories/postgres.py (portfolio + strategy_set JOIN 쿼리 추가), app/main.py (/v1 라우터 등록)
- Tests: tests/test_v1_assets.py (신규)
+- Tests: tests/test_v1.py (GET /v1/assets 관련 케이스 및 owner scope 회귀 검증)

 ## Notes
 - broker_type은 portfolios.broker 컬럼을 그대로 매핑한다(m-2 finding 반영).
@@ -39,6 +39,49 @@

 ## Change Log

+### CHG-20260511-02
+- Date: 2026-05-11
+- Author: repository-maintainers
+
+#### Change Summary
+- owner scope 회귀 수정 반영 — GET /v1/assets는 service-token 소유자의 portfolio만 반환함을 REQ와 verification evidence에 명시
+
+#### Intent
+- CONFLICT-1 분석 결과와 2026-05-11 사용자 결정에 따라 trex-basic은 전체 사용자의 portfolio를 조회하면 안 되며, 서비스 토큰 소유자 범위로만 조회되어야 한다는 설계를 REQ 본문과 검증 기준에 명확히 남긴다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - none
+- Updated:
+  - AC1: 반환 범위를 "해당 사용자 소유 portfolio 목록만"으로 명확화하고, 다른 사용자 소유 portfolio 비포함 조건을 추가
+- Removed:
+  - none
+
+#### Impacted Area Delta
+- Docs:
+  - docs/batches/bat-001_20260502_trex-basic-v1-api-contract/verification.md: REQ-006 AC1 evidence를 owner scope 기준으로 재정렬
+- Modules:
+  - app/api/v1_assets.py: `owner_user_id=auth.user_id` 적용으로 owner scope 강제
+- Tests:
+  - tests/test_v1.py: `test_v1_assets_returns_asset_list`에 `owner_user_id="user-1"` 전달 assert 추가
+
+#### Delivery Trace Delta
+- Batches:
+  - BAT-001 (release-candidate) — REQ-006 targeted re-verification 필요 및 evidence 갱신
+- Releases:
+  - REL-001 (draft) — release 입력 전 owner scope 기준 반영 여부 재확인 필요
+
+#### Revalidation Impact
+- Reverification Needed: yes
+- Existing Implementation Invalidated: yes
+- Status Recommendation: keep-current
+- Follow-up Action: owner scope 수정 코드와 targeted pytest 재실행 결과를 BAT-001 verification에 반영하고 Implemented 상태 유지
+
+#### Validation Plan
+- `app/api/v1_assets.py`에서 `owner_user_id=auth.user_id` 적용 여부 확인
+- `tests/test_v1.py -k 'v1_assets'` 재실행으로 GET /v1/assets 회귀 테스트 PASS 확인
+- BAT-001 verification.md의 REQ-006 AC1 evidence를 최신 테스트와 맞춤
+
 ### CHG-20260511-01
 - Date: 2026-05-11
 - Author: repository-maintainers
@@ -9,7 +9,7 @@

 - 발급된 service-token의 원문이 노출되었거나 주기적 교체가 필요한 경우, token을 revoke 없이 in-place로 갱신할 수 있는 CLI 명령이 필요하다.
 - 기존 `revoke → re-issue` 방식은 `token_id`, `user_id`, `permission`, `expires_at`, `created_at` 등 메타데이터가 변경되므로, 운영 시스템에서 동일한 이름으로 참조하는 통합 구성을 다시 설정해야 하는 불편이 있다.
- rotate는 `token_hash`, `token_prefix`, `runtime_id`만 교체하고 나머지 메타데이터를 유지하여, 통합 구성 변경 없이 새 token 원문만 배포할 수 있게 한다.
+- rotate는 `token_hash`, `token_prefix`, `runtime_id`만 교체하고 나머지 메타데이터를 유지하여, 동일한 token 이름과 메타데이터를 유지한 채 새 token 원문만 배포할 수 있게 한다. 단, `runtime_id`를 소비하는 시스템은 rotate 후 새 토큰 기준으로 runtime_id를 재조회해야 한다.

 ## Requirement

@@ -47,11 +47,54 @@

 - `expires_at`은 rotate 시 변경하지 않는다. 만료일 변경이 필요하면 revoke + re-issue를 사용한다.
 - rotate는 `--no-expiry`로 발급된 영구 토큰(`expires_at IS NULL`)에만 허용된다. 만료일이 설정된 토큰은 rotate 대상이 아니다. 해당 토큰은 만료 후 re-issue하는 것이 권장 패턴이다.
+- rotate는 `runtime_id`도 새 값으로 갱신한다. trex-basic 등 `runtime_id`를 소비하는 시스템은 rotate 후 새 토큰으로 다시 인증하고 `GET /v1/user_info`를 재호출해 새 `runtime_id`를 재인식해야 한다.
+- 기존 `runtime_id`를 캐싱한 상태로 계속 사용하면 consumer 식별 불일치가 발생할 수 있다. rotate는 "토큰 원문 교체 시 token name과 메타데이터를 유지한다"는 의미이지, `runtime_id`까지 불변이라는 뜻은 아니다.
 - DB 스키마 변경(migration)은 없다. 기존 `auth_tokens` 테이블의 기존 컬럼만 UPDATE한다.
 - 구조/인터페이스/런타임 흐름 변경 없음 → minor-change fast path 적용.

 ## Change Log

+### CHG-20260511-01
+- Date: 2026-05-11
+- Author: repository-maintainers
+
+#### Change Summary
+- rotate 후 `runtime_id` lifecycle 명시 추가 — downstream consumer는 새 토큰 배포 후 `runtime_id`를 재조회해야 함
+
+#### Intent
+- CONFLICT-3 분석 결과를 반영해 `runtime_id`가 rotate 시 변경된다는 사실과, trex-basic 같은 consumer가 이를 어떻게 재인식해야 하는지 REQ-012 문서에 명시한다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - none
+- Updated:
+  - none
+- Removed:
+  - none
+
+#### Impacted Area Delta
+- Docs:
+  - `docs/srs/Interface/req-012_service-token-rotate-cli.md`: Intent/Notes에 rotate 후 `runtime_id` 재조회 lifecycle 추가
+- Modules:
+  - none
+- Tests:
+  - none
+
+#### Delivery Trace Delta
+- Batches:
+  - BAT-002 (release-candidate) — verification evidence는 유지 가능하나, rotate 후 consumer 재인식 절차를 운영 메모로 함께 검토해야 한다.
+- Releases:
+  - none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: trex-basic 연동 runbook 또는 후속 REQ에서 rotate 후 `runtime_id` 재조회 절차를 운영 문서에 반영 검토
+
+#### Validation Plan
+- REQ-005, REQ-007, REQ-012 문구를 대조해 rotate 시 `runtime_id` 변경과 `GET /v1/user_info` 재조회 필요성이 일관되게 설명되는지 코드 리뷰로 확인
+
 ### CHG-20260502-01
 - Date: 2026-05-02
 - Author: repository-maintainers
@@ -1,6 +1,6 @@
 # req-002: Alembic와 runtime schema ownership 경계 정리

- Status: Approved
+- Status: Implemented
 - Type: Migration
 - Priority: High
 - Owner: repository-maintainers
@@ -29,6 +29,35 @@

 ## Change Log

+### CHG-20260511-01
+- Date: 2026-05-11
+- Author: repository-maintainers
+
+#### Change Summary
+- Implemented 전환 — BAT-007 verification passed, confirm-req-implemented 게이트 통과
+
+#### Intent
+- BAT-007 verification.md AC-1~3 모두 PASS. Blocking Issues 없음. docs/project-structure.md "Schema Ownership Boundary", docs/runtime-flows.md "Alembic vs ensure_schema() Schema Ownership Boundary" evidence 연결 확인 완료. 잔여 리스크(idx_auth_tokens_service_name_unique Alembic 미등록)는 후속 batch 검토 항목으로 남겨둠.
+
+#### Acceptance Criteria Delta
+- none
+
+#### Impacted Area Delta
+- none
+
+#### Delivery Trace Delta
+- Batches: BAT-007 (release-candidate)
+- Releases: none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: implemented
+- Follow-up Action: draft-release (BAT-007); idx_auth_tokens_service_name_unique Alembic revision 추가 검토 권장
+
+#### Validation Plan
+- BAT-007 verification.md AC-1~3 evidence 연결 확인 완료
+
 ### CHG-20260430-02
 - Date: 2026-04-30
 - Author: GitHub Copilot
@@ -1,6 +1,6 @@
 # req-001: 로컬 DB 초기화 및 마이그레이션 검증 시나리오 정의

- Status: Approved
+- Status: Implemented
 - Type: Testing
 - Priority: High
 - Owner: repository-maintainers
@@ -29,6 +29,35 @@

 ## Change Log

+### CHG-20260511-01
+- Date: 2026-05-11
+- Author: repository-maintainers
+
+#### Change Summary
+- Implemented 전환 — BAT-007 verification passed, confirm-req-implemented 게이트 통과
+
+#### Intent
+- BAT-007 verification.md AC-1~3 모두 PASS. Blocking Issues 없음. README.md "Local DB Validation Runbook", docs/runtime-flows.md "Flow: Local DB Initialization and Validation" evidence 연결 확인 완료.
+
+#### Acceptance Criteria Delta
+- none
+
+#### Impacted Area Delta
+- none
+
+#### Delivery Trace Delta
+- Batches: BAT-007 (release-candidate)
+- Releases: none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: implemented
+- Follow-up Action: draft-release (BAT-007)
+
+#### Validation Plan
+- BAT-007 verification.md AC-1~3 evidence 연결 확인 완료
+
 ### CHG-20260430-02
 - Date: 2026-04-30
 - Author: GitHub Copilot
@@ -81,9 +81,9 @@

 | ID | Title | Type | Status | Priority | Owner | Link |
 | --- | --- | --- | --- | --- | --- | --- |
-| REQ-001 | 로컬 DB 초기화 및 마이그레이션 검증 시나리오 정의 | Testing | Approved | High | repository-maintainers | [REQ-001](./Testing/req-001_local-db-validation-scenarios.md) |
-| REQ-002 | Alembic와 runtime schema ownership 경계 정리 | Migration | Approved | High | repository-maintainers | [REQ-002](./Migration/req-002_alembic-runtime-schema-ownership.md) |
-| REQ-003 | 로컬 DB 운영 runbook 및 baseline 문서 갱신 | Documentation | Approved | Medium | repository-maintainers | [REQ-003](./Documentation/req-003_local-db-operations-runbook-and-baseline-updates.md) |
+| REQ-001 | 로컬 DB 초기화 및 마이그레이션 검증 시나리오 정의 | Testing | Implemented | High | repository-maintainers | [REQ-001](./Testing/req-001_local-db-validation-scenarios.md) |
+| REQ-002 | Alembic와 runtime schema ownership 경계 정리 | Migration | Implemented | High | repository-maintainers | [REQ-002](./Migration/req-002_alembic-runtime-schema-ownership.md) |
+| REQ-003 | 로컬 DB 운영 runbook 및 baseline 문서 갱신 | Documentation | Implemented | Medium | repository-maintainers | [REQ-003](./Documentation/req-003_local-db-operations-runbook-and-baseline-updates.md) |
 | REQ-004 | GET /health 응답 스키마 확장 | Interface | Implemented | High | repository-maintainers | [REQ-004](./Interface/req-004_health-response-schema-extension.md) |
 | REQ-005 | service-token 발급 시 runtime_id 동시 생성 | Interface | Implemented | High | repository-maintainers | [REQ-005](./Interface/req-005_service-token-runtime-id-issuance.md) |
 | REQ-006 | GET /v1/assets 엔드포인트 구현 | Interface | Implemented | High | repository-maintainers | [REQ-006](./Interface/req-006_v1-assets-endpoint.md) |
@@ -103,8 +103,8 @@

 ## Recent Change Log Summary

- 2026-05-11: REQ-004~010 Implemented 전환 — BAT-001 re-verified verification passed, confirm-req-implemented 게이트 통과
- 2026-05-11: REQ-016~019 Implemented 전환 — BAT-006 verification passed, confirm-req-implemented 게이트 통과
- 2026-05-11: REQ-016~019 Approved 전환 — confirm-req 게이트 통과 (source Discovery: dcy-004)
- 2026-05-11: REQ-016~019 Proposed 생성 — dcy-004 draft-req (portfolio_id UUID 교체 및 CLI 사용자 범위 기반 자산 식별 구조 전환)
- 2026-05-03: REQ-006 CHG-20260503-01 — strategy_type 필드 추가 (StrategySet.name), BAT-001 재검증 필요
+- 2026-05-11: REQ-005 CHG-20260511-02 — service-token 발급 API 경로를 POST /auth/service-tokens로 명확화
+- 2026-05-11: REQ-012 CHG-20260511-01 — rotate 후 runtime_id lifecycle 및 consumer 재조회 필요성 명시
+- 2026-05-11: REQ-001~003 Implemented 전환 — BAT-007 verification passed, confirm-req-implemented 게이트 통과
+- 2026-05-11: REQ-006 CHG-20260511-02 — GET /v1/assets owner scope 회귀 수정 및 BAT-001 verification 정합화
+- 2026-05-11: REQ-004~010 Implemented 전환 — BAT-001 re-verified verification passed, confirm-req-implemented 게이트 통과