Initial commit
This commit is contained in:
Zzzz
@@ -0,0 +1,52 @@
|
||||
# Component Guidelines
|
||||
|
||||
> JSP fragment, form, table, and reusable UI conventions.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This project uses JSP-based presentation, not a component framework. Treat JSP
|
||||
includes, fragments, tag files, form layouts, tables, and shared CSS classes as
|
||||
the reusable UI units.
|
||||
|
||||
---
|
||||
|
||||
## JSP Includes And Fragments
|
||||
|
||||
- Use shared fragments for repeated layout pieces such as header, navigation,
|
||||
sidebar, footer, pagination, and message banners.
|
||||
- Prefer `.jspf` includes or JSP tag files once the project chooses one
|
||||
pattern; document the actual paths after implementation.
|
||||
- Keep fragments presentation-focused. They should not open database
|
||||
connections or call DAOs.
|
||||
|
||||
---
|
||||
|
||||
## Forms
|
||||
|
||||
- Forms should post to Servlet controller endpoints, not directly to DAOs or
|
||||
JSP-only handlers.
|
||||
- Render validation messages from request attributes set by controllers.
|
||||
- Preserve user-entered values on validation failure where practical.
|
||||
- Use clear labels, required-field indicators, and server-side validation for
|
||||
book, reader, borrowing, login, and permission forms.
|
||||
|
||||
---
|
||||
|
||||
## Tables And Reports
|
||||
|
||||
- Use consistent table patterns for book lists, reader lists, borrowing
|
||||
records, rankings, inventory reports, overdue reports, and system logs.
|
||||
- Include stable empty states and pagination or filtering controls when lists
|
||||
can grow.
|
||||
- Keep search forms aligned with supported filters: title, author, category,
|
||||
and book ID.
|
||||
|
||||
---
|
||||
|
||||
## Styling
|
||||
|
||||
Implement JSP/CSS pages to faithfully restore the approved image design. Prefer
|
||||
semantic class names tied to page structure or reusable UI roles. Avoid adding a
|
||||
frontend component framework unless explicitly introduced later.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Directory Structure
|
||||
|
||||
> JSP page and static asset organization for the presentation layer.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Future frontend code should be JSP/CSS rendered by the Servlet/Tomcat
|
||||
application. There is no application source tree yet; the paths below are
|
||||
illustrative conventions for the first implementation.
|
||||
|
||||
---
|
||||
|
||||
## Suggested Layout
|
||||
|
||||
```text
|
||||
src/main/webapp/
|
||||
WEB-INF/jsp/
|
||||
common/ Shared JSP fragments such as header.jspf
|
||||
auth/ Login and permission pages
|
||||
books/ Book list, form, detail, category pages
|
||||
readers/ Reader list, form, detail pages
|
||||
borrowing/ Borrow, return, renew, overdue pages
|
||||
statistics/ Search, ranking, inventory, overdue reports
|
||||
maintenance/ System logs, backup, exception trace pages
|
||||
static/
|
||||
css/ Page and shared styles
|
||||
js/ Small page scripts when needed
|
||||
images/ Designed/generated UI images and static assets
|
||||
```
|
||||
|
||||
JSPs that should not be accessed directly belong under `WEB-INF/jsp/` and are
|
||||
rendered through Servlet forwards. Public static files belong under `static/`.
|
||||
|
||||
---
|
||||
|
||||
## Page Naming
|
||||
|
||||
Use module-oriented JSP names such as `books/list.jsp`, `books/form.jsp`,
|
||||
`readers/detail.jsp`, `borrowing/overdue.jsp`, and
|
||||
`maintenance/system-logs.jsp`. Match Servlet dispatch paths once controllers
|
||||
exist.
|
||||
|
||||
---
|
||||
|
||||
## Static Assets
|
||||
|
||||
Keep CSS in `static/css/`, small browser scripts in `static/js/`, and
|
||||
image-first design references or exported assets in `static/images/` once the
|
||||
application tree exists. Do not create React/Vue component directories or SPA
|
||||
asset conventions unless the stack changes.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Hook Guidelines
|
||||
|
||||
> Hook conventions for this frontend.
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
There are no React, Vue, or hook-based frontend conventions in this project.
|
||||
The established frontend approach is JSP/CSS rendered by Servlets on Tomcat.
|
||||
|
||||
Do not introduce React hooks, Vue composables, SPA lifecycle hooks, client-side
|
||||
state hooks, or hook-style data fetching unless the developer explicitly changes
|
||||
the stack later.
|
||||
|
||||
---
|
||||
|
||||
## JSP Alternative
|
||||
|
||||
For reusable presentation behavior, use JSP includes/fragments, tag files if
|
||||
introduced, request attributes, session attributes for authenticated identity,
|
||||
and small page scripts only when server-rendered JSP cannot handle the
|
||||
interaction cleanly.
|
||||
|
||||
---
|
||||
|
||||
## Future Updates
|
||||
|
||||
If a JavaScript framework is explicitly introduced later, replace this file
|
||||
with concrete conventions from the new source code and update the frontend
|
||||
index status at the same time.
|
||||
@@ -0,0 +1,57 @@
|
||||
# Frontend Development Guidelines
|
||||
|
||||
> Frontend conventions for the JSP/CSS presentation layer.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The developer has established a JSP-based presentation layer served by a
|
||||
Servlet/Tomcat application. Frontend work should use JSP, JSP includes or
|
||||
fragments, CSS, static images, and small page scripts when needed. Do not assume
|
||||
React, Vue, frontend hooks, SPA state libraries, or TypeScript conventions
|
||||
unless the developer explicitly introduces them later.
|
||||
|
||||
The frontend workflow is image-first: UI should be designed or generated as
|
||||
images first, then JSP/CSS pages should restore the design faithfully.
|
||||
|
||||
---
|
||||
|
||||
## Guidelines Index
|
||||
|
||||
| Guide | Description | Status |
|
||||
|-------|-------------|--------|
|
||||
| [Directory Structure](./directory-structure.md) | JSP pages, includes, and static assets | Project decision documented |
|
||||
| [Component Guidelines](./component-guidelines.md) | JSP fragments, forms, tables, and reusable UI | Project decision documented |
|
||||
| [Hook Guidelines](./hook-guidelines.md) | No React/Vue hook conventions unless introduced later | Project decision documented |
|
||||
| [State Management](./state-management.md) | Server-rendered request/session/form state | Project decision documented |
|
||||
| [Quality Guidelines](./quality-guidelines.md) | Image-to-JSP restoration and UI checks | Project decision documented |
|
||||
| [Type Safety](./type-safety.md) | JSP/Servlet validation and JavaBean display contracts | Project decision documented |
|
||||
|
||||
---
|
||||
|
||||
## Pre-Development Checklist
|
||||
|
||||
Before frontend implementation, read:
|
||||
|
||||
- `.trellis/spec/frontend/directory-structure.md`
|
||||
- `.trellis/spec/frontend/component-guidelines.md`
|
||||
- `.trellis/spec/frontend/hook-guidelines.md`
|
||||
- `.trellis/spec/frontend/state-management.md`
|
||||
- `.trellis/spec/frontend/type-safety.md`
|
||||
- `.trellis/spec/frontend/quality-guidelines.md`
|
||||
- `.trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md`
|
||||
|
||||
---
|
||||
|
||||
## Evidence
|
||||
|
||||
- `.trellis/tasks/00-bootstrap-guidelines/research/repo-scan.md` records that
|
||||
no application source code exists yet.
|
||||
- `.trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md`
|
||||
records the developer-provided JSP presentation approach and image-to-JSP
|
||||
workflow.
|
||||
|
||||
---
|
||||
|
||||
**Language**: All documentation should be written in **English**.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Quality Guidelines
|
||||
|
||||
> Frontend quality constraints for JSP/CSS pages.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Frontend work should implement JSP/CSS pages that match the approved
|
||||
image-first design and preserve the Servlet/JSP layered architecture.
|
||||
|
||||
---
|
||||
|
||||
## Image-To-JSP Workflow
|
||||
|
||||
1. Design or generate the UI as images first.
|
||||
2. Use the approved image as the visual reference for JSP/CSS implementation.
|
||||
3. Restore layout, spacing, typography, color, table density, and form states
|
||||
faithfully in JSP/CSS.
|
||||
4. Preserve the image assets or references in the application assets area once
|
||||
the source tree exists.
|
||||
5. Compare the implemented page against the source image before considering UI
|
||||
work complete.
|
||||
|
||||
---
|
||||
|
||||
## Required Patterns
|
||||
|
||||
- JSP pages focus on display and user interaction.
|
||||
- Forms submit to Servlet controllers and render server-provided validation
|
||||
messages.
|
||||
- Tables and reports support scanning for books, readers, borrowing records,
|
||||
rankings, inventory, overdue data, and system logs.
|
||||
- Navigation should reflect role permissions for administrator, librarian, and
|
||||
reader users.
|
||||
- Keep CSS and small scripts in static assets rather than inline unless there
|
||||
is a local reason.
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns
|
||||
|
||||
- Do not introduce React, Vue, SPA routing, hook/state conventions, or
|
||||
TypeScript tooling without an explicit stack change.
|
||||
- Do not implement UI only from text descriptions when an approved image
|
||||
reference exists.
|
||||
- Do not put SQL, DAO calls, or business workflows in JSP pages.
|
||||
- Do not rely only on browser validation for protected workflows.
|
||||
|
||||
---
|
||||
|
||||
## Review Checklist
|
||||
|
||||
- Does the JSP/CSS page visibly match the approved image design?
|
||||
- Are forms, tables, empty states, errors, and permission-specific navigation
|
||||
handled?
|
||||
- Are JSPs rendered through Servlet controllers where access control or page
|
||||
data is required?
|
||||
- Are accessibility basics preserved with labels, headings, focus order, and
|
||||
readable contrast?
|
||||
@@ -0,0 +1,42 @@
|
||||
# State Management
|
||||
|
||||
> State conventions for server-rendered JSP pages.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This project does not use React/Vue state libraries or SPA stores. State should
|
||||
flow through the Servlet/JSP request cycle unless a future explicit decision
|
||||
changes the frontend architecture.
|
||||
|
||||
---
|
||||
|
||||
## State Categories
|
||||
|
||||
- Request attributes: page data, validation errors, form echoes, table rows,
|
||||
reports, and short result messages for a single render.
|
||||
- Session attributes: authenticated user identity, role, permission summary,
|
||||
and short-lived flash-style messages when redirects are used.
|
||||
- Database state: books, categories, readers, borrowing records,
|
||||
administrators, permissions, and logs stored in MySQL through services/DAOs.
|
||||
- Form state: submitted by browser forms to Servlets and re-rendered from
|
||||
validated request attributes on failure.
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
- Keep business state in MySQL, not hidden fields or long-lived browser state.
|
||||
- Keep permission decisions server-side.
|
||||
- Use redirects after successful mutations such as create/update/delete,
|
||||
borrow, return, renew, and permission changes.
|
||||
- Do not add Redux, Pinia, client caches, or SPA routing state unless the
|
||||
developer explicitly introduces that stack later.
|
||||
|
||||
---
|
||||
|
||||
## Page Scripts
|
||||
|
||||
Small JavaScript can improve interaction, such as confirm dialogs or local form
|
||||
helpers, but server-side validation and service-layer rules remain mandatory.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Type Safety
|
||||
|
||||
> Display and validation contracts for JSP/Servlet frontend work.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The frontend is JSP/CSS, not TypeScript. Type safety comes from Java entities,
|
||||
Servlet parameter parsing, service contracts, DAO results, and careful JSP
|
||||
rendering.
|
||||
|
||||
---
|
||||
|
||||
## JSP Data Contracts
|
||||
|
||||
- Servlets should set clearly named request attributes before forwarding to
|
||||
JSPs, such as `books`, `reader`, `borrowRecords`, `errors`, and `message`.
|
||||
- JSP pages should render JavaBean/entity properties through JSP EL or JSTL
|
||||
rather than embedding business Java code.
|
||||
- Keep attribute names stable between Servlet controllers and JSP pages; update
|
||||
both sides together when a contract changes.
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
- Parse and validate IDs, dates, enum/status values, and required strings in
|
||||
Servlet controllers before calling services.
|
||||
- Services should re-check business rules such as borrowing eligibility,
|
||||
inventory availability, overdue status, and permission access.
|
||||
- JSP pages should display validation messages but should not be the only place
|
||||
validation occurs.
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns
|
||||
|
||||
- Do not claim TypeScript, generated API types, React prop types, or Vue type
|
||||
conventions exist unless the stack changes.
|
||||
- Do not use JSP scriptlets for business logic.
|
||||
- Do not let JSP pages infer database schema details directly.
|
||||
Reference in New Issue
Block a user