From d51dbfb6bf3ed1e4adff3ef79f7528d8bceb044d Mon Sep 17 00:00:00 2001
From: Martin Trigaux <mat@openerp.com>
Date: Fri, 1 Mar 2013 12:27:20 +0100
Subject: [PATCH] [IMP] gamification: better cron call and comments

bzr revid: mat@openerp.com-20130301112720-tc781hdz1y1vnqp1
---
 addons/gamification/goal.py                   | 37 ++++++++++++++++---
 addons/gamification/goal_view.xml             |  2 +-
 addons/gamification/plan.py                   | 27 +++++---------
 .../templates/personal_progress.mako          |  3 +-
 4 files changed, 44 insertions(+), 25 deletions(-)

diff --git a/addons/gamification/goal.py b/addons/gamification/goal.py
index 95e55fe4ab5..bf5973b7dea 100644
--- a/addons/gamification/goal.py
+++ b/addons/gamification/goal.py
@@ -162,17 +162,26 @@ class gamification_goal(osv.Model):
     }
 
 
-    def _update_all(self, cr, uid, ids=False, context=None):
-        """Update every goal in progress"""
+    def _update_all(self, cr, uid, context=None, ids=False):
+        """Update every goal in progress or reached whose date is not passed"""
+        if not context: context = {}
         if not ids:
-            ids = self.search(cr, uid, [('state', 'in', ('inprogress','inprogress_update', 'reached'))])
+            ids = self.search(cr, uid, [
+                '&',
+                    ('state', 'in', ('inprogress','inprogress_update', 'reached')),
+                    '|',
+                        ('end_date', '>=', fields.date.today()),
+                        ('end_date', '=', False)
+                ])
 
         return self.update(cr, uid, ids, context=context)
 
     def update(self, cr, uid, ids, context=None):
         """Update the goals to recomputes values and change of states
 
-        If a goal reaches the target value, the status is set to reach
+        If a manual goal is not updated for enough time, the user will be
+        reminded to do so (done only once, in 'inprogress' state).
+        If a goal reaches the target value, the status is set to reached
         If the end date is passed (at least +1 day, time not considered) without
         the target value being reached, the goal is set as failed."""
         
@@ -239,16 +248,31 @@ class gamification_goal(osv.Model):
         return True
 
     def action_start(self, cr, uid, ids, context=None):
+        """Mark a goal as started.
+
+        This should only be used when creating goals manually (in draft state)"""
         self.write(cr, uid, ids, {'state': 'inprogress'}, context=context)
         return self.update(cr, uid, ids, context=context)
 
     def action_reach(self, cr, uid, ids, context=None):
+        """Mark a goal as reached.
+
+        If the target goal condition is not met, the state will be reset to In
+        Progress at the next goal update until the end date."""
         return self.write(cr, uid, ids, {'state': 'reached'}, context=context)
 
     def action_fail(self, cr, uid, ids, context=None):
+        """Set the state of the goal to failed.
+
+        A failed goal will be ignored in future checks."""
         return self.write(cr, uid, ids, {'state': 'failed'}, context=context)
 
     def action_cancel(self, cr, uid, ids, context=None):
+        """Reset the completion after setting a goal as reached or failed.
+
+        This is only the current state, if the date and/or target criterias
+        match the conditions for a change of state, this will be applied at the 
+        next goal update."""
         return self.write(cr, uid, ids, {'state': 'inprogress'}, context=context)
 
     def create(self, cr, uid, vals, context=None):
@@ -258,7 +282,10 @@ class gamification_goal(osv.Model):
         return super(gamification_goal, self).create(cr, uid, vals, context=context)
         
     def write(self, cr, uid, ids, vals, context=None):
-        """Overwrite the write method to update the last_update field to today"""
+        """Overwrite the write method to update the last_update field to today
+
+        If the current value is changed and the report frequency is set to On 
+        change, q report is generated"""
         for goal in self.browse(cr, uid, ids, vals):
             vals['last_update'] = fields.date.today()
 
diff --git a/addons/gamification/goal_view.xml b/addons/gamification/goal_view.xml
index 4c605f2660c..f0305eb758a 100644
--- a/addons/gamification/goal_view.xml
+++ b/addons/gamification/goal_view.xml
@@ -58,7 +58,7 @@
                             </group>
                             <group string="Schedule">
                                 <field name="start_date" attrs="{'readonly':[('state','!=','draft')]}"/>
