Refactored interfaces related to business process management and simulation....

Refactored interfaces related to business process management and simulation. Nexedi refactoring should include "6th element" idea if possible, once it is better understood. 

git-svn-id: https://svn.erp5.org/repos/public/erp5/sandbox/amount_generator@35543 20353a03-c40f-0410-a6d1-a30d3c3de9de

product/ERP5/Document/BusinessPath.py

@@ -91,8 +91,6 @@ class BusinessPath(Path, Predicate):
   zope.interface.implements(interfaces.ICategoryAccessProvider,
                             interfaces.IArrowBase,
                             interfaces.IBusinessPath,
-                            interfaces.IBusinessBuildable,
-                            interfaces.IBusinessCompletable,
                             interfaces.IPredicate,
                             )
 

product/ERP5/interfaces/business_buildable.py

-# -*- coding: utf-8 -*-
-##############################################################################
-#
-# Copyright (c) 2009 Nexedi SA and Contributors. All Rights Reserved.
-#                    Jean-Paul Smets-Solanes <jp@nexedi.com>
-#
-# WARNING: This program as such is intended to be used by professional
-# programmers who take the whole responsability of assessing all potential
-# consequences resulting from its eventual inadequacies and bugs
-# End users who are looking for a ready-to-use solution with commercial
-# garantees and support are strongly adviced to contract a Free Software
-# Service Company
-#
-# This program is Free Software; you can redistribute it and/or
-# modify it under the terms of the GNU General Public License
-# as published by the Free Software Foundation; either version 2
-# of the License, or (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
-#
-##############################################################################
-"""
-Products.ERP5.interfaces.business_buildable
-"""
-
-from zope.interface import Interface
-
-class IBusinessBuildable(Interface):
-  """Business Buildable interface specification
-
-  This interface is implemented by Business Path as part
-  of Business Process management. It can be used to
-  check which path in a business process can be built
-  and to trigger the build process for a given path.
-  """
-
-  def isBuildable(explanation):
-    """Returns True if any of the related Simulation Movement
-    is buildable and if the predecessor state is completed.
-
-    'explanation' is the Order or Item or Document which is the
-    cause of a root applied rule in the simulation
-    """
-
-  def isPartiallyBuildable(explanation):
-    """Returns True if any of the related Simulation Movement
-    is buildable and if the predecessor state is partially completed.
-
-    'explanation' is the Order or Item or Document which is the
-    cause of a root applied rule in the simulation
-
-    NOTE (JPS): It is not sure whether this method will ever
-    be used.
-    """
-
-  def build(explanation):
-    """Builds all related movements in the simulation
-    using the builders defined on the Business Path
-
-    'explanation' is the Order or Item or Document which is the
-    cause of a root applied rule in the simulation
-    """

product/ERP5/interfaces/business_path.py

+# -*- coding: utf-8 -*-
 ##############################################################################
 #
 # Copyright (c) 2009 Nexedi SA and Contributors. All Rights Reserved.
@@ -29,49 +30,81 @@
 Products.ERP5.interfaces.business_path
 """
 
-from Products.ERP5.interfaces.business_completable import IBusinessCompletable
-from Products.ERP5.interfaces.business_buildable import IBusinessBuildable
+from zope.interface import Interface
 
-class IBusinessPath(IBusinessCompletable, IBusinessBuildable):
+class IBusinessPath(Interface):
   """Business Path interface specification
+
+  IBusinessPath provides a method to calculate the completion
+  date of existing movements based on business path properties.
+  It also provides methods to determine whether all related simulation
+  movements related to a given explanation are completed, partially
+  completed or frozen. Finally, it provides a method to invoke
+  delivery builders for all movements related to a given explanation.
   """
-  def getExpectedStartDate(task, predecessor_date=None):
-    """Returns the expected start date for this
-    path based on the task and provided predecessor_date.
 
-    'task' is a document which follows the ITaskGetter interface
-    (getStartDate, getStopDate) and defined the reference dates
-    for the business process execution
+  def getMovementCompletionDate(self, movement):
+    """Returns the date of completion of the movemnet 
+    based on paremeters of the business path. This complete date can be
+    the start date, the stop date, the date of a given workflow transition
+    on the explaining delivery, etc.
 
-    'predecessor_date' can be provided as predecessor date and
-     to override the date provided in the task
+    movement -- a Simulation Movement
     """
   
-  def getExpectedStopDate(task, predecessor_date=None):
-    """Returns the expected stop date for this
-    path based on the task and provided predecessor_date.
+  def isCompleted(explanation):
+    """returns True if all related simulation movements for this explanation
+    document are in a simulation state which is considered as completed
+    according to the configuration of the current business path.
+    Completed means that it is possible to move to next step
+    of Business Process. This method does not check however whether previous
+    trade states of a given business process are completed or not.
+    Use instead IBusinessPathProcess.isBusinessPathCompleted for this purpose.
 
