Git Product home page Git Product logo

api.reserve.utsa's Introduction

reserve.utsa

A platform to reserve the spaces and items managed by UTSA.

Develop documentation: Wiki

Back-end API Documentation

How to run:

back end

  1. cd backend
  2. npm install
  3. nodemon (if you don't need auto reload, you can use npm start)

fornt end

  1. cd frontend
  2. npm install
  3. npm run dev

api.reserve.utsa's People

Contributors

chun-cheng avatar jeff92316046 avatar barney9211 avatar yiyu0501 avatar dependabot[bot] avatar terchang avatar

Stargazers

avatar avatar shinn avatar avatar

api.reserve.utsa's Issues

PUT `/reserve/{reservation_id}` : 更改預約資料

輸入與輸出

  • parameters
    • reservation_id (path)
      預約紀錄 ID
      string, required
      format: Object ID /^[a-fA-F0-9]{24}$/
      example: "652038af1b2271aa002c0a09"
    • request body (body)
      更新的預約紀錄
      required
      content: application/json
      schema:
      • (Almost the same as GET /reserve)
  • response

    • status: 200 OK
      content: application/json

      example:

      {
  "title": "UTSA reservation system", 
  "hello": "world"
}

    • status: 404 Not found content: application/json

      • error_code: string, 錯誤代碼
      • message: string, 提示訊息

      example:

      {
  "error_code": "R_ID_NOT_FOUND", 
  "message": "Reservation ID not found"
}

檔案

  • /routes/reserve/put_reservation.js

資料集

  • reservations
  • item_reserved_time
  • space_reserved_time
  • items
  • spaces

GET `/space_available_time` : 查詢特定時段場地是否可預約

輸入與輸出

  • parameters
    • intervals (query)
      是否切分成各時段進行回傳
      string, optional(false by dafault)
      format: true/false
      example: false
    • space_id (query)
      場地 _id
      string, required
      format: Object ID /^[a-fA-F0-9]{24}$/
      example: "652038af1b2271aa002c0a09"
  • response

    • status: 200 OK
      content: application/json

      if intervals is false:

      • available: integer, 是否可預約, 1:可 0:不可

      example:

      {
  "available": 0
}

      if intervals is true:

      • intervals: Array, 各時段可否預約資料
        • start_datetime: string, 時段開始時間
          format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
        • end_datetime: string, 時段結束時間
          format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
        • available: integer, 是否可預約, 1:可 0:不可

        example:

        {
  "intervals": [
    {
      "start_datetime": "2024-05-02T13:00",
      "end_datetime": "2024-05-02T17:00",
      "available": 0
    },
    {
      "start_datetime": "2024-05-02T18:00",
      "end_datetime": "2024-05-02T22:00",
      "available": 1
    },
  ]
}

      • status: 404 Not found
        content: application/json

        • error_code: string, 錯誤代碼
        • message: string, 提示訊息

        example:

        {
  "error_code": "R_ID_NOT_FOUND",
  "message": "Space ID not found"
}

        • 檔案

        • /routes/reserve/get_space_available_time.js

        資料集

        • space_reserved_time
        • spaces

        備註

        合併 /routes/reserve/get_interval_space_availability.js（各時段場地能否預約）及 /routes/reserve/get_integral_space_availability.js（整體時段場地能否預約）

Item reservation check

Add a check mechanism to ensure the item reservation's quantity is not over when the item reservation is on the same date and the total is more than the quantity that can be reserved.

Front-end can reject the user's answer when ze fills in the same date and the same item.

GET `/spaces` : 取得場地搜尋清單

輸入與輸出

  • parameters
    • space_id (query)
      場地 _id
      string, optional
      format: Object ID /^[a-fA-F0-9]{24}$/
      example: "65f48bbc6f21a65d302a6149"
  • response

    • status: 200 OK
      content: application/json

      if space_id was given, it'll return an object. Otherwise, it'll return an array.

      if space_id === undefined:

      • data: Array
        • _id: string, 場地 _id
        • name: Object, 場地名稱
          • zh-tw: string, 場地中文名稱
          • en: string, space English name
        • open: integer, 是否開放預約, 1: 可預約, 0: 不可預約
        • exception_time: Array
          • ......

      if space_id !== undefined:

      • _id: string, 場地 _id
      • name: Object, 場地名稱
        • zh-tw: string, 場地中文名稱
        • en: string, space English name
      • open: integer, 是否開放預約, 1: 可預約, 0: 不可預約
      • exception_time: Array
        • ......

      example: space_id: undefined

      {
  "data": [
    {
      "_id": "65f48bbc6f21a65d302a6149",
      "name": {
        "zh-tw": "學生活動中心",
        "en": "Student Activity Center"
      },
      "open": 1,
      "exception_time": []
    },
    {
      "_id": "65f48bbc6f21a65d302a614a",
      "name": {
        "zh-tw": "勤樸樓B1小舞台",
        "en": "Cin-Pu Building B1 Stage"
      },
      "open": 1,
      "exception_time": []
    }
  ]
}

      space_id: "65f48bbc6f21a65d302a6149"

      {
  {
    "_id": "65f48bbc6f21a65d302a6149",
    "name": {
      "zh-tw": "學生活動中心",
      "en": "Student Activity Center"
    },
    "open": 1,
    "exception_time": []
  }
}

    • status: 404 Not found content: application/json

      • error_code: string, 錯誤代碼
      • message: string, 提示訊息

      example:

      {
  "error_code": "R_ID_NOT_FOUND", 
  "message": "Space ID not found"
}

檔案

  • /routes/reserve/get_spaces.js

資料集

  • spaces

POST `/reserve` : 新增預約資料

輸入與輸出

  • parameters

    • reservation (body)
      新增預約紀錄
      required
      content: application/json
      schema:

      • submit_datetime: 用戶端表單送出時間
        string, optional
        format: ISO date-time string /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d*)?\+08:?00$/
        example: "2024-04-26T14:06:23.286+0800"
      • name: 登記人姓名
        string, required
      • department_grade: 系級
        string, required
      • organization: 借用單位(社團/單位等)
        string, required
      • email: 聯絡用電子信箱
        string, required
        format: email /^[\w-.\+]+@([\w-]+\.)+[\w-]{2,4}$/
        example: "[email protected]"
      • reason: 借用原因/用途
        string, required
      • note: 備註
        string, optional
      • space_reservations: 空間預約資料
        array, required ( Union(space_reservations, item_reservations) )
        • space_id: 場地 _id
          string, required
          format: Object ID /^[a-fA-F0-9]{24}$/
          example: "65f48bbc6f21a65d302a6149"
        • start_datetime: 預約時段開始時間
          string, required
          format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
          example: "2024-04-29T13:00"
        • end_datetime: 預約時段結束時間 string, required
          format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
          example: "2024-04-29T17:00"
      • item_reservations: 場地預約資料
        array, required ( Union(space_reservations, item_reservations) )
        • item_id: 物品 _id
          string, required
          format: Object ID /^[a-fA-F0-9]{24}$/
          example: "652038af1b2271aa002c0a09"
        • item_code: 物品編號
          string, optional (required if the admin set to required)
        • start_datetime: 預約時段開始時間
          string, required
          format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
          example: "2024-04-29T13:00"
        • end_datetime: 預約時段結束時間 string, required
          format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
          example: "2024-04-29T17:00"
        • quantity: 預約物品數量
          integer, required
          example: 15

      example:

      {
  "submit_datetime": "2024-04-26T14:31:23.486+0800",
  "name": "王小名",
  "department_grade": "資科二",
  "organization": "學生會",
  "email": "[email protected]",
  "reason": "舉辦迎新大會",
  "space_reservations": [
    {
      "space_id": "65253db7053c98f0bd1593db",
      "start_datetime": "2024-01-23T18:00",
      "end_datetime": "2024-01-25T22:00"
    }
  ],
  "item_reservations": [
    {
      "item_id": "652038af1b2271aa002c0a09",
      "item_code": "ABC-123",
      "start_datetime": "2024-01-23T18:00",
      "end_datetime": "2024-01-25T22:00",
      "quantity": 15
    }
  ],
  "note": "無"
}
  • response

    • status: 200 OK
      content: application/json

      {
  "code": "R_SUCCESS", 
  "message": "Success!"
}

    • status: 404 Not Found
      content: application/json

      • error_code: string, 錯誤代碼
      • message: string, 提示訊息

      example:

      {
  "error_code": "R_ID_NOT_FOUND",
  "message": "Space ID not found"
}

