@hed-hog/contact 0.0.333 → 0.0.347

package/hedhog/data/role.yaml

@@ -20,4 +20,12 @@
     pt: Aprovador de Propostas
   description:
     en: User authorized to approve proposals.
-    pt: Usuario autorizado a aprovar propostas.
+    pt: Usuario autorizado a aprovar propostas.
+
+- slug: person-user-linker
+  name:
+    en: Person User Linker
+    pt: Vinculador de Pessoa a Usuario
+  description:
+    en: User allowed to relate a person to a system user.
+    pt: Usuario permitido para relacionar uma pessoa com um usuario do sistema.

package/hedhog/endpoint/person.yaml

@@ -0,0 +1,263 @@
+resource: person
+base_url: /person
+roles: [admin, admin-contact]
+
+endpoints:
+  - method: GET
+    path: /
+    description: List persons with pagination and filters
+    pagination: true
+    response:
+      schema: person
+      paginated: true
+
+  - method: GET
+    path: /stats
+    description: Get aggregated person statistics
+
+  - method: GET
+    path: /dashboard
+    description: Get dashboard data (charts, KPIs)
+    locale: true
+    query:
+      period: string?
+
+  - method: GET
+    path: /reports
+    description: Get report data
+    locale: true
+    query:
+      from: date?
+      to: date?
+
+  - method: GET
+    path: /owner-options
+    description: List users available as owner options (search-able)
+    query:
+      search: string?
+
+  - method: GET
+    path: /linked-user-options
+    description: List users available to be linked to a person
+    query:
+      search: string?
+
+  - method: GET
+    path: /duplicates
+    description: Check for duplicate persons by name or document
+    query:
+      name: string?
+      document: string?
+
+  - method: GET
+    path: /accounts
+    description: List company/person accounts with pagination
+    pagination: true
+    query:
+      type: enum[company,individual]?
+
+  - method: GET
+    path: /accounts/stats
+    description: Get account statistics
+
+  - method: GET
+    path: /followups
+    description: List followups with pagination and filters
+    pagination: true
+    query:
+      status: string?
+      assigned_to: int?
+
+  - method: GET
+    path: /followups/stats
+    description: Get followup statistics
+    query:
+      period: string?
+
+  - method: GET
+    path: /activities
+    description: List activities with pagination and filters
+    pagination: true
+    query:
+      type: string?
+      person_id: int?
+
+  - method: GET
+    path: /activities/stats
+    description: Get activity statistics
+
+  - method: GET
+    path: /activities/:id
+    description: Get a single activity detail
+    locale: true
+    params:
+      id: int
+
+  - method: GET
+    path: /:id
+    description: Get a single person with full details
+    locale: true
+    params:
+      id: int
+
+  - method: GET
+    path: /avatar/:id
+    description: Stream person avatar image (public)
+    auth: public
+    params:
+      id: int
+    locale: true
+
+  - method: POST
+    path: /
+    description: Create a new person (individual or company)
+    locale: true
+    body:
+      name: string
+      type: enum[individual,company]
+      status: enum[active,inactive]
+      avatar_id: int?
+      birth_date: date?
+      gender: enum[male,female,other]?
+      job_title: string?
+      trade_name: string?
+      foundation_date: date?
+      legal_nature: string?
+      notes: string?
+      employer_company_id: int?
+      owner_user_id: int?
+      user_id: int?
+      source: enum[referral,website,social,inbound,outbound,other]?
+      lifecycle_stage: enum[new,contacted,qualified,proposal,negotiation,customer,lost]?
+      next_action_at: datetime?
+      score: number?
+      deal_value: number?
+      tags: array<string>?
+
+  - method: POST
+    path: /accounts
+    description: Create a new account (company linked to persons)
+    locale: true
+    body:
+      name: string
+      document: string?
+      email: string?
+      phone: string?
+
+  - method: POST
+    path: /merge
+    description: Merge two person records into one
+    locale: true
+    body:
+      source_id: int
+      target_id: int
+
+  - method: POST
+    path: /import/preview
+    description: Preview CSV import before applying
+    multipart: true
+
+  - method: POST
+    path: /import
+    description: Import persons from CSV file
+    locale: true
+    multipart: true
+
+  - method: POST
+    path: /:id/interaction
+    description: Add an interaction record to a person
+    locale: true
+    params:
+      id: int
+    body:
+      type: string
+      content: string
+      occurred_at: datetime?
+
+  - method: POST
+    path: /:id/followup
+    description: Schedule a followup for a person
+    locale: true
+    params:
+      id: int
+    body:
+      title: string
+      due_at: datetime
+      notes: string?
+      assigned_to_user_id: int?
+
+  - method: POST
+    path: /:id/lifecycle-stage
+    description: Update lifecycle stage of a person
+    locale: true
+    params:
+      id: int
+    body:
+      stage: enum[new,contacted,qualified,proposal,negotiation,customer,lost]
+
+  - method: POST
+    path: /activities/:id/complete
+    description: Mark an activity as completed
+    locale: true
+    params:
+      id: int
+
+  - method: PATCH
+    path: /:id
+    description: Update a person record
+    locale: true
+    params:
+      id: int
+    body:
+      name: string?
+      type: enum[individual,company]?
+      status: enum[active,inactive]?
+      avatar_id: int?
+      birth_date: date?
+      gender: enum[male,female,other]?
+      job_title: string?
+      trade_name: string?
+      foundation_date: date?
+      legal_nature: string?
+      notes: string?
+      employer_company_id: int?
+      owner_user_id: int?
+      user_id: int?
+      source: enum[referral,website,social,inbound,outbound,other]?
+      lifecycle_stage: enum[new,contacted,qualified,proposal,negotiation,customer,lost]?
+      next_action_at: datetime?
+      score: number?
+      deal_value: number?
+      tags: array<string>?
+
+  - method: PATCH
+    path: /accounts/:id
+    description: Update an account
+    locale: true
+    params:
+      id: int
+    body:
+      name: string?
+      document: string?
+      email: string?
+      phone: string?
+
+  - method: DELETE
+    path: /
+    description: Delete multiple persons (bulk)
+    body:
+      ids: array<int>
+
+  - method: DELETE
+    path: /accounts
+    description: Delete multiple accounts (bulk)
+    locale: true
+    body:
+      ids: array<int>
+
+  - method: GET
+    path: /:id/interaction
+    description: List interactions for a person
+    locale: true
+    params:
+      id: int

