1. Núcleo del sistema (Core Platform)

Base técnica: RBAC, auditoría, workflows, colas y estándares API.

ClaveSeguridad + trazabilidad

EscalaMulti-tenant

ControlAprobaciones

Visión del módulo

Base técnica común: identidad, permisos, auditoría, colas y reglas. Este módulo define cómo se comporta toda la plataforma y cómo se garantizan trazabilidad y control.

Objetivos

Asegurar aislamiento multi-tenant (cliente/empresa/ejercicio).
Controlar permisos de forma granular (RBAC/ABAC).
Garantizar auditoría completa y evidencias de acciones críticas.
Estandarizar APIs, eventos y colas para el resto de módulos.
Facilitar integraciones robustas (idempotencia, reintentos, monitorización).

Alcance

Autenticación (SSO opcional) y gestión de sesiones.
RBAC por módulo/acción y permisos por cliente/empresa.
Auditoría (event-sourcing parcial o audit log inmutable).
Motor de workflows (estados, aprobaciones, transiciones).
Motor de notificaciones (email/app) + plantillas.
Colas de trabajo para tareas asíncronas (OCR, importaciones, presentaciones).

Personas y roles

Rol	Necesidad / uso principal
Administrador del despacho	Gestionar usuarios, permisos, integraciones, políticas y plantillas.
Gestor fiscal/contable/laboral	Operar expedientes con flujos y aprobaciones; acceder a evidencias.
Supervisor	Aprobar presentaciones y revisar riesgos/incidencias.
Cliente	Acceso limitado a su portal y documentos; trazabilidad de lo presentado.
Sistema/Integraciones	Acceso por API keys/OAuth con scopes e idempotencia.

Diseño funcional

Flujos principales

Gestión de usuarios y roles

Alta/edición de usuarios internos y perfiles por cliente/empresa.

Crear usuario interno (email, nombre, 2FA opcional).
Asignar rol base (fiscal/contable/laboral/supervisor/administrador).
Asignar alcance: clientes/empresas/ejercicios permitidos.
Definir permisos adicionales (acciones) y restricciones (IP, horario, etc.).
Registrar auditoría y notificar al usuario.

Salida: Usuario operativo con permisos trazables y revisables.

Workflow estándar con aprobación

Cualquier proceso crítico: presentar modelo, cerrar periodo, emitir asiento masivo.

Estado inicial: 'Borrador'.
Validaciones automáticas (datos mínimos, cuadres, checklist documental).
Transición a 'En revisión' con asignación de responsable.
Transición a 'Aprobado' solo por rol supervisor.
Ejecución (presentación / cierre) por cola asíncrona.
Estado final: 'Completado' + evidencias (CSV, justificante, logs).

Salida: Proceso trazable con evidencias y sin saltos de control.

Notificaciones

Vencimientos, incidencias, solicitudes de documentos, cambios de estado.

Regla detecta evento (ej.: modelo 303 vence en 7 días).
Genera tarea y notificación según preferencias del usuario/cliente.
Incluye enlaces a pantalla concreta y checklist asociado.
Registra entrega/lectura si aplica.

Salida: Cliente informado y gestoría con menos llamadas/emails.

Pantallas (UI)

Panel Admin: usuarios, roles, scopes, integraciones.
Monitor de colas: estado, reintentos, fallos y trazas.
Editor de workflows: estados, transiciones, validadores.
Centro de notificaciones y plantillas.

Diseño técnico

Entidades y modelo de datos (mínimo)

Entidad	Campos principales / notas
User	id, email, name, status, mfa_enabled, last_login_at
Role	id, name, description
Permission	module, action, resource_scope (client/company/year)
TenantScope	client_id, company_id, fiscal_year_id
AuditLog	id, actor_id, action, resource_type/id, before/after, ip, ua, created_at
Workflow	id, name, states[], transitions[], validators[]
Notification	id, to_user/to_client, channel, template_id, payload, status
JobQueue	id, type, payload, status, attempts, scheduled_at, result

