b24014/Q-A_test
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit
CI / typecheck (push) Successful in 1m8s
Details
CI / format (push) Failing after 1m6s
Details
CI / lint (push) Failing after 49s
Details
CI / test (push) Failing after 1m8s
Details

Browse Source
This commit is contained in:
SDI
2026-07-15 18:05:12 +09:00
commit 12e4f17b62
4633 changed files with 817125 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/i18n/en/docusaurus-plugin-content-docs/current.json
+27
View File
@@ -0,0 +1,27 @@
{
"version.label": {
"message": "Next",
"description": "The label for version current"
},
"sidebar.docs.category.소개": {
"message": "Introduction",
"description": "The label for category Introduction in sidebar docs"
},
"sidebar.docs.category.사용자 가이드": {
"message": "User Guide",
"description": "The label for category User Guide in sidebar docs"
},
"sidebar.docs.category.설정": {
"message": "Settings",
"description": "The label for category Settings in sidebar docs"
},
"sidebar.docs.category.개발자 가이드": {
"message": "Developer Guide",
"description": "The label for category Developer Guide in sidebar docs"
},
"sidebar.docs.category.설치": {
"message": "Installation",
"description": "The label for category Installation in sidebar docs"
}
}
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/00-introduction/00-index.md
+40
View File
@@ -0,0 +1,40 @@
---
sidebar_position: 1
slug: /
---
# Welcome
Welcome! This documentation provides a comprehensive guide to ABC User Feedback.
![ABC User Feedback](/assets/cover.png)
## What is ABC User Feedback?
ABC User Feedback is a standalone web application designed to efficiently collect, classify, and manage Voice of Customer (VoC) feedback. It provides various features including a feedback tagging system, kanban mode, issue tracker, SSO authentication, and more. It is currently being used in a service with 10 million MAU.
<p align="center">
<video src="https://github.com/user-attachments/assets/a2ef7a1a-41ec-4cec-b7d1-bda5fbd7d48b" width="100%" />
</p>
## Key Features
- **Feedback Tagging System**: Classify and manage feedback by topic
- **Kanban Mode**: Efficiently visualize and manage issue groups
- **Issue Tracker Integration**: Track issues with status indicators and integrate with external systems
- **Single Sign-On (SSO)**: OAuth authentication supporting enterprise-grade authentication requirements
- **Role-Based Access Control (RBAC)**: Granular user permission management
- **Dashboard**: Visualize statistical data for feedback and issues
## Getting Started
- [Installation Guide](/en/developer-guide/installation/docker-hub-images) - Installation methods using Docker, CLI tools, or manual setup
- [Tutorial](/en/user-guide/getting-started) - Basic usage guide
## Get Support
Have questions or need help? Check out these resources:
- [GitHub Issues](https://github.com/line/abc-user-feedback/issues) - Bug reports and feature requests
- [GitHub Discussions](https://github.com/line/abc-user-feedback/discussions) - Community discussions
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/00-introduction/01-project-overview.md
+75
View File
@@ -0,0 +1,75 @@
---
sidebar_position: 1
title: "Project Overview"
description: "Introducing the project overview."
---
# Project Overview
## What is ABC User Feedback?
ABC User Feedback is a standalone web application designed to efficiently collect, classify, and manage Voice of Customer (VoC). This open-source solution focuses on systematically managing user feedback to derive insights needed for product and service improvements.
Currently, this application is being used in a service with 10 million Monthly Active Users (MAU), demonstrating proven stability for large-scale feedback processing.
## Core Value Proposition
ABC User Feedback provides the following core values:
1. **Centralized Feedback Management**: Manage user feedback collected from various channels in one place
2. **Structured Analysis**: Classify feedback and identify trends through the issue system
3. **Issue Tracking**: Convert problems found in feedback into issues and track them
4. **Data-Driven Decision Making**: Visualize feedback data and derive insights through dashboards
## Technology Stack
ABC User Feedback is built on modern web technologies:
- **Frontend**: [Next.js](https://nextjs.org/) - React-based frontend framework
- **Backend**: [NestJS](https://nestjs.com/) - Scalable backend framework based on TypeScript
- **Database**: [MySQL v8](https://www.mysql.com/) - Reliable relational database
- **Search Engine**: [OpenSearch v2.16](https://opensearch.org/) (Optional) - High-performance search functionality for large amounts of feedback data
## Architecture Overview
ABC User Feedback consists of the following main components:
1. **Web Admin Interface**: Next.js-based web application providing user interfaces for feedback management, issue tracking, dashboards, etc.
2. **API Server**: NestJS-based backend server handling data processing, business logic, authentication, etc.
3. **Database**: MySQL database storing feedback, issues, user information, etc.
4. **Search Engine**: OpenSearch (optional) providing high-performance search for large amounts of feedback data
5. **SMTP Server**: Component responsible for sending emails required for user authentication processes such as email verification during account creation and password reset
These components are containerized through Docker, making them easy to deploy and scale.
## Main Use Cases
ABC User Feedback is particularly useful in the following situations:
1. **Product Improvement Process**: Collect and analyze user feedback to set product improvement directions
2. **Customer Support**: Efficiently track and manage user inquiries and issues
3. **User Experience Optimization**: Improve UX/UI based on user opinions
4. **Quality Management**: Systematically manage bug reports and feature requests
5. **Data-Driven Decision Making**: Support strategic decision-making using user feedback statistics
## Differentiators
ABC User Feedback differentiates itself from other feedback management tools with the following features:
1. **Fully Open Source**: Unlike commercial solutions, it's completely free to use and customizable
2. **Enterprise-Grade Features**: Provides features needed for enterprise environments such as SSO authentication and RBAC
3. **Scalability**: Proven performance in large-scale user base (10 million MAU)
4. **Easy Integration**: Easy integration with existing systems through RESTful API and webhooks
5. **Containerization**: Easy deployment and scaling with Docker support
## Next Steps
To get started with ABC User Feedback, refer to the following documents:
- [Key Features](./02-key-features.md) - Detailed feature descriptions
- [Installation Guide](/en/developer-guide/installation/docker-hub-images) - Installation methods
---
This document provides a basic overview of ABC User Feedback. For more detailed information, refer to the documents in the relevant sections.
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/00-introduction/02-key-features.md
+173
View File
@@ -0,0 +1,173 @@
---
sidebar_position: 3
title: 'Key Features'
description: 'Introducing key features.'
---
# Key Features
ABC User Feedback provides various features to effectively collect, manage, and analyze user feedback. This document describes the core features in detail.
## Feedback Tagging System
![Feedback Tag](/assets/01-feedback-tag.png)
The feedback tagging system is a core feature for systematically classifying and managing large amounts of user feedback.
### Key Features
- **Multiple Issue Assignment**: Assign multiple issues to each feedback for multidimensional classification
- **Custom Issue Creation**: Create and manage customized issues tailored to project characteristics
- **Issue-Based Filtering**: Filter feedback by issue to focus on specific topics
- **Issue Statistics**: Derive insights through analysis of issue usage frequency and trends
### How to Use
1. Create issue categories and issues in the admin panel
2. Assign relevant issues to received feedback
3. Filter and analyze feedback by issue
4. Identify key issues and trends through issue usage patterns
## Kanban Mode
![Issue Kanban](/assets/02-Issue-Kanban.png)
Kanban mode is a feature for visually managing issue groups and optimizing workflows.
### Key Features
- **Intuitive Drag and Drop**: Simple interface for changing issue status
- **Status-Based Column Configuration**: Column separation based on issue progress status (e.g., To Do, In Progress, Done)
- **Workflow Visualization**: Understand team work processes and progress at a glance
- **Workload Management**: Monitor workload through the number of issues in each status
- **Filter and Sort**: Filter and sort issues in the kanban board by various criteria
### How to Use
1. Select kanban mode view
2. Check and manage issues by status
3. Change issue status with drag and drop
4. Optimize team workflows and identify bottlenecks
## Issue Tracker Integration
![Issue Tracker](/assets/03-issue-tracker.png)
Issue tracker integration is a feature for systematically managing problems or improvements found in feedback.
### Key Features
- **Status Indicators**: Visually display the current status of issues (New, In Progress, Resolved, etc.)
- **External System Integration**: Connect with issue tracker systems (JIRA)
### How to Use
1. Create issues from feedback or in the issue menu
2. Configure external issue tracker connection (optional)
3. Set issue details and issue tracking ticket
4. Monitor and update issue progress
5. Close issue after resolution
## Single Sign-On (SSO)
![Single Sign-on](/assets/04-single-signon.png)
Single Sign-On simplifies authentication processes in enterprise environments and enhances security.
### Key Features
- **OAuth Support**: Authentication support through various OAuth providers
- **Enterprise ID Integration**: Seamless integration with existing enterprise ID systems
- **Centralized User Management**: Manage user access through a single authentication system
- **Enhanced Security**: Apply multi-factor authentication and enterprise security policies
- **Simplified Login Experience**: No need for users to create additional accounts
### Supported SSO Providers
- Google
- Custom (Standard OAuth 2.0 and OpenID Connect providers)
### How to Use
1. Configure SSO provider in admin settings
2. Set authentication parameters and redirect URLs
3. Configure user attribute mapping
4. Enable and test SSO login
## Role-Based Access Control (RBAC)
![Role Management](/assets/05-role-management.png)
Role-Based Access Control is a feature for effectively managing user permissions and maintaining system security.
### Key Features
- **Predefined Roles**: Provides basic roles such as Administrator, Analyst, Viewer
- **Custom Role Creation**: Create customized roles and permissions tailored to organizational structure
- **Granular Permission Control**: Set access permissions by function and data
- **Role Assignment Management**: Assign and change roles per user
- **Permission Inheritance**: Support hierarchical permission structures
### How to Use
1. Access role management menu in admin panel
2. Create new roles or modify existing roles as needed
3. Assign appropriate roles to users
4. Regularly review permissions and access scope by role
## Dashboard
![Dashboard](/assets/06-dashboard.png)
The dashboard is a feature that visualizes feedback data to understand important insights at a glance.
### Key Features
- **Real-time Statistics**: Real-time display of key metrics such as feedback count, issue count, resolution rate
- **Trend Analysis**: Graphs showing feedback and issue trends over time
- **Issue Distribution**: Visualization of feedback distribution by issue
### Provided Charts and Widgets
1. **Feedback Summary Cards**: Key metrics such as total feedback count, new feedback, processed feedback
2. **Time Series Graphs**: Daily/weekly/monthly feedback trends
3. **Issue Status Donut Chart**: Distribution by issue status
### How to Use
1. Access the dashboard page
2. Adjust data range through period and filter settings
3. Analyze key metrics and trends
4. Derive insights-based decisions and action items
## Additional Features
In addition to the key features described above, ABC User Feedback provides the following additional features:
### API Integration
- Integration with external systems through RESTful API
- Programmatic feedback collection and management
### Webhooks
- Notify external systems when major events occur
- Support building automated workflows
### Image Storage Integration
- Manage user-submitted images through S3-compatible storage
- Attach screenshots and images to feedback
### Data Export
- Export feedback data in CSV, Excel formats
### Multi-Language Support
- Provide interfaces in various languages
- Multi-language feedback management for international teams
---
This document provides an overview of ABC User Feedback's key features. For more detailed usage of each feature, refer to the [User Guide](/en/user-guide/getting-started) section.
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/00-introduction/_category_.json
+5
View File
@@ -0,0 +1,5 @@
{
"position": 1,
"label": "Introduction"
}
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/01-getting-started.md
+263
View File
@@ -0,0 +1,263 @@
---
title: Getting Started
description: This document explains how to start the system from initial setup to collecting the first feedback after installing ABC User Feedback.
sidebar_position: 1
---
# Getting Started
After installing ABC User Feedback for the first time, initial setup is required to use the system. This document provides step-by-step guidance from tenant creation to collecting the first feedback.
---
## Initial Setup Overview
To start ABC User Feedback, proceed with the following setup steps in order:
1. **Create tenant and administrator account**
2. **First login and profile setup**
3. **Create project**
4. **Create channel and configure fields**
5. **Generate API key**
6. **Test first feedback collection**
---
## Accessing the System
If you need to install ABC User Feedback, first proceed with [Installation using Docker Hub images](/en/developer-guide/installation/docker-hub-images).
After completing the installation, access ABC User Feedback through a web browser:
```
http://localhost:3000
```
> If you changed the port or domain, enter the address according to your settings.
---
## Creating Tenant and Administrator Account
![member-register.png](/img/tenant.png)
When you first access the system, the **Tenant Creation and Administrator Account Registration** screen will be displayed.
### Step 1: Enter Tenant Information
Set the tenant name.
After entering the tenant name, click the **Next** button.
> This tenant name will be displayed in the login UI.
### Step 2: Create Administrator Account
Create the first administrator account for the system.
1. Enter the administrator account email and click the **Request Code** button.
2. Check the authentication code in your email inbox and enter it
3. Click the **Verify** button
4. After verification is complete, set a password.
:::info Password Requirements
- **At least 8 characters**
- **Include letters** (A–Z, a–z)
- **Include special characters** (e.g., `@`, `#`, `!`)
- **No consecutive characters** (e.g., `aa`, `11`)
> **Examples**: ✅ `MyCompany2024!`, ❌ `12345678`, `password`
:::
After tenant and administrator account creation is complete, a confirmation screen will be displayed.
**Next step**: Click the **Confirm** button to proceed to the login screen.
---
## Logging In
Log in for the first time with the created administrator account.
1. **Email**: Enter the administrator email registered earlier
2. **Password**: Enter the set password
3. Click the **Sign In** button
---
## Creating First Project
After logging in, the project creation wizard will automatically start.
### Understanding System Structure
ABC User Feedback has the following hierarchical structure:
```
Tenant (Organization)
└── Project (Product/Service Unit)
└── Channel (Feedback Collection Path)
```
### Step 1: Project Basic Information
| Item | Description | Example |
| --------------- | ------------------------------------------------- | ------------------------------------------- |
| **Name** | Project name | `Mobile App`, `Web Service` |
| **Description** | Project description (optional) | `Customer feedback collection and analysis` |
| **Time Zone** | Time reference (affects dashboard and statistics) | `Asia/Seoul` |
**After completion**: After entering the information, click the **Next** button.
### Step 2: Invite Team Members (Optional)
In this step, you can invite team members to the project. You can skip this now and add them later anytime.
### Step 3: Generate API Key (Optional)
You can pre-generate an API key for integration with external systems.
### Project Creation Complete
After entering all information, project creation will be complete.
**Select next step**:
- **Create Channel**: Immediately create a channel to start collecting feedback
- **Skip for Now**: Create channel later
---
## Creating First Channel
After project creation, you need to create a **channel** to actually collect feedback.
### Understanding Channel Concept
A channel represents a **feedback collection path**:
- Website inquiry form
- In-app feedback in mobile app
- Customer service VoC
- Survey responses
### Step 1: Channel Basic Information
| Item | Description | Example |
| ---------------------------------- | -------------------------------------------------------- | ---------------------------- |
| **Name** | Channel name | `Web Feedback`, `App Review` |
| **Description** | Channel description (optional) | `Website user opinions` |
| **Maximum Feedback Search Period** | Searchable period for feedback (30/90/180/365 days, all) | `90 days` |
**After completion**: After entering the information, click the **Next** button.
### Step 2: Field Configuration
Define the data structure to collect in the channel.
#### Default Fields
Fields automatically created by the system:
| Field Name | Format | Property | Description |
| ----------- | ----------- | --------- | --------------------- |
| `id` | number | Read Only | Unique feedback ID |
| `createdAt` | date | Read Only | Creation time |
| `updatedAt` | date | Read Only | Modification time |
| `issues` | multiSelect | Editable | List of linked issues |
#### Adding Custom Fields
Add custom fields for actual feedback collection:
1. Click the **Add Field** button
2. Enter field information:
| Item | Description | Example |
| ---------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Key** | Unique identifier (uppercase/lowercase letters, numbers, `_`) | `message`, `rating` |
| **Display Name** | Name displayed in UI | `Feedback Content` |
| **Format** | Data format | `text`,`keyword`,`number`,`date`,`select`,`multiSelect`,`images`,`aiField` |
| **Property** | `Editable` (modifiable in UI) / `Read Only` (not modifiable) | `Editable` |
| **Status** | `Active` / `Inactive` | `Active` |
#### Recommended Default Field Configuration
For the first channel, it is recommended to add the following fields:
| Key | Display Name | Format | Description |
| ----------- | ---------------- | ------- | ------------------ |
| `message` | Feedback Content | text | User feedback |
| `userEmail` | User Email | keyword | Contact (optional) |
| `rating` | Satisfaction | number | 1-5 point rating |
### Field Preview
After completing field configuration, you can preview the feedback input screen with the **Preview** button.
**After completion**: Complete channel creation with the **Complete** button.
### Channel Creation Complete
**Next step**: Click the **Start** button to begin collecting feedback.
---
## Testing First Feedback Collection
After channel creation is complete, you can actually collect feedback.
### Registering Feedback via API
Let's register the first feedback using the created API key.
#### API Request Example
```bash
curl -X POST http://localhost:4000/api/projects/1/channels/1/feedbacks \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{
"message": "The app runs slowly",
"userEmail": "user@example.com",
"rating": 3
}'
```
> Replace `YOUR_API_KEY` with the actual API key created earlier.
#### Checking Success Response
If the API request succeeds, you will receive the following response:
```json
{
"id": 1
}
```
### Checking Feedback
Let's check the registered feedback in the web interface.
1. Click the **Feedback** tab in the top menu
2. Check the registered feedback in the feedback list
3. Click the feedback to view detailed information
### Creating First Issue
Let's create an issue based on the feedback.
1. In the feedback detail screen, click the **`+` button** in the **Issue** section
2. Enter the issue name and press **Enter** or click the **Create** button
3. Check the created issue
## Next Steps Guide
Basic setup and first feedback collection are complete!
## Related Documents
- [API Integration](/en/developer-guide/api-integration) - Detailed API usage guide
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/02-project-management.md
+347
View File
@@ -0,0 +1,347 @@
---
title: Project
description: This document explains how to create, configure, and manage projects in ABC User Feedback, and how to set team member roles and permissions.
sidebar_position: 2
---
# Project
In ABC User Feedback, a **project** is the most basic unit for collecting and analyzing feedback. This document covers features from project creation to team management and permission settings.
---
## Project Overview
Projects have the following hierarchical structure:
```
Tenant
└── Project (multiple allowed)
├── Channel (multiple allowed)
├── Members and Roles
├── Issue Tracker Integration
├── Webhook Integration
├── AI Features
└── API Keys
```
Each project is a management unit that includes multiple channels, and can independently set and operate team members, roles, issue tracker integration, external system integration, etc.
---
## Creating a Project
### Access Permissions
Only **Super users** can create projects. Regular users can participate by being invited as members to existing projects.
> If you need Super user permissions, please contact your system administrator.
### Access Method
There are two ways to create a new project:
1. **First login**: The project creation wizard automatically starts
2. **Additional projects**: Click the **Create Project** button at the top of the left sidebar
### Step 1: Project Basic Information
![create-project-1](/img/project/1.png)
When creating a project, enter the following information:
| Item | Description | Example |
| --------------- | -------------------------------------------------------------- | ------------------------------------------------ |
| **Name** | Project name (required) | `Mobile App`, `Customer Service`, `Beta Service` |
| **Description** | Brief description (optional) | `iOS/Android app user feedback collection` |
| **Time Zone** | Used as the time reference for feedback and reports (required) | `Asia/Seoul` |
> The time zone affects **dashboard statistics**.
**After completion**: After entering all information, click the **Next** button.
### Step 2: Add Team Members (Optional)
![create-project-2](/img/project/2.png)
This step can be **skipped**. You can add members later from the project settings at any time.
#### Adding Members
1. Click the **Register Member** button at the top right
2. Enter the following items:
- **Email**: Select a user registered in the system
- **Role**: Choose from Admin, Editor, or Viewer
> If you want to use custom roles, click the **Role Management** button for additional settings.
**After completion**: Check the member list and click **Next**.
### Step 3: Generate API Key (Optional)
![create-project-3](/img/project/3.png)
API keys are used when collecting feedback from external systems. You can generate them later from the settings menu, so you can skip this step now.
#### Key Generation Method
1. Click the **Create API Key** button at the top right
2. The key is automatically generated and displayed in the list
3. Copy the generated key and store it in a safe place
### Project Creation Complete
![create-project-4](/img/project/4.png)
After completing all steps, a **summary screen** appears:
- Project information: name, description, time zone
- Member list
- Generated API keys
- Role settings status
#### Next Steps
- To immediately create a channel and start collecting feedback, click the **Create Channel** button
- Or click the **Later** button to create it later
---
## Managing Project Settings
![project-setting.png](/img/project/project-setting.png)
### Access Method
To change project settings:
1. Click **Settings** in the top menu
2. Select **Project Setting** from the left menu
### Editing Basic Information
You can modify the following items at any time:
| Item | Description | Notes |
| --------------- | --------------------------------------------------- | ----------------------------------- |
| **Name** | Project name | Name displayed to team members |
| **Description** | Description (optional) | Purpose of the project |
| **Time Zone** | Time reference for statistics and time-related data | Changes do not affect existing data |
**Save method**: After making changes, click the **Save** button at the top right.
### Notes on Time Zone Changes
- Does not affect the time information of existing feedback/issues
- Data inconsistencies may occur in dashboard statistics after changes.
### Deleting a Project
#### Deletion Procedure
To completely delete a project:
1. Click the **Delete Project** button at the bottom of the Project Setting screen
2. Enter the project name exactly in the confirmation popup
3. Click the **Delete** button to finalize
#### Deletion Notes
- **All feedback, issues, and settings within the project will be permanently deleted**
- **Cannot be undone**, so backup or export is recommended beforehand
- Connected channels and API keys are also removed upon deletion
---
## Member Management
![member-setting.png](/img/project/member-setting.png)
### Viewing Member List
To view members currently participating in the project:
1. Click **Settings** in the top menu
2. Select **Member Management** from the left menu
The member list displays the following information:
| Item | Description |
| ---------- | -------------------------- |
| Email | Account email |
| Name | User name (from profile) |
| Department | Department |
| Role | Role within the project |
| Joined | Project participation date |
### Inviting New
![member-register.png](/img/project/member-register.png)
#### Invitation Procedure
1. Click the **Register Member** button
2. Enter invitation information:
| Item | Description |
| --------- | -------------------------------------------- |
| **Email** | Email of the user to invite |
| **Role** | Role to assign (Admin, Editor, Viewer, etc.) |
3. Click the **Invite** button to complete the invitation
### Editing Member Information
To modify existing member information:
1. Click the row of the member you want to edit in the member list
2. In the popup, you can modify the Role:
3. Click the **Save** button to save changes
### Removing Members
To remove a member from the project:
1. Click the **Delete** button at the bottom of the member edit popup
2. Click **Confirm** in the confirmation message
> Removing a member does not delete feedback/issue records created by that user; only project access permissions are removed.
---
## Role and Permission Management
![role-setting.png](/img/project/role-setting.png)
### Default Roles
The system provides the following default roles:
| Role | Permission Summary |
| ---------- | ---------------------------------------------------------------------- |
| **Admin** | Access to all features. Includes project deletion |
| **Editor** | Can create, modify, and delete feedback/issues. Cannot access settings |
| **Viewer** | View only. Cannot modify, delete, or access settings |
### Creating Custom Roles
![role-create.png](/img/project/role-create.png)
You can create custom roles when more granular permissions are needed:
1. Click the **Role Management** link in the Member Management screen
2. Click the **Create Role** button
3. Enter the role name and permissions:
### Permission Settings
For each role, you can set the following feature-specific permissions:
#### Feedback Permissions
| Permission Item | Description |
| ----------------------------------- | -------------------------------- |
| **Download Feedback** | Download feedback data |
| **Edit Feedback** | Edit feedback |
| **Delete Feedback** | Delete feedback |
| **Attach/Detach Issue in Feedback** | Link/unlink issues with feedback |
#### Issue Permissions
| Permission Item | Description |
| ---------------- | ------------- |
| **Create Issue** | Create issues |
| **Edit Issue** | Edit issues |
| **Delete Issue** | Delete issues |
#### Project Management
| Permission Item | Description |
| --------------------- | ------------------------ |
| **Edit Project Info** | Edit project information |
| **Delete Project** | Delete project |
#### Member Management
| Permission Item | Description |
| ------------------------- | ---------------------- |
| **Read Project Member** | View project members |
| **Create Project Member** | Invite project members |
| **Edit Project Member** | Edit project members |
| **Delete Project Member** | Remove project members |
#### Role Management
| Permission Item | Description |
| ----------------------- | -------------------- |
| **Read Project Role** | View project roles |
| **Create Project Role** | Create project roles |
| **Edit Project Role** | Edit project roles |
| **Delete Project Role** | Delete project roles |
#### API Key Management
| Permission Item | Description |
| ------------------ | --------------- |
| **Read API Key** | View API keys |
| **Create API Key** | Create API keys |
| **Edit API Key** | Edit API keys |
| **Delete API Key** | Delete API keys |
#### Issue Tracker
| Permission Item | Description |
| ---------------------- | ----------------------- |
| **Read Issue Tracker** | View issue tracker |
| **Edit Issue Tracker** | Configure issue tracker |
#### Webhook Management
| Permission Item | Description |
| ------------------ | --------------- |
| **Read Webhook** | View webhooks |
| **Create Webhook** | Create webhooks |
| **Edit Webhook** | Edit webhooks |
| **Delete Webhook** | Delete webhooks |
#### AI and Channel Settings
| Permission Item | Description |
| ---------------------- | ---------------- |
| **Read Generative AI** | View AI settings |
| **Edit Generative AI** | Edit AI settings |
#### Channel-Related Settings
| Permission Item | Description |
| ---------------------- | ------------------------ |
| **Edit Channel Info** | Edit channel information |
| **Delete Channel** | Delete channel |
| **Read Field** | View fields |
| **Edit Field** | Edit fields |
| **Read Image Setting** | View image settings |
| **Edit Image Setting** | Edit image settings |
| **Create Channel** | Create new channels |
### Permission Setting Tips
#### Security Best Practices
- **Principle of least privilege**: Grant only the minimum permissions necessary for work
- **Regular review**: Check permissions when team changes or employees leave
- **Limit Admin role**: Keep the number of administrators as small as possible
### Editing and Deleting Roles
- **Edit**: Click the desired item in the role list to modify the name and permissions
- **Delete**: Roles not in use can be deleted with the **Delete** button
> **Note**: At least one Admin role must always exist and cannot be deleted.
---
## Related Documents
- [Channel Management](./03-channel-management.md) - Channel creation and field settings
- [Feedback Management](./04-feedback-management.md) - Feedback collection and analysis
- [API Integration](/en/developer-guide/api-integration) - API key usage
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/03-channel-management.md
+237
View File
@@ -0,0 +1,237 @@
---
title: Channel
description: This document explains how to create, configure, and manage feedback collection channels in ABC User Feedback, and how to handle custom fields and image settings.
sidebar_position: 3
---
# Channel
A **Channel** is a unit that distinguishes feedback collection paths or purposes. Each channel has an independent field structure, image settings, and AI features, allowing configuration for various feedback collection scenarios.
---
## Channel Overview
### Role of Channels
Channels serve the following roles:
- **Distinguish feedback collection paths**: Web, app, customer service, surveys, etc.
- **Define data structure**: Unique field settings per channel
- **Manage collection policies**: Image allowance, search period, security settings, etc.
- **Provide analysis units**: Independent statistics and analysis per channel
---
## Creating a Channel
### Access Method
To create a new channel:
1. **Right after project creation**: Click the **Create Channel** button on the project completion screen
2. **Additional channel creation**: Click the **Create Channel** button in **Settings > Channel List**
### Step 1: Channel Basic Information
![channel-create-1](/img/channel/1.png)
| Item | Description | Example |
| ---------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
| **Name** | Channel name (required) | `Web Feedback`, `App Review`, `Customer Service` |
| **Description** | Brief channel description (optional) | `Website user opinion collection` |
| **Maximum Feedback Search Period** | Maximum searchable period for feedback (30/90/180/365 days, all) | `90 days` |
#### Notes on Maximum Feedback Search Period Setting
- **Impact scope**: Directly affects the feedback download functionality
- **Download behavior**: All feedback within the set search period becomes the download target
- **Performance testing**: If daily feedback count is high, test with various periods to find the optimal value
- **Gradual adjustment**: Start with a short period and gradually increase as needed
**After completion**: After entering the information, click the **Next** button.
### Step 2: Field Configuration
![channel-create-2](/img/channel/2.png)
Define the data structure to collect in the channel. This directly affects the API request structure and feedback table configuration.
#### Default System Fields
Fields automatically included in all channels:
| Key | Format | Property | Description |
| ----------- | ----------- | --------- | -------------------------- |
| `id` | number | Read Only | Unique feedback ID |
| `createdAt` | date | Read Only | Feedback creation time |
| `updatedAt` | date | Read Only | Feedback modification time |
| `issues` | multiSelect | Editable | List of linked issues |
> These fields cannot be deleted or have their main properties modified.
#### Adding Custom Fields
Add fields that match actual business requirements.
1. Click the **Add Field** button
2. Enter field information
| Item | Description | Example |
| ---------------- | ------------------------------------------------------------- | -------------------------------- |
| **Key** | Unique identifier (uppercase/lowercase letters, numbers, `_`) | `message`, `rating` |
| **Display Name** | Name displayed in UI | `Feedback Content`, `User Email` |
| **Format** | Data format (see table below) | `text`, `keyword`, `number` |
| **Property** | `Editable` (can input) / `Read Only` (view only) | `Editable` |
| **Status** | `Active` / `Inactive` | `Active` |
| **Description** | Easy-to-understand description for team members (optional) | `User-entered feedback content` |
### Field Format Types
| Format | Description | Usage Example | API Example |
| ------------- | ------------------------ | ----------------------------------------------- | ------------------------ |
| `text` | Free text input | Feedback content, detailed description | `"App keeps freezing"` |
| `keyword` | Short keyword/tag | Version info, page name | `"v1.2.3"` |
| `number` | Number | Rating, age, usage time | `5` |
| `date` | Date | Occurrence date, expiration date | `"2024-03-01T00:00:00Z"` |
| `select` | Single selection | Category, priority | `"Feature Request"` |
| `multiSelect` | Multiple selection | Tags, related features | `["Bug", "UI"]` |
| `images` | Image URL array | Screenshots, attachments | `["https://..."]` |
| `aiField` | AI analysis result field | Sentiment analysis, summary, keyword extraction | `"Positive"` |
> **About images format**: For detailed image setting methods, refer to the [Image Settings](/en/user-guide/settings/image-setting) document.
>
> **About aiField format**: For AI field settings and template configuration methods, refer to the [AI Settings](/en/user-guide/settings/ai-setting) document.
### Field Configuration Examples
#### Web Feedback Channel
| Key | Display Name | Format | Purpose |
| ------------- | ---------------- | ------- | ------------------------------- |
| `message` | Feedback Content | text | User opinion |
| `userEmail` | Email | keyword | Contact (optional) |
| `pageUrl` | Page URL | keyword | Feedback occurrence location |
| `category` | Category | select | Bug/Feature Request/Improvement |
| `priority` | Priority | select | High/Medium/Low |
| `screenshots` | Screenshots | images | Problem situation capture |
#### Mobile App Review Channel
| Key | Display Name | Format | Purpose |
| ------------ | -------------- | ------- | -------------------- |
| `message` | Review Content | text | User review |
| `rating` | Rating | number | 1-5 point rating |
| `appVersion` | App Version | keyword | For bug tracking |
| `deviceType` | Device Type | select | iOS/Android |
| `crashLogs` | Crash Logs | text | Technical error info |
### Field Preview
After completing field configuration, you can preview the actual feedback input screen with the **Preview** button.
This preview matches the field structure required for API requests.
**After completion**: Proceed to the next step with the **Next** button.
### Step 3: Channel Creation Complete
![create-channel-3](/img/channel/3.png)
Once all steps are completed, a **summary screen** appears:
- Channel information: Name, description, time zone
- Field information
---
## Field Management
![field-management.png](/img/channel/field-management.png)
### Editing Fields
To modify existing fields, click the row of the field you want to edit in the field list and modify the information.
> **Note**: `Key` and `Format` cannot be modified after creation. This is restricted for data consistency.
### Field Deletion
To ensure data integrity and consistency, **field deletion is not provided**.
#### Recommended Method Instead of Deletion
1. **Change to Inactive status**: Disable the field to exclude it from new feedback collection
2. **Preserve data**: Keep existing collected feedback data as is
3. **Use filtering**: Display only Active fields in the field list for management efficiency
#### When Complete Removal is Needed
If you need to completely remove a field:
- Consider deleting the entire channel and creating a new one
- Export data and migrate to a new structure
- Consult with the development team for database-level processing
### Field Status Management
#### Active / Inactive Toggle
- **Active**: Fields used during feedback collection
- **Inactive**: Temporarily disabled fields (data is preserved)
#### Filtering Options
You can filter fields by the following conditions using the top controls:
- **Status**: `Active` / `Inactive`
- **Property**: `Editable` / `Read Only`
---
## Channel Information Management
![channel-setting](/img/channel/channel-setting.png)
### Editing Channel Basic Information
You can modify the basic information of created channels.
#### Access Method
1. **Settings > Channel List > [Select Channel]**
2. Click the **Channel Information** tab
#### Editable Items
| Item | Editable | Notes |
| ---------------------------------- | -------- | ------------------------------ |
| **Channel ID** | ❌ No | Internal system identifier |
| **Channel Name** | ✅ Yes | Name displayed to team members |
| **Description** | ✅ Yes | Channel purpose |
| **Maximum Feedback Search Period** | ✅ Yes | May affect performance |
### Channel Deletion
You can delete channels that are no longer in use.
#### Deletion Procedure
1. Click the **Delete Channel** button at the bottom of the Channel Information screen
2. Enter the channel name exactly in the confirmation popup
3. Finalize with the **Delete** button
#### Deletion Notes
- **All feedback data for that channel will be permanently deleted**
- **Cannot be undone**, so backup or export is recommended beforehand
- Related API key settings should also be checked
---
## Related Documents
- [Project Management](./02-project-management.md) - Project settings and permission management
- [Feedback Management](./04-feedback-management.md) - Analysis and utilization of collected feedback
- [API Integration](/en/developer-guide/api-integration) - Integration methods with external systems
- [AI Integration](/en/user-guide/settings/ai-setting) - AI feature settings
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/04-feedback-management.md
+336
View File
@@ -0,0 +1,336 @@
---
title: Feedback
description: This document explains how to create, view, analyze, and manage feedback in ABC User Feedback.
sidebar_position: 4
---
# Feedback
Feedback is the core data of ABC User Feedback. This document covers all features related to feedback, from creation to analysis and management.
![feedback](/img/feedback/0.png)
---
## Creating Feedback
Feedback is mainly created by external systems (websites, mobile apps, API integration), but administrators can also create it directly.
### Creating Feedback via API
This is the most common method of creating feedback.
#### Basic API Request Structure
```bash
curl -X POST http://your-domain.com/api/v1/projects/{projectId}/channels/{channelId}/feedbacks \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{
"message": "User feedback content",
"userEmail": "user@example.com",
"category": "Bug Report"
}'
```
#### Request Examples by Channel Fields
The request structure varies depending on each channel's field settings:
**Web Feedback Channel Example**:
```json
{
"message": "Login button is not working",
"userEmail": "user@company.com",
"pageUrl": "https://example.com/login",
"category": "Bug",
"priority": "High",
"browserInfo": "Chrome 119.0.0"
}
```
**Mobile App Channel Example**:
```json
{
"message": "App freezes frequently",
"rating": 2,
"appVersion": "v2.1.3",
"deviceType": "iOS",
"crashLogs": "Exception in thread main..."
}
```
#### Feedback with Images
When using image URL method:
```json
{
"message": "Screen appears broken",
"userEmail": "user@example.com",
"images": [
"https://cdn.example.com/screenshot1.png",
"https://cdn.example.com/screenshot2.png"
]
}
```
### Verifying Feedback Creation
Created feedback is immediately displayed in the feedback list.
---
## Accessing Feedback List
Access the feedback list to view and manage created feedback.
### Access Method
1. Select the desired **project** from the left sidebar
2. Click the desired **channel** from the channel list at the bottom
3. Select the **Feedback** tab in the top menu
### Feedback Table Structure
The feedback list is displayed in table format with the following basic structure:
| Column Type | Description | Example |
| ------------------- | --------------------------------------------- | ---------------------------- |
| **Default Columns** | Displayed for all channels | ID, Created, Updated, Issue |
| **Custom Columns** | Displayed according to channel field settings | Message, UserEmail, Category |
---
## Feedback Filtering/Sorting/View Options
Various tools are provided to quickly find desired information from large amounts of feedback data.
![feedback-option](/img/feedback/1.png)
### Date Filtering
You can set the viewing period with the **Date** button at the top.
#### Available Period Options
| Option | Description | Use Case |
| ---------------- | --------------------------- | ------------------------ |
| **Today** | Feedback registered today | Real-time monitoring |
| **Yesterday** | Previous day's feedback | Daily review |
| **Last 7 Days** | Recent 1 week of data | Weekly analysis |
| **Last 30 Days** | Recent 1 month of data | Monthly trend analysis |
| **Custom** | Set start-end date directly | Specific period analysis |
### Filters
Click the **Filter** button to filter feedback by various conditions.
![feedback-filter](/img/feedback/2.png)
#### Filter Structure
```
Where: First condition
And: Feedback that satisfies all conditions
Or: Feedback that satisfies at least one condition
```
> **Note**: `And` and `Or` cannot be mixed at the same time.
#### Filter Options by Field Type
| Field Type | Available Operators | Example |
| --------------- | ------------------------------------------ | ----------------------------- |
| **text** | Contains (partial match) | message contains "bug" |
| **keyword** | Is (exact match) | category is "Feature Request" |
| **number** | Is (exact match) | rating == 3 |
| **select** | Is (exact match) | |
| **multiSelect** | Is (exact match), Contains (partial match) | |
| **aiField** | Contains (partial match) | |
| **date** | Is (exact match), Between (period match) | created between date range |
#### Filter Usage Examples
**Advanced Search for Multi-Select Category**:
```
Where: category contains "Bug"
And: priority is "High"
```
**Finding Feedback Linked to Multiple Issues**:
```
Where: issues contains "Login Issue"
Or: issues contains "UI Improvement"
```
**Finding 4-Rating Feedback in Specific Category**:
```
Where: category is "Feature Request"
And: rating is 4
```
### Sorting Function
Click table headers to sort by that column. This feature is available for Created and Updated columns.
### View Options
You can adjust the display method of the feedback list to suit your needs.
#### Expand Feature
Click the **Expand** button to preview detailed content of each feedback in the table.
**Usage**:
- Check main content without opening detail panel
- Quickly browse through multiple feedback
- View full content of long text fields
#### Show/Hide Columns
You can select columns to display with the **View** button at the top of the table.
**Features**:
- **Required columns**: ID, Created are always displayed (cannot be hidden)
- **Optional columns**: Custom fields can be individually shown/hidden
- **Screen optimization**: Efficiently use screen space by displaying only needed information
**Usage Tips**:
```
For monitoring: Display only ID, Created, Message
For analysis: Display all custom fields
For review: Display Message, Category, Priority
```
## Viewing/Editing/Deleting Feedback
You can view detailed information of individual feedback and edit or delete it as needed.
### Viewing Feedback Details
#### Access Method
Click a **row** in the feedback table to open the detail view panel on the right.
![feedback-detail](/img/feedback/3.png)
### Detail Panel Structure
The detail panel is structured as follows:
#### 1. Basic Information Area
- **Feedback ID**: Unique identification number
- **Creation Time**: Initial registration date/time
- **Modification Time**: Last change date/time
- **Issues**: Tagged issues
#### 2. Custom Fields Area
All custom fields set in the channel are displayed.
### Editing Feedback
#### Editable Fields
Click the **Edit** button in the detail panel to switch to edit mode.
#### Editable Items
| Item | Editable | Notes |
| ------------------ | -------- | -------------------------------------------------------------------- |
| **Default Fields** | ❌ No | ID, creation date, etc. |
| **Custom Fields** | ✅ Yes | Varies by field setting Property, not possible if Status is Inactive |
#### Completing Edits
1. Modify necessary information
2. Click the **Save** button
3. Changes are immediately reflected and "Updated" time is refreshed
### Issue Link Management
#### Creating New Issue
1. Click the **+ button** in the issue column
2. Enter the issue name and click the **Create** option
#### Linking Existing Issue
1. Click the **+ button** in the issue section
2. Enter the name of the issue to link
3. Select the issue to link from the dropdown
#### Unlinking Issue
1. Click the **+ button** in the issue section
2. Select the issue to unlink
### Deleting Feedback
#### Single Feedback Deletion
1. Click the **Delete Feedback** button at the bottom of the detail panel
2. Approve deletion in the confirmation dialog
#### Multiple Feedback Deletion
1. Select multiple feedback using **checkboxes** in the feedback list
2. Click the **Delete Selected** button that appears at the top
3. Confirm batch deletion
#### Deletion Notes
- **Cannot be recovered**: Deleted feedback cannot be restored
- **Issue links removed**: Linked issues remain but links are removed
- **Statistics impact**: Data is excluded from dashboard statistics
---
## Downloading Feedback
You can export collected feedback data in various formats for analysis or backup.
### Accessing Download Function
#### Download All Feedback
1. Click the **Export** button at the top of the feedback list
#### Download Filtered Feedback
1. Apply filtering with desired conditions
2. Click the **Export** button to download only data matching current filter conditions
#### Download Selected Feedback
1. Select specific feedback using checkboxes
2. Click the **Export Selected** button
### Download Format Selection
When clicking the Export button, you can select the download format.
#### Supported Formats
| Format | Extension | Advantages | Recommended Use Cases |
| --------- | --------- | ---------------------------------------- | ---------------------------------- |
| **CSV** | `.csv` | Lightweight and highly compatible | Excel, Google Sheets analysis |
| **Excel** | `.xlsx` | Format preservation, multi-sheet support | Detailed analysis, report creation |
---
## Related Documents
- [Channel Management](./03-channel-management.md) - Channel and field settings for feedback collection
- [Issue Management](./05-issue-management.md) - Creating and managing issues from feedback
- [API Integration](/en/developer-guide/api-integration) - How to send feedback from external systems
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/05-issue-management.md
+314
View File
@@ -0,0 +1,314 @@
---
title: Issue
description: This document explains how to create and manage issues in ABC User Feedback and efficiently track them using kanban/list views.
sidebar_position: 5
---
# Issue
**Issues** are a core feature for systematically managing problems or improvements found in feedback. This document covers all issue management features, from issue creation to category management and various view modes.
![issue](/img/issue/1.png)
---
## Issue Overview
### Role of Issues
Issues are used for the following purposes:
- **Problem tracking**: Systematically manage bugs, errors, performance issues, etc.
- **Feature request management**: Structure user requests and reflect them in development plans
- **Identifying improvements**: Identify improvement points through feedback analysis
### Issue Status
Each issue has the following status:
| Status | Description | When Used |
| --------------- | ------------------- | --------------------------------------- |
| **New** | Newly registered | Initial issue creation |
| **On Review** | Under review | When assignee starts review |
| **In Progress** | In progress | During actual work |
| **Resolved** | Resolved | Problem solved and completed |
| **On Hold** | Temporarily on hold | Waiting for additional info or deferred |
---
## Creating/Editing/Deleting Issues
### Issue Creation Methods
Issues can be created in two ways.
#### 1. Create Issue from Feedback (Recommended)
The most common method, creating an issue based on specific feedback.
1. Click feedback in the **Feedback** tab to open detail view
2. Click the **`+` button** in the **Issue** section of the right detail panel
3. Enter the issue name and press **Enter** or click the **Create** option
#### 2. Create Directly from Issue List
1. Click the **Issue** tab in the top menu
2. Click the **+ Create Issue** button at the top left
3. Enter information in the issue creation dialog:
| Item | Description | Required | Example |
| --------------- | ----------------------------- | -------- | ---------------------------- |
| **Title** | Issue title | Required | `Login button malfunction` |
| **Description** | Detailed description | Optional | `Occurs in specific browser` |
| **Category** | Issue classification | Optional | `Bug` |
| **Status** | Initial status (default: New) | Optional | `New` |
### Editing Issues
You can modify information of created issues.
#### Editing Method
1. Click the issue you want to edit in the issue list
2. Click the **Edit** button in the **Issue Details** panel that opens on the right
3. In edit mode, you can modify the following items:
#### Editable Items
| Item | Editable | Description |
| --------------- | -------- | ------------------------------------------- |
| **Title** | ✅ Yes | Issue title |
| **Description** | ✅ Yes | Detailed description |
| **Category** | ✅ Yes | Issue classification (select from dropdown) |
| **Status** | ✅ Yes | Current progress status |
| **Ticket** | ✅ Yes | External issue tracker ticket number |
| **ID** | ❌ No | System auto-generated |
| **Created** | ❌ No | Creation date/time |
#### Save and Cancel
- **Save** button: Saves changes and exits edit mode
- **Cancel** button: Cancels changes and reverts to original state
### External Issue Tracker Integration
When integration with external issue trackers (Jira, etc.) is configured, you can link external tickets to issues.
#### Ticket Linking Method
1. Enter the external ticket number in the **Ticket** field in the issue detail panel
2. The entered number is automatically converted to an external system link
> **Note**: External issue tracker integration requires prior configuration in **Settings > Issue Tracker Management**.
### Deleting Issues
You can delete issues that are no longer needed.
#### Deletion Method
1. Click the **Delete** button in the issue detail panel
2. Approve deletion in the confirmation dialog
#### Deletion Notes
- **Cannot be recovered**: Deleted issues cannot be restored
- **Feedback links removed**: Issue links in connected feedback are removed
- **Statistics impact**: Data is excluded from dashboard issue statistics
---
## Kanban View
Kanban view is a viewing method that allows visual management by separating issues into columns by status.
![issue-kanban](/img/issue/2.png)
### Accessing Kanban View
1. Click the **Issue** tab in the top menu
2. Select **Kanban** view at the top right
### Kanban Board Structure
Columns are organized by each status, and issues are displayed as cards.
#### Kanban Column Structure
| Column | Display Information | Card Count Display |
| --------------- | ----------------------- | ------------------ |
| **New** | Newly registered issues | Number at top |
| **On Review** | Issues under review | Number at top |
| **In Progress** | Issues in progress | Number at top |
| **Resolved** | Resolved issues | Number at top |
| **On Hold** | Issues on hold | Number at top |
#### Issue Card Information
Each issue card displays the following information:
- **Issue title**: Click to go to detail view
- **Feedback count**: Number of linked feedback (with 📝 icon)
- **Category**: Displayed at bottom if set
- **External ticket**: Ticket number displayed if linked
### Drag and Drop Status Change
A core feature of kanban view, you can change status by dragging issue cards to different columns.
#### Usage Method
1. Click and drag an issue card with the mouse
2. Move it over the desired status column
3. Release the mouse to automatically change status
### Kanban View Filtering
You can display only issues matching specific conditions using the filter function at the top.
#### Available Filters
1. **Date** filter: Display only issues created in a specific period
2. **Filter** button: Set advanced filter conditions
#### Filter Condition Examples
| Filter Type | Condition Example | Use Case |
| ------------ | ---------------------- | ---------------------------------- |
| **Category** | Category = "Bug" | Check only bug issues |
| **Title** | Title contains "Login" | Find login-related issues |
| **Created** | Created >= 2024-03-01 | Issues created after specific date |
| **Status** | Status != "Resolved" | Display only unresolved issues |
### Kanban View Sorting
You can change the sort order of issue cards within each column.
#### Sort Options
- **Created Date ↓**: Newest first
- **Created Date ↑**: Oldest first
- **Feedback Count ↓**: Most linked feedback first
---
## List View
List view is a viewing method that displays issues grouped by category in table format.
### Accessing List View
1. Click the **Issue** tab in the top menu
2. Select **List** view at the top right
### List View Structure
Issues grouped by category are displayed hierarchically.
#### Category Groups
Each category is displayed as a collapsible/expandable group:
- **Group header**: Category name and number of included issues
- **Collapse/Expand arrow**: Toggle group content display/hide
- **"No Category"**: Issues without assigned category
### List View Filtering
Provides the same filter function as kanban view.
#### Filter Application Method
1. Click the **Date** or **Filter** button at the top
2. Set desired conditions
3. Filtered results are displayed grouped by category
#### Empty Category Handling
Categories with no issues in the filtering results are automatically hidden.
### List View Sorting
You can sort by clicking each column header.
#### Sort Behavior
- **First click**: Ascending sort ↑
- **Second click**: Descending sort ↓
#### Each Sort Content
| Sort Criteria | Use Case |
| -------------------- | ----------------------------- |
| **Created ↓** | Check latest issues first |
| **Feedback Count ↓** | Prioritize high-impact issues |
| **Status** | Check grouped by status |
---
## Issue Categories
Issue categories are a feature that allows systematic management by classifying issues.
### Purpose of Categories
- **Issue classification**: Distinguish bugs, feature requests, improvements, etc.
- **Analysis ease**: Analyze issue occurrence patterns by category
### Default Category Examples
Commonly used category classifications:
| Category | Description | Priority | Example Team |
| ------------------- | ----------------------------- | -------- | ---------------------------- |
| **Bug** | Function malfunction, errors | High | Development Team |
| **Feature Request** | New feature addition requests | Medium | Planning Team |
| **Improvement** | Existing feature enhancement | Medium | UX Team |
| **Performance** | Speed, stability issues | High | Infrastructure Team |
| **UI/UX** | User interface problems | Low | Design Team |
| **Documentation** | Help, guide related | Low | Technical Documentation Team |
### Category Management
#### Adding Categories
You can add new categories in the issue detail panel:
1. Click the **Add** button in the **Category** field of the issue detail panel
2. Enter the new category name
3. Press **Enter** or click the confirm button
#### Assigning Categories
You can assign or change categories for existing issues:
1. Click the **Edit** button in the issue detail panel
2. Select the desired category from the **Category** dropdown
3. Save changes with the **Save** button
### Category-Based Issue Management
#### Checking by Category in List View
In list view, you can see issues grouped by category at a glance:
- **Issue count by category**: Number of included issues displayed in each group header
- **Group collapse/expand**: Selectively check only needed categories
- **"No Category" group**: Separate management of unclassified issues
#### Category-Based Filtering
When you want to check only issues of a specific category:
1. Click the **Filter** button
2. Add a **Category** condition
3. Select the desired category
---
## Related Documents
- [Feedback Management](./04-feedback-management.md) - How to create and link issues from feedback
- [Issue Tracker Integration](/en/user-guide/settings/issue-tracker-management) - Integration settings with external tools
- [Project Management](./02-project-management.md) - Team composition and permission management
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/07-settings/01-tenant-settings.md
+236
View File
@@ -0,0 +1,236 @@
---
title: Tenant Settings
description: This guide explains how to manage tenant information, login methods, user management, and other organization-wide settings in ABC User Feedback.
sidebar_position: 1
---
# Tenant Settings
Tenant settings are the top-level management features of ABC User Feedback, covering important settings that affect the entire organization. This document explains how to manage tenant information, configure login methods, and manage all users.
> **Note**: These settings can only be accessed by users with **Super Admin permissions**.
---
## Tenant Settings
A tenant is the top-level unit of an organization, encompassing all projects and users.
### Access Method
1. Click the **Home** icon in the top right menu
2. Select **Tenant Information** from the left menu
### Editable Items
| Item | Description | Editable | Example |
| --------------- | -------------------------------------------- | -------- | ---------------------------- |
| **ID** | Unique tenant identifier (system auto-generated) | ❌ No | `1` |
| **Name** | Tenant name (organization name, company name, etc.) | ✅ Yes | `ABC Company` |
| **Description** | Tenant description (optional) | ✅ Yes | `Customer feedback management system` |
### How to Edit Information
1. Modify the **Name** or **Description** field
2. Click the **Save** button at the top right
3. A success message is displayed when saved
> The tenant name may be displayed in the login UI.
---
## Login Settings
Configure the authentication method users will use when accessing the system.
### Access Method
1. Click the **Home** icon in the top right menu
2. Select **Login Management** from the left menu
### Supported Login Methods
#### 1. Email Login
The default email + password combination method.
**Features**:
- Enabled by default without additional setup
- User invitation → email verification → password setup sequence
- Password reset functionality provided
**Password Policy**:
- Minimum 8 characters
- Recommended to include letters, numbers, and special characters
- Consecutive characters prohibited (e.g., `aa`, `11`)
#### 2. Google Login
Social login method via Google OAuth 2.0.
**Setup Method**:
1. **Enable Google Login**: Toggle to ON
2. **Google Cloud Console setup is required**:
> **Note**: For detailed implementation of Google OAuth integration, refer to the [OAuth Integration Guide](/en/developer-guide/oauth-integration).
#### 3. Custom OAuth Login
Method using your own OAuth server or other OAuth providers.
**Setup Items**:
| Item | Description | Example |
| ----------------- | ------------------------------------ | --------------------------------------------- |
| **Provider Name** | Name displayed on login button | `Sign in with Microsoft` |
| **Client ID** | OAuth client ID | `abc123xyz` |
| **Client Secret** | OAuth client secret | `supersecret` |
| **Auth URL** | Authentication request URL | `https://auth.example.com/oauth2/auth` |
| **Token URL** | Token request URL | `https://auth.example.com/oauth2/token` |
| **User Info URL** | User information request URL | `https://auth.example.com/oauth2/userinfo` |
| **Scope** | Permission scope to request | `openid email profile` |
| **Email Key** | Email field name in user information | `email` |
**Setup Sequence**:
1. Enter OAuth server information in each field
2. Click the **Save** button to save
3. A button with the configured Provider Name is displayed on the login screen
### Login Method Combinations
Multiple login methods can be enabled simultaneously:
- **Email only**: Only default login form displayed
- **Email + Google**: Login form + "Sign in with Google" button
- **Email + Custom**: Login form + custom OAuth button
### Testing Login Settings
After changing settings, be sure to test:
1. Access the login page in browser incognito mode
2. Verify that configured login methods are displayed correctly
3. Perform actual login tests with each method
---
## User Management
A feature to centrally manage all users across the tenant.
### Access Method
1. Click the **Home** icon in the top right menu
2. Select **User Management** from the left menu
### Viewing User List
#### Displayed Information
| Column | Description | Display Example |
| ---------- | -------------------------------- | ---------------------------- |
| Email | Login account email | `user@company.com` |
| Name | User name (from profile) | `John Doe` |
| Department | Department | `Development Team` |
| Type | User type | `SUPER` / `GENERAL` |
| Project | List of accessible projects | `Project A, Project B` |
| Created | Account creation date/time | `2024-03-15 14:30` |
#### User Type Description
| Type | Description | Permission Scope |
| --------- | --------------------------------------------------------------- | ---------------------- |
| `SUPER` | Can access all projects and settings. Acts as full system administrator | Entire tenant |
| `GENERAL` | Can only access specified projects | Specific projects only |
### User Search and Filtering
You can quickly find desired users when there are many users.
#### Filter Function
Click the **Filter** button at the top to set conditions.
**Filter Conditions**:
- **Email**: Search by email address
- **Name**: Search by user name
- **Department**: Search by department name
**Operator Options**:
- **CONTAINS**: When it contains
- **IS**: When it exactly matches
### Inviting Users
Invite new users to the system.
#### Invitation Method
1. Click the **Invite User** button at the top right
2. Enter invitation information
| Item | Description | Options |
| ----------- | ---------------------------------- | --------------------------- |
| **Email** | Email address of user to invite | Required input |
| **Type** | User type | `GENERAL` / `SUPER` |
| **Project** | Projects to allow access | Select from project list |
| **Role** | Role in that project | `Admin` / `Editor` / `Viewer` |
3. Click the **Invite** button to complete the invitation
#### Post-Invitation Process
1. An email is sent to the invited user
2. The user clicks the link in the email to proceed with registration
3. After registration is complete, they are automatically added to the specified project
### Editing User Information
You can modify information and permissions of existing users.
#### Editing Method
1. Click the user you want to edit in the user list
2. The **Edit User** popup opens
#### Editable Items
| Item | Editable | Description |
| --------- | -------- | ------------------------------------- |
| **Email** | ❌ No | Cannot be changed as account identifier |
| **Type** | ✅ Yes | Can change between `GENERAL` ↔ `SUPER` |
#### Save and Apply
1. Modify necessary information
2. Click the **Save** button
3. Changes are applied immediately and reflected from the user's next login
### Deleting Users
You can delete users who no longer use the system.
#### Deletion Method
1. Click the **Delete** button at the bottom of the user edit popup
2. Approve deletion in the confirmation dialog
#### Deletion Notes
- **Cannot be recovered**: Deleted user accounts cannot be restored
- **Immediate access removal**: All system access is blocked immediately upon deletion
---
## Related Documents
- [Project Management](../02-project-management.md) - Member and permission management per project
- [OAuth Integration Guide](../../02-developer-guide/03-oauth-integration.md) - Technical implementation of OAuth settings
- [API Integration](/en/developer-guide/api-integration) - User management via API
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/07-settings/02-api-key-management.md
+134
View File
@@ -0,0 +1,134 @@
---
title: API Key Settings
description: This document explains how to create, manage, and maintain security for API keys used for external system integration in ABC User Feedback.
sidebar_position: 2
---
# API Key Settings
API keys are authentication means that allow external systems to securely integrate with ABC User Feedback. This document explains API key creation, management, and security maintenance from a UI perspective.
![api-key-setting.png](/img/api-key/api-key-setting.png)
---
## API Key Overview
### Role of API Keys
API keys are used for the following purposes:
- **External system authentication**: Send feedback from websites, mobile apps
- **Automation integration**: Data collection through batch jobs, scripts
- **Third-party tool connection**: Integration with analysis tools, monitoring systems
- **Security control**: Independent access permission management per project
### Security Features
- **Per-project independence**: Separate keys issued for each project
- **Status management**: Can be controlled immediately with Active/Inactive status
---
## Creating API Keys
### Access Method
1. Click **Settings** in the top menu
2. Select **API Key Management** from the left menu
### Key Creation Process
#### 1. Click Create Button
Click the **Create API Key** button at the top right of the API Key Management screen.
#### 2. Auto Generation and Display
A new API key is automatically generated and displayed in a popup immediately upon clicking the button.
**Popup Components**:
- **API Key Value**: Displays the full key string
- **Copy Button**: Instantly copies to clipboard
---
## Managing API Key List
### Key List Screen Structure
Created API keys are managed in table format.
#### Table Column Information
| Column | Description | Display Format |
| ----------- | ------------------------- | ----------------------------- |
| **API Key** | Generated key value | `AbcdEfgh...` |
| **Status** | Current activation status | Active / Inactive |
| **Created** | Key creation date/time | `2024-03-15 14:30` |
| **Actions** | Management action buttons | Status change, delete buttons |
#### Key Identification Method
Since the full key value cannot be viewed again, distinguish keys using the following methods:
- **Creation time**: Check when the key was created
- **Usage purpose memo**: Record the key's purpose separately
---
## API Key Status Management
![api-key-detail.png](/img/api-key/api-key-detail.png)
### Active / Inactive Toggle
Each API key can be activated/deactivated immediately.
#### Status Meanings
| Status | Description | API Call Result |
| ------------ | ------------------------------ | ----------------- |
| **Active** | Available for actual API calls | Normal processing |
| **Inactive** | Call blocked state | 401 Unauthorized |
#### Status Change Method
1. Click the toggle switch in the **Status** column of the API key list
2. Status changes immediately and is reflected on screen
3. External systems using that key are immediately affected
---
## Deleting API Keys
### When to Delete
API keys should be deleted in the following cases:
- **Key exposure**: When a key is accidentally made public
- **Project termination**: When use of that project ends
- **Security policy**: According to regular key rotation policy
- **Unused keys**: Cleanup of keys no longer in use
### Deletion Method
#### 1. Click Delete Button
Click the delete button in the **Actions** column of the key you want to delete in the key list.
#### 2. Confirm Deletion
Approve deletion in the confirmation dialog.
#### 3. Deletion Complete
When you click the **Delete** button, the key is immediately deleted and removed from the list.
---
## Related Documents
- [API Integration Guide](/en/developer-guide/api-integration) - Actual integration implementation using API keys
- [Project Management](/en/user-guide/project-management) - API key management per project
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/07-settings/03-issue-tracker-management.md
+167
View File
@@ -0,0 +1,167 @@
---
title: Issue Tracker Settings
description: This guide explains how to integrate ABC User Feedback issues with external issue trackers (Jira, etc.) to track and link issues.
sidebar_position: 3
---
# Issue Tracker Settings
With issue tracker settings, you can integrate ABC User Feedback issues with external issue management systems (Jira, etc.). You can link external ticket links to internal issues to naturally integrate with development workflows.
---
## Issue Tracker Overview
### Purpose of Integration
Issue tracker integration is used for the following purposes:
- **Workflow integration**: Connect customer feedback with development work
- **Issue tracking**: One-to-one mapping between internal issues and external tickets
- **Progress sharing**: Synchronize information between development and customer support teams
- **Efficiency improvement**: Prevent duplicate work and maintain context
### Integration Method
- **Manual link connection**: Manually enter external ticket numbers in ABC issues
- **Automatic URL generation**: Automatically generate links with configured Base URL and Project Key
- **Click navigation**: Click generated links to immediately navigate to external systems
> **Note**: Real-time bidirectional synchronization is not supported. If synchronization such as status changes is needed, use [Webhook](./04-webhook-management.md).
---
## Accessing Settings Screen
### Access Method
1. Click **Settings** in the top menu
2. Select **Issue Tracker Management** from the left menu
### Settings Screen Structure
The issue tracker management screen is structured as follows:
- **Issue Tracking System**: Dropdown to select system to integrate
- **Connection Settings**: Area to enter connection information
- **Link Preview**: Preview of links to be generated
- **Test Connection**: Connection test button
---
## Jira Integration Settings
### System Selection
#### 1. Issue Tracking System Setting
Select **Jira** from the dropdown.
### Entering Connection Information
#### 2. Base URL Setting
Enter the base address of the Jira system.
| Input Example | Description |
| --------------------------------------- | ------------------------------ |
| `https://yourcompany.atlassian.net` | Jira Cloud instance |
| `https://jira.company.com` | Self-hosted Jira Server |
| `https://jira.internal:8080` | Internal network Jira |
**Notes**:
- Must include `https://` or `http://` protocol
- Remove trailing slash (`/`)
- Include port number if present
#### 3. Project Key Setting
Enter the unique key of the Jira project.
| Input Example | Description |
| ------------- | --------------------------- |
| `PROJ` | Common project key |
| `DEV` | Development team project |
| `CS` | Customer support team project |
| `BUG` | Bug management dedicated |
**How to Check Project Key**:
1. Access the project in Jira
2. The part before `-` in the issue number is the Project Key
3. Example: In `PROJ-123`, `PROJ` is the Project Key
### Link Preview
You can preview the links that will be generated based on the configured information.
#### Preview Structure
```
Base URL + /browse/ + Project Key + - + Issue Number
```
**Example**:
- Base URL: `https://yourcompany.atlassian.net`
- Project Key: `PROJ`
- Issue Number: `123` (entered by user)
- **Generated Link**: `https://yourcompany.atlassian.net/browse/PROJ-123`
#### Link Format Validation
Use the preview to check the following:
- Whether the URL format is correct
- Whether actual Jira issues are accessible
- Whether team members have access permissions
---
## Linking Tickets to Issues
### Entering Ticket Number
After issue tracker settings are complete, you can link external tickets to individual issues.
#### Linking Method
1. Click the desired issue in the **Issue** tab
2. The **Issue Details** panel opens on the right
3. Enter the external ticket number in the **Ticket** field
#### Input Format
| Input Method | Description | Generated Link |
| ----------- | ----------- | -------------------------------------------- |
| `123` | Enter only number | `https://jira.company.com/browse/PROJ-123` |
The system automatically adds the Project Key, so you only need to enter the number.
### Automatic Link Generation
After entering the ticket number, click the **Save** button to automatically generate the link.
#### Link Features
- **Click navigation**: Clicking the link opens the external Jira issue in a new tab
- **External link display**: External link icon displayed next to the link
- **Editable**: Can change ticket number in Edit mode
### Unlinking
To remove external ticket connection:
1. Click the **Edit** button in the issue detail panel
2. Delete the content in the **Ticket** field
3. Save changes with the **Save** button
---
## Related Documents
- [Issue Management](/en/user-guide/issue-management) - How to create issues and link tickets
- [Webhook Management](/en/user-guide/settings/webhook-management) - External system notifications when issue status changes
- [API Integration Guide](/en/developer-guide/api-integration) - Issue management via API
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/07-settings/04-webhook-management.md
+172
View File
@@ -0,0 +1,172 @@
---
sidebar_position: 4
title: 'Webhook Settings'
description: 'This document explains how to set up webhooks for automatic integration with external systems and send notifications when events occur.'
---
# Webhook Settings
Webhooks are a feature that **automatically sends notifications to external systems when specific events occur** in ABC User Feedback. You can deliver events such as feedback creation and issue status changes in real-time to external services (Slack, Discord, your own server, etc.). For detailed integration guide, refer to the [Webhook Integration](/en/developer-guide/webhook-integration) document.
![webhook-setting](/img/webhook/webhook-setting.png)
---
## Access Method
1. Click **Settings** in the top menu
2. Select **Webhook Integration** from the left menu
---
## Webhook Integration Screen Overview
![webhook-list.png](/img/webhook/webhook-list.png)
The webhook integration screen is structured as follows:
### Webhook List Table Structure
| Column | Description |
| ----------------- | --------------------------------------------- |
| **On/Off** | Webhook activation/deactivation toggle switch |
| **Name** | Webhook name |
| **URL** | External endpoint to receive notifications |
| **Event Trigger** | Subscribed event triggers |
| **Created** | Webhook creation date/time |
---
## Creating New Webhooks
![webhook-create](/img/webhook/webhook-create.png)
### 1. Start Webhook Registration
Click the **Register Webhook** button at the top right to open the webhook registration modal.
### 2. Enter Basic Information
#### Required Input Items
| Item | Description |
| -------- | -------------------------------------- |
| **Name** | Name for webhook identification |
| **URL** | Endpoint to receive HTTP POST requests |
### 3. Token Setting (Optional)
You can set a token for authentication in the **Token** field:
- Click the **Generate** button to auto-generate
- Or enter token value directly
### 4. Event Trigger Selection
You can select events to subscribe to per channel:
#### Supported Event Types
For each channel (VOC, Review, Survey, VOC Test), you can select the following events:
| Event Type | Description |
| ----------------------- | -------------------------------- |
| **Feedback Creation** | When new feedback is registered |
| **Issue Registration** | When new issue is created |
| **Issue Status Change** | When issue status is changed |
| **Issue Creation** | When issue is linked to feedback |
### 5. Save Webhook
After entering all information:
1. Click the **OK** button to create the webhook
2. You can cancel with the **Cancel** button
---
## Webhook Status Management
### Activation/Deactivation Toggle
You can change the status by clicking the toggle switch in the **On/Off** column of each webhook in the webhook list:
- **On (Active)**: Real-time transmission when events occur
- **Off (Inactive)**: Webhook is maintained but transmission is stopped
### Temporary Deactivation Scenarios
- When external server is under maintenance
- When changing webhook URL
- When spam notifications need to be prevented
---
## Webhook Editing and Deletion
### Webhook Editing
Click the webhook you want to edit in the webhook list to open the edit modal:
#### Editable Items
- Webhook name
- Target URL change
- Token value modification
- Event type addition/removal
### Webhook Deletion
To completely remove a webhook:
1. Select delete option in the edit modal
2. Or click delete button directly in the list (if delete button exists in UI)
---
## Webhook Testing and Validation
### Manual Validation Method
1. **Feedback Creation Test**:
- Register test feedback to check `Feedback Creation` event
2. **Issue Management Test**:
- Create issues or change status to check related events
3. **External Service Check**:
- Check message reception in Slack, Discord, etc.
---
## Common Integration Examples
### Slack Webhook Settings
```
Name: Slack Notifications
URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX
Events: Feedback Creation, Issue Registration (all channels)
```
### Discord Webhook Settings
```
Name: Discord Development Team Notifications
URL: https://discord.com/api/webhooks/123456789/abcdefghijk
Events: Issue Status Change (VOC channel only)
```
### Custom Server Integration
```
Name: Internal Analysis System
URL: https://api.yourcompany.com/webhooks/feedback
Token: your-generated-token
Events: All events (all channels)
```
---
## Related Documents
- [Webhook Developer Guide](/en/developer-guide/webhook-integration) - How to implement webhook receiving server
- [API Key Management](./02-api-key-management.md) - API key-based authentication settings
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/07-settings/05-ai-setting.md
+272
View File
@@ -0,0 +1,272 @@
---
sidebar_position: 5
title: 'AI Settings'
description: 'This document explains basic settings and integration methods for using generative AI features.'
---
# AI Settings
To use **generative AI features** in ABC User Feedback, you must first set up integration with an AI provider.
After completing AI settings, you can use all features such as **AI Field Templates**, **AI Issue Recommendations**, and **AI Usage Monitoring**.
---
## Access Method
1. Click **Settings** in the top menu
2. Select **Generative AI Integration** from the left menu
3. Click **AI Setting** in the top tabs
---
## AI Provider Selection and Settings
![ai-setting.png](/img/ai/ai-setting.png)
### 1. Provider Selection
Select one of the currently supported AI providers: OpenAI, Google Gemini:
### 2. API Key Input
Enter the API key issued from the selected AI provider.
### 3. Base URL Setting (Optional)
In most cases, **leave it empty** and the default value will be used automatically.
Enter only when using special endpoints or proxy servers.
### 4. System Prompt Setting (Optional)
You can set **basic instructions** that the AI will reference when processing all requests.
Use this when you have organizational tone and manner or special requirements.
### 5. Save Settings
After entering all information, click the **Save** button at the top right.
---
## AI Usage Monitoring
![ai-usage.png](/img/ai/ai-usage.png)
You can monitor AI feature usage and costs in the **AI Usage** tab.
### Usage Dashboard
Information you can check:
- **Daily/monthly API call count**
- **Token usage** (input/output separately)
- **Usage distribution by feature** (AI fields vs issue recommendations)
---
## AI Field Template Management
![ai-field-template.png](/img/ai/ai-field-template.png)
After completing AI settings, you can manage automatic feedback analysis templates in the **AI Field Template** tab.
### Default Templates
Default templates provided by the system:
| Template | Description | Usage Example |
| ---------------------- | ---------------------------------------------- | ---------------------------------------- |
| **Feedback Summary** | Summarize feedback in one sentence | Grasp core of long feedback |
| **Sentiment Analysis** | Sentiment analysis (positive/negative/neutral) | Analyze customer satisfaction trends |
| **Translation** | Translate feedback to English | Integrate multilingual feedback analysis |
| **Keyword Extraction** | Extract 2-3 core keywords | Auto-tag issue categories |
### Creating Custom Templates
![ai-field-template-create.png](/img/ai/ai-field-template-create.png)
1. Click the **Create New** card
2. Enter template information
| Item | Description |
| --------------- | ------------------------------- |
| **Title** | Template name |
| **Prompt** | Instruction sentence for AI |
| **Model** | Select AI model to use |
| **Temperature** | Creativity adjustment (0.0~1.0) |
3. Test in Playground
- Enter test feedback with "Add Data" button
- Check results by clicking "AI test execution"
### Template Editing and Deletion
- Click template card → edit
- Delete with **Delete Template** button
- Deletion may affect AI fields using that template
---
## Applying AI Fields to Channels
After creating AI field templates, you must apply them as actual channel fields to view AI analysis results in feedback.
### 1. Add AI Field in Field Management
Add AI fields in **Settings > Channel List > [Select Channel] > Field Management**.
#### AI Field Setting Items
| Item | Description | Required |
| ----------------------- | -------------------------------- | -------- |
| **Key** | Unique field identifier | Required |
| **Display Name** | Name displayed in UI | Required |
| **Format** | Select `aiField` | Required |
| **Template** | Select created AI field template | Required |
| **Target Field** | Text field to be analyzed | Required |
| **Property** | Editable or Read Only | Required |
| **AI Field Automation** | Auto execution | Optional |
#### Setting Example
```
Key: sentiment_analysis
Display Name: Sentiment Analysis
Format: aiField
Template: Feedback Sentiment Analysis
Target Field: message
Property: Read Only
AI Field Automation: ON (auto execution)
```
### 2. Template Connection and Target Field Setting
Select the AI field template created earlier from the **Template** dropdown.
**Target Field** specifies the fields to be analyzed by AI
### 3. AI Field Automation Setting
Select execution method through **AI Field Automation** toggle:
- **ON (Auto execution)**: Automatically execute AI analysis when new feedback is registered
- **OFF (Manual execution)**: User must manually click execution button
## Checking AI Analysis Results in Feedback
After AI field settings are complete, you can check AI analysis results in the feedback list and detail screens.
### Checking in Feedback List
AI fields are added as new columns in the feedback table:
- **Summary**: Summary generated by AI
- **Classification**: AI classification results
- **Korean**: Translation results, etc.
### Checking in Feedback Detail Screen
You can check more detailed AI analysis results in the feedback detail view panel:
1. Click feedback row → right detail panel opens
2. Check AI analysis results by field
3. Displayed with analysis results for each AI field
## Manual AI Analysis Execution
You can manually execute AI analysis in the feedback detail screen.
### Using Run AI Button
1. Click **Run AI** button in feedback detail screen
2. AI analysis executes and results are automatically entered in that field
3. Results can be checked immediately after analysis completes
### Manual Execution Usage Scenarios
- **Cost savings**: Select only needed feedback for AI analysis
- **Performance check**: Test results of new templates in advance
- **Re-analysis**: Re-analyze existing feedback after template modification
---
## AI Issue Recommendation Settings
![ai-issue-recommendation.png](/img/ai/ai-issue-recommendation.png)
You can set up automatic issue recommendation features based on feedback in the **AI Issue Recommendation** tab.
### Creating AI Issue Recommendation Settings
![ai-issue-recommendation-create.png](/img/ai/ai-issue-recommendation-create.png)
1. Click **Create New** button
2. Enter setting items
| Item | Description | Required |
| ---------------- | -------------------------------- | -------- |
| **Channel** | Select channel to apply | Required |
| **Target Field** | Field to analyze (e.g., message) | Required |
| **Prompt** | Recommendation criteria prompt | Optional |
| **Enable** | Feature activation toggle | Required |
3. Advanced Settings
| Setting | Description |
| ------------------------- | ----------------------------------------------------------- |
| **Model** | Model to use |
| **Temperature** | Creativity adjustment |
| **Data Reference Amount** | Amount of issues to reference (issues and related feedback) |
### Testing AI Issue Recommendation Feature
Test in Playground with entered settings:
1. Enter example feedback
2. Click "AI test execution"
3. Check recommended issue list
### Using Recommendations in Actual Feedback
In feedback detail view:
- Check AI recommended issue list
- Select appropriate issues with checkboxes
- Request different recommendations with **Retry** button
### Using Issue Recommendations in Feedback List
In channels with AI issue recommendations configured, you can also use issue recommendation features directly in the feedback list screen.
#### Usage Method
1. Click the **+ button** in the **Issue column** of the feedback you want to link issues to in the feedback list
2. When dropdown menu appears, select **"Run AI"**
3. AI analyzes related issues and displays recommendation list
#### Checking and Applying Recommendation Results
After AI analysis completes, from the recommended issue list:
- Check **recommended issues**
- Select appropriate recommended issues
- Option to create new issues also provided
- After selection, that issue is automatically linked to feedback
#### Batch Processing Usage
You can use AI issue recommendations even when multiple feedback are selected, enabling efficient feedback classification:
1. Select multiple rows in feedback list (using checkboxes)
2. Execute AI issue recommendations from top batch operation menu
3. Check and apply recommended issues for each feedback
---
## Related Documents
- [Field Settings](/en/user-guide/feedback-management) - How to apply AI fields to channels
- [Issue Creation and Status Management](/en/user-guide/issue-management) - How to use AI recommended issues
- [Feedback Checking and Filtering](/en/user-guide/feedback-management) - How to check AI analysis results
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/07-settings/06-image-setting.md
+102
View File
@@ -0,0 +1,102 @@
---
sidebar_position: 6
title: 'Image Settings'
description: 'This guide explains how to set up image storage methods and security policies for images attached to feedback.'
---
# Image Settings
ABC User Feedback supports **uploading images along with feedback** when users submit feedback. You can build a safe and efficient feedback collection environment by appropriately setting image storage methods and security policies.
![image-setting.png](/img/image/image-setting.png)
---
## Access Method
1. Click **Settings** in the top menu
2. Select **Channel List > [Select Channel]** from the left menu
3. Select **Image Management** from the bottom tabs
---
## Image Storage Integration Settings
S3 or S3-compatible storage integration is required to upload images directly to the server via **Multipart Upload API** or use **Presigned URL Download** functionality.
### Required Setting Items
| Item | Description | Example |
| --------------------- | ------------------------------------- | ----------------------------------------- |
| **Access Key ID** | Key ID for S3 access | `AKIAIOSFODNN7EXAMPLE` |
| **Secret Access Key** | Secret for the key | `wJalrXUtnFEMI/K7MDENG/...` |
| **End Point** | S3 API endpoint URL | `https://s3.ap-northeast-1.amazonaws.com` |
| **Region** | Region where bucket is located | `ap-northeast-1` |
| **Bucket Name** | Target bucket where images are stored | `consumer-ufb-images` |
### Presigned URL Download Settings
You can enhance image download security through the **Presigned URL Download** option.
#### Setting Options
- **Enable**: Access images through authenticated one-time URLs (enhanced security)
- **Disable**: Image URLs are directly exposed and publicly accessible
### Connection Test
After entering all settings, click the **Test Connection** button to verify storage connection.
Connection results:
- ✅ **Success**: "Connection test succeeded" message
- ❌ **Failure**: Recheck input values, bucket permissions, network settings
---
## Image URL Domain Whitelist Settings
When using **Image URL method** or wanting to enhance security, you can set a whitelist to allow only trusted domains.
### Current Status Check
Default setting is **"All image URLs are allowed"** state, allowing image URLs from all domains.
### Adding to Whitelist
To allow only specific domains for security enhancement:
1. Add trusted domains in the **Whitelist** area
2. Example domains:
- `cdn.yourcompany.com`
- `images.trusted-partner.io`
- `storage.googleapis.com`
---
## Supported Storage Services
### AWS S3
- Most commonly used cloud storage
- Stable and highly scalable
---
## Saving Settings
After completing all settings, click the **Save** button at the top right to save changes.
After saving:
- New image uploads work according to configured method
- Existing images remain with existing settings
- Recommended to recheck normal operation with Test Connection
---
## Related Documents
- [Field Settings](/en/user-guide/feedback-management) - How to add image fields to feedback forms
- [Feedback Checking and Filtering](/en/user-guide/feedback-management) - How to check uploaded images in feedback
- [API Key Management](./02-api-key-management.md) - API key security management methods
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/07-settings/_category_.json
+5
View File
@@ -0,0 +1,5 @@
{
"position": 7,
"label": "Settings",
"description": "Guide for settings."
}
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/07-settings/index.md
+8
View File
@@ -0,0 +1,8 @@
---
title: Settings
description: Guide for settings.
---
import DocCardList from '@theme/DocCardList';
<DocCardList />
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/_category_.json
+5
View File
@@ -0,0 +1,5 @@
{
"position": 2,
"label": "User Guide"
}
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/01-user-guide/index.md
+7
View File
@@ -0,0 +1,7 @@
---
title: User Guide
---
import DocCardList from '@theme/DocCardList';
<DocCardList />
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/01-docker-hub-images.md
+375
View File
@@ -0,0 +1,375 @@
---
id: docker-hub-images
title: Docker Hub Image Installation
description: This document explains how to quickly install the system using the official ABC User Feedback images registered on Docker Hub.
sidebar_position: 1
---
# Docker Hub Image Installation
ABC User Feedback provides official Docker images.
This document explains how to quickly set up the system locally using Docker Compose, including **Web UI, API server, database, SMTP server**, etc.
---
## 1. Prerequisites
| Item | Description |
| -------------- | ------------------------------------------------------------------------ |
| Docker | 20.10 or higher |
| Docker Compose | v2 or higher recommended |
| Ports Used | `3000`, `4000`, `13306`, `5080`, `25` (must be free on local machine) |
---
## 2. Docker Image Configuration
| Service Name | Description | Docker Image Name |
| ----------------- | ----------------------------------------- | ------------------------------------ |
| Web (Admin UI) | Frontend web UI (Next.js) | `line/abc-user-feedback-web` |
| API (Backend) | Backend server (NestJS) | `line/abc-user-feedback-api` |
| MySQL | Database | `mysql:8.0` |
| SMTP4Dev | Email server for local testing | `rnwood/smtp4dev:v3` |
| (Optional) OpenSearch | For search functionality and improved AI analysis accuracy | `opensearchproject/opensearch:2.16.0` |
---
## 3. `docker-compose.yml` Example
```yaml
name: abc-user-feedback
services:
web:
image: line/abc-user-feedback-web:latest
environment:
- NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
ports:
- 3000:3000
depends_on:
- api
restart: unless-stopped
api:
image: line/abc-user-feedback-api:latest
environment:
- JWT_SECRET=jwtsecretjwtsecretjwtsecret
- MYSQL_PRIMARY_URL=mysql://userfeedback:userfeedback@mysql:3306/userfeedback
- SMTP_HOST=smtp4dev
- SMTP_PORT=25
- SMTP_SENDER=user@feedback.com
# Uncomment below if using OpenSearch
# - OPENSEARCH_USE=true
# - OPENSEARCH_NODE=http://opensearch-node:9200
ports:
- 4000:4000
depends_on:
- mysql
restart: unless-stopped
mysql:
image: mysql:8.0
command:
[
"--default-authentication-plugin=mysql_native_password",
"--collation-server=utf8mb4_bin",
]
environment:
MYSQL_ROOT_PASSWORD: userfeedback
MYSQL_DATABASE: userfeedback
MYSQL_USER: userfeedback
MYSQL_PASSWORD: userfeedback
TZ: UTC
ports:
- 13306:3306
volumes:
- mysql:/var/lib/mysql
restart: unless-stopped
smtp4dev:
image: rnwood/smtp4dev:v3
ports:
- 5080:80
- 25:25
- 143:143
volumes:
- smtp4dev:/smtp4dev
restart: unless-stopped
# Uncomment below if you want to use OpenSearch
# opensearch-node:
# image: opensearchproject/opensearch:2.16.0
# restart: unless-stopped
# environment:
# - cluster.name=opensearch-cluster
# - node.name=opensearch-node
# - discovery.type=single-node
# - bootstrap.memory_lock=true
# - 'OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m'
# - plugins.security.disabled=true
# - OPENSEARCH_INITIAL_ADMIN_PASSWORD=UserFeedback123!@#
# ulimits:
# memlock:
# soft: -1
# hard: -1
# nofile:
# soft: 65536
# hard: 65536
# volumes:
# - opensearch:/usr/share/opensearch/data
# ports:
# - 9200:9200
# - 9600:9600
volumes:
mysql:
smtp4dev:
# opensearch:
```
---
## 4. Execution Steps
### 4.1 Download and Run Docker Images
```bash
# Run all services in the background using Docker Compose
docker compose up -d
```
### 4.2 Check Running Status
```bash
# Check if all containers are running normally
docker compose ps
```
### 4.3 Check Service Access
- **Web Application**: [http://localhost:3000](http://localhost:3000)
- **API Server**: [http://localhost:4000](http://localhost:4000)
- **SMTP Test Page**: [http://localhost:5080](http://localhost:5080)
- **MySQL Database**: `localhost:13306` (user: `userfeedback`, password: `userfeedback`)
---
## 5. SMTP Configuration
By default, this configuration allows you to test emails through `smtp4dev`.
- **Web Interface**: [http://localhost:5080](http://localhost:5080)
- **SMTP Port**: `25`
- **IMAP Port**: `143`
### SMTP Testing Method
1. Register a user or use the user invitation feature in the web application
2. Check sent emails at [http://localhost:5080](http://localhost:5080)
3. Test email content and attachments
> **Important**: In actual production environments, you must integrate with an external SMTP server (e.g., Gmail, SendGrid, corporate SMTP, etc.).
## 6. Installation Verification
### 6.1 Web Application Access Verification
Access `http://localhost:3000` in your browser and verify:
- Tenant creation screen displays normally
- Page loading completes
- No JavaScript errors (check in browser developer tools)
### 6.2 API Server Status Check
```bash
# API server health check
curl http://localhost:4000/api/health
```
Expected response:
```json
{
"status": "ok",
"info": {
"database": {
"status": "up"
}
}
}
```
### 6.3 Database Connection Verification
```bash
# Directly access MySQL container to check database
docker compose exec mysql mysql -u userfeedback -puserfeedback -e "SHOW DATABASES;"
# Check table creation
docker compose exec mysql mysql -u userfeedback -puserfeedback -e "USE userfeedback; SHOW TABLES;"
```
### 6.4 Log Check
```bash
# Check logs for all services
docker compose logs
# Check logs for specific service only
docker compose logs api
docker compose logs web
docker compose logs mysql
```
---
## 7. OpenSearch Usage Notes
OpenSearch is an optional component that improves search functionality and AI analysis accuracy.
### 7.1 How to Enable OpenSearch
1. Uncomment environment variables in the `api` service in `docker-compose.yml`:
```yaml
- OPENSEARCH_USE=true
- OPENSEARCH_NODE=http://opensearch-node:9200
```
2. Uncomment the `opensearch-node` service
3. Uncomment `opensearch:` in the `volumes:` section
4. Ensure ports `9200`, `9600` are not in use on local machine
### 7.2 Memory Requirements
> **Warning**: OpenSearch requires at least 2GB of memory. If memory is insufficient, the container may automatically terminate.
### 7.3 OpenSearch Status Check
```bash
# Check OpenSearch cluster status
curl http://localhost:9200/_cluster/health
# Check OpenSearch node information
curl http://localhost:9200/_nodes
# Check indices
curl http://localhost:9200/_cat/indices
```
### 7.4 Disabling OpenSearch
To not use OpenSearch, comment out the corresponding service and environment variables in `docker-compose.yml`.
---
## 8. Troubleshooting
### 8.1 Port Conflict Issue
**Symptom**: Port binding error occurs when running `docker compose up`
**Solution**:
```bash
# Check ports in use
lsof -i :3000 # Web port
lsof -i :4000 # API port
lsof -i :13306 # MySQL port
lsof -i :5080 # SMTP port
# Stop processes using those ports and restart
docker compose down
docker compose up -d
```
### 8.2 Container Startup Failure
**Symptom**: Some containers fail to start or keep restarting
**Solution**:
```bash
# Check container status
docker compose ps
# Check logs for failed container
docker compose logs [service-name]
# Stop and remove all containers
docker compose down
# Remove volumes as well (warning: data loss)
docker compose down -v
# Start again
docker compose up -d
```
### 8.3 Database Connection Error
**Symptom**: MySQL connection failure from API server
**Solution**:
```bash
# Wait until MySQL container is fully started
docker compose logs mysql
# Test direct connection to MySQL container
docker compose exec mysql mysql -u userfeedback -puserfeedback -e "SELECT 1;"
# Restart API service
docker compose restart api
```
### 8.4 Image Download Failure
**Symptom**: Cannot download Docker images
**Solution**:
```bash
# Check Docker Hub login
docker login
# Manually download images
docker pull line/abc-user-feedback-web:latest
docker pull line/abc-user-feedback-api:latest
# Check network connection
ping hub.docker.com
```
### 8.5 Memory Insufficient Issue
**Symptom**: OpenSearch container automatically terminates
**Solution**:
```bash
# Check system memory
free -h
# Check Docker memory usage
docker stats
# Disable OpenSearch (comment out in docker-compose.yml)
# Or increase memory allocation
```
---
## 9. Reference Links
- [ABC User Feedback Web - Docker Hub](https://hub.docker.com/r/line/abc-user-feedback-web)
- [ABC User Feedback API - Docker Hub](https://hub.docker.com/r/line/abc-user-feedback-api)
- [smtp4dev - Docker Hub](https://hub.docker.com/r/rnwood/smtp4dev)
- [OpenSearch - Docker Hub](https://hub.docker.com/r/opensearchproject/opensearch)
---
## Related Documents
- [Initial Setup Guide](/en/user-guide/getting-started)
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/02-cli-tool.md
+273
View File
@@ -0,0 +1,273 @@
---
sidebar_position: 2
title: "CLI Tool Usage"
description: "This document explains how to quickly and easily install and manage the system using the ABC User Feedback CLI tool."
---
# CLI Tool Usage
The ABC User Feedback CLI (`auf-cli`) is a command-line tool that simplifies system installation, execution, and management. As long as Node.js and Docker are installed, you can run it immediately via `npx` without installing additional dependencies or cloning the repository.
## Main Features
- Automatic setup of required infrastructure (MySQL, SMTP, OpenSearch)
- Simplified environment variable configuration
- Automatic start/stop of API and web servers
- Volume data cleanup
- Dynamic Docker Compose file generation
## Docker Images Used
- `line/abc-user-feedback-web:latest` - Web frontend
- `line/abc-user-feedback-api:latest` - API backend
- `mysql:8.0` - Database
- `rnwood/smtp4dev:v3` - SMTP test server
- `opensearchproject/opensearch:2.16.0` - Search engine (optional)
## Prerequisites
Before using the CLI tool, you must meet the following requirements:
- [Node.js v22 or higher](https://nodejs.org/en/download/)
- [Docker](https://docs.docker.com/desktop/)
## Basic Commands
### Initialization
To set up the infrastructure required for ABC User Feedback, run the following command:
```bash
npx auf-cli init
```
This command performs the following tasks:
1. Creates `config.toml` file for environment variable configuration
2. Sets up required infrastructure according to architecture (ARM/AMD)
After initialization is complete, a `config.toml` file is created in the current directory. You can edit this file as needed to adjust environment variables.
### Starting Server
To start the API and web servers, run the following command:
```bash
npx auf-cli start
```
This command performs the following tasks:
1. Reads environment variables from `config.toml` file
2. Generates Docker Compose file and starts services
3. Starts API and web server containers and required infrastructure (MySQL, SMTP, OpenSearch)
After the server starts successfully, you can access the ABC User Feedback web interface at `http://localhost:3000` (or configured URL) in your web browser. The CLI displays the following URLs:
- Web interface URL
- API URL
- MySQL connection string
- OpenSearch URL (if enabled)
- SMTP web interface (when using smtp4dev)
### Stopping Server
To stop the API and web servers, run the following command:
```bash
npx auf-cli stop
```
This command stops running API and web server containers and infrastructure containers. All data stored in volumes is preserved.
### Volume Cleanup
To clean up Docker volumes created during startup, run the following command:
```bash
npx auf-cli clean
```
This command stops all containers and deletes Docker volumes for MySQL, SMTP, OpenSearch, etc.
**Warning**: This operation deletes all data, so back up if needed.
You can also clean up unused Docker images using the `--images` option:
```bash
npx auf-cli clean --images
```
## Configuration File (config.toml)
Running the `init` command creates a `config.toml` file in the current directory. This file is used to configure environment variables for ABC User Feedback.
The following is an example of a `config.toml` file:
```toml
[web]
port = 3000
# api_base_url = "http://localhost:4000"
[api]
port = 4000
jwt_secret = "jwtsecretjwtsecretjwtsecretjwtsecretjwtsecretjwtsecret"
# master_api_key = "MASTER_KEY"
# access_token_expired_time = "10m"
# refresh_token_expired_time = "1h"
# [api.auto_feedback_deletion]
# enabled = true
# period_days = 365
# [api.smtp]
# host = "smtp4dev" # SMTP_HOST
# port = 25 # SMTP_PORT
# sender = "user@feedback.com"
# username=
# password=
# tls=
# cipher_spec=
# opportunitic_tls=
# [api.opensearch]
# enabled = true
[mysql]
port = 13306
```
You can edit this file as needed to adjust environment variables. For detailed information on environment variables, refer to the [Environment Variable Settings](./05-configuration.md) document.
## Advanced Usage
### Changing Ports
By default, the web server uses port 3000 and the API server uses port 4000. To change these, modify the following settings in the `config.toml` file:
```toml
[web]
port = 8000 # Change web server port
api_base_url = "http://localhost:8080" # API URL must also be changed
[api]
port = 8080 # Change API server port
[mysql]
port = 13307 # Change MySQL port if needed
```
### Enabling OpenSearch
To enable OpenSearch for advanced search features:
```toml
[api.opensearch]
enabled = true
```
**Notes**:
- OpenSearch requires at least 2GB of available memory
- OpenSearch container is available at `http://localhost:9200`
- Check OpenSearch status: `http://localhost:9200/_cluster/health`
### SMTP Settings
For development environments, the default `smtp4dev` settings are recommended:
```toml
[api.smtp]
host = "smtp4dev"
port = 25
sender = "dev@feedback.local"
```
The smtp4dev web interface is available at `http://localhost:5080` to check sent emails.
## Troubleshooting
### Common Issues
1. **Docker-related errors**:
- Check if Docker is running: `docker --version`
- Check Docker permissions: `docker ps`
- Verify Docker Desktop is properly installed and running
2. **Port conflicts**:
- Check port usage: `lsof -i :PORT` (macOS/Linux) or `netstat -ano | findstr :PORT` (Windows)
- Change port settings in `config.toml`
- Common conflicting ports: 3000, 4000, 13306, 9200, 5080
3. **Service startup failure**:
- Check container logs: `docker compose logs SERVICE_NAME`
- Verify Docker images are available: `docker images`
- Check sufficient system resources (memory, disk space)
4. **Database connection issues**:
- Check MySQL container status: `docker compose ps mysql`
- Check MySQL logs: `docker compose logs mysql`
- Test connection: `docker compose exec mysql mysql -u userfeedback -p`
### Debugging Tips
1. **Check container logs**:
```bash
# All container logs
docker compose logs
# Specific service logs
docker compose logs api
docker compose logs web
docker compose logs mysql
```
2. **Check service status**:
```bash
# Check API status
curl http://localhost:4000/api/health
# Check OpenSearch status (if enabled)
curl http://localhost:9200/_cluster/health
```
3. **Direct database access**:
```bash
# Connect to MySQL
docker compose exec mysql mysql -u userfeedback -p userfeedback
```
## Limitations
The CLI tool is designed for development and testing environments. For production deployment, consider the following:
1. **Security Considerations**:
- Use environment variables instead of configuration files for sensitive data
- Implement proper secret management
- Use production-grade JWT secrets
- Enable HTTPS/TLS encryption
2. **Scalability and Availability**:
- Use orchestration tools like Kubernetes or Docker Swarm
- Implement load balancing and auto-scaling
- Set up proper monitoring and alerts
- Use managed database services (RDS, Cloud SQL, etc.)
3. **Data Management**:
- Implement automated backup strategies
- Use persistent volumes with proper backups
- Consider data retention policies
- Monitor disk usage and performance
## Next Steps
For detailed API and web server configuration options, refer to the [Environment Variable Settings](./05-configuration.md) document.
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/03-manual-setup.md
+276
View File
@@ -0,0 +1,276 @@
---
sidebar_position: 3
title: 'Manual Installation'
description: 'Manual installation guide for building and running ABC User Feedback directly from source code'
---
# Manual Installation
This document explains how to manually install and configure ABC User Feedback. This is useful when you want to build and run the application directly from source code.
## Prerequisites
Before proceeding with manual installation, you must meet the following requirements:
- [Node.js v22.19.0 or higher](https://nodejs.org/en/download/)
- [pnpm v10.15.0 or higher](https://pnpm.io/installation) (package manager)
- [Git](https://git-scm.com/downloads)
- [MySQL 8.0](https://www.mysql.com/downloads/)
- SMTP server
- (Optional) [OpenSearch 2.16](https://opensearch.org/)
## Downloading Source Code
First, clone the ABC User Feedback source code from the GitHub repository:
```bash
git clone https://github.com/line/abc-user-feedback.git
cd abc-user-feedback
```
## Infrastructure Setup
ABC User Feedback requires a MySQL database, SMTP server, and optionally OpenSearch. There are several ways to set up these infrastructure components.
### Infrastructure Setup Using Docker
The simplest method is to set up required infrastructure with Docker Compose:
```bash
docker-compose -f docker/docker-compose.infra.yml up -d
```
### Using Existing Infrastructure
If you already have MySQL, OpenSearch, or SMTP server, you can configure connection information as environment variables later.
## Installing Dependencies
ABC User Feedback uses a monorepo structure managed through TurboRepo. To install dependencies for all packages:
```bash
pnpm install
```
After installing dependencies, build all packages:
```bash
pnpm build
```
## Environment Variable Configuration
### API Server Environment Variables
Create a `.env` file in the `apps/api` directory and configure it by referring to `.env.example`:
```env
# Required environment variables
JWT_SECRET=DEV
MYSQL_PRIMARY_URL=mysql://userfeedback:userfeedback@localhost:13306/userfeedback # required
ACCESS_TOKEN_EXPIRED_TIME=10m # default: 10m
REFRESH_TOKEN_EXPIRED_TIME=1h # default: 1h
# Optional environment variables
# APP_PORT=4000 # default: 4000
# APP_ADDRESS=0.0.0.0 # default: 0.0.0.0
# MYSQL_SECONDARY_URLS= ["mysql://userfeedback:userfeedback@localhost:13306/userfeedback"] # optional
SMTP_HOST=localhost # required
SMTP_PORT=25 # required
SMTP_SENDER=user@feedback.com # required
# SMTP_USERNAME= # optional
# SMTP_PASSWORD= # optional
# SMTP_TLS= # default: false
# SMTP_CIPHER_SPEC= # default: TLSv1.2 if SMTP_TLS=true
# SMTP_OPPORTUNISTIC_TLS= # default: true if SMTP_TLS=true
# OPENSEARCH_USE=false # default: false
# OPENSEARCH_NODE= # required if OPENSEARCH_USE=true
# OPENSEARCH_USERNAME= # optional
# OPENSEARCH_PASSWORD= # optional
# AUTO_MIGRATION=true # default: true
# MASTER_API_KEY= # default: none
# BASE_URL=https://api.example.com # Public API server URL used in Swagger documentation (optional)
# AUTO_FEEDBACK_DELETION_ENABLED=false # default: false
# AUTO_FEEDBACK_DELETION_PERIOD_DAYS=365*5
```
### Web Server Environment Variables
Create a `.env` file in the `apps/web` directory and configure it by referring to `.env.example`:
```env
NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
```
For detailed information on environment variables, refer to the [Environment Variable Settings](./05-configuration.md) document.
## Database Migration
Before running the API server for the first time, you need to create the database schema. If you set the `AUTO_MIGRATION=true` environment variable, migrations will run automatically when the server starts.
To run migrations manually:
```bash
cd apps/api
npm run migration:run
```
## Running in Development Mode
### Running with Single Command
To run the API server and web server in development mode:
```bash
# From project root directory
pnpm dev
```
This command starts both the API server and web server simultaneously. The API server runs on port 4000 by default, and the web server runs on port 3000.
### Running Individual Packages
#### Building Common Packages
Before running the web application, you need to build shared packages:
```bash
# From project root directory
cd packages/ufb-shared
pnpm build
```
#### Building UI Packages
Before running the web application, you need to build UI packages:
```bash
# From project root directory
cd packages/ufb-tailwindcss
pnpm build
```
#### Running Each Server Individually
To run each server individually:
```bash
# Run API server only
cd apps/api
pnpm dev
# Run web server only
cd apps/web
pnpm dev
```
## Production Build
To build the application for production environment:
```bash
# From project root directory
pnpm build
```
This command builds both the API server and web server.
## Running in Production Mode
To run the production build:
```bash
# Run API server
cd apps/api
pnpm start
# Run web server
cd apps/web
pnpm start
```
## API Type Generation
When the backend API is running, you can generate API types for the frontend:
```bash
cd apps/web
pnpm generate-api-type
```
This command generates TypeScript types from OpenAPI specification and saves them to the `src/shared/types/api.type.ts` file.
**Note**: For this command to work properly, the API server must be running at `http://localhost:4000`.
## Code Quality Management
### Linting
To run code linting:
```bash
pnpm lint
```
### Formatting
To run code formatting:
```bash
pnpm format
```
### Testing
To run tests:
```bash
pnpm test
```
## Swagger Documentation
When the API server is running, you can check Swagger documentation at the following endpoints:
- **API Documentation**: http://localhost:4000/docs
- **Admin API Documentation**: http://localhost:4000/admin-docs
- **OpenAPI JSON**: http://localhost:4000/docs-json
- **Admin OpenAPI JSON**: http://localhost:4000/admin-docs-json
> **Note**: If you are serving the API server on a different URL (e.g., behind a reverse proxy), you can set the `BASE_URL` environment variable to generate correct API endpoint URLs in the Swagger documentation. Example: `BASE_URL=https://api.example.com`
## Troubleshooting
### Common Issues
1. **Dependency Installation Errors**:
- Verify Node.js version is v22.19.0 or higher.
- Verify pnpm version is v10.15.0 or higher.
- Update pnpm to the latest version.
- Try `pnpm install --force`.
2. **Database Connection Errors**:
- Verify MySQL server is running.
- Verify database credentials are correct.
- Verify `MYSQL_PRIMARY_URL` environment variable format is correct.
- If using Docker infrastructure, verify MySQL is running on port 13306 (not 3306).
3. **Build Errors**:
- Verify UI packages are built (`pnpm build:ui`).
- Verify all dependencies are installed.
- Check TypeScript errors.
4. **Runtime Errors**:
- Verify environment variables are set correctly.
- Verify required ports are available.
- Check error messages in logs.
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/04-smtp-configuration.md
+165
View File
@@ -0,0 +1,165 @@
---
id: smtp-configuration
title: SMTP Server Integration Guide
description: This guide explains how to integrate with external SMTP servers for sending authentication emails in production environments.
sidebar_position: 4
---
# SMTP Server Integration Guide
In production environments, instead of local test servers like `smtp4dev`,
you need to connect to **external SMTP servers (Gmail, SendGrid, company SMTP, etc.)**
to properly send authentication emails (registration, password reset, etc.).
This document explains environment variable configuration for SMTP server integration and major integration examples.
---
## 1. SMTP-Related Environment Variables
Set the following environment variables in the `api` service or `.env` file:
> **Note**: For SMTP servers that do not require authentication, `SMTP_USERNAME` and `SMTP_PASSWORD` can be omitted.
| Environment Variable | Description | Required |
| ---------------------------------- | ------------------------------------------------------ | -------- |
| `SMTP_HOST` | SMTP server address (e.g., smtp.gmail.com) | Required |
| `SMTP_PORT` | Port number (usually 587, 465, etc.) | Required |
| `SMTP_SENDER` | Sender email address (e.g., `noreply@yourdomain.com`) | Required |
| `SMTP_USERNAME` | SMTP authentication username (account ID) | Optional |
| `SMTP_PASSWORD` | SMTP authentication password or API key | Optional |
| `SMTP_TLS` | Whether to use TLS (`true` or `false`) | Optional |
| `SMTP_CIPHER_SPEC` | TLS encryption algorithm (default: `TLSv1.2`) | Optional |
| `SMTP_OPPORTUNISTIC_TLS` | Whether to use STARTTLS (`true` or `false`) | Optional |
> **Important**: In actual code, `SMTP_USERNAME` and `SMTP_PASSWORD` are used, and `SMTP_TLS=true` is mainly used for port 465, while `false` is mainly used for port 587.
---
## 2. Docker Environment Example
```yaml
api:
image: line/abc-user-feedback-api
environment:
- SMTP_HOST=smtp.gmail.com
- SMTP_PORT=587
- SMTP_USERNAME=your-email@gmail.com
- SMTP_PASSWORD=your-email-app-password
- SMTP_SENDER=noreply@yourdomain.com
- SMTP_TLS=false
- SMTP_OPPORTUNISTIC_TLS=true
```
Or you can manage it separately with a `.env` file:
```env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-email-app-password
SMTP_SENDER=noreply@yourdomain.com
SMTP_TLS=false
SMTP_OPPORTUNISTIC_TLS=true
```
---
## 3. SMTP Integration Examples
### ✅ Gmail SMTP Integration (for personal testing)
- `SMTP_HOST`: `smtp.gmail.com`
- `SMTP_PORT`: `587`
- `SMTP_USERNAME`: Gmail address (e.g., `abc@gmail.com`)
- `SMTP_PASSWORD`: **App password** (Allow less secure apps → not recommended)
- `SMTP_TLS`: `false`
- `SMTP_OPPORTUNISTIC_TLS`: `true`
> If **two-factor authentication** is enabled on your Gmail account, you must create an [app password](https://myaccount.google.com/apppasswords).
---
### ✅ SendGrid Integration (Recommended)
- `SMTP_HOST`: `smtp.sendgrid.net`
- `SMTP_PORT`: `587`
- `SMTP_USERNAME`: `apikey`
- `SMTP_PASSWORD`: Actual SendGrid API Key
- `SMTP_SENDER`: verified sender address
- `SMTP_TLS`: `false`
- `SMTP_OPPORTUNISTIC_TLS`: `true`
---
## 4. Testing Methods
### 4.1 Email Sending Test
1. **Email Verification Test**:
- Create admin or user account
- Verify email verification code is sent
2. **Password Reset Test**:
- Request password reset
- Verify email with reset link is received
3. **User Invitation Test**:
- Admin invites new user
- Verify invitation email is sent
### 4.2 Log Checking
If email sending fails, check detailed logs with the following command:
```bash
# Docker Compose environment
docker compose logs api
# Check logs for specific time period
docker compose logs --since=10m api
# Real-time log monitoring
docker compose logs -f api
```
If SMTP errors occur, detailed messages will be displayed in the logs.
---
## 5. Troubleshooting
| Problem Type | Cause or Solution |
| ----------------------------- | -------------------------------------- |
| Authentication Error (`535`) | Recheck `SMTP_USERNAME` / `SMTP_PASSWORD` |
| Connection Refused (`ECONNREFUSED`) | Firewall or incorrect port settings |
| Email Not Arriving | `SMTP_SENDER` is not verified |
| TLS Error (`ETLS`) | `SMTP_TLS` setting is incorrect |
| STARTTLS Failure | Check `SMTP_OPPORTUNISTIC_TLS` setting |
---
## 6. Email Templates Related to SMTP
Currently, emails are sent in the following situations:
- **Email Verification**: Send verification code when admin/user registers
- **Password Reset**: Send link when password reset is requested
- **User Invitation**: Send invitation email when admin invites user
Email content is based on **Handlebars templates** and includes the following information:
- Sender: `"User feedback" <SMTP_SENDER>`
- Base URL: Uses `ADMIN_WEB_URL` environment variable value
- Template location: `src/configs/modules/mailer-config/templates/`
---
## Related Documents
- [Docker Hub Installation Guide](./docker-hub-images)
- [Environment Variable Settings](./configuration)
- [Getting Started Guide](/en/user-guide/getting-started)
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/05-configuration.md
+207
View File
@@ -0,0 +1,207 @@
---
id: configuration
title: Environment Variable Configuration
description: This document explains how to configure environment variables for ABC User Feedback's API and web servers.
sidebar_position: 5
---
# Environment Variable Configuration
This document explains the main environment variables used by ABC User Feedback's **API server** and **web server** and how to configure them.
---
## 1. API Server Environment Variables
### Required Environment Variables
| Environment Variable | Description | Default | Example |
| ---------------------------- | ----------------------------- | ------- | -------------------------------- |
| `JWT_SECRET` | Secret key for JWT signing | None | `jwtsecretjwtsecretjwtsecret` |
| `MYSQL_PRIMARY_URL` | MySQL connection URL | None | `mysql://user:pass@host:3306/db` |
| `ACCESS_TOKEN_EXPIRED_TIME` | Access Token validity period | `10m` | `10m`, `30s`, `1h` |
| `REFRESH_TOKEN_EXPIRED_TIME` | Refresh Token validity period | `1h` | `1h`, `7d` |
> JWT secret should be a sufficiently complex and secure string.
⚠️ **Security Notes**:
- `JWT_SECRET` should be at least 32 characters long and complex
- Never use default values in production environments
- Do not include environment variable files (`.env`) in version control
- Manage sensitive information through environment variables or secret management systems
---
### Optional Environment Variables
| Environment Variable | Description | Default | Example |
| ---------------------- | --------------------------------------------------- | ----------------------- | --------------------------- |
| `APP_PORT` | API server port | `4000` | `4000` |
| `APP_ADDRESS` | Binding address | `0.0.0.0` | `127.0.0.1` |
| `ADMIN_WEB_URL` | Admin web URL | `http://localhost:3000` | `https://admin.company.com` |
| `BASE_URL` | Public API server URL used in Swagger documentation | None | `https://api.example.com` |
| `MYSQL_SECONDARY_URLS` | Secondary DB URLs (JSON array) | None | `["mysql://..."]` |
| `AUTO_MIGRATION` | Auto migration on app startup | `true` | `false` |
| `MASTER_API_KEY` | Master permission API key (optional) | None | `abc123xyz` |
| `NODE_OPTIONS` | Node execution options | None | `--max_old_space_size=4096` |
---
### SMTP Settings (Email Authentication)
| Environment Variable | Description | Example |
| ------------------------ | ---------------------------- | ------------------------------ |
| `SMTP_HOST` | SMTP server address | `smtp.gmail.com` |
| `SMTP_PORT` | Port (usually 587 or 465) | `587` |
| `SMTP_USERNAME` | Login username | `user@example.com` |
| `SMTP_PASSWORD` | Login password or token | `app-password` |
| `SMTP_SENDER` | Sender address | `noreply@company.com` |
| `SMTP_BASE_URL` | Base URL for links in emails | `https://feedback.company.com` |
| `SMTP_TLS` | Whether to use TLS | `true` |
| `SMTP_CIPHER_SPEC` | Encryption spec | `TLSv1.2` |
| `SMTP_OPPORTUNISTIC_TLS` | Whether to support STARTTLS | `true` |
📎 For detailed settings, refer to the [SMTP Integration Guide](./04-smtp-configuration.md).
---
## 2. OpenSearch Settings (Optional)
| Environment Variable | Description | Example |
| --------------------- | ---------------------------- | ----------------------- |
| `OPENSEARCH_USE` | Whether to enable OpenSearch | `true` |
| `OPENSEARCH_NODE` | OpenSearch node URL | `http://localhost:9200` |
| `OPENSEARCH_USERNAME` | Authentication ID | `admin` |
| `OPENSEARCH_PASSWORD` | Authentication password | `admin123` |
> OpenSearch is used to improve search speed and AI features.
---
## 3. Automatic Feedback Deletion Settings
| Environment Variable | Description | Default / Condition |
| ------------------------------------ | ------------------------------------ | --------------------------- |
| `AUTO_FEEDBACK_DELETION_ENABLED` | Enable old feedback deletion feature | `false` |
| `AUTO_FEEDBACK_DELETION_PERIOD_DAYS` | Deletion criteria in days | `365` (required if enabled) |
---
## 4. API Log Export Settings (Optional)
The API can export application logs through OpenTelemetry in addition to the standard console logs.
<!-- markdownlint-disable MD060 -->
| Environment Variable | Description | Default | Example |
| ---------------------------------- | ---------------------------------------------------------------- | ------- | ---------------------------------------------------------- |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP HTTP logs endpoint used by the pino OpenTelemetry transport | None | `http://localhost:4319/v1/logs` |
| `OTEL_RESOURCE_ATTRIBUTES` | OpenTelemetry resource attributes for exported logs | None | `service.name=abc-user-feedback-api,service.version=1.1.1` |
<!-- markdownlint-enable MD060 -->
> When `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` is set, the API keeps writing pretty console logs and also sends the same logs to the configured OTLP HTTP endpoint.
> If you also set `OTEL_RESOURCE_ATTRIBUTES`, you can attach standard OpenTelemetry resource metadata such as `service.name` and `service.version` using comma-separated `key=value` pairs.
> Use the example values from `apps/api/.env.example` as the baseline when configuring local development environments.
### Local Verification Flow
- Start the local OTEL test stack from the repository root:
```bash
docker compose -f docker/docker-compose.otel-test.yml up -d
```
- Set the following variables in `apps/api/.env` based on the example in `apps/api/.env.example`:
```env
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4319/v1/logs
OTEL_RESOURCE_ATTRIBUTES=service.name=abc-user-feedback-api,service.version=1.1.1
```
> The API does not parse this value itself. `pino-opentelemetry-transport` and the OpenTelemetry SDK consume these standard OTEL environment variables directly.
- Start the API server and trigger requests that generate logs.
- Vector should receive OTLP logs on port `4319` and print transformed log records to its console output.
- OpenSearch should be reachable on host port `9201`.
- OpenSearch Dashboards should be reachable on [http://localhost:5602](http://localhost:5602), where you can inspect the `logs-*` indices created by the local stack.
> The local test stack uses OTLP HTTP on `4319`, OpenSearch on `9201`, and OpenSearch Dashboards on `5602` as defined in `docker/docker-compose.otel-test.yml`.
---
## 5. Web Server Environment Variables
### Required Environment Variables
| Environment Variable | Description | Example |
| -------------------------- | --------------------------------- | ----------------------- |
| `NEXT_PUBLIC_API_BASE_URL` | API server address for client use | `http://localhost:4000` |
### Optional Environment Variables
| Environment Variable | Description | Default | Example |
| -------------------- | ------------- | ------- | ------- |
| `PORT` | Frontend port | `3000` | `3000` |
---
## 6. Configuration Methods
### Docker Compose Example
```yaml
services:
api:
image: line/abc-user-feedback-api
environment:
- JWT_SECRET=changeme
- MYSQL_PRIMARY_URL=mysql://user:pass@mysql:3306/userfeedback
- SMTP_HOST=smtp.sendgrid.net
- SMTP_USERNAME=apikey
- SMTP_PASSWORD=your-sendgrid-key
```
### .env File Example
```env
# apps/api/.env
JWT_SECRET=changemechangemechangeme
MYSQL_PRIMARY_URL=mysql://root:pass@localhost:3306/db
ACCESS_TOKEN_EXPIRED_TIME=10m
REFRESH_TOKEN_EXPIRED_TIME=1h
SMTP_HOST=smtp.example.com
SMTP_SENDER=noreply@example.com
# BASE_URL=https://api.example.com # Set when serving behind a reverse proxy
# apps/web/.env
NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
```
---
## 7. Troubleshooting Guide
<!-- markdownlint-disable MD060 -->
| Problem | Cause and Solution |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Environment variables not recognized | Check `.env` location or restart container |
| DB connection failure | Check `MYSQL_PRIMARY_URL` format or connection info |
| SMTP error | Recheck port/TLS settings or authentication info |
| OpenSearch error | Check node URL or user authentication |
| OTEL log export not working | Check whether `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` is set, verify the endpoint URL, and confirm the OTEL stack is running |
| JWT token error | Check `JWT_SECRET` length and complexity |
| Environment variable validation failure | Check for missing required variables or type errors |
| Port conflict | Check `APP_PORT`, `PORT` settings |
<!-- markdownlint-enable MD060 -->
---
## Related Documents
- [Docker Installation Guide](./docker-hub-images)
- [SMTP Integration Guide](./smtp-configuration)
- [Getting Started Guide](/en/user-guide/getting-started)
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/_category_.json
+5
View File
@@ -0,0 +1,5 @@
{
"position": 1,
"label": "Installation",
"description": "Guide for setting up development environment and installation."
}
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/index.md
+7
View File
@@ -0,0 +1,7 @@
---
title: Installation
---
import DocCardList from '@theme/DocCardList';
<DocCardList />
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/02-api-integration.md
+533
View File
@@ -0,0 +1,533 @@
---
sidebar_position: 2
title: "API Integration"
description: "This guide explains how to integrate external systems using ABC User Feedback API and provides actual implementation examples."
---
# API Integration
ABC User Feedback can integrate with external systems through **RESTful API**. You can programmatically collect feedback, manage issues, and query data, making it easy to integrate with existing services or workflows.
---
## API Basic Information
### Official API Documentation
The **complete API documentation** for ABC User Feedback can be found at the following link:
🔗 **[Official API Documentation (Redocly)](https://line.github.io/abc-user-feedback/)**
This documentation provides detailed specs for all endpoints, request/response examples, and an interface for actual testing.
### Base URL
```
https://your-domain.com/api
```
### Authentication Method
All API requests use **API key-based authentication**.
```http
X-API-KEY: your-api-key-here
Content-Type: application/json
```
:::warning Security Notice
Use API keys only on the server side, and do not expose them to clients (browsers, mobile apps).
:::
### API Key Issuance Method
1. **Access Admin Page**: Log in to ABC User Feedback admin page
2. **Project Settings**: Navigate to the settings page for the project
3. **API Key Management**: Create a new API key from the "API Key Management" menu
4. **Copy Key**: Save the generated API key in a safe place
:::info API Key Permissions
API keys are issued per project and can only access data for that project.
:::
---
## Main API Endpoint Examples
### 1. Creating Feedback
#### Basic Feedback Creation
```javascript
const createFeedback = async (
projectId,
channelId,
message,
issueNames = []
) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
message: message,
issueNames: issueNames,
}),
}
);
return await response.json();
};
// Usage example
const feedback = await createFeedback(1, 1, "Payment error occurred", [
"Payment",
"Error",
]);
```
### 2. Querying Feedback
#### Channel-Based Feedback Search
```javascript
const searchFeedbacks = async (
projectId,
channelId,
searchText,
limit = 10,
page = 1
) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks/search`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
limit: limit,
page: page,
query: {
searchText: searchText,
createdAt: {
gte: "2024-01-01",
lt: "2024-12-31",
},
},
sort: {
createdAt: "DESC",
},
}),
}
);
return await response.json();
};
// Usage example
const feedbacks = await searchFeedbacks(1, 1, "Payment", 20, 1);
console.log(
`Retrieved ${feedbacks.items.length} out of ${feedbacks.meta.totalItems} feedback`
);
```
#### Single Feedback Query
```javascript
const getFeedbackById = async (projectId, channelId, feedbackId) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}`,
{
method: "GET",
headers: {
"X-API-KEY": "your-api-key-here",
},
}
);
return await response.json();
};
// Usage example
const feedback = await getFeedbackById(1, 1, 123);
console.log("Feedback details:", feedback);
```
#### Feedback Update
```javascript
const updateFeedback = async (projectId, channelId, feedbackId, updateData) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}`,
{
method: "PUT",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify(updateData),
}
);
return await response.json();
};
// Usage example
const updatedFeedback = await updateFeedback(1, 1, 123, {
message: "Updated feedback content",
issueNames: ["Updated issue"],
});
```
#### Feedback Deletion
```javascript
const deleteFeedbacks = async (projectId, channelId, feedbackIds) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks`,
{
method: "DELETE",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
feedbackIds: feedbackIds,
}),
}
);
return await response.json();
};
// Usage example
const result = await deleteFeedbacks(1, 1, [123, 124, 125]);
console.log("Deletion complete:", result);
```
### 3. Issue Management
#### Issue Creation
```javascript
const createIssue = async (projectId, name, description) => {
const response = await fetch(`/api/projects/${projectId}/issues`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
name: name,
description: description,
}),
});
return await response.json();
};
// Usage example
const issue = await createIssue(
1,
"Payment Error",
"User experienced error during payment process"
);
```
#### Issue Search
```javascript
const searchIssues = async (projectId, query = {}) => {
const response = await fetch(`/api/projects/${projectId}/issues/search`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
limit: 10,
page: 1,
query: query,
sort: {
createdAt: "DESC",
},
}),
});
return await response.json();
};
// Usage example
const issues = await searchIssues(1, { name: "Payment" });
```
#### Issue Query
```javascript
const getIssueById = async (projectId, issueId) => {
const response = await fetch(`/api/projects/${projectId}/issues/${issueId}`, {
method: "GET",
headers: {
"X-API-KEY": "your-api-key-here",
},
});
return await response.json();
};
// Usage example
const issue = await getIssueById(1, 123);
console.log("Issue details:", issue);
```
#### Issue Update
```javascript
const updateIssue = async (projectId, issueId, updateData) => {
const response = await fetch(`/api/projects/${projectId}/issues/${issueId}`, {
method: "PUT",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify(updateData),
});
return await response.json();
};
// Usage example
const updatedIssue = await updateIssue(1, 123, {
name: "Updated issue name",
description: "Updated issue description",
});
```
#### Issue Deletion
```javascript
const deleteIssues = async (projectId, issueIds) => {
const response = await fetch(`/api/projects/${projectId}/issues`, {
method: "DELETE",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
issueIds: issueIds,
}),
});
return await response.json();
};
// Usage example
const result = await deleteIssues(1, [123, 124, 125]);
console.log("Issue deletion complete:", result);
```
#### Adding Issue to Feedback
```javascript
const addIssueToFeedback = async (
projectId,
channelId,
feedbackId,
issueId
) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}/issues/${issueId}`,
{
method: "POST",
headers: {
"X-API-KEY": "your-api-key-here",
},
}
);
return await response.json();
};
// Usage example
const result = await addIssueToFeedback(1, 1, 123, 456);
console.log("Issue added:", result);
```
#### Removing Issue from Feedback
```javascript
const removeIssueFromFeedback = async (
projectId,
channelId,
feedbackId,
issueId
) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}/issues/${issueId}`,
{
method: "DELETE",
headers: {
"X-API-KEY": "your-api-key-here",
},
}
);
return await response.json();
};
// Usage example
const result = await removeIssueFromFeedback(1, 1, 123, 456);
console.log("Issue removed:", result);
```
### 4. Project and Channel Information
#### Project Information Query
```javascript
const getProjectInfo = async (projectId) => {
const response = await fetch(`/api/projects/${projectId}`, {
method: "GET",
headers: {
"X-API-KEY": "your-api-key-here",
},
});
return await response.json();
};
// Usage example
const project = await getProjectInfo(1);
console.log("Project information:", project);
```
#### Channel Field Query
```javascript
const getChannelFields = async (projectId, channelId) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/fields`,
{
method: "GET",
headers: {
"X-API-KEY": "your-api-key-here",
},
}
);
return await response.json();
};
// Usage example
const fields = await getChannelFields(1, 1);
console.log("Channel fields:", fields);
```
---
## API Testing via Swagger
ABC User Feedback provides **Swagger UI** to easily test and understand the API.
### Swagger Access Method
Access via **API server address + `/docs`**:
```
https://your-domain.com/api/docs
```
Or in **ReDoc format**:
```
https://your-domain.com/api/docs/redoc
```
### Setting API Key in Swagger
1. Click the **"Authorize"** button at the top of Swagger UI
2. Enter the issued API key in the **X-API-KEY** field
3. Click **"Authorize"** to complete authentication
After this, all API requests will automatically include the API key for testing.
### Swagger Usage Tips
- Use **"Try it out"** button to test actual API calls
- Check actual response data structure in **Response body** section
- View detailed request/response data format in **Schema** tab
- Generate **cURL** commands automatically for CLI testing
---
## Error Handling and Retry Logic
### HTTP Status Codes
| Status Code | Meaning | Handling Method |
| ----------- | ---------------- | ----------------------------- |
| **200** | Success | Normal processing |
| **400** | Bad Request | Validate request data |
| **401** | Authentication Failed | Check API key |
| **403** | Forbidden | Check project access permissions |
| **404** | Not Found | Check ID value |
| **429** | Rate Limit Exceeded | Retry after a moment |
| **500** | Server Error | Retry or contact support team |
## Response Data Parsing Method
### Pagination Response Structure
```json
{
"meta": {
"itemCount": 10,
"totalItems": 100,
"itemsPerPage": 10,
"totalPages": 10,
"currentPage": 1
},
"items": [
{
"id": 1,
"message": "Feedback content",
"createdAt": "2024-01-01T00:00:00.000Z",
"issues": [
{
"id": 1,
"name": "Issue name"
}
]
}
]
}
```
## Security and Performance Optimization
### API Key Security
- **Use environment variables**: Manage API keys as environment variables
- **Server side only**: Do not expose API keys to clients
- **Key rotation**: Regularly replace API keys
- **IP whitelist**: Allow access only from specific IPs when possible
### Performance Optimization
- **Use pagination**: Set appropriate limit when querying large amounts of data
- **Request only needed fields**: Improve response speed through query optimization
- **Caching strategy**: Cache frequently queried data on client side
- **Batch processing**: Process multiple requests together
## Related Documents
- [API Key Management](/en/user-guide/settings/api-key-management) - How to issue API keys from UI
- [Image Settings](/en/user-guide/settings/image-setting) - Settings for using image upload API
- [Webhook Integration](/en/user-guide/settings/webhook-management) - Real-time notification settings that can be used with API
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/03-oauth-integration.md
+172
View File
@@ -0,0 +1,172 @@
---
sidebar_position: 3
title: "OAuth Integration"
description: "This guide explains how to integrate single sign-on (SSO) through Google OAuth and custom OAuth providers."
---
# OAuth Integration
By setting up OAuth 2.0-based single sign-on (SSO) in ABC User Feedback, users can log in with existing accounts (Google, Microsoft, GitHub, etc.) without creating separate accounts. This improves user convenience and is essential for implementing integrated authentication in enterprise environments.
---
## OAuth Integration Overview
OAuth methods supported by ABC User Feedback:
### 1. Google OAuth
- Provided by default without additional setup
- Easy login via Google account
### 2. Custom OAuth Provider
- In-house authentication systems
- Other OAuth 2.0/OpenID Connect compatible services
After setting up OAuth, it can be used alongside existing email login, and you can restrict to OAuth only according to organizational policy.
---
## Google OAuth Integration Settings
### Settings in Google Cloud Console
#### 1. Access Google Cloud Console
Access [Google Cloud Console](https://console.cloud.google.com) and create a project or select an existing project.
#### 2. Create OAuth 2.0 Client ID
1. Navigate to **APIs & Services > Credentials** menu
2. Select **+ Create Credentials > OAuth Client ID**
3. Select application type as **Web Application**
#### 3. Set Authorized Redirect URIs
Add the following URL to **Authorized Redirect URIs**:
```
https://your-domain.com/auth/oauth-callback
```
Examples:
- `https://feedback.company.com/auth/oauth-callback`
- `http://localhost:3000/auth/oauth-callback` (development environment)
#### 4. Check Client Information
After creation is complete, check and copy the following information:
- **Client ID**: `1234567890-abc123def456.apps.googleusercontent.com`
- **Client Secret**: `GOCSPX-abcdef123456`
### Google OAuth Settings in ABC User Feedback
To use Google OAuth, follow these steps to configure:
#### 1. Enable Google OAuth Settings
In **Settings > Login Management**:
1. Enable **OAuth2.0 Login** toggle
2. Select **Login Button Type** as "Google Login"
3. Enter information obtained from Google Cloud Console:
- **Client ID**: Client ID created in Google Cloud Console
- **Client Secret**: Client secret created in Google Cloud Console
- **Authorization Code Request URL**: `https://accounts.google.com/o/oauth2/v2/auth`
- **Scope**: `openid email profile`
- **Access Token URL**: `https://oauth2.googleapis.com/token`
- **User Profile Request URL**: `https://www.googleapis.com/oauth2/v2/userinfo`
- **Email Key**: `email`
#### 2. Register Redirect URI
Add the following URL to **Authorized Redirect URIs** in Google Cloud Console:
```
https://your-domain.com/auth/oauth-callback
```
For development environment:
```
http://localhost:3000/auth/oauth-callback
```
---
## Custom OAuth Provider Integration
### In-House Authentication System Integration
ABC User Feedback can integrate with in-house authentication systems used in enterprise environments. Most in-house authentication systems support OAuth 2.0 or OpenID Connect standards, so integration is possible through standard OAuth flow.
#### Requirements for In-House Authentication System Settings
To integrate with an in-house authentication system, the following information is required:
1. **OAuth Client Registration**
- Client ID
- Client Secret
- Redirect URI: `https://your-domain.com/auth/oauth-callback`
2. **OAuth Endpoint Information**
- Authorization URL (authentication request URL)
- Token URL (token exchange URL)
- User Info URL (user information query URL)
3. **Permission Scope (Scope)**
- User profile information access permissions
- Email address access permissions
#### Common In-House Authentication System Examples
| Item | Description | In-House System Example |
| ---------------------------------- | ----------------------------------------- | ------------------------------------------------- |
| **Login Button Type** | Login button type | `CUSTOM` |
| **Login Button Name** | Name displayed on login button | `Sign in with Company Account` |
| **Client ID** | OAuth client ID | `company-auth-client-123` |
| **Client Secret** | Client secret | `company-secret-abc123` |
| **Authorization Code Request URL** | User authentication request URL | `https://auth.company.com/oauth/authorize` |
| **Scope** | Permission scope to request | `openid email profile` |
| **Access Token URL** | Token request URL | `https://auth.company.com/oauth/token` |
| **User Profile Request URL** | User information query API | `https://auth.company.com/api/user` |
| **Email Key** | Email field name in user information JSON | `email` or `mail` |
### Other OAuth 2.0/OpenID Connect Compatible Services
ABC User Feedback can integrate with all authentication services that comply with OAuth 2.0 or OpenID Connect standards.
#### Supported Service Types
- **OpenID Connect Providers**: Services supporting standard OpenID Connect protocol
- **OAuth 2.0 Providers**: Services supporting OAuth 2.0 Authorization Code flow
- **Custom Authentication Servers**: Self-built services providing standard OAuth endpoints
#### Integration Setup Method
Configure custom OAuth in **Settings > Login Management**:
1. **Log in with admin account** and navigate to **Settings > Login Management** menu
2. Enable **OAuth2.0 Login** toggle
3. Select **Login Button Type** as `CUSTOM`
4. Enter information received from authentication service provider:
- **Login Button Name**: Text displayed on login button (e.g., "Sign in with Company Account")
- **Client ID**: OAuth client identifier
- **Client Secret**: Client authentication secret
- **Authorization Code Request URL**: User authentication request URL
- **Scope**: Permission scope to request (space-separated, e.g., "openid email profile")
- **Access Token URL**: Access token request URL
- **User Profile Request URL**: User profile information query URL
- **Email Key**: Email field name in user information JSON (e.g., "email" or "mail")
---
## Related Documents
- [Login Management](/en/user-guide/settings/tenant-settings) - How to configure OAuth in UI
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/04-webhook-integration.md
+303
View File
@@ -0,0 +1,303 @@
---
sidebar_position: 4
title: 'Webhook Integration'
description: 'This guide explains how to integrate with external systems in real-time using webhooks and provides implementation examples.'
---
# Webhook Integration
With webhooks, you can deliver major events occurring in ABC User Feedback to external systems in real-time. You can integrate with Slack notifications, automation workflows, custom analysis systems, etc.
---
## Supported Event Types
Events supported by ABC User Feedback are as follows:
### 1. FEEDBACK_CREATION
Occurs when new feedback is created.
**Request Headers:**
```
Content-Type: application/json
x-webhook-token: your-secret-token
```
**Payload Example:**
```json
{
"event": "FEEDBACK_CREATION",
"data": {
"feedback": {
"id": 123,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"message": "User feedback content",
"userEmail": "user@example.com",
"issues": [
{
"id": 456,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"name": "Bug Report",
"description": "Issue description",
"status": "OPEN",
"externalIssueId": "EXT-123",
"feedbackCount": 5
}
]
},
"channel": {
"id": 1,
"name": "Website Feedback"
},
"project": {
"id": 1,
"name": "My Project"
}
}
}
```
### 2. ISSUE_CREATION
Occurs when a new issue is created.
**Payload Example:**
```json
{
"event": "ISSUE_CREATION",
"data": {
"issue": {
"id": 789,
"createdAt": "2024-01-15T11:00:00.000Z",
"updatedAt": "2024-01-15T11:00:00.000Z",
"name": "New Issue",
"description": "Issue description",
"status": "OPEN",
"externalIssueId": "EXT-789",
"feedbackCount": 0
},
"project": {
"id": 1,
"name": "My Project"
}
}
}
```
### 3. ISSUE_STATUS_CHANGE
Occurs when issue status is changed.
**Payload Example:**
```json
{
"event": "ISSUE_STATUS_CHANGE",
"data": {
"issue": {
"id": 789,
"createdAt": "2024-01-15T11:00:00.000Z",
"updatedAt": "2024-01-15T12:00:00.000Z",
"name": "Issue Name",
"description": "Issue description",
"status": "IN_PROGRESS",
"externalIssueId": "EXT-789",
"feedbackCount": 3
},
"project": {
"id": 1,
"name": "My Project"
},
"previousStatus": "OPEN"
}
}
```
### 4. ISSUE_ADDITION
Occurs when an issue is added to feedback.
**Payload Example:**
```json
{
"event": "ISSUE_ADDITION",
"data": {
"feedback": {
"id": 123,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"message": "User feedback content",
"issues": [
{
"id": 456,
"name": "Existing Issue",
"status": "OPEN"
},
{
"id": 789,
"name": "Newly Added Issue",
"status": "OPEN"
}
]
},
"channel": {
"id": 1,
"name": "Website Feedback"
},
"project": {
"id": 1,
"name": "My Project"
},
"addedIssue": {
"id": 789,
"createdAt": "2024-01-15T11:00:00.000Z",
"updatedAt": "2024-01-15T11:00:00.000Z",
"name": "Newly Added Issue",
"description": "Issue description",
"status": "OPEN",
"externalIssueId": "EXT-456",
"feedbackCount": 1
}
}
}
```
---
## Webhook Receiving Server Implementation
You need to implement an HTTP server to receive webhooks. The server must meet the following requirements:
### Basic Requirements
1. **HTTP POST Request Handling**: Webhooks are sent via HTTP POST
2. **JSON Payload Parsing**: Request body is in JSON format
3. **Return 200 Response Code**: Must respond with 200 status code on successful processing
### Implementation Example (Node.js/Express)
```javascript
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhook', (req, res) => {
const { event, data } = req.body;
const token = req.headers['x-webhook-token'];
// Token verification
if (token !== 'your-secret-token') {
return res.status(401).json({ error: 'Unauthorized' });
}
// Event processing
switch (event) {
case 'FEEDBACK_CREATION':
console.log('New feedback created:', data.feedback);
// Feedback processing logic
break;
case 'ISSUE_CREATION':
console.log('New issue created:', data.issue);
// Issue processing logic
break;
case 'ISSUE_STATUS_CHANGE':
console.log(
'Issue status changed:',
data.issue,
'Previous status:',
data.previousStatus,
);
// Status change processing logic
break;
case 'ISSUE_ADDITION':
console.log('Issue added:', data.addedIssue);
// Issue addition processing logic
break;
}
res.status(200).json({ success: true });
});
app.listen(3000, () => {
console.log('Webhook listener server running on port 3000.');
});
```
---
## Security and Retry Policy
### Security Considerations
- **Token Verification**: Verify requests through `x-webhook-token` header
- **HTTPS Usage**: Always use HTTPS in production environments
### Retry Policy
- **Automatic Retry**: ABC User Feedback automatically retries up to 3 times on webhook transmission failure
- **Retry Interval**: Each retry is executed after 3 seconds
### Error Handling
- **4xx Errors**: Considered client errors, not retried
- **5xx Errors**: Considered server errors, retried
- **Network Errors**: Retried on connection failure
---
## Usage Examples
### 1. Automatic Translation
```javascript
// Receive FEEDBACK_CREATION event and automatically translate
if (event === 'FEEDBACK_CREATION') {
const translatedMessage = await translateText(data.feedback.message);
// Update feedback with translated content
await updateFeedback(data.feedback.id, { translatedMessage });
}
```
### 2. External Ticket System Integration
```javascript
// Receive ISSUE_CREATION event and create ticket in external system
if (event === 'ISSUE_CREATION') {
const ticketId = await createExternalTicket({
title: data.issue.name,
description: data.issue.description,
priority: 'medium',
});
// Store external ticket ID in issue
await updateIssue(data.issue.id, { externalIssueId: ticketId });
}
```
### 3. Notification System Integration
```javascript
// Receive ISSUE_STATUS_CHANGE event and notify team
if (event === 'ISSUE_STATUS_CHANGE') {
await sendSlackNotification({
channel: '#feedback-alerts',
message: `Issue "${data.issue.name}" status changed from ${data.previousStatus} to ${data.issue.status}.`,
});
}
```
---
## Related Documents
- [Webhook Management](/en/user-guide/settings/webhook-management) - How to configure webhooks in UI
- [API Integration](./02-api-integration.md) - API usage that can be used with webhooks
- [Issue Management](/en/user-guide/issue-management) - Understanding issue status change events
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/_category_.json
+5
View File
@@ -0,0 +1,5 @@
{
"position": 3,
"label": "Developer Guide"
}
apps/docs/i18n/en/docusaurus-plugin-content-docs/current/02-developer-guide/index.md
+7
View File
@@ -0,0 +1,7 @@
---
title: Developer Guide
---
import DocCardList from '@theme/DocCardList';
<DocCardList />
apps/docs/i18n/en/docusaurus-theme-classic/footer.json
+14
View File
@@ -0,0 +1,14 @@
{
"copyright": {
"message": "Copyright © {year} ABC User Feedback.",
"description": "The footer copyright"
},
"link.title.Docs": {
"message": "Docs",
"description": "The title of the footer links column with title=Docs in the footer"
},
"link.title.More": {
"message": "More",
"description": "The title of the footer links column with title=More in the footer"
}
}
apps/docs/i18n/en/docusaurus-theme-classic/navbar.json
+18
View File
@@ -0,0 +1,18 @@
{
"title": {
"message": "ABC User Feedback",
"description": "The title in the navbar"
},
"item.label.Docs": {
"message": "Docs",
"description": "Navbar item with label Docs"
},
"item.label.GitHub": {
"message": "GitHub",
"description": "Navbar item with label GitHub"
},
"logo.alt": {
"message": "LOGO",
"description": "The alt text of navbar logo"
}
}