[BE] Create CompetencyCriteria #665

• [non-blocking, owner: implementer] Should the two new UniqueConstraints (one root per competency; one course-level group per competency+course) land in this ticket's own follow-up migration, or fold into [BE] Implement CBE core data models (CompetencyTaxonomy, criteria, learner status) #613's initial migration if it hasn't merged yet? Recommended: an independent follow-up migration here, to keep the tickets decoupled.
• [non-blocking, owner: implementer] Naming convention for the root and course-level groups, which are never shown in the UI but likely need a non-null name per ADR 0002's field list. Recommended: a deterministic placeholder such as f"{tag.value} (root)" / f"{tag.value} — {course_run.title}", to aid admin/debug visibility.
• [non-blocking, owner: architect/future] object_id currently must resolve to a CourseRun (400 otherwise). Future library-subsection support may need this to loosen; no action needed now.
• [non-blocking, owner: architect/future] Validating that object_id is gradeable was dropped: openedx-core has no grading data to check against (CourseGradingPolicy isn't built yet; grading lives in openedx-platform, never imported here). If needed later, it'll need a sync mechanism into openedx_catalog or enforcement at another layer (frontend, or the evaluation handler). Not resolved here.
• [non-blocking, owner: architect/future] This ticket builds only the 3-level hierarchy (root/course-level/leaf), no richer author-defined grouping. If added later, resolve_supplied_leaf_group's leaf-shape test (parent_id set, course_id null) breaks, since a new grouping node would have the same shape. Fix needs either an explicit node-type field or a relationship-based check (child groups vs. a CompetencyCriterion). Not resolved here; flagged so a future ticket doesn't rediscover it.
• [non-blocking, owner: implementer] Whether to keep the urls.py → rest_api/urls.py → rest_api/v1/urls.py indirection when this app currently has only one URL to register. Raised as a minor review quibble; not blocking, and trivial to collapse to fewer files in the PR if the implementer prefers a flatter structure.

Data Structures

CompetencyCriteriaGroup (ADR 0002 fields, unchanged) gains two partial unique constraints:
  UniqueConstraint(fields=["oel_tagging_tag_id"], condition=Q(parent_id__isnull=True))
      # at most one root group per competency
  UniqueConstraint(fields=["oel_tagging_tag_id", "course_id", "parent_id"], condition=Q(course_id__isnull=False))
      # at most one course-level group per (competency, course) under a given parent

These constraints make root/course-level resolution race-safe via plain get_or_create() inside transaction.atomic(), the pattern this repo already uses elsewhere for constraint-backed get_or_create() calls, rather than select_for_update or catch-and-retry, neither of which appears in this codebase. A leaf group never sets course_id and always has a non-null parent_id, so it never matches either constraint's condition: no new depth/level column is needed, since (parent_id, course_id) alone identifies root, course-level, and leaf.

def create_competency_criterion(
    group: CompetencyCriteriaGroup,
    object_id: str,
    rule_profile_id: int | None = None,
    rule_type_override: str | None = None,
    rule_payload_override: dict | None = None,
) -> CompetencyCriterion:
    """Read-merge-write the ObjectTag, call the reserved _validate_containment(group,
    object_id) seam (implemented by #666, not here), then create and return the
    CompetencyCriterion row under group."""

def resolve_or_create_leaf_group(
    tag: Tag, course_run: CourseRun, logic_operator: str | None = None,
) -> CompetencyCriteriaGroup:
    """Get-or-create the root and course-level groups for this competency/course, then
    always create and return a fresh leaf group parented under the course-level group,
    with logic_operator set from the argument, defaulting to "OR" if None."""

def resolve_supplied_leaf_group(group_id: int, tag: Tag, course_run: CourseRun) -> CompetencyCriteriaGroup:
    """Resolve group_id via get_object_or_404 (this app has no custom exception-handling
    mixin, so a bare .get() would surface as an unhandled 500, not a 404). Validate, in
    order: it is a leaf (parent_id not null, course_id null); it belongs to tag; its
    course-level parent's course_id matches course_run. Raise a field-level 400 on the
    first failure that doesn't hold; otherwise return the group unchanged."""

def associate_competency_criterion(
    tag_id: int,
    object_id: str,
    group_id: int | None = None,
    logic_operator: str | None = None,
    rule_profile_id: int | None = None,
    rule_type_override: str | None = None,
    rule_payload_override: dict | None = None,
) -> CompetencyCriterion:
    """The single public entry point. Resolves the competency Tag and the CourseRun from
    object_id's parsed course key, rejects a duplicate (tag_id, object_id) association
    regardless of group_id, then branches on whether group_id was supplied
    (resolve_supplied_leaf_group vs. resolve_or_create_leaf_group), then calls
    create_competency_criterion() on the resulting leaf, all inside one
    transaction.atomic() block. Rejects with a 400 if group_id and logic_operator are
    both supplied, since logic_operator only ever applies to a leaf group this call
    creates, and updating an existing leaf's logic_operator is #675's scope. When
    logic_operator is supplied without group_id, it is threaded into
    resolve_or_create_leaf_group."""

Logic

1. Resolve the competency Tag from the URL's tag_id; 404 if missing or not backed by a CompetencyTaxonomy.
2. Parse object_id via UsageKey.from_string; 400 with a field-level error if it doesn't parse.
3. Resolve the CourseRun from the parsed key's course key via openedx_catalog.api.get_course_run(); 400 if no matching row. This course_run is the single source of truth for course: it drives the course-scope check, whichever branch runs.
4. Permission check: build the taxonomy/object-id permission object and check oel_tagging.can_tag_object; 403 on failure. This composite (studio write access to the subsection's course plus taxonomy view access) is already registered globally by openedx-platform's content_tagging app, so no new predicate is needed.
5. Duplicate check: look up ObjectTag.objects.filter(object_id=object_id, taxonomy_id=tag.taxonomy_id, tag_id=tag.id).first(). If found, check whether any CompetencyCriterion already references it (CompetencyCriterion.objects.filter(oel_tagging_objecttag=existing_object_tag).exists()); if so, reject with a 400 ValidationError (this repo's existing pattern for uniqueness violations — see src/openedx_tagging/rest_api/v1/serializers.py's validate_tag_value; there is no 409 usage anywhere in this codebase's REST API). If no ObjectTag exists yet for this tag on this object, there is nothing to conflict with; proceed. This check runs before any group creation, regardless of whether group_id was supplied, so a duplicate attempt via the derive-or-create path doesn't leave behind an orphaned empty group (ADR 0002 forbids persisting empty groups).
6. group_id/logic_operator exclusivity check: if both group_id and logic_operator are supplied, reject with a 400 ValidationError naming the conflict, before resolving or creating anything. logic_operator only ever sets a newly created leaf's operator; an existing leaf's operator is [BE] Build endpoint for removing a Competency Criteria Group #675's to change, not this endpoint's, so the two fields together are a client error rather than an ambiguity for this endpoint to resolve on its own.
7. Branch on group_id: if supplied, call resolve_supplied_leaf_group(); if not, call resolve_or_create_leaf_group(), passing logic_operator through so the newly created leaf's logic_operator column is set from it, defaulting to "OR" if omitted. Both return a CompetencyCriteriaGroup guaranteed to be a valid, course-matched leaf (see Data Structures for the supplied-group validation order).
8. Inside one transaction.atomic() block covering steps 7-8: call create_competency_criterion() on the resolved/created leaf. Keeping this inside the same atomic block as group resolution matters for the no-group_id branch: if criterion creation fails (a containment violation from [BE] Add Competency hierarchy dominance validation to Competency Criteria Creation #666's seam, an invalid override), the rollback must also undo any newly-created root/course-level/leaf groups, since ADR 0002 forbids persisting empty groups. create_competency_criterion()'s own read-merge-write step will re-resolve the same ObjectTag row checked in step 5 (or find none, on a first association) — an implementer may thread the already-resolved ObjectTag through to avoid a redundant query, but this is an optimization, not a correctness requirement.
9. Return 201 with the created criterion's representation, including group_id referring to whichever leaf was used.

Public-API impact: additive functions in applets/cbe/api.py, reusing openedx_tagging.api.get_object_tags/tag_object and openedx_catalog.api.get_course_run unchanged. No breaking changes: greenfield work, no shipped callers. .importlinter needs openedx_catalog and openedx_learning added to its layering contract if #613 hasn't already, since this ticket's course-run lookup crosses into openedx_catalog.

Test strategy: unit tests for associate_competency_criterion covering both branches (derive-or-create: first association, same-course reuse, different-course reuse, a concurrent-request race not producing duplicate root/course-level rows, logic_operator supplied vs. defaulted to "OR"; supplied-group: happy path, non-leaf rejection, ownership-mismatch rejection, course-mismatch rejection, not-found) plus the three duplicate-association rejection cases (same group, different existing group, derive-path) plus the group_id/logic_operator mutual-exclusion rejection plus DRF integration tests for every acceptance criterion above.

Example Resolution Prompt

Implement POST /api/cbe/v1/competencies/<int:tag_id>/criteria/ per the Data Structures and Logic above: request body {object_id, group_id?, logic_operator?, rule_profile_id?, rule_type_override?, rule_payload_override?}. Assume #613 has landed CompetencyCriteriaGroup/CompetencyCriterion matching ADR docs/openedx_learning/decisions/0002-competency-criteria-model.rst; code goes under src/openedx_learning/applets/cbe/ per ADR 0001.

Build associate_competency_criterion() as the single api.py entry point, following the Technical Details signatures and call order exactly: course/tag resolution, the permission check, the duplicate-association check, the group_id branch, then the shared atomic block. One CompetencyCriterionSerializer, no variant needed, with group_id genuinely optional, mirroring the existing optional-field-driven-branching pattern in this repo's TaxonomyTagsView tag-creation body (see Context). Reuse the existing oel_tagging.can_tag_object permission; no new predicate. Do not validate gradeability of object_id — deliberately out of scope, see Open Questions. Do not implement containment/isolation-rule validation — that is #666's scope, not this ticket's.

Verify against every scenario in Acceptance Criteria above.

Context

• Namespace: /api/cbe/v1/ is one combined namespace, deliberately not split into authoring vs. learner API paths, even if a learner-facing CBE endpoint is added under this app later.
• [FE] "+ Rule" & "+ Rule Group" Buttons #671: source of the course-author actor and the reuse-vs-create branching this ticket implements.
• [BE] Add Competency hierarchy dominance validation to Competency Criteria Creation #666: implements the parent-competency dominance validation via the _validate_containment(group, object_id) seam this ticket reserves (see Explicitly out of scope above for its resolved scope).
• [FE] Create & View Competency Criteria #672: eventual UI consumer of this endpoint; no contract dependency.
• [BE] Build endpoint for removing a Competency Criteria Group #675: update/delete of a CompetencyCriteriaGroup.
• [BE] GET Competency Criteria & Groups #681: GET endpoint for groups + criteria.
• Companion ticket, openedx-platform (not yet numbered): this ticket's oel_tagging.can_tag_object check (step 4 above) currently resolves course objects through a legacy-only role check that never consults the new authorization service, even after a course has switched over to it, unlike Studio's own tag-editing endpoint, which already handles that switch correctly. The companion ticket fixes the shared permission check itself; this ticket needs no code change once it lands, since has_perm('oel_tagging.can_tag_object', ...) will simply start returning the right answer.
• ADR 0002 (docs/openedx_learning/decisions/0002-competency-criteria-model.rst): canonical field lists and tree semantics for both models; its rule against persisting empty groups is why group creation and criterion creation share one transaction.
• ADR 0001: places this ticket's code at src/openedx_learning/applets/cbe/.
• openedx-platform's content_tagging/rules.py: overrides oel_tagging.can_tag_object with the permission composite this ticket relies on.
• src/openedx_tagging/rest_api/v1/views.py's TaxonomyTagsView: precedent for an optional request field (parent_tag_value) branching create logic downstream, the pattern group_id follows.
• src/openedx_tagging/rest_api/v1/exception_handlers.py: only APIException/Http404/ PermissionDenied map to a clean response, hence get_object_or_404 over a bare .get() for the supplied-group_id path.
• src/openedx_tagging/rest_api/v1/serializers.py's validate_tag_value: this repo's only existing uniqueness-violation precedent, a 400 ValidationError, the pattern the duplicate-association check follows. No 409 usage exists anywhere in this codebase's REST API.
• src/openedx_tagging/models/base.py's ObjectTag: unique_together on (object_id, taxonomy, tag_id), which the duplicate-association check relies on.
• src/openedx_tagging/api.py (get_object_tags, tag_object): the two public functions this ticket's read-merge-write logic composes.
• openedx_catalog.api.get_course_run(): resolves the CourseRun from a course key. See Open Questions for why gradeable-subsection validation isn't checked against it.

Files to create and modify

New files

Modified files