@hed-hog/contact 0.0.293 → 0.0.295

package/src/person/person.service.ts

@@ -10,13 +10,34 @@ import {
     NotFoundException,
     forwardRef,
 } from '@nestjs/common';
+import {
+  ACCOUNT_LIFECYCLE_STAGES,
+  type AccountLifecycleStage,
+  type CreateAccountDTO,
+  type UpdateAccountDTO,
+} from './dto/account.dto';
+import {
+  type ActivityListQueryDTO,
+  type CrmActivityPriority,
+  type CrmActivitySourceKind,
+  type CrmActivityStatus,
+  type CrmActivityType,
+} from './dto/activity.dto';
 import { CreateFollowupDTO } from './dto/create-followup.dto';
 import {
     CreateInteractionDTO,
     PersonInteractionTypeDTO,
 } from './dto/create-interaction.dto';
 import { CreateDTO } from './dto/create.dto';
+import {
+  type CrmDashboardPeriod,
+  type DashboardQueryDTO,
+} from './dto/dashboard-query.dto';
 import { CheckPersonDuplicatesQueryDTO } from './dto/duplicates-query.dto';
+import {
+  FollowupListQueryDTO,
+  FollowupStatsQueryDTO,
+} from './dto/followup-query.dto';
 import { MergePersonDTO } from './dto/merge.dto';
 import { UpdateLifecycleStageDTO } from './dto/update-lifecycle-stage.dto';
 
@@ -59,6 +80,162 @@ type PersonInteractionRecord = {
   user_name: string | null;
 };
 
