取得獎項資料 | Cube Rewards Tool

取得獎項資料.md

185 additions, 0 deletions

...	...	@@ -1 +1,186 @@
	1	+# 任務看板 - 取得獎項群組
	2	+### SUMMARY
	3	+取得指定獎項群組的詳細資訊,包含該群組下所有關聯的獎項。此 API 會預先載入獎項的獎品群組資訊,回傳完整的獎項群組資料結構。
	4	+
	5	+### REFERENCE TABLE
	6	+
	7	+獎項相關
	8	+* `DBMT.AWARD_GROUP`
	9	+* `DBMT.AWARD`
	10	+
	11	+### ATTRIBUTES
	12	+* METHOD: GET
	13	+* PATH: `/api/features/mission-board/award-group/{int: id}`
	14	+* LOGIN REQUIRED: TRUE
	15	+* FEATURE: `AWARD_GROUP`
	16	+* PERMISSION: `READ`
	17	+* CRYPTO: None
	18	+
	19	+### REQUEST
	20	+#### HEADERS
	21	+
	22	+\| Name \| Type/Len \| Required(*) \| Desc \|
	23	+\| ---\| ---\| ---\| --- \|
	24	+\| Authorization \| String \| * \| JWT Token \|
	25	+\| X-Request-Id \| String \| \| X-Request-Id for api flow tracing \|
	26	+
	27	+```json
	28	+// Example:
	29	+{
	30	+ "Authorization": "Bearer jwt-token",
	31	+ "x-request-id": "78f91284-d9df-43e6-a8d2-d557273c10bb"
	32	+}
	33	+```
	34	+
	35	+#### PATH PARAMETERS
	36	+
	37	+\| Name \| Type/Len \| Required(*) \| Desc \|
	38	+\| ---\| ---\| ---\| --- \|
	39	+\| id \| Integer \| * \| 獎項群組 ID \|
	40	+
	41	+```cs
	42	+// Example
	43	+GET /api/features/mission-board/award-group/1
	44	+```
	45	+
	46	+### RESPONSE
	47	+#### STATUS CODE
	48	+* 200
	49	+
	50	+#### HEADERS
	51	+
	52	+\| Name \| Type/Len \| Desc \|
	53	+\| ---\| ---\| --- \|
	54	+\| Authorization \| String \| JWT Token \|
	55	+\| X-Request-Id \| String \| Returning Request-Id \|
	56	+
	57	+```json
	58	+// Example:
	59	+{
	60	+ "Authorization": "Bearer jwt-token",
	61	+ "x-request-id": "78f91284-d9df-43e6-a8d2-d557273c10bb"
	62	+}
	63	+```
	64	+
	65	+#### BODY
	66	+
	67	+\| Level \| Name \| Type/Len \| Nullable(*) \| Desc \|
	68	+\| ---\| ---\| ---\| ---\| --- \|
	69	+\| 1 \| code \| Integer \| \| 回應狀態碼 \|
	70	+\| 1 \| message \| String \| \| 回應訊息 \|
	71	+\| 1 \| data \| Dict \| \| 獎項群組資料 \|
	72	+
	73	+#### Data (AwardGroup)
	74	+
	75	+\| Level \| Name \| Type/Len \| Nullable(*) \| Desc \| Source \|
	76	+\| ---\| ---\| ---\| ---\| ---\| --- \|
	77	+\| 2 \| id \| Integer \| \| 獎項群組 ID \| `AWARD_GROUP.ID` \|
	78	+\| 2 \| name \| String \| \| 獎項群組名稱 \| `AWARD_GROUP.NAME` \|
	79	+\| 2 \| status \| Enum \| \| 獎項群組狀態 \| `AWARD_GROUP.STATUS` \|
	80	+\| 2 \| start_time \| Datetime \| \| 開始時間 \| `AWARD_GROUP.START_TIME` \|
	81	+\| 2 \| end_time \| Datetime \| \| 結束時間 \| `AWARD_GROUP.END_TIME` \|
	82	+\| 2 \| create_time \| Datetime \| \| 建立時間 \| `AWARD_GROUP.CREATE_TIME` \|
	83	+\| 2 \| update_time \| Datetime \| * \| 更新時間 \| `AWARD_GROUP.UPDATE_TIME` \|
	84	+\| 2 \| awards \| List \| \| 獎項清單 \| - \|
	85	+
	86	+#### Awards
	87	+
	88	+\| Level \| Name \| Type/Len \| Nullable(*) \| Desc \| Source \|
	89	+\| ---\| ---\| ---\| ---\| ---\| --- \|
	90	+\| 3 \| id \| Integer \| \| 獎項 ID \| `AWARD.ID` \|
	91	+\| 3 \| code \| String \| \| 獎項代號 \| `AWARD.CODE` \|
	92	+\| 3 \| name \| String \| \| 獎項名稱 \| `AWARD.NAME` \|
	93	+\| 3 \| group_id \| Integer \| \| 獎項群組 ID \| `AWARD.GROUP_ID` \|
	94	+\| 3 \| active_status \| Enum \| \| 啟用狀態 \| `AWARD.ACTIVE_STATUS` \|
	95	+\| 3 \| process_status \| Enum \| \| 處理狀態 \| `AWARD.PROCESS_STATUS` \|
	96	+\| 3 \| award_type \| Enum \| \| 獎項類型 \| `AWARD.AWARD_TYPE` \|
	97	+\| 3 \| deliver_type \| Enum \| \| 派發類型 \| `AWARD.DELIVER_TYPE` \|
	98	+\| 3 \| deliver_amount \| Integer \| \| 派發數量 \| `AWARD.DELIVER_AMOUNT` \|
	99	+\| 3 \| deliver_limit \| Integer \| \| 派發上限 \| `AWARD.DELIVER_LIMIT` \|
	100	+\| 3 \| deliver_time \| Datetime \| * \| 派發時間 \| `AWARD.DELIVER_TIME` \|
	101	+\| 3 \| create_time \| Datetime \| \| 建立時間 \| `AWARD.CREATE_TIME` \|
	102	+\| 3 \| update_time \| Datetime \| * \| 更新時間 \| `AWARD.UPDATE_TIME` \|
	103	+
	104	+```json
	105	+// Example:
	106	+{
	107	+ "status": "success",
	108	+ "data": {
	109	+ "id": 1,
	110	+ "name": "春季活動獎項組",
	111	+ "status": "ACTIVE",
	112	+ "start_time": "2026/03/01 00:00:00",
	113	+ "end_time": "2026/03/31 23:59:59",
	114	+ "create_time": "2026/02/15 10:30:00",
	115	+ "update_time": "2026/02/20 14:45:00",
	116	+ "awards": [
	117	+ {
	118	+ "id": 101,
	119	+ "code": "AWARD_001",
	120	+ "name": "小樹點獎勵",
	121	+ "group_id": 1,
	122	+ "active_status": "ACTIVE",
	123	+ "process_status": "AVAILABLE",
	124	+ "award_type": "ORCA_POINT",
	125	+ "deliver_type": "IMMEDIATE",
	126	+ "deliver_amount": 100,
	127	+ "deliver_limit": 1000,
	128	+ "deliver_time": null,
	129	+ "create_time": "2026/02/15 10:35:00",
	130	+ "update_time": "2026/02/20 14:50:00"
	131	+ },
	132	+ {
	133	+ "id": 102,
	134	+ "code": "AWARD_002",
	135	+ "name": "國泰世華票券",
	136	+ "group_id": 1,
	137	+ "active_status": "ACTIVE",
	138	+ "process_status": "AVAILABLE",
	139	+ "award_type": "CATHAYBANK_VOUCHER",
	140	+ "deliver_type": "ETA",
	141	+ "deliver_amount": 50,
	142	+ "deliver_limit": 500,
	143	+ "deliver_time": "2026/04/01 00:00:00",
	144	+ "create_time": "2026/02/15 10:40:00",
	145	+ "update_time": null
	146	+ }
	147	+ ]
	148	+ }
	149	+}
	150	+```
	151	+
	152	+### ENUM VALUES
	153	+
	154	+#### AwardGroupStatus
	155	+
	156	+\| Value \| Desc \|
	157	+\| ---\| --- \|
	158	+\| ACTIVE \| 啟用中 \|
	159	+\| INACTIVE \| 未啟用 \|
	160	+\| RETIRED \| 已退役 \|
	161	+
	162	+#### AwardActiveStatus
	163	+
	164	+\| Value \| Desc \|
	165	+\| ---\| --- \|
	166	+\| ACTIVE \| 啟用 \|
	167	+\| INACTIVE \| 未啟用 \|
	168	+
	169	+#### AwardProcessStatus
	170	+
	171	+#### AwardType
	172	+
	173	+#### AwardDeliverType
	174	+
	175	+#### ERROR CODE
	176	+
	177	+```json
	178	+{
	179	+ "status": "failure",
	180	+ "status_code": 404,
	181	+ "error_code": "AwardGroupError.NOT_FOUND",
	182	+ "message": "Award group not found",
	183	+ "detail": "'{"id": 123}'",
	184	+}
	185	+```