-    'task' is a document which follows the ITaskGetter interface
-    (getStartDate, getStopDate) and defined the reference dates
-    for the business process execution
+    explanation -- the Order, Order Line, Delivery or Delivery Line which
+                   implicitely defines a simulation subtree and a union 
+                   business process.
 
-    'predecessor_date' can be provided as predecessor date and
-     to override the date provided in the task
+    NOTE: simulation movements can be completed (ex. in 'started' state) but
+    not yet frozen (ex. in 'delivered' state).
     """
 
-  def getRelatedSimulationMovementValueList(explanation):
-    """Returns list of values of Simulation Movements related to self
-    and delivery
+  def isPartiallyCompleted(explanation):
+    """returns True if some related simulation movements for this explanation
+    document are in a simulation state which is considered as completed
+    according to the configuration of the current business path.
+    Completed means that it is possible to move to next step
+    of Business Process. This method does not check however whether previous
+    trade states of a given business process are completed or not.
+    Use instead IBusinessPathProcess.isBusinessPathCompleted for this purpose.
 
-    explanation - any document related to business path - which bootstraped
-                  process or is related to build of one paths
+    explanation -- the Order, Order Line, Delivery or Delivery Line which
+                   implicitely defines a simulation subtree and a union 
+                   business process.
     """
 
-  def isMovementRelatedWithMovement(movement_value_a, movement_value_b):
-    """Checks if self is parent or children to movement_value
+  def isFrozen(explanation):
+    """returns True if all related simulation movements for this explanation
+    document are in a simulation state which is considered as frozen
+    according to the configuration of the current business path.
+    Frozen means that simulation movement cannot be modified.
+    This method does not check however whether previous
+    trade states of a given business process are completed or not.
+    Use instead IBusinessPathProcess.isBusinessPathCompleted for this purpose.
+
+    explanation -- the Order, Order Line, Delivery or Delivery Line which
+                   implicitely defines a simulation subtree and a union 
+                   business process.
+
+    NOTE: simulation movements can be frozen (ex. in 'stopped' state) but
+    not yet completed (ex. in 'delivered' state).
+    """
 
-    This logic is Business Process specific for Simulation Movements, as
-    sequence of Business Process is not related appearance of Simulation Tree
+  def build(explanation):
+    """Builds all related movements in the simulation using the builders
+    defined on the Business Path
 
-    movement_value_a, movement_value_b - movements to check relation between
+    explanation -- the Order, Order Line, Delivery or Delivery Line which
+                   implicitely defines a simulation subtree and a union 
+                   business process.
     """
\ No newline at end of file

product/ERP5/interfaces/business_completable.py → product/ERP5/interfaces/explainable.py

 # -*- coding: utf-8 -*-
 ##############################################################################
 #
-# Copyright (c) 2009 Nexedi SA and Contributors. All Rights Reserved.
+# Copyright (c) 2010 Nexedi SA and Contributors. All Rights Reserved.
 #                    Jean-Paul Smets-Solanes <jp@nexedi.com>
 #
 # WARNING: This program as such is intended to be used by professional
@@ -27,66 +27,66 @@
 #
 ##############################################################################
 """
-Products.ERP5.interfaces.business_completable
+Products.ERP5.interfaces.business_path
 """
 
 from zope.interface import Interface
 
-class IBusinessCompletable(Interface):
-  """Business Completable interface specification
+class IExplainable(Interface):
+  """Explainable interface specification
 
-  This interface is implemented by Business Path and Business
-  States as part of Business Process Management. It can be
-  used to check whether a path or a state is completed, or
-  partially completed.
+  IExplainable defines the notion of Explanation in  ERP5 simulation. 
+  Explanation was initially introduced  to provide better indexing of 
+  movements in stock and movement tables. Thanks to explanation, it is
+  possible to relate unbuilt simulation movements (ex. planned sourcing)
+  to a root explanation (ex. a production order). This is used
+  in the inventory browser user interface to provide an explanation
+  for each simulated movement which is not yet built. Explanation of 
+  simulation movements are sometimes used to calculate efficiently aggregated
+  quantities and prices of all simulation movements which are part of the
+  same simulation tree.
 
-  TODO: make sure interface can support simulation movements
-  """
-  def isCompleted(explanation):
-    """True if all related simulation movements for this explanation
-    document are delivered and in a simulation state which is considered
-    as finished.
+  IExplainable is implemented by all simulation movements.
 
-    Completed means that it is possible to move to next step of Business Process
+  Explanations in ERP5 are also used in another meaning, as a way to calculate
+  efficiently aggregated quantities and prices of movements in a Delivery. 
+  The current interface is unrelated to this meaning.
   """