檔案

  • /routes/reserve/post_reserve.js

資料集

  • reservations
  • item_reserved_time
  • space_reserved_time
  • items
  • spaces

GET `/items` : 取得物品搜尋清單

輸入與輸出

  • parameters
    • item_id (query)
      物品 _id
      string, optional
      format: Object ID /^[a-fA-F0-9]{24}$/
      example: "65f48bbc6f21a65d302a6147"
  • response

    • status: 200 OK
      content: application/json

      if item_id was given, it'll return an object. Otherwise, it'll return an array.

      if item_id === undefined:

      • data: Array
        • _id: Object ID, 物品 _id
        • name: Object, 物品名稱
          • zh-tw: string, 物品中文名稱
          • en: string, item English name
        • quantity: integer, 物品數量
        • exception_time: Array
          • ......

      if item_id !== undefined:

      • _id: Object ID, 物品 _id
      • name: Object, 物品名稱
        • zh-tw: string, 物品中文名稱
        • en: string, item English name
      • quantity: integer, 物品數量
      • exception_time: Array
        • ......

      example: item_id: undefined

      {
  "data": [
    {
      "_id": "65f48bbc6f21a65d302a6147",
      "name": {
        "zh-tw": "塑膠椅",
        "en": "Plastic Chairs"
      },
      "quantity": 30,
      "exception_time": []
    },
    {
      "_id": "65f48bbc6f21a65d302a6148",
      "name": {
        "zh-tw": "長桌",
        "en": "Tables"
      },
      "quantity": 2,
      "exception_time": []
    }
  ]
}

      item_id: "65f48bbc6f21a65d302a6147"

      {
  {
    "_id": "65f48bbc6f21a65d302a6147",
    "name": {
      "zh-tw": "塑膠椅",
      "en": "Plastic Chairs"
    },
    "quantity": 30,
    "exception_time": []
  }
}

    • status: 404 Not found content: application/json

      • error_code: string, 錯誤代碼
      • message: string, 提示訊息

      example:

      {
  "error_code": "R_ID_NOT_FOUND", 
  "message": "Item ID not found"
}