+type FollowupStatus = 'today' | 'upcoming' | 'overdue';
+
+type FollowupListParams = PaginationDTO &
+  FollowupListQueryDTO & {
+    page?: number;
+    pageSize?: number;
+  };
+
+type FollowupListItem = {
+  person: any;
+  next_action_at: string;
+  last_interaction_at: string | null;
+  status: FollowupStatus;
+};
+
+type AccountListParams = Omit<PaginationDTO, 'sortField' | 'sortOrder'> & {
+  search?: string;
+  status?: 'all' | 'active' | 'inactive';
+  lifecycle_stage?: 'all' | AccountLifecycleStage;
+  sortField?: 'name' | 'created_at';
+  sortOrder?: 'asc' | 'desc';
+  page?: number;
+  pageSize?: number;
+};
+
+type AccountListItem = {
+  id: number;
+  name: string;
+  trade_name: string | null;
+  status: 'active' | 'inactive';
+  industry: string | null;
+  website: string | null;
+  email: string | null;
+  phone: string | null;
+  owner_user_id: number | null;
+  owner_user: { id: number; name: string } | null;
+  annual_revenue: number | null;
+  employee_count: number | null;
+  lifecycle_stage: AccountLifecycleStage | null;
+  city: string | null;
+  state: string | null;
+  created_at: string;
+  last_interaction_at: string | null;
+};
+
+type CrmActivityListParams = Omit<PaginationDTO, 'sortField' | 'sortOrder'> &
+  ActivityListQueryDTO & {
+    page?: number;
+    pageSize?: number;
+  };
+
+type CrmActivityUserSummary = {
+  id: number;
+  name: string;
+};
+
+type CrmActivityPersonSummary = {
+  id: number;
+  name: string;
+  type: 'individual' | 'company';
+  status: 'active' | 'inactive';
+  trade_name: string | null;
+};
+
+type CrmActivityListItem = {
+  id: number;
+  person_id: number;
+  person: CrmActivityPersonSummary;
+  owner_user_id: number | null;
+  owner_user: CrmActivityUserSummary | null;
+  type: CrmActivityType;
+  subject: string;
+  notes: string | null;
+  due_at: string;
+  completed_at: string | null;
+  created_at: string;
+  priority: CrmActivityPriority;
+  status: CrmActivityStatus;
+};
+
+type CrmActivityDetail = CrmActivityListItem & {
+  source_kind: CrmActivitySourceKind;
+  created_by_user_id: number | null;
+  created_by_user: CrmActivityUserSummary | null;
+  completed_by_user_id: number | null;
+  completed_by_user: CrmActivityUserSummary | null;
+};
+
+const CRM_DASHBOARD_STAGE_ORDER = [
+  'new',
+  'contacted',
+  'qualified',
+  'proposal',
+  'negotiation',
+  'customer',
+  'lost',
+] as const;
+
+const CRM_DASHBOARD_SOURCE_ORDER = [
+  'website',
+  'referral',
+  'social',
+  'inbound',
+  'outbound',
+  'other',
+] as const;
+
+type CrmDashboardStageKey = (typeof CRM_DASHBOARD_STAGE_ORDER)[number];
+type CrmDashboardSourceKey = (typeof CRM_DASHBOARD_SOURCE_ORDER)[number];
+
+type DashboardListPersonItem = {
+  id: number;
+  name: string;
+  trade_name: string | null;
+  owner_user: { id: number; name: string } | null;
+  source: CrmDashboardSourceKey;
+  lifecycle_stage: CrmDashboardStageKey;
+  next_action_at?: string;
+  created_at?: string;
+};
+
+type DashboardOwnerPerformanceItem = {
+  owner_user_id: number;
+  owner_name: string;
+  leads: number;
+  customers: number;
+  pipeline_value: number;
+};
+
+type DashboardBucket<T extends string> = {
+  key: T;
+  total: number;
+};
+
+type DashboardPayload = {
+  kpis: {
+    total_leads: number;
+    qualified: number;
+    proposal: number;
+    customers: number;
+    lost: number;
+    unassigned: number;
+    overdue: number;
+    next_actions: number;
+  };
+  charts: {
+    stage: Array<DashboardBucket<CrmDashboardStageKey>>;
+    source: Array<DashboardBucket<CrmDashboardSourceKey>>;
+    owner_performance: DashboardOwnerPerformanceItem[];
+  };
+  lists: {
+    next_actions: DashboardListPersonItem[];
+    unattended: DashboardListPersonItem[];
+  };
+};
+
 @Injectable()
 export class PersonService {
   constructor(
@@ -112,6 +289,139 @@ export class PersonService {
     };
   }
 
+  async getDashboard(
+    query: DashboardQueryDTO,
+    locale: string,
+  ): Promise<DashboardPayload> {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+    const ownerUserId = this.coerceNumber(query.owner_user_id);
+    const ranges = this.resolveDashboardRanges(query, locale);
+
+    const where: Prisma.personWhereInput = {};
+
+    if (!allowCompanyRegistration) {
+      where.type = 'individual';
+    }
+
+    if (ownerUserId > 0) {
+      where.AND = [
+        {
+          person_metadata: {
+            some: {
+              key: OWNER_USER_METADATA_KEY,
+              value: ownerUserId as any,
+            },
+          },
+        },
+      ];
+    }
+
+    const people = await this.prismaService.person.findMany({
+      where,
+      select: {
+        id: true,
+        name: true,
+        type: true,
+        status: true,
+        avatar_id: true,
+        created_at: true,
+        updated_at: true,
+        person_metadata: true,
+      },
+      orderBy: {
+        created_at: 'desc',
+      },
+    });
+
+    const enriched = await this.enrichPeople(people as any[], allowCompanyRegistration);
+    const createdScoped = enriched.filter((person) =>
+      this.isDateWithinRange(person.created_at, ranges.created),
+    );
+    const nextActionScoped = enriched.filter(
+      (person) =>
+        !!person.next_action_at &&
+        this.isDateWithinRange(person.next_action_at, ranges.operational),
+    );
+
+    const kpis = {
+      total_leads: createdScoped.length,
+      qualified: createdScoped.filter((person) =>
+        ['qualified', 'proposal', 'negotiation', 'customer'].includes(
+          person.lifecycle_stage ?? 'new',
+        ),
+      ).length,
+      proposal: createdScoped.filter(
+        (person) => person.lifecycle_stage === 'proposal',
+      ).length,
+      customers: createdScoped.filter(
+        (person) => person.lifecycle_stage === 'customer',
+      ).length,
+      lost: createdScoped.filter((person) => person.lifecycle_stage === 'lost')
+        .length,
+      unassigned: createdScoped.filter((person) => !person.owner_user_id).length,
+      overdue: nextActionScoped.filter((person) => {
+        const nextActionAt = this.parseDateOrNull(person.next_action_at);
+        return !!nextActionAt && nextActionAt.getTime() < Date.now();
+      }).length,
+      next_actions: nextActionScoped.length,
+    };
+
+    const charts = {
+      stage: CRM_DASHBOARD_STAGE_ORDER.map((key) => ({
+        key,
+        total: createdScoped.filter(
+          (person) => (person.lifecycle_stage ?? 'new') === key,
+        ).length,
+      })),
+      source: CRM_DASHBOARD_SOURCE_ORDER.map((key) => ({
+        key,
+        total: createdScoped.filter(
+          (person) => (person.source ?? 'other') === key,
+        ).length,
+      })),
+      owner_performance: this.buildDashboardOwnerPerformance(createdScoped),
+    };
+
+    const lists = {
+      next_actions: [...nextActionScoped]
+        .sort(
+          (left, right) =>
+            new Date(left.next_action_at ?? 0).getTime() -
+            new Date(right.next_action_at ?? 0).getTime(),
+        )
+        .slice(0, 5)
+        .map((person) =>
+          this.mapDashboardListItem(person, {
+            includeCreatedAt: false,
+            includeNextActionAt: true,
+          }),
+        ),
+      unattended: [...createdScoped]
+        .filter(
+          (person) =>
+            !person.owner_user_id || (person.lifecycle_stage ?? 'new') === 'new',
+        )
+        .sort(
+          (left, right) =>
+            new Date(right.created_at ?? 0).getTime() -
+            new Date(left.created_at ?? 0).getTime(),
+        )
+        .slice(0, 5)
+        .map((person) =>
+          this.mapDashboardListItem(person, {
+            includeCreatedAt: true,
+            includeNextActionAt: false,
+          }),
+        ),
+    };
+
+    return {
+      kpis,
+      charts,
+      lists,
+    };
+  }
+
   async getOwnerOptions(currentUserId?: number) {
     const where: Prisma.userWhereInput = {
       OR: [
@@ -501,114 +811,826 @@ export class PersonService {
     };
   }
 
-  async get(locale: string, id: number) {
+  async listAccounts(paginationParams: AccountListParams) {
     const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+    const page = Math.max(Number(paginationParams.page || 1), 1);
+    const pageSize = Math.max(Number(paginationParams.pageSize || 12), 1);
+    const skip = (page - 1) * pageSize;
 
-    const person = await this.prismaService.person.findUnique({
-      where: { id },
-      include: {
-        person_address: {
-          include: {
-            address: true,
-          },
-        },
-        contact: true,
-        document: true,
-        person_metadata: true,
-      },
+    if (!allowCompanyRegistration) {
+      return this.createEmptyAccountPagination(page, pageSize);
+    }
+
+    const search = this.normalizeTextOrNull(paginationParams.search);
+    const filters = this.buildAccountSqlFilters({
+      search,
+      status: paginationParams.status,
+      lifecycleStage: paginationParams.lifecycle_stage,
     });
+    const orderBy = this.getAccountOrderBySql(
+      paginationParams.sortField,
+      paginationParams.sortOrder,
+    );
 
-    if (!person) {
-      throw new BadRequestException(
-        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
-      );
-    }
+    const totalRows = await this.prismaService.$queryRaw<Array<{ total: unknown }>>(
+      Prisma.sql`
+        SELECT COUNT(*) AS total
+        FROM person p
+        INNER JOIN person_company pc ON pc.id = p.id
+        WHERE p.type = 'company'
+        ${filters}
+      `,
+    );
+    const total = this.coerceCount(totalRows[0]?.total);
 
-    if (!allowCompanyRegistration && person.type === 'company') {
-      throw new NotFoundException(
-        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
-      );
+    if (total === 0) {
+      return this.createEmptyAccountPagination(page, pageSize);
     }
 
-    const [normalized] = await this.enrichPeople(
-      [person as any],
-      allowCompanyRegistration,
+    const rows = await this.prismaService.$queryRaw<Array<{ person_id: number }>>(
+      Prisma.sql`
+        SELECT p.id AS person_id
+        FROM person p
+        INNER JOIN person_company pc ON pc.id = p.id
+        WHERE p.type = 'company'
+        ${filters}
+        ORDER BY ${orderBy}, p.id ASC
+        LIMIT ${pageSize}
+        OFFSET ${skip}
+      `,
     );
-    return normalized;
-  }
 
-  async listInteractions(id: number, locale: string) {
-    const person = await this.ensurePersonAccessible(id, locale);
-    const metadata = await this.prismaService.person_metadata.findFirst({
+    const personIds = rows.map((row) => row.person_id).filter((id) => id > 0);
+    if (personIds.length === 0) {
+      return this.createEmptyAccountPagination(page, pageSize);
+    }
+
+    const people = await this.loadAccountPeopleByIds(personIds);
+    const companies = await this.prismaService.person_company.findMany({
       where: {
-        person_id: person.id,
-        key: INTERACTIONS_METADATA_KEY,
-      },
-      select: {
-        value: true,
+        id: {
+          in: personIds,
+        },
       },
     });
+    const personById = new Map(people.map((item) => [item.id, item]));
+    const companyById = new Map(companies.map((item) => [item.id, item]));
 
-    return this.metadataToInteractions(metadata?.value);
+    const data = rows
+      .map((row) => {
+        const person = personById.get(row.person_id);
+        const company = companyById.get(row.person_id);
+
+        if (!person || !company) {
+          return null;
+        }
+
+        return this.mapAccountFromPerson(person, company);
+      })
+      .filter((item): item is AccountListItem => item != null);
+
+    const lastPage = Math.max(1, Math.ceil(total / pageSize));
+
+    return {
+      total,
+      lastPage,
+      page,
+      pageSize,
+      prev: page > 1 ? page - 1 : null,
+      next: page < lastPage ? page + 1 : null,
+      data,
+    };
   }
 
-  async createInteraction(
-    id: number,
-    data: CreateInteractionDTO,
-    locale: string,
-    user: { id?: number; name?: string | null },
-  ) {
-    const person = await this.ensurePersonAccessible(id, locale);
-    const interaction = this.buildInteractionRecord(data, user);
+  async getAccountStats() {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
 
-    await this.prismaService.$transaction(async (tx) => {
-      const currentInteractions = await this.loadInteractionsFromTx(tx, person.id);
-      const nextInteractions = this.sortInteractions([
-        interaction,
-        ...currentInteractions,
-      ]);
+    if (!allowCompanyRegistration) {
+      return {
+        total: 0,
+        active: 0,
+        customers: 0,
+        prospects: 0,
+      };
+    }
 
-      await this.upsertMetadataValue(
-        tx,
-        person.id,
-        INTERACTIONS_METADATA_KEY,
-        nextInteractions,
+    const rows = await this.prismaService.$queryRaw<
+      Array<{
+        total: unknown;
+        active: unknown;
+        customers: unknown;
+        prospects: unknown;
+      }>
+    >(
+      Prisma.sql`
+        SELECT
+          COUNT(*) AS total,
+          COUNT(*) FILTER (WHERE p.status = 'active') AS active,
+          COUNT(*) FILTER (WHERE pc.account_lifecycle_stage = 'customer') AS customers,
+          COUNT(*) FILTER (WHERE pc.account_lifecycle_stage = 'prospect') AS prospects
+        FROM person p
+        INNER JOIN person_company pc ON pc.id = p.id
+        WHERE p.type = 'company'
+      `,
+    );
+
+    return {
+      total: this.coerceCount(rows[0]?.total),
+      active: this.coerceCount(rows[0]?.active),
+      customers: this.coerceCount(rows[0]?.customers),
+      prospects: this.coerceCount(rows[0]?.prospects),
+    };
+  }
+
+  async createAccount(data: CreateAccountDTO, locale: string) {
+    await this.ensureCompanyRegistrationAllowed({
+      nextType: 'company',
+      locale,
+    });
+
+    const normalizedName = this.normalizeTextOrNull(data.name);
+    if (!normalizedName) {
+      throw new BadRequestException(
+        getLocaleText('validation.nameMustBeString', locale, 'Name is required.'),
       );
-      await this.upsertMetadataValue(
+    }
+
+    return this.prismaService.$transaction(async (tx) => {
+      const person = await tx.person.create({
+        data: {
+          name: normalizedName,
+          type: 'company',
+          status: data.status,
+        },
+      });
+
+      await this.syncPersonSubtypeData(
         tx,
         person.id,
-        LAST_INTERACTION_AT_METADATA_KEY,
-        interaction.created_at,
+        null,
+        {
+          ...data,
+          type: 'company',
+          name: normalizedName,
+        },
+        locale,
       );
-    });
+      await this.syncPersonMetadata(tx, person.id, {
+        owner_user_id: data.owner_user_id,
+      });
+      await this.upsertPrimaryAccountContact(tx, person.id, 'EMAIL', data.email);
+      await this.upsertPrimaryAccountContact(tx, person.id, 'PHONE', data.phone);
 
-    return interaction;
+      return {
+        success: true,
+        id: person.id,
+      };
+    });
   }
 
-  async scheduleFollowup(
-    id: number,
-    data: CreateFollowupDTO,
-    locale: string,
-    user: { id?: number; name?: string | null },
-  ) {
-    const person = await this.ensurePersonAccessible(id, locale);
-    const normalizedNextActionAt = this.normalizeDateTimeOrNull(data.next_action_at);
+  async updateAccount(id: number, data: UpdateAccountDTO, locale: string) {
+    await this.ensureCompanyRegistrationAllowed({
+      currentType: 'company',
+      nextType: 'company',
+      locale,
+    });
 
-    if (!normalizedNextActionAt) {
+    const person = await this.ensureCompanyAccountAccessible(id, locale);
+    const nextName = this.normalizeTextOrNull(data.name) ?? person.name;
+
+    return this.prismaService.$transaction(async (tx) => {
+      await tx.person.update({
+        where: { id },
+        data: {
+          name: nextName,
+          type: 'company',
+          status: data.status ?? person.status,
+        },
+      });
+
+      await this.syncPersonSubtypeData(
+        tx,
+        id,
+        'company',
+        {
+          ...data,
+          type: 'company',
+          name: nextName,
+        },
+        locale,
+      );
+      await this.syncPersonMetadata(tx, id, {
+        owner_user_id: data.owner_user_id,
+      });
+      await this.upsertPrimaryAccountContact(tx, id, 'EMAIL', data.email);
+      await this.upsertPrimaryAccountContact(tx, id, 'PHONE', data.phone);
+
+      return {
+        success: true,
+        id,
+      };
+    });
+  }
+
+  async deleteAccounts({ ids }: DeleteDTO, locale: string) {
+    if (ids == undefined || ids == null) {
       throw new BadRequestException(
         getLocaleText(
-          'validation.dateMustBeString',
+          'deleteItemsRequired',
           locale,
-          'next_action_at must be a valid datetime.',
+          'You must select at least one item to delete.',
         ),
       );
     }
 
-    await this.prismaService.$transaction(async (tx) => {
-      await this.upsertMetadataValue(
-        tx,
-        person.id,
-        NEXT_ACTION_AT_METADATA_KEY,
+    const companies = await this.prismaService.person.findMany({
+      where: {
+        id: {
+          in: ids,
+        },
+      },
+      select: {
+        id: true,
+        type: true,
+      },
+    });
+
+    const existingIds = companies.map((item) => item.id);
+    const missingIds = ids.filter((itemId) => !existingIds.includes(itemId));
+    if (missingIds.length > 0) {
+      throw new BadRequestException(
+        getLocaleText(
+          'personNotFound',
+          locale,
+          `Person(s) with ID(s) ${missingIds.join(', ')} not found.`,
+        ),
+      );
+    }
+
+    const invalidIds = companies
+      .filter((item) => item.type !== 'company')
+      .map((item) => item.id);
+    if (invalidIds.length > 0) {
+      throw new BadRequestException(
+        getLocaleText(
+          'companyRelationInvalidTarget',
+          locale,
+          'Only company records can be managed as accounts.',
+        ),
+      );
+    }
+
+    return this.delete({ ids }, locale);
+  }
+
+  async listActivities(paginationParams: CrmActivityListParams) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+    const page = Math.max(Number(paginationParams.page || 1), 1);
+    const pageSize = Math.max(Number(paginationParams.pageSize || 12), 1);
+    const skip = (page - 1) * pageSize;
+    const filters = this.buildCrmActivitySqlFilters({
+      allowCompanyRegistration,
+      search: this.normalizeTextOrNull(paginationParams.search),
+      status: paginationParams.status,
+      type: paginationParams.type,
+      priority: paginationParams.priority,
+    });
+
+    const totalRows = await this.prismaService.$queryRaw<Array<{ total: unknown }>>(
+      Prisma.sql`
+        SELECT COUNT(*) AS total
+        FROM crm_activity a
+        INNER JOIN person p ON p.id = a.person_id
+        LEFT JOIN "user" owner_user ON owner_user.id = a.owner_user_id
+        WHERE 1 = 1
+        ${filters}
+      `,
+    );
+    const total = this.coerceCount(totalRows[0]?.total);
+
+    if (total === 0) {
+      return this.createEmptyCrmActivityPagination(page, pageSize);
+    }
+
+    const rows = await this.prismaService.$queryRaw<Array<Record<string, unknown>>>(
+      Prisma.sql`
+        SELECT
+          a.id,
+          a.person_id,
+          a.owner_user_id,
+          a.type,
+          a.subject,
+          a.notes,
+          a.due_at,
+          a.completed_at,
+          a.created_at,
+          a.priority,
+          p.name AS person_name,
+          p.type AS person_type,
+          p.status AS person_status,
+          pc.trade_name AS person_trade_name,
+          owner_user.name AS owner_user_name
+        FROM crm_activity a
+        INNER JOIN person p ON p.id = a.person_id
+        LEFT JOIN person_company pc ON pc.id = p.id
+        LEFT JOIN "user" owner_user ON owner_user.id = a.owner_user_id
+        WHERE 1 = 1
+        ${filters}
+        ORDER BY a.due_at ASC, a.id ASC
+        LIMIT ${pageSize}
+        OFFSET ${skip}
+      `,
+    );
+
+    const data = rows.map((row) => this.mapCrmActivityListRow(row));
+    const lastPage = Math.max(1, Math.ceil(total / pageSize));
+
+    return {
+      total,
+      lastPage,
+      page,
+      pageSize,
+      prev: page > 1 ? page - 1 : null,
+      next: page < lastPage ? page + 1 : null,
+      data,
+    };
+  }
+
+  async getActivityStats() {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+    const visibilityFilter = allowCompanyRegistration
+      ? Prisma.empty
+      : Prisma.sql`AND p.type = 'individual'`;
+
+    const rows = await this.prismaService.$queryRaw<
+      Array<{
+        total: unknown;
+        pending: unknown;
+        overdue: unknown;
+        completed: unknown;
+      }>
+    >(
+      Prisma.sql`
+        SELECT
+          COUNT(*) AS total,
+          COUNT(*) FILTER (
+            WHERE a.completed_at IS NULL
+              AND a.due_at >= NOW()
+          ) AS pending,
+          COUNT(*) FILTER (
+            WHERE a.completed_at IS NULL
+              AND a.due_at < NOW()
+          ) AS overdue,
+          COUNT(*) FILTER (
+            WHERE a.completed_at IS NOT NULL
+          ) AS completed
+        FROM crm_activity a
+        INNER JOIN person p ON p.id = a.person_id
+        WHERE 1 = 1
+        ${visibilityFilter}
+      `,
+    );
+
+    return {
+      total: this.coerceCount(rows[0]?.total),
+      pending: this.coerceCount(rows[0]?.pending),
+      overdue: this.coerceCount(rows[0]?.overdue),
+      completed: this.coerceCount(rows[0]?.completed),
+    };
+  }
+
+  async getActivity(id: number, locale: string): Promise<CrmActivityDetail> {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+    const visibilityFilter = allowCompanyRegistration
+      ? Prisma.empty
+      : Prisma.sql`AND p.type = 'individual'`;
+
+    const rows = await this.prismaService.$queryRaw<Array<Record<string, unknown>>>(
+      Prisma.sql`
+        SELECT
+          a.id,
+          a.person_id,
+          a.owner_user_id,
+          a.created_by_user_id,
+          a.completed_by_user_id,
+          a.type,
+          a.subject,
+          a.notes,
+          a.due_at,
+          a.completed_at,
+          a.created_at,
+          a.priority,
+          a.source_kind,
+          p.name AS person_name,
+          p.type AS person_type,
+          p.status AS person_status,
+          pc.trade_name AS person_trade_name,
+          owner_user.name AS owner_user_name,
+          created_by_user.name AS created_by_user_name,
+          completed_by_user.name AS completed_by_user_name
+        FROM crm_activity a
+        INNER JOIN person p ON p.id = a.person_id
+        LEFT JOIN person_company pc ON pc.id = p.id
+        LEFT JOIN "user" owner_user ON owner_user.id = a.owner_user_id
+        LEFT JOIN "user" created_by_user ON created_by_user.id = a.created_by_user_id
+        LEFT JOIN "user" completed_by_user ON completed_by_user.id = a.completed_by_user_id
+        WHERE a.id = ${id}
+        ${visibilityFilter}
+        LIMIT 1
+      `,
+    );
+
+    const row = rows[0];
+    if (!row) {
+      throw new NotFoundException(
+        getLocaleText(
+          'personNotFound',
+          locale,
+          `Activity with ID ${id} not found`,
+        ),
+      );
+    }
+
+    return this.mapCrmActivityDetailRow(row);
+  }
+
+  async completeActivity(
+    id: number,
+    locale: string,
+    user: { id?: number; name?: string | null },
+  ) {
+    const actorUserId = Number(user?.id || 0) || null;
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+    const visibilityFilter = allowCompanyRegistration
+      ? Prisma.empty
+      : Prisma.sql`AND p.type = 'individual'`;
+
+    return this.prismaService.$transaction(async (tx) => {
+      const rows = (await tx.$queryRaw(
+        Prisma.sql`
+          SELECT
+            a.id,
+            a.person_id,
+            a.completed_at,
+            a.source_kind
+          FROM crm_activity a
+          INNER JOIN person p ON p.id = a.person_id
+          WHERE a.id = ${id}
+          ${visibilityFilter}
+          LIMIT 1
+        `,
+      )) as Array<{
+        id: number;
+        person_id: number;
+        completed_at: Date | null;
+        source_kind: CrmActivitySourceKind;
+      }>;
+      const activity = rows[0];
+
+      if (!activity) {
+        throw new NotFoundException(
+          getLocaleText(
+            'personNotFound',
+            locale,
+            `Activity with ID ${id} not found`,
+          ),
+        );
+      }
+
+      if (activity.completed_at) {
+        return {
+          success: true,
+          completed_at: activity.completed_at.toISOString(),
+        };
+      }
+
+      const completedAt = new Date();
+
+      await tx.$executeRaw(
+        Prisma.sql`
+          UPDATE crm_activity
+          SET
+            completed_at = CAST(${completedAt.toISOString()} AS TIMESTAMPTZ),
+            completed_by_user_id = ${actorUserId},
+            updated_at = NOW()
+          WHERE id = ${id}
+        `,
+      );
+
+      if (activity.source_kind === 'followup') {
+        await this.upsertMetadataValue(
+          tx,
+          activity.person_id,
+          NEXT_ACTION_AT_METADATA_KEY,
+          null,
+        );
+      }
+
+      return {
+        success: true,
+        completed_at: completedAt.toISOString(),
+      };
+    });
+  }
+
+  async listFollowups(
+    paginationParams: FollowupListParams,
+    _currentUserId?: number,
+  ) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+    const page = Math.max(Number(paginationParams.page || 1), 1);
+    const pageSize = Math.max(Number(paginationParams.pageSize || 12), 1);
+    const skip = (page - 1) * pageSize;
+    const searchPersonIds = await this.findFollowupSearchPersonIds(
+      paginationParams.search,
+      allowCompanyRegistration,
+    );
+
+    if (searchPersonIds && searchPersonIds.length === 0) {
+      return this.createEmptyFollowupPagination(page, pageSize);
+    }
+
+    const filters = this.buildFollowupSqlFilters({
+      allowCompanyRegistration,
+      searchPersonIds,
+      status: paginationParams.status,
+      dateFrom: paginationParams.date_from,
+      dateTo: paginationParams.date_to,
+    });
+    const followupTimestampSql = this.getFollowupTimestampSql();
+    const totalRows = await this.prismaService.$queryRaw<Array<{ total: unknown }>>(
+      Prisma.sql`
+        SELECT COUNT(*) AS total
+        FROM person p
+        INNER JOIN person_metadata pm_next
+          ON pm_next.person_id = p.id
+         AND pm_next.key = ${NEXT_ACTION_AT_METADATA_KEY}
+        WHERE 1 = 1
+        ${filters}
+      `,
+    );
+    const total = this.coerceCount(totalRows[0]?.total);
+
+    if (total === 0) {
+      return this.createEmptyFollowupPagination(page, pageSize);
+    }
+
+    const rows = await this.prismaService.$queryRaw<Array<{ person_id: number }>>(
+      Prisma.sql`
+        SELECT p.id AS person_id
+        FROM person p
+        INNER JOIN person_metadata pm_next
+          ON pm_next.person_id = p.id
+         AND pm_next.key = ${NEXT_ACTION_AT_METADATA_KEY}
+        WHERE 1 = 1
+        ${filters}
+        ORDER BY ${followupTimestampSql} ASC, p.id ASC
+        LIMIT ${pageSize}
+        OFFSET ${skip}
+      `,
+    );
+
+    const personIds = rows.map((row) => row.person_id).filter((id) => id > 0);
+    const people =
+      personIds.length > 0
+        ? await this.prismaService.person.findMany({
+            where: {
+              id: {
+                in: personIds,
+              },
+            },
+            include: {
+              person_address: {
+                include: {
+                  address: true,
+                },
+              },
+              contact: true,
+              document: true,
+              person_metadata: true,
+            },
+          })
+        : [];
+
+    const enrichedPeople = await this.enrichPeople(
+      people as any[],
+      allowCompanyRegistration,
+    );
+    const personById = new Map(
+      enrichedPeople.map((person) => [person.id, person]),
+    );
+    const data = rows
+      .map((row) => {
+        const person = personById.get(row.person_id);
+        const nextActionAt = this.normalizeDateTimeOrNull(person?.next_action_at);
+
+        if (!person || !nextActionAt) {
+          return null;
+        }
+
+        return {
+          person,
+          next_action_at: nextActionAt,
+          last_interaction_at:
+            this.normalizeDateTimeOrNull(person.last_interaction_at) ?? null,
+          status: this.getFollowupStatus(nextActionAt),
+        } as FollowupListItem;
+      })
+      .filter((item): item is FollowupListItem => item != null);
+
+    const lastPage = Math.max(1, Math.ceil(total / pageSize));
+
+    return {
+      total,
+      lastPage,
+      page,
+      pageSize,
+      prev: page > 1 ? page - 1 : null,
+      next: page < lastPage ? page + 1 : null,
+      data,
+    };
+  }
+
+  async getFollowupStats(
+    query: FollowupStatsQueryDTO,
+    _currentUserId?: number,
+  ) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+    const searchPersonIds = await this.findFollowupSearchPersonIds(
+      query.search,
+      allowCompanyRegistration,
+    );
+
+    if (searchPersonIds && searchPersonIds.length === 0) {
+      return {
+        total: 0,
+        today: 0,
+        overdue: 0,
+        upcoming: 0,
+      };
+    }
+
+    const filters = this.buildFollowupSqlFilters({
+      allowCompanyRegistration,
+      searchPersonIds,
+    });
+    const followupTimestampSql = this.getFollowupTimestampSql();
+    const { todayStartIso, tomorrowStartIso } =
+      this.getFollowupDayBoundaryIsoStrings();
+    const rows = await this.prismaService.$queryRaw<
+      Array<{
+        total: unknown;
+        today: unknown;
+        overdue: unknown;
+        upcoming: unknown;
+      }>
+    >(
+      Prisma.sql`
+        SELECT
+          COUNT(*) AS total,
+          COUNT(*) FILTER (
+            WHERE ${followupTimestampSql} >= CAST(${todayStartIso} AS TIMESTAMPTZ)
+              AND ${followupTimestampSql} < CAST(${tomorrowStartIso} AS TIMESTAMPTZ)
+          ) AS today,
+          COUNT(*) FILTER (
+            WHERE ${followupTimestampSql} < CAST(${todayStartIso} AS TIMESTAMPTZ)
+          ) AS overdue,
+          COUNT(*) FILTER (
+            WHERE ${followupTimestampSql} >= CAST(${tomorrowStartIso} AS TIMESTAMPTZ)
+          ) AS upcoming
+        FROM person p
+        INNER JOIN person_metadata pm_next
+          ON pm_next.person_id = p.id
+         AND pm_next.key = ${NEXT_ACTION_AT_METADATA_KEY}
+        WHERE 1 = 1
+        ${filters}
+      `,
+    );
+
+    return {
+      total: this.coerceCount(rows[0]?.total),
+      today: this.coerceCount(rows[0]?.today),
+      overdue: this.coerceCount(rows[0]?.overdue),
+      upcoming: this.coerceCount(rows[0]?.upcoming),
+    };
+  }
+
+  async get(locale: string, id: number) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+
+    const person = await this.prismaService.person.findUnique({
+      where: { id },
+      include: {
+        person_address: {
+          include: {
+            address: true,
+          },
+        },
+        contact: true,
+        document: true,
+        person_metadata: true,
+      },
+    });
+
+    if (!person) {
+      throw new BadRequestException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
+
+    if (!allowCompanyRegistration && person.type === 'company') {
+      throw new NotFoundException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
+
+    const [normalized] = await this.enrichPeople(
+      [person as any],
+      allowCompanyRegistration,
+    );
+    return normalized;
+  }
+
+  async listInteractions(id: number, locale: string) {
+    const person = await this.ensurePersonAccessible(id, locale);
+    const metadata = await this.prismaService.person_metadata.findFirst({
+      where: {
+        person_id: person.id,
+        key: INTERACTIONS_METADATA_KEY,
+      },
+      select: {
+        value: true,
+      },
+    });
+
+    return this.metadataToInteractions(metadata?.value);
+  }
+
+  async createInteraction(
+    id: number,
+    data: CreateInteractionDTO,
+    locale: string,
+    user: { id?: number; name?: string | null },
+  ) {
+    const person = await this.ensurePersonAccessible(id, locale);
+    const interaction = this.buildInteractionRecord(data, user);
+    const ownerUserId = await this.getPersonOwnerUserId(person.id);
+
+    await this.prismaService.$transaction(async (tx) => {
+      const currentInteractions = await this.loadInteractionsFromTx(tx, person.id);
+      const nextInteractions = this.sortInteractions([
+        interaction,
+        ...currentInteractions,
+      ]);
+
+      await this.upsertMetadataValue(
+        tx,
+        person.id,
+        INTERACTIONS_METADATA_KEY,
+        nextInteractions,
+      );
+      await this.upsertMetadataValue(
+        tx,
+        person.id,
+        LAST_INTERACTION_AT_METADATA_KEY,
+        interaction.created_at,
+      );
+      await this.createCompletedInteractionActivity(tx, {
+        personId: person.id,
+        ownerUserId,
+        interaction,
+        actorUserId: Number(user?.id || 0) || null,
+      });
+    });
+
+    return interaction;
+  }
+
+  async scheduleFollowup(
+    id: number,
+    data: CreateFollowupDTO,
+    locale: string,
+    user: { id?: number; name?: string | null },
+  ) {
+    const person = await this.ensurePersonAccessible(id, locale);
+    const normalizedNextActionAt = this.normalizeDateTimeOrNull(data.next_action_at);
+    const ownerUserId = await this.getPersonOwnerUserId(person.id);
+
+    if (!normalizedNextActionAt) {
+      throw new BadRequestException(
+        getLocaleText(
+          'validation.dateMustBeString',
+          locale,
+          'next_action_at must be a valid datetime.',
+        ),
+      );
+    }
+
+    await this.prismaService.$transaction(async (tx) => {
+      await this.upsertMetadataValue(
+        tx,
+        person.id,
+        NEXT_ACTION_AT_METADATA_KEY,
         normalizedNextActionAt,
       );
 
@@ -640,6 +1662,14 @@ export class PersonService {
           interaction.created_at,
         );
       }
+
+      await this.upsertFollowupActivity(tx, {
+        personId: person.id,
+        ownerUserId,
+        dueAt: normalizedNextActionAt,
+        notes: data.notes,
+        actorUserId: Number(user?.id || 0) || null,
+      });
     });
 
     return {
@@ -861,6 +1891,185 @@ export class PersonService {
     ]);
   }
 
+  private async findFollowupSearchPersonIds(
+    search: string | undefined,
+    allowCompanyRegistration: boolean,
+  ) {
+    const normalizedSearch = this.normalizeTextOrNull(search);
+
+    if (!normalizedSearch) {
+      return null;
+    }
+
+    const where: Prisma.personWhereInput = {
+      OR: await this.buildSearchFilters(normalizedSearch),
+    };
+
+    if (!allowCompanyRegistration) {
+      where.type = 'individual';
+    }
+
+    const people = await this.prismaService.person.findMany({
+      where,
+      select: {
+        id: true,
+      },
+    });
+
+    return people.map((person) => person.id).filter((id) => id > 0);
+  }
+
+  private buildFollowupSqlFilters({
+    allowCompanyRegistration,
+    searchPersonIds,
+    status,
+    dateFrom,
+    dateTo,
+  }: {
+    allowCompanyRegistration: boolean;
+    searchPersonIds?: number[] | null;
+    status?: 'all' | FollowupStatus;
+    dateFrom?: string;
+    dateTo?: string;
+  }) {
+    const filters: Prisma.Sql[] = [];
+    const followupTimestampSql = this.getFollowupTimestampSql();
+
+    if (!allowCompanyRegistration) {
+      filters.push(Prisma.sql`AND p.type = 'individual'`);
+    }
+
+    if (searchPersonIds && searchPersonIds.length > 0) {
+      filters.push(
+        Prisma.sql`AND p.id IN (${Prisma.join(searchPersonIds)})`,
+      );
+    }
+
+    const { todayStartIso, tomorrowStartIso } =
+      this.getFollowupDayBoundaryIsoStrings();
+
+    if (status === 'overdue') {
+      filters.push(
+        Prisma.sql`AND ${followupTimestampSql} < CAST(${todayStartIso} AS TIMESTAMPTZ)`,
+      );
+    } else if (status === 'today') {
+      filters.push(
+        Prisma.sql`AND ${followupTimestampSql} >= CAST(${todayStartIso} AS TIMESTAMPTZ)`,
+      );
+      filters.push(
+        Prisma.sql`AND ${followupTimestampSql} < CAST(${tomorrowStartIso} AS TIMESTAMPTZ)`,
+      );
+    } else if (status === 'upcoming') {
+      filters.push(
+        Prisma.sql`AND ${followupTimestampSql} >= CAST(${tomorrowStartIso} AS TIMESTAMPTZ)`,
+      );
+    }
+
+    const dateFromIso = this.normalizeDateOnlyBoundary(dateFrom, 'start');
+    if (dateFromIso) {
+      filters.push(
+        Prisma.sql`AND ${followupTimestampSql} >= CAST(${dateFromIso} AS TIMESTAMPTZ)`,
+      );
+    }
+
+    const dateToIso = this.normalizeDateOnlyBoundary(dateTo, 'endExclusive');
+    if (dateToIso) {
+      filters.push(
+        Prisma.sql`AND ${followupTimestampSql} < CAST(${dateToIso} AS TIMESTAMPTZ)`,
+      );
+    }
+
+    return filters.length > 0
+      ? Prisma.join(filters, '\n')
+      : Prisma.empty;
+  }
+
+  private createEmptyFollowupPagination(page: number, pageSize: number) {
+    return {
+      total: 0,
+      lastPage: 1,
+      page,
+      pageSize,
+      prev: page > 1 ? page - 1 : null,
+      next: null,
+      data: [] as FollowupListItem[],
+    };
+  }
+
+  private getFollowupTimestampSql() {
+    return Prisma.sql`CAST(TRIM(BOTH '"' FROM pm_next.value::text) AS TIMESTAMPTZ)`;
+  }
+
+  private getFollowupDayBoundaryDates(reference = new Date()) {
+    const todayStart = new Date(
+      reference.getFullYear(),
+      reference.getMonth(),
+      reference.getDate(),
+    );
+    const tomorrowStart = new Date(todayStart);
+    tomorrowStart.setDate(tomorrowStart.getDate() + 1);
+
+    return {
+      todayStart,
+      tomorrowStart,
+    };
+  }
+
+  private getFollowupDayBoundaryIsoStrings(reference = new Date()) {
+    const { todayStart, tomorrowStart } =
+      this.getFollowupDayBoundaryDates(reference);
+
+    return {
+      todayStartIso: todayStart.toISOString(),
+      tomorrowStartIso: tomorrowStart.toISOString(),
+    };
+  }
+
+  private normalizeDateOnlyBoundary(
+    value: string | undefined,
+    mode: 'start' | 'endExclusive',
+  ) {
+    if (!value) {
+      return null;
+    }
+
+    const parsed = new Date(`${value}T00:00:00`);
+
+    if (Number.isNaN(parsed.getTime())) {
+      return null;
+    }
+
+    if (mode === 'endExclusive') {
+      parsed.setDate(parsed.getDate() + 1);
+    }
+
+    return parsed.toISOString();
+  }
+
+  private getFollowupStatus(nextActionAt: string): FollowupStatus {
+    const parsed = new Date(nextActionAt);
+    const { todayStart, tomorrowStart } = this.getFollowupDayBoundaryDates();
+
+    if (parsed < todayStart) {
+      return 'overdue';
+    }
+
+    if (parsed < tomorrowStart) {
+      return 'today';
+    }
+
+    return 'upcoming';
+  }
+
+  private coerceCount(value: unknown) {
+    if (typeof value === 'bigint') {
+      return Number(value);
+    }
+
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+
   async openPublicAvatar(locale: string, fileId: number, res: any) {
     const personWithAvatar = await this.prismaService.person.findFirst({
       where: {
@@ -885,7 +2094,179 @@ export class PersonService {
       'Cache-Control': 'public, max-age=3600',
     });
 
-    res.send(buffer);
+    res.send(buffer);
+  }
+
+  private resolveDashboardRanges(
+    query: DashboardQueryDTO,
+    locale: string,
+  ) {
+    const period: CrmDashboardPeriod = query.period ?? '30d';
+    const now = new Date();
+
+    if (period === 'custom') {
+      if (!query.date_from || !query.date_to) {
+        throw new BadRequestException(
+          getLocaleText(
+            'validation.dateMustBeString',
+            locale,
+            'date_from and date_to are required when period is custom.',
+          ),
+        );
+      }
+
+      const start = this.startOfDay(this.parseDateOrThrow(query.date_from, locale));
+      const end = this.endOfDay(this.parseDateOrThrow(query.date_to, locale));
+
+      if (start.getTime() > end.getTime()) {
+        throw new BadRequestException(
+          getLocaleText(
+            'validation.dateMustBeString',
+            locale,
+            'date_from must be less than or equal to date_to.',
+          ),
+        );
+      }
+
+      return {
+        created: { start, end },
+        operational: { start, end },
+      };
+    }
+
+    const dayCount = Number(period.replace('d', ''));
+    const createdStart = this.startOfDay(this.addDays(now, -(dayCount - 1)));
+    const createdEnd = this.endOfDay(now);
+    const operationalStart = this.startOfDay(this.addDays(now, -(dayCount - 1)));
+    const operationalEnd = this.endOfDay(this.addDays(now, dayCount - 1));
+
+    return {
+      created: {
+        start: createdStart,
+        end: createdEnd,
+      },
+      operational: {
+        start: operationalStart,
+        end: operationalEnd,
+      },
+    };
+  }
+
+  private buildDashboardOwnerPerformance(people: any[]): DashboardOwnerPerformanceItem[] {
+    const byOwnerId = new Map<number, DashboardOwnerPerformanceItem>();
+
+    for (const person of people) {
+      const ownerUserId = this.coerceNumber(person.owner_user_id);
+      if (ownerUserId <= 0) {
+        continue;
+      }
+
+      const current =
+        byOwnerId.get(ownerUserId) ??
+        {
+          owner_user_id: ownerUserId,
+          owner_name: person.owner_user?.name || `#${ownerUserId}`,
+          leads: 0,
+          customers: 0,
+          pipeline_value: 0,
+        };
+
+      current.leads += 1;
+      if (person.lifecycle_stage === 'customer') {
+        current.customers += 1;
+      }
+      if (person.lifecycle_stage !== 'lost') {
+        current.pipeline_value += this.coerceNumber(person.deal_value);
+      }
+
+      byOwnerId.set(ownerUserId, current);
+    }
+
+    return Array.from(byOwnerId.values()).sort((left, right) =>
+      left.owner_name.localeCompare(right.owner_name),
+    );
+  }
+
+  private mapDashboardListItem(
+    person: any,
+    {
+      includeCreatedAt,
+      includeNextActionAt,
+    }: {
+      includeCreatedAt: boolean;
+      includeNextActionAt: boolean;
+    },
+  ): DashboardListPersonItem {
+    const source = (person.source ?? 'other') as CrmDashboardSourceKey;
+    const lifecycleStage = (person.lifecycle_stage ?? 'new') as CrmDashboardStageKey;
+
+    return {
+      id: person.id,
+      name: person.name,
+      trade_name: person.trade_name ?? null,
+      owner_user: person.owner_user ?? null,
+      source,
+      lifecycle_stage: lifecycleStage,
+      ...(includeNextActionAt && person.next_action_at
+        ? { next_action_at: person.next_action_at }
+        : {}),
+      ...(includeCreatedAt && person.created_at
+        ? {
+            created_at:
+              this.normalizeDateTimeOrNull(person.created_at) ?? person.created_at,
+          }
+        : {}),
+    };
+  }
+
+  private isDateWithinRange(
+    value: unknown,
+    range: { start: Date; end: Date },
+  ) {
+    const parsed = this.parseDateOrNull(value);
+    if (!parsed) {
+      return false;
+    }
+
+    return (
+      parsed.getTime() >= range.start.getTime() &&
+      parsed.getTime() <= range.end.getTime()
+    );
+  }
+
+  private parseDateOrThrow(value: string, locale: string) {
+    const parsed = /^\d{4}-\d{2}-\d{2}$/.test(value)
+      ? this.parseDateOrNull(`${value}T00:00:00`)
+      : this.parseDateOrNull(value);
+    if (!parsed) {
+      throw new BadRequestException(
+        getLocaleText(
+          'validation.dateMustBeString',
+          locale,
+          `Invalid date value: ${value}`,
+        ),
+      );
+    }
+
+    return parsed;
+  }
+
+  private addDays(date: Date, amount: number) {
+    const next = new Date(date);
+    next.setDate(next.getDate() + amount);
+    return next;
+  }
+
+  private startOfDay(date: Date) {
+    const next = new Date(date);
+    next.setHours(0, 0, 0, 0);
+    return next;
+  }
+
+  private endOfDay(date: Date) {
+    const next = new Date(date);
+    next.setHours(23, 59, 59, 999);
+    return next;
   }
 
   private async enrichPeople(people: any[], allowCompanyRegistration = true) {
@@ -1276,6 +2657,15 @@ export class PersonService {
       create: {
         id: personId,
         trade_name: this.normalizeTextOrNull(data.trade_name),
+        industry: this.normalizeTextOrNull(data.industry),
+        website: this.normalizeTextOrNull(data.website),
+        annual_revenue: this.normalizeDecimalOrNull(data.annual_revenue),
+        employee_count: this.normalizeIntegerOrNull(data.employee_count),
+        account_lifecycle_stage: this.normalizeAccountLifecycleStage(
+          data.lifecycle_stage,
+        ),
+        city: this.normalizeTextOrNull(data.city),
+        state: this.normalizeStateOrNull(data.state),
         foundation_date: this.parseDateOrNull(data.foundation_date),
         legal_nature: this.normalizeTextOrNull(data.legal_nature),
         headquarter_id: normalizedHeadquarterId > 0 ? normalizedHeadquarterId : null,
@@ -1285,6 +2675,34 @@ export class PersonService {
           data.trade_name === undefined
             ? undefined
             : this.normalizeTextOrNull(data.trade_name),
+        industry:
+          data.industry === undefined
+            ? undefined
+            : this.normalizeTextOrNull(data.industry),
+        website:
+          data.website === undefined
+            ? undefined
+            : this.normalizeTextOrNull(data.website),
+        annual_revenue:
+          data.annual_revenue === undefined
+            ? undefined
+            : this.normalizeDecimalOrNull(data.annual_revenue),
+        employee_count:
+          data.employee_count === undefined
+            ? undefined
+            : this.normalizeIntegerOrNull(data.employee_count),
+        account_lifecycle_stage:
+          data.lifecycle_stage === undefined
+            ? undefined
+            : this.normalizeAccountLifecycleStage(data.lifecycle_stage),
+        city:
+          data.city === undefined
+            ? undefined
+            : this.normalizeTextOrNull(data.city),
+        state:
+          data.state === undefined
+            ? undefined
+            : this.normalizeStateOrNull(data.state),
         foundation_date:
           data.foundation_date === undefined
             ? undefined
@@ -1963,6 +3381,24 @@ export class PersonService {
     return Number.isNaN(date.getTime()) ? null : date;
   }
 
+  private normalizeDecimalOrNull(value: unknown): Prisma.Decimal | null {
+    if (value == null || value === '') {
+      return null;
+    }
+
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? new Prisma.Decimal(parsed) : null;
+  }
+
+  private normalizeIntegerOrNull(value: unknown): number | null {
+    if (value == null || value === '') {
+      return null;
+    }
+
+    const parsed = Number(value);
+    return Number.isInteger(parsed) ? parsed : null;
+  }
+
   private normalizeTextOrNull(value: unknown): string | null {
     if (typeof value !== 'string') {
       return value == null ? null : String(value);
@@ -1983,6 +3419,25 @@ export class PersonService {
     return Number.isFinite(parsed) ? parsed : 0;
   }
 
+  private normalizeStateOrNull(value: unknown): string | null {
+    const normalized = this.normalizeTextOrNull(value)?.toUpperCase() ?? null;
+    return normalized ? normalized.slice(0, 2) : null;
+  }
+
+  private normalizeAccountLifecycleStage(
+    value: unknown,
+  ): AccountLifecycleStage | null {
+    const normalized = this.normalizeTextOrNull(value);
+
+    if (!normalized) {
+      return null;
+    }
+
+    return ACCOUNT_LIFECYCLE_STAGES.includes(normalized as AccountLifecycleStage)
+      ? (normalized as AccountLifecycleStage)
+      : null;
+  }
+
   private resolveRequestedOwnerUserId(
     ownerUserId: string | number | undefined,
     mine: string | boolean | undefined,
@@ -2024,6 +3479,367 @@ export class PersonService {
     return person;
   }
 
+  private async getPersonOwnerUserId(personId: number) {
+    const metadata = await this.prismaService.person_metadata.findFirst({
+      where: {
+        person_id: personId,
+        key: OWNER_USER_METADATA_KEY,
+      },
+      select: {
+        value: true,
+      },
+    });
+
+    const ownerUserId = this.metadataToNumber(metadata?.value);
+    return ownerUserId && ownerUserId > 0 ? ownerUserId : null;
+  }
+
+  private async upsertFollowupActivity(
+    tx: any,
+    {
+      personId,
+      ownerUserId,
+      dueAt,
+      notes,
+      actorUserId,
+    }: {
+      personId: number;
+      ownerUserId: number | null;
+      dueAt: string;
+      notes?: string | null;
+      actorUserId: number | null;
+    },
+  ) {
+    const existingRows = (await tx.$queryRaw(
+      Prisma.sql`
+        SELECT id
+        FROM crm_activity
+        WHERE person_id = ${personId}
+          AND source_kind = 'followup'
+          AND completed_at IS NULL
+        ORDER BY id DESC
+        LIMIT 1
+      `,
+    )) as Array<{ id: number }>;
+    const existing = existingRows[0];
+
+    const normalizedNotes = this.normalizeTextOrNull(notes);
+
+    if (existing) {
+      await tx.$executeRaw(
+        Prisma.sql`
+          UPDATE crm_activity
+          SET
+            owner_user_id = ${ownerUserId},
+            type = CAST(${'task'} AS crm_activity_type_enum),
+            subject = ${this.getFollowupActivitySubject()},
+            notes = ${normalizedNotes},
+            due_at = CAST(${dueAt} AS TIMESTAMPTZ),
+            priority = CAST(${'medium'} AS crm_activity_priority_enum),
+            updated_at = NOW()
+          WHERE id = ${existing.id}
+        `,
+      );
+      return;
+    }
+
+    await tx.$executeRaw(
+      Prisma.sql`
+        INSERT INTO crm_activity (
+          person_id,
+          owner_user_id,
+          created_by_user_id,
+          type,
+          subject,
+          notes,
+          due_at,
+          priority,
+          source_kind,
+          created_at,
+          updated_at
+        )
+        VALUES (
+          ${personId},
+          ${ownerUserId},
+          ${actorUserId},
+          CAST(${'task'} AS crm_activity_type_enum),
+          ${this.getFollowupActivitySubject()},
+          ${normalizedNotes},
+          CAST(${dueAt} AS TIMESTAMPTZ),
+          CAST(${'medium'} AS crm_activity_priority_enum),
+          CAST(${'followup'} AS crm_activity_source_kind_enum),
+          NOW(),
+          NOW()
+        )
+      `,
+    );
+  }
+
+  private async createCompletedInteractionActivity(
+    tx: any,
+    {
+      personId,
+      ownerUserId,
+      interaction,
+      actorUserId,
+    }: {
+      personId: number;
+      ownerUserId: number | null;
+      interaction: PersonInteractionRecord;
+      actorUserId: number | null;
+    },
+  ) {
+    const completedAt = new Date(interaction.created_at);
+
+    await tx.$executeRaw(
+      Prisma.sql`
+        INSERT INTO crm_activity (
+          person_id,
+          owner_user_id,
+          created_by_user_id,
+          completed_by_user_id,
+          type,
+          subject,
+          notes,
+          due_at,
+          completed_at,
+          priority,
+          source_kind,
+          created_at,
+          updated_at
+        )
+        VALUES (
+          ${personId},
+          ${ownerUserId},
+          ${actorUserId},
+          ${actorUserId},
+          CAST(${interaction.type} AS crm_activity_type_enum),
+          ${this.getInteractionActivitySubject(interaction.type)},
+          ${this.normalizeTextOrNull(interaction.notes)},
+          CAST(${interaction.created_at} AS TIMESTAMPTZ),
+          CAST(${interaction.created_at} AS TIMESTAMPTZ),
+          CAST(${'medium'} AS crm_activity_priority_enum),
+          CAST(${'interaction'} AS crm_activity_source_kind_enum),
+          CAST(${interaction.created_at} AS TIMESTAMPTZ),
+          NOW()
+        )
+      `,
+    );
+  }
+
+  private getFollowupActivitySubject() {
+    return 'Follow-up';
+  }
+
+  private getInteractionActivitySubject(type: PersonInteractionRecord['type']) {
+    switch (type) {
+      case PersonInteractionTypeDTO.CALL:
+        return 'Call';
+      case PersonInteractionTypeDTO.EMAIL:
+        return 'Email';
+      case PersonInteractionTypeDTO.WHATSAPP:
+        return 'WhatsApp';
+      case PersonInteractionTypeDTO.MEETING:
+        return 'Meeting';
+      case PersonInteractionTypeDTO.NOTE:
+      default:
+        return 'Note';
+    }
+  }
+
+  private async ensureCompanyAccountAccessible(id: number, locale: string) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+
+    if (!allowCompanyRegistration) {
+      throw new NotFoundException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
+
+    const person = await this.prismaService.person.findUnique({
+      where: { id },
+      select: {
+        id: true,
+        name: true,
+        status: true,
+        type: true,
+      },
+    });
+
+    if (!person || person.type !== 'company') {
+      throw new BadRequestException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
+
+    return person;
+  }
+
+  private async loadAccountPeopleByIds(personIds: number[]) {
+    if (personIds.length === 0) {
+      return [];
+    }
+
+    const people = await this.prismaService.person.findMany({
+      where: {
+        id: {
+          in: personIds,
+        },
+      },
+      include: {
+        contact: {
+          include: {
+            contact_type: true,
+          },
+        },
+        person_metadata: true,
+      },
+    });
+
+    return this.enrichPeople(people as any[], true);
+  }
+
+  private mapAccountFromPerson(person: any, company: any): AccountListItem {
+    return {
+      id: person.id,
+      name: person.name,
+      trade_name: company.trade_name ?? null,
+      status: person.status,
+      industry: company.industry ?? null,
+      website: company.website ?? null,
+      email: this.getPrimaryAccountContactValue(person.contact, ['EMAIL']),
+      phone: this.getPrimaryAccountContactValue(person.contact, [
+        'PHONE',
+        'MOBILE',
+        'WHATSAPP',
+      ]),
+      owner_user_id: person.owner_user_id ?? null,
+      owner_user: person.owner_user ?? null,
+      annual_revenue:
+        company.annual_revenue == null ? null : Number(company.annual_revenue),
+      employee_count: company.employee_count ?? null,
+      lifecycle_stage: company.account_lifecycle_stage ?? null,
+      city: company.city ?? null,
+      state: company.state ?? null,
+      created_at: person.created_at?.toISOString?.() ?? String(person.created_at),
+      last_interaction_at:
+        this.normalizeDateTimeOrNull(person.last_interaction_at) ?? null,
+    };
+  }
+
+  private getPrimaryAccountContactValue(
+    contacts: any[] | undefined,
+    codes: string[],
+  ): string | null {
+    const normalizedCodes = new Set(codes.map((code) => code.toUpperCase()));
+    const items = Array.isArray(contacts)
+      ? contacts.filter((contact) =>
+          normalizedCodes.has(
+            String(contact?.contact_type?.code || '').toUpperCase(),
+          ),
+        )
+      : [];
+
+    const primary = items.find((contact) => contact?.is_primary);
+    const fallback = items[0];
+    return this.normalizeTextOrNull(primary?.value ?? fallback?.value);
+  }
+
+  private async upsertPrimaryAccountContact(
+    tx: any,
+    personId: number,
+    code: 'EMAIL' | 'PHONE',
+    value: unknown,
+  ) {
+    const normalizedValue = this.normalizeTextOrNull(value);
+    const allowedCodes =
+      code === 'PHONE' ? ['PHONE', 'MOBILE', 'WHATSAPP'] : ['EMAIL'];
+
+    const type = await tx.contact_type.findFirst({
+      where: {
+        code: {
+          equals: code,
+          mode: 'insensitive',
+        },
+      },
+      select: {
+        id: true,
+      },
+    });
+
+    if (!type) {
+      return;
+    }
+
+    const existingContacts = await tx.contact.findMany({
+      where: {
+        person_id: personId,
+        contact_type: {
+          code: {
+            in: allowedCodes,
+          },
+        },
+      },
+      orderBy: [{ is_primary: 'desc' }, { id: 'asc' }],
+      select: {
+        id: true,
+        is_primary: true,
+      },
+    });
+
+    if (!normalizedValue) {
+      const contactToDelete = existingContacts[0];
+      if (contactToDelete) {
+        await tx.contact.delete({
+          where: {
+            id: contactToDelete.id,
+          },
+        });
+      }
+      return;
+    }
+
+    const primaryContact = existingContacts[0];
+    if (primaryContact) {
+      await tx.contact.update({
+        where: {
+          id: primaryContact.id,
+        },
+        data: {
+          value: normalizedValue,
+          is_primary: true,
+          contact_type_id: type.id,
+        },
+      });
+
+      const secondaryContacts = existingContacts
+        .slice(1)
+        .filter((contact) => contact.is_primary);
+      if (secondaryContacts.length > 0) {
+        await tx.contact.updateMany({
+          where: {
+            id: {
+              in: secondaryContacts.map((contact) => contact.id),
+            },
+          },
+          data: {
+            is_primary: false,
+          },
+        });
+      }
+      return;
+    }
+
+    await tx.contact.create({
+      data: {
+        person_id: personId,
+        contact_type_id: type.id,
+        value: normalizedValue,
+        is_primary: true,
+      },
+    });
+  }
+
   private async loadInteractionsFromTx(tx: any, personId: number) {
     const metadata = await tx.person_metadata.findFirst({
       where: {
@@ -2124,6 +3940,252 @@ export class PersonService {
     return filters;
   }
 
+  private buildAccountSqlFilters({
+    search,
+    status,
+    lifecycleStage,
+  }: {
+    search?: string | null;
+    status?: 'all' | string;
+    lifecycleStage?: 'all' | AccountLifecycleStage;
+  }) {
+    const filters: Prisma.Sql[] = [];
+
+    if (status && status !== 'all') {
+      filters.push(Prisma.sql`AND p.status = ${status}`);
+    }
+
+    if (lifecycleStage && lifecycleStage !== 'all') {
+      filters.push(
+        Prisma.sql`AND pc.account_lifecycle_stage = CAST(${lifecycleStage} AS person_company_account_lifecycle_stage_enum)`,
+      );
+    }
+
+    if (search) {
+      const searchLike = `%${search}%`;
+      const normalizedDigits = this.normalizeDigits(search);
+      const digitsLike = `%${normalizedDigits}%`;
+
+      filters.push(
+        Prisma.sql`
+          AND (
+            p.name ILIKE ${searchLike}
+            OR COALESCE(pc.trade_name, '') ILIKE ${searchLike}
+            OR COALESCE(pc.city, '') ILIKE ${searchLike}
+            OR COALESCE(pc.state, '') ILIKE ${searchLike}
+            OR EXISTS (
+              SELECT 1
+              FROM contact c
+              INNER JOIN contact_type ct ON ct.id = c.contact_type_id
+              WHERE c.person_id = p.id
+                AND UPPER(ct.code) = 'EMAIL'
+                AND c.value ILIKE ${searchLike}
+            )
+            ${
+              normalizedDigits.length > 0
+                ? Prisma.sql`
+                    OR EXISTS (
+                      SELECT 1
+                      FROM contact c
+                      INNER JOIN contact_type ct ON ct.id = c.contact_type_id
+                      WHERE c.person_id = p.id
+                        AND UPPER(ct.code) IN ('PHONE', 'MOBILE', 'WHATSAPP')
+                        AND regexp_replace(COALESCE(c.value, ''), '[^0-9]+', '', 'g') ILIKE ${digitsLike}
+                    )
+                  `
+                : Prisma.empty
+            }
+          )
+        `,
+      );
+    }
+
+    return filters.length > 0 ? Prisma.join(filters, '\n') : Prisma.empty;
+  }
+
+  private getAccountOrderBySql(
+    sortField?: 'name' | 'created_at',
+    sortOrder?: 'asc' | 'desc',
+  ) {
+    const normalizedSortField = sortField === 'created_at' ? 'created_at' : 'name';
+    const normalizedSortOrder = sortOrder === 'desc' ? 'DESC' : 'ASC';
+
+    if (normalizedSortField === 'created_at') {
+      return normalizedSortOrder === 'DESC'
+        ? Prisma.sql`p.created_at DESC`
+        : Prisma.sql`p.created_at ASC`;
+    }
+
+    return normalizedSortOrder === 'DESC'
+      ? Prisma.sql`LOWER(p.name) DESC`
+      : Prisma.sql`LOWER(p.name) ASC`;
+  }
+
+  private createEmptyAccountPagination(page: number, pageSize: number) {
+    return {
+      total: 0,
+      lastPage: 1,
+      page,
+      pageSize,
+      prev: page > 1 ? page - 1 : null,
+      next: null,
+      data: [] as AccountListItem[],
+    };
+  }
+
+  private buildCrmActivitySqlFilters({
+    allowCompanyRegistration,
+    search,
+    status,
+    type,
+    priority,
+  }: {
+    allowCompanyRegistration: boolean;
+    search?: string | null;
+    status?: 'all' | CrmActivityStatus;
+    type?: 'all' | CrmActivityType;
+    priority?: 'all' | CrmActivityPriority;
+  }) {
+    const filters: Prisma.Sql[] = [];
+
+    if (!allowCompanyRegistration) {
+      filters.push(Prisma.sql`AND p.type = 'individual'`);
+    }
+
+    if (status === 'pending') {
+      filters.push(
+        Prisma.sql`AND a.completed_at IS NULL AND a.due_at >= NOW()`,
+      );
+    } else if (status === 'overdue') {
+      filters.push(
+        Prisma.sql`AND a.completed_at IS NULL AND a.due_at < NOW()`,
+      );
+    } else if (status === 'completed') {
+      filters.push(Prisma.sql`AND a.completed_at IS NOT NULL`);
+    }
+
+    if (type && type !== 'all') {
+      filters.push(Prisma.sql`AND a.type = CAST(${type} AS crm_activity_type_enum)`);
+    }
+
+    if (priority && priority !== 'all') {
+      filters.push(
+        Prisma.sql`AND a.priority = CAST(${priority} AS crm_activity_priority_enum)`,
+      );
+    }
+
+    if (search) {
+      const searchLike = `%${search}%`;
+      filters.push(
+        Prisma.sql`
+          AND (
+            a.subject ILIKE ${searchLike}
+            OR COALESCE(a.notes, '') ILIKE ${searchLike}
+            OR p.name ILIKE ${searchLike}
+            OR COALESCE(owner_user.name, '') ILIKE ${searchLike}
+          )
+        `,
+      );
+    }
+
+    return filters.length > 0 ? Prisma.join(filters, '\n') : Prisma.empty;
+  }
+
+  private createEmptyCrmActivityPagination(page: number, pageSize: number) {
+    return {
+      total: 0,
+      lastPage: 1,
+      page,
+      pageSize,
+      prev: page > 1 ? page - 1 : null,
+      next: null,
+      data: [] as CrmActivityListItem[],
+    };
+  }
+
+  private mapCrmActivityListRow(row: Record<string, unknown>): CrmActivityListItem {
+    const completedAt = this.normalizeDateTimeOrNull(row.completed_at);
+    const dueAt = this.normalizeDateTimeOrNull(row.due_at) ?? new Date().toISOString();
+    const ownerUserId = this.coerceNumber(row.owner_user_id) || null;
+
+    return {
+      id: this.coerceNumber(row.id),
+      person_id: this.coerceNumber(row.person_id),
+      person: {
+        id: this.coerceNumber(row.person_id),
+        name: this.normalizeTextOrNull(row.person_name) || `#${row.person_id}`,
+        type:
+          this.normalizeTextOrNull(row.person_type) === 'company'
+            ? 'company'
+            : 'individual',
+        status:
+          this.normalizeTextOrNull(row.person_status) === 'inactive'
+            ? 'inactive'
+            : 'active',
+        trade_name: this.normalizeTextOrNull(row.person_trade_name),
+      },
+      owner_user_id: ownerUserId,
+      owner_user: ownerUserId
+        ? {
+            id: ownerUserId,
+            name:
+              this.normalizeTextOrNull(row.owner_user_name) || `#${ownerUserId}`,
+          }
+        : null,
+      type: (this.normalizeTextOrNull(row.type) || 'task') as CrmActivityType,
+      subject: this.normalizeTextOrNull(row.subject) || 'Activity',
+      notes: this.normalizeTextOrNull(row.notes),
+      due_at: dueAt,
+      completed_at: completedAt,
+      created_at:
+        this.normalizeDateTimeOrNull(row.created_at) ?? new Date().toISOString(),
+      priority:
+        (this.normalizeTextOrNull(row.priority) || 'medium') as CrmActivityPriority,
+      status: this.getCrmActivityStatus(dueAt, completedAt),
+    };
+  }
+
+  private mapCrmActivityDetailRow(row: Record<string, unknown>): CrmActivityDetail {
+    const base = this.mapCrmActivityListRow(row);
+    const createdByUserId = this.coerceNumber(row.created_by_user_id) || null;
+    const completedByUserId = this.coerceNumber(row.completed_by_user_id) || null;
+
+    return {
+      ...base,
+      source_kind:
+        (this.normalizeTextOrNull(row.source_kind) || 'manual') as CrmActivitySourceKind,
+      created_by_user_id: createdByUserId,
+      created_by_user: createdByUserId
+        ? {
+            id: createdByUserId,
+            name:
+              this.normalizeTextOrNull(row.created_by_user_name) ||
+              `#${createdByUserId}`,
+          }
+        : null,
+      completed_by_user_id: completedByUserId,
+      completed_by_user: completedByUserId
+        ? {
+            id: completedByUserId,
+            name:
+              this.normalizeTextOrNull(row.completed_by_user_name) ||
+              `#${completedByUserId}`,
+          }
+        : null,
+    };
+  }
+
+  private getCrmActivityStatus(
+    dueAt: string,
+    completedAt: string | null,
+  ): CrmActivityStatus {
+    if (completedAt) {
+      return 'completed';
+    }
+
+    return new Date(dueAt) < new Date() ? 'overdue' : 'pending';
+  }
+
   private normalizeDigits(value: string) {
     return value.replace(/\D/g, '');
   }