Add more docs for Feature Layer

not complete, but progress..

docs/features/people/customers/index.rst

@@ -0,0 +1,64 @@
+
+Customers
+=========
+
+In many cases it's best for Customer data to live in Rattail (usually
+in addition to POS, which is considered the authority).  But possibly
+not, so let's first look at *why* you might want/need to have it in
+Rattail.
+
+And quickly even before that, let's just say that we're defining a
+"Customer" simply as a "patron" (shopper) of the retailer.  In some
+cases Customer data is held not only in POS but also in a separate CRM
+system, etc.  Your own definition of "Customer" is free to vary a bit
+in terms of how you must represent real-world concerns.
+
+If your POS does not expose a web app, then often there will only be a
+few machines which can be used for account lookup etc.  Rattail web
+app can let you view this data directly (if it can be accessed via
+SQL), i.e. *without* importing it to Rattail.  However such
+"dedicated" views for various tables in other systems are not given a
+lot of priority in terms of aesthetic or utility.
+
+Importing the data to Rattail means the web app can show you the data
+in (hopefully) the "best" way.  That's obviously a loaded term but
+what is meant here, is that the views for native Rattail data are
+given the most attention and are what various other features are built
+on top of.
+
+So if we assume you *are* importing Customer data into Rattail, then
+what?  You can view it, but can/should you edit it?  That again
+depends on whether or not you can (or how difficult it is to) export
+the changes back to the source (or other) systems.  It's *possible*
+for instance, to allow edits in Rattail web app, which then are
+automatically synced back to the POS in real-time (by a separate
+datasync daemon process).  But that is a more advanced topic, and in
+most cases, at least in the beginning, you should only edit data in
+one system, which likely is *not* Rattail.
+
+If you want to track *extra* data for Customer records in Rattail,
+then things change again.  You *would* (probably) want to import the
+data to Rattail, *not* allow edit for that particular data, but then
+*do* allow edit for only the "extra" fields.  With this approach you
+get to start tracking that data while avoiding the need to export
+anything back to POS etc.  Reports can be created in Rattail which
+leverage data from both systems.
+
+And speaking of "extra data" - that is essentially what is happening
+with the Customer Orders feature in Rattail.  Underlying it is the
+Customer record itself, which was likely imported from POS, but then
+when an order is created, that is just extra data on top which never
+needs to be synced back to the POS.  See also
+:doc:`../../custorders/index`.
+
+Finally again there is the concept of :doc:`../entry/batches`.  In
+fact when creating a new Customer Order, really you are creating a
+batch and then adding items to it, finally "executing" which submits
+the order for further processing.  But batch logic can be crafted to
+do anything you need with regard to Customer data maintenance.  And in
+some cases a Customer-related batch may be more "accurate" if it does
+*not* use Rattail data but instead reads directly from the source
+(e.g. POS) when making the batch.  Also a "New Customers" batch by
+definition would contain data not yet "in the system" - so importing
+the data to Rattail is not a requirement in order to use batch
+features generally.

docs/features/people/employees/index.rst