package/hedhog/frontend/app/_components/person-picker.tsx.ejs

@@ -574,6 +574,7 @@ export function PersonPicker({
   createType = 'individual',
   lockCreateType = false,
   initialSelectedLabel = '',
+  initialSelectedAvatarId,
   disabled = false,
   clearable = true,
   showEditButton = false,
@@ -590,6 +591,7 @@ export function PersonPicker({
   createType?: Exclude<PersonTypeFilter, 'all'>;
   lockCreateType?: boolean;
   initialSelectedLabel?: string;
+  initialSelectedAvatarId?: number | null;
   disabled?: boolean;
   clearable?: boolean;
   showEditButton?: boolean;
@@ -605,7 +607,7 @@ export function PersonPicker({
     useState(initialSelectedLabel);
   const [selectedPersonAvatarId, setSelectedPersonAvatarId] = useState<
     number | null
-  >(null);
+  >(initialSelectedAvatarId ?? null);
   const commandInputRef = useRef<HTMLInputElement | null>(null);
   const parentScrollContainerRef = useRef<HTMLElement | null>(null);
   const parentScrollTopRef = useRef(0);
@@ -921,7 +923,7 @@ export function PersonPicker({
             </PopoverContent>
           </Popover>
 
-          {hasSelection && clearable ? (
+          {canEditSelection && clearable ? (
             <Button
               type="button"
               variant="outline"
@@ -941,15 +943,15 @@ export function PersonPicker({
             </Button>
           ) : null}
 
-          {showEditButton ? (
+          {showEditButton && canEditSelection ? (
             <Button
               type="button"
               variant="outline"
               size="icon"
               className="shrink-0"
-              disabled={disabled || !canEditSelection}
+              disabled={disabled}
               onClick={() => {
-                if (!canEditSelection || !onEditSelection) {
+                if (!onEditSelection) {
                   return;
                 }
                 onEditSelection(selectedPersonId);

package/hedhog/frontend/app/accounts/page.tsx.ejs

@@ -40,6 +40,7 @@ import {
 } from '@/components/ui/table';
 import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
 import { getFormDraftOwnerKey } from '@/hooks/use-form-draft';
+import { usePersistedPageSize } from '@/hooks/use-persisted-page-size';
 import { formatDate } from '@/lib/format-date';
 import { cn } from '@/lib/utils';
 import { useApp, useQuery } from '@hed-hog/next-app-provider';
@@ -163,7 +164,11 @@ export default function AccountsPage() {
 
   const [sorting, setSorting] = useState<SortingState>([]);
   const [page, setPage] = useState(1);
-  const [pageSize, setPageSize] = useState(12);
+  const [pageSize, setPageSize] = usePersistedPageSize({
+    storageKey: 'pagination:global:pageSize',
+    defaultValue: 12,
+    allowedValues: [6, 12, 24, 48],
+  });
   const [searchInput, setSearchInput] = useState('');
   const [debouncedSearch, setDebouncedSearch] = useState('');
   const [statusFilter, setStatusFilter] = useState('all');

package/hedhog/frontend/app/activities/page.tsx.ejs

@@ -22,6 +22,7 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
+import { usePersistedPageSize } from '@/hooks/use-persisted-page-size';
 import { formatDateTime } from '@/lib/format-date';
 import { cn } from '@/lib/utils';
 import { useApp, useQuery } from '@hed-hog/next-app-provider';
@@ -95,7 +96,11 @@ export default function CrmActivitiesPage() {
   const [typeFilter, setTypeFilter] = useState('all');
   const [priorityFilter, setPriorityFilter] = useState('all');
   const [page, setPage] = useState(1);
-  const [pageSize, setPageSize] = useState(12);
+  const [pageSize, setPageSize] = usePersistedPageSize({
+    storageKey: 'pagination:global:pageSize',
+    defaultValue: 12,
+    allowedValues: [6, 12, 24, 48],
+  });
   const [viewMode, setViewMode] = useState<ActivityViewMode>('table');
   const [selectedActivityId, setSelectedActivityId] = useState<number | null>(
     null

package/hedhog/frontend/app/contact-type/page.tsx.ejs

@@ -52,6 +52,7 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { useFormDraft } from '@/hooks/use-form-draft';
+import { usePersistedPageSize } from '@/hooks/use-persisted-page-size';
 import { formatDate, formatDateTime } from '@/lib/format-date';
 import { useApp, useQuery } from '@hed-hog/next-app-provider';
 import { zodResolver } from '@hookform/resolvers/zod';
@@ -126,7 +127,11 @@ export default function ContactTypePage() {
     useState<ContactType | null>(null);
 
   const [page, setPage] = useState(1);
-  const [pageSize, setPageSize] = useState(12);
+  const [pageSize, setPageSize] = usePersistedPageSize({
+    storageKey: 'pagination:global:pageSize',
+    defaultValue: 10,
+    allowedValues: [10, 20, 30, 40, 50],
+  });
   const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
   const [deletingId, setDeletingId] = useState<number | null>(null);
 

package/hedhog/frontend/app/document-type/page.tsx.ejs

@@ -61,6 +61,7 @@ import {
 } from '@/components/ui/table';
 import { COUNTRIES } from '@/constants/countries';
 import { useFormDraft } from '@/hooks/use-form-draft';
+import { usePersistedPageSize } from '@/hooks/use-persisted-page-size';
 import { formatDate, formatDateTime } from '@/lib/format-date';
 import { useApp, useQuery } from '@hed-hog/next-app-provider';
 import { zodResolver } from '@hookform/resolvers/zod';
@@ -143,7 +144,11 @@ export default function DocumentTypePage() {
     useState<DocumentType | null>(null);
 
   const [page, setPage] = useState(1);
-  const [pageSize, setPageSize] = useState(12);
+  const [pageSize, setPageSize] = usePersistedPageSize({
+    storageKey: 'pagination:global:pageSize',
+    defaultValue: 10,
+    allowedValues: [10, 20, 30, 40, 50],
+  });
   const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
   const [deletingId, setDeletingId] = useState<number | null>(null);
 

package/hedhog/frontend/app/follow-ups/page.tsx.ejs

@@ -54,6 +54,7 @@ import {
 import { Textarea } from '@/components/ui/textarea';
 import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
 import { useFormDraft } from '@/hooks/use-form-draft';
+import { usePersistedPageSize } from '@/hooks/use-persisted-page-size';
 import { formatDateTime } from '@/lib/format-date';
 import { cn } from '@/lib/utils';
 import { useApp, useQuery } from '@hed-hog/next-app-provider';
@@ -206,7 +207,11 @@ export default function CrmFollowupsPage() {
   const [dateFrom, setDateFrom] = useState('');
   const [dateTo, setDateTo] = useState('');
   const [page, setPage] = useState(1);
-  const [pageSize, setPageSize] = useState(12);
+  const [pageSize, setPageSize] = usePersistedPageSize({
+    storageKey: 'pagination:global:pageSize',
+    defaultValue: 12,
+    allowedValues: [6, 12, 24, 48],
+  });
   const [viewMode, setViewMode] = useState<FollowupViewMode>('table');
   const [sheetOpen, setSheetOpen] = useState(false);
   const [personPickerOpen, setPersonPickerOpen] = useState(false);

package/hedhog/frontend/app/person/_components/person-form-sheet.tsx.ejs

@@ -710,6 +710,19 @@ export function PersonFormSheet({
   const t = useTranslations('contact.ContactPage');
   const { request, currentLocaleCode, getSettingValue, user } = useApp();
   const isEditing = Boolean(person);
+  const canEditLinkedUser = useMemo(
+    () =>
+      (user?.role_user ?? []).some((roleUser) => {
+        const roleSlug = roleUser.role?.slug;
+
+        return (
+          roleSlug === 'admin' ||
+          roleSlug === 'admin-contact' ||
+          roleSlug === 'person-user-linker'
+        );
+      }),
+    [user]
+  );
   const allowCompanyRegistration =
     getSettingValue('contact-allow-company-registration') !== false;
   const effectiveAllowedTypes = useMemo<Array<Person['type']>>(() => {
@@ -1146,11 +1159,6 @@ export function PersonFormSheet({
       ? `${process.env.NEXT_PUBLIC_API_BASE_URL}/person/avatar/${fileId}`
       : '/placeholder.png';
 
-  const getUserPhotoUrl = (photoId?: number | null) =>
-    typeof photoId === 'number' && photoId > 0
-      ? `${process.env.NEXT_PUBLIC_API_BASE_URL}/user/avatar/${photoId}`
-      : undefined;
-
   const resolveApiUrl = (url: string) =>
     /^https?:\/\//i.test(url)
       ? url
@@ -2500,10 +2508,17 @@ export function PersonFormSheet({
                   </div>
                 </CollapsibleTrigger>
 
-                <CollapsibleContent className="mt-2">
+                <CollapsibleContent
+                  className={cn(
+                    'mt-2',
+                    !canEditLinkedUser && 'opacity-60 pointer-events-none'
+                  )}
+                >
                   <EntityPicker
+                    disabled={!canEditLinkedUser}
                     value={linkedUserId}
                     onChange={(val, opt) => {
+                      if (!canEditLinkedUser) return;
                       setLinkedUserId(val as number | null);
                       setLinkedUserLabel(
                         opt
@@ -2513,31 +2528,17 @@ export function PersonFormSheet({
                               '')
                           : ''
                       );
-                      const userPhotoId = (
-                        opt as { photo_id?: number | null } | null
-                      )?.photo_id;
-                      if (val != null && userPhotoId && !avatarId) {
-                        setAvatarId(userPhotoId);
-                        setAvatarPreviewUrl(
-                          getUserPhotoUrl(userPhotoId) ?? '/placeholder.png'
-                        );
-                      }
                     }}
                     placeholder={t('selectLinkedUser')}
                     entityLabel={t('user')}
-                    clearable
+                    clearable={canEditLinkedUser}
                     valueType="number"
                     initialSelectedLabel={linkedUserLabel}
                     loadOptions={async ({ search }) => {
                       const params = new URLSearchParams();
                       if (search) params.set('search', search);
                       const response = await request<
-                        Array<{
-                          id: number;
-                          name: string;
-                          email?: string;
-                          photo_id?: number | null;
-                        }>
+                        Array<{ id: number; name: string; email?: string }>
                       >({
                         url: `/person/linked-user-options?${params.toString()}`,
                         method: 'GET',
@@ -2554,7 +2555,7 @@ export function PersonFormSheet({
                     getOptionDescription={(opt) =>
                       (opt as { email?: string }).email
                     }
-                    showCreateButton
+                    showCreateButton={canEditLinkedUser}
                     createTitle={t('createUserTitle')}
                     mapSearchToCreateValues={(search) => ({
                       name: search,