FESADev/docs/PRD.md

# PRD: FESA 구조해석 솔버

## 제품 정의

FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축하는 프로젝트이다. 물리적으로
설명 가능하고 재현 가능한 해석 결과를 제공하며, 새로운 기능을 요구사항부터 독립 검증까지
추적 가능한 단위로 확장하는 것을 목표로 한다.

이 문서는 특정 요소, 재료, 하중 또는 해석 절차의 명세가 아니라 모든 Feature에 적용되는
제품 기준이다. 개별 지원 범위, 입력 옵션, 수식, 수치 기준과 검증 사례는
`docs/<feature-id>/`의 승인 계약으로 정의한다. 특정 기능의 코드가 존재한다는 사실과
그 기능의 검증 완료 또는 현재 release readiness는 서로 다른 상태다.

현재 선택된 기술 스택과 외부 형식은 [프로젝트 지침](../AGENTS.md) 및 승인된 계약을
따른다. 공통 문서의 일반화는 기존 지원 범위, 파일 형식, 수치 정책 또는 호환성을 변경하는
승인이 아니다.

## 대상 사용자

- Solver 개발자: 요소, 재료, 하중, 제약, 해석 절차와 수치 backend를 구현한다.
- 해석 사용자: 문서화된 입력 범위로 모델을 구성하고 결과와 진단을 해석한다.
- 검증 담당자: 수학적 일관성, 물리적 타당성, reference 비교와 회귀 evidence를 검토한다.
- Maintainer와 workflow 운영자: 요구사항, 결정, 구현과 검증의 추적성 및 변경 범위를 관리한다.

## 제품 목표

1. 해석의 물리·수치 의미를 입력부터 결과까지 보존한다.
2. 작은 Feature를 end-to-end로 완성한 뒤 검증된 기반 위에서 지원 범위를 확장한다.
3. 모델 의미, 계산 상태, 수치 backend와 저장 형식의 책임을 구분한다.
4. 같은 입력과 승인된 실행 조건에서 source identity, 조립·결과·진단 순서를 재현한다.
5. 잘못되거나 지원하지 않는 모델 의미를 조용히 근사하지 않고 명확히 진단한다.
6. 요구사항, 설계 결정, 구현, 테스트와 검증 결과를 같은 Feature와 contract revision으로 연결한다.

Harness와 agent·skill은 이 목표를 달성하기 위한 개발 운영 인프라다. 운영 스크립트나
문서 체계 자체를 구조해석 솔버의 제품 기능으로 간주하지 않는다.

## 문서와 계약의 역할

| 문서 | 소유하는 내용 |
| --- | --- |
| 이 PRD | 제품 목적, 공통 요구사항, 품질 속성과 완료 기준 |
| [ARCHITECTURE](ARCHITECTURE.md) | 공통 책임, 의존성, 수명과 확장 경계 |
| [ADR](ADR.md) | 프로젝트 전반의 설계 결정과 변경 이력 |
| Feature `PRD.md` | 목적·범위·제외, 작은 요구사항·acceptance의 원본, 현재 checklist와 상세 계약 링크 |
| Feature `requirements.md` | 복잡한 요구사항을 분리할 때만 작성하는 상세 요구사항과 verification matrix |
| Feature `ADR.md` | 해당 Feature의 결정·이유·영향·owner와 승인 근거 |
| Feature 전문 산출물 | 연구, 정식화, 수치/reference 검토, I/O, 구현·검증, 물리 검토와 release evidence |

Feature 문서의 생성·재개, 메인이 관리하는 핵심 문서 3개와 선택적 상세 문서는
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. 작은 요구사항은 Feature
PRD에 정의하고, 상세 요구사항을 분리하면 PRD에는 요약과 링크만 남겨 원본을 중복하지 않는다.
공통 기준을 묵시적으로 덮어쓰지 않으며 기준 자체의 변경은 별도로 승인된 문서 작업으로 다룬다.

## 공통 기능 요구사항

아래 `FESA-PRD-GEN-*`는 공통 원칙을 위한 추적 ID다. 기존 `FESA-PRD-001`부터
`FESA-PRD-019`까지의 의미를 바꾸어 재사용하지 않으며, 그 원문과 적용 범위는
[개정 전 PRD](archive/pre-generalization/PRD.md)에 보존한다. Feature의 상세 요구사항은
별도 `FEM-REQ-<FEATURE>-###` ID와 해당 공통 기준을 연결한다.

