eztable/kernel repository overview

⁠Overview

The Kernel project contains smerveral parts:

Core business logics and programming libraries. API implementation for api.eztable.com. Static data accross projects, including Thrift IDL, locale files, common template, and configurations. Common tools, including cli executables and PHPDoctor. Third-party libaries, no matter its by Composer or not.

⁠API Development

⁠Setup Environment

1. fork & clone this repo

2. Copy api/config/Config.inc.sample.php as api/config/Config.inc.php

3. Copy config/aws-config.sample.php as config/aws-config.php

4. modify dev.env for MySQL setting

MYSQL_SERVICE_HOST=Your MySQL host
MYSQL_USER=Your MySQL user id
MYSQL_PASSWORD=Your MySQL password

1. Run bin/dev-up.sh

2. Run docker exec -it kernel bash. enter docker container

3. in docker container composer install & update

4. go to http://{Your Docker IP}:31080/v3/app/shop/channels. You should see a channel list in JSON.

⁠Core Business Logics and Programming Libraries

We should follow PSR to use kernel libraries. The libraries are under class/EZTABLE/Kernel with the following sub-folders:

⁠Accounting

It contains only a SQLClient class, mostly used by Cron when you want to import/export data from our accouting system.

⁠AJAX

In some rare cases, we have to call API to the same host of the application. Which means we cannot call api.eztable.com. So we put general ajax implementation here. However, all classes here are deprecated. We should always try to call api.eztable.com.

⁠API

All version 2 API implementation is in this folder. We use reflection to map class and method to url.

The Utils folder contains helper classes to deal with access_token. Please do not use the RowAttacher class since its buggy and has performance issues. Implement your own attachment logic if you need to return additional data from an API.

Actually the version 2 API is also deprecated. People should use the RESTful version 3.

⁠API/REST

Version 3 API with RESTful design. API are organized as resources and mapped to an URL by the routing configuration. People can use RESTRouter class to implement their own API, even not hosted at api.eztable.com. This allow more freedom to other projects.

The API/ArgReader folder contains serveral classes to help people read arguments from an array.

⁠Application

Basically EZApp. We were trying to put everything like locales, login sessions, global variables into a single Facade object. However, it is proven that its very hard to maintain. As a result, we split these features as different objects. The only function for EZApp is being a container for global variables like $_SESSION, $_COOKIE, ...etc.

⁠Auth

• Account: Admin, Manager, and Member.
• Permissions.
• Third-party logins: Facebook, Google, and Yahoo.
• Facebook utilities.
• Third-party partners.

⁠Cache

Caching utilties.

⁠Composer

Classes required by Composer.

⁠Controller

General controllers. Product team should use those general controllers in their controller to make consistent application behavior.

⁠DAO

Database access layer.

⁠Debug

Utilities for debugging.

⁠Exception

Utilities for handling exceptions.

⁠External

Helpers for external system components:

• AWS.
• Solr.
• Soap services.
• Google API.
• Image Service.
• Redis.

⁠Helper

Helpers for 3rd-party libries:

• Google analytics.
• Markdown.
• Mustache.
• Smarty.

⁠Locale

i18n and runtime locale management.

⁠Log

Everything about logging.

⁠Mail

Email and SMS.

⁠Member

General membership function.

⁠Message

Messaging. Basically should connect to Message Service.

⁠Mining

Actually this should be in Cron.

⁠Model

Deprecated, should be replaced by Controller.

⁠Payment

Payment. Basically should connect to Payment Service.

⁠Plugin

Deprecated. Was for blog plugin, but the project was cut.

⁠Points

Everything about membership point. Should be completely redesign along with Point Service.

⁠Production

EZTABLE Production, an article collection.

⁠Questionnaire

Questionnaires.

⁠Queue

Queue job implementation with php-resque. There is a scheduler using Redis for queue job scheduling.

⁠Recommendation

Restaurant recommendation engine, linked with a node.js service implemented by the data science team.

⁠Report

All about reporting.

⁠Reservation

All about reservation. The quota folder contains logics for booking quotas.

⁠Resource

Resource implementation similar to Doctrine, but without entity manager. We cannot use doctrine because the database schema design. Every new feature should be designed as a resource so people do not need to implement complex login with raw daos.

⁠Restaurant

All about restaurant

⁠Routing

Generate site urls using the routing class.

⁠Service

Clients for internal services. Mostly implemented with Thrift. The Image Service should be move to another independent repository and as a Thrift service.

⁠Share

All about shop. The quota folder contains logics for product quotas.

TODO: the product tables should be merged into one table. So do the quota tables.

⁠Site

Deprecated, site configurations.

⁠Statistics

All about reporting. Should be merged with Report.

