De GED a SIGAD: decisões de arquitetura em Laravel, Vue e PostgreSQL

We began with a set of 23 archival classification and temporality requirements. The system was already an Electronic Document Management (EDM) system capable of receiving and viewing PDFs. The challenge was to add classification plans, temporality tables, and archival processes without losing existing functionality. Implementation required domain decisions before screen design. The main one was defining the process as a classified object. Its PDFs are digital components, organized into representations such as volumes, parts, or attachments.

我们从 23 项档案分类和保管期限要求开始。该系统当时已是一个能够接收和查看 PDF 的电子文档管理系统（GED）。挑战在于如何在不丢失现有功能的情况下，增加分类方案、保管期限表和档案流程。实施过程要求在设计界面前先做出领域决策。最核心的决策是将“流程”定义为分类对象。其 PDF 文件作为数字组件，被组织为卷、部分或附件等表现形式。

Processo arquivístico ├── Metadados, classe, tipologia, eventos e prazos ├── Representação: Volume 1 │ └── Componente: volume-1.pdf └── Representação: Volume 2 └── Componente: volume-2.pdf

档案流程 ├── 元数据、类目、类型学、事件和期限 ├── 表现形式：卷 1 │ └── 组件：volume-1.pdf └── 表现形式：卷 2 └── 组件：volume-2.pdf

This separation determines where each piece of information is recorded, how the viewer presents it, and what needs to be preserved when a rule changes. The technical structure uses PHP 7.4, Laravel 8, and PostgreSQL for the backend, while the interface uses Vue 3 and Inertia. We organized rules primarily into services, leaving controllers responsible for receiving, validating, and authorizing requests.

这种分离决定了每条信息的记录位置、查看器的呈现方式，以及规则变更时需要保留的内容。技术架构方面，后端使用 PHP 7.4、Laravel 8 和 PostgreSQL，界面使用 Vue 3 和 Inertia。我们将规则主要组织在服务层中，控制器仅负责接收、验证和授权请求。

There are two sets of services: Classification (registration of plans, classes, typologies, codes, institutional import, movements, and TTD versions) and SIGAD Processes (capture, digital representations, archival events, deadline projection, reconciliation of new rules, and destination). Migrations create the links between these objects. The application_id delimits the data for each application, while specific permissions control actions like creating, classifying, publishing, consulting, and downloading. A class has a stable internal identifier; its archival code and position in the hierarchy can change without losing historical links.

服务分为两组：分类（方案、类目、类型学、代码、机构导入、移交及保管期限表版本的注册）和 SIGAD 流程（捕获、数字表现形式、档案事件、期限预测、新规则核对及处置）。数据库迁移（Migrations）创建了这些对象之间的关联。application_id 划定了每个应用的数据范围，而特定权限则控制创建、分类、发布、查询和下载等操作。类目拥有稳定的内部标识符；其档案代码和层级位置可以变更，而不会丢失历史关联。

Importing a plan means interpreting a source. We tested the model with institutional plans of different structures. A source might use variable-width codes, reserve codes, or include definitions and observations alongside the class name. Fixing a single tree and a single numbering formula would not satisfy these cases. We created an XLSX template to import hierarchy, typologies, deadlines, initial events, destination, and observations. Processing preserves the reference to the original row. Ambiguous data generates review notes; the import enters a draft state before publication. This decision avoids a dangerous error: turning uncertain source text into an apparently definitive structured rule.

导入方案意味着解读源文件。我们使用不同结构的机构方案测试了该模型。源文件可能使用变长代码、预留代码，或在类目名称旁包含定义和备注。固定单一的树状结构和编号公式无法满足这些情况。我们创建了一个 XLSX 模板来导入层级、类型学、期限、初始事件、处置和备注。处理过程保留了对原始行的引用。模糊数据会生成核对提示；导入内容在发布前处于草稿状态。这一决策避免了一个危险的错误：将不确定的源文本转化为看似确定的结构化规则。

Structural changes have chain effects. Moving, dismembering, or merging classes can alter descendant codes and affect classified processes. Therefore, the operation begins with a preview of the effects and requires justification. The movement request is approved by another user. Changes record revision, author, timestamp, timezone, reason, and previous/subsequent values. We also use expected revision in updates: if someone else changed the plan while the screen was open, saving is refused to avoid overwriting a recent change. Inactivation and logical deletion follow their own rules. A class removed from use remains necessary to explain classifications made in the past.

