Skip to content

feat(file-movement): unified file movement and barcode scanning for version-16 - #25

Merged
mujeerhashmi merged 6 commits into
4csolutions:version-16from
abdullahsyed4c:feat/file-movement-barcode
Nov 14, 2026
Merged

mujeerhashmi merged 6 commits into
4csolutions:version-16from
abdullahsyed4c:feat/file-movement-barcode

Conversation

@abdullahsyed4c

@abdullahsyed4c abdullahsyed4c commented Nov 12, 2026 •

Copy link
Copy Markdown

Summary of Changes

This PR implements the complete, end-to-end File Movement & Barcode Tracking system for Case Central (version-16):

  1. Single Unified Scanner Field (scan_barcode):

    • One single barcode field positioned in its own section directly above the Outgoing Files section.
    • Label displays in bold (Scan Outgoing during dispatch, dynamically switches to Scan Incoming during return).
    • Single clean validation warning (No such Matter ID or Case exists: ...) with deduplication.
  2. Status Lifecycle & Audit Trail:

    • Draft -> Initial movement preparation.
    • Taken Away (Orange) -> Saved & submitted; files out with receiver (linked Matter updates to Working).
    • Incoming Created (Blue) -> Created incoming session without files scanned yet.
    • Missing Files (Red) -> Partially returned; remaining files listed in Missing Files table.
    • Received (Green) -> All files returned; linked Matter resets to Open.
    • Incoming Cancelled (Dark Grey) -> Independent incoming cancellation preserving all traces.
    • Cancelled (Red) -> Full movement cancellation with delete protection (on_trash).
  3. Independent Incoming Cancellation:

    • Dedicated Cancel Incoming button cancels only the return workflow without cancelling or deleting the submitted movement.
    • Re-open Incoming button to resume incoming return when ready.
  4. Operations Sidebar Placement:

    • File Movement added directly under Meeting Room in casecentral/case_central/sidebar/operations/operations.json.
    • Dock icons rail left untouched.
  5. Strict Scope:

    • Only File Movement doctypes and operations.json.
    • Zero changes to unrelated files (Matter, Case, Caveat, Workspace, Dock).

@mujeerhashmi

Copy link
Copy Markdown
Contributor

Critical Findings & Required Changes

1. Violations of Frappe Query Builder Rule (frappe.qb vs frappe.db.sql)

Severity: Critical
Rule Reference: Always use Frappe Query Builder (frappe.qb) instead of raw SQL (frappe.db.sql).

In file_movement.py#L177-L208, raw SQL is used twice inside recalculate_matter_status_from_movements:

# Raw SQL in file_movement.py:
unreturned = frappe.db.sql("""
    SELECT bfi.name, bfi.`case`, bfi.barcode, fm.name as movement_name
    FROM `tabFile Movement Item` bfi
    INNER JOIN `tabFile Movement` fm ON fm.name = bfi.parent
    WHERE fm.docstatus = 1 
      AND fm.status NOT IN ('Received', 'Cancelled')
      AND bfi.parentfield = 'outgoing_files'
      AND bfi.matter = %s
""", (matter_name,), as_dict=True)

Recommended Fix: Refactor to frappe.qb:

bfi = frappe.qb.DocType("File Movement Item")
fm = frappe.qb.DocType("File Movement")

unreturned = (
    frappe.qb.from_(bfi)
    .inner_join(fm).on(fm.name == bfi.parent)
    .select(bfi.name, bfi.case, bfi.barcode, fm.name.as_("movement_name"))
    .where(
        (fm.docstatus == 1)
        & (~fm.status.isin(["Received", "Cancelled"]))
        & (bfi.parentfield == "outgoing_files")
        & (bfi.matter == matter_name)
    )
).run(as_dict=True)

Similarly for checking items in incoming_files, replace the inner loop raw SQL with either a set-difference evaluation in Python or a single batch frappe.qb query to eliminate the N+1 query problem.


2. Missing Permission & Role Enforcement on Whitelisted Endpoints

