bookmanagement

This specification is about book management APIs

Base URI

http://serverroot/api
Headers
Authorization
string required

Token xác nhận danh tính

Example:
Chuỗi mã hexa, kết quả của mã hóa bằng thuật toán AES
Documentation
README

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ộ:

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


Contact:

  • @github: khuongdv
  • @facebook: khuongdv.ptit
  • @live: songokute
  • @skype: khuongdv.ptit
Khuyến mại

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).

  1. 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)

  2. 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 = "":

  1. không có promotion đại chúng nào, thì sản phẩm bán đúng giá (price)
  2. 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)

  1. 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
  2. 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
  3. Nếu không có prom đại chúng, áp dụng luôn selected prom
API Methods
Quản lý danh mục

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

GET /cate/list
DELETE /cate
Get all categories
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
Create new category
PUT /cate

Tạo mới 1 category

Request body

Responses

200 OK
401 Unauthorized
Update existing category
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 category
DELETE /cate

Xóa category

Request body

Responses

400 Bad Request
200 OK
401 Unauthorized
Data Reference
Category

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

Examples

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

Đố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"}
}
Book

Đố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":""
}
Staff

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"
}
Promotion

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
}
Customer

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

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
        }
    ]
}