159 lines
4.1 KiB
Markdown
159 lines
4.1 KiB
Markdown
# Mobicoop V3 - Territory Service
|
|
|
|
Territory data management.
|
|
|
|
## Requirements
|
|
|
|
You need [Docker](https://docs.docker.com/engine/) and its [compose](https://docs.docker.com/compose/) plugin.
|
|
|
|
You also need NodeJS installed locally : we **strongly** advise to install [Node Version Manager](https://github.com/nvm-sh/nvm) and use the latest LTS version of Node (check that your local version matches with the one used in the Dockerfile).
|
|
|
|
The API will run inside a docker container, **but** the install itself is made outside the container, because during development we need tools that need to be available locally (eg. ESLint, Prettier...).
|
|
|
|
A RabbitMQ instance is also required to send / receive messages when data has been inserted/updated/deleted.
|
|
|
|
## Installation
|
|
|
|
- copy `.env.dist` to `.env` :
|
|
|
|
```bash
|
|
cp .env.dist .env
|
|
```
|
|
|
|
Modify it if needed.
|
|
|
|
- install the dependencies :
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
- start the containers :
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
The app runs automatically on port **5004**.
|
|
|
|
## Database migration
|
|
|
|
Before using the app, you need to launch the database migration (it will be launched inside the container) :
|
|
|
|
```bash
|
|
npm run migrate
|
|
```
|
|
|
|
## Usage
|
|
|
|
The app exposes the following [gRPC](https://grpc.io/) services :
|
|
|
|
- **FindForPoint** : find all territories that include a given point (represented by its longitude and latitude)
|
|
|
|
```json
|
|
{
|
|
"lon": 5.493345,
|
|
"lat": 46.143376
|
|
}
|
|
```
|
|
- **FindForPoints** : find all territories that include a list of given points (represented by their longitude and latitude)
|
|
|
|
```json
|
|
{
|
|
"points": [
|
|
{
|
|
"lon": 5.493345,
|
|
"lat": 46.143376
|
|
},
|
|
{
|
|
"lon": 6.493345,
|
|
"lat": 47.143376
|
|
}
|
|
]
|
|
|
|
}
|
|
```
|
|
|
|
- **FindByUuid** : find a territory by its uuid
|
|
|
|
```json
|
|
{
|
|
"uuid": "80126a61-d128-4f96-afdb-92e33c75a3e1"
|
|
}
|
|
```
|
|
|
|
- **FindAll** : find all territories; you can use pagination with `page` (default:_1_) and `perPage` (default:_10_)
|
|
|
|
```json
|
|
{
|
|
"page": 1,
|
|
"perPage": 10
|
|
}
|
|
```
|
|
|
|
- **Create** : create a territory (note that uuid is optional, a uuid will be automatically attributed if it is not provided)
|
|
|
|
```json
|
|
{
|
|
"name": "Ain",
|
|
"shape": "[[[[ 4.7953935, 46.2200671 ], [ 4.793835, 46.2155098 ], ... [ 4.7967607, 46.2219542 ], [ 4.7953935, 46.2200671 ]]]]"
|
|
}
|
|
```
|
|
|
|
Note that _shape_ **must** be a string representation of the [_coordinates_ value of a GeoJSON MultiPolygon](https://www.rfc-editor.org/rfc/rfc7946#section-3.1.7)
|
|
|
|
- **Update** : update a territory
|
|
|
|
```json
|
|
{
|
|
"uuid": "80126a61-d128-4f96-afdb-92e33c75a3e1",
|
|
"name": "Ain",
|
|
"shape": "[[[[ 4.7953935, 46.2200671 ], [ 4.793835, 46.2155098 ], ... [ 4.7967607, 46.2219542 ], [ 4.7953935, 46.2200671 ]]]]"
|
|
}
|
|
```
|
|
|
|
Note that _shape_ **must** be a string representation of the [_coordinates_ value of a GeoJSON MultiPolygon](https://www.rfc-editor.org/rfc/rfc7946#section-3.1.7)
|
|
|
|
- **Delete** : delete a territory by its uuid
|
|
|
|
```json
|
|
{
|
|
"uuid": "80126a61-d128-4f96-afdb-92e33c75a3e1"
|
|
}
|
|
```
|
|
|
|
## Messages
|
|
|
|
As mentionned earlier, RabbitMQ messages are sent after these events :
|
|
|
|
- **Create** (message : the created territory informations, without the shape)
|
|
|
|
- **Update** (message : the updated territory informations, without the shape)
|
|
|
|
- **Delete** (message : the uuid of the deleted territory)
|
|
|
|
Various messages are also sent for logging purpose.
|
|
|
|
## Tests
|
|
|
|
Tests are run outside the container for ease of use (switching between different environments inside containers using prisma is complicated and error prone).
|
|
The integration tests use a dedicated database (see _db-test_ section of _docker-compose.yml_).
|
|
|
|
```bash
|
|
# run all tests (unit + integration)
|
|
npm run test
|
|
|
|
# unit tests only
|
|
npm run test:unit
|
|
|
|
# integration tests only
|
|
npm run test:integration
|
|
|
|
# coverage
|
|
npm run test:cov
|
|
```
|
|
|
|
## License
|
|
|
|
Mobicoop V3 - Territory Service is [AGPL licensed](LICENSE).
|