Support Module - Feature List

1. Feature Overview

The support module owns customer communication and operational follow-up across three related surfaces:

• support inquiries for homepage/live-chat style conversations, including guests and authenticated customers
• support requests for authenticated customer tickets that are tied to a verified customer record
• feedback submissions for app/product feedback that should be reviewed by admins but does not become a live conversation

Support now uses a mixed interaction model:

• synchronous REST for creating, listing, identifying, verifying, assigning, closing, linking, and reading records
• websocket delta events for live support request and inquiry messages
• scheduled maintenance for inactive inquiry closing
• existing notification queue for support inquiry email verification

The support inquiry flow is intentionally safe for guest users. A guest can provide an email address, but an email match with an existing customer is never revealed to the frontend and never links the inquiry to that customer until the email is verified or the customer logs in.

2. Route Ownership and Surfaces

Swagger tags used by support controllers:

• Support Inquiries
• Support Inquiries (Admin)
• Support Requests
• Support Requests (Admin)
• Feedback
• Feedback (Admin)

Notes:

• Support inquiry customer routes are mounted directly at /api/support-inquiries because they are intended for website/homepage chat, including unauthenticated guests.
• Existing authenticated mobile support requests remain mounted through the mobile composition layer at /api/mobile/support-requests.
• Feedback is not a chat surface. It is a one-way submission plus admin review workflow.

3. Admin Feature Matrix

Admin mutations record activity logs for support inquiry operations, support request operations, and feedback review operations. The audit context includes the request-derived metadata provided by SupportAdminSharedService.buildAuditContext(...).

4. Customer / Guest / Mobile Feature Matrix

5. Key Product Rules

• A support inquiry is a lightweight chat-style record that can exist before the visitor is known.
• A support request is a customer ticket and requires a real customer_id.
• A guest email does not prove identity. It is stored as contact data only until verification succeeds.
• If a guest email matches an existing customer, the backend silently sends verification and does not expose whether the email exists.
• A verified guest inquiry can be linked to a customer and then converted to a normal support request.
• A guest inquiry can still be handled by admins even when it never becomes a support request.
• Closing or resolving an inquiry changes status only; messages are retained for admin history.
• Inactive inquiries are automatically closed by scheduled maintenance after the configured inactivity window.
• Customer-facing APIs never expose raw token hashes.
• Guest inquiry access uses Authorization: Bearer si_..., not a customer JWT.
• Websocket rooms are additive. REST remains the source of truth for initial state and full history.
• Feedback submissions are reviewed, not replied to. They do not have message threads.

6. Domain Surfaces

6.1 Support inquiries

Support inquiries are for live chat and homepage inquiry capture. They support:

• guest creation
• authenticated customer creation
• tracking codes
• first system greeting message
• guest name/email/phone capture
• guest access token
• silent customer email lookup
• OTP verification before customer linking
• admin assignment
• admin replies
• status management
• linking to an existing support request
• creating a new support request after verified identity
• websocket rooms for live message deltas
• scheduled inactive close

6.2 Support requests

Support requests are the existing authenticated ticket system. They support:

• mobile customer ticket creation
• mobile customer replies
• admin listing/filtering/search
• admin detail view with full message history
• admin assignment
• admin replies
• status changes
• resolution notes
• websocket rooms for message deltas
• customer reply reopen behavior for resolved tickets

6.3 Feedback submissions

Feedback submissions are one-way app feedback records. They support:

• authenticated mobile submission
• admin listing/filtering/search
• admin detail view
• admin review marker
• activity log on review

7. State Models

7.1 Support inquiry status lifecycle

Typical path:

open -> active -> waiting -> resolved -> closed

Conversion path:

open -> active -> linked

Moderation path:

open -> spam

State notes:

• open means inquiry exists and may have only system/visitor messages.
• active means staff or visitor conversation is ongoing.
• waiting means the team is waiting on the visitor/customer.
• linked means the inquiry is tied to a support_request.
• resolved means the conversation is resolved but not necessarily hard-closed.
• closed means no more visitor/admin messages are accepted.
• spam is terminal-like and records closedAt.

7.2 Support request status lifecycle

Typical path:

open -> in_progress -> resolved -> closed

Reply behavior:

