@fmsim/fmsim-restful 1.0.14 → 1.0.16

package/dist-app/helps/integration/ui/scenario.md

@@ -0,0 +1,37 @@
+# Scenario
+
+In the Scenario Definition screen, you can manage scenarios to be operated by the system (create/modify/delete/test).
+
+## Properties
+
+- Name
+  - Specify the name of the scenario.
+  - The name must be unique.
+- Description
+- Schedule [schedule](./crontab-editor.md)
+- Timezone
+  - Set the base timezone for when the schedule is to be executed.
+- Required Privilege
+  - Set the required privileges to execute the scenario.
+- Activation Flag
+  - Automatically specify whether it starts when the application starts.
+- Progress (Information displayed only during monitoring)
+  - (Current step number / Total number of steps in the scenario) %
+  - Based on the main scenario, server scenarios are calculated as a single step.
+- Round (Information displayed only during monitoring)
+  - Indicates the current number of repetitions in case of a recurring scenario.
+- Message (Information displayed only during monitoring)
+  - Message related to the final state of the scenario instance.
+
+## Operations
+
+- Start Monitoring
+  - Navigate to the [Integration Monitoring](./integration-monitor.md) screen.
+- Copy Scenario
+  - Copy the selected scenario.
+- Save Scenario
+  - Save changes to the scenario.
+  - Running scenarios cannot be modified.
+- Delete Scenario
+  - Delete the selected scenario.
+  - Running scenarios cannot be deleted.

package/dist-app/helps/integration/ui/scenario.ms.md

@@ -0,0 +1,40 @@
+# Senario
+
+Dalam layar Definisi Senario, Anda dapat mengelola senario yang akan dioperasikan oleh sistem (membuat/mengubah/menghapus/menguji).
+
+## Properti
+
+- Nama
+  - Tentukan nama senario.
+  - Nama harus unik.
+- Deskripsi
+- Jadwal [schedule](./crontab-editor.md)
+- Zona Waktu
+  - Tetapkan zona waktu dasar untuk kapan jadwal akan dijalankan.
+- Hak Istimewa yang Diperlukan
+  - Tetapkan kebenaran yang diperlukan untuk menjalankan senario.
+- Flag Aktivasi
+  - Secara otomatis tentukan apakah senario tersebut akan dimulai ketika aplikasi dimulai.
+- Kemajuan (Informasi yang hanya ditampilkan selama pemantauan)
+  - (Nomor langkah saat ini / Jumlah total langkah dalam senario) %
+  - Berdasarkan senario utama, senario server dihitung sebagai satu langkah.
+- Putaran (Informasi yang hanya ditampilkan selama pemantauan)
+  - Menunjukkan jumlah putaran saat ini dalam kasus senario yang berulang.
+- Pesan (Informasi yang hanya ditampilkan selama pemantauan)
+  - Pesan terkait dengan status akhir instansi senario.
+
+## Operasi
+
+- Memulai Pemantauan
+  - Beralih ke layar [Pemantauan
+
+Integrasi](./integration-monitor.md).
+
+- Salin Senario
+  - Salin senario yang dipilih.
+- Simpan Senario
+  - Simpan perubahan pada senario.
+  - Senario yang sedang berjalan tidak dapat diubah.
+- Hapus Senario
+  - Hapus senario yang dipilih.
+  - Senario yang sedang berjalan tidak dapat dihapus.

package/dist-app/helps/integration/ui/scenario.zh.md

@@ -0,0 +1,37 @@
+# 情景
+
+在情景定义屏幕上，您可以管理系统将运行的情景（创建/修改/删除/测试）。
+
+## 属性
+
+- 名称
+  - 指定情景的名称。
+  - 名称必须是唯一的。
+- 描述
+- 计划 [schedule](./crontab-editor.md)
+- 时区
+  - 设置计划执行的基准时区。
+- 必需权限
+  - 设置执行场景所需的权限。
+- 激活标志
+  - 自动指定是否在应用程序启动时启动。
+- 进度（仅在监控期间显示的信息）
+  - （当前步骤编号 / 情景中的总步骤数）%
+  - 基于主要情景，服务器情景被计算为单个步骤。
+- 轮次（仅在监控期间显示的信息）
+  - 表示在情况下的当前重复次数。
+- 消息（仅在监控期间显示的信息）
+  - 与情景实例的最终状态相关的消息。
+
+## 操作
+
+- 启动监控
+  - 转到[集成监控](./integration-monitor.md)屏幕。
+- 复制情景
+  - 复制所选的情景。
+- 保存情景
+  - 保存情景的更改。
+  - 运行中的情景无法修改。
+- 删除情景
+  - 删除所选的情景。
+  - 运行中的情景无法删除。

