FinalScheduler Documentation

FinalScheduler is a comprehensive shift management system. Its core features include:

• Personnel Management (人员管理): Maintain personnel information through CRUD (Create, Read, Update, Delete) operations.
• Group Management (分组管理): Organize personnel into groups based on tasks or departments to facilitate scheduling.
• Shift Settings (班次设置): Define custom shifts, including custom names, colors, and time ranges.
• Scheduling Management (排班管理): Create schedules based on personnel groups and predefined shift settings. Shift colors are automatically synchronized from the shift settings.
• Attendance Statistics (考勤统计): Generate statistics for various attendance statuses, such as normal, late, absenteeism, and leave (customizable).

To deploy FinalScheduler, follow these steps:

1. Database Creation: Create a new MySQL database named finalschedule.
2. Data Import: Import the structure and data tables found in the sql folder of the repository into your new database.
3. User Configuration: The provided SQL files use the database username dlwy. You must either change dlwy to your own MySQL username within the SQL files before importing, or create a MySQL user named dlwy with the appropriate permissions.
4. Deployment: Deploy and start the project using your preferred Java application server.

The scheduling module relies on several global variables attached to the Giscafer object to maintain state across different operations:

• Giscafer.pbglXhyCache: Stores grouped personnel information (array of { groupName, personArr }).
• Giscafer.pbglBcColorObj: Maps shift names to their respective colors (e.g., { 'Night': '#ff0000' }).
• Giscafer.pbglEventsCache: Stores fetched schedule events organized by person and date ({ pid: { date: 'event1|event2' } }).
• Giscafer.calendar: Holds the initialized FullCalendar instance.
• Giscafer.calenderVisStart / Giscafer.calenderVisEnd: Used for date range calculations in the UI.

The module respects a global configuration setting config.options.lockData. When this is enabled, the following restrictions are enforced:

• Editing: Rows where row.lock == 1 cannot be edited via editRow.
• Deletion: If any selected row has lock == 1, the deletion process is aborted.

The loadUI(ui) function handles switching between different system interface views. It clears the current content in #giscafer_content and loads the requested UI.

If the target UI element (identified by a generated ID based on the string length) does not already exist in the DOM, the function performs an asynchronous POST request to fetch the new UI content. If the server response indicates a login redirect (redirect->login), the browser is redirected to the window.hostUrl.

Parameters:

• ui (String): The page path or template name. If provided, it is appended to window.hostUrl as a template query parameter.

// Example: Load a specific UI template
loadUI('myTemplateName');

Fetches the current saved order of shifts from the server.

Behavior:

• If shifts are found, it sets Giscafer.bcglObjectId and builds the HTML list in #plan_order_list using the planItem string (split by |).
• If no order is found, it calls queryPlanTable() to fetch the master list of shifts and initialize the order.

Endpoint: GET {hostUrl}/plan/getPlanOrderList.

exports.getPlanOrder(function(result) {
    console.log('Shift order retrieved:', result);
});

Use getGroupInfoFromDB(flag) to retrieve the current personnel group configuration from the server and render it in the #group_container element.

• flag (boolean): If true, the rendered groups will be in an editable state (enabling drag-and-drop and operation menus). If false or omitted, they are rendered in read-only mode.

If no groups are found in the database, the module automatically attempts to create an initial 'Unnamed' group containing all existing personnel via groupFirstSave().

personGroup.getGroupInfoFromDB(true); // Load groups in editable mode

Fetches the available shift plans and their associated colors from the server. It populates the global Giscafer.pbglBcColorObj where keys are the plan names (planName) and values are the color strings. This function also triggers getBcOrderInfo() to build the UI toolbar.

exports.getPlanInfoAndColor = function() {
  // Fetches data and populates Giscafer.pbglBcColorObj
};

When using the 'Rename Group' dialog, call initRenameGroup() to bind the save button logic. This function reads the new name from #groupNewName and performs an updateGroup POST request using the Giscafer.fzglObjectId as the identifier.

personGroup.initRenameGroup();

Use editRow(index, row) to put a specific row in the #persondg datagrid into edit mode. The function handles validation of any currently editing row before proceeding. If the row is marked as locked (row.lock == 1) and the global configuration config.options.lockData is enabled, editing will be blocked with a warning message.

// Assuming the module is required via SeaJS
var personModule = require('app/person/index.js');

// index is the row index in the datagrid, row is the data object
personModule.editRow(0, { pid: 123, name: 'John Doe', lock: 0 });

The gcGet(url, callback) function is a wrapper around jQuery's $.get method to perform asynchronous GET requests.

Parameters:

• url (String): The URL to request.
• callback (Function): A function that receives the response data from the server.

gcGet('/api/data', function(data) {
    console.log('Received data:', data);
});

Creates a new shift configuration. It validates the #updatePlanForm and sends the new shift data to the server.

Data Payload Structure: Sends a JSON array containing an object with the following keys:

• color
• planName
• defineType
• planType
• periodTime
• totalTime

Endpoint: POST {hostUrl}/plan/save with the key inserted containing the JSON string.

Side Effects:

• On success, it re-renders the UI using loadUIAndRender.
• It emits the afterPlanAddSuccess event via Giscafer.ep.
• It automatically attempts to update the shift order via addPlanOrderAfterAddPlan.

// Example usage:
exports.addPlan();