docs: add solver core skeleton phase

2026-06-12 01:31:31 +09:00
parent 6646344113
commit 4e7fd1087d
11 changed files with 1100 additions and 0 deletions
@@ -0,0 +1,118 @@
+# Step 7: results-containers
+
+## 읽어야 할 파일
+
+먼저 아래 파일들을 읽고 프로젝트의 아키텍처와 이전 step 산출물을 파악하라:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/src/fesa/analysis/analysis_state.hpp`
+- `/src/fesa/analysis/analysis.hpp`
+- `/tests/unit/analysis_flow_template_test.cpp`
+
+이전 step에서 만들어진 AnalysisState와 Analysis flow를 꼼꼼히 읽고, 결과 container가 HDF5 API에 직접 의존하지 않도록 유지하라.
+
+## 작업
+
+HDF5 writer 구현 전 단계의 results data model skeleton을 `/src/fesa/results/`에 구현한다.
+
+필수 파일:
+
+- `/src/fesa/results/results.hpp`
+- `/tests/unit/results_containers_test.cpp`
+
+필수 interface:
+
+```cpp
+namespace fesa::results {
+
+enum class FieldLocation { nodal, element, integration_point };
+
+struct FieldOutput {
+    std::string name;
+    FieldLocation location;
+    std::vector<std::string> components;
+    std::vector<int> entity_ids;
+    std::vector<double> values;
+};
+
+struct HistoryOutput {
+    std::string name;
+    std::vector<double> time;
+    std::vector<double> values;
+};
+
+class ResultFrame {
+public:
+    ResultFrame(int frame_id, double time);
+    int frame_id() const;
+    double time() const;
+    void add_field_output(FieldOutput output);
+    void add_history_output(HistoryOutput output);
+    const std::vector<FieldOutput>& field_outputs() const;
+    const std::vector<HistoryOutput>& history_outputs() const;
+};
+
+class ResultStep {
+public:
+    explicit ResultStep(std::string name);
+    const std::string& name() const;
+    ResultFrame& add_frame(int frame_id, double time);
+    const std::vector<ResultFrame>& frames() const;
+};
+
+} // namespace fesa::results
+```
+
+구현 규칙:
+
+- Result hierarchy는 `ResultStep -> ResultFrame -> FieldOutput/HistoryOutput` 구조를 따른다.
+- Field output은 row identity를 위해 `entity_ids`를 보존한다.
+- Field output values layout은 skeleton 단계에서 row-major flat vector로 둔다.
+- HDF5 file/dataset, schema writer, CSV export는 구현하지 않는다.
+- validation은 크기 consistency만 최소로 확인한다:
+  - `components`가 비어 있으면 `std::invalid_argument`
+  - `entity_ids.size() * components.size() == values.size()`가 아니면 `std::invalid_argument`
+
+## Tests To Write First
+
+- `/tests/unit/results_containers_test.cpp`
+  - ResultStep이 이름과 frame 목록을 보존한다.
+  - ResultFrame이 frame id/time을 보존한다.
+  - nodal displacement FieldOutput을 추가하면 components/entity ids/values가 보존된다.
+  - invalid FieldOutput shape가 `std::invalid_argument`를 던진다.
+  - HistoryOutput이 time/value series를 보존한다.
+
+RED 확인:
+
+1. 테스트 파일을 먼저 작성한다.
+2. targeted CTest를 실행해 missing `results.hpp`로 실패함을 확인한다.
+3. 그 뒤 production header를 작성한다.
+
+## Acceptance Criteria
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R results_containers_test
+```
+
+## 검증 절차
+
+1. 위 AC 커맨드를 실행한다.
+2. 아키텍처 체크리스트를 확인한다:
+   - Results hierarchy가 ARCHITECTURE.md와 일치하는가?
+   - HDF5 API가 results container에 직접 노출되지 않는가?
+   - reference comparison을 위한 entity row identity가 보존되는가?
+3. 결과에 따라 `phases/solver-core-skeleton/index.json`의 step 7을 업데이트한다:
+   - 성공: `"status": "completed"`, `"summary": "ResultStep, ResultFrame, FieldOutput, and HistoryOutput containers added"`
+   - 3회 수정 시도 후 실패: `"status": "error"`, `"error_message": "구체적 에러 내용"`
+   - 사용자 개입 필요: `"status": "blocked"`, `"blocked_reason": "구체적 사유"` 후 중단
+
+## 금지사항
+
+- HDF5 writer/reader를 구현하지 마라.
+- deterministic CSV export를 구현하지 마라.
+- JavaScript/TypeScript/npm fallback을 추가하지 마라.