AdminManagement User Guide

This guide is for developers and project users who need to understand the current workspace, run the local application, and work within the QDBAdmin workflow without drifting into legacy RS assumptions.

1. What this project is

AdminManagement is a project workspace for the active QDB-native admin and checking system. The current application is QDBAdmin, and the overall repo includes:

• the active web application in QDBAdmin/
• design and reference docs in Documentation/
• version handover notes in QDBAdmin/handover/
• historical material retained for context and reference

The key product intent is to build a QDB-native checking and issue/comment workflow, rather than directly porting legacy RS validation logic.

2. Start here

Before making changes, read these documents in order:

1. README.md
2. Documentation/START-HERE.md
3. QDBAdmin/handover/README.md
4. QDBAdmin/handover/HANDOVER-1.0.0.md
5. Documentation/design/qdb_checking_system_design.md

This gives the clearest picture of the current product direction, architecture, and active build priorities.

3. Run the app locally

From the project root:

start_server.bat

This starts the local application on:

http://localhost:8998/qdbadmin/

If you need to run it manually instead:

cd QDBAdmin
python -m pip install -r requirements.txt
python manage.py runserver --settings=qdbadmin.settings2 8998

4. Working rules for this repo

Use the following rules in order to keep work consistent with the current design direction:

Use the current settings files

Use:

• qdbadmin.settings2
• views2.py
• urls2.py

These are the current active configuration paths described in the local docs.

Treat RS material as reference only

The repository includes historical RS validation and SQL reference assets, but they are not the current system of record. The project guidance says:

• do not directly port RS checks into current QDBAdmin logic
• use RS material only to understand historical intent
• redesign checks in QDB-native terms before implementing them

Keep the data model in QDB terms

The active design direction is a QDB-backed issue/checking workflow. Operational data should be read and generated from QDB tables, not from live rs.* tables unless those tables have been intentionally migrated or modeled as QDB sources.

5. Current project direction

The current active direction is a QDB-native checking workflow with the following capabilities already described in the project docs:

• generic check definitions and admin rows
• data-change and event queue support
• seeded SQL checks
• durable issue responses
• issue actions and comments
• external event API for other systems
• issue counts and badges in QDBAdmin grids
• issue detail panel or modal
• Integrity page

The recommended near-term work is workflow hardening:

• real user attribution
• 30-day purge for deletion-marked issues
• richer issue-context details in the issue panel
• per-check parameter prompts in the Integrity page

6. Repository map

A quick guide to the main folders:

• Documentation/ - current design and reference documents
• QDBAdmin/ - active app and app-level handover notes
• changelog/ - project-level changelog notes
• handover/ - repo-level handover summaries
• entities/ - schema and entity definition files
• templates/ - shared templates and app support files
• Test API/ - older API/test tooling retained for historical context

7. Important cautions

• Do not expose DB credentials or local secrets in project docs.
• Prefer carefully verified edits; the repo has a history of Windows-mounted write corruption concerns.
• Some older docs mention old local paths; use the current workspace path as the source of truth.
• Sales entities are still partial or stale until the proper QDB V6 sales schema is available.

8. Verification checklist before finishing work

Before concluding work on a feature or fix, verify:

1. the relevant handover or design doc still matches the intended behavior
2. the app still runs with the local startup command
3. current settings and route files are the ones being used
4. legacy RS references are treated as context, not current implementation truth
5. any project documentation update reflects the actual system state

9. Related pages

• overview
• changelog

This guide should be updated as the working design or operational procedures change.