第三方 API 整合規格書

deploy-note.md

Deploy note

1. git clone $repository
2. yum install gcc-c++
3. npm ci
4. copy correct .env file
5. pm2 start src/index.js (change the process port and test with admin UI)
6. db schema migration: user and ecpartner
7. point web address

web address - point mapping

1. frontend UI -> DomainName:8088 -> aws:elb -> backend process

third_paryt_api_integration.md

DB schema users

• 增加一個 field -- uuid ，對應於 API 的 userId

DB schema ecpartners

• 原本的 merchantId 對應於 API 的 ecommerceId
• 增加一個 field -- allowUseEcoPackage

DB schema orders

• 原本的 uuid 對應於 API 的 orderUniqData (讓電商可以用電商的資料，識別唯一對應的 order )
• 利用原本的 orderEcoPackagesNum (當電商取消某 order 時，可以打 cancelRecylePkg ，設定為 orderEcoPackagesNum 的值為 0 )

comparison table

Table	users	ecpartner
schema	uuid	allowUseEcoPackage
required	yes
default		true

API

Name	isRecylePkgAllowed	useRecylePkg	cancelRecylePkg
read or write	Read API	Write API	Write API
input arg	ecommerceId, userId	ecommerceId, userId, orderUniqData	ecommerceId, userId, orderUniqData
return value	true/false or not allowed reasons	used or not allowed to use	cancel successfully

API 使用情境：

• isRecylePkgAllowed
  1. 根據電商的狀態來判斷，若該電商已被標記為 invalid，則不可借。
  2. 根據使用者的狀態來判斷，若該使用者已被標記為 invalid，則不可借。
  3. 該使用者是否已經借用了三個 package ？若否，可以借。 (skip implementation)
  4. 該電商是否還可能有足夠的 package ？比方說，電商那邊總共有 100 個，但是，已經借出 100 個 package 。那電商的狀態應該已經是 invalid 的狀態。 (skip implementation)
• useRecyclePkg
  1. 有可能明明該使用者不被允許使用，循環包裝，電商還是硬是要打這個 API ，就要傳回 not allowed to use
  2. 有可能電商對同一筆訂單 (一樣的 orderUniqData) ，重複打這個 API ，就要一直傳回 used
• cancelRecylePkg
  • 使用者之後可能會要退貨，所以要可以打這個 API 來「歸還」包裝。

todo.md

Plan

• 設法完成用來串接的 API

  1. add db testing data into development env
  2. add new db schema
  3. finish controller.js
  4. add API input validator
  5. add API tracker design (design for debugging)
  6. Move production db data into testing db server
  7. DB schema migration in testing server
  8. test with API - 特別考慮 idempotence 的問題。
  9. test with admin UI - 特別是與 schema migration 相關的 part
  10. DB schema migration in production server + deployment

• 設法處理 stage 2 的 auth-key exchange

  1. login
  2. UI

• UserTracker

  • 增加一個 API 來做 cronjob ，定期清理掉 usertracker

• 歸還包裝時的 operation

  • 核對包裝編號，將對應的 order 標記為「已歸還」

• 修正 frontend 部分寫死的 master key

work_log.md

• 9/21:
  • 設定好 AWS 上 automatic database backup 設置
• 10/21:
  • Setup development environment. (mongodb)
  • Write down spec.
• 10/23:
  • handle backend process halt problem. (daily maintenance services)
  • 查 order vs ec-partner-order 的差異。(study original design)
• 10/26
  • backup all the documentation in pp+ (daily maintenance services)
  • 研究 index.js controller.js 的寫法 (study original implementation)
• 10/28
  • add a minimalist API skeleton into thirdparty
  • import testing data successfully
• 10/30
  • add db schema
• 11/2
  • finish controller.js
• 11/4
  • 處理 return collection 刪除的問題。(daily maintenance services)
  • 看懂 populate 語法。(study original implementation)
• 11/6
  • 與 COO 開會。
• 11/9
  • add API input validator
  • Move production db data into testing db server
• 11/11
  • drop usertrackers
  • 用簡易的 db shell command 生成 UUID string 來做 db schema migration
• 11/13
  • 與 COO 開會。
• 11/16
  • test with API
• 11/18
  • 詢問 Eric deployment 的問題與細節
• 11/20
  • 研究 Moogoose 的 pre save middleware https://stackoverflow.com/questions/22903314/define-a-function-as-a-default-in-a-field-in-mongoose
• 11/23
  • 測試時，發現 frontend 有一個地方，直接寫死 master key 。考慮把這個地方改成依賴於 config file & environment variables
• 11/25 11/27
  • 測試、準備 deploy 、merge commit、處理 App 的一些小狀況。
• 12/1
  • 增加 DB-URL 的 dependency injection
  • deploy 失敗，待研究之。
• 12/4
  • 開會 - 討論 SBIR 相關問題
• 12/7
  • 根據明錩的 API ，重新討論串接
• 12/9
  • 重新撰寫文件 / 畫 sequence graph

Debugging 常用的 mongo db query --- 看最後一筆的 API result

db.usertrackers.find().sort({createdAt: -1}).limit(1).pretty()