lucky-cat/docs/device-fortune-controller-api.md

# DeviceFortuneController API

## Overview

| Item | Value |
| --- | --- |
| Service module | `token` |
| Controller | `com.talkingq.controller.DeviceFortuneController` |
| Purpose | Generate Four Pillars, Five Elements, daily favorable color, and daily wealth direction from the device ID, birth time, and birthplace |
| Endpoint | `POST /token/api/device/fortune/daily-wealth` |
| Content type | `application/json` |
| Response envelope | `AjaxResult`, always containing `code` and `message`, with `data` on successful responses that contain results |

The complete path through the gateway is normally:

```text
POST https://gz.api.talkingq.com/token/api/device/fortune/daily-wealth
```

When connecting directly to the token service, use its deployed port, for example:

```text
POST http://localhost:8095/token/api/device/fortune/daily-wealth
```

## Endpoint Behavior

### Generate Daily Fortune Data

```http
POST /token/api/device/fortune/daily-wealth
```

The device submits the user's birth year, month, day, hour, minute, and birthplace. The service returns:

- Device ID
- Four Pillars of Destiny
- Five Elements attribute
- Daily favorable color
- Daily wealth direction

Behavior:

- The Four Pillars and Five Elements remain stable for the same birth data.
- The favorable color and wealth direction are calculated for the target date. Results remain stable for the same device, birth data, and date.
- The birthplace participates in the calculation. It is matched to built-in province or city coordinates and used to adjust the birth time to local solar time.

## Request

The request body is a JSON object.

| Field | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| `deviceId` | string | Yes | `test-device` | Device ID. The trimmed value is returned as `设备id`. |
| `birthYear` | integer | Yes | `1998` | Birth year. It must form a valid date with the month and day. |
| `birthMonth` | integer | Yes | `5` | Birth month, normally 1 through 12 and validated by Java date handling. |
| `birthDay` | integer | Yes | `21` | Birth day. It must form a valid date with the year and month. |
| `birthHour` | integer | Yes | `14` | Birth hour, from 0 through 23. |
| `birthMinute` | integer | Yes | `30` | Birth minute, from 0 through 59. |
| `birthPlace` | string | Yes | `广东省广州市` | Birthplace. The current implementation matches supported provinces and major cities. |
| `timezone` | string | No | `Asia/Shanghai` | Time zone used to determine the target date. Defaults to the birthplace time zone, currently `Asia/Shanghai`. |
| `currentResidence` | string | No | `广东省深圳市` | Current residence. Reserved but not currently used by the algorithm. |
| `mbti` | string | No | `INFJ` | MBTI type. Reserved but not currently used by the algorithm. |
| `targetDate` | string | No | `2026-06-08` | Date used for the favorable color and wealth direction, formatted as `yyyy-MM-dd`. Defaults to the current date in `timezone`. |
| `dayBoundaryMode` | string | No | `zi_hour_23` | Day-pillar boundary rule. Supports `zi_hour_23`, `zi_23`, and `midnight`. Defaults to `zi_hour_23`. |

## Response

### Envelope

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | Business status code. Success is `200`; failures are normally `500`. |
| `message` | string | Response message. The success message is `生成命理信息成功`; failures contain a specific reason. |
| `data` | object | Business result on success. Usually omitted on failure. |

### Data Object

The response field names are part of the current server contract and are intentionally shown in Chinese.

| Field | Type | Example | Description |
| --- | --- | --- | --- |
| `设备id` | string | `test-device` | The request's `deviceId`. |
| `生辰八字` | string | `戊寅年 丁巳月 己巳日 辛未时` | Four Pillars text adjusted for birth time and birthplace. |
| `五行属性` | string | `土` | Five Elements attribute derived from the day stem. Possible values are `金`, `木`, `水`, `火`, and `土`. |
| `今日喜色` | string | `火` | Favorable color element. Possible values are `金`, `木`, `水`, `火`, and `土`. |
| `今日财位` | string | `正北` | Wealth direction. Possible values include `正北`, `东北`, `正东`, `东南`, `正南`, `西南`, `正西`, and `西北`. |

## Request Examples

### Windows PowerShell

```powershell
curl.exe -X POST "https://gz.api.talkingq.com/token/api/device/fortune/daily-wealth" `
  -H "Content-Type: application/json" `
  -d "{\"deviceId\":\"test-device\",\"birthYear\":1998,\"birthMonth\":5,\"birthDay\":21,\"birthHour\":14,\"birthMinute\":30,\"birthPlace\":\"广东省广州市\",\"currentResidence\":\"广东省深圳市\",\"mbti\":\"INFJ\",\"timezone\":\"Asia/Shanghai\",\"targetDate\":\"2026-06-08\"}"
```

### Linux and macOS

