FESADev/docs2/PRD.md

# Product Requirements: Structural FEM Solver Framework

## 1. 제품 정의

이 프로젝트는 유한요소 구조해석 솔버를 신뢰성 있게 확장할 수 있는 C++ 해석 코어와
그 개발·검증 workflow를 구축한다. 지원하는 해석, 요소, 재료와 입출력 형식은 feature별로
명시하며, 구현 여부와 검증 수준을 추적 가능한 evidence로 제공한다.

현재 repository의 제품은 agent/skill 문서 체계와 C++ 개발 Harness를 포함한 초기
framework다. 아직 C++ solver build metadata가 없으므로 특정 해석 기능이 구현되었다고
간주하지 않는다.

## 2. 대상 사용자

- 구조해석 알고리즘과 요소 정식화를 구현하는 solver 개발자
- 해석 결과의 수치 정확성, 물리적 타당성과 회귀를 검토하는 CAE 엔지니어
- 입력·결과 형식과 외부 reference model을 관리하는 integration 개발자
- 기능별 요구사항, 검증 evidence와 release readiness를 추적하는 maintainer

## 3. 제품 목표

1. 해석 물리와 수치 계약을 코드 구조에 명확히 반영한다.
2. 작은 요소·재료·해석 기능을 기존 기능을 깨지 않고 단계적으로 추가할 수 있게 한다.
3. 동일 입력과 설정에서 재현 가능한 assembly, solve와 output을 제공한다.
4. 단위 테스트, analytical/benchmark 검증, mesh convergence, invariant와 독립 reference
   비교를 결합해 correctness evidence를 축적한다.
5. 지원하지 않는 모델 의미를 조용히 근사하지 않고 명확한 진단으로 거부한다.
6. agent가 일반적인 설계·구현·검증 결정을 자율적으로 처리하고, 제품 의미를 바꾸는
   결정만 사용자에게 요청하게 한다.

## 4. 비목표

- 특정 상용 solver의 비공개 알고리즘을 복제하는 것
- Abaqus 전체 keyword, 모든 element/material/procedure와 bitwise 결과 호환을 약속하는 것
- 검증되지 않은 기능을 입력만 받아들이는 형태로 노출하는 것
- 하나의 sparse backend, 저장 형식 또는 운영체제를 solver core 계약으로 고정하는 것
- 모델 생성용 GUI, CAD geometry kernel, mesher 또는 범용 전후처리기를 초기 범위에 포함하는 것
- 외부 결과와 수치가 비슷하다는 사실만으로 물리·수치 정확성을 선언하는 것

## 5. 핵심 기능 요구사항

### 5.1 모델 의미

- Node, element, material, property, set, constraint, load와 analysis step을 명시적 semantic
  model로 표현해야 한다.
- Source label, internal identity, DOF와 equation identity를 구분해야 한다.
- 단위계, 좌표계, component 순서와 부호를 입력 및 결과 계약에 기록해야 한다.
- 잘못된 참조, 중복 identity, 비유한 값과 지원하지 않는 조합을 analysis 시작 전에
  진단해야 한다.

### 5.2 요소 및 재료 확장

- Element formulation은 kinematics, interpolation, integration, residual/tangent,
  state variable과 recovery 계약을 함께 제공해야 한다.
- Material model은 committed/trial state의 lifetime과 update 실패 의미를 정의해야 한다.
- Element나 material 추가가 global assembly, parser 또는 특정 linear algebra backend의
  변경을 필수로 만들지 않아야 한다.
- 각 기능은 적용 범위와 알려진 locking, hourglass, conditioning 또는 convergence 제한을
  문서화해야 한다.

### 5.3 해석 절차

- Analysis procedure는 model validation, DOF 구성, assembly, constraint 적용, solve,
  convergence 판단, state commit과 result recovery 순서를 소유해야 한다.
- Linear/nonlinear, static/dynamic, eigen 또는 contact 계열 기능은 공통 이름 아래 암묵적으로
  섞지 않고 feature contract로 활성화해야 한다.
- 반복해석은 residual과 correction을 구분하고 실패 시 마지막 committed state를 보존해야
  한다.

### 5.4 입출력

- Solver core와 input/output adapter를 분리해야 한다.
- 지원 형식과 subset은 versioned contract로 공개해야 한다.
- Abaqus `.inp` 호환 feature를 선택한 경우 model data와 history data의 공개 의미를
  보존하고, 지원 keyword와 option, validation, 미지원 동작을 명시해야 한다.