-                                <field name="end_date" attrs="{'readonly':[('state','!=','draft')]}"/>
+                                <field name="end_date" />
                                 <field name="computation_mode" invisible="1"/>
 
                                 <label for="remind_update_delay" attrs="{'invisible':[('computation_mode','!=', 'manually')]}"/>
diff --git a/addons/gamification/plan.py b/addons/gamification/plan.py
index 9bede3ba62e..bdaafd5f4ba 100644
--- a/addons/gamification/plan.py
+++ b/addons/gamification/plan.py
@@ -160,13 +160,13 @@ class gamification_goal_plan(osv.Model):
             self.plan_subscribe_users(cr, uid, ids, [user.id for user in new_group.users], context=context)
         return write_res
 
-    def _update_all(self, cr, uid, ids=False, context=None):
+    def _update_all(self, cr, uid, context=None, ids=False):
         """Update the plans
 
         Create the goals for planlines not linked to goals (eg: modified the 
             plan to add planlines)
         :param list(int) ids: the ids of the plans to update, if False will 
-        update every goal in progress"""
+        update only goals in progress."""
 
         if not ids:
             ids = self.search(cr, uid, [('state', '=', 'inprogress')])
@@ -180,19 +180,6 @@ class gamification_goal_plan(osv.Model):
                 goal_ids = goal_obj.search(cr, uid, [('planline_id', '=', planline.id)] , context=context)
                 goal_obj.update(cr, uid, goal_ids, context=context)
 
-            # useless, goals removed in cascade
-            # current_planlines = [planline.id for planline in plan.planline_ids]
-            # print(current_planlines)
-            # related_planlines = planline_obj.search(cr, uid, [('plan_id','=',plan.id)])
-            # print(related_planlines)
-            # # the list of planlines linked to the plan but not in plan.planline_ids
-            # excluded_planlines = [plid for plid in related_planlines if plid not in current_planlines ]
-            # print(excluded_planlines)
-            # excluded_goals = goal_obj.search(cr, uid, [('planline_id', 'in', excluded_planlines)], context=context)
-            # print(excluded_goals)
-            # goal_obj.write(cr, uid, excluded_goals, {'state': 'canceled'}, context=context)
-
-
     def action_start(self, cr, uid, ids, context=None):
         """Start a draft goal plan
 
@@ -261,7 +248,12 @@ class gamification_goal_plan(osv.Model):
         return res
 
     def generate_goals_from_plan(self, cr, uid, ids, context=None):
-        """Generate the lsit of goals fron a plan"""
+        """Generate the list of goals linked to a plan.
+
+        If goals already exist for this planline, the planline is skipped. This 
+        can be called after each change in the user or planline list.
+        :param list(int) ids: the list of plan concerned"""
+
         for plan in self.browse(cr, uid, ids, context):
             (start_date, end_date) = start_end_date_for_period(plan.period)
 
@@ -314,11 +306,12 @@ class gamification_goal_plan(osv.Model):
         """ Add the following users to plans
 
         :param ids: ids of plans to which the users will be added
-        :param user_ids: ids of the users to add"""
+        :param new_user_ids: ids of the users to add"""
 
         for plan in self.browse(cr,uid, ids, context):
             subscription = [user.id for user in plan.user_ids]
             subscription.extend(new_user_ids)
+            # remove duplicates
             unified_subscription = list(set(subscription))
             self.write(cr, uid, ids, {'user_ids': [(4, uid) for uid in unified_subscription]}, context=context)
         return True
diff --git a/addons/gamification/templates/personal_progress.mako b/addons/gamification/templates/personal_progress.mako
index 3c4e48f82a1..702e844cf06 100644
--- a/addons/gamification/templates/personal_progress.mako
+++ b/addons/gamification/templates/personal_progress.mako
@@ -7,9 +7,8 @@
 	<header>
         <strong>${object.name}</strong>
     </header>
-
     <p class="oe_grey">${object.report_header or ''}</p>
-    <br/><br/>
+    <br><br>
     <table width="100%" border="1">
     <tr>
         <th>Goal</th>