encoach_frontend_new_v3/frontend/docs/DEVELOPER_FEEDBACK.md

EnCoach Odoo 19 -- Developer Feedback

Date: March 11, 2026 Status: ALL ITEMS RESOLVED (March 13, 2026) Reference: ODOO_MIGRATION_SRS_v2.md

---

Overall Assessment

The delivery covers approximately 85% of the SRS v2 requirements. All 15 custom modules are present, the core AI/ML services are well-implemented, data models match the specification, and 67-72 API endpoints are wired up with proper JWT authentication and security groups. The code quality is solid -- clean structure, proper error handling, and good separation of concerns.

The items below still need to be implemented to reach full SRS compliance.

---

1. Payment Integration (Critical -- Not Implemented)

SRS Reference: Section 7

All three payment services are currently stubs that return "not yet implemented". The SRS requires full integration with:

1.1 Stripe

Files: encoach_subscription/services/stripe_service.py

Required functionality:

• Install and use the stripe Python SDK
• create_checkout_session() -- Create a Stripe Checkout Session using stripe.checkout.Session.create() with:
  • line_items from the selected encoach.package
  • success_url and cancel_url from the request
  • client_reference_id = user ID
  • customer_email = user email
  • Apply discount if discount_code is provided (validate against encoach.discount)
• Return { "sessionId": "cs_...", "url": "https://checkout.stripe.com/..." }
• Webhook endpoint (POST /api/stripe/webhook):
  • Verify signature using stripe.Webhook.construct_event() with STRIPE_WEBHOOK_SECRET
  • Handle checkout.session.completed event:
    • Find user by client_reference_id
    • Extend subscription_expiration by the package's duration_days
    • Create encoach.subscription.payment record
    • For corporate users, propagate subscription to entity members

1.2 PayPal

Files: encoach_subscription/services/paypal_service.py

Required functionality:

• Use PayPal REST API (httpx or requests)
• Obtain access token from PAYPAL_ACCESS_TOKEN_URL using client_id + client_secret
• create_order() -- Create PayPal order via POST /v2/checkout/orders:
  • intent: "CAPTURE"
  • purchase_units with amount from package (minus discount)
  • Return { "orderId": "...", "approvalUrl": "https://paypal.com/..." }
• capture_order() -- Capture approved order via POST /v2/checkout/orders/{id}/capture:
  • On success, extend subscription and create payment record
  • Return { "ok": true }

1.3 Paymob

Files: encoach_subscription/services/paymob_service.py

Required functionality:

• Use Paymob API (httpx or requests)
• create_intention() -- Create payment intention:
  • Authenticate with PAYMOB_API_KEY
  • Create order, then payment key
  • Return { "intentionId": "...", "clientSecret": "..." }
• verify_transaction() -- Verify webhook callback:
  • Validate HMAC using PAYMOB_SECRET
  • On success, extend subscription and create payment record
• Webhook endpoint (POST /api/paymob/webhook):
  • Verify transaction authenticity
  • Update subscription on success

1.4 Subscription Extension Logic

After any successful payment (all providers), the system must:

1. Calculate new expiration: max(current_expiration, now()) + duration_days
2. Update user.subscription_expiration
3. Create encoach.subscription.payment record with provider, amount, transaction ID
4. For corporate users: propagate the new expiration to all entity members

---

2. Missing API Endpoints

SRS Reference: Section 4

The following endpoints are specified in the SRS but not present in the delivery:

2.1 Exam Variants (add to encoach_api/controllers/generation.py or exams.py)

Endpoint	Method	Description
POST /api/exam/writing/<task>/attachment	POST	Academic writing Task 1 with image upload (multipart form with file + difficulty). Must send image to GPT-4o vision API for prompt generation.
GET /api/exam/level/	GET	Return a pre-built level exam (no AI generation)
GET /api/exam/level/utas	GET	Return a UTAS-format level exam
POST /api/exam/level/import/	POST	Import level exam from uploaded file
POST /api/exam/level/custom/	POST	Generate custom level exam from JSON specification
POST /api/exam/reading/import	POST	Import reading exam from Word/Excel file
POST /api/exam/listening/import	POST	Import listening exam from file

2.2 Entity/Role/Permission Management (new controller files needed)

Endpoint	Method	Description
GET /api/entities	GET	List entities (with pagination)
POST /api/entities	POST	Create entity
PATCH /api/entities/<id>	PATCH	Update entity
DELETE /api/entities/<id>	DELETE	Delete entity
GET /api/roles	GET	List roles (filter by entityID)
POST /api/roles	POST	Create role
PATCH /api/roles/<id>	PATCH	Update role
DELETE /api/roles/<id>	DELETE	Delete role
GET /api/permissions	GET	List permissions

2.3 Other Missing Endpoints

