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:

docker compose pull
docker compose run --rm node npm install
docker compose up --detach
docker compose exec phpfpm composer install
docker compose exec phpfpm bin/console doctrine:migrations:migrate --no-interaction

Set create .env.local with the following values set

###> Project tracker connection ###
JIRA_PROJECT_TRACKER_URL=<VALUE>
JIRA_PROJECT_TRACKER_USER=<VALUE>
JIRA_PROJECT_TRACKER_TOKEN=<VALUE>
LEANTIME_PROJECT_TRACKER_URL=<VALUE>
LEANTIME_PROJECT_TRACKER_TOKEN=<VALUE>
###< Project tracker connection ###

###> 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_RECEIVER_ACCOUNT=<VALUE>
APP_INVOICE_DEFAULT_DESCRIPTION=<VALUE>

JIRA_API_SERVICE_CUSTOM_FIELD_EPIC_LINK=<VALUE>
JIRA_API_SERVICE_CUSTOM_FIELD_ACCOUNT=<VALUE>
JIRA_API_SERVICE_CUSTOM_FIELD_SPRINT=<VALUE>
JIRA_API_SERVICE_DEFAULT_BOARD=<VALUE>

Sync projects and accounts.

docker compose exec phpfpm bin/console app:sync-projects
docker compose exec phpfpm bin/console app:sync-accounts

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

Then sync issues and worklogs

docker compose exec phpfpm bin/console app:sync-issues
docker compose exec phpfpm bin/console app:sync-worklogs

Assets

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

Use

docker 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:

# Apply coding standards and run static analysis for php and twig
docker compose exec phpfpm composer coding-standards-check

# Check coding standards for assets and markdown
docker compose run --rm node npm run coding-standards-check

Apply some coding standards with:

# Apply coding standards and run static analysis for php and twig
docker compose exec phpfpm composer prepare-code

# Apply coding standards for assets and markdown
docker compose run --rm node npm run coding-standards-apply

Code analysis

We use Psalm for static code analysis:

docker compose exec phpfpm composer code-analysis

Testing

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

To run tests:

docker compose exec phpfpm composer tests

DoctrineFixtures are load each time phpunit is run. Between each test the initial state of the database is restored using DAMADoctrineTestBundle.

Production

Deploy

Build the assets locally

docker compose run --rm node npm run 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:sync

Importing products

We need an initial product import to get going. Use

docker compose exec phpfpm bin/console app:product:import «CSV filename»

to import from a CSV file.

The CSV must contain the following headers:

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