---
doc_id: aile-point-acquisition-user-stories
title: Aile 點獲取體系使用者故事（開發參考）
description: Aile 點獲取體系的 Backend、Admin、AileApp 與活動引擎使用者故事，供開發團隊在正式規格發布前參考。
slug: /developers/aile-point-acquisition-user-stories
product: Aile
category: development-reference
audience:
  - developer
  - product
visibility: public
status: published
version: 2.0.0
owner: aile-platform
updated_at: 2026-06-12
tags:
  - Aile
  - 點數體系
  - 使用者故事
  - 開發參考
rendered_html: /rendered/developers/aile-point-acquisition-user-stories/
download: true
sidebar_position: 2
---

# Aile 點獲取體系 — 完整使用者故事（統整修訂版 v2.0）

版本：v2.0（統整修訂版）

日期：2026-06-07

分組：Backend / Admin / AileApp / 活動引擎

配套設計規格：[Aile 點獲取體系 — 完整設計規格（統整修訂版 v2.0）](/docs/developers/aile-point-acquisition-design-spec/)

> [!NOTE]
> 本文件定位為開發參考用的臨時設計稿，協助團隊在正式規格文件發布前對齊需求拆解；待正式規格建立後，可由正式文件取代並移除此參考稿。

## 0. 說明

<aside>
🧭

本稿在原使用者故事 v1.0 基礎上，對齊三份文件衝突後重新整理，並補充了由統整方案推匯出、但原使用者故事缺失的條目（許可權校驗、一鍵補發、追加預算、補單重試）。關鍵修訂點已在條目備註中標註（參見設計規格第 12 節衝突編號）。

</aside>

階段總覽：**Phase 1** 給點底座 + 管理員給點 + 個人租戶購買 + 基礎審計；**Phase 2** AileApp 購買/明細與 Admin 報表增強；**Phase 3** 活動給點。

## Backend

### BE-01 統一給點基礎服務

**使用者故事**

作為 Aile 後端團隊，我想要提供統一的給點服務，封裝 AIPool 累點、冪等、狀態流轉與審計，以便管理員給點、使用者自購到賬、活動給點都能複用同一套可靠底座。

**驗收標準**

1. 給點服務支援管理員給點、購買到賬、活動給點等來源場景。
2. 每次給點生成或接收全域性唯一 `eventId`，同一 `eventId` 不重複給點。
3. 給點前寫入審計底稿（目標租戶、`openId`、點數、場景、來源業務 ID、狀態、備註）。
4. AIPool 成功返回後，審計狀態更新為 `Success`，記錄 `outTraceId`。
5. AIPool 業務拒絕時審計更新為 `Failed` 並保留失敗原因。
6. **（修訂 C2）**通訊超時/異常時保留 `Processing`，交由補單 Job 或手動重試，不靜默標為失敗。
7. 已成功的重複請求直接返回既有結果，不再呼叫 AIPool。

**備註**

- Phase：1
- 依賴：AIPool 累點介面契約、個人租戶與 `openId` 對映。
- **（修訂 C1）**新建 `TenantPointGrantService`，不堆入審計服務；審計讀寫複用 `TenantPointAuditService`。
- 不包含：審批流、活動規則引擎、前端頁面。

### BE-02 Aile 官方管理員給點服務

**使用者故事**

作為 Aile 官方管理員，我想要透過後臺對個人租戶直接授予 Aile 點，以便處理客訴補償、服務關懷、使用者挽留和運營激勵等場景。

**驗收標準**

1. 提供官方管理員給點介面，僅允許具備 Aile 官方管理員許可權的操作者使用。
2. 給點目標僅限個人租戶，團隊租戶不可作為 Phase 1 給點目標。
3. **（修訂 C8）**審計 `tenantId` 必須寫入目標個人租戶 ID（非 `SYSTEM_GLOBAL_TENANT`），以 `operatorId` 記錄管理員身份。
4. 支援給點原因：客訴補償、服務關懷、使用者挽留、系統故障補償、運營激勵、其他；“其他”必須提供備註。
5. 給點結果可透過 `eventId` 或審計記錄查詢。
6. 給點失敗時返回明確失敗原因，便於 Admin 展示和運營排查。

