HeuJung
3cb598ce5f
직전 커밋 산출물에 「Phase 4/5 에서 추가」 문구가 박힌 것을 가 지적했다. 그 문자열은 이번 브랜치에서 쓴 것이 아니라 editor-spec.json 의 description 에 원래 있던 값이고, 새로 만든 생성기가 그것을 문서 앞머리로 옮겨 실으면서 승격된 것이다. 그 필드는 코드가 아니라 사람이 쓴 메모라 실측과 대조되지 않는다. 전수 조사에서 12건 중 5건이 오염돼 있었고, 그중 둘은 바로 아래 실측 표와 정반대를 말했다 — 「controls 는 나중에 추가」라는데 표는 303개가 있다고 한다. 오류도 경고도 나지 않는다: 문서가 자기 자신을 반박한 채로 읽힐 뿐이다. 한 줄 요약은 남기되 실측에서 만든다. 두 표에 흩어진 값을 한 줄로 압축하므로 읽는 쪽이 잃는 것이 없고, 코드에서 파생되므로 어긋날 자리가 사라진다. 도메인 의미는 바로 아래 사람 서술 칸이 이미 담당한다. 스펙 파일의 오염된 메모 5건도 정리했다. 그 파일을 여는 개발자는 문서와 별개로 그 값을 읽고, 확장과 함께 공개 배포된다. 재발 방지는 규정에 명시하고 검사는 두지 않았다 — 어휘를 정규식으로 고정하면 정당한 서술까지 걸리고 목록 밖 표현은 통과해, 「검사했으나 통과」와 「보지 않음」이 구분되지 않는다.
6.2 KiB
마케팅 동의 — 레이아웃 편집기 스펙
레이아웃 편집기에 선언한 팔레트·컨트롤·샘플 데이터 · 진입점: AGENTS.md
선언 요약
| 항목 | 값 |
|---|---|
| manifest | plugins/_bundled/sirsoft-marketing/editor-spec.json |
| 형태 | 단일 파일 (인라인) |
| 스펙 버전 | 1.0.0 |
| 스타일 시스템 | - |
| 다크 모드 전략 | - |
단일 파일 · 프리뷰 샘플 1
마케팅 동의 플러그인의 스펙은 sampleData 한 블록, ID 하나가 전부입니다. 이 플러그인이
소유한 화면이 설정 화면 하나뿐이고 그 화면이 읽는 도메인 데이터가 marketing_settings
하나이기 때문입니다.
스펙이 작다는 것이 곧 부실을 뜻하지는 않습니다. 필요한 만큼만 선언하는 것이 규율이고, 쓰지 않는 블록을 빈 값으로 채워 두면 다음 사람이 그것을 채워야 할 자리로 오해합니다.
선언 블록
| 블록 | 역할 | 항목 수 | 출처 |
|---|---|---|---|
sampleData.byDataSourceId |
레이아웃 data_sources ID 로 붙는 프리뷰 응답 |
1 | editor-spec.json (인라인) |
states.groups 를 두지 않은 것은 이 플러그인의 설정 화면에 상태 변종이 없기
때문입니다. 값이 있든 없든 같은 폼이 그려지므로, 상태를 나눠도 편집기에서 보이는 화면이
달라지지 않습니다.
동의 항목이 여러 개로 늘거나 항목별로 화면이 갈라지는 날이 오면 그때 states 를
신설합니다.
컴포넌트 팔레트
이 확장은 componentPalette 를 선언하지 않습니다 — 편집기 팔레트에 추가되는 항목이 없습니다.
컴포넌트를 만드는 것은 템플릿의 일입니다. 모듈·플러그인은 레이아웃 JSON 에서 템플릿이
제공하는 컴포넌트를 쓰기만 하므로, 편집기 팔레트에 새로 얹을 것이 없습니다. 그래서 이
확장의 스펙은 componentPalette·controls·componentCapabilities·nesting 을 비우고
도메인 데이터(sampleData·states)만 담습니다.
팔레트에 무언가를 추가하고 싶다면 그것은 이 확장이 아니라 활성 템플릿
(sirsoft-admin_basic / sirsoft-basic)의 스펙에 가야 합니다. 여기에 팔레트를 선언하면
템플릿 선언과 같은 자리를 두고 다투게 되고, 어느 쪽이 이기는지가 합본 순서에 좌우됩니다.
샘플 데이터와 페이지 상태
| 자리 | 역할 | 개수 | ID |
|---|---|---|---|
sampleData.byDataSourceId |
레이아웃 data_sources ID 로 붙는 프리뷰 응답 |
1 | marketing_settings |
sampleData.byEndpointPattern |
엔드포인트 패턴으로 붙는 프리뷰 응답 | 미선언 | - |
states.groups |
상태 변종을 적용할 범위(라우트·베이스 레이아웃) | 미선언 | - |
이 확장 레이아웃의 data_source 는 전부 프리뷰 샘플이 붙습니다 (이 확장 또는 번들 템플릿 스펙이 커버).
마케팅 동의는 회원가입 폼·마이페이지 등 다른 확장이 소유한 화면에도 얹힙니다.
그 자리들은 레이아웃 확장 조각으로 주입되므로 이 스펙이 아니라 그 화면을 소유한 쪽의
샘플로 그려집니다 — 여기 sampleData 가 하나뿐인 이유입니다.
이 플러그인이 주입한 조각이 편집기에서 비어 보인다면 고칠 자리는 여기가 아니라 그 화면을 소유한 확장의 스펙입니다.
수정 시 동반 의무
| 이런 변경을 했다면 | 편집기 스펙에서 함께 할 일 |
|---|---|
| 컴포넌트를 새로 만들었다 | componentPalette 에 항목 추가 · componentCapabilities 에 편집 역량 선언 · nesting 에 담길 자리 규정 |
레이아웃에 data_sources 를 추가했다 |
sampleData 에 같은 ID 로 프리뷰 응답 추가 (없으면 편집기 캔버스만 빈 화면) |
_global.* 을 새로 읽는다 |
sampleGlobal 에 baseline 값 추가 |
| 빈 목록·오류 같은 화면 변종을 추가했다 | states 에 변종 추가 · stateLabels 에 친화 명칭 |
| 새 액션·조건 패턴을 도입했다 | actionRecipes / conditionRecipes 에 친화 명칭 등록 |
편집기 스펙은 JSON 이므로 빌드가 필요 없습니다. 다만 편집기 서빙은 활성 디렉토리만 읽으므로(_bundled 폴백 없음) 편집 후 반드시 반영합니다:
php artisan plugin:update sirsoft-marketing --force
위 표는 "무엇을 함께 고치는가" 만 말합니다. 실제로 놓치는 자리는 반영 절차입니다 —
편집기가 읽는 것은 활성 디렉토리이고 _bundled 폴백이 없으므로, _bundled 에서 스펙을
고치고 update 커맨드를 돌리지 않으면 편집기에는 직전 내용이 그대로 보입니다. 파일은
고쳤는데 화면이 안 바뀌었다면 거의 이 경우입니다.
또 하나는 검증 시점입니다. 편집기 스펙은 스키마 검증을 통과해도 "레이아웃이 실제로 쓰는 ID 와 맞는가" 는 확인해 주지 않습니다. 그 어긋남은 편집기 캔버스에서만 빈 화면으로 나타나고 실제 화면은 정상이므로, 위 "샘플 데이터와 페이지 상태" 절의 미커버 목록이 유일한 통로입니다.