bookmanagement

This specification is about book management APIs

Base URI

http://serverroot/api

Specification này dựng API cho một ứng dụng quản lý sách.

User cần đăng nhập mới dùng được, sau khi đăng nhập, server sinh ra 1 mã AES dùng làm token qua lại. Nên mỗi request cần có header tên là Authorization.

Implement sử dụng Nodejs, dữ liệu dạng JSON

Expected frontend: AngularJS, ReactJS

Tính năng sơ bộ:

Quản lý category - CRUD
Quản lý sách - CRUD
Quản lý nhân viên (cho admin) - CRUD
Quản lý khuyến mại (cho admin) - CRUD
Bán sách (áp dụng khuyến mại)
Thông báo khi có hàng (Khi cập nhật thông tin sách)
<Update later>

Contact:

@github: khuongdv
@facebook: khuongdv.ptit
@live: songokute
@skype: khuongdv.ptit

Cách tính khuyến mại

Đối tượng Book có thuộc tính prom_code (mã khuyến mại của sách)

Đối tượng Customer có thuộc tính prom_code (mã khuyến mại cho khách hàng đặc biệt)

Đối tượng Promotion (khuyến mại) có thuộc tính type (đại chúng hoặc cục bộ) và exclusive (gộp cùng KM khác hay không).

Prom đại chúng (type = 1) là prom được áp dụng cho toàn bộ sản phẩm, toàn bộ khách hàng (Ví dụ đồng loạt giảm 10% nhân ngày 20-11, hoặc giảm 10% cho sách dạy nấu ăn nếu có hóa đơn 400K trở lên)

Các Prom đại chúng không gộp (luôn exclusive nhau)
Prom cục bộ (type = 2): chỉ áp dụng cho 1 số cuốn sách hoặc 1 số khách hàng, coupon… Các prom cục bộ đc áp dụng đồng thời, giảm max bằng giá trị sản phẩm

Quy tắc kết hợp prom đại chúng và cục bộ

Nếu book.prom_code == “” && customer.prom_code = “”:

không có promotion đại chúng nào, thì sản phẩm bán đúng giá (price)
Có prom đại chúng thì app dụng prom đại chúng mức giảm cao nhất

Nếu có customer.prom_code hoặc book.prom_code (Nếu có cả hai thì lựa chọn KM giảm sâu hơn (gọi là selected prom) để so với prom đại chúng)

Nếu có prom đại chúng, và có exclusive = 1 (tức là không gộp) thì sử dụng KM giảm sâu hơn
Nếu có prom đại chúng và có exclusive = 2 thì gộp 2 KMai này (ý là prom đại chúng và selected prom), giảm max bằng giá trị sản phẩm
Nếu không có prom đại chúng, áp dụng luôn selected prom

APIs cho việc quản lý danh mục (CRUD)

Get all categories

GET /cate/list

Create new category

PUT /cate

Update existing category

POST /cate

Delete category

DELETE /cate

GET /cate/list

Trả về tất cả danh mục sách (để build menu, for example)

Responses

200 OK

Body

Array of Category

401 Unauthorized

PUT /cate

Tạo mới 1 category

Request body

Responses

200 OK

401 Unauthorized

POST /cate

Cập nhật category, nếu category code chưa tồn tại thì tạo mới

Request body

Responses

201 Created

401 Unauthorized

DELETE /cate

Xóa category

Request body

Responses

400 Bad Request

Body

CommonMessage

200 OK

Body

CommonMessage

401 Unauthorized

Body

CommonMessage

Danh mục sách, ví dụ sách thiếu nhi, sách văn học, sách lịch sử

Object

name

string

Example:

Sách thiếu nhi

code

string

Example:

CT_001

update_datetime

string date

lần sửa cuối cùng (nếu tạo mới thì bằng now())

status

string

1 đang hoạt động, 0 bị xóa

Example:

1

Methods: Create new category Delete category Get all categories Update existing category

Examples

{
    "name": "Sách thiếu nhi",
    "code": "CT_001",
    "update_datetime":"2016-03-22T00:02:13-08:00",
    "status": 1
}

Đối tượng chung để chứa message

Object

status

number

Example:

200

data

Object

Methods: Delete category

Examples

{
    "status": 200,
    "data": {"message":"No category found"}
}

Đối tượng sách

Object

name

string

Example:

Tôi thấy hoa vàng trên cỏ xanh

author

string

Example:

AU_001

cate

string

Example:

CT_001

thumb

string

Example:

/path/to/image.jpg

original_price

number

Example:

100

price

number

Example:

120

quantity

number

Example:

230

number_of_page

number

Example:

400

is_featured

boolean

Example:

false

code

string

Example:

B001

status

string

Trạng thái: 0 inactive, 1 hết hàng, 2 available

prom_code

