PureRecruitment-TAMO-bupter

Release

Group-16 Members

Github UserName	Chinese Name	Name in English	BUPT ID	QM ID	Email
StarDust-XCHH	管宇涵	Yuhan Guan	2023213116	231220725	lmtgyh@163.com
zfh53	张峰豪	Fenghao Zhang	2023213136	231221216	zhang.fenghao@qq.com
6a696c6c	李玉峰	Yufeng Li	2023213131	231222556	3171506351@qq.com
StellaWang309	汪以琳	Yilin Wang	2023213143	231222305	1938508113@qq.com
TTslmy	刘慧颖	Huiying Liu	2023213172	231221788	2497604794@qq.com
Au2789	庞博文	Bowen Pang	2023213124	231220998	pbw3319@163.com

• Yuxuan:yuxuanwwang@outlook.com (Support TA)

2. Repository README

Project Overview

PureRecruitment-TAMO-bupter is a Java web application for Teaching Assistant recruitment. It supports role-specific workflows for TA users, Module Organisers (MO), and Admin users. The application is packaged as a WAR and uses Jakarta Servlet/JSP pages with front-end assets in src/main/webapp. The main login page lets users switch between TA and MO sign-in, create TA/MO accounts, and access the TA guest job list. Admin access is intentionally hidden in the landing page: click the title area five times to reveal the Admin sign-in panel. The current front-end demo accepts admin / admin123 for Admin entry, as implemented in src/main/webapp/assets/common/js/index.js.

The project does not require a separate database server for the supplied release. Runtime data is stored in the external mounted data directory mountDataTAMObupter, which contains shared course data, TA/MO/Admin JSON files, uploaded resumes, images, AI conversations, AI attachments, and application state. The application resolves this directory through the mountDataTAMObupter environment variable, with a fallback to the repository-local mountDataTAMObupter/ directory if the variable is not set.

Environment

Required tools:

• JDK 17
• Maven wrapper included in the repository: mvnw.cmd on Windows or ./mvnw on Unix-like systems
• Tomcat 10.1.x, following the project-specific setup guide in docs/Github操作指南+Tomcat配置.docx
• IntelliJ IDEA local Tomcat run configuration for the recommended development setup
• The mountDataTAMObupter data directory from this repository or from the release package

Important configuration:

Variable	Required	Purpose
mountDataTAMObupter	Strongly recommended	Absolute path to the runtime data directory
TONGYI_API_KEY	Only for AI features	Enables TA/MO AI assistant and AI recommendation/analysis calls
MAIL_SMTP_PASSWORD	Only for email sending	Enables SMTP decision emails
MAIL_SMTP_HOST, MAIL_SMTP_PORT, MAIL_SMTP_USER, MAIL_FROM_ADDRESS, MAIL_FROM_NAME, APP_PUBLIC_BASE_URL	Optional	Override default mail settings and public email links

PowerShell example:

$env:mountDataTAMObupter = "D:\demo\data\mountDataTAMObupter"
$env:TONGYI_API_KEY = "your_api_key_here"

For the recommended IDEA + Tomcat workflow, do not rely only on a random terminal session. In IDEA, open the local Tomcat configuration, enable passing environment variables, and add mountDataTAMObupter with the absolute path copied from the repository's mountDataTAMObupter folder. This follows the project guide and ensures the Tomcat process can actually see the data path.

Do not commit real API keys or SMTP passwords. If TONGYI_API_KEY is not configured, the AI features should be unavailable or show a service-disabled message, while normal recruitment workflows should still run.

Build and Run

From the repository root, the WAR can be built with:

.\mvnw.cmd clean package

The generated WAR is written under target/. For day-to-day local running, the project guide recommends IDEA + Tomcat rather than a standalone command:

1. Download Tomcat 10.1.x and extract it to a stable local path without Chinese characters.
2. In IDEA, open Run/Debug Configurations and add a local Tomcat Server configuration, not a TomEE configuration.
3. Set the Tomcat home directory to the extracted Tomcat folder.
4. Set the HTTP port to 8788.
5. Set the startup URL to:

http://localhost:8788/PureRecruitment_TAMO_bupter_war_exploded/

6. Copy the absolute path of the repository mountDataTAMObupter folder.
7. In the Tomcat configuration, enable passing environment variables and add:

mountDataTAMObupter=<absolute path copied from the repository data folder>

8. Use IDEA's artifact fix prompt if it appears, and select the war exploded artifact.
9. Run the configuration and confirm that the browser opens the main login page.

As an optional quick developer smoke run, the Maven Jetty plugin is also configured on port 8080:

.\mvnw.cmd jetty:run

Then open:

http://localhost:8080/

For Tomcat deployment:

1. Build the WAR with .\mvnw.cmd clean package.
2. Copy the generated WAR from target/ into Tomcat webapps/.
3. Set mountDataTAMObupter to the absolute path of the extracted data directory.
4. Optionally set TONGYI_API_KEY and SMTP variables before starting Tomcat.
5. Restart Tomcat and check the startup log for a [data-mount] line, for example:

[data-mount] root=D:\demo\data\mountDataTAMObupter fromEnvironment=true env=mountDataTAMObupter

If fromEnvironment=false, Tomcat did not read the environment variable and the application fell back to a relative data path. In that case, configure the variable in the same process context that starts Tomcat and restart the server.

Main Entry Points

• / - main login, registration, role switching, and hidden Admin entry
• pages/ta/ta-guest-home.jsp - guest TA job list
• pages/ta/ta-home.jsp - TA workspace after login
• pages/mo/mo-home.jsp - MO workspace after login
• pages/admin/admin-home.jsp - Admin console after Admin entry

Key runtime data is under:

• mountDataTAMObupter/common/recruitment-courses.json - shared job/course data
• mountDataTAMObupter/ta/ - TA accounts, profiles, settings, applications, status, events, resumes, and TA AI data
• mountDataTAMObupter/mo/ - MO accounts, profiles, settings, application read state, comments, shortlist, and MO AI data
• mountDataTAMObupter/admin/ - Admin accounts, profiles, settings, and notices

Verification Checklist

After deployment, reviewers can validate the release with the following checks:

• The home page loads at http://localhost:8788/PureRecruitment_TAMO_bupter_war_exploded/ for the recommended IDEA Tomcat setup, or at http://localhost:8080/ for the optional Jetty smoke run.
• Static CSS and JavaScript assets load without obvious 404 errors.
• TA and MO registration can create new accounts and return to login.
• TA/MO login reaches the correct workspace.
• The TA guest job list and logged-in job board show mounted course data.
• Applying for a job, viewing status, reading comments, or downloading a resume uses files from mountDataTAMObupter.
• Without TONGYI_API_KEY, AI panels fail gracefully instead of breaking the whole application.
• With TONGYI_API_KEY, AI assistant, recommendation, and analysis features can call the configured model service.
• Admin entry appears after clicking the landing-page title five times, and the demo credential admin / admin123 opens the Admin console.

For deeper deployment details, see docs/releaseReadme/RELEASE-README.md, docs/releaseReadme/ENVIRONMENT-SETUP.md, docs/releaseReadme/DEPLOY-ON-TOMCAT.md, and docs/releaseReadme/DATASET-README.md.