feat: add app db schema extension, for CoreUser

need a way to map Wutta User to CORE Employee for auth purposes

docs/api/wutta_corepos.db.model.rst

@@ -0,0 +1,6 @@
+
+``wutta_corepos.db.model``
+==========================
+
+.. automodule:: wutta_corepos.db.model
+   :members:

docs/api/wutta_corepos.db.rst

@@ -0,0 +1,6 @@
+
+``wutta_corepos.db``
+====================
+
+.. automodule:: wutta_corepos.db
+   :members:

docs/index.rst

@@ -5,8 +5,15 @@ Wutta-COREPOS
 This package adds basic integration with `CORE-POS`_, using
 `pyCOREPOS`_.
 
-Its main purpose is to setup DB connections for CORE Office, but it
-also contains basic readonly web views for some CORE tables.
+It provides the following:
+
+* standard configuration for CORE Office + Lane databases
+* special :term:`handler` for CORE integration
+  (:class:`~wutta_corepos.handler.CoreposHandler`)
+* readonly web views for primary CORE Office DB tables
+* :term:`data model` extension to map
+  :class:`~wuttjamaican:wuttjamaican.db.model.auth.User` to CORE
+  Employee
 
 .. _CORE-POS: https://www.core-pos.com/
 
@@ -26,6 +33,8 @@ also contains basic readonly web views for some CORE tables.
    api/wutta_corepos
    api/wutta_corepos.app
    api/wutta_corepos.conf
+   api/wutta_corepos.db
+   api/wutta_corepos.db.model
    api/wutta_corepos.handler
    api/wutta_corepos.web
    api/wutta_corepos.web.db

docs/narr/install.rst

@@ -39,3 +39,47 @@ related settings.
    02.url = mysql+mysqlconnector://lane02/translog
 
 And that's it, the CORE-POS integration is configured.
+
+
+Schema Extension
+----------------
+
+As of writing the only reason to add the schema extension is if you
+need to map Wutta Users to CORE Employees, for auth (login) purposes.
+So this section can be skipped if you do not need that.
+
+This will effectively add the
+:attr:`~wutta_corepos.db.model.CoreUser.corepos_employee_number`
+attribute on the
+:class:`~wuttjamaican:wuttjamaican.db.model.auth.User` model.
+
+First you must override the :term:`app model` with your own.  To do
+this, create your own module (e.g. ``poser.db.model``) to contain::
+
+   from wuttjamaican.db.model import *
+   from wutta_corepos.db.model import *
+
+Then configure your app model to override the default:
+
+.. code-block:: ini
+
+   [wutta]
+   model_spec = poser.db.model
+
+Then configure the Alembic section for schema migrations:
+
+.. code-block:: ini
+
+   [alembic]
+   script_location = wuttjamaican.db:alembic
+   version_locations = wutta_corepos.db:alembic/versions wuttjamaican.db:alembic/versions
+
+And finally run the Alembic command to migrate:
+
+.. code-block:: sh
+
+   cd /path/to/env
+   bin/alembic -c app/wutta.conf upgrade heads
+
+That should do it, from then on any changes will be migrated
+automatically during upgrade.