string

Mã khuyến mại sách này được áp dụng

Examples

{
    "name": "Tôi thấy hoa vàng trên cỏ xanh",
    "author": "AU_001",
    "cate": "CT_001",
    "thumb": "/path/to/image.jpg",
    "original_price": 100,
    "price": 120,
    "quantity": 230,
    "number_of_page": 400,
    "is_featured": true,
    "code": "B001",
    "status":2,
    "prom_code":""
}

Nhân viên

Object

code

string

Example:

ST_001

name

string

Example:

Dao Van Khuong

birth

string

Example:

1991-03-22

gender

string

Example:

male

password

string

Example:

encoded-password

date_start

string

Example:

2016-01-12

status

string

0 nghỉ việc, 1 đang làm việc

type

string

is admin or not

Examples

{
    "code": "ST_001",
    "name": "Dao Van Khuong",
    "birth": "1991-03-22",
    "gender": "male",
    "password": "encoded-password",
    "date_start": "2016-01-12",
    "status": "1"
}

Chương trình khuyến mại (hoàn thiện dần), coupon cũng thuộc dạng này, khuyến mại cho các ngày lễ, hoặc mua nhiều tặng gì đó

Object

code

string

Example:

PRM01

name

string

Example:

Khuyến mại giáng sinh 2016

created_date

string

Example:

2016-03-22T00:02:13-08:00

effect_date

string

Example:

2016-03-22T00:02:13-08:00

end_date

string

Example:

2016-04-22T00:02:13-08:00

exclusive

string

Có gộp với khuyến mại có sẵn khác không

status

string

0 inactive, 1 active

type

string

Loại KM: có thể đại chúng, như áp dụng ngày 30-4, hoặc riêng rẽ như việc mua 2 tặng 1 1: đại chúng, 2: cục bộ

money_type

string

Dạng tính tiền, % trên giá trị (1) hay giá trị fix (2)

money_value

number

Giá trị (theo money_type) Ví dụ giá trị = 40, moeny_type = 1, thì đc giảm giá 40%

Examples

Ví dụ dưới đây là 1 Khuyến mại có code PRM01, bắt đầu có tác dụng từ 2016-03-22T00:02:13-08:00, Hết tác dụng vào 2016-04-22T00:02:13-08:00, chương trình này không áp dụng cùng với PRM02, PRM03. Giảm giá 20% trên sản phẩm được áp dụng. Nếu sản phẩm nào đó đang có khuyến mại lưu trong Book rồi thì không được áp dụng KM này nữa (exclusive =1) Nếu exclusive = 0 thì được cộng dồn khuyến mại

{
    "code": "PRM01",
    "name": "Khuyến mại giáng sinh 2016",
    "created_date": "2016-03-22T00:02:13-08:00",
    "effect_date": "2016-03-22T00:02:13-08:00",
    "end_date": "2016-04-22T00:02:13-08:00",
    "exclusive": "1",
    "status": "1",
    "type":"1",
    "money_type":"1",
    "money_value": 20
}

Khách hàng

Object

code

string

Example:

CT10

name

string

Example:

Dao Van Khuong

birth

string

Example:

1992-02-22

gender

string

Example:

male

address

string

Example:

Ha Noi

point

number

Example:

210

prom_code

string

Mã khuyến mại

type

string

Loại: G = Golden, D = Diamond, N = Normal

status

string

0 inactive, 1 active

Examples

Bạn Dao Van Khuong tích lũy đc 210 điểm mua hàng

{
    "code": "CT10",
    "name": "Dao Van Khuong",
    "birth": "1992-02-22",
    "gender": "male",
    "address": "Ha Noi",
    "point": 210,
    "prom_code": "PM01",
    "type": "G"
}

Order

Object

code

string

Example:

Ord01

staff_code

string

Example:

st01

customer_code

string

Example:

cs01

create_date

string

Example:

2016-03-20 18:02:01

status

string

Example:

1

total

number

Example:

125000

items

Array

Object

book_code

string

Example:

B001

quantity

number

Example:

4

prom_code

string

Example:

PM01

price

number

Example:

100000

Examples

Code of order: Ord01 Items sold by “st01”, customer is “cs01”, there are 6 books (4 B001 and 2 B002) and total money paid = 125k. B001 has PM01 applied (after consider both its own promotion code and global promotion code)…

{
    "code": "Ord01",
    "staff_code": "st01",
    "customer_code": "cs01",
    "create_date": "2016-03-20 18:02:01",
    "status": "1",
    "total": 125000,
    "items": [
        {
            "book_code": "B001",
            "quantity": 4,
            "prom_code": "PM01",
            "price": 100000
        },
        {
            "book_code": "B002",
            "quantity": 2,
            "prom_code": "PM06",
            "price": 25000
        }
    ]
}