gnuboard7-hello_module

Imported from gnuboard/g7 (modules/_bundled/gnuboard7-hello_module/AGENTS.md). Install upstream with npx skills add gnuboard/g7 --skill gnuboard7-hello_module. Copyright stays with the author.

그누보드7 Hello 모듈 — 에이전트 가이드

이 문서는 이 모듈을 수정하는 에이전트·확장개발자를 위한 것입니다. 도입 검토·운영 관점은 README.md 를 보세요.

TL;DR (5초 요약)

1. 유형: 모듈 (gnuboard7-hello_module) — 학습용 최소 샘플. 메모(Memo) 하나로 모듈의 전 계층을 1파일씩 시연한다. 실제 업무 기능 없음, `hidden: true`
2. 확장 방식: 발행 훅 1개(`memo.created`) — `gnuboard7-hello_plugin` 이 그것을 구독하고, `gnuboard7-hello_user_template` 은 공개 API 를 소비한다
3. 건드리면 안 되는 것: 샘플에 기능 추가(짧게 유지), `hidden` 제거, 검증을 Service 에 넣기, Repository 구체 클래스 주입 — 샘플은 규약의 본보기다
4. 작업 위치: `modules/_bundled/gnuboard7-hello_module` — 활성 디렉토리 직접 수정 금지
5. 반영: `php artisan module:update gnuboard7-hello_module --force`

1. 이 확장은 무엇인가

학습용 최소 샘플 모듈입니다. 실제 업무 기능을 제공하지 않으며, 모듈이 필요로 하는 계층을 하나씩만 담아 "모듈은 이런 모양이다" 를 보여주는 것이 유일한 목적입니다.

도메인은 메모(Memo) 하나이고 필드는 셋뿐입니다. 그 위에 Model · Migration · Factory · Seeder · Repository(인터페이스 + 구현) · Service · FormRequest · Resource · Controller · Listener · Layout · Test · 다국어(백엔드 PHP + 프론트 JSON)가 각 1개씩 있습니다. 실제 모듈은 이 계층을 엔티티 수만큼 늘린 것입니다.

설계 원칙: 짧게 유지한다. 샘플의 가치는 완결성이 아니라 한눈에 읽히는 것입니다. 여기에 기능을 더하면 계층 구조를 보러 온 사람이 도메인 로직을 읽게 되므로, 새 기능이 필요하면 이 샘플이 아니라 별도 확장을 만듭니다.

manifest.hidden = true 라 관리자 UI 의 모듈 목록에 나타나지 않습니다. artisan CLI 로는 정상 설치·활성화됩니다 — 학습용이 운영 화면에 섞이지 않게 하면서도 실제로 동작해 봐야 학습이 되기 때문입니다.

의도적으로 하지 않는 것: 검색 색인·SEO·알림·스케줄·미들웨어·브로드캐스트. 각 축의 사용법은 그것을 실제로 쓰는 확장(게시판·이커머스)의 문서가 다룹니다.

2. 디렉토리 지도

3. 핵심 흐름

계층 하나씩을 지나는 가장 짧은 CRUD 가 이 샘플의 전부입니다.

메모 생성: Admin\MemoController::store() → MemoRequest(검증) → MemoService::create() → MemoRepositoryInterface(인터페이스 주입) → MemoRepository → Memo 모델. 저장 직후 gnuboard7-hello_module.memo.created 액션 훅을 발행하고, LogMemoCreatedListener 가 그것을 받아 로그를 남깁니다.

이 한 흐름에 그누보드7 모듈의 규약이 전부 들어 있습니다:

• 검증은 Service 가 아니라 FormRequest 에 둔다
• Service 는 구체 Repository 가 아니라 인터페이스를 주입받는다
• 부가 작업(로그·알림·집계)은 Service 안이 아니라 훅 리스너로 뺀다
• 응답 형태는 컨트롤러가 조립하지 않고 Resource 가 정한다

