DP44/enriched-qwen3-coder-next/DataPRO/Users.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/Users/ChallengeDialog.cs DataPRO/Users/IUIItems.cs DataPRO/Users/UIItemHelper.cs DataPRO/Users/ChallengeDialog.designer.cs DataPRO/Users/ITagAware.cs DataPRO/Users/Tags.cs DataPRO/Users/UserCollection.cs	2026-04-16T03:46:19.938942+00:00	Qwen/Qwen3-Coder-Next-FP8	1	411369925e7525de

Documentation: DTS.Slice.Users Module

1. Purpose

This module provides core user and tag management functionality for the DataPRO application, including UI permission/visibility control, user CRUD operations, and tag-based object association. It enables role-based access control (RBAC) by associating users with permission levels and visibility flags for UI elements, and supports tagging arbitrary entities (users, groups, tests, sensors, etc.) for flexible filtering and grouping. The module includes a modal dialog (ChallengeDialog) for prompting administrator credentials when elevated privileges are required.

2. Public Interface

ChallengeDialog (Windows Form)

• ChallengeDialog()
  Public constructor. Initializes the form via InitializeComponent(). Displays a password prompt for admin access with fields for password entry (tbPassword), a failure message label (lblLoginFailedMessage), and Continue/Cancel buttons (btnContinue, btnCancel). No custom logic is implemented in the provided source—behavior is entirely UI-driven.

IUIItems Interface

• UserPermissionLevels GetDefaultRolePermission(DefaultRoles role)
  Returns the default permission level for a given role on this UI item.
• bool GetDefaultRoleVisibility(DefaultRoles role)
  Returns whether the UI item is visible by default for a given role.
• void SetVisible(bool bShow)
  Sets the visibility state of the UI item.
• void SetEnabled(bool bEnabled)
  Sets the enabled state of the UI item.
• UserPermissionLevels GetRequiredPermission()
  Returns the minimum permission level required to access this UI item.
• string GetName()
  Returns the display name of the UI item.
• long GetID()
  Returns the unique identifier of the UI item.
• void SetID(long id)
  Sets the unique identifier of the UI item.

UIItemHelper Class

• UIItemHelper(long uiItemId, short permission, bool visible, string uiItemName)
  Constructor. Stores UI item metadata: ID, permission level, visibility, and name.
• long UIItemId { get; }
  Read-only ID of the UI item.
• string UIItemName { get; }
  Read-only display name of the UI item.
• bool IsVisible { get; }
  Read-only visibility flag.
• short Permission { get; }
  Read-only permission level (stored as short).

TagAwareBase (Abstract Class)

• TagTypes TagType { get; }
  Abstract property returning the type of entity this tag-aware object represents (e.g., User, TestSetup).
• int[] TagIDs { get; set; }
  Array of tag IDs associated with the object. Setter accepts null (treated as empty array).
• byte[] TagsBlobBytes { get; set; }
  Binary blob representation of TagIDs (int array → byte array via Buffer.BlockCopy). Setter logs exceptions on failure.
• void SetTagsFromCommaSeparatedString(string tagText)
  Parses comma-separated tag text, trims whitespace, and updates TagIDs via SetTags().
• virtual void SetTags(string[] tagsText)
  Updates Tags collection and TagIDs based on tag text array. Raises OnPropertyChanged("TagIDs").
• string GetTagsAsCommaSeparatedString()
  Returns comma-separated tag text (e.g., "tag1,tag2").
• virtual string[] GetTagsArray()
  Returns array of tag text strings corresponding to TagIDs.
• virtual int[] GetTagIDs()
  Returns TagIDs array.
• virtual void RemoveTags(string[] tagsText)
  Stub—no implementation provided.
• bool TagCompatible(string tags)
  Returns true if any tag in the input string matches a tag on this object. Ignores empty/whitespace tags.
• virtual bool TagCompatible(int[] tags)
  Returns true if tags array is empty or shares at least one ID with TagIDs.
