From 97b413dd50d4be8d6797d4e451b80c6c5369732c Mon Sep 17 00:00:00 2001 From: xfy Date: Thu, 25 Jun 2026 13:39:28 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20AGENTS.md=20?= =?UTF-8?q?=E4=B8=8E=E5=BD=93=E5=89=8D=E4=BB=A3=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 修正与代码不符的过时描述： - server functions 分布补全 comments/ 与 settings.rs（原仅列 auth + posts） - rate_limit tiers 从 3 个更正为 5 个（strict/upload/image/comment/unknown） - Rust 测试数 392 → 402 补全 lightbox 子项目文档（新增独立章节，说明其经 Dioxus.toml 全局注入而非 wasm-bindgen 桥接的差异），并在 Build Artifacts 与 make test 描述中补上 lightbox 产物与测试（23 tests）。 --- AGENTS.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bda0359..2cbd801 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ make build # build-editor → highlight-css → tailwindcss → dx build make build-linux # same as build but targets x86_64-unknown-linux-musl make css # one-shot CSS make css-watch # watch mode -make test # cargo test +make test # cargo test + vitest (tiptap-editor + lightbox libs) make clean # cargo clean + rm public/style.css ``` @@ -88,7 +88,7 @@ Dioxus 0.7 fullstack project with **two independent gates** — the most common The server exposes two distinct API patterns: -1. **Dioxus server functions** (`#[server(Name, "/api")]` in `src/api/`) — auto-routed, callable from both client and server Rust. Spread across `src/api/auth.rs` and `src/api/posts/`. +1. **Dioxus server functions** (`#[server(Name, "/api")]` in `src/api/`) — auto-routed, callable from both client and server Rust. Spread across `src/api/auth.rs`, `src/api/posts/`, `src/api/comments/`, and `src/api/settings.rs`. 2. **Axum routes** (registered in `src/main.rs`) — manual `axum::Router` for endpoints that don't fit the server-function model: - `POST /api/upload` — image upload (multipart, auth-required, rate-limited) @@ -99,10 +99,12 @@ The server exposes two distinct API patterns: ``` src/api/ — server functions + Axum handlers auth.rs — login, register, session validation + comments/ — comment CRUD + approval/spam/trash server functions markdown.rs — Markdown→HTML rendering (pulldown-cmark + ammonia sanitization) image.rs — image serving with processing pipeline + disk+memory cache upload.rs — image upload, auto-converts to WebP - rate_limit.rs — governor-based rate limiting (3 tiers: strict/upload/image) + rate_limit.rs — governor-based rate limiting (5 tiers: strict/upload/image/comment/unknown) + settings.rs — site settings server functions (trash retention, etc.) slug.rs — URL slug generation posts/ — CRUD server functions for blog posts src/auth/ — password hashing (Argon2) + session token management @@ -129,6 +131,16 @@ Rich-text editor in `libs/tiptap-editor/`, built as an IIFE library exposing `wi Do not edit `public/tiptap/` — they are build artifacts. +## Lightbox Subproject + +Image lightbox (click-to-zoom) in `libs/lightbox/`, built as an IIFE library. Unlike the Tiptap editor, it is **not** wired through wasm-bindgen; the built `lightbox.js` is injected globally via `Dioxus.toml` (`script = ["/lightbox/lightbox.js"]`), and `src/components/post/post_content.rs` sets `window.__lightboxSelectors` (e.g. `['.post-content', '.entry-cover']`) before the script loads. The IIFE tail reads this config and self-initializes; `post_content.rs` also calls it directly as a fallback if the script was already loaded. + +- Output: `public/lightbox/` (`lightbox.js`, `lightbox.css`, `lightbox.js.map`) +- `make build` runs `npm ci --include=dev && npm run build` inside `libs/lightbox`; the `build` script is `tsc --noEmit && vite build` +- Unit tests: `npm test` (Vitest, 23 tests), covering `geometry` math and `lightbox` rendering/lifecycle + +Do not edit `public/lightbox/` — they are build artifacts. + ## Syntax Highlighting Pipeline - `themes/` contains Catppuccin Latte (light) and Mocha (dark) `.tmTheme` files @@ -152,12 +164,12 @@ Do not edit `public/tiptap/` — they are build artifacts. ## Testing ```bash -make test # cargo test (Rust, 392 tests) + vitest (editor lib, 46 tests) +make test # cargo test (Rust, 402 tests) + vitest (tiptap-editor 46 tests, lightbox 23 tests) dx check # Dioxus type-check (catches component/Router issues) cargo clippy # lint ``` -Most tests use `#[cfg(all(test, feature = "server"))]` — they only run when the server feature is active (which is the default). No integration tests requiring a database connection. +Most tests use `#[cfg(all(test, feature = "server"))]` — they only run when the server feature is active (which is the default). No integration tests requiring a database connection. The two `libs/` subprojects (tiptap-editor, lightbox) run their own vitest suites. ## Image Processing Constraints @@ -170,9 +182,10 @@ Most tests use `#[cfg(all(test, feature = "server"))]` — they only run when th - `public/style.css` — Tailwind output - `public/highlight.css` — generated by `generate_highlight_css` binary -- `public/tiptap/` — Vite build output +- `public/tiptap/` — Vite build output (editor) +- `public/lightbox/` — Vite build output (lightbox) - `/dist`, `/.dioxus`, `/target` -- `node_modules` (inside `libs/tiptap-editor/`) +- `node_modules` (inside `libs/tiptap-editor/` and `libs/lightbox/`) - `uploads/.cache/` — image processing disk cache ## Notes