MyDoc/장헌 레거시 리눅스전환 검토/장헌 레거시 서비스 검증 표준.md

장헌 레거시 서비스 검증 표준

1. 목적

PHP 8.4 전환 소스가 기존 레거시 동작을 유지하는지 서비스별로 확인하고, 단위 테스트·통합 테스트·화면 회귀검증·RED팀 검토 결과를 근거로 안전하게 이슈와 PR을 처리하기 위한 공통 기준이다.

이 문서를 각 서비스 검증의 시작점으로 사용한다. 검증 결과는 서비스별 증적 문서와 Gitea Issue/PR에 연결한다.

2. 적용 대상과 순서

2.1 우선 검증 순서

순서	서비스	주요 위험
1	factory_mng	기존 수정사항, 생산·재고 데이터 흐름
2	factory_board	공장 게시판과 공통 화면 연결
3	intranet	인증·세션·전자결재·파일·PDF 등 공통 호출
4	person_mng	인사·근태·권한 데이터
5	account	회계 데이터와 권한 경계
6	virtual_yard	외부/정적 자원과 브라우저 의존성

projt_mng, worker_mng, proj_new2는 이미 별도 검증·이슈 흐름이 있으므로 해당 문서와 현재 Gitea 상태를 먼저 확인한 뒤 연결 검증한다.

2.2 범위 원칙

• 최신 main을 기준으로 검증한다.
• 운영·스테이징 환경은 명시적인 배포 요청 없이는 변경하지 않는다.
• 실제 운영 DB·실사용자 파일·외부 서비스에 쓰기 작업을 하지 않는다.
• 테스트 데이터는 격리된 DB와 고유한 식별자를 사용하고, 종료 후 잔여 0건을 확인한다.
• docs/ 증적 문서에는 비밀번호·토큰·개인키를 기록하지 않는다.

3. 시작 전 고정 절차

1. Gitea origin/main의 최신 커밋을 확인한다.
2. 작업 저장소·브랜치·worktree·미커밋 변경을 확인한다.
3. 다른 개발자의 브랜치와 변경을 덮어쓰지 않는다.
4. 서비스 전용 검증 브랜치를 최신 main에서 만든다.
5. 대상 서비스, 대상 파일, 테스트 DB, 후보 컨테이너 이름을 검증 기록에 고정한다.
6. 기존 테스트 문서와 관련 Issue/PR을 읽고 중복 검증을 피한다.

권장 브랜치 형식:

validation/<service>-deep-<YYYYMMDD>
fix/issue-<번호>-<짧은-이름>

4. PHP 파일 인벤토리와 상태 분류

모든 대상 PHP 파일은 다음 중 하나의 상태를 가져야 한다.

상태	의미
unit-tested	순수 함수/정책 단위 테스트가 통과함
characterization-tested	변경 전 기존 동작을 고정하고 비교 검증함
integration-only	HTTP·DB·세션 결합으로 통합검증만 가능함
excluded-with-reason	범위 제외 사유·담당자·재검토 시점을 기록함

인벤토리에는 최소한 파일 경로, 서비스, 호출 역할, 테스트 상태, sourceHash, 제외 사유를 기록한다. sourceHash 변경만으로 기능 정상이라고 판단하지 않는다.

5. 테스트 방법

5.1 Characterization 테스트

변경 전 레거시 또는 기준 후보에서 정상·경계·실패 동작을 먼저 기록한다.

• 입력과 출력 형식
• HTTP 상태와 응답 표식
• DB 변경 전후
• 세션·파일·캐시 변화
• 외부 호출 여부
• 오류 메시지와 권한 차단 결과

기존 동작을 확인하지 못한 경우에는 추측으로 기대값을 만들지 말고 integration-only 또는 excluded-with-reason으로 표시한다.

5.2 단위 테스트: RED → GREEN

1. RED: 정상·경계·실패 케이스를 먼저 작성하고 실패를 확인한다. 가능하면 같은 케이스를 2회 반복해 재현성을 확인한다.
2. GREEN: 최소한의 코드 변경으로 테스트를 통과시킨다.
3. 입력 변형, 권한 우회, 빈 값, 중복 값, 길이 경계, 날짜·숫자 형식을 확인한다.
4. P0 정책·권한 분기에는 branch coverage 100%를 원칙으로 한다. 미달 시 사유·소유자·재검토일을 기록한다.

권장 위치:

tests/php/<service>_<policy>_unit.php

5.3 통합·HTTP 테스트

• 격리된 합성 DB와 테스트 계정을 사용한다.
• 익명 접근, 인증 성공, 권한 허용, 권한 차단을 모두 실행한다.
• 실제 PHP 핸들러와 라우트를 호출한다.
• HTTP 200이어도 응답 본문에 Fatal/Parse/Warning/Deprecated가 있는지 별도로 검사한다.
• 400/405는 자동으로 허용하지 말고 요구된 계약과 비교한다.
• 외부 HTTP·메일·파일 공유 호출은 차단하거나 모의 처리한다.
• 성공 표식은 응답 코드만이 아니라 화면/본문의 의미 있는 값으로 확인한다.

5.4 DB·파일·합성 데이터 검사

각 쓰기 기능은 다음 순서로 기록한다.

1. 실행 전 DB·세션·파일·캐시 상태를 저장한다.
2. 생성·수정·삭제 또는 권한 차단을 실행한다.
3. 실행 후 DB 변경 전후를 비교한다.
4. 권한 차단 시 DB·파일·세션에 변경이 없어야 한다.
5. 테스트 식별자로 검색해 합성 데이터 잔여가 0건인지 확인한다.
6. 실제 업무 파일과 운영 영속 저장소를 건드리지 않았는지 확인한다.

