Initial commit

This commit is contained in:
Zzzz
2026-04-27 18:40:30 +08:00
commit 2120774b05
112 changed files with 12308 additions and 0 deletions
@@ -0,0 +1,13 @@
{"file": ".trellis/spec/backend/index.md", "reason": "Check implementation against backend architecture and expected core modules."}
{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Verify backend file placement and layering."}
{"file": ".trellis/spec/backend/database-guidelines.md", "reason": "Verify schema/DAO choices for login and roles."}
{"file": ".trellis/spec/backend/error-handling.md", "reason": "Verify validation, authentication failure, and unauthorized access handling."}
{"file": ".trellis/spec/backend/logging-guidelines.md", "reason": "Verify logging/error tracing expectations where authentication code warrants it."}
{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Verify backend quality and layer boundary constraints."}
{"file": ".trellis/spec/frontend/index.md", "reason": "Check JSP/CSS frontend stack alignment."}
{"file": ".trellis/spec/frontend/directory-structure.md", "reason": "Verify JSP/static asset placement."}
{"file": ".trellis/spec/frontend/component-guidelines.md", "reason": "Verify JSP form and fragment conventions."}
{"file": ".trellis/spec/frontend/hook-guidelines.md", "reason": "Ensure SPA/hook conventions were not introduced."}
{"file": ".trellis/spec/frontend/state-management.md", "reason": "Verify request/session/form-state handling."}
{"file": ".trellis/spec/frontend/type-safety.md", "reason": "Verify display contracts and validation boundaries."}
{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Verify frontend quality expectations."}
@@ -0,0 +1,13 @@
{"file": ".trellis/spec/backend/index.md", "reason": "Backend architecture overview and pre-development checklist for the JSP + Servlet + MySQL system."}
{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Backend source layout conventions for Servlet, service, DAO, entity, and config files."}
{"file": ".trellis/spec/backend/database-guidelines.md", "reason": "MySQL schema, DAO CRUD, keys, and transaction guidance for login and role persistence."}
{"file": ".trellis/spec/backend/error-handling.md", "reason": "Validation, authentication failure, service failure, and safe Servlet response handling."}
{"file": ".trellis/spec/backend/logging-guidelines.md", "reason": "Guidance for operation logs and exception tracing in authentication-related code."}
{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Layer boundary and backend quality constraints for implementation."}
{"file": ".trellis/spec/frontend/index.md", "reason": "Frontend overview for JSP/CSS presentation served by Servlet/Tomcat."}
{"file": ".trellis/spec/frontend/directory-structure.md", "reason": "JSP, include, static CSS/JS/image placement conventions."}
{"file": ".trellis/spec/frontend/component-guidelines.md", "reason": "JSP fragment, form, table, and reusable UI conventions for login views."}
{"file": ".trellis/spec/frontend/hook-guidelines.md", "reason": "Constraint that React/Vue hooks and SPA conventions should not be introduced."}
{"file": ".trellis/spec/frontend/state-management.md", "reason": "Server-rendered request/session/form state conventions for login flow."}
{"file": ".trellis/spec/frontend/type-safety.md", "reason": "JSP/Servlet validation and JavaBean display contract guidance."}
{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "JSP/CSS quality and UI verification guidance."}
+70
View File
@@ -0,0 +1,70 @@
# brainstorm: start coding
## Goal
Build the initial Java Web project scaffold and a login/permission skeleton for this JSP + Servlet + MySQL library-management system.
## What I already know
* The user asked to start writing code.
* There is no active task before this one.
* The repository currently has Trellis project guidance but no application source code files.
* Existing project specs describe a B/S Java web application using JSP, Servlet, MySQL, Tomcat, and IDEA.
* Backend guidance expects a layered structure: JSP/CSS presentation -> Servlet controller -> Service/business -> DAO -> MySQL.
* Frontend guidance expects JSP/CSS pages, JSP includes or fragments, static assets, and small page scripts when needed.
* The user selected option A: build the Java Web foundation and login/permission skeleton first.
## Assumptions (temporary)
* The desired work is to start building the library-management system rather than editing an existing application.
* Maven is a reasonable default for Java web project scaffolding unless the user prefers plain IDEA/Tomcat project files.
* The first implementation should establish a compilable structure and a minimal login flow rather than complete every business module.
## Open Questions
* None currently blocking.
## Requirements (evolving)
* Follow the existing Trellis backend and frontend specs.
* Keep backend and frontend conventions aligned with JSP + Servlet + MySQL, not SPA frameworks.
* Create or update tests/checks where practical for the selected implementation scope.
* Create the base Java Web project structure for Tomcat deployment.
* Add a login/permission skeleton covering administrator, librarian, and reader roles.
* Add model/entity, DAO, service, servlet/controller, JSP, and static asset structure needed for the login slice.
* Include database initialization or schema notes for user/role data needed by the skeleton.
* Keep business logic layered: Servlet parameter/session handling, Service authentication and role checks, DAO persistence access.
* Include safe error handling for invalid credentials, missing parameters, and unauthorized access.
## Acceptance Criteria (evolving)
* [x] The selected first module or feature is explicitly confirmed.
* [ ] The implementation follows the documented JSP + Servlet + MySQL layered architecture.
* [ ] A fresh checkout has recognizable Java Web/Tomcat project structure and build configuration.
* [ ] Login page submits credentials to a Servlet controller and displays validation/authentication failures safely.
* [ ] Authentication logic is represented through service and DAO boundaries rather than embedded in JSP.
* [ ] Session state stores the authenticated user and role in a controlled way.
* [ ] Basic role/permission constants or helpers exist for administrator, librarian, and reader.
* [ ] SQL/schema guidance exists for the minimal account/role tables needed by login.
* [ ] Lint, type-check, compile, or equivalent project validation is run where available.
## Definition of Done (team quality bar)
* Tests added/updated where appropriate.
* Lint / typecheck / compile / CI-equivalent checks are green where available.
* Docs/notes updated if behavior changes.
* Rollout/rollback considered if risky.
## Out of Scope (explicit)
* Choosing React, Vue, TypeScript, SPA routing, or frontend hook/state-library conventions unless the user explicitly changes the stack.
* Implementing full book, reader, borrowing, statistics, backup, or logging modules beyond placeholders needed for navigation or role skeleton.
* Implementing production-grade password reset, remember-me, MFA, or external identity provider integration.
## Technical Notes
* Relevant spec indexes: `.trellis/spec/backend/index.md`, `.trellis/spec/frontend/index.md`.
* Backend pre-development checklist includes directory structure, database, error handling, logging, and quality guidelines.
* Frontend pre-development checklist includes directory structure, JSP component guidelines, state management, type safety, and quality guidelines.
* Codebase retrieval on 2026-04-27 found no application source code and surfaced the project specs as the main implementation context.
* Spec indexes reference `.trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md`, but that file is absent in the current workspace, so context curation uses only present spec files.
@@ -0,0 +1,26 @@
{
"id": "start-coding",
"name": "start-coding",
"title": "brainstorm: start coding",
"description": "",
"status": "in_progress",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "Zzzz",
"assignee": "Zzzz",
"createdAt": "2026-04-27",
"completedAt": null,
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1,5 @@
{"file": ".trellis/spec/guides/index.md", "reason": "Shared Trellis thinking guide index for reviewing bootstrap spec quality"}
{"file": ".trellis/spec/guides/code-reuse-thinking-guide.md", "reason": "Shared guidance for checking that specs avoid duplicated or invented conventions"}
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Shared guidance for reviewing future backend/frontend boundary notes"}
{"file": ".trellis/tasks/00-bootstrap-guidelines/research/repo-scan.md", "reason": "Repository scan findings to verify specs reflect the actual empty app workspace"}
{"file": ".trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md", "reason": "Developer-provided architecture and module decisions to verify against backend/frontend specs"}
@@ -0,0 +1,5 @@
{"file": ".trellis/spec/guides/index.md", "reason": "Shared Trellis thinking guide index for documenting current reality without inventing conventions"}
{"file": ".trellis/spec/guides/code-reuse-thinking-guide.md", "reason": "Shared guidance for avoiding duplicated or invented conventions while bootstrapping specs"}
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Shared guidance for future backend/frontend cross-layer decisions"}
{"file": ".trellis/tasks/00-bootstrap-guidelines/research/repo-scan.md", "reason": "Repository scan findings showing no application source conventions currently exist"}
{"file": ".trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md", "reason": "Developer-provided JSP/Servlet/MySQL/Tomcat architecture, modules, and frontend workflow decisions"}
@@ -0,0 +1,140 @@
# Bootstrap Task: Fill Project Development Guidelines
**You (the AI) are running this task. The developer does not read this file.**
The developer just ran `trellis init` on this project for the first time.
`.trellis/` now exists with empty spec scaffolding, and this task has been
set as their current task. They'll open their AI tool, run `/trellis:continue`,
and you'll land here.
**Your job**: help them populate `.trellis/spec/` with the team's real
coding conventions. Every future AI session — this project's
`trellis-implement` and `trellis-check` sub-agents — auto-loads spec files
listed in per-task jsonl manifests. Empty spec = sub-agents write generic
code. Real spec = sub-agents match the team's actual patterns.
Don't dump instructions. Open with a short greeting, figure out if the repo
has any existing convention docs (CLAUDE.md, .cursorrules, etc.), and drive
the rest conversationally.
---
## Status (update the checkboxes as you complete each item)
- [x] Record developer-provided JSP + Servlet + MySQL + Tomcat project decisions
- [x] Fill backend guidelines with the layered B/S architecture, DAO, MySQL, service, controller, logging, and permission conventions
- [x] Fill frontend guidelines with JSP/CSS presentation conventions and the image-to-JSP restoration workflow
- [x] Preserve the note that no application source code exists yet; examples are illustrative conventions until real files are introduced
---
## Spec files to populate
### Backend guidelines
| File | What to document |
|------|------------------|
| `.trellis/spec/backend/directory-structure.md` | JSP/Servlet Java web app layering: controller, service, DAO, entity, filter, util |
| `.trellis/spec/backend/database-guidelines.md` | MySQL core tables, DAO CRUD, keys, query patterns, integrity constraints |
| `.trellis/spec/backend/error-handling.md` | Servlet validation, service failures, DAO/database exceptions, safe user results |
| `.trellis/spec/backend/logging-guidelines.md` | System logs, key operations, backup events, exception tracing |
| `.trellis/spec/backend/quality-guidelines.md` | Layer boundaries, permission checks, validation, documentation-only checks |
### Frontend guidelines
| File | What to document |
|------|------------------|
| `.trellis/spec/frontend/directory-structure.md` | JSP pages, WEB-INF organization, shared fragments, static CSS/JS/images |
| `.trellis/spec/frontend/component-guidelines.md` | JSP includes/fragments, forms, tables, reports, shared CSS conventions |
| `.trellis/spec/frontend/hook-guidelines.md` | Explicit absence of React/Vue hook conventions unless introduced later |
| `.trellis/spec/frontend/state-management.md` | Servlet/JSP request, session, database, and form state |
| `.trellis/spec/frontend/type-safety.md` | JSP/Servlet data contracts, JavaBean display, server-side validation |
| `.trellis/spec/frontend/quality-guidelines.md` | Image-first design and faithful JSP/CSS restoration workflow |
### Thinking guides (already populated)
`.trellis/spec/guides/` contains general thinking guides pre-filled with
best practices. Customize only if something clearly doesn't fit this project.
---
## How to fill the spec
### Step 1: Import from existing convention files first (preferred)
Search the repo for existing convention docs. If any exist, read them and
extract the relevant rules into the matching `.trellis/spec/` files —
usually much faster than documenting from scratch.
| File / Directory | Tool |
|------|------|
| `CLAUDE.md` / `CLAUDE.local.md` | Claude Code |
| `AGENTS.md` | Codex / Claude Code / agent-compatible tools |
| `.cursorrules` | Cursor |
| `.cursor/rules/*.mdc` | Cursor (rules directory) |
| `.windsurfrules` | Windsurf |
| `.clinerules` | Cline |
| `.roomodes` | Roo Code |
| `.github/copilot-instructions.md` | GitHub Copilot |
| `.vscode/settings.json``github.copilot.chat.codeGeneration.instructions` | VS Code Copilot |
| `CONVENTIONS.md` / `.aider.conf.yml` | aider |
| `CONTRIBUTING.md` | General project conventions |
| `.editorconfig` | Editor formatting rules |
### Step 2: Analyze the codebase for anything not covered by existing docs
Scan real code to discover patterns. Before writing each spec file:
- Find 2-3 real examples of each pattern in the codebase.
- Reference real file paths (not hypothetical ones).
- Document anti-patterns the team clearly avoids.
### Step 3: Document reality, not ideals
**Critical**: write what the code *actually does*, not what it should do.
Sub-agents match the spec, so aspirational patterns that don't exist in the
codebase will cause sub-agents to write code that looks out of place.
If the team has known tech debt, document the current state — improvement
is a separate conversation, not a bootstrap concern.
---
## Quick explainer of the runtime (share when they ask "why do we need spec at all")
- Every AI coding task spawns two sub-agents: `trellis-implement` (writes
code) and `trellis-check` (verifies quality).
- Each task has `implement.jsonl` / `check.jsonl` manifests listing which
spec files to load.
- The platform hook auto-injects those spec files + the task's `prd.md`
into every sub-agent prompt, so the sub-agent codes/reviews per team
conventions without anyone pasting them manually.
- Source of truth: `.trellis/spec/`. That's why filling it well now pays
off forever.
---
## Completion
When the developer confirms the checklist items above are done with real
examples (not placeholders), guide them to run:
```bash
python3 ./.trellis/scripts/task.py finish
python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
```
After archive, every new developer who joins this project will get a
`00-join-<slug>` onboarding task instead of this bootstrap task.
---
## Suggested opening line
"Welcome to Trellis! Your init just set me up to help you fill the project
spec — a one-time setup so every future AI session follows the team's
conventions instead of writing generic code. Before we start, do you have
any existing convention docs (CLAUDE.md, .cursorrules, CONTRIBUTING.md,
etc.) I can pull from, or should I scan the codebase from scratch?"
@@ -0,0 +1,73 @@
# Project Requirements From Developer
## Source
Captured on 2026-04-27 during the Trellis bootstrap-guidelines task from
developer-provided project facts.
## Architecture And Stack
- The system uses B/S architecture with a typical layered design.
- The application stack is JSP + Servlet, MySQL, Tomcat, developed in IDEA.
- The layers are presentation, controller, business/service, DAO, and data.
## Data Layer
MySQL is the data layer and stores:
- Book information.
- Book category information.
- Reader information.
- Borrowing records.
- Administrator information.
- Role and permission information.
- System logs.
Core entity tables should include book information, book categories, reader
information, borrowing records, administrators, role permissions, and system
logs. Use primary keys and foreign keys to preserve data integrity.
## DAO Layer
The data access layer uses DAO classes to perform database CRUD. DAOs should own
SQL/database access concerns and should not contain presentation or business
workflow logic.
## Business And Service Layer
The service layer handles:
- Book warehousing/intake.
- Borrowing and returning.
- Inventory status updates.
- Overdue statistics.
- Permission checks.
## Controller Layer
Servlet controllers handle request dispatch, parameter validation, and result
return. Controllers should coordinate request/response flow and call services
for business behavior.
## Presentation Layer
JSP/CSS pages handle page display and user interaction.
The frontend approach is image-first: UI should be designed or generated as
images first, then JSP/CSS pages should restore and implement the image
faithfully.
## Core Modules
- Login and permission management for administrator, librarian, and reader
roles.
- Book information management for create, update, delete, category
maintenance, and inventory status.
- Reader information management for profiles, borrowing eligibility, and
contact information.
- Borrowing and return management for borrow, return, renew, overdue handling,
and automatic collection status updates.
- Book search and statistics for combined search by title, author, category,
and ID, plus borrowing rankings, inventory reports, and overdue reports.
- System maintenance and logs for key operation logs, data backup support, and
exception tracing.
@@ -0,0 +1,42 @@
# Repository Scan
## Scope
Scanned the workspace on 2026-04-27 while bootstrapping Trellis project guidelines.
## Findings
- The workspace root is `/mnt/d/document/mzh`.
- `git status --short --branch` from the workspace root fails with `fatal: not a git repository`; no git metadata is available at this level.
- The only root-level convention file discovered by the bootstrap search is `AGENTS.md`.
- `AGENTS.md` contains Trellis-managed instructions only. It does not describe backend or frontend implementation conventions.
- No app package manifests were found at the workspace root, including `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, or common lockfiles.
- No application source files were found outside Trellis/Codex scaffolding at shallow workspace depth. The current files are Trellis workflow/config/scripts/specs/tasks and Codex agent configuration.
- At initial scan time, existing `.trellis/spec/backend/*.md` and
`.trellis/spec/frontend/*.md` files were unpopulated scaffold templates; they
have since been populated during this bootstrap task.
## Later Developer Decision
The source scan remains accurate as a scan of files on disk, but it no longer
means the project stack lacks a decision. The developer later provided explicit
project requirements in
`.trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md`.
Future agents should combine both facts: application source code does not exist
yet, and the intended stack is JSP + Servlet + MySQL + Tomcat with a layered
B/S architecture.
## Source-Code Evidence Boundary
Because there is no backend or frontend application code in this workspace yet,
the bootstrap specs should distinguish source-code evidence from
developer-provided decisions:
- Backend and frontend conventions are not evidenced by source files yet.
- The project stack and intended architecture are established by the developer:
B/S layered JSP + Servlet + MySQL + Tomcat development in IDEA.
- Future agents should follow the populated `.trellis/spec/` files and
`.trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md`
for stack, module, table, and workflow decisions.
- When new backend/frontend code is introduced, agents should update the
matching `.trellis/spec/` files with concrete examples from that code.
@@ -0,0 +1,29 @@
{
"id": "00-bootstrap-guidelines",
"name": "00-bootstrap-guidelines",
"title": "Bootstrap Guidelines",
"description": "Fill in project development guidelines for AI agents",
"status": "completed",
"dev_type": "docs",
"scope": null,
"package": null,
"priority": "P1",
"creator": "Zzzz",
"assignee": "Zzzz",
"createdAt": "2026-04-27",
"completedAt": "2026-04-27",
"branch": null,
"base_branch": null,
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [
".trellis/spec/backend/",
".trellis/spec/frontend/"
],
"notes": "First-time setup task created by trellis init (fullstack project)",
"meta": {}
}