**備註**

- Phase：1
- 依賴：BE-01、Admin 許可權模型、租戶列表查詢能力。
- 不包含：額度上限、分級審批、AilePro 聊天介面給點。

### BE-03 Aile 點內嵌購買代理與到賬同步

**使用者故事**

作為個人租戶使用者，我想要在 Aile 內完成 Aile 點購買並自動到賬，以便減少跳轉 AIPool 的摩擦，在配額不足時及時恢復使用。

**驗收標準**

1. 後端可提供 Aile 點購買套餐或支付引數給 Admin/App 前端。
2. 使用者發起購買時，後端能建立或代理 AIPool 支付流程。
3. 支付成功後同步到賬結果並寫入點數審計（`auditScene=UserPurchase`）。
4. 購買到賬以訂單 ID 或支付流水作為冪等依據，不重複入賬。
5. 支付失敗、取消或超時狀態可被查詢並展示。
6. Aile 側餘額展示以 AIPool 或可信同步結果為準。

**備註**

- Phase：1 Admin；Phase：2 AileApp。
- 依賴：AIPool 支付/套餐/回撥契約。
- 不包含：Aile 自建支付通道。
- 待確認：套餐來源、支付方式、到賬觸發方式（見設計規格第 13 節）。

### BE-04 點數收支審計與報表介面

**使用者故事**

作為運營和客服團隊，我想要查詢所有 Aile 點收入、支出、失敗和處理中記錄，以便追蹤使用者點數變化、排查異常並統計運營效果。

**驗收標準**

1. 支援按租戶、時間範圍、場景、狀態、操作人、來源業務 ID 查詢審計記錄。
2. 審計列表同時展示收入和支出，正數表示獲點，負數表示扣點。
3. 支援基礎統計：本日/本月給點總額、給點次數、按場景或原因分佈。
4. 每條記錄展示 AIPool 響應碼、`outTraceId`、失敗原因等排障欄位。
5. 查詢介面不影響現有扣點審計與配額統計口徑。

**備註**

- Phase：1 基礎；Phase：2 報表增強。
- 依賴：BE-01、現有 `TenantPointAudit` 資料完整性。

### BE-05 活動給點規則與事件執行服務

**使用者故事**

作為運營團隊，我想要透過活動規則向符合條件的使用者自動發放 Aile 點，以便用註冊獎勵、邀請獎勵、節日活動等方式提升活躍和轉化。

**驗收標準**

1. 系統能接收使用者行為事件，並根據活動規則判斷是否符合給點條件。
2. 活動支援基礎配置：時間範圍、觸發條件、單次給點數量、參與上限、總預算。
3. 發點前必須完成預算原子扣減，避免併發超發。
4. 符合條件後釋出給點事件，透過統一給點服務執行。
5. 活動參與記錄可查詢，包含成功、失敗、重複、預算不足等狀態。
6. 活動預算耗盡時自動進入 `EXHAUSTED` 狀態並停止繼續發點。

**備註**

- Phase：3
- 依賴：BE-01、活動服務歸屬確認（見設計規格 Q7）、Pub/Sub/Redis 可用性。
- **（修訂 C3）**活動狀態列舉統一為 `DRAFT/ACTIVE/PAUSED/EXHAUSTED/ENDED/ARCHIVED`。
- 不包含：複雜 Blockly 規則編輯器首期完整實現，可先支援固定規則模板。

### BE-06 失敗補單與手動重試（新增）

**使用者故事**

作為運維/後端團隊，我想要對處於 `Failed` 或長期 `Processing` 的給點記錄進行補單重試，以便在 AIPool 超時/異常後安全恢復給點，且不重複發放。