package/dist-app/helps/integration/ui/state-register.ja.md

@@ -0,0 +1,29 @@
+# 状態登録簿 (StateRegister)
+
+[状態登録簿(state-register)](../concept/state-register.md)は、特定の意味を持つ状態の値を定義する画面です。
+
+- この機能は通常、[シナリオ](../concept/scenario.md)の[state-write](../task/state-write.md)、[state-read](../task/state-read.md)タスクによって使用されます。
+
+## 属性(properties)
+
+- 名前(name)
+  - 状態の名前を指定
+  - 名前はユニークである必要があります
+- 説明(description)
+- 区分(type)
+  - 任意のテキストを入力でき、各状態をユーザーが区別するための目的です
+- TTL (Time To Live)
+  - 状態値が有効な時間を秒単位で定義できます。
+  - TTL 値が 0 より大きい場合、TTL が設定されていると判断されます。
+  - 最後に設定された状態値は、TTL 時間が経過すると無効になります
+- 状態値(state)
+  - この状態が持つ現在の値を意味します。
+- 修改日時(wrote at)
+  - 状態値が最終的に修正された時間
+
+## 操作
+
+- 保存(save state-register)
+  - 状態登録の変更を保存します。
+- 削除(delete state-register)
+  - 選択された状態登録を削除します。

package/dist-app/helps/integration/ui/state-register.ko.md

@@ -0,0 +1,29 @@
+# 상태등록부 (StateRegister)
+
+[상태등록부(state-register)](../concept/state-register.md)는 특정 의미를 가지는 상태의 값을 정의하는 화면이다.
+
+- 이 기능은 보통 [시나리오](../concept/scenario.md)의 [state-write](../task/state-write.md), [state-read](../task/state-read.md) 태스크에 의해서 사용된다.
+
+## 속성(properties)
+
+- 이름(name)
+  - 상태의 이름을 지정
+  - 이름은 유니크해야함
+- 설명(description)
+- 구분(type)
+  - 임의의 텍스트를 입력할 수 있으며, 각 상태들을 사용자가 구분하고자 하는 목적이다
+- TTL (Time To Live)
+  - 상태값이 유효한 시간을 초단위로 정의할 수 있다.
+  - TTL 값이 0보다 크면, TTL이 설정된 것으로 판단한다.
+  - 마지막에 설정된 상태값이 TTL 시간이 지나면 무효화된다
+- 상태값(state)
+  - 이 상태가 가지는 현재의 값을 의미한다.
+- 수정일시(wrote at)
+  - 상태값이 수정된 최종 시간
+
+## operations
+
+- 저장(save state-register)
+  - 상태등록 수정사항을 저장한다.
+- 삭제(delete state-register)
+  - 선택된 상태등록을 삭제한다.

package/dist-app/helps/integration/ui/state-register.md

@@ -0,0 +1,29 @@
+# StateRegister
+
+[State-register(state-register)](../concept/state-register.md) is a screen that defines values for states with specific meanings.
+
+- This function is usually used by tasks in [scenario](../concept/scenario.md) such as [state-write](../task/state-write.md), [state-read](../task/state-read.md).
+
+## Properties
+
+- Name (name)
+  - Specifies the name of the state
+  - Name must be unique
+- Description (description)
+- Type (type)
+  - Arbitrary text can be entered, and it is for the purpose of users differentiating among the states
+- TTL (Time To Live)
+  - The valid time of the state value can be defined in seconds.
+  - If the TTL value is greater than 0, it is considered set.
+  - The last set state value becomes invalid after the TTL time has passed
+- State Value (state)
+  - Refers to the current value of this state.
+- Last Modified (wrote at)
+  - The last time the state value was modified
+
+## Operations
+
+- Save (save state-register)
+  - Saves changes in the state register.
+- Delete (delete state-register)
+  - Deletes the selected state register.

package/dist-app/helps/integration/ui/state-register.ms.md

