apksel-dev/apskel-pos-backend
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: cash advance

Browse Source
This commit is contained in:
Efril
2026-08-13 14:38:28 +07:00
parent e6078e3c0b
commit 2c6864147b
36 changed files with 2355 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+134 -72
View File
@@ -15,15 +15,19 @@ Makefile requires installed dependecies:
```shell
$ make
Usage: make [command]
Usage: make [command] [ENV=staging|production]
Commands:
run Run server (default: staging)
run ENV=production Run server with production config
rename-project name={name} Rename project
build-http Build http server
migration-create name={name} Create migration
migration-up Up migrations
migration-up ENV=production Up migrations (production DB)
migration-down Down last migration
docker-up Up docker services
@@ -36,24 +40,16 @@ Commands:
## HTTP Server
```shell
$ ./bin/http-server --help
Usage: http-server
Flags:
-h, --help Show mycontext-sensitive help.
--env-path=STRING Path to env config file
```
**Configuration** is based on the environment variables. See [.env.template](.env).
The server takes no CLI flags. It reads `ENV_MODE` and loads the matching YAML file from
[infra/](infra/) — see [Running the Application](#running-the-application) for details.
```shell
# Expose env vars before and start server
$ ./bin/http-server
# Build, then start with the staging config (default)
$ go build -o ./bin/http-server ./cmd/server/main.go
$ ENV_MODE=staging ./bin/http-server
# Expose env vars from the file and start server
$ ./bin/http-server --env-path ./config/env/.env
# Start with the production config
$ ENV_MODE=production ./bin/http-server
```
## API Docs
@@ -124,7 +120,7 @@ Handler → Service → Processor → Repository
## API Endpoints
### Health Check
- `GET /api/v1/health` - Health check endpoint
- `GET /health` - Health check endpoint (registered at the root, not under `/api/v1`)
### Organizations
- `POST /api/v1/organizations` - Create organization
@@ -157,73 +153,139 @@ Handler → Service → Processor → Repository
- `PUT /api/v1/order-items/{id}` - Update order item
- `DELETE /api/v1/order-items/{id}` - Remove order item
## Installation
## Running the Application
1. **Clone the repository**
```bash
git clone <repository-url>
cd apskel-pos-backend
```
### Prerequisites
2. **Install dependencies**
```bash
go mod tidy
```
| Tool | Version | Needed for |
|------|---------|------------|
| [Go](https://go.dev/doc/install) | 1.24+ | building & running the server |
| [golang-migrate](https://github.com/golang-migrate/migrate) | latest | `make migration-*` targets |
| [make](https://www.gnu.org/software/make/) | any | shortcut commands (Windows: use Git Bash / WSL, see note below) |
| [docker & docker-compose](https://docs.docker.com/compose/) | optional | running Postgres/Redis locally |
| [air](https://github.com/air-verse/air) | optional | hot reload during development (`.air.toml` is already configured) |
3. **Set up database**
```bash
# Set your PostgreSQL database URL
export DATABASE_URL="postgres://username:password@localhost:5432/apskel_pos?sslmode=disable"
```
4. **Run migrations**
```bash
make migration-up
```
## Usage
### Development
### 1. Clone & install dependencies
```bash
# Start the server
go run cmd/server/main.go -port 8080 -db-url "postgres://username:password@localhost:5432/apskel_pos?sslmode=disable"
# Or using environment variable
export DATABASE_URL="postgres://username:password@localhost:5432/apskel_pos?sslmode=disable"
go run cmd/server/main.go -port 8080
git clone <repository-url>
cd apskel-pos-backend
go mod download
```
### Using Make Commands
### 2. Configuration
Configuration is **not** read from `.env` files — it is loaded from YAML files in [infra/](infra/)
by [config/configs.go](config/configs.go) using viper.
The file is selected by the `ENV_MODE` environment variable:
| `ENV_MODE` | Config file loaded |
|------------|--------------------|
| `local` | `infra/local.yaml` |
| `development` | `infra/development.yaml` |
| `staging` *(default)* | `infra/staging.yaml` |
| `production` | `infra/production.yaml` |
Any other/unset value falls back to `staging`. Only `staging.yaml` and `production.yaml` are
committed — for `local`/`development` copy one of them first:
```bash
# Run the application
make start
# Format code
make fmt
# Run tests
make test
# Build for production
make build-http
# Docker operations
make docker-up
make docker-down
# Database migrations
make migration-create name=create_users_table
make migration-up
make migration-down
cp infra/staging.yaml infra/local.yaml
```
Two important notes:
* The config path is **relative to the working directory**, so always run the server from the
repository root, otherwise viper panics with `failed to read config file`.
* Push notifications need `infra/firebase-service-account.json` (git-ignored). Without it, obtain
the file from the team before enabling FCM features.
### 3. Run migrations
The migration targets build the DB URL from the credentials at the top of the [Makefile](Makefile):
```bash
make migration-up # staging DB (default)
make migration-up ENV=production # production DB
make migration-create name=create_cash_advances_table
make migration-down # roll back the last migration
make migration-force version=87 # clear a dirty migration state
```
### 4. Start the server
```bash
make run # ENV_MODE=staging
make run ENV=production # ENV_MODE=production
```
`make run` is just a wrapper around:
```bash
ENV_MODE=staging go run cmd/server/main.go
```
The server listens on the `server.port` value from the loaded YAML (**4000** for both staging and
production). Verify it is up:
```bash
curl http://localhost:4000/health
```
All application routes live under `/api/v1` (see [internal/router/router.go](internal/router/router.go)).
#### Windows note
The `run`/`start` targets use POSIX inline env-var syntax, which `cmd.exe` and PowerShell do not
understand. Either run `make` from Git Bash / WSL, or start the server directly:
```powershell
# PowerShell
$env:ENV_MODE = "staging"; go run cmd/server/main.go
```
```cmd
:: cmd.exe
set ENV_MODE=staging && go run cmd/server/main.go
```
#### Hot reload
```bash
ENV_MODE=local air # rebuilds ./tmp/main on every .go change
```
### 5. Other commands
```bash
make # show all available targets
make fmt # go fmt ./...
make test # go test ./... -v
# Build a binary (make build-http still points at the old ./cmd/http path)
go build -o ./bin/http-server ./cmd/server/main.go
```
### Running with Docker
`docker-compose.yaml` provides Postgres (`5432`), Redis (`6379`), and the API image. See
[DOCKER.md](DOCKER.md) for the full workflow.
```bash
make docker-up # docker-compose up -d
make docker-down # docker-compose down
```
If you use the containerised Postgres/Redis, point `infra/local.yaml` at `localhost:5432` /
`localhost:6379` instead of the remote hosts baked into `staging.yaml`.
## Example API Usage
### Create Organization
```bash
curl -X POST http://localhost:8080/api/v1/organizations \
curl -X POST http://localhost:4000/api/v1/organizations \
-H "Content-Type: application/json" \
-d '{
"name": "My Restaurant",
@@ -233,7 +295,7 @@ curl -X POST http://localhost:8080/api/v1/organizations \
### Create User
```bash
curl -X POST http://localhost:8080/api/v1/users \
curl -X POST http://localhost:4000/api/v1/users \
-H "Content-Type: application/json" \
-d '{
"organization_id": "uuid-here",
@@ -247,7 +309,7 @@ curl -X POST http://localhost:8080/api/v1/users \
### Create Order with Items
```bash
curl -X POST http://localhost:8080/api/v1/orders \
curl -X POST http://localhost:4000/api/v1/orders \
-H "Content-Type: application/json" \
-d '{
"outlet_id": "uuid-here",