• virtual bool HasIntersectingTag(int[] tags)
  Returns true if tags and TagIDs share at least one ID.
• void InsertTagsFromCommaSeparatedString(int id, TagTypes tagType, string tags)
  Sets tags from comma-separated string and commits associations to DB.
• void Commit(int id, TagTypes tagType)
  Deletes existing tag assignments for (id, tagType) and inserts new assignments for current TagIDs. Uses stored procedures sp_TagAssignmentsDelete and sp_TagAssignmentsInsert. Logs errors via APILogger.
• List<int> GetTagIdList(int objectId, TagTypes tagType)
  Retrieves tag IDs for (objectId, tagType) from DB via sp_TagAssignmentsGet. Returns empty list on failure; logs exceptions.

Tags Class (Singleton)

• Tag INVALID_ID = -1
  Constant representing an invalid/missing tag ID.
• class Tag
  Represents a single tag with ID, Text, and IsObsolete properties. Implements ICloneable.
• static Tags TagsInstance { get; }
  Singleton instance. Initialized on first access.
• static bool AddTag(string tagText)
  Adds a new tag if not already present in cache or DB. Returns false if tag exists or input is null/empty.
• static bool MigrateTag(string tagText)
  Commits a tag to DB (used for migration). Does not check cache.
• static bool[] AddRange(string[] tagText)
  Adds multiple tags. Trims leading whitespace from each. Returns array of success flags.
• static int GetIDFromTagText(string tagText)
  Retrieves tag ID from DB for given text. Returns Tag.INVALID_ID if not found.
• static int[] GetIDsFromTagText(string[] tagText)
  Converts array of tag text to array of IDs. Skips invalid IDs.
• static string GetTagTextFromID(int tagID)
  Retrieves tag text from in-memory cache for given ID. Returns null if invalid or not found.
• static string[] GetTagTextFromIDs(int[] tagId)
  Converts array of IDs to array of tag text. Skips invalid/empty entries.
• bool ContainsTag(string text)
  Checks if tag text exists in in-memory cache.
• void UpdateList()
  Refreshes in-memory cache from DB via sp_TagsGet. Clears cache first.

UserCollection Class (Singleton)

• static UserCollection UsersList { get; }
  Singleton instance. Thread-safe via lock.
• static Dictionary<int, List<int>> GetUserToTagIdLookup()
  Returns mapping of user IDs to their associated tag IDs. Calls DbOperations.TagAssignmentsGet(TagTypes.User, out ...).
• static User[] GetAllUsers(IUIItems[] allItems, int? uid = null)
  Loads users from DB. If uid is provided, returns only that user; otherwise, ensures default users (roles + special accounts like DefaultAeroUsername) exist in DB. Uses sp_UserUIItemSettingsGet, sp_UsersGet. For non-uid calls, commits missing default users via UsersList.Commit().
• static User GetUser(int uid, IUIItems[] items)
  Wrapper around GetAllUsers(items, uid). Returns first result or null.
• static User GetUser(string username, IUIItems[] items)
  Retrieves user ID by username via sp_UsersGetId, then calls GetUser(id, items).
• void Commit(User user, string username, IUIItems[] items)
  Persists user to DB via sp_UsersUpdateInsert. Updates user settings and permissions/visibility via InsertPermissionsAndVisibility() and InsertTags(). Raises OnPropertyChanged("AllUsers").
• void Delete(User user) / void Delete(User[] users)
  Deletes user(s) via sp_UsersDelete. Raises OnPropertyChanged("AllUsers").
• private static void InsertTags(User user)
  Deletes existing tag assignments for user and inserts new ones for user.TagIDs.
• private static void InsertPermissionsAndVisibility(User user, IReadOnlyList<IUIItems> items)
  Deletes existing UI item permissions for user via sp_UserUIItemSettingsDelete, then inserts new permissions/visibility for each item via sp_UserUIItemSettingsInsert.

3. Invariants

