Add claude-generated README

2026-04-02 19:31:09 +03:00
parent 6d67e969e0
commit 2402d0e01f
1 changed files with 381 additions and 160 deletions
--- a/README.md
+++ b/README.md
@@ -1,177 +1,398 @@
 # Payouts Service

-## API Endpoints
+A Go service for processing payouts via YooKassa, supporting SBP, YooMoney, bank card, and widget-based payout flows.

-### User Management
+---

-#### Register User
- **Path**: `/api/v1/user/register`
- **Method**: POST
- **Request Parameters**:
-  ```json
-  {
-    "tin": "string",
-    "phone": "string",
-    "password": "string",
-    "password_cfm": "string"
-  }
-  ```
- **Response Parameters**:
-  ```json
-  {
-    "status": "string"
-  }
-  ```
- **Curl Example**:
-  ```bash
-  curl -X POST http://localhost:8080/api/v1/user/register \
-    -H "Content-Type: application/json" \
-    -d '{"tin":"1234567890","phone":"+79991234567","password":"password123","password_cfm":"password123"}'
-  ```
+## API Reference

-#### User Login
- **Path**: `/api/v1/user/login`
- **Method**: POST
- **Request Parameters**:
-  ```json
-  {
-    "phone": "string",
-    "password": "string"
-  }
-  ```
- **Response Parameters**:
-  ```json
-  {
-    "token": "string",
-    "token_ttl": "integer"
-  }
-  ```
- **Curl Example**:
-  ```bash
-  curl -X POST http://localhost:8080/api/v1/user/login \
-    -H "Content-Type: application/json" \
-    -d '{"phone":"+79991234567","password":"password123"}'
-  ```
+### `GET /health`

-### Payout Operations
+Health check endpoint. Verifies database connectivity.

-#### Get SBP Banks
- **Path**: `/api/v1/payout/sbp/banks`
- **Method**: GET
- **Request Parameters**: None
- **Response Parameters**:
-  ```json
-  [
-      {
-        "bank_id": "string",
-        "name": "string",
-        "bic": "string"
-      }
+**Request parameters:** None
+
+**Response:**
+
+| Status | Body |
+|--------|------|
+| `200 OK` | `{"OK": true}` |
+| `503 Service Unavailable` | `{"OK": false, "Error": "error details"}` |
+
+**Example:**
+```bash
+curl -s http://localhost:8080/health
+```
+
+---
+
+### `GET /version`
+
+Returns the application version.
+
+**Request parameters:** None
+
+**Response:** Plain text version string (e.g. `v1.0.0`). If version is `unknown`, the git commit hash from build info is appended.
+
+**Example:**
+```bash
+curl -s http://localhost:8080/version
+```
+
+---
+
+### `POST /api/v1/user/register`
+
+Register a new user.
+
+**Request body (JSON):**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `tin` | string | yes | Tax identification number |
+| `phone` | string | yes | Phone number (must be unique) |
+| `password` | string | yes | Password |
+| `password_cfm` | string | yes | Password confirmation (must match `password`) |
+
+**Response:**
+
+| Status | Description |
+|--------|-------------|
+| `201 Created` | User registered successfully (no body) |
+| `400 Bad Request` | Validation error or phone already registered |
+| `500 Internal Server Error` | Password hashing failure |
+
+**Example:**
+```bash
+curl -s -X POST http://localhost:8080/api/v1/user/register \
+  -H "Content-Type: application/json" \
+  -d '{"tin":"123456789","phone":"+79001234567","password":"secret","password_cfm":"secret"}'
+```
+
+---
+
+### `POST /api/v1/user/login`
+
+Authenticate a user and obtain a session token.
+
+**Request body (JSON):**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `phone` | string | yes | Registered phone number |
+| `password` | string | yes | Password |
+
+**Response (200 OK):**
+```json
+{
+  "token": "550e8400-e29b-41d4-a716-446655440000",
+  "token_ttl": 1712000000
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `token` | string | UUID session token to use in subsequent requests |
+| `token_ttl` | integer | Unix timestamp when the token expires |
+
+**Error response:**
+```json
+{
+  "status": 401,
+  "message": "Unauthorized"
+}
+```
+
+**Example:**
+```bash
+curl -s -X POST http://localhost:8080/api/v1/user/login \
+  -H "Content-Type: application/json" \
+  -d '{"phone":"+79001234567","password":"secret"}'
+```
+
+---
+
+### `GET /api/v1/payout/sbp/banks`
+
+Retrieve the list of banks available for SBP payouts.
+
+**Request parameters:** None
+
+**Authentication:** Not required
+
+**Response (200 OK):**
+```json
+{
+  "type": "sbp_banks",
+  "items": [
+    {
+      "bank_id": "100000000111",
+      "name": "Тинькофф Банк",
+      "bic": "044525974"
+    }
  ]
-  ```
- **Curl Example**:
-  ```bash
-  curl -X GET http://localhost:8080/api/v1/payout/sbp/banks
-  ```
+}
+```

-#### Create Payout
- **Path**: `/api/v1/payout/create`
- **Method**: POST
- **Request Parameters: SBP**:
-  ```json
-  {
-    "payout_type": "spb",
-    "bank_id": "string",
-    "amount": "float"
-  }
-  ```
-> **_NOTE:_**
-> Phone number for SBP payout comes from user's profile
+**Example:**
+```bash
+curl -s http://localhost:8080/api/v1/payout/sbp/banks
+```

- **Request Parameters: YooMoney**:
-  ```json
-  {
-    "payout_type": "yoo_money",
-    "account_number": "string",
-    "amount": "float"
-  }
-  ```
- **Response Parameters**:
-  ```json
-  {
-    "payout_id": "string",
-    "payout_status": "string"
-  }
-  ```
- **Curl Example**:
-  ```bash
-  curl -X POST http://localhost:8080/api/v1/payout/create \
-    -H "Content-Type: application/json" \
-    -H "Authorization: Bearer <session_token>" \
-    -d '{"payout_type":"spb","bank_id":"123456","amount":10.00}'
-  ```
+---

-#### Payout Callback
- **Path**: `/api/v1/payout/callback`
- **Method**: POST
- **Request Parameters**: YooKassa webhook data (JSON)
- **Response Parameters**: None
- **Curl Example**:
-  ```bash
-  curl -X POST http://localhost:8080/api/v1/payout/callback \
-    -H "Content-Type: application/json" \
-    -d '{"id":"payout_123456","status":"succeeded","amount":{"value":"10.00","currency":"RUB"}}'
-  ```
+### `POST /api/v1/payout/create`

-## Service Configuration
+Create a payout. The `payout_type` determines which additional fields are required.

-### Server Configuration
-| Property | Description | Default Value |
-|----------|-------------|---------------|
-| Server.Tls.Enabled | Enable TLS for the server | false |
-| Server.Tls.CertFile | Path to TLS certificate file | (empty) |
-| Server.Tls.KeyFile | Path to TLS key file | (empty) |
-| Server.Port | Server port | :8080 |
-| Server.WriteTimeout | Write timeout for requests | 35s |
-| Server.ReadTimeout | Read timeout for requests | 35s |
-| Server.EnablePProfEndpoints | Enable pprof debug endpoints | false |
+**Request headers:**

-### Database Configuration
-| Property | Description | Default Value |
-|----------|-------------|---------------|
-| Database.Type | Database type (sqlite, postgres) |  (empty) |
-| Database.Connection | Database connection string |  (empty)  |
-| Database.LogLevel | Database logging level | Info |
-| Database.TraceRequests | Enable request tracing | false |
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Authorization` | yes | `Bearer {token}` — session token from login |
+| `Content-Type` | yes | `application/json` |