```bash
curl -X POST "https://gz.api.talkingq.com/token/api/device/fortune/daily-wealth" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "test-device",
    "birthYear": 1998,
    "birthMonth": 5,
    "birthDay": 21,
    "birthHour": 14,
    "birthMinute": 30,
    "birthPlace": "广东省广州市",
    "currentResidence": "广东省深圳市",
    "mbti": "INFJ",
    "timezone": "Asia/Shanghai",
    "targetDate": "2026-06-08"
  }'
```

### HTTP

Send this HTTP/1.1 request over TLS to `gz.api.talkingq.com`:

```http
POST /token/api/device/fortune/daily-wealth HTTP/1.1
Host: gz.api.talkingq.com
Content-Type: application/json

{
  "deviceId": "test-device",
  "birthYear": 1998,
  "birthMonth": 5,
  "birthDay": 21,
  "birthHour": 14,
  "birthMinute": 30,
  "birthPlace": "广东省广州市",
  "currentResidence": "广东省深圳市",
  "mbti": "INFJ",
  "timezone": "Asia/Shanghai",
  "targetDate": "2026-06-08"
}
```

## Success Response

This deterministic example uses:

```json
{
  "deviceId": "test-device",
  "birthYear": 1998,
  "birthMonth": 5,
  "birthDay": 21,
  "birthHour": 14,
  "birthMinute": 30,
  "birthPlace": "广东省广州市",
  "currentResidence": "广东省深圳市",
  "mbti": "infj",
  "timezone": "Asia/Shanghai",
  "targetDate": "2026-06-08"
}
```

Response:

```json
{
  "code": 200,
  "message": "生成命理信息成功",
  "data": {
    "设备id": "test-device",
    "生辰八字": "戊寅年 丁巳月 己巳日 辛未时",
    "五行属性": "土",
    "今日喜色": "火",
    "今日财位": "正北"
  }
}
```

## Failure Responses

The following messages are literal server responses.

### Missing Birthplace

Request:

```json
{
  "deviceId": "test-device",
  "birthYear": 1998,
  "birthMonth": 5,
  "birthDay": 21,
  "birthHour": 14,
  "birthMinute": 30
}
```

Response:

```json
{
  "code": 500,
  "message": "出生地点不能为空"
}
```

### Missing Device ID

```json
{
  "code": 500,
  "message": "deviceId不能为空"
}
```

### Invalid Birth Date

For example, `birthYear=2026`, `birthMonth=2`, and `birthDay=30`:

```json
{
  "code": 500,
  "message": "birthYear/birthMonth/birthDay不是有效日期"
}
```

### Invalid Birth Time

For example, `birthHour=25` or `birthMinute=80`:

```json
{
  "code": 500,
  "message": "birthHour/birthMinute不是有效时间"
}
```

### Invalid Target Date

```json
{
  "code": 500,
  "message": "targetDate格式不正确，应为yyyy-MM-dd"
}
```

### Invalid Time Zone

```json
{
  "code": 500,
  "message": "timezone格式不正确"
}
```

### Unsupported Birthplace

```json
{
  "code": 500,
  "message": "暂不支持该出生地点，请传入省份或主要城市名称"
}
```

### Unsupported Day Boundary Mode

```json
{
  "code": 500,
  "message": "dayBoundaryMode仅支持midnight或zi_hour_23"
}
```

## Supported Birthplaces

The implementation uses a built-in keyword list covering major Chinese provinces, municipalities, provincial capitals, important cities, Hong Kong, Macau, and Taiwan. Prefer the following input format:

```text
Province + city
```

Examples:

```text
广东省广州市
广东省深圳市
北京市
上海市
四川省成都市
浙江省杭州市
福建省厦门市
香港
澳门
台湾
```

An unmatched birthplace returns:

```text
暂不支持该出生地点，请传入省份或主要城市名称
```

## Test Coverage

| Test class | Coverage |
| --- | --- |
| `DeviceFortuneControllerTest` | Stable results for fixed birth data and date; daily results can change across dates; missing birthplace returns an error; client time zone does not change Four Pillars after birthplace adjustment. |
| `DeviceFortuneControllerRandomReportTest` | Generates random birth data, verifies `code=200`, and verifies that two consecutive calls with the same request return identical `data`. |

The existing random test report is:

```text
token/daily_wealth_interface_random_test_report.md
```

## Notes

- The response field names are currently Chinese: `设备id`, `生辰八字`, `五行属性`, `今日喜色`, and `今日财位`.
- `currentResidence` and `mbti` are reserved request fields and are not currently used.
- `今日喜色` returns a Five Elements name rather than a literal color. The business mapping is: metal (`金`) = white, wood (`木`) = green, water (`水`) = blue, fire (`火`) = red, and earth (`土`) = yellow.
- When `targetDate` is omitted, the server uses its current date and the request time zone. Specify `targetDate` for deterministic device behavior and automated testing.