Project Registration

Revision 1.3 (2026-01-20) - Added Follow-Up Workflows feature, simplified ReviewPreWorkProceduresForm commands Revision 1.2 (2026-01-17) - Added Command Confirmation Assignee Auto-Selection Revision 1.1 (2026-01-16) - Added Two-Step Dialog for task creation Revision 1.0 (2026-01-14) - Complete documentation with workflow integration

Feature Summary

Project Registration (การลงทะเบียนโครงการ) is a workflow feature that manages the approval process for new projects. It coordinates between Work Owner, Purchasing, and Contractor roles to complete project setup before work permits can be issued.

Key Capabilities:

• Create and track project registration tasks
• Multi-role workflow: Work Owner → Purchasing → Contractor → Approval
• Document form management (Project Registration Form, Pre-Work Procedures Form)
• Form edit permissions based on workflow state
• Task assignment with email notifications
• Workflow history and audit trail
• Optional command support (planned) - Skip Purchasing if project has PO No.

Workflow Relationship:

Project Registration is the first workflow in the Safety App process:

1. Work Owner creates registration task via Two-Step Dialog:
   • Has PR No.: Search and select existing project
   • No PR No.: Enter project name to create new project
2. Workflow progresses through 8 states (see Workflow Documentation)
3. Upon approval, project can proceed to Work Permit Workflow

Prerequisites:

• For existing projects: Project must exist in Project Settings with PR.No assigned
• For new projects: Work Owner can create project directly via Two-Step Dialog
• Contractor must be configured with coordinator and supervisor

---

Two-Step Dialog for Task Creation

Added in Revision 1.1 (2026-01-16)

When Work Owner creates a Project Registration task, a two-step dialog guides them through project selection or creation.

Problem Solved

Original behavior created orphaned projects:

Issue	Original	New (Two-Step Dialog)
When project created	Immediately on dialog open	Only after user submits
Project name	Empty string ""	User-provided (required)
Orphan risk	High - user can abandon	None - no project until submit

User Flow

WO clicks "สร้างงาน" → Selects "ขึ้นทะเบียนโครงการ"
    ↓
Dialog: "คุณมีเลขที่ใบขอซื้อ (PR No.) หรือไม่?"
    │
    ├─ [มี PR No.] → Search by PR No. → Select project → Create task
    │
    └─ [ไม่มี PR No.] → Enter project name (required)
                        + description (optional) → Create task + project

Two Scenarios

Scenario	Has PR No.?	Action	Result
Case 1	Yes	Search existing project by PR No.	Task linked to existing project
Case 2	No	Enter project name + description	New project created with task

Benefits Over Alternatives

Rejected Option	Why Not Used
Lazy Project Creation	Major backend refactor, FK constraint issues, high risk
Scheduled Cleanup Job	Still creates orphans temporarily, magic cleanup rules
Draft Status for Projects	Adds project status complexity, requires updating all queries

Why Two-Step Dialog is Best:

1. No orphaned projects - Project only created on explicit submission
2. Clear user intent - User explicitly chooses their path
3. Better data quality - Projects always have meaningful names
4. Minimal risk - Frontend-focused change, backend receives optional params
5. No cleanup needed - Unlike scheduled jobs, no delayed deletion logic

Implementation Details

Frontend:

File	Change
select-project-for-pr-dialog.component.ts	New dialog with 3 steps
my-tasks.component.ts	Routes PR task to new dialog
my-tasks.contract.ts	Added newProjectData to request

Backend:

File	Change
CreateTaskEndpoint.cs	Accepts optional NewProjectData
TaskLifecycleService.cs	Uses provided name/description

i18n Keys

Key	Thai	English
tasks.pr.dialogTitle	ขึ้นทะเบียนโครงการ	Project Registration
tasks.pr.hasPrNo	คุณมีเลขที่ใบขอซื้อ (PR No.) หรือไม่?	Do you have a PR No.?
tasks.pr.searchExisting	มี PR No. - ค้นหาโครงการ	Has PR No. - Search project
tasks.pr.createNew	ไม่มี PR No. - สร้างโครงการใหม่	No PR No. - Create new project

