🛠️ [TASK] : Implement CRUD Functionality for Proposals

[minikin]

Description

Subtasks:

• 🛠️ [TASK] : Add Basic Database Queries to support the signed_docs table. #1324
• 🛠️ [TASK] : Make Signed documents library have a basic deserializer #1364

Goal:

API to Create/Read/Update and Delete Proposals.

We will maintain proposals historically, so each update will be a unique Proposal ID in a set of Proposals.
This will mean a Proposal will need two IDs <ProposalID>,<ProposalVersionID>.
The ID's are ULID and are therefore unambiguous. A Proposal can be found solely by its <ProposalVersionID> or all versions of a proposal can be found with the <ProposalID>. Ulids also enforce the time order of versions.

Draft Rough API:

PUT /api/draft/proposal

This posts a new proposal, or an update to a proposal.
The :proposalid path parameter is required.

• If this is a new proposal, the front end creates a well formed ULID for it. The backend will reject it if the ULID is too old, or too far into the future.
• If the proposalID exists, the new version of the document will fail to be added IF its not signed by the same set of proposers who posted the first proposal. (Currently limited to a single proposer, but in future will be extended to include multiple proposers.)

The backend will create a proposalVersionID automatically for each update. However, if the document already exists, it will not create a new version, because it already exists.

The backend will return the documents proposalVersionId in its response. It should also respond if the document is a new version, or already existed *and so nothing changed).

This must be a signed document.

GET /api/draft/proposal/:id?ver=version

Returns the actual proposal identified by the version ID.
This returns the signed document submitted back.

POST /api/draft/proposal/list?<paging parameters>

Gets a list of proposals.

• id: optionally restricted to a particular campaign within a brand, or category_id or a specific proposal_id.
• proposer: optionally restrict to a particular proposer. If not set, will automatically restrict to the proposer identified by the Auth Token. Can also be set to "all" to get all proposers.
• state: optionally restrict to proposals in this set of states. [eg, PRIVATE, DRAFT, SUBMITTED, FINALIZED, WITHDRAWN]. Should be able to select multiple states. If not set, all states are reported.
• List could be long, so results need to be paged.

The list should return the list of each proposal_id and the proposal_versions which match the states requested.
Because proposals could be in multiple states, across multiple brands/campaigns. These should be unambiguously listed.

This is NOT a signed response, as its distilled from signed data.

PUT /api/draft/proposal/state

This submits a state change document. This is a signed document which changes the state of a proposal.
The state of a proposal can only be changed by an authorized entity, currently that means the proposer themselves.
However, it could be others when we introduce moderation. Some states would only be settable by different actors.

The document includes the proposal version whose state is changed.
The category the state change applies to.
Some state changes are not applicable, for example a PRIVATE state document is a draft that is encrypted, and can only be read by someone holding a key. DRAFT is any proposal that is not submitted to a category.
The author of the proposal can set "SUBMITTED" and "FINALIZED" and "WITHDRAWN" states for a proposal to a category.
Other states may be set by other acors in a future state.

The update is idempotent, in that multiple "SUBMITTED" for the same proposal version to the same category id will not result in a new submission.

The API will reject any update which is invalid (State change outside time boundaries, or invalid proposal version/category id, etc.) However, in a decentralized system success in publishing a state change does not mean the state is changed, the state change needs to always be valid with respect to the rules of the campaign.

Acceptance Criteria

• List clear, specific, and measurable criteria for when the task is considered complete.

Resources

• Add relevant links, documentation, or references.