feat(core,extensions): 확장 문서 호칭 통일과 레이아웃 편집기 문서 축 신설
확장 문서의 제품 호칭을 「그누보드7」로 통일했다. 가 지적한 두 문구는 개별 오타가 아니라 생성기가 찍는 정형 문구여서, 산출물이 아니라 방출 지점 세 곳을 먼저 고쳤다 — 그러지 않으면 21번째 확장부터 다시 샌다. 정리 범위는 확장 문서와 그 생성기까지이며, 코어 docs 와 언어팩 표시명은 의도적으로 남긴다. 레이아웃 편집기 대응 문서가 없던 문제는 확장마다 docs/editor-spec.md 를 두어 닫았다. 실측은 EditorSpecCollector 가 유지하며, 합본에 런타임과 같은 EditorSpecAssembler 를 써서 문서가 말하는 스펙과 편집기가 읽는 스펙이 갈라질 경로를 두지 않았다. 스펙을 두지 않은 확장에도 문서를 둔다 — 미보유가 정상일 수 있고, 그 정상 여부를 적을 자리가 없으면 다음 사람이 부재를 누락으로 오해하거나 필요한 시점을 놓친다. 초안이 낸 수치 다섯 건이 틀렸고 전부 오류 없이 "사실" 로 실릴 값이었다. 블록 최상위 키를 세어 팔레트가 79 대신 3 이 되던 것, `_` 접두 일괄 배제가 실제 항목을 삼키던 것 등을 정정했다. 게이트를 인위적으로 깨뜨려 점검한 결과 사각 하나가 드러났다 — 채워 넣으라는 표시만 지우고 서술을 쓰지 않으면 검사를 통과해, 빈 문서가 완비로 집계됐다. 미채움을 두 축으로 만들어 닫았고 되돌림으로 검산했다. 편집기 스펙 편집 시 규정이 주입되지 않던 것과 스캐폴딩 안내가 새 문서를 빠뜨리던 것도 함께 고쳤다.
This commit is contained in:
HeuJung committed
1 parent
eb7ff4ec6a
commit
3a0aba85bc
114 files changed
+3433
-129
No files matched your search
@@ -10,6 +10,7 @@
|
||||
3. 분할 형식: manifest(editor-spec.json) + `$include` 맵 → editor-spec/{block}.json. 서버가 합본해 단일 spec 으로 서빙
|
||||
4. 서빙은 활성 디렉토리만 기준 (_bundled 폴백 없음). _bundled 작업분은 {type}:update 로 활성 반영 후 런타임 노출
|
||||
5. 친화 라벨은 $t: 다국어 키, comment 는 작성자 메모(엔진 무시), 알려진 필드 외 자유 필드는 보존만
|
||||
6. 확장별 선언 실측·동반 의무는 그 확장의 docs/editor-spec.md 가 소유 (ext:docgen 이 유지)
|
||||
```
|
||||
|
||||
## 개요
|
||||
@@ -60,6 +61,71 @@ editor-spec.json 이 커지면(코어 admin 템플릿은 단일 파일 18,000줄
|
||||
|
||||
런타임 서빙은 **활성 디렉토리(`templates/{id}/...`)만** 읽는다. `_bundled` 폴백은 없다. `_bundled` 에서 작업한 분할본은 `{type}:update {id} --force` 로 활성 디렉토리에 반영된 뒤에만 편집기에 나타난다. JSON 만 바뀐 경우 빌드는 불필요하고 update 만 실행한다.
|
||||
|
||||
## 확장 개발자의 작업 순서
|
||||
|
||||
아래 규칙들은 블록 하나하나의 **문법**을 말한다. 실제로 확장을 고칠 때 필요한 것은 그
|
||||
앞의 판단이다 — 무엇을 손대야 하고, 무엇을 빠뜨리면 어떤 증상이 나는가.
|
||||
|
||||
### 어느 확장의 스펙에 넣는가
|
||||
|
||||
컴포넌트를 만드는 것은 템플릿의 일이고, 모듈·플러그인은 템플릿이 제공하는 컴포넌트를
|
||||
쓰기만 한다. 그래서 두 부류가 담는 것이 다르다.
|
||||
|
||||
| 선언할 것 | 자리 |
|
||||
|---|---|
|
||||
| `componentPalette` · `controls` · `componentCapabilities` · `nesting` | **템플릿** 스펙 |
|
||||
| `sampleData` · `sampleGlobal` · `states` · `*Recipes` | 그 데이터를 소유한 **모듈·플러그인** 스펙 |
|
||||
| 여러 확장이 함께 쓰는 공용 ID(`settings` · `roles` · `me` 등) | **템플릿** 스펙 |
|
||||
|
||||
공용 ID 를 확장마다 각자 선언하면 같은 ID 의 샘플이 여러 곳에 생기고, 그것들이 갈라져도
|
||||
오류가 나지 않는다 — 어느 것이 쓰이는지가 병합 순서에 좌우된다.
|
||||
|
||||
모듈·플러그인이 `componentPalette` 를 선언하면 템플릿 선언과 같은 자리를 두고 다투게
|
||||
되므로 두지 않는다. 팔레트에 얹고 싶은 것이 있다면 그것은 활성 템플릿의 스펙으로 간다.
|
||||
|
||||
### 무엇을 빠뜨렸는지는 증상으로 가른다
|
||||
|
||||
편집기는 선언되지 않은 것을 **없는 것**으로 다룰 뿐 실패를 보고하지 않는다. 그래서
|
||||
빠뜨린 자리를 알려 주는 것은 오류 메시지가 아니라 증상이다.
|
||||
|
||||
| 증상 | 빠뜨린 자리 |
|
||||
|---|---|
|
||||
| 컴포넌트가 팔레트 목록에 아예 없다 | `componentPalette.entries` |
|
||||
| 팔레트에 등록했는데 목록에 안 보인다 | `componentPalette.groups` 의 어느 묶음에도 없다 |
|
||||
| 팔레트에서 끌어 놓을 수 없다 | `nesting.draggable` |
|
||||
| 놓을 자리가 없다(컨테이너가 거부한다) | `nesting.containers` |
|
||||
| 놓았는데 속성 패널이 비어 있다 | `componentCapabilities` |
|
||||
| 속성 패널에 특정 항목만 없다 | `controls` |
|
||||
| 캔버스의 한 영역만 빈 화면이다 | `sampleData.byDataSourceId`(또는 `byEndpointPattern`) |
|
||||
| 값이 `undefined` 라 영역 전체가 사라진다 | `sampleGlobal` |
|
||||
| 특정 상태(빈 목록·오류·모달 열림)를 볼 수 없다 | `states` |
|
||||
|
||||
캔버스는 실제 API 를 부르지 않고 `sampleData` 로 그린다. 그래서 레이아웃에
|
||||
`data_source` 를 추가하고 샘플을 붙이지 않으면 **편집기에서만** 그 자리가 비고 실제
|
||||
화면은 정상 동작한다 — 오류도 경고도 서버 로그도 남지 않는다.
|
||||
|
||||
캔버스는 또한 정적 시뮬레이션이라 클릭·응답으로 만들어지는 상태를 스스로 만들지 못한다.
|
||||
모바일 드로어(햄버거 클릭), 쿠키 동의 배너(동의 전 방문자), 본인인증 창(428 응답)처럼
|
||||
**어떤 사건 뒤에만 나타나는 화면**은 `states` 로 그 상태를 주입해 두지 않으면 편집
|
||||
자체가 불가능하다.
|
||||
|
||||
### 반영 절차
|
||||
|
||||
편집기 스펙은 JSON 이므로 빌드가 필요 없다. 다만 서빙은 **활성 디렉토리만** 읽고
|
||||
`_bundled` 폴백이 없으므로, `_bundled` 에서 고친 뒤 update 커맨드를 돌리지 않으면
|
||||
편집기에는 직전 내용이 그대로 보인다. 파일은 고쳤는데 화면이 안 바뀌었다면 거의 이 경우다.
|
||||
|
||||
```bash
|
||||
php artisan {module|plugin|template}:update {id} --force
|
||||
```
|
||||
|
||||
### 확장별 실측은 그 확장이 소유한다
|
||||
|
||||
어느 확장이 무엇을 얼마나 선언했는지, 그 확장에서 프리뷰 샘플이 붙지 않는 `data_source`
|
||||
가 무엇인지는 **그 확장의 `docs/editor-spec.md`** 가 답한다. `php artisan ext:docgen` 이
|
||||
그 실측 부분을 유지하므로 스펙을 고친 뒤 재실행한다. 코어 문서(이 문서)에는 블록 문법과
|
||||
공통 판단 기준만 둔다.
|
||||
|
||||
## 블록별 작성 규칙
|
||||
|
||||
### componentPalette — 요소 추가 팔레트
|
||||
@@ -240,4 +306,6 @@ export function registerSirsoftAdminBasicEditorWidgets(): void {
|
||||
- 타입 SSoT: `resources/js/core/template-engine/layout-editor/spec/specTypes.ts`
|
||||
- 로더(fetch + 병합): `resources/js/core/template-engine/layout-editor/spec/editorSpecLoader.ts`
|
||||
- 서버 합본 헬퍼: `app/Extension/Helpers/EditorSpecAssembler.php`
|
||||
- 확장별 실측 문서 생성: `php artisan ext:docgen` — 각 확장 `docs/editor-spec.md`
|
||||
- 확장 문서 규정: [extension-documentation.md](extension-documentation.md)
|
||||
- 서빙: `app/Http/Controllers/Api/Public/PublicTemplateController.php`, `app/Http/Controllers/Api/Admin/AdminTemplateAssetController.php`, `app/Services/ModuleService.php`, `app/Services/PluginService.php`
|
||||
@@ -54,11 +54,14 @@
|
||||
├─ components.md 제공 컴포넌트 [템플릿]
|
||||
├─ layouts.md 레이아웃 목록 · 라우트 매핑 [템플릿]
|
||||
├─ handlers.md 템플릿 전용 핸들러 · 부트스트랩 [템플릿]
|
||||
├─ editor-spec.md 레이아웃 편집기 선언 · 프리뷰 샘플 커버리지
|
||||
└─ api/ API 레퍼런스 (별도 체계)
|
||||
```
|
||||
|
||||
템플릿은 API·모델·훅 축이 사실상 비므로 골격이 다르다. `ext:docgen` 이 manifest 유형을 보고 골격을 고르므로 유형을 직접 지정할 필요가 없다.
|
||||
|
||||
`docs/editor-spec.md` 만은 **세 유형 공통**이다. 편집기 스펙(`editor-spec.json`)을 두지 않는 확장에도 문서를 두는 것은, 미보유가 정상일 수 있고 그 정상 여부를 적을 자리가 필요하기 때문이다 — "이 확장은 왜 스펙이 없어도 되는가 / 언제 필요해지는가" 가 어디에도 없으면 다음 사람이 그 부재를 누락으로 오해하거나 반대로 필요한 시점을 놓친다.
|
||||
|
||||
이 문서들은 `{ext}/` 안에 있으므로 **릴리즈 페이로드에 실리는 공개 배포물**이다. 확장 저장소를 받은 사람이 그대로 읽는다.
|
||||
|
||||
## 3. 역할 경계와 SSoT
|
||||
@@ -93,6 +96,7 @@
|
||||
| `docs/components.md` (템플릿) | `제공 컴포넌트` |
|
||||
| `docs/layouts.md` (템플릿) | `레이아웃 목록` · `라우트 매핑` |
|
||||
| `docs/handlers.md` (템플릿) | `템플릿 전용 핸들러` · `부트스트랩` |
|
||||
| `docs/editor-spec.md` | `선언 요약` · `선언 블록` · `컴포넌트 팔레트` · `샘플 데이터와 페이지 상태` · `수정 시 동반 의무` |
|
||||
|
||||
목록의 SSoT 는 생성기이므로, 직접 옮겨 적기보다 `ext:docgen --init` 이 만든 골격에서 시작하는 편이 어긋나지 않는다.
|
||||
|
||||
|
||||
Reference in new issue
Block a user