---

Command Confirmation Assignee Auto-Selection

Added in Revision 1.2 (2026-01-17)

When executing workflow commands that require assigning to another user, the assignee dropdown now intelligently pre-selects based on Project data.

How It Works

Target Role	Auto-Selection Logic	Fallback
Work Owner	project.workOwnerUserId	First user in list
Safety Officer	project.safetyOfficerUserId	First user in list
Workspace Owner	project.workspaceOwnerUserId	First user in list
Other roles	-	First user in list

Command Types

Type	Use Case	Auto-Selection
AssigneeRequired	Single assignee (e.g., Send to Purchasing)	One dropdown
AllRequired	Parallel approval (e.g., SO + WO review)	Multiple dropdowns

Implementation Details

File: review-task-execute-command.component.ts

The dialog reads task.project to match user IDs:

• For WO/SO/WAO: Pre-selects the user assigned to the project
• For other roles: Defaults to first available user

Benefits

1. Faster workflow - Correct assignee pre-selected
2. Fewer errors - Users don't accidentally pick wrong person
3. Respects project setup - Uses actual project team assignments

---

Follow-Up Workflow Creation

Added in Revision 1.3 (2026-01-20)

After final approval, optional follow-up workflows can be automatically created:

Follow-Up	Default	Assigned To	Purpose
JSA Preparation	✅ Checked	Contractor Supervisor	Risk assessment for job site
Tool List Preparation	✅ Checked	Contractor Supervisor	Equipment and tool inventory

How It Works

1. Work Owner clicks Approve on ReviewPreWorkProceduresForm
2. Confirmation dialog shows checkboxes for follow-up workflows
3. Both workflows are checked by default
4. User can uncheck to skip creation
5. Selected workflows are created and assigned to Contractor Supervisor

Workflow Chaining

Implementation Details

Configuration is defined via FollowUpWorkflowConfig in the workflow definition.

Developer Reference

See .claude/rules/workflow-implementation.md in the repository root for the full pattern documentation.

---

Role Matrix

Revision 1.0 (2026-01-14) - Initial version

Feature-Level Access

Action	Admin	Purchasing	Work Owner	Safety Officer	Workspace Owner	Contractor
View all tasks	✅	❌	Own only	✅	❌	Assigned only
Create task	❌	❌	✅	❌	❌	❌
Execute commands	❌	Own only	Own only	❌	❌	Own only
View task history	✅	Own only	Own only	✅	❌	Own only
Add notes	❌	Own only	Own only	❌	❌	Own only
Delete task	✅	❌	Own only	❌	❌	❌

Workflow State Access

State	Who Can Act	Available Commands
FillInProjectInfo	Work Owner	Send to Purchasing, Cancel
FillInPurchasingInfo	Purchasing	Submit Back
ReviewPurchasingInfo	Work Owner	Send to Purchasing, Send to Contractor, Cancel
FillInPreWorkProceduresForm	Contractor	Acknowledge Procedures
ReviewPreWorkProceduresForm	Work Owner	Approve, Cancel

Note: ReviewPreWorkProceduresForm was simplified from 4 commands to 2 (Revision 1.3). "Send Back" commands removed because form validation and digital signature verification prevent incomplete approvals.

Form Edit Permissions by State

State	ProjectRegistrationForm	PreWorkProceduresForm
FillInProjectInfo	✅ WorkOwner	-
FillInPurchasingInfo	✅ Purchasing	-
ReviewPurchasingInfo	✅ WorkOwner	-
FillInPreWorkProceduresForm	🔒 Locked	✅ Contractor
ReviewPreWorkProceduresForm	🔒 Locked	🔒 Locked
Approved/Canceled	🔒 Locked	🔒 Locked

Legend:

• ✅ = Can edit
• 🔒 = Read-only (locked)
• Own only = Can only access tasks where user is current assignee
• Assigned only = Can only see tasks assigned to them

Backend Test Report

Location: backend/tests/http/project-registration/ (planned) Status: Test files to be created in Phase 6

API Endpoints

