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:

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:

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

Endpoint Behavior

Generate Daily Fortune Data

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

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

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:

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:

{
  "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:

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

Failure Responses

The following messages are literal server responses.

Missing Birthplace

Request:

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

Response:

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

Missing Device ID

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

Invalid Birth Date

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

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

Invalid Birth Time

For example, birthHour=25 or birthMinute=80:

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

Invalid Target Date

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

Invalid Time Zone

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

Unsupported Birthplace

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

Unsupported Day Boundary Mode

{
  "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:

Province + city

Examples:

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

An unmatched birthplace returns:

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

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:

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.