mini-shop-server: a Flask backend for a WeChat mini program shop, with RBAC and generated API docs

What the project is and who it is for

mini-shop-server is a WeChat mini program shop backend built on Flask. The README describes it as a complete, reliable and extensible e-commerce backend solution for small and medium businesses and for developers, and the repository description notes it can also serve as a Python graduation project.

That second use is worth pausing on, because it explains several things about the project. The documentation is written as a tutorial rather than as a reference, the setup instructions go through installing PostgreSQL and Python from the command line, and the built-in feature list covers the parts of a back-office system that a course would want to demonstrate.

The stack is Python 3.12, Flask 2.0.3, PostgreSQL and SQLAlchemy, with a pyproject.toml that requires Python 3.12 or newer. The development environment is Mac OS and the production environment is Linux Ubuntu 16.04, which is an odd combination to state, and the README credits the course that the project was originally based on.

The features list has eleven entries, and it is a real back-office rather than a thin CRUD API. User management covers user configuration. Permission group or role management handles interface permission assignment and menu permission assignment. Menu management implements back-end configured menu dynamic routing with support for multi-level menus. Dictionary management maintains frequently used lookup data such as gender and status. Parameter management holds system dynamic configuration such as page size and front-end theme colour. Notification management handles system notifications and announcements. Log management keeps operation logs and login logs. Interface documentation is generated from the business code in Swagger style. Error codes define the convention shared between front end and back end. File management and upload handles folders and files. Article management covers articles.

The licence is MIT and the documentation site is allen7d.github.io/mini-shop-docs.

The design decisions the README highlights

Five decisions stand out in the highlights section, and two of them are about the plumbing rather than the features.

The first is that the API is built on native Flask to deliver a RESTful interface, rather than through a framework that generates the API for you. The second is a more flexible API documentation generator that can carry a Token, which matters because the docs are meant to be usable as a console against a live server rather than only as a description.

The third is the use of AOP, aspect-oriented programming, to implement a parameter validation layer and a unified exception handling layer. That is an unusual choice in a Flask project and it is worth understanding what it buys. Flask already has a before_request hook and a blueprint-level error handler, so the aspect approach here is a way of declaring validation and error handling once and having it applied across the endpoints, rather than remembering to register it in each view.

The fourth is package management. The project uses uv in place of pipenv, for faster dependency installation and resolution. That is a recent change, and it is visible everywhere: the uv.lock file at the root, the pyproject.toml with a tool.uv section, and the whole local run procedure written in uv commands rather than pip commands.

The fifth is the deployment: Nginx, Gunicorn and uv on Ubuntu 16.04 and later, which is the standard Python production shape with a reverse proxy in front of a WSGI server.

The README also lists a three-tier separation in its table of contents, but marks it as coming later, not as something already in place. What the repository currently gives you is the back half of a mini program.

Running it with Docker, which is the recommended path

The Docker path is the one the README recommends, and it is a single command.

The Dockerfile, .dockerignore and docker-compose.yml are already in the repository, and the db container runs zerd_pg.sql on first initialisation to create the tables and load the seed data. The quick start is:

$ git clone https://github.com/Allen7D/mini-shop-server.git
$ cd mini-shop-server

$ docker compose up -d --build

After that, docker compose ps should show both the app and db containers as Up. The success marker the README gives is opening http://localhost:8080/apidocs/#/ in a browser and seeing the Swagger interface documentation page, which is a neat way to check the whole stack is working.

The compose file is worth reading for its details. The database is postgres:16-alpine, named mini-shop-db, with restart unless-stopped, a named volume for the data, and the seed script mounted read-only into the docker-entrypoint-initdb.d directory so it runs exactly once on first start. It has a healthcheck using pg_isready against the zerd database with a five second interval and ten retries, and the app service depends on it with the condition service_healthy, so the app waits for the database rather than racing it.

