# Deployment & Technical Setup

This document provides instructions for developers and devops engineers to set up and deploy the FUJ Management system.

## 🛠 Prerequisites

-   **Python 3.12+**: The project uses modern type hinting and syntax features.
-   **uv**: High-performance Python package installer and resolver.
    -   Install via brew: `brew install uv`
-   **Docker** (Optional): For containerized deployments.

## ⚙️ Initial Setup

1.  **Clone the repository**:
    ```bash
    git clone <repo-url>
    cd fuj-management
    ```

2.  **Install dependencies**:
    Using `uv`, everything is handled automatically:
    ```bash
    make venv
    ```

3.  **Secrets Management**:
    Create a `.secret/` directory. You will need two main credentials:
    -   `fuj-management-bot-credentials.json`: A Google Cloud Service Account key with access to the Sheets API.
    -   `fio-token.txt`: (Implicitly used by `fio_utils.py`) Your Fio bank API token.

    Ensure these are never committed! They are ignored by `.gitignore`.

## 🐳 Containerization

The project can be built and run as an OCI image.

1.  **Build the image**:
    ```bash
    make image
    ```
    This uses the `build/Dockerfile`, which is optimized for small size and security.

2.  **Run the container**:
    ```bash
    make run
    ```
    The app exposes port `5001`.

## 🧪 Testing & Validation

The project includes a suite of infrastructure and logic tests.

-   **Run all tests**:
    ```bash
    make test
    ```
-   **Verbose output**:
    ```bash
    make test-v
    ```

Tests are located in the `tests/` directory and use the standard Python `unittest` framework. They cover:
-   CSV parsing logic.
-   Fee calculation rules.
-   Name matching and normalization.

## 🚀 Future Roadmap

-   **Automated Backups**: Regular snapshots of the Google Sheet.
-   **Authentication Layer**: Login for the web dashboard (currently assumes internal VPN or trusted environment).
-   **Gitea Actions**: Continuous Integration for building and testing images.
```