같은 모듈이 자기 훅을 구독하는 것도 의도된 예시입니다. 실제로는 다른 확장이 구독하지만, 샘플 하나만 설치해도 훅 흐름이 눈에 보이게 하려고 리스너를 같이 넣었습니다 — gnuboard7-hello_plugin 을 함께 설치하면 바깥에서 구독하는 모습도 볼 수 있습니다.

4. 확장점

발행 훅 하나(memo.created)가 전부입니다. 실제 모듈이라면 도메인마다 before_* → filter_*_data → after_* 3단을 두지만, 샘플에서는 훅이 무엇인지만 보이면 되므로 하나로 줄였습니다.

gnuboard7-hello_plugin 이 이 훅을 구독합니다. 두 샘플을 함께 설치하면 "모듈이 발행하고 플러그인이 받는" 확장 시스템의 기본 관계를 실제로 확인할 수 있습니다 — 플러그인이 그 모듈에 dependencies 로 묶여 있는 것도 그 관계의 표현입니다.

gnuboard7-hello_user_template 도 이 모듈에 의존합니다. 그쪽은 훅이 아니라 공개 API 를 data_sources 로 소비하는 관계이며, 모듈이 데이터를, 템플릿이 화면을 담당하는 경계를 보여줍니다.

미들웨어·브로드캐스트 채널·스케줄·알림은 없습니다. 샘플에 넣으면 계층 구조를 보러 온 사람이 읽어야 할 코드가 늘어납니다.

5. 수정 시 동반 의무

• _bundled 에서만 수정하고 php artisan module:update gnuboard7-hello_module --force 로 반영
• manifest version 상향 시 package.json · package-lock.json · composer.json 동기화 + CHANGELOG 기재
• 스키마 변경 시 마이그레이션(한국어 comment + down()) + 기설치본 백필용 업그레이드 스텝
• 발행 훅 추가·이름 변경 시 php artisan ext:docgen 재실행 (구독하는 확장의 계약이 바뀝니다)
• API 표면 변경 시 php artisan api:docgen --scope=module:gnuboard7-hello_module 재실행 + docs/api/** 갱신
• 레이아웃 JSON 변경 시 빌드 없이 update 만 — 신규 Tailwind 클래스는 빌드된 CSS 에 존재하는지 확인
• 다국어 키 추가 시 ko·en 동시 반영 + 번들 ja 언어팩 증분 동기화
• 계층을 늘리기 전에 "이것이 샘플에 필요한가" 를 먼저 묻는다 — 샘플의 가치는 한눈에 읽히는 것이다
• manifest.hidden = true 를 유지 (복제본에서만 제거)
• 규약(FormRequest 검증 · Repository 인터페이스 주입 · 훅으로 부가작업 분리)이 흐트러지지 않았는지 확인 — 이 코드는 본보기로 읽힌다
• docs/extension/sample-extensions.md 의 계층 표와 어긋나지 않는지 확인 (파일을 추가·삭제했다면 그 표도 갱신)
• 발행 훅 이름을 바꾸면 gnuboard7-hello_plugin 의 구독이 조용히 끊긴다
• 레이아웃·컴포넌트·data_source 를 건드렸다면 docs/editor-spec.md 를 확인 — 이 확장은 편집기 스펙이 없어 memoData · memos 가 편집기 캔버스에서 빈 화면으로 보인다. data_source 를 더 늘리면 그 자리도 같은 상태가 된다

6. 금지 패턴

7. 테스트 실행

기저 TestCase: tests/ModuleTestCase.php — 확장 테스트는 이 클래스를 상속합니다 (Tests\TestCase 직접 상속 금지).

# PHPUnit (변경 범위만) (Bash)
php vendor/bin/phpunit modules/_bundled/gnuboard7-hello_module/tests --filter='<대상클래스>'

무필터 전체 실행은 금지되어 있습니다 — 변경 범위에 걸리는 대상만 지정해 실행합니다.

8. 문서 목차