- Unknown semantic construct는 기본적으로 오류이며, 결과에 영향을 주지 않는다고 계약된
  항목만 warning으로 처리할 수 있다.
- 결과는 entity, step/frame, location, coordinate system, component, units와 provenance로
  식별 가능해야 한다.

### 5.5 진단과 실패

- Parser, model, formulation, assembly, solver, convergence, recovery와 I/O 실패를 구분하는
  structured diagnostic을 제공해야 한다.
- 오류에는 가능한 경우 source location 또는 semantic entity identity와 수정 가능한
  설명을 포함해야 한다.
- 실패한 analysis가 부분적으로 authoritative한 결과 파일을 남겨 성공으로 오인되게 해서는
  안 된다.

### 5.6 검증과 추적성

- 모든 필수 requirement는 verification method, acceptance criterion과 evidence에 연결되어야
  한다.
- 수치 feature는 최소한 직접 kernel test와 독립적인 system/benchmark 검증을 가져야 한다.
- Reference comparison은 model 의미와 result identity를 먼저 일치시킨 뒤
  `docs/TOLERANCE.md`에 정의된 metric을 적용해야 한다.
- Reference artifact는 read-only이며 구현 결과를 맞추기 위해 수정할 수 없다.
- Release verdict는 requirement부터 physics review까지 동일 feature revision의 evidence만
  사용해야 한다.

### 5.7 개발 자동화

- C++ 변경은 실패 test를 먼저 관찰하는 TDD workflow를 따라야 한다.
- Harness는 repository 설정에서 build system과 test command를 결정하고 shell string이
  아닌 검증된 argument list를 실행해야 한다.
- 자동화는 사용자의 관련 없는 working-tree 변경을 commit하거나 삭제하지 않아야 한다.
- 실패, timeout과 미실행 검사는 성공으로 승격되지 않아야 한다.

## 6. 품질 속성

| 속성 | 요구사항 |
| --- | --- |
| Correctness | 공식화된 방정식, 독립 검증과 물리 invariant로 입증한다. |
| Determinism | 동일 platform/config/input에서 ordering과 결과 identity가 재현된다. |
| Traceability | Requirement, formulation, code, test, artifact와 verdict를 feature ID로 연결한다. |
| Extensibility | Core 변경 없이 adapter/backend를, owner 경계를 깨지 않고 physics 기능을 추가한다. |
| Diagnosability | 실패 단계, entity, 원인과 실행 evidence를 구조화해 남긴다. |
| Portability | Core C++는 vendor/OS type을 노출하지 않으며 현재 Windows/MSVC baseline을 검증한다. |
| Safety | 미지원 의미는 fail closed, artifact 갱신과 외부 변경은 명시적 권한 아래 수행한다. |
| Performance | 정확성과 재현성을 먼저 보존하고 측정된 병목에만 최적화를 적용한다. |

## 7. Feature 완료 조건

Feature는 다음 조건을 모두 만족할 때만 완료된다.

- 요구사항과 지원/비지원 범위가 식별 가능하다.
- formulation과 numerical review가 같은 convention을 사용한다.
- I/O 및 result identity가 versioned contract에 정의되어 있다.
- 관련 unit/integration/benchmark test가 통과한다.
- 필요한 build, reference comparison과 physics sanity check가 실제로 실행되었다.
- 알려진 제한과 미실행 검사가 release evidence에 기록되었다.
- 동일 revision의 artifact digest가 handoff chain 전체에서 일치한다.

## 8. 단계적 제공 원칙

초기 feature는 하나의 작은 해석 capability를 end-to-end로 완성하는 vertical slice로
선정한다. 요소 종류나 analysis family를 넓히기 전에 semantic model, deterministic
assembly, diagnostic, result identity와 검증 경로를 먼저 안정화한다. 구체적인 첫 해석
기능은 요구사항 단계에서 결정하며 이 PRD가 임의로 선결정하지 않는다.

## 9. 성공 지표

- 필수 requirement의 verification evidence 연결률 100%
- 지원 feature의 blocking regression test 통과율 100%
- 알려지지 않은 semantic input의 silent acceptance 0건
- 관련 없는 사용자 파일을 자동화가 수정·commit한 사례 0건
- 같은 failure signature의 무한 agent 재시도 0건
- release verdict에서 미실행 검사를 통과로 표시한 사례 0건