Feat/module interface standardization

[Mrchinedum]

fixed #369

feat: implement module interface standardization

Module interfaces were inconsistent across the codebase. Some modules
used free functions (reputation.rs), others used manager structs
(audit.rs, performance.rs) with no shared convention for doc comments,
section grouping, or return-value annotations. This change defines the
standard and brings all affected modules into compliance.

Changes

docs/MODULE_INTERFACE_STANDARDS.md (new)

• Defines 8 mandatory rules for every module in contracts/teachlink/src/:
  1. Module-level //! doc comment with purpose and responsibilities
  2. Manager-struct pattern — all public logic on a zero-size struct,
     no free functions
  3. Section comments using // ===== Section Name ===== style;
     required sections: Initialization, Mutations, Admin, Queries
  4. #[must_use] on every pure getter (no side effects)
  5. Error handling — state-changing fns return Result<T, E>;
     getters return T or Option
  6. Authorization — user.require_auth() at the top of every
     state-changing function; #[cfg(not(test))] guards only where
     the test harness cannot provide auth
  7. Compliance table listing all conformant modules as reference
  8. Minimal end-to-end example module (ExampleManager)

contracts/teachlink/src/reputation.rs

• Replaced 4 free functions (update_participation, update_course_progress,
  rate_contribution, get_reputation) with ReputationManager struct
• Added //! module doc comment
• Added section comments: Mutations, Queries, Internal
• Added #[must_use] to get_reputation
• Moved set_reputation to a private Internal helper (was already private
  but now explicitly grouped)
• Logic is unchanged; only the interface shape changed

contracts/teachlink/src/score.rs

• Added //! module doc comment with responsibilities list
• Added // ===== Mutations ===== section comment above update_score
• Added // ===== Queries ===== section comment above get_score
• Added #[must_use] to get_score, get_courses, get_contributions

contracts/teachlink/src/rewards.rs

• Added //! module doc comment with responsibilities list
• Replaced // ========================== / // Section / // ==========================
  style comments with standard // ===== Section ===== style:
  Initialization (initialize_rewards)
  Mutations (fund_reward_pool, issue_reward, claim_rewards)
  Admin (set_reward_rate, update_rewards_admin)
  Queries (get_user_rewards, get_reward_pool_balance,
  get_total_rewards_issued, get_reward_rate,
  get_rewards_admin)
• Added #[must_use] to all 5 getters

contracts/teachlink/src/lib.rs

• Updated all 4 reputation call sites from free-function style to
  manager-struct style:
  reputation::update_participation -> ReputationManager::update_participation
  reputation::update_course_progress -> ReputationManager::update_course_progress
  reputation::rate_contribution -> ReputationManager::rate_contribution
  reputation::get_reputation -> ReputationManager::get_reputation

Acceptance criteria met

✓ Interface standards defined — docs/MODULE_INTERFACE_STANDARDS.md
✓ Non-compliant modules refactored — reputation.rs (struct), score.rs
(doc + sections), rewards.rs (doc + sections)
✓ Interface documentation added — module-level //! doc on all three
modules; standards doc with compliance table
✓ Examples created — minimal ExampleManager in standards doc;
reputation.rs, score.rs, and rewards.rs serve as living reference
implementations

[drips-wave]

@Mrchinedum Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits