premanandc/functional requirements

## functional requirements
Me: Okay. Let's move on to create the notion of a Plan. This is the idea of wanting to apply an update over the population of devices. First, we need to know which devices are affected for a given update. A device is affected if:
1. A software package needs to be installed on it if it wasn't previously or a package is marked as forced.
2. A software package needs to be upgraded (it has a lower version of the software than the one specified in the update)
3. A software package needs to be uninstalled (if it is installed on the device)

Once the candidate list of devices is identified, the devices need to be split into smaller batches. Batches are of two types: test and mass. A test batch usually contains a smaller number of devices than mass batches. The purpose of a test batch is to assess how an update would perform, before it is applied on a larger number of devices. In that sense, each batch is a step in a plan. For each batch, the admin user will eventually specify a set of success criteria that needs to be attained by a specific amount of time. For now, we can simply specify an amount of time (in hours or days) for which the batch will be monitored. The admin user will look at the batch at the end of the monitoring time and decide whether to proceed ahead with the next batch in the plan (until the last batch).

So a plan will comprise of an ordered set of test and mass batches. Mass batches will typically come at the end. A plan needs to be shared with the user in its entirety. For now, here are some rules on how to create batches:
1. Every batch should contain at least one device
2. If there is only one affected device, then just make it part of a mass batch
3. If there are less than 5 affected devices, create one test batch with a single device and the rest as mass batches
4. For bigger batches, create two test batches, with 10% of the devices in each batch (or 1 device, whichever is larger). After the two batches are created, put the remainder into a single mass batch.

This strategy needs to be maintained separately. Later, we will need to need to change the strategy and we want to the ability to do this flexibly, without requiring to change code. But for now, it's okay to keep this logic in code.

Once a plan is presented to the user, the user can suggest edits. They can:
1. Change the number of affected devices in the plan (they can reduce it to only include a subset)
2. Change the number and type of batches
3. Remove or add devices to a batch. Move a device from one batch to another. When adding devices, we should make sure that they are affected by the update and that they aren't already part of the plan.

After a set of optional edits to the originally presented plan, the user can either approve or reject a plan. So a plan will start in draft state if it was created by the system and then move to approved or rejected.

For approved plans, we will transition to Executions. But we will cover that later. Reiterate your understanding back to me before making any changes.

-------

AI: I understand you're looking to implement a Plan concept for managing how updates are deployed to devices. Here's my understanding of the requirements:
Plan Concept
A Plan represents the strategy for applying an update across multiple devices, organized in batches with a specific execution order.
Device Selection Logic
Devices are considered "affected" by an update if:
A package needs installation (not present or forced installation)
A package needs upgrading (device has lower version)
A package needs uninstalling (if currently installed)
Batch Structure
Types: Test batches (smaller, for validation) and Mass batches (larger, for widespread deployment)
Purpose: Test batches allow assessing update performance before wider rollout
Monitoring: Each batch has a monitoring period (hours/days)
Sequence: Admin evaluates each batch's success before proceeding to the next
Batch Creation Rules
Every batch must contain at least one device
Single affected device → one mass batch
<5 affected devices → one test batch (1 device) + rest in mass batches
Larger sets → two test batches (10% each, min 1 device) + remainder in single mass batch
Plan Lifecycle
Initially created in DRAFT state with system-generated batches
Admin can edit:
Number of affected devices
Batch configuration (count, type)
Device assignments between batches
Admin approves or rejects plan
Approved plans proceed to execution phase (to be implemented later)
Implementation Approach
The batch creation strategy should be designed for future flexibility, allowing different strategies without code changes (though initial implementation can be in code).
Is this understanding accurate before I proceed with implementation?

-------

Me: Now let's introduce the concept of an Execution. Once a plan is approved, it transitions to become an execution. Per the plan, we will start by issuing update instructions to the devices in the batch. Update instructions are largely fire and forget. We should record that we have issued the update instruction to the device in that batch in that execution. Devices will eventually report how the update fared (whether it succeeded or failed). Some devices may not report anything during the monitoring period. If all devices in a batch report success or failure, that batch is complete. Finally, we will come to the end of the monitoring period. At that time, we will have to make a decision on whether to proceed with the next batch in the execution, abandon the execution, or create a new plan. There are two things here. The batch execution status (pending, executing, completed) and the batch result (incomplete, successful or failed). If the monitoring period ends and if all the devices in the batch haven't reported either success or failure, the batch remains incomplete. We may need to enhance our domain model to accommodate for this.

Reiterate this understanding back to me before we proceed to making changes.