檔案

  • /routes/reserve/get_items.js

資料集

  • items

POST `/verify/{reservation_id}` : 進行預約驗證

更改預約紀錄（reservation）的 verified 欄位值。

輸入與輸出

  • parameters
    • reservation_id (path)
      預約紀錄 _id
      string, required
      format: Object ID /^[a-fA-F0-9]{24}$/
      example: "652038af1b2271aa002c0a09"
  • response

    • status: 200 OK
      content: application/json

      • code: string, 代碼
      • message: string, 提示訊息

      example:

      {
  "code": "R_SUCCESS",
  "message": "success!"
}

    • status: 404 Not found
      content: application/json

      • error_code: string, 錯誤代碼
      • message: string, 提示訊息

      example:

      {
  "error_code": "R_ID_NOT_FOUND", 
  "message": "Reservation ID not found"
}

檔案

  • /routes/reserve/post_verify.js

資料集

  • reservations

Auto generate API docs

Is your feature request related to a problem? Please describe.
有點懶得維護文件😆

Describe the solution you'd like
使用 OpenAPI 及 Swagger 自動生成 API 文件（希望達到像是 FastAPI 一樣的效果）

Describe alternatives you've considered
不能自動生成的話也還可以接受

Additional context
參考資源：https://www.npmjs.com/package/swagger-ui-express

查詢預約紀錄

檔案: /server/routes/reserve/GET_reservation.js

資料庫：

  • reservations
  • items_reserved_time
  • spaces_reserved_time

GET `/item_available_time` : 查詢特定時段物品可預約數量

輸入與輸出

  • parameters
    • intervals (query)
      是否切分成各時段進行回傳
      string, optional(false by dafault)
      format: true/false example: false
    • item_id (query)
      物品 _id
      string, required
      format: Object ID /^[a-fA-F0-9]{24}$/
      example: "652038af1b2271aa002c0a09"
  • response

    • status: 200 OK
      content: application/json

      if intervals is false:

      • available_quantity: integer, 可預約數量

      example:

      {
  "available_quantity": 5
}

      if intervals is true:

      • intervals: Array, 各時段可否預約資料
        • start_datetime: string, 時段開始時間
          format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
        • end_datetime: string, 時段結束時間
          format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
        • available_quantity: integer, 可預約數量

      example:

      {
  "intervals": [
    {
      "start_datetime": "2024-05-01T13:00",
      "end_datetime": "2024-05-02T12:00",
      "available_quantity": 20
    },
    {
      "start_datetime": "2024-05-02T13:00",
      "end_datetime": "2024-05-03T12:00",
      "available_quantity": 5
    },
  ]
}

    • status: 404 Not found content: application/json

      • error_code: string, 錯誤代碼
      • message: string, 提示訊息

      example:

      {
  "error_code": "R_ID_NOT_FOUND", 
  "message": "Item ID not found"
}

