From 4014d799cb26a72b278a9e9d1c2bb8e97351f242 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=AC=B8=ED=98=95=EC=84=9D?= Date: Mon, 10 Aug 2026 13:51:47 +0900 Subject: [PATCH] =?UTF-8?q?=EC=9E=A5=ED=97=8C=20=EB=A0=88=EA=B1=B0?= =?UTF-8?q?=EC=8B=9C=20=EB=A6=AC=EB=88=85=EC=8A=A4=EC=A0=84=ED=99=98=20?= =?UTF-8?q?=EA=B2=80=ED=86=A0/=EC=9E=A5=ED=97=8C=20=EB=A0=88=EA=B1=B0?= =?UTF-8?q?=EC=8B=9C=20=EC=84=9C=EB=B9=84=EC=8A=A4=20=EA=B2=80=EC=A6=9D=20?= =?UTF-8?q?=ED=91=9C=EC=A4=80.md=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../장헌 레거시 서비스 검증 표준.md | 237 ++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 장헌 레거시 리눅스전환 검토/장헌 레거시 서비스 검증 표준.md diff --git a/장헌 레거시 리눅스전환 검토/장헌 레거시 서비스 검증 표준.md b/장헌 레거시 리눅스전환 검토/장헌 레거시 서비스 검증 표준.md new file mode 100644 index 0000000..8385544 --- /dev/null +++ b/장헌 레거시 리눅스전환 검토/장헌 레거시 서비스 검증 표준.md @@ -0,0 +1,237 @@ +# 장헌 레거시 서비스 검증 표준 + +## 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을 읽고 중복 검증을 피한다. + +권장 브랜치 형식: + +```text +validation/-deep- +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%를 원칙으로 한다. 미달 시 사유·소유자·재검토일을 기록한다. + +권장 위치: + +```text +tests/php/__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 + +제목은 다음 형식을 권장한다. + +```text +[test][] <관찰된 문제 또는 검증 목표> +``` + +본문에는 다음을 포함한다. + +- 재현 계정/역할(비밀번호는 기록하지 않음) +- 메뉴·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이어도 다음 순서를 지킨다. + +```text +최신 main 확인 + → 서비스 전용 브랜치 검증 + → Issue/PR 증적 작성 + → 후보 이미지·격리 컨테이너 재검증 + → 스테이징 canary 및 rollback 기준 확인 + → main 병합 + → 스테이징 회귀검증 + → 별도 승인 후 운영 배포 +``` + +공통 CI gate가 실패한 경우 해당 서비스의 통과 결과와 공통 gate의 미완료를 분리해 보고한다. 공통 gate가 실패한 상태에서 서비스 완료나 운영 배포 완료라고 주장하지 않는다. + +현재 확인된 공통 PHP Unit completion gate(`#95`, `#97`)처럼 기준선 자체가 미완료인 경우에는 해당 Issue를 선행/차단 항목으로 기록하고, 서비스별 검증 결과를 그 사실과 함께 보고한다. + +## 10. 증적 문서 양식 + +서비스별 결과에는 다음 항목을 남긴다. + +```text +서비스: +기준 main SHA: +검증 브랜치/커밋: +검증 일시: +검증 계정/역할: + +메뉴·화면: +- 경로/단계: +- 결과: PASS / BLOCKED / FAIL +- 콘솔·HTTP·PHP 오류: + +단위/특성화 테스트: +- RED 재현: +- GREEN 결과: +- 반복 횟수: + +통합/DB/파일: +- DB 변경 전후: +- 외부 호출: +- 합성 데이터 잔여: + +RED팀: +- 발견 위험: +- 분류: +- 후속 Issue: + +최종 판정: +- 즉시 수정 / 추가 확인 / 현행 유지 / 병합 보류 +``` + +## 11. 작업 안전 규칙 + +- `git reset --hard`, `git clean`, 무차별 Docker 정리, worktree 삭제를 사용하지 않는다. +- 다른 개발자의 브랜치·worktree·컨테이너를 임의로 수정하거나 제거하지 않는다. +- 임시 후보 컨테이너를 제거할 때는 정확한 이름과 소유를 확인한다. +- 운영 DB·운영 파일·토큰·비밀번호를 테스트 증적에 복사하지 않는다. +- 문서에 기록된 “통과”는 실제 명령·경로·커밋·결과가 남아 있을 때만 사용한다.