Jared ← Retour au site
STATUS: FINAL FS-001-user-management-workflows.md
Extrait réel d'un cahier fonctionnel produit par Jared — non modifié, à l'exception du nom du projet, anonymisé.

FS-001: User Management Workflows

Overview

This specification defines the user management workflows for the Ptidonjon platform, including user registration, authentication, session management, password reset, and external service integrations. The system supports multiple user acquisition channels (website direct registration and Instagram chatbot) with a unified user model.

User Stories

US-001.1: Website Registration

As a visitor, I want to create an account on the website using my email and password so that I can access the platform's features.

US-001.2: Instagram Auto-Registration

As an Instagram user, I want my account to be automatically created when I first message the chatbot so that I can start using the service without manual registration.

US-001.3: Email/Password Login

As a registered user, I want to log in with my email and password so that I can access my personal space.

US-001.4: Magic Link Login

As a user (especially Instagram-originated), I want to log in via a secure magic link so that I can access my content without remembering credentials.

US-001.5: Profile Completion

As a pre-registered user (via Instagram), I want to complete my profile with email and password so that I have full access to my account.

US-001.6: Password Reset

As a registered user, I want to reset my password via a magic link so that I can regain access to my account if I forget my credentials.

Functional Requirements

FS-001.1: User Registration - Website

Description: The system shall allow visitors to create accounts directly on the website.

Acceptance Criteria:

Test Scenarios:

GIVEN a visitor on the signup page
WHEN they provide a valid email and password meeting strength requirements
THEN a new user is created with state "registered" and a unique sourceId in the format "website-{uuid}"
AND the user receives an authentication token
AND the user is redirected to their personal space

GIVEN a visitor on the signup page
WHEN they provide a password that does not meet strength requirements
THEN an error message is displayed indicating the password requirements
AND no user is created

GIVEN a visitor on the signup page
WHEN they provide an email that is already registered
THEN an error message is displayed asking to choose another email or use "forgot password"
AND no duplicate user is created

FS-001.2: User Registration - Instagram (Auto-Registration)

Description: The system shall automatically create user accounts when Instagram users first interact with the chatbot.

Acceptance Criteria:

Test Scenarios:

GIVEN an Instagram webhook request with a sender ID not in the database
WHEN the request passes authenticity validation
THEN a new user is created with state "preregistered" and sourceId equal to the Instagram sender ID

GIVEN an Instagram webhook request with a sender ID already in the database
WHEN the request is processed
THEN no new user is created

FS-001.3: Authentication - Email/Password Login

Description: The system shall authenticate users via email and password credentials.

Acceptance Criteria:

Test Scenarios:

GIVEN a registered user
WHEN they provide correct email and password
THEN they receive an authentication token
AND are redirected to their personal space

GIVEN a login attempt
WHEN the credentials are invalid
THEN an error message is displayed
AND no token is issued

FS-001.4: Authentication - Magic Link Login

Description: The system shall provide passwordless authentication via temporary magic links.

Acceptance Criteria:

Test Scenarios:

GIVEN a valid magic link token
WHEN the user accesses the link
THEN the token is validated
AND the user receives an authentication token
AND the one-time token is deleted from the user record
AND the user is redirected to the appropriate context (e.g., their universe)

GIVEN an invalid or already-used magic link token
WHEN the user accesses the link
THEN an error message is displayed
AND no authentication token is issued

FS-001.5: Profile Completion (Pre-registered to Registered)

Description: The system shall prompt pre-registered users to complete their profile with email and password.

Acceptance Criteria:

Test Scenarios:

GIVEN a pre-registered user viewing their book
WHEN a cover image exists AND the user has no email on record
THEN after the configured delay, a profile completion modal is displayed
AND the modal cannot be dismissed

GIVEN the profile completion modal is displayed
WHEN the user submits valid email and password meeting strength requirements
THEN their credentials are updated
AND the modal is hidden
AND a new authentication token is issued

GIVEN the profile completion modal is displayed
WHEN the user submits an email that is already registered
THEN an error message is displayed asking to choose another email or use "forgot password"
AND the modal remains visible

FS-001.6: Session Management

