Add more docs for Feature Layer

not complete, but progress..

docs/features/people/entry/batches.rst

@@ -0,0 +1,36 @@
+
+Batches
+=======
+
+Batches are a sort of hybrid of import/edit/export.  They assume a
+certain "data set" will be brought into a dedicated workspace, using
+whatever (sometimes custom) logic, then the user previews the
+"results" before committing to it.  See also :doc:`/data/batch/index`.
+
+For instance one common type of batch is for new Customer entry.
+Maybe there is a web form which some users fill out to enter new
+Customer records, but in fact those go into a "queue" / batch and are
+not truly injected to the system proper until the batch is reviewed
+and executed by some (possibly more highly authorized) user.  This can
+be helpful not only for workflow optimization but also custom data
+validation, and/or preventing duplicates from entering the system.
+
+Another type might be for a periodic import to "sync" 2 systems which
+do not normally stay in sync.  For instance if your POS and CRM do not
+stay in sync all the time, but maybe once a month you export the data
+from one system to Excel file, for import to the other.  It is of
+course possible to make a Rattail "importer" (or "exporter" depending
+on your perspective) which could automate this.  But for sake of
+better visibility and instilling confidence in the logic, you might
+prefer a batch.
+
+In the above example the process might be like:
+
+* export data from CRM to Excel
+* upload file as new batch in Rattail
+* preview the changes; execute the batch
+* which generates yet another file, e.g. CSV
+* which you then import to the POS
+
+There are many possibilities here; for instance more likely the batch
+writes directly to POS when executed.

docs/features/people/entry/editing.rst

@@ -0,0 +1,32 @@
+
+Editing
+=======
+
+Rattail makes it possible to edit most data it contains regardless of
+its nature.  This of course includes Person-related data.
+
+However just because you *can* edit data in Rattail, does not mean you
+*should* do so.  You must keep in mind, "which system is the
+authority?" for any given data point.
+
+In other words if you import Customer records from your POS, but then
+do not configure an export mechanism to get any changes made in
+Rattail *back* into the POS system, then by far the easiest thing is
+to just not allow editing in Rattail.  But you still can view the
+data, and use various app features which leverage the data (e.g.
+:doc:`../../custorders/index`).
+
+However if you *do* configure export mechanisms then you may want to
+allow editing directly in Rattail.  This can be any data point which
+is supported by the export mechanism.  For instance if you allow
+editing of a Customer name in Rattail, the change could be synced back
+to POS.
+
+But it's also possible for Rattail to contain "more" data than the
+source (e.g. POS) system does.  For instance your POS DB may have a
+field to track the "birthday" for each Customer, but maybe you also
+need to track their "favorite color" and the POS DB does not provide a
+way to do that.  In this case you can import Customer records from POS
+into Rattail, and then allow editing in Rattail only for the "favorite
+color" field.  Best of both worlds, you can now track whatever you
+want with no need to export data back to the source system.

docs/features/people/entry/exporting.rst

@@ -0,0 +1,42 @@
+
+Exporting
+=========
+
+Once you have Person-related data in Rattail, you can export it
+"anywhere else" you need.  This may be an Excel file, SQL DB, web API
+etc. but for the sake of this discussion we'll assume data is to be
+exported back to the POS system.
+
+In fact the export features do not require you to first import the
+data to Rattail.  Every export that could be done "from Rattail DB"
+could also be done e.g. "from POS DB".  For instance that's exactly
+what happens when data is imported from the POS into Rattail, it is
+just another way of saying "export from POS to Rattail" and therefore
+you can export straight from your POS to e.g. some web API for mailing
+list or online shopping etc.
+
+An export is "reading" data from e.g. Rattail or POS DB, and then
+"writing" it somewhere else.  The reading part is pretty
+straightforward but the writing part may have limitations depending on
+your target.  As a rule Rattail is willing to read directly from a SQL
+DB but will always write data via some more "official" route,
+i.e. documented API.  Which means the writing "possibilities" are
+limited to what the API exposes.  Whereas exporting to e.g. Excel file
+would not have such a limitation, but may have others (e.g. file
+size).
+
+So how is data exported back to the POS specifically, for example?
+That definitely will depend on your POS system, and as of writing only
+3 are well supported.
+
+If you're lucky enough to run a SIL-compliant POS then a great deal is
+possible; Rattail can generate SIL files which add/modify data of
+nearly any kind.
+
+If your POS exposes a web API then Rattail can use that to write some
+data.  At this point in time these are rather limited though.
+
+If writing directly to POS SQL DB is an option for you, then Rattail
+can certainly accommodate.  It should be stressed that this is **not
+ideal** as it would likely bypass any data validation, audit trail
+etc. that the POS may be doing were an official channel used instead.