檔案

  • /routes/reserve/get_item_available_time.js

資料集

  • item_reserved_time
  • items

備註

合併 /routes/reserve/get_interval_item_availability.js（各時段物品能否預約）及 /routes/reserve/get_integral_item_availability.js（整體時段物品能否預約）

統一程式風格

  • 從 CommonJS 改用 ES6 語法
  • 使用 ESLint 統一程式撰寫風格

DELETE `/reserve/{reservation_id}` : 刪除預約資料

輸入與輸出

  • parameters
    • reservation_id (path)
      預約紀錄 ID
      string, required
      format: Object ID /^[a-fA-F0-9]{24}$/
      example: "652038af1b2271aa002c0a09"
  • response

    • status: 200 OK
      content: application/json

      If the server found the reservation data and delete it, the following content will be returned:

      {
  "code": "R_SUCCESS",
  "message": "Delete success!"
}

      If the reservation data not exist, the following content will be returned:

      {
  "code": "R_ID_NOT_FOUND",
  "message": "Reservation ID not found"
}

檔案

  • /server/routes/reserve/DELETE_reservation.js

資料庫 collection

  • reservations
  • items_reserved_time
  • spaces_reserved_time

GET `/reserve/{reservation_id}` : 取得預約資料

輸入與輸出

  • parameters
    • reservation_id (path)
      預約紀錄 ID
      string, required
      format: Object ID /^[a-fA-F0-9]{24}$/
      example: "652038af1b2271aa002c0a09"
  • response

    • status: 200 OK
      content: application/json
      schema:

      • submit_datetime: string, 用戶端表單送出時間
        format: ISO date-time string
      • server_datetime: string, 伺服器端資料建立時間
        format: ISO date-time string
      • verified: integer, 是否完成驗證，1:是 0:否
      • name: string, 登記人姓名
      • department_grade: string, 系級
      • organization: string, 借用單位(社團/單位等)
      • email: string, 聯絡用電子信箱
        format: email /^[\w-.\+]+@([\w-]+\.)+[\w-]{2,4}$/
      • reason: string, 借用原因/用途
      • note: string, 備註
      • space_reservations: array, 空間預約資料
        • space_id: string, 場地 _id
          format: Object ID /^[a-fA-F0-9]{24}$/
        • start_datetime: string, 預約時段開始時間
          format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
        • end_datetime: string, 預約時段結束時間 format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
      • item_reservations: array, 場地預約資料
        • item_id: string, 物品 _id
          format: Object ID /^[a-fA-F0-9]{24}$/
        • item_code: string, 物品編號
        • start_datetime: string, 預約時段開始時間
          format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
        • end_datetime: string, 預約時段結束時間 format: /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
        • quantity: integer, 預約物品數量

      example:

      {
  "submit_datetime": "2024-04-26T14:36:24.593+0800",
  "server_datetime": "2024-04-26T14:36:25.286Z",
  "name": "王小名",
  "department_grade": "資科二",
  "organization": "學生會",
  "email": "[email protected]",
  "reason": "舉辦迎新大會",
  "note": "無",
  "space_reservations": [
    {
      "space_id": "65253db7053c98f0bd1593db",
      "start_datetime": "2024-01-23T18:00",
      "end_datetime": "2024-01-25T22:00"
    }
  ],
  "item_reservations": [
    {
      "item_id": "652038af1b2271aa002c0a09",
      "item_code": "ABC-123",
      "start_datetime": "2024-01-23T18:00",
      "end_datetime": "2024-01-25T22:00",
      "quantity": 15
    }
  ]
}

    • status: 404 Not found
      content: application/json

      • error_code: string, 錯誤代碼
      • message: string, 提示訊息

      example:

      {
  "error_code": "R_ID_NOT_FOUND", 
  "message": "Reservation ID not found"
}

檔案

  • /routes/reserve/get_reserve.js

資料集

  • reservations

場地列表查詢

功能: 回傳場地 ID、場地列表

檔案:

  • /server/routes/reserve/GET_spaces.js

資料庫 collection:

  • spaces

Make a reserve-availability timetable

Make a page shows spaces/items availability in specific time slots.

Example:

Date 08:00~12:00 13:00~17:00 18:00~22:00
yyyy/mm/dd day Available Available
......

Additional task:

  • search specific dates or time slots: a date or an interval.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.