@@ -0,0 +1,32 @@
+# Daftar Keadaan (StateRegister)
+
+[Daftar keadaan(state-register)](../concept/state-register.md) adalah skrin yang mentakrif nilai-nilai keadaan dengan makna tertentu.
+
+- Fungsi ini biasanya digunakan oleh tugas [senario](../concept/scenario.md) seperti [state-write](../task/state-write.md), [state-read](../task/state-read.md).
+
+## Sifat-sifat (properties)
+
+- Nama (name)
+  - Menentukan nama keadaan
+  - Nama harus unik
+- Deskripsi (description)
+- Jenis (type)
+  - Boleh memasukkan teks bebas, bertujuan untuk pengguna membezakan antara keadaan-keadaan
+- TTL (Time To Live)
+  - Boleh menentukan masa sah nilai keadaan dalam unit detik.
+  - Jika nilai TTL lebih dari 0, maka dianggap telah
+
+menetapkan TTL.
+
+- Nilai keadaan yang terakhir ditetapkan akan tidak sah setelah masa TTL berlalu
+- Nilai keadaan (state)
+  - Maksudnya nilai semasa keadaan itu.
+- Tarikh pengubahsuaian (wrote at)
+  - Masa terakhir nilai keadaan diubah
+
+## Operasi
+
+- Simpan (save state-register)
+  - Menyimpan perubahan dalam daftar keadaan.
+- Padam (delete state-register)
+  - Menghapus daftar keadaan yang dipilih.

package/dist-app/helps/integration/ui/state-register.zh.md

@@ -0,0 +1,29 @@
+# 状态登记册 (StateRegister)
+
+[状态登记册(state-register)](../concept/state-register.md)是一个定义具有特定意义状态值的界面。
+
+- 这个功能通常由[场景](../concept/scenario.md)中的[state-write](../task/state-write.md)、[state-read](../task/state-read.md)任务使用。
+
+## 属性 (properties)
+
+- 名称(name)
+  - 指定状态的名称
+  - 名称必须是唯一的
+- 描述(description)
+- 类型(type)
+  - 可以输入任意文本，用于用户区分各个状态的目的
+- TTL (Time To Live)
+  - 可以以秒为单位定义状态值的有效时间。
+  - 如果 TTL 值大于 0，则认为设置了 TTL。
+  - 最后设置的状态值在 TTL 时间过后将失效
+- 状态值(state)
+  - 指当前该状态的值。
+- 修改时间(wrote at)
+  - 状态值最后修改的时间
+
+## 操作
+
+- 保存(save state-register)
+  - 保存状态登记的修改。
+- 删除(delete state-register)
+  - 删除选定的状态登记。

package/dist-app/helps/module/api.md