The comment explains why the host's 5432 port is not mapped: to avoid conflicting with a PostgreSQL already running on the machine, with the app reaching the database over the internal compose network at db:5432 instead. The published port is 8080.

The Docker image itself is a python:3.12-slim base with uv installed from PyPI rather than pulled from a uv image, with the reasoning given as more reliable and avoiding occasional download stalls. The dependency manifest is copied before the source so the Docker layer cache survives source changes, and the final command runs Gunicorn with one worker on 0.0.0.0:8080, with a comment that a single worker is enough for quick starts and local demos.

The local path with uv, and the seed data caveat

The manual route starts from the same clone and then builds an environment with uv rather than pip:

$ uv venv --python 3.12           # 创建指定 Python 3.12 版本的虚拟环境
$ uv sync                         # 创建虚拟环境并安装所有依赖
$ uv run python server.py run     # 启动方式1:默认5000端口
$ uv run python server.py run -p 8080                 # 启动方式2:改为8080端口
$ uv run python server.py run -h 0.0.0.0 -p 8080     # 启动方式3:以本地IP地址访问

Three startup modes, on the default port, on an alternative port, and bound to the local interface address for access from other devices. That is a sensible touch for mobile testing, where the mini program on a phone needs to reach a server on your laptop.

The README also documents the uv commands the project uses day to day, including uv sync, uv add with and without a version pin, uv remove, uv run, and activating the environment on both Unix and Windows paths. It also explains installing Python 3.12 itself on a machine that does not have it, using the deadsnakes PPA.

The seed data deserves a warning, and the README is clear about it. The seed data in zerd_pg.sql mainly provides business data, but the old account password hashes in it have expired and cannot be used to log in. For a usable test account you run the generator:

$ uv run python fake.py

The generated accounts are super with 123456 as a super administrator, admin with 123456 as an ordinary administrator, and user with 123456 as an ordinary user. The README also warns that the usernames, email addresses and WeChat openid all have unique constraints, so running fake.py twice raises a unique constraint error and it should be run once.

That last detail is a good example of the seed data being a snapshot of a live system rather than a designed fixture.

Configuration, WeChat integration and the operation surface

The.env.example file shows the configuration surface, and it is short enough to read in one go.

There is the SECRET_KEY, the Flask session secret, which in the example file carries a passage of text rather than a generated value. There is the database URI in the SQLAlchemy form using the pg8000 driver, pointing at localhost:5432 with the database named zerd.

Then the WeChat credentials, in three groups. APP_ID and APP_SECRET are the mini program itself. OPEN_APP_ID, OPEN_APP_SECRET and OPEN_STATE are for the open platform login. ACCOUNT_APP_ID and ACCOUNT_APP_SECRET are for the official account service login. The file states that system environment variables take priority over the.env file, and that.env is in.gitignore and must never be committed.

The fact that there are three separate WeChat login paths is a detail specific to the Chinese platform ecosystem, where a mini program, an open platform account and a service account are different applications with different credential sets.

The pyproject.toml pins the rest of the stack. Flask 2.0.3 with Werkzeug 2.0.3 and Jinja2 3.1.6, Flask-SQLAlchemy 2.5.1 on SQLAlchemy 1.4.46, flask-httpauth 4.7.0 and flask-wtf 1.1.1 for the authentication and form layers, flask-cors 3.0.10 for cross-origin access, wechatpy 1.8.18 for the WeChat API, gunicorn 21.2.0 for production serving, cachelib 0.10.2, itsdangerous 2.0.1, psutil 5.9.6, email-validator 2.1.0, qiniu 7.12.1 for object storage, requests 2.31.0 and python-dotenv 1.0.1.

The optional dev group is where the documentation tooling lives: flasgger 0.9.7.1 for the Swagger-style documentation, flask-admin 1.6.1 for an admin interface, pytest 7.4.3 and pylint 3.0.3. The Dockerfile notes that flasgger and flask-admin sit in the dev group, which is why the default uv sync installs them as well.

