Apéndices
Modelo de datos común, convenciones API, eventos y checklist de producción.
GuíaConvenciones
BaseModelo común
OpsProducción
Convenciones generales
Naming y recursos
- Todos los recursos deben incluir tenant_scope: client_id, company_id, fiscal_year_id.
- Endpoints con versionado:
/api/v1/...
- Operaciones críticas con header Idempotency-Key.
- Correlación por correlation_id en logs y jobs.
Modelo de datos común (mínimo)
| Entidad | Propósito |
|---|
| Client / Company / FiscalYear | Base multi-tenant y ejercicios. |
| User / Role / Permission / Scope | Seguridad y RBAC. |
| Document / DocumentLink | Documentación y evidencias vinculadas. |
| Workflow / Checklist / Task | Control operacional (estados y tareas). |
| AuditLog | Trazabilidad inmutable. |
| JobQueue / ConnectorLog | Procesos asíncronos e integraciones. |
Mapa de eventos
Eventos recomendados para arquitectura basada en colas y auditoría:
audit.logged
workflow.transitioned
document.uploaded
ocr.completed
accounting.entry.created
tax.model.calculated
tax.filing.completed
portal.document.uploaded
alert.created
integration.failed
security.event.raised
Checklist de "listo para producción"
- Separación multi-tenant validada con tests automáticos.
- Backups verificados y pruebas de restauración.
- Monitor de colas e integraciones con alertas.
- Auditoría completa en acciones críticas.
- Políticas RGPD (retención, exportación, supresión) implementadas.
通用约定
命名和资源
- 所有资源必须包含 tenant_scope：client_id、company_id、fiscal_year_id。
- 带版本控制的端点：
/api/v1/...
- 关键操作带 Idempotency-Key 标头。
- 在日志和作业中通过 correlation_id 进行关联。
通用数据模型（最小）
| 实体 | 目的 |
|---|
| Client / Company / FiscalYear | 多租户基础和财年。 |
| User / Role / Permission / Scope | 安全和RBAC。 |
| Document / DocumentLink | 文档和链接的证据。 |
| Workflow / Checklist / Task | 运营控制（状态和任务）。 |
| AuditLog | 不可变的可追溯性。 |
| JobQueue / ConnectorLog | 异步流程和集成。 |
事件映射
基于队列和审计架构的推荐事件：
audit.logged
workflow.transitioned
document.uploaded
ocr.completed
accounting.entry.created
tax.model.calculated
tax.filing.completed
portal.document.uploaded
alert.created
integration.failed
security.event.raised
"准备生产"清单
- 通过自动测试验证的多租户分离。
- 验证的备份和恢复测试。
- 带警报的队列和集成监控。
- 关键操作的完整审计。
- 已实施的GDPR策略（保留、导出、删除）。
Appendices
Common data model, API conventions, events and production checklist.
GuideConventions
BaseCommon Model
OpsProduction
General conventions
Naming and resources
- All resources must include tenant_scope: client_id, company_id, fiscal_year_id.
- Versioned endpoints:
/api/v1/...
- Critical operations with Idempotency-Key header.
- Correlation by correlation_id in logs and jobs.
Common data model (minimum)
| Entity | Purpose |
|---|
| Client / Company / FiscalYear | Multi-tenant base and fiscal years. |
| User / Role / Permission / Scope | Security and RBAC. |
| Document / DocumentLink | Documentation and linked evidence. |
| Workflow / Checklist / Task | Operational control (status and tasks). |
| AuditLog | Immutable traceability. |
| JobQueue / ConnectorLog | Asynchronous processes and integrations. |
Event map
Recommended events for queue-based and audit architecture:
audit.logged
workflow.transitioned
document.uploaded
ocr.completed
accounting.entry.created
tax.model.calculated
tax.filing.completed
portal.document.uploaded
alert.created
integration.failed
security.event.raised
"Ready for production" checklist
- Multi-tenant separation validated with automatic tests.
- Verified backups and restoration tests.
- Queue and integration monitor with alerts.
- Complete audit on critical actions.
- GDPR policies (retention, export, deletion) implemented.
Vista desarrollo - contenido pendiente...
Development view - content pending...