189 lines
7.6 KiB
Python
189 lines
7.6 KiB
Python
"""Guides: step-by-step procedures written and read inside ShopDB.
|
|
|
|
WHY THIS IS NOT THE KNOWLEDGE BASE PLUGIN
|
|
|
|
The knowledgebase plugin is a LINK REGISTRY - a short description, a URL and
|
|
some keywords, pointing at a document that lives somewhere else. That is a
|
|
different job. This holds the document itself.
|
|
|
|
WHY BLOCKS RATHER THAN A BLOB OF HTML
|
|
|
|
A guide is stored as an ordered list of typed blocks, each with a stable id,
|
|
serialized as JSON. Free-form HTML would be easier to write and would defeat
|
|
three of the four things this feature exists for:
|
|
|
|
checklists a tickable step has to be identifiable to be remembered, and
|
|
an <input> buried in pasted markup has no identity
|
|
dark mode pasted content carries hardcoded colours, which then fight the
|
|
theme - black text on a dark background, and nobody can say
|
|
why
|
|
printing print has to know where a step begins and ends to avoid
|
|
splitting one across a page
|
|
|
|
Blocks also mean a new block type later is additive: old guides keep
|
|
rendering, because the renderer skips what it does not know.
|
|
|
|
INLINE TEXT IS A RESTRICTED MARKDOWN SUBSET - bold, italic, inline code, links,
|
|
line breaks, and nothing else. No fonts, sizes or colours: emphasis is semantic
|
|
and the theme decides how it looks. That single rule is what keeps a guide
|
|
written next year looking like one written today, and what makes dark mode work
|
|
without an author thinking about it.
|
|
"""
|
|
|
|
import json
|
|
from datetime import datetime
|
|
|
|
from shopdb.api import db
|
|
from shopdb.core.models.base import BaseModel
|
|
|
|
|
|
def _utcnow():
|
|
return datetime.utcnow()
|
|
|
|
|
|
# Block types the renderer knows. Stored as data, not as markup, so the same
|
|
# guide can render to screen, to dark mode and to paper differently.
|
|
BLOCKTYPES = (
|
|
'heading',
|
|
'paragraph',
|
|
'step', # a numbered step, with its own body
|
|
'checklist', # tickable items - the reason progress is a feature
|
|
'bullets',
|
|
'numbers',
|
|
'callout', # info / warning / success, per the KB house style
|
|
'code',
|
|
'image',
|
|
'table',
|
|
)
|
|
|
|
|
|
class Guide(BaseModel):
|
|
"""One guide. Blocks live in a JSON column rather than a child table.
|
|
|
|
A guide is edited and saved WHOLE - nobody reorders one paragraph in
|
|
isolation - so a child table would buy ordering machinery, a second
|
|
migration and N+1 reads, in exchange for nothing this feature needs. The
|
|
same reasoning the geenforce manifests and backup payloads already follow.
|
|
"""
|
|
|
|
__tablename__ = 'guides'
|
|
|
|
guideid = db.Column(db.Integer, primary_key=True)
|
|
|
|
# Human title, and the slug the URL uses. The slug is stored rather than
|
|
# derived on read so an edited title cannot silently break a link somebody
|
|
# pasted into a work order.
|
|
title = db.Column(db.String(300), nullable=False)
|
|
slug = db.Column(db.String(300), nullable=False, unique=True, index=True)
|
|
|
|
# One line, shown in the list and in search results.
|
|
summary = db.Column(db.String(1000))
|
|
|
|
# Comma-separated, matching how knowledgebase.keywords already works, so one
|
|
# search can cover both and there is one tag vocabulary rather than two.
|
|
tags = db.Column(db.String(500))
|
|
|
|
# 'draft' or 'published'. A draft is visible to people who can edit, and
|
|
# invisible to everyone else: a half-written procedure on a shop floor is
|
|
# worse than no procedure.
|
|
status = db.Column(db.String(20), nullable=False, default='draft', index=True)
|
|
|
|
# MEDIUMTEXT: serialized blocks. Text rather than a native JSON column so the
|
|
# bytes come back exactly as written and a diff between versions is stable -
|
|
# the same reason the backups plugin stores its projection as text.
|
|
blocksjson = db.Column(db.Text(length=16777215), nullable=False, default='[]')
|
|
|
|
createdby = db.Column(db.Integer, db.ForeignKey('users.userid'))
|
|
updatedby = db.Column(db.Integer, db.ForeignKey('users.userid'))
|
|
createdat = db.Column(db.DateTime, nullable=False, default=_utcnow)
|
|
updatedat = db.Column(db.DateTime, nullable=False, default=_utcnow,
|
|
onupdate=_utcnow)
|
|
publishedat = db.Column(db.DateTime)
|
|
|
|
# Bumped on every save. Cheap, and it gives a printed copy something
|
|
# honest to put in its footer: "version 7, printed 26 Aug 2026".
|
|
revision = db.Column(db.Integer, nullable=False, default=1)
|
|
|
|
@property
|
|
def blocks(self):
|
|
"""The decoded block list, or [] on a corrupt row.
|
|
|
|
Deliberately forgiving, unlike the backups payload getter: a guide that
|
|
will not render is a page a person cannot read, and an empty guide with
|
|
its title and tags intact is a better failure than an error page. The
|
|
corruption is still visible - the editor shows no blocks.
|
|
"""
|
|
if not self.blocksjson:
|
|
return []
|
|
try:
|
|
data = json.loads(self.blocksjson)
|
|
except (ValueError, TypeError):
|
|
return []
|
|
return data if isinstance(data, list) else []
|
|
|
|
@blocks.setter
|
|
def blocks(self, value):
|
|
self.blocksjson = json.dumps(value or [], separators=(',', ':'))
|
|
|
|
def taglist(self):
|
|
"""Tags as a clean list, empties dropped."""
|
|
return [t.strip() for t in (self.tags or '').split(',') if t.strip()]
|
|
|
|
def to_dict(self, includeblocks=False):
|
|
data = {
|
|
'guideid': self.guideid,
|
|
'title': self.title,
|
|
'slug': self.slug,
|
|
'summary': self.summary,
|
|
'tags': self.taglist(),
|
|
'status': self.status,
|
|
'revision': self.revision,
|
|
'createdat': self.createdat.isoformat() + 'Z' if self.createdat else None,
|
|
'updatedat': self.updatedat.isoformat() + 'Z' if self.updatedat else None,
|
|
'publishedat': (self.publishedat.isoformat() + 'Z'
|
|
if self.publishedat else None),
|
|
}
|
|
if includeblocks:
|
|
data['blocks'] = self.blocks
|
|
return data
|
|
|
|
|
|
class GuideImage(BaseModel):
|
|
"""An image pasted or dropped into a guide.
|
|
|
|
Bytes live in the database, not on disk. Guides are small, the images are
|
|
screenshots rather than photographs, and a row travels with a database
|
|
backup - whereas a file under instance/ has been lost to a container rebuild
|
|
on this very deployment before. If a site ever puts thousands of these in,
|
|
the storage decision is one column and one route to revisit.
|
|
"""
|
|
|
|
__tablename__ = 'guideimages'
|
|
|
|
guideimageid = db.Column(db.Integer, primary_key=True)
|
|
|
|
# Nullable: an image is uploaded while a NEW guide is still unsaved, so it
|
|
# exists before the guide it belongs to does. The editor attaches it on
|
|
# save; anything still unattached is orphaned and prunable.
|
|
guideid = db.Column(db.Integer, db.ForeignKey('guides.guideid',
|
|
ondelete='CASCADE'), index=True)
|
|
|
|
filename = db.Column(db.String(255))
|
|
mimetype = db.Column(db.String(100), nullable=False)
|
|
bytesize = db.Column(db.Integer, nullable=False)
|
|
data = db.Column(db.LargeBinary(length=(2 ** 24) - 1), nullable=False)
|
|
|
|
uploadedby = db.Column(db.Integer, db.ForeignKey('users.userid'))
|
|
createdat = db.Column(db.DateTime, nullable=False, default=_utcnow)
|
|
|
|
def to_dict(self):
|
|
return {
|
|
'guideimageid': self.guideimageid,
|
|
'guideid': self.guideid,
|
|
'filename': self.filename,
|
|
'mimetype': self.mimetype,
|
|
'bytesize': self.bytesize,
|
|
'url': '/api/guides/images/{}'.format(self.guideimageid),
|
|
'createdat': self.createdat.isoformat() + 'Z' if self.createdat else None,
|
|
}
|