Integration Specification: INT-003 – Matching Microservice (Rule-based + AI)¶
Phiên bản: 1.2 Ngày tạo: 2026-04-01 Cập nhật: 2026-04-02 – Xác định Matching là microservice riêng biệt tích hợp với hệ thống chính qua API Trạng thái: 📝 Draft Ready
1. Overview¶
1.1 Business Purpose¶
Matching Microservice là một dịch vụ riêng biệt (microservice), triển khai độc lập và tích hợp với hệ thống chính qua API. Đây là chức năng cốt lõi – đối chiếu các field names đã trích xuất từ CSDL đơn vị với Data Element trong khung Anchored Data.
Microservice kết hợp nhiều tầng matching theo workflow có decision tree rõ ràng:
- Rule-based matching (tầng 1): Đối chiếu chính xác và pattern-based dựa trên tên trường, kiểu dữ liệu, alias đã đăng ký.
- AI matching (tầng 2): Đối chiếu ngữ nghĩa qua LLM khi rule-based không đủ tin cậy.
- Fallback & manual review (tầng 3): Khi cả rule-based và AI đều không đạt ngưỡng, trả kết quả về hệ thống chính để Manager xử lý thủ công.
Mỗi gợi ý matching được gán confident score. Kết quả cuối cùng xây dựng nên bản đồ dữ liệu hiện trạng.
1.2 Kiến trúc tích hợp¶
┌─────────────────────────────┐ API call ┌──────────────────────────────┐
│ Hệ thống chính │ ─────────────────────→ │ Matching Microservice │
│ (Quản trị Dữ liệu) │ │ │
│ │ ←───────────────────── │ ┌────────────────────┐ │
│ - Quản lý metadata │ matching results │ │ Rule-based Engine │ │
│ - UI cho Manager │ │ └────────┬───────────┘ │
│ - Lưu kết quả matching │ │ │ decision tree │
│ - Manual review workflow │ │ ┌────────▼───────────┐ │
│ │ │ │ AI Provider Layer │ │
└─────────────────────────────┘ │ │ (OpenAI/Gemini/ │ │
│ │ Ollama) │ │
│ └────────────────────┘ │
│ - Dead letter queue │
│ - Retry logic │
└──────────────────────────────┘
1.3 Related Use Cases¶
| Use Case | Mô tả | Vai trò |
|---|---|---|
| UC-MAP-001 | Đối chiếu field với Anchored Data (matching) | Manager + Hệ thống |
| UC-MAP-002 | Rà soát kết quả matching và đề xuất chủ quản | Manager |
1.4 In Scope / Out of Scope¶
In Scope (Matching Microservice):
- Triển khai như microservice riêng biệt, expose REST API cho hệ thống chính
- Rule-based matching: exact match, pattern match, alias lookup, data type inference
- AI matching qua API dịch vụ bên thứ ba, hỗ trợ multi-model (OpenAI, Gemini, Ollama)
- Decision tree workflow xác định tầng matching nào xử lý từng field
- Gán confident score cho mỗi gợi ý matching (cả rule-based lẫn AI)
- Phân loại kết quả: Auto-match / Cần review / Không match
- Fallback: khi AI lỗi → rule-based only; khi cả hai không đạt → trả về hệ thống chính để manual review
- Retry logic và dead letter queue nội bộ microservice
In Scope (Hệ thống chính):
- Gọi API Matching Microservice khi Manager khởi động matching
- Nhận và lưu trữ kết quả matching
- UI cho Manager review, override kết quả
- Manual review workflow cho các field dưới ngưỡng
Out of Scope:
- Tự xây dựng hoặc huấn luyện AI/ML model
- Xử lý dữ liệu thực tế (chỉ xử lý metadata cấu trúc)
2. Existing System Constraints¶
2.1 Systems Involved¶
| Hệ thống | Vai trò | Loại | Ràng buộc |
|---|---|---|---|
| Hệ thống chính (Quản trị Dữ liệu) | Consumer | Monolith / Main app | Gọi API microservice, lưu kết quả, hiển thị UI cho Manager |
| Matching Microservice | Provider | Microservice riêng | Triển khai độc lập. Chứa rule-based engine + AI provider layer + decision tree |
| AI Service (OpenAI / Gemini / Ollama) | AI Provider | External API / Self-hosted | Matching Microservice gọi ra ngoài. Multi-model |
2.2 Dependency Constraints¶
- Microservice independence: Matching Microservice triển khai, scale và deploy độc lập với hệ thống chính. Giao tiếp qua REST API.
- Hệ thống chính phụ thuộc microservice: Nếu Matching Microservice không khả dụng, hệ thống chính vẫn hoạt động bình thường (quản lý metadata, tra cứu, etc.) nhưng chức năng matching tạm ngưng.
- Multi-model AI: Matching Microservice quản lý provider abstraction layer nội bộ để chuyển đổi giữa OpenAI ↔ Gemini ↔ Ollama.
- Ollama (self-hosted): Model chạy on-premise → không phụ thuộc internet nhưng cần hạ tầng GPU/CPU.
- OpenAI/Gemini (cloud): Yêu cầu kết nối internet từ on-premise → cần xem xét chính sách bảo mật mạng của Thành phố.
- Chi phí: Cloud AI services tính phí theo token – decision tree tối ưu bằng cách chỉ gọi AI cho field mà rule-based không xử lý được.
- Rule-based engine: Nằm trong microservice. Cần duy trì bộ alias/synonym registry.
3. Interaction Scenarios¶
3.1 Trigger and Preconditions¶
| Trigger | Preconditions |
|---|---|
| Manager khởi động matching cho một batch metadata đã upload | Metadata đã được parse thành công (UC-DISC-001); Anchored Data đã được thiết lập (UC-ANCHOR-001/002); Matching Microservice đang hoạt động |
3.2 Main Business Flow – Decision Tree Workflow¶
HỆ THỐNG CHÍNH MATCHING MICROSERVICE
══════════════ ════════════════════
Manager → [Chọn batch metadata]
→ [Khởi động matching]
→ [Gọi API Matching Microservice] ─────────→ [Nhận request: fields + Anchored Data]
│
┌────────▼─────────────────────────┐
│ TẦNG 1: RULE-BASED MATCHING │
│ │
│ Với mỗi field: │
│ ├── Exact match │
│ ├── Pattern match (regex) │
│ ├── Alias lookup (synonym) │
│ └── Data type inference │
│ │
│ → Gán confident score │
└────────┬─────────────────────────┘
│
┌──────▼──────┐
│ Decision │
│ Point 1 │
└──────┬──────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
Score ≥ T1 T2 ≤ Score Score < T2
(High) < T1 (Mid) (Low/None)
│ │ │
▼ ▼ ▼
SUGGESTED Chuyển sang Chuyển sang
(HIGH) TẦNG 2 TẦNG 2
│ │
┌───────┴───────────┘
│
┌────────▼─────────────────────────┐
│ TẦNG 2: AI MATCHING │
│ │
│ Gửi field + context → AI API │
│ (OpenAI / Gemini / Ollama) │
│ │
│ → Nhận gợi ý + score │
│ → Kết hợp với rule-based │
│ → Tính final confident score │
└────────┬─────────────────────────┘
│
┌──────▼──────┐
│ Decision │
│ Point 2 │
└──────┬──────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
Score ≥ T1 T2 ≤ Score Score < T2
│ < T1 │
▼ │ ▼
SUGGESTED PENDING KHÔNG MATCH
(HIGH) REVIEW (ghi nhận)
│ │
┌────────▼───────────▼──┐
│ Trả kết quả về │
│ hệ thống chính │
└──────────────────────┘
│
[Nhận kết quả matching] ←─────────────────────────────┘
→ [Lưu kết quả vào DB]
→ [Hiển thị cho Manager]
│
▼
┌─────────────────────────────────────────────────┐
│ TẦNG 3: MANUAL REVIEW (tại hệ thống chính) │
│ │
│ Manager xem xét các field PENDING REVIEW: │
│ ├── Chấp nhận gợi ý (override score) │
│ ├── Chọn DE khác từ danh sách │
│ ├── Bỏ qua (field nội bộ, không cần match) │
│ └── Đề xuất bổ sung DE mới vào Anchored Data │
└─────────────────────────────────────────────────┘
→ [Tổng hợp kết quả matching cho toàn bộ batch]
→ [Hiển thị cho Manager review tổng thể (UC-MAP-002)]
T1 = threshold cao (giai đoạn này:
suggested-high, chờ review; tương lai: có thể auto-match), T2 = threshold thấp (minimum để gợi ý). Giá trị cụ thể TBD. Xem ASM-INT-009, ASM-INT-012.
3.3 Alternative/Error Flows¶
| Scenario | Xử lý | Xảy ra tại |
|---|---|---|
| Rule-based match score cao (≥ T1) | Bỏ qua AI, đánh dấu SUGGESTED (HIGH) → tiết kiệm chi phí AI. Giai đoạn này vẫn cần Manager review (ASM-INT-012) | Microservice |
| AI service không phản hồi | Retry tối đa 3 lần với exponential backoff | Microservice |
| Sau 3 lần retry thất bại | Đưa vào dead letter queue → thử lại sau hoặc thông báo | Microservice |
| AI trả kết quả không hợp lệ | Log lỗi, bỏ qua gợi ý, đánh dấu field là pending review | Microservice |
| Toàn bộ AI service không khả dụng | Graceful degradation: rule-based matching vẫn chạy. Field không xử lý được → trả về pending review | Microservice |
| Matching Microservice không khả dụng | Hệ thống chính vẫn hoạt động bình thường. Chức năng matching tạm ngưng. Thông báo Admin | Hệ thống chính |
| Manager không đồng ý kết quả matching | Override kết quả, ghi audit log | Hệ thống chính |
⚠️ Cần phân tích sâu (ASM-INT-007): Luồng dead letter queue, retry interval, notification mechanism cần thiết kế chi tiết ở giai đoạn kỹ thuật để đảm bảo production-ready.
4. Business Data Contract¶
4.1 API Contract: Hệ thống chính → Matching Microservice¶
| Dữ liệu gửi đi | Mô tả | Bắt buộc |
|---|---|---|
| fields | Danh sách field names đã trích xuất (từ UC-DISC-001) | Có |
| source_metadata | Thông tin nguồn: tên bảng, kiểu dữ liệu, context DDL (nếu có) | Có |
| anchored_data | Danh sách Data Element chuẩn để so sánh | Có |
| organization_unit | Đơn vị sở hữu batch metadata | Có |
| config | Threshold T1/T2, AI model preference, max retries | Không (dùng default) |
| Dữ liệu nhận về | Mô tả | Bắt buộc |
|---|---|---|
| results[] | Danh sách kết quả matching cho từng field | Có |
| results[].field_name | Tên field đầu vào | Có |
| results[].matched_element | Data Element ID được gợi ý match | Có (null nếu không match) |
| results[].confident_score | Điểm tin cậy (0.0 – 1.0) | Có |
| results[].match_source | Nguồn matching: rule-based, ai, combined |
Có |
| results[].status | suggested-high, pending-review, no-match. Giai đoạn hiện tại: suggested-high thay thế auto-matched (ASM-INT-012 — không auto-accept). Tương lai khi enable auto-accept: có thể dùng auto-matched |
Có |
| results[].reasoning | Lý do gợi ý (từ AI hoặc rule matched) | Không |
| results[].alternatives | Danh sách gợi ý thay thế | Không |
| metadata.processing_time | Thời gian xử lý | Có |
| metadata.ai_model_used | Model AI đã dùng (nếu có) | Không |
4.2 API Contract: Matching Microservice → AI Provider (Internal)¶
⚠️ OPEN ITEM (ASM-INT-006): Data contract cho AI chưa được chốt. Cần phân tích sâu ở giai đoạn thiết kế kỹ thuật.
Vấn đề cần giải quyết:
| Phương án | Ưu điểm | Nhược điểm |
|---|---|---|
| Gửi từng field name riêng lẻ | Token ít, chi phí thấp, dễ parallelize | Mất ngữ cảnh → matching kém chính xác. VD: field "ten" không rõ là "tên người" hay "tên đường" |
| Gửi toàn bộ DDL context (bảng + tất cả cột + kiểu dữ liệu) | AI hiểu ngữ cảnh đầy đủ → matching chính xác hơn | Token nhiều, chi phí cao, có thể vượt context window |
| Gửi theo batch (nhóm field cùng bảng + metadata bảng) | Cân bằng context và chi phí | Cần thiết kế logic phân nhóm |
Dữ liệu có thể gửi (tùy phương án):
| Dữ liệu | Mô tả | Nhạy cảm? |
|---|---|---|
| Field names | Tên cột/trường từ CSDL đơn vị | Không – chỉ là tên metadata |
| Table names | Tên bảng | Không |
| Data types | Kiểu dữ liệu (VARCHAR, INT, DATE...) | Không |
| Anchored Data Elements | Danh sách DE chuẩn để so sánh | Không |
| Table context | Mô tả / comment của bảng (nếu có trong DDL) | Không |
| Rule-based hints | Kết quả sơ bộ từ tầng 1 (nếu gửi kèm để AI tham khảo) | Không |
Kết luận tạm thời: Chỉ gửi metadata cấu trúc, không gửi dữ liệu thực tế. Phương án cụ thể cần phân tích POC ở giai đoạn kỹ thuật.
4.3 Rule-based Matching Data (Internal)¶
| Dữ liệu | Mô tả |
|---|---|
| Alias/Synonym Registry | Bảng mapping: tên phổ biến ↔ Data Element chuẩn. VD: "CCCD" = "Số căn cước công dân" = DE001 |
| Naming patterns | Regex patterns cho các convention phổ biến. VD: *_id → khả năng cao là khóa ngoại |
| Data type rules | Quy tắc suy luận: DATE + tên chứa "ngay_sinh" → khả năng match DE "Ngày sinh" |
4.4 Inbound Data (AI Service → System)¶
| Dữ liệu | Mô tả | Bắt buộc |
|---|---|---|
| matched_element | Data Element ID được gợi ý match | Có |
| confident_score | Điểm tin cậy (0.0 – 1.0) | Có |
| reasoning | Lý do AI đưa ra gợi ý (explanation) | Không (nice-to-have cho Manager review) |
| alternatives | Danh sách gợi ý thay thế (nếu có) | Không |
4.5 Validation and Mapping Rules¶
| Rule | Mô tả |
|---|---|
| Threshold T1 (auto-match) | Confident score ≥ T1 → đánh dấu suggested-high (chờ Manager review). Giai đoạn hiện tại không auto-accept (ASM-INT-012). Tương lai có thể enable → chấp nhận tự động. Giá trị TBD |
| Threshold T2 (minimum) | Confident score ≥ T2 và < T1 → pending review. Giá trị TBD |
| Score combination | Khi cả rule-based và AI đều có kết quả, final score = weighted combination. Trọng số TBD |
| Deduplication | Nếu 1 field match với nhiều DE → hiển thị tất cả cho Manager chọn |
| No match | Field không match bất kỳ DE nào → ghi nhận, Manager quyết định bỏ qua hoặc đề xuất DE mới |
| Conflict resolution | Rule-based và AI đề xuất khác nhau → hiển thị cả hai cho Manager quyết định |
5. Operational Rules¶
5.1 SLA / Rate Limit / Cut-off¶
| Metric | Giá trị | Ghi chú |
|---|---|---|
| Rule-based response | Milliseconds | Chạy nội bộ, rất nhanh |
| AI response time | Tùy provider và model | OpenAI/Gemini: vài giây. Ollama: tùy phần cứng |
| Rate limit | Tùy provider | OpenAI: RPM/TPM limit. Ollama: không giới hạn (self-hosted) |
| Xử lý nền | Có | Matching chạy background job, không block UI |
| Cost | Chỉ tính cho AI calls | Rule-based miễn phí. Tối ưu bằng cách dùng rule-based trước |
5.2 Error Handling / Retry / Fallback¶
| Tình huống | Xử lý |
|---|---|
| Rule-based matching lỗi | Log lỗi, chuyển field sang AI matching |
| AI API timeout/error | Retry tối đa 3 lần với exponential backoff |
| Sau 3 lần AI retry thất bại | Đưa vào dead letter queue → thử lại sau hoặc thông báo Manager |
| Dead letter queue | Hệ thống thử lại sau (configurable interval) hoặc thông báo Manager xử lý thủ công |
| AI service hoàn toàn không khả dụng | Graceful degradation: Rule-based matching vẫn chạy bình thường. Field mà rule-based không xử lý được → chuyển thẳng manual review. Thông báo Admin về tình trạng AI |
| Manager override | Manager có quyền chấp nhận/từ chối/sửa bất kỳ kết quả matching nào, bất kể score |
⚠️ Cần phân tích sâu (ASM-INT-007): Luồng dead letter queue, retry interval, notification mechanism, graceful degradation UX cần thiết kế chi tiết ở giai đoạn kỹ thuật.
5.3 Audit and Monitoring Expectations¶
| Loại | Mô tả |
|---|---|
| Audit log | Ghi nhận mỗi lần matching: source (rule-based/AI/manual), request, response, thời gian, model (nếu AI), score |
| Quality tracking | Theo dõi tỉ lệ auto-match vs manual review, rule-based hit rate vs AI hit rate |
| Cost monitoring | Theo dõi chi phí AI API theo tháng/theo batch. So sánh với scenario rule-based only |
| Accuracy tracking | Theo dõi tỉ lệ Manager override (chỉ số chất lượng matching) |
6. Open Questions and Assumptions¶
| Assumption ID | Statement | Impact | Status | User Confirmation |
|---|---|---|---|---|
| ASM-INT-004 | AI matching sử dụng dịch vụ bên thứ ba qua API, hỗ trợ multi-model (OpenAI, Gemini, Ollama). Không tự xây dựng model | Medium | Confirmed by User | 2026-04-01 |
| ASM-INT-006 | Data contract Microservice → AI chưa xác định: gửi từng field hay toàn bộ DDL context. Cần POC/phân tích ở giai đoạn kỹ thuật | High | Accepted Risk (User Approved) | 2026-04-01 |
| ASM-INT-007 | Error handling: retry 3 lần → dead letter queue. Luồng chi tiết + graceful degradation cần thiết kế kỹ thuật | Medium | Accepted Risk (User Approved) | 2026-04-01 |
| ASM-INT-008 | Rule-based matching chạy trước AI trong decision tree. Field đạt score cao từ rule-based sẽ bỏ qua AI để tối ưu chi phí | Low | Confirmed by User | 2026-04-02 |
| ASM-INT-009 | Threshold T1 (auto-match) và T2 (minimum) chưa xác định giá trị cụ thể. Cần calibrate qua POC. Giai đoạn này T1 không áp dụng (không auto-accept) — chỉ cần T2 (minimum để hiển thị gợi ý) | Medium | Accepted Risk (User Approved) | 2026-04-02 |
| ASM-INT-012 | Giai đoạn hiện tại: KHÔNG auto-accept — mọi gợi ý AI phải human review, bất kể score. Tương lai có thể enable auto-accept lại — thiết kế cần giữ threshold T1 (auto-match) trong cấu hình, chỉ tắt ở giai đoạn này. Mọi quyết định ACCEPT/REJECT/MODIFY ghi vào ai_feedback_log | High | ✅ Đã chốt | 2026-04-08 |
| ASM-INT-010 | Matching được triển khai như microservice riêng biệt, giao tiếp với hệ thống chính qua REST API. Triển khai, scale và deploy độc lập | Low | Confirmed by User | 2026-04-02 |
7. Dependencies and Impact¶
- Related Roles (Role Matrix IDs): RM-002 (Manager – khởi động và review matching)
- Related Use Cases: UC-MAP-001 (matching), UC-MAP-002 (rà soát kết quả)
- Upstream: UC-DISC-001 (metadata đã parse là đầu vào)
- Downstream: UC-MAP-003 (bản đồ hiện trạng được xây dựng từ kết quả matching)
- Related Screen Flows: SCR-MAP-10 (Bản đồ hiện trạng)
- Architecture:
- Matching Microservice triển khai độc lập, expose REST API
- Hệ thống chính gọi API microservice, lưu kết quả, cung cấp UI manual review
- Design Constraints (Microservice):
- AI provider abstraction layer (multi-model support)
- Decision tree engine / workflow orchestrator
- Rule-based engine + Alias/Synonym registry
- Dead letter queue infrastructure
- On-premise ↔ Cloud connectivity (nếu dùng OpenAI/Gemini)
- Graceful degradation khi AI không khả dụng
- Design Constraints (Hệ thống chính):
- API client cho Matching Microservice
- Background job processing (gọi microservice không block UI)
- Manual review workflow + UI
- Health check / circuit breaker cho microservice dependency
Last Updated: 2026-04-02