Merge pull request #6169 from LibreSign/feat/file-level-signature-flow

feat: file level signature flow

Author: vitormattos

lib/Controller/RequestSignatureController.php

@@ -56,6 +56,7 @@ public function __construct(
 	 * @param string $name The name of file to sign
 	 * @param string|null $callback URL that will receive a POST after the document is signed
 	 * @param integer|null $status Numeric code of status * 0 - no signers * 1 - signed * 2 - pending
+	 * @param string|null $signatureFlow Signature flow mode: 'parallel' or 'ordered_numeric'. If not provided, uses global configuration
 	 * @return DataResponse<Http::STATUS_OK, array{data: LibresignValidateFile, message: string}, array{}>|DataResponse<Http::STATUS_UNPROCESSABLE_ENTITY, array{message?: string, action?: integer, errors?: list<array{message: string, title?: string}>}, array{}>
 	 *
 	 * 200: OK
@@ -65,15 +66,23 @@ public function __construct(
 	#[NoCSRFRequired]
 	#[RequireManager]
 	#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/request-signature', requirements: ['apiVersion' => '(v1)'])]
-	public function request(array $file, array $users, string $name, ?string $callback = null, ?int $status = 1): DataResponse {
+	public function request(
+		array $file,
+		array $users,
+		string $name,
+		?string $callback = null,
+		?int $status = 1,
+		?string $signatureFlow = null,
+	): DataResponse {
 		$user = $this->userSession->getUser();
 		$data = [
 			'file' => $file,
 			'name' => $name,
 			'users' => $users,
 			'status' => $status,
 			'callback' => $callback,
-			'userManager' => $user
+			'userManager' => $user,
+			'signatureFlow' => $signatureFlow,
 		];
 		try {
 			$this->requestSignatureService->validateNewRequestToFile($data);

lib/Db/File.php

@@ -8,6 +8,7 @@
 
 namespace OCA\Libresign\Db;
 
+use OCA\Libresign\Enum\SignatureFlow;
 use OCP\AppFramework\Db\Entity;
 use OCP\DB\Types;
 
@@ -38,6 +39,8 @@
  * @method ?array getMetadata()
  * @method void setModificationStatus(int $modificationStatus)
  * @method int getModificationStatus()
+ * @method void setSignatureFlow(int $signatureFlow)
+ * @method int getSignatureFlow()
  */
 class File extends Entity {
 	protected int $nodeId = 0;
@@ -52,6 +55,7 @@ class File extends Entity {
 	protected ?string $callback = null;
 	protected ?array $metadata = null;
 	protected int $modificationStatus = 0;
+	protected int $signatureFlow = SignatureFlow::NUMERIC_PARALLEL;
 	public const STATUS_NOT_LIBRESIGN_FILE = -1;
 	public const STATUS_DRAFT = 0;
 	public const STATUS_ABLE_TO_SIGN = 1;
@@ -78,6 +82,7 @@ public function __construct() {
 		$this->addType('status', Types::INTEGER);
 		$this->addType('metadata', Types::JSON);
 		$this->addType('modificationStatus', Types::SMALLINT);
+		$this->addType('signatureFlow', Types::SMALLINT);
 	}
 
 	public function isDeletedAccount(): bool {
@@ -89,4 +94,12 @@ public function getUserId(): string {
 		$metadata = $this->getMetadata();
 		return $metadata['deleted_account']['account'] ?? $this->userId ?? '';
 	}
+
+	public function getSignatureFlowEnum(): \OCA\Libresign\Enum\SignatureFlow {
+		return \OCA\Libresign\Enum\SignatureFlow::fromNumeric($this->signatureFlow);
+	}
+
+	public function setSignatureFlowEnum(\OCA\Libresign\Enum\SignatureFlow $flow): void {
+		$this->setSignatureFlow($flow->toNumeric());
+	}
 }

lib/Db/SignRequestMapper.php

@@ -9,6 +9,7 @@
 namespace OCA\Libresign\Db;
 
 use DateTimeInterface;
+use OCA\Libresign\Enum\SignatureFlow;
 use OCA\Libresign\Enum\SignRequestStatus;
 use OCA\Libresign\Helper\Pagination;
 use OCA\Libresign\Service\IdentifyMethod\IIdentifyMethod;
@@ -500,6 +501,7 @@ private function getFilesAssociatedFilesWithMeQueryBuilder(string $userId, array
 				'f.status',
 				'f.metadata',
 				'f.created_at',
+				'f.signature_flow',
 			)
 				->groupBy(
 					'f.id',
@@ -510,6 +512,7 @@ private function getFilesAssociatedFilesWithMeQueryBuilder(string $userId, array
 					'f.name',
 					'f.status',
 					'f.created_at',
+					'f.signature_flow',
 				);
 			// metadata is a json column, the right way is to use f.metadata::text
 			// when the database is PostgreSQL. The problem is that the command
@@ -620,11 +623,13 @@ private function formatListRow(array $row): array {
 		$row['nodeId'] = (int)$row['node_id'];
 
 		$row['name'] = $this->removeExtensionFromName($row['name'], $row['metadata']);
+		$row['signatureFlow'] = SignatureFlow::fromNumeric((int)($row['signature_flow']))->value;
 
 		unset(
 			$row['user_id'],
 			$row['node_id'],
 			$row['signed_node_id'],
+			$row['signature_flow'],
 		);
 		return $row;
 	}

lib/Enum/SignatureFlow.php

@@ -15,4 +15,22 @@
 enum SignatureFlow: string {
 	case PARALLEL = 'parallel';
 	case ORDERED_NUMERIC = 'ordered_numeric';
+
+	public const NUMERIC_PARALLEL = 1;
+	public const NUMERIC_ORDERED_NUMERIC = 2;
+
+	public function toNumeric(): int {
+		return match($this) {
+			self::PARALLEL => self::NUMERIC_PARALLEL,
+			self::ORDERED_NUMERIC => self::NUMERIC_ORDERED_NUMERIC,
+		};
+	}
+
+	public static function fromNumeric(int $value): self {
+		return match($value) {
+			self::NUMERIC_PARALLEL => self::PARALLEL,
+			self::NUMERIC_ORDERED_NUMERIC => self::ORDERED_NUMERIC,
+			default => throw new \ValueError("Invalid numeric value for SignatureFlow: $value"),
+		};
+	}
 }

lib/Migration/Version15000Date20251209000000.php

@@ -9,6 +9,7 @@
 namespace OCA\Libresign\Migration;
 
 use Closure;
+use OCA\Libresign\Enum\SignatureFlow;
 use OCP\DB\ISchemaWrapper;
 use OCP\DB\QueryBuilder\IQueryBuilder;
 use OCP\DB\Types;
@@ -56,6 +57,17 @@ public function changeSchema(IOutput $output, Closure $schemaClosure, array $opt
 			}
 		}
 
+		if ($schema->hasTable('libresign_file')) {
+			$tableFile = $schema->getTable('libresign_file');
+			if (!$tableFile->hasColumn('signature_flow')) {
+				$tableFile->addColumn('signature_flow', Types::SMALLINT, [
+					'notnull' => true,
+					'default' => SignatureFlow::NUMERIC_PARALLEL,
+					'comment' => 'Signature flow mode: 1=parallel, 2=ordered_numeric',
+				]);
+			}
+		}
+
 		return $schema;
 	}
 

lib/ResponseDefinitions.php

@@ -186,6 +186,7 @@
  *     status: 0|1|2|3|4,
  *     statusText: string,
  *     nodeId: non-negative-int,
+ *     signatureFlow: int,
  *     totalPages: non-negative-int,
  *     size: non-negative-int,
  *     pdfVersion: string,

lib/Service/FileService.php

@@ -711,6 +711,7 @@ private function loadLibreSignData(): void {
 		$this->fileData->created_at = $this->file->getCreatedAt()->format(DateTimeInterface::ATOM);
 		$this->fileData->statusText = $this->fileMapper->getTextOfStatus($this->file->getStatus());
 		$this->fileData->nodeId = $this->file->getNodeId();
+		$this->fileData->signatureFlow = $this->file->getSignatureFlow();
 
 		$this->fileData->requested_by = [
 			'userId' => $this->file->getUserId(),

lib/Service/RequestSignatureService.php

@@ -8,19 +8,22 @@
 
 namespace OCA\Libresign\Service;
 
+use OCA\Libresign\AppInfo\Application;
 use OCA\Libresign\Db\File as FileEntity;
 use OCA\Libresign\Db\FileElementMapper;
 use OCA\Libresign\Db\FileMapper;
 use OCA\Libresign\Db\IdentifyMethodMapper;
 use OCA\Libresign\Db\SignRequest as SignRequestEntity;
 use OCA\Libresign\Db\SignRequestMapper;
+use OCA\Libresign\Enum\SignatureFlow;
 use OCA\Libresign\Handler\DocMdpHandler;
 use OCA\Libresign\Helper\ValidateHelper;
 use OCA\Libresign\Service\IdentifyMethod\IIdentifyMethod;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\Files\IMimeTypeDetector;
 use OCP\Files\Node;
 use OCP\Http\Client\IClientService;
+use OCP\IAppConfig;
 use OCP\IL10N;
 use OCP\IUser;
 use OCP\IUserManager;
@@ -47,6 +50,7 @@ public function __construct(
 		protected DocMdpHandler $docMdpHandler,
 		protected LoggerInterface $logger,
 		protected SequentialSigningService $sequentialSigningService,
+		protected IAppConfig $appConfig,
 	) {
 	}
 
@@ -56,6 +60,7 @@ public function save(array $data): FileEntity {
 		if (!isset($data['status'])) {
 			$data['status'] = $file->getStatus();
 		}
+		$this->sequentialSigningService->setFile($file);
 		$this->associateToSigners($data, $file->getId());
 		return $file;
 	}
@@ -106,10 +111,28 @@ public function saveFile(array $data): FileEntity {
 		} else {
 			$file->setStatus(FileEntity::STATUS_ABLE_TO_SIGN);
 		}
+
+		if (isset($data['signatureFlow']) && is_string($data['signatureFlow'])) {
+			try {
+				$signatureFlow = \OCA\Libresign\Enum\SignatureFlow::from($data['signatureFlow']);
+				$file->setSignatureFlowEnum($signatureFlow);
+			} catch (\ValueError) {
+				$this->setSignatureFlowFromGlobalConfig($file);
+			}
+		} else {
+			$this->setSignatureFlowFromGlobalConfig($file);
+		}
+
 		$this->fileMapper->insert($file);
 		return $file;
 	}
 
+	private function setSignatureFlowFromGlobalConfig(FileEntity $file): void {
+		$globalFlowValue = $this->appConfig->getValueString(Application::APP_ID, 'signature_flow', SignatureFlow::PARALLEL->value);
+		$globalFlow = SignatureFlow::from($globalFlowValue);
+		$file->setSignatureFlowEnum($globalFlow);
+	}
+
 	private function updateStatus(FileEntity $file, int $status): FileEntity {
 		if ($status > $file->getStatus()) {
 			$file->setStatus($status);

lib/Service/SequentialSigningService.php

@@ -8,14 +8,15 @@
 
 namespace OCA\Libresign\Service;
 
-use OCA\Libresign\AppInfo\Application;
+use OCA\Libresign\Db\File as FileEntity;
 use OCA\Libresign\Db\SignRequestMapper;
 use OCA\Libresign\Enum\SignatureFlow;
 use OCA\Libresign\Enum\SignRequestStatus;
 use OCP\IAppConfig;
 
 class SequentialSigningService {
 	private int $currentOrder = 1;
+	private ?FileEntity $file = null;
 
 	public function __construct(
 		private IAppConfig $appConfig,
@@ -24,9 +25,11 @@ public function __construct(
 	) {
 	}
 
-	/**
-	 * Check if ordered numeric flow is enabled
-	 */
+	public function setFile(FileEntity $file): self {
+		$this->file = $file;
+		return $this;
+	}
+
 	public function isOrderedNumericFlow(): bool {
 		return $this->getSignatureFlow() === SignatureFlow::ORDERED_NUMERIC;
 	}
@@ -51,8 +54,8 @@ public function determineSigningOrder(?int $userProvidedOrder): int {
 		}
 
 		if ($userProvidedOrder !== null) {
-			if ($userProvidedOrder > $this->currentOrder) {
-				$this->currentOrder = $userProvidedOrder;
+			if ($userProvidedOrder >= $this->currentOrder) {
+				$this->currentOrder = $userProvidedOrder + 1;
 			}
 			return $userProvidedOrder;
 		}
@@ -162,13 +165,10 @@ private function activateSignersForOrder(array $signRequests, int $order): void
 	}
 
 	private function getSignatureFlow(): SignatureFlow {
-		$value = $this->appConfig->getValueString(
-			Application::APP_ID,
-			'signature_flow',
-			SignatureFlow::PARALLEL->value
-		);
-
-		return SignatureFlow::from($value);
+		if ($this->file === null) {
+			throw new \LogicException('File must be set before calling getSignatureFlow(). Call setFile() first.');
+		}
+		return $this->file->getSignatureFlowEnum();
 	}
 
 	/**

lib/Service/SignFileService.php

@@ -380,10 +380,12 @@ protected function updateSignRequest(string $hash): void {
 
 		$this->signRequestMapper->update($this->signRequest);
 
-		$this->sequentialSigningService->releaseNextOrder(
-			$this->signRequest->getFileId(),
-			$this->signRequest->getSigningOrder()
-		);
+		$this->sequentialSigningService
+			->setFile($this->libreSignFile)
+			->releaseNextOrder(
+				$this->signRequest->getFileId(),
+				$this->signRequest->getSigningOrder()
+			);
 	}
 
 	protected function updateLibreSignFile(string $hash): void {