Description: The system shall manage user sessions via JWT tokens with automatic renewal.

Acceptance Criteria:

Test Scenarios:

GIVEN a request to a protected endpoint
WHEN a valid JWT is provided
THEN the request is processed with the authenticated user context

GIVEN a request to a protected endpoint
WHEN no JWT or an invalid JWT is provided
THEN the request is rejected with an authorization error

GIVEN an active user session
WHEN the token approaches expiration
THEN the system automatically renews the token
AND the user session continues uninterrupted

FS-001.7: User Data Retrieval

Description: The system shall allow authenticated users to retrieve their profile data.

Acceptance Criteria:

Test Scenarios:

GIVEN an authenticated user
WHEN they request their profile data
THEN they receive their user data without the password field

FS-001.8: Password Reset

Description: The system shall allow registered users to reset their password via a magic link sent to their email.

Acceptance Criteria:

Test Scenarios:

GIVEN a user on the login page
WHEN they click "forgot password" and enter their registered email
THEN a magic link is sent to their email
AND a confirmation message is displayed (without revealing if email exists)

GIVEN a user who clicked a valid password reset magic link
WHEN the password reset modal is displayed
AND they enter a new password meeting strength requirements
THEN their password is updated
AND they receive an authentication token
AND are redirected to their personal space

GIVEN a user who clicked an already-used password reset link
WHEN they attempt to reset their password
THEN an error message is displayed
AND no password change occurs

Business Rules

BS-001.1: User Identification and Source Linking

Rule: Each user is associated with a globally unique sourceId that identifies their origin and ensures uniqueness across all users.

Rationale: The platform supports multiple user acquisition channels that need to be tracked and distinguished. Each sourceId must be globally unique to support data integrity during migrations and prevent duplicate user issues.

Specifics:

Examples:

Note: The sourceId is primarily meaningful during user registration to identify the acquisition channel. Once registration is complete, the sourceId serves no ongoing functional purpose beyond historical tracking.

BS-001.2: User States

Rule: Users exist in one of two states: "preregistered" or "registered".

Rationale: Instagram users start with minimal information and may later complete their profile.

State Definitions:

State Transitions:

BS-001.3: Temporary Token Lifecycle

Rule: One-time tokens (magic links) are single-use and must be invalidated after use.

Rationale: Security measure to prevent token reuse and unauthorized access.

Specifics:

BS-001.4: Instagram Webhook Authenticity

Rule: All Instagram webhook requests must be cryptographically verified before processing.

Rationale: Prevents spoofed requests from creating unauthorized users or executing actions.

Verification Method:

BS-001.5: Password Security

Rule: User passwords must be hashed before storage.

Rationale: Protect user credentials in case of database breach.

BS-001.6: Email Update on Payment

Rule: When a payment event occurs, the user's email is updated if not already set.

Rationale: Capture email during checkout for users who haven't completed registration.

Conditions:

BS-001.7: Password Strength Requirements

Rule: Passwords must meet minimum strength requirements to be accepted.

Rationale: Ensure user accounts are protected with sufficiently strong passwords.

Reference: Password validation is defined in the shared package (packages/shared/src/acceptors/password/condition.ts)

Valid Passwords: A password is considered valid if it meets EITHER the Medium OR Strong criteria:

Medium Password Requirements:

Strong Password Requirements:

Examples:

BS-001.8: Duplicate Email Prevention

Rule: Each email address can only be associated with one user account.

Rationale: Ensure unique user identification and prevent account confusion.

Behavior:

Examples:

BS-001.9: JWT Token Expiration

Rule: JWT authentication tokens expire after 72 hours.

Rationale: Balance security (limiting token lifetime) with user convenience (avoiding frequent re-authentication).

Reference: Token expiration is configured in packages/back/src/shared/auth/auth.module.ts

BS-001.10: JWT Token Auto-Renewal

Rule: The system shall automatically renew JWT tokens before they expire for active users.

Rationale: Provide seamless user experience without unexpected session terminations.

Behavior:

BS-001.11: Profile Completion Modal Behavior

Rule: The profile completion modal is mandatory and cannot be dismissed.

Rationale: Ensure pre-registered users provide contact information to complete their account.

