extend information about the online instances to the README.md

README.md

@@ -0,0 +1,158 @@
+# C3LF System3
+
+the third try to automate lost&found organization for chaos events. not a complete rewrite, but instead building on top
+of the web frontend of version 2. everything else is new but still API compatible. now with more monorepo.
+
+## Architecture
+
+C3LF System3 integrates a Django-Rest-Framework + WebSocket backend, Vue.js frontend SPA and a minimal LMTP mail server
+integrated with the Django backend. It is additionally deployed with a Postfix mail server as Proxy in front of the
+LMTP socket, a MariaDB database, a Redis cache and an Nginx reverse proxy that serves the static SPA frontend, proxies
+the API requests to the backend and serves the media files in cooperation with the Django backend using the
+`X-Accel-Redirect` header.
+
+The production deployment is automated using Ansible and there are some Docker Compose configurations for development.
+
+## Project Structure
+
+- `core/`  Contains the Django backend with database models, API endpoints, migrations, API tests, and mail server
+  functionalities.
+- `web/` Contains the Vue.js frontend application.
+- `deploy/` Contains deployment configurations and Docker scripts for various development modes.
+
+For more information, see the README.md files in the respective directories.
+
+## Development Modes
+
+There are currently 4 development modes for this Project:
+
+- Frontend-Only
+- Backend-API-Only
+- Full-Stack-Lite 'dev' (docker)
+- **[WIP]** Full-Stack 'testing' (docker)
+
+*Choose the one that is most suited to the feature you want to work on or ist easiest for you to set up ;)*
+
+For all modes it is assumed that you have `git` installed, have cloned the repository and are in the root directory of
+the project. Use `git clone https://git.hannover.ccc.de/c3lf/c3lf-system-3.git` to get the official upstream repository.
+The required packages for each mode are listed separately and also state the specific package name for Debian 12.
+
+### Frontend-Only
+
+This mode is for developing the frontend only. It uses the vue-cli-service (webpack) to serve the frontend and watches
+for changes in the source code to provide hot reloading. The API requests are proxied to the staging backend.
+
+#### Requirements
+
+* Node.js (~20.19.0) (`nodejs`)
+* npm (~9.2.0) (`npm`)
+
+*Note: The versions are not strict, but these are tested. Other versions might work as well.*
+
+#### Steps
+
+```bash
+cd web
+npm intall
+npm run serve
+```
+
+Now you can access the frontend at `localhost:8080` and start editing the code in the `web` directory.
+For more information, see the README.md file in the `web` directory.
+
+### Backend-API-Only
+
+This mode is for developing the backend API only. It also specifically excludes most WebSockets and mail server
+functionalities. Use this mode to focus on the backend API and Database models.
+
+#### Requirements
+
+* Python (~3.11) (`python3`)
+* pip (`python3-pip`)
+* virtualenv (`python3-venv`)
+
+*Note: The versions are not strict, but these are tested. Other versions might work as well.*
+
+#### Steps
+
+```
+python -m venv venv
+source venv/bin/activate
+pip install -r core/requirements.dev.txt
+cd core
+python manage.py test
+```
+
+The tests should run successfully to start and you can now start the TDD workflow by adding new failing tests.
+For more information about the backend and TDD, see the README.md file in the `core` directory.
+
+### Full-Stack-Lite 'dev' (docker)
+
+This mode is for developing the both frontend and backend backend at the same time in a containerized environment. It
+uses the `docker-compose` command to build and run the application in a container. It specifically excludes all mail
+server and most WebSocket functionalities.
+
+#### Requirements
+
+* Docker (`docker.io`)
+* Docker Compose (`docker-compose`)
+
+*Note: Depending on your system, the `docker compose` command might be included in general `docker` or `docker-ce`
+package, or you might want to use podman instead.*
+
+#### Steps
+
+```bash 
+docker-compose -f deploy/dev/docker-compose.yml up --build
+```
+
+The page should be available at [localhost:8080](http://localhost:8080)
+This Mode provides a minimal set of testdata, including a user `testuser` with password `testuser`. The test dataset is
+defined in deploy/testdata.py and can be extended there.
+
+You can now edit code in `/web` and `/core` and changes will be applied to the running page as soon as the file is
+saved.
+
+For details about each part, read `/web/README.md` and `/core/README.md` respectively. To execute commands in the
+container context use 'exec' like
+
+```bash
+docker exec -it c3lf-sys3-dev-core-1 ./manage.py test`
+```
+
+### Full-Stack 'testing' (docker)
+
+**WORK IN PROGRESS**
+
+*will include postfix, mariadb, redis, nginx and the ability to test sending mails, receiving mail and websocket based
+realiteme updates in the frontend. the last step in verification before deploying to the staging system using ansible*
+
+## Online Instances
+
+These are deployed using `deploy/ansible/playbooks/deploy-c3lf-sys3.yml` and follow a specific git branch.
+
+### 'live'
+
+| URL            | [c3lf.de](https://c3lf.de) |
+|----------------|----------------------------|
+| **Branch**     | live                       |
+| **Host**       | polaris.lab.or.it          |
+| **Debug Mode** | off                        |
+
+This is the **'production' system** and should strictly follow the staging system after all changes have been validated.
+
+### 'staging'
+
+| URL            | [staging.c3lf.de](https://staging.c3lf.de) |
+|----------------|--------------------------------------------|
+| **Branch**     | testing                                    |
+| **Host**       | andromeda.lab.or.it                        |
+| **Debug Mode** | on                                         |
+
+This system ist automatically updated by [git.hannover.ccc.de](https://git.hannover.ccc.de/c3lf/c3lf-system-3/) whenever
+a commit is pushed to the 'testing' branch and the backend tests passed.
+
+**WARNING: allthough this is the staging system, it is fully functional and contains a copy of the 'production' data, so
+do not for example reply to tickets for testing purposes as the system WILL SEND AN EMAIL to the person who originally
+created it. If you want to test something like that, first create you own test ticket by sending an email to
+`<event>@staging.c3lf.de`**

core/README.md

@@ -0,0 +1,68 @@
+# Core
+
+This directory contains the backend of the C3LF System3 project, which is built using Django and Django Rest Framework.
+
+## Modules
+
+- `authentication`: Handles user authentication and authorization.
+- `files`: Manages file uploads and related operations.
+- `inventory`: Handles inventory management, including events, containers and items.
+- `mail`: Manages email-related functionalities, including sending and receiving emails.
+- `notify_sessions`: Handles real-time notifications and WebSocket sessions.
+- `tickets`: Manages the ticketing system for issue tracking.
+
+## Modules Structure
+
+Most modules follow a similar structure, including the following components:
+
+- `<module>/models.py`: Contains the database models for the module.
+- `<module>/serializers.py`: Contains the serializers for the module models.
+- `<module>/api_<api_version>.py`: Contains the API views and endpoints for the module.
+- `<module>/migrations/`: Contains database migration files. Needs to contain an `__init__.py` file to be recognized as
+  a Python package and automatically migration creation to work.
+- `<module>/tests/<api_version>/test_<feature_model_or_testcase>.py`: Contains the test cases for the module.
+
+## Development Setup
+
+follow the instructions under 'Backend-API-Only' or 'Fullstack-Lite' in the root level `README.md` to set up a
+development environment.
+
+## Test-Driven Development (TDD) Workflow
+
+The project follows a TDD workflow to ensure code quality and reliability. Here is a step-by-step guide to the TDD
+process:
+
+1. **Write a Test**: Start by writing a test case for the new feature or bug fix. Place the test case in the appropriate
+   module within the `<module>/tests/<api_version>/test_<feature_model_or_testcase>.py` file.
+
+2. **Run the Test**: Execute the test to ensure it fails, confirming that the feature is not yet implemented or the bug
+   exists.
+    ```bash
+    python manage.py test
+    ```
+
+3. **Write the Code**: Implement the code required to pass the test. Write the code in the appropriate module within the
+   project.
+
+4. **Run the Test Again**: Execute the test again to ensure it passes.
+    ```bash
+    python manage.py test
+    ```
+
+5. **Refactor**: Refactor the code to improve its structure and readability while ensuring that all tests still pass.
+
+6. **Repeat**: Repeat the process for each new feature or bug fix.
+
+## Measuring Test Coverage
+
+The project uses the `coverage` package to measure test coverage. To generate a coverage report, run the following
+command:
+
+```bash
+coverage run --source='.' manage.py test
+coverage report
+```
+
+## Additional Information
+
+For more detailed information on the project structure and development modes, refer to the root level `README.md`.

core/tickets/migrations/0013_alter_statechange_state.py

@@ -0,0 +1,18 @@
+# Generated by Django 4.2.7 on 2025-03-15 21:31
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('tickets', '0012_remove_issuethread_related_items_and_more'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='statechange',
+            name='state',
+            field=models.CharField(choices=[('pending_new', 'New'), ('pending_open', 'Open'), ('pending_shipping', 'Needs to be shipped'), ('pending_physical_confirmation', 'Needs to be confirmed physically'), ('pending_return', 'Needs to be returned'), ('pending_postponed', 'Postponed'), ('pending_suspected_spam', 'Suspected Spam'), ('waiting_details', 'Waiting for details'), ('waiting_pre_shipping', 'Waiting for Address/Shipping Info'), ('closed_returned', 'Closed: Returned'), ('closed_shipped', 'Closed: Shipped'), ('closed_not_found', 'Closed: Not found'), ('closed_not_our_problem', 'Closed: Not our problem'), ('closed_duplicate', 'Closed: Duplicate'), ('closed_timeout', 'Closed: Timeout'), ('closed_spam', 'Closed: Spam'), ('closed_nothing_missing', 'Closed: Nothing missing'), ('closed_wtf', 'Closed: WTF'), ('found_open', 'Item Found and stored externally'), ('found_closed', 'Item Found and stored externally and closed')], default='pending_new', max_length=255),
+        ),
+    ]