-### YooKassa Configuration
-| Property | Description | Default Value |
-|----------|-------------|---------------|
-| YooKassa.Test | Enable test mode | false |
-| YooKassa.ApiBaseKey | YooKassa base API key | (empty) |
-| YooKassa.ApiBaseSecret | YooKassa base API secret | (empty) |
-| YooKassa.ApiPayoutKey | YooKassa payout API key | (empty) |
-| YooKassa.ApiPayoutSecret | YooKassa payout API secret | (empty) |
-| YooKassa.BaseUrl | YooKassa API base URL | https://api.yookassa.ru/v3 |
-| YooKassa.Timeout | Request timeout | 2s |
-| YooKassa.CheckAllowedCallbackAddress | Check callback IP addresses | true |
-| YooKassa.AllowedCallbackSubnets | Allowed callback IP subnets | (list of allowed subnets) |
-| YooKassa.CallbackProcessTimeout | Delay to process YooKassa allback | 1s |
-| YooKassa.Retry.Enabled | Enable request retries | false |
-| YooKassa.Retry.Count | Number of retry attempts | 3 |
-| YooKassa.Retry.WaitTime | Initial wait time between retries | 200ms |
-| YooKassa.Retry.MaxWaitTime | Maximum wait time between retries | 5s |
+**Request body (JSON):**

-### Cache Configuration
-| Property | Description | Default Value |
-|----------|-------------|---------------|
-| Cache.TTL | Session TTL | 24h |
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `payout_type` | string | yes | One of: `spb`, `yoo_money`, `bank_card`, `widget` |
+| `amount` | float | yes | Payout amount in rubles |
+| `payout_token` | string | for `widget` | Token received from the YooKassa widget `success_callback` |
+| `account_number` | string | for `yoo_money` | YooMoney wallet number or phone |
+| `bank_id` | string | for `spb` | Bank identifier from `/api/v1/payout/sbp/banks` |
+| `card_number` | string | for `bank_card` | Card number |

