Economics

Integration with project/issue tracker to ease management. The worklogs and projects are synced from a project tracker (e.g. Jira).

The project consists of the following parts:

• Invoices: Create invoices for projects and clients. These can consist of manual invoice entries and invoice entries created from worklogs.
• Project Billing: Automatically create invoices from a project for a given period.
• Planning: Overview of planned work for the coming sprints.
• Sprint Report: Detailed overview of the work for a given project/version.
• Projects: Overview of which projects to work with in the system.
• Project Creator: Create a new project in the Project Tracker.

Entity model

graph TD;
   ProjectBilling-->Invoice;
   ProjectBilling-->Project;
   Invoice-->Project;
   Invoice-->Client;
   Invoice-->InvoiceEntry;
   InvoiceEntry-->Worklog;
   Issue-->Worklog;
   Issue-->Project;
   Issue-->Account;
   Client-->Account;

Loading

The system is build around Invoices. Each invoice is connected to a project and consists of invoice entries. The output is a .csv file.

Projects, clients, accounts, issues and worklogs are synchronized from a project tracker.

Invoice entries can be manual entries or connected to a number of worklogs from a project tracker.

Project billing can create a number of invoices for a given project for a given project. Only issues from the project tracker that have a connected account will be included. This is used to create invoices for the Support project, where issues are billed to different accounts.

Synchronization

Economics depends on data fra external systems. The integrations with external systems are called Data Providers.

Each Data Provider integration should implement App\Interface\DataProviderServiceInterface.

The data synchronization is handled by symfony messenger. This is handled differently in development and production.

Production

Supervisor is added to docker-compose.server.override.yaml to make sure the job queue is running.

Symfony scheduler is used for creating a new job each hour at minute 5. See App\Command\QueueSyncCommand.

Develop

In development the job queue should be run manually.

docker compose exec phpfpm bin/console messenger:consume async -vv --failure-limit 1

Queuing jobs

Jobs can be queued manually with App\Command\QueueSyncCommand

docker compose exec phpfpm bin/console app:queue-sync

Jobs can also be queued in the admin interface in the bottom left corner.

In production jobs are queued automatically each hour.

Development

Getting started — Taskfile.yml wraps the container commands, so install go-task (brew install go-task) and run:

task setup

That creates the frontend network, pulls the images, installs the npm and Composer dependencies, starts the stack and runs the migrations. Run task to list every available task.

Create .env.local with the following values set:

###> itk-dev/openid-connect-bundle ###
USER_OIDC_METADATA_URL=<VALUE>
USER_OIDC_CLIENT_ID=<VALUE>
USER_OIDC_CLIENT_SECRET=<VALUE>
USER_OIDC_REDIRECT_URI=https://economics.local.itkdev.dk/openid-connect/generic
USER_OIDC_ALLOW_HTTP=<VALUE>
USER_OIDC_LEEWAY=<VALUE>
###< itk-dev/openid-connect-bundle ###

APP_INVOICE_SUPPLIER_ACCOUNT=<VALUE>
APP_INVOICE_EXTERNAL_RECEIVER_ACCOUNT=<VALUE>
APP_INVOICE_DESCRIPTION_TEMPLATE=<VALUE>

The project tracker connection is not configured through the environment. Each integration is a DataProvider row holding its own URL and token, created with:

task phpfpm -- bin/console app:data-provider:create

Visit /admin/project and "include" the projects that should be synchronized in the installation.

Then synchronize:

task phpfpm -- bin/console app:data-providers:sync

Run app:data-providers:sync --help for the per-entity flags (-p projects, -r workers, -s versions, -i issues, -w worklogs).

Assets

The node container will watch for code changes in the assets folder and recompile.

Use

task compose -- logs --tail 0 --follow node

to see the compilation log, e.g. to detect errors.

Coding standards

Each PR is reviewed with Github Actions.

Check coding standards with:

# Check coding standards for php and twig
task coding-standards:php:check

# Check coding standards for assets and markdown
task coding-standards:js:check

Apply coding standards with:

# Apply coding standards for php and twig
task coding-standards:php:apply

# Apply coding standards for assets and markdown
task coding-standards:js:apply

task prepare-code runs the whole set — Composer normalization, coding standards, static analysis and the tests — and is the check to run before pushing.

Code analysis

We use PHPStan for static code analysis, at level 8 over src and tests:

task code-analysis

Pre-existing errors are recorded in phpstan-baseline.neon. New code is expected to be clean rather than added to the baseline.

Testing

The test setup follows the guidelines from: https://symfony.com/doc/current/testing.html.

To run tests:

task test

# a single file
task test:file -- tests/Unit/Service/LeantimeApiServiceTest.php

# fail if line coverage drops below the threshold, as CI does
task test:coverage:check

tests/bootstrap.php rebuilds the test database on every run — it clears the cache, then drops, creates and migrates the database and loads App\DataFixtures\AppFixtures. Tests are not wrapped in transactions, so a test that writes is responsible for cleaning up after itself.

Production

Deploy

Build the assets locally

task assets:build

Copy the /public/build folder to the server.

docker compose up --detach
docker compose exec phpfpm composer install --no-dev --classmap-authoritative
docker compose exec phpfpm bin/console doctrine:migrations:migrate

Sync

Run synchronization with a cron process with a given interval to synchronize with the project tracker:

  bin/console app:data-providers:sync

Importing products

We need an initial product import to get going. Use

task phpfpm -- bin/console app:products:import «CSV filename»

to import from a CSV file.

The CSV must contain the following headers:

id,name,price,project.id,project.name