From 76cb5ba4c7b257d1f4e672488c02a23cc89fdf93 Mon Sep 17 00:00:00 2001 From: Petr Baudis Date: Sun, 10 Feb 2013 16:18:34 +0100 Subject: [PATCH] Add basic documentation: README, INSTALL, Architectural overview --- brmbar3/INSTALL.md | 67 +++++++++++++++++++++++ brmbar3/README.md | 71 ++++++++++++++++++++++++ brmbar3/doc/architecture.md | 106 ++++++++++++++++++++++++++++++++++++ 3 files changed, 244 insertions(+) create mode 100644 brmbar3/INSTALL.md create mode 100644 brmbar3/README.md create mode 100644 brmbar3/doc/architecture.md diff --git a/brmbar3/INSTALL.md b/brmbar3/INSTALL.md new file mode 100644 index 0000000..cdff5c4 --- /dev/null +++ b/brmbar3/INSTALL.md @@ -0,0 +1,67 @@ +BrmBar v3 Installation +====================== + +This is woefully incomplete; if you are deploying BrmBar, at this +point you will likely need to learn at least something aobut its +structure and internals. Some code modifications might even be +required too. Patches enhancing user configurability are welcome! + +Maybe some things are missing. Ask the developers if you get in trouble, +e.g. in #brmlab on FreeNode. + +Hardware Requirements +--------------------- + +* Display. Current UI is optimized for 4:3, 1024x768 display. +* Touchscreen. In emergency, you can use a mouse too, but it's + clumsy and scrolling is not too intuitive. +* Barcode reader. We want the kind that will behave as a HID device + and on scanning a barcode, it will send a CR-terminated scanned string. +* Physical keyboard stashed in vicinity will help. It is possible + to enter text (inventory names, receipt reasons) on the touchscreen, + but it's a bit frustrating. +* You will want to print a sheet of barcodes with names of all user + accounts; these will be then used by people to buy stuff using their + accounts - first scan barcode of the item, then scan your barcode, + voila. Scanning your barcode directly can bring the user to a screen + where they can see their credit and charge it too. + +Software Requirements +--------------------- + +* Developed and tested on Debian, but should work on other systems too. +* Python 3. +* QT4 with Python bindings: + * QT4 with the "Declarative" module, e.g. libqt4-declarative package. + * The PySide Qt4 bindings, e.g. python3-pyside.qtdeclarative package. + * Installing the qtcreator program may be helpful for QML testing + and development. +* PostgreSQL with Python pindings: + * The database server itself, e.g. postgresql package. + * PsyCoPg2, e.g. python3-psycopg2 package. + +Software Setup +-------------- + +* Create psql user and `brmbar` database. +* The SQL schema in file `SQL` contains the required SQL tables, + but also INSERTs that add some rows essential for proper operation; + base currency and two base accounts. You *will* want to tweak the + currency name; default is `Kč` (the Czech crown), replace it with + your currency symbol. Then do `git grep 'Kč'` and replace all other + occurences of `Kč` in brmbar source with your currency name. +* Load the SQL schema stored in file `SQL` in the database (redirect + it to psql command standard input). +* You should be able to fire up the GUI now and start entering data. + If you want to make sure all works as expected, execute the SQL + statements in file `SQL.test` (revisit for currency names too) which + will populate the database with a bit of sample data for testing. + +TODO: Mention the actual commands to execute. + +Troubleshooting +--------------- + +Assuming that you run brmbar from a terminal, if something gets +stuck, you can switch to the terminal by Alt-TAB, then kill brmbar +by the Ctrl-\ shortcut (sends SIGQUIT) and restart it. diff --git a/brmbar3/README.md b/brmbar3/README.md new file mode 100644 index 0000000..4972c42 --- /dev/null +++ b/brmbar3/README.md @@ -0,0 +1,71 @@ +BrmBar v3 +========= + +BrmBar is a management system for running a tiny hackerspace shop +with self-service usage based on trust and support for user accounts +and inventory tracking. + +BrmBar offers a touchscreen-based user interface, identifies items +and users by barcodes scanned by a barcode reader, should run on any +decent Linux machine and stores its data in PostgreSQL database. + +Features +-------- + +* Very simple user interface (using big touchscreen buttons and + barcode reader) that should enable even non-technical users to + do basic shopping with little to no training. +* Users may have their accounts they can load with money by + depositing larger sum of money in advance, then charging their + account when buying stuff. Of course, paying direct for cash + is also supported. +* Inventory and cash accounts are tracked so that you can make sure + there is no Club Mate mysteriously disappearing or if the amount + of cash in the cash box is not less than expected by the system. +* You can enter receipts for duct tapes and other necessities to be + financed by cash surplus generated by brmbar. +* Simple management operations (depositing and withdrawing money + from user accounts, entering receipts, stocking in new inventory) + can be also performed in the user interface even by non-technical + users with basic training. +* The database is based on the classical accounting paradigm. + This means no information is needlessly lost, you could even + make a GNUCash export and your accounting geeks will feel warm + and fuzzy. +* Multiple user interfaces available (and possible). The primary + user interface is based on QtQuick (Qt4 QML QtDeclarative). + +User Interfaces +--------------- + +These UIs are provided: + +* **brmbar-gui-qt4**: The default touchscreen-based UI. The Python side + provides an adapter object whose methods can be executed by the QML + code; ad-hoc directionary objects are used to exchange complex data + like account information. +* **brmbar-tui**: A trivial text-based "shell" UI that mimics a historic + interface used in the Brmlab hackerspace in the past. It supports only + selling items, querying item price and user account balance and + depositing money for the user accounts. +* **brmbar-cli**: A command-line interface intended for use in scripts + and remote usage when fixing problems. It is also meant to provide + advanced functionality like inventory revision that is too tedious + to implement in the Qt4 GUI and only the brmbar admins are expected + to do these tasks. + +TODO +---- + +* The user interface needs some improvements, mainly regarding + scrolling in large lists. +* The brmbar-cli.py admin script for advanced/remote management + operations is largely unfinished. In the meantime, you need to use + SQL statements, sorry. Or finish it yourself. :-) +* It is common to have two stashes of cash, one in a cash box + in the shop, another in a vault (sometimes called "overflow") + where extra cash is stored. The brmbar model supports this, + but UI support needs to be added. +* Bitcoin support, somehow... + +Some more TODO items may be listed in the GitHub issue tracker. diff --git a/brmbar3/doc/architecture.md b/brmbar3/doc/architecture.md new file mode 100644 index 0000000..791517f --- /dev/null +++ b/brmbar3/doc/architecture.md @@ -0,0 +1,106 @@ +BrmBar v3 - Architectural Overview +================================== + +BrmBar v3 is written in Python, with the database stored in PostgreSQL +and the primary user interface modelled in QtQuick. All user interfaces +share a common *brmbar* package that provides few Python classes for +manipulation with the base objects. + +Objects and Database Schema +--------------------------- + +### Account ### + +The most essential brmbar object is an Account, which can track +balances of various kinds (described by *acctype* column) in the +classical accounting paradigm: + +* **Cash**: A physical stash of cash. One cash account is created + by default, corresponding to the cash box where people put money + when buying stuff (or depositing money in their user accounts). + Often, that's the only cash account you need. +* **Debt**: Represents brmbar's debt to some person. These accounts + are actually the "user accounts" where people deposit money. When + a deposit of 100 is made, 100 is *subtracted* from the balance, + the balance is -100 and brmbar is in debt of 100 to the user. + When the user buys something for 200, 200 is *added* to the balance, + the balance is 100 and the user is in debt of 100 to the brmbar. + This is correct notation from accounting point of view, but somewhat + confusing for the users, so in the user interface (and crbalance + column of some views), this balance is *negated*! +* **Inventory**: Represents inventory items (e.g. Club Mate bottles). + The account balance represents the quantity of items. +* **Income**: Represents pure income of brmbar, i.e. the profit; + there is usually just a single account of this type where all the + profit (sell price of an item minus the buy price of an item) + is accumulated. +* **Expense**: This type is currently not used. +* **Starting balance** and **ending balance**: This may be used + in the future when transaction book needs to be compressed. + +As you can see, the amount of cash, user accounts, inventory items +etc. are all represented as **Account** objects that are of various +**types**, are **named** and have a certain balance (calculated +from a transaction book). That balance is a number represented +in certain **currency**. It also has a set of **barcodes** associated. + +### Currency, Exchange rate ### + +Usually, all accounts that deal with cash (the cash, debt, income, ... +accounts) share a single currency that corresponds to the physical +currency locally in use (the default is `Kč`). However, inventory +items have balances corresponding to item quantities - to deal with +this correctly, each inventory item *has its own currency*; i.e. +`Club Mate` bottle is a currency associated with the `Club Mate` +account. + +Currencies have defined (uni-directional) exchange rates. The exchange +rate of "Kč to Club Mate bottles" is the buy price of Club Mate, how +much you pay for one bottle of Club Mate from the cash box when you +are stocking in Club Mate. The exchange rate of "Club Mate bottle to Kč" +is the sell price of Club Mate, how much you pay for one bottle of Club +Mate to the cash box when you are buying it from brmbar (sell price +should be higher than buy price if you want to make a profit). + +Exchange rate is valid since some defined time; historical exchange +rates are therefore kept and this allows to account for changing prices +of inventory items. (Unfortunately, at the time of writing this, the +profit calculation actually didn't make use of that yet.) + +### Transactions, Transaction splits ### + +A transaction book is used to determine current account balances and +stores all operations related to accounts - depositing or withdrawing +money, stocking in items, and most importantly buying stuff (either for +cash or from a debt account). A transaction happenned at some **time** +and was performed by certain **responsible** person. + +The actual accounts involved in a transaction are specified by a list of +transaction splits that either put balance into the transaction (*credit* +side) or grab balance from it (*debit* side). For example, a typical +transaction representing a sale of Club Mate bottle to user "pasky" +would be split like this: + +* *credit* of 1 Club Mate on Club Mate account with memo "pasky". +* *debit* of 35 Kč on "pasky" account with memo "Club Mate" + (indeed we _add_ 35Kč to the debt account for pasky buying + the Club Mate; if this seems weird, refer to the "debt" account + type description). +* *debit* of 5 Kč on income account Profits with memo "Margin + on Club Mate" (this represents the sale price - buy price delta, + i.e. the profit we made in brmbar by selling this Club Mate). + +The brmbar Python Package +------------------------- + +The **brmbar** package (in brmbar/ subdirectory) provides common brmbar +functionality for the various user interfaces: + +* **Database**: Layer for performing SQL queries with some error handling. +* **Currency**: Class for querying and manipulating currency objects and + converting between them based on stored exchange rates. +* **Account**: Class for querying and manipulating the account objects + and their current balance. +* **Shop**: Class providing the "business logic" of all the actual user + operations: selling stuff, depositing and withdrawing moeny, adding + stock, retrieving list of accounts of given type, etc.