Merge pull request #2915 from carpentries/feature/2576-update-member-code-docs

 [Docs] Update member code docs, add some docs for the Offering project

Author: pbanaszkiewicz

docs/design/database_models.md

@@ -151,6 +151,10 @@ organisations) in The Carpentries project. Memberships can be paid. With
 each membership comes a number of fields defining perks like allowable
 number of centrally-organised workshops that don't need to pay fee.
 
+Includes a `registration_code` field — a unique code shared with member organisations
+and used by trainees and workshop requesters to identify their membership when submitting
+forms (see [Member Code Enforcement](./projects/2023_member_code_enforcement.md)).
+
 ### `Airport`
 Represents an airport (used for example to locate instructors).
 
@@ -198,6 +202,10 @@ Represents a knowledge domain (like High Performance Computing) a person is enga
 Represents a request for instructor training. Usually these requests come from people
 who are not AMY users.
 
+Includes a `member_code` field (the registration code entered by the applicant), which is validated against active memberships, partnerships or account benefits, and a
+`member_code_override` boolean field, which records whether the applicant chose to
+submit despite an invalid member code (see [Member Code Enforcement](./projects/2023_member_code_enforcement.md)).
+
 This model falls into `external requests` domain, which also includes `WorkshopRequest`,
 `WorkshopInquiryRequest`, and `SelfOrganisedSubmission`.
 
@@ -242,6 +250,10 @@ some common parts were extracted into `CommonRequest` abstract model (mixin).
 ### `WorkshopRequest`
 Represents a request for teaching a Carpentries workshop.
 
+Includes a `member_code` field for the registration code entered by the requester, which
+is validated against active memberships, partnerships or account benefits when member code enforcement is
+enabled (see [Member Code Enforcement](./projects/2023_member_code_enforcement.md)).
+
 This model falls into `external requests` domain.
 
 ----------------------------------------------------------------------------------------