| ID | 요구사항 | 확인할 evidence |
| --- | --- | --- |
| FESA-PRD-GEN-001 | 지원·미지원 범위와 관찰 가능한 동작을 Feature 계약으로 명시해야 한다. | 범위·제외·입력/출력 계약 및 양성·음성 검증 |
| FESA-PRD-GEN-002 | 입력을 일관된 semantic model로 변환하고 잘못된 참조·중복·비유한 값·미지원 조합을 진단해야 한다. | Mapping·validation 계약과 실패 경로 테스트 |
| FESA-PRD-GEN-003 | Source identity, internal index, DOF, equation과 result identity를 구분하고 필요한 대응 관계를 보존해야 한다. | Identity mapping과 재정렬·누락·중복 검사 |
| FESA-PRD-GEN-004 | 모델 정의, 실행 view, equation 구성과 mutable state의 소유권·수명을 분리해야 한다. | Architecture·lifetime 검토와 관련 테스트 |
| FESA-PRD-GEN-005 | 요소·재료·하중·제약의 수학적 계약을 검토한 뒤 local 계산과 전역 해석을 연결해야 한다. | 정식화, Numerical Review, local·integration evidence |
| FESA-PRD-GEN-006 | 해석 절차마다 필요한 state, 해법, 종료 조건, commit과 recovery 의미를 정의해야 한다. | Procedure 계약과 성공·실패 lifecycle 검증 |
| FESA-PRD-GEN-007 | 결과의 물리량, location, units, coordinates, component, entity와 step/frame 의미를 식별할 수 있어야 한다. | I/O·result schema 계약과 mapping 검증 |
| FESA-PRD-GEN-008 | 실패한 candidate가 유효한 state나 최종 결과를 부분적으로 오염시키지 않도록 계약된 보존 범위를 지켜야 한다. | State commit·복구·출력 실패 검증 |
| FESA-PRD-GEN-009 | 외부 형식과 vendor/OS API를 adapter 뒤에 격리하고 solver core에 노출하지 않아야 한다. | Public dependency와 adapter 경계 검토 |
| FESA-PRD-GEN-010 | Production 동작 변경은 해당 동작을 확인하는 테스트로 검증하고, 버그는 가능한 경우 실패를 재현한 뒤 최소 수정해야 한다. | 변경 영향에 맞는 검사, 가능한 버그 재현, 기능 완료 시 전체 검증 명령과 실제 결과 |
| FESA-PRD-GEN-011 | 기능에 필요한 독립 검증과 reference 비교를 수행하고 승인된 identity·수치 정책을 유지해야 한다. | 검증 matrix, 사전검사, reference 또는 명시적 N/A와 대체 근거 |
| FESA-PRD-GEN-012 | 기능 완료는 같은 계약 revision의 필수 evidence와 미해결 항목을 추적하여 판정해야 한다. | 해당 계약을 지지하는 검증 결과, 적용 범위·제한과 미해결 항목 |

요구사항 단계는 acceptance intent와 필요한 물리적 관찰을 정한다. Numerical Review는
기존 승인 정책 안에서 논리적 비교량·identity/component·판정 구분을 구체화하고, I/O는 이를
외부 syntax와 결과 schema에 대응시킨다. 구현 담당자가 누락된 상위 계약을 임의로 정하지 않는다.

## 품질 속성

| 속성 | 공통 기준 |
| --- | --- |
| Correctness | 실행 성공이나 유한한 결과만으로 판단하지 않고 수학적 계약과 기능별 검증으로 설명한다. |
| Determinism | 승인된 실행 조건에서 identity, numbering, reduction, 결과와 diagnostic 순서를 재현한다. |
| Traceability | 요구사항·결정·코드·테스트·artifact·verdict를 Feature ID와 revision으로 연결한다. |
| Extensibility | 실제 사용 사례에 필요한 최소 경계를 추가하며, 지원하지 않는 physics나 미래 state를 선할당하지 않는다. |
| Diagnosability | 실패 단계와 관련 source/entity, 원인과 재개에 필요한 정보를 제공한다. |
| Safety | 미지원 의미는 fail-closed로 처리하고, reference와 관련 없는 사용자 변경을 보존한다. |
| Maintainability | 사람이 계약과 수식을 대조할 수 있는 단순한 코드와 중복 없는 문서를 유지한다. |
| Performance | 정확성·재현성을 보존하고 측정된 병목과 승인된 요구를 근거로 최적화한다. |