• Tag IDs are non-negative integers except Tag.INVALID_ID = -1 (used for missing IDs).
• Tags singleton is lazily initialized and thread-safe via lock(LOCK_OBJECT) for cache access.
• UserCollection.UsersList is a singleton with thread-safe lazy initialization (lock(MyLock)).
• UIItemHelper properties are immutable after construction (read-only auto-properties).
• TagIDs array is never null (setter normalizes null to new int[0]).
• TagCompatible(string) ignores empty/whitespace tags in input.
• Commit(int id, TagTypes tagType) in TagAwareBase deletes existing assignments before inserting new ones—no partial updates.
• GetAllUsers ensures default users exist in DB when called without uid (e.g., DefaultAeroUsername, DefaultCrashUsername, DefaultTSRAIRUsername).
• ChallengeDialog has no custom logic—behavior is purely UI-driven (no event handlers or validation in source).

4. Dependencies

Internal Dependencies

• DTS.Slice.Users.User (not provided in source, but referenced in UserCollection.cs): Core user model with properties like Id, UserName, Role, TagIDs, GetPermission(), IsShowTabFlagSet(), GetPasswordHash(), IsADefaultUser, TagType.
• DTS.Slice.Users.UserSettings.TestSetupDefaults: Used in UserCollection.Commit() to manage user-specific settings.
• DTS.Slice.Users.UserSettings.Defaults: Used to create/update user setting properties.

External Dependencies

• System.Windows.Forms: ChallengeDialog inherits from Form; uses TableLayoutPanel, TextBox, Button, Label.
• DTS.Common.Storage.DbOperations: Provides database access methods (GetSQLCommand, QueryDataSet, TagAssignmentsGet, Tags nested class with fields like TagFields, TagAssignmentFields).
• DTS.Common.Storage.DbOperationsEnum.StoredProcedure: Enum for stored procedure names (e.g., sp_TagsInsert, sp_UsersGet).
• DTS.Common.Utilities.Logging.APILogger: Used for exception logging.
• DTS.Common.Base.BasePropertyChanged: Base class for TagAwareBase (implements INotifyPropertyChanged).
• DTS.Common.Interface.Tags: Namespace for tag-related interfaces (e.g., ICloneable usage).

Inferred Dependencies

• Database stored procedures: sp_TagsInsert, sp_TagsGetId, sp_TagsGet, sp_UsersUpdateInsert, sp_UsersGet, sp_UsersGetId, sp_UsersDelete, sp_UserUIItemSettingsGet, sp_UserUIItemSettingsDelete, sp_UserUIItemSettingsInsert, sp_TagAssignmentsDelete, sp_TagAssignmentsInsert.
• User.DefaultRoles enum: Referenced in IUIItems and UserCollection.GetAllUsers.
• User.UserPermissionLevels enum: Referenced in IUIItems and UIItemHelper.

5. Gotchas

• TagIDs setter accepts null but normalizes to empty array—no exception thrown, but TagsBlobBytes setter silently returns if input length < sizeof(int).
• TagCompatible(string) returns true for empty/whitespace input—not false as might be expected.
• Tags cache is only updated on startup or when AddTag/MigrateTag is called—changes to tags in DB by other processes are not reflected until UpdateList() is explicitly invoked.
• GetAllUsers commits missing default users to DB—this may cause unintended side effects if called repeatedly (e.g., during testing).
• ChallengeDialog has no public methods or properties—its behavior (e.g., password validation, dialog result) is not implemented in the provided source.
• RemoveTags in TagAwareBase is a stub—no implementation provided.
• UserCollection.Commit calls InsertPermissionsAndVisibility for all IUIItems—even if permission/visibility hasn’t changed, potentially causing unnecessary DB writes.
• Tags.GetTagTextFromID uses in-memory cache only—no DB fallback if tag is missing from cache.
• Tags.AddTag trims leading whitespace only (via TrimStart) when adding tags—trailing whitespace is preserved in DB.
• UIItemHelper.Permission is stored as short—mismatch with UserPermissionLevels enum (assumed to be short-backed, but not verified in source).