feat(12.2-02): add the fileupload field with deferred uploads committed on save

- type: fileupload compiles the D-08 keys and binds to the model's attach.Relation at boot
- X-Session-Key (cabana.SessionKeyHeader) carries the form session key; RecordInput.SessionKey
- GET and POST .../{id}/files/{field}: list with pending uploads, multipart upload into attach.Store
- the create and update save attaches the session's pending files in its transaction
- swagger2openapi folds formData parameters into a multipart requestBody
- admin OpenAPI, TS types, conformance cases, README and forms docs

modules/cabana/admin_openapi.go

@@ -359,6 +359,7 @@ func AdminList() {}
 // @Param plugin path string true "Plugin"
 // @Param controller path string true "Controller"
 // @Param body body AdminRecord true "Field values keyed by field name; relation fields carry ids"
+// @Param X-Session-Key header string false "Form session key: the save attaches the files uploaded under it"
 // @Success 201 {object} RecordEnvelope
 // @Failure 401 {object} ErrorEnvelope
 // @Failure 403 {object} ErrorEnvelope
@@ -494,6 +495,7 @@ func AdminShow() {}
 // @Param controller path string true "Controller"
 // @Param id path integer true "Record id"
 // @Param body body AdminRecord true "Field values keyed by field name; relation fields carry ids"
+// @Param X-Session-Key header string false "Form session key: the save applies the file uploads and removals held against it"
 // @Success 200 {object} RecordEnvelope
 // @Failure 401 {object} ErrorEnvelope
 // @Failure 403 {object} ErrorEnvelope
@@ -609,3 +611,54 @@ func AdminRelationLink() {}
 // @Failure 404 {object} ErrorEnvelope
 // @Router /{vendor}/{plugin}/{controller}/{id}/relations/{name}/unlink [post]
 func AdminRelationUnlink() {}
+
+// FileMutationResult is the payload of a file removal: the number of files
+// removed (always 1 on success).
+type FileMutationResult struct {
+	Removed int `json:"removed"`
+}
+
+// AdminFileList documents the file list of a fileupload field.
+//
+// @Summary List the files of a fileupload field
+// @Description The files attached to the record minus the session's pending removals, plus the session's pending uploads, in sort_order. id 0 is the record being created in the X-Session-Key session (the key is then required). url and thumb_url are set only for a public relation.
+// @Tags admin
+// @Produce json
+// @Security BackendBearer
+// @Param vendor path string true "Vendor"
+// @Param plugin path string true "Plugin"
+// @Param controller path string true "Controller"
+// @Param id path integer true "Owner id (0 for the record being created)"
+// @Param field path string true "fileupload field name"
+// @Param X-Session-Key header string false "Form session key (32-128 characters of A-Z a-z 0-9 _ -)"
+// @Success 200 {object} Envelope[[]FileItem]
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 422 {object} ErrorEnvelope
+// @Router /{vendor}/{plugin}/{controller}/{id}/files/{field} [get]
+func AdminFileList() {}
+
+// AdminFileUpload documents the upload of one file to a fileupload field.
+//
+// @Summary Upload a file to a fileupload field
+// @Description Stores one multipart file_data part and binds it to the X-Session-Key session; the record's next create or update save with the same key attaches it. id 0 is the record being created. A body over the upload cap answers 413 payload_too_large; a file over maxFilesize, of a type the field does not allow, or that fails the image check answers 422 on the field.
+// @Tags admin
+// @Accept multipart/form-data
+// @Produce json
+// @Security BackendBearer
+// @Param vendor path string true "Vendor"
+// @Param plugin path string true "Plugin"
+// @Param controller path string true "Controller"
+// @Param id path integer true "Owner id (0 for the record being created)"
+// @Param field path string true "fileupload field name"
+// @Param X-Session-Key header string true "Form session key (32-128 characters of A-Z a-z 0-9 _ -)"
+// @Param file_data formData file true "The file"
+// @Success 201 {object} Envelope[FileItem]
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 413 {object} ErrorEnvelope
+// @Failure 422 {object} ErrorEnvelope
+// @Router /{vendor}/{plugin}/{controller}/{id}/files/{field} [post]
+func AdminFileUpload() {}