chore: 프로젝트 가이드 파일 추가
- CLAUDE.md 파일 추가하여 프로젝트 아키텍처 및 개발 규칙 문서화 - 멀티 저장소 관리를 위한 일관된 가이드 제공 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
340
CLAUDE.md
Normal file
340
CLAUDE.md
Normal file
@@ -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**
|
||||||
Reference in New Issue
Block a user