5.5 화면·메뉴 회귀검증

• 서비스 로그인 후 메뉴를 순서대로 탐색한다.
• 기본 메뉴에서 최소 3단계 깊이까지 진입한다.
• 페이지에 추가 버튼·팝업·이미지·다운로드·상세 링크가 보이면 더 깊은 단계까지 검사한다.
• 정상 화면뿐 아니라 빈 데이터, 권한 없음, 존재하지 않는 파일, 잘못된 입력도 확인한다.
• 브라우저 콘솔의 404, 500, PHP 오류, 깨진 이미지, 무한 로딩을 기록한다.

6. RED팀 검토

단위·통합 테스트가 통과한 뒤 독립적인 관점으로 다음을 다시 공격한다.

• 익명 요청이 인증된 응답을 얻는지
• 권한 없는 계정이 다른 역할의 기능을 실행하는지
• 성공 표식만 보고 실패를 통과로 판정한 것은 아닌지
• 오래된 이미지·OPcache·잘못된 볼륨을 보고 테스트한 것은 아닌지
• DB·세션·파일·캐시에 합성 데이터가 남는지
• 외부 URL·메일·실서버 파일에 연결되는지
• HTTP 200 안에 PHP Fatal/Warning이 숨겨져 있지 않은지

결과는 Blocker, Scope Out, Follow-up/Residual로 분류한다. RED팀 검토 없이 “완료”로 표시하지 않는다.

7. 결함·이슈·수정 규칙

7.1 Gitea Issue

제목은 다음 형식을 권장한다.

[test][<service>] <관찰된 문제 또는 검증 목표>

본문에는 다음을 포함한다.

• 재현 계정/역할(비밀번호는 기록하지 않음)
• 메뉴·URL·입력 조건
• 기대 결과와 실제 결과
• HTTP/PHP/DB/파일 증적
• 영향 범위와 우선순위
• 관련 부모 Issue·CI gate·PR
• 완료 기준과 재검증 방법

7.2 수정과 PR

1. 최신 main에서 이슈 전용 브랜치를 만든다.
2. 최소 범위만 수정하고 unrelated 파일은 건드리지 않는다.
3. RED → GREEN 단위 테스트를 남긴다.
4. 원래 실패 시나리오를 최소 2회 재검사한다.
5. 관련 서비스와 DB 변경 전후를 재검사한다.
6. PHP 진단·합성 데이터 잔여·RED팀 검토 결과를 첨부한다.
7. PR에서 Issue를 연결하고 CI 결과와 테스트 커밋을 명시한다.
8. 최신 main 후보에서 다시 검증한 뒤에만 병합한다.

8. 서비스별 완료 기준

서비스 하나를 완료로 표시하려면 다음을 모두 만족해야 한다.

• 대상 PHP 인벤토리 상태가 승인된 상태로 채워짐
• 메뉴·링크·팝업·3단계 이상 화면 회귀검증 완료
• 정상·경계·실패·권한 차단 테스트 통과
• DB 변경 전후와 합성 데이터 잔여 0건 확인
• PHP Fatal/Parse/Warning/Deprecated 0건
• HTTP 5xx 및 의도하지 않은 외부 호출 0건
• RED팀 검토 결과 기록
• 관련 Gitea Issue/PR·커밋 SHA·검증 시각 기록
• 실패 항목은 Blocker 또는 Follow-up으로 분리되어 담당자와 다음 조치가 있음

9. 배포·병합 게이트

검증 브랜치의 결과가 GREEN이어도 다음 순서를 지킨다.

최신 main 확인
  → 서비스 전용 브랜치 검증
  → Issue/PR 증적 작성
  → 후보 이미지·격리 컨테이너 재검증
  → 스테이징 canary 및 rollback 기준 확인
  → main 병합
  → 스테이징 회귀검증
  → 별도 승인 후 운영 배포

공통 CI gate가 실패한 경우 해당 서비스의 통과 결과와 공통 gate의 미완료를 분리해 보고한다. 공통 gate가 실패한 상태에서 서비스 완료나 운영 배포 완료라고 주장하지 않는다.

현재 확인된 공통 PHP Unit completion gate(#95, #97)처럼 기준선 자체가 미완료인 경우에는 해당 Issue를 선행/차단 항목으로 기록하고, 서비스별 검증 결과를 그 사실과 함께 보고한다.

10. 증적 문서 양식

서비스별 결과에는 다음 항목을 남긴다.

서비스:
기준 main SHA:
검증 브랜치/커밋:
검증 일시:
검증 계정/역할:

메뉴·화면:
- 경로/단계:
- 결과: PASS / BLOCKED / FAIL
- 콘솔·HTTP·PHP 오류:

단위/특성화 테스트:
- RED 재현:
- GREEN 결과:
- 반복 횟수:

통합/DB/파일:
- DB 변경 전후:
- 외부 호출:
- 합성 데이터 잔여:

RED팀:
- 발견 위험:
- 분류:
- 후속 Issue:

최종 판정:
- 즉시 수정 / 추가 확인 / 현행 유지 / 병합 보류

11. 작업 안전 규칙

• git reset --hard, git clean, 무차별 Docker 정리, worktree 삭제를 사용하지 않는다.
• 다른 개발자의 브랜치·worktree·컨테이너를 임의로 수정하거나 제거하지 않는다.
• 임시 후보 컨테이너를 제거할 때는 정확한 이름과 소유를 확인한다.
• 운영 DB·운영 파일·토큰·비밀번호를 테스트 증적에 복사하지 않는다.
• 문서에 기록된 “통과”는 실제 명령·경로·커밋·결과가 남아 있을 때만 사용한다.