###### tags: `Spec`

# faq spec notes

## Proposal for API

**Base Path**: `/faq`

| Path | Task |
| ------------------------ | ------------------------------------ |
| `/tags` | returns all available tag names and whether priortity flag.<br><br> **Parameters:** `filter`, `offset`, `limit`, `Accept-Language`, sort is alphabetical ascending without customization.|
| `/tags/questions` | return a list of filterable questions and corresponding answers for each prioritized tag found. <br><br> **Parameters:** `filter`, `offset`, `limit`, `Accept-Language`, `sortBy` (={ *hits*, *ID default*, *updatedAt* }), `sortDir`, `search` |
| `/questions` | return a list of filterable questions and corresponding answers. <br><br> **Parameters:** `filter`, `offset`, `limit`, `Accept-Language`, `sortBy` (={ *hits*, *ID default*, *updatedAt* }), `sortDir`, `search` |
| `/questions/{id}/{var}` | post statistical values to the server.<br><br>{var} := { *hit*, *like*, *(helpful)Vote*, }<br><br>**Paramaters:** `id`, in case of user related feedback: `uuid` |

## Proposal with multiple 'primary' tags - BE voted for this

@startuml

skinparam linetype ortho
skinparam nodesep 40
skinparam ranksep 40
skinparam monochrome true
skinparam shadowing false
skinparam dpi 300

skinparam StereotypeEBackgroundColor white

entity "faq_questions" as questions {
	*id: int32 <<generated>>
	--
	question_de: varchar(512)
	question_en: varchar(512)
	answer_de: text
	answer_en: text
	hit_count: int32
	color_id: tinyint unsigned
	persistent: boolean
}

entity "faq_tags" as tags {
	*id: int32 <<generated>>
	--
	name_de: varchar(512)
	name_en: varchar(512)
	*is_priority: boolean
}

entity "faq_reactions" as reactions {
	*id: int32 <<generated>>
	--
	uuid: uuid
	faq_question_id: int unsigned
	helpful: tinyint(1)
}

entity "colors" {
	*id: tinyint unsigned <<generated>>
	--
	name: varchar(64)
}

colors ||-r-o{ questions
questions }o--o{ tags
questions ||--o{ reactions

' note right on tags::isPriority: "Hello World"

note right of questions::persistent
  This flag indicates if this
  question should be updated
  /deleted/created by the importer.
end note

note as priority_note
  This flag indicates if this
  tag is one of the "priority"-tags.
  These tags are "browsable".
end note
tags::is_priority .. priority_note

note as helpful_note
  This flag indicates if this reaction should
  be interpreted as helpful (1) or not helpful (-1).
  <i>Allowed values: -1,1</i>
  We use tinyint (not boolean) so that we
  can sum all values up to get the helpful rate.
end note
reactions::helpful .. helpful_note

@enduml

## cheatsheet

| Type | Symbol |
| ------------- | --------- |
| Zero or One | `|o--` |
| Exactly One | `||--` |
| Zero or Many | `}o--` |
| One or Many | `}|--` |
| layout | `right, left, up, down` or `r, l, u, d` |

## Proposal with single 'primary' tags

@startuml

' skinparam linetype ortho
skinparam nodesep 40
skinparam ranksep 40
skinparam monochrome true
skinparam shadowing false
skinparam dpi 300

skinparam StereotypeEBackgroundColor white

entity "faq_questions" as questions {
	*id: int32 <<generated>>
	--
	*primary_tag_id: int32 <<FK>>
	question_de: varchar(512)
	question_en: varchar(512)
	answer_de: text
	answer_en: text
	hit_count: int32
}

entity "faq_tags" as tags {
	*id: int32 <<generated>>
	--
	name_de: varchar(512)
	name_en: varchar(512)
	*can_primary: boolean
}

questions }o-right-|| tags : relation for primary tag
questions }o--o{ tags : relation for secondary tags

note "This flag indicates if this\ntag should be choosable\nas primary tag" as can_primary_note

tags::can_primary .. can_primary_note

@enduml