@fmsim/fmsim 0.0.50 → 0.0.51

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/help.md

@@ -0,0 +1,40 @@
+# HELP module
+
+사용자에게 어플리케이션 사용과 관련한 온라인 도움말을 제공하는 목적의 모듈이다.
+
+각 도움말 컨텐츠는 계층 구조의 topic으로 작성되며, 내용은 [Marked Documentation](https://marked.js.org/) 형식으로 작성된다.
+
+## 토픽 작성
+
+- 온라인 헬프를 제공하고자 하는 모듈에서는 각 모듈의 루트 폴더 아래에 'helps' 폴더를 생성한다.
+- 'helps' 폴더 이하의 패스이름이 도움말 'topic' 에 매핑된다. 예를 들어, '/helps/module/help.md' 파일은 topic 'module/help' 의 내용이 된다.
+- 파일 확장자 .md 는 markdown 파일임을 의미하며, 그 내용은 [Marked Documentation](https://marked.js.org/) 형식으로 작성한다.
+- 각 모듈별로 작성한 도움말들은 프레임워크에 의해서 최종 어플리케이션 레벨에서 통합된다. 그러므로 각 모듈에서 작성되는 도움말의 토픽이 중복되지 않도록 토픽 구조의 관습을 따르는 것을 권장한다.
+- 토픽 구조
+  - 'module/{module-name}'
+    - 각 모듈에 대한 설명을 제공한다. 이 토픽은 주로 things-factory 프레임워크를 이해해서 어플리케이션을 개발하고자하는 개발자를 대상으로 하는 매뉴얼에 연결될 것이다.
+  - '{module-name}/...'
+    - 각 모듈에서 제공하는 기능을 어플리케이션 사용자를 위해 작성하는 경우에는, module-name 으로 시작하는 토픽 구조에 작성한다.
+    - 각 모듈내에서는 자유로운 하위 구조로 작성한다.
+    - module-name 은 심플하지만 유일한 이름을 사용하는 것을 권장하며, 모듈 뒤의 'base', 'ui' 등의 postfix를 빼는 것을 권장한다.
+      - integration <= integration-base, integration-ui
+      - grist <= grist-ui
+      - import <= import-base, import-ui
+    - scene 모듈의 경우에는 각 scene 컴포넌트의 통합된 구성을 위해서 'scene/component/{component-name}' 과 같이 만드는 것을 관습으로 정한다.
+      - 'scene/component/connection-control'
+      - 'scene/component/simple-switch'
+- Assets
+  - 각 헬프 페이지에서 참조되는 이미지 동영상 등 asset들은 /helps/{asset-type}s/{module-name}/.. 에 두도록 한다.
+  - 이 파일들 역시 최종 어플리케이션 레벨에서 통합되므로, 다른 모듈의 파일들과 중복되지 않도록 module-name 폴더 아래에 위치하도록 한다.
+  - 예시
+    - /helps/images/integration/abc.png
+    - /helps/videos/integration/xyz.mov
+
+## 다국어 제공 (i18n)
+
+- The help(markdown) file is selected in response to the user's language information.
+- help file finding order (ie. user language is 'ko-KR' and topic is 'about/things-factory' and fallback language is 'en')
+  1. /helps/about/things-factory.ko-KR.md
+  2. /helps/about/things-factory.ko.md
+  3. /helps/about/things-factory.en.md
+  4. /helps/about/things-factory.md

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)

package/dist-app/helps/notification/noti-box.md

@@ -0,0 +1,160 @@
+# Notification
+
+Paragraphs are separated by a blank line.
+
+2nd paragraph. _Italic_, **bold**, and `monospace`. Itemized lists
+look like:
+
+- this one
+- that one
+- the other one
+
+Note that --- not considering the asterisk --- the actual text
+content starts at 4-columns in.
+
+> Block quotes are
+> written like so.
+>
+> They can span multiple paragraphs,
+> if you like.
+
+Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all
+in chapters 12--14"). Three dots ... will be converted to an ellipsis.
+Unicode is supported. ☺
+
+## An h2 header
+
+Here's a numbered list:
+
+1. first item
+2. second item
+3. third item
+
+Note again how the actual text starts at 4 columns in (4 characters
+from the left side). Here's a code sample:
+
+# Let me re-iterate ...
+
+for i in 1 .. 10 { do-something(i) }
+
+As you probably guessed, indented 4 spaces. By the way, instead of
+indenting the block, you can use delimited blocks, if you like:
+
+```
+define foobar() {
+print "Welcome to flavor country!";
+}
+```
+
+(which makes copying & pasting easier). You can optionally mark the
+delimited block for Pandoc to syntax highlight it:
+
+```python
+import time
+# Quick, count to ten!
+for i in range(10):
+# (but not *too* quick)
+time.sleep(0.5)
+print(i)
+```
+
+### An h3 header
+
+Now a nested list:
+
+1. First, get these ingredients:
+
+- carrots
+- celery
+- lentils
+
+2. Boil some water.
+
+3. Dump everything in the pot and follow
+   this algorithm:
+
+find wooden spoon
+uncover pot
+stir
+cover pot
+balance wooden spoon precariously on pot handle
+wait 10 minutes
+goto first step (or shut off burner when done)
+
+Do not bump wooden spoon or it will fall.
+
+Notice again how text always lines up on 4-space indents (including
+that last line which continues item 3 above).
+
+Here's a link to [a website](http://foo.bar), to a [local
+doc](local-doc.html), and to a [section heading in the current
+doc](#an-h2-header). Here's a footnote [^1].
+
+[^1]: Some footnote text.
+
+Tables can look like this:
+
+Name Size Material Color
+
+---
+
+All Business 9 leather brown
+Roundabout 10 hemp canvas natural
+Cinderella 11 glass transparent
+
+Table: Shoes sizes, materials, and colors.
+
+(The above is the caption for the table.) Pandoc also supports
+multi-line tables:
+
+---
+
+Keyword Text
+
+---
+
+red Sunsets, apples, and
+other red or reddish
+things.
+
+green Leaves, grass, frogs
+and other things it's
+not easy being.
+
+---
+
+A horizontal rule follows.
+
+---
+
+Here's a definition list:
+
+apples
+: Good for making applesauce.
+
+oranges
+: Citrus!
+
+tomatoes
+: There's no "e" in tomatoe.
+
+Again, text is indented 4 spaces. (Put a blank line between each
+term and its definition to spread things out more.)
+
+Here's a "line block" (note how whitespace is honored):
+
+| Line one
+| Line too
+| Line tree
+
+and images can be specified like so:
+
+![example image](example-image.jpg 'An exemplary image')
+
+Inline math equation: $\omega = d\phi / dt$. Display
+math should get its own line like so:
+
+$$I = \int \rho R^{2} dV$$
+
+And note that you can backslash-escape any punctuation characters
+which you wish to be displayed literally, ex.: \`foo\`, \*bar\*, etc.

package/dist-app/helps/notification/noti-rule.md

@@ -0,0 +1,160 @@
+# NotificationRule
+
+Paragraphs are separated by a blank line.
+
+2nd paragraph. _Italic_, **bold**, and `monospace`. Itemized lists
+look like:
+
+- this one
+- that one
+- the other one
+
+Note that --- not considering the asterisk --- the actual text
+content starts at 4-columns in.
+
+> Block quotes are
+> written like so.
+>
+> They can span multiple paragraphs,
+> if you like.
+
+Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all
+in chapters 12--14"). Three dots ... will be converted to an ellipsis.
+Unicode is supported. ☺
+
+## An h2 header
+
+Here's a numbered list:
+
+1. first item
+2. second item
+3. third item
+
+Note again how the actual text starts at 4 columns in (4 characters
+from the left side). Here's a code sample:
+
+# Let me re-iterate ...
+
+for i in 1 .. 10 { do-something(i) }
+
+As you probably guessed, indented 4 spaces. By the way, instead of
+indenting the block, you can use delimited blocks, if you like:
+
+```
+define foobar() {
+print "Welcome to flavor country!";
+}
+```
+
+(which makes copying & pasting easier). You can optionally mark the
+delimited block for Pandoc to syntax highlight it:
+
+```python
+import time
+# Quick, count to ten!
+for i in range(10):
+# (but not *too* quick)
+time.sleep(0.5)
+print(i)
+```
+
+### An h3 header
+
+Now a nested list:
+
+1. First, get these ingredients:
+
+- carrots
+- celery
+- lentils
+
+2. Boil some water.
+
+3. Dump everything in the pot and follow
+   this algorithm:
+
+find wooden spoon
+uncover pot
+stir
+cover pot
+balance wooden spoon precariously on pot handle
+wait 10 minutes
+goto first step (or shut off burner when done)
+
+Do not bump wooden spoon or it will fall.
+
+Notice again how text always lines up on 4-space indents (including
+that last line which continues item 3 above).
+
+Here's a link to [a website](http://foo.bar), to a [local
+doc](local-doc.html), and to a [section heading in the current
+doc](#an-h2-header). Here's a footnote [^1].
+
+[^1]: Some footnote text.
+
+Tables can look like this:
+
+Name Size Material Color
+
+---
+
+All Business 9 leather brown
+Roundabout 10 hemp canvas natural
+Cinderella 11 glass transparent
+
+Table: Shoes sizes, materials, and colors.
+
+(The above is the caption for the table.) Pandoc also supports
+multi-line tables:
+
+---
+
+Keyword Text
+
+---
+
+red Sunsets, apples, and
+other red or reddish
+things.
+
+green Leaves, grass, frogs
+and other things it's
+not easy being.
+
+---
+
+A horizontal rule follows.
+
+---
+
+Here's a definition list:
+
+apples
+: Good for making applesauce.
+
+oranges
+: Citrus!
+
+tomatoes
+: There's no "e" in tomatoe.
+
+Again, text is indented 4 spaces. (Put a blank line between each
+term and its definition to spread things out more.)
+
+Here's a "line block" (note how whitespace is honored):
+
+| Line one
+| Line too
+| Line tree
+
+and images can be specified like so:
+
+![example image](example-image.jpg 'An exemplary image')
+
+Inline math equation: $\omega = d\phi / dt$. Display
+math should get its own line like so:
+
+$$I = \int \rho R^{2} dV$$
+
+And note that you can backslash-escape any punctuation characters
+which you wish to be displayed literally, ex.: \`foo\`, \*bar\*, etc.