docs: [종합정비] Phase 1 시스템 현황 문서 14개 작성
- system/overview.md: 전체 아키텍처 개요 - system/api-structure.md: API 구조 (220 모델, 1027 엔드포인트, 18 라우트 도메인) - system/react-structure.md: React 구조 (249 페이지, 612 컴포넌트) - system/mng-structure.md: MNG 구조 (171 컨트롤러, 436 Blade 뷰) - system/docker-setup.md: Docker 7 컨테이너 구성 - system/database/README.md + 9개 도메인 스키마 (270+ 테이블) - core, hr, sales, production, finance, boards, files, system, erp-analysis Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
523
system/board-system-spec.md
Normal file
523
system/board-system-spec.md
Normal file
@@ -0,0 +1,523 @@
|
||||
# 게시판 시스템 스펙
|
||||
|
||||
**작성일**: 2025-11-27
|
||||
**상태**: 설계 완료, 구현 대기
|
||||
**관련 프로젝트**: mng, api
|
||||
|
||||
---
|
||||
|
||||
## 1. 개요
|
||||
|
||||
### 1.1 목적
|
||||
- mng에서 **시스템 게시판**을 생성하여 모든 테넌트에게 제공
|
||||
- sam(api)에서 테넌트별 **자체 게시판** 생성 가능
|
||||
- 공지사항, 1:1 문의, FAQ 등 다양한 게시판 유형 지원
|
||||
|
||||
### 1.2 핵심 개념
|
||||
|
||||
| 구분 | 설명 |
|
||||
|------|------|
|
||||
| **시스템 게시판** | mng에서 생성, `is_system=true`, 모든 테넌트에서 접근 가능 |
|
||||
| **테넌트 게시판** | sam에서 생성, `is_system=false`, 해당 테넌트만 접근 |
|
||||
| **board_type** | 자유 입력 (notice, qna, faq, free 등 제한 없음) |
|
||||
|
||||
### 1.3 역할 분리
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ mng (상위 관리자) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • 시스템 게시판 CRUD (is_system = true) │
|
||||
│ • 게시판 필드 정의 (board_settings) │
|
||||
│ • 게시판 유형 자유 설정 (board_type) │
|
||||
│ • tenant_id = NULL │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓ 전체 테넌트 공개
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ sam (api - 테넌트용) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • 테넌트 게시판 CRUD (is_system = false) │
|
||||
│ • 시스템 게시판 사용 (읽기 전용 구조) │
|
||||
│ • 게시글 CRUD (posts) │
|
||||
│ • tenant_id = 현재 테넌트 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 데이터베이스 스키마
|
||||
|
||||
### 2.1 기존 테이블 현황
|
||||
|
||||
현재 구현된 테이블 (6개):
|
||||
- `boards` - 게시판 정의
|
||||
- `board_settings` - EAV 커스텀 필드 정의
|
||||
- `posts` - 게시글
|
||||
- `post_custom_field_values` - EAV 커스텀 필드 값
|
||||
- `board_comments` - 댓글
|
||||
- `board_files` - 파일 첨부
|
||||
|
||||
### 2.2 boards 테이블 확장
|
||||
|
||||
**추가 컬럼:**
|
||||
|
||||
| 컬럼 | 타입 | 설명 |
|
||||
|------|------|------|
|
||||
| `is_system` | TINYINT(1) DEFAULT 0 | 시스템 게시판 여부 (1=전체 공개) |
|
||||
| `board_type` | VARCHAR(50) NULL | 게시판 유형 (자유 입력) |
|
||||
|
||||
**변경 컬럼:**
|
||||
|
||||
| 컬럼 | 변경 내용 |
|
||||
|------|----------|
|
||||
| `tenant_id` | NOT NULL → **NULL 허용** (시스템 게시판용) |
|
||||
|
||||
**최종 boards 테이블 구조:**
|
||||
|
||||
```sql
|
||||
CREATE TABLE boards (
|
||||
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
||||
tenant_id BIGINT UNSIGNED NULL COMMENT '테넌트 ID (NULL=시스템 게시판)',
|
||||
is_system TINYINT(1) DEFAULT 0 COMMENT '시스템 게시판 여부 (1=전체 테넌트 공개)',
|
||||
board_type VARCHAR(50) NULL COMMENT '게시판 유형 (notice, qna, faq, free 등)',
|
||||
board_code VARCHAR(50) NOT NULL COMMENT '게시판 코드 (URL용)',
|
||||
name VARCHAR(100) NOT NULL COMMENT '게시판명',
|
||||
description TEXT NULL COMMENT '게시판 설명',
|
||||
editor_type VARCHAR(20) DEFAULT 'wysiwyg' COMMENT '에디터 타입',
|
||||
allow_files TINYINT(1) DEFAULT 1 COMMENT '파일 첨부 허용',
|
||||
max_file_count INT DEFAULT 5 COMMENT '최대 파일 수',
|
||||
max_file_size INT DEFAULT 20480 COMMENT '최대 파일 크기 (KB)',
|
||||
extra_settings JSON NULL COMMENT '추가 설정 (권한, 옵션 등)',
|
||||
is_active TINYINT(1) DEFAULT 1 COMMENT '활성 여부',
|
||||
created_at TIMESTAMP NULL,
|
||||
updated_at TIMESTAMP NULL,
|
||||
created_by BIGINT UNSIGNED NULL,
|
||||
updated_by BIGINT UNSIGNED NULL,
|
||||
deleted_at TIMESTAMP NULL,
|
||||
deleted_by BIGINT UNSIGNED NULL,
|
||||
|
||||
INDEX idx_boards_tenant (tenant_id),
|
||||
INDEX idx_boards_is_system (is_system),
|
||||
INDEX idx_boards_board_type (board_type),
|
||||
UNIQUE INDEX uk_boards_code (tenant_id, board_code)
|
||||
);
|
||||
```
|
||||
|
||||
### 2.3 board_settings 테이블 (EAV 필드 정의)
|
||||
|
||||
현재 구조 유지:
|
||||
|
||||
```sql
|
||||
CREATE TABLE board_settings (
|
||||
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
||||
board_id BIGINT UNSIGNED NOT NULL COMMENT '게시판 ID',
|
||||
name VARCHAR(100) NOT NULL COMMENT '필드명',
|
||||
field_key VARCHAR(50) NOT NULL COMMENT '필드 키',
|
||||
field_type VARCHAR(30) NOT NULL COMMENT '필드 타입 (text, number, select, date 등)',
|
||||
field_meta JSON NULL COMMENT '필드 메타 (옵션, 유효성 등)',
|
||||
is_required TINYINT(1) DEFAULT 0 COMMENT '필수 여부',
|
||||
sort_order INT DEFAULT 0 COMMENT '정렬 순서',
|
||||
created_at TIMESTAMP NULL,
|
||||
updated_at TIMESTAMP NULL,
|
||||
created_by BIGINT UNSIGNED NULL,
|
||||
updated_by BIGINT UNSIGNED NULL,
|
||||
|
||||
INDEX idx_board_settings_board (board_id),
|
||||
FOREIGN KEY (board_id) REFERENCES boards(id) ON DELETE CASCADE
|
||||
);
|
||||
```
|
||||
|
||||
### 2.4 posts 테이블
|
||||
|
||||
현재 구조 유지 (SoftDeletes 적용):
|
||||
|
||||
```sql
|
||||
CREATE TABLE posts (
|
||||
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
||||
tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID',
|
||||
board_id BIGINT UNSIGNED NOT NULL COMMENT '게시판 ID',
|
||||
user_id BIGINT UNSIGNED NOT NULL COMMENT '작성자 ID',
|
||||
title VARCHAR(255) NOT NULL COMMENT '제목',
|
||||
content LONGTEXT NULL COMMENT '내용',
|
||||
editor_type VARCHAR(20) DEFAULT 'wysiwyg' COMMENT '에디터 타입',
|
||||
ip_address VARCHAR(45) NULL COMMENT 'IP 주소',
|
||||
is_notice TINYINT(1) DEFAULT 0 COMMENT '공지 여부',
|
||||
is_secret TINYINT(1) DEFAULT 0 COMMENT '비밀글 여부',
|
||||
views INT DEFAULT 0 COMMENT '조회수',
|
||||
status VARCHAR(20) DEFAULT 'active' COMMENT '상태',
|
||||
created_at TIMESTAMP NULL,
|
||||
updated_at TIMESTAMP NULL,
|
||||
created_by BIGINT UNSIGNED NULL,
|
||||
updated_by BIGINT UNSIGNED NULL,
|
||||
deleted_at TIMESTAMP NULL,
|
||||
deleted_by BIGINT UNSIGNED NULL,
|
||||
|
||||
INDEX idx_posts_tenant_board (tenant_id, board_id),
|
||||
INDEX idx_posts_status (status),
|
||||
FOREIGN KEY (board_id) REFERENCES boards(id) ON DELETE CASCADE
|
||||
);
|
||||
```
|
||||
|
||||
### 2.5 post_custom_field_values 테이블 (EAV 값)
|
||||
|
||||
현재 구조 유지:
|
||||
|
||||
```sql
|
||||
CREATE TABLE post_custom_field_values (
|
||||
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
||||
post_id BIGINT UNSIGNED NOT NULL COMMENT '게시글 ID',
|
||||
field_id BIGINT UNSIGNED NOT NULL COMMENT '필드 ID (board_settings.id)',
|
||||
value TEXT NULL COMMENT '필드 값',
|
||||
created_at TIMESTAMP NULL,
|
||||
updated_at TIMESTAMP NULL,
|
||||
created_by BIGINT UNSIGNED NULL,
|
||||
updated_by BIGINT UNSIGNED NULL,
|
||||
|
||||
INDEX idx_pcfv_post (post_id),
|
||||
INDEX idx_pcfv_field (field_id),
|
||||
FOREIGN KEY (post_id) REFERENCES posts(id) ON DELETE CASCADE,
|
||||
FOREIGN KEY (field_id) REFERENCES board_settings(id) ON DELETE CASCADE
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 게시판 유형 (board_type)
|
||||
|
||||
### 3.1 권장 유형
|
||||
|
||||
| board_type | 설명 | 특징 |
|
||||
|------------|------|------|
|
||||
| `notice` | 공지사항 | 관리자만 작성, 전체 공개 |
|
||||
| `qna` | 1:1 문의 | 작성자+관리자만 열람, 비밀글 기본 |
|
||||
| `faq` | FAQ | 관리자 작성, 카테고리 분류 |
|
||||
| `free` | 자유게시판 | 댓글 허용, 전체 공개 |
|
||||
| `gallery` | 갤러리 | 이미지 중심 |
|
||||
| `download` | 자료실 | 파일 첨부 중심 |
|
||||
|
||||
### 3.2 유형별 extra_settings 예시
|
||||
|
||||
```json
|
||||
// notice (공지사항)
|
||||
{
|
||||
"write_roles": ["admin", "manager"],
|
||||
"allow_comment": false,
|
||||
"allow_secret": false
|
||||
}
|
||||
|
||||
// qna (1:1 문의)
|
||||
{
|
||||
"write_roles": ["*"],
|
||||
"allow_comment": true,
|
||||
"default_secret": true,
|
||||
"only_author_view": true
|
||||
}
|
||||
|
||||
// faq
|
||||
{
|
||||
"write_roles": ["admin"],
|
||||
"use_category": true,
|
||||
"allow_comment": false
|
||||
}
|
||||
|
||||
// free (자유게시판)
|
||||
{
|
||||
"write_roles": ["*"],
|
||||
"allow_comment": true,
|
||||
"allow_secret": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. API 설계
|
||||
|
||||
### 4.1 mng API (시스템 게시판 관리)
|
||||
|
||||
```
|
||||
# 시스템 게시판 CRUD
|
||||
GET /mng/boards # 시스템 게시판 목록
|
||||
POST /mng/boards # 시스템 게시판 생성
|
||||
GET /mng/boards/{id} # 시스템 게시판 상세
|
||||
PUT /mng/boards/{id} # 시스템 게시판 수정
|
||||
DELETE /mng/boards/{id} # 시스템 게시판 삭제
|
||||
|
||||
# 게시판 필드 관리
|
||||
GET /mng/boards/{id}/fields # 필드 목록
|
||||
POST /mng/boards/{id}/fields # 필드 추가
|
||||
PUT /mng/boards/{id}/fields/{fid} # 필드 수정
|
||||
DELETE /mng/boards/{id}/fields/{fid} # 필드 삭제
|
||||
POST /mng/boards/{id}/fields/reorder # 필드 순서 변경
|
||||
```
|
||||
|
||||
### 4.2 sam API (테넌트용)
|
||||
|
||||
```
|
||||
# 게시판 조회 (시스템 + 테넌트)
|
||||
GET /v1/boards # 접근 가능한 게시판 목록
|
||||
GET /v1/boards/{code} # 게시판 상세
|
||||
|
||||
# 테넌트 게시판 관리
|
||||
POST /v1/boards # 테넌트 게시판 생성
|
||||
PUT /v1/boards/{code} # 테넌트 게시판 수정
|
||||
DELETE /v1/boards/{code} # 테넌트 게시판 삭제
|
||||
|
||||
# 게시글 CRUD
|
||||
GET /v1/boards/{code}/posts # 게시글 목록
|
||||
POST /v1/boards/{code}/posts # 게시글 작성
|
||||
GET /v1/boards/{code}/posts/{id} # 게시글 상세
|
||||
PUT /v1/boards/{code}/posts/{id} # 게시글 수정
|
||||
DELETE /v1/boards/{code}/posts/{id} # 게시글 삭제
|
||||
|
||||
# 댓글
|
||||
GET /v1/posts/{id}/comments # 댓글 목록
|
||||
POST /v1/posts/{id}/comments # 댓글 작성
|
||||
PUT /v1/comments/{id} # 댓글 수정
|
||||
DELETE /v1/comments/{id} # 댓글 삭제
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 모델 설계
|
||||
|
||||
### 5.1 Board 모델
|
||||
|
||||
```php
|
||||
// api/app/Models/Boards/Board.php
|
||||
|
||||
namespace App\Models\Boards;
|
||||
|
||||
use App\Traits\BelongsToTenant;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
use Illuminate\Database\Eloquent\SoftDeletes;
|
||||
|
||||
class Board extends Model
|
||||
{
|
||||
use SoftDeletes;
|
||||
|
||||
protected $fillable = [
|
||||
'tenant_id', 'is_system', 'board_type', 'board_code', 'name',
|
||||
'description', 'editor_type', 'allow_files', 'max_file_count',
|
||||
'max_file_size', 'extra_settings', 'is_active',
|
||||
'created_by', 'updated_by', 'deleted_by',
|
||||
];
|
||||
|
||||
protected $casts = [
|
||||
'is_system' => 'boolean',
|
||||
'is_active' => 'boolean',
|
||||
'allow_files' => 'boolean',
|
||||
'extra_settings' => 'array',
|
||||
];
|
||||
|
||||
/**
|
||||
* 현재 테넌트에서 접근 가능한 게시판
|
||||
* - 시스템 게시판 (is_system = true)
|
||||
* - 해당 테넌트 게시판 (tenant_id = 현재 테넌트)
|
||||
*/
|
||||
public function scopeAccessible($query, int $tenantId)
|
||||
{
|
||||
return $query->where(function ($q) use ($tenantId) {
|
||||
$q->where('is_system', true)
|
||||
->orWhere('tenant_id', $tenantId);
|
||||
})->where('is_active', true);
|
||||
}
|
||||
|
||||
/**
|
||||
* 시스템 게시판만 (mng용)
|
||||
*/
|
||||
public function scopeSystemOnly($query)
|
||||
{
|
||||
return $query->where('is_system', true);
|
||||
}
|
||||
|
||||
/**
|
||||
* 테넌트 게시판만
|
||||
*/
|
||||
public function scopeTenantOnly($query, int $tenantId)
|
||||
{
|
||||
return $query->where('is_system', false)
|
||||
->where('tenant_id', $tenantId);
|
||||
}
|
||||
|
||||
// 관계
|
||||
public function fields()
|
||||
{
|
||||
return $this->hasMany(BoardSetting::class, 'board_id')
|
||||
->orderBy('sort_order');
|
||||
}
|
||||
|
||||
public function posts()
|
||||
{
|
||||
return $this->hasMany(Post::class, 'board_id');
|
||||
}
|
||||
|
||||
// Helper
|
||||
public function getSetting(string $key, $default = null)
|
||||
{
|
||||
return data_get($this->extra_settings, $key, $default);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 BoardService
|
||||
|
||||
```php
|
||||
// api/app/Services/Boards/BoardService.php
|
||||
|
||||
namespace App\Services\Boards;
|
||||
|
||||
use App\Models\Boards\Board;
|
||||
use App\Services\Service;
|
||||
|
||||
class BoardService extends Service
|
||||
{
|
||||
/**
|
||||
* 접근 가능한 게시판 목록 (시스템 + 테넌트)
|
||||
*/
|
||||
public function getAccessibleBoards(array $filters = [])
|
||||
{
|
||||
return Board::accessible($this->tenantId())
|
||||
->when(isset($filters['board_type']), fn($q) =>
|
||||
$q->where('board_type', $filters['board_type']))
|
||||
->orderBy('is_system', 'desc')
|
||||
->orderBy('name')
|
||||
->get();
|
||||
}
|
||||
|
||||
/**
|
||||
* 시스템 게시판 목록 (mng용)
|
||||
*/
|
||||
public function getSystemBoards()
|
||||
{
|
||||
return Board::systemOnly()
|
||||
->orderBy('name')
|
||||
->get();
|
||||
}
|
||||
|
||||
/**
|
||||
* 시스템 게시판 생성 (mng용)
|
||||
*/
|
||||
public function createSystemBoard(array $data): Board
|
||||
{
|
||||
$data['is_system'] = true;
|
||||
$data['tenant_id'] = null;
|
||||
$data['created_by'] = $this->apiUserId();
|
||||
|
||||
return Board::create($data);
|
||||
}
|
||||
|
||||
/**
|
||||
* 테넌트 게시판 생성 (sam용)
|
||||
*/
|
||||
public function createTenantBoard(array $data): Board
|
||||
{
|
||||
$data['is_system'] = false;
|
||||
$data['tenant_id'] = $this->tenantId();
|
||||
$data['created_by'] = $this->apiUserId();
|
||||
|
||||
return Board::create($data);
|
||||
}
|
||||
|
||||
/**
|
||||
* 게시판 코드로 조회
|
||||
*/
|
||||
public function getBoardByCode(string $code): ?Board
|
||||
{
|
||||
return Board::accessible($this->tenantId())
|
||||
->where('board_code', $code)
|
||||
->first();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 권한 모델
|
||||
|
||||
### 6.1 extra_settings 기반 권한
|
||||
|
||||
게시판별 권한은 `extra_settings` JSON 필드로 관리:
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"read": ["*"], // 모든 역할 읽기 가능
|
||||
"write": ["admin", "user"], // admin, user 역할만 작성
|
||||
"manage": ["admin"] // admin만 관리
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 권한 검증
|
||||
|
||||
```php
|
||||
// Board 모델에 추가
|
||||
public function canRead(User $user): bool
|
||||
{
|
||||
$roles = $this->getSetting('permissions.read', ['*']);
|
||||
return in_array('*', $roles) ||
|
||||
$user->hasAnyRole($roles);
|
||||
}
|
||||
|
||||
public function canWrite(User $user): bool
|
||||
{
|
||||
$roles = $this->getSetting('permissions.write', ['*']);
|
||||
return in_array('*', $roles) ||
|
||||
$user->hasAnyRole($roles);
|
||||
}
|
||||
|
||||
public function canManage(User $user): bool
|
||||
{
|
||||
$roles = $this->getSetting('permissions.manage', ['admin']);
|
||||
return $user->hasAnyRole($roles);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 구현 계획
|
||||
|
||||
### 7.1 Phase 1: DB 마이그레이션 (api/)
|
||||
|
||||
1. `boards` 테이블 확장
|
||||
- `tenant_id` nullable 변경
|
||||
- `is_system` 컬럼 추가
|
||||
- `board_type` 컬럼 추가
|
||||
- `deleted_at`, `deleted_by` 추가 (없으면)
|
||||
- 인덱스 추가
|
||||
|
||||
### 7.2 Phase 2: 모델/서비스 수정 (api/)
|
||||
|
||||
1. `Board` 모델 업데이트
|
||||
- 스코프 추가 (accessible, systemOnly, tenantOnly)
|
||||
- SoftDeletes 적용
|
||||
- 권한 헬퍼 메서드
|
||||
|
||||
2. `BoardService` 구현
|
||||
- 시스템/테넌트 게시판 분리 로직
|
||||
|
||||
### 7.3 Phase 3: mng 화면 개발
|
||||
|
||||
1. 게시판 목록 (`/mng/boards`)
|
||||
2. 게시판 생성/수정 폼
|
||||
3. 게시판 필드 관리
|
||||
|
||||
### 7.4 Phase 4: sam API 개발
|
||||
|
||||
1. 게시판 API (`/v1/boards`)
|
||||
2. 게시글 API (`/v1/boards/{code}/posts`)
|
||||
3. Swagger 문서
|
||||
|
||||
---
|
||||
|
||||
## 8. 관련 문서
|
||||
|
||||
- [데이터베이스 스키마](./database/README.md)
|
||||
- [API 개발 규칙](../standards/api-rules.md)
|
||||
- [MNG Critical Rules](../../mng/docs/MNG_CRITICAL_RULES.md)
|
||||
|
||||
---
|
||||
|
||||
**최종 업데이트**: 2025-11-27
|
||||
**버전**: 1.0
|
||||
**상태**: 설계 완료
|
||||
Reference in New Issue
Block a user