We may be able to make a decision earlier if all the devices in the batch report back in advance of the monitoring period ending. But we have to give them at least until the end of the monitoring period. In some cases, the user may decide to abort an ongoing execution. In that case, the execution should be marked as abandoned.
	Me: Okay. Let's move on to create the notion of a Plan. This is the idea of wanting to apply an update over the population of devices. First, we need to know which devices are affected for a given update. A device is affected if:
	1. A software package needs to be installed on it if it wasn't previously or a package is marked as forced.
	2. A software package needs to be upgraded (it has a lower version of the software than the one specified in the update)
	3. A software package needs to be uninstalled (if it is installed on the device)

	Once the candidate list of devices is identified, the devices need to be split into smaller batches. Batches are of two types: test and mass. A test batch usually contains a smaller number of devices than mass batches. The purpose of a test batch is to assess how an update would perform, before it is applied on a larger number of devices. In that sense, each batch is a step in a plan. For each batch, the admin user will eventually specify a set of success criteria that needs to be attained by a specific amount of time. For now, we can simply specify an amount of time (in hours or days) for which the batch will be monitored. The admin user will look at the batch at the end of the monitoring time and decide whether to proceed ahead with the next batch in the plan (until the last batch).

	So a plan will comprise of an ordered set of test and mass batches. Mass batches will typically come at the end. A plan needs to be shared with the user in its entirety. For now, here are some rules on how to create batches:
	1. Every batch should contain at least one device
	2. If there is only one affected device, then just make it part of a mass batch
	3. If there are less than 5 affected devices, create one test batch with a single device and the rest as mass batches
	4. For bigger batches, create two test batches, with 10% of the devices in each batch (or 1 device, whichever is larger). After the two batches are created, put the remainder into a single mass batch.

	This strategy needs to be maintained separately. Later, we will need to need to change the strategy and we want to the ability to do this flexibly, without requiring to change code. But for now, it's okay to keep this logic in code.

	Once a plan is presented to the user, the user can suggest edits. They can:
	1. Change the number of affected devices in the plan (they can reduce it to only include a subset)
	2. Change the number and type of batches
	3. Remove or add devices to a batch. Move a device from one batch to another. When adding devices, we should make sure that they are affected by the update and that they aren't already part of the plan.

	After a set of optional edits to the originally presented plan, the user can either approve or reject a plan. So a plan will start in draft state if it was created by the system and then move to approved or rejected.

	For approved plans, we will transition to Executions. But we will cover that later. Reiterate your understanding back to me before making any changes.

	-------

	AI: I understand you're looking to implement a Plan concept for managing how updates are deployed to devices. Here's my understanding of the requirements:
	Plan Concept
	A Plan represents the strategy for applying an update across multiple devices, organized in batches with a specific execution order.
	Device Selection Logic
	Devices are considered "affected" by an update if:
	A package needs installation (not present or forced installation)
	A package needs upgrading (device has lower version)
	A package needs uninstalling (if currently installed)
	Batch Structure
	Types: Test batches (smaller, for validation) and Mass batches (larger, for widespread deployment)
	Purpose: Test batches allow assessing update performance before wider rollout
	Monitoring: Each batch has a monitoring period (hours/days)
	Sequence: Admin evaluates each batch's success before proceeding to the next
	Batch Creation Rules
	Every batch must contain at least one device
	Single affected device → one mass batch
	<5 affected devices → one test batch (1 device) + rest in mass batches
	Larger sets → two test batches (10% each, min 1 device) + remainder in single mass batch
	Plan Lifecycle
	Initially created in DRAFT state with system-generated batches
	Admin can edit:
	Number of affected devices
	Batch configuration (count, type)
	Device assignments between batches
	Admin approves or rejects plan
	Approved plans proceed to execution phase (to be implemented later)
	Implementation Approach
	The batch creation strategy should be designed for future flexibility, allowing different strategies without code changes (though initial implementation can be in code).
	Is this understanding accurate before I proceed with implementation?

	-------

	Me: Now let's introduce the concept of an Execution. Once a plan is approved, it transitions to become an execution. Per the plan, we will start by issuing update instructions to the devices in the batch. Update instructions are largely fire and forget. We should record that we have issued the update instruction to the device in that batch in that execution. Devices will eventually report how the update fared (whether it succeeded or failed). Some devices may not report anything during the monitoring period. If all devices in a batch report success or failure, that batch is complete. Finally, we will come to the end of the monitoring period. At that time, we will have to make a decision on whether to proceed with the next batch in the execution, abandon the execution, or create a new plan. There are two things here. The batch execution status (pending, executing, completed) and the batch result (incomplete, successful or failed). If the monitoring period ends and if all the devices in the batch haven't reported either success or failure, the batch remains incomplete. We may need to enhance our domain model to accommodate for this.

	Reiterate this understanding back to me before we proceed to making changes.

	We may be able to make a decision earlier if all the devices in the batch report back in advance of the monitoring period ending. But we have to give them at least until the end of the monitoring period. In some cases, the user may decide to abort an ongoing execution. In that case, the execution should be marked as abandoned.