docs/features/people/entry/importing.rst

@@ -0,0 +1,27 @@
+
+Importing
+=========
+
+The most common scenario involves Rattail importing most
+Person-related data from other (e.g. POS or CRM) systems.
+
+However it should be noted that Rattail is meant to live "alongside"
+the other systems, it is not normally going to "replace" them - and
+this means Rattail must *continually* import data from the other
+systems, to remain accurate.  This may be done nightly, or hourly, or
+even in "real-time" (e.g. once every few seconds, or 5 minutes) -
+whatever is needed and/or is possible given the system constraints.
+
+One immediate feature that comes "for free" when importing data into
+Rattail, is its versioning history, aka. audit trail.  Each time an
+import actually *changes* a record in Rattail, the new data is
+separately stored as a "version" record along with the timestamp and
+the "user" who made the change.  In the case of import, the "user" is
+the system from which data is being imported; a dedicated User account
+is created for this purpose (which does not tie back to any Person).
+
+We're talking here of importing data from e.g. POS into Rattail.  But
+if it's also possible to "import" e.g. new Customer records into your
+POS or other system, then Rattail can also be used as a workflow tool
+to assist with organizing new records for import to your other system.
+See :doc:`batches` for more about that.

docs/features/people/entry/index.rst

@@ -0,0 +1,16 @@
+
+Entry
+=====
+
+Here we'll discuss how various Person-related records are first
+entered into the system, and how they are maintained going forward.
+
+.. toctree::
+   :maxdepth: 1
+
+   overview
+   importing
+   editing
+   exporting
+   batches
+   merging

docs/features/people/entry/merging.rst

@@ -0,0 +1,44 @@
+
+Merging
+=======
+
+Rattail ostensibly supports merging any 2 records, of any kind.  But
+the devil is always in the details...
+
+In most cases a merge involves:
+
+* inspect differences between 2 records
+* choose which one to "keep" vs. "remove"
+* perform the merge, which:
+
+ * may *update* the "keep" record, with certain data from the "remove" record
+ * then *deletes* the "remove" record
+
+For some things this can be pretty straightforward, for instance if
+your User records are maintained only in Rattail and aren't imported
+from elsewhere, then a merge of 2 User records could by definition
+only affect Rattail anyway.
+
+Although even that example can be tricky, because a User is often
+involved in some audit trail(s) of various other data records.  In
+such cases Rattail can update the historical records to reflect the
+new "keep" User record; but in practice there may be edge cases as yet
+unexplored.
+
+Customer and Employee records etc. can present more of a challenge,
+because often that data lives in multiple systems.  The question
+becomes, what should a merge actually *do*, i.e. what should the
+ideal outcome be?
+
+In particular your POS may have 2 customer records which you'd like to
+merge, but even if your ideal outcome is for one of them to be deleted
+(i.e. typical use case described above), the problem of historical
+data may come up again.  Often times both of the customer records will
+already have accrued some transaction history within your POS, and it
+may not be possible or practical to correct those with the new
+("keep") customer reference.
+
+But the merge tool is meant to be as flexible as is reasonable.  Your
+merge logic might be able to go ahead with certain "simple" merges but
+then raise an error when complex situations are encountered.  Then you
+can look more closely at those and see what can be done (if anything).

docs/features/people/entry/overview.rst

@@ -0,0 +1,32 @@
+
+Overview
+========
+
+In most cases the Person-related data already lives in a (e.g. POS)
+SQL database and may be queried directly by Rattail.  This means you
+may view that data directly in the web app.
+
+All of the Person-related records may also be *imported* into Rattail
+from other systems, and this is usually the best place to get started;
+see :doc:`importing`.
+
+Once the data lives in Rattail you obviously may view it within the
+web app (so, reading from Rattail DB instead of POS DB now).  But this
+also sets the stage for other features which require such data to be
+in place; for instance :doc:`../../custorders/index`.
+
+You also may want to allow editing for some or perhaps all aspects;
+see :doc:`editing`.
+
+The data (and any changes made via editing, if applicable) may also be
+exported back to the source and/or other systems; see
+:doc:`exporting`.
+
+Sometimes you need to process a "set" of data, for instance taking an
+export file from one system and then preparing it for import to
+another system.  This is a broad topic; for a starting point see
+:doc:`batches`.
+
+Duplicate records are an ongoing problem in many systems, when it
+comes to Person-related data.  Rattail does allow merging of 2 records
+but it can be tricky; see :doc:`merging`.