@@ -256,6 +268,21 @@ Simple model, represents person role within a membership (see
 Similar to [`Task`](#task) model, but it's for a person task within a membership. Links
 to `MembershipPersonRole`.
 
+### `Consortium`
+Represents a consortium of multiple organisations. A consortium can be the partner in a
+[`Partnership`](#partnership).
+
+### `PartnershipTier`
+Represents a tier level for a partnership (e.g. "Bronze", "Silver", "Gold"), with an
+associated credit count.
+
+### `Partnership`
+Represents a service partnership between The Carpentries and an organisation or
+consortium. A follow-up to the [`Membership`](#membership) model, introduced as part of
+the [Service Offering 2025 project](./projects/2025_service_offering.md).
+
+Includes a `registration_code` field — a unique code used to identify the partnership in trainee applications or workshop requests (see also [Member Code Enforcement](./projects/2023_member_code_enforcement.md)).
+
 ----------------------------------------------------------------------------------------
 
 ## External requests application - `extrequests/models.py`
@@ -375,3 +402,31 @@ be sent by the email worker.
 ### `ScheduledEmailLog`
 Represents a log entry for a scheduled email. This is used to track the status changes
 of an email.
+
+----------------------------------------------------------------------------------------
+
+## Offering application - `offering/models.py`
+
+The offering application models support the [Service Offering 2025](./projects/2025_service_offering.md) project. They represent
+the purchasing and allocation of benefits to partner organisations and individuals.
+
+### `Account`
+Represents the individual or organisation that purchases benefits. An `Account` is linked
+to a `Person`, `Organization`, or `Consortium` via a generic foreign key.
+
+### `AccountOwner`
+Represents a person appointed as the owner of an account. Stores the permission type
+(owner, programmatic contact, or billing contact).
+
+### `Benefit`
+Represents a single good available to be purchased for an account (e.g. training seats
+or workshop events). Stores a unit type and credit count.
+
+### `AccountBenefitDiscount`
+Simple model representing a discount that can be applied to an account benefit purchase. The discount is just a text, no logic is applied to it in AMY, but it can be used for reporting and tracking purposes.
+
+### `AccountBenefit`
+Represents a single benefit purchased for an account. Links an [`Account`](#account) to
+a [`Benefit`](#benefit), optionally via a [`Partnership`](#partnership). Stores
+allocation, date range, and a unique `registration_code` used to identify the benefit in
+training requests and workshop requests (see [Member Code Enforcement](./projects/2023_member_code_enforcement.md)).

docs/design/projects/2025_service_offering.md

@@ -0,0 +1,7 @@
+# Service Offering Model (2025)
+
+[GitHub project](https://github.com/orgs/carpentries/projects/20).
+
+"Offering" or "Partnership Model" for short.
+
+TBC.

docs/design/projects/README.md

@@ -13,3 +13,6 @@ Documentation provided for each of the functional projects.
 * [Instructor Selection](./2021_instructor_selection.md)
 * [Single Instructor Badge](./2021_single_instructor_badge.md)
 * [Automated emails v2 (2023)](./2023_automated_emails/index.md)
+* [Instructor Checkout Changes (2023)](./2023_instructor_checkout_changes.md)
+* [Member Code Enforcement (2023)](./2023_member_code_enforcement.md)
+* [Service Offering (2025)](./2025_service_offering.md)

docs/users_guide/admin_index.md

@@ -199,8 +199,16 @@ A workshop can be requested from a host site, and this information can be used t
 
 This will take you to a summary view of the workshop requests, workshop inquiries, or self-organised submissions.  Click on the "information" icon at the right of each row to see more details.
 
+The workshop requests list includes a filter to find requests submitted by a member organisation that did not include a member code.
+
 ![AMY workshop request list](images/workshop_requests.png)
 
+!!! note "Member code validation on workshop requests"
+
+    Workshop requests include a field for a registration (member) code. The code is validated against active memberships, partnerships and account benefits. If the code is invalid or inactive, the form displays an error — unlike training requests, there is no option for the submitter to override an invalid code.
+
+    When viewing a workshop request detail page, an info box shows the membership associated with the submitted member code (if applicable) and the number of workshops remaining for that membership. If the request is submitted with a member code from a partnership or account benefit, then a link to that model is shown.
+
 At the bottom of the request information page, the user has the option to accept or discard the request. All requests should be accepted (unless spam or otherwise inappropriate) so The Carpentries can maintain a history of workshop requests. Events can later be tagged as stalled or cancelled. Choosing "Change state to Accepted" will mark it as accepted in the workshop request list but will not create a new event. Select "Accept and create a new event" to create a new event from this request.
 
 This will open a page with a side by side view of the request details and view to create a new event, similar to the general new event page. The new event can be created [manually](#creating-a-new-event-manually) or if available, [from the URL](#creating-a-new-event-from-url), as described above.
@@ -350,16 +358,22 @@ See [section above](#adding-bulk-person-records).
 
 #### Accepting Trainee Applications
 
-In addition to tracking workshops, AMY also allows us to track applications to instructor training events. [The public facing application is here](https://amy.carpentries.org/forms/request_training/). Applicants are given a registration code if participating in a member training event and should select "Profile Creation for Pre-approved Trainees" using this code. Open applicants will not have a registration code.
+In addition to tracking workshops, AMY also allows us to track applications to instructor training events. [The public facing application is here](https://amy.carpentries.org/forms/request_training/). Applicants are given a registration code if participating in a member training event. Open applicants will not have a registration code.
 
 Once an individual submits the form, they receive an email that confirms their application has been received and includes a copy of the individual's responses. An admin user can then view the record by going to Requests --> [Training Requests](https://amy.carpentries.org/requests/training_requests/).
 
 ![Training request menu](images/training_request_menu.png)
 
 This will display a list of all applications that are *Pending or Accepted* and *Unmatched* to an existing person. Applications can then be searched by individual name, email address, group (registration code), status (pending, accepted, discarded, or withdrawn), affiliation, or location.  Affiliation and location searches rely on text strings, so *UCLA* will not return *University of California Los Angeles* and *Joburg ZA* will not return *Johannesburg* or *South Africa*.
 
+There is also a filter to show only applications where the applicant submitted with an invalid registration code using the override option (see below). This can be used to manually check these applications.
+
 ![Training request list view](images/amy_training_requests.png)
 
+!!! note "Member code validation on training requests"
+
+    AMY validates the registration code entered by applicants. If the code is invalid, inactive, or has no seats remaining (applicable for memberships), the form will display an error. However, applicants may check a box labelled "Continue with registration code marked as invalid" to submit the application anyway.
+
 Some trainees will already be in AMY. If there is a record with a matching name and email address, they will show up with a "matched trainee" when you search for them. You can match the application to this trainee, or if the match was incorrect, search for a different Person record or create a new Person.
 
 ![Match trainee to person](images/match_trainee.png)