322 lines
9.2 KiB
Markdown
322 lines
9.2 KiB
Markdown
# 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.
|