Endpoint	Method	Description
GET /api/discounts	GET	List discount codes
POST /api/discounts	POST	Create discount code
PATCH /api/discounts/<id>	PATCH	Update discount code
DELETE /api/discounts/<id>	DELETE	Delete discount code
GET /api/approval-workflows	GET	List approval workflows
POST /api/approval-workflows	POST	Create approval workflow
PATCH /api/approval-workflows/<id>	PATCH	Update approval workflow
DELETE /api/approval-workflows/<id>	DELETE	Delete approval workflow

---

3. Evaluation Status Endpoint Path

SRS Reference: Section 4.2

Current: GET /api/evaluate/status?sessionId=...&exerciseId=... (query params) SRS specifies: GET /api/evaluate/<sessionId>/<exerciseId> (path params)

The frontend SRS document (ODOO_MIGRATION_FRONTEND_SRS.md) references the path-param version. Please either:

• (A) Change the endpoint to use path params to match the SRS, OR
• (B) Confirm that query params are intentional so we can update the frontend SRS

---

4. Record-Level Security Rules (ir.rule)

SRS Reference: Section 5

The delivery has model-level ACL rules (ir.model.access.csv) for each module, which is good. However, record-level security rules (ir.rule) are also needed to ensure:

• Students can only read/write their own records (sessions, stats, evaluations, training, tickets)
• Teachers can see records for students in their groups/assignments
• Corporate users can see records within their entity
• Admin/Developer users have unrestricted access

Example rules needed (add to each module's security/ directory):

<!-- encoach_stats/security/rules.xml -->
<record id="rule_stat_student_own" model="ir.rule">
    <field name="name">Students see own stats</field>
    <field name="model_id" ref="model_encoach_stat"/>
    <field name="groups" eval="[(4, ref('encoach_core.group_encoach_student'))]"/>
    <field name="domain_force">[('user_id', '=', user.id)]</field>
</record>

Models that need record rules:

• encoach.session -- students see own sessions only
• encoach.stat -- students see own stats only
• encoach.evaluation -- students see own evaluations only
• encoach.training -- students see own training only
• encoach.ticket -- students see own tickets, admins see all
• encoach.assignment -- students see assignments they're assigned to
• encoach.exam -- filtered by access field (public/private/entity)

---

5. Whisper Scaling

SRS Reference: Section 6.5

Current: Single lazy-loaded Whisper model instance in whisper_service.py SRS specifies: 4 model instances with ThreadPoolExecutor(max_workers=4) for parallel transcription

Update encoach_ai_media/services/whisper_service.py to:

1. Load the configurable number of model instances (from encoach.whisper_workers system parameter, default 4)
2. Use concurrent.futures.ThreadPoolExecutor to process transcription requests in parallel
3. Round-robin or queue-based assignment of requests to model instances

This is important for production performance when multiple students submit speaking exams simultaneously.

---

6. FAISS Index Type

SRS Reference: Section 6.8

Current: faiss.IndexFlatIP (inner product) SRS specifies: faiss.IndexFlatL2 (L2/Euclidean distance)

The current implementation normalizes vectors and uses inner product, which effectively gives cosine similarity. This works correctly, but it's a deviation from the SRS. If the original ielts-be training data was built with L2 distance, the results may differ slightly. Please verify which index type the original system used and align accordingly.

---

7. Payment Webhook Endpoints

SRS Reference: Section 7

In addition to the payment service implementations (Item 1 above), the following webhook controller routes need to be added to encoach_api/controllers/subscriptions.py:

@http.route('/api/stripe/webhook', type='http', auth='public', methods=['POST'], csrf=False, cors='*')
def stripe_webhook(self, **kwargs):
    """Handle Stripe webhook events (checkout.session.completed, etc.)."""
    ...

@http.route('/api/paymob/webhook', type='http', auth='public', methods=['POST'], csrf=False, cors='*')
def paymob_webhook(self, **kwargs):
    """Handle Paymob transaction callbacks."""
    ...

These must be auth='public' (no JWT) since they're called by external services.

---

Summary of Action Items

#	Item	Priority	Status
1	Payment integration (Stripe/PayPal/Paymob)	Critical	RESOLVED
2	Missing API endpoints (~20 endpoints)	High	RESOLVED
3	Evaluation status endpoint path alignment	Medium	RESOLVED
4	ir.rule record-level security rules	High	RESOLVED
5	Whisper multi-instance scaling	Medium	RESOLVED
6	FAISS index type verification	Low	RESOLVED
7	Payment webhook endpoints	Critical	RESOLVED

---

Changes Already Applied

The following small fixes have been applied directly to the codebase:

1. encoach_ai_media/__manifest__.py -- Added missing external_dependencies: numpy, openai-whisper, librosa, soundfile, httpx
2. encoach_training/__manifest__.py -- Added missing external_dependencies: numpy, faiss-cpu, sentence-transformers
3. requirements.txt -- Created at project root with all Python dependencies and versions from SRS Section 6.10