The console entry point is mini-shop-server mapped to server:main, the version is read dynamically from app/__init__.py through the [tool.hatch.version] path, and the build backend is hatchling with the app package included in the wheel.

Limits: a fixed stack, committed credentials and an unfinished front end

The limits are worth naming precisely, because several of them are the kind of thing you discover in a deployment rather than in a review.

The first is the committed credentials. The.env.example file contains a SECRET_KEY with an actual value in it, the database password is postgres123 in the compose file and the same in the example URI, and the docker-compose environment sets SECRET_KEY to docker-quick-start-secret-key. These are placeholders and are obviously meant to be replaced, but they are in the repository, and a deployment that copies the compose file unchanged is running with a known session secret.

The second is the version floor. Flask is pinned to 2.0.3, which is a long way behind current Flask, and Flask-SQLAlchemy 2.5.1 sits on SQLAlchemy 1.4.46, which is the last 1.x release. The pins are consistent with each other, since the 2.x SQLAlchemy release needs a newer Flask-SQLAlchemy, but it means the project is not on current versions of its main dependencies.

The third is that the front end is not here. The README describes a three-tier separation with the front end and back end separated, and the repository holds only the back half. The dynamic menu routing means the front end has to implement the route consumption, so this is a back-end project for a specific front-end plan rather than a standalone service.

The fourth is that the operation and audit features are the interesting part and the least documented. Operation logs, login logs, dictionary data, system parameters and file management are all listed as built in, and the visible README text does not describe their endpoints or their retention behaviour. For a system handling user accounts and admin actions, the audit log in particular is something you want to know about before you deploy.

The fifth is the deployment target. The production environment is described as Linux Ubuntu 16.04, and the Nginx configuration is referenced rather than included in the visible repository listing. The compose path is the one that is fully specified.

This project against a fresh Flask scaffold and against a full e-commerce platform

Two comparisons make the choice clearer.

The first is against starting a Flask project from scratch and adding the pieces you need. The difference in approach is how much of the administrative back office you would otherwise build. Users, roles, per-interface permissions, dynamic menus with multi-level routing, dictionaries, system parameters, notifications, audit logs, file management and articles is a lot of tables and a lot of endpoints, and they are the parts that are tedious rather than hard. If you are writing a mini program shop, inheriting that set is worth more than the weeks it would take to reproduce.

The cost is that you inherit it wholesale, including its schema, its permission model and its opinions, and you have to read enough of it to know which parts to keep. The generated API documentation helps here, since it lets you see the surface before you commit to it.

The second comparison is against a full e-commerce platform. Those come with the store, the orders, the payments, the inventory and the admin interface already integrated, and they come with a licence or a subscription. The difference in approach is that a platform assumes your business model and gives you a configuration surface, while this gives you an HTTP API and a schema you can reshape.

For a graduation project or for a small shop with a custom front end, that difference is the point. The README is explicit about the intended audience, and it is a narrow one: a WeChat mini program storefront with a conventional Chinese e-commerce back-office, on a stack that is readable by one developer.

The practical recommendation is to treat it as a starting point rather than a product. The feature set is real and the structure is sound, but the credentials need replacing, the dependency versions need a decision, and the audit behaviour needs checking before it handles anything you care about.

Editorial conclusion

Adopt mini-shop-server if you are building a WeChat mini program shop and want the administrative half already built, including roles, menus and generated API documentation. Do not adopt it as a starting point for a public service without replacing the shipped credentials, since the example secret key and database password are committed in the repository. Verify first that your WeChat app credentials are set in the environment, that the seed data's account hashes are regenerated rather than reused, and that the documented Python and Flask versions match what you intend to deploy.

Frequently asked questions

Official sources

1. Allen7D/mini-shop-server on GitHub
2. Issues
3. License: MIT
4. Project website
5. README