230 lines
11 KiB
Markdown
230 lines
11 KiB
Markdown
# Master Plan: Loyalty Agent Service
|
|
|
|
_Focus hiện tại: MCP Orchestrator cho Reward Core API, dựa trên `loyalty-mcp-server/src/main/resources/specs/reward.json`._
|
|
|
|
Core Reward API đang expose **11 CSR resources chính** theo cùng một pattern Maker-Checker:
|
|
|
|
1. `Transaction Category`
|
|
2. `Transaction Code`
|
|
3. `Statement Output Pool (SOP)`
|
|
4. `Pool Definition`
|
|
5. `Pool Conversion Rate`
|
|
6. `Currency Rate`
|
|
7. `Event Maintenance`
|
|
8. `Deduction Sequences`
|
|
9. `Counter Definition`
|
|
10. `Campaign`
|
|
11. `Campaign Rule`
|
|
|
|
Ngoài nhóm CSR trên, spec còn có các endpoint hỗ trợ rất quan trọng cho Agent như `id/generate`, `id/check`, `list`, `count`, `history`, `list-by-ids`, `list-by-codes`, `list-by-pool`, `precision-by-pools`, `find-default`, `exists-default`, `verifyCriteria`, `amount-to-use-view`, `decide-tier-view`.
|
|
|
|
Vì Core API không sửa được, Loyalty Agent Service/MCP Server sẽ đóng vai trò **orchestrator + DTO builder + validator**: hướng dẫn user điền thông tin, tra cứu dữ liệu phụ thuộc, build DTO hợp lệ, validate trước, rồi mới gọi endpoint CSR tương ứng.
|
|
|
|
---
|
|
|
|
## Phase 1: Reward MCP Orchestrator
|
|
|
|
_Mục tiêu: biến Reward OpenAPI thành bộ MCP tools dùng được trong hội thoại, ưu tiên luồng tạo Campaign/Rule/Pool end-to-end._
|
|
|
|
### 1.1. Foundation Tools dùng chung
|
|
|
|
Các resource CSR có pattern giống nhau, nên cần build một lớp client/tool generator hoặc wrapper dùng chung thay vì viết thủ công từng API.
|
|
|
|
- `generate_id(resource)`: gọi `/api/{resource}/csr/id/generate`.
|
|
- `check_id(resource, id)`: gọi `/api/{resource}/csr/id/check/{id}`.
|
|
- `get_by_id(resource, id)` hoặc `get_by_record_no(resource, recordNo)`.
|
|
- `list(resource, criteria, page, size, sort)`.
|
|
- `count(resource, criteria)`.
|
|
- `create_draft(resource, dto)`.
|
|
- `edit_draft(resource, dto)`.
|
|
- `approve/reject/bulk-approve/bulk-reject` chỉ expose sau, vì đây là hành động nhạy cảm.
|
|
- `history(resource, criteria)` và `rejection_reason(recordNo)` dùng để giải thích trạng thái Maker-Checker cho user.
|
|
|
|
Nguyên tắc: trong giai đoạn đầu, Agent ưu tiên tạo draft, không tự approve.
|
|
|
|
### 1.2. DTO Builder & Validation Layer
|
|
|
|
MCP Server cần giữ local draft theo conversation/session để user có thể build DTO từng bước.
|
|
|
|
- Mỗi draft có `draftId`, `resource`, `dto`, `missingRequiredFields`, `warnings`, `lastCoreValidation`.
|
|
- Không đưa các field `readOnly` vào request: `status`, `lastUpdateBy`, `lastUpdateDate`, `lastApproveBy`, `lastApproveDate`, `lastUpdateByName`, `lastApproveByName`.
|
|
- Validate required fields theo schema trước khi gọi Core API.
|
|
- Validate enum, maxLength/minLength, date/date-time format.
|
|
- Với field `$ref: ReferenceData`, Agent phải tra cứu hoặc xác nhận object reference, không chỉ nhét string trần nếu Core client yêu cầu object.
|
|
- Với nested DTO trong `CampaignRuleDto`, build theo template theo `ruleType` thay vì hỏi tất cả field.
|
|
|
|
Required fields quan trọng theo spec:
|
|
|
|
- `Campaign`: `campaignId`, `name`.
|
|
- `CampaignRuleDto`: `campaignId`, `ruleId`, `ruleName`.
|
|
- `PoolDefinitionDto`: `poolId`, `poolName`.
|
|
- `TransactionCodeDto`: `code`, `description`.
|
|
- `TransactionCategoryDto`: `code`, `name`.
|
|
- `PoolConversionRateDto`: `code`, `description`.
|
|
- `CurrencyRateDto`: `pcrCode`, `effectiveFrom`, `effectiveTo`, `buyRate`, `sellRate`.
|
|
- `EventMaintenanceDto`: `eventId`, `description`, `occursNext`.
|
|
- `DeductionSequencesDto`: `sequenceId`, `sequenceName`, `effectiveFrom`, `effectiveTo`, `isDefault`.
|
|
- `CounterDefinitionDto`: `counterId`, `counterName`, `effectiveFrom`, `effectiveTo`, `entity`, `bucketPeriodUnit`, `whatToCount`, `resetType`, `resetValue`, `updateStateWhen`, `lateValuePosting`.
|
|
|
|
### 1.3. Dependency Graph thực tế
|
|
|
|
Không hard-code rằng Campaign Rule nối trực tiếp với Event. Trong schema hiện tại, `CampaignRuleDto` không có `eventId`; nó nối chủ yếu qua:
|
|
|
|
- `campaignId`
|
|
- `poolId` / `subPoolId`
|
|
- `campaignTcLinkages`
|
|
- `campaignCriteria`
|
|
- `campaignFormula*`
|
|
- `campaignRuleSchedule`
|
|
- `marketingRewardRequest`
|
|
- reward content theo channel `SMS`, `EMAIL`, `NOTIFY`
|
|
|
|
Dependency graph đề xuất:
|
|
|
|
1. **Reference/Lookup layer**
|
|
- `amount-to-use-view/list`
|
|
- `decide-tier-view/list`
|
|
- transaction code lookup: `/api/transaction-code/list-by-codes`
|
|
- pool lookup: `/api/pool-definition/list-by-ids`, `/api/pool-definition/precision-by-pools`
|
|
- deduction sequence default: `/api/deduction-seq/find-default`
|
|
|
|
2. **Parameter layer**
|
|
- `Transaction Category`
|
|
- `Transaction Code`
|
|
- `Pool Conversion Rate`
|
|
- `Currency Rate`
|
|
|
|
3. **Pool layer**
|
|
- `Statement Output Pool`
|
|
- `Pool Definition`
|
|
- optional `Counter Definition` nếu rule dùng cap/limit/counter formula
|
|
|
|
4. **Campaign layer**
|
|
- `Campaign`
|
|
|
|
5. **Rule layer**
|
|
- `Campaign Rule`
|
|
- validate criteria bằng `/api/campaign-rule/campaign-criteria/verify`
|
|
- kiểm tra liên kết bằng `/api/campaign-rule/list-by-pool`, `/api/campaign-rule/rule-linked-by-transaction-code`, `/api/campaign-rule/find-matching-rules`
|
|
|
|
6. **Standalone/scheduled support**
|
|
- `Event Maintenance`
|
|
- `Deduction Sequences`
|
|
|
|
### 1.4. Scope triển khai Phase 1
|
|
|
|
Không làm cả 11 resource ngang nhau ngay. Ưu tiên theo giá trị end-to-end:
|
|
|
|
**Milestone 1: Read/Lookup Tools**
|
|
|
|
- Implement tool list/search cho `Campaign`, `Campaign Rule`, `Pool Definition`, `Transaction Code`.
|
|
- Implement `generate_id` và `check_id` cho các resource chính.
|
|
- Implement helper lookup: `list-by-codes`, `list-by-ids`, `precision-by-pools`, `amount-to-use-view/list`, `decide-tier-view/list`.
|
|
- Output tool phải trả dữ liệu ngắn gọn để Agent dùng tiếp, không dump DTO lớn.
|
|
|
|
**Milestone 2: Pool Setup**
|
|
|
|
- Tool tạo draft `PoolConversionRateDto`.
|
|
- Tool tạo draft `PoolDefinitionDto`.
|
|
- Tool tạo draft `StatementOutputPoolDto` nếu workflow statement cần SOP.
|
|
- Validate expiry policy: `FD`, `NE`, `ARD`, `MF`, `QF`, `YF`, `SP`, `AOM`.
|
|
- Validate pool type: `BPT`, `CR`, `GFT`, `MI`, `LDR`.
|
|
|
|
**Milestone 3: Campaign Setup**
|
|
|
|
- Tool tạo draft `Campaign`.
|
|
- Agent tự generate/check `campaignId` nếu user chưa có mã.
|
|
- Giữ template tối thiểu: `campaignId`, `name`, `ownerName`, `description`, `campaignType`, `effectiveFrom`, `effectiveTo`.
|
|
- Không yêu cầu user nhập `numOfRule`; field này nên derive/hiển thị từ Core nếu có.
|
|
|
|
**Milestone 4: Campaign Rule Setup**
|
|
|
|
- Tool tạo draft `CampaignRuleDto`.
|
|
- Template theo `ruleType`: `AWD`, `RED`, `IRED`, `ADJ`, `CEP`, `REP`, `TEP`, `MAWD`.
|
|
- Với earning/award flow, ưu tiên support:
|
|
- `campaignId`
|
|
- `ruleId`, `ruleName`
|
|
- `poolId`
|
|
- `campaignTcLinkages`
|
|
- `campaignCriteria`
|
|
- `campaignFormulaSetting`
|
|
- một trong các `campaignFormulaOne/Two/Four/Five/Six/Eight/Ten/Eleven`
|
|
- `campaignAwardLimits` nếu có cap/counter
|
|
- Gọi `verifyCriteria` trước khi submit draft nếu user có nhập criteria expression.
|
|
|
|
**Milestone 5: Approval Visibility**
|
|
|
|
- Tool xem trạng thái draft, history, rejection reason.
|
|
- Tool giải thích record đang ở trạng thái nào và cần maker/checker làm gì tiếp theo.
|
|
- Chưa expose approve/reject mặc định; chỉ bật khi có phân quyền và xác nhận rõ.
|
|
|
|
---
|
|
|
|
## Phase 2: Memory & Conversation State
|
|
|
|
_Mục tiêu: Agent nhớ chính xác DTO đang build, các reference đã chọn, và trạng thái Maker-Checker._
|
|
|
|
- Lưu conversation memory và local draft state trong DB.
|
|
- Context locking theo draft: khi user đang build `CampaignRuleDto`, Agent không tự chuyển sang draft khác trừ khi user xác nhận.
|
|
- Cho phép nested flow có kiểm soát: nếu đang build rule nhưng thiếu pool, Agent có thể tạo sub-draft `PoolDefinitionDto`, hoàn tất xong quay lại rule.
|
|
- Lưu các reference đã tạo/chọn gần nhất: `campaignId`, `ruleId`, `poolId`, `transactionCode`, `counterId`, `pcrCode`.
|
|
- Khi user nói "dùng pool vừa tạo", Agent phải resolve từ memory thành reference rõ ràng và hỏi lại nếu có nhiều pool gần đây.
|
|
- Mỗi draft cần có audit trail: user intent, fields collected, validation result, endpoint đã gọi, response recordNo/status.
|
|
|
|
---
|
|
|
|
## Phase 3: UI/Dashboard hỗ trợ Agent
|
|
|
|
_Mục tiêu: giảm hội thoại dài bằng UI chuyên biệt cho DTO lớn._
|
|
|
|
- **Draft Inspector:** hiển thị DTO hiện tại, missing fields, warnings, Core response.
|
|
- **Dependency Viewer:** hiển thị Campaign -> Campaign Rule -> Pool -> Transaction Code/Counter/Formula.
|
|
- **Interactive Forms:** form động sinh từ schema cho các DTO lớn như `CampaignRuleDto`.
|
|
- **Criteria Builder:** UI hỗ trợ build và verify `campaignCriteria.criteria`.
|
|
- **Formula Builder:** UI chọn formula type và chỉ hiện field liên quan.
|
|
- **Maker-Checker Timeline:** show draft/history/rejection reason để user biết đang chờ bước nào.
|
|
- Dùng WebSocket hiện tại để sync draft state real-time giữa chat và UI.
|
|
|
|
---
|
|
|
|
## Phase 4: Auto-Pilot & Simulation
|
|
|
|
_Mục tiêu: từ intent tự nhiên tạo được campaign/rule/pool hoàn chỉnh nhưng vẫn kiểm soát được rủi ro._
|
|
|
|
- Intent template: "Tạo campaign nhân đôi điểm sinh nhật", "Tạo campaign hoàn tiền 5%", "Tạo rule tặng điểm theo tier".
|
|
- Agent tự lập execution plan trước khi gọi API: cần tạo/check resource nào, endpoint nào, payload summary nào.
|
|
- Auto-create draft theo thứ tự phụ thuộc, dừng lại khi thiếu field bắt buộc hoặc Core reject.
|
|
- Simulation trước approve:
|
|
- sample transaction
|
|
- matched transaction code
|
|
- pool impacted
|
|
- formula result
|
|
- cap/limit/counter impact
|
|
- Human confirmation bắt buộc trước các hành động tạo nhiều draft hoặc gửi approve/reject.
|
|
|
|
---
|
|
|
|
## Nguyên tắc triển khai
|
|
|
|
- OpenAPI spec là source of truth; không đoán DTO field ngoài schema.
|
|
- Tool output phải ngắn, có cấu trúc, dễ đưa lại vào Agent context.
|
|
- Mutating tools phải idempotent ở tầng Agent/MCP nếu có thể: có `draftId`, correlation id, request summary.
|
|
- Mọi create/edit draft đều chạy local validation trước, rồi mới gọi Core.
|
|
- Với action nhạy cảm (`approve`, `reject`, `bulk-*`, `delete`), bắt buộc xác nhận rõ từ user.
|
|
- Không để Agent tự tạo/chỉnh quá nhiều resource ngầm nếu chưa trình bày execution plan.
|
|
|
|
---
|
|
|
|
## Backlog kỹ thuật gần nhất
|
|
|
|
- [ ] Parse `reward.json` thành metadata nội bộ: resources, schemas, required fields, enums, readOnly fields, endpoints.
|
|
- [ ] Implement generic Reward API client cho CSR pattern.
|
|
- [ ] Implement MCP tools read-only cho Campaign/Rule/Pool/Transaction Code.
|
|
- [ ] Implement local draft store cho `Campaign`, `PoolDefinitionDto`, `CampaignRuleDto`.
|
|
- [ ] Implement validator dùng OpenAPI schema.
|
|
- [ ] Implement create-draft flow cho Pool Definition.
|
|
- [ ] Implement create-draft flow cho Campaign.
|
|
- [ ] Implement create-draft flow cho Campaign Rule với `verifyCriteria`.
|
|
- [ ] Add integration tests dùng mock Reward Core API.
|
|
- [ ] Add UI Draft Inspector sau khi backend flow ổn định.
|