**驗收標準**

1. 補單/重試始終攜帶原 `eventId`，依賴冪等保證不重複給點。
2. 已 `Success` 的記錄補單時直接返回原成功結果。
3. 補單 Job 可自動掃描長期 `Processing` 記錄並重推；人工可手動觸發重試。
4. 重試走過同一狀態機（`Failed`→`Processing`→`Success`/`Failed`）。

**備註**

- Phase：1（手動重試基礎）；Phase：3（活動補發控制檯）。
- 依賴：BE-01。
- 說明：對應設計規格衝突 C2的狀態保留策略。

## Admin

### AD-01 官方管理員租戶列表給點

**使用者故事**

作為 Aile 官方管理員，我想要在租戶列表中篩選個人租戶併發起給點，以便快速完成補償、關懷或運營激勵。

**驗收標準**

1. 租戶列表支援搜尋、租戶型別篩選和狀態篩選。
2. 僅個人租戶顯示“給點”操作入口。
3. 給點彈窗展示目標租戶資訊，支援輸入點數、選擇原因、填寫備註。
4. 提交前展示二次確認，避免誤發。
5. 提交後展示成功、失敗或處理中狀態。
6. 重複點選提交不會造成重複給點。

**備註**

- Phase：1
- 依賴：BE-02、租戶列表介面、Admin 許可權識別。

### AD-02 點數審計查詢與運營統計

**使用者故事**

作為 Aile 運營人員，我想要在後臺檢視點數給出、扣除、購買和失敗記錄，以便做日常排查、對賬和運營分析。

**驗收標準**

1. 支援按租戶、時間、場景、狀態、操作人、原因篩選記錄。
2. 明細列表展示點數變化、來源場景、狀態、原因、AIPool trace、時間。
3. 收入和支出有清晰區分。
4. 頁面展示本日/本月給點總額、給點次數和原因分佈。
5. 失敗記錄可看到失敗原因，並能複製 `eventId` 供 backend 排查。

**備註**

- Phase：1 基礎；Phase：2 報表增強。
- 依賴：BE-04。

### AD-03 個人租戶內嵌購買元件

**使用者故事**

作為個人租戶管理員，我想要在 Admin 我的配額頁面直接購買 Aile 點，以便在點數不足時快速補充餘額，繼續使用付費配額能力。

**驗收標準**

1. 我的配額頁面展示 Aile 點餘額和“立即購買”入口。
2. 購買彈窗展示可購買檔位、價格、贈送資訊和支付方式。
3. 使用者選擇檔位後可進入 AIPool 支付流程。
4. 支付成功後頁面重新整理餘額，並展示購買成功狀態。
5. 支付失敗、取消或超時時有明確提示。
6. 購買記錄出現在點數收支明細中。

**備註**

- Phase：1
- 依賴：BE-03、AIPool 支付流程。

### AD-04 活動管理與參與審計

**使用者故事**

作為運營人員，我想要在 Admin 後臺配置和監控點數活動，以便管理活動預算、規則、參與情況和發點異常。

**驗收標準**

1. 支援建立、編輯、啟用、暫停、結束活動。
2. 活動配置至少包含時間範圍、觸發條件、獎勵點數、總預算、參與上限。
3. 活動列表展示狀態、預算剩餘、參與人數、發放點數。
4. 參與審計可檢視每個使用者的獎勵狀態和失敗原因。
5. **（修訂 C3）**預算耗盡時狀態清晰展示為 `EXHAUSTED` 並停止繼續發點；狀態取值使用統一列舉。
6. 支援對失敗記錄進行人工排查，是否補發由許可權與流程控制。

**備註**

- Phase：3
- 依賴：BE-05。
- 不包含：首期不強制實現複雜視覺化規則編排器。

### AD-05 活動預算追加與一鍵補發（新增）

**使用者故事**