Permisos y seguridad (RBAC)

RBAC mínimo: admin, supervisor, fiscal, contable, laboral, lectura.
Acciones críticas requieren doble control: approve + execute separados.
Scopes por cliente/empresa/ejercicio para evitar fugas multi-tenant.
Registro de accesos y cambios en AuditLog (obligatorio).
API Keys por integración con scopes y rotación; revocación inmediata.

Validaciones y reglas

No permitir transiciones si faltan validaciones definidas por workflow.
Idempotencia en endpoints críticos (header Idempotency-Key).
Bloqueo de periodos cerrados: solo admin/supervisor puede reabrir con motivo.
Control de concurrencia: versioning (ETag/row_version) en ediciones.
Retención de logs y documentos según política RGPD/contrato.

APIs sugeridas (API-first)

# Auth POST /api/v1/auth/login POST /api/v1/auth/logout POST /api/v1/auth/mfa/verify GET /api/v1/auth/me # Users/Roles/Permissions GET /api/v1/users POST /api/v1/users PATCH /api/v1/users/{id} GET /api/v1/roles POST /api/v1/roles GET /api/v1/permissions/catalog PUT /api/v1/users/{id}/scopes # Workflows GET /api/v1/workflows POST /api/v1/workflows POST /api/v1/workflows/{id}/transition # {state_from, state_to, resource_ref} # Audit / Jobs / Notifications GET /api/v1/audit?resource=...&from=...&to=... GET /api/v1/jobs?status=... POST /api/v1/jobs/retry/{id} GET /api/v1/notifications PATCH /api/v1/notifications/{id}/read

Eventos y auditoría

audit.logged (siempre)
workflow.transitioned
job.created / job.completed / job.failed
notification.sent / notification.read
security.suspicious_login

Impacto de negocio

Beneficio para la gestoría

Estandariza procesos: mismo resultado aunque cambie el gestor.
Menos errores por validaciones y doble control.
Escala a más clientes con el mismo equipo.
Auditoría útil ante incidencias y revisiones.

Beneficio para el cliente

Transparencia: estados, evidencias y justificantes.
Menos fricción: notificaciones y portal estructurado.
Mayor seguridad y confianza.

Riesgos / puntos críticos

Diseño insuficiente de permisos puede romper el aislamiento multi-tenant.
Sin colas e idempotencia, integraciones y OCR fallarán con volumen.
Auditoría incompleta = riesgo legal y operativo.
Workflows mal definidos generan bloqueos o saltos de control.

1. 系统核心 (Core Platform)

技术基础：RBAC、审计、工作流、队列和API标准。

关键安全性 + 可追溯性

规模多租户

控制审批

模块愿景

共同技术基础：身份、权限、审计、队列和规则。此模块定义整个平台的行为方式以及如何保证可追溯性和控制。

目标

确保多租户隔离（客户/公司/财年）。
细粒度控制权限（RBAC/ABAC）。
保证完整审计和关键操作证据。
为其余模块标准化API、事件和队列。
促进强大的集成（幂等性、重试、监控）。

范围

身份验证（可选SSO）和会话管理。
按模块/操作的RBAC和按客户/公司的权限。
审计（部分事件溯源或不可变审计日志）。
工作流引擎（状态、审批、转换）。
通知引擎（电子邮件/应用）+ 模板。
异步任务的工作队列（OCR、导入、提交）。

人员和角色

角色	需求 / 主要用途
办公室管理员	管理用户、权限、集成、策略和模板。
税务/会计/劳工经理	使用工作流和审批操作档案；访问证据。
主管	批准提交并审查风险/事件。
客户	对其门户和文档的有限访问；已提交内容的可追溯性。
系统/集成	通过API密钥/OAuth访问，具有范围和幂等性。

功能设计

主要流程

用户和角色管理

内部用户和按客户/公司的配置文件的高管/编辑。

