chore: 프로젝트 가이드 파일 추가

- CLAUDE.md 파일 추가하여 프로젝트 아키텍처 및 개발 규칙 문서화 - 멀티 저장소 관리를 위한 일관된 가이드 제공 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-19 19:25:54 +09:00
parent 785e367472
commit 8d7426de7a
1 changed files with 340 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,340 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Architecture
+
+This is a multi-application Laravel-based SAM (Smart Application Management) system consisting of:
+
+### Core Applications
+- **admin/** - Laravel 12 application with Filament admin panel for tenant management
+- **api/** - Laravel 12 REST API backend with comprehensive API endpoints and Swagger documentation
+- **front/** - CodeIgniter 3 frontend application
+  - `front/www/` - Main CodeIgniter application directory
+  - `front/_Codeigniter/` - CodeIgniter 3 system files (extracted from www)
+- **5130/** - Legacy PHP application for construction/manufacturing management
+- **shared/** - Common models and services package shared between applications
+- **docker/** - Docker configuration files
+
+### Key Features & Components
+- Multi-tenant architecture with tenant switching capabilities
+- Role-based access control (RBAC) with permissions and departments
+- Product management with BOM (Bill of Materials) support
+- Material management and inventory tracking
+- File upload and management system
+- Category management with templates and versioning
+- Design workflow with version control and audit logging
+
+### Shared Models Structure
+The `shared/` directory contains common Eloquent models organized by domain:
+- **Members/** - User and tenant management
+- **Products/** - Product catalog and BOM structures
+- **Materials/** - Material specifications and inventory
+- **Orders/** - Order processing workflows
+- **Tenants/** - Multi-tenant configurations
+- **Commons/** - Shared utilities and common data
+
+## Development Commands
+
+### Admin Application (admin/)
+```bash
+# Development server with all services
+composer dev
+
+# Individual services
+php artisan serve          # Laravel server
+php artisan queue:listen --tries=1  # Queue worker
+php artisan pail --timeout=0        # Log viewer
+npm run dev                          # Vite dev server
+
+# Testing
+composer test
+php artisan test
+
+# Code quality
+./vendor/bin/pint          # PHP CS Fixer
+```
+
+### API Application (api/)
+```bash
+# Development server with all services  
+composer dev
+
+# API documentation
+# Access Swagger UI at: /api-docs/index.html (root redirects here)
+# JSON spec at: /docs/api-docs.json
+
+# Database
+php artisan migrate
+php artisan migrate:generate    # Generate migrations from existing DB
+
+# Development tools
+php artisan ide-helper:generate
+php artisan ide-helper:models
+```
+
+### Frontend Application (front/www/)
+```bash
+# CodeIgniter 3 application
+composer install         # Install PHP dependencies
+php -S localhost:8080    # Built-in development server
+
+# Note: front/_Codeigniter/ contains the extracted CI3 system files
+# Main application is in front/www/ directory
+```
+
+### Build and Assets
+```bash
+# Frontend assets (both admin and api)
+npm run build    # Production build
+npm run dev      # Development with hot reload
+
+# In individual directories
+cd admin && npm run build
+cd api && npm run build
+```
+
+## API Structure & Authentication
+
+### Authentication Flow
+1. **API Key Authentication** - All endpoints require valid API key via `auth.apikey` middleware
+2. **User Authentication** - POST `/v1/login` returns Sanctum token
+3. **Protected Routes** - Use `auth:sanctum` middleware for user-specific operations
+
+### Core API Endpoints (v1/)
+- **Auth**: `/v1/login`, `/v1/logout`, `/v1/signup`
+- **Users**: `/v1/users/*` - User management and profile operations  
+- **Tenants**: `/v1/tenants/*` - Multi-tenant operations and switching
+- **Admin**: `/v1/admin/*` - Tenant user administration
+- **Products**: `/v1/products/*` - Product catalog with BOM support
+- **Materials**: `/v1/materials/*` - Material management
+- **Categories**: `/v1/categories/*` - Hierarchical category management
+- **Files**: `/v1/file/*` - File upload and management
+- **Design**: `/v1/design/*` - Design workflow and versioning
+
+### Permission System
+- Menu-based permissions with role inheritance
+- Department-based access control
+- Multi-level permission matrix (user → role → department → menu)
+
+## Database & Models
+
+### Multi-tenant Data Architecture
+- Tenant isolation via `tenant_id` columns with BelongsToTenant global scope
+- Shared models in `shared/Models/` with tenant scoping
+- Global admin tables for system management
+- Soft deletes (`deleted_at`) applied across most entities
+- Common audit columns: `created_by`, `updated_by`, `deleted_by`
+
+### Core Tables & Relationships
+
+#### Authentication & Authorization
+- **`api_keys`** - API key management with active status
+- **`users`** - User accounts with soft deletes
+- **`user_tenants`** - Many-to-many user-tenant relationships with active/default flags
+- **`personal_access_tokens`** - Sanctum token storage
+- **`permissions`** - Role-based permissions with tenant scoping
+- **`roles`** - Tenant-scoped roles
+- **`model_has_permissions/roles`** - Spatie permission assignments
+- **`permission_overrides`** - Manual permission allow/deny with temporal validity
+
+#### Multi-tenant Organization
+- **`tenants`** - Company/organization master with subscription info
+- **`tenant_user_profiles`** - Extended user profiles per tenant
+- **`departments`** - Hierarchical organizational structure
+- **`department_user`** - User-department assignments with primary department flag
+
+#### Product Management
+- **`categories`** - Hierarchical product categorization with soft deletes
+- **`category_fields`** - Dynamic field definitions per category
+- **`category_templates`** - Versioned category field snapshots
+- **`products`** - Product catalog with type classification (PRODUCT/PART/SUBASSEMBLY)
+- **`product_components`** - BOM relationships (MATERIAL|PRODUCT references)
+- **`materials`** - Material master with dynamic attributes
+- **`classifications`** - Flat code tables by group (product_type, payment_method, etc.)
+
+#### Design & Manufacturing
+- **`models`** - Design model master with lifecycle status
+- **`model_versions`** - Versioned model releases with DRAFT/RELEASED status
+- **`bom_templates`** - BOM templates linked to model versions
+- **`bom_template_items`** - Template BOM line items with quantities and waste rates
+
+#### Orders & Operations
+- **`orders`** - Order/quotation master with workflow status
+- **`order_items`** - Order line items with design codes
+- **`order_item_components`** - Required materials/products per order item
+- **`order_histories`** - Order change tracking and notes
+- **`clients`** - Customer/vendor master
+
+#### Inventory & Materials
+- **`material_receipts`** - Incoming material receipts with lot tracking
+- **`material_inspections`** - Quality inspection records
+- **`material_inspection_items`** - Inspection checklist items
+- **`lots`** - Material lot management
+- **`lot_sales`** - Lot consumption tracking
+- **`price_histories`** - Historical pricing with temporal validity
+
+#### System & Configuration
+- **`common_codes`** - Hierarchical master codes with tenant support
+- **`files`** - Polymorphic file attachments
+- **`audit_logs`** - Comprehensive audit trail with 13-month retention
+- **`setting_field_defs`** - Global field definitions
+- **`tenant_field_settings`** - Tenant-specific field configurations
+- **`tenant_option_groups/values`** - Tenant-managed dropdown options
+
+#### Content Management
+- **`boards`** - Configurable board system
+- **`posts`** - Board posts with custom fields
+- **`board_settings`** - Dynamic field definitions per board
+- **`board_comments`** - Hierarchical commenting system
+
+### Key Model Relationships
+- **Tenant → Users** (many-to-many via user_tenants)
+- **Products ↔ Materials** (via product_components with ref_type)
+- **Models → Versions → BOM Templates** (design workflow)
+- **Orders → Items → Components** (order breakdown)
+- **Categories ↔ Fields ↔ Templates** (dynamic forms with versioning)
+- **Audit Logs** (polymorphic tracking across all major entities)
+
+## Legacy Integration (5130/)
+
+The `5130/` directory contains a large legacy PHP application for:
+- Construction/manufacturing workflow management
+- Equipment and material tracking  
+- Work order processing
+- Financial calculations and reporting
+
+Key legacy components:
+- **dbeditor/** - Database administration tools
+- **estimate/** - Cost estimation system
+- **output/** - Report generation
+- Various specialized modules for construction processes
+
+## File Organization
+
+### Configuration
+- Environment files: `.env` in each application directory
+- Docker configs: `docker/` directory
+- Asset building: `vite.config.js` and `tailwind.config.js` in each app
+
+### Testing
+- PHPUnit configuration: `phpunit.xml` in each Laravel app
+- Test directories: `tests/` in Laravel applications
+
+## Development Workflow
+
+1. **Environment Setup**: Configure `.env` files for each application
+2. **Database**: Run migrations in both admin and api applications  
+3. **Dependencies**: `composer install` and `npm install` in relevant directories
+4. **Development**: Use `composer dev` to run all services concurrently
+5. **API Testing**: Access Swagger documentation for API endpoints
+6. **Code Quality**: Run Pint for PHP formatting
+
+## SAM API Development Rules
+
+### 1. Architecture Philosophy
+- **Service First**: All business logic must be written in Service classes (public functions)
+- **Controller**: Only responsible for DI injection of Services and calling them. Use ApiResponse::handle() for responses
+- **Exception Flow**: Errors are thrown → converted to JSON by global handler
+- **Context Enforcement**: Base Service requires tenantId(), apiUserId(). Throws exception if not set
+
+### 2. Multi-tenancy & Models
+- BelongsToTenant global scope applied
+- ModelTrait for is_active, date handling
+- SoftDeletes by default
+- Common columns: tenant_id, created_by, updated_by, deleted_by (COMMENT required)
+- FK constraints: Created during design, minimal in production
+
+### 3. Middleware Stack
+- ApiKeyMiddleware, CheckSwaggerAuth, CorsMiddleware, CheckPermission, PermMapper
+- Default route group: auth.apikey (some with auth:sanctum)
+
+### 4. Routing (v1)
+- Auth, Common codes, Files, Tenants, Users (me/tenants/switch), Menus+Permissions, Roles/Permissions, Departments, Field settings, Options, Categories, Classifications, Products, BOM
+- REST conventions: index/show/store/update/destroy + extensions (toggle, bulkUpsert, reorder)
+
+### 5. Controller/Service Rules
+- **Controller**: FormRequest type-hint → only pass $request->validated() to Service
+- **Service**: extends Service, tenantId()/apiUserId() required
+- **Lists**: Pagination, explicit search parameters
+- **Responses**: {success, message, data}, message must be i18n key only
+
+### 6. i18n & Response Messages
+- Messages: lang/{locale}/message.php
+- Errors: lang/{locale}/error.php
+- **Rule**: No direct strings, must use __('message.xxx'), __('error.xxx')
+- Common keys: message.fetched/created/updated/deleted/bulk_upsert/reordered
+- Resource-specific keys allowed: message.product.created, message.bom.bulk_upsert
+
+### 7. Swagger Documentation (l5-swagger 9.0)
+- **Tags**: Resource-based (User, Auth, Product, BOM...)
+- **Security**: ApiKeyAuth + BearerAuth
+- **Schemas**: Reuse ApiResponse, ErrorResponse, resource DTOs
+- **Specifications**: Clear Path/Query/Body parameters with examples
+- **No duplicate schemas**, accurate nullable/oneOf distinctions
+
+### 8. Validation (FormRequest)
+- **No direct validate() calls**. Separate all into FormRequest classes
+- **Reuse common Requests**: PaginateRequest, BomItemsRequest, DateRangeRequest
+- **Boundary validation** (effective_from ≤ effective_to) in Request
+
+### 9. Audit Logging
+- **Table**: audit_logs (tenant_id, target_type, target_id, action, before/after(json), actor_id, ip, ua, created_at)
+- **Actions**: created, updated, deleted, released, cloned, items_replaced, diff_viewed
+- **Retention**: 13 months default, audit:prune scheduler cleanup
+- **Failure tolerance**: Log failures don't block business operations
+
+### 10. Domain Rules
+- **Status**: Strings (DRAFT/RELEASED/ARCHIVED)
+- **Unique/Indexes**: models(code), model_versions(version_no), bom_items(parent, order)
+- **BOM**: Supports summary/validate/bulkUpsert/reorder
+
+### 11. Commit Messages
+- **Format**: [type]: title + detailed bullets
+- **Types**: feat | fix | chore | refactor | style
+- **Example**: `feat: 감사 로그 도입 및 스케줄러 추가`
+
+## Design/Estimation/Ordering Domain
+
+### Parameter-based BOM Resolution
+- **Input Parameters**: W0/H0, installation type, power source, etc.
+- **Output Preview**: W1/H1, area, weight, motor, bracket, guide, case, bottom, shaft, pipe (auto-calculated)
+- **Rules**: Product family-specific formulas (Screen/Steel), boundary values apply higher capacity
+- **Proposed APIs**:
+  - `GET /design/models/{id}/parameters` → Returns input schema
+  - `POST /design/models/{id}/bom/resolve` → BOM/item calculation preview based on input values
+
+## Git Repository Structure & Workflow
+
+### Multiple Repository Setup
+This project uses **5 separate Git repositories** for different components:
+- **api/** - API project repository
+- **admin/** - Laravel admin panel repository
+- **front/www/** - CodeIgniter frontend repository
+- **front/_Codeigniter/** - Extracted CI3 system files repository
+- **shared/** - Shared models and services (planned for future use when API is mature)
+
+### Work Tracking & Commit Workflow
+1. **Work Tracking**: All ongoing work is documented in `CURRENT_WORKS.md` at the root level
+2. **Progress Updates**: As features are developed, update `CURRENT_WORKS.md` with changes per repository
+3. **Commit Process**: When a feature is complete:
+   - Organize completed work by repository (api, admin, front/www, front/_Codeigniter, shared)
+   - Update `CURRENT_WORKS.md` with summary of modified/added/deleted files
+   - Create Git commits in each affected repository
+   - If `CURRENT_WORKS.md` doesn't exist, create it and add to Git
+
+### Repository-Specific Operations
+Each repository operates independently with its own:
+- Git history and branches
+- Environment configuration (`.env` files)
+- Dependencies and build processes
+- Deployment workflows
+
+## Important Notes
+
+- The system uses Laravel 12 with PHP 8.2+
+- Filament v3 is used for admin panel interface
+- TailwindCSS for styling with Vite for asset building
+- Sanctum for API authentication
+- Multi-tenant architecture requires proper tenant context in all operations
+- **Follow SAM API Development Rules strictly when working on API-related tasks**