feat: port basic functionality to elixir

2025-09-14 12:19:44 +02:00
parent 0a6b7e08e2
commit 5e49cb79a0
14 changed files with 1405 additions and 14 deletions
--- a/README.md
+++ b/README.md
@@ -1,18 +1,182 @@
-# ComponentsElixir
+# Components Inventory - Elixir/Phoenix Implementation

-To start your Phoenix server:
+A modern, idiomatic Elixir/Phoenix port of the original PHP-based component inventory management system.

-* Run `mix setup` to install and setup dependencies
-* Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
+## Features

-Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
+### ✨ Improvements over the original PHP version:

-Ready to run in production? Please [check our deployment guides](https://hexdocs.pm/phoenix/deployment.html).
+1. **Modern Architecture**
+   - Phoenix LiveView for real-time, reactive UI without JavaScript
+   - Ecto for type-safe database operations
+   - Proper separation of concerns with Phoenix contexts
+   - Built-in validation and error handling

-## Learn more
+2. **Enhanced User Experience**
+   - Real-time search with no page refreshes
+   - Responsive design with Tailwind CSS
+   - Loading states and better feedback
+   - Improved mobile experience

-* Official website: https://www.phoenixframework.org/
-* Guides: https://hexdocs.pm/phoenix/overview.html
-* Docs: https://hexdocs.pm/phoenix
-* Forum: https://elixirforum.com/c/phoenix-forum
-* Source: https://github.com/phoenixframework/phoenix
+3. **Better Data Management**
+   - Full-text search with PostgreSQL
+   - Hierarchical categories with parent-child relationships
+   - Proper foreign key constraints
+   - Database migrations for schema management
+
+4. **Security & Reliability**
+   - CSRF protection built-in
+   - SQL injection prevention through Ecto
+   - Session-based authentication
+   - Input validation and sanitization
+
+### 🔧 Core Functionality
+
+- **Component Management**: Add, edit, delete, and track electronic components
+- **Inventory Tracking**: Monitor component quantities with increment/decrement buttons
+- **Search & Filter**: Fast search across component names, descriptions, and keywords
+- **Category Organization**: Hierarchical category system for better organization
+- **Datasheet Links**: Direct links to component datasheets
+- **Position Tracking**: Track component storage locations
+
+## Setup
+
+1. **Install dependencies:**
+   ```bash
+   mix deps.get
+   ```
+
+2. **Set up the database:**
+   ```bash
+   mix ecto.create
+   mix ecto.migrate
+   mix run priv/repo/seeds.exs
+   ```
+
+3. **Start the server:**
+   ```bash
+   mix phx.server
+   ```
+
+4. **Visit the application:**
+   Open [http://localhost:4000](http://localhost:4000)
+
+## Authentication
+
+The application uses a simple password-based authentication system:
+- Default password: `changeme`
+- Set custom password via environment variable: `AUTH_PASSWORD=your_password`
+
+## Database Schema
+
+### Categories
+- `id`: Primary key
+- `name`: Category name (required)
+- `description`: Optional description
+- `parent_id`: Foreign key for hierarchical categories
+- Supports unlimited nesting levels
+
+### Components
+- `id`: Primary key
+- `name`: Component name (required)
+- `description`: Detailed description
+- `keywords`: Search keywords
+- `position`: Storage location/position
+- `count`: Current quantity (default: 0)
+- `datasheet_url`: Optional link to datasheet
+- `image_filename`: Optional image file name
+- `category_id`: Required foreign key to categories
+
+## Architecture
+
+### Contexts
+- **`ComponentsElixir.Inventory`**: Business logic for components and categories
+- **`ComponentsElixir.Auth`**: Simple authentication system
+
+### Live Views
+- **`ComponentsElixirWeb.LoginLive`**: Authentication interface
+- **`ComponentsElixirWeb.ComponentsLive`**: Main component management interface
+
+### Key Features
+- **Real-time updates**: Changes are immediately reflected without page refresh
+- **Infinite scroll**: Load more components as needed
+- **Search optimization**: Uses PostgreSQL full-text search for long queries, ILIKE for short ones
+- **Responsive design**: Works on desktop and mobile devices
+
+## API Comparison
+
+| Original PHP | New Elixir/Phoenix | Improvement |
+|-------------|-------------------|-------------|
+| `getItems.php` | `Inventory.list_components/1` | Type-safe, composable queries |
+| `getCategories.php` | `Inventory.list_categories/0` | Proper associations, hierarchical support |
+| `addItem.php` | `Inventory.create_component/1` | Built-in validation, changesets |
+| `changeAmount.php` | `Inventory.update_component_count/2` | Atomic operations, constraints |
+| `imageUpload.php` | (Future: Phoenix file uploads) | Planned improvement |
+| Session management | Phoenix sessions + LiveView | Built-in CSRF protection |
+
+## Future Enhancements
+
+1. **Image Upload**: Implement Phoenix file uploads for component images
+2. **Category Management UI**: Add/edit/delete categories through the web interface
+3. **Bulk Operations**: Import/export components via CSV
+4. **API Endpoints**: REST API for external integrations
+5. **User Management**: Multi-user support with roles and permissions
+6. **Advanced Search**: Filters by category, stock level, etc.
+7. **Barcode/QR Codes**: Generate and scan codes for quick inventory updates
+
+## Development
+
+### Running Tests
+```bash
+mix test
+```
+
+### Code Quality
+```bash
+mix format
+mix credo
+```
+
+### Database Management
+```bash
+# Reset database
+mix ecto.reset
+
+# Add new migration
+mix ecto.gen.migration add_feature
+
+# Check migration status
+mix ecto.migrations
+```
+
+## Deployment
+
+For production deployment:
+
+1. **Set environment variables:**
+   ```bash
+   export AUTH_PASSWORD=your_secure_password
+   export SECRET_KEY_BASE=your_secret_key
+   export DATABASE_URL=postgresql://user:pass@host/db
+   ```
+
+2. **Build release:**
+   ```bash
+   MIX_ENV=prod mix release
+   ```
+
+3. **Run migrations:**
+   ```bash
+   _build/prod/rel/components_elixir/bin/components_elixir eval "ComponentsElixir.Release.migrate"
+   ```
+
+## Contributing
+
+This is a modernized, idiomatic Elixir/Phoenix implementation that maintains feature parity with the original PHP version while providing significant improvements in code quality, security, and user experience.
+
+The application follows Phoenix and Elixir best practices:
+- Contexts for business logic
+- LiveView for interactive UI
+- Ecto for database operations
+- Comprehensive error handling
+- Input validation and sanitization