创建内部用户（电子邮件、姓名、可选2FA）。
分配基础角色（税务/会计/劳工/主管/管理员）。
分配范围：允许的客户/公司/财年。
定义额外权限（操作）和限制（IP、时间等）。
记录审计并通知用户。

输出：具有可追溯和可审查权限的操作用户。

带审批的标准工作流

任何关键流程：提交模型、关闭期间、发出批量分录。

初始状态：'草稿'。
自动验证（最小数据、对账、文档清单）。
转换到'审查中'并分配负责人。
仅由主管角色转换到'已批准'。
通过异步队列执行（提交/关闭）。
最终状态：'已完成' + 证据（CSV、证明、日志）。

输出：具有证据且无控制跳跃的可追溯流程。

通知

到期、事件、文档请求、状态更改。

规则检测事件（例如：模型303在7天内到期）。
根据用户/客户偏好生成任务和通知。
包括到具体屏幕和相关清单的链接。
如果适用，记录交付/阅读。

输出：客户知情，管理办公室减少电话/电子邮件。

屏幕（UI）

管理面板：用户、角色、范围、集成。
队列监控：状态、重试、失败和跟踪。
工作流编辑器：状态、转换、验证器。
通知中心和模板。

技术设计

实体和数据模型（最小）

实体	主要字段 / 注释
User	id, email, name, status, mfa_enabled, last_login_at
Role	id, name, description
Permission	module, action, resource_scope (client/company/year)
TenantScope	client_id, company_id, fiscal_year_id
AuditLog	id, actor_id, action, resource_type/id, before/after, ip, ua, created_at
Workflow	id, name, states[], transitions[], validators[]
Notification	id, to_user/to_client, channel, template_id, payload, status
JobQueue	id, type, payload, status, attempts, scheduled_at, result

权限和安全性（RBAC）

最小RBAC：管理员、主管、税务、会计、劳工、阅读。
关键操作需要双重控制：批准 + 执行分开。
按客户/公司/财年的范围以避免多租户泄漏。
在AuditLog中记录访问和更改（强制）。
每个集成的API密钥，具有范围和轮换；立即撤销。

验证和规则

如果缺少工作流定义的验证，则不允许转换。
关键端点中的幂等性（标头Idempotency-Key）。
封闭期间的锁定：只有管理员/主管可以重新打开并说明原因。
并发控制：编辑中的版本控制（ETag/row_version）。
根据GDPR/合同策略保留日志和文档。

建议的API（API优先）

事件和审计

audit.logged（始终）
workflow.transitioned
job.created / job.completed / job.failed
notification.sent / notification.read
security.suspicious_login

业务影响

对管理办公室的好处

标准化流程：即使经理更换，结果也相同。
通过验证和双重控制减少错误。
用同一团队扩展到更多客户。
在事件和审查时有用的审计。

对客户的好处

透明度：状态、证据和证明。
减少摩擦：通知和结构化门户。
更高的安全性和信任。

风险 / 关键点

权限设计不足可能破坏多租户隔离。
没有队列和幂等性，集成和OCR在大量使用时将失败。
不完整的审计 = 法律和运营风险。
定义不当的工作流会产生阻塞或控制跳跃。

1. System Core (Core Platform)

Technical foundation: RBAC, auditing, workflows, queues and API standards.

KeySecurity + traceability

ScaleMulti-tenant

ControlApprovals

Module Vision

Common technical foundation: identity, permissions, auditing, queues and rules. This module defines how the entire platform behaves and how traceability and control are guaranteed.

Objectives

Ensure multi-tenant isolation (client/company/fiscal year).
Control permissions in a granular way (RBAC/ABAC).
Guarantee complete auditing and evidence of critical actions.
Standardize APIs, events and queues for the rest of the modules.
Facilitate robust integrations (idempotency, retries, monitoring).

Scope

