docs(proofline): record line 0004 QC remediation
This commit is contained in:
@@ -0,0 +1,226 @@
|
||||
# line-0004 구현 에이전트 수정 재요청
|
||||
|
||||
- **대상 이슈:** `fourblocks2020/portfolio-hub#27`
|
||||
- **대상 Line:** `line-0004`
|
||||
- **작업 worktree:** `/home/genichin/workspace/trex-lead/repos/portfolio-hub/.worktrees/line-0004`
|
||||
- **작업 브랜치:** `line/line-0004-implementation`
|
||||
- **수정 기준 커밋:** `e2102b6f2b855b7679ab67818202ef706d9848fb`
|
||||
- **범위 권위:** `.proofline/lines/line-0004/dcy-0004.md`
|
||||
- **1차 QC 결과:** `.proofline/lines/line-0004/evidence/first-qc-review.md`
|
||||
- **요청 상태:** QC 반려 수정 요청
|
||||
|
||||
## 1. 작업 원칙
|
||||
|
||||
기존 구현의 의미와 승인된 Discovery 범위를 변경하지 말고 아래 blocker 및 관련 회귀 검증만 수정한다. 새로운 제품 결정, 다른 서비스 계약 영향, 승인 범위와의 충돌이 발견되면 구현을 중단하고 팀장에게 반환한다.
|
||||
|
||||
`trex-web`은 명시적인 Out of Scope다. 해당 저장소의 코드·타입·화면·테스트를 변경하거나 실행하지 않는다.
|
||||
|
||||
## 2. 필수 수정 — 참조 중 daemon owner transfer 차단
|
||||
|
||||
현재 daemon이 portfolio에 배정된 뒤 `update_daemon_owner()`로 daemon 소유자를 변경하면 다음 불변식이 깨진다.
|
||||
|
||||
```text
|
||||
daemon.owner_user_id == portfolio.owner_user_id
|
||||
```
|
||||
|
||||
`update_daemon_owner()`에서 해당 daemon을 참조하는 portfolio가 하나라도 있으면 owner transfer가 원자적으로 실패하도록 수정한다.
|
||||
|
||||
필수 결과:
|
||||
|
||||
- 참조 중 daemon owner transfer: `409 Conflict`
|
||||
- daemon owner: 변경되지 않음
|
||||
- portfolio `managed_by_daemon_id`: 변경되지 않음
|
||||
- 기존 broker credentials: 삭제되지 않음
|
||||
- transaction 일부만 반영되는 상태: 금지
|
||||
|
||||
다음 자동 동작은 승인 범위 밖이므로 구현하지 않는다.
|
||||
|
||||
- portfolio assignment 자동 해제
|
||||
- portfolio를 새 daemon owner에게 자동 이전
|
||||
- 다른 daemon으로 자동 재배정
|
||||
- 기존 데이터 backfill
|
||||
|
||||
## 3. 필수 수정 — assignment와 owner transfer 직렬화
|
||||
|
||||
portfolio assignment와 daemon owner transfer가 동일 daemon을 대상으로 동시에 실행될 때 일관된 row-lock 순서와 transaction 경계를 사용한다.
|
||||
|
||||
허용되는 결과:
|
||||
|
||||
1. owner transfer가 먼저 commit되면 이전 owner portfolio의 assignment는 foreign daemon으로 판단되어 실패한다.
|
||||
2. assignment가 먼저 commit되면 owner transfer는 참조 충돌로 실패한다.
|
||||
|
||||
금지되는 최종 상태:
|
||||
|
||||
```text
|
||||
portfolio.managed_by_daemon_id = daemon.id
|
||||
portfolio.owner_user_id != daemon.owner_user_id
|
||||
```
|
||||
|
||||
동시 실행이 timeout 또는 deadlock으로 끝나지 않도록 lock order를 검토한다.
|
||||
|
||||
## 4. 도메인 및 API 오류 계약
|
||||
|
||||
참조 중 owner transfer 충돌을 daemon 미존재 오류와 구분한다.
|
||||
|
||||
권장 구현 경계:
|
||||
|
||||
- 전용 domain error 추가
|
||||
- repository `update_daemon_owner()`에서 전용 error 발생
|
||||
- `PATCH /v1/admin/daemons/{daemon_id}`에서 HTTP 409로 매핑
|
||||
- 기존 daemon 미존재 404 유지
|
||||
- 기존 admin 인증·권한 계약 유지
|
||||
- 미참조 owner transfer의 기존 credential invalidation 정책 유지
|
||||
|
||||
## 5. 필수 테스트
|
||||
|
||||
### 5.1 단위/API
|
||||
|
||||
다음을 추가하거나 보강한다.
|
||||
|
||||
- [ ] 미참조 daemon owner transfer 성공
|
||||
- [ ] 참조 중 daemon owner transfer `409`
|
||||
- [ ] `409` 후 daemon owner 무변경
|
||||
- [ ] `409` 후 portfolio assignment 유지
|
||||
- [ ] `409` 후 broker credentials 유지
|
||||
- [ ] daemon 미존재 `404` 회귀 없음
|
||||
- [ ] PATCH missing daemon `404` 및 portfolio 무변경
|
||||
- [ ] admin PATCH에서 호출자 대신 target portfolio owner 기준 검증
|
||||
- [ ] deactivation 후 기존 assignment reference 보존
|
||||
- [ ] deactivation 시 기존 service token revoke 유지
|
||||
|
||||
### 5.2 실제 PostgreSQL
|
||||
|
||||
migration head가 적용된 disposable PostgreSQL에서 검증한다.
|
||||
|
||||
#### 순차 owner transfer
|
||||
|
||||
1. owner A daemon 생성
|
||||
2. owner A portfolio에 daemon 배정
|
||||
3. daemon을 owner B로 이전 시도
|
||||
4. owner transfer 실패
|
||||
5. 동일 소유자 불변식 유지
|
||||
6. owner·assignment·credential 무변경 확인
|
||||
|
||||
#### assignment/owner-transfer race
|
||||
|
||||
1. 별도 connection/thread에서 assignment와 owner transfer 동시 실행
|
||||
2. 두 실행 순서를 모두 유도하거나 반복 검증
|
||||
3. 허용된 결과만 발생하는지 확인
|
||||
4. 최종 DB 동일 소유자 불변식 확인
|
||||
5. thread timeout/deadlock 없음 확인
|
||||
|
||||
#### 미참조 owner transfer
|
||||
|
||||
1. portfolio가 참조하지 않는 daemon owner transfer 성공
|
||||
2. 기존 broker credential invalidation 정책 유지
|
||||
|
||||
## 6. PostgreSQL 실행 전제
|
||||
|
||||
완전히 빈 DB에는 먼저 migration head를 적용한다.
|
||||
|
||||
```bash
|
||||
export TIMESCALEDB_HOST=127.0.0.1
|
||||
export TIMESCALEDB_PORT=5432
|
||||
export TIMESCALEDB_NAME=<disposable-db>
|
||||
export TIMESCALEDB_USER=portfolio_hub_user
|
||||
export TIMESCALEDB_PASSWORD=<local-test-password>
|
||||
export TIMESCALEDB_SSLMODE=prefer
|
||||
export PFHUB_DB_ENABLED=true
|
||||
|
||||
.venv/bin/pfhub migrate-db
|
||||
|
||||
PORTFOLIOHUB_RUN_POSTGRES_INTEGRATION=1 \
|
||||
.venv/bin/python -m pytest -q \
|
||||
tests/test_v1_portfolios_daemon_postgres_integration.py
|
||||
```
|
||||
|
||||
실행 후 disposable DB를 삭제한다. 기존 공유·운영 DB를 오염시키지 않는다.
|
||||
|
||||
## 7. 문서 및 evidence
|
||||
|
||||
실제 동작과 일치하도록 필요한 범위에서 갱신한다.
|
||||
|
||||
- `docs/interface-contract.md`
|
||||
- `docs/data-model.md`
|
||||
- daemon admin owner-transfer runtime flow 문서
|
||||
- `.proofline/lines/line-0004/evidence/implementation-progress.md`
|
||||
|
||||
문서에 다음을 명시한다.
|
||||
|
||||
- 참조 중 daemon owner transfer는 409
|
||||
- owner transfer와 assignment의 원자적 직렬화
|
||||
- 자동 assignment 해제·portfolio owner 변경 없음
|
||||
- 충돌 시 owner·assignment·credential partial mutation 없음
|
||||
|
||||
`implementation-progress.md`의 “미커밋” 표기를 실제 상태로 수정하고 다음 실행 근거를 기록한다.
|
||||
|
||||
- QC 반려 blocker와 해결 방식
|
||||
- 수정 파일 목록
|
||||
- 수정 커밋
|
||||
- 집중 테스트 결과
|
||||
- 전체 회귀 결과
|
||||
- 실제 PostgreSQL 순차·경합 검증 결과
|
||||
- Ruff, compileall, diff check, ProofLine validate 결과
|
||||
- push·PR·main 반영·배포·release 미수행 경계
|
||||
|
||||
QC 재검증 전에는 implementation complete 또는 lifecycle 완료 문서를 새로 만들지 않는다.
|
||||
|
||||
## 8. 최소 재검증
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m pytest -q \
|
||||
tests/test_v1_portfolios_daemon_assignment.py \
|
||||
tests/test_v1_portfolios_crud.py \
|
||||
tests/test_bat022_req053_admin_daemon_crud.py
|
||||
```
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m pytest -q
|
||||
```
|
||||
|
||||
```bash
|
||||
PORTFOLIOHUB_RUN_POSTGRES_INTEGRATION=1 \
|
||||
.venv/bin/python -m pytest -q \
|
||||
tests/test_v1_portfolios_daemon_postgres_integration.py
|
||||
```
|
||||
|
||||
```bash
|
||||
ruff check \
|
||||
app/api/v1_portfolios.py \
|
||||
app/api/v1_admin_daemons.py \
|
||||
app/domain/errors.py \
|
||||
app/repositories/portfolio_repository.py \
|
||||
app/repositories/postgres.py \
|
||||
tests/test_v1_portfolios_daemon_assignment.py \
|
||||
tests/test_v1_portfolios_daemon_postgres_integration.py \
|
||||
tests/test_bat022_req053_admin_daemon_crud.py
|
||||
```
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m compileall -q app tests
|
||||
git diff --check
|
||||
proofline validate
|
||||
```
|
||||
|
||||
## 9. 금지 사항
|
||||
|
||||
- `trex-web` 변경·테스트 금지
|
||||
- approved Discovery 범위 변경 금지
|
||||
- 명시적 `managed_by_daemon_id: null` 해제 구현 금지
|
||||
- 자동 daemon 해제·이전·재배정·backfill 금지
|
||||
- main 작업 금지
|
||||
- push·PR·배포·release 금지
|
||||
|
||||
## 10. 반환 조건
|
||||
|
||||
수정·테스트·로컬 커밋 후 다음을 팀장에게 반환한다.
|
||||
|
||||
1. 새 커밋 SHA
|
||||
2. 변경 파일 목록
|
||||
3. blocker 해결 방식과 transaction/lock order
|
||||
4. 테스트별 실제 pass/fail/skip 수
|
||||
5. 실제 PostgreSQL 순차·경합 결과
|
||||
6. 남은 비차단 위험
|
||||
7. worktree clean 여부
|
||||
|
||||
수정 완료는 QC 재검증 입력일 뿐 QC PASS나 lifecycle 완료를 의미하지 않는다.
|
||||
Reference in New Issue
Block a user