结构性变更具有连锁反应。移动、拆分或合并类目可能会改变下级代码并影响已分类的流程。因此，操作开始前会预览影响并要求说明理由。移交请求需由另一用户审批。变更记录包含修订版本、作者、时间戳、时区、原因以及变更前后的值。我们在更新中还使用了“预期修订”机制：如果屏幕打开期间其他人修改了方案，系统将拒绝保存，以避免覆盖最近的更改。停用和逻辑删除遵循各自的规则。已停用的类目对于解释过去的分类记录仍然是必要的。

Temporality depends on events. The capture date in the system is not automatically the process opening date. A historical process can be captured today and have been opened years earlier. The published TTD indicates which event starts each deadline. The application records the event with an effective date and source, then calculates the projection of the current or intermediate age. Unarchiving and including confidential content only change a deadline when the rule expressly mentions them. When the classification or TTD changes, the service recalculates the applicable projections. If there is no unequivocal correspondence between the old and new rule, the process remains pending review. This is particularly relevant before a destination decision.

保管期限取决于事件。系统中的捕获日期并不自动等同于流程的开启日期。一个历史流程可能在今天被捕获，但实际上几年前就已经开启。已发布的保管期限表（TTD）指明了每个期限的起始事件。应用程序记录带有生效日期和来源的事件，然后计算当前或中间阶段的期限预测。解封和包含机密内容仅在规则明确提及的情况下才会改变期限。当分类或 TTD 变更时，服务会重新计算适用的预测。如果新旧规则之间没有明确的对应关系，流程将处于待核对状态。这在做出处置决定前尤为重要。

Coexistence with the existing EDM: The EDM had two upload APIs: a general one and one used by the file screen. For applications with SIGAD enabled, both pass through a backend check that blocks new standalone uploads. The interface also directs the user to open processes. The SIGAD flow uses another route: including a PDF as a representation of a process. In it, the physical file remains registered, but archival links and the SHA-256 hash of the component are also created. Recently, we added multiple selection during opening. The interface creates the process in draft and sends the PDFs in sequence via the existing representation route. If a file fails, the previous ones remain linked to the draft, and the screen keeps the pending ones for a retry. Classification and capture are subsequent steps.

与现有 GED 的共存：GED 原有两个上传 API：一个通用 API 和一个供文件界面使用的 API。对于启用了 SIGAD 的应用，两者都会经过后端检查，拦截新的独立上传。界面也会引导用户开启流程。SIGAD 流程使用另一条路径：将 PDF 作为流程的表现形式包含在内。在此过程中，物理文件保持注册状态，同时创建档案关联和组件的 SHA-256 哈希值。最近，我们增加了开启时的多选功能。界面创建草稿流程，并通过现有的表现形式路径依次发送 PDF。如果某个文件失败，之前的文件仍会关联到草稿，界面会保留待处理文件以供重试。分类和捕获是后续步骤。

How we verify the work: The implementation combines tests of services, APIs, and complete flows with PostgreSQL. Scenarios cover, among other points, permissions, versions, movements, import, events, deadlines, and processes with multiple volumes. Vue compilation verifies interface integration. There is still a step that automated tests cannot replace: validating the archival interpretation of real plans and tables. The test roadmap separates the implemented technical behavior from the acceptance of sources, access profiles, and institutional decisions. The main lesson from this worktree was that classification and temporality form a set of rules about objects that continue living after registration. Modeling identity, history, events, and the impact of changes from the beginning made these rules verifiable.

我们如何验证工作：实施过程结合了服务、API 和 PostgreSQL 完整流程的测试。场景涵盖了权限、版本、移交、导入、事件、期限以及多卷流程等要点。Vue 编译验证了界面集成。仍有一个步骤是自动化测试无法替代的：验证真实方案和表格的档案解读。测试路线图将已实现的各种技术行为与源文件、访问权限配置及机构决策的验收分离开来。从这项工作中得到的主要教训是：分类和保管期限构成了一套关于对象的规则，这些对象在注册后仍会持续存在。从一开始就对身份、历史、事件和变更影响进行建模，使得这些规则变得可验证。