作為運營人員，我想要對進行中或已用罄的活動追加預算，並對發放失敗的記錄一鍵補發，以便靈活調整活動節奏並修復異常。

**驗收標準**

1. 可對 `ACTIVE`/`EXHAUSTED` 活動追加預算，追加成功後差額同步 `INCRBY` 至 Redis 可用預算。
2. 追加預算為執行緒安全操作，不會造成預算超發。
3. 對 `Failed` 參與記錄可一鍵 `Re-run`，底層攜帶原 `eventId`。
4. 由於 Unique Index + `code` 雙重冪等，重複點選或原交易實際已成功時絕不重複發點。

**備註**

- Phase：3
- 依賴：BE-05、BE-06。

## AileApp 前端

### APP-01 Aile 點購買入口與超額引導

**使用者故事**

作為 AileApp 使用者，我想要在點數不足或觸發超額時看到購買入口，以便快速補充 Aile 點並繼續完成當前操作。

**驗收標準**

1. 點數管理或配額相關頁面展示 Aile 點餘額和購買入口。
2. 當使用者觸發點數不足或超額提示時，能進入購買引導。
3. 購買入口能展示可購買檔位，並接入後端支付流程。
4. 支付成功後餘額重新整理。
5. 支付失敗、取消或超時時有明確提示。

**備註**

- Phase：2
- 依賴：BE-03。

### APP-02 點數收支明細

**使用者故事**

作為 AileApp 使用者，我想要檢視自己的 Aile 點收入和支出明細，以便理解點數來源、消費原因和當前餘額變化。

**驗收標準**

1. 明細頁按時間倒序展示點數收入與支出。
2. 每條記錄展示場景、點數變化、狀態、時間和簡短說明。
3. 收入和支出視覺區分清晰。
4. 支援檢視購買充值、管理員給點、活動獎勵、超額扣點等型別。
5. 失敗或處理中記錄不誤導使用者為已到賬或已扣除。

**備註**

- Phase：2
- 依賴：BE-04。

### APP-03 活動中心與獎勵狀態

**使用者故事**

作為 AileApp 使用者，我想要檢視當前可參與的點數活動和獎勵領取狀態，以便透過完成活動獲得 Aile 點。

**驗收標準**

1. 活動中心展示進行中的活動列表。
2. 活動詳情展示規則、獎勵點數、時間範圍和參與條件。
3. 使用者能看到自己的參與狀態：未參與、已達成、發放中、已到賬、失敗。
4. 獎勵到賬後有明確通知或狀態變化。
5. 活動結束或預算用盡時，不再引導使用者參與。

**備註**

- Phase：3
- 依賴：BE-05、AD-04。

## 活動引擎（專項，Phase 3）

### ENG-01 高併發預算原子扣減與防刷（新增）

**使用者故事**

作為活動引擎，我想要在高併發下原子化執行預算校驗與扣減，以便徹底杜絕點數超發。

**驗收標準**

1. 使用 Redis Lua 指令碼序列化執行“檢查餘額 + 扣減”原子操作。
2. 預算充足返回成功併發布給點事件；不足返回失敗。
3. 預算不足時釋出告警並非同步更新活動狀態為 `EXHAUSTED`。
4. 同一使用者受頻次限制（如 `LIFETIME`、每日）約束，不可繞過。

**備註**

- Phase：3
- 依賴：BE-05、Redis/MemoryStore。

## 推進建議

1. **Phase 1** 優先同時推進 BE-01、BE-02、BE-03、BE-04 基礎版、BE-06手動重試基礎，以及 AD-01、AD-02 基礎版、AD-03。
2. **Phase 2** 推進 AileApp 購買與明細體驗（APP-01、APP-02），並增強 Admin 報表。
3. **Phase 3** 再推進活動給點（BE-05、ENG-01、AD-04、AD-05、APP-03），避免活動規則複雜度阻塞首期商業閉環。