@@ -0,0 +1,32 @@
+
+Employees
+=========
+
+Employee data normally comes from the POS, if it indeed comes into
+play at all.  You may or may not have a reason to import or otherwise
+act on Employee data using Rattail.
+
+It is the User record in Rattail which is given attribution for
+changes made etc. and not the Employee.  So even if a certain User is
+also an Employee, when logged in and making changes their User account
+is deemed responsible.
+
+Whereas a User record does not technically need to tie back to a
+Person record, an Employee record *must* tie back to a Person.  When
+importing Employee data from POS, both the Person and Employee records
+are created in Rattail.
+
+There are certain places where an Employee *is* assumed, for instance
+the "Buyer" of a Purchase Order will reference an Employee record and
+not a User.  Whereas the creation and execution of a "batch" related
+to purchasing will reference a User.  (See also
+:doc:`../../purchasing/index`.)
+
+Rattail could also be used as a "time clock" system in which case the
+Employee records must obviously be present, for tracking times.
+
+You also can use Rattail to track additional info for each Employee,
+e.g. the start/end dates for their employment over time.  Often an
+employee might come and go more than once, and the POS will rarely
+have a way to track historical dates.  Rattail has a basic way to do
+that built-in, but more "data extensions" are of course possible.

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`.

docs/features/people/household/index.rst

@@ -0,0 +1,53 @@
+
+Household / Shared Accounts
+===========================
+
+A common scenario is where a Customer (or Employee, or Member) is able
+to "share" benefits of their account, with their immediate household.
+There may be other variations but we'll stick with that example here.
+
+Although to clarify, while many e.g. retail food co-ops may consider
+the "Household" concept to be an extension of a "Member" account
+specifically, Rattail instead considers it a logical extension of the
+"Customer" account.  This is because the benefits which are extended
+to the household normally apply to "shopping" specifically, and
+Rattail uses the "Customer" concept to represent that.  (Same holds
+true for a more traditional retailer which might extend benefits to
+the Household of an Employee - the Household will still fall under a
+Customer account logically.)
+
+So it might be possible for Rattail to add a broader / more generic
+"Household" concept later, but for now it's all about Customers.  (And
+a Member account is normally tied to a Customer account, so it's not
+much more than a difference of semantics.)
+
+Okay! With that out of the way...
+
+Household accounts can be tricky.  For instance are these people
+actually tracked in your system?  (Do they need to be?)  If so are
+they tracked as separate accounts or just minimal (e.g. name) info
+somehow tacked onto the main account?  In particular how are the
+accounts represented in your POS system?
+
+Rattail can be used to help track e.g. Household-related links between
+various Person and/or Customer records.  What you do with such links
+is up to you of course, but some ideas:
+
+If your POS allows for it, you might have Rattail keep the POS in sync
+for (at least certain types of) changes to Household-related accounts.
+For instance in the dynamic coupon scenario, let's say you do maintain
+separate POS accounts for the "parent" Customer as well as the
+Household "shopper".  When a coupon is given it may be enabled for
+both of the accounts, but then when it is redeemed by either it
+becomes disabled for both.
+
+Now, maybe your POS already has a way to link Household accounts, and
+even a way to handle the dynamic coupon example.  But then that sounds
+like you already have a good enough system and don't need Rattail to
+be the Household "system" at all.  Although it could still be used for
+reporting and similar needs, etc.
+
+So if your current situation is "not ideal" then Rattail is here to
+help in whatever way it can; however it's difficult to describe the
+scenarios it might best be suited for, until more real-world scenarios
+are dealt with.

docs/features/people/index.rst

@@ -0,0 +1,22 @@
+
+People
+======
+
+Rattail considers the Person to be a central concept, which underpins
+various other concepts such as User, Customer etc. and ideally ties
+them together (e.g. one Person may be both a Customer and Employee).
+
+Rattail can import this data from other (e.g. POS) systems, but it
+also can *export* data to other systems.  And once this data is in
+Rattail it can be used for other features as needed; for instance
+:doc:`../custorders/index`.
+
+.. toctree::
+   :maxdepth: 2
+
+   entry/index
+   users/index
+   employees/index
+   customers/index
+   members/index
+   household/index

docs/features/people/members/index.rst

@@ -0,0 +1,80 @@
+
+Members
+=======
+
+As with Employee and Customer data, the first questions regarding
+Member data are: What is it, and what does it have to do with Rattail?
+
+Rattail's concept of a "Member" comes primarily from the world of
+retail food co-ops, where a Member is more like a Customer than an
+Employee.  But there exist also worker co-ops, where a Member is
+really more like an Employee.  Rattail's Member features are meant to
+acommodate both scenarios.
+
+Members often have some equity account associated with them, with join
+and (where applicable) withdrawal dates, and usually also a payment
+history for the equity.
+
+So if your organization has a membership component, then you most
+likely already have some way to track accounts and equity etc.  Why
+bring it into Rattail?
+
+As usual the first answer is simple visibility.  For instance you
+might be tracking accounts in a spreadsheet or Microsoft Access, or
+any of a number of similar "undesirable" solutions.  Even if you
+continue with that tracking approach, you also could periodically
+import data to Rattail just so it can be more easily viewed by others
+via the web app.
+
+And part of visibility is cross-referencing related data.  Maybe you
+already have a good way to view accounts, but you have no way to view
+an account alongside its equity, or perhaps POS Transaction history
+etc.  Showing the various types of data on one screen (maybe with a
+link back to the other system) can be quite helpful in some cases.
+
+Another potential feature is to send email reminders to Members who
+have an upcoming payment due, etc. based on their account details.
+And it's possible to monitor an IMAP folder for any "bounces" that
+result from sending such reminders, in which case can e.g. flag the
+account as having a bad email on file.
+
+Similarly a Member account status may dynamically affect which
+discounts are available to their Customer account at the POS.  This
+idea depends on the ability to effect certain changes in the POS
+system, e.g. add/remove electronic coupons for an account.
+
+But..everything just stated is technically possible *without*
+importing the data to Rattail.  So still at this point we've not
+established a good reason to actually import it.
+
+You can of course create batches for performing account maintenance in
+whatever way is needed.  Same general "rules" apply as for other
+(e.g. Customer) tables.  Member data need not be imported into Rattail
+in order to use the batch features.
+
+But unlike the Customer data, where the POS is frequently the obvious
+"authority", many times Member data is *not* tracked (well) by the
+POS, and so custom spreadsheet workflows or similar tactics are
+employed to keep track of it.
+
+So this finally is why you *might* want to import it into Rattail.
+Any tasks being managed via spreadsheet workflows (or whatever) can
+instead be managed directly in the web app.
+
+If you choose this route, a couple of implications:
+
+Rattail becomes your primary Member system, and you (presumably /
+ideally) no longer need your previous system for that, other than to
+keep it as an archive.
+
+Data is maintained directly in the web app, for instance creating a
+new Member account, or withdrawing one etc.  Also equity payments
+could be entered directly if they happen outside of the POS, e.g. when
+someone mails a check.
+
+But equity payments still likely will happen in the POS also.  And for
+this to work "seamlessly" it means Rattail must monitor the POS
+Transactions which occur, at whatever frequency is acceptable.  Near
+real-time is possible and in some cases necessary for sake of dynamic
+coupons etc.  But in other cases a nightly processing of the previous
+day's transactions may be sufficient.

docs/features/people/users/index.rst

@@ -0,0 +1,39 @@
+
+Users
+=====
+
+Users are a bit unique in the realm of Person-related data, because
+it's often the case that they are *not* imported from some other
+system, being instead maintained only in Rattail.  (Of course it *is*
+still possible to import User records from another system.)
+
+When you first setup a Rattail system you create the first "admin"
+User.  You then login as that User and can create other Users as
+needed, depending on who needs access.  For more info see also
+:doc:`/data/auth`.
+
+It's possible to tie a User record to a Person record, although
+technically not required.  It is recommended since it opens up other
+possibilities, for instance the app might present different features
+based on some other related aspects e.g. of the Employee record of the
+current User.
+
+It's also common to create dedicated User accounts to represent the
+other systems involved, e.g. your POS.  Such accounts do not tie back
+to any Person and exist only for sake of attributing changes to the
+applicable system, when data is imported to Rattail.
+
+The username for each User must be unique.  Passwords are stored using
+1-way encryption, so are not recoverable and must be reset if lost.
+
+It is possible to authenticate users against something other than
+Rattail, instead of or in addition to normal Rattail authentication.
+For instance it can check LDAP, or a corresponding employee table in
+your POS DB (e.g. if those credentials are stored as plain text).
+
+It is also possible for Rattail to auto-create users upon first login,
+if authenticating from another system like that.  If your permissions
+are setup such that *any* "authenticated" (i.e. logged in) user has
+access to certain features, this may be a useful option for you.  In
+some cases you may also need to add logic to auto-assign the
+newly-created user to some particular role(s) based on whatever...