docs: add modular refactoring implementation plan

2026-08-16 02:49:35 +09:00
parent 1e5758f3e4
commit 2ab2e0c641
28 changed files with 2876 additions and 1 deletions
@@ -0,0 +1,130 @@
+# Step 14: Runtime Element and Factory
+
+## 담당 역할과 필수 스킬
+
+- 담당 역할: `implementation-agent`
+- 필수 스킬: `harness`, `fesa-cpp-msvc-tdd`
+- 이 Step만 `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`로 수행한다.
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/CODINGSTYLE.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/linear-static-3d-euler-beam/formulation.md`
+- `/docs/linear-static-mitc4-shell/formulation.md`
+- `/docs/cpp-object-oriented-modular-refactoring/implementation-plan.md`
+- Step 12 material/property hierarchy files
+- Step 13 element definition and Domain files
+- `/include/fesa/elements/euler_beam_3d.h`, `/src/fesa/elements/euler_beam_3d.cpp`
+- `/include/fesa/elements/mitc4_shell.h`, `/src/fesa/elements/mitc4_shell.cpp`
+- element/model/result record tests
+- `/src/fesa/CMakeLists.txt`, `/tests/CMakeLists.txt`
+- `/phases/cpp-object-oriented-modular-refactoring/index.json`
+- `/phases/cpp-object-oriented-modular-refactoring/step14.md`
+
+## 작업
+
+Requirement `R-ELEMENT-001`의 numerical runtime boundary를 구현한다.
+
+1. `/tests/unit/elements/element_factory_test.cpp`를 먼저 추가한다. `C-ELEMENT-001` covers
+   base-pointer virtual destruction, B33 and MITC4 factory success, stable DOF layout, stiffness
+   and recovery through base, unknown/mismatched property/material/null rejection.
+2. Missing `element.h` and `element_factory.h` cause RED compile failure.
+3. Create `/include/fesa/elements/element.h`,
+   `/include/fesa/elements/element_factory.h`, and
+   `/src/fesa/elements/element_factory.cpp`; register the source and factory test in CMake.
+4. Candidate interfaces:
+
+```cpp
+struct ElementDofLayout {
+  SourceEntityId source_id;
+  std::vector<EntityIndex> node_indices;
+  std::vector<DofComponent> components_per_node;
+};
+
+struct ElementStiffnessContribution {
+  ElementDofLayout layout;
+  Matrix values;
+};
+
+struct BeamElementResultRows {
+  std::vector<EndpointResultRow> endpoint_rows;
+  std::vector<GaussResultRow> gauss_rows;
+  std::vector<StressS11Row> stress_rows;
+};
+
+struct ShellElementResultRows {
+  std::vector<ShellResultRow> rows;
+  double physical_strain_energy;
+};
+
+using ElementResultPayload =
+    std::variant<BeamElementResultRows, ShellElementResultRows>;
+
+struct ElementResultBundle {
+  SourceEntityId source_id;
+  ElementResultPayload payload;
+};
+
+class Element {
+ public:
+  virtual ~Element() = default;
+  virtual const ElementDofLayout& DofLayout() const noexcept = 0;
+  virtual Result<ElementStiffnessContribution> ComputeStiffness() const = 0;
+  virtual Result<ElementResultBundle> Recover(
+      const Vector& full_displacement) const = 0;
+};
+
+using ElementView = std::vector<std::reference_wrapper<const Element>>;
+
+class ElementFactory {
+ public:
+  Result<std::unique_ptr<Element>> Create(
+      const ElementDefinition& definition,
+      const Domain& domain) const;
+};
+```
+
+5. The linear-static candidate owns `std::vector<std::unique_ptr<Element>>` and builds an
+   `ElementView` whose lifetime is bounded by that owner. Carrier type locations may be adjusted
+   to avoid circular public dependencies, but semantics and names must stay consistent for
+   Steps 15–17.
+6. Factory centralizes explicit definition/property/material kind compatibility, bounds checks,
+   and structured diagnostic. It may use a checked kind discriminator and concrete access after
+   validation; downstream consumers must not downcast.
+7. Existing B33/MITC4 numerical kernels implement `Element` without changing formulation or adding
+   fields meaningless to the other element.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build .harness/build --config Debug --target fesa_unit_tests
+ctest --test-dir .harness/build -C Debug `
+  -R "ElementFactory|EulerBeam3D|Mitc4Shell" --output-on-failure
+rg -n "dynamic_cast" src/fesa include/fesa
+& "C:/Program Files/LLVM/bin/clang-format.exe" --dry-run --Werror `
+  include/fesa/elements/element.h include/fesa/elements/element_factory.h `
+  src/fesa/elements/element_factory.cpp tests/unit/elements/element_factory_test.cpp
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug --show-only=json-v1
+ctest --test-dir .harness/build -C Debug --output-on-failure
+```
+
+The downcast scan must show no newly scattered consumer downcasts. If the centralized factory uses
+a checked cast, document the preceding kind validation and keep it in the factory only.
+
+## 검증 및 상태 갱신
+
+- RED, success/rejection cases, base stiffness/recovery, downcast scan and full CTest를 summary에 기록한다.
+- Formulation or result identity changes are `error`.
+- 성공 시 현재 Step만 `completed`로 갱신한다.
+- timestamp, retry, commit, advancement는 Executor 소유다.
+
+## 금지사항
+
+- Semantic definition and runtime kernel을 one class로 합치지 마라.
+- Future element registry/global static registration을 추가하지 마라.
+- Giant common result record with meaningless optional fields를 만들지 마라.
+- 직접 commit하거나 hook script를 수동 실행하지 마라.