Behavior:

Data Requirements

User Entity

Attribute Description Required Notes
id Unique identifier Yes System-generated
state User state Yes "preregistered" or "registered"
sourceId Origin identifier Yes Instagram ID or "website-{uuid}" format. Must be globally unique across all users.
email User email Conditional Required for "registered" state
password Hashed password Conditional Required for "registered" state
oneTimeToken Magic link token No Temporary, deleted after use

Future Enhancement - sourceId Optionality: The sourceId attribute is currently required but should be made optional in a future iteration. The sourceId is only meaningful during user registration to identify the acquisition channel. Once registration is complete, the sourceId serves no ongoing functional purpose and could be nullable. This change would simplify the data model for users who do not need acquisition tracking.

User Interactions

Flow 1: Website Registration

1. Visitor navigates to signup page
2. Visitor enters email and password
3. System validates password strength (BS-001.7)
4. System checks for duplicate email (BS-001.8)
5. If validation fails: display appropriate error message
6. If validation passes: System creates registered user
7. System issues JWT token
8. User is redirected to personal space (/universes)

Flow 2: Instagram Auto-Registration

1. Instagram user sends message to chatbot
2. Webhook received with sender ID
3. System validates webhook signature
4. System checks if user exists
5. If new: System creates preregistered user
6. Conversation proceeds (handled by Assistant module)

Flow 3: Login

1. User navigates to login page
2. User enters email and password
3. System validates credentials
4. System issues JWT token
5. User is redirected to personal space (/universes)

Flow 4: Magic Link Access

1. System generates magic link (triggered by book completion)
2. Link is sent to user (via Instagram)
3. User clicks link
4. System validates token
5. System issues JWT token
6. Token is invalidated
7. User is redirected to their content (universe/book)

Flow 5: Profile Completion

1. Pre-registered user accesses book page
2. System detects cover image exists but email is missing
3. After delay, mandatory profile completion modal appears
4. User cannot dismiss the modal
5. User enters email and password
6. System validates password strength (BS-001.7)
7. System checks for duplicate email (BS-001.8)
8. If validation fails: display appropriate error message
9. If validation passes: System updates user credentials
10. Modal is dismissed
11. User continues with full access

Flow 6: Password Reset

1. User navigates to login page
2. User clicks "Forgot Password" link
3. User enters their email address
4. System sends magic link to email (if email exists)
5. System displays confirmation (without revealing if email exists)
6. User clicks magic link in email
7. Password reset modal is displayed
8. User enters new password
9. System validates password strength (BS-001.7)
10. If validation fails: display error message
11. If validation passes: System updates password
12. System issues JWT token
13. User is redirected to personal space

Edge Cases & Error Scenarios

EC-001.1: Duplicate Instagram Registration

EC-001.2: Invalid Magic Link

EC-001.3: Registration with Existing Email

EC-001.4: Invalid Webhook Signature

EC-001.5: Weak Password Submission

EC-001.6: Session Expiry for Inactive User

EC-001.7: Token Auto-Renewal

EC-001.8: Password Reset for Non-Existent Email

EC-001.9: Profile Completion with Existing Email

EC-001.10: Malformed or Non-User Webhook Payload

Dependencies

Future Enhancements (Out of Scope)

The following features have been identified but are not included in this specification:

Self-Verification Checklist

Revision History

Version Date Author Changes
0.1 2026-01-08 PM Agent Initial draft from existing SPEC001.md and codebase analysis
1.0 2026-01-08 PM Agent Incorporated clarification answers: password requirements (BS-001.7), duplicate email handling (BS-001.8), JWT expiry and auto-renewal (BS-001.9, BS-001.10), mandatory profile modal (BS-001.11), password reset flow (FS-001.8)
1.1 2026-01-12 PM Agent Added EC-001.10: Malformed or Non-User Webhook Payload edge case
1.2 2026-01-16 PM Agent Updated BS-001.1: sourceId for website users now uses "website-{uuid}" format instead of "website". Each sourceId must be globally unique across all users. Added future enhancement note about making sourceId optional. Updated FS-001.1 acceptance criteria and test scenarios. Updated User Entity data requirements.