-
-  def isPartiallyCompleted(explanation):
-    """True if some related simulation movements for this explanation
-    document are delivered and in simulation state which is considered
-    as finished.
+  def getExplanationValueList():
+    """Returns the list of deliveries of parent simulation
+    movements. The first item in the list is the immediate
+    explanation value. The last item in the list is the root
+    explanation.
     """
 
-  def isFrozen(explanation):
-    """True if all related simulation movements for this explanation
-    are frozen.
-
-    Frozen means that simulation movement cannot be modified.
-
-    NOTE: simulation movements can be frozen (ex. in stopped state) but
-    not yet completed (ex. in delivered state).
+  def getRootExplanationValue():
+    """Returns the delivery of the root simulation
+    movement.
     """
 
-  def getExpectedCompletionDate(task):
-    """Returns the date at which the given state is expected to
-    be completed, based on the start_date and stop_date of
-    the given task document.
-
-    'task' is a document which follows the ITaskGetter interface
-    (getStartDate, getStopDate)
+  def getImmediateExplanationValue():
+    """Returns the delivery of the first parent simulation
+    which has a delivery.
     """
 
-  def getExpectedCompletionDuration(task):
-    """Returns the duration at which the state is expected to be completed,
-    based on the start_date and stop_date of the explanation document.
+  def getExplanationLineValueList():
+    """Returns the list of delivery lines of parent simulation
+    movements. The first item in the list is the immediate
+    explanation value. The last item in the list is the root
+    explanation.
+    """
 
-    'task' is a document which follows the ITaskGetter interface
-    (getStartDate, getStopDate)
+  def getRootExplanationLineValue():
+    """Returns the delivery line of the root simulation
+    movement.
     """
 
-  def getRemainingTradePhaseList(explanation, trade_phase_list=None):
-    """Returns the list of remaining trade phases which to be done on the
-    explanation.
+  def getImmediateExplanationLineValue():
+    """Returns the delivery line of the first parent simulation
+    which has a delivery.
+    """
 
-    trade_phase_list -- if provided, the result is filtered by it after
-                        being collected
+  # Compatibility API
+  def getExplanationUid():
+    """Returns the UID of the root explanation
     """
\ No newline at end of file

product/ERP5/interfaces/simulation_movement.py

@@ -33,9 +33,9 @@ Products.ERP5.interfaces.simulation_movement
 from Products.ERP5.interfaces.property_recordable import IPropertyRecordable
 from Products.ERP5.interfaces.movement import IMovement
 from Products.ERP5.interfaces.divergence_controller import IDivergenceController
-from Products.ERP5.interfaces.business_completable import IBusinessCompletable
+from Products.ERP5.interfaces.explainable import IExplainable
 
-class ISimulationMovement(IMovement, IPropertyRecordable, IDivergenceController, IBusinessCompletable):
+class ISimulationMovement(IMovement, IPropertyRecordable, IDivergenceController, IExplainable):
   """Simulation Movement interface specification
 
   The ISimulationMovement interface introduces in addition
@@ -82,15 +82,42 @@ class ISimulationMovement(IMovement, IPropertyRecordable, IDivergenceController,
     """
 
   def getDeliveryQuantity():
-    """
-    Returns quantity which was actually shipped, taking
+    """ Returns quantity which was actually shipped, taking
     into account the errors of the simulation fixed by
     the delivery:
+
        quantity + delivery_error
     """
 
   def isDeletable():
+    """Returns True if this simulation movement can be deleted, False
+    else. A simulation movement can be deleted if all its children
+    can be deleted of if it has no child.
+    """
+
+  def isCompleted():
+    """Returns True if the simulation state of this simulation movement
+    is considered as completed by the business path which this simulation 
+    movement relates to through causality base category.
+
+    NOTE: simulation movements can be completed (ex. in started state) but
+    not yet frozen (ex. in delivered state). This is the case for example
+    of accounting movements which are completed as soon as they are posted 
+    (to allow next steps in the business process) but can still be modified
+    are thus not yet frozen.
     """
-    Returns True is this simumlation can be deleted, False
-    else.
+
+  def isFrozen():
+    """Returns True if the simulation state of this simulation movement
+    is considered as frozen by the business path which this simulation 
+    movement relates to through causality base category.
+
+    Frozen means that simulation movement cannot be modified anylonger.
+
+    NOTE: simulation movements can be frozen (ex. in stopped state) but
+    not yet completed (ex. in delivered state). This is the case of 
+    sales purchase movements which are frozen as soon they are received
+    because they should not be modified any longer but are only completed
+    once some extra steps bring them to delivered state, thus allowing the
+    generation of planned purchase invoice.
     """