⁠TableManagement

Table management.

⁠Test

Test utilities and base class for testcases.

⁠Thrift

All about Thrift.

⁠Timeline

User timeline. Timeline tables are sharded.

⁠Utils

Common programming libries. Like Apache Commons for JAVA.

⁠View

Common views for front-end.

⁠Business Logic

⁠Shop

⁠Order state

The state of newly created order is new. If the payment not done in 20 minutes, the state would convert to canceled. The third state is paid which means the user paid the order. Also, the state would not change anymore. If the order refunded, we would create return order in a different table.

⁠Overview

訂單儲存於 union_purchase ，訂單內容可能如下：

• PREPAY_1 餐券 * 3
• COUPON_1 老爺餐券 * 2

這些資訊存在 order_item。

如果訂單內容有電子餐券，則會在 value_card 多儲存一份電子資訊， 包含用了幾份，有幾張餐券等資訊。以下用一筆訂單來說明資料結構：

假設我們有一筆訂單編號 123

是 Andy 買了以下產品

product id | quantity

• COUPON_1 | 1
• PREPAY_123 | 3

在 union_purchase 會有一筆訂單 row :

id  | name | tel
123 | andy | 0917436767

在 order_item 會有兩筆 row

id | purchase id | type   | product_id | quantity
1  | 123         | COUPON | 1          | 1
2  | 123         | PREPAY | 123        | 3

因為只有一張電子餐券，所以 value_card 只有一個 row

id code         purchase-id  
1  dsfkljdslfk  123         

這張電子餐券可以使用 PREPAY_123 產品 3 次，在 value_card_item 會有這樣一個 row

id | product_id | quantity | used_quantity | return_quantity
1  | 123        | 3        | 1             | 0

prepay_transaction 記錄了每一筆電子餐券的 life cycle 。

餐券的使用有三種方式，

type     | term    | table
直接使用 | consume | prepay_consumed_items
綁定定位 | attach  | prepay_reservation_item

⁠Life cycle of Value Card

Purchase -> Publish -> Consume/Attach -> Confirm -> Balance

一筆擁有電子餐券的訂單產生後，會跟著產生(publish)電子餐卷的資料，publish 會隨機產生序號(value_card)和可使用的產品(value_card_item)建立，接著對這筆 value_card 做履約保證(guarantee)，此電子餐券才真正可以使用。

消費者拿到序號後，有兩種用法

• 綁定位(attach): 消費者透過 EZTABLE 網站將餐卷綁在一筆定位(prepay_reservation_items)上
• 餐廳端直接使用(confirm): 餐廳端透過 pcConsole 直接調整使用數量(prepay_consumed_item)

餐廳每個月會跟 EZTABLE 結賬請款這個月已使用的電子餐券，已經結賬撥款過的會標上(is_balanced)

⁠A -> B (定位綁餐券)

餐券綁在定位上，主要先檢查定位的時間點，該餐廳的該餐券是否能使用。如果能使用，這筆餐券就能夠綁上去。請參考 method ValueCard->attachItems 。

⁠履約保證

目前履約保證有跟華泰與歐付寶Allpay合作，

⁠華泰

使用報表的方式，每天詳細記錄總履約保證金額，並產生日報表與月報表

⁠Allpay

對方有提供API，在餐券 publish 同時會呼叫對方 API 產生履約保證。 由於對方要求序號必須由他們產生，所以由 Allpay 履保過的電子餐券， 序號會是 16 碼，其他履約保證是我們產生序號長度是 20 。

⁠API Implementation

The api folder.

No matter version 2 or version 3 API, they use a router file along with .htaccess file to map urls to class methods.

Callbacks, other special implementations, and public static files are in their own folders.

⁠Static Data

In the data folder, there are:

• Routing configuration for all projects.
• Common template files.
• iodocs documentation for API v3.

⁠Common Tools

We currently use PHPDoctor to generate documentation. However, APIGen seems like a better choice.

There are useful command line tools in the bin folder, including Thrift code generation and Composer scripts for local development.

⁠Third-party Libaries

If possible, use Composer. Otherwise, put it in the lib folder and load it using a helper class.

⁠Testing

We currently run unit-test on Travis.

Instruments that run unit-test in local enviroment:

$ cd ~/workspace/dev

$ vagrant up 

$ vagrant ssh

$ cd /workspace/kernel

# execute the command below only when the first time unit-test
$ mysql -u root -p < bin/createUnitTestDB.sql

$ ./vendor/bin/phpunit test

⁠Docker

⁠production

docker run -d --env-file=./production.env --net=host kernel

⁠develop

docker run -d --net=host --env-file=./dev.env -v $(pwd):/var/www/eztable/kernel kernel