• Mobile/customer reply on a resolved request reopens it to open.
• Closed support requests reject both customer and admin replies.
• Resolution notes are only valid for resolved and closed.

7.3 Feedback status lifecycle

new -> reviewed

Review state requires:

• reviewedByAdminId
• reviewedAt

New state requires both fields to be null.

8. Identity, Security, and Privacy

8.1 Guest access token

Guest support inquiries return an inquiryAccessToken only at creation time. The token:

• starts with si_
• is used as Authorization: Bearer si_...
• is hashed with SHA-256 before storage
• is stored in support_inquiry_tokens.token_hash
• expires using the inquiry token expiry policy
• can be revoked by setting revoked_at
• is accepted by REST inquiry endpoints and websocket inquiry room joins

8.2 Optional auth behavior

Support inquiry public routes use an optional auth guard:

• normal customer JWTs are parsed as customer identity
• Bearer si_... is treated as guest inquiry token
• invalid or missing customer JWT does not automatically become an admin identity
• guest token access is validated against the target inquiry

8.3 Email verification and customer linking

Production-safe flow:

1. Guest creates inquiry.
2. System creates inquiry and a system greeting message.
3. Guest adds or updates email using create or identify endpoint.
4. If the email matches a customer, backend does not reveal the match.
5. Backend sends OTP/magic verification to the email.
6. Guest confirms OTP.
7. Backend links inquiry to customerId only after successful verification.
8. Admin can create or link a support request after identity is verified.

Security constraints:

• No account enumeration response.
• No customer support request is created from email alone.
• Guest cannot read customer ticket data without a verified customer link.
• Admin can still handle the guest inquiry without converting it.

9. Tracking Codes

Each support inquiry has a customer-safe trackingCode, independent from the serial database id.

Example:

INQ-8K4P2X

Usage:

• returned on inquiry creation
• shown to guest/customer as the inquiry ID
• available in admin list/detail/search
• included in websocket inquiry message payloads
• remains visible if the inquiry later links to a support request

When linked, both identifiers remain useful:

10. Realtime Features

Realtime support uses websocket rooms and event history.

Room types:

Client events:

• support:join_request_messages
• support:leave_request_messages
• support:sync_request_messages
• support:join_inquiry_messages
• support:leave_inquiry_messages
• support:sync_inquiry_messages

Server events:

• support.request_message.created
• support.inquiry_message.created

Realtime rules:

• REST is used for initial full history.
• Websocket events are deltas only.
• Clients dedupe by eventId.
• Clients call sync with sinceEventId after reconnect.
• If a gap is detected, clients refetch REST detail/messages.
• Admins can join any support request/inquiry room if they have read permission.
• Customers can join only their own support request/inquiry rooms.
• Guests can join only inquiry rooms for which they hold a valid si_... token.

11. Search and Filtering

11.1 Admin support inquiry list

Admin inquiry list supports:

• status
• category
• customerId
• assignedAdminId
• supportRequestId
• search
• pagination
• sort by createdAt or updatedAt

Search matches:

• tracking code
• subject
• guest email
• guest name
• guest phone

11.2 Customer support inquiry list

Customer inquiry list supports:

• current customer only
• status
• category
• pagination
• sort by createdAt or updatedAt

Guest users do not use list; they fetch a specific inquiry with the inquiry token.

11.3 Admin support request list

Admin request list supports:

• status
• category
• customerId
• assignedAdminId
• search by subject
• pagination
• sort

11.4 Mobile support request list

Mobile request list supports:

• current customer only
• status
• category
• pagination
• sort

11.5 Admin feedback list

Admin feedback list supports:

• status
• category
• customerId
• search
• pagination
• sort by createdAt or updatedAt

12. Rate Limiting

Support inquiry public write flows use IpThrottlerGuard:

• create inquiry
• add inquiry message
• identify guest contact
• request email verification
• confirm email verification

The guard protects unauthenticated homepage chat surfaces where there is no stable customer identity. Authenticated mobile support request and feedback routes use the existing authenticated API guards and global request controls.

Rate-limit errors use the project standard RateLimitExceededException path and return the shared rate-limit error contract.

13. Notifications and Email

Support inquiry verification uses existing notification infrastructure:

• VerificationTokenService creates the OTP.
• QueueName.NOTIFICATIONS receives an email job.
• NotificationJob.SEND_EMAIL is used to send the verification email.

The inquiry verification email is sent without revealing whether the email belongs to an existing customer. The response remains generic.

Support request replies use the existing SupportNotificationService path where applicable for customer notification of admin replies.

14. Maintenance Features

Support inquiries include scheduled inactive-close behavior:

Default behavior:

• cron: 0 * * * *
• inactivity window: 7 days

The scheduler marks stale open, active, waiting, or resolved inquiries as closed and sets closedAt. It does not delete inquiry messages.

15. Business Flow Diagrams

15.1 Guest live inquiry with verification

15.2 Live message realtime path

15.3 Existing mobile support request flow

16. Error UX Mapping

Existing support request and feedback paths may also return standard validation, not-found, forbidden, and unauthorized errors from the shared exception layer.

17. Release/QA Checklist

• Guest inquiry creation returns id, trackingCode, messages with system greeting, and inquiryAccessToken.
• Authenticated inquiry creation links directly to the customer without returning guest token.
• Guest token can fetch detail/messages only for the matching inquiry.
• Customer JWT can list only that customer's linked inquiries.
• Guest email identify flow stores normalized email and does not reveal customer existence.
• Email verification request sends a generic response for existing and non-existing email states.
• Email verification confirm links customerId only after valid OTP.
• Admin can list/search inquiries by tracking code, subject, guest email, guest name, and guest phone.
• Admin can reply, assign, update status, and link/create support request from inquiry.
• Linked inquiry preserves both trackingCode and supportRequestId.
• Closed/spam inquiries do not accept new visitor/admin messages.
• Inactive-close scheduler closes stale inquiries without deleting messages.
• Existing mobile support request create/list/detail/reply still works.
• Existing admin support request list/detail/status/assign/reply still works.
• Feedback create/list/detail/review still works.
• Websocket request rooms enforce customer/admin authorization.
• Websocket inquiry rooms enforce customer/admin/guest-token authorization.
• Reconnect sync returns replay events or gapDetected so clients can REST refetch.
• Admin permissions include SupportInquiries_READ and SupportInquiries_UPDATE.
• Permission seed includes SupportInquiries.

18. Integration Flows

18.1 Homepage guest chat

1. Frontend calls POST /api/support-inquiries with subject, optional category, optional first message, and optional guest contact fields.
2. Backend creates support_inquiries, support_inquiry_tokens, and system greeting message.
3. Frontend stores the returned inquiryAccessToken securely for the browser session.
4. Frontend displays trackingCode.
5. Frontend joins support:inquiry:{id}:messages using websocket auth Bearer si_....
6. Guest posts messages through REST and receives admin replies through websocket.
7. If guest leaves email, frontend calls identify and verification endpoints.
8. Admin can continue handling the inquiry even if the guest never verifies.

18.2 Authenticated customer inquiry

1. Customer is logged in and calls POST /api/support-inquiries with customer JWT.
2. Backend creates inquiry linked to customerId.
3. No guest inquiry token is returned.
4. Customer can list inquiries using GET /api/support-inquiries.
5. Customer can join the websocket inquiry room with the normal customer JWT.
6. Admin can create a support request from the inquiry because customer identity is already known.

18.3 Inquiry to support request conversion

1. Admin opens an inquiry detail.
2. Admin verifies the inquiry has customerId.
3. Admin calls POST /api/admin/support-inquiries/:id/link-support-request.
4. If supportRequestId is omitted, backend creates a new support_request for the verified customer.
5. Non-system inquiry messages are copied into support_request_messages.
6. Inquiry status becomes linked.
7. Admin support request workflow continues from /api/admin/support-requests/:id.

18.4 Feedback review

1. Mobile customer submits POST /api/mobile/feedback.
2. Admin lists new feedback with GET /api/admin/feedback?status=new.
3. Admin opens detail with GET /api/admin/feedback/:id.
4. Admin marks reviewed with PATCH /api/admin/feedback/:id/review.
5. Backend records reviewer and review timestamp.

See Also

• API Reference: See Support - API & Integration Guide for request/response contracts and websocket payloads.
• Backend Reference: See Support - Backend Documentation for schema, services, scheduler, and data model details.