From 36ae290cb69876c1d4fd596d30dbe15475902633 Mon Sep 17 00:00:00 2001 From: kl Date: Tue, 14 Apr 2026 07:54:42 +0800 Subject: [PATCH 1/2] Add AI-friendly repository guide --- AGENTS.md | 230 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..40466059 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,230 @@ +# AGENTS.md + +This document is for coding agents and automation tools working in this repository. + +## Project Overview + +- Project: `kkFileView` +- Stack: Spring Boot + Freemarker + Redis/Redisson (optional) + JODConverter + front-end preview pages +- Main module: `server` +- Default local URL: `http://127.0.0.1:8012/` +- Production demo: `https://file.kkview.cn/` + +This repository is a document preview service. Most user-facing work falls into one of these areas: + +1. preview routing and file-type dispatch +2. conversion pipelines for Office / PDF / CAD / archives / images +3. Freemarker preview templates under `server/src/main/resources/web` +4. CI, E2E fixtures, and production deployment automation + +## Repository Layout + +- `server/` + Main application code, templates, config, packaged artifacts +- `server/src/main/java/cn/keking/` + Core Java application code +- `server/src/main/resources/web/` + Freemarker preview templates +- `server/src/main/resources/static/` + Front-end static assets used by preview pages +- `server/src/main/config/` + Main runtime config files +- `server/src/main/bin/` + Local startup/dev scripts +- `tests/e2e/` + Playwright-based end-to-end tests and fixtures +- `.github/workflows/` + CI and deployment workflows +- `.github/scripts/` + Windows production deployment scripts over WinRM + +## Key Entry Points + +- App entry: + - `server/src/main/java/cn/keking/ServerMain.java` +- Preview controller: + - `server/src/main/java/cn/keking/web/controller/OnlinePreviewController.java` +- File attribute parsing / request handling: + - `server/src/main/java/cn/keking/service/FileHandlerService.java` +- Office preview flow: + - `server/src/main/java/cn/keking/service/impl/OfficeFilePreviewImpl.java` +- PDF preview flow: + - `server/src/main/java/cn/keking/service/impl/PdfFilePreviewImpl.java` +- Archive extraction: + - `server/src/main/java/cn/keking/service/CompressFileReader.java` + +## Important Templates + +- `server/src/main/resources/web/compress.ftl` + Archive directory/tree preview page +- `server/src/main/resources/web/pdf.ftl` + PDF preview container page +- `server/src/main/resources/web/picture.ftl` + Single image preview page +- `server/src/main/resources/web/officePicture.ftl` + Office/PDF image-mode preview page +- `server/src/main/resources/web/officeweb.ftl` + Front-end xlsx/html preview page + +When debugging UX issues, inspect the exact template selected by the preview flow first. Do not assume two similar preview pages share the same CSS or behavior. + +## Local Development + +### Recommended dev mode + +Use: + +```bash +./server/src/main/bin/dev.sh +``` + +This runs Spring Boot with resource hot reload using: + +- `spring-boot:run` +- `-Dspring-boot.run.addResources=true` +- `server/src/main/config/application.properties` + +For front-end template or CSS/JS edits, prefer `dev.sh` over rebuilding jars repeatedly. + +### Jar build + +```bash +mvn -q -pl server -DskipTests package +``` + +### Main test command used in CI + +```bash +mvn -B package -Dmaven.test.skip=true --file pom.xml +``` + +## Configuration Notes + +Primary runtime config: + +- `server/src/main/config/application.properties` + +Test config: + +- `server/src/main/config/test.properties` + +Be careful: some environments may explicitly start the app with `test.properties` instead of `application.properties`. Always verify the actual startup command before assuming which config file is active. + +Examples of config that commonly affects behavior: + +- `office.preview.type` +- `office.preview.switch.disabled` +- `trust.host` +- `not.trust.host` +- `file.upload.disable` + +## Preview Behavior Notes + +- Office files can render in `pdf` mode or `image` mode. +- PDF preview uses `pdf.ftl`. +- Single images use `picture.ftl`. +- Office image-mode previews use `officePicture.ftl`. +- Archive previews are not simple file lists; they can load nested previews via the archive UI in `compress.ftl`. + +When changing preview defaults, verify both: + +1. server-side default config +2. front-end mode-switch links/buttons + +## Archive Preview Notes + +Archive preview is a sensitive area because it combines: + +- directory tree generation +- extraction to disk +- nested preview URL construction +- inline iframe loading + +If an archive-contained Office file gets stuck on loading: + +1. verify the extracted file on disk is not corrupted +2. verify conversion output exists +3. verify the preview template points to the correct generated artifact +4. verify the running Office manager / LibreOffice process is healthy + +Do not assume “loading forever” is a front-end issue. + +## Testing + +### Targeted Java tests + +Example targeted test: + +```bash +mvn -q -pl server -Dtest=PdfViewerCompatibilityTests test +``` + +### E2E tests + +See: + +- `tests/e2e/README.md` + +PR E2E currently covers: + +- common preview smoke tests +- Office smoke tests +- archive smoke tests +- basic security and performance checks + +## CI / Deployment + +### CI + +- `maven.yml` + - builds on `push` to `master` + - builds on PRs targeting `master` +- `pr-e2e-mvp.yml` + - runs E2E on PRs to `master` + +### Production deployment + +- `master-auto-deploy.yml` + - triggers on push to `master` + - deploys to Windows over WinRM + +Deployment script: + +- `.github/scripts/remote_windows_deploy.ps1` + +Important operational detail: + +- the Windows server may launch the app from `bin/startup.bat` +- that startup script can point at a specific config file such as `..\config\test.properties` + +If a production config change “does not take effect”, inspect the actual startup command on the server first. + +## Working Conventions For Agents + +- Prefer minimal, targeted changes over wide refactors. +- Inspect the active preview template before editing CSS. +- Verify whether behavior is controlled by config, back-end routing, or front-end template logic before changing code. +- For production/debug tasks, distinguish clearly between: + - repository source defaults + - deployed server config + - runtime process arguments +- When changing defaults, mention whether the change affects: + - local dev only + - repository default config + - deployed server config + - existing query-param overrides + +## Suggested Validation Checklist + +For preview-related changes, validate as many of these as apply: + +1. target URL returns `200` +2. selected template is the expected one +3. generated intermediate artifacts exist when required +4. target UI element or style change is actually present in rendered HTML +5. targeted Java test passes +6. relevant E2E path is still compatible + +## Non-Goals + +This file is not a replacement for user-facing product documentation. Keep it focused on helping coding agents navigate the codebase and make correct changes faster. From 1c6691d785c2cd22044546a7aae23fd23decff17 Mon Sep 17 00:00:00 2001 From: kl Date: Tue, 14 Apr 2026 08:06:52 +0800 Subject: [PATCH 2/2] Clarify config defaults in AGENTS guide --- AGENTS.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 40466059..e9acda25 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,15 +100,15 @@ mvn -B package -Dmaven.test.skip=true --file pom.xml ## Configuration Notes -Primary runtime config: +Primary runtime config used by the scripts and defaults committed in this repository: - `server/src/main/config/application.properties` -Test config: +Optional environment-specific config: - `server/src/main/config/test.properties` -Be careful: some environments may explicitly start the app with `test.properties` instead of `application.properties`. Always verify the actual startup command before assuming which config file is active. +Be careful: the repository defaults point at `application.properties`. If a deployment environment explicitly starts the app with `test.properties`, treat that as an environment-specific override rather than the repository default. Always verify the actual startup command before assuming which config file is active. Examples of config that commonly affects behavior: @@ -194,10 +194,10 @@ Deployment script: Important operational detail: -- the Windows server may launch the app from `bin/startup.bat` -- that startup script can point at a specific config file such as `..\config\test.properties` +- the committed `bin/startup.bat` in this repo points at `..\config\application.properties` +- if production uses a different config file, treat that as an out-of-repo server override rather than a repository default -If a production config change “does not take effect”, inspect the actual startup command on the server first. +If a production config change “does not take effect”, inspect the actual startup command or deployed `startup.bat` on the server first and verify which config file path it is using. ## Working Conventions For Agents