특정 모델 크기, 성능 목표와 환경별 보장은 해당 요구와 evidence가 있을 때 Feature 계약으로
정한다. 수치 검증 기준은 적용되는 공통 정책과 승인된 Feature 계약을 따르며 외부 reference
기준을 기능마다 임의로 정하지 않는다. 이 표는 검증되지 않은 성능이나 모든 platform의
동등성을 약속하지 않는다.

## 검증과 완료 기준

검증은 서로 다른 오류를 확인하는 계층으로 구성한다. Numerical Review가 Feature에 맞는
unit, analytical/benchmark, integration, convergence, invariant 및 외부 reference coverage를
정의한다. 한 계층의 성공이 다른 필수 계층을 대신하지 않는다.

- 외부 reference 비교는 identity와 component를 대응시키고 missing, extra, duplicate,
  nonfinite 값을 거부한 뒤 [TOLERANCE](TOLERANCE.md)를 적용한다.
- 물리 평형, 수렴과 정식화 검증의 기준을 외부 reference tolerance와 혼용하지 않는다.
- Reference artifact는 read-only로 취급하며 구현 결과에 맞추어 생성·보정하지 않는다.
- 비교가 N/A인 경우 이유와 계약이 요구하는 대체 evidence를 명시한다.
- 실패·미실행·stale evidence를 통과로 표시하지 않는다. 과거 통과 기록을 현재 검증으로
  소급 적용하지 않는다.

메인 assistant가 범위를 파악하고 필요한 전문 작업을 선택하여 구현·검증·결과 확인을
조정한다. 수식·요소·재료·적분·상태 갱신을 추가하거나 변경하면 독립 numerical review와
해당 analytical/invariant 검증을 수행한다. 필요한 물리 검토와 reference 비교도 유지한다.

변경 중에는 관련 검사를 수행하고, 솔버 기능 완료 시 구성된 전체 build/test와 계약상 필수
reference 비교를 한 번 수행한다. 요청되거나 영향이 넓어 전체 검증이 필요한 경우에도
실행한다. 이후 변경·실패가 없으면 같은 검증을 반복하지 않는다. 기존 coverage가 충분한
rename/refactor에는 형식적인 새 테스트를 요구하지 않는다.

Release-readiness 감사는 사용자가 명시적으로 요청할 때만 수행한다. Readiness 권고는
외부 publish, push, tag, deploy 또는 package 권한이 아니다. 메인은 필수 evidence와
미해결 항목을 확인하여 완료 여부를 판단하며, 문서 수정에는 정적 검토를 적용한다.

현재 운영 결정은 [ADR-028](ADR.md#adr-028), 역할과 인계·실패 처리는
[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md)을 따른다. Skill의 적용 경계는
[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md), 실행 절차는 각 현재 `SKILL.md`를 따른다.

## 단계적 확장과 비목표

새 Feature는 입력 의미부터 결과와 검증까지 연결되는 작은 단위로 정의한다. Kernel,
parser 또는 dataset 하나가 존재한다는 이유만으로 제품 노출을 선언하지 않는다.
공통 문서에 구현 항목별 목록이나 진행 상태를 누적하지 않고 해당 Feature 문서에서 관리한다.

다음은 별도 승인 없이 목표로 삼지 않는다.

- 특정 외부 solver의 전체 호환성이나 비공개 알고리즘·내부 상태·결과 생성 절차의 동등성
- 아직 요구되거나 검증되지 않은 요소·재료·해석 절차·입출력 형식의 지원
- GUI, 모델러, mesher 또는 범용 전후처리기로의 제품 범위 확대
- 외부 solver 실행, reference 갱신, 원격 게시 또는 파괴적 작업의 자동 승인

외부 제품의 공개 입력 의미, 출력 정의와 검증 사례는 승인된 범위의 reference로 사용할 수
있다. 수치 결과의 exact equality는 허용되지만 내부 동작 동등성을 증명하지 않는다.

## 개정 이력의 보존

이 개정은 프로젝트 공통 기준과 구현 항목별 계약의 문서 경계를 정리한다. 기존 기능의
요구사항을 폐기하거나 수치 acceptance를 변경하지 않는다. 기능별 설명과 기존 ID의 원문은
[개정 전 PRD](archive/pre-generalization/PRD.md)에 보존하며, 향후 Feature PRD로 이관할 때
원래 범위·revision·근거를 함께 연결한다. 보존본의 오래된 지원·검증 상태보다 해당 Feature의
승인된 최신 계약과 evidence를 확인한다.