-### Logging Configuration
-| Property | Description | Default Value |
-|----------|-------------|---------------|
-| Log.Level | Log level | DEBUG |
-| Log.FilePath | | ./logs/payouts.log
-| Log.TextOutput | | false
-| Log.StdoutEnabled | | true
-| Log.FileEnabled | | false
+> **Note:** For `spb`, the phone number is taken from the authenticated user's profile.
+
+**Response (200 OK):**
+```json
+{
+  "payout_id": "po-285e5ee7-0022-5000-8000-01516a44b37d",
+  "payout_status": "succeeded"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `payout_id` | string | YooKassa payout identifier |
+| `payout_status` | string | One of: `created`, `pending`, `succeeded`, `canceled`, `failed` |
+
+**Error response:**
+```json
+{
+  "status": 401,
+  "message": "Unauthorized"
+}
+```
+
+**Example (SBP payout):**
+```bash
+curl -s -X POST http://localhost:8080/api/v1/payout/create \
+  -H "Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000" \
+  -H "Content-Type: application/json" \
+  -d '{"payout_type":"spb","amount":500.00,"bank_id":"100000000111"}'
+```
+
+**Example (widget payout):**
+```bash
+curl -s -X POST http://localhost:8080/api/v1/payout/create \
+  -H "Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000" \
+  -H "Content-Type: application/json" \
+  -d '{"payout_type":"widget","amount":500.00,"payout_token":"pt-285e5ee7-0022-5000-8000-01516a44b37d"}'
+```
+
+---
+
+### `POST /api/v1/payout/callback`
+
+Webhook endpoint for YooKassa payout status notifications. Called by YooKassa when a payout status changes.
+
+> **Note:** When `YooKassa.CheckAllowedCallbackAddress = true`, requests are validated against a CIDR whitelist of YooKassa IP ranges.
+
+**Request body (JSON, sent by YooKassa):**
+
+```json
+{
+  "id": "po-285e5ee7-0022-5000-8000-01516a44b37d",
+  "status": "succeeded",
+  "amount": {
+    "value": "500.00",
+    "currency": "RUB"
+  },
+  "payout_destination": {
+    "type": "bank_card",
+    "card": {
+      "number": "220000******0001",
+      "first6": "220000",
+      "last4": "0001",
+      "card_type": "MIR",
+      "issuer_country": "RU",
+      "issuer_name": "Sberbank"
+    }
+  },
+  "description": "Payout description",
+  "created_at": "2024-01-01T12:00:00.000Z",
+  "succeeded_at": "2024-01-01T12:00:05.000Z",
+  "test": false
+}
+```
+
+**Response:** `200 OK` (processing is asynchronous)
+
+**Example:**
+```bash
+curl -s -X POST http://localhost:8080/api/v1/payout/callback \
+  -H "Content-Type: application/json" \
+  -d '{"id":"po-285e5ee7-0022-5000-8000-01516a44b37d","status":"succeeded","amount":{"value":"500.00","currency":"RUB"}}'
+```
+
+---
+
+## Payout Widget: `/payout/widget`
+
+`GET /payout/widget` serves an HTML page that embeds the [YooKassa Payout Widget](https://yookassa.ru/developers/payouts/making-payouts/bank-card/using-payout-widget/implementing-widget). The widget collects card details from the user and returns a one-time `payout_token` that must be passed to `/api/v1/payout/create`.
+
+### Mobile App Integration
+
+The widget page is designed to be loaded inside a **WebView** on Android or iOS. The widget communicates back to the native app via JavaScript bridge callbacks.
+
+#### Widget Callbacks
+
+The widget fires two callbacks:
+
+**`success_callback(data)`** — called when the user successfully submits card details. The `data` object contains the `payout_token` and card metadata. See [YooKassa widget output parameters](https://yookassa.ru/developers/payouts/making-payouts/bank-card/using-payout-widget/implementing-widget#reference-output-parameters).
+
+**`error_callback(error)`** — called when an error occurs in the widget. See [error output parameters](https://yookassa.ru/developers/payouts/making-payouts/bank-card/using-payout-widget/implementing-widget#reference-output-parameters-error).
+
+#### Android
+
+Expose a JavaScript interface named `AndroidCallback` on the WebView:
+
+```kotlin
+class AndroidBridge {
+    @JavascriptInterface
+    fun onWidgetData(dataJson: String) {
+        val data = JSONObject(dataJson)
+        val payoutToken = data.getString("payout_token")
+        // Call /api/v1/payout/create with payout_type "widget"
+        createPayout(payoutToken = payoutToken, amount = 500.0)
+    }
+
+    @JavascriptInterface
+    fun onWidgetError(errorJson: String) {
+        // Handle widget error
+    }
+}
+
+webView.addJavascriptInterface(AndroidBridge(), "AndroidCallback")
+```
+
+#### iOS (WKWebView)
+
+Add a `WKScriptMessageHandler` named `iosCallback`:
+
+```swift
+class WidgetMessageHandler: NSObject, WKScriptMessageHandler {
+    func userContentController(
+        _ userContentController: WKUserContentController,
+        didReceive message: WKScriptMessage
+    ) {
+        guard let body = message.body as? String,
+              let data = body.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+        else { return }
+
+        if message.name == "onWidgetData" {
+            let payoutToken = json["payout_token"] as? String ?? ""
+            // Call /api/v1/payout/create with payout_type "widget"
+            createPayout(payoutToken: payoutToken, amount: 500.0)
+        } else if message.name == "onWidgetError" {
+            // Handle widget error
+        }
+    }
+}
+
+let contentController = WKUserContentController()
+let handler = WidgetMessageHandler()
+contentController.add(handler, name: "onWidgetData")
+contentController.add(handler, name: "onWidgetError")
+```
+
+#### Payout Flow After Widget Callback
+
+When `onWidgetData` fires, call `/api/v1/payout/create` with `payout_type = "widget"` and the received `payout_token`:
+
+```bash
+curl -s -X POST https://your-service/api/v1/payout/create \
+  -H "Authorization: Bearer {session_token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "payout_type": "widget",
+    "amount": 500.00,
+    "payout_token": "{payout_token_from_widget}"
+  }'
+```
+
+---
+
+## Configuration
+
+Configuration is loaded from a `.properties` file (default: `config/payouts.properties`).
+
+### YooKassa
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `YooKassa.BaseUrl` | `https://api.yookassa.ru/v3` | YooKassa API base URL |
+| `YooKassa.Timeout` | `2s` | HTTP request timeout |
+| `YooKassa.Test` | `false` | Enable test mode |
+| `YooKassa.ApiBaseKey` | — | Base API key (used for SBP bank list) |
+| `YooKassa.ApiBaseSecret` | — | Base API secret |
+| `YooKassa.ApiPayoutKey` | — | Payouts API key (gateway account ID; also used as `account_id` in the widget) |
+| `YooKassa.ApiPayoutSecret` | — | Payouts API secret |
+| `YooKassa.Retry.Enabled` | `false` | Enable automatic request retries |
+| `YooKassa.Retry.Count` | `3` | Total attempt count (including the initial request) |
+| `YooKassa.Retry.WaitTime` | `200ms` | Initial delay between retries |
+| `YooKassa.Retry.MaxWaitTime` | `5s` | Maximum delay (exponential backoff cap) |
+| `YooKassa.CheckAllowedCallbackAddress` | `true` | Validate callback source IP against whitelist |
+| `YooKassa.AllowedCallbackSubnets` | YooKassa IP ranges | Comma-separated CIDR subnets allowed to send callbacks |
+| `YooKassa.CallbackProcessTimeout` | `1s` | Timeout for async callback processing |
+| `YooKassa.WidgetVersion` | `3.1.0` | YooKassa widget JS version loaded on `/payout/widget` |
+
+### Database
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `Database.Type` | — | Database driver: `sqlite` or `postgres` |
+| `Database.Connection` | — | Connection string. SQLite: `payouts.db`. PostgreSQL: `host=127.0.0.1 user=gorm password=gorm dbname=gorm port=5432 sslmode=disable` |
+| `Database.LogLevel` | `Info` | GORM log level: `Debug`, `Info`, `Warn`, `Error` |
+| `Database.TraceRequests` | `false` | Log all SQL queries |
+
+### Session Cache
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `Cache.TTL` | `24h` | Session token time-to-live (Go duration string) |
+
+### Server
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `Server.Port` | `:8080` | Listening address and port |
+| `Server.WriteTimeout` | `35s` | Response write timeout |
+| `Server.ReadTimeout` | `35s` | Request read timeout |
+| `Server.EnablePProfEndpoints` | `false` | Expose `/debug/pprof` endpoints |
+| `Server.Tls.Enabled` | `false` | Enable TLS |
+| `Server.Tls.CertFile` | — | Path to TLS certificate file |
+| `Server.Tls.KeyFile` | — | Path to TLS private key file |
+
+### Logging
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `Log.Level` | `DEBUG` | Log level: `DEBUG`, `INFO`, `WARN`, `ERROR` |
+| `Log.FilePath` | `./logs/payouts.log` | Log file path |
+| `Log.TextOutput` | `false` | Use plain text output instead of JSON |
+| `Log.StdoutEnabled` | `true` | Write logs to stdout |
+| `Log.FileEnabled` | `false` | Write logs to file |