@@ -0,0 +1,117 @@
+# API module
+
+외부 클라이언트에 RESTful 서비스를 제공하기위한 기본 모듈이다.
+
+- openapi V3 [Swagger](https://swagger.io/) 명세를 지원한다.
+- (서버) Graphql Resolver로 구현된 기능 중에서 외부 클라이언트를 위한 RESTful API로 노출하는 패턴을 제공한다.
+- (클라이언트) API 테스트를 위한 API Sandbox를 제공한다.
+- 각 모듈별로 제공된 API 기능은 최종 Application에 통합된다.
+
+## 모듈에서 API 기능 제공하기 (기본 구조)
+
+- API를 제공하고자하는 모듈의 package.json에서 API 모듈을 dependency에 추가한다.
+- openapi 명세
+  - 각 모듈의 root 폴더에 'openapi' 라는 폴더를 만들어서 제공한다.
+  - 각 API 버전별로 {version}.yaml 파일을 생성하고 openapi V3 명세에 맞게 API 명세를 작성한다.
+  - API 내용이 많아서 하나의 파일로 작성하기 어려운 경우 openapi/{version} 폴더를 만들고, {version}.yaml 의 일부 내용을 분리해서 폴더에 추가할 수 있다.
+  - 프레임워크는 openapi/{version}.yaml 과 openapi/{version}/\*.yaml 을 모두 합해서 해당 버전의 API 명세로 이해한다.
+  - openapi/{version}.yaml 에는 openapi 명세의 공통 정의만 가지고, openapi/{verion}/{tag}.yaml 에 명세의 각 tag에 해당하는 내용을 담는 것을 추천한다.
+- 서버
+  - server/restful 폴더를 생성
+  - server/restful/{version} 폴더를 생성. 버전은 API 버전을 의미하며, 'unstable', 'v1', 'v2' 식으로 네이밍할 수 있다.
+  - server/restful/{version} 폴더에 구현될 API는 @things-factory/api 모듈에서 정의한 restfulApiRouter에 endpoint를 추가하는 방법으로 정의한다.
+  - 'get', 'post', 'put', 'delete' 메쏘드를 각 API의 의미에 맞게 사용할 것을 권장한다. (get => retrieve, post => create, put => update, delete => delete)
+- 클라이언트
+  - 각 모듈 또는 어플리케이션의 client/api/api-sandbox-{version}.js 에 구현할 것을 권장한다.
+  - 현재는 이 페이지에 APIS 명세를 별도로 정의하고 있으나, 향후 openapi 명세를 활용하는 것으로 통합될 예정이다.
+
+## 클라이언트 사이드 기능
+
+### 클라이언트 라우팅
+
+- 클라이언트 페이지명 : 'api-swagger'
+  - 'api-swagger' 페이지로 이동하면, openapi 명세에 기반한 swagger 페이지를 볼 수 있으며, 샌드박스 테스트를 해볼 수 있다.
+
+### APIPageTemplate
+
+- API 샌드박스 구성 시에 활용.
+- APIPageTemplate
+
+```
+import { APIPageTemplate } from '@things-factory/api'
+
+const APIS = [
+  {
+    name: 'scenario',
+    path: 'scenario/:id',
+    method: 'get',
+    parameters: [],
+    description: 'get scenario information'
+  }
+]
+
+class APISandbox extends APIPageTemplate {
+  constructor() {
+    super()
+  }
+
+  get APIS() {
+    return APIS
+  }
+
+  get context() {
+    return {
+      title: 'API Sandbox',
+      apiCategory: 'Integration',
+      description: 'Scenario control, connection control, ...'
+    }
+  }
+}
+
+window.customElements.define('api-sandbox', APISandbox)
+```
+
+## 서버 사이드 기능
+
+- RESTful API router
+  - 외부 클라이언트에 RESTful 엔드포인트를 제공
+  - 내부적으로는 Graphql Resolver를 호출하여 그 결과를 외부 클라이언트에 제공하는 패턴을 권장
+  - endpoint 패턴
+    - '/api/{version}/...'
+
+```
+/* API implementation sample */
+
+import gql from 'graphql-tag'
+import { restfulApiRouter as router } from '@things-factory/api'
+
+/* restfulApiRouter의 prefix가 '/api' 이므로, 그 이후의 path를 지정 */
+router.get('/unstable/scenario/:id', async (context, next) => {
+  const { client } = context.state
+  const { id } = context.params
+
+  context.body = await client.query({
+    query: gql`
+      query($id: String!) {
+        scenario(id: $id) {
+          id
+          name
+          description
+        }
+      }
+    `,
+    variables: {
+      id
+    },
+    context
+  })
+})
+```
+
+## Swagger API Page 제공
+
+- about [Swagger](https://swagger.io/)
+- [/api-docs](/api-docs)
+  - 시스템의 대표 버전의 API 도큐먼트(Swagger) 페이지로 redirect됨
+- [/api-docs/{version}](/api-docs/{version})
+  - 시스템의 해당 버전의 API 도큐먼트(Swagger) 페이지를 제공함

package/dist-app/helps/module/notification.md

@@ -0,0 +1,161 @@
+# module - Notification
+
+- 사용자에게 알림을 전달하는 기능
+- 백그라운드 알림 (Push notification)
+  - 사용자가 어플리케이션을 사용하는 중이 아니더라도 알림을 전달
+  - 웹푸시 기능을 사용하며, Firebase Cloud Messaging (FCM)을 사용한다.
+- 클라이언트 알림 (In-app messaging)
+  - 사용자가 어플리케이션을 사용하는 중에 알림을 전달
+  - 웹푸시 기능을 사용할 수 없거나, 백그라운드 알림 기능 사용을 원하지 않을 때, 웹소켓을 사용하여 어플리케이션 사용 중에만 알림을 전달한다.
+- 오류 알림
+  - 사용자가 어플리케이션 조작 중에 발생하는 오류 등을 유지
+
+## terminology
+
+- notification
+  - 코드 상의 notification 용어는 주로 알림과 관련한 데이타 형식을 의미한다.
+- notify
+  - 사용자에게 알림을 전달하는 행위를 의미한다.
+
+## techonologies
+
+- web push notification
+- fcm
+- service worker
+
+## middlewares
+
+- notification-middleware
+  - koa-context의 state에 notify 라는 함수를 전달한다.
+  - 코드 내에서는 notify함수를 사용해서 알림을 전달할 수 있다.
+  - notify 기능의 표준화를 위해서 제공된다.
+- directive-notification
+  - resolver 수행 이후에 자동으로 해당 도메인의 사용자들에게 알림을 전달한다.
+  - TODO more descriptions about directive notification
+
+## security
+
+- 매우 강력한 보안 기준을 만족해야 pubsub 채널에 조인할 수 있다.
+- websocket은 tenancy 인증을 완료한 사용자로부터의 연결 요청만을 허가한다.
+- 해당 tenancy(domain)의 jwt-authentication을 가지고 있어야만 pubsub 그룹에 조인할 수 있다.
+
+## common elements
+
+### notification-setting-let
+
+![notification-setting-let](./notification-images/element-notification-setting-let.png)
+
+### notification-badge
+
+![notification-badge](./notification-images/element-notification-badge.png)
+
+### notification-list
+
+![notification-list](./notification-images/element-notification-list.png)
+
+## usages
+
+### configuration
+
+- config.(development|production).js
+
+```
+  notification: {
+    fcm: {
+      serviceAccount: {
+        project_id: "----",
+        private_key: "-----BEGIN PRIVATE KEY-----\nMIIEvQIB-----END PRIVATE KEY-----\n",
+        client_email: "-----"
+      },
+      appConfig: {
+        apiKey: '-----',
+        projectId: '-----',
+        messagingSenderId: '-----',
+        appId: '-----'
+      },
+      serverKey: '-----'
+    },
+    vapidKey: {
+      subject: 'mailto:abc@def.xyz',
+      publicKey: '-----',
+      privateKey: '-----'
+    }
+  }
+```
+
+- you can get serviceAccount configuration from firebase console
+
+![get service account config](./notification-images/config-service-account.png)
+
+- you can get app configuration from firebase console
+
+![get app config menu](./notification-images/config-app-1.png)
+![get app config](./notification-images/config-app-2.png)
+
+- you can get serverKey from firebase console
+
+![get server key config](./notification-images/config-server-key.png)
+
+- you can get vapidKey from firebase console
+
+![get vapidkey menu](./notification-images/config-vapidkey-1.png)
+![get vapid public key](./notification-images/config-vapidkey-2-get-public-key.png)
+![get vapid private key](./notification-images/config-vapidkey-3-get-private-key.png)
+
+## test
+
+### test on chrome dev
+
+- push test on chrome samples (outside url)
+
+```
+{
+  "notification": {
+    "title":"Congratulations on your performance",
+    "body": "Daily Acheivement",
+    "image": "https://d2mvzyuse3lwjc.cloudfront.net/doc/en/UserGuide/images/Pie_Of_Pie_Chart/Pie_Of_Pie_Chart.png?v=83478",
+    "url": "https://github.com/klaude416/wms-notebook/blob/master/step5_shipping.ipynb"
+  }
+}
+```
+
+- inside url sample
+
+```
+{
+  "notification": {
+    "title":"Congratulations on your performance",
+    "body": "Daily Acheivement",
+    "image": "https://d2mvzyuse3lwjc.cloudfront.net/doc/en/UserGuide/images/Pie_Of_Pie_Chart/Pie_Of_Pie_Chart.png?v=83478",
+    "url": "http://board.localhost:3000/system"
+  }
+}
+```
+
+- sample with actions
+
+```
+{
+  "notification": {
+    "title":"Congratulations on your performance",
+    "body": "Daily Acheivement",
+    "image": "https://d2mvzyuse3lwjc.cloudfront.net/doc/en/UserGuide/images/Pie_Of_Pie_Chart/Pie_Of_Pie_Chart.png?v=83478",
+    "url": "https://github.com/klaude416/wms-notebook/blob/master/step5_shipping.ipynb",
+    "actions": [{
+      "action": "save", "title": "save"
+    }, {
+      "action": "delete", "title": "delete"
+    }]
+  }
+}
+```
+
+![push test on chrome](./notification-images/push-test-on-chrome-1.png)
+![push test on chrome result](./notification-images/push-test-on-chrome-2.png)
+
+### test on firebase
+
+![push test on firebase](./notification-images/push-test-on-firebase-1.png)
+![push test on firebase](./notification-images/push-test-on-firebase-2.png)
+![push test on firebase](./notification-images/push-test-on-firebase-3.png)
+![push test on firebase result](./notification-images/push-test-on-firebase-4.png)