데이터 모델과 마이그레이션
Note의 분류 필드를 DB, 검증, API, 폼, 목록까지 연결합니다.
데이터 모델과 마이그레이션
Resource 만들기에서 생성한 Note에 선택 입력 항목 분류를 추가합니다. 기존 레코드는 null을 유지하고 새 입력은 80자까지 받습니다. 파일 경로는 모두 App 루트 기준입니다. 배포 업그레이드를 검토하기 전에는 실습 테넌트에만 적용하세요.
아래 wsp_notes는 Workshop 예제의 테이블명입니다. 빠른 시작에서 다른 앱을 만들었다면 생성된 Note migration의 실제 테이블명을 사용하세요.
서비스 중 마이그레이션 단계 지정
배포 중에는 이전 앱과 새 앱이 잠시 함께 실행됩니다. 기존 앱이 아직 사용하는 컬럼이나 제약조건을 제거·교체하는 변경은 이전 앱이 종료된 뒤 실행해야 합니다. 이전 앱과 새 앱이 모두 사용할 수 있는 컬럼 추가처럼 호환되는 변경은 기본 준비 단계에서 실행합니다. 새 앱은 전환 직후부터 뒤늦은 변경이 끝나기 전까지 동작해야 합니다.
예를 들어 기존에는 코드가 전체에서 유일해야 하고 새 버전은 법인별로 유일해야 한다고 합시다. 새 앱을 먼저 배포하되, 이전 제약이 유지되는 동안 다른 법인에 같은 코드를 추가하려는 요청이 거절될 수 있음을 처리합니다. 기존 제약 이름과 실제 데이터에 맞춰 별도 마이그레이션을 작성합니다.
<?php
// database/migrations/tenant/2026_11_12_070000_scope_record_code.php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration {
public function up(): void
{
Schema::table('example_records', function (Blueprint $table): void {
$table->dropUnique('example_records_code_unique');
$table->unique(['legal_entity_id', 'code'], 'example_records_entity_code_unique');
});
}
};이 파일을 전환 후 실행하려면 앱의 database/tenant-migration-phases.json에 확장자를 뺀 파일명을 적습니다.
{
"contract": ["2026_11_12_070000_scope_record_code"]
}이 목록에 없는 마이그레이션은 전환 전에 실행됩니다. 플랫폼은 선언된 파일과 내용을 심사한 뒤 이전 런타임 종료를 확인하고 contract를 실행합니다. 이미 배포된 마이그레이션을 수정하지 말고 새 파일을 추가하세요. 제약을 느슨하게 바꾸더라도 다른 앱이나 연동이 기존 동작에 의존하는지 별도로 확인해야 합니다.
앱 루트에서 nexia check로 소스를 확인하고 제출 심사의 마이그레이션 결과를 확인하세요. nexia check는 이 단계 선언 파일의 내용, 운영 데이터나 실제 전환을 검증하지 않습니다. 동일한 선언을 nexia.json의 tenant_migration_phases로도 작성할 수 있지만, 두 위치에 동시에 선언할 수는 없습니다. 오래된 PHP 개발 도구에서 nexia.json 필드를 인식하지 못하면 위 파일 방식을 사용하거나 nexia setup --devtools로 개발 도구를 갱신하세요.
마이그레이션 심사에 미해결 동시성 결과가 표시되면 이전 릴리스, 소스 식별값과 결과를 확인하세요. 계약 비교, 데이터 보존과 이전 버전 조회에 필요한 증거가 통과한 경우에만 권한 있는 심사자가 판단 이유를 기록할 수 있습니다. 보고서에는 스키마·트리거 정의가 포함되지 않으며 판단은 표시된 릴리스 쌍에만 적용됩니다. 다른 설치 버전은 별도 증거가 필요합니다.
컬럼 추가
database/migrations/tenant/2026_09_07_120000_add_category_to_wsp_notes_table.php를 만듭니다. 파일의 시각은 기존 생성 마이그레이션보다 뒤여야 하며 다른 파일과 겹치지 않아야 합니다.
<?php
declare(strict_types=1);
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
public function up(): void
{
Schema::table('wsp_notes', function (Blueprint $table): void {
$table->string('category', 80)->nullable();
});
}
public function down(): void
{
Schema::table('wsp_notes', function (Blueprint $table): void {
$table->dropColumn('category');
});
}
};게시된 마이그레이션은 수정·삭제하지 않고 새 파일을 추가합니다. 개발 중에는 rollback·수정·migrate를 실행할 수 있으며 checksum 변경은 개발 잠금이 아닌 진단으로 표시합니다. 위 변경은 기존 행을 유지하지만 down() 실행 시 분류 데이터가 삭제되므로 앱 제거·업데이트 실패 시 자동 rollback에 사용하지 않습니다. 생성된 Manifest가 테넌트 마이그레이션 디렉터리를 반환하므로 Core 소스에 경로를 추가할 필요가 없습니다.
일반 앱 런타임은 자기 테이블의 데이터만 변경하며 DDL은 선택한 앱의 별도 migration 작업으로 실행합니다. Core 키를 참조해야 한다면 플랫폼이 명시적으로 허용한 테이블·컬럼의 외래키만 사용합니다. REFERENCES 권한은 Core 데이터의 조회·수정 권한이 아닙니다. 지원하는 PostgreSQL 확장(예: btree_gist)은 플랫폼이 준비하며 앱에 DB 관리자 권한을 제공하지 않습니다. 다른 앱의 데이터는 SDK 공개 계약으로 연결합니다.
허용된 Core 테이블·컬럼, 숫자 키와 공개 UUID의 차이, 전체 FK 마이그레이션 예제는 Core 식별자를 외래키로 참조하기를 참고하세요.
저장과 응답 연결
src/Models/Note.php의 $fillable에 'category'를 넣습니다. nullable 문자열에는 별도 cast가 필요하지 않습니다. src/Http/Controllers/NoteController.php의 store()와 update() 검증 배열 모두에 다음을 추가합니다.
'category' => ['sometimes', 'nullable', 'string', 'max:80'],기본 serialize()는 $record->toArray()에서 응답을 만들므로 일반 속성인 category는 목록·상세·저장 응답에 포함됩니다. 직렬화를 바꾼 App이라면 $hidden과 $visible도 확인하세요. 보호 필드에는 이 공개 방식을 적용하지 않습니다.
resources/js/resources/notes/note-resource-contract.ts의 NoteRecord에 category: string | null;을 추가합니다. 요청과 응답에 추가되는 값은 다음과 같습니다. 전체 생성 요청은 아닙니다.
{ "category": "Planning" }생성 시에는 기존 name이 필요하며 법인 소유 Resource에만 인가된 대상 legal_entity_public_id가 추가로 필요합니다. 수정 요청에서 category를 생략하면 기존 값이 유지되고 null을 보내면 비워집니다.
폼 입력과 정보 표시
note-resource-contract.ts의 기존 NoteInput에 category?: string | null을 추가합니다. RecordSurface와 mutation은 이미 이 타입을 공유하므로 제출 타입을 따로 만들지 않습니다.
RecordForm과 공통 RecordDetails를 소유하는 surface/NoteRecordSurface.tsx를 수정합니다.
- 기존 draft 상태에
category와categoryBaseline을 추가하고initialItem?.category ?? ''로 초기화합니다. 미저장 비교에도 category를 포함합니다. 백그라운드 재조회는 변경 없는 폼만 갱신하고 미저장 필드는 유지해야 합니다. onSubmit({ name, category: draft.category.trim() || null })로 제출합니다. 기존 대상 선택·권한·저장 오류 처리는 유지합니다.- 폼의
onSaved에서 확정된 레코드 값으로 category 기준값을 갱신하고, 현재 입력이 제출값과 같을 때만 현재 값도 교체합니다. 생성 완료 후 이동할 때는 기존 name 처리처럼savedForm경로 상태와 다음 폼의 초기 초안 props에도 이후 입력한 category를 전달합니다. - 기존
NxFormSection안에 다음 입력을 추가합니다. 공통 draft binding을 유지하면 실제 편집 가능한 필드가 입력 컴포넌트의 정상 writer를 통해 Agent에 전달됩니다.
<NxFormField fieldKey="category" label={t('workshop.note.category.label')}
error={firstFieldError(fieldErrors, 'category')}>
{slot => <NxTextInput id={slot.id} aria-describedby={slot.describedBy}
invalid={slot.invalid} value={draft.category} maxLength={80}
disabled={pending || submitDisabled}
onValueChange={value => {
setDraft(current => ({ ...current, category: value }));
onFieldChange?.('category');
}} />}
</NxFormField>RecordDetails에 <NxDetailRow label={t('workshop.note.category.label')}>{item.category || t('common.cell.empty')}</NxDetailRow>를 추가합니다. 상세와 Inspector가 같은 컴포넌트를 사용하므로 레이아웃도 이곳에서 한 번 수정합니다. Section·information-schema·별도 Inspector 파일은 필요하지 않습니다.
NoteModule의 ResourceMutationDescriptor 생성·수정 입력 properties에도 'category' => ['type' => ['string', 'null'], 'maxLength' => 80]을 추가합니다. 이는 인가된 Controller 입력을 설명하는 계약이며 쓰기 권한을 부여하지 않습니다. 서버 검증과 일치시켜 유지하세요.
목록에 표시
surface/NoteListSurface.tsx의 컬럼 배열에 다음을 추가합니다. ResourceTextCell은 기존 import를 사용합니다.
{
key: 'category',
header: t('workshop.note.category.label'),
size: 'meta',
cell: (row) => (
<ResourceTextCell primary={row.category ?? t('common.cell.empty')} />
),
},검색·정렬에도 쓰려면 Note::resourceListFields()에 ->field('category', searchable: true, sortable: true)를 추가합니다. 목록 질의 허용 항목은 백엔드에서 관리하므로 프런트엔드에 별도 목록을 만들지 않습니다.
resources/lang/의 각 파일에 workshop.note.category.label을 넣습니다. en.json은 Category, ko.json은 분류, zh.json은 分类입니다. 캐시 갱신과 검사 절차는 App 다국어 처리에 있습니다.
외부 소비자나 Dashboard builder에 공개할지는 별도로 결정합니다. 공개가 필요하면 NoteModule의 descriptor에 nullable string 필드를 선언하고 계약 버전을 검토하세요. DB 컬럼이 있다고 자동으로 공개 descriptor 필드가 되지는 않습니다.
적용 후 확인
nexia dev를 켜 둔 채 수정합니다. 다른 터미널의 해당 앱 폴더에서 현재 로컬 소스를 명시적으로 적용하세요.
nexia db migrate명령은 현재 소스를 업로드하고 완료까지 기다립니다. 파일 저장만으로 DB에 적용하지 않습니다. 중단됐다면 nexia db status로 확인하거나 동일 --request-id로 복구하세요. dev를 켜 둔 채 db status로 확인하고 롤백·수정·재실행하세요. 비트랜잭션 부분 실패는 앱 DB를 직접 확인·보정한 뒤 명시적으로 재실행하며 관리자 승인은 필요하지 않습니다. 게시된 migration 파일은 유지해야 하며 제출 시 검사합니다.
개발 migration 작업은 일반 파일마다 checksum과 함께 커밋합니다. 뒤의 파일이
실패해도 먼저 성공한 파일은 적용 상태로 남습니다. PostgreSQL의
CREATE INDEX CONCURRENTLY 등에는 Laravel의
public $withinTransaction = false를 명시합니다. 이런 작업은 rollback을
보장할 수 없으므로 중단되면 플랫폼이 결과를 확인하기 전까지 재실행·필수
초기화·fixture 실행을 막습니다. 실패 파일을 삭제해도 이 상태가 해제되지는
않습니다. 복구 목적으로 자동 down()이나 고객 데이터 초기화를 추가하지 마세요.
분류를 넣어 생성하고, 수정하고, 비운 뒤 목록·상세·Inspector를 다시 엽니다. 기존 노트도 열리는지 확인하세요. 폼의 maxLength가 일반 입력을 제한하므로 80자 초과 category는 API에 직접 보내 HTTP 422와 필드 오류를 확인합니다. App 테스트하기에서는 API를 통해 저장 결과와 잘못된 입력을 검사합니다.
생성 기준선에는 UUID, 이름, 시각, soft delete, 소유자 컬럼과 인덱스가 있습니다. 업무별 유일성·감사 증거·동시성 제어까지 자동 제공하지는 않습니다. 필요한 불변 조건은 DB 제약으로 보강하고 충돌하는 쓰기에는 트랜잭션이나 명시적 동시성 검사를 사용합니다. 다른 App의 레코드는 테이블 FK 대신 Resource Reference로 연결합니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.