Authentication (optional SSO) and session management.
RBAC by module/action and permissions by client/company.
Auditing (partial event-sourcing or immutable audit log).
Workflow engine (states, approvals, transitions).
Notification engine (email/app) + templates.
Work queues for asynchronous tasks (OCR, imports, submissions).

People and Roles

Role	Need / main use
Office Administrator	Manage users, permissions, integrations, policies and templates.
Tax/Accounting/Labor Manager	Operate files with workflows and approvals; access evidence.
Supervisor	Approve submissions and review risks/incidents.
Client	Limited access to their portal and documents; traceability of what was submitted.
System/Integrations	Access via API keys/OAuth with scopes and idempotency.

Functional Design

Main Flows

User and Role Management

Creation/editing of internal users and profiles by client/company.

Create internal user (email, name, optional 2FA).
Assign base role (tax/accounting/labor/supervisor/administrator).
Assign scope: allowed clients/companies/fiscal years.
Define additional permissions (actions) and restrictions (IP, schedule, etc.).
Record audit and notify user.

Output: Operational user with traceable and reviewable permissions.

Standard Workflow with Approval

Any critical process: submit model, close period, issue massive entry.

Initial state: 'Draft'.
Automatic validations (minimum data, reconciliations, document checklist).
Transition to 'Under Review' with assignment of responsible party.
Transition to 'Approved' only by supervisor role.
Execution (submission / closing) via asynchronous queue.
Final state: 'Completed' + evidence (CSV, proof, logs).

Output: Traceable process with evidence and without control jumps.

Notifications

Expirations, incidents, document requests, status changes.

Rule detects event (e.g.: model 303 expires in 7 days).
Generates task and notification according to user/client preferences.
Includes links to specific screen and associated checklist.
Records delivery/reading if applicable.

Output: Informed client and office management with fewer calls/emails.

Screens (UI)

Admin Panel: users, roles, scopes, integrations.
Queue Monitor: status, retries, failures and traces.
Workflow Editor: states, transitions, validators.
Notification Center and templates.

Technical Design

Entities and Data Model (minimum)

Entity	Main fields / notes
User	id, email, name, status, mfa_enabled, last_login_at
Role	id, name, description
Permission	module, action, resource_scope (client/company/year)
TenantScope	client_id, company_id, fiscal_year_id
AuditLog	id, actor_id, action, resource_type/id, before/after, ip, ua, created_at
Workflow	id, name, states[], transitions[], validators[]
Notification	id, to_user/to_client, channel, template_id, payload, status
JobQueue	id, type, payload, status, attempts, scheduled_at, result

Permissions and Security (RBAC)

Minimum RBAC: admin, supervisor, tax, accounting, labor, read.
Critical actions require double control: approve + execute separated.
Scopes by client/company/fiscal year to avoid multi-tenant leaks.
Record of accesses and changes in AuditLog (mandatory).
API Keys per integration with scopes and rotation; immediate revocation.

Validations and Rules

Do not allow transitions if validations defined by workflow are missing.
Idempotency in critical endpoints (header Idempotency-Key).
Locking of closed periods: only admin/supervisor can reopen with reason.
Concurrency control: versioning (ETag/row_version) in edits.
Retention of logs and documents according to GDPR/contract policy.

Suggested APIs (API-first)

Events and Auditing

audit.logged (always)
workflow.transitioned
job.created / job.completed / job.failed
notification.sent / notification.read
security.suspicious_login

Business Impact

Benefit for the Office

Standardizes processes: same result even if manager changes.
Fewer errors through validations and double control.
Scales to more clients with the same team.
Useful auditing in case of incidents and reviews.

Benefit for the Client

Transparency: statuses, evidence and proofs.
Less friction: notifications and structured portal.
Greater security and trust.

Risks / Critical Points

Insufficient permission design can break multi-tenant isolation.
Without queues and idempotency, integrations and OCR will fail with volume.
Incomplete auditing = legal and operational risk.
Poorly defined workflows generate blockages or control jumps.