Tiến độ migrate
Đây là trang để kiểm tra độ phủ: với mỗi API Shukah mà app gọi trong mảng user và điểm, có route Locate nào thay thế nó không, và route đó hiện có phản hồi trên dev không?
Bấm vào một route Shukah để xem nó được đặt cạnh route Locate trên trang Shukah vs Locate. Bấm Chi tiết để mở trang endpoint đầy đủ.
Đang chuyển app sang Locate? Hãy bắt đầu từ Danh sách chuyển đổi: mọi thay đổi app phải làm, gom ở một chỗ.
Chú giải trạng thái
| Dấu | Ý nghĩa |
|---|---|
| ✅ Đã thay thế | Đã có route Locate cho API Shukah này. App có thể chuyển sang dùng nó, sau khi xử lý các điểm khác biệt ghi trên trang của nó. |
| ❌ Chưa thay thế | Chưa có route Locate. App vẫn gọi Shukah cho API này. |
| ➖ Không migrate | API này cố ý ở lại Shukah. Hiện chưa có API nào ở trạng thái này. |
| 🚩 flag | Route Locate đã có, nhưng một công tắc quyết định có dùng hay không: flag ở server, hoặc setting của app (với enableMerchantService thì route ở server đã bật, và setting của app quyết định app có gọi nó hay không). Ghi chú cho biết công tắc nằm ở đâu. |
Cột Verdict cho biết chuyển app sang route Locate cần làm gì:
| Verdict | Ý nghĩa |
|---|---|
| Drop-in | Chỉ đổi base URL và path. |
| Adapt | App phải đổi code: có ít nhất một khác biệt breaking. |
| Blocked | Route đã có nhưng app chưa dùng được (flag đang tắt hoặc token bị từ chối). Ghi chú nêu lý do. |
Trong hộp TL;DR trên mỗi trang endpoint, 🔴 breaking nghĩa là app hiện tại sẽ hỏng hoặc hiển thị sai dữ liệu nếu không đổi code, còn 🟡 to watch nghĩa là route có khác biệt nhưng app hiện tại vẫn chạy được, hoặc chỉ ảnh hưởng một trường hợp biên.
Cột Kiểm tra trên dev là một request tới route Locate trên dev, gửi không kèm token, vào ngày được
hiển thị. Nó cho biết route đã được deploy và có phản hồi hay chưa, chứ không cho biết route có chạy
đúng với một client đã đăng nhập hay không. ✅ có phản hồi nghĩa là route có đó và đã trả lời; mã HTTP
đi kèm trong ngoặc, ví dụ (401) khi route đòi token. ❌ chưa có trên dev nghĩa là 404.
⚠️ không phản hồi nghĩa là request thất bại.
Auth
12/14 đã thay thế · 2 chưa thay thế · 0 không migrate
| API Shukah | API Locate | Service | Trạng thái | Kết luận | Kiểm tra trên dev | Trang | Ghi chú |
|---|---|---|---|---|---|---|---|
GET /maeda/api/reset-otp | GET /api/v1/clients/reset-otp | auth-service | ✅ Đã thay thế | Thay thẳng | ✅ có phản hồi (400) · 2026-10-01 | Chi tiết | Một route phục vụ cả đăng nhập lẫn đăng ký, giống Shukah; trên Locate, số điện thoại chưa tồn tại nhận 400 "Last Name cannot be blank." (tín hiệu để app mở màn hình đăng ký; theo code, còn nội dung hiện tại của Shukah chưa được tài liệu hóa) và receive_offers không được đọc. |
GET /maeda/api/verify-otp | GET /api/v1/clients/verify-otp | auth-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (400) · 2026-10-01 | Chi tiết | Trả về access_token và profile trong data, trong đó token là một JWT của Locate (body thành công của Shukah có cùng shape, capture 2026-10-02), còn fcm_token và platform bị bỏ qua. |
GET /maeda/api/verify-token | GET /api/v1/clients/verify-token | auth-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
GET /maeda/client | GET /api/v1/clients | auth-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
GET /maeda/address-book | GET /api/v1/clients/address-book | auth-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | Locate trả is_default dạng boolean và id dạng chuỗi 24 ký tự hex, trong khi Shukah trả 0 hoặc 1 và id là số nguyên (lat và lng là số ở cả hai phía); phần kiểm tra mặc định của app chấp nhận boolean, nhưng mọi chỗ coi id là số đều phải sửa. |
GET /maeda/address-book/:id | GET /api/v1/clients/address-book/:id | auth-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
POST /maeda/address-book | POST /api/v1/clients/address-book | auth-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
PUT /maeda/address-book/:id | PUT /api/v1/clients/address-book/:id | auth-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | Body phẳng theo kiểu Shukah; id có thể là id 24 ký tự hex hoặc id số của Shukah. |
DELETE /maeda/address-book/:id | DELETE /api/v1/clients/address-book/:id | auth-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
PUT /maeda/client/:client_id | PUT /api/v1/clients/:client_id | auth-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
PUT /maeda/client/:client_id | PUT /api/v1/clients/setting | auth-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
POST /maeda/client/add-device-id | POST /api/v1/clients/add-device-id | auth-service | ✅ Đã thay thế | Thay thẳng | ✅ có phản hồi (200) · 2026-10-01 | Chi tiết | |
GET /maeda/client/status | — | — | ❌ Chưa thay thế | — | — | — | Không có route Locate. Snapshot của app có khai báo route này nhưng không có code nào gọi nó, vậy mà bảng traffic production ngày 2026-10-02 ghi nhận 768 lượt gọi trong 3 ngày; Shukah dev trả 404 "The route maeda/client/status could not be found." |
GET /maeda/client/delete | — | — | ❌ Chưa thay thế | — | — | — | Không có route nào của Locate xóa tài khoản, nên app vẫn gọi route Shukah này, route cần một token mà Shukah chấp nhận. App xóa token đã lưu khi gặp 401 ở đây, nên app chỉ có JWT sẽ bị đăng xuất. |
Điểm
11/16 đã thay thế · 5 chưa thay thế · 0 không migrate
| API Shukah | API Locate | Service | Trạng thái | Kết luận | Kiểm tra trên dev | Trang | Ghi chú |
|---|---|---|---|---|---|---|---|
GET /maeda/client/points | GET /api/v2/client/points | order-v2 → point-service | ✅ Đã thay thế | Thay thẳng | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
GET /maeda/point-rate | GET /api/v2/client/system_configs/point_rates | order-v2 | ✅ Đã thay thế 🚩 enableMerchantService | Thay thẳng | ✅ có phản hồi (200) · 2026-10-01 | Chi tiết | |
GET /maeda/giftcard-code/use | POST /api/v2/client/gift-card-code | order-v2 | ✅ Đã thay thế 🚩 enableMerchantService | Thay thẳng | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | Locate nhận POST với {code} thay vì GET ?code= và kiểm tra code với các gift-card code do chính Locate giữ (chưa rõ code do Shukah phát hành có tồn tại ở đó không); app đã gọi route này ở chế độ Merchant. 0 lượt gọi trong bảng traffic production ngày 2026-10-02 (3 ngày). |
GET /maeda/client/point-history | GET /api/v2/client/point-history | order-v2 → point-service | ✅ Đã thay thế | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
GET /maeda/point-offer | GET /api/v2/client/point-offers | order-v2 → point-service | ✅ Đã thay thế | Thay thẳng | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | Bộ lọc ?id= bị bỏ qua: lệnh gọi vẫn trả toàn bộ danh sách. |
GET /maeda/point-occasion | GET /api/v2/client/point-occasions | order-v2 → point-service | ✅ Đã thay thế | Thay thẳng | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
POST /maeda/point-order | POST /api/v2/client/point-orders | order-v2 → point-service | ✅ Đã thay thế 🚩 POINT_ORDER_POINT_ENABLED | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | Chỉ chấp nhận payment_type point hoặc checkout (không có payfort hay hyperpay) và trả về order có shape khác (correlation_id, money_amount, v.v.). |
POST /maeda/point-order/get-description | POST /api/v2/client/point-orders/description | order-v2 → point-service | ✅ Đã thay thế | Thay thẳng | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | |
POST /maeda/order/checkout-payment-standalone | POST /api/v2/client/point-orders/:correlation_id/pay/card | order-v2 → point-service | ✅ Đã thay thế 🚩 POINT_ORDER_CARD_ENABLED | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | Chỉ cho point order: body giống nhau (id, cvv), nhưng order được chỉ định trong path bằng correlation_id, không phải point_order_id. |
POST /maeda/order/checkout-payment-flow | POST /api/v2/client/point-orders/:correlation_id/pay/session | order-v2 → point-service | ✅ Đã thay thế 🚩 POINT_ORDER_CARD_ENABLED | Cần sửa app | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | Chỉ cho point order: body giống nhau (rememberMe); point_order_id và payment_type bị bỏ qua và order được chỉ định bằng correlation_id trong path. |
GET /maeda/points-faq | GET /api/v2/client/points-faq | order-v2 → point-service | ✅ Đã thay thế | Thay thẳng | ✅ có phản hồi (401) · 2026-10-01 | Chi tiết | Năm mục FAQ giống hệt Shukah trên dev, nhưng Locate cần token trong khi Shukah trả lời không cần token. |
GET /maeda/point-order | — | — | ❌ Chưa thay thế | — | — | — | Không có route Locate nào liệt kê các quà đã gửi của một user, nên tab Sent gifts vẫn gọi Shukah. |
POST /maeda/order/checkout-payment | — | — | ❌ Chưa thay thế | — | — | — | Với point order, Locate chỉ có route thẻ đã lưu và route session, nên route thanh toán bằng token thẻ Checkout.com không có route thay thế. 0 lượt gọi trong bảng traffic production ngày 2026-10-02 (3 ngày). |
POST /maeda/order/checkout-payment-stcpay | — | — | ❌ Chưa thay thế | — | — | — | Theo thiết kế (D24), Locate dự kiến xử lý STC Pay bên trong route pay-session chứ không dùng endpoint STC Pay riêng của order-v2; chưa được chứng minh trên thiết bị. |
POST /maeda/order/payfort-token | — | — | ❌ Chưa thay thế | — | — | — | PayFort được hoãn có chủ đích cho point order của Locate, nên đường PayFort vẫn gọi Shukah. 0 lượt gọi trong bảng traffic production ngày 2026-10-02 (3 ngày). |
POST /maeda/order/payfort-stc-pay-checkout | — | — | ❌ Chưa thay thế | — | — | — | PayFort được hoãn có chủ đích cho point order của Locate, nên đường STC Pay này vẫn gọi Shukah. 0 lượt gọi trong bảng traffic production ngày 2026-10-02 (3 ngày). |
Endpoint mới (không có endpoint tương đương trên Shukah)
Các route Locate này không có API Shukah đứng sau, nên chúng không phải là dòng trong các bảng ở trên. Đó là những khả năng mới mà app có thể dùng.
GET /api/v1/users: hồ sơ của client mà một token thuộc về.POST /api/v1/clients/exchange-token: đổi token Shukah lấy token Locate, hoặc ngược lại.GET /api/v2/client/point-offers/:id: một ưu đãi điểm.GET /api/v2/client/point-orders/:correlation_id: đọc lại một đơn mua điểm, ví dụ sau khi bị timeout.
Danh sách này đến từ đâu
Danh sách là các lời gọi Shukah tìm thấy trong một snapshot của mobile app (mobile/locate-client,
branch development) ngày 2026-02-26, đối chiếu với tài liệu và code của Locate service đọc vào
2026-10-01. Hai nguồn muộn hơn được thêm vào ngày 2026-10-02:
- Bảng traffic production ("api used last 3 days", nhận ngày 2026-10-02): các route Shukah mà
production đã phục vụ trong 3 ngày, kèm số lời gọi. Nó đã thêm
client/status(768 lời gọi) và cho thấy bốn dòng hoàn toàn không có lời gọi nào (xem bên dưới). Cột "Implemented in Laravel" của nó theo dõi bản port Laravel của chính Shukah ở cùng các URL, không phải việc chuyển sang Locate. - Capture app 2.31.5 (dev, 2026-10-02): các request body mà app 2.31.5 đã gửi tới các route
checkout-payment-flowvàcheckout-payment-stcpay.
Snapshot vẫn là nguồn duy nhất cho code của app. Bất cứ thứ gì app thêm sau 2026-02-26 mà hai nguồn trên không cho thấy đều không có trên trang này.
Không có lời gọi nào trong 3 ngày. Bảng traffic cho thấy 0 lời gọi với giftcard-code/use,
order/checkout-payment, order/payfort-token và order/payfort-stc-pay-checkout. Chúng vẫn giữ
dòng của mình, vì code của app vẫn có các lời gọi đó; ghi chú của mỗi dòng nói rõ điều này.
Team mobile: vui lòng xác nhận danh sách này với app hiện tại. Hãy cho chúng tôi biết mọi lời gọi Shukah trong mảng user hoặc điểm mà đang thiếu ở đây, và mọi dòng mà app không còn gọi nữa.
Cố ý không đưa vào, vì không thuộc migrate user hay điểm:
GET /maeda/api/settings, mà Locate phục vụ dưới dạng order-v2GET /api/v2/client/settings. Đó là cấu hình chung của app và app chỉ gọi nó ở chế độ Merchant. Nó không có dòng nào và không có dev check.- Catalog và nhà hàng:
merchant,item,category,cuisine,service,advert,popular-search,bannervàapi/restaurant-config, cùng các sub-route của chúng. - Đơn hàng, checkout và group order:
order,order/history,order/checkout, các routemake-payment-*vàconfirm-order-change,api/get-distance, các routegroup-order,order/add-push-tokenvàclient/apns/token. - Thay đổi đơn hàng:
order/calculate-delivery-fee,order/change-to-deliveryvàorder/change-to-pickup. - Đơn nhà hàng trên bốn route
order/checkout-payment*. Các dòng ở trên chỉ phủ trường hợp dùng cho đơn mua điểm. - Thẻ đã lưu:
order/payment-card(get và delete). Tài liệu của point service có nêu các route Locate cho việc này trên order-v2. - Thông báo:
notificationvànotification/status. Không tìm thấy route Locate nào cho chúng. - FAQ chung và điều khoản:
faq. Điều khoản là một trang trênlocate.sa, không phải lời gọi API. - Được khai báo trong app nhưng không bao giờ được gọi:
client/create-food-truck-user,api/point-ordervàapi/point-offer. Một ShukahGET point-order/{id}cũng có trong code của app, nhưng không màn hình nào dùng nó, nên nó không có dòng. (client/statusnằm trong danh sách này cho đến 2026-10-02. Bảng traffic cho thấy 768 lời gọi trong 3 ngày, nên giờ nó có dòng.) - Server-to-server: các route mà backend service gọi, không phải app. Số lời gọi lấy từ
bảng traffic (3 ngày).
client/add-point(30,049 lời gọi) vàclient/reduce-point(2,434). order-v2 vẫn cộng điểm qua Shukahadd-pointkhi flagusePointServicecủa nó đang tắt (xem Points wallet).GET client/{id}(21 lời gọi): hồ sơ của client.talon-one-servicegọi nó bằng API key, không phải token của client. Shukah dev trả401cho token của chính client.POST billing-info/create(14 lời gọi) vàPUT billing-info/{id}(38 lời gọi): lưu dữ liệu thanh toán, không phải dữ liệu user. Merchant sync củalocate-merchant-v2-apigửi các thay đổi billing của store sang Shukah bằngPOST billing-infovàPUT billing-info/{Shukah merchant id}. Caller nào dùng path/create: Chưa được tài liệu hóa.
Cách xác định trạng thái
- ✅ Đã thay thế nghĩa là route Locate đã được implement trên branch
developcủa service. Việc nó đã deploy lên production hay chưa là một câu hỏi riêng mà Dev check và các ghi chú flag trả lời. - ❌ Chưa thay thế nghĩa là không tìm thấy route Locate nào cho API này trên
develop. Điều này được quyết định dựa trên code. - 🚩 flag nghĩa là route đã implement nhưng bị tắt bởi một flag. Trạng thái vẫn là Đã thay thế và flag cho biết cái gì phải được bật.
- Dev check là một request duy nhất không kèm token tới route Locate trên dev. Nó được thực hiện vào 2026-10-01. Ngày cũ hơn lần thay đổi route nghĩa là kết quả kiểm tra đã lỗi thời.
Cách cập nhật trang này
Các bảng không được viết tay. Mỗi dòng là một entry trong
sites/internal/src/components/migration/registry.ts, và cùng entry đó cấp dữ liệu cho các bảng
Shukah vs Locate và hộp "Replaces" trên mọi trang endpoint.
Để đổi một dòng, sửa đúng entry đó (status, flag, dev check hoặc note), rồi chạy:
npm run test:internal && npm run build:internal
Các test kiểm tra quy tắc của registry và build kiểm tra mọi link. Đừng chạy build khi dev server đang chạy trong cùng checkout; xem README của repository. Để thêm một API Shukah, thêm một
entry và section của nó trên trang so sánh, và trỏ page tới một endpoint block có thật.
Bản dịch
Vietnamese: translated 2026-10-02 from the English pages of that date.
Arabic: translated 2026-10-02 from the English pages of that date — needs review by a native Arabic speaker before it is shared.