Method	Endpoint	Description	Authorization
POST	/api/tasks/search	Search tasks by type, status	RealmBasic
GET	/api/tasks/get/{id}	Get task details with workflow state	RealmBasic
POST	/api/tasks/createTask	Create new workflow task	RealmBasic
POST	/api/tasks/preExecuteCommand	Validate and prepare command	RealmBasic
POST	/api/tasks/executeCommand	Execute workflow state transition	RealmBasic
POST	/api/tasks/upload/formAttachment	Upload form attachment	RealmBasic
POST	/api/tasks/remove/formAttachment	Remove form attachment	RealmBasic
POST	/api/tasks/saveDocumentForm	Auto-save form data	RealmBasic
POST	/api/tasks/notes/create	Create task note	RealmBasic
PUT	/api/tasks/notes/{noteId}	Update task note	RealmBasic
DELETE	/api/tasks/notes/{noteId}	Delete task note	RealmBasic
POST	/api/tasks/remove	Delete task (Admin/Owner only)	RealmBasic

Workflow-Specific Endpoints

Method	Endpoint	Description	Authorization
GET	/api/projects/searchByPrNo	Search project by PR.No for task creation	ProjectMgmt

Test Coverage (Planned)

Part	Section	Tests	Description
A	Task Creation	6	Create task with project link
A	Task Get	4	Retrieve task with workflow state
B	Standard Path	8	Full workflow: WO → Purchasing → WO → Contractor → WO → Approve
B	Skip Path	6	Optional: WO → Contractor (skip Purchasing)
C	Commands	12	All 6 commands with role validation
D	Form Attachments	4	Upload/download/remove attachments
E	Notes	4	Create/update/delete notes

Frontend Test Report

Location: frontend/e2e/features/project-registration/ (planned) Status: E2E tests to be created in Phase 6

Components

Component	Type	Description
review-task.component.ts	Smart	Main container component
review-task.service.ts	Service	State management (to be migrated to rxResource)
review-task-toolbar.component.ts	Dumb	Command buttons and actions
review-task-form.component.ts	Dumb	Form wrapper with tabs
review-task-workflow.component.ts	Dumb	Workflow visualization (stepper + diagram)
review-task-stepper.component.ts	Dumb	Horizontal workflow stepper
review-task-transaction.component.ts	Dumb	Task history/log table
review-task-note.component.ts	Dumb	Notes section
workflow-svg-viewer.component.ts	Dumb	SVG diagram viewer

Workflow Visualization Components

Component	Purpose
Stepper	Shows workflow progress with circular step indicators
Full Diagram	SVG visualization of complete workflow
State Info Cards	Current state and branch target information

E2E Test Plan (Phase 6)

Test ID	Description
TC-PR-E2E-001	Work Owner creates task from project
TC-PR-E2E-002	Work Owner sends to Purchasing
TC-PR-E2E-003	Purchasing fills PO info and submits
TC-PR-E2E-004	Work Owner reviews and sends to Contractor
TC-PR-E2E-005	Contractor acknowledges procedures
TC-PR-E2E-006	Work Owner approves registration
TC-PR-E2E-007	Work Owner skips Purchasing (when has PO No.)
TC-PR-E2E-008	Stepper shows correct state transitions
TC-PR-E2E-009	Optional step shows dashed border
TC-PR-E2E-010	Transaction log shows all state changes

Manual Test Cases

For comprehensive manual testing documentation, see: Project Registration Test Cases

Test Summary:

• Standard Workflow Path (31 test cases)
• Optional Path - Skip Purchasing (9 test cases)
• Total: 40 test cases

---

Workflow States Reference

For complete workflow documentation including:

• All 9 workflow states with Thai names
• State transition diagram
• Document form mappings
• Form edit permissions matrix

See: Project Registration Workflow

Related Documentation

• Project Settings - Prerequisite: Create projects here first
• Project Registration Workflow - Technical workflow specification
• Work Permit Workflow - Next step after project approval

---

Labels verified against:

• review-task-toolbar.component.ts (command button labels)
• review-task-stepper.component.ts (step labels)
• review-task-transaction.component.ts (log table headers)
• review-task-note.component.ts (notes section)
• project-registration-state-metadata.config.ts (state names)