Severity: High
File: file_movement.py

The whitelisted functions (create_incoming, cancel_incoming, scan_incoming_file, return_missing_files) directly alter document state and child tables without checking doc permissions:

  • Any authenticated user with Desk access can invoke frappe.call("...cancel_incoming", {movement_name: "..."}) or inject items into incoming files.
  • frappe.get_doc("File Movement", movement_name) does not assert write permissions by default unless doc.check_permission("write") is explicitly invoked.

Recommended Fix: Add permission checks at the start of mutating APIs:

doc = frappe.get_doc("File Movement", movement_name)
doc.check_permission("write")

3. Role Permissions Only Grant System Manager in DocType JSON

Severity: High
File: file_movement.json

In file_movement.json, the only configured permission is:

"permissions": [
  {
   "create": 1,
   "delete": 1,
   "email": 1,
   "export": 1,
   "print": 1,
   "read": 1,
   "report": 1,
   "role": "System Manager",
   "share": 1,
   "write": 1
  }
]

In a typical law practice environment running CaseCentral, paralegals, clerks, lawyers, or Legal Assistant / Case Manager roles handle file dispatch and barcode scanning. Restricting to System Manager prevents standard legal staff from using this feature.

Recommended Fix: Add standard CaseCentral roles (e.g., Legal Assistant, Case Manager, Advocate) with appropriate read, write, create, submit, and cancel permissions in file_movement.json.


4. Direct SQL Mutation vs Document Model Integrity

Severity: Medium
File: file_movement.py#L414-L420, L596-L624, L753-L759

Child table updates are being executed using raw table operations:

frappe.db.delete("Missing File Items", {"parent": doc.name})
for row in doc.missing_file_items:
    row.parent = doc.name
    row.parenttype = "File Movement"
    row.parentfield = "missing_file_items"
    row.db_insert()

While this bypasses submittable doc status validation checks (since docstatus == 1), it bypasses document versioning, modified timestamps, and change log audits.

  • Consider utilizing Frappe's allow_on_submit field property combined with doc.flags.ignore_validate_update_after_submit = True and doc.save(), or ensure doc.db_set("modified", now_datetime()) is touched to preserve cache invalidation and concurrency tracking.

5. DOM & UI Anti-Patterns in Form Scripts

Severity: Medium
File: file_movement.js

  1. Global CSS Injections in onload:

    frappe.dom.set_style(`
        [data-fieldname="scan_barcode"] .control-label, ...
    `);

    Injecting into global DOM head styles can bleed across views and tabs in Desk. Prefer scoping styles to frm.fields_dict.scan_barcode.$wrapper or using standard field description styling.

  2. Hardcoded Inline Hex Colors:
    In dialogs and missing tables:

    var row_bg = item.scanned ? "background-color: #f0fdf4;" : "";

    This will break visual contrast in Desk Dark Mode. Use Frappe theme variables instead (e.g. var(--bg-green-50), var(--text-green-700), var(--text-muted)).


Strengths & Commendable Practices

  1. Robust Barcode Handling: Multi-target scanning (Matter ID, Case ID, Case Barcode) with automatic fallback resolution works smoothly.
  2. Double-Scanning Prevention: Both backend and frontend validate against duplicate barcode and case inclusions.
  3. Comprehensive Test Suite: 350+ lines of tests covering edge scenarios, validation checks, and transitions.
  4. Non-invasive Scoping: PR strictly adheres to its module boundaries without polluting core Case or Matter files.

Suggested Action Items Before Approval

  • Convert frappe.db.sql calls in recalculate_matter_status_from_movements to frappe.qb.
  • Add doc.check_permission("write") to all modifying whitelisted endpoints.
  • Add standard CaseCentral legal operational roles to file_movement.json permissions list.
  • Replace hardcoded light-theme CSS styles in file_movement.js with Frappe CSS variables (var(--...)) for dark mode compatibility.

@mujeerhashmi
mujeerhashmi merged commit 57064f8 into 4csolutions:version-16 Nov 14, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants