From f9f7fb678fdc4f16c37d73b0975222b99c6c58a6 Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sat, 22 Aug 2026 22:03:12 +0800
Subject: [PATCH 01/15] =?UTF-8?q?=E9=98=B6=E6=AE=B5=E5=9B=9B=EF=BC=9A?=
 =?UTF-8?q?=E5=BB=BA=E7=AB=8B=E8=AF=84=E8=AE=BA=E6=A8=A1=E5=9E=8B=E4=B8=8E?=
 =?UTF-8?q?=E5=AE=89=E5=85=A8=E5=9F=BA=E7=A1=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .env.example                                  |   1 +
 .../application/CommentChallengeService.java  |  60 +++++
 .../application/CommentSecurityService.java   | 128 ++++++++++
 .../io/haoblog/comment/domain/Comment.java    |  98 ++++++++
 .../haoblog/comment/domain/CommentStatus.java |   9 +
 .../persistence/CommentRepository.java        |  13 +
 .../web/PublicCommentContextController.java   |  54 +++++
 .../content/application/ArticleService.java   |  12 +-
 .../io/haoblog/content/domain/Article.java    |   4 +
 .../ArticleRevisionRepository.java            |   7 +-
 .../haoblog/content/web/AdminArticleDtos.java |   8 +-
 .../content/web/PublicArticleController.java  |  10 +-
 .../haoblog/site/application/SiteService.java |   8 +-
 .../io/haoblog/site/domain/SiteSetting.java   |   4 +
 .../site/web/PublicSiteController.java        |   8 +-
 apps/api/src/main/resources/application.yml   |   2 +
 .../V10__comment_model_and_flags.sql          |  36 +++
 .../test/java/io/haoblog/ContentModelIT.java  |   8 +-
 .../CommentChallengeServiceTest.java          |  42 ++++
 .../CommentSecurityServiceTest.java           |  48 ++++
 apps/web/app/utils/publicSite.ts              |   1 +
 docs/openapi/public-api.yaml                  |  39 ++-
 ...56\346\240\207\344\273\273\345\212\241.md" | 226 ------------------
 ...06\345\205\245\346\270\205\345\215\225.md" |  95 --------
 infra/compose/.env.ci.example                 |   1 +
 packages/api-client/src/generated.ts          |  51 ++++
 26 files changed, 628 insertions(+), 345 deletions(-)
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/application/CommentChallengeService.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/domain/Comment.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/domain/CommentStatus.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java
 create mode 100644 apps/api/src/main/resources/db/migration/V10__comment_model_and_flags.sql
 create mode 100644 apps/api/src/test/java/io/haoblog/comment/application/CommentChallengeServiceTest.java
 create mode 100644 apps/api/src/test/java/io/haoblog/comment/application/CommentSecurityServiceTest.java
 delete mode 100644 "docs/\347\254\254\344\270\211\351\230\266\346\256\265\347\233\256\346\240\207\344\273\273\345\212\241.md"
 delete mode 100644 "docs/\351\230\266\346\256\265\344\270\211\345\207\206\345\205\245\346\270\205\345\215\225.md"

diff --git a/.env.example b/.env.example
index 5430252..171378a 100644
--- a/.env.example
+++ b/.env.example
@@ -18,6 +18,7 @@ HAOBLOG_ADMIN_PASSWORD_HASH=replace-with-a-bcrypt-hash
 HAOBLOG_SESSION_COOKIE_SECURE=false
 HAOBLOG_PUBLIC_BASE_URL=http://localhost:3000
 HAOBLOG_AUTHOR_NAME=Hao
+HAOBLOG_COMMENT_SECURITY_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
 
 # OSS is disabled locally by default. These are server-only values; never put a real key in Git.
 HAOBLOG_OSS_ENABLED=false
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentChallengeService.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentChallengeService.java
new file mode 100644
index 0000000..2f5746e
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentChallengeService.java
@@ -0,0 +1,60 @@
+package io.haoblog.comment.application;
+
+import com.github.benmanes.caffeine.cache.Cache;
+import com.github.benmanes.caffeine.cache.Caffeine;
+import org.springframework.stereotype.Service;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.UUID;
+
+@Service
+public class CommentChallengeService {
+    static final Duration MINIMUM_FILL_TIME = Duration.ofSeconds(3);
+    static final Duration MAXIMUM_AGE = Duration.ofHours(2);
+    private static final long MAX_CACHE_SIZE = 4096;
+
+    private final Clock clock;
+    private final CommentSecurityService security;
+    private final Cache<String, Challenge> challenges = Caffeine.newBuilder()
+            .maximumSize(MAX_CACHE_SIZE)
+            .expireAfterWrite(MAXIMUM_AGE)
+            .build();
+
+    public CommentChallengeService(Clock clock, CommentSecurityService security) {
+        this.clock = clock;
+        this.security = security;
+    }
+
+    public IssuedChallenge issue(UUID articleId) {
+        Instant issuedAt = clock.instant();
+        Instant expiresAt = issuedAt.plus(MAXIMUM_AGE);
+        String token = security.challengeToken(articleId, issuedAt);
+        challenges.put(token, new Challenge(articleId, issuedAt, expiresAt));
+        return new IssuedChallenge(token, expiresAt);
+    }
+
+    public boolean consume(UUID articleId, String token) {
+        if (token == null || token.isBlank()) return false;
+        Challenge challenge = challenges.getIfPresent(token);
+        if (challenge == null) return false;
+        Instant now = clock.instant();
+        if (!challenge.articleId().equals(articleId)
+                || now.isBefore(challenge.issuedAt().plus(MINIMUM_FILL_TIME))
+                || !challenge.expiresAt().isAfter(now)) {
+            return false;
+        }
+        challenges.invalidate(token);
+        return true;
+    }
+
+    long cacheSize() {
+        challenges.cleanUp();
+        return challenges.estimatedSize();
+    }
+
+    public record IssuedChallenge(String token, Instant expiresAt) {}
+
+    private record Challenge(UUID articleId, Instant issuedAt, Instant expiresAt) {}
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
new file mode 100644
index 0000000..fd396c3
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
@@ -0,0 +1,128 @@
+package io.haoblog.comment.application;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+
+import javax.crypto.Cipher;
+import javax.crypto.Mac;
+import javax.crypto.spec.GCMParameterSpec;
+import javax.crypto.spec.SecretKeySpec;
+import java.nio.charset.StandardCharsets;
+import java.security.GeneralSecurityException;
+import java.security.MessageDigest;
+import java.security.SecureRandom;
+import java.time.LocalDate;
+import java.util.Base64;
+import java.util.UUID;
+
+@Service
+public class CommentSecurityService {
+    private static final int KEY_BYTES = 32;
+    private static final int NONCE_BYTES = 12;
+    private final byte[] emailKey;
+    private final byte[] ipKey;
+    private final byte[] challengeKey;
+    private final SecureRandom random = new SecureRandom();
+
+    public CommentSecurityService(@Value("${haoblog.comment.security-key:}") String encodedKey) {
+        if (encodedKey == null || encodedKey.isBlank()) {
+            byte[] masterKey = new byte[KEY_BYTES];
+            randomize(masterKey);
+            this.emailKey = derive(masterKey, "email-v1");
+            this.ipKey = derive(masterKey, "ip-v1");
+            this.challengeKey = derive(masterKey, "challenge-v1");
+        } else {
+            byte[] masterKey;
+            try {
+                masterKey = Base64.getDecoder().decode(encodedKey);
+            } catch (IllegalArgumentException exception) {
+                throw new IllegalArgumentException("HAOBLOG_COMMENT_SECURITY_KEY must be Base64", exception);
+            }
+            if (masterKey.length != KEY_BYTES) {
+                throw new IllegalArgumentException("HAOBLOG_COMMENT_SECURITY_KEY must decode to 32 bytes");
+            }
+            this.emailKey = derive(masterKey, "email-v1");
+            this.ipKey = derive(masterKey, "ip-v1");
+            this.challengeKey = derive(masterKey, "challenge-v1");
+        }
+    }
+
+    public EmailCiphertext encryptEmail(UUID commentId, String email) {
+        if (email == null || email.isBlank()) return null;
+        byte[] nonce = new byte[NONCE_BYTES];
+        random.nextBytes(nonce);
+        try {
+            Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
+            cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(emailKey, "AES"), new GCMParameterSpec(128, nonce));
+            cipher.updateAAD(commentId.toString().getBytes(StandardCharsets.UTF_8));
+            return new EmailCiphertext(nonce, cipher.doFinal(email.trim().getBytes(StandardCharsets.UTF_8)));
+        } catch (GeneralSecurityException exception) {
+            throw new IllegalStateException("Unable to encrypt comment email", exception);
+        }
+    }
+
+    public String decryptEmail(UUID commentId, EmailCiphertext encrypted) {
+        try {
+            Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
+            cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(emailKey, "AES"),
+                    new GCMParameterSpec(128, encrypted.nonce()));
+            cipher.updateAAD(commentId.toString().getBytes(StandardCharsets.UTF_8));
+            return new String(cipher.doFinal(encrypted.ciphertext()), StandardCharsets.UTF_8);
+        } catch (GeneralSecurityException exception) {
+            throw new IllegalArgumentException("Comment email authentication failed", exception);
+        }
+    }
+
+    public byte[] dailyIpHmac(String ip, LocalDate date) {
+        return hmac(ipKey, "ip-v1:" + date + ":" + ip);
+    }
+
+    public byte[] contentFingerprint(UUID articleId, String normalizedBody) {
+        return digest(articleId + "\n" + normalizedBody);
+    }
+
+    public byte[] deleteTokenDigest(String token) {
+        return digest(token);
+    }
+
+    public String challengeToken(UUID articleId, java.time.Instant issuedAt) {
+        return Base64.getUrlEncoder().withoutPadding().encodeToString(
+                hmac(challengeKey, "challenge-v1:" + articleId + ":" + issuedAt + ":" + UUID.randomUUID()));
+    }
+
+    private static byte[] derive(byte[] masterKey, String purpose) {
+        return hmac(masterKey, "haoblog-comment-key:" + purpose);
+    }
+
+    private static byte[] hmac(byte[] hmacKey, String value) {
+        try {
+            Mac mac = Mac.getInstance("HmacSHA256");
+            mac.init(new SecretKeySpec(hmacKey, "HmacSHA256"));
+            return mac.doFinal(value.getBytes(StandardCharsets.UTF_8));
+        } catch (GeneralSecurityException exception) {
+            throw new IllegalStateException("Unable to hash comment security value", exception);
+        }
+    }
+
+    private static byte[] digest(String value) {
+        try {
+            return MessageDigest.getInstance("SHA-256").digest(value.getBytes(StandardCharsets.UTF_8));
+        } catch (java.security.NoSuchAlgorithmException exception) {
+            throw new IllegalStateException("Unable to hash comment security value", exception);
+        }
+    }
+
+    private static void randomize(byte[] value) {
+        new SecureRandom().nextBytes(value);
+    }
+
+    public record EmailCiphertext(byte[] nonce, byte[] ciphertext) {
+        public EmailCiphertext {
+            nonce = nonce.clone();
+            ciphertext = ciphertext.clone();
+        }
+
+        @Override public byte[] nonce() { return nonce.clone(); }
+        @Override public byte[] ciphertext() { return ciphertext.clone(); }
+    }
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java b/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java
new file mode 100644
index 0000000..e640aa3
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java
@@ -0,0 +1,98 @@
+package io.haoblog.comment.domain;
+
+import io.haoblog.shared.id.UuidV7;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import jakarta.persistence.Version;
+
+import java.time.Instant;
+import java.util.Arrays;
+import java.util.UUID;
+
+@Entity
+@Table(name = "comment")
+public class Comment {
+    @Id
+    private UUID id = UuidV7.generate();
+    @Column(name = "article_id", nullable = false)
+    private UUID articleId;
+    @Column(name = "parent_id")
+    private UUID parentId;
+    @Column(nullable = false, length = 40)
+    private String nickname;
+    @Column(name = "email_ciphertext")
+    private byte[] emailCiphertext;
+    @Column(name = "email_nonce")
+    private byte[] emailNonce;
+    @Column(nullable = false, columnDefinition = "text")
+    private String body;
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false, length = 16)
+    private CommentStatus status = CommentStatus.PENDING;
+    @Column(name = "ip_hmac", nullable = false)
+    private byte[] ipHmac;
+    @Column(name = "content_fingerprint", nullable = false)
+    private byte[] contentFingerprint;
+    @Column(name = "delete_token_digest", nullable = false, unique = true)
+    private byte[] deleteTokenDigest;
+    @Column(name = "moderated_by")
+    private UUID moderatedBy;
+    @Column(name = "moderation_reason", length = 600)
+    private String moderationReason;
+    @Column(name = "created_at", nullable = false)
+    private Instant createdAt;
+    @Column(name = "updated_at", nullable = false)
+    private Instant updatedAt;
+    @Column(name = "moderated_at")
+    private Instant moderatedAt;
+    @Column(name = "deleted_at")
+    private Instant deletedAt;
+    @Version
+    @Column(nullable = false)
+    private long version;
+
+    protected Comment() {}
+
+    public Comment(UUID articleId, UUID parentId, String nickname, byte[] emailCiphertext,
+                   byte[] emailNonce, String body, byte[] ipHmac, byte[] contentFingerprint,
+                   byte[] deleteTokenDigest, Instant now) {
+        this.articleId = articleId;
+        this.parentId = parentId;
+        this.nickname = nickname;
+        this.emailCiphertext = copy(emailCiphertext);
+        this.emailNonce = copy(emailNonce);
+        this.body = body;
+        this.ipHmac = copy(ipHmac);
+        this.contentFingerprint = copy(contentFingerprint);
+        this.deleteTokenDigest = copy(deleteTokenDigest);
+        this.createdAt = now;
+        this.updatedAt = now;
+    }
+
+    public UUID getId() { return id; }
+    public UUID getArticleId() { return articleId; }
+    public UUID getParentId() { return parentId; }
+    public String getNickname() { return nickname; }
+    public byte[] getEmailCiphertext() { return copy(emailCiphertext); }
+    public byte[] getEmailNonce() { return copy(emailNonce); }
+    public String getBody() { return body; }
+    public CommentStatus getStatus() { return status; }
+    public byte[] getIpHmac() { return copy(ipHmac); }
+    public byte[] getContentFingerprint() { return copy(contentFingerprint); }
+    public byte[] getDeleteTokenDigest() { return copy(deleteTokenDigest); }
+    public UUID getModeratedBy() { return moderatedBy; }
+    public String getModerationReason() { return moderationReason; }
+    public Instant getCreatedAt() { return createdAt; }
+    public Instant getUpdatedAt() { return updatedAt; }
+    public Instant getModeratedAt() { return moderatedAt; }
+    public Instant getDeletedAt() { return deletedAt; }
+    public long getVersion() { return version; }
+
+    private static byte[] copy(byte[] value) {
+        return value == null ? null : Arrays.copyOf(value, value.length);
+    }
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/domain/CommentStatus.java b/apps/api/src/main/java/io/haoblog/comment/domain/CommentStatus.java
new file mode 100644
index 0000000..b394a8b
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/domain/CommentStatus.java
@@ -0,0 +1,9 @@
+package io.haoblog.comment.domain;
+
+public enum CommentStatus {
+    PENDING,
+    APPROVED,
+    SPAM,
+    REJECTED,
+    USER_DELETED
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java b/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
new file mode 100644
index 0000000..15ca80f
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
@@ -0,0 +1,13 @@
+package io.haoblog.comment.persistence;
+
+import io.haoblog.comment.domain.Comment;
+import io.haoblog.comment.domain.CommentStatus;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.UUID;
+
+public interface CommentRepository extends JpaRepository<Comment, UUID> {
+    Page<Comment> findByArticleIdAndStatusAndParentIdIsNull(UUID articleId, CommentStatus status, Pageable pageable);
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java b/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java
new file mode 100644
index 0000000..9dfcd1a
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java
@@ -0,0 +1,54 @@
+package io.haoblog.comment.web;
+
+import io.haoblog.comment.application.CommentChallengeService;
+import io.haoblog.content.application.ArticleService;
+import io.haoblog.shared.web.ProblemResponse;
+import io.haoblog.site.application.SiteService;
+import org.slf4j.MDC;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.web.csrf.CsrfToken;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.time.Instant;
+
+@RestController
+@RequestMapping("/api/v1/public/articles")
+public class PublicCommentContextController {
+    private final ArticleService articles;
+    private final SiteService site;
+    private final CommentChallengeService challenges;
+
+    public PublicCommentContextController(ArticleService articles, SiteService site, CommentChallengeService challenges) {
+        this.articles = articles;
+        this.site = site;
+        this.challenges = challenges;
+    }
+
+    @GetMapping("/{slug}/comments/form-context")
+    public FormContext formContext(@PathVariable String slug, CsrfToken csrfToken) {
+        var article = articles.findPublicBySlug(slug).orElseThrow(() -> new ArticleNotFoundException(slug));
+        var issued = challenges.issue(article.articleId());
+        return new FormContext(csrfToken.getToken(), issued.token(), issued.expiresAt(),
+                site.get().commentsEnabled() && article.commentsEnabled());
+    }
+
+    @ExceptionHandler(ArticleNotFoundException.class)
+    ResponseEntity<ProblemResponse> articleNotFound(ArticleNotFoundException ignored) {
+        return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                .body(new ProblemResponse("ARTICLE_NOT_FOUND", "Article not found",
+                        "The requested public article does not exist", MDC.get("traceId")));
+    }
+
+    public record FormContext(String csrfToken, String challenge, Instant expiresAt, boolean commentsEnabled) {}
+
+    private static final class ArticleNotFoundException extends RuntimeException {
+        private ArticleNotFoundException(String slug) {
+            super("Article not found: " + slug);
+        }
+    }
+}
diff --git a/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java b/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
index 7a469f0..8a75908 100644
--- a/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
+++ b/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
@@ -55,7 +55,7 @@ public Map<UUID, String> publicCoverUrls(Collection<UUID> mediaIds) {
                 .collect(Collectors.toUnmodifiableMap(MediaAsset::getId, MediaAsset::getPublicUrl));
     }
     private PublicArticle toPublicArticle(ArticleRevisionRepository.PublicArticleProjection projection) {
-        return new PublicArticle(projection.getRevision(), projection.getPublishedAt());
+        return new PublicArticle(projection.getRevision(), projection.getPublishedAt(), projection.getCommentsEnabled());
     }
 
     private PublicFeedArticle toPublicFeedArticle(ArticleRevisionRepository.PublicArticleProjection projection) {
@@ -64,7 +64,15 @@ private PublicFeedArticle toPublicFeedArticle(ArticleRevisionRepository.PublicAr
                 revision.getExcerpt(), projection.getPublishedAt());
     }
 
-    public record PublicArticle(ArticleRevision revision, java.time.Instant publishedAt) {}
+    public record PublicArticle(ArticleRevision revision, java.time.Instant publishedAt, boolean commentsEnabled) {
+        public PublicArticle(ArticleRevision revision, java.time.Instant publishedAt) {
+            this(revision, publishedAt, true);
+        }
+
+        public UUID articleId() {
+            return revision.getArticleId();
+        }
+    }
     public record PageResult(Page<PublicArticle> page) {}
     public record PublishedBatch(List<PublicFeedArticle> items, boolean hasNext) {}
     public record PublicFeedArticle(UUID id, String slug, String title, String excerpt, java.time.Instant publishedAt) {}
diff --git a/apps/api/src/main/java/io/haoblog/content/domain/Article.java b/apps/api/src/main/java/io/haoblog/content/domain/Article.java
index 098a02d..e600166 100644
--- a/apps/api/src/main/java/io/haoblog/content/domain/Article.java
+++ b/apps/api/src/main/java/io/haoblog/content/domain/Article.java
@@ -44,6 +44,8 @@ public class Article {
     private UUID categoryId;
     @Column(name = "cover_media_id")
     private UUID coverMediaId;
+    @Column(name = "comments_enabled", nullable = false)
+    private boolean commentsEnabled = true;
     @ManyToMany
     @JoinTable(name = "article_tag",
             joinColumns = @JoinColumn(name = "article_id"),
@@ -139,6 +141,8 @@ private static String normalizeSlug(String raw, ArticleStatus status) {
     public UUID getPublishedRevisionId() { return publishedRevisionId; }
     public UUID getCategoryId() { return categoryId; }
     public UUID getCoverMediaId() { return coverMediaId; }
+    public boolean isCommentsEnabled() { return commentsEnabled; }
+    public void setCommentsEnabled(boolean commentsEnabled) { this.commentsEnabled = commentsEnabled; }
     public Set<Tag> getTags() { return tags; }
     public Instant getCreatedAt() { return createdAt; }
     public Instant getUpdatedAt() { return updatedAt; }
diff --git a/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java b/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java
index 3d65033..0c78f3f 100644
--- a/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java
+++ b/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java
@@ -30,7 +30,7 @@ public interface ArticleRevisionRepository extends JpaRepository<ArticleRevision
     Optional<ArticleRevision> findByIdAndArticleId(UUID id, UUID articleId);
 
     @Query("""
-            select r as revision, a.publishedAt as publishedAt
+            select r as revision, a.publishedAt as publishedAt, a.commentsEnabled as commentsEnabled
             from ArticleRevision r, Article a
             where r.id = a.publishedRevisionId
               and a.status in (:published, :scheduled)
@@ -45,7 +45,7 @@ Page<PublicArticleProjection> findVisible(@Param("published") ArticleStatus publ
                                               Pageable pageable);
 
     @Query("""
-            select r as revision, a.publishedAt as publishedAt
+            select r as revision, a.publishedAt as publishedAt, a.commentsEnabled as commentsEnabled
             from ArticleRevision r, Article a
             where r.id = a.publishedRevisionId
               and a.status = :published
@@ -59,7 +59,7 @@ Page<PublicArticleProjection> findPublished(@Param("published") ArticleStatus pu
                                                 Pageable pageable);
 
     @Query("""
-            select r as revision, a.publishedAt as publishedAt
+            select r as revision, a.publishedAt as publishedAt, a.commentsEnabled as commentsEnabled
             from ArticleRevision r, Article a
             where r.id = a.publishedRevisionId
               and r.slug = :slug
@@ -92,6 +92,7 @@ boolean existsVisibleSlug(@Param("slug") String slug, @Param("articleId") UUID a
     interface PublicArticleProjection {
         ArticleRevision getRevision();
         java.time.Instant getPublishedAt();
+        boolean getCommentsEnabled();
     }
 
     interface SummaryProjection {
diff --git a/apps/api/src/main/java/io/haoblog/content/web/AdminArticleDtos.java b/apps/api/src/main/java/io/haoblog/content/web/AdminArticleDtos.java
index ed5d2cc..4a7142c 100644
--- a/apps/api/src/main/java/io/haoblog/content/web/AdminArticleDtos.java
+++ b/apps/api/src/main/java/io/haoblog/content/web/AdminArticleDtos.java
@@ -42,11 +42,11 @@ public record ListResponse(List<Summary> items, int page, int size, long total)
 
     public record Summary(UUID id, String slug, String title, ArticleStatus status,
                           UUID categoryId,
-                          Instant updatedAt, long version) {
+                          Instant updatedAt, long version, boolean commentsEnabled) {
         static Summary from(Article article) {
             return new Summary(article.getId(), article.getSlug(), article.getTitle(), article.getStatus(),
                     article.getCategoryId(),
-                    article.getUpdatedAt(), article.getVersion());
+                    article.getUpdatedAt(), article.getVersion(), article.isCommentsEnabled());
         }
     }
 
@@ -54,13 +54,13 @@ public record Response(UUID id, String slug, String title, String excerpt, Strin
                            ArticleStatus status, Instant publishedAt, Instant scheduledAt,
                            String seoTitle, String seoDescription, UUID categoryId,
                            UUID coverMediaId, List<UUID> tagIds, Instant createdAt,
-                           Instant updatedAt, long version) {
+                           Instant updatedAt, long version, boolean commentsEnabled) {
         static Response from(Article article) {
             return new Response(article.getId(), article.getSlug(), article.getTitle(), article.getExcerpt(),
                     article.getMarkdownSource(), article.getStatus(), article.getPublishedAt(), article.getScheduledAt(),
                     article.getSeoTitle(), article.getSeoDescription(), article.getCategoryId(), article.getCoverMediaId(),
                     article.getTags().stream().map(tag -> tag.getId()).toList(), article.getCreatedAt(),
-                    article.getUpdatedAt(), article.getVersion());
+                    article.getUpdatedAt(), article.getVersion(), article.isCommentsEnabled());
         }
     }
 }
diff --git a/apps/api/src/main/java/io/haoblog/content/web/PublicArticleController.java b/apps/api/src/main/java/io/haoblog/content/web/PublicArticleController.java
index 0022930..14dc08c 100644
--- a/apps/api/src/main/java/io/haoblog/content/web/PublicArticleController.java
+++ b/apps/api/src/main/java/io/haoblog/content/web/PublicArticleController.java
@@ -73,21 +73,23 @@ private static String representationHash(Object... values) {
         }
     }
 
-    public record ArticleSummary(UUID id, String slug, String title, String excerpt, Instant publishedAt, String coverImageUrl) {
+    public record ArticleSummary(UUID id, String slug, String title, String excerpt, Instant publishedAt, String coverImageUrl,
+                                 boolean commentsEnabled) {
         static ArticleSummary from(ArticleService.PublicArticle article, String coverImageUrl) {
             ArticleRevision revision = article.revision();
             return new ArticleSummary(revision.getArticleId(), revision.getSlug(), revision.getTitle(), revision.getExcerpt(),
-                    article.publishedAt(), coverImageUrl);
+                    article.publishedAt(), coverImageUrl, article.commentsEnabled());
         }
     }
     public record ArticleListResponse(List<ArticleSummary> items, int page, int size, long total) {}
     public record ArticleResponse(UUID id, String slug, String title, String excerpt, Instant publishedAt, Instant modifiedAt,
-                                  String markdown, String seoTitle, String seoDescription, String coverImageUrl) {
+                                  String markdown, String seoTitle, String seoDescription, String coverImageUrl,
+                                  boolean commentsEnabled) {
         static ArticleResponse from(ArticleService.PublicArticle article, String coverImageUrl) {
             ArticleRevision revision = article.revision();
             return new ArticleResponse(revision.getArticleId(), revision.getSlug(), revision.getTitle(), revision.getExcerpt(),
                     article.publishedAt(), revision.getCreatedAt(), revision.getMarkdownSource(), revision.getSeoTitle(),
-                    revision.getSeoDescription(), coverImageUrl);
+                    revision.getSeoDescription(), coverImageUrl, article.commentsEnabled());
         }
     }
 }
diff --git a/apps/api/src/main/java/io/haoblog/site/application/SiteService.java b/apps/api/src/main/java/io/haoblog/site/application/SiteService.java
index 779dac7..f0e9eaf 100644
--- a/apps/api/src/main/java/io/haoblog/site/application/SiteService.java
+++ b/apps/api/src/main/java/io/haoblog/site/application/SiteService.java
@@ -26,7 +26,7 @@ public SiteService(SiteSettingRepository repository,
 
     public SiteResult get() {
         var setting = repository.findBySiteKey("default").orElseThrow();
-        return new SiteResult(setting.getTitle(), setting.getDescription(), publicBaseUrl, authorName);
+        return new SiteResult(setting.getTitle(), setting.getDescription(), publicBaseUrl, authorName, setting.isCommentsEnabled());
     }
 
     static String normalizePublicBaseUrl(String raw) {
@@ -47,5 +47,9 @@ static String normalizePublicBaseUrl(String raw) {
         return raw.trim().replaceFirst("/+$", "");
     }
 
-    public record SiteResult(String title, String description, String siteUrl, String authorName) {}
+    public record SiteResult(String title, String description, String siteUrl, String authorName, boolean commentsEnabled) {
+        public SiteResult(String title, String description, String siteUrl, String authorName) {
+            this(title, description, siteUrl, authorName, true);
+        }
+    }
 }
diff --git a/apps/api/src/main/java/io/haoblog/site/domain/SiteSetting.java b/apps/api/src/main/java/io/haoblog/site/domain/SiteSetting.java
index b56beb0..2880402 100644
--- a/apps/api/src/main/java/io/haoblog/site/domain/SiteSetting.java
+++ b/apps/api/src/main/java/io/haoblog/site/domain/SiteSetting.java
@@ -11,10 +11,14 @@ public class SiteSetting {
     @Column(name = "site_key", nullable = false, unique = true, length = 64) private String siteKey;
     @Column(nullable = false, length = 160) private String title;
     @Column(nullable = false, length = 600) private String description;
+    @Column(name = "comments_enabled", nullable = false) private boolean commentsEnabled = true;
+    @Version @Column(nullable = false) private long version;
     protected SiteSetting() {}
     public SiteSetting(String siteKey, String title, String description) {
         this.siteKey = siteKey; this.title = title; this.description = description;
     }
     public String getTitle() { return title; }
     public String getDescription() { return description; }
+    public boolean isCommentsEnabled() { return commentsEnabled; }
+    public long getVersion() { return version; }
 }
diff --git a/apps/api/src/main/java/io/haoblog/site/web/PublicSiteController.java b/apps/api/src/main/java/io/haoblog/site/web/PublicSiteController.java
index 946df8a..b2f6020 100644
--- a/apps/api/src/main/java/io/haoblog/site/web/PublicSiteController.java
+++ b/apps/api/src/main/java/io/haoblog/site/web/PublicSiteController.java
@@ -20,7 +20,7 @@ public class PublicSiteController {
     @GetMapping
     public ResponseEntity<SiteResponse> site(@RequestHeader(value = HttpHeaders.IF_NONE_MATCH, required = false) String ifNoneMatch) {
         var result = service.get();
-        var response = new SiteResponse(result.title(), result.description(), result.siteUrl(), result.authorName());
+        var response = new SiteResponse(result.title(), result.description(), result.siteUrl(), result.authorName(), result.commentsEnabled());
         var headers = new HttpHeaders();
         headers.setETag(representationHash(response));
         headers.setCacheControl("public, max-age=0, s-maxage=60, must-revalidate");
@@ -39,5 +39,9 @@ private static String representationHash(Object value) {
         }
     }
 
-    public record SiteResponse(String title, String description, String siteUrl, String authorName) {}
+    public record SiteResponse(String title, String description, String siteUrl, String authorName, boolean commentsEnabled) {
+        public SiteResponse(String title, String description, String siteUrl, String authorName) {
+            this(title, description, siteUrl, authorName, true);
+        }
+    }
 }
diff --git a/apps/api/src/main/resources/application.yml b/apps/api/src/main/resources/application.yml
index b60b158..c50669f 100644
--- a/apps/api/src/main/resources/application.yml
+++ b/apps/api/src/main/resources/application.yml
@@ -74,3 +74,5 @@ haoblog:
       public-base-url: ${HAOBLOG_OSS_PUBLIC_BASE_URL:}
       max-size-bytes: ${HAOBLOG_OSS_MAX_SIZE_BYTES:5242880}
       max-dimension: ${HAOBLOG_OSS_MAX_DIMENSION:2560}
+  comment:
+    security-key: ${HAOBLOG_COMMENT_SECURITY_KEY:}
diff --git a/apps/api/src/main/resources/db/migration/V10__comment_model_and_flags.sql b/apps/api/src/main/resources/db/migration/V10__comment_model_and_flags.sql
new file mode 100644
index 0000000..e3fb46e
--- /dev/null
+++ b/apps/api/src/main/resources/db/migration/V10__comment_model_and_flags.sql
@@ -0,0 +1,36 @@
+ALTER TABLE site_setting
+    ADD COLUMN comments_enabled boolean NOT NULL DEFAULT true,
+    ADD COLUMN version bigint NOT NULL DEFAULT 0;
+
+ALTER TABLE article
+    ADD COLUMN comments_enabled boolean NOT NULL DEFAULT true;
+
+CREATE TABLE comment (
+    id uuid PRIMARY KEY,
+    article_id uuid NOT NULL REFERENCES article(id) ON DELETE CASCADE,
+    parent_id uuid,
+    nickname varchar(40) NOT NULL,
+    email_ciphertext bytea,
+    email_nonce bytea,
+    body text NOT NULL,
+    status varchar(16) NOT NULL DEFAULT 'PENDING'
+        CHECK (status IN ('PENDING', 'APPROVED', 'SPAM', 'REJECTED', 'USER_DELETED')),
+    ip_hmac bytea NOT NULL CHECK (octet_length(ip_hmac) = 32),
+    content_fingerprint bytea NOT NULL CHECK (octet_length(content_fingerprint) = 32),
+    delete_token_digest bytea NOT NULL UNIQUE CHECK (octet_length(delete_token_digest) = 32),
+    moderated_by uuid REFERENCES admin_user(id) ON DELETE SET NULL,
+    moderation_reason varchar(600),
+    created_at timestamptz NOT NULL,
+    updated_at timestamptz NOT NULL,
+    moderated_at timestamptz,
+    deleted_at timestamptz,
+    version bigint NOT NULL DEFAULT 0,
+    CONSTRAINT comment_id_article_uq UNIQUE (id, article_id),
+    CONSTRAINT comment_email_pair CHECK ((email_ciphertext IS NULL) = (email_nonce IS NULL)),
+    CONSTRAINT comment_email_nonce_length CHECK (email_nonce IS NULL OR octet_length(email_nonce) = 12),
+    CONSTRAINT comment_article_parent_fk FOREIGN KEY (parent_id, article_id)
+        REFERENCES comment(id, article_id) ON DELETE RESTRICT
+);
+
+CREATE INDEX comment_article_status_created_idx ON comment (article_id, status, created_at, id);
+CREATE INDEX comment_parent_created_idx ON comment (parent_id, created_at, id);
diff --git a/apps/api/src/test/java/io/haoblog/ContentModelIT.java b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
index 6e61fa2..795d677 100644
--- a/apps/api/src/test/java/io/haoblog/ContentModelIT.java
+++ b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
@@ -51,9 +51,9 @@ static void database(DynamicPropertyRegistry registry) {
 
     @Test
     void migratesAllVersionsAndCreatesContentTables() {
-        assertEquals(9, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
+        assertEquals(10, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
         for (String table : List.of("article", "category", "tag", "article_tag", "article_revision",
-                "article_preview_token", "media_asset", "media_upload", "outbox_event")) {
+                "article_preview_token", "media_asset", "media_upload", "outbox_event", "comment")) {
             assertEquals(1, jdbc.queryForObject(
                     "SELECT count(*) FROM information_schema.tables WHERE table_schema='public' AND table_name=?",
                     Integer.class, table));
@@ -62,6 +62,10 @@ void migratesAllVersionsAndCreatesContentTables() {
                 "SELECT is_nullable FROM information_schema.columns WHERE table_name='article' AND column_name='slug'", String.class));
         assertEquals("bigint", jdbc.queryForObject(
                 "SELECT data_type FROM information_schema.columns WHERE table_name='article' AND column_name='version'", String.class));
+        assertEquals("boolean", jdbc.queryForObject(
+                "SELECT data_type FROM information_schema.columns WHERE table_name='article' AND column_name='comments_enabled'", String.class));
+        assertEquals("boolean", jdbc.queryForObject(
+                "SELECT data_type FROM information_schema.columns WHERE table_name='site_setting' AND column_name='comments_enabled'", String.class));
     }
 
     @Test
diff --git a/apps/api/src/test/java/io/haoblog/comment/application/CommentChallengeServiceTest.java b/apps/api/src/test/java/io/haoblog/comment/application/CommentChallengeServiceTest.java
new file mode 100644
index 0000000..643eb43
--- /dev/null
+++ b/apps/api/src/test/java/io/haoblog/comment/application/CommentChallengeServiceTest.java
@@ -0,0 +1,42 @@
+package io.haoblog.comment.application;
+
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.util.Base64;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class CommentChallengeServiceTest {
+    @Test
+    void requiresMinimumAgeAndConsumesOnce() {
+        var clock = new MutableClock(Instant.parse("2026-08-22T00:00:00Z"));
+        var security = new CommentSecurityService(Base64.getEncoder().encodeToString(
+                "01234567890123456789012345678901".getBytes(StandardCharsets.UTF_8)));
+        var challenges = new CommentChallengeService(clock, security);
+        UUID articleId = UUID.randomUUID();
+        var issued = challenges.issue(articleId);
+
+        assertFalse(challenges.consume(articleId, issued.token()));
+
+        clock.advance(Duration.ofSeconds(3));
+        assertTrue(challenges.consume(articleId, issued.token()));
+        assertFalse(challenges.consume(articleId, issued.token()));
+    }
+
+    private static final class MutableClock extends Clock {
+        private Instant instant;
+
+        private MutableClock(Instant instant) { this.instant = instant; }
+        private void advance(Duration duration) { instant = instant.plus(duration); }
+        @Override public ZoneId getZone() { return ZoneId.of("UTC"); }
+        @Override public Clock withZone(ZoneId zone) { return this; }
+        @Override public Instant instant() { return instant; }
+    }
+}
diff --git a/apps/api/src/test/java/io/haoblog/comment/application/CommentSecurityServiceTest.java b/apps/api/src/test/java/io/haoblog/comment/application/CommentSecurityServiceTest.java
new file mode 100644
index 0000000..5d39a53
--- /dev/null
+++ b/apps/api/src/test/java/io/haoblog/comment/application/CommentSecurityServiceTest.java
@@ -0,0 +1,48 @@
+package io.haoblog.comment.application;
+
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+import java.time.LocalDate;
+import java.util.Base64;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class CommentSecurityServiceTest {
+    private static final UUID COMMENT_ID = UUID.fromString("00000000-0000-0000-0000-000000000001");
+
+    private final CommentSecurityService security = new CommentSecurityService(
+            Base64.getEncoder().encodeToString("01234567890123456789012345678901".getBytes(StandardCharsets.UTF_8)));
+
+    @Test
+    void encryptsEmailWithAuthenticatedRandomNonce() {
+        var first = security.encryptEmail(COMMENT_ID, "author@example.test");
+        var second = security.encryptEmail(COMMENT_ID, "author@example.test");
+
+        assertNotEquals(Base64.getEncoder().encodeToString(first.nonce()), Base64.getEncoder().encodeToString(second.nonce()));
+        assertEquals("author@example.test", security.decryptEmail(COMMENT_ID, first));
+        assertThrows(IllegalArgumentException.class, () -> security.decryptEmail(UUID.randomUUID(), first));
+    }
+
+    @Test
+    void derivesScopedDigests() {
+        var today = security.dailyIpHmac("192.0.2.1", LocalDate.of(2026, 8, 22));
+        var tomorrow = security.dailyIpHmac("192.0.2.1", LocalDate.of(2026, 8, 23));
+
+        assertFalse(java.util.Arrays.equals(today, tomorrow));
+        assertArrayEquals(security.deleteTokenDigest("token"), security.deleteTokenDigest("token"));
+        assertTrue(security.contentFingerprint(COMMENT_ID, "body").length == 32);
+    }
+
+    @Test
+    void rejectsInvalidKey() {
+        assertThrows(IllegalArgumentException.class, () -> new CommentSecurityService(
+                Base64.getEncoder().encodeToString(new byte[16])));
+    }
+}
diff --git a/apps/web/app/utils/publicSite.ts b/apps/web/app/utils/publicSite.ts
index af31882..a8d5521 100644
--- a/apps/web/app/utils/publicSite.ts
+++ b/apps/web/app/utils/publicSite.ts
@@ -7,6 +7,7 @@ export const defaultPublicSite: PublicSite = {
   description: '极夜观测站',
   siteUrl: 'http://localhost:3000',
   authorName: 'Hao',
+  commentsEnabled: true,
 }
 
 export function usePublicSite() {
diff --git a/docs/openapi/public-api.yaml b/docs/openapi/public-api.yaml
index ac57f11..9931302 100644
--- a/docs/openapi/public-api.yaml
+++ b/docs/openapi/public-api.yaml
@@ -137,6 +137,22 @@ paths:
           $ref: '#/components/responses/ArticleNotFound'
         '500':
           $ref: '#/components/responses/InternalError'
+  /api/v1/public/articles/{slug}/comments/form-context:
+    get:
+      operationId: getPublicCommentFormContext
+      parameters:
+        - name: slug
+          in: path
+          required: true
+          schema: { type: string, minLength: 1, maxLength: 160 }
+      responses:
+        '200':
+          description: CSRF token and one-time comment form challenge
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/CommentFormContext' }
+        '404':
+          $ref: '#/components/responses/ArticleNotFound'
   /api/v1/public/article-previews/{token}:
     get:
       operationId: getPublicArticlePreview
@@ -686,15 +702,16 @@ components:
   schemas:
     SiteResponse:
       type: object
-      required: [title, description, siteUrl, authorName]
+      required: [title, description, siteUrl, authorName, commentsEnabled]
       properties:
         title: { type: string }
         description: { type: string }
         siteUrl: { type: string, format: uri }
         authorName: { type: string }
+        commentsEnabled: { type: boolean }
     ArticleSummary:
       type: object
-      required: [id, slug, title, excerpt, publishedAt, coverImageUrl]
+      required: [id, slug, title, excerpt, publishedAt, coverImageUrl, commentsEnabled]
       properties:
         id: { type: string, format: uuid }
         slug: { type: string }
@@ -702,6 +719,7 @@ components:
         excerpt: { type: [string, 'null'] }
         publishedAt: { type: string, format: date-time }
         coverImageUrl: { type: [string, 'null'], format: uri }
+        commentsEnabled: { type: boolean }
     ArticleListResponse:
       type: object
       required: [items, page, size, total]
@@ -712,7 +730,7 @@ components:
         total: { type: integer, format: int64 }
     ArticleResponse:
       type: object
-      required: [id, slug, title, excerpt, publishedAt, modifiedAt, markdown, seoTitle, seoDescription, coverImageUrl]
+      required: [id, slug, title, excerpt, publishedAt, modifiedAt, markdown, seoTitle, seoDescription, coverImageUrl, commentsEnabled]
       properties:
         id: { type: string, format: uuid }
         slug: { type: string }
@@ -724,6 +742,15 @@ components:
         seoTitle: { type: [string, 'null'] }
         seoDescription: { type: [string, 'null'] }
         coverImageUrl: { type: [string, 'null'], format: uri }
+        commentsEnabled: { type: boolean }
+    CommentFormContext:
+      type: object
+      required: [csrfToken, challenge, expiresAt, commentsEnabled]
+      properties:
+        csrfToken: { type: string, minLength: 1 }
+        challenge: { type: string, minLength: 43, maxLength: 43 }
+        expiresAt: { type: string, format: date-time }
+        commentsEnabled: { type: boolean }
     ProblemResponse:
       type: object
       required: [code, title, detail, traceId]
@@ -883,7 +910,7 @@ components:
         tagIds: { type: array, items: { type: string, format: uuid } }
     AdminArticleSummary:
       type: object
-      required: [id, title, status, categoryId, updatedAt, version]
+      required: [id, title, status, categoryId, updatedAt, version, commentsEnabled]
       properties:
         id: { type: string, format: uuid }
         slug: { type: [string, 'null'] }
@@ -892,6 +919,7 @@ components:
         categoryId: { type: [string, 'null'], format: uuid }
         updatedAt: { type: string, format: date-time }
         version: { type: integer, format: int64, minimum: 0 }
+        commentsEnabled: { type: boolean }
     AdminArticleListResponse:
       type: object
       required: [items, page, size, total]
@@ -902,7 +930,7 @@ components:
         total: { type: integer, format: int64 }
     AdminArticleResponse:
       type: object
-      required: [id, title, markdown, status, createdAt, updatedAt, version, tagIds]
+      required: [id, title, markdown, status, createdAt, updatedAt, version, tagIds, commentsEnabled]
       properties:
         id: { type: string, format: uuid }
         slug: { type: [string, 'null'] }
@@ -920,6 +948,7 @@ components:
         createdAt: { type: string, format: date-time }
         updatedAt: { type: string, format: date-time }
         version: { type: integer, format: int64, minimum: 0 }
+        commentsEnabled: { type: boolean }
     MediaUploadRequest:
       type: object
       required: [mimeType, sizeBytes, width, height, sha256]
diff --git "a/docs/\347\254\254\344\270\211\351\230\266\346\256\265\347\233\256\346\240\207\344\273\273\345\212\241.md" "b/docs/\347\254\254\344\270\211\351\230\266\346\256\265\347\233\256\346\240\207\344\273\273\345\212\241.md"
deleted file mode 100644
index a58910e..0000000
--- "a/docs/\347\254\254\344\270\211\351\230\266\346\256\265\347\233\256\346\240\207\344\273\273\345\212\241.md"
+++ /dev/null
@@ -1,226 +0,0 @@
-# HaoBlog 阶段 3：公开阅读完整开发计划
-
-## 一、目标与边界
-
-阶段 3 将 HaoBlog 从“能够 SSR 展示文章”提升为完整的公开阅读产品：
-
-- 首页、文章时间线和文章详情形成统一的“极夜观测站”静态阅读体验。
-- 标题、正文、TOC、代码、公式和主要 SEO 信息均存在于 SSR HTML。
-- 支持安全的高级 Markdown：Shiki、KaTeX、Mermaid、表格、任务列表、脚注、提示块和代码复制。
-- 完成 Canonical、Open Graph、Twitter、JSON-LD、RSS 和 Sitemap。
-- 满足 360/768/1280/1600px、无 JavaScript、Save-Data、reduced-motion 和键盘访问。
-- 文章初始 JavaScript 小于 180KB gzip，Performance、SEO、Accessibility 均达到 90。
-
-明确不做：评论、工具箱功能、AI/RAG、知识星图、Three.js、终端解析器、音乐、404 游戏、真实部署和域名备案。
-
-设计主线采用“仪器，而非装饰”和“可读性永远赢”；首页只完成 SSR 校准首屏与近期观测日志，不留下空的星图占位。
-
-S3-08 收口状态（2026-08-22）：
-
-- Java 21.0.11 环境已恢复；API `-DskipITs verify` 49 项和 PostgreSQL/pgvector Failsafe 36 项均通过。
-- Web typecheck、66 项 Vitest、生产构建、客户端预算和完整 8 项 Chromium Playwright 均通过。
-- 文章初始客户端静态闭包为 60,932 bytes gzip；Mermaid 位于异步 chunk，未把 Shiki、编辑器或 Three.js 放入初始闭包。
-- Lighthouse 移动端 Performance、Accessibility、SEO 均为 1.00；Best Practices 0.96 的已知项是 `.test` HTTPS 图片不会真实联网。
-- 独立生产 Compose 项目中的 Caddy、Web、API、PostgreSQL/pgvector 全部健康，资源限制与端口隔离已在运行时读取验证。
-- 工作树中的演示稿和既有未跟踪文件未删除、未提交；本轮未执行提交、推送、部署或云资源变更。
-- 仓库没有 `.openai/hosting.json`，继续使用既有 Nuxt、Spring Boot、Caddy、Compose 架构；Sites 不创建项目或部署。
-- 远端 CI、真实 OSS、真实域名 HTTPS、备案、ACR 和自动部署未在本轮执行，不得宣称上线验收通过。
-
-## 二、接口与实现决策
-
-### 公开契约
-
-- `SiteResponse` 增加 `siteUrl`、`authorName`；由 `HAOBLOG_PUBLIC_BASE_URL` 和 `HAOBLOG_AUTHOR_NAME` 提供，生产必须配置，开发默认 `http://localhost:3000` 和 `Hao`。
-- `ArticleSummary` 只保留列表需要的 `id/slug/title/excerpt/publishedAt/coverImageUrl`，删除 Markdown 和 SEO 正文数据。
-- `ArticleResponse` 增加 `modifiedAt`，并修正 `publishedAt` 为文章真实发布时间，不再用版本快照创建时间代替。
-- ETag 必须包含公开版本 ID、真实发布时间、分页信息和影响响应的媒体数据。
-- 前台页码使用 1 起始，API 继续使用 0 起始；`?page=1` 永久重定向到 `/articles`，非法或越界页返回 404。
-- 增加 `GET /rss.xml` 和 `GET /sitemap.xml`，写入 OpenAPI；RSS 返回最近 20 篇摘要，Sitemap 分批读取全部公开文章。
-- 不新增数据库表；公开数据继续来自不可变 `article_revision` 与文章公开状态。
-
-### Markdown SSR 数据流
-
-```text
-Spring 公开文章 API
-  → Nuxt /_content/articles/{slug} 公开读模型
-  → 服务端 Markdown 解析、安全清洗和代码高亮
-  → { article, renderedHtml, toc, hasMermaid }
-  → 文章页 SSR
-  → 可选的轻量客户端增强
-```
-
-- 使用 `markdown-it`，设置 `html=false`、`linkify=false`、`typographer=false`；选择已修复相关性能安全问题的兼容稳定版本。[markdown-it 官方仓库](https://github.com/markdown-it/markdown-it)
-- 使用 `@mdit/plugin-footnote`、`@mdit/plugin-tasklist`、`@mdit/plugin-container` 和 `@mdit/plugin-katex`，不引入整套预设。[Markdown It Plugins](https://mdit-plugins.github.io/)
-- Shiki 只存在于 Nitro 服务端，采用细粒度语言/主题包、JavaScript 正则引擎和单例高亮器；未知语言回退为纯文本，不进入文章客户端包。[Shiki 性能建议](https://shiki.style/guide/best-performance)
-- 支持 Java、Kotlin、Vue、TypeScript、JavaScript、HTML/XML、CSS、JSON、YAML、SQL、Shell、PowerShell、Dockerfile、Markdown 和纯文本。
-- 代码围栏元数据固定为 ```` ```lang [file.ext] {1,3-5} ````，支持文件名、行号、聚焦行和复制按钮；非法元数据忽略并转义。
-- 文章标题是页面唯一 `h1`；正文标题整体下移一级。TOC 收集渲染后的 `h2/h3`。
-- 标题 ID 使用 NFKC、Unicode 字母数字、小写化和连字符规范化；空标题回退 `section`，重复标题追加 `-2/-3`。
-- 链接只允许站内绝对路径、`https:` 和 `mailto:`；图片只允许 `https:`；禁止 `javascript:`、`data:`、原始 HTML 和任意 Vue 组件。
-- 提示块仅支持 `note/tip/warning/danger`；任务复选框只读；脚注回链必须键盘可达。
-- KaTeX 使用美元与括号两套分隔符，`trust=false`、严格模式、有限 `maxSize/maxExpand`；错误公式回退为可读源码。[KaTeX 安全选项](https://katex.org/docs/options)
-- Mermaid 首次进入视口后动态加载，配置 `startOnLoad=false`、`securityLevel=strict`、`maxTextSize=50000`、`maxEdges=500`；无 JS 或渲染失败时保留源码。[Mermaid 安全级别](https://mermaid.js.org/config/schema-docs/config-properties-securitylevel.html)
-- 最终 HTML 再经服务端标签、属性、协议和 Shiki/KaTeX 样式白名单清洗。
-
-### SEO 与索引策略
-
-- 使用可信配置的站点根地址生成 Canonical，不信任转发 Host。
-- 文章 JSON-LD 使用 `BlogPosting`，包含标题、摘要、作者、站点、Canonical、封面、`datePublished`、`dateModified` 和 `inLanguage=zh-CN`；不嵌入 Markdown 正文。
-- `/`、`/articles`、有效分页、`/about` 和公开文章允许索引。
-- `/studio/**`、预览链接、404、尚未实现内容的 `/garden`、`/tools` 设置 `noindex,nofollow`。
-- Sitemap 只包含 `/`、`/articles`、`/about` 和公开文章，不包含分页、预览、Studio 或占位页。
-- RSS/Sitemap 由 Spring Boot 使用 JDK XML API生成，不新增 Java Feed 依赖；Caddy 将两个精确路径转发至 API并保留条件缓存。
-- 保留现有 `og-default.svg`，文章有 HTTPS 封面时优先使用封面，不生成新的社交预览图。
-
-## 三、任务划分
-
-```mermaid
-flowchart LR
-  S300["S3-00 准入"] --> S301["S3-01 公开读模型"]
-  S301 --> S302["S3-02 Markdown SSR"]
-  S302 --> S303["S3-03 TOC 与阅读增强"]
-  S301 --> S304["S3-04 公共站视觉"]
-  S301 --> S305["S3-05 SEO 与索引"]
-  S301 --> S306["S3-06 RSS/Sitemap"]
-  S303 --> S307["S3-07 响应式与性能"]
-  S304 --> S307
-  S305 --> S307
-  S306 --> S307
-  S307 --> S308["S3-08 综合验收"]
-```
-
-### S3-00：冻结阶段 3 基线，2–4 小时
-
-- 记录当前分支、HEAD、远端 CI 结果和所有用户改动。
-- 删除 `PublicSiteController` 中明显异常的无关注释；演示稿和无关未跟踪资产不纳入阶段 3，用户明确要求更新的阶段文档按 S3-08 收口范围处理。
-- 恢复 Java 21，并先运行 API 单测确认真实基线。
-- 保存阶段 3 起始 Commit，不提交、不推送，除非用户另行授权。
-
-验收：阶段 3 文件与用户资产边界清晰，Java 21、Web 基线和 `git diff --check` 可执行。
-
-### S3-01：公开文章读模型与缓存契约，8–12 小时
-
-- 修正公开发布时间、分页、投影查询和列表过量字段。
-- 增加 `modifiedAt/siteUrl/authorName` 契约并重新生成客户端。
-- 首页读取最近 5 篇文章；列表增加 1 起始的上一页/下一页导航。
-- 统一 API/Nuxt 的 404、ETag、304 和 60 秒共享缓存行为。
-
-验收：草稿、未到期定时文、归档文不可见；列表不返回 Markdown；发布修改在 60 秒内可见；API 类型无手写副本。
-
-### S3-02：安全高级 Markdown SSR 引擎，18–26 小时
-
-- 建立服务端读模型和单一 Markdown 解析/清洗管线。
-- 实现基础语法、表格、任务列表、脚注、提示块、KaTeX、Shiki 和 Mermaid 源码回退。
-- 对渲染结果设置版本化 ETag；解析或高亮失败只降级相关块，不使文章整体 500。
-- 限制输入大小、公式展开、Mermaid 文本/边数及高亮语言集合。
-
-验收：恶意 HTML、协议、公式和图表配置不能越过白名单；Shiki/KaTeX 不进入文章客户端初始包；未知语言和错误公式仍可阅读。
-
-### S3-03：文章结构、TOC 与轻量增强，10–14 小时
-
-- 桌面采用左信号进度、中间 720px 正文、右侧 TOC 的仪器布局。
-- 移动端将进度压缩为细线，TOC 使用原生 `<details>` 抽屉。
-- TOC、正文锚点由同一 token 流生成；支持重复中文标题、键盘导航和深链接。
-- 复用一个滚动监听器驱动 Dock 与左侧进度；IntersectionObserver 仅增强当前章节状态。
-- 增加代码复制、Mermaid 懒加载和失败提示；无 JS 时正文、源码与锚点仍完整。
-
-验收：页面只有一个 `h1`；TOC/正文 ID 一致；复制和图表增强失败不影响阅读。
-
-### S3-04：公共站完整静态视觉，10–14 小时
-
-- 完善全局发丝线、正文舞台、48px Dock 和 CSS 径向 INDEX；Dock 仍只有 INDEX、⌘K、AI。
-- 首页实现“信号校准”SSR 首屏和近期观测日志，不加载 Three.js 或空星图占位。
-- 列表实现带封面、时间戳和摘要的单列观测时间线，不转成卡片网格。
-- 文章页保证正文对比度、代码/表格横向滚动、封面尺寸稳定和图片懒加载。
-- ⌘K 与 AI 继续保持明确禁用状态，不提前实现后续功能。
-
-验收：360px 无横向页面溢出；触摸不依赖 Hover；设计保持极夜观测站而非通用博客模板。
-
-### S3-05：完整 SEO 与索引边界，8–12 小时
-
-- 为首页、列表、About 和文章生成 title、description、Canonical、Open Graph、Twitter。
-- 文章输出安全的 `BlogPosting` JSON-LD。
-- 添加全站 RSS `<link rel="alternate">`。
-- 固化分页、旧/非法 slug、404、占位页、Studio 和预览链接的索引策略。
-
-验收：SSR 源码中即可看到全部 Meta、Canonical 和 JSON-LD；JSON-LD 可解析且不含不可信脚本终止序列。
-
-### S3-06：RSS、Sitemap 与网关路由，8–12 小时
-
-- Spring Boot 生成 RSS 2.0 和 Sitemap XML。
-- RSS 固定最近 20 篇，只有标题、摘要、绝对链接、稳定 GUID 和发布时间。
-- Sitemap 使用 500 条一批读取，最多 50,000 URL，正确 XML 转义。
-- 支持 ETag、304 和短时共享缓存；Caddy 精确转发两个 XML 路径。
-- 本地 Nitro 提供轻量代理，使 `localhost:3000/rss.xml` 与生产入口一致。
-
-验收：草稿、预览、归档和未来文章不出现在 XML；响应 Content-Type、绝对 URL 和缓存头正确。
-
-### S3-07：响应式、无障碍与性能预算，8–12 小时
-
-- 覆盖 360/768/1280/1600px、键盘、可见焦点和触摸路径。
-- SSR 根据 `Save-Data` 请求头设置降级状态，客户端再同步 `navigator.connection.saveData`。
-- reduced-motion 禁用扫描、平滑滚动和 TOC 过渡；Save-Data 下 Mermaid 只在用户主动请求后加载。
-- 增加构建产物预算脚本，递归统计文章路由初始 gzip 资源并拒绝 Three.js、编辑器、Shiki、KaTeX JS 和 Mermaid 初始加载。
-- 使用开发依赖中的固定版本 Lighthouse CI 验证文章移动端 Performance、SEO、Accessibility 均不低于 0.90。
-
-验收：文章初始 JS ≤180KB gzip；SSR 首屏无布局阻塞；高级渲染没有进入 Studio 或其他无关包。
-
-### S3-08：契约、E2E、文档与阶段验收，8–12 小时
-
-- 增加高级 Markdown 固定样例，覆盖重复标题、代码元数据、公式、图表、脚注、提示块、表格、任务和恶意输入。
-- Playwright 验证首页、分页、文章、TOC、Meta、JSON-LD、RSS、Sitemap、图片与 404。
-- 使用禁用 JavaScript的浏览器上下文确认正文、TOC、公式、代码和 Mermaid 源码存在。
-- 在生产 Compose 中验证 Caddy、Web、API 路由及缓存。
-- 更新 README、本地启动指南、CI 和 `docs/第三阶段目标任务.md`；只有真实脚本存在后才更新命令清单。
-
-验收：本节所有自动化和手工性能门槛通过，阶段 3 之外的功能没有提前实现。
-
-实际结果：固定文章、分页、SEO/XML、四档视口、无 JavaScript、Save-Data、reduced-motion、键盘焦点、生产拓扑、客户端预算和 Lighthouse 均已通过本地自动化；修复了客户端分页查询复用、HTML 语言、进度条名称、代码复制名称、INDEX 名称和脚注链接辨识度。阶段三之外的评论、工具箱功能、AI、RAG、Three.js、终端和部署均未实现。
-
-总工作量约 80–118 个理想小时；按每周 15–20 小时估算约 4–8 周。选择“完整高级 Markdown”后，不再沿用原计划的一周估算。
-
-## 四、测试与完成定义
-
-执行顺序：
-
-1. Java 21 环境确认与 API 单测。
-2. API `-DskipITs verify`。
-3. Web typecheck、Vitest、build。
-4. OpenAPI 重新生成与一致性检查。
-5. PostgreSQL Failsafe 集成测试。
-6. Compose dev/prod 配置与资源边界检查。
-7. 生产 Compose Smoke、Playwright、构建预算和 Lighthouse。
-8. `git diff --check`。
-
-关键场景：
-
-- 实际发布时间与版本修改时间不同。
-- 空站点、单页、最后一页、非法页码和越界分页。
-- 两个相同中文标题、纯符号标题和深链接刷新。
-- 未知代码语言、超长代码、非法聚焦行和复制失败。
-- KaTeX 非法命令、超量展开和 HTML 扩展攻击。
-- Mermaid 指令覆盖配置、超边数、解析错误、Save-Data、无 JS。
-- Markdown 原始 HTML、恶意 URL、图片协议、脚本闭合序列。
-- 草稿、归档、未来定时文和预览链接不进入 SEO/RSS/Sitemap。
-- 360px 长 URL、宽表格、长代码、超长标题和大封面。
-- 文章路由初始包不包含编辑器、Shiki、Mermaid、Three.js。
-
-阶段 3 只有在以下条件同时满足时完成：
-
-- 公共阅读页面形成完整静态极夜体验。
-- 高级 Markdown 安全且 SSR 可读。
-- TOC、SEO、JSON-LD、RSS、Sitemap 全部可验证。
-- 无 JS、Save-Data、reduced-motion、键盘和四档视口通过。
-- JS、Lighthouse 和生产 Compose 门槛通过。
-- API/OpenAPI/生成客户端一致，README 与真实命令同步。
-- 用户未授权的文件未被提交、删除、推送或部署。
-
-## 五、假设与默认值
-
-- 继续使用阿里云 OSS；阶段 2 文档中的腾讯云 COS 描述视为历史方案。
-- `Hao` 仅是本地默认作者名，生产必须显式设置。
-- `/garden` 和 `/tools` 保留可访问占位页但不索引，等对应阶段完成后再加入 Sitemap。
-- 不支持原始 HTML、任意组件、动态图、SVG Markdown 图片或通用嵌入。
-- 不建立 HTML 数据库缓存；先使用 Nuxt 60 秒有界缓存，只有观测到渲染瓶颈后再持久化。
-- 不引入动画库；本阶段使用 CSS、原生 `<details>`、IntersectionObserver 和现有 Vue 能力。
-- 建议提交信息均使用中文，但本计划不授权自动提交或推送。
diff --git "a/docs/\351\230\266\346\256\265\344\270\211\345\207\206\345\205\245\346\270\205\345\215\225.md" "b/docs/\351\230\266\346\256\265\344\270\211\345\207\206\345\205\245\346\270\205\345\215\225.md"
deleted file mode 100644
index 6c66602..0000000
--- "a/docs/\351\230\266\346\256\265\344\270\211\345\207\206\345\205\245\346\270\205\345\215\225.md"
+++ /dev/null
@@ -1,95 +0,0 @@
-# 阶段三准入清单：公开阅读
-
-阶段三只处理公开阅读体验，不提前实现评论、工具箱、AI、RAG、Three.js、终端或部署功能。
-
-## S3-08 本地收口状态
-
-2026-08-22 在 Windows 11、Java 21.0.11、Node.js 24.14.0、pnpm 11.16.0、Docker Engine 29.7.2 和 Compose 5.3.1 下完成本地验收。远端 CI、真实 OSS、真实域名 HTTPS、备案、ACR 和自动部署未在本轮执行，不能据本清单宣称通过。
-
-### S3-01 公开数据与页面基线
-
-- [x] `/api/v1/public/site`、文章列表和文章详情 DTO 的缓存头、ETag 和分页边界可验证。
-- [x] 首页在 SSR HTML 中展示站点信息和最近公开文章入口。
-- [x] 列表页展示发布时间、摘要、HTTPS 封面、空状态和真实分页。
-- [x] 文章页读取不可变发布快照；草稿、归档和未来定时文不可见。
-
-### S3-02 高级 Markdown 与阅读结构
-
-- [x] S3-08 固定验收文章覆盖重复中文标题、多语言代码与围栏元数据、KaTeX、Mermaid、表格、任务列表、脚注和四种提示块。
-- [x] 固定文章同时覆盖 HTTPS 图片、原始恶意 HTML、`javascript:` URL、HTTP URL 和 HTTP 图片。
-- [x] h2/h3 TOC 从安全渲染结果生成，重复标题锚点稳定去重。
-- [x] Shiki 与 KaTeX 在 SSR 阶段生成可读 HTML；Mermaid 仅交互异步加载，失败时保留源码。
-- [x] 无 JavaScript 时标题、正文、TOC、公式、代码和 Mermaid 源码可读。
-
-### S3-03 SEO 与订阅入口
-
-- [x] 输出 title、description、Canonical、Open Graph 和 Twitter Meta。
-- [x] 输出可解析的 `BlogPosting` JSON-LD，且正文不依赖客户端执行。
-- [x] `/rss.xml` 与 `/sitemap.xml` 返回正确 XML 类型、绝对 URL、ETag 和 304。
-- [x] 分页 canonical、非法页码、越界页、文章 404、草稿和预览链接索引边界可验证。
-
-### S3-04 响应式、无障碍与性能
-
-- [x] 360/768/1280/1600px 公共路由无页面横向溢出。
-- [x] 无 JavaScript、`Save-Data: on`、`prefers-reduced-motion` 和键盘可见焦点通过 Playwright。
-- [x] 文章初始客户端静态闭包为 60,932 bytes gzip，小于 180 KB；Mermaid 位于异步 chunk，Shiki/编辑器/Three.js 不在初始闭包。
-- [x] Lighthouse 移动端：Performance 1.00、Accessibility 1.00、SEO 1.00，均不低于 0.90。
-- [x] Lighthouse Best Practices 为 0.96；唯一已知项是固定验收用 `https://cdn.example.test/...` 图片不会真实联网，不将其冒充为已上线 CDN。
-
-### S3-05 生产拓扑
-
-- [x] 生产 Compose 的 Caddy、Web、API、PostgreSQL/pgvector 均为 `healthy`。
-- [x] 运行时内存限制分别为 64/320/640/480 MiB，CPU 分别为 0.2/0.6/1.25/0.8，PID 上限分别为 64/128/256/128。
-- [x] 只有 Caddy 暴露宿主机 80/443；Web 3000、API 8080、PostgreSQL 5432 仅在 Compose 网络内可见。
-- [x] Smoke 与完整 Chromium Playwright E2E 通过。
-
-## 阶段三验收命令
-
-依赖、代码、契约和配置：
-
-```powershell
-corepack pnpm install --frozen-lockfile
-git diff --check
-Push-Location apps/api
-.\mvnw.cmd -DskipITs verify
-.\mvnw.cmd failsafe:integration-test failsafe:verify
-Pop-Location
-corepack pnpm --dir apps/web typecheck
-corepack pnpm --dir apps/web test
-corepack pnpm --dir apps/web build
-corepack pnpm --filter @haoblog/api-client generate
-corepack pnpm --filter @haoblog/api-client check
-git diff --exit-code -- packages/api-client/src/generated.ts
-docker compose --env-file infra/compose/.env.ci.example -f infra/compose/compose.dev.yml config --quiet
-docker compose --env-file infra/compose/.env.ci.example -f infra/compose/compose.prod.yml config --quiet
-corepack pnpm compose:verify
-corepack pnpm web:budget
-```
-
-生产编排浏览器验收使用测试专用项目名，避免覆盖开发 Compose：
-
-```powershell
-docker build -f apps/api/Dockerfile -t haoblog-api:ci .
-docker build -f apps/web/Dockerfile -t haoblog-web:ci .
-$env:HAOBLOG_PUBLIC_BASE_URL = 'http://localhost'
-docker compose -p haoblog-s3-acceptance --env-file infra/compose/.env.ci.example -f infra/compose/compose.prod.yml up -d --wait --wait-timeout 180
-$env:HAOBLOG_BASE_URL = 'http://localhost'
-corepack pnpm smoke
-corepack pnpm --dir apps/web exec playwright install chromium
-$env:CI = 'true'
-corepack pnpm --dir apps/web e2e
-$env:LHCI_EXISTING_SERVER = 'true'
-$env:LHCI_BASE_URL = 'http://localhost'
-corepack pnpm web:lighthouse
-docker compose -p haoblog-s3-acceptance --env-file infra/compose/.env.ci.example -f infra/compose/compose.prod.yml down -v --remove-orphans
-```
-
-最后一条命令会删除测试项目的 PostgreSQL 与 Caddy volumes；不要把项目名改成正在使用的开发或生产项目。仓库示例凭据仅用于离线、本地和 CI 验收。
-
-## 阶段边界与阶段四准入
-
-- 评论、审核和限频：阶段四。
-- 工具箱的功能实现：后续独立切片，不在阶段三提前实现。
-- 百炼 Chat、Embedding、SSE 和 RAG：阶段五及以后。
-- 备案、真实域名 HTTPS、真实 OSS、ACR 和自动部署：部署阶段另行验收。
-- 阶段三的本地准入条件已经满足；阶段四可以开始，但应先等待当前改动经正常代码审查和远端 CI 通过。公网部署事项不是阶段四业务开发的阻塞条件，也不能据此标记为已上线。
diff --git a/infra/compose/.env.ci.example b/infra/compose/.env.ci.example
index c3ee038..101007e 100644
--- a/infra/compose/.env.ci.example
+++ b/infra/compose/.env.ci.example
@@ -11,6 +11,7 @@ HAOBLOG_ADMIN_USERNAME=admin
 HAOBLOG_ADMIN_PASSWORD_HASH='$2a$10$0V.Xs7CLOUYSekm7RKq3Z.iY76KUan/Xbeu5vjmLpX.sVd4pcFpIu'
 HAOBLOG_PUBLIC_BASE_URL=http://localhost:3000
 HAOBLOG_AUTHOR_NAME=Hao
+HAOBLOG_COMMENT_SECURITY_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
 SPRING_PROFILES_ACTIVE=dev
 HAOBLOG_SEED_ENABLED=true
 HAOBLOG_CONTENT_SCHEDULING_FIXED_DELAY_MS=1000
diff --git a/packages/api-client/src/generated.ts b/packages/api-client/src/generated.ts
index 56924ab..75745cc 100644
--- a/packages/api-client/src/generated.ts
+++ b/packages/api-client/src/generated.ts
@@ -84,6 +84,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/public/articles/{slug}/comments/form-context": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getPublicCommentFormContext"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/public/article-previews/{token}": {
         parameters: {
             query?: never;
@@ -444,6 +460,7 @@ export interface components {
             /** Format: uri */
             siteUrl: string;
             authorName: string;
+            commentsEnabled: boolean;
         };
         ArticleSummary: {
             /** Format: uuid */
@@ -455,6 +472,7 @@ export interface components {
             publishedAt: string;
             /** Format: uri */
             coverImageUrl: string | null;
+            commentsEnabled: boolean;
         };
         ArticleListResponse: {
             items: components["schemas"]["ArticleSummary"][];
@@ -478,6 +496,14 @@ export interface components {
             seoDescription: string | null;
             /** Format: uri */
             coverImageUrl: string | null;
+            commentsEnabled: boolean;
+        };
+        CommentFormContext: {
+            csrfToken: string;
+            challenge: string;
+            /** Format: date-time */
+            expiresAt: string;
+            commentsEnabled: boolean;
         };
         ProblemResponse: {
             code: string;
@@ -648,6 +674,7 @@ export interface components {
             updatedAt: string;
             /** Format: int64 */
             version: number;
+            commentsEnabled: boolean;
         };
         AdminArticleListResponse: {
             items: components["schemas"]["AdminArticleSummary"][];
@@ -681,6 +708,7 @@ export interface components {
             updatedAt: string;
             /** Format: int64 */
             version: number;
+            commentsEnabled: boolean;
         };
         MediaUploadRequest: {
             /** @enum {string} */
@@ -1078,6 +1106,29 @@ export interface operations {
             500: components["responses"]["InternalError"];
         };
     };
+    getPublicCommentFormContext: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                slug: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description CSRF token and one-time comment form challenge */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentFormContext"];
+                };
+            };
+            404: components["responses"]["ArticleNotFound"];
+        };
+    };
     getPublicArticlePreview: {
         parameters: {
             query?: never;

From a51e09fe3a08e5ad7b52f1340770fa36d44adab0 Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sat, 22 Aug 2026 22:35:10 +0800
Subject: [PATCH 02/15] =?UTF-8?q?=E9=98=B6=E6=AE=B5=E5=9B=9B=EF=BC=9A?=
 =?UTF-8?q?=E6=94=B6=E5=8F=A3=E8=AF=84=E8=AE=BA=E5=AE=89=E5=85=A8=E4=B8=8E?=
 =?UTF-8?q?=20Outbox=20=E7=BA=A6=E6=9D=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/ci.yml                      |   1 +
 apps/api/pom.xml                              |  14 ++-
 .../application/CommentSecurityService.java   |  47 ++++---
 .../io/haoblog/comment/domain/Comment.java    |  35 ++++--
 .../web/PublicCommentContextController.java   |   8 +-
 .../application/ArticleCommentLookup.java     |  11 ++
 .../content/application/ArticleService.java   |   8 +-
 ...__comment_security_and_outbox_payloads.sql |  49 ++++++++
 .../java/io/haoblog/ArchitectureTest.java     |   8 +-
 .../test/java/io/haoblog/ContentModelIT.java  | 116 +++++++++++++++++-
 .../CommentSecurityServiceTest.java           |  10 ++
 11 files changed, 265 insertions(+), 42 deletions(-)
 create mode 100644 apps/api/src/main/java/io/haoblog/content/application/ArticleCommentLookup.java
 create mode 100644 apps/api/src/main/resources/db/migration/V11__comment_security_and_outbox_payloads.sql

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ab8b3ef..ffce40e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -44,6 +44,7 @@ jobs:
       - name: PostgreSQL integration tests
         env:
           HAOBLOG_PUBLIC_BASE_URL: http://localhost:3000
+          HAOBLOG_COMMENT_SECURITY_KEY: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
         run: ./mvnw failsafe:integration-test failsafe:verify
         working-directory: apps/api
 
diff --git a/apps/api/pom.xml b/apps/api/pom.xml
index 1d54881..ca40e68 100644
--- a/apps/api/pom.xml
+++ b/apps/api/pom.xml
@@ -49,12 +49,22 @@
       <plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId>
-        <configuration><includes><include>**/*Test.java</include><include>**/*Tests.java</include></includes></configuration>
+        <configuration>
+          <includes><include>**/*Test.java</include><include>**/*Tests.java</include></includes>
+          <systemPropertyVariables>
+            <haoblog.comment.security-key>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</haoblog.comment.security-key>
+          </systemPropertyVariables>
+        </configuration>
       </plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId><artifactId>maven-failsafe-plugin</artifactId>
         <version>3.5.3</version>
-        <configuration><includes><include>**/*IT.java</include></includes></configuration>
+        <configuration>
+          <includes><include>**/*IT.java</include></includes>
+          <systemPropertyVariables>
+            <haoblog.comment.security-key>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</haoblog.comment.security-key>
+          </systemPropertyVariables>
+        </configuration>
         <executions><execution><goals><goal>integration-test</goal><goal>verify</goal></goals></execution></executions>
       </plugin>
     </plugins>
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
index fd396c3..75eb104 100644
--- a/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
@@ -19,6 +19,7 @@
 public class CommentSecurityService {
     private static final int KEY_BYTES = 32;
     private static final int NONCE_BYTES = 12;
+    private static final int EMAIL_KEY_VERSION = 1;
     private final byte[] emailKey;
     private final byte[] ipKey;
     private final byte[] challengeKey;
@@ -26,25 +27,20 @@ public class CommentSecurityService {
 
     public CommentSecurityService(@Value("${haoblog.comment.security-key:}") String encodedKey) {
         if (encodedKey == null || encodedKey.isBlank()) {
-            byte[] masterKey = new byte[KEY_BYTES];
-            randomize(masterKey);
-            this.emailKey = derive(masterKey, "email-v1");
-            this.ipKey = derive(masterKey, "ip-v1");
-            this.challengeKey = derive(masterKey, "challenge-v1");
-        } else {
-            byte[] masterKey;
-            try {
-                masterKey = Base64.getDecoder().decode(encodedKey);
-            } catch (IllegalArgumentException exception) {
-                throw new IllegalArgumentException("HAOBLOG_COMMENT_SECURITY_KEY must be Base64", exception);
-            }
-            if (masterKey.length != KEY_BYTES) {
-                throw new IllegalArgumentException("HAOBLOG_COMMENT_SECURITY_KEY must decode to 32 bytes");
-            }
-            this.emailKey = derive(masterKey, "email-v1");
-            this.ipKey = derive(masterKey, "ip-v1");
-            this.challengeKey = derive(masterKey, "challenge-v1");
+            throw new IllegalArgumentException("HAOBLOG_COMMENT_SECURITY_KEY must be configured");
+        }
+        byte[] masterKey;
+        try {
+            masterKey = Base64.getDecoder().decode(encodedKey.trim());
+        } catch (IllegalArgumentException exception) {
+            throw new IllegalArgumentException("HAOBLOG_COMMENT_SECURITY_KEY must be Base64", exception);
+        }
+        if (masterKey.length != KEY_BYTES) {
+            throw new IllegalArgumentException("HAOBLOG_COMMENT_SECURITY_KEY must decode to 32 bytes");
         }
+        this.emailKey = derive(masterKey, "email-v1");
+        this.ipKey = derive(masterKey, "ip-v1");
+        this.challengeKey = derive(masterKey, "challenge-v1");
     }
 
     public EmailCiphertext encryptEmail(UUID commentId, String email) {
@@ -55,13 +51,17 @@ public EmailCiphertext encryptEmail(UUID commentId, String email) {
             Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
             cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(emailKey, "AES"), new GCMParameterSpec(128, nonce));
             cipher.updateAAD(commentId.toString().getBytes(StandardCharsets.UTF_8));
-            return new EmailCiphertext(nonce, cipher.doFinal(email.trim().getBytes(StandardCharsets.UTF_8)));
+            return new EmailCiphertext(EMAIL_KEY_VERSION, nonce,
+                    cipher.doFinal(email.trim().getBytes(StandardCharsets.UTF_8)));
         } catch (GeneralSecurityException exception) {
             throw new IllegalStateException("Unable to encrypt comment email", exception);
         }
     }
 
     public String decryptEmail(UUID commentId, EmailCiphertext encrypted) {
+        if (encrypted == null || encrypted.keyVersion() != EMAIL_KEY_VERSION) {
+            throw new IllegalArgumentException("Unsupported comment email key version");
+        }
         try {
             Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
             cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(emailKey, "AES"),
@@ -112,12 +112,11 @@ private static byte[] digest(String value) {
         }
     }
 
-    private static void randomize(byte[] value) {
-        new SecureRandom().nextBytes(value);
-    }
-
-    public record EmailCiphertext(byte[] nonce, byte[] ciphertext) {
+    public record EmailCiphertext(int keyVersion, byte[] nonce, byte[] ciphertext) {
         public EmailCiphertext {
+            if (nonce == null || nonce.length != NONCE_BYTES || ciphertext == null) {
+                throw new IllegalArgumentException("Invalid email ciphertext");
+            }
             nonce = nonce.clone();
             ciphertext = ciphertext.clone();
         }
diff --git a/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java b/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java
index e640aa3..43647ad 100644
--- a/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java
+++ b/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java
@@ -10,6 +10,7 @@
 import jakarta.persistence.Version;
 
 import java.time.Instant;
+import java.time.LocalDate;
 import java.util.Arrays;
 import java.util.UUID;
 
@@ -28,19 +29,23 @@ public class Comment {
     private byte[] emailCiphertext;
     @Column(name = "email_nonce")
     private byte[] emailNonce;
+    @Column(name = "email_key_version")
+    private Integer emailKeyVersion;
     @Column(nullable = false, columnDefinition = "text")
-    private String body;
+    private String content;
     @Enumerated(EnumType.STRING)
     @Column(nullable = false, length = 16)
     private CommentStatus status = CommentStatus.PENDING;
     @Column(name = "ip_hmac", nullable = false)
     private byte[] ipHmac;
+    @Column(name = "ip_hmac_date", nullable = false)
+    private LocalDate ipHmacDate;
     @Column(name = "content_fingerprint", nullable = false)
     private byte[] contentFingerprint;
     @Column(name = "delete_token_digest", nullable = false, unique = true)
     private byte[] deleteTokenDigest;
-    @Column(name = "moderated_by")
-    private UUID moderatedBy;
+    @Column(name = "moderator_id")
+    private UUID moderatorId;
     @Column(name = "moderation_reason", length = 600)
     private String moderationReason;
     @Column(name = "created_at", nullable = false)
@@ -58,15 +63,18 @@ public class Comment {
     protected Comment() {}
 
     public Comment(UUID articleId, UUID parentId, String nickname, byte[] emailCiphertext,
-                   byte[] emailNonce, String body, byte[] ipHmac, byte[] contentFingerprint,
-                   byte[] deleteTokenDigest, Instant now) {
+                   byte[] emailNonce, Integer emailKeyVersion, String content, byte[] ipHmac,
+                   LocalDate ipHmacDate, byte[] contentFingerprint, byte[] deleteTokenDigest,
+                   Instant now) {
         this.articleId = articleId;
         this.parentId = parentId;
         this.nickname = nickname;
         this.emailCiphertext = copy(emailCiphertext);
         this.emailNonce = copy(emailNonce);
-        this.body = body;
+        this.emailKeyVersion = emailKeyVersion;
+        this.content = content;
         this.ipHmac = copy(ipHmac);
+        this.ipHmacDate = ipHmacDate;
         this.contentFingerprint = copy(contentFingerprint);
         this.deleteTokenDigest = copy(deleteTokenDigest);
         this.createdAt = now;
@@ -79,12 +87,14 @@ public Comment(UUID articleId, UUID parentId, String nickname, byte[] emailCiphe
     public String getNickname() { return nickname; }
     public byte[] getEmailCiphertext() { return copy(emailCiphertext); }
     public byte[] getEmailNonce() { return copy(emailNonce); }
-    public String getBody() { return body; }
+    public Integer getEmailKeyVersion() { return emailKeyVersion; }
+    public String getContent() { return content; }
     public CommentStatus getStatus() { return status; }
     public byte[] getIpHmac() { return copy(ipHmac); }
+    public LocalDate getIpHmacDate() { return ipHmacDate; }
     public byte[] getContentFingerprint() { return copy(contentFingerprint); }
     public byte[] getDeleteTokenDigest() { return copy(deleteTokenDigest); }
-    public UUID getModeratedBy() { return moderatedBy; }
+    public UUID getModeratorId() { return moderatorId; }
     public String getModerationReason() { return moderationReason; }
     public Instant getCreatedAt() { return createdAt; }
     public Instant getUpdatedAt() { return updatedAt; }
@@ -92,6 +102,15 @@ public Comment(UUID articleId, UUID parentId, String nickname, byte[] emailCiphe
     public Instant getDeletedAt() { return deletedAt; }
     public long getVersion() { return version; }
 
+    public void moderate(CommentStatus status, UUID moderatorId, String reason, Instant now) {
+        if (status == null || now == null) throw new IllegalArgumentException("Comment status and time are required");
+        this.status = status;
+        this.moderatorId = moderatorId;
+        this.moderationReason = reason;
+        this.moderatedAt = now;
+        this.updatedAt = now;
+    }
+
     private static byte[] copy(byte[] value) {
         return value == null ? null : Arrays.copyOf(value, value.length);
     }
diff --git a/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java b/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java
index 9dfcd1a..8e140b2 100644
--- a/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java
+++ b/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java
@@ -1,7 +1,7 @@
 package io.haoblog.comment.web;
 
 import io.haoblog.comment.application.CommentChallengeService;
-import io.haoblog.content.application.ArticleService;
+import io.haoblog.content.application.ArticleCommentLookup;
 import io.haoblog.shared.web.ProblemResponse;
 import io.haoblog.site.application.SiteService;
 import org.slf4j.MDC;
@@ -19,11 +19,11 @@
 @RestController
 @RequestMapping("/api/v1/public/articles")
 public class PublicCommentContextController {
-    private final ArticleService articles;
+    private final ArticleCommentLookup articles;
     private final SiteService site;
     private final CommentChallengeService challenges;
 
-    public PublicCommentContextController(ArticleService articles, SiteService site, CommentChallengeService challenges) {
+    public PublicCommentContextController(ArticleCommentLookup articles, SiteService site, CommentChallengeService challenges) {
         this.articles = articles;
         this.site = site;
         this.challenges = challenges;
@@ -31,7 +31,7 @@ public PublicCommentContextController(ArticleService articles, SiteService site,
 
     @GetMapping("/{slug}/comments/form-context")
     public FormContext formContext(@PathVariable String slug, CsrfToken csrfToken) {
-        var article = articles.findPublicBySlug(slug).orElseThrow(() -> new ArticleNotFoundException(slug));
+        var article = articles.findPublicCommentTarget(slug).orElseThrow(() -> new ArticleNotFoundException(slug));
         var issued = challenges.issue(article.articleId());
         return new FormContext(csrfToken.getToken(), issued.token(), issued.expiresAt(),
                 site.get().commentsEnabled() && article.commentsEnabled());
diff --git a/apps/api/src/main/java/io/haoblog/content/application/ArticleCommentLookup.java b/apps/api/src/main/java/io/haoblog/content/application/ArticleCommentLookup.java
new file mode 100644
index 0000000..87d4c5d
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/content/application/ArticleCommentLookup.java
@@ -0,0 +1,11 @@
+package io.haoblog.content.application;
+
+import java.util.Optional;
+import java.util.UUID;
+
+/** 为 comment 模块公开文章身份和评论开关，不暴露 content 实体或仓储。 */
+public interface ArticleCommentLookup {
+    Optional<Target> findPublicCommentTarget(String slug);
+
+    record Target(UUID articleId, boolean commentsEnabled) {}
+}
diff --git a/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java b/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
index 8a75908..202597f 100644
--- a/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
+++ b/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
@@ -19,7 +19,7 @@
 import java.util.stream.Collectors;
 
 @Service
-public class ArticleService {
+public class ArticleService implements ArticleCommentLookup {
     private final ArticleRevisionRepository repository;
     private final MediaAssetRepository mediaRepository;
     private final Clock clock;
@@ -42,6 +42,12 @@ public Optional<PublicArticle> findPublicBySlug(String slug) {
                 .map(this::toPublicArticle);
     }
 
+    @Override
+    public Optional<ArticleCommentLookup.Target> findPublicCommentTarget(String slug) {
+        return findPublicBySlug(slug)
+                .map(article -> new ArticleCommentLookup.Target(article.articleId(), article.commentsEnabled()));
+    }
+
     public PublishedBatch listPublishedBatch(int page, int size) {
         if (page < 0 || size < 1 || size > 500) throw new IllegalArgumentException("page/size out of range");
         var result = repository.findPublished(ArticleStatus.PUBLISHED, java.time.Instant.now(clock), PageRequest.of(page, size));
diff --git a/apps/api/src/main/resources/db/migration/V11__comment_security_and_outbox_payloads.sql b/apps/api/src/main/resources/db/migration/V11__comment_security_and_outbox_payloads.sql
new file mode 100644
index 0000000..440ae99
--- /dev/null
+++ b/apps/api/src/main/resources/db/migration/V11__comment_security_and_outbox_payloads.sql
@@ -0,0 +1,49 @@
+ALTER TABLE comment
+    RENAME COLUMN body TO content;
+
+ALTER TABLE comment
+    RENAME COLUMN moderated_by TO moderator_id;
+
+ALTER TABLE comment
+    ADD COLUMN email_key_version integer,
+    ADD COLUMN ip_hmac_date date;
+
+UPDATE comment
+SET email_key_version = 1
+WHERE email_ciphertext IS NOT NULL;
+
+UPDATE comment
+SET ip_hmac_date = (created_at AT TIME ZONE 'UTC')::date;
+
+ALTER TABLE comment
+    ALTER COLUMN ip_hmac_date SET NOT NULL,
+    DROP CONSTRAINT comment_email_pair,
+    ADD CONSTRAINT comment_email_pair CHECK (
+        (email_ciphertext IS NULL AND email_nonce IS NULL AND email_key_version IS NULL)
+        OR (email_ciphertext IS NOT NULL AND email_nonce IS NOT NULL AND email_key_version = 1)
+    ),
+    ADD CONSTRAINT comment_uuid_v7_check CHECK (substring(id::text, 15, 1) = '7');
+
+ALTER TABLE outbox_event
+    DROP CONSTRAINT outbox_article_payload,
+    ADD CONSTRAINT outbox_event_payload_by_type CHECK (
+        event_type NOT IN ('ARTICLE_PUBLISHED', 'COMMENT_CREATED')
+        OR (
+            event_type = 'ARTICLE_PUBLISHED'
+            AND jsonb_typeof(payload) = 'object'
+            AND payload->>'eventType' = 'ARTICLE_PUBLISHED'
+            AND payload ?& ARRAY['articleId', 'revisionId', 'eventType', 'occurredAt']
+            AND (payload - ARRAY['articleId', 'revisionId', 'eventType', 'occurredAt']) = '{}'::jsonb
+        )
+        OR (
+            event_type = 'COMMENT_CREATED'
+            AND jsonb_typeof(payload) = 'object'
+            AND payload->>'eventType' = 'COMMENT_CREATED'
+            AND payload ?& ARRAY['commentId', 'articleId', 'eventType', 'occurredAt']
+            AND (payload - ARRAY['commentId', 'articleId', 'eventType', 'occurredAt']) = '{}'::jsonb
+        )
+    );
+
+CREATE UNIQUE INDEX outbox_comment_created_uq
+    ON outbox_event (aggregate_id, event_type)
+    WHERE event_type = 'COMMENT_CREATED';
diff --git a/apps/api/src/test/java/io/haoblog/ArchitectureTest.java b/apps/api/src/test/java/io/haoblog/ArchitectureTest.java
index 7238774..488c6fd 100644
--- a/apps/api/src/test/java/io/haoblog/ArchitectureTest.java
+++ b/apps/api/src/test/java/io/haoblog/ArchitectureTest.java
@@ -16,8 +16,14 @@ class ArchitectureTest {
 
     @ArchTest
     static final ArchRule other_modules_must_not_depend_on_content_internals = noClasses()
-            .that().resideInAnyPackage("io.haoblog.identity..", "io.haoblog.comment..",
+            .that().resideInAnyPackage("io.haoblog.identity..",
                     "io.haoblog.toolbox..", "io.haoblog.ai..", "io.haoblog.media..", "io.haoblog.site..")
             .should().dependOnClassesThat().resideInAnyPackage(
                     "io.haoblog.content.persistence..", "io.haoblog.content.domain..");
+
+    @ArchTest
+    static final ArchRule comment_must_use_content_public_boundary = noClasses()
+            .that().resideInAnyPackage("io.haoblog.comment..")
+            .should().dependOnClassesThat().resideInAnyPackage(
+                    "io.haoblog.content.persistence..", "io.haoblog.content.domain..");
 }
diff --git a/apps/api/src/test/java/io/haoblog/ContentModelIT.java b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
index 795d677..53ea8c6 100644
--- a/apps/api/src/test/java/io/haoblog/ContentModelIT.java
+++ b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
@@ -1,8 +1,12 @@
 package io.haoblog;
 
+import io.haoblog.comment.domain.Comment;
+import io.haoblog.comment.domain.CommentStatus;
+import io.haoblog.comment.persistence.CommentRepository;
 import io.haoblog.content.domain.Article;
 import io.haoblog.content.domain.ArticleStatus;
 import io.haoblog.content.persistence.ArticleRepository;
+import io.haoblog.shared.id.UuidV7;
 import jakarta.persistence.EntityManager;
 import jakarta.persistence.EntityManagerFactory;
 import jakarta.persistence.RollbackException;
@@ -20,6 +24,7 @@
 import java.nio.charset.StandardCharsets;
 import java.security.MessageDigest;
 import java.time.Instant;
+import java.time.ZoneOffset;
 import java.time.temporal.ChronoUnit;
 import java.sql.Timestamp;
 import java.util.List;
@@ -47,11 +52,12 @@ static void database(DynamicPropertyRegistry registry) {
 
     @Autowired JdbcTemplate jdbc;
     @Autowired ArticleRepository articles;
+    @Autowired CommentRepository comments;
     @Autowired EntityManagerFactory entityManagerFactory;
 
     @Test
     void migratesAllVersionsAndCreatesContentTables() {
-        assertEquals(10, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
+        assertEquals(11, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
         for (String table : List.of("article", "category", "tag", "article_tag", "article_revision",
                 "article_preview_token", "media_asset", "media_upload", "outbox_event", "comment")) {
             assertEquals(1, jdbc.queryForObject(
@@ -66,6 +72,24 @@ void migratesAllVersionsAndCreatesContentTables() {
                 "SELECT data_type FROM information_schema.columns WHERE table_name='article' AND column_name='comments_enabled'", String.class));
         assertEquals("boolean", jdbc.queryForObject(
                 "SELECT data_type FROM information_schema.columns WHERE table_name='site_setting' AND column_name='comments_enabled'", String.class));
+        assertEquals("bigint", jdbc.queryForObject(
+                "SELECT data_type FROM information_schema.columns WHERE table_name='site_setting' AND column_name='version'", String.class));
+        for (String column : List.of("article_id", "parent_id", "content", "email_ciphertext", "email_nonce",
+                "email_key_version", "ip_hmac", "ip_hmac_date", "content_fingerprint", "delete_token_digest",
+                "moderator_id", "moderation_reason", "moderated_at", "version", "created_at", "updated_at")) {
+            assertEquals(1, jdbc.queryForObject(
+                    "SELECT count(*) FROM information_schema.columns WHERE table_name='comment' AND column_name=?",
+                    Integer.class, column));
+        }
+        for (String index : List.of("comment_article_status_created_idx", "comment_parent_created_idx", "outbox_comment_created_uq")) {
+            assertEquals(1, jdbc.queryForObject(
+                    "SELECT count(*) FROM pg_indexes WHERE schemaname='public' AND indexname=?", Integer.class, index));
+        }
+        for (String constraint : List.of("comment_article_parent_fk", "comment_email_pair", "comment_uuid_v7_check",
+                "outbox_event_payload_by_type")) {
+            assertEquals(1, jdbc.queryForObject(
+                    "SELECT count(*) FROM pg_constraint WHERE conname=?", Integer.class, constraint));
+        }
     }
 
     @Test
@@ -170,7 +194,7 @@ void articleRevisionCannotBeUpdatedOrDeleted() {
     }
 
     @Test
-    void outboxPayloadIsRestrictedToPublicationEnvelope() {
+    void outboxPayloadsAreRestrictedAndDeduplicatedByEventType() {
         Instant now = Instant.now();
         Timestamp timestamp = Timestamp.from(now);
         UUID eventId = UUID.randomUUID();
@@ -190,6 +214,94 @@ void outboxPayloadIsRestrictedToPublicationEnvelope() {
         assertThrows(DataAccessException.class, () -> jdbc.update(
                 "INSERT INTO outbox_event(id, aggregate_id, event_type, payload, available_at, created_at) VALUES (?, ?, ?, ?::jsonb, ?, ?)",
                 UUID.randomUUID(), UUID.randomUUID(), "ARTICLE_PUBLISHED", "{\"articleId\":\"x\",\"revisionId\":\"y\",\"eventType\":\"x\",\"occurredAt\":\"z\",\"markdown\":\"secret\"}", timestamp, timestamp));
+
+        UUID commentId = UuidV7.generate();
+        String commentPayload = "{\"commentId\":\"" + commentId + "\",\"articleId\":\"" + aggregateId
+                + "\",\"eventType\":\"COMMENT_CREATED\",\"occurredAt\":\"" + now + "\"}";
+        jdbc.update("INSERT INTO outbox_event(id, aggregate_id, event_type, payload, available_at, created_at) VALUES (?, ?, ?, ?::jsonb, ?, ?)",
+                UUID.randomUUID(), commentId, "COMMENT_CREATED", commentPayload, timestamp, timestamp);
+        assertThrows(DataAccessException.class, () -> jdbc.update(
+                "INSERT INTO outbox_event(id, aggregate_id, event_type, payload, available_at, created_at) VALUES (?, ?, ?, ?::jsonb, ?, ?)",
+                UUID.randomUUID(), commentId, "COMMENT_CREATED", commentPayload, timestamp, timestamp));
+        assertThrows(DataAccessException.class, () -> jdbc.update(
+                "INSERT INTO outbox_event(id, aggregate_id, event_type, payload, available_at, created_at) VALUES (?, ?, ?, ?::jsonb, ?, ?)",
+                UUID.randomUUID(), UUID.randomUUID(), "COMMENT_CREATED",
+                commentPayload.replace("COMMENT_CREATED", "ARTICLE_PUBLISHED"), timestamp, timestamp));
+    }
+
+    @Test
+    void commentConstraintsStatusParentAndUuidAreEnforced() {
+        Instant now = Instant.now();
+        Timestamp timestamp = Timestamp.from(now);
+        UUID articleId = UUID.randomUUID();
+        UUID otherArticleId = UUID.randomUUID();
+        insertDraft(articleId, "comment-article-" + articleId);
+        insertDraft(otherArticleId, "comment-article-" + otherArticleId);
+        UUID parentId = UuidV7.generate();
+        byte[] digest = new byte[32];
+        jdbc.update("INSERT INTO comment(id, article_id, nickname, content, ip_hmac, ip_hmac_date, content_fingerprint, delete_token_digest, created_at, updated_at) "
+                        + "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                parentId, articleId, "Hao", "parent", digest, now.atZone(ZoneOffset.UTC).toLocalDate(), digest, digest, timestamp, timestamp);
+        assertEquals("PENDING", jdbc.queryForObject("SELECT status FROM comment WHERE id=?", String.class, parentId));
+        assertThrows(DataAccessException.class, () -> jdbc.update(
+                "INSERT INTO comment(id, article_id, nickname, content, status, ip_hmac, ip_hmac_date, content_fingerprint, delete_token_digest, created_at, updated_at) "
+                        + "VALUES (?, ?, ?, ?, 'UNKNOWN', ?, ?, ?, ?, ?, ?)",
+                UuidV7.generate(), articleId, "Hao", "invalid", digest, now.atZone(ZoneOffset.UTC).toLocalDate(), digest, new byte[31], timestamp, timestamp));
+        assertThrows(DataAccessException.class, () -> jdbc.update(
+                "INSERT INTO comment(id, article_id, nickname, content, ip_hmac, ip_hmac_date, content_fingerprint, delete_token_digest, created_at, updated_at) "
+                        + "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                UUID.randomUUID(), articleId, "Hao", "not v7", digest, now.atZone(ZoneOffset.UTC).toLocalDate(), digest, new byte[32], timestamp, timestamp));
+        assertThrows(DataAccessException.class, () -> jdbc.update(
+                "INSERT INTO comment(id, article_id, parent_id, nickname, content, ip_hmac, ip_hmac_date, content_fingerprint, delete_token_digest, created_at, updated_at) "
+                        + "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                UuidV7.generate(), otherArticleId, parentId, "Hao", "wrong parent article", digest, now.atZone(ZoneOffset.UTC).toLocalDate(), digest,
+                new byte[32], timestamp, timestamp));
+    }
+
+    @Test
+    void commentStatusPersistsAndOptimisticLockRejectsStaleUpdate() {
+        Instant now = Instant.now();
+        Article article = articles.saveAndFlush(new Article("comment-lock-" + UUID.randomUUID(), "Comment lock", null, "# lock",
+                ArticleStatus.DRAFT, null, now));
+        byte[] deleteTokenDigest;
+        try {
+            deleteTokenDigest = MessageDigest.getInstance("SHA-256")
+                    .digest(UUID.randomUUID().toString().getBytes(StandardCharsets.UTF_8));
+        } catch (Exception exception) {
+            throw new AssertionError(exception);
+        }
+        Comment saved = comments.saveAndFlush(new Comment(article.getId(), null, "Hao", null, null, null,
+                "body", new byte[32], now.atZone(ZoneOffset.UTC).toLocalDate(), new byte[32], deleteTokenDigest, now));
+        assertEquals(7, saved.getId().version());
+        assertEquals(CommentStatus.PENDING, saved.getStatus());
+        EntityManager firstManager = entityManagerFactory.createEntityManager();
+        EntityManager secondManager = entityManagerFactory.createEntityManager();
+        var firstTransaction = firstManager.getTransaction();
+        var secondTransaction = secondManager.getTransaction();
+        try {
+            firstTransaction.begin();
+            secondTransaction.begin();
+            Comment first = firstManager.find(Comment.class, saved.getId());
+            Comment second = secondManager.find(Comment.class, saved.getId());
+            first.moderate(CommentStatus.APPROVED, UUID.fromString("0198a4f0-0000-7000-8000-000000000002"), "ok", now.plusSeconds(1));
+            firstTransaction.commit();
+            assertEquals(1, first.getVersion());
+            assertEquals(CommentStatus.APPROVED, first.getStatus());
+            second.moderate(CommentStatus.SPAM, null, "stale", now.plusSeconds(2));
+            assertThrows(RollbackException.class, secondTransaction::commit);
+        } finally {
+            if (firstTransaction.isActive()) firstTransaction.rollback();
+            if (secondTransaction.isActive()) secondTransaction.rollback();
+            firstManager.close();
+            secondManager.close();
+        }
+    }
+
+    private void insertDraft(UUID id, String slug) {
+        Instant now = Instant.now();
+        Timestamp timestamp = Timestamp.from(now);
+        jdbc.update("INSERT INTO article(id, slug, title, markdown_source, status, created_at, updated_at) VALUES (?, ?, ?, ?, 'DRAFT', ?, ?)",
+                id, slug, "Comment article", "# article", timestamp, timestamp);
     }
 
     private static String toJson(Map<String, Object> values) {
diff --git a/apps/api/src/test/java/io/haoblog/comment/application/CommentSecurityServiceTest.java b/apps/api/src/test/java/io/haoblog/comment/application/CommentSecurityServiceTest.java
index 5d39a53..4b82463 100644
--- a/apps/api/src/test/java/io/haoblog/comment/application/CommentSecurityServiceTest.java
+++ b/apps/api/src/test/java/io/haoblog/comment/application/CommentSecurityServiceTest.java
@@ -25,14 +25,23 @@ void encryptsEmailWithAuthenticatedRandomNonce() {
         var first = security.encryptEmail(COMMENT_ID, "author@example.test");
         var second = security.encryptEmail(COMMENT_ID, "author@example.test");
 
+        assertEquals(1, first.keyVersion());
         assertNotEquals(Base64.getEncoder().encodeToString(first.nonce()), Base64.getEncoder().encodeToString(second.nonce()));
+        assertNotEquals(Base64.getEncoder().encodeToString(first.ciphertext()), Base64.getEncoder().encodeToString(second.ciphertext()));
+        assertFalse(new String(first.ciphertext(), StandardCharsets.UTF_8).contains("author@example.test"));
         assertEquals("author@example.test", security.decryptEmail(COMMENT_ID, first));
         assertThrows(IllegalArgumentException.class, () -> security.decryptEmail(UUID.randomUUID(), first));
+
+        byte[] tampered = first.ciphertext();
+        tampered[tampered.length - 1] ^= 1;
+        assertThrows(IllegalArgumentException.class, () -> security.decryptEmail(
+                COMMENT_ID, new CommentSecurityService.EmailCiphertext(1, first.nonce(), tampered)));
     }
 
     @Test
     void derivesScopedDigests() {
         var today = security.dailyIpHmac("192.0.2.1", LocalDate.of(2026, 8, 22));
+        assertArrayEquals(today, security.dailyIpHmac("192.0.2.1", LocalDate.of(2026, 8, 22)));
         var tomorrow = security.dailyIpHmac("192.0.2.1", LocalDate.of(2026, 8, 23));
 
         assertFalse(java.util.Arrays.equals(today, tomorrow));
@@ -42,6 +51,7 @@ void derivesScopedDigests() {
 
     @Test
     void rejectsInvalidKey() {
+        assertThrows(IllegalArgumentException.class, () -> new CommentSecurityService(" "));
         assertThrows(IllegalArgumentException.class, () -> new CommentSecurityService(
                 Base64.getEncoder().encodeToString(new byte[16])));
     }

From d9dac8b2648049f7962b5e40bbd8ee60bfaea18c Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sat, 22 Aug 2026 23:17:53 +0800
Subject: [PATCH 03/15] =?UTF-8?q?=E9=98=B6=E6=AE=B5=E5=9B=9B=EF=BC=9A?=
 =?UTF-8?q?=E5=AE=8C=E6=88=90=E5=85=AC=E5=85=B1=E8=AF=84=E8=AE=BA=E5=AE=89?=
 =?UTF-8?q?=E5=85=A8=E9=97=AD=E7=8E=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../application/CommentChallengeService.java  |  32 ++-
 .../CommentRateLimitException.java            |  12 +
 .../application/CommentRateLimiter.java       |  72 +++++
 .../application/CommentSecurityService.java   |  12 +
 .../comment/application/CommentService.java   | 248 ++++++++++++++++++
 .../io/haoblog/comment/domain/Comment.java    |  23 ++
 .../persistence/CommentRepository.java        |  15 +-
 .../web/PublicCommentContextController.java   |  26 +-
 .../comment/web/PublicCommentController.java  |  94 +++++++
 .../shared/web/GlobalExceptionHandler.java    |  10 +-
 .../V12__comment_fingerprint_uniqueness.sql   |   2 +
 .../test/java/io/haoblog/ContentModelIT.java  |   5 +-
 .../CommentChallengeServiceTest.java          |  13 +
 .../application/CommentRateLimiterTest.java   |  49 ++++
 .../application/CommentServiceTest.java       | 183 +++++++++++++
 docs/openapi/public-api.yaml                  | 116 ++++++++
 infra/compose/compose.prod.yml                |   1 +
 packages/api-client/src/generated.ts          | 184 +++++++++++++
 18 files changed, 1079 insertions(+), 18 deletions(-)
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/application/CommentRateLimitException.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/application/CommentRateLimiter.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/application/CommentService.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/web/PublicCommentController.java
 create mode 100644 apps/api/src/main/resources/db/migration/V12__comment_fingerprint_uniqueness.sql
 create mode 100644 apps/api/src/test/java/io/haoblog/comment/application/CommentRateLimiterTest.java
 create mode 100644 apps/api/src/test/java/io/haoblog/comment/application/CommentServiceTest.java

diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentChallengeService.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentChallengeService.java
index 2f5746e..8fd22d2 100644
--- a/apps/api/src/main/java/io/haoblog/comment/application/CommentChallengeService.java
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentChallengeService.java
@@ -36,17 +36,27 @@ public IssuedChallenge issue(UUID articleId) {
     }
 
     public boolean consume(UUID articleId, String token) {
-        if (token == null || token.isBlank()) return false;
-        Challenge challenge = challenges.getIfPresent(token);
-        if (challenge == null) return false;
+        return validateAndConsume(articleId, token) == Validation.VALID;
+    }
+
+    public Validation validateAndConsume(UUID articleId, String token) {
+        if (token == null || token.isBlank()) return Validation.INVALID;
         Instant now = clock.instant();
-        if (!challenge.articleId().equals(articleId)
-                || now.isBefore(challenge.issuedAt().plus(MINIMUM_FILL_TIME))
-                || !challenge.expiresAt().isAfter(now)) {
-            return false;
-        }
-        challenges.invalidate(token);
-        return true;
+        var result = new Validation[] {Validation.INVALID};
+        challenges.asMap().computeIfPresent(token, (key, challenge) -> {
+            if (!challenge.articleId().equals(articleId)) return challenge;
+            if (now.isBefore(challenge.issuedAt().plus(MINIMUM_FILL_TIME))) {
+                result[0] = Validation.TOO_EARLY;
+                return challenge;
+            }
+            if (!challenge.expiresAt().isAfter(now)) {
+                result[0] = Validation.EXPIRED;
+                return null;
+            }
+            result[0] = Validation.VALID;
+            return null;
+        });
+        return result[0];
     }
 
     long cacheSize() {
@@ -56,5 +66,7 @@ long cacheSize() {
 
     public record IssuedChallenge(String token, Instant expiresAt) {}
 
+    public enum Validation { VALID, INVALID, TOO_EARLY, EXPIRED }
+
     private record Challenge(UUID articleId, Instant issuedAt, Instant expiresAt) {}
 }
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentRateLimitException.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentRateLimitException.java
new file mode 100644
index 0000000..ea57e27
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentRateLimitException.java
@@ -0,0 +1,12 @@
+package io.haoblog.comment.application;
+
+public class CommentRateLimitException extends RuntimeException {
+    private final long retryAfterSeconds;
+
+    public CommentRateLimitException(long retryAfterSeconds) {
+        super("Comment rate limit exceeded");
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+
+    public long getRetryAfterSeconds() { return retryAfterSeconds; }
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentRateLimiter.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentRateLimiter.java
new file mode 100644
index 0000000..2e656c3
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentRateLimiter.java
@@ -0,0 +1,72 @@
+package io.haoblog.comment.application;
+
+import com.github.benmanes.caffeine.cache.Cache;
+import com.github.benmanes.caffeine.cache.Caffeine;
+import org.springframework.stereotype.Component;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneOffset;
+import java.util.ArrayList;
+import java.util.List;
+
+@Component
+public class CommentRateLimiter {
+    static final Duration SHORT_WINDOW = Duration.ofMinutes(10);
+    static final int SHORT_LIMIT = 3;
+    static final int DAILY_LIMIT = 10;
+    private static final long MAX_CACHE_SIZE = 4096;
+
+    private final Clock clock;
+    private final Cache<String, State> states = Caffeine.newBuilder()
+            .maximumSize(MAX_CACHE_SIZE)
+            .expireAfterAccess(Duration.ofDays(1))
+            .build();
+
+    public CommentRateLimiter(Clock clock) {
+        this.clock = clock;
+    }
+
+    public Decision checkAndRecord(String source) {
+        Instant now = clock.instant();
+        String dayKey = source + ":" + LocalDate.ofInstant(now, ZoneOffset.UTC);
+        var result = new Decision[] {Decision.permitted()};
+        states.asMap().compute(dayKey, (key, state) -> {
+            List<Instant> recent = state == null ? new ArrayList<>() : new ArrayList<>(state.timestamps());
+            recent.removeIf(time -> !time.plus(Duration.ofDays(1)).isAfter(now));
+            long shortCount = recent.stream().filter(time -> time.plus(SHORT_WINDOW).isAfter(now)).count();
+            if (shortCount >= SHORT_LIMIT) {
+                Instant earliest = recent.stream()
+                        .filter(time -> time.plus(SHORT_WINDOW).isAfter(now))
+                        .min(Instant::compareTo).orElse(now);
+                result[0] = new Decision(false, retryAfter(now, earliest.plus(SHORT_WINDOW)));
+                return new State(List.copyOf(recent));
+            }
+            if (recent.size() >= DAILY_LIMIT) {
+                result[0] = new Decision(false, retryAfter(now,
+                        LocalDate.ofInstant(now, ZoneOffset.UTC).plusDays(1).atStartOfDay().toInstant(ZoneOffset.UTC)));
+                return new State(List.copyOf(recent));
+            }
+            recent.add(now);
+            return new State(List.copyOf(recent));
+        });
+        return result[0];
+    }
+
+    long cacheSize() {
+        states.cleanUp();
+        return states.estimatedSize();
+    }
+
+    private static long retryAfter(Instant now, Instant availableAt) {
+        return Math.max(1, (Duration.between(now, availableAt).toMillis() + 999) / 1000);
+    }
+
+    public record Decision(boolean allowed, long retryAfterSeconds) {
+        static Decision permitted() { return new Decision(true, 0); }
+    }
+
+    private record State(List<Instant> timestamps) {}
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
index 75eb104..2288653 100644
--- a/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
@@ -90,6 +90,18 @@ public String challengeToken(UUID articleId, java.time.Instant issuedAt) {
                 hmac(challengeKey, "challenge-v1:" + articleId + ":" + issuedAt + ":" + UUID.randomUUID()));
     }
 
+    public String newVisitorToken() {
+        byte[] token = new byte[32];
+        random.nextBytes(token);
+        return Base64.getUrlEncoder().withoutPadding().encodeToString(token);
+    }
+
+    public String newDeleteToken() {
+        byte[] token = new byte[32];
+        random.nextBytes(token);
+        return Base64.getUrlEncoder().withoutPadding().encodeToString(token);
+    }
+
     private static byte[] derive(byte[] masterKey, String purpose) {
         return hmac(masterKey, "haoblog-comment-key:" + purpose);
     }
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java
new file mode 100644
index 0000000..38f368f
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java
@@ -0,0 +1,248 @@
+package io.haoblog.comment.application;
+
+import io.haoblog.comment.domain.Comment;
+import io.haoblog.comment.domain.CommentStatus;
+import io.haoblog.comment.persistence.CommentRepository;
+import io.haoblog.content.application.ArticleCommentLookup;
+import io.haoblog.shared.outbox.OutboxEvent;
+import io.haoblog.shared.outbox.OutboxEventRepository;
+import io.haoblog.shared.web.ProblemException;
+import io.haoblog.site.application.SiteService;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.stereotype.Service;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneOffset;
+import java.text.Normalizer;
+import java.util.Base64;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.UUID;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+@Service
+public class CommentService {
+    private static final Pattern URL_SCHEME = Pattern.compile("(?i)\\b([a-z][a-z0-9+.-]*)://");
+    private static final Pattern UNSAFE_SCHEME = Pattern.compile("(?i)(?:javascript|data|vbscript|file|mailto):");
+    private static final Pattern RAW_HTML = Pattern.compile("(?is)<\\s*/?\\s*[a-z!][^>]*>");
+    private static final Pattern HTTPS_LINK = Pattern.compile("(?i)https://");
+    private static final int MAX_PAGE_SIZE = 50;
+
+    private final CommentRepository comments;
+    private final OutboxEventRepository outbox;
+    private final ArticleCommentLookup articles;
+    private final SiteService site;
+    private final CommentSecurityService security;
+    private final CommentChallengeService challenges;
+    private final CommentRateLimiter rateLimiter;
+    private final Clock clock;
+
+    public CommentService(CommentRepository comments, OutboxEventRepository outbox,
+                          ArticleCommentLookup articles, SiteService site,
+                          CommentSecurityService security, CommentChallengeService challenges,
+                          CommentRateLimiter rateLimiter, Clock clock) {
+        this.comments = comments;
+        this.outbox = outbox;
+        this.articles = articles;
+        this.site = site;
+        this.security = security;
+        this.challenges = challenges;
+        this.rateLimiter = rateLimiter;
+        this.clock = clock;
+    }
+
+    @Transactional
+    public CommentPage list(String slug, int page, int size) {
+        if (page < 0 || size < 1 || size > MAX_PAGE_SIZE) {
+            throw new IllegalArgumentException("page/size out of range");
+        }
+        UUID articleId = publicArticle(slug).articleId();
+        if (!site.get().commentsEnabled()) {
+            return new CommentPage(List.of(), page, size, 0);
+        }
+        Page<Comment> topLevel = comments.findByArticleIdAndStatusAndParentIdIsNullOrderByCreatedAtAscIdAsc(
+                articleId, CommentStatus.APPROVED, PageRequest.of(page, size));
+        List<UUID> parentIds = topLevel.getContent().stream().map(Comment::getId).toList();
+        Map<UUID, List<Comment>> replies = parentIds.isEmpty() ? Map.of() : comments
+                .findByArticleIdAndStatusAndParentIdInOrderByCreatedAtAscIdAsc(
+                        articleId, CommentStatus.APPROVED, parentIds)
+                .stream().collect(java.util.stream.Collectors.groupingBy(
+                        Comment::getParentId, LinkedHashMap::new, java.util.stream.Collectors.toList()));
+        List<CommentView> items = topLevel.getContent().stream()
+                .map(comment -> view(comment, replies.getOrDefault(comment.getId(), List.of())))
+                .toList();
+        return new CommentPage(items, topLevel.getNumber(), topLevel.getSize(), topLevel.getTotalElements());
+    }
+
+    @Transactional
+    public CreateResult create(String slug, CreateCommand command, String visitorCookie, String remoteAddress) {
+        ArticleCommentLookup.Target target = publicArticle(slug);
+        if (!site.get().commentsEnabled() || !target.commentsEnabled()) {
+            throw new ProblemException("COMMENTING_DISABLED", "Comments are disabled",
+                    "Comments are not currently accepting new submissions");
+        }
+        String nickname = requiredTrimmed(command.nickname(), "COMMENT_NICKNAME_INVALID", "Nickname must be 2 to 40 characters");
+        String content = requiredTrimmed(command.content(), "COMMENT_CONTENT_INVALID", "Content must be 2 to 2000 characters");
+        String email = command.email() == null ? null : command.email().trim();
+        validateLengths(nickname, content, email);
+        validateContent(content);
+
+        CommentChallengeService.Validation challenge = challenges.validateAndConsume(target.articleId(), command.challenge());
+        if (challenge != CommentChallengeService.Validation.VALID) {
+            throw switch (challenge) {
+                case TOO_EARLY -> new ProblemException("COMMENT_CHALLENGE_TOO_EARLY", "Comment challenge submitted too soon",
+                        "Please keep the form open for at least three seconds");
+                case EXPIRED -> new ProblemException("COMMENT_CHALLENGE_EXPIRED", "Comment challenge expired",
+                        "Request a new comment form challenge");
+                default -> new ProblemException("COMMENT_CHALLENGE_INVALID", "Invalid comment challenge",
+                        "Request a new comment form challenge");
+            };
+        }
+
+        String honeypot = command.honeypot();
+        if ((honeypot != null && !honeypot.isBlank()) || (command.website() != null && !command.website().isBlank())) {
+            RateDecision rate = rate(visitorCookie, remoteAddress);
+            if (!rate.allowed()) throw new CommentRateLimitException(rate.retryAfterSeconds());
+            return new CreateResult(null, CommentStatus.PENDING, clock.instant(), null);
+        }
+
+        UUID parentId = command.parentId();
+        if (parentId != null && comments.findByIdAndArticleIdAndStatusAndParentIdIsNull(
+                parentId, target.articleId(), CommentStatus.APPROVED).isEmpty()) {
+            throw new ProblemException("COMMENT_PARENT_INVALID", "Invalid parent comment",
+                    "Replies must target an approved top-level comment on the same article");
+        }
+        byte[] fingerprint = security.contentFingerprint(target.articleId(), normalizeForFingerprint(content));
+        if (comments.existsByArticleIdAndContentFingerprint(target.articleId(), fingerprint)) {
+            throw new ProblemException("COMMENT_DUPLICATE", "Duplicate comment",
+                    "An equivalent comment has already been submitted");
+        }
+        RateDecision rate = rate(visitorCookie, remoteAddress);
+        if (!rate.allowed()) throw new CommentRateLimitException(rate.retryAfterSeconds());
+
+        Instant now = clock.instant();
+        UUID commentId = io.haoblog.shared.id.UuidV7.generate();
+        String deleteToken = security.newDeleteToken();
+        CommentSecurityService.EmailCiphertext encryptedEmail = security.encryptEmail(commentId, email);
+        Comment comment = new Comment(commentId, target.articleId(), parentId, nickname,
+                encryptedEmail == null ? null : encryptedEmail.ciphertext(),
+                encryptedEmail == null ? null : encryptedEmail.nonce(),
+                encryptedEmail == null ? null : encryptedEmail.keyVersion(), content,
+                security.dailyIpHmac(remoteAddress, LocalDate.ofInstant(now, ZoneOffset.UTC)),
+                LocalDate.ofInstant(now, ZoneOffset.UTC), fingerprint,
+                security.deleteTokenDigest(deleteToken), now);
+        comments.save(comment);
+        outbox.save(new OutboxEvent(commentId, "COMMENT_CREATED", Map.of(
+                "commentId", commentId.toString(),
+                "articleId", target.articleId().toString(),
+                "eventType", "COMMENT_CREATED",
+                "occurredAt", now.toString()), now, now));
+        return new CreateResult(commentId, CommentStatus.PENDING, now, deleteToken);
+    }
+
+    @Transactional
+    public void delete(UUID commentId, String deleteToken) {
+        Comment comment = comments.findById(commentId).orElseThrow(() ->
+                new ProblemException("COMMENT_NOT_FOUND", "Comment not found", "The requested comment does not exist"));
+        if (comment.getStatus() == CommentStatus.USER_DELETED) {
+            throw new ProblemException("COMMENT_ALREADY_DELETED", "Comment already deleted", "The comment has already been deleted");
+        }
+        if (deleteToken == null || deleteToken.isBlank()
+                || !java.security.MessageDigest.isEqual(comment.getDeleteTokenDigest(), security.deleteTokenDigest(deleteToken))) {
+            throw new ProblemException("COMMENT_DELETE_TOKEN_INVALID", "Invalid delete token", "The delete token is invalid");
+        }
+        comment.userDelete(clock.instant());
+    }
+
+    private RateDecision rate(String visitorCookie, String remoteAddress) {
+        String source = validVisitorCookie(visitorCookie)
+                ? "visitor:" + visitorCookie
+                : "ip:" + Base64.getUrlEncoder().withoutPadding().encodeToString(
+                        security.dailyIpHmac(remoteAddress, LocalDate.ofInstant(clock.instant(), ZoneOffset.UTC)));
+        CommentRateLimiter.Decision decision = rateLimiter.checkAndRecord(source);
+        return new RateDecision(decision.allowed(), decision.retryAfterSeconds());
+    }
+
+    private ArticleCommentLookup.Target publicArticle(String slug) {
+        return articles.findPublicCommentTarget(slug).orElseThrow(() ->
+                new ProblemException("ARTICLE_NOT_FOUND", "Article not found", "The requested public article does not exist"));
+    }
+
+    private static boolean validVisitorCookie(String value) {
+        return value != null && value.matches("[A-Za-z0-9_-]{43}");
+    }
+
+    private static String requiredTrimmed(String value, String code, String detail) {
+        String normalized = value == null ? "" : value.strip();
+        if (normalized.isEmpty()) throw new ProblemException(code, "Invalid comment", detail);
+        return normalized;
+    }
+
+    private static void validateLengths(String nickname, String content, String email) {
+        checkCharacters(nickname, 2, 40, "COMMENT_NICKNAME_INVALID", "Nickname must be 2 to 40 characters");
+        checkCharacters(content, 2, 2000, "COMMENT_CONTENT_INVALID", "Content must be 2 to 2000 characters");
+        if (email != null && email.codePointCount(0, email.length()) > 254) {
+            throw new ProblemException("COMMENT_EMAIL_INVALID", "Invalid comment email", "Email must be at most 254 characters");
+        }
+    }
+
+    private static void checkCharacters(String value, int min, int max, String code, String detail) {
+        int length = value.codePointCount(0, value.length());
+        if (length < min || length > max) throw new ProblemException(code, "Invalid comment", detail);
+    }
+
+    private static void validateContent(String content) {
+        if (RAW_HTML.matcher(content).find() || content.indexOf('\u0000') >= 0) {
+            throw new ProblemException("COMMENT_CONTENT_INVALID", "Invalid comment content", "Raw HTML is not allowed");
+        }
+        Matcher unsafe = UNSAFE_SCHEME.matcher(content);
+        if (unsafe.find()) {
+            throw new ProblemException("COMMENT_LINK_PROTOCOL_INVALID", "Invalid comment link",
+                    "Only https links are allowed");
+        }
+        Matcher schemes = URL_SCHEME.matcher(content);
+        while (schemes.find()) {
+            if (!"https".equalsIgnoreCase(schemes.group(1))) {
+                throw new ProblemException("COMMENT_LINK_PROTOCOL_INVALID", "Invalid comment link",
+                        "Only https links are allowed");
+            }
+        }
+        Matcher links = HTTPS_LINK.matcher(content);
+        int count = 0;
+        while (links.find() && ++count <= 3) { /* 统计安全链接数量 */ }
+        if (count > 3) {
+            throw new ProblemException("COMMENT_TOO_MANY_LINKS", "Too many comment links",
+                    "At most three https links are allowed");
+        }
+    }
+
+    private static String normalizeForFingerprint(String content) {
+        return Normalizer.normalize(content, Normalizer.Form.NFC)
+                .replaceAll("\\s+", " ").strip().toLowerCase(Locale.ROOT);
+    }
+
+    private static CommentView view(Comment comment, List<Comment> replies) {
+        return new CommentView(comment.getId(), comment.getNickname(), comment.getContent(), comment.getCreatedAt(),
+                replies.stream().map(reply -> new CommentView(reply.getId(), reply.getNickname(), reply.getContent(),
+                        reply.getCreatedAt(), List.of())).toList());
+    }
+
+    public record CreateCommand(String nickname, String email, String content, UUID parentId,
+                                String challenge, String honeypot, String website) {}
+
+    public record CreateResult(UUID id, CommentStatus status, Instant createdAt, String deleteToken) {}
+
+    public record CommentPage(List<CommentView> items, int page, int size, long total) {}
+
+    public record CommentView(UUID id, String nickname, String content, Instant createdAt,
+                              List<CommentView> replies) {}
+
+    private record RateDecision(boolean allowed, long retryAfterSeconds) {}
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java b/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java
index 43647ad..126fd8a 100644
--- a/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java
+++ b/apps/api/src/main/java/io/haoblog/comment/domain/Comment.java
@@ -81,6 +81,16 @@ public Comment(UUID articleId, UUID parentId, String nickname, byte[] emailCiphe
         this.updatedAt = now;
     }
 
+    public Comment(UUID id, UUID articleId, UUID parentId, String nickname, byte[] emailCiphertext,
+                   byte[] emailNonce, Integer emailKeyVersion, String content, byte[] ipHmac,
+                   LocalDate ipHmacDate, byte[] contentFingerprint, byte[] deleteTokenDigest,
+                   Instant now) {
+        this(articleId, parentId, nickname, emailCiphertext, emailNonce, emailKeyVersion, content,
+                ipHmac, ipHmacDate, contentFingerprint, deleteTokenDigest, now);
+        if (id == null) throw new IllegalArgumentException("Comment id is required");
+        this.id = id;
+    }
+
     public UUID getId() { return id; }
     public UUID getArticleId() { return articleId; }
     public UUID getParentId() { return parentId; }
@@ -111,6 +121,19 @@ public void moderate(CommentStatus status, UUID moderatorId, String reason, Inst
         this.updatedAt = now;
     }
 
+    public void userDelete(Instant now) {
+        if (now == null) throw new IllegalArgumentException("Deletion time is required");
+        if (status == CommentStatus.USER_DELETED) throw new IllegalStateException("Comment is already deleted");
+        this.status = CommentStatus.USER_DELETED;
+        this.nickname = "";
+        this.content = "";
+        this.emailCiphertext = null;
+        this.emailNonce = null;
+        this.emailKeyVersion = null;
+        this.deletedAt = now;
+        this.updatedAt = now;
+    }
+
     private static byte[] copy(byte[] value) {
         return value == null ? null : Arrays.copyOf(value, value.length);
     }
diff --git a/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java b/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
index 15ca80f..28114f6 100644
--- a/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
+++ b/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
@@ -6,8 +6,21 @@
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.jpa.repository.JpaRepository;
 
+import java.util.List;
+import java.util.Optional;
 import java.util.UUID;
 
 public interface CommentRepository extends JpaRepository<Comment, UUID> {
-    Page<Comment> findByArticleIdAndStatusAndParentIdIsNull(UUID articleId, CommentStatus status, Pageable pageable);
+    Page<Comment> findByArticleIdAndStatusAndParentIdIsNullOrderByCreatedAtAscIdAsc(
+            UUID articleId, CommentStatus status, Pageable pageable);
+
+    List<Comment> findByArticleIdAndStatusAndParentIdInOrderByCreatedAtAscIdAsc(
+            UUID articleId, CommentStatus status, List<UUID> parentIds);
+
+    Optional<Comment> findByIdAndArticleId(UUID id, UUID articleId);
+
+    Optional<Comment> findByIdAndArticleIdAndStatusAndParentIdIsNull(
+            UUID id, UUID articleId, CommentStatus status);
+
+    boolean existsByArticleIdAndContentFingerprint(UUID articleId, byte[] contentFingerprint);
 }
diff --git a/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java b/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java
index 8e140b2..1c11d6d 100644
--- a/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java
+++ b/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentContextController.java
@@ -6,7 +6,11 @@
 import io.haoblog.site.application.SiteService;
 import org.slf4j.MDC;
 import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseCookie;
 import org.springframework.http.ResponseEntity;
+import jakarta.servlet.http.Cookie;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
 import org.springframework.security.web.csrf.CsrfToken;
 import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -15,6 +19,7 @@
 import org.springframework.web.bind.annotation.RestController;
 
 import java.time.Instant;
+import java.time.Duration;
 
 @RestController
 @RequestMapping("/api/v1/public/articles")
@@ -22,21 +27,38 @@ public class PublicCommentContextController {
     private final ArticleCommentLookup articles;
     private final SiteService site;
     private final CommentChallengeService challenges;
+    private final io.haoblog.comment.application.CommentSecurityService security;
 
-    public PublicCommentContextController(ArticleCommentLookup articles, SiteService site, CommentChallengeService challenges) {
+    public PublicCommentContextController(ArticleCommentLookup articles, SiteService site, CommentChallengeService challenges,
+                                          io.haoblog.comment.application.CommentSecurityService security) {
         this.articles = articles;
         this.site = site;
         this.challenges = challenges;
+        this.security = security;
     }
 
     @GetMapping("/{slug}/comments/form-context")
-    public FormContext formContext(@PathVariable String slug, CsrfToken csrfToken) {
+    public FormContext formContext(@PathVariable String slug, CsrfToken csrfToken,
+                                   HttpServletRequest request, HttpServletResponse response) {
         var article = articles.findPublicCommentTarget(slug).orElseThrow(() -> new ArticleNotFoundException(slug));
         var issued = challenges.issue(article.articleId());
+        if (visitorCookie(request) == null) {
+            response.addHeader("Set-Cookie", ResponseCookie.from("HAOBLOG_VISITOR", security.newVisitorToken())
+                    .httpOnly(true).sameSite("Lax").path("/").maxAge(Duration.ofDays(365)).build().toString());
+        }
         return new FormContext(csrfToken.getToken(), issued.token(), issued.expiresAt(),
                 site.get().commentsEnabled() && article.commentsEnabled());
     }
 
+    private String visitorCookie(HttpServletRequest request) {
+        if (request.getCookies() == null) return null;
+        for (Cookie cookie : request.getCookies()) {
+            if ("HAOBLOG_VISITOR".equals(cookie.getName()) && cookie.getValue() != null
+                    && cookie.getValue().matches("[A-Za-z0-9_-]{43}")) return cookie.getValue();
+        }
+        return null;
+    }
+
     @ExceptionHandler(ArticleNotFoundException.class)
     ResponseEntity<ProblemResponse> articleNotFound(ArticleNotFoundException ignored) {
         return ResponseEntity.status(HttpStatus.NOT_FOUND)
diff --git a/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentController.java b/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentController.java
new file mode 100644
index 0000000..d809e71
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/web/PublicCommentController.java
@@ -0,0 +1,94 @@
+package io.haoblog.comment.web;
+
+import io.haoblog.comment.application.CommentRateLimitException;
+import io.haoblog.comment.application.CommentService;
+import io.haoblog.shared.web.ProblemResponse;
+import io.haoblog.shared.web.ProblemResponseWriter;
+import jakarta.servlet.http.Cookie;
+import jakarta.servlet.http.HttpServletRequest;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.web.csrf.CsrfToken;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.time.Duration;
+import java.util.UUID;
+
+@RestController
+@RequestMapping("/api/v1/public")
+public class PublicCommentController {
+    private static final String VISITOR_COOKIE = "HAOBLOG_VISITOR";
+    private static final String DELETE_TOKEN_HEADER = "X-Comment-Delete-Token";
+
+    private final CommentService comments;
+    private final ProblemResponseWriter problemResponseWriter;
+
+    public PublicCommentController(CommentService comments, ProblemResponseWriter problemResponseWriter) {
+        this.comments = comments;
+        this.problemResponseWriter = problemResponseWriter;
+    }
+
+    @GetMapping("/articles/{slug}/comments")
+    public CommentService.CommentPage list(@PathVariable String slug,
+                                           @RequestParam(defaultValue = "0") int page,
+                                           @RequestParam(defaultValue = "20") int size) {
+        return comments.list(slug, page, size);
+    }
+
+    @PostMapping("/articles/{slug}/comments")
+    public ResponseEntity<SubmissionResponse> create(@PathVariable String slug,
+                                                      @RequestBody CommentRequest request,
+                                                      HttpServletRequest httpRequest) {
+        CommentService.CreateResult result = comments.create(slug,
+                new CommentService.CreateCommand(request.nickname(), request.email(), request.content(), request.parentId(),
+                        request.challenge(), request.honeypot(), request.website()),
+                visitorCookie(httpRequest), httpRequest.getRemoteAddr());
+        return ResponseEntity.status(HttpStatus.ACCEPTED)
+                .body(new SubmissionResponse(result.id(), result.status().name(), result.createdAt(), result.deleteToken()));
+    }
+
+    @DeleteMapping("/comments/{id}")
+    public ResponseEntity<Void> delete(@PathVariable UUID id,
+                                       @RequestHeader(value = DELETE_TOKEN_HEADER, required = false) String deleteToken) {
+        comments.delete(id, deleteToken);
+        return ResponseEntity.noContent().build();
+    }
+
+    @ExceptionHandler(CommentRateLimitException.class)
+    ResponseEntity<ProblemResponse> rateLimited(CommentRateLimitException exception) {
+        ProblemResponse body = problemResponseWriter.response(HttpStatus.TOO_MANY_REQUESTS,
+                "COMMENT_RATE_LIMITED", "Comment rate limit exceeded",
+                "Too many comments have been submitted from this source").getBody();
+        return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
+                .header(HttpHeaders.RETRY_AFTER, Long.toString(exception.getRetryAfterSeconds()))
+                .contentType(ProblemResponseWriter.PROBLEM)
+                .body(body);
+    }
+
+    private String visitorCookie(HttpServletRequest request) {
+        if (request.getCookies() != null) {
+            for (Cookie cookie : request.getCookies()) {
+                if (VISITOR_COOKIE.equals(cookie.getName()) && cookie.getValue() != null
+                        && cookie.getValue().matches("[A-Za-z0-9_-]{43}")) {
+                    return cookie.getValue();
+                }
+            }
+        }
+        return null;
+    }
+
+    public record CommentRequest(String nickname, String email, String content, UUID parentId,
+                                 String challenge, String honeypot, String website) {}
+
+    public record SubmissionResponse(UUID id, String status, java.time.Instant createdAt, String deleteToken) {}
+}
diff --git a/apps/api/src/main/java/io/haoblog/shared/web/GlobalExceptionHandler.java b/apps/api/src/main/java/io/haoblog/shared/web/GlobalExceptionHandler.java
index 6ec6ac2..82b203a 100644
--- a/apps/api/src/main/java/io/haoblog/shared/web/GlobalExceptionHandler.java
+++ b/apps/api/src/main/java/io/haoblog/shared/web/GlobalExceptionHandler.java
@@ -13,6 +13,7 @@
 import org.springframework.web.bind.annotation.RestControllerAdvice;
 import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
 import org.springframework.http.converter.HttpMessageNotReadableException;
+import org.springframework.web.HttpMediaTypeNotSupportedException;
 import org.springframework.web.servlet.NoHandlerFoundException;
 import org.springframework.web.servlet.resource.NoResourceFoundException;
 
@@ -29,7 +30,8 @@ public GlobalExceptionHandler(ProblemResponseWriter problemResponseWriter) {
 
     @ExceptionHandler({MethodArgumentNotValidException.class, HandlerMethodValidationException.class,
             MethodArgumentTypeMismatchException.class, MissingServletRequestParameterException.class,
-            HttpMessageNotReadableException.class, IllegalArgumentException.class})
+            HttpMessageNotReadableException.class, HttpMediaTypeNotSupportedException.class,
+            IllegalArgumentException.class})
     ResponseEntity<ProblemResponse> badRequest(Exception exception) {
         return problemResponseWriter.response(HttpStatus.BAD_REQUEST, "BAD_REQUEST", "Invalid request", "Request parameters are invalid");
     }
@@ -39,8 +41,10 @@ ResponseEntity<ProblemResponse> content(ProblemException exception) {
         HttpStatus status = "MEDIA_STORAGE_UNAVAILABLE".equals(exception.getCode()) ? HttpStatus.SERVICE_UNAVAILABLE :
                 exception.getCode().endsWith("_NOT_FOUND") ? HttpStatus.NOT_FOUND :
                 (Set.of("ARTICLE_PREVIEW_GONE", "MEDIA_UPLOAD_EXPIRED").contains(exception.getCode()) ? HttpStatus.GONE :
-                        (exception.getCode().contains("CONFLICT") || exception.getCode().endsWith("_IN_USE")
-                                ? HttpStatus.CONFLICT : HttpStatus.BAD_REQUEST));
+                        (Set.of("COMMENTING_DISABLED", "COMMENT_DUPLICATE", "COMMENT_ALREADY_DELETED").contains(exception.getCode())
+                                || exception.getCode().contains("CONFLICT") || exception.getCode().endsWith("_IN_USE")
+                                ? HttpStatus.CONFLICT :
+                                ("COMMENT_DELETE_TOKEN_INVALID".equals(exception.getCode()) ? HttpStatus.FORBIDDEN : HttpStatus.BAD_REQUEST)));
         return problemResponseWriter.response(status, exception.getCode(), exception.getTitle(), exception.getMessage(),
                 exception.getCurrentVersion());
     }
diff --git a/apps/api/src/main/resources/db/migration/V12__comment_fingerprint_uniqueness.sql b/apps/api/src/main/resources/db/migration/V12__comment_fingerprint_uniqueness.sql
new file mode 100644
index 0000000..7d2bb74
--- /dev/null
+++ b/apps/api/src/main/resources/db/migration/V12__comment_fingerprint_uniqueness.sql
@@ -0,0 +1,2 @@
+CREATE UNIQUE INDEX comment_article_fingerprint_uq
+    ON comment (article_id, content_fingerprint);
diff --git a/apps/api/src/test/java/io/haoblog/ContentModelIT.java b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
index 53ea8c6..cfc63b8 100644
--- a/apps/api/src/test/java/io/haoblog/ContentModelIT.java
+++ b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
@@ -57,7 +57,7 @@ static void database(DynamicPropertyRegistry registry) {
 
     @Test
     void migratesAllVersionsAndCreatesContentTables() {
-        assertEquals(11, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
+        assertEquals(12, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
         for (String table : List.of("article", "category", "tag", "article_tag", "article_revision",
                 "article_preview_token", "media_asset", "media_upload", "outbox_event", "comment")) {
             assertEquals(1, jdbc.queryForObject(
@@ -81,7 +81,8 @@ void migratesAllVersionsAndCreatesContentTables() {
                     "SELECT count(*) FROM information_schema.columns WHERE table_name='comment' AND column_name=?",
                     Integer.class, column));
         }
-        for (String index : List.of("comment_article_status_created_idx", "comment_parent_created_idx", "outbox_comment_created_uq")) {
+        for (String index : List.of("comment_article_status_created_idx", "comment_parent_created_idx",
+                "comment_article_fingerprint_uq", "outbox_comment_created_uq")) {
             assertEquals(1, jdbc.queryForObject(
                     "SELECT count(*) FROM pg_indexes WHERE schemaname='public' AND indexname=?", Integer.class, index));
         }
diff --git a/apps/api/src/test/java/io/haoblog/comment/application/CommentChallengeServiceTest.java b/apps/api/src/test/java/io/haoblog/comment/application/CommentChallengeServiceTest.java
index 643eb43..e108cd1 100644
--- a/apps/api/src/test/java/io/haoblog/comment/application/CommentChallengeServiceTest.java
+++ b/apps/api/src/test/java/io/haoblog/comment/application/CommentChallengeServiceTest.java
@@ -30,6 +30,19 @@ void requiresMinimumAgeAndConsumesOnce() {
         assertFalse(challenges.consume(articleId, issued.token()));
     }
 
+    @Test
+    void rejectsExpiredChallenge() {
+        var clock = new MutableClock(Instant.parse("2026-08-22T00:00:00Z"));
+        var security = new CommentSecurityService(Base64.getEncoder().encodeToString(
+                "01234567890123456789012345678901".getBytes(StandardCharsets.UTF_8)));
+        var challenges = new CommentChallengeService(clock, security);
+        UUID articleId = UUID.randomUUID();
+        var issued = challenges.issue(articleId);
+
+        clock.advance(Duration.ofHours(2).plusSeconds(1));
+        assertFalse(challenges.consume(articleId, issued.token()));
+    }
+
     private static final class MutableClock extends Clock {
         private Instant instant;
 
diff --git a/apps/api/src/test/java/io/haoblog/comment/application/CommentRateLimiterTest.java b/apps/api/src/test/java/io/haoblog/comment/application/CommentRateLimiterTest.java
new file mode 100644
index 0000000..ac651f5
--- /dev/null
+++ b/apps/api/src/test/java/io/haoblog/comment/application/CommentRateLimiterTest.java
@@ -0,0 +1,49 @@
+package io.haoblog.comment.application;
+
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class CommentRateLimiterTest {
+    private final AtomicReference<Instant> now = new AtomicReference<>(Instant.parse("2026-08-22T00:00:00Z"));
+    private final Clock clock = new Clock() {
+        @Override public ZoneOffset getZone() { return ZoneOffset.UTC; }
+        @Override public Clock withZone(java.time.ZoneId zone) { return this; }
+        @Override public Instant instant() { return now.get(); }
+    };
+
+    @Test
+    void limitsThreeInTenMinutesThenAllowsAfterWindow() {
+        CommentRateLimiter limiter = new CommentRateLimiter(clock);
+        assertTrue(limiter.checkAndRecord("visitor:a").allowed());
+        assertTrue(limiter.checkAndRecord("visitor:a").allowed());
+        assertTrue(limiter.checkAndRecord("visitor:a").allowed());
+        var limited = limiter.checkAndRecord("visitor:a");
+        assertFalse(limited.allowed());
+        assertTrue(limited.retryAfterSeconds() > 0);
+
+        now.updateAndGet(value -> value.plus(Duration.ofMinutes(10).plusSeconds(1)));
+        assertTrue(limiter.checkAndRecord("visitor:a").allowed());
+    }
+
+    @Test
+    void limitsTenPerUtcDayAndBoundsCache() {
+        CommentRateLimiter limiter = new CommentRateLimiter(clock);
+        for (int i = 0; i < 10; i++) {
+            assertTrue(limiter.checkAndRecord("ip:a").allowed());
+            now.updateAndGet(value -> value.plus(Duration.ofMinutes(11)));
+        }
+        var limited = limiter.checkAndRecord("ip:a");
+        assertFalse(limited.allowed());
+        assertTrue(limited.retryAfterSeconds() > 0);
+
+        for (int i = 0; i < 4097; i++) limiter.checkAndRecord("source-" + i);
+        assertEquals(4096, limiter.cacheSize());
+    }
+}
diff --git a/apps/api/src/test/java/io/haoblog/comment/application/CommentServiceTest.java b/apps/api/src/test/java/io/haoblog/comment/application/CommentServiceTest.java
new file mode 100644
index 0000000..f8c9939
--- /dev/null
+++ b/apps/api/src/test/java/io/haoblog/comment/application/CommentServiceTest.java
@@ -0,0 +1,183 @@
+package io.haoblog.comment.application;
+
+import io.haoblog.comment.domain.Comment;
+import io.haoblog.comment.domain.CommentStatus;
+import io.haoblog.comment.persistence.CommentRepository;
+import io.haoblog.content.application.ArticleCommentLookup;
+import io.haoblog.shared.outbox.OutboxEventRepository;
+import io.haoblog.shared.web.ProblemException;
+import io.haoblog.site.application.SiteService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.PageRequest;
+
+import java.nio.charset.StandardCharsets;
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.util.Base64;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+class CommentServiceTest {
+    private static final UUID ARTICLE_ID = UUID.randomUUID();
+
+    @Mock CommentRepository comments;
+    @Mock OutboxEventRepository outbox;
+    @Mock ArticleCommentLookup articles;
+    @Mock SiteService site;
+    private MutableClock clock;
+    private CommentSecurityService security;
+    private CommentChallengeService challenges;
+    private CommentRateLimiter limiter;
+    private CommentService service;
+
+    @BeforeEach
+    void setUp() {
+        clock = new MutableClock(Instant.parse("2026-08-22T00:00:00Z"));
+        security = new CommentSecurityService(Base64.getEncoder().encodeToString(
+                "01234567890123456789012345678901".getBytes(StandardCharsets.UTF_8)));
+        challenges = new CommentChallengeService(clock, security);
+        limiter = new CommentRateLimiter(clock);
+        service = new CommentService(comments, outbox, articles, site, security, challenges, limiter, clock);
+        lenient().when(articles.findPublicCommentTarget("post"))
+                .thenReturn(Optional.of(new ArticleCommentLookup.Target(ARTICLE_ID, true)));
+        lenient().when(site.get()).thenReturn(new SiteService.SiteResult("HaoBlog", "", "https://example.test", "Hao", true));
+    }
+
+    @Test
+    void createsPendingCommentAndOutboxInOneApplicationFlow() {
+        var challenge = challenges.issue(ARTICLE_ID);
+        clock.advance(Duration.ofSeconds(3));
+        var result = service.create("post", command(challenge.token(), "hello"), "A".repeat(43), "192.0.2.1");
+
+        assertEquals(CommentStatus.PENDING, result.status());
+        assertNotNull(result.id());
+        assertNotNull(result.deleteToken());
+        verify(comments).save(any(Comment.class));
+        verify(outbox).save(any());
+    }
+
+    @Test
+    void rejectsUnsafeContentAndFakeParent() {
+        var htmlChallenge = challenges.issue(ARTICLE_ID);
+        assertThrows(ProblemException.class, () -> service.create("post", command(htmlChallenge.token(), "<b>x</b>"), null, "192.0.2.1"));
+
+        var protocolChallenge = challenges.issue(ARTICLE_ID);
+        var protocol = assertThrows(ProblemException.class, () -> service.create("post",
+                command(protocolChallenge.token(), "see javascript:alert(1)"), null, "192.0.2.1"));
+        assertEquals("COMMENT_LINK_PROTOCOL_INVALID", protocol.getCode());
+
+        var longChallenge = challenges.issue(ARTICLE_ID);
+        var longContent = "x".repeat(2001);
+        var tooLong = assertThrows(ProblemException.class, () -> service.create("post",
+                command(longChallenge.token(), longContent), null, "192.0.2.1"));
+        assertEquals("COMMENT_CONTENT_INVALID", tooLong.getCode());
+
+        var parentChallenge = challenges.issue(ARTICLE_ID);
+        clock.advance(Duration.ofSeconds(3));
+        var exception = assertThrows(ProblemException.class, () -> service.create("post",
+                new CommentService.CreateCommand("Hao", null, "reply", UUID.randomUUID(), parentChallenge.token(), null, null),
+                null, "192.0.2.1"));
+        assertEquals("COMMENT_PARENT_INVALID", exception.getCode());
+    }
+
+    @Test
+    void honeypotIsAcceptedWithoutPersistenceAndDuplicateIsAConflict() {
+        var honeypotChallenge = challenges.issue(ARTICLE_ID);
+        clock.advance(Duration.ofSeconds(3));
+        var accepted = service.create("post", new CommentService.CreateCommand(
+                "Hao", null, "normal text", null, honeypotChallenge.token(), "filled", null), null, "192.0.2.1");
+        assertEquals(CommentStatus.PENDING, accepted.status());
+        assertNull(accepted.id());
+        verifyNoInteractions(comments, outbox);
+
+        var duplicateChallenge = challenges.issue(ARTICLE_ID);
+        clock.advance(Duration.ofSeconds(3));
+        when(comments.existsByArticleIdAndContentFingerprint(eq(ARTICLE_ID), any(byte[].class))).thenReturn(true);
+        var duplicate = assertThrows(ProblemException.class, () -> service.create("post",
+                command(duplicateChallenge.token(), "duplicate"), null, "192.0.2.1"));
+        assertEquals("COMMENT_DUPLICATE", duplicate.getCode());
+    }
+
+    @Test
+    void globalAndArticleSwitchesHideOrRejectComments() {
+        when(site.get()).thenReturn(new SiteService.SiteResult("HaoBlog", "", "https://example.test", "Hao", false));
+        var page = service.list("post", 0, 20);
+        assertTrue(page.items().isEmpty());
+        verifyNoInteractions(comments);
+
+        var challenge = challenges.issue(ARTICLE_ID);
+        clock.advance(Duration.ofSeconds(3));
+        var disabled = assertThrows(ProblemException.class, () -> service.create("post", command(challenge.token(), "nope"), null, "192.0.2.1"));
+        assertEquals("COMMENTING_DISABLED", disabled.getCode());
+    }
+
+    @Test
+    void listsTopLevelCommentsAndLoadsRepliesWithOneBatchQuery() {
+        Comment top = comment("top", null);
+        top.moderate(CommentStatus.APPROVED, null, null, clock.instant());
+        Comment reply = comment("reply", top.getId());
+        reply.moderate(CommentStatus.APPROVED, null, null, clock.instant());
+        when(comments.findByArticleIdAndStatusAndParentIdIsNullOrderByCreatedAtAscIdAsc(
+                eq(ARTICLE_ID), eq(CommentStatus.APPROVED), any(PageRequest.class)))
+                .thenReturn(new PageImpl<>(List.of(top), PageRequest.of(0, 20), 1));
+        when(comments.findByArticleIdAndStatusAndParentIdInOrderByCreatedAtAscIdAsc(
+                eq(ARTICLE_ID), eq(CommentStatus.APPROVED), eq(List.of(top.getId()))))
+                .thenReturn(List.of(reply));
+
+        var page = service.list("post", 0, 20);
+        assertEquals(1, page.items().size());
+        assertEquals(1, page.items().getFirst().replies().size());
+        verify(comments, times(1)).findByArticleIdAndStatusAndParentIdInOrderByCreatedAtAscIdAsc(
+                eq(ARTICLE_ID), eq(CommentStatus.APPROVED), eq(List.of(top.getId())));
+    }
+
+    @Test
+    void deletesWithTokenAndClearsUserContentButKeepsAuditStatus() {
+        String token = security.newDeleteToken();
+        Instant now = clock.instant();
+        Comment comment = new Comment(ARTICLE_ID, null, "Hao", security.encryptEmail(UUID.randomUUID(), "a@b.test").ciphertext(),
+                null, null, "body", new byte[32], now.atZone(ZoneId.of("UTC")).toLocalDate(),
+                new byte[32], security.deleteTokenDigest(token), now);
+        // 仅验证删除路径的擦除；实体保存时邮箱 nonce/key version 由创建路径提供。
+        when(comments.findById(comment.getId())).thenReturn(Optional.of(comment));
+        assertThrows(ProblemException.class, () -> service.delete(comment.getId(), "wrong-token"));
+        service.delete(comment.getId(), token);
+        assertEquals(CommentStatus.USER_DELETED, comment.getStatus());
+        assertEquals("", comment.getNickname());
+        assertEquals("", comment.getContent());
+        assertNull(comment.getEmailCiphertext());
+        assertThrows(ProblemException.class, () -> service.delete(comment.getId(), token));
+    }
+
+    private CommentService.CreateCommand command(String challenge, String content) {
+        return new CommentService.CreateCommand("Hao", null, content, null, challenge, null, null);
+    }
+
+    private Comment comment(String content, UUID parentId) {
+        return new Comment(ARTICLE_ID, parentId, "Hao", null, null, null, content, new byte[32],
+                clock.instant().atZone(ZoneId.of("UTC")).toLocalDate(), new byte[32], new byte[32], clock.instant());
+    }
+
+    private static final class MutableClock extends Clock {
+        private Instant current;
+        private MutableClock(Instant current) { this.current = current; }
+        private void advance(Duration duration) { current = current.plus(duration); }
+        @Override public ZoneId getZone() { return ZoneId.of("UTC"); }
+        @Override public Clock withZone(ZoneId zone) { return this; }
+        @Override public Instant instant() { return current; }
+    }
+}
diff --git a/docs/openapi/public-api.yaml b/docs/openapi/public-api.yaml
index 9931302..df53701 100644
--- a/docs/openapi/public-api.yaml
+++ b/docs/openapi/public-api.yaml
@@ -137,6 +137,55 @@ paths:
           $ref: '#/components/responses/ArticleNotFound'
         '500':
           $ref: '#/components/responses/InternalError'
+  /api/v1/public/articles/{slug}/comments:
+    get:
+      operationId: listPublicArticleComments
+      parameters:
+        - name: slug
+          in: path
+          required: true
+          schema: { type: string, minLength: 1, maxLength: 160 }
+        - name: page
+          in: query
+          schema: { type: integer, minimum: 0, default: 0 }
+        - name: size
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 50, default: 20 }
+      responses:
+        '200':
+          description: Approved top-level comments and first-level replies
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/CommentPageResponse' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '404': { $ref: '#/components/responses/ArticleNotFound' }
+        '500': { $ref: '#/components/responses/InternalError' }
+    post:
+      operationId: createPublicArticleComment
+      parameters:
+        - name: slug
+          in: path
+          required: true
+          schema: { type: string, minLength: 1, maxLength: 160 }
+        - $ref: '#/components/parameters/CsrfHeader'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/CommentCreateRequest' }
+      responses:
+        '202':
+          description: Comment accepted for moderation
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/CommentSubmissionResponse' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '403':
+          description: Invalid CSRF token or delete credential
+          content: { application/problem+json: { schema: { $ref: '#/components/schemas/ProblemResponse' } } }
+        '404': { $ref: '#/components/responses/ArticleNotFound' }
+        '409': { $ref: '#/components/responses/CommentConflict' }
+        '429': { $ref: '#/components/responses/CommentRateLimited' }
   /api/v1/public/articles/{slug}/comments/form-context:
     get:
       operationId: getPublicCommentFormContext
@@ -153,6 +202,18 @@ paths:
               schema: { $ref: '#/components/schemas/CommentFormContext' }
         '404':
           $ref: '#/components/responses/ArticleNotFound'
+  /api/v1/public/comments/{id}:
+    delete:
+      operationId: deletePublicComment
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
+        - $ref: '#/components/parameters/CsrfHeader'
+        - $ref: '#/components/parameters/CommentDeleteToken'
+      responses:
+        '204': { description: Comment content deleted }
+        '403': { $ref: '#/components/responses/CsrfInvalid' }
+        '404': { $ref: '#/components/responses/ResourceNotFound' }
+        '409': { $ref: '#/components/responses/CommentConflict' }
   /api/v1/public/article-previews/{token}:
     get:
       operationId: getPublicArticlePreview
@@ -619,6 +680,11 @@ components:
       in: header
       required: true
       schema: { type: string }
+    CommentDeleteToken:
+      name: X-Comment-Delete-Token
+      in: header
+      required: true
+      schema: { type: string, minLength: 43, maxLength: 43 }
     IfNoneMatch:
       name: If-None-Match
       in: header
@@ -655,6 +721,20 @@ components:
       content:
         application/problem+json:
           schema: { $ref: '#/components/schemas/ProblemResponse' }
+    CommentConflict:
+      description: Comment submission conflicts with current state or duplicate content
+      content:
+        application/problem+json:
+          schema: { $ref: '#/components/schemas/ProblemResponse' }
+    CommentRateLimited:
+      description: Comment rate limit exceeded
+      headers:
+        Retry-After:
+          description: Seconds until another comment may be submitted
+          schema: { type: integer, minimum: 1 }
+      content:
+        application/problem+json:
+          schema: { $ref: '#/components/schemas/ProblemResponse' }
     ArticleVersionConflict:
       description: Article working copy version is stale
       content:
@@ -751,6 +831,42 @@ components:
         challenge: { type: string, minLength: 43, maxLength: 43 }
         expiresAt: { type: string, format: date-time }
         commentsEnabled: { type: boolean }
+    CommentCreateRequest:
+      type: object
+      required: [nickname, content, challenge]
+      properties:
+        nickname: { type: string, minLength: 2, maxLength: 40 }
+        email: { type: [string, 'null'], maxLength: 254, format: email }
+        content: { type: string, minLength: 2, maxLength: 2000 }
+        parentId: { type: [string, 'null'], format: uuid }
+        challenge: { type: string, minLength: 43, maxLength: 43 }
+        honeypot: { type: string, maxLength: 200 }
+        website: { type: string, maxLength: 200 }
+    CommentView:
+      type: object
+      required: [id, nickname, content, createdAt, replies]
+      properties:
+        id: { type: string, format: uuid }
+        nickname: { type: string }
+        content: { type: string }
+        createdAt: { type: string, format: date-time }
+        replies: { type: array, items: { $ref: '#/components/schemas/CommentView' } }
+    CommentPageResponse:
+      type: object
+      required: [items, page, size, total]
+      properties:
+        items: { type: array, items: { $ref: '#/components/schemas/CommentView' } }
+        page: { type: integer }
+        size: { type: integer }
+        total: { type: integer, format: int64 }
+    CommentSubmissionResponse:
+      type: object
+      required: [id, status, createdAt]
+      properties:
+        id: { type: [string, 'null'], format: uuid }
+        status: { type: string, enum: [PENDING] }
+        createdAt: { type: string, format: date-time }
+        deleteToken: { type: [string, 'null'], minLength: 43, maxLength: 43 }
     ProblemResponse:
       type: object
       required: [code, title, detail, traceId]
diff --git a/infra/compose/compose.prod.yml b/infra/compose/compose.prod.yml
index 20dd058..11cca62 100644
--- a/infra/compose/compose.prod.yml
+++ b/infra/compose/compose.prod.yml
@@ -60,6 +60,7 @@ services:
       HAOBLOG_ADMIN_PASSWORD_HASH: ${HAOBLOG_ADMIN_PASSWORD_HASH:?HAOBLOG_ADMIN_PASSWORD_HASH is required}
       HAOBLOG_PUBLIC_BASE_URL: ${HAOBLOG_PUBLIC_BASE_URL:?HAOBLOG_PUBLIC_BASE_URL is required}
       HAOBLOG_AUTHOR_NAME: ${HAOBLOG_AUTHOR_NAME:-Hao}
+      HAOBLOG_COMMENT_SECURITY_KEY: ${HAOBLOG_COMMENT_SECURITY_KEY:?HAOBLOG_COMMENT_SECURITY_KEY is required}
       JDBC_DATABASE_URL: jdbc:postgresql://postgres-pgvector:5432/${POSTGRES_DB:?POSTGRES_DB is required}
       JDBC_DATABASE_USERNAME: ${POSTGRES_USER:?POSTGRES_USER is required}
       JDBC_DATABASE_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
diff --git a/packages/api-client/src/generated.ts b/packages/api-client/src/generated.ts
index 75745cc..0e5a394 100644
--- a/packages/api-client/src/generated.ts
+++ b/packages/api-client/src/generated.ts
@@ -84,6 +84,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/public/articles/{slug}/comments": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["listPublicArticleComments"];
+        put?: never;
+        post: operations["createPublicArticleComment"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/public/articles/{slug}/comments/form-context": {
         parameters: {
             query?: never;
@@ -100,6 +116,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/public/comments/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        delete: operations["deletePublicComment"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/public/article-previews/{token}": {
         parameters: {
             query?: never;
@@ -505,6 +537,42 @@ export interface components {
             expiresAt: string;
             commentsEnabled: boolean;
         };
+        CommentCreateRequest: {
+            nickname: string;
+            /** Format: email */
+            email?: string | null;
+            content: string;
+            /** Format: uuid */
+            parentId?: string | null;
+            challenge: string;
+            honeypot?: string;
+            website?: string;
+        };
+        CommentView: {
+            /** Format: uuid */
+            id: string;
+            nickname: string;
+            content: string;
+            /** Format: date-time */
+            createdAt: string;
+            replies: components["schemas"]["CommentView"][];
+        };
+        CommentPageResponse: {
+            items: components["schemas"]["CommentView"][];
+            page: number;
+            size: number;
+            /** Format: int64 */
+            total: number;
+        };
+        CommentSubmissionResponse: {
+            /** Format: uuid */
+            id: string | null;
+            /** @enum {string} */
+            status: "PENDING";
+            /** Format: date-time */
+            createdAt: string;
+            deleteToken?: string | null;
+        };
         ProblemResponse: {
             code: string;
             title: string;
@@ -839,6 +907,26 @@ export interface components {
                 "application/problem+json": components["schemas"]["ProblemResponse"];
             };
         };
+        /** @description Comment submission conflicts with current state or duplicate content */
+        CommentConflict: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/problem+json": components["schemas"]["ProblemResponse"];
+            };
+        };
+        /** @description Comment rate limit exceeded */
+        CommentRateLimited: {
+            headers: {
+                /** @description Seconds until another comment may be submitted */
+                "Retry-After"?: number;
+                [name: string]: unknown;
+            };
+            content: {
+                "application/problem+json": components["schemas"]["ProblemResponse"];
+            };
+        };
         /** @description Article working copy version is stale */
         ArticleVersionConflict: {
             headers: {
@@ -916,6 +1004,7 @@ export interface components {
     };
     parameters: {
         CsrfHeader: string;
+        CommentDeleteToken: string;
         IfNoneMatch: string;
     };
     requestBodies: never;
@@ -1106,6 +1195,75 @@ export interface operations {
             500: components["responses"]["InternalError"];
         };
     };
+    listPublicArticleComments: {
+        parameters: {
+            query?: {
+                page?: number;
+                size?: number;
+            };
+            header?: never;
+            path: {
+                slug: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Approved top-level comments and first-level replies */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentPageResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            404: components["responses"]["ArticleNotFound"];
+            500: components["responses"]["InternalError"];
+        };
+    };
+    createPublicArticleComment: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-CSRF-TOKEN": components["parameters"]["CsrfHeader"];
+            };
+            path: {
+                slug: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CommentCreateRequest"];
+            };
+        };
+        responses: {
+            /** @description Comment accepted for moderation */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentSubmissionResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            /** @description Invalid CSRF token or delete credential */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ProblemResponse"];
+                };
+            };
+            404: components["responses"]["ArticleNotFound"];
+            409: components["responses"]["CommentConflict"];
+            429: components["responses"]["CommentRateLimited"];
+        };
+    };
     getPublicCommentFormContext: {
         parameters: {
             query?: never;
@@ -1129,6 +1287,32 @@ export interface operations {
             404: components["responses"]["ArticleNotFound"];
         };
     };
+    deletePublicComment: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-CSRF-TOKEN": components["parameters"]["CsrfHeader"];
+                "X-Comment-Delete-Token": components["parameters"]["CommentDeleteToken"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Comment content deleted */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: components["responses"]["CsrfInvalid"];
+            404: components["responses"]["ResourceNotFound"];
+            409: components["responses"]["CommentConflict"];
+        };
+    };
     getPublicArticlePreview: {
         parameters: {
             query?: never;

From f860ae2b2d82c1ec3b6b916f7f497b527af6d930 Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sat, 22 Aug 2026 23:45:23 +0800
Subject: [PATCH 04/15] =?UTF-8?q?=E9=98=B6=E6=AE=B5=E5=9B=9B=EF=BC=9A?=
 =?UTF-8?q?=E5=AE=8C=E6=88=90=E6=96=87=E7=AB=A0=E8=AF=84=E8=AE=BA=E5=8C=BA?=
 =?UTF-8?q?=20SSR=20=E4=B8=8E=E8=AE=BF=E5=AE=A2=E4=BA=A4=E4=BA=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 apps/web/app/assets/styles/articles.css       |  44 ++++
 .../components/articles/CommentSignalItem.vue |  54 ++++
 .../articles/CommentSignalSection.vue         | 246 ++++++++++++++++++
 .../components/articles/CommentSignalText.vue |  14 +
 apps/web/app/pages/articles/[slug].vue        |  18 +-
 apps/web/app/utils/commentSignal.ts           |  42 +++
 apps/web/e2e/stage4.spec.ts                   |  46 ++++
 apps/web/test/comment-signal.test.ts          | 144 ++++++++++
 8 files changed, 606 insertions(+), 2 deletions(-)
 create mode 100644 apps/web/app/components/articles/CommentSignalItem.vue
 create mode 100644 apps/web/app/components/articles/CommentSignalSection.vue
 create mode 100644 apps/web/app/components/articles/CommentSignalText.vue
 create mode 100644 apps/web/app/utils/commentSignal.ts
 create mode 100644 apps/web/e2e/stage4.spec.ts
 create mode 100644 apps/web/test/comment-signal.test.ts

diff --git a/apps/web/app/assets/styles/articles.css b/apps/web/app/assets/styles/articles.css
index c446083..0e69f11 100644
--- a/apps/web/app/assets/styles/articles.css
+++ b/apps/web/app/assets/styles/articles.css
@@ -47,6 +47,7 @@
 .article-pagination a { color: var(--color-accent); text-decoration: none; }
 .article-pagination a:hover, .article-pagination a:focus-visible { text-decoration: underline; }
 .article-instrument { display: grid; grid-template-columns: minmax(3rem, 8rem) minmax(0, 45rem) minmax(10rem, 15rem); gap: clamp(1rem, 3vw, 2.5rem); max-width: 90rem; margin: 8vh auto 0; }
+.article-reading-column { min-width: 0; }
 .article-reading { min-width: 0; }
 .article-reading h1 { max-width: none; font-size: clamp(2.5rem, 7vw, 6rem); line-height: .98; }
 .article-excerpt { color: var(--color-text-muted); font-size: var(--text-lg); }
@@ -87,6 +88,49 @@ html[data-theme='blueprint'] .safe-markdown .shiki span { color: var(--shiki-lig
 .article-toc a { display: block; color: var(--color-text-muted); text-decoration: none; }
 .article-toc a:hover, .article-toc a:focus-visible, .article-toc a.is-current { color: var(--color-accent); }
 .article-toc a.is-current { border-left: 2px solid var(--color-accent); padding-left: .5rem; }
+.comment-signal { margin-top: clamp(4rem, 10vw, 8rem); padding-top: 1.5rem; border-top: 1px solid var(--color-border); }
+.comment-signal-heading { display: flex; align-items: end; justify-content: space-between; gap: 1rem; }
+.comment-signal-heading h2 { margin: .65rem 0 0; font-family: var(--font-display); font-size: clamp(1.8rem, 5vw, 3.5rem); line-height: 1; }
+.comment-signal-count, .comment-signal-form-label, .comment-signal-safety, .comment-signal-counter { color: var(--color-text-muted); font: var(--text-xs)/1.5 var(--font-mono); letter-spacing: .06em; }
+.comment-signal-count { white-space: nowrap; }
+.comment-signal-note { margin: 1.5rem 0 0; color: var(--color-text-muted); }
+.comment-signal-list { margin-top: 2rem; border-left: 1px solid var(--color-border); }
+.comment-signal-entry { position: relative; display: grid; grid-template-columns: .75rem minmax(0, 1fr); gap: .9rem; margin-left: -.4rem; padding: 0 0 1.75rem; }
+.comment-signal-entry[data-depth='1'] { margin-left: 1.2rem; padding-bottom: 1.25rem; }
+.comment-signal-point { width: .7rem; height: .7rem; margin-top: .35rem; border: 1px solid var(--color-accent); background: var(--color-bg-base); }
+.comment-signal-entry[data-depth='1'] .comment-signal-point { width: .5rem; height: .5rem; margin-top: .42rem; border-color: var(--color-text-muted); }
+.comment-signal-entry-body { min-width: 0; }
+.comment-signal-entry-header { display: flex; align-items: baseline; gap: .75rem; flex-wrap: wrap; }
+.comment-signal-author { color: var(--color-text-main); font-weight: 650; }
+.comment-signal-entry-header time { color: var(--color-text-muted); font: var(--text-xs)/1.5 var(--font-mono); }
+.comment-signal-content { margin: .55rem 0 0; color: var(--color-text-main); line-height: 1.75; overflow-wrap: anywhere; white-space: pre-wrap; }
+.comment-signal-content a { color: var(--color-accent); text-decoration-thickness: 1px; text-underline-offset: .16em; overflow-wrap: anywhere; }
+.comment-signal-actions { display: flex; gap: .85rem; flex-wrap: wrap; margin-top: .65rem; }
+.comment-signal-actions button, .comment-signal-cancel { padding: 0; border: 0; color: var(--color-text-muted); background: transparent; font: var(--text-xs)/1.5 var(--font-mono); text-decoration: underline; text-underline-offset: .2em; cursor: pointer; }
+.comment-signal-actions button:hover, .comment-signal-actions button:focus-visible, .comment-signal-cancel:hover, .comment-signal-cancel:focus-visible { color: var(--color-accent); }
+.comment-signal button, .comment-signal input, .comment-signal textarea { touch-action: manipulation; -webkit-tap-highlight-color: transparent; }
+.comment-signal-replies { margin-top: 1rem; border-left: 1px solid var(--color-border-soft); }
+.comment-signal-compose { margin-top: 1.75rem; }
+.comment-signal-expand { width: 100%; padding: .85rem 0; border: 1px solid var(--color-border); color: var(--color-accent); background: transparent; font: var(--text-xs)/1.5 var(--font-mono); letter-spacing: .06em; text-align: left; cursor: pointer; }
+.comment-signal-expand span { float: right; font-size: 1.1rem; line-height: 1; }
+.comment-signal-expand:hover, .comment-signal-expand:focus-visible { border-color: var(--color-accent); background: color-mix(in srgb, var(--color-accent) 7%, transparent); }
+.comment-signal-form { position: relative; margin-top: 1rem; padding: 1rem; border: 1px solid var(--color-border); background: color-mix(in srgb, var(--color-bg-sub) 55%, transparent); }
+.comment-signal-form-label { margin: 0; color: var(--color-accent); }
+.comment-signal-cancel { position: absolute; top: 1rem; right: 1rem; }
+.comment-signal-safety { margin: .85rem 0 1rem; }
+.comment-signal-fields { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: .75rem; }
+.comment-signal-form label { display: grid; gap: .35rem; margin-top: .8rem; color: var(--color-text-muted); font: var(--text-xs)/1.5 var(--font-mono); }
+.comment-signal-form input, .comment-signal-form textarea { width: 100%; min-width: 0; padding: .65rem .7rem; border: 1px solid var(--color-border); border-radius: 0; color: var(--color-text-main); background: var(--color-bg-base); font: var(--text-base)/1.5 var(--font-body); }
+.comment-signal-form textarea { resize: vertical; }
+.comment-signal-form input:focus, .comment-signal-form textarea:focus { border-color: var(--color-accent); outline: 2px solid var(--color-accent); outline-offset: 1px; }
+.comment-signal-form-footer { display: flex; align-items: center; justify-content: space-between; gap: 1rem; margin-top: .8rem; }
+.comment-signal-form-footer button { padding: .6rem .8rem; border: 1px solid var(--color-accent); color: var(--color-accent-ink); background: var(--color-accent); font: var(--text-xs)/1.5 var(--font-mono); cursor: pointer; }
+.comment-signal-form-footer button:disabled { cursor: wait; opacity: .55; }
+.comment-signal-counter { letter-spacing: normal; }
+.comment-signal-feedback { min-height: 1.5em; margin: .8rem 0 0; color: var(--color-accent); font: var(--text-xs)/1.5 var(--font-mono); }
+.comment-signal-feedback[data-status='error'], .comment-signal-feedback[data-status='rate-limited'] { color: var(--color-warn); }
+.comment-signal-honeypot { position: absolute !important; width: 1px !important; height: 1px !important; margin: -1px !important; padding: 0 !important; overflow: hidden !important; clip: rect(0 0 0 0) !important; white-space: nowrap !important; border: 0 !important; }
+@media (max-width: 480px) { .comment-signal-heading { align-items: start; flex-direction: column; gap: .5rem; }.comment-signal-fields { grid-template-columns: 1fr; gap: 0; }.comment-signal-form { padding: .8rem; }.comment-signal-cancel { top: .8rem; right: .8rem; }.comment-signal-safety { padding-right: 4.5rem; } }
 @media (max-width: 1023px) { .article-instrument { display: block; max-width: 45rem; margin-top: 6vh; }.article-signal { position: sticky; top: 0; z-index: 2; display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-items: center; gap: .75rem; height: auto; margin: 0 0 2rem; padding: .5rem 0; background: var(--color-bg-base); }.article-signal-track { width: 100%; height: 2px; }.article-signal-fill { width: var(--signal-progress); height: 100%; }.article-toc { position: static; margin-top: 3rem; padding: 1rem 0 0; border-left: 0; border-top: 1px solid var(--color-border); }.article-toc ol { padding-bottom: .25rem; } }
 @media (max-width: 767px) { .observation-entry { grid-template-columns: 1fr; gap: .4rem; padding-left: 1rem; }.article-pagination { padding-left: 1rem; }.recent-list li { grid-template-columns: 2rem 1fr; gap: .35rem .75rem; }.recent-list time { grid-column: 2; }.recent-list a { grid-column: 2; }.recent-list .recent-index { grid-row: 1 / span 2; }.home-calibration, .recent-heading { align-items: start; flex-direction: column; gap: .75rem; }.home-coordinate { text-align: left; }.observation-entry-heading { grid-template-columns: 2rem minmax(0, 1fr); }.article-cover-frame { grid-column: 2; width: min(12rem, 100%); }.observation-entry-content p { margin-top: .9rem; } }
 @media (max-width: 360px) { .home-overview h1 { font-size: clamp(3rem, 18vw, 4.5rem); } .home-overview::before { display: none; } .safe-markdown { font-size: 1rem; line-height: 1.8; } .observation-entry-heading { grid-template-columns: 1.5rem minmax(0, 1fr); gap: .5rem; } .observation-index { font-size: .68rem; } }
diff --git a/apps/web/app/components/articles/CommentSignalItem.vue b/apps/web/app/components/articles/CommentSignalItem.vue
new file mode 100644
index 0000000..98b26e3
--- /dev/null
+++ b/apps/web/app/components/articles/CommentSignalItem.vue
@@ -0,0 +1,54 @@
+<script setup lang="ts">
+import type { components } from '@haoblog/api-client'
+import CommentSignalText from './CommentSignalText.vue'
+
+type CommentView = components['schemas']['CommentView']
+
+const props = withDefaults(defineProps<{
+  comment: CommentView
+  depth?: number
+  ownedTokens?: Readonly<Record<string, string>>
+  hiddenIds?: ReadonlySet<string>
+}>(), { depth: 0 })
+
+const emit = defineEmits<{
+  reply: [comment: CommentView]
+  delete: [comment: CommentView]
+}>()
+
+const dateFormatter = new Intl.DateTimeFormat('zh-CN', {
+  timeZone: 'Asia/Shanghai', year: 'numeric', month: '2-digit', day: '2-digit',
+})
+const formatDate = (value: string) => {
+  const parts = Object.fromEntries(dateFormatter.formatToParts(new Date(value)).map(part => [part.type, part.value]))
+  return `${parts.year}.${parts.month}.${parts.day}`
+}
+</script>
+
+<template>
+  <article v-if="!props.hiddenIds?.has(props.comment.id)" class="comment-signal-entry" :data-depth="props.depth">
+    <span class="comment-signal-point" aria-hidden="true" />
+    <div class="comment-signal-entry-body">
+      <header class="comment-signal-entry-header">
+        <span class="comment-signal-author">{{ props.comment.nickname }}</span>
+        <time :datetime="props.comment.createdAt">{{ formatDate(props.comment.createdAt) }}</time>
+      </header>
+      <p class="comment-signal-content"><CommentSignalText :text="props.comment.content" /></p>
+      <div class="comment-signal-actions">
+        <button v-if="props.depth === 0" type="button" @click="emit('reply', props.comment)">回复</button>
+        <button v-if="props.ownedTokens?.[props.comment.id]" type="button" @click="emit('delete', props.comment)">删除我的评论</button>
+      </div>
+      <div v-if="props.comment.replies.length" class="comment-signal-replies">
+        <CommentSignalItem
+          v-for="reply in props.comment.replies"
+          :key="reply.id"
+          :comment="reply"
+          :depth="props.depth + 1"
+          :owned-tokens="props.ownedTokens"
+          :hidden-ids="props.hiddenIds"
+          @delete="emit('delete', $event)"
+        />
+      </div>
+    </div>
+  </article>
+</template>
diff --git a/apps/web/app/components/articles/CommentSignalSection.vue b/apps/web/app/components/articles/CommentSignalSection.vue
new file mode 100644
index 0000000..59c963c
--- /dev/null
+++ b/apps/web/app/components/articles/CommentSignalSection.vue
@@ -0,0 +1,246 @@
+<script setup lang="ts">
+import { computed, nextTick, onMounted, reactive, ref, watch } from 'vue'
+import type { components } from '@haoblog/api-client'
+import CommentSignalItem from './CommentSignalItem.vue'
+
+type CommentPage = components['schemas']['CommentPageResponse']
+type CommentView = components['schemas']['CommentView']
+type CommentFormContext = components['schemas']['CommentFormContext']
+type Submission = components['schemas']['CommentSubmissionResponse']
+type FormStatus = 'idle' | 'loading' | 'submitting' | 'pending' | 'rate-limited' | 'error'
+
+const props = defineProps<{
+  slug: string
+  comments: CommentPage
+  siteCommentsEnabled: boolean
+  articleCommentsEnabled: boolean
+}>()
+
+const expanded = ref(false)
+const formContext = ref<CommentFormContext | null>(null)
+const formStatus = ref<FormStatus>('idle')
+const formMessage = ref('')
+const actionMessage = ref('')
+const retryAfter = ref<number | null>(null)
+const replyTo = ref<CommentView | null>(null)
+const contentInput = ref<HTMLTextAreaElement | null>(null)
+const ownedTokens = ref<Record<string, string>>({})
+const hiddenIds = ref(new Set<string>())
+const formReadyAt = ref(0)
+const form = reactive({ nickname: '', email: '', content: '', website: '' })
+
+const isGloballyClosed = computed(() => !props.siteCommentsEnabled)
+const isArticleClosed = computed(() => props.siteCommentsEnabled && !props.articleCommentsEnabled)
+const canComment = computed(() => !isGloballyClosed.value && !isArticleClosed.value)
+const visibleComments = computed(() => props.comments.items.filter(comment => !hiddenIds.value.has(comment.id)))
+const contentLength = computed(() => [...form.content].length)
+
+function tokenKey(id: string) { return `haoblog-comment-delete:${id}` }
+
+function restoreTokens() {
+  if (typeof localStorage === 'undefined') return
+  const restored: Record<string, string> = {}
+  for (const comment of props.comments.items) {
+    const token = localStorage.getItem(tokenKey(comment.id))
+    if (token) restored[comment.id] = token
+    for (const reply of comment.replies) {
+      const replyToken = localStorage.getItem(tokenKey(reply.id))
+      if (replyToken) restored[reply.id] = replyToken
+    }
+  }
+  ownedTokens.value = restored
+}
+
+function rememberToken(id: string | null | undefined, token: string | null | undefined) {
+  if (!id || !token || typeof localStorage === 'undefined') return
+  localStorage.setItem(tokenKey(id), token)
+  ownedTokens.value = { ...ownedTokens.value, [id]: token }
+}
+
+function forgetToken(id: string) {
+  if (typeof localStorage !== 'undefined') localStorage.removeItem(tokenKey(id))
+  const next = { ...ownedTokens.value }
+  delete next[id]
+  ownedTokens.value = next
+}
+
+function problemMessage(error: unknown, fallback: string) {
+  const data = (error as { response?: { _data?: { detail?: string } } })?.response?._data
+  return typeof data?.detail === 'string' ? data.detail : fallback
+}
+
+function responseStatus(error: unknown) {
+  return (error as { response?: { status?: number } })?.response?.status
+}
+
+function responseRetryAfter(error: unknown) {
+  const value = (error as { response?: { headers?: Headers } })?.response?.headers?.get('Retry-After')
+  const seconds = Number(value)
+  return Number.isFinite(seconds) && seconds > 0 ? Math.ceil(seconds) : null
+}
+
+async function loadFormContext() {
+  if (formContext.value || formStatus.value === 'loading') return
+  formStatus.value = 'loading'
+  formMessage.value = ''
+  try {
+    formContext.value = await $fetch<CommentFormContext>(`/api/v1/public/articles/${encodeURIComponent(props.slug)}/comments/form-context`, { credentials: 'include' })
+    formReadyAt.value = Date.now() + 3000
+    formStatus.value = 'idle'
+  } catch (error) {
+    formStatus.value = 'error'
+    formMessage.value = problemMessage(error, '评论表单暂时无法接收信号，请稍后再试。')
+  }
+}
+
+function openForm() {
+  expanded.value = true
+}
+
+function startReply(comment: CommentView) {
+  replyTo.value = comment
+  openForm()
+  void nextTick(() => contentInput.value?.focus())
+}
+
+function cancelReply() { replyTo.value = null }
+
+async function ensureFormContext() {
+  if (!formContext.value || formContext.value.expiresAt <= new Date().toISOString()) {
+    formContext.value = null
+    await loadFormContext()
+  }
+  return formContext.value
+}
+
+async function submitComment() {
+  if (formStatus.value === 'submitting') return
+  if (contentLength.value < 2 || contentLength.value > 2000) {
+    formStatus.value = 'error'
+    formMessage.value = '正文需要 2–2000 个字符。'
+    void nextTick(() => contentInput.value?.focus())
+    return
+  }
+  const readyIn = Math.ceil((formReadyAt.value - Date.now()) / 1000)
+  if (readyIn > 0) {
+    formStatus.value = 'error'
+    formMessage.value = `安全校验还在校准，请再停留 ${readyIn} 秒。`
+    return
+  }
+  const context = await ensureFormContext()
+  if (!context) return
+
+  formStatus.value = 'submitting'
+  formMessage.value = ''
+  retryAfter.value = null
+  try {
+    const result = await $fetch<Submission>(`/api/v1/public/articles/${encodeURIComponent(props.slug)}/comments`, {
+      method: 'POST',
+      credentials: 'include',
+      headers: { 'X-CSRF-TOKEN': context.csrfToken },
+      body: {
+        nickname: form.nickname,
+        email: form.email.trim() || null,
+        content: form.content,
+        parentId: replyTo.value?.id || null,
+        challenge: context.challenge,
+        website: form.website,
+      },
+    })
+    rememberToken(result.id, result.deleteToken)
+    formStatus.value = 'pending'
+    formMessage.value = '评论已接收，待审核通过后会回到这条回波信号。'
+    form.content = ''
+    replyTo.value = null
+    formContext.value = null
+    formReadyAt.value = 0
+  } catch (error) {
+    const status = responseStatus(error)
+    retryAfter.value = status === 429 ? responseRetryAfter(error) : null
+    formStatus.value = status === 429 ? 'rate-limited' : 'error'
+    formMessage.value = status === 429
+      ? `信号频率过高，请${retryAfter.value ? `在 ${retryAfter.value} 秒后` : '稍后'}再试。`
+      : problemMessage(error, '评论没有送达，请检查输入后再试。')
+    if (status === 403) formContext.value = null
+  }
+}
+
+async function deleteComment(comment: CommentView) {
+  const token = ownedTokens.value[comment.id]
+  if (!token) return
+  if (typeof window !== 'undefined' && !window.confirm('确定删除这条评论吗？删除后公开正文将被移除。')) return
+  const context = await ensureFormContext()
+  if (!context) return
+  try {
+    await $fetch(`/api/v1/public/comments/${encodeURIComponent(comment.id)}`, {
+      method: 'DELETE',
+      credentials: 'include',
+      headers: {
+        'X-CSRF-TOKEN': context.csrfToken,
+        'X-Comment-Delete-Token': token,
+      },
+    })
+    forgetToken(comment.id)
+    hiddenIds.value = new Set(hiddenIds.value).add(comment.id)
+    actionMessage.value = '评论已从公开信号中移除。'
+  } catch (error) {
+    formStatus.value = 'error'
+    actionMessage.value = problemMessage(error, '删除操作没有完成，请稍后再试。')
+  }
+}
+
+watch(expanded, value => { if (value && canComment.value) void loadFormContext() })
+onMounted(restoreTokens)
+</script>
+
+<template>
+  <section class="comment-signal" aria-labelledby="comment-signal-title">
+    <div class="comment-signal-heading">
+      <div>
+        <p class="instrument-label">SIGNAL / ECHO</p>
+        <h2 id="comment-signal-title">回波信号</h2>
+      </div>
+      <span class="comment-signal-count" aria-label="评论数量">{{ props.comments.total }} 条</span>
+    </div>
+
+    <p v-if="isGloballyClosed" class="comment-signal-note">评论信号已关闭</p>
+    <template v-else>
+      <p v-if="isArticleClosed" class="comment-signal-note">此篇观测已关闭新评论，历史回波仍可读取。</p>
+      <p v-else-if="!visibleComments.length" class="comment-signal-note">暂未捕获回波。成为第一个留下信号的人。</p>
+      <p v-if="actionMessage" class="comment-signal-feedback" role="status" aria-live="polite">{{ actionMessage }}</p>
+
+      <div v-if="visibleComments.length" class="comment-signal-list" aria-label="文章评论">
+        <CommentSignalItem
+          v-for="comment in visibleComments"
+          :key="comment.id"
+          :comment="comment"
+          :owned-tokens="ownedTokens"
+          :hidden-ids="hiddenIds"
+          @reply="startReply"
+          @delete="deleteComment"
+        />
+      </div>
+
+      <div v-if="canComment" class="comment-signal-compose">
+        <button v-if="!expanded" class="comment-signal-expand" type="button" @click="openForm">展开评论入口 <span aria-hidden="true">＋</span></button>
+        <form v-else class="comment-signal-form" @submit.prevent="submitComment">
+          <p class="comment-signal-form-label">{{ replyTo ? `REPLY / @${replyTo.nickname}` : 'TRANSMIT / NEW ECHO' }}</p>
+          <button v-if="replyTo" class="comment-signal-cancel" type="button" @click="cancelReply">取消回复</button>
+          <p class="comment-signal-safety">纯文本 · 最多 2000 字 · 仅允许 https 安全链接（最多 3 个）</p>
+          <div class="comment-signal-fields">
+            <label>昵称<input v-model="form.nickname" name="nickname" required minlength="2" maxlength="40" autocomplete="nickname" spellcheck="false" /></label>
+            <label>邮箱（可选）<input v-model="form.email" name="email" type="email" maxlength="254" autocomplete="email" spellcheck="false" /></label>
+          </div>
+          <label>正文<textarea ref="contentInput" v-model="form.content" name="content" required minlength="2" maxlength="2000" rows="6" aria-describedby="comment-signal-count comment-signal-feedback" /></label>
+          <input v-model="form.website" name="website" class="comment-signal-honeypot" tabindex="-1" autocomplete="off" aria-hidden="true" />
+          <div class="comment-signal-form-footer">
+            <span id="comment-signal-count" class="comment-signal-counter">{{ contentLength }} / 2000</span>
+            <button type="submit" :disabled="formStatus === 'loading' || formStatus === 'submitting'">{{ formStatus === 'submitting' ? '发送中…' : '发送回波' }}</button>
+          </div>
+          <p v-if="formStatus === 'loading'" class="comment-signal-feedback" role="status">正在校准安全表单…</p>
+          <p v-else-if="formMessage" id="comment-signal-feedback" class="comment-signal-feedback" :data-status="formStatus" role="status" aria-live="polite">{{ formMessage }}</p>
+        </form>
+      </div>
+    </template>
+  </section>
+</template>
diff --git a/apps/web/app/components/articles/CommentSignalText.vue b/apps/web/app/components/articles/CommentSignalText.vue
new file mode 100644
index 0000000..2b530d0
--- /dev/null
+++ b/apps/web/app/components/articles/CommentSignalText.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { splitCommentSignalText } from '../../utils/commentSignal'
+
+const props = defineProps<{ text: string }>()
+const segments = computed(() => splitCommentSignalText(props.text))
+</script>
+
+<template>
+  <template v-for="(segment, index) in segments" :key="`${index}-${segment.text}`">
+    <a v-if="segment.href" :href="segment.href" target="_blank" rel="noreferrer noopener">{{ segment.text }}</a>
+    <span v-else>{{ segment.text }}</span>
+  </template>
+</template>
diff --git a/apps/web/app/pages/articles/[slug].vue b/apps/web/app/pages/articles/[slug].vue
index 20fb948..1e2a878 100644
--- a/apps/web/app/pages/articles/[slug].vue
+++ b/apps/web/app/pages/articles/[slug].vue
@@ -1,16 +1,22 @@
 <script setup lang="ts">
 import { nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
 import PublicArticleBody from '~/components/articles/PublicArticleBody.vue'
+import CommentSignalSection from '~/components/articles/CommentSignalSection.vue'
 import type { PublicArticleContent } from '~/utils/publicArticleContent'
+import type { components } from '@haoblog/api-client'
 import { buildPublicArticleJsonLd, buildPublicArticleSeo, buildPublicPageSeo, publicPageHead, serializeJsonLd } from '~/utils/publicArticleSeo'
 import { defaultPublicSite, usePublicSite } from '~/utils/publicSite'
 import { useMotionPreference } from '~/composables/useMotionPreference'
 
 const route = useRoute()
 const config = useRuntimeConfig()
-const [{ data, pending, error }, { data: site }] = await Promise.all([
+const [{ data, pending, error }, { data: site }, { data: comments }] = await Promise.all([
   usePublicApi<PublicArticleContent>(`/_content/articles/${encodeURIComponent(String(route.params.slug))}`, { baseURL: config.public.apiBase }),
   usePublicSite(),
+  usePublicApi<components['schemas']['CommentPageResponse']>(`/api/v1/public/articles/${encodeURIComponent(String(route.params.slug))}/comments`, {
+    query: { size: 20 },
+    default: () => ({ items: [], page: 0, size: 20, total: 0 }),
+  }),
 ])
 if (error.value?.statusCode === 404 || (!pending.value && !data.value)) {
   throw createError({ statusCode: 404, statusMessage: 'Article not found', fatal: true })
@@ -73,7 +79,15 @@ useHead(() => {
         </span>
         <span class="article-signal-value">{{ Math.round(articleProgress * 100) }}%</span>
       </aside>
-      <PublicArticleBody ref="articleBody" :content="data" />
+      <div class="article-reading-column">
+        <PublicArticleBody ref="articleBody" :content="data" />
+        <CommentSignalSection
+          :slug="data.article.slug"
+          :comments="comments || { items: [], page: 0, size: 20, total: 0 }"
+          :site-comments-enabled="resolvedSite.commentsEnabled"
+          :article-comments-enabled="data.article.commentsEnabled"
+        />
+      </div>
       <nav v-if="data.toc.length" class="article-toc" aria-label="文章航标">
         <details open>
           <summary>TOC / NAV <span aria-hidden="true">{{ data.toc.length }}</span></summary>
diff --git a/apps/web/app/utils/commentSignal.ts b/apps/web/app/utils/commentSignal.ts
new file mode 100644
index 0000000..13430da
--- /dev/null
+++ b/apps/web/app/utils/commentSignal.ts
@@ -0,0 +1,42 @@
+export type CommentSignalTextSegment = { text: string; href?: string }
+
+const URL_PATTERN = /https:\/\/[^\s<>"'()[\]{}]+/gi
+const TRAILING_PUNCTUATION = /[.,!?;:\uFF0C\u3002\uFF01\uFF1F\uFF1B\uFF1A\uFF09\u3011]+$/
+
+function safeHttpsUrl(value: string) {
+  try {
+    const url = new URL(value)
+    return url.protocol === 'https:' && !/[\u0000-\u001f\u007f]/.test(value) ? url.toString() : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function splitCommentSignalText(value: string): CommentSignalTextSegment[] {
+  const segments: CommentSignalTextSegment[] = []
+  const pushText = (text: string) => {
+    if (!text) return
+    const previous = segments.at(-1)
+    if (previous && !previous.href) previous.text += text
+    else segments.push({ text })
+  }
+  let cursor = 0
+  for (const match of value.matchAll(URL_PATTERN)) {
+    const start = match.index ?? 0
+    const raw = match[0]
+    let candidate = raw
+    let suffix = ''
+    while (TRAILING_PUNCTUATION.test(candidate)) {
+      suffix = candidate.slice(-1) + suffix
+      candidate = candidate.slice(0, -1)
+    }
+    const href = safeHttpsUrl(candidate)
+    if (!href) continue
+    if (start > cursor) pushText(value.slice(cursor, start))
+    segments.push({ text: candidate, href })
+    pushText(suffix)
+    cursor = start + raw.length
+  }
+  if (cursor < value.length) pushText(value.slice(cursor))
+  return segments.length ? segments : [{ text: value }]
+}
diff --git a/apps/web/e2e/stage4.spec.ts b/apps/web/e2e/stage4.spec.ts
new file mode 100644
index 0000000..1fc8031
--- /dev/null
+++ b/apps/web/e2e/stage4.spec.ts
@@ -0,0 +1,46 @@
+import { expect, test } from '@playwright/test'
+
+test.describe('S4-03 article comment signal', () => {
+  test('keeps the comment signal SSR-readable and submits through the lazy form context', async ({ page, browser }) => {
+    const articles = await page.request.get('/api/v1/public/articles?size=1')
+    expect(articles.ok()).toBe(true)
+    const firstArticle = (await articles.json() as { items: Array<{ slug: string }> }).items[0]
+    expect(firstArticle?.slug).toBeTruthy()
+    const articlePath = `/articles/${firstArticle.slug}`
+
+    const noJs = await browser.newContext({ baseURL: process.env.HAOBLOG_BASE_URL || 'http://127.0.0.1', javaScriptEnabled: false })
+    const noJsPage = await noJs.newPage()
+    const noJsResponse = await noJsPage.goto(articlePath)
+    expect(noJsResponse?.status()).toBe(200)
+    await expect(noJsPage.locator('.comment-signal')).toBeVisible()
+    await expect(noJsPage.locator('.comment-signal')).toContainText(/回波信号|评论信号已关闭/)
+    await noJs.close()
+
+    let submitHeaders: Record<string, string> | undefined
+    await page.route('**/api/v1/public/articles/*/comments/form-context', route => route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ csrfToken: 'e2e-csrf', challenge: 'e2e-challenge', expiresAt: new Date(Date.now() + 60_000).toISOString(), commentsEnabled: true }),
+    }))
+    await page.route('**/api/v1/public/articles/*/comments', async route => {
+      if (route.request().method() !== 'POST') return route.continue()
+      submitHeaders = route.request().headers()
+      await route.fulfill({
+        status: 202,
+        contentType: 'application/json',
+        body: JSON.stringify({ id: '00000000-0000-7000-8000-000000000099', status: 'PENDING', createdAt: new Date().toISOString(), deleteToken: 'e2e-delete-token' }),
+      })
+    })
+    await page.goto(articlePath)
+    await expect(page.getByRole('button', { name: '展开评论入口' })).toBeVisible()
+    await page.getByRole('button', { name: '展开评论入口' }).click()
+    await expect(page.getByLabel('昵称')).toBeVisible()
+    await page.getByLabel('昵称').fill('Playwright 观测员')
+    await page.getByLabel('正文').fill('这是一条待审核回波。')
+    await page.waitForTimeout(3200)
+    await page.getByRole('button', { name: '发送回波' }).click()
+    await expect(page.locator('[data-status="pending"]')).toContainText('待审核')
+    expect(submitHeaders?.['x-csrf-token']).toBe('e2e-csrf')
+    expect(await page.evaluate(() => localStorage.getItem('haoblog-comment-delete:00000000-0000-7000-8000-000000000099'))).toBe('e2e-delete-token')
+  })
+})
diff --git a/apps/web/test/comment-signal.test.ts b/apps/web/test/comment-signal.test.ts
new file mode 100644
index 0000000..9f77f4c
--- /dev/null
+++ b/apps/web/test/comment-signal.test.ts
@@ -0,0 +1,144 @@
+import { createSSRApp, nextTick } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+import { renderToString } from 'vue/server-renderer'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { components } from '@haoblog/api-client'
+import CommentSignalSection from '../app/components/articles/CommentSignalSection.vue'
+import { splitCommentSignalText } from '../app/utils/commentSignal'
+
+type CommentPage = components['schemas']['CommentPageResponse']
+
+const comments: CommentPage = {
+  items: [{
+    id: '00000000-0000-7000-8000-000000000001',
+    nickname: '观测员',
+    content: '纯文本 <script>alert(1)</script> https://example.com/echo.',
+    createdAt: '2026-08-20T03:00:00Z',
+    replies: [{
+      id: '00000000-0000-7000-8000-000000000002',
+      nickname: '回声',
+      content: 'reply',
+      createdAt: '2026-08-20T04:00:00Z',
+      replies: [],
+    }],
+  }],
+  page: 0,
+  size: 20,
+  total: 1,
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  localStorage.clear()
+})
+
+describe('comment signal', () => {
+  it('splits only valid https URLs and preserves punctuation as text', () => {
+    expect(splitCommentSignalText('看 https://example.com/a。 和 javascript://bad')).toEqual([
+      { text: '看 ' },
+      { text: 'https://example.com/a', href: 'https://example.com/a' },
+      { text: '。 和 javascript://bad' },
+    ])
+  })
+
+  it('renders SSR comments as readable text and safe links without raw HTML', async () => {
+    const html = await renderToString(createSSRApp(CommentSignalSection, {
+      slug: 'signal', comments, siteCommentsEnabled: true, articleCommentsEnabled: true,
+    }))
+    expect(html).toContain('纯文本 &lt;script&gt;alert(1)&lt;/script&gt;')
+    expect(html).toContain('href="https://example.com/echo"')
+    expect(html).toContain('回声')
+    expect(html).not.toContain('<script>')
+    expect(html).not.toContain('v-html')
+    expect(html).not.toContain('comment-signal-form')
+  })
+
+  it('requests form context only after the visitor expands the form and sends CSRF on submit', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-08-22T00:00:00Z'))
+    const fetcher = vi.fn()
+      .mockResolvedValueOnce({ csrfToken: 'csrf-1', challenge: 'challenge-1', expiresAt: '2026-08-22T00:10:00Z', commentsEnabled: true })
+      .mockResolvedValueOnce({ id: comments.items[0]!.id, status: 'PENDING', createdAt: '2026-08-22T00:00:04Z', deleteToken: 'delete-1' })
+    vi.stubGlobal('$fetch', fetcher)
+    const wrapper = mount(CommentSignalSection, {
+      props: { slug: 'signal', comments, siteCommentsEnabled: true, articleCommentsEnabled: true },
+    })
+
+    expect(fetcher).not.toHaveBeenCalled()
+    await wrapper.get('.comment-signal-expand').trigger('click')
+    await nextTick()
+    expect(fetcher).toHaveBeenCalledTimes(1)
+    expect(fetcher.mock.calls[0]?.[0]).toContain('/comments/form-context')
+
+    await wrapper.get('input[autocomplete="nickname"]').setValue('访客')
+    await wrapper.get('textarea').setValue('留下一个回波')
+    vi.advanceTimersByTime(3000)
+    await wrapper.get('form').trigger('submit')
+    await nextTick()
+    expect(fetcher).toHaveBeenCalledTimes(2)
+    expect(fetcher.mock.calls[1]?.[1]).toMatchObject({
+      method: 'POST',
+      headers: { 'X-CSRF-TOKEN': 'csrf-1' },
+    })
+    expect(wrapper.get('[data-status="pending"]').text()).toContain('待审核')
+    expect(localStorage.getItem(`haoblog-comment-delete:${comments.items[0]!.id}`)).toBe('delete-1')
+    vi.useRealTimers()
+  })
+
+  it('restores a per-comment delete token from localStorage and sends it with CSRF', async () => {
+    const id = comments.items[0]!.id
+    localStorage.setItem(`haoblog-comment-delete:${id}`, 'delete-restored')
+    vi.stubGlobal('confirm', vi.fn(() => true))
+    const fetcher = vi.fn()
+      .mockResolvedValueOnce({ csrfToken: 'csrf-delete', challenge: 'unused', expiresAt: '2030-01-01T00:00:00Z', commentsEnabled: true })
+      .mockResolvedValueOnce(undefined)
+    vi.stubGlobal('$fetch', fetcher)
+    const wrapper = mount(CommentSignalSection, {
+      props: { slug: 'signal', comments, siteCommentsEnabled: true, articleCommentsEnabled: true },
+    })
+    await nextTick()
+    const deleteButton = wrapper.findAll('button').find(button => button.text() === '删除我的评论')
+    expect(deleteButton).toBeDefined()
+    await deleteButton!.trigger('click')
+    await flushPromises()
+    expect(fetcher.mock.calls[1]?.[1]).toMatchObject({
+      method: 'DELETE',
+      headers: { 'X-CSRF-TOKEN': 'csrf-delete', 'X-Comment-Delete-Token': 'delete-restored' },
+    })
+    expect(localStorage.getItem(`haoblog-comment-delete:${id}`)).toBeNull()
+    expect(wrapper.text()).not.toContain('纯文本')
+  })
+
+  it('surfaces Retry-After for rate-limited submissions', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-08-22T00:00:00Z'))
+    const fetcher = vi.fn()
+      .mockResolvedValueOnce({ csrfToken: 'csrf-429', challenge: 'challenge-429', expiresAt: '2026-08-22T00:10:00Z', commentsEnabled: true })
+      .mockRejectedValueOnce({ response: { status: 429, headers: new Headers({ 'Retry-After': '17' }), _data: { detail: 'rate limited' } } })
+    vi.stubGlobal('$fetch', fetcher)
+    const wrapper = mount(CommentSignalSection, {
+      props: { slug: 'signal', comments, siteCommentsEnabled: true, articleCommentsEnabled: true },
+    })
+    await wrapper.get('.comment-signal-expand').trigger('click')
+    await wrapper.get('textarea').setValue('稍后再试')
+    vi.advanceTimersByTime(3000)
+    await wrapper.get('form').trigger('submit')
+    await flushPromises()
+    expect(wrapper.get('[data-status="rate-limited"]').text()).toContain('17 秒')
+    vi.useRealTimers()
+  })
+
+  it('keeps history visible for a single article close and shows the global close signal', async () => {
+    const singleClosed = await renderToString(createSSRApp(CommentSignalSection, {
+      slug: 'signal', comments, siteCommentsEnabled: true, articleCommentsEnabled: false,
+    }))
+    expect(singleClosed).toContain('历史回波仍可读取')
+    expect(singleClosed).toContain('纯文本')
+    expect(singleClosed).not.toContain('展开评论入口')
+
+    const globalClosed = await renderToString(createSSRApp(CommentSignalSection, {
+      slug: 'signal', comments: { ...comments, items: [], total: 0 }, siteCommentsEnabled: false, articleCommentsEnabled: true,
+    }))
+    expect(globalClosed).toContain('评论信号已关闭')
+  })
+})

From fed715b9247b94915e36c06ede93f18207fcd6ec Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 00:59:51 +0800
Subject: [PATCH 05/15] =?UTF-8?q?=E5=AE=9E=E7=8E=B0=20Studio=20=E8=AF=84?=
 =?UTF-8?q?=E8=AE=BA=E5=AE=A1=E6=A0=B8=E4=B8=8E=E8=AF=84=E8=AE=BA=E5=BC=80?=
 =?UTF-8?q?=E5=85=B3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../application/CommentSecurityService.java   |   5 +
 .../comment/application/CommentService.java   | 126 +++++++-
 .../persistence/CommentRepository.java        |  14 +
 .../comment/web/AdminCommentController.java   |  69 +++++
 .../application/AdminContentService.java      |   6 +-
 .../content/web/AdminArticleController.java   |   6 +-
 .../haoblog/content/web/AdminArticleDtos.java |   6 +-
 .../content/web/PublicArticleController.java  |  33 +-
 .../haoblog/site/application/SiteService.java |  26 ++
 .../io/haoblog/site/domain/SiteSetting.java   |   1 +
 .../haoblog/site/web/AdminSiteController.java |  47 +++
 .../test/java/io/haoblog/AdminCommentIT.java  | 193 ++++++++++++
 .../studio/StudioArticleEditor.client.vue     |   9 +
 apps/web/app/composables/useAdminComments.ts  |  45 +++
 apps/web/app/composables/useAdminSite.ts      |  25 ++
 .../web/app/composables/useArticleAutosave.ts |   1 +
 apps/web/app/layouts/studio.vue               |   2 +
 apps/web/app/pages/studio/comments.vue        | 205 +++++++++++++
 apps/web/app/pages/studio/settings.vue        |  80 +++++
 apps/web/app/utils/studioArticleForm.ts       |   3 +
 apps/web/test/article-autosave.test.ts        |   2 +
 apps/web/test/studio-article-form.test.ts     |   3 +
 docs/openapi/public-api.yaml                  | 135 ++++++++
 packages/api-client/src/generated.ts          | 290 ++++++++++++++++++
 24 files changed, 1317 insertions(+), 15 deletions(-)
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/web/AdminCommentController.java
 create mode 100644 apps/api/src/main/java/io/haoblog/site/web/AdminSiteController.java
 create mode 100644 apps/api/src/test/java/io/haoblog/AdminCommentIT.java
 create mode 100644 apps/web/app/composables/useAdminComments.ts
 create mode 100644 apps/web/app/composables/useAdminSite.ts
 create mode 100644 apps/web/app/pages/studio/comments.vue
 create mode 100644 apps/web/app/pages/studio/settings.vue

diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
index 2288653..3ea7820 100644
--- a/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentSecurityService.java
@@ -73,6 +73,11 @@ public String decryptEmail(UUID commentId, EmailCiphertext encrypted) {
         }
     }
 
+    public String decryptEmail(UUID commentId, byte[] ciphertext, byte[] nonce, Integer keyVersion) {
+        if (ciphertext == null || nonce == null || keyVersion == null) return null;
+        return decryptEmail(commentId, new EmailCiphertext(keyVersion, nonce, ciphertext));
+    }
+
     public byte[] dailyIpHmac(String ip, LocalDate date) {
         return hmac(ipKey, "ip-v1:" + date + ":" + ip);
     }
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java
index 38f368f..1720228 100644
--- a/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java
@@ -4,12 +4,16 @@
 import io.haoblog.comment.domain.CommentStatus;
 import io.haoblog.comment.persistence.CommentRepository;
 import io.haoblog.content.application.ArticleCommentLookup;
+import io.haoblog.identity.domain.AdminUser;
+import io.haoblog.identity.persistence.AdminUserRepository;
 import io.haoblog.shared.outbox.OutboxEvent;
 import io.haoblog.shared.outbox.OutboxEventRepository;
 import io.haoblog.shared.web.ProblemException;
 import io.haoblog.site.application.SiteService;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Sort;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.transaction.annotation.Transactional;
 import org.springframework.stereotype.Service;
 
@@ -19,6 +23,7 @@
 import java.time.ZoneOffset;
 import java.text.Normalizer;
 import java.util.Base64;
+import java.util.EnumSet;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Locale;
@@ -34,6 +39,8 @@ public class CommentService {
     private static final Pattern RAW_HTML = Pattern.compile("(?is)<\\s*/?\\s*[a-z!][^>]*>");
     private static final Pattern HTTPS_LINK = Pattern.compile("(?i)https://");
     private static final int MAX_PAGE_SIZE = 50;
+    private static final EnumSet<CommentStatus> MODERATABLE = EnumSet.of(
+            CommentStatus.APPROVED, CommentStatus.SPAM, CommentStatus.REJECTED);
 
     private final CommentRepository comments;
     private final OutboxEventRepository outbox;
@@ -42,12 +49,14 @@ public class CommentService {
     private final CommentSecurityService security;
     private final CommentChallengeService challenges;
     private final CommentRateLimiter rateLimiter;
+    private final AdminUserRepository admins;
     private final Clock clock;
 
+    @Autowired
     public CommentService(CommentRepository comments, OutboxEventRepository outbox,
                           ArticleCommentLookup articles, SiteService site,
                           CommentSecurityService security, CommentChallengeService challenges,
-                          CommentRateLimiter rateLimiter, Clock clock) {
+                          CommentRateLimiter rateLimiter, AdminUserRepository admins, Clock clock) {
         this.comments = comments;
         this.outbox = outbox;
         this.articles = articles;
@@ -55,9 +64,100 @@ public CommentService(CommentRepository comments, OutboxEventRepository outbox,
         this.security = security;
         this.challenges = challenges;
         this.rateLimiter = rateLimiter;
+        this.admins = admins;
         this.clock = clock;
     }
 
+    public CommentService(CommentRepository comments, OutboxEventRepository outbox,
+                          ArticleCommentLookup articles, SiteService site,
+                          CommentSecurityService security, CommentChallengeService challenges,
+                          CommentRateLimiter rateLimiter, Clock clock) {
+        this(comments, outbox, articles, site, security, challenges, rateLimiter, null, clock);
+    }
+
+    @Transactional(readOnly = true)
+    public Page<AdminComment> listAdmin(CommentStatus status, UUID articleId, String keyword,
+                                        int page, int size, Sort.Direction direction) {
+        validatePage(page, size);
+        String normalizedKeyword = normalizeKeyword(keyword);
+        var pageable = PageRequest.of(page, size, Sort.by(direction, "createdAt").and(Sort.by(direction, "id")));
+        return comments.findAdminComments(status, articleId, normalizedKeyword, pageable).map(this::adminListView);
+    }
+
+    @Transactional(readOnly = true)
+    public AdminCommentDetail getAdmin(UUID commentId) {
+        Comment comment = comments.findById(commentId).orElseThrow(() -> notFound("COMMENT_NOT_FOUND"));
+        return adminDetail(comment);
+    }
+
+    @Transactional
+    public AdminCommentDetail moderate(UUID commentId, long expectedVersion, CommentStatus target,
+                                       String reason, String username) {
+        if (!MODERATABLE.contains(target)) {
+            throw new ProblemException("COMMENT_MODERATION_STATE_CONFLICT", "Invalid moderation state",
+                    "Comments can only be moderated to APPROVED, SPAM or REJECTED");
+        }
+        Comment comment = comments.findById(commentId).orElseThrow(() -> notFound("COMMENT_NOT_FOUND"));
+        if (comment.getStatus() == CommentStatus.USER_DELETED) {
+            throw new ProblemException("COMMENT_MODERATION_STATE_CONFLICT", "Invalid moderation state",
+                    "A deleted comment cannot be moderated");
+        }
+        if (comment.getVersion() != expectedVersion) throw versionConflict(comment.getVersion());
+        if (admins == null) throw new ProblemException("ADMIN_NOT_FOUND", "Administrator not found",
+                "The administrator account is no longer available");
+        UUID moderatorId = admins.findForAuthentication(username).map(AdminUser::getId)
+                .orElseThrow(() -> new ProblemException("ADMIN_NOT_FOUND", "Administrator not found",
+                        "The administrator account is no longer available"));
+        comment.moderate(target, moderatorId, normalizeReason(reason), clock.instant());
+        return adminDetail(comments.saveAndFlush(comment));
+    }
+
+    private AdminComment adminListView(Comment comment) {
+        return AdminComment.from(comment, maskedEmail(comment));
+    }
+
+    private AdminCommentDetail adminDetail(Comment comment) {
+        return AdminCommentDetail.from(comment, decryptedEmail(comment));
+    }
+
+    private String decryptedEmail(Comment comment) {
+        return security.decryptEmail(comment.getId(), comment.getEmailCiphertext(), comment.getEmailNonce(), comment.getEmailKeyVersion());
+    }
+
+    private String maskedEmail(Comment comment) {
+        String email = decryptedEmail(comment);
+        if (email == null || email.isBlank()) return null;
+        int at = email.lastIndexOf('@');
+        if (at <= 0 || at == email.length() - 1) return "***";
+        String local = email.substring(0, at);
+        String visible = local.length() > 1 ? local.substring(0, 1) : "";
+        return visible + "***@" + email.substring(at + 1);
+    }
+
+    private static void validatePage(int page, int size) {
+        if (page < 0 || size < 1 || size > MAX_PAGE_SIZE) throw new IllegalArgumentException("page/size out of range");
+    }
+
+    private static String normalizeKeyword(String keyword) {
+        if (keyword == null || keyword.isBlank()) return null;
+        String normalized = keyword.strip();
+        if (normalized.length() > 240) throw new IllegalArgumentException("keyword is too long");
+        return normalized;
+    }
+
+    private static String normalizeReason(String reason) {
+        return reason == null || reason.isBlank() ? null : reason.strip();
+    }
+
+    private static ProblemException notFound(String code) {
+        return new ProblemException(code, "Comment not found", "The requested comment does not exist");
+    }
+
+    private static ProblemException versionConflict(long currentVersion) {
+        return new ProblemException("COMMENT_VERSION_CONFLICT", "Comment version conflict",
+                "Reload the latest comment before moderating it", currentVersion);
+    }
+
     @Transactional
     public CommentPage list(String slug, int page, int size) {
         if (page < 0 || size < 1 || size > MAX_PAGE_SIZE) {
@@ -244,5 +344,29 @@ public record CommentPage(List<CommentView> items, int page, int size, long tota
     public record CommentView(UUID id, String nickname, String content, Instant createdAt,
                               List<CommentView> replies) {}
 
+    public record AdminComment(UUID id, UUID articleId, UUID parentId, String nickname, String content,
+                               String emailMasked, CommentStatus status, UUID moderatorId,
+                               String moderationReason, Instant moderatedAt, Instant createdAt,
+                               Instant updatedAt, long version) {
+        static AdminComment from(Comment comment, String emailMasked) {
+            return new AdminComment(comment.getId(), comment.getArticleId(), comment.getParentId(), comment.getNickname(),
+                    comment.getContent(), emailMasked, comment.getStatus(), comment.getModeratorId(),
+                    comment.getModerationReason(), comment.getModeratedAt(), comment.getCreatedAt(),
+                    comment.getUpdatedAt(), comment.getVersion());
+        }
+    }
+
+    public record AdminCommentDetail(UUID id, UUID articleId, UUID parentId, String nickname, String content,
+                                     String email, CommentStatus status, UUID moderatorId,
+                                     String moderationReason, Instant moderatedAt, Instant createdAt,
+                                     Instant updatedAt, long version) {
+        static AdminCommentDetail from(Comment comment, String email) {
+            return new AdminCommentDetail(comment.getId(), comment.getArticleId(), comment.getParentId(),
+                    comment.getNickname(), comment.getContent(), email, comment.getStatus(), comment.getModeratorId(),
+                    comment.getModerationReason(), comment.getModeratedAt(), comment.getCreatedAt(),
+                    comment.getUpdatedAt(), comment.getVersion());
+        }
+    }
+
     private record RateDecision(boolean allowed, long retryAfterSeconds) {}
 }
diff --git a/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java b/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
index 28114f6..c6d36d0 100644
--- a/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
+++ b/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
@@ -5,12 +5,26 @@
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 
 import java.util.List;
 import java.util.Optional;
 import java.util.UUID;
 
 public interface CommentRepository extends JpaRepository<Comment, UUID> {
+    @Query("""
+            select c from Comment c
+            where (:status is null or c.status = :status)
+              and (:articleId is null or c.articleId = :articleId)
+              and (:keyword is null or lower(c.nickname) like lower(concat('%', :keyword, '%'))
+                   or lower(c.content) like lower(concat('%', :keyword, '%')))
+            """)
+    Page<Comment> findAdminComments(@Param("status") CommentStatus status,
+                                    @Param("articleId") UUID articleId,
+                                    @Param("keyword") String keyword,
+                                    Pageable pageable);
+
     Page<Comment> findByArticleIdAndStatusAndParentIdIsNullOrderByCreatedAtAscIdAsc(
             UUID articleId, CommentStatus status, Pageable pageable);
 
diff --git a/apps/api/src/main/java/io/haoblog/comment/web/AdminCommentController.java b/apps/api/src/main/java/io/haoblog/comment/web/AdminCommentController.java
new file mode 100644
index 0000000..ab4940e
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/web/AdminCommentController.java
@@ -0,0 +1,69 @@
+package io.haoblog.comment.web;
+
+import io.haoblog.comment.application.CommentService;
+import io.haoblog.comment.domain.CommentStatus;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import org.springframework.data.domain.Sort;
+import org.springframework.dao.OptimisticLockingFailureException;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+import java.util.UUID;
+
+@RestController
+@RequestMapping("/api/v1/admin/comments")
+public class AdminCommentController {
+    private final CommentService service;
+
+    public AdminCommentController(CommentService service) {
+        this.service = service;
+    }
+
+    @GetMapping
+    public ListResponse list(@RequestParam(defaultValue = "0") int page,
+                             @RequestParam(defaultValue = "20") int size,
+                             @RequestParam(required = false) CommentStatus status,
+                             @RequestParam(required = false) UUID articleId,
+                             @RequestParam(required = false) String keyword,
+                             @RequestParam(defaultValue = "desc") String direction) {
+        var result = service.listAdmin(status, articleId, keyword, page, size, parseDirection(direction));
+        return new ListResponse(result.getContent(), result.getNumber(), result.getSize(), result.getTotalElements());
+    }
+
+    @GetMapping("/{id}")
+    public CommentService.AdminCommentDetail get(@PathVariable UUID id) {
+        return service.getAdmin(id);
+    }
+
+    @PostMapping("/{id}/moderation")
+    public CommentService.AdminCommentDetail moderate(@PathVariable UUID id,
+                                                      @RequestBody @Valid ModerationRequest request,
+                                                      Authentication authentication) {
+        try {
+            return service.moderate(id, request.version(), request.status(), request.reason(), authentication.getName());
+        } catch (OptimisticLockingFailureException exception) {
+            throw new io.haoblog.shared.web.ProblemException("COMMENT_VERSION_CONFLICT", "Comment version conflict",
+                    "Reload the latest comment before moderating it", service.getAdmin(id).version());
+        }
+    }
+
+    private static Sort.Direction parseDirection(String direction) {
+        if ("asc".equalsIgnoreCase(direction)) return Sort.Direction.ASC;
+        if ("desc".equalsIgnoreCase(direction)) return Sort.Direction.DESC;
+        throw new IllegalArgumentException("direction must be asc or desc");
+    }
+
+    public record ListResponse(List<CommentService.AdminComment> items, int page, int size, long total) {}
+
+    public record ModerationRequest(@NotNull Long version, @NotNull CommentStatus status,
+                                    @Size(max = 600) String reason) {}
+}
diff --git a/apps/api/src/main/java/io/haoblog/content/application/AdminContentService.java b/apps/api/src/main/java/io/haoblog/content/application/AdminContentService.java
index 9170b89..f2408db 100644
--- a/apps/api/src/main/java/io/haoblog/content/application/AdminContentService.java
+++ b/apps/api/src/main/java/io/haoblog/content/application/AdminContentService.java
@@ -66,7 +66,7 @@ public Page<Article> listArticles(int page, int size, ArticleStatus status, Stri
     @Transactional
     public Article createArticle(String slug, String title, String excerpt, String markdown,
                                  String seoTitle, String seoDescription, Instant scheduledAt, UUID categoryId,
-                                 UUID coverMediaId, List<UUID> tagIds) {
+                                 UUID coverMediaId, List<UUID> tagIds, Boolean commentsEnabled) {
         String resolvedTitle = title == null || title.isBlank() ? "未命名草稿" : title.trim();
         String resolvedMarkdown = markdown == null ? "" : markdown;
         validateArticle(resolvedTitle, resolvedMarkdown, excerpt, seoTitle, seoDescription);
@@ -82,6 +82,7 @@ public Article createArticle(String slug, String title, String excerpt, String m
                 ArticleStatus.DRAFT, null, now);
         article.updateWorkingCopy(normalizedSlug, resolvedTitle, excerpt, resolvedMarkdown, seoTitle, seoDescription,
                 scheduledAt, categoryId, coverMediaId, now);
+        article.setCommentsEnabled(commentsEnabled == null || commentsEnabled);
         article.replaceTags(resolvedTags);
         return articles.saveAndFlush(article);
     }
@@ -142,7 +143,7 @@ public Article restoreRevision(UUID articleId, UUID revisionId, long version) {
     @Transactional
     public Article updateArticle(UUID id, long version, String slug, String title, String excerpt, String markdown,
                                  String seoTitle, String seoDescription, Instant scheduledAt, UUID categoryId,
-                                 UUID coverMediaId, List<UUID> tagIds) {
+                                 UUID coverMediaId, List<UUID> tagIds, Boolean commentsEnabled) {
         Article article = getArticle(id);
         if (article.getStatus() == ArticleStatus.ARCHIVED) {
             throw new ProblemException("ARTICLE_STATE_CONFLICT", "Article is archived",
@@ -162,6 +163,7 @@ public Article updateArticle(UUID id, long version, String slug, String title, S
         requireMedia(coverMediaId);
         article.updateWorkingCopy(resolvedSlug, title.trim(), excerpt, markdown, seoTitle, seoDescription,
                 scheduledAt, categoryId, coverMediaId, Instant.now(clock));
+        if (commentsEnabled != null) article.setCommentsEnabled(commentsEnabled);
         article.replaceTags(resolvedTags);
         return articles.saveAndFlush(article);
     }
diff --git a/apps/api/src/main/java/io/haoblog/content/web/AdminArticleController.java b/apps/api/src/main/java/io/haoblog/content/web/AdminArticleController.java
index d0c96a0..11931eb 100644
--- a/apps/api/src/main/java/io/haoblog/content/web/AdminArticleController.java
+++ b/apps/api/src/main/java/io/haoblog/content/web/AdminArticleController.java
@@ -51,9 +51,9 @@ public ListResponse list(@RequestParam(defaultValue = "0") int page,
 
     @PostMapping
     public ResponseEntity<Response> create(@RequestBody(required = false) @Valid CreateRequest request) {
-        CreateRequest body = request == null ? new CreateRequest(null, null, null, null, null, null, null, null, null, null) : request;
+        CreateRequest body = request == null ? new CreateRequest(null, null, null, null, null, null, null, null, null, null, null) : request;
         Response response = Response.from(service.createArticle(body.slug(), body.title(), body.excerpt(), body.markdown(),
-                body.seoTitle(), body.seoDescription(), body.scheduledAt(), body.categoryId(), body.coverMediaId(), body.tagIds()));
+                body.seoTitle(), body.seoDescription(), body.scheduledAt(), body.categoryId(), body.coverMediaId(), body.tagIds(), body.commentsEnabled()));
         URI location = ServletUriComponentsBuilder.fromCurrentRequest().path("/{id}").buildAndExpand(response.id()).toUri();
         return ResponseEntity.created(location).body(response);
     }
@@ -89,7 +89,7 @@ public Response restoreVersion(@PathVariable UUID id, @PathVariable UUID revisio
     public Response update(@PathVariable UUID id, @RequestBody @Valid UpdateRequest request) {
         try {
             return Response.from(service.updateArticle(id, request.version(), request.slug(), request.title(), request.excerpt(),
-                    request.markdown(), request.seoTitle(), request.seoDescription(), request.scheduledAt(), request.categoryId(), request.coverMediaId(), request.tagIds()));
+                    request.markdown(), request.seoTitle(), request.seoDescription(), request.scheduledAt(), request.categoryId(), request.coverMediaId(), request.tagIds(), request.commentsEnabled()));
         } catch (OptimisticLockingFailureException exception) {
             throw new ProblemException("ARTICLE_VERSION_CONFLICT", "Article version conflict",
                     "Reload the latest article before saving", service.currentVersion(id));
diff --git a/apps/api/src/main/java/io/haoblog/content/web/AdminArticleDtos.java b/apps/api/src/main/java/io/haoblog/content/web/AdminArticleDtos.java
index 4a7142c..c1bcc95 100644
--- a/apps/api/src/main/java/io/haoblog/content/web/AdminArticleDtos.java
+++ b/apps/api/src/main/java/io/haoblog/content/web/AdminArticleDtos.java
@@ -23,7 +23,8 @@ public record CreateRequest(
             Instant scheduledAt,
             UUID categoryId,
             UUID coverMediaId,
-            List<UUID> tagIds) {}
+            List<UUID> tagIds,
+            Boolean commentsEnabled) {}
 
     public record UpdateRequest(
             @NotNull Long version,
@@ -36,7 +37,8 @@ public record UpdateRequest(
             Instant scheduledAt,
             UUID categoryId,
             UUID coverMediaId,
-            List<UUID> tagIds) {}
+            List<UUID> tagIds,
+            Boolean commentsEnabled) {}
 
     public record ListResponse(List<Summary> items, int page, int size, long total) {}
 
diff --git a/apps/api/src/main/java/io/haoblog/content/web/PublicArticleController.java b/apps/api/src/main/java/io/haoblog/content/web/PublicArticleController.java
index 14dc08c..7310683 100644
--- a/apps/api/src/main/java/io/haoblog/content/web/PublicArticleController.java
+++ b/apps/api/src/main/java/io/haoblog/content/web/PublicArticleController.java
@@ -3,12 +3,14 @@
 import io.haoblog.content.application.ArticleService;
 import io.haoblog.content.domain.ArticleRevision;
 import io.haoblog.shared.web.ProblemResponse;
+import io.haoblog.site.application.SiteService;
 import org.slf4j.MDC;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
+import org.springframework.beans.factory.annotation.Autowired;
 
 import java.security.MessageDigest;
 import java.time.Instant;
@@ -23,8 +25,17 @@
 public class PublicArticleController {
     private static final MediaType PROBLEM = MediaType.valueOf("application/problem+json");
     private final ArticleService service;
+    private final SiteService siteService;
 
-    public PublicArticleController(ArticleService service) { this.service = service; }
+    @Autowired
+    public PublicArticleController(ArticleService service, SiteService siteService) {
+        this.service = service;
+        this.siteService = siteService;
+    }
+
+    public PublicArticleController(ArticleService service) {
+        this(service, null);
+    }
 
     @GetMapping
     public ResponseEntity<ArticleListResponse> articles(@RequestParam(defaultValue = "0") int page,
@@ -33,8 +44,10 @@ public ResponseEntity<ArticleListResponse> articles(@RequestParam(defaultValue =
         var result = service.list(page, size).page();
         Map<UUID, String> coverUrls = service.publicCoverUrls(result.getContent().stream()
                 .map(article -> article.revision().getCoverMediaId()).filter(java.util.Objects::nonNull).collect(Collectors.toSet()));
+        boolean globalCommentsEnabled = globalCommentsEnabled();
         var response = new ArticleListResponse(result.getContent().stream().map(article -> ArticleSummary.from(article,
-                        article.revision().getCoverMediaId() == null ? null : coverUrls.get(article.revision().getCoverMediaId()))).toList(),
+                        article.revision().getCoverMediaId() == null ? null : coverUrls.get(article.revision().getCoverMediaId()),
+                        globalCommentsEnabled)).toList(),
                 result.getNumber(), result.getSize(), result.getTotalElements());
         String etag = representationHash("list", result.getContent().stream().map(article -> article.revision().getId()).toList(), response);
         return withCache(response, etag, ifNoneMatch);
@@ -45,7 +58,7 @@ public ResponseEntity<ArticleResponse> article(@PathVariable String slug,
                                                    @RequestHeader(value = HttpHeaders.IF_NONE_MATCH, required = false) String ifNoneMatch) {
         ArticleService.PublicArticle article = service.findPublicBySlug(slug).orElseThrow(() -> new ArticleNotFoundException(slug));
         String coverImageUrl = article.revision().getCoverMediaId() == null ? null : service.publicCoverUrls(java.util.Set.of(article.revision().getCoverMediaId())).get(article.revision().getCoverMediaId());
-        var response = ArticleResponse.from(article, coverImageUrl);
+        var response = ArticleResponse.from(article, coverImageUrl, globalCommentsEnabled());
         return withCache(response, representationHash("detail", article.revision().getId(), response), ifNoneMatch);
     }
 
@@ -73,23 +86,29 @@ private static String representationHash(Object... values) {
         }
     }
 
+    private boolean globalCommentsEnabled() {
+        if (siteService == null) return true;
+        var site = siteService.get();
+        return site == null || site.commentsEnabled();
+    }
+
     public record ArticleSummary(UUID id, String slug, String title, String excerpt, Instant publishedAt, String coverImageUrl,
                                  boolean commentsEnabled) {
-        static ArticleSummary from(ArticleService.PublicArticle article, String coverImageUrl) {
+        static ArticleSummary from(ArticleService.PublicArticle article, String coverImageUrl, boolean globalCommentsEnabled) {
             ArticleRevision revision = article.revision();
             return new ArticleSummary(revision.getArticleId(), revision.getSlug(), revision.getTitle(), revision.getExcerpt(),
-                    article.publishedAt(), coverImageUrl, article.commentsEnabled());
+                    article.publishedAt(), coverImageUrl, article.commentsEnabled() && globalCommentsEnabled);
         }
     }
     public record ArticleListResponse(List<ArticleSummary> items, int page, int size, long total) {}
     public record ArticleResponse(UUID id, String slug, String title, String excerpt, Instant publishedAt, Instant modifiedAt,
                                   String markdown, String seoTitle, String seoDescription, String coverImageUrl,
                                   boolean commentsEnabled) {
-        static ArticleResponse from(ArticleService.PublicArticle article, String coverImageUrl) {
+        static ArticleResponse from(ArticleService.PublicArticle article, String coverImageUrl, boolean globalCommentsEnabled) {
             ArticleRevision revision = article.revision();
             return new ArticleResponse(revision.getArticleId(), revision.getSlug(), revision.getTitle(), revision.getExcerpt(),
                     article.publishedAt(), revision.getCreatedAt(), revision.getMarkdownSource(), revision.getSeoTitle(),
-                    revision.getSeoDescription(), coverImageUrl, article.commentsEnabled());
+                    revision.getSeoDescription(), coverImageUrl, article.commentsEnabled() && globalCommentsEnabled);
         }
     }
 }
diff --git a/apps/api/src/main/java/io/haoblog/site/application/SiteService.java b/apps/api/src/main/java/io/haoblog/site/application/SiteService.java
index f0e9eaf..103d1a2 100644
--- a/apps/api/src/main/java/io/haoblog/site/application/SiteService.java
+++ b/apps/api/src/main/java/io/haoblog/site/application/SiteService.java
@@ -29,6 +29,29 @@ public SiteResult get() {
         return new SiteResult(setting.getTitle(), setting.getDescription(), publicBaseUrl, authorName, setting.isCommentsEnabled());
     }
 
+    public AdminSiteResult getAdmin() {
+        var setting = repository.findBySiteKey("default").orElseThrow();
+        return new AdminSiteResult(setting.getTitle(), setting.getDescription(), publicBaseUrl, authorName,
+                setting.isCommentsEnabled(), setting.getVersion());
+    }
+
+    @org.springframework.transaction.annotation.Transactional
+    public AdminSiteResult updateCommentsEnabled(long expectedVersion, boolean commentsEnabled) {
+        var setting = repository.findBySiteKey("default").orElseThrow();
+        if (setting.getVersion() != expectedVersion) {
+            throw new io.haoblog.shared.web.ProblemException("SITE_VERSION_CONFLICT", "Site setting version conflict",
+                    "Reload the latest site settings before saving", setting.getVersion());
+        }
+        setting.setCommentsEnabled(commentsEnabled);
+        var saved = repository.saveAndFlush(setting);
+        return new AdminSiteResult(saved.getTitle(), saved.getDescription(), publicBaseUrl, authorName,
+                saved.isCommentsEnabled(), saved.getVersion());
+    }
+
+    public long currentVersion() {
+        return repository.findBySiteKey("default").orElseThrow().getVersion();
+    }
+
     static String normalizePublicBaseUrl(String raw) {
         if (raw == null || raw.isBlank()) {
             throw new IllegalArgumentException("HAOBLOG_PUBLIC_BASE_URL must be an absolute HTTP(S) origin");
@@ -52,4 +75,7 @@ public SiteResult(String title, String description, String siteUrl, String autho
             this(title, description, siteUrl, authorName, true);
         }
     }
+
+    public record AdminSiteResult(String title, String description, String siteUrl, String authorName,
+                                  boolean commentsEnabled, long version) {}
 }
diff --git a/apps/api/src/main/java/io/haoblog/site/domain/SiteSetting.java b/apps/api/src/main/java/io/haoblog/site/domain/SiteSetting.java
index 2880402..34366e1 100644
--- a/apps/api/src/main/java/io/haoblog/site/domain/SiteSetting.java
+++ b/apps/api/src/main/java/io/haoblog/site/domain/SiteSetting.java
@@ -21,4 +21,5 @@ public SiteSetting(String siteKey, String title, String description) {
     public String getDescription() { return description; }
     public boolean isCommentsEnabled() { return commentsEnabled; }
     public long getVersion() { return version; }
+    public void setCommentsEnabled(boolean commentsEnabled) { this.commentsEnabled = commentsEnabled; }
 }
diff --git a/apps/api/src/main/java/io/haoblog/site/web/AdminSiteController.java b/apps/api/src/main/java/io/haoblog/site/web/AdminSiteController.java
new file mode 100644
index 0000000..9aff3df
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/site/web/AdminSiteController.java
@@ -0,0 +1,47 @@
+package io.haoblog.site.web;
+
+import io.haoblog.shared.web.ProblemException;
+import io.haoblog.site.application.SiteService;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotNull;
+import org.springframework.dao.OptimisticLockingFailureException;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api/v1/admin/site")
+public class AdminSiteController {
+    private final SiteService service;
+
+    public AdminSiteController(SiteService service) {
+        this.service = service;
+    }
+
+    @GetMapping
+    public Response get() {
+        return Response.from(service.getAdmin());
+    }
+
+    @PutMapping
+    public Response update(@RequestBody @Valid UpdateRequest request) {
+        try {
+            return Response.from(service.updateCommentsEnabled(request.version(), request.commentsEnabled()));
+        } catch (OptimisticLockingFailureException exception) {
+            throw new ProblemException("SITE_VERSION_CONFLICT", "Site setting version conflict",
+                    "Reload the latest site settings before saving", service.currentVersion());
+        }
+    }
+
+    public record UpdateRequest(@NotNull Long version, @NotNull Boolean commentsEnabled) {}
+
+    public record Response(String title, String description, String siteUrl, String authorName,
+                           boolean commentsEnabled, long version) {
+        static Response from(SiteService.AdminSiteResult result) {
+            return new Response(result.title(), result.description(), result.siteUrl(), result.authorName(),
+                    result.commentsEnabled(), result.version());
+        }
+    }
+}
diff --git a/apps/api/src/test/java/io/haoblog/AdminCommentIT.java b/apps/api/src/test/java/io/haoblog/AdminCommentIT.java
new file mode 100644
index 0000000..f4b3c1e
--- /dev/null
+++ b/apps/api/src/test/java/io/haoblog/AdminCommentIT.java
@@ -0,0 +1,193 @@
+package io.haoblog;
+
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+import io.haoblog.comment.application.CommentSecurityService;
+import io.haoblog.content.domain.Article;
+import io.haoblog.content.domain.ArticleStatus;
+import io.haoblog.content.persistence.ArticleRepository;
+import io.haoblog.shared.id.UuidV7;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.springframework.test.web.servlet.MockMvc;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import java.sql.Date;
+import java.sql.Timestamp;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.temporal.ChronoUnit;
+import java.util.Map;
+import java.util.UUID;
+
+import static org.hamcrest.Matchers.not;
+import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf;
+import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.user;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@Testcontainers
+@SpringBootTest
+@AutoConfigureMockMvc
+class AdminCommentIT {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("pgvector/pgvector:0.8.6-pg17");
+
+    @DynamicPropertySource
+    static void database(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+        registry.add("spring.flyway.placeholders.admin_username", () -> "admin");
+        registry.add("spring.flyway.placeholders.admin_password_hash", () -> "$2a$10$0V.Xs7CLOUYSekm7RKq3Z.iY76KUan/Xbeu5vjmLpX.sVd4pcFpIu");
+    }
+
+    @Autowired MockMvc mvc;
+    @Autowired ObjectMapper objectMapper;
+    @Autowired JdbcTemplate jdbc;
+    @Autowired ArticleRepository articles;
+    @Autowired CommentSecurityService security;
+    private UUID articleId;
+
+    @BeforeEach
+    void seed() {
+        jdbc.execute("TRUNCATE comment, article_revision, article CASCADE");
+        jdbc.update("UPDATE site_setting SET comments_enabled=true, version=0 WHERE site_key='default'");
+        Instant now = Instant.parse("2030-01-01T00:00:00Z");
+        Article article = articles.saveAndFlush(new Article("moderation-signal", "Moderation signal", "Excerpt", "# body",
+                ArticleStatus.PUBLISHED, now.minus(1, ChronoUnit.DAYS), now));
+        articleId = article.getId();
+        UUID revisionId = UuidV7.generate();
+        jdbc.update("INSERT INTO article_revision(id, article_id, source_version, title, slug, excerpt, markdown_source, tag_snapshot, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, '[]'::jsonb, ?)",
+                revisionId, articleId, 0L, "Moderation signal", "moderation-signal", "Excerpt", "# body", Timestamp.from(now));
+        jdbc.update("UPDATE article SET published_revision_id=? WHERE id=?", revisionId, articleId);
+        insertComment("Alice", "first signal", "alice@example.com", "PENDING", now.minusSeconds(30));
+        insertComment("Bob", "second signal", null, "APPROVED", now.minusSeconds(10));
+        insertComment("Alice", "third signal", null, "REJECTED", now);
+    }
+
+    @Test
+    void protectsAdminEndpointsWithAuthenticationRoleAndCsrf() throws Exception {
+        mvc.perform(get("/api/v1/admin/comments")).andExpect(status().isUnauthorized())
+                .andExpect(content().contentType("application/problem+json"));
+        mvc.perform(get("/api/v1/admin/comments").with(user("reader").roles("USER")))
+                .andExpect(status().isForbidden());
+        mvc.perform(post("/api/v1/admin/comments/{id}/moderation", firstComment()).with(user("admin").roles("ADMIN"))
+                        .contentType("application/json").content("{}"))
+                .andExpect(status().isForbidden()).andExpect(jsonPath("$.code").value("CSRF_INVALID"));
+    }
+
+    @Test
+    void filtersAndPagesModerationLog() throws Exception {
+        mvc.perform(get("/api/v1/admin/comments").with(admin())
+                        .param("status", "PENDING").param("articleId", articleId.toString())
+                        .param("keyword", "Alice").param("page", "0").param("size", "1").param("direction", "asc"))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.total").value(1))
+                .andExpect(jsonPath("$.items[0].nickname").value("Alice"))
+                .andExpect(jsonPath("$.items[0].emailMasked").value("a***@example.com"))
+                .andExpect(jsonPath("$.items[0].ipHmac").doesNotExist())
+                .andExpect(jsonPath("$.items[0].deleteTokenDigest").doesNotExist());
+    }
+
+    @Test
+    void onlyDetailReturnsDecryptedEmailAndModerationUsesVersionAndAudit() throws Exception {
+        UUID id = firstComment();
+        var detail = mvc.perform(get("/api/v1/admin/comments/{id}", id).with(admin()))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.email").value("alice@example.com"))
+                .andExpect(jsonPath("$.ipHmac").doesNotExist()).andReturn();
+        JsonNode body = objectMapper.readTree(detail.getResponse().getContentAsString());
+        long version = body.get("version").asLong();
+
+        mvc.perform(post("/api/v1/admin/comments/{id}/moderation", id).with(admin()).with(csrf())
+                        .contentType("application/json")
+                        .content(objectMapper.writeValueAsString(Map.of("version", version, "status", "SPAM", "reason", "链接密度过高"))))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.status").value("SPAM"))
+                .andExpect(jsonPath("$.moderationReason").value("链接密度过高"))
+                .andExpect(jsonPath("$.moderatorId").isNotEmpty()).andExpect(jsonPath("$.version").value(1));
+
+        mvc.perform(post("/api/v1/admin/comments/{id}/moderation", id).with(admin()).with(csrf())
+                        .contentType("application/json")
+                        .content("{\"version\":0,\"status\":\"APPROVED\"}"))
+                .andExpect(status().isConflict()).andExpect(jsonPath("$.code").value("COMMENT_VERSION_CONFLICT"));
+
+        mvc.perform(post("/api/v1/admin/comments/{id}/moderation", id).with(admin()).with(csrf())
+                        .contentType("application/json")
+                        .content("{\"version\":1,\"status\":\"PENDING\"}"))
+                .andExpect(status().isConflict()).andExpect(jsonPath("$.code").value("COMMENT_MODERATION_STATE_CONFLICT"));
+    }
+
+    @Test
+    void globalSiteSwitchChangesPublicSiteAndArticleEtags() throws Exception {
+        var site = mvc.perform(get("/api/v1/public/site")).andExpect(status().isOk()).andReturn();
+        var article = mvc.perform(get("/api/v1/public/articles/moderation-signal")).andExpect(status().isOk()).andReturn();
+        String siteEtag = site.getResponse().getHeader("ETag");
+        String articleEtag = article.getResponse().getHeader("ETag");
+
+        mvc.perform(put("/api/v1/admin/site").with(admin()).with(csrf()).contentType("application/json")
+                        .content("{\"version\":0,\"commentsEnabled\":false}"))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.commentsEnabled").value(false));
+
+        mvc.perform(get("/api/v1/public/site").header("If-None-Match", siteEtag))
+                .andExpect(status().isOk()).andExpect(header().string("ETag", not(siteEtag)))
+                .andExpect(jsonPath("$.commentsEnabled").value(false));
+        mvc.perform(get("/api/v1/public/articles/moderation-signal").header("If-None-Match", articleEtag))
+                .andExpect(status().isOk()).andExpect(header().string("ETag", not(articleEtag)))
+                .andExpect(jsonPath("$.commentsEnabled").value(false));
+        mvc.perform(put("/api/v1/admin/site").with(admin()).with(csrf()).contentType("application/json")
+                        .content("{\"version\":0,\"commentsEnabled\":true}"))
+                .andExpect(status().isConflict()).andExpect(jsonPath("$.code").value("SITE_VERSION_CONFLICT"));
+    }
+
+    @Test
+    void articleSwitchChangesPublicArticleEtag() throws Exception {
+        var before = mvc.perform(get("/api/v1/public/articles/moderation-signal")).andExpect(status().isOk()).andReturn();
+        var adminArticle = mvc.perform(get("/api/v1/admin/articles/{id}", articleId).with(admin()))
+                .andExpect(status().isOk()).andReturn();
+        long version = objectMapper.readTree(adminArticle.getResponse().getContentAsString()).get("version").asLong();
+        mvc.perform(put("/api/v1/admin/articles/{id}", articleId).with(admin()).with(csrf())
+                        .contentType("application/json")
+                        .content(objectMapper.writeValueAsString(Map.of("version", version, "title", "Moderation signal",
+                                "markdown", "# body", "commentsEnabled", false))))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.commentsEnabled").value(false));
+        mvc.perform(get("/api/v1/public/articles/moderation-signal")
+                        .header("If-None-Match", before.getResponse().getHeader("ETag")))
+                .andExpect(status().isOk()).andExpect(header().string("ETag", not(before.getResponse().getHeader("ETag"))))
+                .andExpect(jsonPath("$.commentsEnabled").value(false));
+    }
+
+    private org.springframework.test.web.servlet.request.RequestPostProcessor admin() {
+        return user("admin").roles("ADMIN");
+    }
+
+    private UUID firstComment() {
+        return jdbc.queryForObject("SELECT id FROM comment WHERE nickname='Alice' AND content='first signal'", UUID.class);
+    }
+
+    private void insertComment(String nickname, String content, String email, String status, Instant createdAt) {
+        UUID id = UuidV7.generate();
+        var encrypted = security.encryptEmail(id, email);
+        jdbc.update("""
+                INSERT INTO comment(id, article_id, nickname, email_ciphertext, email_nonce, email_key_version,
+                    content, status, ip_hmac, ip_hmac_date, content_fingerprint, delete_token_digest, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """, id, articleId, nickname,
+                encrypted == null ? null : encrypted.ciphertext(), encrypted == null ? null : encrypted.nonce(),
+                encrypted == null ? null : encrypted.keyVersion(), content, status, new byte[32],
+                Date.valueOf(LocalDate.ofInstant(createdAt, java.time.ZoneOffset.UTC)),
+                security.contentFingerprint(articleId, nickname + content), security.deleteTokenDigest(security.newDeleteToken()),
+                Timestamp.from(createdAt), Timestamp.from(createdAt));
+    }
+}
diff --git a/apps/web/app/components/studio/StudioArticleEditor.client.vue b/apps/web/app/components/studio/StudioArticleEditor.client.vue
index d2282d5..7101038 100644
--- a/apps/web/app/components/studio/StudioArticleEditor.client.vue
+++ b/apps/web/app/components/studio/StudioArticleEditor.client.vue
@@ -72,6 +72,13 @@
         </div>
         <small v-else>暂无可用标签。</small>
       </div>
+      <div class="field-line field-wide">
+        <label class="switch-line" for="article-comments-enabled">
+          <input id="article-comments-enabled" v-model="form.commentsEnabled" type="checkbox" name="commentsEnabled">
+          <span>允许公开评论</span>
+        </label>
+        <small>关闭后仅影响这篇文章；站点全局开关仍可统一暂停评论。</small>
+      </div>
       <div class="field-line field-wide">
         <span class="field-label">媒体 / DIRECT OSS UPLOAD</span>
         <div class="media-upload-box">
@@ -315,6 +322,8 @@ legend { padding: 0 var(--space-2); color: var(--color-accent); font: var(--text
 .field-wide { grid-column: 1 / -1; }
 .field-line { display: grid; gap: var(--space-2); min-width: 0; }
 .field-line label, .field-label { color: var(--color-accent); font: var(--text-xs)/1.4 var(--font-mono); letter-spacing: .08em; }
+.switch-line { display: inline-flex; align-items: center; gap: .6rem; width: fit-content; cursor: pointer; }
+.switch-line input { width: 1rem; height: 1rem; accent-color: var(--color-accent); }
 .field-line input, .field-line textarea, .field-line select { width: 100%; min-width: 0; padding: .7rem 0; border: 0; border-bottom: 1px solid var(--color-border); border-radius: 0; outline: 0; background: transparent; color: var(--color-text-main); font: var(--text-base)/1.45 var(--font-body); }
 .field-line textarea { resize: vertical; }
 .field-line select { appearance: auto; }
diff --git a/apps/web/app/composables/useAdminComments.ts b/apps/web/app/composables/useAdminComments.ts
new file mode 100644
index 0000000..8785297
--- /dev/null
+++ b/apps/web/app/composables/useAdminComments.ts
@@ -0,0 +1,45 @@
+import type { components } from '@haoblog/api-client'
+import { useAdminSession } from './useAdminSession'
+
+type CommentList = components['schemas']['AdminCommentListResponse']
+type CommentDetail = components['schemas']['AdminCommentDetail']
+type ModerationRequest = components['schemas']['CommentModerationRequest']
+
+export function useAdminComments() {
+  const session = useAdminSession()
+
+  async function listComments(params: {
+    page?: number
+    size?: number
+    status?: components['schemas']['CommentStatus']
+    articleId?: string
+    keyword?: string
+    direction?: 'asc' | 'desc'
+  } = {}) {
+    const query = new URLSearchParams({
+      page: String(params.page ?? 0),
+      size: String(params.size ?? 20),
+      direction: params.direction ?? 'desc',
+    })
+    if (params.status) query.set('status', params.status)
+    if (params.articleId) query.set('articleId', params.articleId)
+    if (params.keyword?.trim()) query.set('keyword', params.keyword.trim())
+    return session.request<CommentList>(`/api/v1/admin/comments?${query}`)
+  }
+
+  async function getComment(id: string) {
+    return session.request<CommentDetail>(`/api/v1/admin/comments/${encodeURIComponent(id)}`)
+  }
+
+  async function moderateComment(id: string, payload: ModerationRequest) {
+    return session.write<CommentDetail>(`/api/v1/admin/comments/${encodeURIComponent(id)}/moderation`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+  }
+
+  return { listComments, getComment, moderateComment }
+}
+
+export type { CommentDetail, CommentList, ModerationRequest }
diff --git a/apps/web/app/composables/useAdminSite.ts b/apps/web/app/composables/useAdminSite.ts
new file mode 100644
index 0000000..452c7ef
--- /dev/null
+++ b/apps/web/app/composables/useAdminSite.ts
@@ -0,0 +1,25 @@
+import type { components } from '@haoblog/api-client'
+import { useAdminSession } from './useAdminSession'
+
+type Site = components['schemas']['AdminSiteResponse']
+type SiteUpdateRequest = components['schemas']['AdminSiteUpdateRequest']
+
+export function useAdminSite() {
+  const session = useAdminSession()
+
+  async function getSite() {
+    return session.request<Site>('/api/v1/admin/site')
+  }
+
+  async function updateSite(payload: SiteUpdateRequest) {
+    return session.write<Site>('/api/v1/admin/site', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+  }
+
+  return { getSite, updateSite }
+}
+
+export type { Site, SiteUpdateRequest }
diff --git a/apps/web/app/composables/useArticleAutosave.ts b/apps/web/app/composables/useArticleAutosave.ts
index b9b6159..37a563e 100644
--- a/apps/web/app/composables/useArticleAutosave.ts
+++ b/apps/web/app/composables/useArticleAutosave.ts
@@ -27,6 +27,7 @@ type Options = {
 const fieldLabels: Record<keyof ArticleFormModel, string> = {
   title: '标题', slug: 'Slug', excerpt: '摘要', seoTitle: 'SEO 标题', seoDescription: 'SEO 描述',
   categoryId: '分类', tagIds: '标签', coverMediaId: '封面', scheduledAt: '定时发布时间', markdown: 'Markdown', version: '版本',
+  commentsEnabled: '评论开关',
 }
 
 function lineCount(value: string) { return value ? value.split(/\r?\n/).length : 0 }
diff --git a/apps/web/app/layouts/studio.vue b/apps/web/app/layouts/studio.vue
index dcfd127..e50f6dd 100644
--- a/apps/web/app/layouts/studio.vue
+++ b/apps/web/app/layouts/studio.vue
@@ -10,6 +10,8 @@
       <nav v-if="session" class="studio-nav" aria-label="工作台导航">
         <NuxtLink to="/studio/articles" :aria-current="route.path === '/studio/articles' ? 'page' : undefined">文章日志</NuxtLink>
         <NuxtLink to="/studio/articles/new">新建文章</NuxtLink>
+        <NuxtLink to="/studio/comments" :aria-current="route.path === '/studio/comments' ? 'page' : undefined">评论审核</NuxtLink>
+        <NuxtLink to="/studio/settings" :aria-current="route.path === '/studio/settings' ? 'page' : undefined">站点开关</NuxtLink>
         <NuxtLink to="/" external>返回公开站</NuxtLink>
         <button type="button" :disabled="pending" @click="signOut">{{ pending ? 'CLEARING…' : '退出' }}</button>
       </nav>
diff --git a/apps/web/app/pages/studio/comments.vue b/apps/web/app/pages/studio/comments.vue
new file mode 100644
index 0000000..6416a51
--- /dev/null
+++ b/apps/web/app/pages/studio/comments.vue
@@ -0,0 +1,205 @@
+<template>
+  <section class="moderation-scene" aria-labelledby="comments-title">
+    <div class="page-heading">
+      <div>
+        <p class="instrument-label">STUDIO / COMMENT SIGNAL</p>
+        <h1 id="comments-title">评论审核</h1>
+      </div>
+      <p class="signal-note">{{ list?.total ?? 0 }} 条记录 · {{ page + 1 }} / {{ pageCount }}</p>
+    </div>
+
+    <form class="filter-bar" @submit.prevent="applyFilters">
+      <label>状态
+        <select v-model="filters.status" aria-label="按状态筛选">
+          <option value="">全部</option>
+          <option value="PENDING">待审核</option>
+          <option value="APPROVED">已通过</option>
+          <option value="SPAM">垃圾</option>
+          <option value="REJECTED">已拒绝</option>
+          <option value="USER_DELETED">用户删除</option>
+        </select>
+      </label>
+      <label>文章
+        <select v-model="filters.articleId" aria-label="按文章筛选">
+          <option value="">全部文章</option>
+          <option v-for="article in articles" :key="article.id" :value="article.id">{{ article.title }}</option>
+        </select>
+      </label>
+      <label class="keyword-field">关键词
+        <input v-model="filters.keyword" maxlength="240" placeholder="昵称或内容" aria-label="按关键词筛选">
+      </label>
+      <label>排序
+        <select v-model="filters.direction" aria-label="时间排序">
+          <option value="desc">最新在前</option>
+          <option value="asc">最早在前</option>
+        </select>
+      </label>
+      <button class="instrument-button" type="submit">重新扫描</button>
+    </form>
+
+    <p v-if="error" class="form-error" role="alert">{{ error }}</p>
+    <p v-if="loading" class="signal-note" role="status">正在读取审核日志…</p>
+    <div v-else class="log-layout">
+      <div class="log-table-wrap">
+        <table class="log-table">
+          <caption class="sr-only">评论审核日志</caption>
+          <thead><tr><th>时间</th><th>状态</th><th>信号</th><th>文章 ID</th><th>邮箱</th><th>操作</th></tr></thead>
+          <tbody>
+            <tr v-for="item in list?.items || []" :key="item.id" :data-active="selected?.id === item.id">
+              <td class="mono">{{ formatDate(item.createdAt) }}</td>
+              <td><span class="status-mark" :data-status="item.status">{{ statusLabel(item.status) }}</span></td>
+              <td><button class="log-link" type="button" @click="select(item.id)">{{ item.nickname }}：{{ item.content }}</button></td>
+              <td class="mono">{{ item.articleId.slice(0, 8) }}</td>
+              <td class="mono">{{ item.emailMasked || '—' }}</td>
+              <td><button class="quiet-button" type="button" @click="select(item.id)">详情</button></td>
+            </tr>
+            <tr v-if="!list?.items.length"><td colspan="6" class="empty-row">没有匹配的审核信号。</td></tr>
+          </tbody>
+        </table>
+      </div>
+
+      <aside v-if="selected" class="detail-panel" aria-labelledby="comment-detail-title">
+        <p class="instrument-label">COMMENT / DETAIL</p>
+        <h2 id="comment-detail-title">{{ selected.nickname }}</h2>
+        <dl class="detail-grid">
+          <div><dt>邮箱</dt><dd>{{ selected.email || '未提供' }}</dd></div>
+          <div><dt>文章</dt><dd class="mono">{{ selected.articleId }}</dd></div>
+          <div><dt>提交</dt><dd>{{ formatDate(selected.createdAt) }}</dd></div>
+          <div><dt>版本</dt><dd class="mono">{{ selected.version }}</dd></div>
+        </dl>
+        <blockquote>{{ selected.content || '（内容已清除）' }}</blockquote>
+        <form class="moderation-form" @submit.prevent="submitModeration">
+          <label for="moderation-status">写入状态</label>
+          <select id="moderation-status" v-model="moderation.status">
+            <option value="APPROVED">通过</option>
+            <option value="SPAM">垃圾</option>
+            <option value="REJECTED">拒绝</option>
+          </select>
+          <label for="moderation-reason">审核理由</label>
+          <textarea id="moderation-reason" v-model="moderation.reason" maxlength="600" rows="4" placeholder="可选；会写入审核记录" />
+          <p v-if="actionError" class="form-error" role="alert">{{ actionError }}</p>
+          <button class="instrument-button" type="submit" :disabled="saving || selected.status === 'USER_DELETED'">
+            {{ saving ? 'WRITING…' : '写入审核结果' }}
+          </button>
+        </form>
+      </aside>
+    </div>
+
+    <nav v-if="pageCount > 1" class="pagination" aria-label="评论分页">
+      <button class="quiet-button" type="button" :disabled="page === 0" @click="goPage(page - 1)">上一页</button>
+      <span class="signal-note">PAGE {{ page + 1 }} / {{ pageCount }}</span>
+      <button class="quiet-button" type="button" :disabled="page + 1 >= pageCount" @click="goPage(page + 1)">下一页</button>
+    </nav>
+  </section>
+</template>
+
+<script setup lang="ts">
+import type { components } from '@haoblog/api-client'
+import { computed, onMounted, reactive, ref } from 'vue'
+import type { CommentDetail, CommentList } from '../../composables/useAdminComments'
+
+definePageMeta({ layout: 'studio' })
+
+const { listComments, getComment, moderateComment } = useAdminComments()
+const { listArticles } = useAdminContent()
+const list = ref<CommentList | null>(null)
+const articles = ref<components['schemas']['AdminArticleSummary'][]>([])
+const selected = ref<CommentDetail | null>(null)
+const loading = ref(true)
+const saving = ref(false)
+const error = ref('')
+const actionError = ref('')
+const page = ref(0)
+const filters = reactive<{ status: components['schemas']['CommentStatus'] | ''; articleId: string; keyword: string; direction: 'asc' | 'desc' }>({ status: '', articleId: '', keyword: '', direction: 'desc' })
+const moderation = reactive<{ status: 'APPROVED' | 'SPAM' | 'REJECTED'; reason: string }>({ status: 'APPROVED', reason: '' })
+const pageCount = computed(() => Math.max(1, Math.ceil((list.value?.total || 0) / (list.value?.size || 20))))
+
+async function load() {
+  loading.value = true
+  error.value = ''
+  try {
+    list.value = await listComments({ page: page.value, size: 20, status: filters.status || undefined, articleId: filters.articleId || undefined, keyword: filters.keyword, direction: filters.direction })
+  } catch (cause) {
+    error.value = cause instanceof Error ? cause.message : '审核日志暂时不可用。'
+  } finally {
+    loading.value = false
+  }
+}
+
+async function select(id: string) {
+  actionError.value = ''
+  try {
+    selected.value = await getComment(id)
+    moderation.status = selected.value.status === 'PENDING' ? 'APPROVED' : (selected.value.status === 'USER_DELETED' ? 'REJECTED' : selected.value.status)
+    moderation.reason = selected.value.moderationReason || ''
+  } catch (cause) {
+    actionError.value = cause instanceof Error ? cause.message : '评论详情暂时不可用。'
+  }
+}
+
+async function submitModeration() {
+  if (!selected.value || saving.value) return
+  saving.value = true
+  actionError.value = ''
+  try {
+    selected.value = await moderateComment(selected.value.id, { version: selected.value.version, status: moderation.status, reason: moderation.reason.trim() || null })
+    await load()
+  } catch (cause) {
+    actionError.value = cause instanceof Error ? cause.message : '审核结果写入失败。'
+  } finally {
+    saving.value = false
+  }
+}
+
+function applyFilters() { page.value = 0; void load() }
+function goPage(next: number) { page.value = next; void load() }
+function formatDate(value: string) { return new Date(value).toLocaleString('zh-CN', { hour12: false }) }
+function statusLabel(value: components['schemas']['CommentStatus']) { return ({ PENDING: '待审', APPROVED: '通过', SPAM: '垃圾', REJECTED: '拒绝', USER_DELETED: '已删' } as Record<string, string>)[value] }
+
+onMounted(async () => {
+  const [articleResult] = await Promise.all([listArticles({ page: 0, size: 50, direction: 'asc' }), load()])
+  articles.value = articleResult.items
+})
+</script>
+
+<style scoped>
+.moderation-scene { max-width: 100rem; margin: 0 auto; }
+.page-heading { display: flex; align-items: end; justify-content: space-between; gap: var(--space-4); margin-bottom: var(--space-6); }
+.page-heading h1 { margin: .8rem 0 0; font-size: clamp(2.2rem, 7vw, 5rem); }
+.filter-bar { display: flex; flex-wrap: wrap; align-items: end; gap: var(--space-3); margin-bottom: var(--space-4); padding: var(--space-3) 0; border-block: 1px solid var(--color-border); }
+.filter-bar label, .moderation-form label { display: grid; gap: .35rem; color: var(--color-accent); font: var(--text-xs)/1.2 var(--font-mono); }
+.filter-bar select, .filter-bar input, .moderation-form select, .moderation-form textarea { min-width: 8rem; padding: .55rem .6rem; border: 1px solid var(--color-border); border-radius: 0; background: var(--color-bg-sub); color: var(--color-text-main); font: var(--text-sm)/1.3 var(--font-body); }
+.keyword-field { flex: 1 1 14rem; }
+.keyword-field input { width: 100%; }
+.log-layout { display: grid; grid-template-columns: minmax(0, 1fr) minmax(18rem, 25rem); gap: var(--space-6); align-items: start; }
+.log-table-wrap { overflow-x: auto; border: 1px solid var(--color-border); }
+.log-table { width: 100%; border-collapse: collapse; font-size: var(--text-sm); }
+.log-table th, .log-table td { padding: .75rem; border-bottom: 1px solid var(--color-border); text-align: left; vertical-align: top; }
+.log-table th { color: var(--color-accent); font: var(--text-xs)/1.2 var(--font-mono); letter-spacing: .06em; white-space: nowrap; }
+.log-table tr[data-active='true'] { background: color-mix(in srgb, var(--color-accent) 8%, transparent); }
+.mono { font-family: var(--font-mono); font-size: var(--text-xs); }
+.log-link { max-width: 26rem; padding: 0; border: 0; background: transparent; color: var(--color-text-main); text-align: left; cursor: pointer; }
+.log-link:hover, .log-link:focus-visible { color: var(--color-accent); }
+.status-mark { color: var(--color-text-muted); font: var(--text-xs)/1 var(--font-mono); white-space: nowrap; }
+.status-mark[data-status='PENDING'] { color: var(--color-warn); }
+.status-mark[data-status='APPROVED'] { color: var(--color-accent); }
+.detail-panel { padding: var(--space-4); border-left: 2px solid var(--color-accent); background: linear-gradient(90deg, color-mix(in srgb, var(--color-accent) 7%, transparent), transparent 80%); }
+.detail-panel h2 { margin: .7rem 0 1rem; font-size: var(--text-lg); }
+.detail-grid { display: grid; gap: .55rem; margin: 0 0 var(--space-4); font: var(--text-xs)/1.4 var(--font-mono); }
+.detail-grid div { display: grid; grid-template-columns: 4rem 1fr; gap: .5rem; }
+.detail-grid dt { color: var(--color-accent); }
+.detail-grid dd { min-width: 0; margin: 0; overflow-wrap: anywhere; color: var(--color-text-muted); }
+blockquote { margin: 0 0 var(--space-4); padding: var(--space-3); border-left: 1px solid var(--color-border); color: var(--color-text-main); white-space: pre-wrap; overflow-wrap: anywhere; }
+.moderation-form { display: grid; gap: .6rem; }
+.moderation-form textarea { resize: vertical; }
+.instrument-button, .quiet-button { width: fit-content; padding: .65rem .8rem; border: 1px solid var(--color-accent); background: transparent; color: var(--color-accent); cursor: pointer; font: var(--text-xs)/1 var(--font-mono); }
+.quiet-button { border-color: var(--color-border); color: var(--color-text-muted); }
+.instrument-button:hover:not(:disabled), .instrument-button:focus-visible, .quiet-button:hover:not(:disabled), .quiet-button:focus-visible { background: var(--color-accent); color: var(--color-accent-ink); }
+button:disabled { cursor: wait; opacity: .55; }
+.pagination { display: flex; justify-content: end; align-items: center; gap: var(--space-3); margin-top: var(--space-4); }
+.empty-row { padding: 2rem !important; color: var(--color-text-muted); text-align: center !important; font-family: var(--font-mono); }
+.form-error { color: var(--color-warn); font: var(--text-sm)/1.5 var(--font-mono); }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; }
+@media (max-width: 800px) { .log-layout { grid-template-columns: 1fr; } .detail-panel { border-top: 2px solid var(--color-accent); border-left: 0; } }
+@media (max-width: 360px) { .page-heading { align-items: start; flex-direction: column; } .filter-bar { display: grid; grid-template-columns: 1fr; } .filter-bar label, .filter-bar select, .filter-bar input { width: 100%; } .log-table th, .log-table td { padding: .55rem; } }
+</style>
diff --git a/apps/web/app/pages/studio/settings.vue b/apps/web/app/pages/studio/settings.vue
new file mode 100644
index 0000000..c9492ec
--- /dev/null
+++ b/apps/web/app/pages/studio/settings.vue
@@ -0,0 +1,80 @@
+<template>
+  <section class="settings-scene" aria-labelledby="settings-title">
+    <p class="instrument-label">STUDIO / SITE CONTROL</p>
+    <h1 id="settings-title">站点开关</h1>
+    <p v-if="loading" class="signal-note" role="status">正在读取站点控制面板…</p>
+    <p v-else-if="error" class="form-error" role="alert">{{ error }}</p>
+    <form v-else-if="site" class="settings-console" @submit.prevent="save">
+      <p class="console-label">GLOBAL / COMMENT SIGNAL</p>
+      <label class="switch-line" for="global-comments-enabled">
+        <input id="global-comments-enabled" v-model="draft" type="checkbox">
+        <span>允许公开评论</span>
+      </label>
+      <p class="signal-note">关闭后，公共文章与评论表单会在下一次请求中反映状态；公共缓存策略最长 60 秒。</p>
+      <p class="signal-note">当前版本：<span class="mono">{{ site.version }}</span></p>
+      <p v-if="saved" class="success-note" role="status">站点开关已写入，公共信号已刷新。</p>
+      <button class="instrument-button" type="submit" :disabled="saving || draft === site.commentsEnabled">
+        {{ saving ? 'WRITING…' : '保存全局开关' }}
+      </button>
+    </form>
+  </section>
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from 'vue'
+import type { Site } from '../../composables/useAdminSite'
+
+definePageMeta({ layout: 'studio' })
+
+const { getSite, updateSite } = useAdminSite()
+const site = ref<Site | null>(null)
+const draft = ref(true)
+const loading = ref(true)
+const saving = ref(false)
+const saved = ref(false)
+const error = ref('')
+
+async function load() {
+  try {
+    site.value = await getSite()
+    draft.value = site.value.commentsEnabled
+  } catch (cause) {
+    error.value = cause instanceof Error ? cause.message : '站点设置暂时不可用。'
+  } finally {
+    loading.value = false
+  }
+}
+
+async function save() {
+  if (!site.value || saving.value || draft.value === site.value.commentsEnabled) return
+  saving.value = true
+  saved.value = false
+  error.value = ''
+  try {
+    site.value = await updateSite({ version: site.value.version, commentsEnabled: draft.value })
+    saved.value = true
+  } catch (cause) {
+    error.value = cause instanceof Error ? cause.message : '站点开关写入失败。'
+  } finally {
+    saving.value = false
+  }
+}
+
+onMounted(load)
+</script>
+
+<style scoped>
+.settings-scene { max-width: 48rem; margin: 10vh auto 0; }
+.settings-scene h1 { margin: .8rem 0; font-size: clamp(2.5rem, 8vw, 6rem); }
+.settings-console { display: grid; gap: var(--space-5); max-width: 34rem; margin-top: var(--space-8); padding: var(--space-5) 0 var(--space-5) var(--space-5); border-left: 2px solid var(--color-accent); background: linear-gradient(90deg, color-mix(in srgb, var(--color-accent) 7%, transparent), transparent 75%); }
+.console-label, .switch-line { color: var(--color-accent); font: var(--text-xs)/1.4 var(--font-mono); letter-spacing: .1em; }
+.switch-line { display: inline-flex; align-items: center; gap: .6rem; width: fit-content; cursor: pointer; }
+.switch-line input { width: 1rem; height: 1rem; accent-color: var(--color-accent); }
+.mono { font-family: var(--font-mono); }
+.instrument-button { width: fit-content; padding: .7rem 1rem; border: 1px solid var(--color-accent); background: transparent; color: var(--color-accent); cursor: pointer; font: var(--text-xs)/1 var(--font-mono); }
+.instrument-button:hover:not(:disabled), .instrument-button:focus-visible { background: var(--color-accent); color: var(--color-accent-ink); }
+.instrument-button:disabled { cursor: not-allowed; opacity: .5; }
+.form-error { color: var(--color-warn); font: var(--text-sm)/1.5 var(--font-mono); }
+.success-note { color: var(--color-accent); font: var(--text-sm)/1.5 var(--font-mono); }
+@media (max-width: 360px) { .settings-console { padding-left: var(--space-3); } }
+</style>
diff --git a/apps/web/app/utils/studioArticleForm.ts b/apps/web/app/utils/studioArticleForm.ts
index 71d2e8b..06d31c5 100644
--- a/apps/web/app/utils/studioArticleForm.ts
+++ b/apps/web/app/utils/studioArticleForm.ts
@@ -15,6 +15,7 @@ export type ArticleFormModel = {
   coverMediaId: string | null
   scheduledAt: string
   markdown: string
+  commentsEnabled: boolean
   version: number | null
 }
 
@@ -48,6 +49,7 @@ export function articleToForm(article?: Article | null): ArticleFormModel {
     coverMediaId: article?.coverMediaId || null,
     scheduledAt: localDateTime(article?.scheduledAt),
     markdown: article?.markdown || '',
+    commentsEnabled: article?.commentsEnabled ?? true,
     version: article?.version ?? null,
   }
 }
@@ -68,6 +70,7 @@ function commonPayload(form: ArticleFormModel) {
     categoryId: form.categoryId || null,
     coverMediaId: form.coverMediaId,
     tagIds: [...form.tagIds],
+    commentsEnabled: form.commentsEnabled,
   }
 }
 
diff --git a/apps/web/test/article-autosave.test.ts b/apps/web/test/article-autosave.test.ts
index 0dc6d26..2cbfc4c 100644
--- a/apps/web/test/article-autosave.test.ts
+++ b/apps/web/test/article-autosave.test.ts
@@ -11,6 +11,7 @@ const article = (version = 1): Article => ({
   id: 'article-1', title: 'Server title', slug: 'server-title', excerpt: null, markdown: '# Server', status: 'DRAFT',
   publishedAt: null, scheduledAt: null, seoTitle: null, seoDescription: null, categoryId: null, coverMediaId: null,
   tagIds: [], createdAt: '2030-01-01T00:00:00Z', updatedAt: '2030-01-01T00:00:00Z', version,
+  commentsEnabled: true,
 })
 
 function storeWith(record: ArticleDraftRecord | null = null) {
@@ -26,6 +27,7 @@ function localRecord(baseVersion = 0): ArticleDraftRecord {
   const form: ArticleFormModel = {
     title: 'Local title', slug: 'local-title', excerpt: '', seoTitle: '', seoDescription: '', categoryId: '', tagIds: [],
     coverMediaId: null, scheduledAt: '', markdown: '# Local', version: baseVersion,
+    commentsEnabled: true,
   }
   return { articleId: 'article-1', form, baseVersion, localUpdatedAt: '2030-01-02T00:00:00.000Z' }
 }
diff --git a/apps/web/test/studio-article-form.test.ts b/apps/web/test/studio-article-form.test.ts
index 880d050..187dee8 100644
--- a/apps/web/test/studio-article-form.test.ts
+++ b/apps/web/test/studio-article-form.test.ts
@@ -4,6 +4,7 @@ import { articleFormSnapshot, articleToForm, formToCreateRequest, formToUpdateRe
 const form: ArticleFormModel = {
   title: '  Studio signal  ', slug: 'studio-signal', excerpt: '摘要', seoTitle: 'SEO', seoDescription: 'SEO 描述',
   categoryId: 'category-1', tagIds: ['tag-2', 'tag-1'], coverMediaId: 'media-1', scheduledAt: '2030-01-02T03:04', markdown: '# Hello', version: 4,
+  commentsEnabled: true,
 }
 
 describe('Studio article form mapping', () => {
@@ -12,6 +13,7 @@ describe('Studio article form mapping', () => {
       id: 'article-1', title: 'Title', slug: 'title', excerpt: null, markdown: '# Body', status: 'DRAFT',
       publishedAt: null, scheduledAt: '2030-01-02T03:04:05Z', seoTitle: null, seoDescription: 'desc', categoryId: 'category-1',
       coverMediaId: 'media-1', tagIds: ['tag-1'], createdAt: '2030-01-01T00:00:00Z', updatedAt: '2030-01-01T00:00:00Z', version: 2,
+      commentsEnabled: true,
     })
     expect(result).toMatchObject({ title: 'Title', excerpt: '', categoryId: 'category-1', coverMediaId: 'media-1', version: 2, markdown: '# Body' })
     expect(result.scheduledAt).toMatch(/^2030-01-02T/)
@@ -21,6 +23,7 @@ describe('Studio article form mapping', () => {
     expect(formToCreateRequest(form)).toEqual({
       title: 'Studio signal', slug: 'studio-signal', excerpt: '摘要', markdown: '# Hello', seoTitle: 'SEO', seoDescription: 'SEO 描述',
       scheduledAt: expect.any(String), categoryId: 'category-1', coverMediaId: 'media-1', tagIds: ['tag-2', 'tag-1'],
+      commentsEnabled: true,
     })
     expect(formToCreateRequest(form).scheduledAt).toMatch(/^2030-01-0[12]T.*\.000Z$/)
     expect(formToUpdateRequest(form).version).toBe(4)
diff --git a/docs/openapi/public-api.yaml b/docs/openapi/public-api.yaml
index df53701..1d55c9d 100644
--- a/docs/openapi/public-api.yaml
+++ b/docs/openapi/public-api.yaml
@@ -280,6 +280,71 @@ paths:
         '401': { $ref: '#/components/responses/Unauthenticated' }
         '403': { $ref: '#/components/responses/CsrfInvalid' }
         '503': { $ref: '#/components/responses/MediaStorageUnavailable' }
+  /api/v1/admin/comments:
+    get:
+      operationId: listAdminComments
+      security: [{ sessionCookie: [] }]
+      parameters:
+        - { name: page, in: query, schema: { type: integer, minimum: 0, default: 0 } }
+        - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 50, default: 20 } }
+        - { name: status, in: query, schema: { $ref: '#/components/schemas/CommentStatus' } }
+        - { name: articleId, in: query, schema: { type: string, format: uuid } }
+        - { name: keyword, in: query, schema: { type: string, maxLength: 240 } }
+        - { name: direction, in: query, schema: { type: string, enum: [asc, desc], default: desc } }
+      responses:
+        '200':
+          description: Administrator comment moderation log; email is masked and security material is omitted
+          content: { application/json: { schema: { $ref: '#/components/schemas/AdminCommentListResponse' } } }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+  /api/v1/admin/comments/{id}:
+    parameters:
+      - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
+    get:
+      operationId: getAdminComment
+      security: [{ sessionCookie: [] }]
+      responses:
+        '200':
+          description: Comment detail with decrypted optional email, content, and moderation audit
+          content: { application/json: { schema: { $ref: '#/components/schemas/AdminCommentDetail' } } }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/ResourceNotFound' }
+  /api/v1/admin/comments/{id}/moderation:
+    parameters:
+      - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
+    post:
+      operationId: moderateAdminComment
+      security: [{ sessionCookie: [] }]
+      parameters: [{ $ref: '#/components/parameters/CsrfHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/CommentModerationRequest' } } } }
+      responses:
+        '200': { description: Moderated comment, content: { application/json: { schema: { $ref: '#/components/schemas/AdminCommentDetail' } } } }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/CsrfInvalid' }
+        '404': { $ref: '#/components/responses/ResourceNotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+  /api/v1/admin/site:
+    get:
+      operationId: getAdminSite
+      security: [{ sessionCookie: [] }]
+      responses:
+        '200': { description: Administrator site settings, content: { application/json: { schema: { $ref: '#/components/schemas/AdminSiteResponse' } } } }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+    put:
+      operationId: updateAdminSite
+      security: [{ sessionCookie: [] }]
+      parameters: [{ $ref: '#/components/parameters/CsrfHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/AdminSiteUpdateRequest' } } } }
+      responses:
+        '200': { description: Site settings updated, content: { application/json: { schema: { $ref: '#/components/schemas/AdminSiteResponse' } } } }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/CsrfInvalid' }
+        '409': { $ref: '#/components/responses/Conflict' }
   /api/v1/admin/media/uploads/{uploadId}/complete:
     post:
       operationId: completeAdminMediaUpload
@@ -867,6 +932,58 @@ components:
         status: { type: string, enum: [PENDING] }
         createdAt: { type: string, format: date-time }
         deleteToken: { type: [string, 'null'], minLength: 43, maxLength: 43 }
+    CommentStatus:
+      type: string
+      enum: [PENDING, APPROVED, SPAM, REJECTED, USER_DELETED]
+    CommentModerationRequest:
+      type: object
+      required: [version, status]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        status: { type: string, enum: [APPROVED, SPAM, REJECTED] }
+        reason: { type: [string, 'null'], maxLength: 600 }
+    AdminCommentSummary:
+      type: object
+      required: [id, articleId, nickname, content, status, createdAt, updatedAt, version]
+      properties:
+        id: { type: string, format: uuid }
+        articleId: { type: string, format: uuid }
+        parentId: { type: [string, 'null'], format: uuid }
+        nickname: { type: string }
+        content: { type: string }
+        emailMasked: { type: [string, 'null'] }
+        status: { $ref: '#/components/schemas/CommentStatus' }
+        moderatorId: { type: [string, 'null'], format: uuid }
+        moderationReason: { type: [string, 'null'] }
+        moderatedAt: { type: [string, 'null'], format: date-time }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+        version: { type: integer, format: int64, minimum: 0 }
+    AdminCommentListResponse:
+      type: object
+      required: [items, page, size, total]
+      properties:
+        items: { type: array, items: { $ref: '#/components/schemas/AdminCommentSummary' } }
+        page: { type: integer }
+        size: { type: integer }
+        total: { type: integer, format: int64 }
+    AdminCommentDetail:
+      type: object
+      required: [id, articleId, nickname, content, email, status, createdAt, updatedAt, version]
+      properties:
+        id: { type: string, format: uuid }
+        articleId: { type: string, format: uuid }
+        parentId: { type: [string, 'null'], format: uuid }
+        nickname: { type: string }
+        content: { type: string }
+        email: { type: [string, 'null'], format: email }
+        status: { $ref: '#/components/schemas/CommentStatus' }
+        moderatorId: { type: [string, 'null'], format: uuid }
+        moderationReason: { type: [string, 'null'] }
+        moderatedAt: { type: [string, 'null'], format: date-time }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+        version: { type: integer, format: int64, minimum: 0 }
     ProblemResponse:
       type: object
       required: [code, title, detail, traceId]
@@ -1009,6 +1126,7 @@ components:
         categoryId: { type: [string, 'null'], format: uuid }
         coverMediaId: { type: [string, 'null'], format: uuid }
         tagIds: { type: array, items: { type: string, format: uuid } }
+        commentsEnabled: { type: boolean, description: Defaults to true when omitted }
     AdminArticleUpdateRequest:
       type: object
       required: [version, title, markdown]
@@ -1024,6 +1142,7 @@ components:
         categoryId: { type: [string, 'null'], format: uuid }
         coverMediaId: { type: [string, 'null'], format: uuid }
         tagIds: { type: array, items: { type: string, format: uuid } }
+        commentsEnabled: { type: boolean, description: Defaults to true when omitted }
     AdminArticleSummary:
       type: object
       required: [id, title, status, categoryId, updatedAt, version, commentsEnabled]
@@ -1065,6 +1184,22 @@ components:
         updatedAt: { type: string, format: date-time }
         version: { type: integer, format: int64, minimum: 0 }
         commentsEnabled: { type: boolean }
+    AdminSiteUpdateRequest:
+      type: object
+      required: [version, commentsEnabled]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        commentsEnabled: { type: boolean }
+    AdminSiteResponse:
+      type: object
+      required: [title, description, siteUrl, authorName, commentsEnabled, version]
+      properties:
+        title: { type: string }
+        description: { type: string }
+        siteUrl: { type: string, format: uri }
+        authorName: { type: string }
+        commentsEnabled: { type: boolean }
+        version: { type: integer, format: int64, minimum: 0 }
     MediaUploadRequest:
       type: object
       required: [mimeType, sizeBytes, width, height, sha256]
diff --git a/packages/api-client/src/generated.ts b/packages/api-client/src/generated.ts
index 0e5a394..675c8c5 100644
--- a/packages/api-client/src/generated.ts
+++ b/packages/api-client/src/generated.ts
@@ -180,6 +180,74 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/admin/comments": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["listAdminComments"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/admin/comments/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        get: operations["getAdminComment"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/admin/comments/{id}/moderation": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["moderateAdminComment"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/admin/site": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getAdminSite"];
+        put: operations["updateAdminSite"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/admin/media/uploads/{uploadId}/complete": {
         parameters: {
             query?: never;
@@ -573,6 +641,69 @@ export interface components {
             createdAt: string;
             deleteToken?: string | null;
         };
+        /** @enum {string} */
+        CommentStatus: "PENDING" | "APPROVED" | "SPAM" | "REJECTED" | "USER_DELETED";
+        CommentModerationRequest: {
+            /** Format: int64 */
+            version: number;
+            /** @enum {string} */
+            status: "APPROVED" | "SPAM" | "REJECTED";
+            reason?: string | null;
+        };
+        AdminCommentSummary: {
+            /** Format: uuid */
+            id: string;
+            /** Format: uuid */
+            articleId: string;
+            /** Format: uuid */
+            parentId?: string | null;
+            nickname: string;
+            content: string;
+            emailMasked?: string | null;
+            status: components["schemas"]["CommentStatus"];
+            /** Format: uuid */
+            moderatorId?: string | null;
+            moderationReason?: string | null;
+            /** Format: date-time */
+            moderatedAt?: string | null;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            updatedAt: string;
+            /** Format: int64 */
+            version: number;
+        };
+        AdminCommentListResponse: {
+            items: components["schemas"]["AdminCommentSummary"][];
+            page: number;
+            size: number;
+            /** Format: int64 */
+            total: number;
+        };
+        AdminCommentDetail: {
+            /** Format: uuid */
+            id: string;
+            /** Format: uuid */
+            articleId: string;
+            /** Format: uuid */
+            parentId?: string | null;
+            nickname: string;
+            content: string;
+            /** Format: email */
+            email: string | null;
+            status: components["schemas"]["CommentStatus"];
+            /** Format: uuid */
+            moderatorId?: string | null;
+            moderationReason?: string | null;
+            /** Format: date-time */
+            moderatedAt?: string | null;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            updatedAt: string;
+            /** Format: int64 */
+            version: number;
+        };
         ProblemResponse: {
             code: string;
             title: string;
@@ -712,6 +843,8 @@ export interface components {
             /** Format: uuid */
             coverMediaId?: string | null;
             tagIds?: string[];
+            /** @description Defaults to true when omitted */
+            commentsEnabled?: boolean;
         };
         AdminArticleUpdateRequest: {
             /** Format: int64 */
@@ -729,6 +862,8 @@ export interface components {
             /** Format: uuid */
             coverMediaId?: string | null;
             tagIds?: string[];
+            /** @description Defaults to true when omitted */
+            commentsEnabled?: boolean;
         };
         AdminArticleSummary: {
             /** Format: uuid */
@@ -778,6 +913,21 @@ export interface components {
             version: number;
             commentsEnabled: boolean;
         };
+        AdminSiteUpdateRequest: {
+            /** Format: int64 */
+            version: number;
+            commentsEnabled: boolean;
+        };
+        AdminSiteResponse: {
+            title: string;
+            description: string;
+            /** Format: uri */
+            siteUrl: string;
+            authorName: string;
+            commentsEnabled: boolean;
+            /** Format: int64 */
+            version: number;
+        };
         MediaUploadRequest: {
             /** @enum {string} */
             mimeType: "image/jpeg" | "image/png" | "image/webp";
@@ -1430,6 +1580,146 @@ export interface operations {
             503: components["responses"]["MediaStorageUnavailable"];
         };
     };
+    listAdminComments: {
+        parameters: {
+            query?: {
+                page?: number;
+                size?: number;
+                status?: components["schemas"]["CommentStatus"];
+                articleId?: string;
+                keyword?: string;
+                direction?: "asc" | "desc";
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Administrator comment moderation log; email is masked and security material is omitted */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdminCommentListResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    getAdminComment: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Comment detail with decrypted optional email, content, and moderation audit */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdminCommentDetail"];
+                };
+            };
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["ResourceNotFound"];
+        };
+    };
+    moderateAdminComment: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-CSRF-TOKEN": components["parameters"]["CsrfHeader"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CommentModerationRequest"];
+            };
+        };
+        responses: {
+            /** @description Moderated comment */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdminCommentDetail"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["CsrfInvalid"];
+            404: components["responses"]["ResourceNotFound"];
+            409: components["responses"]["Conflict"];
+        };
+    };
+    getAdminSite: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Administrator site settings */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdminSiteResponse"];
+                };
+            };
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    updateAdminSite: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-CSRF-TOKEN": components["parameters"]["CsrfHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["AdminSiteUpdateRequest"];
+            };
+        };
+        responses: {
+            /** @description Site settings updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdminSiteResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["CsrfInvalid"];
+            409: components["responses"]["Conflict"];
+        };
+    };
     completeAdminMediaUpload: {
         parameters: {
             query?: never;

From 0c88d3c727a74b605f839e327028043fe31cce20 Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 01:33:18 +0800
Subject: [PATCH 06/15] =?UTF-8?q?=E5=AE=9E=E7=8E=B0=E8=AF=84=E8=AE=BA=20Ou?=
 =?UTF-8?q?tbox=20=E9=82=AE=E4=BB=B6=E9=80=9A=E7=9F=A5=E4=B8=8E=E5=A4=B1?=
 =?UTF-8?q?=E8=B4=A5=E9=9A=94=E7=A6=BB?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .env.example                                  |  10 ++
 apps/api/pom.xml                              |   1 +
 .../CommentNotificationException.java         |   7 +
 .../CommentNotificationMailer.java            |  72 ++++++++
 .../CommentNotificationOutboxProcessor.java   |  58 +++++++
 .../CommentNotificationProperties.java        |  19 +++
 .../application/ArticleCommentLookup.java     |   3 +
 .../content/application/ArticleService.java   |   6 +
 .../ArticleRevisionRepository.java            |  12 ++
 .../io/haoblog/shared/outbox/OutboxEvent.java |  38 +++++
 .../shared/outbox/OutboxEventRepository.java  |  22 ++-
 .../outbox/OutboxEventStateService.java       |  59 +++++++
 apps/api/src/main/resources/application.yml   |  15 ++
 .../db/migration/V13__outbox_claim_index.sql  |   4 +
 .../test/java/io/haoblog/AdminCommentIT.java  |   2 +-
 .../test/java/io/haoblog/ContentModelIT.java  |   4 +-
 .../CommentNotificationMailerTest.java        |  89 ++++++++++
 ...ommentNotificationOutboxProcessorTest.java | 159 ++++++++++++++++++
 ...57\345\212\250\346\214\207\345\215\227.md" |   2 +
 infra/compose/.env.ci.example                 |   3 +
 infra/compose/compose.dev.yml                 |   8 +
 infra/compose/compose.prod.yml                |   8 +
 22 files changed, 597 insertions(+), 4 deletions(-)
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationException.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationMailer.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationOutboxProcessor.java
 create mode 100644 apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationProperties.java
 create mode 100644 apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEventStateService.java
 create mode 100644 apps/api/src/main/resources/db/migration/V13__outbox_claim_index.sql
 create mode 100644 apps/api/src/test/java/io/haoblog/comment/application/CommentNotificationMailerTest.java
 create mode 100644 apps/api/src/test/java/io/haoblog/comment/application/CommentNotificationOutboxProcessorTest.java

diff --git a/.env.example b/.env.example
index 171378a..19d999d 100644
--- a/.env.example
+++ b/.env.example
@@ -20,6 +20,16 @@ HAOBLOG_PUBLIC_BASE_URL=http://localhost:3000
 HAOBLOG_AUTHOR_NAME=Hao
 HAOBLOG_COMMENT_SECURITY_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
 
+# Comment notification is disabled locally. Never put real SMTP credentials in this file.
+HAOBLOG_COMMENT_NOTIFICATION_ENABLED=false
+# HAOBLOG_COMMENT_NOTIFICATION_SMTP_HOST=smtp.example.invalid
+# HAOBLOG_COMMENT_NOTIFICATION_SMTP_PORT=587
+# HAOBLOG_COMMENT_NOTIFICATION_SMTP_USERNAME=replace-with-smtp-username
+# HAOBLOG_COMMENT_NOTIFICATION_SMTP_PASSWORD=replace-with-smtp-password
+# HAOBLOG_COMMENT_NOTIFICATION_SMTP_TLS=true
+# HAOBLOG_COMMENT_NOTIFICATION_RECIPIENT=owner@example.invalid
+# HAOBLOG_COMMENT_NOTIFICATION_FROM=haoblog@example.invalid
+
 # OSS is disabled locally by default. These are server-only values; never put a real key in Git.
 HAOBLOG_OSS_ENABLED=false
 # HAOBLOG_OSS_BUCKET=haoblog-bucket
diff --git a/apps/api/pom.xml b/apps/api/pom.xml
index ca40e68..184b19b 100644
--- a/apps/api/pom.xml
+++ b/apps/api/pom.xml
@@ -31,6 +31,7 @@
     <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-security</artifactId></dependency>
     <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-session-jdbc</artifactId></dependency>
     <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-jpa</artifactId></dependency>
+    <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-mail</artifactId></dependency>
     <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-flyway</artifactId></dependency>
     <dependency><groupId>org.flywaydb</groupId><artifactId>flyway-core</artifactId></dependency>
     <dependency><groupId>org.flywaydb</groupId><artifactId>flyway-database-postgresql</artifactId></dependency>
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationException.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationException.java
new file mode 100644
index 0000000..d8f8d02
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationException.java
@@ -0,0 +1,7 @@
+package io.haoblog.comment.application;
+
+public class CommentNotificationException extends RuntimeException {
+    public CommentNotificationException() {
+        super("Comment notification could not be sent");
+    }
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationMailer.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationMailer.java
new file mode 100644
index 0000000..d2ad7ed
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationMailer.java
@@ -0,0 +1,72 @@
+package io.haoblog.comment.application;
+
+import io.haoblog.comment.domain.Comment;
+import io.haoblog.comment.persistence.CommentRepository;
+import io.haoblog.content.application.ArticleCommentLookup;
+import io.haoblog.site.application.SiteService;
+import org.springframework.mail.SimpleMailMessage;
+import org.springframework.mail.javamail.JavaMailSender;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.UUID;
+
+@Service
+public class CommentNotificationMailer {
+    private static final int SUMMARY_LENGTH = 240;
+
+    private final CommentRepository comments;
+    private final ArticleCommentLookup articles;
+    private final SiteService site;
+    private final CommentNotificationProperties properties;
+    private final JavaMailSender mailSender;
+
+    public CommentNotificationMailer(CommentRepository comments, ArticleCommentLookup articles,
+                                     SiteService site, CommentNotificationProperties properties,
+                                     JavaMailSender mailSender) {
+        this.comments = comments;
+        this.articles = articles;
+        this.site = site;
+        this.properties = properties;
+        this.mailSender = mailSender;
+    }
+
+    @Transactional(readOnly = true)
+    public void send(UUID commentId) {
+        Comment comment = comments.findById(commentId).orElseThrow(CommentNotificationException::new);
+        ArticleCommentLookup.NotificationArticle article = articles
+                .findCommentNotificationArticle(comment.getArticleId())
+                .orElseThrow(CommentNotificationException::new);
+        String recipient = required(properties.getRecipient());
+        String from = required(properties.getFrom());
+        String studioUrl = site.get().siteUrl() + "/studio/comments?commentId=" + commentId;
+
+        SimpleMailMessage message = new SimpleMailMessage();
+        message.setTo(recipient);
+        message.setFrom(from);
+        message.setSubject("HaoBlog 新评论待审核");
+        message.setText("有一条评论待审核\n\n"
+                + "昵称：" + comment.getNickname() + "\n"
+                + "文章：" + article.title() + "\n"
+                + "时间：" + comment.getCreatedAt() + "\n"
+                + "正文摘要：" + summarize(comment.getContent()) + "\n"
+                + "Studio 审核链接：" + studioUrl + "\n");
+        try {
+            mailSender.send(message);
+        } catch (Exception ignored) {
+            throw new CommentNotificationException();
+        }
+    }
+
+    private static String required(String value) {
+        if (value == null || value.isBlank()) throw new CommentNotificationException();
+        return value.trim();
+    }
+
+    private static String summarize(String content) {
+        String normalized = content == null ? "" : content.replaceAll("\\s+", " ").strip();
+        if (normalized.codePointCount(0, normalized.length()) <= SUMMARY_LENGTH) return normalized;
+        int end = normalized.offsetByCodePoints(0, SUMMARY_LENGTH);
+        return normalized.substring(0, end) + "…";
+    }
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationOutboxProcessor.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationOutboxProcessor.java
new file mode 100644
index 0000000..8c42f66
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationOutboxProcessor.java
@@ -0,0 +1,58 @@
+package io.haoblog.comment.application;
+
+import io.haoblog.shared.outbox.OutboxEvent;
+import io.haoblog.shared.outbox.OutboxEventStateService;
+import org.slf4j.MDC;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+import java.util.UUID;
+
+@Component
+public class CommentNotificationOutboxProcessor {
+    private static final Logger LOG = LoggerFactory.getLogger(CommentNotificationOutboxProcessor.class);
+
+    private final OutboxEventStateService state;
+    private final CommentNotificationMailer mailer;
+    private final CommentNotificationProperties properties;
+
+    public CommentNotificationOutboxProcessor(OutboxEventStateService state, CommentNotificationMailer mailer,
+                                              CommentNotificationProperties properties) {
+        this.state = state;
+        this.mailer = mailer;
+        this.properties = properties;
+    }
+
+    @Scheduled(
+            fixedDelayString = "${HAOBLOG_COMMENT_NOTIFICATION_FIXED_DELAY_MS:60000}",
+            initialDelayString = "${HAOBLOG_COMMENT_NOTIFICATION_INITIAL_DELAY_MS:5000}"
+    )
+    public void processDueBatch() {
+        for (OutboxEvent event : state.claimCommentCreatedBatch()) {
+            processOne(event);
+        }
+    }
+
+    private void processOne(OutboxEvent event) {
+        UUID traceId = UUID.randomUUID();
+        try (MDC.MDCCloseable ignored = MDC.putCloseable("traceId", traceId.toString())) {
+            if (properties.isEnabled()) {
+                mailer.send(event.getAggregateId());
+            }
+            state.markProcessed(event.getId());
+            LOG.info("评论通知已处理 eventId={} commentId={} traceId={}",
+                    event.getId(), event.getAggregateId(), traceId);
+        } catch (Exception ignored) {
+            try {
+                state.markFailedOrRetry(event.getId());
+            } catch (Exception stateFailure) {
+                LOG.warn("评论通知状态更新失败 eventId={} commentId={} traceId={}",
+                        event.getId(), event.getAggregateId(), traceId);
+            }
+            LOG.warn("评论通知失败 eventId={} commentId={} traceId={}",
+                    event.getId(), event.getAggregateId(), traceId);
+        }
+    }
+}
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationProperties.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationProperties.java
new file mode 100644
index 0000000..aea3e42
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentNotificationProperties.java
@@ -0,0 +1,19 @@
+package io.haoblog.comment.application;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+@Component
+@ConfigurationProperties(prefix = "haoblog.comment.notification")
+public class CommentNotificationProperties {
+    private boolean enabled;
+    private String recipient = "";
+    private String from = "";
+
+    public boolean isEnabled() { return enabled; }
+    public void setEnabled(boolean enabled) { this.enabled = enabled; }
+    public String getRecipient() { return recipient; }
+    public void setRecipient(String recipient) { this.recipient = recipient; }
+    public String getFrom() { return from; }
+    public void setFrom(String from) { this.from = from; }
+}
diff --git a/apps/api/src/main/java/io/haoblog/content/application/ArticleCommentLookup.java b/apps/api/src/main/java/io/haoblog/content/application/ArticleCommentLookup.java
index 87d4c5d..d79e3fc 100644
--- a/apps/api/src/main/java/io/haoblog/content/application/ArticleCommentLookup.java
+++ b/apps/api/src/main/java/io/haoblog/content/application/ArticleCommentLookup.java
@@ -7,5 +7,8 @@
 public interface ArticleCommentLookup {
     Optional<Target> findPublicCommentTarget(String slug);
 
+    Optional<NotificationArticle> findCommentNotificationArticle(UUID articleId);
+
     record Target(UUID articleId, boolean commentsEnabled) {}
+    record NotificationArticle(String title) {}
 }
diff --git a/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java b/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
index 202597f..5f03e18 100644
--- a/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
+++ b/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
@@ -48,6 +48,12 @@ public Optional<ArticleCommentLookup.Target> findPublicCommentTarget(String slug
                 .map(article -> new ArticleCommentLookup.Target(article.articleId(), article.commentsEnabled()));
     }
 
+    @Override
+    public Optional<ArticleCommentLookup.NotificationArticle> findCommentNotificationArticle(UUID articleId) {
+        return repository.findNotificationArticle(articleId)
+                .map(article -> new ArticleCommentLookup.NotificationArticle(article.getTitle()));
+    }
+
     public PublishedBatch listPublishedBatch(int page, int size) {
         if (page < 0 || size < 1 || size > 500) throw new IllegalArgumentException("page/size out of range");
         var result = repository.findPublished(ArticleStatus.PUBLISHED, java.time.Instant.now(clock), PageRequest.of(page, size));
diff --git a/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java b/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java
index 0c78f3f..56c0a0a 100644
--- a/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java
+++ b/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java
@@ -29,6 +29,14 @@ public interface ArticleRevisionRepository extends JpaRepository<ArticleRevision
 
     Optional<ArticleRevision> findByIdAndArticleId(UUID id, UUID articleId);
 
+    @Query("""
+            select r.title as title
+            from ArticleRevision r, Article a
+            where r.id = a.publishedRevisionId
+              and a.id = :articleId
+            """)
+    Optional<NotificationArticleProjection> findNotificationArticle(@Param("articleId") UUID articleId);
+
     @Query("""
             select r as revision, a.publishedAt as publishedAt, a.commentsEnabled as commentsEnabled
             from ArticleRevision r, Article a
@@ -102,4 +110,8 @@ interface SummaryProjection {
         UUID getCreatedBy();
         java.time.Instant getCreatedAt();
     }
+
+    interface NotificationArticleProjection {
+        String getTitle();
+    }
 }
diff --git a/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEvent.java b/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEvent.java
index 1a6f09e..b838843 100644
--- a/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEvent.java
+++ b/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEvent.java
@@ -53,4 +53,42 @@ public OutboxEvent(UUID aggregateId, String eventType, Map<String, Object> paylo
     public UUID getAggregateId() { return aggregateId; }
     public String getEventType() { return eventType; }
     public Map<String, Object> getPayload() { return payload; }
+    public OutboxStatus getStatus() { return status; }
+    public int getAttemptCount() { return attemptCount; }
+    public Instant getAvailableAt() { return availableAt; }
+    public Instant getProcessedAt() { return processedAt; }
+    public Instant getCreatedAt() { return createdAt; }
+
+    public void claim(Instant now, Instant leaseUntil) {
+        if (status != OutboxStatus.PENDING && status != OutboxStatus.PROCESSING) {
+            throw new IllegalStateException("Only pending outbox events can be claimed");
+        }
+        if (now == null || leaseUntil == null || leaseUntil.isBefore(now)) {
+            throw new IllegalArgumentException("Outbox claim times are invalid");
+        }
+        status = OutboxStatus.PROCESSING;
+        attemptCount++;
+        availableAt = leaseUntil;
+    }
+
+    public void markProcessed(Instant now) {
+        if (status != OutboxStatus.PROCESSING) {
+            throw new IllegalStateException("Only processing outbox events can be processed");
+        }
+        status = OutboxStatus.PROCESSED;
+        processedAt = now;
+    }
+
+    public void retryOrFail(Instant now, Instant nextRetry, int maxAttempts) {
+        if (status != OutboxStatus.PROCESSING) {
+            throw new IllegalStateException("Only processing outbox events can be retried");
+        }
+        if (attemptCount >= maxAttempts) {
+            status = OutboxStatus.FAILED;
+            availableAt = now;
+            return;
+        }
+        status = OutboxStatus.PENDING;
+        availableAt = nextRetry;
+    }
 }
diff --git a/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEventRepository.java b/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEventRepository.java
index c818e9c..32469be 100644
--- a/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEventRepository.java
+++ b/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEventRepository.java
@@ -1,7 +1,27 @@
 package io.haoblog.shared.outbox;
 
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.Lock;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+import jakarta.persistence.LockModeType;
 
+import java.time.Instant;
+import java.util.List;
 import java.util.UUID;
 
-public interface OutboxEventRepository extends JpaRepository<OutboxEvent, UUID> {}
+public interface OutboxEventRepository extends JpaRepository<OutboxEvent, UUID> {
+    @Lock(LockModeType.PESSIMISTIC_WRITE)
+    @Query("""
+            select e from OutboxEvent e
+            where e.eventType = :eventType
+              and e.status in :statuses
+              and e.availableAt <= :now
+            order by e.availableAt asc, e.createdAt asc, e.id asc
+            """)
+    List<OutboxEvent> findAvailable(@Param("eventType") String eventType,
+                                    @Param("statuses") List<OutboxStatus> statuses,
+                                    @Param("now") Instant now,
+                                    Pageable pageable);
+}
diff --git a/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEventStateService.java b/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEventStateService.java
new file mode 100644
index 0000000..e01441d
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/shared/outbox/OutboxEventStateService.java
@@ -0,0 +1,59 @@
+package io.haoblog.shared.outbox;
+
+import org.springframework.data.domain.PageRequest;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.List;
+import java.util.UUID;
+
+@Service
+public class OutboxEventStateService {
+    public static final int MAX_ATTEMPTS = 5;
+    public static final int BATCH_SIZE = 10;
+    private static final Duration PROCESSING_LEASE = Duration.ofSeconds(60);
+
+    private final OutboxEventRepository repository;
+    private final Clock clock;
+
+    public OutboxEventStateService(OutboxEventRepository repository, Clock clock) {
+        this.repository = repository;
+        this.clock = clock;
+    }
+
+    @Transactional
+    public List<OutboxEvent> claimCommentCreatedBatch() {
+        Instant now = clock.instant();
+        List<OutboxEvent> events = repository.findAvailable("COMMENT_CREATED",
+                List.of(OutboxStatus.PENDING, OutboxStatus.PROCESSING), now,
+                PageRequest.of(0, BATCH_SIZE));
+        events.forEach(event -> event.claim(now, now.plus(PROCESSING_LEASE)));
+        return List.copyOf(events);
+    }
+
+    @Transactional
+    public void markProcessed(UUID eventId) {
+        repository.findById(eventId).ifPresent(event -> {
+            if (event.getStatus() == OutboxStatus.PROCESSING) {
+                event.markProcessed(clock.instant());
+            }
+        });
+    }
+
+    @Transactional
+    public void markFailedOrRetry(UUID eventId) {
+        repository.findById(eventId).ifPresent(event -> {
+            if (event.getStatus() != OutboxStatus.PROCESSING) return;
+            Instant now = clock.instant();
+            event.retryOrFail(now, now.plus(retryDelay(event.getAttemptCount())), MAX_ATTEMPTS);
+        });
+    }
+
+    static Duration retryDelay(int attemptCount) {
+        long seconds = Math.min(120L, 10L << Math.max(0, attemptCount - 1));
+        return Duration.ofSeconds(seconds);
+    }
+}
diff --git a/apps/api/src/main/resources/application.yml b/apps/api/src/main/resources/application.yml
index c50669f..4c2db88 100644
--- a/apps/api/src/main/resources/application.yml
+++ b/apps/api/src/main/resources/application.yml
@@ -8,6 +8,17 @@ spring:
     hikari:
       maximum-pool-size: ${DB_POOL_MAXIMUM_SIZE:6}
       minimum-idle: ${DB_POOL_MINIMUM_IDLE:1}
+  mail:
+    host: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_HOST:}
+    port: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_PORT:25}
+    username: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_USERNAME:}
+    password: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_PASSWORD:}
+    properties:
+      mail.smtp.auth: true
+      mail.smtp.starttls.enable: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_TLS:false}
+      mail.smtp.connectiontimeout: 5000
+      mail.smtp.timeout: 3000
+      mail.smtp.writetimeout: 5000
   jpa:
     open-in-view: false
     hibernate:
@@ -76,3 +87,7 @@ haoblog:
       max-dimension: ${HAOBLOG_OSS_MAX_DIMENSION:2560}
   comment:
     security-key: ${HAOBLOG_COMMENT_SECURITY_KEY:}
+    notification:
+      enabled: ${HAOBLOG_COMMENT_NOTIFICATION_ENABLED:false}
+      recipient: ${HAOBLOG_COMMENT_NOTIFICATION_RECIPIENT:}
+      from: ${HAOBLOG_COMMENT_NOTIFICATION_FROM:}
diff --git a/apps/api/src/main/resources/db/migration/V13__outbox_claim_index.sql b/apps/api/src/main/resources/db/migration/V13__outbox_claim_index.sql
new file mode 100644
index 0000000..133e0a0
--- /dev/null
+++ b/apps/api/src/main/resources/db/migration/V13__outbox_claim_index.sql
@@ -0,0 +1,4 @@
+CREATE INDEX outbox_comment_available_idx
+    ON outbox_event (available_at, created_at, id)
+    WHERE event_type = 'COMMENT_CREATED'
+      AND status IN ('PENDING', 'PROCESSING');
diff --git a/apps/api/src/test/java/io/haoblog/AdminCommentIT.java b/apps/api/src/test/java/io/haoblog/AdminCommentIT.java
index f4b3c1e..f09f095 100644
--- a/apps/api/src/test/java/io/haoblog/AdminCommentIT.java
+++ b/apps/api/src/test/java/io/haoblog/AdminCommentIT.java
@@ -66,7 +66,7 @@ static void database(DynamicPropertyRegistry registry) {
     void seed() {
         jdbc.execute("TRUNCATE comment, article_revision, article CASCADE");
         jdbc.update("UPDATE site_setting SET comments_enabled=true, version=0 WHERE site_key='default'");
-        Instant now = Instant.parse("2030-01-01T00:00:00Z");
+        Instant now = Instant.parse("2020-01-01T00:00:00Z");
         Article article = articles.saveAndFlush(new Article("moderation-signal", "Moderation signal", "Excerpt", "# body",
                 ArticleStatus.PUBLISHED, now.minus(1, ChronoUnit.DAYS), now));
         articleId = article.getId();
diff --git a/apps/api/src/test/java/io/haoblog/ContentModelIT.java b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
index cfc63b8..d522420 100644
--- a/apps/api/src/test/java/io/haoblog/ContentModelIT.java
+++ b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
@@ -57,7 +57,7 @@ static void database(DynamicPropertyRegistry registry) {
 
     @Test
     void migratesAllVersionsAndCreatesContentTables() {
-        assertEquals(12, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
+        assertEquals(13, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
         for (String table : List.of("article", "category", "tag", "article_tag", "article_revision",
                 "article_preview_token", "media_asset", "media_upload", "outbox_event", "comment")) {
             assertEquals(1, jdbc.queryForObject(
@@ -82,7 +82,7 @@ void migratesAllVersionsAndCreatesContentTables() {
                     Integer.class, column));
         }
         for (String index : List.of("comment_article_status_created_idx", "comment_parent_created_idx",
-                "comment_article_fingerprint_uq", "outbox_comment_created_uq")) {
+                "comment_article_fingerprint_uq", "outbox_comment_created_uq", "outbox_comment_available_idx")) {
             assertEquals(1, jdbc.queryForObject(
                     "SELECT count(*) FROM pg_indexes WHERE schemaname='public' AND indexname=?", Integer.class, index));
         }
diff --git a/apps/api/src/test/java/io/haoblog/comment/application/CommentNotificationMailerTest.java b/apps/api/src/test/java/io/haoblog/comment/application/CommentNotificationMailerTest.java
new file mode 100644
index 0000000..e9535ad
--- /dev/null
+++ b/apps/api/src/test/java/io/haoblog/comment/application/CommentNotificationMailerTest.java
@@ -0,0 +1,89 @@
+package io.haoblog.comment.application;
+
+import io.haoblog.comment.domain.Comment;
+import io.haoblog.comment.persistence.CommentRepository;
+import io.haoblog.content.application.ArticleCommentLookup;
+import io.haoblog.site.application.SiteService;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.mail.MailSendException;
+import org.springframework.mail.SimpleMailMessage;
+import org.springframework.mail.javamail.JavaMailSender;
+
+import java.time.Instant;
+import java.time.LocalDate;
+import java.util.Optional;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class CommentNotificationMailerTest {
+    private static final UUID COMMENT_ID = UUID.fromString("018f0f1e-7b5c-7000-8000-000000000001");
+    private static final UUID ARTICLE_ID = UUID.fromString("018f0f1e-7b5c-7000-8000-000000000002");
+
+    @Mock CommentRepository comments;
+    @Mock ArticleCommentLookup articles;
+    @Mock SiteService site;
+    @Mock JavaMailSender mailSender;
+
+    @Test
+    void sendsOnlyRequiredCommentSummaryFields() {
+        CommentNotificationProperties properties = properties();
+        Comment comment = comment("Hao", "第一行\n第二行");
+        when(comments.findById(COMMENT_ID)).thenReturn(Optional.of(comment));
+        when(articles.findCommentNotificationArticle(ARTICLE_ID))
+                .thenReturn(Optional.of(new ArticleCommentLookup.NotificationArticle("文章标题")));
+        when(site.get()).thenReturn(new SiteService.SiteResult("HaoBlog", "desc", "https://blog.example.invalid", "Hao"));
+
+        new CommentNotificationMailer(comments, articles, site, properties, mailSender).send(COMMENT_ID);
+
+        ArgumentCaptor<SimpleMailMessage> captor = ArgumentCaptor.forClass(SimpleMailMessage.class);
+        verify(mailSender).send(captor.capture());
+        SimpleMailMessage message = captor.getValue();
+        assertEquals("owner@example.invalid", message.getTo()[0]);
+        assertEquals("notify@example.invalid", message.getFrom());
+        assertFalse(message.getText().contains("email"));
+        assertEquals(true, message.getText().contains("昵称：Hao"));
+        assertEquals(true, message.getText().contains("文章：文章标题"));
+        assertEquals(true, message.getText().contains("Studio 审核链接：https://blog.example.invalid/studio/comments?commentId=" + COMMENT_ID));
+    }
+
+    @Test
+    void hidesMailSenderExceptionDetails() {
+        CommentNotificationProperties properties = properties();
+        when(comments.findById(COMMENT_ID)).thenReturn(Optional.of(comment("Hao", "正文")));
+        when(articles.findCommentNotificationArticle(ARTICLE_ID))
+                .thenReturn(Optional.of(new ArticleCommentLookup.NotificationArticle("文章标题")));
+        when(site.get()).thenReturn(new SiteService.SiteResult("HaoBlog", "desc", "https://blog.example.invalid", "Hao"));
+        doThrow(new MailSendException("SMTP timeout smtp-password owner@example.invalid 正文"))
+                .when(mailSender).send(any(SimpleMailMessage.class));
+
+        CommentNotificationException exception = assertThrows(CommentNotificationException.class,
+                () -> new CommentNotificationMailer(comments, articles, site, properties, mailSender).send(COMMENT_ID));
+
+        assertEquals("Comment notification could not be sent", exception.getMessage());
+    }
+
+    private static CommentNotificationProperties properties() {
+        CommentNotificationProperties properties = new CommentNotificationProperties();
+        properties.setRecipient("owner@example.invalid");
+        properties.setFrom("notify@example.invalid");
+        return properties;
+    }
+
+    private static Comment comment(String nickname, String content) {
+        return new Comment(COMMENT_ID, ARTICLE_ID, null, nickname, null, null, null, content,
+                new byte[32], LocalDate.of(2026, 8, 23), new byte[32], new byte[32],
+                Instant.parse("2026-08-23T00:00:00Z"));
+    }
+}
diff --git a/apps/api/src/test/java/io/haoblog/comment/application/CommentNotificationOutboxProcessorTest.java b/apps/api/src/test/java/io/haoblog/comment/application/CommentNotificationOutboxProcessorTest.java
new file mode 100644
index 0000000..5a3e1fd
--- /dev/null
+++ b/apps/api/src/test/java/io/haoblog/comment/application/CommentNotificationOutboxProcessorTest.java
@@ -0,0 +1,159 @@
+package io.haoblog.comment.application;
+
+import ch.qos.logback.classic.Logger;
+import ch.qos.logback.classic.spi.ILoggingEvent;
+import ch.qos.logback.core.read.ListAppender;
+import io.haoblog.shared.outbox.OutboxEvent;
+import io.haoblog.shared.outbox.OutboxEventRepository;
+import io.haoblog.shared.outbox.OutboxEventStateService;
+import io.haoblog.shared.outbox.OutboxStatus;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.data.domain.Pageable;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class CommentNotificationOutboxProcessorTest {
+    private static final Instant NOW = Instant.parse("2026-08-23T00:00:00Z");
+    private static final Clock CLOCK = Clock.fixed(NOW, ZoneOffset.UTC);
+
+    @Mock OutboxEventRepository repository;
+    @Mock CommentNotificationMailer mailer;
+
+    @Test
+    void successMarksProcessed() {
+        OutboxEvent event = event();
+        when(repository.findAvailable(any(), any(), any(), any())).thenReturn(List.of(event));
+        when(repository.findById(event.getId())).thenReturn(Optional.of(event));
+
+        processor(true).processDueBatch();
+
+        verify(mailer).send(event.getAggregateId());
+        assertEquals(OutboxStatus.PROCESSED, event.getStatus());
+        assertEquals(1, event.getAttemptCount());
+    }
+
+    @Test
+    void smtpFailureIsRetriedAndDoesNotBlockOtherEvents() {
+        OutboxEvent failed = event();
+        OutboxEvent successful = new OutboxEvent(UUID.randomUUID(), "COMMENT_CREATED", payload(), NOW, NOW);
+        when(repository.findAvailable(any(), any(), any(), any())).thenReturn(List.of(failed, successful));
+        when(repository.findById(failed.getId())).thenReturn(Optional.of(failed));
+        when(repository.findById(successful.getId())).thenReturn(Optional.of(successful));
+        doThrow(new CommentNotificationException()).when(mailer).send(failed.getAggregateId());
+
+        processor(true).processDueBatch();
+
+        verify(mailer).send(failed.getAggregateId());
+        verify(mailer).send(successful.getAggregateId());
+        assertEquals(OutboxStatus.PENDING, failed.getStatus());
+        assertEquals(OutboxStatus.PROCESSED, successful.getStatus());
+    }
+
+    @Test
+    void fifthFailureIsTerminal() {
+        OutboxEvent event = event();
+        when(repository.findAvailable(any(), any(), any(), any())).thenReturn(List.of(event));
+        when(repository.findById(event.getId())).thenReturn(Optional.of(event));
+        doThrow(new CommentNotificationException()).when(mailer).send(event.getAggregateId());
+
+        for (int attempt = 0; attempt < OutboxEventStateService.MAX_ATTEMPTS; attempt++) {
+            processor(true).processDueBatch();
+        }
+
+        verify(mailer, times(OutboxEventStateService.MAX_ATTEMPTS)).send(event.getAggregateId());
+        assertEquals(OutboxStatus.FAILED, event.getStatus());
+        assertEquals(OutboxEventStateService.MAX_ATTEMPTS, event.getAttemptCount());
+    }
+
+    @Test
+    void disabledNotificationDrainsWithoutSending() {
+        OutboxEvent event = event();
+        when(repository.findAvailable(any(), any(), any(), any())).thenReturn(List.of(event));
+        when(repository.findById(event.getId())).thenReturn(Optional.of(event));
+
+        processor(false).processDueBatch();
+
+        verify(mailer, never()).send(event.getAggregateId());
+        assertEquals(OutboxStatus.PROCESSED, event.getStatus());
+    }
+
+    @Test
+    void processedEventsAreNotClaimedAgain() {
+        when(repository.findAvailable(any(), any(), any(), any())).thenReturn(List.of());
+
+        processor(true).processDueBatch();
+
+        verify(mailer, never()).send(any());
+    }
+
+    @Test
+    void claimsOnlyACommentBatchOfTen() {
+        when(repository.findAvailable(any(), any(), any(), any())).thenReturn(List.of());
+
+        processor(true).processDueBatch();
+
+        var captor = org.mockito.ArgumentCaptor.forClass(Pageable.class);
+        verify(repository).findAvailable(org.mockito.ArgumentMatchers.eq("COMMENT_CREATED"), any(), any(), captor.capture());
+        assertEquals(10, captor.getValue().getPageSize());
+    }
+
+    @Test
+    void failureLogsDoNotContainSensitiveExceptionDetails() {
+        OutboxEvent event = event();
+        when(repository.findAvailable(any(), any(), any(), any())).thenReturn(List.of(event));
+        when(repository.findById(event.getId())).thenReturn(Optional.of(event));
+        doThrow(new IllegalStateException("smtp-password owner@example.invalid comment body"))
+                .when(mailer).send(event.getAggregateId());
+
+        Logger logger = (Logger) org.slf4j.LoggerFactory.getLogger(CommentNotificationOutboxProcessor.class);
+        ListAppender<ILoggingEvent> appender = new ListAppender<>();
+        appender.start();
+        logger.addAppender(appender);
+        try {
+            processor(true).processDueBatch();
+        } finally {
+            logger.detachAppender(appender);
+            appender.stop();
+        }
+
+        String logs = appender.list.stream().map(ILoggingEvent::getFormattedMessage).reduce("", (a, b) -> a + b);
+        assertFalse(logs.contains("smtp-password"));
+        assertFalse(logs.contains("owner@example.invalid"));
+        assertFalse(logs.contains("comment body"));
+    }
+
+    private CommentNotificationOutboxProcessor processor(boolean enabled) {
+        CommentNotificationProperties properties = new CommentNotificationProperties();
+        properties.setEnabled(enabled);
+        return new CommentNotificationOutboxProcessor(
+                new OutboxEventStateService(repository, CLOCK), mailer, properties);
+    }
+
+    private static OutboxEvent event() {
+        return new OutboxEvent(UUID.randomUUID(), "COMMENT_CREATED", payload(), NOW, NOW);
+    }
+
+    private static Map<String, Object> payload() {
+        return Map.of("commentId", UUID.randomUUID().toString(), "articleId", UUID.randomUUID().toString(),
+                "eventType", "COMMENT_CREATED", "occurredAt", NOW.toString());
+    }
+}
diff --git "a/docs/\346\234\254\345\234\260\345\220\257\345\212\250\346\214\207\345\215\227.md" "b/docs/\346\234\254\345\234\260\345\220\257\345\212\250\346\214\207\345\215\227.md"
index 2d736f5..063610c 100644
--- "a/docs/\346\234\254\345\234\260\345\220\257\345\212\250\346\214\207\345\215\227.md"
+++ "b/docs/\346\234\254\345\234\260\345\220\257\345\212\250\346\214\207\345\215\227.md"
@@ -88,6 +88,8 @@ HAOBLOG_ADMIN_PASSWORD_HASH=BCrypt 哈希
 
 不要把 `.env` 提交到 Git，也不要把真实密码、OSS AccessKey 或生产连接信息写入 `.env.example`。
 
+评论通知默认关闭。需要本地联调时，只在未提交的 `.env` 中设置 `HAOBLOG_COMMENT_NOTIFICATION_ENABLED=true`，并提供 SMTP 主机、端口、用户名、密码、TLS、站长接收地址和发件地址；仓库示例只使用占位值。API 会使用 5 秒连接、3 秒读取、5 秒写入超时。通知发送失败只进入 Outbox 重试，不会回滚评论提交或审核。
+
 ### 2.2 安装 Web 依赖
 
 ```powershell
diff --git a/infra/compose/.env.ci.example b/infra/compose/.env.ci.example
index 101007e..d82375a 100644
--- a/infra/compose/.env.ci.example
+++ b/infra/compose/.env.ci.example
@@ -12,6 +12,9 @@ HAOBLOG_ADMIN_PASSWORD_HASH='$2a$10$0V.Xs7CLOUYSekm7RKq3Z.iY76KUan/Xbeu5vjmLpX.s
 HAOBLOG_PUBLIC_BASE_URL=http://localhost:3000
 HAOBLOG_AUTHOR_NAME=Hao
 HAOBLOG_COMMENT_SECURITY_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+HAOBLOG_COMMENT_NOTIFICATION_ENABLED=false
+HAOBLOG_COMMENT_NOTIFICATION_SMTP_PORT=25
+HAOBLOG_COMMENT_NOTIFICATION_SMTP_TLS=false
 SPRING_PROFILES_ACTIVE=dev
 HAOBLOG_SEED_ENABLED=true
 HAOBLOG_CONTENT_SCHEDULING_FIXED_DELAY_MS=1000
diff --git a/infra/compose/compose.dev.yml b/infra/compose/compose.dev.yml
index a4d54b4..a5d0ef2 100644
--- a/infra/compose/compose.dev.yml
+++ b/infra/compose/compose.dev.yml
@@ -31,6 +31,14 @@ services:
       HAOBLOG_ADMIN_PASSWORD_HASH: ${HAOBLOG_ADMIN_PASSWORD_HASH:?HAOBLOG_ADMIN_PASSWORD_HASH is required}
       HAOBLOG_PUBLIC_BASE_URL: ${HAOBLOG_PUBLIC_BASE_URL:-http://localhost:3000}
       HAOBLOG_AUTHOR_NAME: ${HAOBLOG_AUTHOR_NAME:-Hao}
+      HAOBLOG_COMMENT_NOTIFICATION_ENABLED: ${HAOBLOG_COMMENT_NOTIFICATION_ENABLED:-false}
+      HAOBLOG_COMMENT_NOTIFICATION_SMTP_HOST: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_HOST:-}
+      HAOBLOG_COMMENT_NOTIFICATION_SMTP_PORT: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_PORT:-25}
+      HAOBLOG_COMMENT_NOTIFICATION_SMTP_USERNAME: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_USERNAME:-}
+      HAOBLOG_COMMENT_NOTIFICATION_SMTP_PASSWORD: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_PASSWORD:-}
+      HAOBLOG_COMMENT_NOTIFICATION_SMTP_TLS: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_TLS:-false}
+      HAOBLOG_COMMENT_NOTIFICATION_RECIPIENT: ${HAOBLOG_COMMENT_NOTIFICATION_RECIPIENT:-}
+      HAOBLOG_COMMENT_NOTIFICATION_FROM: ${HAOBLOG_COMMENT_NOTIFICATION_FROM:-}
       JDBC_DATABASE_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB:?POSTGRES_DB is required}
       JDBC_DATABASE_USERNAME: ${POSTGRES_USER:?POSTGRES_USER is required}
       JDBC_DATABASE_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
diff --git a/infra/compose/compose.prod.yml b/infra/compose/compose.prod.yml
index 11cca62..1cd22c2 100644
--- a/infra/compose/compose.prod.yml
+++ b/infra/compose/compose.prod.yml
@@ -61,6 +61,14 @@ services:
       HAOBLOG_PUBLIC_BASE_URL: ${HAOBLOG_PUBLIC_BASE_URL:?HAOBLOG_PUBLIC_BASE_URL is required}
       HAOBLOG_AUTHOR_NAME: ${HAOBLOG_AUTHOR_NAME:-Hao}
       HAOBLOG_COMMENT_SECURITY_KEY: ${HAOBLOG_COMMENT_SECURITY_KEY:?HAOBLOG_COMMENT_SECURITY_KEY is required}
+      HAOBLOG_COMMENT_NOTIFICATION_ENABLED: ${HAOBLOG_COMMENT_NOTIFICATION_ENABLED:-false}
+      HAOBLOG_COMMENT_NOTIFICATION_SMTP_HOST: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_HOST:-}
+      HAOBLOG_COMMENT_NOTIFICATION_SMTP_PORT: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_PORT:-25}
+      HAOBLOG_COMMENT_NOTIFICATION_SMTP_USERNAME: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_USERNAME:-}
+      HAOBLOG_COMMENT_NOTIFICATION_SMTP_PASSWORD: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_PASSWORD:-}
+      HAOBLOG_COMMENT_NOTIFICATION_SMTP_TLS: ${HAOBLOG_COMMENT_NOTIFICATION_SMTP_TLS:-false}
+      HAOBLOG_COMMENT_NOTIFICATION_RECIPIENT: ${HAOBLOG_COMMENT_NOTIFICATION_RECIPIENT:-}
+      HAOBLOG_COMMENT_NOTIFICATION_FROM: ${HAOBLOG_COMMENT_NOTIFICATION_FROM:-}
       JDBC_DATABASE_URL: jdbc:postgresql://postgres-pgvector:5432/${POSTGRES_DB:?POSTGRES_DB is required}
       JDBC_DATABASE_USERNAME: ${POSTGRES_USER:?POSTGRES_USER is required}
       JDBC_DATABASE_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}

From 6b2c7deb3693245b1fe19e15a1f6ffb8aa8fff03 Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 13:42:51 +0800
Subject: [PATCH 07/15] =?UTF-8?q?=E5=AE=8C=E6=88=90=E5=B7=A5=E5=85=B7?=
 =?UTF-8?q?=E9=A2=86=E5=9F=9F=E4=B8=8E=20Studio=20=E7=AE=A1=E7=90=86?=
 =?UTF-8?q?=E9=97=AD=E7=8E=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../application/AdminContentService.java      |   2 +-
 .../application/ToolManagementService.java    | 167 +++++++
 .../java/io/haoblog/toolbox/domain/Tool.java  | 150 +++++++
 .../haoblog/toolbox/domain/ToolCategory.java  |  61 +++
 .../toolbox/domain/ToolComponentKey.java      |  17 +
 .../domain/ToolComponentKeyConverter.java     |  17 +
 .../io/haoblog/toolbox/domain/ToolSlug.java   |  20 +
 .../io/haoblog/toolbox/domain/ToolStatus.java |   5 +
 .../io/haoblog/toolbox/domain/ToolType.java   |   5 +
 .../java/io/haoblog/toolbox/package-info.java |   2 +-
 .../persistence/ToolCategoryRepository.java   |  15 +
 .../toolbox/persistence/ToolRepository.java   |  13 +
 .../web/AdminToolCategoryController.java      |  77 ++++
 .../toolbox/web/AdminToolController.java      | 104 +++++
 .../migration/V14__toolbox_domain_model.sql   |  44 ++
 .../test/java/io/haoblog/ContentModelIT.java  |   2 +-
 .../src/test/java/io/haoblog/ToolAdminIT.java | 128 ++++++
 .../toolbox/domain/ToolDomainTest.java        |  30 ++
 apps/web/app/composables/useAdminTools.ts     |  49 ++
 apps/web/app/layouts/studio.vue               |   1 +
 apps/web/app/pages/studio/tools.vue           | 114 +++++
 apps/web/app/utils/studioToolForm.ts          |  77 ++++
 apps/web/server/routes/api/[...path].ts       |   6 +
 apps/web/test/studio-tool-form.test.ts        |  19 +
 docs/openapi/public-api.yaml                  | 191 ++++++++
 packages/api-client/src/generated.ts          | 420 ++++++++++++++++++
 26 files changed, 1733 insertions(+), 3 deletions(-)
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/application/ToolManagementService.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/domain/Tool.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/domain/ToolCategory.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/domain/ToolComponentKey.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/domain/ToolComponentKeyConverter.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/domain/ToolSlug.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/domain/ToolStatus.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/domain/ToolType.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolCategoryRepository.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolRepository.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/web/AdminToolCategoryController.java
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/web/AdminToolController.java
 create mode 100644 apps/api/src/main/resources/db/migration/V14__toolbox_domain_model.sql
 create mode 100644 apps/api/src/test/java/io/haoblog/ToolAdminIT.java
 create mode 100644 apps/api/src/test/java/io/haoblog/toolbox/domain/ToolDomainTest.java
 create mode 100644 apps/web/app/composables/useAdminTools.ts
 create mode 100644 apps/web/app/pages/studio/tools.vue
 create mode 100644 apps/web/app/utils/studioToolForm.ts
 create mode 100644 apps/web/server/routes/api/[...path].ts
 create mode 100644 apps/web/test/studio-tool-form.test.ts

diff --git a/apps/api/src/main/java/io/haoblog/content/application/AdminContentService.java b/apps/api/src/main/java/io/haoblog/content/application/AdminContentService.java
index f2408db..ad808f5 100644
--- a/apps/api/src/main/java/io/haoblog/content/application/AdminContentService.java
+++ b/apps/api/src/main/java/io/haoblog/content/application/AdminContentService.java
@@ -153,7 +153,7 @@ public Article updateArticle(UUID id, long version, String slug, String title, S
             throw new ProblemException("ARTICLE_VERSION_CONFLICT", "Article version conflict",
                     "Reload the latest article before saving", article.getVersion());
         }
-        String resolvedSlug = Slug.normalizeNullable(slug);
+        String resolvedSlug = slug == null ? article.getSlug() : Slug.normalizeNullable(slug);
         if (resolvedSlug != null && articles.existsBySlugAndIdNot(resolvedSlug, id)) {
             throw conflict("ARTICLE_SLUG_CONFLICT", "Article slug conflict", "The article slug is already in use");
         }
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/application/ToolManagementService.java b/apps/api/src/main/java/io/haoblog/toolbox/application/ToolManagementService.java
new file mode 100644
index 0000000..cc4f0fe
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/application/ToolManagementService.java
@@ -0,0 +1,167 @@
+package io.haoblog.toolbox.application;
+
+import io.haoblog.shared.web.ProblemException;
+import io.haoblog.toolbox.domain.Tool;
+import io.haoblog.toolbox.domain.ToolCategory;
+import io.haoblog.toolbox.domain.ToolComponentKey;
+import io.haoblog.toolbox.domain.ToolStatus;
+import io.haoblog.toolbox.domain.ToolType;
+import io.haoblog.toolbox.persistence.ToolCategoryRepository;
+import io.haoblog.toolbox.persistence.ToolRepository;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Sort;
+import org.springframework.data.jpa.domain.Specification;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.util.List;
+import java.util.UUID;
+
+@Service
+public class ToolManagementService {
+    private final ToolCategoryRepository categories;
+    private final ToolRepository tools;
+    private final Clock clock;
+
+    public ToolManagementService(ToolCategoryRepository categories, ToolRepository tools, Clock clock) {
+        this.categories = categories;
+        this.tools = tools;
+        this.clock = clock;
+    }
+
+    @Transactional(readOnly = true)
+    public List<ToolCategory> listCategories() { return categories.findAllByOrderBySortOrderAscNameAsc(); }
+
+    @Transactional
+    public ToolCategory createCategory(String name, String slug, String description, int sortOrder) {
+        validateCategory(name, slug, description);
+        String normalizedSlug = normalizeSlug(slug);
+        if (categories.existsByNameIgnoreCase(name.trim()) || categories.existsBySlug(normalizedSlug)) {
+            throw conflict("TOOL_CATEGORY_CONFLICT", "Tool category conflict", "The tool category name or slug is already in use");
+        }
+        return categories.saveAndFlush(new ToolCategory(name, normalizedSlug, description, sortOrder, Instant.now(clock)));
+    }
+
+    @Transactional(readOnly = true)
+    public ToolCategory getCategory(UUID id) { return categories.findById(id).orElseThrow(() -> notFound("TOOL_CATEGORY_NOT_FOUND")); }
+
+    @Transactional
+    public ToolCategory updateCategory(UUID id, long version, String name, String slug, String description, int sortOrder) {
+        ToolCategory category = getCategory(id);
+        requireVersion(category.getVersion(), version, "TOOL_CATEGORY_VERSION_CONFLICT", "Reload the latest tool category before saving");
+        validateCategory(name, slug, description);
+        String normalizedSlug = normalizeSlug(slug);
+        if (categories.existsByNameIgnoreCaseAndIdNot(name.trim(), id) || categories.existsBySlugAndIdNot(normalizedSlug, id)) {
+            throw conflict("TOOL_CATEGORY_CONFLICT", "Tool category conflict", "The tool category name or slug is already in use");
+        }
+        category.update(name, normalizedSlug, description, sortOrder, Instant.now(clock));
+        return categories.saveAndFlush(category);
+    }
+
+    @Transactional
+    public void deleteCategory(UUID id, long version) {
+        ToolCategory category = getCategory(id);
+        requireVersion(category.getVersion(), version, "TOOL_CATEGORY_VERSION_CONFLICT", "Reload the latest tool category before deleting");
+        if (tools.existsByCategoryId(id)) {
+            throw conflict("TOOL_CATEGORY_IN_USE", "Tool category in use", "The category is referenced by a tool");
+        }
+        categories.delete(category);
+        categories.flush();
+    }
+
+    @Transactional(readOnly = true)
+    public Page<Tool> listTools(int page, int size, UUID categoryId, ToolType type, ToolStatus status,
+                                String keyword, String sort, Sort.Direction direction) {
+        if (page < 0 || size < 1 || size > 50) throw new IllegalArgumentException("page/size out of range");
+        if (keyword != null && keyword.length() > 240) throw new IllegalArgumentException("keyword is too long");
+        String value = keyword == null || keyword.isBlank() ? null : escapeLike(keyword.trim());
+        Specification<Tool> specification = (root, query, cb) -> cb.conjunction();
+        if (categoryId != null) specification = specification.and((root, query, cb) -> cb.equal(root.get("categoryId"), categoryId));
+        if (type != null) specification = specification.and((root, query, cb) -> cb.equal(root.get("type"), type));
+        if (status != null) specification = specification.and((root, query, cb) -> cb.equal(root.get("status"), status));
+        if (value != null) {
+            String pattern = "%" + value.toLowerCase() + "%";
+            specification = specification.and((root, query, cb) -> cb.or(
+                    cb.like(cb.lower(root.get("title")), pattern, '!'),
+                    cb.like(cb.lower(root.get("slug")), pattern, '!'),
+                    cb.like(cb.lower(root.get("description")), pattern, '!')));
+        }
+        Sort safeSort = Sort.by(direction, allowedSort(sort)).and(Sort.by(direction, "id"));
+        return tools.findAll(specification, PageRequest.of(page, size, safeSort));
+    }
+
+    @Transactional(readOnly = true)
+    public Tool getTool(UUID id) { return tools.findById(id).orElseThrow(() -> notFound("TOOL_NOT_FOUND")); }
+
+    @Transactional
+    public Tool createTool(UUID categoryId, ToolType type, ToolStatus status, String title, String slug,
+                           String description, String url, String imageUrl, ToolComponentKey componentKey,
+                           List<String> tags, int sortOrder) {
+        requireCategory(categoryId);
+        validateTool(title, slug, description);
+        String normalizedSlug = normalizeSlug(slug);
+        if (tools.existsBySlug(normalizedSlug)) throw conflict("TOOL_CONFLICT", "Tool conflict", "The tool slug is already in use");
+        return tools.saveAndFlush(new Tool(categoryId, type, status, title, normalizedSlug, description, url, imageUrl,
+                componentKey, tags, sortOrder, Instant.now(clock)));
+    }
+
+    @Transactional
+    public Tool updateTool(UUID id, long version, UUID categoryId, ToolType type, ToolStatus status, String title, String slug,
+                           String description, String url, String imageUrl, ToolComponentKey componentKey,
+                           List<String> tags, int sortOrder) {
+        Tool tool = getTool(id);
+        requireVersion(tool.getVersion(), version, "TOOL_VERSION_CONFLICT", "Reload the latest tool before saving");
+        requireCategory(categoryId);
+        validateTool(title, slug, description);
+        String normalizedSlug = normalizeSlug(slug);
+        if (tools.existsBySlugAndIdNot(normalizedSlug, id)) throw conflict("TOOL_CONFLICT", "Tool conflict", "The tool slug is already in use");
+        tool.update(categoryId, type, status, title, normalizedSlug, description, url, imageUrl, componentKey,
+                tags, sortOrder, Instant.now(clock));
+        return tools.saveAndFlush(tool);
+    }
+
+    @Transactional
+    public void deleteTool(UUID id, long version) {
+        Tool tool = getTool(id);
+        requireVersion(tool.getVersion(), version, "TOOL_VERSION_CONFLICT", "Reload the latest tool before deleting");
+        tools.delete(tool);
+        tools.flush();
+    }
+
+    public long currentCategoryVersion(UUID id) { return getCategory(id).getVersion(); }
+    public long currentToolVersion(UUID id) { return getTool(id).getVersion(); }
+
+    private void requireCategory(UUID id) {
+        if (id == null || !categories.existsById(id)) throw notFound("TOOL_CATEGORY_NOT_FOUND");
+    }
+
+    private static void validateCategory(String name, String slug, String description) {
+        if (name == null || name.isBlank() || name.trim().length() > 120) throw new IllegalArgumentException("name is invalid");
+        if (description != null && description.length() > 600) throw new IllegalArgumentException("description is too long");
+        normalizeSlug(slug);
+    }
+
+    private static void validateTool(String title, String slug, String description) {
+        if (title == null || title.isBlank() || title.trim().length() > 160) throw new IllegalArgumentException("title is invalid");
+        if (description != null && description.length() > 600) throw new IllegalArgumentException("description is too long");
+        normalizeSlug(slug);
+    }
+
+    private static void requireVersion(long current, long requested, String code, String detail) {
+        if (current != requested) throw new ProblemException(code, "Version conflict", detail, current);
+    }
+
+    private static String escapeLike(String value) { return value.replace("!", "!!").replace("%", "!%").replace("_", "!_"); }
+    private static String normalizeSlug(String value) { return io.haoblog.toolbox.domain.ToolSlug.normalizeRequired(value); }
+    private static String allowedSort(String sort) {
+        return switch (sort == null || sort.isBlank() ? "sortOrder" : sort) {
+            case "sortOrder", "createdAt", "updatedAt", "title" -> sort == null || sort.isBlank() ? "sortOrder" : sort;
+            default -> throw new IllegalArgumentException("sort must be sortOrder, createdAt, updatedAt or title");
+        };
+    }
+    private static ProblemException notFound(String code) { return new ProblemException(code, "Resource not found", "The requested toolbox resource was not found"); }
+    private static ProblemException conflict(String code, String title, String detail) { return new ProblemException(code, title, detail); }
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/domain/Tool.java b/apps/api/src/main/java/io/haoblog/toolbox/domain/Tool.java
new file mode 100644
index 0000000..6dd59da
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/domain/Tool.java
@@ -0,0 +1,150 @@
+package io.haoblog.toolbox.domain;
+
+import io.haoblog.shared.id.UuidV7;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.Convert;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import jakarta.persistence.Version;
+import org.hibernate.annotations.JdbcTypeCode;
+import org.hibernate.type.SqlTypes;
+
+import java.net.URI;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+@Entity
+@Table(name = "tool")
+public class Tool {
+    @Id
+    private UUID id = UuidV7.generate();
+    @Column(name = "category_id", nullable = false)
+    private UUID categoryId;
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false, length = 16)
+    private ToolType type;
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false, length = 16)
+    private ToolStatus status;
+    @Column(nullable = false, length = 160)
+    private String title;
+    @Column(nullable = false, unique = true, length = 160)
+    private String slug;
+    @Column(length = 600)
+    private String description;
+    @Column(length = 2048)
+    private String url;
+    @Column(name = "image_url", length = 2048)
+    private String imageUrl;
+    @Convert(converter = ToolComponentKeyConverter.class)
+    @Column(name = "component_key", length = 32)
+    private ToolComponentKey componentKey;
+    @JdbcTypeCode(SqlTypes.JSON)
+    @Column(nullable = false, columnDefinition = "jsonb")
+    private List<String> tags = new ArrayList<>();
+    @Column(name = "sort_order", nullable = false)
+    private int sortOrder;
+    @Version
+    @Column(nullable = false)
+    private long version;
+    @Column(name = "created_at", nullable = false)
+    private Instant createdAt;
+    @Column(name = "updated_at", nullable = false)
+    private Instant updatedAt;
+
+    protected Tool() {}
+
+    public Tool(UUID categoryId, ToolType type, ToolStatus status, String title, String slug,
+                String description, String url, String imageUrl, ToolComponentKey componentKey,
+                List<String> tags, int sortOrder, Instant now) {
+        this.categoryId = require(categoryId, "categoryId");
+        this.type = require(type, "type");
+        this.status = require(status, "status");
+        this.title = title.trim();
+        this.slug = ToolSlug.normalizeRequired(slug);
+        this.description = description;
+        this.url = httpsOrNull(url);
+        this.imageUrl = httpsOrNull(imageUrl);
+        this.componentKey = componentKey;
+        this.tags = copyTags(tags);
+        this.sortOrder = sortOrder;
+        validateFields(this.type, this.url, this.componentKey);
+        this.createdAt = now;
+        this.updatedAt = now;
+    }
+
+    public void update(UUID categoryId, ToolType type, ToolStatus status, String title, String slug,
+                       String description, String url, String imageUrl, ToolComponentKey componentKey,
+                       List<String> tags, int sortOrder, Instant now) {
+        this.categoryId = require(categoryId, "categoryId");
+        this.type = require(type, "type");
+        this.status = require(status, "status");
+        this.title = title.trim();
+        this.slug = ToolSlug.normalizeRequired(slug);
+        this.description = description;
+        this.url = httpsOrNull(url);
+        this.imageUrl = httpsOrNull(imageUrl);
+        this.componentKey = componentKey;
+        this.tags = copyTags(tags);
+        this.sortOrder = sortOrder;
+        validateFields(this.type, this.url, this.componentKey);
+        this.updatedAt = now;
+    }
+
+    private static void validateFields(ToolType type, String url, ToolComponentKey componentKey) {
+        if (type == ToolType.EMBEDDED && (url != null || componentKey == null)) {
+            throw new IllegalArgumentException("Embedded tools require a whitelisted componentKey and no url");
+        }
+        if (type != ToolType.EMBEDDED && (url == null || componentKey != null)) {
+            throw new IllegalArgumentException("Link and showcase tools require an https url and no componentKey");
+        }
+    }
+
+    private static String httpsOrNull(String raw) {
+        if (raw == null || raw.isBlank()) return null;
+        String value = raw.trim();
+        try {
+            URI uri = URI.create(value);
+            if (!"https".equalsIgnoreCase(uri.getScheme()) || uri.getHost() == null || uri.getUserInfo() != null) {
+                throw new IllegalArgumentException("Only absolute https URLs are allowed");
+            }
+        } catch (IllegalArgumentException exception) {
+            throw new IllegalArgumentException("Only absolute https URLs are allowed", exception);
+        }
+        return value;
+    }
+
+    private static List<String> copyTags(List<String> values) {
+        if (values == null) return new ArrayList<>();
+        if (values.size() > 32 || values.stream().anyMatch(value -> value == null || value.isBlank() || value.trim().length() > 64)) {
+            throw new IllegalArgumentException("tags are invalid");
+        }
+        return values.stream().map(String::trim).distinct().toList();
+    }
+
+    private static <T> T require(T value, String name) {
+        if (value == null) throw new IllegalArgumentException(name + " is required");
+        return value;
+    }
+
+    public UUID getId() { return id; }
+    public UUID getCategoryId() { return categoryId; }
+    public ToolType getType() { return type; }
+    public ToolStatus getStatus() { return status; }
+    public String getTitle() { return title; }
+    public String getSlug() { return slug; }
+    public String getDescription() { return description; }
+    public String getUrl() { return url; }
+    public String getImageUrl() { return imageUrl; }
+    public ToolComponentKey getComponentKey() { return componentKey; }
+    public List<String> getTags() { return List.copyOf(tags); }
+    public int getSortOrder() { return sortOrder; }
+    public long getVersion() { return version; }
+    public Instant getCreatedAt() { return createdAt; }
+    public Instant getUpdatedAt() { return updatedAt; }
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolCategory.java b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolCategory.java
new file mode 100644
index 0000000..c727d47
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolCategory.java
@@ -0,0 +1,61 @@
+package io.haoblog.toolbox.domain;
+
+import io.haoblog.shared.id.UuidV7;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import jakarta.persistence.Version;
+
+import java.time.Instant;
+import java.util.UUID;
+
+@Entity
+@Table(name = "tool_category")
+public class ToolCategory {
+    @Id
+    private UUID id = UuidV7.generate();
+    @Column(nullable = false, unique = true, length = 120)
+    private String name;
+    @Column(nullable = false, unique = true, length = 160)
+    private String slug;
+    @Column(length = 600)
+    private String description;
+    @Column(name = "sort_order", nullable = false)
+    private int sortOrder;
+    @Version
+    @Column(nullable = false)
+    private long version;
+    @Column(name = "created_at", nullable = false)
+    private Instant createdAt;
+    @Column(name = "updated_at", nullable = false)
+    private Instant updatedAt;
+
+    protected ToolCategory() {}
+
+    public ToolCategory(String name, String slug, String description, int sortOrder, Instant now) {
+        this.name = name.trim();
+        this.slug = ToolSlug.normalizeRequired(slug);
+        this.description = description;
+        this.sortOrder = sortOrder;
+        this.createdAt = now;
+        this.updatedAt = now;
+    }
+
+    public void update(String name, String slug, String description, int sortOrder, Instant now) {
+        this.name = name.trim();
+        this.slug = ToolSlug.normalizeRequired(slug);
+        this.description = description;
+        this.sortOrder = sortOrder;
+        this.updatedAt = now;
+    }
+
+    public UUID getId() { return id; }
+    public String getName() { return name; }
+    public String getSlug() { return slug; }
+    public String getDescription() { return description; }
+    public int getSortOrder() { return sortOrder; }
+    public long getVersion() { return version; }
+    public Instant getCreatedAt() { return createdAt; }
+    public Instant getUpdatedAt() { return updatedAt; }
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolComponentKey.java b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolComponentKey.java
new file mode 100644
index 0000000..c98a8f9
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolComponentKey.java
@@ -0,0 +1,17 @@
+package io.haoblog.toolbox.domain;
+
+public enum ToolComponentKey {
+    JSON_FORMAT("json-format"), BASE64("base64"), URL_CODEC("url-codec"), TIMESTAMP("timestamp"), REGEX_TEST("regex-test");
+
+    private final String value;
+
+    ToolComponentKey(String value) { this.value = value; }
+
+    public String getValue() { return value; }
+
+    public static ToolComponentKey fromValue(String value) {
+        if (value == null || value.isBlank()) return null;
+        for (ToolComponentKey key : values()) if (key.value.equals(value)) return key;
+        throw new IllegalArgumentException("componentKey is not allowed");
+    }
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolComponentKeyConverter.java b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolComponentKeyConverter.java
new file mode 100644
index 0000000..adf7eb3
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolComponentKeyConverter.java
@@ -0,0 +1,17 @@
+package io.haoblog.toolbox.domain;
+
+import jakarta.persistence.AttributeConverter;
+import jakarta.persistence.Converter;
+
+@Converter
+public class ToolComponentKeyConverter implements AttributeConverter<ToolComponentKey, String> {
+    @Override
+    public String convertToDatabaseColumn(ToolComponentKey attribute) {
+        return attribute == null ? null : attribute.getValue();
+    }
+
+    @Override
+    public ToolComponentKey convertToEntityAttribute(String value) {
+        return ToolComponentKey.fromValue(value);
+    }
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolSlug.java b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolSlug.java
new file mode 100644
index 0000000..a63f3e1
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolSlug.java
@@ -0,0 +1,20 @@
+package io.haoblog.toolbox.domain;
+
+import java.util.Locale;
+import java.util.regex.Pattern;
+
+public final class ToolSlug {
+    private static final Pattern VALID = Pattern.compile("^[a-z0-9]+(?:-[a-z0-9]+)*$");
+
+    private ToolSlug() {}
+
+    public static String normalizeRequired(String raw) {
+        if (raw == null || raw.isBlank()) throw new IllegalArgumentException("Slug is required");
+        String value = raw.trim().toLowerCase(Locale.ROOT).replaceAll("[\\s_]+", "-")
+                .replaceAll("-+", "-").replaceAll("^-|-$", "");
+        if (value.isEmpty() || value.length() > 160 || !VALID.matcher(value).matches()) {
+            throw new IllegalArgumentException("Slug must be lowercase ASCII kebab-case");
+        }
+        return value;
+    }
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolStatus.java b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolStatus.java
new file mode 100644
index 0000000..0b0a21d
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolStatus.java
@@ -0,0 +1,5 @@
+package io.haoblog.toolbox.domain;
+
+public enum ToolStatus {
+    ACTIVE, INACTIVE
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolType.java b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolType.java
new file mode 100644
index 0000000..58540ba
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/domain/ToolType.java
@@ -0,0 +1,5 @@
+package io.haoblog.toolbox.domain;
+
+public enum ToolType {
+    LINK, EMBEDDED, SHOWCASE
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/package-info.java b/apps/api/src/main/java/io/haoblog/toolbox/package-info.java
index 459224e..d10be0d 100644
--- a/apps/api/src/main/java/io/haoblog/toolbox/package-info.java
+++ b/apps/api/src/main/java/io/haoblog/toolbox/package-info.java
@@ -1,2 +1,2 @@
-/** Toolbox boundary reserved for browser tools and links. */
+/** 管理浏览器工具、链接及白名单内嵌组件配置。 */
 package io.haoblog.toolbox;
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolCategoryRepository.java b/apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolCategoryRepository.java
new file mode 100644
index 0000000..0290e35
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolCategoryRepository.java
@@ -0,0 +1,15 @@
+package io.haoblog.toolbox.persistence;
+
+import io.haoblog.toolbox.domain.ToolCategory;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+import java.util.UUID;
+
+public interface ToolCategoryRepository extends JpaRepository<ToolCategory, UUID> {
+    List<ToolCategory> findAllByOrderBySortOrderAscNameAsc();
+    boolean existsByNameIgnoreCase(String name);
+    boolean existsByNameIgnoreCaseAndIdNot(String name, UUID id);
+    boolean existsBySlug(String slug);
+    boolean existsBySlugAndIdNot(String slug, UUID id);
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolRepository.java b/apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolRepository.java
new file mode 100644
index 0000000..601321d
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolRepository.java
@@ -0,0 +1,13 @@
+package io.haoblog.toolbox.persistence;
+
+import io.haoblog.toolbox.domain.Tool;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+
+import java.util.UUID;
+
+public interface ToolRepository extends JpaRepository<Tool, UUID>, JpaSpecificationExecutor<Tool> {
+    boolean existsByCategoryId(UUID categoryId);
+    boolean existsBySlug(String slug);
+    boolean existsBySlugAndIdNot(String slug, UUID id);
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/web/AdminToolCategoryController.java b/apps/api/src/main/java/io/haoblog/toolbox/web/AdminToolCategoryController.java
new file mode 100644
index 0000000..db1c955
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/web/AdminToolCategoryController.java
@@ -0,0 +1,77 @@
+package io.haoblog.toolbox.web;
+
+import io.haoblog.shared.web.ProblemException;
+import io.haoblog.toolbox.application.ToolManagementService;
+import io.haoblog.toolbox.domain.ToolCategory;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import org.springframework.dao.OptimisticLockingFailureException;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.net.URI;
+import java.time.Instant;
+import java.util.List;
+import java.util.UUID;
+
+@RestController
+@RequestMapping("/api/v1/admin/tool-categories")
+public class AdminToolCategoryController {
+    private final ToolManagementService service;
+
+    public AdminToolCategoryController(ToolManagementService service) { this.service = service; }
+
+    @GetMapping
+    public List<Response> list() { return service.listCategories().stream().map(Response::from).toList(); }
+
+    @PostMapping
+    public ResponseEntity<Response> create(@RequestBody @Valid CreateRequest request) {
+        Response result = Response.from(service.createCategory(request.name(), request.slug(), request.description(), sortOrderOrDefault(request.sortOrder())));
+        return ResponseEntity.created(URI.create("/api/v1/admin/tool-categories/" + result.id())).body(result);
+    }
+
+    @GetMapping("/{id}")
+    public Response get(@PathVariable UUID id) { return Response.from(service.getCategory(id)); }
+
+    @PutMapping("/{id}")
+    public Response update(@PathVariable UUID id, @RequestBody @Valid UpdateRequest request) {
+        try {
+            return Response.from(service.updateCategory(id, request.version(), request.name(), request.slug(), request.description(), sortOrderOrDefault(request.sortOrder())));
+        } catch (OptimisticLockingFailureException exception) {
+            throw new ProblemException("TOOL_CATEGORY_VERSION_CONFLICT", "Version conflict", "Reload the latest tool category before saving", service.currentCategoryVersion(id));
+        }
+    }
+
+    @DeleteMapping("/{id}")
+    public ResponseEntity<Void> delete(@PathVariable UUID id, @RequestParam long version) {
+        try {
+            service.deleteCategory(id, version);
+            return ResponseEntity.noContent().build();
+        } catch (OptimisticLockingFailureException exception) {
+            throw new ProblemException("TOOL_CATEGORY_VERSION_CONFLICT", "Version conflict", "Reload the latest tool category before deleting", service.currentCategoryVersion(id));
+        }
+    }
+
+    public record CreateRequest(@NotBlank @Size(max = 120) String name, @NotBlank @Size(max = 160) String slug,
+                                @Size(max = 600) String description, Integer sortOrder) {}
+    public record UpdateRequest(@NotNull Long version, @NotBlank @Size(max = 120) String name,
+                                @NotBlank @Size(max = 160) String slug, @Size(max = 600) String description,
+                                Integer sortOrder) {}
+    public record Response(UUID id, String name, String slug, String description, int sortOrder, long version,
+                           Instant createdAt, Instant updatedAt) {
+        static Response from(ToolCategory value) { return new Response(value.getId(), value.getName(), value.getSlug(), value.getDescription(),
+                value.getSortOrder(), value.getVersion(), value.getCreatedAt(), value.getUpdatedAt()); }
+    }
+
+    private static int sortOrderOrDefault(Integer sortOrder) { return sortOrder == null ? 0 : sortOrder; }
+}
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/web/AdminToolController.java b/apps/api/src/main/java/io/haoblog/toolbox/web/AdminToolController.java
new file mode 100644
index 0000000..89dc2fa
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/web/AdminToolController.java
@@ -0,0 +1,104 @@
+package io.haoblog.toolbox.web;
+
+import io.haoblog.shared.web.ProblemException;
+import io.haoblog.toolbox.application.ToolManagementService;
+import io.haoblog.toolbox.domain.Tool;
+import io.haoblog.toolbox.domain.ToolCategory;
+import io.haoblog.toolbox.domain.ToolComponentKey;
+import io.haoblog.toolbox.domain.ToolStatus;
+import io.haoblog.toolbox.domain.ToolType;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import org.springframework.dao.OptimisticLockingFailureException;
+import org.springframework.data.domain.Sort;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.UUID;
+
+@RestController
+@RequestMapping("/api/v1/admin/tools")
+public class AdminToolController {
+    private final ToolManagementService service;
+
+    public AdminToolController(ToolManagementService service) { this.service = service; }
+
+    @GetMapping
+    public ListResponse list(@RequestParam(defaultValue = "0") int page, @RequestParam(defaultValue = "20") int size,
+                             @RequestParam(required = false) UUID categoryId, @RequestParam(required = false) ToolType type,
+                             @RequestParam(required = false) ToolStatus status, @RequestParam(required = false) String keyword,
+                             @RequestParam(defaultValue = "sortOrder") String sort, @RequestParam(defaultValue = "asc") String direction) {
+        PageResult result = new PageResult(service.listTools(page, size, categoryId, type, status, keyword, sort, parseDirection(direction)));
+        return new ListResponse(result.items(), result.page(), result.size(), result.total());
+    }
+
+    @GetMapping("/{id}")
+    public Response get(@PathVariable UUID id) { return Response.from(service.getTool(id)); }
+
+    @PostMapping
+    public org.springframework.http.ResponseEntity<Response> create(@RequestBody @Valid Request request) {
+        Response result = Response.from(service.createTool(request.categoryId(), request.type(), request.status(), request.title(), request.slug(),
+                request.description(), request.url(), request.imageUrl(), ToolComponentKey.fromValue(request.componentKey()), request.tags(), sortOrderOrDefault(request.sortOrder())));
+        return org.springframework.http.ResponseEntity.created(java.net.URI.create("/api/v1/admin/tools/" + result.id())).body(result);
+    }
+
+    @PutMapping("/{id}")
+    public Response update(@PathVariable UUID id, @RequestBody @Valid UpdateRequest request) {
+        try {
+            return Response.from(service.updateTool(id, request.version(), request.categoryId(), request.type(), request.status(), request.title(), request.slug(),
+                    request.description(), request.url(), request.imageUrl(), ToolComponentKey.fromValue(request.componentKey()), request.tags(), sortOrderOrDefault(request.sortOrder())));
+        } catch (OptimisticLockingFailureException exception) {
+            throw new ProblemException("TOOL_VERSION_CONFLICT", "Version conflict", "Reload the latest tool before saving", service.currentToolVersion(id));
+        }
+    }
+
+    @DeleteMapping("/{id}")
+    public org.springframework.http.ResponseEntity<Void> delete(@PathVariable UUID id, @RequestParam long version) {
+        try {
+            service.deleteTool(id, version);
+            return org.springframework.http.ResponseEntity.noContent().build();
+        } catch (OptimisticLockingFailureException exception) {
+            throw new ProblemException("TOOL_VERSION_CONFLICT", "Version conflict", "Reload the latest tool before deleting", service.currentToolVersion(id));
+        }
+    }
+
+    private static Sort.Direction parseDirection(String direction) {
+        if ("asc".equalsIgnoreCase(direction)) return Sort.Direction.ASC;
+        if ("desc".equalsIgnoreCase(direction)) return Sort.Direction.DESC;
+        throw new IllegalArgumentException("direction must be asc or desc");
+    }
+
+    public record Request(@NotNull UUID categoryId, @NotNull ToolType type, @NotNull ToolStatus status,
+                          @NotBlank @Size(max = 160) String title, @NotBlank @Size(max = 160) String slug,
+                          @Size(max = 600) String description, @Size(max = 2048) String url,
+                          @Size(max = 2048) String imageUrl, @Size(max = 32) String componentKey,
+                          @Size(max = 32) List<@NotBlank @Size(max = 64) String> tags, Integer sortOrder) {}
+    public record UpdateRequest(@NotNull Long version, @NotNull UUID categoryId, @NotNull ToolType type, @NotNull ToolStatus status,
+                                @NotBlank @Size(max = 160) String title, @NotBlank @Size(max = 160) String slug,
+                                @Size(max = 600) String description, @Size(max = 2048) String url,
+                                @Size(max = 2048) String imageUrl, @Size(max = 32) String componentKey,
+                                @Size(max = 32) List<@NotBlank @Size(max = 64) String> tags, Integer sortOrder) {}
+    public record ListResponse(List<Response> items, int page, int size, long total) {}
+    private record PageResult(List<Response> items, int page, int size, long total) {
+        PageResult(org.springframework.data.domain.Page<Tool> page) { this(page.getContent().stream().map(Response::from).toList(), page.getNumber(), page.getSize(), page.getTotalElements()); }
+    }
+    public record Response(UUID id, UUID categoryId, ToolType type, ToolStatus status, String title, String slug,
+                           String description, String url, String imageUrl, String componentKey, List<String> tags,
+                           int sortOrder, long version, Instant createdAt, Instant updatedAt) {
+        static Response from(Tool value) { return new Response(value.getId(), value.getCategoryId(), value.getType(), value.getStatus(), value.getTitle(), value.getSlug(),
+                value.getDescription(), value.getUrl(), value.getImageUrl(), value.getComponentKey() == null ? null : value.getComponentKey().getValue(), value.getTags(), value.getSortOrder(), value.getVersion(), value.getCreatedAt(), value.getUpdatedAt()); }
+        }
+
+    private static int sortOrderOrDefault(Integer sortOrder) { return sortOrder == null ? 0 : sortOrder; }
+}
diff --git a/apps/api/src/main/resources/db/migration/V14__toolbox_domain_model.sql b/apps/api/src/main/resources/db/migration/V14__toolbox_domain_model.sql
new file mode 100644
index 0000000..4fdf07e
--- /dev/null
+++ b/apps/api/src/main/resources/db/migration/V14__toolbox_domain_model.sql
@@ -0,0 +1,44 @@
+CREATE TABLE tool_category (
+    id uuid PRIMARY KEY,
+    name varchar(120) NOT NULL UNIQUE,
+    slug varchar(160) NOT NULL UNIQUE,
+    description varchar(600),
+    sort_order integer NOT NULL DEFAULT 0,
+    version bigint NOT NULL DEFAULT 0,
+    created_at timestamptz NOT NULL,
+    updated_at timestamptz NOT NULL,
+    CONSTRAINT tool_category_slug_format CHECK (slug ~ '^[a-z0-9]+(-[a-z0-9]+)*$')
+);
+
+CREATE TABLE tool (
+    id uuid PRIMARY KEY,
+    category_id uuid NOT NULL REFERENCES tool_category(id) ON DELETE RESTRICT,
+    type varchar(16) NOT NULL CHECK (type IN ('LINK', 'EMBEDDED', 'SHOWCASE')),
+    status varchar(16) NOT NULL DEFAULT 'ACTIVE' CHECK (status IN ('ACTIVE', 'INACTIVE')),
+    title varchar(160) NOT NULL,
+    slug varchar(160) NOT NULL UNIQUE,
+    description varchar(600),
+    url varchar(2048),
+    image_url varchar(2048),
+    component_key varchar(32),
+    tags jsonb NOT NULL DEFAULT '[]'::jsonb,
+    sort_order integer NOT NULL DEFAULT 0,
+    version bigint NOT NULL DEFAULT 0,
+    created_at timestamptz NOT NULL,
+    updated_at timestamptz NOT NULL,
+    CONSTRAINT tool_tags_array CHECK (jsonb_typeof(tags) = 'array'),
+    CONSTRAINT tool_component_key CHECK (component_key IS NULL OR component_key IN (
+        'json-format', 'base64', 'url-codec', 'timestamp', 'regex-test'
+    )),
+    CONSTRAINT tool_https_urls CHECK (
+        (url IS NULL OR url ~ '^https://[^[:space:]]+$')
+        AND (image_url IS NULL OR image_url ~ '^https://[^[:space:]]+$')
+    ),
+    CONSTRAINT tool_type_fields CHECK (
+        (type IN ('LINK', 'SHOWCASE') AND url IS NOT NULL AND component_key IS NULL)
+        OR (type = 'EMBEDDED' AND url IS NULL AND component_key IS NOT NULL)
+    )
+);
+
+CREATE INDEX tool_category_sort_idx ON tool (category_id, sort_order, id);
+CREATE INDEX tool_filter_idx ON tool (type, status, updated_at, id);
diff --git a/apps/api/src/test/java/io/haoblog/ContentModelIT.java b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
index d522420..d681245 100644
--- a/apps/api/src/test/java/io/haoblog/ContentModelIT.java
+++ b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
@@ -57,7 +57,7 @@ static void database(DynamicPropertyRegistry registry) {
 
     @Test
     void migratesAllVersionsAndCreatesContentTables() {
-        assertEquals(13, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
+        assertEquals(14, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
         for (String table : List.of("article", "category", "tag", "article_tag", "article_revision",
                 "article_preview_token", "media_asset", "media_upload", "outbox_event", "comment")) {
             assertEquals(1, jdbc.queryForObject(
diff --git a/apps/api/src/test/java/io/haoblog/ToolAdminIT.java b/apps/api/src/test/java/io/haoblog/ToolAdminIT.java
new file mode 100644
index 0000000..f66b67b
--- /dev/null
+++ b/apps/api/src/test/java/io/haoblog/ToolAdminIT.java
@@ -0,0 +1,128 @@
+package io.haoblog;
+
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.dao.DataIntegrityViolationException;
+import org.springframework.http.MediaType;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.springframework.test.web.servlet.MockMvc;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import java.sql.Timestamp;
+import java.time.Instant;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf;
+import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.user;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@Testcontainers
+@SpringBootTest
+@AutoConfigureMockMvc
+class ToolAdminIT {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("pgvector/pgvector:0.8.6-pg17");
+
+    @DynamicPropertySource
+    static void database(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+        registry.add("spring.flyway.placeholders.admin_username", () -> "admin");
+        registry.add("spring.flyway.placeholders.admin_password_hash", () -> "$2a$10$0V.Xs7CLOUYSekm7RKq3Z.iY76KUan/Xbeu5vjmLpX.sVd4pcFpIu");
+    }
+
+    @Autowired MockMvc mvc;
+    @Autowired ObjectMapper objectMapper;
+    @Autowired JdbcTemplate jdbc;
+
+    @Test
+    void migrationStartsWithEmptyToolTablesAndWritesNeedAuthAndCsrf() throws Exception {
+        assertNotNull(jdbc.queryForObject("select to_regclass('tool_category')", String.class));
+        assertNotNull(jdbc.queryForObject("select to_regclass('tool')", String.class));
+        mvc.perform(get("/api/v1/admin/tool-categories"))
+                .andExpect(status().isUnauthorized()).andExpect(content().contentType("application/problem+json"));
+        mvc.perform(post("/api/v1/admin/tool-categories").with(admin()).contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"name\":\"No CSRF\",\"slug\":\"no-csrf\"}"))
+                .andExpect(status().isForbidden()).andExpect(jsonPath("$.code").value("CSRF_INVALID"));
+    }
+
+    @Test
+    void rejectsUnsafeComponentAndUrlCombinations() throws Exception {
+        String categoryId = createCategory();
+        tool(categoryId, "{\"type\":\"EMBEDDED\",\"componentKey\":\"<script>\",\"title\":\"Bad\",\"slug\":\"bad-component\",\"tags\":[]}")
+                .andExpect(status().isBadRequest());
+        tool(categoryId, "{\"type\":\"EMBEDDED\",\"componentKey\":\"json-format\",\"url\":\"https://example.com\",\"title\":\"Bad\",\"slug\":\"bad-fields\",\"tags\":[]}")
+                .andExpect(status().isBadRequest());
+        tool(categoryId, "{\"type\":\"LINK\",\"url\":\"http://example.com\",\"title\":\"Bad\",\"slug\":\"bad-http\",\"tags\":[]}")
+                .andExpect(status().isBadRequest());
+        tool(categoryId, "{\"type\":\"EMBEDDED\",\"componentKey\":\"json-format\",\"title\":\"JSON\",\"slug\":\"json-format\",\"tags\":[]}")
+                .andExpect(status().isCreated());
+    }
+
+    @Test
+    void filtersPaginatesUsesVersionAndProtectsCategoryDeletion() throws Exception {
+        String categoryId = createCategory();
+        String first = createTool(categoryId, "alpha-tool", "Alpha", "LINK", "https://example.com/alpha", null);
+        createTool(categoryId, "beta-tool", "Beta", "SHOWCASE", "https://example.com/beta", null);
+
+        mvc.perform(get("/api/v1/admin/tools?categoryId=" + categoryId + "&type=LINK&keyword=alpha&page=0&size=1")
+                        .with(admin()))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.total").value(1)).andExpect(jsonPath("$.items[0].slug").value("alpha-tool"));
+        mvc.perform(put("/api/v1/admin/tools/" + first).with(admin()).with(csrf()).contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"version\":99,\"categoryId\":\"" + categoryId + "\",\"type\":\"LINK\",\"status\":\"INACTIVE\",\"title\":\"Alpha\",\"slug\":\"alpha-tool\",\"url\":\"https://example.com/alpha\",\"tags\":[],\"sortOrder\":1}"))
+                .andExpect(status().isConflict()).andExpect(jsonPath("$.code").value("TOOL_VERSION_CONFLICT"));
+        JsonNode category = objectMapper.readTree(mvc.perform(get("/api/v1/admin/tool-categories/" + categoryId).with(admin()))
+                .andReturn().getResponse().getContentAsString());
+        mvc.perform(delete("/api/v1/admin/tool-categories/" + categoryId + "?version=" + category.get("version").asLong()).with(admin()).with(csrf()))
+                .andExpect(status().isConflict()).andExpect(jsonPath("$.code").value("TOOL_CATEGORY_IN_USE"));
+    }
+
+    @Test
+    void databaseConstraintsRejectArbitraryComponentAndNonArrayTags() {
+        UUID categoryId = UUID.randomUUID();
+        Timestamp now = Timestamp.from(Instant.now());
+        jdbc.update("insert into tool_category(id,name,slug,created_at,updated_at) values (?,?,?,?,?)", categoryId, "DB " + categoryId, "db-" + categoryId.toString().substring(0, 8), now, now);
+        assertThrows(DataIntegrityViolationException.class, () -> jdbc.update("insert into tool(id,category_id,type,status,title,slug,component_key,tags,created_at,updated_at) values (?, ?, ?, ?, ?, ?, ?, ?::jsonb, ?, ?)",
+                UUID.randomUUID(), categoryId, "EMBEDDED", "ACTIVE", "Invalid", "invalid-" + categoryId.toString().substring(0, 8), "arbitrary-path", "{}", now, now));
+    }
+
+    private String createCategory() throws Exception {
+        String suffix = UUID.randomUUID().toString().substring(0, 8);
+        var result = mvc.perform(post("/api/v1/admin/tool-categories").with(admin()).with(csrf()).contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"name\":\"Category " + suffix + "\",\"slug\":\"category-" + suffix + "\"}"))
+                .andExpect(status().isCreated()).andReturn();
+        return objectMapper.readTree(result.getResponse().getContentAsString()).get("id").asText();
+    }
+
+    private org.springframework.test.web.servlet.ResultActions tool(String categoryId, String body) throws Exception {
+        String base = body.substring(0, body.length() - 1);
+        String payload = base + ",\"categoryId\":\"" + categoryId + "\",\"status\":\"ACTIVE\"}";
+        return mvc.perform(post("/api/v1/admin/tools").with(admin()).with(csrf()).contentType(MediaType.APPLICATION_JSON).content(payload));
+    }
+
+    private String createTool(String categoryId, String slug, String title, String type, String url, String componentKey) throws Exception {
+        String body = "{\"categoryId\":\"" + categoryId + "\",\"type\":\"" + type + "\",\"status\":\"ACTIVE\",\"title\":\"" + title + "\",\"slug\":\"" + slug + "\",\"url\":" + (url == null ? "null" : "\"" + url + "\"") + ",\"componentKey\":" + (componentKey == null ? "null" : "\"" + componentKey + "\"") + ",\"tags\":[]}";
+        var result = mvc.perform(post("/api/v1/admin/tools").with(admin()).with(csrf()).contentType(MediaType.APPLICATION_JSON).content(body))
+                .andExpect(status().isCreated()).andReturn();
+        return objectMapper.readTree(result.getResponse().getContentAsString()).get("id").asText();
+    }
+
+    private static org.springframework.test.web.servlet.request.RequestPostProcessor admin() { return user("admin").roles("ADMIN"); }
+}
diff --git a/apps/api/src/test/java/io/haoblog/toolbox/domain/ToolDomainTest.java b/apps/api/src/test/java/io/haoblog/toolbox/domain/ToolDomainTest.java
new file mode 100644
index 0000000..d196ca8
--- /dev/null
+++ b/apps/api/src/test/java/io/haoblog/toolbox/domain/ToolDomainTest.java
@@ -0,0 +1,30 @@
+package io.haoblog.toolbox.domain;
+
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ToolDomainTest {
+    private static final UUID CATEGORY_ID = UUID.randomUUID();
+
+    @Test
+    void acceptsOnlyWhitelistedEmbeddedComponent() {
+        Tool tool = new Tool(CATEGORY_ID, ToolType.EMBEDDED, ToolStatus.ACTIVE, "JSON", "json",
+                null, null, null, ToolComponentKey.JSON_FORMAT, List.of("json"), 0, Instant.now());
+        assertEquals("json-format", tool.getComponentKey().getValue());
+        assertThrows(IllegalArgumentException.class, () -> ToolComponentKey.fromValue("/components/Arbitrary.vue"));
+    }
+
+    @Test
+    void rejectsUnsafeUrlsAndMismatchedFields() {
+        assertThrows(IllegalArgumentException.class, () -> new Tool(CATEGORY_ID, ToolType.LINK, ToolStatus.ACTIVE,
+                "HTTP", "http", null, "http://example.com", null, null, List.of(), 0, Instant.now()));
+        assertThrows(IllegalArgumentException.class, () -> new Tool(CATEGORY_ID, ToolType.EMBEDDED, ToolStatus.ACTIVE,
+                "Mixed", "mixed", null, "https://example.com", null, ToolComponentKey.JSON_FORMAT, List.of(), 0, Instant.now()));
+    }
+}
diff --git a/apps/web/app/composables/useAdminTools.ts b/apps/web/app/composables/useAdminTools.ts
new file mode 100644
index 0000000..a2e57a8
--- /dev/null
+++ b/apps/web/app/composables/useAdminTools.ts
@@ -0,0 +1,49 @@
+import type { components } from '@haoblog/api-client'
+import { useAdminSession } from './useAdminSession'
+
+type ToolCategory = components['schemas']['ToolCategoryResponse']
+type ToolCategoryCreateRequest = components['schemas']['ToolCategoryCreateRequest']
+type ToolCategoryUpdateRequest = components['schemas']['ToolCategoryUpdateRequest']
+type Tool = components['schemas']['ToolResponse']
+type ToolCreateRequest = components['schemas']['ToolCreateRequest']
+type ToolUpdateRequest = components['schemas']['ToolUpdateRequest']
+type ToolList = components['schemas']['AdminToolListResponse']
+
+export function useAdminTools() {
+  const session = useAdminSession()
+
+  async function listCategories() { return session.request<ToolCategory[]>('/api/v1/admin/tool-categories') }
+  async function createCategory(payload: ToolCategoryCreateRequest) {
+    return session.write<ToolCategory>('/api/v1/admin/tool-categories', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) })
+  }
+  async function updateCategory(id: string, payload: ToolCategoryUpdateRequest) {
+    return session.write<ToolCategory>(`/api/v1/admin/tool-categories/${encodeURIComponent(id)}`, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) })
+  }
+  async function deleteCategory(id: string, version: number) {
+    return session.write<void>(`/api/v1/admin/tool-categories/${encodeURIComponent(id)}?version=${version}`, { method: 'DELETE' })
+  }
+  async function listTools(params: {
+    page?: number; size?: number; categoryId?: string; type?: components['schemas']['ToolType']; status?: components['schemas']['ToolStatus']; keyword?: string; sort?: 'sortOrder' | 'createdAt' | 'updatedAt' | 'title'; direction?: 'asc' | 'desc'
+  } = {}) {
+    const query = new URLSearchParams({ page: String(params.page ?? 0), size: String(params.size ?? 20), sort: params.sort ?? 'sortOrder', direction: params.direction ?? 'asc' })
+    if (params.categoryId) query.set('categoryId', params.categoryId)
+    if (params.type) query.set('type', params.type)
+    if (params.status) query.set('status', params.status)
+    if (params.keyword?.trim()) query.set('keyword', params.keyword.trim())
+    return session.request<ToolList>(`/api/v1/admin/tools?${query}`)
+  }
+  async function getTool(id: string) { return session.request<Tool>(`/api/v1/admin/tools/${encodeURIComponent(id)}`) }
+  async function createTool(payload: ToolCreateRequest) {
+    return session.write<Tool>('/api/v1/admin/tools', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) })
+  }
+  async function updateTool(id: string, payload: ToolUpdateRequest) {
+    return session.write<Tool>(`/api/v1/admin/tools/${encodeURIComponent(id)}`, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) })
+  }
+  async function deleteTool(id: string, version: number) {
+    return session.write<void>(`/api/v1/admin/tools/${encodeURIComponent(id)}?version=${version}`, { method: 'DELETE' })
+  }
+
+  return { listCategories, createCategory, updateCategory, deleteCategory, listTools, getTool, createTool, updateTool, deleteTool }
+}
+
+export type { Tool, ToolCategory, ToolCategoryCreateRequest, ToolCategoryUpdateRequest, ToolCreateRequest, ToolList, ToolUpdateRequest }
diff --git a/apps/web/app/layouts/studio.vue b/apps/web/app/layouts/studio.vue
index e50f6dd..84cb2e7 100644
--- a/apps/web/app/layouts/studio.vue
+++ b/apps/web/app/layouts/studio.vue
@@ -11,6 +11,7 @@
         <NuxtLink to="/studio/articles" :aria-current="route.path === '/studio/articles' ? 'page' : undefined">文章日志</NuxtLink>
         <NuxtLink to="/studio/articles/new">新建文章</NuxtLink>
         <NuxtLink to="/studio/comments" :aria-current="route.path === '/studio/comments' ? 'page' : undefined">评论审核</NuxtLink>
+        <NuxtLink to="/studio/tools" :aria-current="route.path === '/studio/tools' ? 'page' : undefined">工具控制台</NuxtLink>
         <NuxtLink to="/studio/settings" :aria-current="route.path === '/studio/settings' ? 'page' : undefined">站点开关</NuxtLink>
         <NuxtLink to="/" external>返回公开站</NuxtLink>
         <button type="button" :disabled="pending" @click="signOut">{{ pending ? 'CLEARING…' : '退出' }}</button>
diff --git a/apps/web/app/pages/studio/tools.vue b/apps/web/app/pages/studio/tools.vue
new file mode 100644
index 0000000..bddcb7e
--- /dev/null
+++ b/apps/web/app/pages/studio/tools.vue
@@ -0,0 +1,114 @@
+<template>
+  <section class="tools-scene" aria-labelledby="tools-title">
+    <div class="page-heading">
+      <div><p class="instrument-label">STUDIO / TOOLBOX CONTROL</p><h1 id="tools-title">工具控制台</h1></div>
+      <button class="instrument-button" type="button" @click="newTool">新建工具</button>
+    </div>
+
+    <p v-if="errorMessage" class="form-error" role="alert">{{ errorMessage }}</p>
+    <div class="control-grid">
+      <aside class="category-panel" aria-labelledby="category-title">
+        <div class="panel-heading"><h2 id="category-title">分类舱</h2><button class="plain-button" type="button" @click="newCategory">新建分类</button></div>
+        <form class="console-form" @submit.prevent="saveCategory">
+          <label>名称<input v-model="categoryDraft.name" maxlength="120" required></label>
+          <label>Slug<input v-model="categoryDraft.slug" maxlength="160" required></label>
+          <label>描述<textarea v-model="categoryDraft.description" maxlength="600" rows="2" /></label>
+          <label>排序<input v-model.number="categoryDraft.sortOrder" type="number"></label>
+          <p v-if="categoryError" class="form-error" role="alert">{{ categoryError }}</p>
+          <div class="button-row"><button class="instrument-button" type="submit" :disabled="savingCategory">{{ savingCategory ? 'WRITING…' : '写入分类' }}</button><button v-if="categoryDraft.id" class="plain-button" type="button" @click="removeCategory">删除</button></div>
+        </form>
+        <ul class="category-list">
+          <li v-for="category in categories" :key="category.id" :data-active="category.id === categoryDraft.id"><button type="button" @click="editCategory(category)"><span>{{ category.name }}</span><small>{{ category.sortOrder }} / v{{ category.version }}</small></button></li>
+        </ul>
+      </aside>
+
+      <div class="tool-panel">
+        <form class="filter-console" role="search" @submit.prevent="applyFilters">
+          <label>分类<select v-model="filters.categoryId"><option value="">全部分类</option><option v-for="category in categories" :key="category.id" :value="category.id">{{ category.name }}</option></select></label>
+          <label>类型<select v-model="filters.type"><option value="">全部类型</option><option v-for="type in toolTypes" :key="type" :value="type">{{ type }}</option></select></label>
+          <label>状态<select v-model="filters.status"><option value="">全部状态</option><option value="ACTIVE">启用</option><option value="INACTIVE">停用</option></select></label>
+          <label class="keyword-field">关键词<input v-model="filters.keyword" maxlength="240" placeholder="标题 / slug / 描述"></label>
+          <button class="instrument-button" type="submit" :disabled="loading">筛选</button>
+        </form>
+        <p v-if="loading" class="signal-note" role="status">正在扫描工具信号…</p>
+        <p v-else-if="!tools.length" class="empty-signal">当前观测范围没有工具。</p>
+        <ol v-else class="tool-log">
+          <li v-for="(tool, index) in tools" :key="tool.id" :data-active="tool.id === toolDraft.id">
+            <button class="tool-row" type="button" @click="editTool(tool)"><span class="tool-index">{{ String(index + 1 + page * pageSize).padStart(2, '0') }}</span><span class="tool-signal" :data-status="tool.status" aria-hidden="true" /><span class="tool-copy"><strong>{{ tool.title }}</strong><small>{{ tool.slug }} · {{ tool.type }} · v{{ tool.version }}</small></span><span class="tool-state">{{ tool.status === 'ACTIVE' ? 'ACTIVE' : 'INACTIVE' }}</span></button>
+          </li>
+        </ol>
+        <div v-if="total > pageSize" class="pagination"><button class="plain-button" type="button" :disabled="page === 0 || loading" @click="changePage(page - 1)">上一页</button><span>PAGE {{ page + 1 }} / {{ Math.ceil(total / pageSize) }}</span><button class="plain-button" type="button" :disabled="(page + 1) * pageSize >= total || loading" @click="changePage(page + 1)">下一页</button></div>
+
+        <form class="tool-editor" @submit.prevent="saveTool">
+          <div class="panel-heading"><h2>{{ toolDraft.id ? '校准工具' : '新建工具' }}</h2><button v-if="toolDraft.id" class="plain-button" type="button" @click="newTool">清空</button></div>
+          <div class="form-columns">
+            <label>分类<select v-model="toolDraft.categoryId"><option value="">请选择</option><option v-for="category in categories" :key="category.id" :value="category.id">{{ category.name }}</option></select><small v-if="toolErrors.categoryId" class="field-error">{{ toolErrors.categoryId }}</small></label>
+            <label>类型<select v-model="toolDraft.type"><option v-for="type in toolTypes" :key="type" :value="type">{{ type }}</option></select></label>
+            <label>状态<select v-model="toolDraft.status"><option value="ACTIVE">ACTIVE / 启用</option><option value="INACTIVE">INACTIVE / 停用</option></select></label>
+            <label>排序<input v-model.number="toolDraft.sortOrder" type="number"></label>
+            <label>标题<input v-model="toolDraft.title" maxlength="160" required><small v-if="toolErrors.title" class="field-error">{{ toolErrors.title }}</small></label>
+            <label>Slug<input v-model="toolDraft.slug" maxlength="160" required><small v-if="toolErrors.slug" class="field-error">{{ toolErrors.slug }}</small></label>
+          </div>
+          <label>描述<textarea v-model="toolDraft.description" maxlength="600" rows="2" /></label>
+          <div class="form-columns"><label>URL（仅 https）<input v-model="toolDraft.url" type="url" inputmode="url" :disabled="toolDraft.type === 'EMBEDDED'" placeholder="https://"><small v-if="toolErrors.url" class="field-error">{{ toolErrors.url }}</small></label><label>图片 URL（可选）<input v-model="toolDraft.imageUrl" type="url" inputmode="url" placeholder="https://"><small v-if="toolErrors.imageUrl" class="field-error">{{ toolErrors.imageUrl }}</small></label></div>
+          <div class="form-columns"><label v-if="toolDraft.type === 'EMBEDDED'">白名单组件<select v-model="toolDraft.componentKey"><option value="">请选择</option><option v-for="key in componentKeys" :key="key" :value="key">{{ key }}</option></select><small v-if="toolErrors.componentKey" class="field-error">{{ toolErrors.componentKey }}</small></label><label>标签（逗号分隔）<input v-model="toolDraft.tags" maxlength="2080" placeholder="json, format"></label></div>
+          <p v-if="toolError" class="form-error" role="alert">{{ toolError }}</p>
+          <div class="button-row"><button class="instrument-button" type="submit" :disabled="savingTool">{{ savingTool ? 'WRITING…' : toolDraft.id ? '保存工具' : '创建工具' }}</button><button v-if="toolDraft.id && toolDraft.status === 'ACTIVE'" class="plain-button" type="button" :disabled="savingTool" @click="deactivateTool">立即停用</button></div>
+        </form>
+      </div>
+    </div>
+  </section>
+</template>
+
+<script setup lang="ts">
+import type { components } from '@haoblog/api-client'
+import { onMounted, reactive, ref } from 'vue'
+import { toolFormToCreateRequest, toolFormToUpdateRequest, toolToForm, validateToolForm, type ToolFormModel } from '../../utils/studioToolForm'
+
+definePageMeta({ layout: 'studio' })
+type ToolType = components['schemas']['ToolType']
+const { listCategories, createCategory, updateCategory, deleteCategory, listTools, createTool, updateTool } = useAdminTools()
+const categories = ref<components['schemas']['ToolCategoryResponse'][]>([])
+const tools = ref<components['schemas']['ToolResponse'][]>([])
+const page = ref(0); const pageSize = 20; const total = ref(0); const loading = ref(false)
+const errorMessage = ref(''); const categoryError = ref(''); const toolError = ref(''); const savingCategory = ref(false); const savingTool = ref(false)
+const filters = reactive<{ categoryId: string; type: ToolType | ''; status: components['schemas']['ToolStatus'] | ''; keyword: string }>({ categoryId: '', type: '', status: '', keyword: '' })
+const categoryDraft = reactive<{ id: string; name: string; slug: string; description: string; sortOrder: number; version: number | null }>({ id: '', name: '', slug: '', description: '', sortOrder: 0, version: null })
+const toolDraft = reactive<ToolFormModel>(toolToForm(null))
+const toolErrors = ref<Record<string, string>>({})
+const toolTypes: ToolType[] = ['LINK', 'EMBEDDED', 'SHOWCASE']; const componentKeys = ['json-format', 'base64', 'url-codec', 'timestamp', 'regex-test'] as const
+
+function newCategory() { Object.assign(categoryDraft, { id: '', name: '', slug: '', description: '', sortOrder: 0, version: null }); categoryError.value = '' }
+function editCategory(category: typeof categories.value[number]) { Object.assign(categoryDraft, { ...category, description: category.description || '' }); categoryError.value = '' }
+function newTool() { Object.assign(toolDraft, toolToForm(null, categories.value[0]?.id || '')); toolErrors.value = {}; toolError.value = '' }
+function editTool(tool: typeof tools.value[number]) { Object.assign(toolDraft, toolToForm(tool)); toolErrors.value = {}; toolError.value = '' }
+function toError(cause: unknown, fallback: string) { return cause instanceof Error ? cause.message : fallback }
+
+async function loadCategories() { categories.value = await listCategories() }
+async function loadTools() { loading.value = true; errorMessage.value = ''; try { const result = await listTools({ page: page.value, size: pageSize, categoryId: filters.categoryId || undefined, type: filters.type || undefined, status: filters.status || undefined, keyword: filters.keyword }); tools.value = result.items; total.value = result.total } catch (cause) { errorMessage.value = toError(cause, '工具列表暂时不可用。') } finally { loading.value = false } }
+async function load() { try { await loadCategories(); if (!toolDraft.categoryId) toolDraft.categoryId = categories.value[0]?.id || ''; await loadTools() } catch (cause) { errorMessage.value = toError(cause, '工具控制台暂时不可用。') } }
+async function saveCategory() { savingCategory.value = true; categoryError.value = ''; try { const payload = { name: categoryDraft.name.trim(), slug: categoryDraft.slug.trim(), description: categoryDraft.description.trim() || null, sortOrder: categoryDraft.sortOrder }; const result = categoryDraft.id ? await updateCategory(categoryDraft.id, { ...payload, version: categoryDraft.version ?? 0 }) : await createCategory(payload); await loadCategories(); editCategory(result) } catch (cause) { categoryError.value = toError(cause, '分类写入失败。') } finally { savingCategory.value = false } }
+async function removeCategory() { if (!categoryDraft.id || !window.confirm('删除这个工具分类？')) return; categoryError.value = ''; try { await deleteCategory(categoryDraft.id, categoryDraft.version ?? 0); newCategory(); await loadCategories(); await loadTools() } catch (cause) { categoryError.value = toError(cause, '分类删除失败，可能仍被工具使用。') } }
+async function saveTool() { toolErrors.value = validateToolForm(toolDraft); if (Object.keys(toolErrors.value).length) return; savingTool.value = true; toolError.value = ''; try { const result = toolDraft.id ? await updateTool(toolDraft.id, toolFormToUpdateRequest(toolDraft)) : await createTool(toolFormToCreateRequest(toolDraft)); await loadTools(); editTool(result) } catch (cause) { toolError.value = toError(cause, '工具写入失败。') } finally { savingTool.value = false } }
+async function deactivateTool() { toolDraft.status = 'INACTIVE'; await saveTool() }
+async function applyFilters() { page.value = 0; await loadTools() }
+async function changePage(next: number) { page.value = next; await loadTools() }
+onMounted(load)
+</script>
+
+<style scoped>
+.tools-scene { max-width: 110rem; margin: 0 auto; }
+.page-heading, .panel-heading, .button-row { display: flex; align-items: end; justify-content: space-between; gap: var(--space-4); }
+.page-heading { margin-bottom: var(--space-8); } h1 { margin: .8rem 0 0; font-size: clamp(2.5rem, 8vw, 6rem); } h2 { margin: 0; color: var(--color-text-main); font: var(--text-lg)/1.2 var(--font-display); }
+.control-grid { display: grid; grid-template-columns: minmax(15rem, 22rem) minmax(0, 1fr); gap: var(--space-8); align-items: start; }
+.category-panel, .tool-editor { padding: var(--space-4); border: 1px solid var(--color-border); background: color-mix(in srgb, var(--color-bg-sub) 72%, transparent); }
+.category-panel { display: grid; gap: var(--space-5); } .console-form, .tool-editor { display: grid; gap: var(--space-4); }
+label { display: grid; gap: .35rem; color: var(--color-text-muted); font: var(--text-xs)/1.3 var(--font-mono); } input, select, textarea { width: 100%; min-width: 0; padding: .55rem .6rem; border: 1px solid var(--color-border); border-radius: 0; background: var(--color-bg-base); color: var(--color-text-main); font: var(--text-sm)/1.35 var(--font-body); } textarea { resize: vertical; } input:focus, select:focus, textarea:focus { border-color: var(--color-accent); outline: 1px solid var(--color-accent); }
+.category-list, .tool-log { display: grid; gap: 1px; margin: 0; padding: 0; list-style: none; background: var(--color-border); } .category-list li, .tool-log li { background: var(--color-bg-base); } .category-list li[data-active='true'], .tool-log li[data-active='true'] { background: color-mix(in srgb, var(--color-accent) 9%, var(--color-bg-base)); } .category-list button { display: flex; width: 100%; justify-content: space-between; gap: .5rem; padding: .7rem; border: 0; background: transparent; color: var(--color-text-main); text-align: left; cursor: pointer; font: var(--text-sm)/1.3 var(--font-body); } .category-list small { color: var(--color-text-muted); font: var(--text-xs)/1 var(--font-mono); }
+.tool-panel { display: grid; gap: var(--space-6); min-width: 0; } .filter-console { display: grid; grid-template-columns: repeat(4, minmax(8rem, 1fr)) auto; align-items: end; gap: var(--space-3); padding-bottom: var(--space-3); border-bottom: 1px solid var(--color-border); } .keyword-field { min-width: 12rem; }
+.tool-row { display: grid; grid-template-columns: 2.5rem .5rem minmax(0, 1fr) auto; align-items: center; gap: .7rem; width: 100%; padding: .8rem .7rem; border: 0; background: transparent; color: var(--color-text-main); text-align: left; cursor: pointer; } .tool-index, .tool-state, .tool-copy small, .pagination, .signal-note, .empty-signal { font: var(--text-xs)/1.3 var(--font-mono); } .tool-index, .tool-copy small, .tool-state { color: var(--color-text-muted); } .tool-copy { display: grid; gap: .25rem; min-width: 0; } .tool-copy strong { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font: var(--text-base)/1.3 var(--font-display); } .tool-signal { width: .45rem; height: .45rem; border-radius: 50%; background: var(--color-warn); } .tool-signal[data-status='ACTIVE'] { background: var(--color-accent); }
+.form-columns { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--space-4); } .instrument-button { width: fit-content; padding: .7rem 1rem; border: 1px solid var(--color-accent); background: transparent; color: var(--color-accent); cursor: pointer; font: var(--text-xs)/1 var(--font-mono); } .instrument-button:hover:not(:disabled), .instrument-button:focus-visible { background: var(--color-accent); color: var(--color-accent-ink); } .instrument-button:disabled { cursor: wait; opacity: .55; } .plain-button { padding: .4rem 0; border: 0; background: transparent; color: var(--color-text-muted); cursor: pointer; font: var(--text-xs)/1 var(--font-mono); } .plain-button:hover:not(:disabled), .plain-button:focus-visible { color: var(--color-accent); } .form-error, .field-error { color: var(--color-warn); font: var(--text-xs)/1.4 var(--font-mono); } .pagination { display: flex; justify-content: center; gap: var(--space-6); color: var(--color-text-muted); }
+@media (max-width: 860px) { .control-grid { grid-template-columns: 1fr; } .category-panel { grid-template-columns: minmax(0, 1fr) minmax(12rem, 1fr); } .category-list { grid-column: 1 / -1; } }
+@media (max-width: 600px) { .filter-console, .form-columns, .category-panel { grid-template-columns: 1fr; } .filter-console .instrument-button { justify-self: start; } }
+@media (max-width: 360px) { .page-heading { align-items: start; flex-direction: column; } .category-panel, .tool-editor { padding: var(--space-3); } .tool-row { grid-template-columns: 2rem .45rem minmax(0, 1fr); } .tool-state { display: none; } }
+</style>
diff --git a/apps/web/app/utils/studioToolForm.ts b/apps/web/app/utils/studioToolForm.ts
new file mode 100644
index 0000000..8d8e470
--- /dev/null
+++ b/apps/web/app/utils/studioToolForm.ts
@@ -0,0 +1,77 @@
+import type { components } from '@haoblog/api-client'
+
+type Tool = components['schemas']['ToolResponse']
+type ToolType = components['schemas']['ToolType']
+type ToolStatus = components['schemas']['ToolStatus']
+type ToolComponentKey = components['schemas']['ToolComponentKey']
+type CreateRequest = components['schemas']['ToolCreateRequest']
+type UpdateRequest = components['schemas']['ToolUpdateRequest']
+
+export type ToolFormModel = {
+  id: string
+  categoryId: string
+  type: ToolType
+  status: ToolStatus
+  title: string
+  slug: string
+  description: string
+  url: string
+  imageUrl: string
+  componentKey: ToolComponentKey | ''
+  tags: string
+  sortOrder: number
+  version: number | null
+}
+
+export type ToolFormErrors = Partial<Record<'categoryId' | 'title' | 'slug' | 'url' | 'componentKey' | 'imageUrl' | 'tags', string>>
+
+const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const httpsPattern = /^https:\/\/[^\s]+$/i
+
+export function toolToForm(tool?: Tool | null, categoryId = ''): ToolFormModel {
+  return {
+    id: tool?.id || '',
+    categoryId: tool?.categoryId || categoryId,
+    type: tool?.type || 'EMBEDDED',
+    status: tool?.status || 'ACTIVE',
+    title: tool?.title || '', slug: tool?.slug || '', description: tool?.description || '',
+    url: tool?.url || '', imageUrl: tool?.imageUrl || '', componentKey: tool?.componentKey || '',
+    tags: (tool?.tags || []).join(', '), sortOrder: tool?.sortOrder || 0, version: tool?.version ?? null,
+  }
+}
+
+function tags(value: string) { return value.split(',').map(item => item.trim()).filter(Boolean).filter((item, index, all) => all.indexOf(item) === index) }
+function nullable(value: string) { return value.trim() || null }
+
+function common(form: ToolFormModel) {
+  return {
+    categoryId: form.categoryId, type: form.type, status: form.status, title: form.title.trim(), slug: form.slug.trim(),
+    description: nullable(form.description), url: nullable(form.url), imageUrl: nullable(form.imageUrl),
+    componentKey: form.componentKey || null, tags: tags(form.tags), sortOrder: form.sortOrder,
+  }
+}
+
+export function toolFormToCreateRequest(form: ToolFormModel): CreateRequest { return common(form) }
+export function toolFormToUpdateRequest(form: ToolFormModel): UpdateRequest { return { ...common(form), version: form.version ?? 0 } }
+
+export function validateToolForm(form: ToolFormModel): ToolFormErrors {
+  const errors: ToolFormErrors = {}
+  if (!form.categoryId) errors.categoryId = '请选择工具分类。'
+  if (!form.title.trim()) errors.title = '工具标题不能为空。'
+  else if (form.title.trim().length > 160) errors.title = '工具标题不能超过 160 个字符。'
+  if (!slugPattern.test(form.slug.trim()) || form.slug.trim().length > 160) errors.slug = 'Slug 只能使用小写字母、数字和连字符。'
+  if (form.imageUrl.trim() && !httpsPattern.test(form.imageUrl.trim())) errors.imageUrl = '图片地址必须使用 https。'
+  if (form.type === 'EMBEDDED') {
+    if (!form.componentKey) errors.componentKey = '内嵌工具必须选择白名单组件。'
+    if (form.url.trim()) errors.url = '内嵌工具不能填写外部 URL。'
+  } else if (!httpsPattern.test(form.url.trim())) errors.url = '链接和展示工具必须填写 https URL。'
+  if (tags(form.tags).length > 32) errors.tags = '标签不能超过 32 个。'
+  return errors
+}
+
+export function toolFormSnapshot(form: ToolFormModel) {
+  const { id: _id, version: _version, ...content } = form
+  return JSON.stringify({ ...content, tags: tags(content.tags).sort() })
+}
+
+export type { ToolComponentKey, ToolStatus, ToolType }
diff --git a/apps/web/server/routes/api/[...path].ts b/apps/web/server/routes/api/[...path].ts
new file mode 100644
index 0000000..f1ad60f
--- /dev/null
+++ b/apps/web/server/routes/api/[...path].ts
@@ -0,0 +1,6 @@
+export default defineEventHandler((event) => {
+  const path = getRouterParam(event, 'path') || ''
+  const target = new URL(`/api/${path}`, useRuntimeConfig(event).apiBaseUrl)
+  target.search = getRequestURL(event).search
+  return proxyRequest(event, target.toString())
+})
diff --git a/apps/web/test/studio-tool-form.test.ts b/apps/web/test/studio-tool-form.test.ts
new file mode 100644
index 0000000..ebe852a
--- /dev/null
+++ b/apps/web/test/studio-tool-form.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { toolFormSnapshot, toolFormToCreateRequest, toolFormToUpdateRequest, toolToForm, validateToolForm } from '../app/utils/studioToolForm'
+
+describe('Studio tool form mapping', () => {
+  it('maps embedded tools without leaking URL fields and keeps version for updates', () => {
+    const form = toolToForm({ id: 'tool-1', categoryId: 'cat-1', type: 'EMBEDDED', status: 'ACTIVE', title: 'JSON', slug: 'json', description: null, url: null, imageUrl: null, componentKey: 'json-format', tags: ['json', 'format'], sortOrder: 2, version: 4, createdAt: '', updatedAt: '' })
+    expect(toolFormToCreateRequest(form)).toMatchObject({ categoryId: 'cat-1', componentKey: 'json-format', url: null, tags: ['json', 'format'] })
+    expect(toolFormToUpdateRequest(form)).toMatchObject({ version: 4, status: 'ACTIVE' })
+    expect(toolFormSnapshot(form)).not.toContain('version')
+  })
+
+  it('validates protocol and type/component field combinations', () => {
+    const form = toolToForm(null, 'cat-1')
+    form.title = 'JSON'; form.slug = 'json'; form.type = 'LINK'; form.url = 'http://example.com'
+    expect(validateToolForm(form).url).toContain('https')
+    form.type = 'EMBEDDED'; form.url = ''; form.componentKey = ''
+    expect(validateToolForm(form).componentKey).toBeTruthy()
+  })
+})
diff --git a/docs/openapi/public-api.yaml b/docs/openapi/public-api.yaml
index 1d55c9d..29937cc 100644
--- a/docs/openapi/public-api.yaml
+++ b/docs/openapi/public-api.yaml
@@ -667,6 +667,121 @@ paths:
         '403': { $ref: '#/components/responses/CsrfInvalid' }
         '404': { $ref: '#/components/responses/ResourceNotFound' }
         '409': { $ref: '#/components/responses/Conflict' }
+  /api/v1/admin/tool-categories:
+    get:
+      operationId: listAdminToolCategories
+      security: [{ sessionCookie: [] }]
+      responses:
+        '200': { description: Tool categories, content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/ToolCategoryResponse' } } } } }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+    post:
+      operationId: createAdminToolCategory
+      security: [{ sessionCookie: [] }]
+      parameters: [{ $ref: '#/components/parameters/CsrfHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ToolCategoryCreateRequest' } } } }
+      responses:
+        '201': { description: Tool category created, content: { application/json: { schema: { $ref: '#/components/schemas/ToolCategoryResponse' } } } }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/CsrfInvalid' }
+        '409': { $ref: '#/components/responses/Conflict' }
+  /api/v1/admin/tool-categories/{id}:
+    parameters: [{ name: id, in: path, required: true, schema: { type: string, format: uuid } }]
+    get:
+      operationId: getAdminToolCategory
+      security: [{ sessionCookie: [] }]
+      responses:
+        '200': { description: Tool category, content: { application/json: { schema: { $ref: '#/components/schemas/ToolCategoryResponse' } } } }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/ResourceNotFound' }
+    put:
+      operationId: updateAdminToolCategory
+      security: [{ sessionCookie: [] }]
+      parameters: [{ $ref: '#/components/parameters/CsrfHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ToolCategoryUpdateRequest' } } } }
+      responses:
+        '200': { description: Tool category updated, content: { application/json: { schema: { $ref: '#/components/schemas/ToolCategoryResponse' } } } }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/CsrfInvalid' }
+        '404': { $ref: '#/components/responses/ResourceNotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+    delete:
+      operationId: deleteAdminToolCategory
+      security: [{ sessionCookie: [] }]
+      parameters:
+        - { $ref: '#/components/parameters/CsrfHeader' }
+        - { name: version, in: query, required: true, schema: { type: integer, format: int64, minimum: 0 } }
+      responses:
+        '204': { description: Tool category deleted }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/CsrfInvalid' }
+        '404': { $ref: '#/components/responses/ResourceNotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+  /api/v1/admin/tools:
+    get:
+      operationId: listAdminTools
+      security: [{ sessionCookie: [] }]
+      parameters:
+        - { name: page, in: query, schema: { type: integer, minimum: 0, default: 0 } }
+        - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 50, default: 20 } }
+        - { name: categoryId, in: query, schema: { type: string, format: uuid } }
+        - { name: type, in: query, schema: { $ref: '#/components/schemas/ToolType' } }
+        - { name: status, in: query, schema: { $ref: '#/components/schemas/ToolStatus' } }
+        - { name: keyword, in: query, schema: { type: string, maxLength: 240 } }
+        - { name: sort, in: query, schema: { type: string, enum: [sortOrder, createdAt, updatedAt, title], default: sortOrder } }
+        - { name: direction, in: query, schema: { type: string, enum: [asc, desc], default: asc } }
+      responses:
+        '200': { description: Tools, content: { application/json: { schema: { $ref: '#/components/schemas/AdminToolListResponse' } } } }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+    post:
+      operationId: createAdminTool
+      security: [{ sessionCookie: [] }]
+      parameters: [{ $ref: '#/components/parameters/CsrfHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ToolCreateRequest' } } } }
+      responses:
+        '201': { description: Tool created, content: { application/json: { schema: { $ref: '#/components/schemas/ToolResponse' } } } }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/CsrfInvalid' }
+        '409': { $ref: '#/components/responses/Conflict' }
+  /api/v1/admin/tools/{id}:
+    parameters: [{ name: id, in: path, required: true, schema: { type: string, format: uuid } }]
+    get:
+      operationId: getAdminTool
+      security: [{ sessionCookie: [] }]
+      responses:
+        '200': { description: Tool, content: { application/json: { schema: { $ref: '#/components/schemas/ToolResponse' } } } }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/ResourceNotFound' }
+    put:
+      operationId: updateAdminTool
+      security: [{ sessionCookie: [] }]
+      parameters: [{ $ref: '#/components/parameters/CsrfHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ToolUpdateRequest' } } } }
+      responses:
+        '200': { description: Tool updated, content: { application/json: { schema: { $ref: '#/components/schemas/ToolResponse' } } } }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/CsrfInvalid' }
+        '404': { $ref: '#/components/responses/ResourceNotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+    delete:
+      operationId: deleteAdminTool
+      security: [{ sessionCookie: [] }]
+      parameters:
+        - { $ref: '#/components/parameters/CsrfHeader' }
+        - { name: version, in: query, required: true, schema: { type: integer, format: int64, minimum: 0 } }
+      responses:
+        '204': { description: Tool deleted }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/CsrfInvalid' }
+        '404': { $ref: '#/components/responses/ResourceNotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
   /api/v1/admin/session:
     post:
       operationId: loginAdmin
@@ -1267,6 +1382,82 @@ components:
         slug: { type: string }
         createdAt: { type: string, format: date-time }
         updatedAt: { type: string, format: date-time }
+    ToolType:
+      type: string
+      enum: [LINK, EMBEDDED, SHOWCASE]
+    ToolStatus:
+      type: string
+      enum: [ACTIVE, INACTIVE]
+    ToolComponentKey:
+      type: string
+      enum: [json-format, base64, url-codec, timestamp, regex-test]
+    ToolCategoryCreateRequest:
+      type: object
+      required: [name, slug]
+      properties:
+        name: { type: string, minLength: 1, maxLength: 120 }
+        slug: { type: string, minLength: 1, maxLength: 160 }
+        description: { type: [string, 'null'], maxLength: 600 }
+        sortOrder: { type: integer }
+    ToolCategoryUpdateRequest:
+      allOf:
+        - $ref: '#/components/schemas/ToolCategoryCreateRequest'
+        - type: object
+          required: [version]
+          properties:
+            version: { type: integer, format: int64, minimum: 0 }
+    ToolCategoryResponse:
+      type: object
+      required: [id, name, slug, sortOrder, version, createdAt, updatedAt]
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string }
+        slug: { type: string }
+        description: { type: [string, 'null'] }
+        sortOrder: { type: integer }
+        version: { type: integer, format: int64, minimum: 0 }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+    ToolCreateRequest:
+      type: object
+      required: [categoryId, type, status, title, slug, tags]
+      properties:
+        categoryId: { type: string, format: uuid }
+        type: { $ref: '#/components/schemas/ToolType' }
+        status: { $ref: '#/components/schemas/ToolStatus' }
+        title: { type: string, minLength: 1, maxLength: 160 }
+        slug: { type: string, minLength: 1, maxLength: 160 }
+        description: { type: [string, 'null'], maxLength: 600 }
+        url: { type: [string, 'null'], format: uri, pattern: '^https://' }
+        imageUrl: { type: [string, 'null'], format: uri, pattern: '^https://' }
+        componentKey: { oneOf: [{ $ref: '#/components/schemas/ToolComponentKey' }, { type: 'null' }] }
+        tags: { type: array, maxItems: 32, items: { type: string, minLength: 1, maxLength: 64 } }
+        sortOrder: { type: integer }
+    ToolUpdateRequest:
+      allOf:
+        - $ref: '#/components/schemas/ToolCreateRequest'
+        - type: object
+          required: [version]
+          properties:
+            version: { type: integer, format: int64, minimum: 0 }
+    ToolResponse:
+      allOf:
+        - $ref: '#/components/schemas/ToolCreateRequest'
+        - type: object
+          required: [id, version, createdAt, updatedAt]
+          properties:
+            id: { type: string, format: uuid }
+            version: { type: integer, format: int64, minimum: 0 }
+            createdAt: { type: string, format: date-time }
+            updatedAt: { type: string, format: date-time }
+    AdminToolListResponse:
+      type: object
+      required: [items, page, size, total]
+      properties:
+        items: { type: array, items: { $ref: '#/components/schemas/ToolResponse' } }
+        page: { type: integer }
+        size: { type: integer }
+        total: { type: integer, format: int64 }
   headers:
     ETag:
       description: Entity tag for the public representation
diff --git a/packages/api-client/src/generated.ts b/packages/api-client/src/generated.ts
index 675c8c5..0deca5e 100644
--- a/packages/api-client/src/generated.ts
+++ b/packages/api-client/src/generated.ts
@@ -518,6 +518,74 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/admin/tool-categories": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["listAdminToolCategories"];
+        put?: never;
+        post: operations["createAdminToolCategory"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/admin/tool-categories/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        get: operations["getAdminToolCategory"];
+        put: operations["updateAdminToolCategory"];
+        post?: never;
+        delete: operations["deleteAdminToolCategory"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/admin/tools": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["listAdminTools"];
+        put?: never;
+        post: operations["createAdminTool"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/admin/tools/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        get: operations["getAdminTool"];
+        put: operations["updateAdminTool"];
+        post?: never;
+        delete: operations["deleteAdminTool"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/admin/session": {
         parameters: {
             query?: never;
@@ -1001,6 +1069,73 @@ export interface components {
             /** Format: date-time */
             updatedAt: string;
         };
+        /** @enum {string} */
+        ToolType: "LINK" | "EMBEDDED" | "SHOWCASE";
+        /** @enum {string} */
+        ToolStatus: "ACTIVE" | "INACTIVE";
+        /** @enum {string} */
+        ToolComponentKey: "json-format" | "base64" | "url-codec" | "timestamp" | "regex-test";
+        ToolCategoryCreateRequest: {
+            name: string;
+            slug: string;
+            description?: string | null;
+            sortOrder?: number;
+        };
+        ToolCategoryUpdateRequest: components["schemas"]["ToolCategoryCreateRequest"] & {
+            /** Format: int64 */
+            version: number;
+        };
+        ToolCategoryResponse: {
+            /** Format: uuid */
+            id: string;
+            name: string;
+            slug: string;
+            description?: string | null;
+            sortOrder: number;
+            /** Format: int64 */
+            version: number;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            updatedAt: string;
+        };
+        ToolCreateRequest: {
+            /** Format: uuid */
+            categoryId: string;
+            type: components["schemas"]["ToolType"];
+            status: components["schemas"]["ToolStatus"];
+            title: string;
+            slug: string;
+            description?: string | null;
+            /** Format: uri */
+            url?: string | null;
+            /** Format: uri */
+            imageUrl?: string | null;
+            componentKey?: components["schemas"]["ToolComponentKey"] | null;
+            tags: string[];
+            sortOrder?: number;
+        };
+        ToolUpdateRequest: components["schemas"]["ToolCreateRequest"] & {
+            /** Format: int64 */
+            version: number;
+        };
+        ToolResponse: components["schemas"]["ToolCreateRequest"] & {
+            /** Format: uuid */
+            id: string;
+            /** Format: int64 */
+            version: number;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            updatedAt: string;
+        };
+        AdminToolListResponse: {
+            items: components["schemas"]["ToolResponse"][];
+            page: number;
+            size: number;
+            /** Format: int64 */
+            total: number;
+        };
     };
     responses: {
         /** @description Invalid request */
@@ -2420,6 +2555,291 @@ export interface operations {
             409: components["responses"]["Conflict"];
         };
     };
+    listAdminToolCategories: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Tool categories */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ToolCategoryResponse"][];
+                };
+            };
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    createAdminToolCategory: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-CSRF-TOKEN": components["parameters"]["CsrfHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ToolCategoryCreateRequest"];
+            };
+        };
+        responses: {
+            /** @description Tool category created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ToolCategoryResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["CsrfInvalid"];
+            409: components["responses"]["Conflict"];
+        };
+    };
+    getAdminToolCategory: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Tool category */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ToolCategoryResponse"];
+                };
+            };
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["ResourceNotFound"];
+        };
+    };
+    updateAdminToolCategory: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-CSRF-TOKEN": components["parameters"]["CsrfHeader"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ToolCategoryUpdateRequest"];
+            };
+        };
+        responses: {
+            /** @description Tool category updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ToolCategoryResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["CsrfInvalid"];
+            404: components["responses"]["ResourceNotFound"];
+            409: components["responses"]["Conflict"];
+        };
+    };
+    deleteAdminToolCategory: {
+        parameters: {
+            query: {
+                version: number;
+            };
+            header: {
+                "X-CSRF-TOKEN": components["parameters"]["CsrfHeader"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Tool category deleted */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["CsrfInvalid"];
+            404: components["responses"]["ResourceNotFound"];
+            409: components["responses"]["Conflict"];
+        };
+    };
+    listAdminTools: {
+        parameters: {
+            query?: {
+                page?: number;
+                size?: number;
+                categoryId?: string;
+                type?: components["schemas"]["ToolType"];
+                status?: components["schemas"]["ToolStatus"];
+                keyword?: string;
+                sort?: "sortOrder" | "createdAt" | "updatedAt" | "title";
+                direction?: "asc" | "desc";
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Tools */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdminToolListResponse"];
+                };
+            };
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    createAdminTool: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-CSRF-TOKEN": components["parameters"]["CsrfHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ToolCreateRequest"];
+            };
+        };
+        responses: {
+            /** @description Tool created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ToolResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["CsrfInvalid"];
+            409: components["responses"]["Conflict"];
+        };
+    };
+    getAdminTool: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Tool */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ToolResponse"];
+                };
+            };
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["ResourceNotFound"];
+        };
+    };
+    updateAdminTool: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-CSRF-TOKEN": components["parameters"]["CsrfHeader"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ToolUpdateRequest"];
+            };
+        };
+        responses: {
+            /** @description Tool updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ToolResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["CsrfInvalid"];
+            404: components["responses"]["ResourceNotFound"];
+            409: components["responses"]["Conflict"];
+        };
+    };
+    deleteAdminTool: {
+        parameters: {
+            query: {
+                version: number;
+            };
+            header: {
+                "X-CSRF-TOKEN": components["parameters"]["CsrfHeader"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Tool deleted */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["Unauthenticated"];
+            403: components["responses"]["CsrfInvalid"];
+            404: components["responses"]["ResourceNotFound"];
+            409: components["responses"]["Conflict"];
+        };
+    };
     getAdminSession: {
         parameters: {
             query?: never;

From a18a7de786fb0b54e3958e00fc1492da4c25f5da Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 14:03:03 +0800
Subject: [PATCH 08/15] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E7=94=9F=E4=BA=A7?=
 =?UTF-8?q?=E7=8E=AF=E5=A2=83=E9=82=AE=E4=BB=B6=E5=81=A5=E5=BA=B7=E6=A3=80?=
 =?UTF-8?q?=E6=9F=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 apps/api/src/main/resources/application.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/api/src/main/resources/application.yml b/apps/api/src/main/resources/application.yml
index 4c2db88..0cfb731 100644
--- a/apps/api/src/main/resources/application.yml
+++ b/apps/api/src/main/resources/application.yml
@@ -50,6 +50,9 @@ management:
   endpoint:
     health:
       show-details: never
+  health:
+    mail:
+      enabled: ${HAOBLOG_COMMENT_NOTIFICATION_ENABLED:false}
 server:
   port: ${API_PORT:8080}
   tomcat:

From 6c245701afdf398fcb98b0b5ab0be9b56561c15a Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 15:00:07 +0800
Subject: [PATCH 09/15] =?UTF-8?q?=E5=AE=8C=E6=88=90=E5=85=AC=E5=85=B1?=
 =?UTF-8?q?=E5=B7=A5=E5=85=B7=E7=9B=AE=E5=BD=95=20API=20=E4=B8=8E=E6=9E=81?=
 =?UTF-8?q?=E5=A4=9C=E8=A7=82=E6=B5=8B=E7=AB=99=E9=A1=B5=E9=9D=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../site/application/PublicFeedService.java   |   4 +-
 .../application/ToolManagementService.java    |  71 ++++++
 .../toolbox/persistence/ToolRepository.java   |   4 +
 .../toolbox/web/PublicToolController.java     |  77 ++++++
 .../src/test/java/io/haoblog/PublicApiIT.java |   2 +-
 .../src/test/java/io/haoblog/ToolAdminIT.java |  45 +++-
 .../application/PublicFeedServiceTest.java    |   2 +-
 apps/web/app/pages/tools.vue                  | 236 +++++++++++++++++-
 apps/web/e2e/stage3.spec.ts                   |   1 +
 apps/web/e2e/stage4.spec.ts                   |  83 ++++++
 apps/web/nuxt.config.ts                       |   1 -
 docs/openapi/public-api.yaml                  |  65 +++++
 infra/compose/compose.dev.yml                 |   1 +
 packages/api-client/src/generated.ts          |  84 +++++++
 14 files changed, 668 insertions(+), 8 deletions(-)
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/web/PublicToolController.java

diff --git a/apps/api/src/main/java/io/haoblog/site/application/PublicFeedService.java b/apps/api/src/main/java/io/haoblog/site/application/PublicFeedService.java
index 7d09e95..5ffd22b 100644
--- a/apps/api/src/main/java/io/haoblog/site/application/PublicFeedService.java
+++ b/apps/api/src/main/java/io/haoblog/site/application/PublicFeedService.java
@@ -23,7 +23,7 @@ public class PublicFeedService {
     private static final int RSS_LIMIT = 20;
     private static final int SITEMAP_BATCH_SIZE = 500;
     private static final int SITEMAP_URL_LIMIT = 50_000;
-    private static final int STATIC_URL_COUNT = 3;
+    private static final int STATIC_URL_COUNT = 4;
     private static final DateTimeFormatter RSS_DATE_FORMAT = DateTimeFormatter.RFC_1123_DATE_TIME;
     private final SiteService siteService;
     private final ArticleService articleService;
@@ -104,7 +104,7 @@ private static String writeSitemap(SiteService.SiteResult site, List<PublicFeedA
         return write(writer -> {
             writer.writeStartElement("urlset");
             writer.writeDefaultNamespace("http://www.sitemaps.org/schemas/sitemap/0.9");
-            for (String path : List.of("/", "/articles", "/about")) {
+            for (String path : List.of("/", "/articles", "/tools", "/about")) {
                 urlElement(writer, url(site.siteUrl(), path));
             }
             for (var article : articles) {
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/application/ToolManagementService.java b/apps/api/src/main/java/io/haoblog/toolbox/application/ToolManagementService.java
index cc4f0fe..c5567a1 100644
--- a/apps/api/src/main/java/io/haoblog/toolbox/application/ToolManagementService.java
+++ b/apps/api/src/main/java/io/haoblog/toolbox/application/ToolManagementService.java
@@ -18,7 +18,12 @@
 import java.time.Clock;
 import java.time.Instant;
 import java.util.List;
+import java.util.Locale;
+import java.util.Map;
 import java.util.UUID;
+import java.util.function.Predicate;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 @Service
 public class ToolManagementService {
@@ -35,6 +40,60 @@ public ToolManagementService(ToolCategoryRepository categories, ToolRepository t
     @Transactional(readOnly = true)
     public List<ToolCategory> listCategories() { return categories.findAllByOrderBySortOrderAscNameAsc(); }
 
+    @Transactional(readOnly = true)
+    public PublicTools listPublicTools(String category, ToolType type, String keyword) {
+        String normalizedCategory = category == null || category.isBlank() ? null : category.trim();
+        if (normalizedCategory != null && normalizedCategory.length() > 160) {
+            throw new IllegalArgumentException("category is too long");
+        }
+        String normalizedKeyword = keyword == null || keyword.isBlank() ? null : keyword.trim();
+        if (normalizedKeyword != null && normalizedKeyword.length() > 240) {
+            throw new IllegalArgumentException("keyword is too long");
+        }
+        return queryPublicTools(normalizedCategory, type, normalizedKeyword);
+    }
+
+    private PublicTools queryPublicTools(String normalizedCategory, ToolType type, String normalizedKeyword) {
+
+        List<Tool> activeTools = tools.findAllByStatus(ToolStatus.ACTIVE,
+                Sort.by(Sort.Direction.ASC, "sortOrder", "title", "id"));
+        Map<UUID, ToolCategory> categoryById = categories.findAllById(
+                activeTools.stream().map(Tool::getCategoryId).distinct().toList()).stream()
+                .collect(Collectors.toMap(ToolCategory::getId, categoryValue -> categoryValue));
+        Predicate<Tool> categoryFilter = categoryPredicate(normalizedCategory, categoryById);
+        String keywordValue = normalizedKeyword == null ? null : normalizedKeyword.toLowerCase(Locale.ROOT);
+        List<PublicTool> items = activeTools.stream()
+                .filter(tool -> type == null || tool.getType() == type)
+                .filter(categoryFilter)
+                .filter(tool -> keywordValue == null || containsKeyword(tool, keywordValue))
+                .map(tool -> PublicTool.from(tool, categoryById.get(tool.getCategoryId())))
+                .filter(tool -> tool.category() != null)
+                .toList();
+        List<ToolCategory> validCategories = items.stream().map(PublicTool::category).distinct()
+                .sorted(java.util.Comparator.comparingInt(ToolCategory::getSortOrder)
+                        .thenComparing(ToolCategory::getName)
+                        .thenComparing(ToolCategory::getId))
+                .toList();
+        return new PublicTools(items, validCategories);
+    }
+
+    private static Predicate<Tool> categoryPredicate(String category, Map<UUID, ToolCategory> categoryById) {
+        if (category == null) return ignored -> true;
+        return tool -> {
+            ToolCategory value = categoryById.get(tool.getCategoryId());
+            return value != null && (value.getSlug().equalsIgnoreCase(category)
+                    || value.getId().toString().equalsIgnoreCase(category));
+        };
+    }
+
+    private static boolean containsKeyword(Tool tool, String keyword) {
+        return Stream.of(tool.getTitle(), tool.getSlug(), tool.getDescription())
+                .filter(java.util.Objects::nonNull)
+                .map(value -> value.toLowerCase(Locale.ROOT))
+                .anyMatch(value -> value.contains(keyword))
+                || tool.getTags().stream().anyMatch(tag -> tag.toLowerCase(Locale.ROOT).contains(keyword));
+    }
+
     @Transactional
     public ToolCategory createCategory(String name, String slug, String description, int sortOrder) {
         validateCategory(name, slug, description);
@@ -164,4 +223,16 @@ private static String allowedSort(String sort) {
     }
     private static ProblemException notFound(String code) { return new ProblemException(code, "Resource not found", "The requested toolbox resource was not found"); }
     private static ProblemException conflict(String code, String title, String detail) { return new ProblemException(code, title, detail); }
+
+    public record PublicTools(List<PublicTool> items, List<ToolCategory> categories) {}
+
+    public record PublicTool(UUID id, ToolCategory category, ToolType type, String title, String slug,
+                             String description, String url, String imageUrl, String componentKey, List<String> tags,
+                             int sortOrder) {
+        static PublicTool from(Tool tool, ToolCategory category) {
+            return new PublicTool(tool.getId(), category, tool.getType(), tool.getTitle(), tool.getSlug(), tool.getDescription(),
+                    tool.getUrl(), tool.getImageUrl(), tool.getComponentKey() == null ? null : tool.getComponentKey().getValue(),
+                    tool.getTags(), tool.getSortOrder());
+        }
+    }
 }
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolRepository.java b/apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolRepository.java
index 601321d..404647d 100644
--- a/apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolRepository.java
+++ b/apps/api/src/main/java/io/haoblog/toolbox/persistence/ToolRepository.java
@@ -1,13 +1,17 @@
 package io.haoblog.toolbox.persistence;
 
 import io.haoblog.toolbox.domain.Tool;
+import io.haoblog.toolbox.domain.ToolStatus;
+import org.springframework.data.domain.Sort;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
 
+import java.util.List;
 import java.util.UUID;
 
 public interface ToolRepository extends JpaRepository<Tool, UUID>, JpaSpecificationExecutor<Tool> {
     boolean existsByCategoryId(UUID categoryId);
     boolean existsBySlug(String slug);
     boolean existsBySlugAndIdNot(String slug, UUID id);
+    List<Tool> findAllByStatus(ToolStatus status, Sort sort);
 }
diff --git a/apps/api/src/main/java/io/haoblog/toolbox/web/PublicToolController.java b/apps/api/src/main/java/io/haoblog/toolbox/web/PublicToolController.java
new file mode 100644
index 0000000..f01a746
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/web/PublicToolController.java
@@ -0,0 +1,77 @@
+package io.haoblog.toolbox.web;
+
+import io.haoblog.toolbox.application.ToolManagementService;
+import io.haoblog.toolbox.domain.ToolCategory;
+import io.haoblog.toolbox.domain.ToolType;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.HexFormat;
+import java.util.List;
+import java.util.UUID;
+
+@RestController
+@RequestMapping("/api/v1/public/tools")
+public class PublicToolController {
+    private final ToolManagementService service;
+
+    public PublicToolController(ToolManagementService service) {
+        this.service = service;
+    }
+
+    @GetMapping
+    public ResponseEntity<Response> list(
+            @RequestParam(required = false) String category,
+            @RequestParam(required = false) ToolType type,
+            @RequestParam(required = false) String keyword,
+            @RequestHeader(value = HttpHeaders.IF_NONE_MATCH, required = false) String ifNoneMatch) {
+        ToolManagementService.PublicTools result = service.listPublicTools(category, type, keyword);
+        Response response = Response.from(result);
+        String etag = representationHash(response);
+        var headers = new HttpHeaders();
+        headers.setETag(etag);
+        headers.setCacheControl("public, max-age=0, s-maxage=60, must-revalidate");
+        if (etag.equals(ifNoneMatch)) {
+            return ResponseEntity.status(304).headers(headers).build();
+        }
+        return ResponseEntity.ok().headers(headers).body(response);
+    }
+
+    private static String representationHash(Object value) {
+        try {
+            var digest = MessageDigest.getInstance("SHA-256");
+            return '"' + HexFormat.of().formatHex(digest.digest(value.toString().getBytes(StandardCharsets.UTF_8))) + '"';
+        } catch (Exception exception) {
+            throw new IllegalStateException("Unable to create public tools ETag", exception);
+        }
+    }
+
+    public record Response(List<ToolResponse> items, List<CategoryResponse> categories) {
+        static Response from(ToolManagementService.PublicTools value) {
+            return new Response(value.items().stream().map(ToolResponse::from).toList(),
+                    value.categories().stream().map(CategoryResponse::from).toList());
+        }
+    }
+
+    public record CategoryResponse(UUID id, String name, String slug, String description, int sortOrder) {
+        static CategoryResponse from(ToolCategory value) {
+            return new CategoryResponse(value.getId(), value.getName(), value.getSlug(), value.getDescription(), value.getSortOrder());
+        }
+    }
+
+    public record ToolResponse(UUID id, CategoryResponse category, ToolType type, String title, String slug,
+                               String description, String url, String imageUrl, String componentKey, List<String> tags,
+                               int sortOrder) {
+        static ToolResponse from(ToolManagementService.PublicTool value) {
+            return new ToolResponse(value.id(), CategoryResponse.from(value.category()), value.type(), value.title(), value.slug(),
+                    value.description(), value.url(), value.imageUrl(), value.componentKey(), value.tags(), value.sortOrder());
+        }
+    }
+}
diff --git a/apps/api/src/test/java/io/haoblog/PublicApiIT.java b/apps/api/src/test/java/io/haoblog/PublicApiIT.java
index afb405b..87294ae 100644
--- a/apps/api/src/test/java/io/haoblog/PublicApiIT.java
+++ b/apps/api/src/test/java/io/haoblog/PublicApiIT.java
@@ -140,7 +140,7 @@ static void database(DynamicPropertyRegistry registry) {
                 .andExpect(content().string(org.hamcrest.Matchers.not(org.hamcrest.Matchers.containsString("scheduled-feed"))))
                 .andExpect(header().exists("ETag"))
                 .andReturn();
-        assertEquals(5, count(sitemap.getResponse().getContentAsString(), "<url>"));
+        assertEquals(6, count(sitemap.getResponse().getContentAsString(), "<url>"));
         mvc.perform(get("/sitemap.xml").header("If-None-Match", sitemap.getResponse().getHeader("ETag")))
                 .andExpect(status().isNotModified()).andExpect(content().string(""));
     }
diff --git a/apps/api/src/test/java/io/haoblog/ToolAdminIT.java b/apps/api/src/test/java/io/haoblog/ToolAdminIT.java
index f66b67b..6523179 100644
--- a/apps/api/src/test/java/io/haoblog/ToolAdminIT.java
+++ b/apps/api/src/test/java/io/haoblog/ToolAdminIT.java
@@ -15,6 +15,7 @@
 import org.testcontainers.containers.PostgreSQLContainer;
 import org.testcontainers.junit.jupiter.Container;
 import org.testcontainers.junit.jupiter.Testcontainers;
+import org.junit.jupiter.api.BeforeEach;
 
 import java.sql.Timestamp;
 import java.time.Instant;
@@ -29,6 +30,7 @@
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
@@ -52,6 +54,11 @@ static void database(DynamicPropertyRegistry registry) {
     @Autowired ObjectMapper objectMapper;
     @Autowired JdbcTemplate jdbc;
 
+    @BeforeEach
+    void cleanToolTables() {
+        jdbc.execute("TRUNCATE tool, tool_category CASCADE");
+    }
+
     @Test
     void migrationStartsWithEmptyToolTablesAndWritesNeedAuthAndCsrf() throws Exception {
         assertNotNull(jdbc.queryForObject("select to_regclass('tool_category')", String.class));
@@ -103,6 +110,41 @@ void databaseConstraintsRejectArbitraryComponentAndNonArrayTags() {
                 UUID.randomUUID(), categoryId, "EMBEDDED", "ACTIVE", "Invalid", "invalid-" + categoryId.toString().substring(0, 8), "arbitrary-path", "{}", now, now));
     }
 
+    @Test
+    void publicDirectoryReturnsActiveToolsValidCategoriesAndSupportsConditionalFilters() throws Exception {
+        String categoryId = createCategory();
+        createTool(categoryId, "json-link", "JSON Link", "LINK", "https://example.com/json", null);
+        createTool(categoryId, "json-format", "JSON Format", "EMBEDDED", null, "json-format");
+        tool(categoryId, "{\"type\":\"LINK\",\"url\":\"https://example.com/hidden\",\"title\":\"Hidden\",\"slug\":\"hidden\",\"tags\":[],\"status\":\"INACTIVE\"}")
+                .andExpect(status().isCreated());
+
+        var directory = mvc.perform(get("/api/v1/public/tools"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.items.length()", org.hamcrest.Matchers.is(2)))
+                .andExpect(jsonPath("$.categories.length()", org.hamcrest.Matchers.is(1)))
+                .andExpect(jsonPath("$.items[0].category.slug").isNotEmpty())
+                .andExpect(jsonPath("$.items[0].tags").isArray())
+                .andExpect(header().string("Cache-Control", org.hamcrest.Matchers.containsString("s-maxage=60")))
+                .andExpect(header().exists("ETag"))
+                .andReturn();
+        String etag = directory.getResponse().getHeader("ETag");
+        mvc.perform(get("/api/v1/public/tools").header("If-None-Match", etag))
+                .andExpect(status().isNotModified()).andExpect(content().string(""));
+        mvc.perform(get("/api/v1/public/tools?type=EMBEDDED&keyword=json"))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.items.length()", org.hamcrest.Matchers.is(1)))
+                .andExpect(jsonPath("$.items[0].componentKey").value("json-format"));
+        mvc.perform(get("/api/v1/public/tools?category=" + categoryId))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.items.length()", org.hamcrest.Matchers.is(2)));
+    }
+
+    @Test
+    void publicDirectoryHasExplicitEmptyState() throws Exception {
+        mvc.perform(get("/api/v1/public/tools?keyword=not-present-" + UUID.randomUUID()))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.items").isEmpty())
+                .andExpect(jsonPath("$.categories").isEmpty());
+    }
+
     private String createCategory() throws Exception {
         String suffix = UUID.randomUUID().toString().substring(0, 8);
         var result = mvc.perform(post("/api/v1/admin/tool-categories").with(admin()).with(csrf()).contentType(MediaType.APPLICATION_JSON)
@@ -113,7 +155,8 @@ private String createCategory() throws Exception {
 
     private org.springframework.test.web.servlet.ResultActions tool(String categoryId, String body) throws Exception {
         String base = body.substring(0, body.length() - 1);
-        String payload = base + ",\"categoryId\":\"" + categoryId + "\",\"status\":\"ACTIVE\"}";
+        String payload = base + ",\"categoryId\":\"" + categoryId + "\""
+                + (body.contains("\"status\"") ? "" : ",\"status\":\"ACTIVE\"") + "}";
         return mvc.perform(post("/api/v1/admin/tools").with(admin()).with(csrf()).contentType(MediaType.APPLICATION_JSON).content(payload));
     }
 
diff --git a/apps/api/src/test/java/io/haoblog/site/application/PublicFeedServiceTest.java b/apps/api/src/test/java/io/haoblog/site/application/PublicFeedServiceTest.java
index 50cc263..e98f62b 100644
--- a/apps/api/src/test/java/io/haoblog/site/application/PublicFeedServiceTest.java
+++ b/apps/api/src/test/java/io/haoblog/site/application/PublicFeedServiceTest.java
@@ -55,7 +55,7 @@ void sitemapReadsPublishedArticlesInFiveHundredItemBatches() throws Exception {
 
         Document xml = parse(new PublicFeedService(siteService, articleService).sitemap().body());
 
-        assertEquals(505, xml.getElementsByTagNameNS("http://www.sitemaps.org/schemas/sitemap/0.9", "url").getLength());
+        assertEquals(506, xml.getElementsByTagNameNS("http://www.sitemaps.org/schemas/sitemap/0.9", "url").getLength());
         verify(articleService).listPublishedBatch(eq(0), eq(500));
         verify(articleService).listPublishedBatch(eq(1), eq(500));
     }
diff --git a/apps/web/app/pages/tools.vue b/apps/web/app/pages/tools.vue
index c37d2c8..aef25f0 100644
--- a/apps/web/app/pages/tools.vue
+++ b/apps/web/app/pages/tools.vue
@@ -1,5 +1,237 @@
 <script setup lang="ts">
-useHead({ title: '工具箱', meta: [{ name: 'robots', content: 'noindex,nofollow' }] })
+import type { components } from '@haoblog/api-client'
+
+type PublicTools = components['schemas']['PublicToolListResponse']
+type PublicTool = components['schemas']['PublicToolResponse']
+type SortMode = 'stable' | 'favorites' | 'frequent'
+
+useHead({
+  title: '工具目录｜极夜观测站',
+  meta: [{ name: 'description', content: '极夜观测站的公共工具目录：按分类、类型和关键词定位可用工具。' }],
+})
+
+const emptyTools: PublicTools = { items: [], categories: [] }
+const { data, error } = await usePublicApi<PublicTools>('/api/v1/public/tools', {
+  key: 'public-tools',
+  default: () => emptyTools,
+})
+
+const category = ref('')
+const type = ref('')
+const keyword = ref('')
+const sortMode = ref<SortMode>('stable')
+const favorites = ref(new Set<string>())
+const usage = ref<Record<string, { count: number; lastUsed: string }>>({})
+const expanded = ref(new Set<string>())
+
+const tools = computed(() => data.value?.items || [])
+const categories = computed(() => data.value?.categories || [])
+const filteredTools = computed(() => {
+  const query = keyword.value.trim().toLocaleLowerCase()
+  const result = tools.value.filter((tool) => {
+    if (category.value && tool.category.slug !== category.value) return false
+    if (type.value && tool.type !== type.value) return false
+    if (!query) return true
+    return [tool.title, tool.slug, tool.description || '', tool.category.name, ...tool.tags]
+      .join(' ')
+      .toLocaleLowerCase()
+      .includes(query)
+  })
+  if (sortMode.value === 'stable') return result
+  const mode = sortMode.value as Exclude<SortMode, 'stable'>
+  return [...result].sort((left, right) => compareTools(left, right, mode))
+})
+
+onMounted(() => {
+  favorites.value = readFavorites()
+  usage.value = readUsage()
+})
+
+function compareTools(left: PublicTool, right: PublicTool, mode: Exclude<SortMode, 'stable'>) {
+  const leftUsage = usage.value[left.id] || { count: 0, lastUsed: '' }
+  const rightUsage = usage.value[right.id] || { count: 0, lastUsed: '' }
+  if (mode === 'favorites') {
+    const favoriteOrder = Number(favorites.value.has(right.id)) - Number(favorites.value.has(left.id))
+    if (favoriteOrder) return favoriteOrder
+  }
+  const countOrder = rightUsage.count - leftUsage.count
+  if (countOrder) return countOrder
+  const recentOrder = rightUsage.lastUsed.localeCompare(leftUsage.lastUsed)
+  if (recentOrder) return recentOrder
+  return stableToolOrder(left, right)
+}
+
+function stableToolOrder(left: PublicTool, right: PublicTool) {
+  return left.sortOrder - right.sortOrder || left.title.localeCompare(right.title) || left.id.localeCompare(right.id)
+}
+
+function toggleFavorite(tool: PublicTool) {
+  const next = new Set(favorites.value)
+  if (next.has(tool.id)) next.delete(tool.id)
+  else next.add(tool.id)
+  favorites.value = next
+  localStorage.setItem('haoblog-tool-favorites', JSON.stringify([...next]))
+}
+
+function toggleTool(tool: PublicTool) {
+  const next = new Set(expanded.value)
+  if (next.has(tool.id)) next.delete(tool.id)
+  else {
+    next.add(tool.id)
+    markUsed(tool)
+  }
+  expanded.value = next
+}
+
+function markUsed(tool: PublicTool) {
+  const next = { ...usage.value, [tool.id]: { count: (usage.value[tool.id]?.count || 0) + 1, lastUsed: new Date().toISOString() } }
+  usage.value = next
+  localStorage.setItem('haoblog-tool-usage', JSON.stringify(next))
+}
+
+function readFavorites() {
+  try {
+    const value: unknown = JSON.parse(localStorage.getItem('haoblog-tool-favorites') || '[]')
+    return new Set(Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [])
+  } catch { return new Set<string>() }
+}
+
+function readUsage() {
+  try {
+    const value: unknown = JSON.parse(localStorage.getItem('haoblog-tool-usage') || '{}')
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => {
+      return item && typeof item === 'object' && typeof (item as { count?: unknown }).count === 'number' && typeof (item as { lastUsed?: unknown }).lastUsed === 'string'
+    })) as Record<string, { count: number; lastUsed: string }>
+  } catch { return {} }
+}
+
+function safeExternalUrl(url: string | null) {
+  if (!url) return null
+  try {
+    const value = new URL(url)
+    return value.protocol === 'https:' && !value.username && !value.password ? value.toString() : null
+  } catch { return null }
+}
 </script>
 
-<template><section class="observation-scene" aria-labelledby="tools-title"><p class="instrument-label">TOOLBOX / SWITCHBOARD</p><h1 id="tools-title">工具箱</h1><p class="signal-copy">轻量工具控制台即将接入。</p></section></template>
+<template>
+  <section class="tools-scene" aria-labelledby="tools-title">
+    <header class="tools-heading">
+      <div>
+        <p class="instrument-label">TOOLBOX / SWITCHBOARD / PUBLIC SIGNAL</p>
+        <h1 id="tools-title">工具目录</h1>
+        <p class="signal-copy">把常用的工程信号收进一台安静的控制台。选择分类、类型或关键词，展开一行即可查看入口。</p>
+      </div>
+      <p class="console-readout" aria-label="工具目录状态"><span class="status-light" aria-hidden="true" /> {{ filteredTools.length }} SIGNALS / ACTIVE ONLY</p>
+    </header>
+
+    <form class="tool-filters" aria-label="工具目录筛选" @submit.prevent>
+      <label>分类<select v-model="category"><option value="">全部分类</option><option v-for="item in categories" :key="item.id" :value="item.slug">{{ item.name }}</option></select></label>
+      <label>类型<select v-model="type"><option value="">全部类型</option><option value="EMBEDDED">EMBEDDED</option><option value="LINK">LINK</option><option value="SHOWCASE">SHOWCASE</option></select></label>
+      <label class="keyword-filter">关键词<input v-model="keyword" type="search" placeholder="title / tag / command" autocomplete="off"></label>
+      <div class="sort-controls" role="group" aria-label="工具排序">
+        <span class="filter-label">排序</span>
+        <button type="button" :aria-pressed="sortMode === 'stable'" @click="sortMode = 'stable'">默认</button>
+        <button type="button" :aria-pressed="sortMode === 'favorites'" @click="sortMode = 'favorites'">收藏优先</button>
+        <button type="button" :aria-pressed="sortMode === 'frequent'" @click="sortMode = 'frequent'">最常用</button>
+      </div>
+    </form>
+
+    <p v-if="error" class="tool-empty" role="status">工具目录暂时无法接入，请稍后重试。</p>
+    <div v-else-if="!tools.length" class="tool-empty" role="status">
+      <span class="empty-code">NO ACTIVE SIGNAL</span>
+      <strong>当前没有可公开使用的工具。</strong>
+      <span>目录将在工具完成校准后重新开放。</span>
+    </div>
+    <div v-else-if="!filteredTools.length" class="tool-empty" role="status">
+      <span class="empty-code">FILTER / 0</span>
+      <strong>没有匹配的工具信号。</strong>
+      <span>尝试清除一个筛选条件。</span>
+    </div>
+    <ol v-else class="tool-console" aria-label="公共工具目录">
+      <li v-for="(tool, index) in filteredTools" :key="tool.id" class="tool-entry" :data-expanded="expanded.has(tool.id)">
+        <div class="tool-row">
+          <span class="tool-index" aria-hidden="true">{{ String(index + 1).padStart(2, '0') }}</span>
+          <span class="tool-signal" aria-hidden="true" />
+          <div class="tool-identity">
+            <strong>{{ tool.title }}</strong>
+            <span>{{ tool.slug }}</span>
+          </div>
+          <div class="tool-metadata">
+            <span>{{ tool.category.name }}</span>
+            <span>{{ tool.type }} / ACTIVE</span>
+            <span v-for="tag in tool.tags" :key="`${tool.id}-${tag}`">#{{ tag }}</span>
+          </div>
+          <button class="tool-favorite" type="button" :aria-pressed="favorites.has(tool.id)" :aria-label="`${favorites.has(tool.id) ? '取消收藏' : '收藏'} ${tool.title}`" @click="toggleFavorite(tool)">{{ favorites.has(tool.id) ? 'FAV' : 'SAVE' }}</button>
+          <button class="tool-unfold" type="button" :aria-expanded="expanded.has(tool.id)" :aria-controls="`tool-panel-${tool.slug}`" @click="toggleTool(tool)">{{ expanded.has(tool.id) ? 'CLOSE' : 'UNFOLD' }}</button>
+        </div>
+        <p class="tool-summary">{{ tool.description || '暂无观测说明。' }}</p>
+        <div v-if="expanded.has(tool.id)" :id="`tool-panel-${tool.slug}`" class="tool-panel" role="region" :aria-label="`${tool.title} 工具面板`">
+          <p class="tool-description">{{ tool.description || '暂无观测说明。' }}</p>
+          <div class="tool-tags" aria-label="工具标签"><span v-for="tag in tool.tags" :key="tag">#{{ tag }}</span></div>
+          <template v-if="tool.type === 'EMBEDDED'">
+            <div class="embedded-slot" :data-component-key="tool.componentKey || undefined">
+              <span class="slot-marker" aria-hidden="true">/</span>
+              <strong>内嵌组件槽位已建立</strong>
+              <span>当前版本未装载此工具算法；不会上传或模拟你的输入。</span>
+            </div>
+          </template>
+          <template v-else>
+            <a v-if="safeExternalUrl(tool.url)" class="external-link" :href="safeExternalUrl(tool.url) || undefined" target="_blank" rel="noopener noreferrer external" @click="markUsed(tool)">访问 {{ tool.type === 'SHOWCASE' ? '项目展示' : '外部工具' }} <span aria-hidden="true">↗</span></a>
+            <p v-else class="tool-warning">外链未通过 HTTPS 校验，已停止访问。</p>
+          </template>
+        </div>
+      </li>
+    </ol>
+  </section>
+</template>
+
+<style scoped>
+.tools-scene { max-width: 74rem; margin: 8vh auto 4rem; }
+.tools-heading { display: flex; align-items: end; justify-content: space-between; gap: var(--space-8); margin-bottom: clamp(2rem, 7vw, 5rem); }
+.tools-heading h1 { max-width: none; margin-bottom: 1.4rem; }
+.signal-copy { max-width: 42rem; }
+.console-readout, .tool-index, .tool-metadata, .tool-favorite, .tool-unfold, .filter-label, .sort-controls button, .tool-identity span, .tool-tags, .empty-code, .embedded-slot, .external-link, .tool-warning { font: var(--text-xs)/1.4 var(--font-mono); letter-spacing: .04em; }
+.console-readout { display: inline-flex; align-items: center; gap: .55rem; flex: 0 0 auto; margin: 0 0 .5rem; color: var(--color-text-muted); }
+.status-light, .tool-signal { display: inline-block; width: .45rem; height: .45rem; border-radius: 50%; background: var(--color-accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--color-accent) 14%, transparent); }
+.tool-filters { display: grid; grid-template-columns: minmax(10rem, 1fr) minmax(10rem, 1fr) minmax(14rem, 2fr) auto; align-items: end; gap: var(--space-3); padding: .8rem 0; border-top: 1px solid var(--color-border); border-bottom: 1px solid var(--color-border); }
+.tool-filters label { display: grid; gap: .35rem; color: var(--color-text-muted); font: var(--text-xs)/1.2 var(--font-mono); }
+.tool-filters select, .tool-filters input { width: 100%; min-height: 2.4rem; padding: .45rem .55rem; border: 1px solid var(--color-border); border-radius: 0; background: var(--color-bg-sub); color: var(--color-text-main); font: var(--text-sm)/1.2 var(--font-mono); }
+.tool-filters input::placeholder { color: var(--color-text-muted); opacity: .7; }
+.sort-controls { display: flex; align-items: center; gap: .3rem; min-height: 2.4rem; }
+.filter-label { color: var(--color-text-muted); margin-right: .2rem; }
+.sort-controls button { padding: .45rem .5rem; border: 1px solid var(--color-border); background: transparent; color: var(--color-text-muted); cursor: pointer; }
+.sort-controls button[aria-pressed='true'], .sort-controls button:focus-visible { border-color: var(--color-accent); color: var(--color-accent); }
+.tool-console { display: grid; gap: 1px; margin: 2rem 0 0; padding: 0; list-style: none; background: var(--color-border); }
+.tool-entry { background: var(--color-bg-base); }
+.tool-entry[data-expanded='true'] { background: color-mix(in srgb, var(--color-accent) 5%, var(--color-bg-base)); }
+.tool-row { display: grid; grid-template-columns: 2.25rem .5rem minmax(10rem, 1.5fr) minmax(10rem, 1fr) auto auto; align-items: center; gap: .8rem; min-height: 4.4rem; padding: .75rem .9rem; }
+.tool-index, .tool-identity span, .tool-metadata { color: var(--color-text-muted); }
+.tool-identity { display: grid; gap: .25rem; min-width: 0; }
+.tool-identity strong { overflow: hidden; color: var(--color-text-main); font: 700 clamp(1rem, 2vw, 1.25rem)/1.2 var(--font-display); letter-spacing: -.02em; text-overflow: ellipsis; white-space: nowrap; }
+.tool-identity span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.tool-metadata { display: flex; flex-wrap: wrap; gap: .3rem .8rem; }
+.tool-metadata span + span { color: var(--color-accent); }
+.tool-favorite, .tool-unfold { border: 1px solid var(--color-border); padding: .45rem .55rem; background: transparent; color: var(--color-text-muted); cursor: pointer; white-space: nowrap; }
+.tool-favorite[aria-pressed='true'], .tool-favorite:hover, .tool-unfold:hover, .tool-favorite:focus-visible, .tool-unfold:focus-visible { border-color: var(--color-accent); color: var(--color-accent); }
+.tool-unfold { color: var(--color-accent); }
+.tool-summary { margin: 0; padding: 0 .9rem .8rem 4.3rem; color: var(--color-text-muted); line-height: 1.5; }
+.tool-panel { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: .8rem 1rem; padding: .25rem .9rem 1.2rem 4.3rem; border-top: 1px solid var(--color-border-soft); }
+.tool-description { grid-column: 1 / -1; max-width: 60rem; margin: .7rem 0 0; color: var(--color-text-main); line-height: 1.65; }
+.tool-tags { display: flex; flex-wrap: wrap; gap: .4rem .7rem; color: var(--color-text-muted); }
+.embedded-slot { display: grid; grid-template-columns: auto 1fr; gap: .15rem .6rem; align-items: baseline; min-width: min(100%, 32rem); padding: .8rem; border: 1px dashed var(--color-border); color: var(--color-text-muted); }
+.embedded-slot strong { color: var(--color-accent); font-weight: 400; }
+.embedded-slot span:last-child { grid-column: 2; }
+.slot-marker { color: var(--color-warn); font-size: 1.2rem; }
+.external-link { justify-self: end; padding: .55rem .75rem; border: 1px solid var(--color-accent); color: var(--color-accent); text-decoration: none; }
+.external-link:hover, .external-link:focus-visible { background: var(--color-accent); color: var(--color-accent-ink); }
+.tool-warning { color: var(--color-warn); }
+.tool-empty { display: grid; gap: .6rem; max-width: 38rem; margin: 2rem 0; padding: 1.5rem; border: 1px dashed var(--color-border); color: var(--color-text-muted); }
+.tool-empty strong { color: var(--color-text-main); font: 700 var(--text-lg)/1.2 var(--font-display); }
+.empty-code { color: var(--color-warn); }
+@media (max-width: 960px) { .tool-filters { grid-template-columns: repeat(2, minmax(0, 1fr)); } .keyword-filter { grid-column: span 2; } .sort-controls { justify-content: end; } .tool-row { grid-template-columns: 2.25rem .5rem minmax(8rem, 1fr) auto auto; } .tool-metadata { grid-column: 3 / -1; grid-row: 2; } }
+@media (max-width: 640px) { .tools-scene { margin-top: 5vh; } .tools-heading { align-items: start; flex-direction: column; gap: 1rem; margin-bottom: 2.5rem; } .tools-heading h1 { font-size: clamp(3rem, 18vw, 5rem); } .tool-filters { grid-template-columns: 1fr; } .keyword-filter { grid-column: auto; } .sort-controls { justify-content: start; flex-wrap: wrap; } .tool-row { grid-template-columns: 1.8rem .45rem minmax(0, 1fr) auto; gap: .55rem; padding-inline: .55rem; } .tool-metadata { grid-column: 3 / -1; grid-row: 2; } .tool-favorite { grid-column: 3; grid-row: 3; justify-self: start; } .tool-unfold { grid-column: 4; grid-row: 3; } .tool-summary { padding-left: 2.7rem; padding-right: .55rem; } .tool-panel { grid-template-columns: 1fr; padding-left: 2.7rem; padding-right: .55rem; } .external-link { justify-self: start; } }
+@media (max-width: 360px) { .tools-scene { margin-top: 2rem; } .tool-row { grid-template-columns: 1.6rem .4rem minmax(0, 1fr); } .tool-favorite, .tool-unfold { grid-column: 3; grid-row: auto; justify-self: start; } .tool-unfold { margin-top: .2rem; } .tool-metadata { grid-column: 3; grid-row: auto; } .tool-summary { padding-left: 2.2rem; } .tool-panel { padding-left: 2.2rem; } }
+@media (prefers-reduced-motion: reduce) { .tools-scene *, .tools-scene *::before, .tools-scene *::after { transition: none !important; animation: none !important; } }
+</style>
diff --git a/apps/web/e2e/stage3.spec.ts b/apps/web/e2e/stage3.spec.ts
index d43abd2..a579436 100644
--- a/apps/web/e2e/stage3.spec.ts
+++ b/apps/web/e2e/stage3.spec.ts
@@ -132,6 +132,7 @@ test.describe.serial('S3-08 public reading acceptance', () => {
         expect(xml).toContain('<item>')
       } else {
         expect(xml).toContain('s3-08-advanced-markdown')
+        expect(xml).toContain('/tools')
       }
       const etag = response.headers().etag
       expect(etag).toBeTruthy()
diff --git a/apps/web/e2e/stage4.spec.ts b/apps/web/e2e/stage4.spec.ts
index 1fc8031..1d6bbe7 100644
--- a/apps/web/e2e/stage4.spec.ts
+++ b/apps/web/e2e/stage4.spec.ts
@@ -44,3 +44,86 @@ test.describe('S4-03 article comment signal', () => {
     expect(await page.evaluate(() => localStorage.getItem('haoblog-comment-delete:00000000-0000-7000-8000-000000000099'))).toBe('e2e-delete-token')
   })
 })
+
+test.describe('S4-07 public toolbox switchboard', () => {
+  test('renders the full directory in SSR and keeps interaction client-owned', async ({ page, browser }) => {
+    const batch = Date.now()
+    const anonymousCsrf = await page.request.get('/api/v1/admin/csrf')
+    const anonymousToken = (await anonymousCsrf.json() as { token: string }).token
+    const login = await page.request.post('/api/v1/admin/session', {
+      headers: { 'X-CSRF-TOKEN': anonymousToken },
+      data: { username: 'admin', password: 'password' },
+    })
+    expect(login.ok()).toBe(true)
+    const authenticatedCsrf = await page.request.get('/api/v1/admin/csrf')
+    const token = (await authenticatedCsrf.json() as { token: string }).token
+    const category = await page.request.post('/api/v1/admin/tool-categories', {
+      headers: { 'X-CSRF-TOKEN': token },
+      data: { name: `S4-07 ${batch}`, slug: `s4-07-${batch}`, description: '公共工具验收分类' },
+    })
+    expect(category.status()).toBe(201)
+    const categoryId = (await category.json() as { id: string }).id
+    const createTool = (body: Record<string, unknown>) => page.request.post('/api/v1/admin/tools', {
+      headers: { 'X-CSRF-TOKEN': token },
+      data: { categoryId, status: 'ACTIVE', tags: [], ...body },
+    })
+    expect((await createTool({ type: 'EMBEDDED', componentKey: 'json-format', title: `JSON Formatter ${batch}`, slug: `json-format-${batch}`, description: 'JSON 工程格式化入口', tags: ['json', 'format'] })).status()).toBe(201)
+    expect((await createTool({ type: 'LINK', url: 'https://example.com/toolbox', title: `Link Tool ${batch}`, slug: `link-tool-${batch}`, description: '安全外链入口', tags: ['link'] })).status()).toBe(201)
+
+    const api = await page.request.get('/api/v1/public/tools')
+    expect(api.ok()).toBe(true)
+    const payload = await api.json() as { items: Array<{ title: string; type: string }>; categories: Array<{ slug: string }> }
+    expect(payload.items.some(item => item.title.includes(`JSON Formatter ${batch}`))).toBe(true)
+    expect(payload.categories.some(item => item.slug === `s4-07-${batch}`)).toBe(true)
+    expect((await page.request.get('/api/v1/public/tools?type=EMBEDDED&keyword=json')).ok()).toBe(true)
+
+    const ssr = await page.request.get('/tools')
+    const html = await ssr.text()
+    expect(ssr.status()).toBe(200)
+    expect(html).toContain(`JSON Formatter ${batch}`)
+    expect(html).toContain('JSON 工程格式化入口')
+    expect(html).toContain('#json')
+    expect(html).not.toContain('noindex')
+
+    const warnings: string[] = []
+    page.on('console', message => { if (message.type() === 'warning') warnings.push(message.text()) })
+    await page.goto('/tools')
+    await expect(page.getByRole('heading', { name: '工具目录' })).toBeVisible()
+    expect(warnings.filter(message => /hydration|mismatch/i.test(message))).toEqual([])
+
+    const embedded = page.locator('.tool-entry').filter({ hasText: `JSON Formatter ${batch}` })
+    await embedded.getByRole('button', { name: `收藏 JSON Formatter ${batch}` }).click()
+    expect(await page.evaluate(() => localStorage.getItem('haoblog-tool-favorites'))).toContain('[')
+    await embedded.getByRole('button', { name: 'UNFOLD' }).click()
+    await expect(embedded.locator('.embedded-slot')).toContainText('内嵌组件槽位已建立')
+    await embedded.getByRole('button', { name: 'CLOSE' }).click()
+    await embedded.getByRole('button', { name: 'UNFOLD' }).click()
+    await embedded.getByRole('button', { name: 'CLOSE' }).click()
+    await page.getByRole('button', { name: '最常用' }).click()
+    await expect(page.locator('.tool-entry').first()).toContainText(`JSON Formatter ${batch}`)
+
+    const linked = page.locator('.tool-entry').filter({ hasText: `Link Tool ${batch}` })
+    await linked.getByRole('button', { name: 'UNFOLD' }).click()
+    await expect(linked.locator('a[rel="noopener noreferrer external"]')).toHaveAttribute('href', 'https://example.com/toolbox')
+
+    const reduced = await browser.newContext({ baseURL: process.env.HAOBLOG_BASE_URL || 'http://127.0.0.1' })
+    const reducedPage = await reduced.newPage()
+    await reducedPage.emulateMedia({ reducedMotion: 'reduce' })
+    await reducedPage.goto('/tools')
+    expect(await reducedPage.locator('.tools-scene').evaluate(element => getComputedStyle(element).animationName)).toBe('none')
+    await reduced.close()
+
+    const saveData = await browser.newContext({ baseURL: process.env.HAOBLOG_BASE_URL || 'http://127.0.0.1', extraHTTPHeaders: { 'Save-Data': 'on' } })
+    const saveDataPage = await saveData.newPage()
+    await saveDataPage.goto('/tools')
+    await expect(saveDataPage.locator('.embedded-slot')).toHaveCount(0)
+    await saveData.close()
+
+    const touch = await browser.newContext({ baseURL: process.env.HAOBLOG_BASE_URL || 'http://127.0.0.1', hasTouch: true, isMobile: true })
+    const touchPage = await touch.newPage()
+    await touchPage.goto('/tools')
+    await touchPage.locator('.tool-entry').filter({ hasText: `JSON Formatter ${batch}` }).getByRole('button', { name: 'UNFOLD' }).click()
+    await expect(touchPage.locator('.embedded-slot')).toBeVisible()
+    await touch.close()
+  })
+})
diff --git a/apps/web/nuxt.config.ts b/apps/web/nuxt.config.ts
index 837fa26..85cba37 100644
--- a/apps/web/nuxt.config.ts
+++ b/apps/web/nuxt.config.ts
@@ -18,7 +18,6 @@ export default defineNuxtConfig({
     '/articles/**': { cache: false },
     '/article-previews/**': { cache: false, headers: { 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', 'x-robots-tag': 'noindex, nofollow' } },
     '/garden': { headers: { 'x-robots-tag': 'noindex, nofollow' } },
-    '/tools': { headers: { 'x-robots-tag': 'noindex, nofollow' } },
   },
   nitro: {
     compressPublicAssets: true,
diff --git a/docs/openapi/public-api.yaml b/docs/openapi/public-api.yaml
index 29937cc..c55609c 100644
--- a/docs/openapi/public-api.yaml
+++ b/docs/openapi/public-api.yaml
@@ -79,6 +79,41 @@ paths:
             Cache-Control: { schema: { type: string } }
         '500':
           $ref: '#/components/responses/InternalError'
+  /api/v1/public/tools:
+    get:
+      operationId: listPublicTools
+      security: []
+      parameters:
+        - name: category
+          in: query
+          description: Category slug or UUID
+          schema: { type: string, maxLength: 160 }
+        - name: type
+          in: query
+          schema: { $ref: '#/components/schemas/ToolType' }
+        - name: keyword
+          in: query
+          schema: { type: string, maxLength: 240 }
+        - $ref: '#/components/parameters/IfNoneMatch'
+      responses:
+        '200':
+          description: Active public tools and their valid categories
+          headers:
+            ETag: { $ref: '#/components/headers/ETag' }
+            Cache-Control: { schema: { type: string } }
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PublicToolListResponse'
+        '304':
+          description: Public tool representation has not changed
+          headers:
+            ETag: { $ref: '#/components/headers/ETag' }
+            Cache-Control: { schema: { type: string } }
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
   /api/v1/public/articles:
     get:
       operationId: listPublicArticles
@@ -1450,6 +1485,36 @@ components:
             version: { type: integer, format: int64, minimum: 0 }
             createdAt: { type: string, format: date-time }
             updatedAt: { type: string, format: date-time }
+    PublicToolCategoryResponse:
+      type: object
+      required: [id, name, slug, sortOrder]
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string }
+        slug: { type: string }
+        description: { type: [string, 'null'] }
+        sortOrder: { type: integer }
+    PublicToolResponse:
+      type: object
+      required: [id, category, type, title, slug, description, url, imageUrl, componentKey, tags, sortOrder]
+      properties:
+        id: { type: string, format: uuid }
+        category: { $ref: '#/components/schemas/PublicToolCategoryResponse' }
+        type: { $ref: '#/components/schemas/ToolType' }
+        title: { type: string }
+        slug: { type: string }
+        description: { type: [string, 'null'] }
+        url: { type: [string, 'null'], format: uri, pattern: '^https://' }
+        imageUrl: { type: [string, 'null'], format: uri, pattern: '^https://' }
+        componentKey: { oneOf: [{ $ref: '#/components/schemas/ToolComponentKey' }, { type: 'null' }] }
+        tags: { type: array, items: { type: string } }
+        sortOrder: { type: integer }
+    PublicToolListResponse:
+      type: object
+      required: [items, categories]
+      properties:
+        items: { type: array, items: { $ref: '#/components/schemas/PublicToolResponse' } }
+        categories: { type: array, items: { $ref: '#/components/schemas/PublicToolCategoryResponse' } }
     AdminToolListResponse:
       type: object
       required: [items, page, size, total]
diff --git a/infra/compose/compose.dev.yml b/infra/compose/compose.dev.yml
index a5d0ef2..44ef3d7 100644
--- a/infra/compose/compose.dev.yml
+++ b/infra/compose/compose.dev.yml
@@ -29,6 +29,7 @@ services:
       HAOBLOG_SEED_ENABLED: "true"
       HAOBLOG_ADMIN_USERNAME: ${HAOBLOG_ADMIN_USERNAME:?HAOBLOG_ADMIN_USERNAME is required}
       HAOBLOG_ADMIN_PASSWORD_HASH: ${HAOBLOG_ADMIN_PASSWORD_HASH:?HAOBLOG_ADMIN_PASSWORD_HASH is required}
+      HAOBLOG_COMMENT_SECURITY_KEY: ${HAOBLOG_COMMENT_SECURITY_KEY:?HAOBLOG_COMMENT_SECURITY_KEY is required}
       HAOBLOG_PUBLIC_BASE_URL: ${HAOBLOG_PUBLIC_BASE_URL:-http://localhost:3000}
       HAOBLOG_AUTHOR_NAME: ${HAOBLOG_AUTHOR_NAME:-Hao}
       HAOBLOG_COMMENT_NOTIFICATION_ENABLED: ${HAOBLOG_COMMENT_NOTIFICATION_ENABLED:-false}
diff --git a/packages/api-client/src/generated.ts b/packages/api-client/src/generated.ts
index 0deca5e..8812712 100644
--- a/packages/api-client/src/generated.ts
+++ b/packages/api-client/src/generated.ts
@@ -52,6 +52,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/public/tools": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["listPublicTools"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/public/articles": {
         parameters: {
             query?: never;
@@ -1129,6 +1145,34 @@ export interface components {
             /** Format: date-time */
             updatedAt: string;
         };
+        PublicToolCategoryResponse: {
+            /** Format: uuid */
+            id: string;
+            name: string;
+            slug: string;
+            description?: string | null;
+            sortOrder: number;
+        };
+        PublicToolResponse: {
+            /** Format: uuid */
+            id: string;
+            category: components["schemas"]["PublicToolCategoryResponse"];
+            type: components["schemas"]["ToolType"];
+            title: string;
+            slug: string;
+            description: string | null;
+            /** Format: uri */
+            url: string | null;
+            /** Format: uri */
+            imageUrl: string | null;
+            componentKey: components["schemas"]["ToolComponentKey"] | null;
+            tags: string[];
+            sortOrder: number;
+        };
+        PublicToolListResponse: {
+            items: components["schemas"]["PublicToolResponse"][];
+            categories: components["schemas"]["PublicToolCategoryResponse"][];
+        };
         AdminToolListResponse: {
             items: components["schemas"]["ToolResponse"][];
             page: number;
@@ -1405,6 +1449,46 @@ export interface operations {
             500: components["responses"]["InternalError"];
         };
     };
+    listPublicTools: {
+        parameters: {
+            query?: {
+                /** @description Category slug or UUID */
+                category?: string;
+                type?: components["schemas"]["ToolType"];
+                keyword?: string;
+            };
+            header?: {
+                "If-None-Match"?: components["parameters"]["IfNoneMatch"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Active public tools and their valid categories */
+            200: {
+                headers: {
+                    ETag: components["headers"]["ETag"];
+                    "Cache-Control"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PublicToolListResponse"];
+                };
+            };
+            /** @description Public tool representation has not changed */
+            304: {
+                headers: {
+                    ETag: components["headers"]["ETag"];
+                    "Cache-Control"?: string;
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            400: components["responses"]["BadRequest"];
+            500: components["responses"]["InternalError"];
+        };
+    };
     listPublicArticles: {
         parameters: {
             query?: {

From 4330ffcf175bb09462c8dfd5edb98a2eb6eb87bd Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 15:40:02 +0800
Subject: [PATCH 10/15] =?UTF-8?q?=E5=AE=8C=E6=88=90=E4=BA=94=E4=B8=AA?=
 =?UTF-8?q?=E6=B5=8F=E8=A7=88=E5=99=A8=E5=86=85=E5=B5=8C=E5=B7=A5=E5=85=B7?=
 =?UTF-8?q?=E4=B8=8E=E5=8F=97=E6=8E=A7=20Worker?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../application/ToolDevelopmentSeeder.java    | 74 ++++++++++++++
 apps/web/app/components/tools/Base64Tool.vue  | 43 +++++++++
 .../components/tools/EmbeddedToolFrame.vue    | 45 +++++++++
 .../app/components/tools/JsonFormatTool.vue   | 50 ++++++++++
 .../app/components/tools/RegexTestTool.vue    | 87 +++++++++++++++++
 .../app/components/tools/TimestampTool.vue    | 63 ++++++++++++
 .../web/app/components/tools/UrlCodecTool.vue | 43 +++++++++
 apps/web/app/composables/useEmbeddedWorker.ts | 74 ++++++++++++++
 apps/web/app/pages/tools.vue                  | 11 ++-
 apps/web/app/utils/embeddedToolOperations.ts  | 84 ++++++++++++++++
 apps/web/app/utils/embeddedToolUi.ts          | 32 +++++++
 apps/web/app/utils/embeddedTools.ts           | 15 +++
 apps/web/app/utils/timestampTool.ts           | 31 ++++++
 apps/web/app/workers/embedded-tool.worker.ts  | 12 +++
 apps/web/e2e/stage4.spec.ts                   | 54 +++++++++++
 apps/web/lighthouserc.cjs                     |  3 +-
 apps/web/test/embedded-tool-lazy-load.test.ts | 29 ++++++
 apps/web/test/embedded-tools.test.ts          | 96 +++++++++++++++++++
 18 files changed, 843 insertions(+), 3 deletions(-)
 create mode 100644 apps/api/src/main/java/io/haoblog/toolbox/application/ToolDevelopmentSeeder.java
 create mode 100644 apps/web/app/components/tools/Base64Tool.vue
 create mode 100644 apps/web/app/components/tools/EmbeddedToolFrame.vue
 create mode 100644 apps/web/app/components/tools/JsonFormatTool.vue
 create mode 100644 apps/web/app/components/tools/RegexTestTool.vue
 create mode 100644 apps/web/app/components/tools/TimestampTool.vue
 create mode 100644 apps/web/app/components/tools/UrlCodecTool.vue
 create mode 100644 apps/web/app/composables/useEmbeddedWorker.ts
 create mode 100644 apps/web/app/utils/embeddedToolOperations.ts
 create mode 100644 apps/web/app/utils/embeddedToolUi.ts
 create mode 100644 apps/web/app/utils/embeddedTools.ts
 create mode 100644 apps/web/app/utils/timestampTool.ts
 create mode 100644 apps/web/app/workers/embedded-tool.worker.ts
 create mode 100644 apps/web/test/embedded-tool-lazy-load.test.ts
 create mode 100644 apps/web/test/embedded-tools.test.ts

diff --git a/apps/api/src/main/java/io/haoblog/toolbox/application/ToolDevelopmentSeeder.java b/apps/api/src/main/java/io/haoblog/toolbox/application/ToolDevelopmentSeeder.java
new file mode 100644
index 0000000..d11537d
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/toolbox/application/ToolDevelopmentSeeder.java
@@ -0,0 +1,74 @@
+package io.haoblog.toolbox.application;
+
+import io.haoblog.toolbox.domain.Tool;
+import io.haoblog.toolbox.domain.ToolCategory;
+import io.haoblog.toolbox.domain.ToolComponentKey;
+import io.haoblog.toolbox.domain.ToolStatus;
+import io.haoblog.toolbox.domain.ToolType;
+import io.haoblog.toolbox.persistence.ToolCategoryRepository;
+import io.haoblog.toolbox.persistence.ToolRepository;
+import org.springframework.boot.ApplicationRunner;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Profile;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.util.List;
+
+@Configuration
+@Profile({"local", "dev"})
+@ConditionalOnProperty(name = "haoblog.seed.enabled", havingValue = "true", matchIfMissing = false)
+public class ToolDevelopmentSeeder {
+    @Bean
+    ApplicationRunner toolSeedRunner(ToolSeedService seedService) {
+        return args -> seedService.seed();
+    }
+
+    @Configuration
+    static class SeedServices {
+        @Bean ToolSeedService toolSeedService(ToolCategoryRepository categories, ToolRepository tools, Clock clock) {
+            return new ToolSeedService(categories, tools, clock);
+        }
+    }
+
+    static class ToolSeedService {
+        private final ToolCategoryRepository categories;
+        private final ToolRepository tools;
+        private final Clock clock;
+
+        ToolSeedService(ToolCategoryRepository categories, ToolRepository tools, Clock clock) {
+            this.categories = categories;
+            this.tools = tools;
+            this.clock = clock;
+        }
+
+        @Transactional
+        public void seed() {
+            Instant now = Instant.now(clock);
+            ToolCategory category = categories.findAllByOrderBySortOrderAscNameAsc().stream()
+                    .filter(value -> value.getSlug().equals("embedded-tools"))
+                    .findFirst()
+                    .orElseGet(() -> categories.saveAndFlush(new ToolCategory(
+                            "浏览器内嵌工具", "embedded-tools", "输入留在浏览器，结果由原生 API 计算。", 10, now)));
+            List<SeedTool> seedTools = List.of(
+                    new SeedTool("json-format", "JSON 格式化", "校验、两空格格式化或压缩 JSON。", ToolComponentKey.JSON_FORMAT, List.of("json", "format")),
+                    new SeedTool("base64", "Base64 编解码", "在浏览器中进行 UTF-8 文本 Base64 编解码。", ToolComponentKey.BASE64, List.of("base64", "utf8")),
+                    new SeedTool("url-codec", "URL 编解码", "使用 encodeURIComponent 和 decodeURIComponent 处理 URI 组件。", ToolComponentKey.URL_CODEC, List.of("url", "encode")),
+                    new SeedTool("timestamp", "时间戳转换", "自动识别秒/毫秒并显示本地时间与 UTC ISO。", ToolComponentKey.TIMESTAMP, List.of("time", "date")),
+                    new SeedTool("regex-test", "正则测试", "在受控 Web Worker 中运行 JavaScript RegExp。", ToolComponentKey.REGEX_TEST, List.of("regex", "worker")));
+            for (int index = 0; index < seedTools.size(); index++) {
+                SeedTool item = seedTools.get(index);
+                if (!tools.existsBySlug(item.slug())) {
+                    tools.save(new Tool(category.getId(), ToolType.EMBEDDED, ToolStatus.ACTIVE, item.title(), item.slug(),
+                            item.description(), null, null, item.componentKey(), item.tags(), index + 1, now));
+                }
+            }
+            tools.flush();
+        }
+
+        private record SeedTool(String slug, String title, String description, ToolComponentKey componentKey, List<String> tags) {}
+    }
+}
diff --git a/apps/web/app/components/tools/Base64Tool.vue b/apps/web/app/components/tools/Base64Tool.vue
new file mode 100644
index 0000000..173251b
--- /dev/null
+++ b/apps/web/app/components/tools/Base64Tool.vue
@@ -0,0 +1,43 @@
+<script setup lang="ts">
+import { inject, ref } from 'vue'
+import EmbeddedToolFrame from './EmbeddedToolFrame.vue'
+import { embeddedWorkerKey } from '~/composables/useEmbeddedWorker'
+import { copyText, validateInput } from '~/utils/embeddedToolUi'
+
+const worker = inject(embeddedWorkerKey)
+const input = ref('')
+const output = ref('')
+const error = ref('')
+const status = ref('')
+const busy = ref(false)
+
+async function run(mode: 'encode' | 'decode') {
+  error.value = ''; status.value = ''
+  const inputError = validateInput(input.value, undefined, 'Base64 输入')
+  if (inputError) { error.value = inputError; return }
+  busy.value = true
+  try { output.value = (await worker?.run('base64', { input: input.value, mode }))?.output || ''; status.value = mode === 'encode' ? 'UTF-8 文本已编码。' : 'Base64 已严格校验并解码为 UTF-8 文本。' }
+  catch (cause) { error.value = cause instanceof Error ? cause.message : 'Base64 处理失败，请检查输入。' }
+  finally { busy.value = false }
+}
+
+async function copyResult() { try { await copyText(output.value); status.value = '结果已复制到剪贴板。' } catch (cause) { error.value = cause instanceof Error ? cause.message : '复制失败，请手动选择结果。' } }
+function clearTool() { input.value = ''; output.value = ''; error.value = ''; status.value = '' }
+</script>
+
+<template>
+  <EmbeddedToolFrame title="BASE64" description="只处理 UTF-8 文本；本轮不读取或上传二进制文件。" :error="error" :status="status">
+    <div class="tool-fields">
+      <label>输入<textarea v-model="input" spellcheck="false" autocomplete="off" placeholder="输入 Unicode 文本或规范 Base64" /></label>
+      <div class="tool-actions">
+        <button class="tool-action" type="button" :disabled="busy" @click="run('encode')">UTF-8 编码</button>
+        <button class="tool-action" type="button" :disabled="busy" @click="run('decode')">Base64 解码</button>
+        <button class="tool-action" type="button" :disabled="!output" @click="copyResult">复制结果</button>
+        <button class="tool-action" type="button" @click="clearTool">清空</button>
+      </div>
+      <div><p class="tool-result-label">结果</p><pre class="tool-output" aria-label="Base64 结果">{{ output }}</pre></div>
+    </div>
+  </EmbeddedToolFrame>
+</template>
+
+<style scoped>.tool-result-label { margin: 0 0 .35rem; color: var(--color-text-muted); font: var(--text-xs)/1 var(--font-mono); }</style>
diff --git a/apps/web/app/components/tools/EmbeddedToolFrame.vue b/apps/web/app/components/tools/EmbeddedToolFrame.vue
new file mode 100644
index 0000000..2d34dfc
--- /dev/null
+++ b/apps/web/app/components/tools/EmbeddedToolFrame.vue
@@ -0,0 +1,45 @@
+<script setup lang="ts">
+defineProps<{ title: string; description: string; error?: string; status?: string }>()
+</script>
+
+<template>
+  <section class="embedded-tool-frame" :aria-label="title">
+    <header class="tool-frame-heading">
+      <div>
+        <p class="tool-frame-kicker">LOCAL / NO UPLOAD</p>
+        <h2>{{ title }}</h2>
+        <p>{{ description }}</p>
+      </div>
+      <span class="tool-frame-light" aria-hidden="true" />
+    </header>
+    <p v-if="error" class="tool-frame-error" role="alert">{{ error }}</p>
+    <p v-if="status" class="tool-frame-status" role="status" aria-live="polite">{{ status }}</p>
+    <slot />
+  </section>
+</template>
+
+<style scoped>
+.embedded-tool-frame { display: grid; gap: 1rem; width: 100%; padding: 1rem; border: 1px solid var(--color-border); background: var(--color-surface-quiet); }
+.tool-frame-heading { display: flex; justify-content: space-between; gap: 1rem; }
+.tool-frame-kicker, .tool-frame-status, .tool-frame-error, .tool-frame-heading h2 + p { margin: 0; font: var(--text-xs)/1.5 var(--font-mono); }
+.tool-frame-kicker { color: var(--color-accent); letter-spacing: .1em; }
+.tool-frame-heading h2 { margin: .3rem 0; color: var(--color-text-main); font: 700 clamp(1.25rem, 3vw, 1.8rem)/1.1 var(--font-display); }
+.tool-frame-heading h2 + p { color: var(--color-text-muted); }
+.tool-frame-light { flex: 0 0 .5rem; width: .5rem; height: .5rem; margin-top: .35rem; border-radius: 50%; background: var(--color-accent); }
+.tool-frame-error { padding: .65rem .75rem; border-left: 2px solid var(--color-warn); background: color-mix(in srgb, var(--color-warn) 8%, transparent); color: var(--color-warn); }
+.tool-frame-status { color: var(--color-accent); }
+:deep(.tool-fields) { display: grid; gap: .75rem; }
+:deep(.tool-fields label) { display: grid; gap: .35rem; color: var(--color-text-muted); font: var(--text-xs)/1.3 var(--font-mono); }
+:deep(.tool-fields textarea), :deep(.tool-fields input), :deep(.tool-fields select) { width: 100%; min-width: 0; padding: .65rem .7rem; border: 1px solid var(--color-border); border-radius: 0; background: var(--color-bg-base); color: var(--color-text-main); font: var(--text-sm)/1.5 var(--font-body); }
+:deep(.tool-fields textarea) { min-height: 8rem; resize: vertical; }
+:deep(.tool-fields textarea:focus), :deep(.tool-fields input:focus), :deep(.tool-fields select:focus) { border-color: var(--color-accent); outline: 1px solid var(--color-accent); }
+:deep(.tool-actions) { display: flex; flex-wrap: wrap; gap: .5rem; }
+:deep(.tool-action) { min-height: 2.4rem; padding: .55rem .75rem; border: 1px solid var(--color-accent); background: transparent; color: var(--color-accent); cursor: pointer; font: var(--text-xs)/1 var(--font-mono); letter-spacing: .04em; }
+:deep(.tool-action:hover), :deep(.tool-action:focus-visible) { background: var(--color-accent); color: var(--color-accent-ink); }
+:deep(.tool-action:disabled) { cursor: wait; opacity: .55; }
+:deep(.tool-output) { min-width: 0; margin: 0; padding: .8rem; overflow: auto; border: 1px solid var(--color-border); background: var(--color-code-bg); color: var(--color-text-main); font: var(--text-sm)/1.55 var(--font-mono); white-space: pre-wrap; overflow-wrap: anywhere; }
+:deep(.tool-output:empty)::before { content: 'RESULT / WAITING'; color: var(--color-text-muted); }
+:deep(.tool-output mark) { padding: 0 .1rem; background: color-mix(in srgb, var(--color-accent) 30%, transparent); color: var(--color-text-main); }
+:deep(.tool-grid) { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: .75rem; }
+@media (max-width: 520px) { .embedded-tool-frame { padding: .75rem; } .tool-frame-heading { align-items: start; } :deep(.tool-grid) { grid-template-columns: 1fr; } }
+</style>
diff --git a/apps/web/app/components/tools/JsonFormatTool.vue b/apps/web/app/components/tools/JsonFormatTool.vue
new file mode 100644
index 0000000..9a0e940
--- /dev/null
+++ b/apps/web/app/components/tools/JsonFormatTool.vue
@@ -0,0 +1,50 @@
+<script setup lang="ts">
+import { inject, ref } from 'vue'
+import EmbeddedToolFrame from './EmbeddedToolFrame.vue'
+import { embeddedWorkerKey } from '~/composables/useEmbeddedWorker'
+import { copyText, validateInput } from '~/utils/embeddedToolUi'
+
+const worker = inject(embeddedWorkerKey)
+const input = ref('')
+const output = ref('')
+const error = ref('')
+const status = ref('')
+const busy = ref(false)
+
+async function run(mode: 'format' | 'compact') {
+  error.value = ''; status.value = ''
+  const inputError = validateInput(input.value, undefined, 'JSON 输入')
+  if (inputError) { error.value = inputError; return }
+  busy.value = true
+  try { output.value = (await worker?.run('json-format', { input: input.value, mode }))?.output || ''; status.value = mode === 'format' ? 'JSON 校验通过，已按两空格格式化。' : 'JSON 校验通过，已压缩。' }
+  catch (cause) { error.value = cause instanceof Error ? cause.message : 'JSON 解析失败，请检查输入。' }
+  finally { busy.value = false }
+}
+
+async function copyResult() {
+  if (!output.value) return
+  try { await copyText(output.value); status.value = '结果已复制到剪贴板。' }
+  catch (cause) { error.value = cause instanceof Error ? cause.message : '复制失败，请手动选择结果。' }
+}
+
+function clearTool() { input.value = ''; output.value = ''; error.value = ''; status.value = '' }
+</script>
+
+<template>
+  <EmbeddedToolFrame title="JSON FORMAT" description="校验 JSON，并在浏览器中格式化或压缩。" :error="error" :status="status">
+    <div class="tool-fields">
+      <label>JSON 输入<textarea v-model="input" spellcheck="false" autocomplete="off" placeholder='{"signal":"ready"}' /></label>
+      <div class="tool-actions">
+        <button class="tool-action" type="button" :disabled="busy" @click="run('format')">格式化 / 两空格</button>
+        <button class="tool-action" type="button" :disabled="busy" @click="run('compact')">压缩</button>
+        <button class="tool-action" type="button" :disabled="!output" @click="copyResult">复制结果</button>
+        <button class="tool-action" type="button" @click="clearTool">清空</button>
+      </div>
+      <div><p class="tool-result-label">结果</p><pre class="tool-output" aria-label="JSON 结果">{{ output }}</pre></div>
+    </div>
+  </EmbeddedToolFrame>
+</template>
+
+<style scoped>
+.tool-result-label { margin: 0 0 .35rem; color: var(--color-text-muted); font: var(--text-xs)/1 var(--font-mono); }
+</style>
diff --git a/apps/web/app/components/tools/RegexTestTool.vue b/apps/web/app/components/tools/RegexTestTool.vue
new file mode 100644
index 0000000..37a8a8b
--- /dev/null
+++ b/apps/web/app/components/tools/RegexTestTool.vue
@@ -0,0 +1,87 @@
+<script setup lang="ts">
+import { computed, inject, ref } from 'vue'
+import EmbeddedToolFrame from './EmbeddedToolFrame.vue'
+import { embeddedWorkerKey } from '~/composables/useEmbeddedWorker'
+import { MAX_REGEX_TEXT_BYTES, copyText, validateInput } from '~/utils/embeddedToolUi'
+import type { RegexMatch } from '~/utils/embeddedToolOperations'
+
+const worker = inject(embeddedWorkerKey)
+const pattern = ref('')
+const flags = ref('g')
+const text = ref('')
+const matches = ref<RegexMatch[]>([])
+const truncated = ref(false)
+const error = ref('')
+const status = ref('')
+const busy = ref(false)
+
+const segments = computed(() => {
+  const parts: Array<{ text: string; match: boolean; index: number }> = []
+  let cursor = 0
+  for (const match of matches.value) {
+    if (match.index > cursor) parts.push({ text: text.value.slice(cursor, match.index), match: false, index: cursor })
+    parts.push({ text: match.text, match: true, index: match.index })
+    cursor = match.end
+  }
+  if (cursor < text.value.length) parts.push({ text: text.value.slice(cursor), match: false, index: cursor })
+  return parts
+})
+
+async function run() {
+  error.value = ''; status.value = ''; matches.value = []; truncated.value = false
+  for (const [value, label] of [[pattern.value, '正则 pattern'], [flags.value, '正则 flags']] as const) {
+    const inputError = validateInput(value, undefined, label)
+    if (inputError) { error.value = inputError; return }
+  }
+  const textError = validateInput(text.value, MAX_REGEX_TEXT_BYTES, '测试文本')
+  if (textError) { error.value = textError; return }
+  busy.value = true
+  try {
+    const response = await worker?.run('regex-test', { pattern: pattern.value, flags: flags.value, text: text.value }, 250)
+    matches.value = response?.matches || []
+    truncated.value = Boolean(response?.truncated)
+    status.value = truncated.value ? '已返回前 1000 个匹配，结果已截断。' : `完成：${matches.value.length} 个匹配。`
+  } catch (cause) { error.value = cause instanceof Error ? cause.message : '正则运行失败，请检查 pattern、flags 和测试文本。' }
+  finally { busy.value = false }
+}
+
+async function copyMatches() {
+  try { await copyText(matches.value.map((match, index) => `${index + 1}. [${match.index}, ${match.end}) ${match.text || '（零长度匹配）'}`).join('\n')); status.value = '匹配列表已复制到剪贴板。' }
+  catch (cause) { error.value = cause instanceof Error ? cause.message : '复制失败，请手动选择匹配列表。' }
+}
+
+function clearTool() { pattern.value = ''; flags.value = 'g'; text.value = ''; matches.value = []; truncated.value = false; error.value = ''; status.value = '' }
+</script>
+
+<template>
+  <EmbeddedToolFrame title="REGEX TEST" description="在受控 Worker 中执行 JavaScript RegExp；单次运行超过 250ms 会立即终止。" :error="error" :status="status">
+    <div class="tool-fields">
+      <div class="tool-grid">
+        <label>pattern<input v-model="pattern" spellcheck="false" autocomplete="off" placeholder="例如：signal\\d+"></label>
+        <label>flags<input v-model="flags" spellcheck="false" autocomplete="off" placeholder="gim"></label>
+      </div>
+      <label>测试文本<textarea v-model="text" spellcheck="false" autocomplete="off" placeholder="输入最多 100 KiB 的测试文本" /></label>
+      <div class="tool-actions">
+        <button class="tool-action" type="button" :disabled="busy" @click="run">运行正则</button>
+        <button class="tool-action" type="button" :disabled="!matches.length" @click="copyMatches">复制匹配列表</button>
+        <button class="tool-action" type="button" @click="clearTool">清空</button>
+      </div>
+      <div>
+        <p class="tool-result-label">高亮结果（文本分段）</p>
+        <pre class="tool-output regex-highlight" aria-label="正则高亮结果"><template v-for="segment in segments" :key="`${segment.index}-${segment.match}`"><mark v-if="segment.match" :aria-label="segment.text ? '匹配文本' : '零长度匹配'">{{ segment.text }}</mark><template v-else>{{ segment.text }}</template></template></pre>
+      </div>
+      <ol class="match-list" aria-label="匹配列表"><li v-for="(match, index) in matches" :key="`${match.index}-${index}`"><span>#{{ index + 1 }}</span><code>[{{ match.index }}, {{ match.end }})</code><span>{{ match.text || '（零长度匹配）' }}</span></li></ol>
+      <p v-if="truncated" class="tool-frame-status">匹配数量已达到 1000 上限。</p>
+    </div>
+  </EmbeddedToolFrame>
+</template>
+
+<style scoped>
+.tool-result-label { margin: 0 0 .35rem; color: var(--color-text-muted); font: var(--text-xs)/1 var(--font-mono); }
+.regex-highlight { min-height: 4rem; }
+.match-list { display: grid; gap: .25rem; max-height: 14rem; overflow: auto; margin: 0; padding: .7rem .7rem .7rem 2.3rem; border: 1px solid var(--color-border); color: var(--color-text-main); font: var(--text-xs)/1.45 var(--font-mono); }
+.match-list li { display: grid; grid-template-columns: 3rem 7rem minmax(0, 1fr); gap: .5rem; min-width: 0; }
+.match-list span:last-child { overflow-wrap: anywhere; }
+.match-list span:first-child, .match-list code { color: var(--color-text-muted); }
+@media (max-width: 520px) { .match-list li { grid-template-columns: 2.5rem minmax(5rem, 1fr); } .match-list span:last-child { grid-column: 2; } }
+</style>
diff --git a/apps/web/app/components/tools/TimestampTool.vue b/apps/web/app/components/tools/TimestampTool.vue
new file mode 100644
index 0000000..33414b0
--- /dev/null
+++ b/apps/web/app/components/tools/TimestampTool.vue
@@ -0,0 +1,63 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import EmbeddedToolFrame from './EmbeddedToolFrame.vue'
+import { datetimeLocalToTimestamp, timestampToDate, type TimestampResult } from '~/utils/timestampTool'
+import { copyText, validateInput } from '~/utils/embeddedToolUi'
+
+const timestamp = ref('')
+const localDate = ref('')
+const result = ref<TimestampResult>()
+const reverseResult = ref('')
+const error = ref('')
+const status = ref('')
+
+function convertTimestamp() {
+  error.value = ''; status.value = ''; result.value = undefined
+  const inputError = validateInput(timestamp.value, undefined, '时间戳输入')
+  if (inputError) { error.value = inputError; return }
+  try { result.value = timestampToDate(timestamp.value); status.value = `已按${result.value.unit}识别。` }
+  catch (cause) { error.value = cause instanceof Error ? cause.message : '时间戳转换失败。' }
+}
+
+function convertLocal() {
+  error.value = ''; status.value = ''; reverseResult.value = ''
+  try { reverseResult.value = datetimeLocalToTimestamp(localDate.value); status.value = 'datetime-local 已按浏览器本地时区转换为毫秒。' }
+  catch (cause) { error.value = cause instanceof Error ? cause.message : '本地日期转换失败。' }
+}
+
+async function copyResult(value: string) { try { await copyText(value); status.value = '结果已复制到剪贴板。' } catch (cause) { error.value = cause instanceof Error ? cause.message : '复制失败，请手动选择结果。' } }
+function clearTool() { timestamp.value = ''; localDate.value = ''; result.value = undefined; reverseResult.value = ''; error.value = ''; status.value = '' }
+</script>
+
+<template>
+  <EmbeddedToolFrame title="TIMESTAMP" description="自动识别秒/毫秒，显示浏览器本地时间与 UTC ISO；反向转换使用本地时区。" :error="error" :status="status">
+    <div class="tool-fields">
+      <div class="tool-grid">
+        <label>秒 / 毫秒时间戳<input v-model="timestamp" inputmode="numeric" autocomplete="off" placeholder="例如：1735689600" @keyup.enter="convertTimestamp"></label>
+        <label>datetime-local<input v-model="localDate" type="datetime-local" step="1" @keyup.enter="convertLocal"></label>
+      </div>
+      <div class="tool-actions">
+        <button class="tool-action" type="button" @click="convertTimestamp">转换时间戳</button>
+        <button class="tool-action" type="button" @click="convertLocal">反向转换</button>
+        <button class="tool-action" type="button" @click="clearTool">清空</button>
+      </div>
+      <dl v-if="result" class="timestamp-result" aria-label="时间戳转换结果">
+        <div><dt>识别单位</dt><dd>{{ result.unit }}</dd></div>
+        <div><dt>本地时间</dt><dd>{{ result.local }}</dd></div>
+        <div><dt>UTC ISO</dt><dd>{{ result.utc }}</dd></div>
+        <div><dt>毫秒值</dt><dd>{{ result.milliseconds }}</dd></div>
+        <button class="tool-action" type="button" @click="copyResult(`${result.local}\n${result.utc}`)">复制时间</button>
+      </dl>
+      <div v-if="reverseResult"><p class="tool-result-label">本地日期对应毫秒值</p><pre class="tool-output">{{ reverseResult }}</pre><button class="tool-action" type="button" @click="copyResult(reverseResult)">复制毫秒值</button></div>
+    </div>
+  </EmbeddedToolFrame>
+</template>
+
+<style scoped>
+.timestamp-result { display: grid; gap: .55rem; margin: 0; padding: .8rem; border: 1px solid var(--color-border); background: var(--color-code-bg); font: var(--text-sm)/1.5 var(--font-mono); }
+.timestamp-result div { display: grid; grid-template-columns: 7rem minmax(0, 1fr); gap: .75rem; }
+.timestamp-result dt { color: var(--color-text-muted); }
+.timestamp-result dd { margin: 0; overflow-wrap: anywhere; color: var(--color-text-main); }
+.timestamp-result .tool-action { justify-self: start; }
+.tool-result-label { margin: 0 0 .35rem; color: var(--color-text-muted); font: var(--text-xs)/1 var(--font-mono); }
+</style>
diff --git a/apps/web/app/components/tools/UrlCodecTool.vue b/apps/web/app/components/tools/UrlCodecTool.vue
new file mode 100644
index 0000000..bee8661
--- /dev/null
+++ b/apps/web/app/components/tools/UrlCodecTool.vue
@@ -0,0 +1,43 @@
+<script setup lang="ts">
+import { inject, ref } from 'vue'
+import EmbeddedToolFrame from './EmbeddedToolFrame.vue'
+import { embeddedWorkerKey } from '~/composables/useEmbeddedWorker'
+import { copyText, validateInput } from '~/utils/embeddedToolUi'
+
+const worker = inject(embeddedWorkerKey)
+const input = ref('')
+const output = ref('')
+const error = ref('')
+const status = ref('')
+const busy = ref(false)
+
+async function run(mode: 'encode' | 'decode') {
+  error.value = ''; status.value = ''
+  const inputError = validateInput(input.value, undefined, 'URL 输入')
+  if (inputError) { error.value = inputError; return }
+  busy.value = true
+  try { output.value = (await worker?.run('url-codec', { input: input.value, mode }))?.output || ''; status.value = mode === 'encode' ? '文本已编码。' : '百分号编码已严格校验并解码。' }
+  catch (cause) { error.value = cause instanceof Error ? cause.message : 'URL 编解码失败，请检查输入。' }
+  finally { busy.value = false }
+}
+
+async function copyResult() { try { await copyText(output.value); status.value = '结果已复制到剪贴板。' } catch (cause) { error.value = cause instanceof Error ? cause.message : '复制失败，请手动选择结果。' } }
+function clearTool() { input.value = ''; output.value = ''; error.value = ''; status.value = '' }
+</script>
+
+<template>
+  <EmbeddedToolFrame title="URL CODEC" description="使用 encodeURIComponent / decodeURIComponent 处理 URI 组件。" :error="error" :status="status">
+    <div class="tool-fields">
+      <label>输入<textarea v-model="input" spellcheck="false" autocomplete="off" placeholder="例如：极夜观测站?mode=scan" /></label>
+      <div class="tool-actions">
+        <button class="tool-action" type="button" :disabled="busy" @click="run('encode')">编码</button>
+        <button class="tool-action" type="button" :disabled="busy" @click="run('decode')">解码</button>
+        <button class="tool-action" type="button" :disabled="!output" @click="copyResult">复制结果</button>
+        <button class="tool-action" type="button" @click="clearTool">清空</button>
+      </div>
+      <div><p class="tool-result-label">结果</p><pre class="tool-output" aria-label="URL 结果">{{ output }}</pre></div>
+    </div>
+  </EmbeddedToolFrame>
+</template>
+
+<style scoped>.tool-result-label { margin: 0 0 .35rem; color: var(--color-text-muted); font: var(--text-xs)/1 var(--font-mono); }</style>
diff --git a/apps/web/app/composables/useEmbeddedWorker.ts b/apps/web/app/composables/useEmbeddedWorker.ts
new file mode 100644
index 0000000..9aa842f
--- /dev/null
+++ b/apps/web/app/composables/useEmbeddedWorker.ts
@@ -0,0 +1,74 @@
+import { onBeforeUnmount, type InjectionKey } from 'vue'
+import { type EmbeddedWorkerPayload, type EmbeddedWorkerResult, type EmbeddedWorkerTask } from '../utils/embeddedToolOperations'
+
+type WorkerResponse = { id: number; ok: boolean; result?: EmbeddedWorkerResult; error?: string }
+type Pending = { resolve: (result: EmbeddedWorkerResult) => void; reject: (error: Error) => void; timer: ReturnType<typeof setTimeout> }
+
+export const embeddedWorkerKey: InjectionKey<EmbeddedWorkerClient> = Symbol('haoblog-embedded-worker')
+
+export class EmbeddedWorkerClient {
+  private worker?: Worker
+  private nextId = 0
+  private disposed = false
+  private pending = new Map<number, Pending>()
+
+  async run(task: EmbeddedWorkerTask, payload: EmbeddedWorkerPayload, timeoutMs = 4000) {
+    if (this.disposed) throw new Error('工具组件已离开当前页面。')
+    const worker = this.ensureWorker()
+    const id = ++this.nextId
+    return new Promise<EmbeddedWorkerResult>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        this.rebuild(new Error('正则运行超过 250ms，已终止本次计算并重建 Worker。'))
+        reject(new Error('正则运行超过 250ms，已终止本次计算并重建 Worker。'))
+      }, timeoutMs)
+      this.pending.set(id, { resolve, reject, timer })
+      worker.postMessage({ id, task, payload })
+    })
+  }
+
+  destroy() {
+    this.disposed = true
+    this.rejectPending(new Error('工具组件已销毁，Worker 已终止。'))
+    this.worker?.terminate()
+    this.worker = undefined
+  }
+
+  private ensureWorker() {
+    if (this.worker) return this.worker
+    if (typeof Worker === 'undefined') throw new Error('当前浏览器不支持 Web Worker。')
+    const worker = new Worker(new URL('../workers/embedded-tool.worker.ts', import.meta.url), { type: 'module' })
+    worker.onmessage = (event: MessageEvent<WorkerResponse>) => {
+      const pending = this.pending.get(event.data.id)
+      if (!pending) return
+      this.pending.delete(event.data.id)
+      clearTimeout(pending.timer)
+      if (event.data.ok && event.data.result) pending.resolve(event.data.result)
+      else pending.reject(new Error(event.data.error || '工具运行失败，请检查输入。'))
+    }
+    worker.onerror = () => this.rebuild(new Error('工具 Worker 发生错误，已重建，请重试。'))
+    this.worker = worker
+    return worker
+  }
+
+  private rebuild(reason: Error) {
+    this.worker?.terminate()
+    this.worker = undefined
+    this.rejectPending(reason)
+    if (!this.disposed) this.ensureWorker()
+  }
+
+  private rejectPending(reason: Error) {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer)
+      pending.reject(reason)
+    }
+    this.pending.clear()
+  }
+}
+
+export function useEmbeddedWorker() {
+  const client = new EmbeddedWorkerClient()
+  onBeforeUnmount(() => client.destroy())
+  return client
+}
diff --git a/apps/web/app/pages/tools.vue b/apps/web/app/pages/tools.vue
index aef25f0..a75ca4a 100644
--- a/apps/web/app/pages/tools.vue
+++ b/apps/web/app/pages/tools.vue
@@ -1,5 +1,8 @@
 <script setup lang="ts">
+import { provide } from 'vue'
 import type { components } from '@haoblog/api-client'
+import { embeddedWorkerKey, useEmbeddedWorker } from '~/composables/useEmbeddedWorker'
+import { getEmbeddedToolComponent } from '~/utils/embeddedTools'
 
 type PublicTools = components['schemas']['PublicToolListResponse']
 type PublicTool = components['schemas']['PublicToolResponse']
@@ -23,6 +26,8 @@ const sortMode = ref<SortMode>('stable')
 const favorites = ref(new Set<string>())
 const usage = ref<Record<string, { count: number; lastUsed: string }>>({})
 const expanded = ref(new Set<string>())
+const embeddedWorker = useEmbeddedWorker()
+provide(embeddedWorkerKey, embeddedWorker)
 
 const tools = computed(() => data.value?.items || [])
 const categories = computed(() => data.value?.categories || [])
@@ -173,8 +178,10 @@ function safeExternalUrl(url: string | null) {
           <template v-if="tool.type === 'EMBEDDED'">
             <div class="embedded-slot" :data-component-key="tool.componentKey || undefined">
               <span class="slot-marker" aria-hidden="true">/</span>
-              <strong>内嵌组件槽位已建立</strong>
-              <span>当前版本未装载此工具算法；不会上传或模拟你的输入。</span>
+              <strong>内嵌组件槽位已建立 · 浏览器本地运行</strong>
+              <span>输入不会上传；组件按白名单 componentKey 懒加载。</span>
+              <component :is="getEmbeddedToolComponent(tool.componentKey)" v-if="getEmbeddedToolComponent(tool.componentKey)" />
+              <span v-else class="tool-warning">此工具组件未通过白名单校验，已停止装载。</span>
             </div>
           </template>
           <template v-else>
diff --git a/apps/web/app/utils/embeddedToolOperations.ts b/apps/web/app/utils/embeddedToolOperations.ts
new file mode 100644
index 0000000..3b426bc
--- /dev/null
+++ b/apps/web/app/utils/embeddedToolOperations.ts
@@ -0,0 +1,84 @@
+export type EmbeddedWorkerTask = 'json-format' | 'base64' | 'url-codec' | 'regex-test'
+
+export type EmbeddedWorkerPayload =
+  | { input: string; mode: 'format' | 'compact' }
+  | { input: string; mode: 'encode' | 'decode' }
+  | { input: string; mode: 'encode' | 'decode' }
+  | { pattern: string; flags: string; text: string }
+
+export type RegexMatch = { index: number; end: number; text: string }
+
+export type EmbeddedWorkerResult = {
+  output?: string
+  matches?: RegexMatch[]
+  truncated?: boolean
+}
+
+const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+export function runEmbeddedOperation(task: EmbeddedWorkerTask, payload: EmbeddedWorkerPayload): EmbeddedWorkerResult {
+  if (task === 'json-format') return runJson(payload as Extract<EmbeddedWorkerPayload, { mode: 'format' | 'compact' }>)
+  if (task === 'base64') return runBase64(payload as Extract<EmbeddedWorkerPayload, { mode: 'encode' | 'decode' }>)
+  if (task === 'url-codec') return runUrlCodec(payload as Extract<EmbeddedWorkerPayload, { mode: 'encode' | 'decode' }>)
+  return runRegex(payload as Extract<EmbeddedWorkerPayload, { pattern: string }>)
+}
+
+function runJson(payload: Extract<EmbeddedWorkerPayload, { mode: 'format' | 'compact' }>) {
+  if (!payload.input) throw new Error('请输入 JSON 内容。')
+  const value: unknown = JSON.parse(payload.input)
+  return { output: JSON.stringify(value, null, payload.mode === 'format' ? 2 : 0) }
+}
+
+function runBase64(payload: Extract<EmbeddedWorkerPayload, { mode: 'encode' | 'decode' }>) {
+  if (payload.mode === 'encode') {
+    const bytes = new TextEncoder().encode(payload.input)
+    let binary = ''
+    for (const byte of bytes) binary += String.fromCharCode(byte)
+    return { output: btoa(binary) }
+  }
+  if (!BASE64_PATTERN.test(payload.input) || payload.input.length % 4 !== 0) {
+    throw new Error('Base64 只接受规范的 A–Z、a–z、0–9、+、/ 字符和末尾 = 填充。')
+  }
+  const binary = atob(payload.input)
+  const bytes = Uint8Array.from(binary, character => character.charCodeAt(0))
+  const output = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  let canonical = ''
+  for (const byte of bytes) canonical += String.fromCharCode(byte)
+  if (btoa(canonical) !== payload.input) throw new Error('Base64 填充位无效，请检查编码内容。')
+  return { output }
+}
+
+function runUrlCodec(payload: Extract<EmbeddedWorkerPayload, { mode: 'encode' | 'decode' }>) {
+  try {
+    return { output: payload.mode === 'encode' ? encodeURIComponent(payload.input) : decodeURIComponent(payload.input) }
+  } catch {
+    throw new Error(payload.mode === 'decode' ? 'URL 含有非法百分号转义（需要 % 后跟两位十六进制数字）。' : '文本包含无法编码的字符（可能是未配对的 Unicode 代理项）。')
+  }
+}
+
+function runRegex(payload: Extract<EmbeddedWorkerPayload, { pattern: string }>) {
+  let expression: RegExp
+  try {
+    expression = new RegExp(payload.pattern, payload.flags)
+  } catch (error) {
+    throw new Error(`正则表达式无效：${error instanceof Error ? error.message : 'pattern 或 flags 不合法。'}`)
+  }
+  const matches: RegexMatch[] = []
+  const global = expression.global || expression.sticky
+  do {
+    const match = expression.exec(payload.text)
+    if (!match) break
+    matches.push({ index: match.index, end: match.index + match[0].length, text: match[0] })
+    if (matches.length === 1000) return { matches, truncated: Boolean(expression.exec(payload.text)) }
+    if (!global) break
+    if (!match[0].length) expression.lastIndex = advanceStringIndex(payload.text, expression.lastIndex, expression.unicode)
+  } while (global)
+  return { matches, truncated: false }
+}
+
+function advanceStringIndex(text: string, index: number, unicode: boolean) {
+  if (!unicode || index + 1 >= text.length) return index + 1
+  const first = text.charCodeAt(index)
+  const second = text.charCodeAt(index + 1)
+  return first >= 0xd800 && first <= 0xdbff && second >= 0xdc00 && second <= 0xdfff ? index + 2 : index + 1
+}
diff --git a/apps/web/app/utils/embeddedToolUi.ts b/apps/web/app/utils/embeddedToolUi.ts
new file mode 100644
index 0000000..06c0ad4
--- /dev/null
+++ b/apps/web/app/utils/embeddedToolUi.ts
@@ -0,0 +1,32 @@
+export const MAX_TOOL_INPUT_BYTES = 1024 * 1024
+export const MAX_REGEX_TEXT_BYTES = 100 * 1024
+
+export function inputBytes(value: string) {
+  return new TextEncoder().encode(value).byteLength
+}
+
+export function validateInput(value: string, maxBytes = MAX_TOOL_INPUT_BYTES, label = '输入') {
+  const bytes = inputBytes(value)
+  return bytes > maxBytes ? `${label}不能超过 ${formatBytes(maxBytes)}（当前 ${formatBytes(bytes)}）。` : ''
+}
+
+function formatBytes(bytes: number) {
+  return bytes >= 1024 * 1024 ? '1 MiB' : `${Math.round(bytes / 1024)} KiB`
+}
+
+export async function copyText(value: string) {
+  if (navigator.clipboard?.writeText) {
+    await navigator.clipboard.writeText(value)
+    return
+  }
+  const textarea = document.createElement('textarea')
+  textarea.value = value
+  textarea.setAttribute('readonly', '')
+  textarea.style.position = 'fixed'
+  textarea.style.opacity = '0'
+  document.body.append(textarea)
+  textarea.select()
+  const copied = document.execCommand('copy')
+  textarea.remove()
+  if (!copied) throw new Error('浏览器拒绝了复制操作，请手动选择结果。')
+}
diff --git a/apps/web/app/utils/embeddedTools.ts b/apps/web/app/utils/embeddedTools.ts
new file mode 100644
index 0000000..158dec2
--- /dev/null
+++ b/apps/web/app/utils/embeddedTools.ts
@@ -0,0 +1,15 @@
+import { defineAsyncComponent, type Component } from 'vue'
+
+export const embeddedToolComponents: Record<string, Component> = {
+  'json-format': defineAsyncComponent(() => import('~/components/tools/JsonFormatTool.vue')),
+  base64: defineAsyncComponent(() => import('~/components/tools/Base64Tool.vue')),
+  'url-codec': defineAsyncComponent(() => import('~/components/tools/UrlCodecTool.vue')),
+  timestamp: defineAsyncComponent(() => import('~/components/tools/TimestampTool.vue')),
+  'regex-test': defineAsyncComponent(() => import('~/components/tools/RegexTestTool.vue')),
+}
+
+export type EmbeddedComponentKey = keyof typeof embeddedToolComponents
+
+export function getEmbeddedToolComponent(componentKey: string | null | undefined) {
+  return componentKey ? embeddedToolComponents[componentKey] : undefined
+}
diff --git a/apps/web/app/utils/timestampTool.ts b/apps/web/app/utils/timestampTool.ts
new file mode 100644
index 0000000..1a2ba22
--- /dev/null
+++ b/apps/web/app/utils/timestampTool.ts
@@ -0,0 +1,31 @@
+export type TimestampResult = { unit: '秒' | '毫秒'; milliseconds: number; local: string; utc: string }
+
+const MAX_DATE_MS = 8_640_000_000_000_000
+
+export function timestampToDate(value: string): TimestampResult {
+  const trimmed = value.trim()
+  if (!trimmed) throw new Error('请输入秒或毫秒时间戳。')
+  if (!/^[+-]?\d+$/.test(trimmed)) throw new Error('时间戳必须是整数，不要包含空格、小数或单位。')
+  const number = Number(trimmed)
+  if (!Number.isSafeInteger(number)) throw new Error('时间戳超出 JavaScript 可安全表示的整数范围。')
+  const unit = Math.abs(number) < 100_000_000_000 ? '秒' : '毫秒'
+  const milliseconds = unit === '秒' ? number * 1000 : number
+  if (!Number.isSafeInteger(milliseconds) || Math.abs(milliseconds) > MAX_DATE_MS) throw new Error('时间戳超出 JavaScript Date 支持的范围。')
+  const date = new Date(milliseconds)
+  if (Number.isNaN(date.getTime())) throw new Error('时间戳无法转换为有效日期。')
+  return { unit, milliseconds, local: date.toLocaleString('zh-CN', { hour12: false }), utc: date.toISOString() }
+}
+
+export function datetimeLocalToTimestamp(value: string) {
+  if (!value) throw new Error('请选择本地日期和时间。')
+  const match = /^(\d{4,6})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/.exec(value)
+  if (!match) throw new Error('datetime-local 格式无效。')
+  const [, year, month, day, hour, minute, second = '0', fraction = '0'] = match
+  const date = new Date(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second), Number(fraction.padEnd(3, '0')))
+  if (Number.isNaN(date.getTime()) || date.getFullYear() !== Number(year) || date.getMonth() !== Number(month) - 1 || date.getDate() !== Number(day)
+    || date.getHours() !== Number(hour) || date.getMinutes() !== Number(minute) || date.getSeconds() !== Number(second)) {
+    throw new Error('datetime-local 不是一个有效的本地日期。')
+  }
+  if (Math.abs(date.getTime()) > MAX_DATE_MS) throw new Error('日期超出 JavaScript Date 支持的范围。')
+  return String(date.getTime())
+}
diff --git a/apps/web/app/workers/embedded-tool.worker.ts b/apps/web/app/workers/embedded-tool.worker.ts
new file mode 100644
index 0000000..242befc
--- /dev/null
+++ b/apps/web/app/workers/embedded-tool.worker.ts
@@ -0,0 +1,12 @@
+import { runEmbeddedOperation, type EmbeddedWorkerPayload, type EmbeddedWorkerTask } from '../utils/embeddedToolOperations'
+
+type WorkerRequest = { id: number; task: EmbeddedWorkerTask; payload: EmbeddedWorkerPayload }
+
+self.onmessage = (event: MessageEvent<WorkerRequest>) => {
+  const { id, task, payload } = event.data
+  try {
+    self.postMessage({ id, ok: true, result: runEmbeddedOperation(task, payload) })
+  } catch (error) {
+    self.postMessage({ id, ok: false, error: error instanceof Error ? error.message : '工具运行失败，请检查输入。' })
+  }
+}
diff --git a/apps/web/e2e/stage4.spec.ts b/apps/web/e2e/stage4.spec.ts
index 1d6bbe7..ba78d5a 100644
--- a/apps/web/e2e/stage4.spec.ts
+++ b/apps/web/e2e/stage4.spec.ts
@@ -127,3 +127,57 @@ test.describe('S4-07 public toolbox switchboard', () => {
     await touch.close()
   })
 })
+
+test.describe('S4-08 embedded browser tools', () => {
+  test('runs all five tools locally, keeps inputs out of the network, and stays usable at 360px', async ({ page }) => {
+    const response = await page.request.get('/api/v1/public/tools?type=EMBEDDED')
+    expect(response.ok()).toBe(true)
+    const payload = await response.json() as { items: Array<{ title: string; componentKey: string }> }
+    const expected = ['json-format', 'base64', 'url-codec', 'timestamp', 'regex-test']
+    expect(new Set(payload.items.map(item => item.componentKey))).toEqual(new Set(expected))
+
+    await page.setViewportSize({ width: 360, height: 900 })
+    await page.goto('/tools')
+    expect(await page.evaluate(() => document.documentElement.scrollWidth)).toBeLessThanOrEqual(360)
+    const requests: string[] = []
+    page.on('request', request => requests.push(request.url()))
+
+    const entryFor = (key: string) => page.locator('.tool-entry').filter({ has: page.locator(`[data-component-key="${key}"]`) })
+    for (const item of payload.items) {
+      const entry = page.locator('.tool-entry').filter({ hasText: item.title })
+      await entry.getByRole('button', { name: 'UNFOLD' }).click()
+      await expect(entry.locator(`[data-component-key="${item.componentKey}"]`)).toBeVisible()
+    }
+
+    const json = entryFor('json-format')
+    await json.getByLabel('JSON 输入').fill('{"ok":true}')
+    await json.getByRole('button', { name: '格式化 / 两空格' }).click()
+    await expect(json.locator('.tool-output')).toContainText('"ok": true')
+
+    const base64 = entryFor('base64')
+    await base64.getByLabel('输入').fill('中文')
+    await base64.getByRole('button', { name: 'UTF-8 编码' }).click()
+    await expect(base64.locator('.tool-output')).toHaveText('5Lit5paH')
+
+    const url = entryFor('url-codec')
+    await url.getByLabel('输入').fill('%E0%A4%A')
+    await url.getByRole('button', { name: '解码' }).click()
+    await expect(url).toContainText('非法百分号转义')
+
+    const timestamp = entryFor('timestamp')
+    await timestamp.getByLabel('秒 / 毫秒时间戳').fill('0')
+    await timestamp.getByRole('button', { name: '转换时间戳' }).click()
+    await expect(timestamp).toContainText('1970-01-01T00:00:00.000Z')
+
+    const regex = entryFor('regex-test')
+    await regex.getByLabel('pattern').fill('^')
+    await regex.getByLabel('flags').fill('gm')
+    await regex.getByLabel('测试文本').fill('a\nb')
+    await regex.getByRole('button', { name: '运行正则' }).click()
+    await expect(regex.getByRole('list', { name: '匹配列表' })).toContainText('零长度匹配')
+    expect(requests.filter(url => /\/api\/v1\//.test(url))).toEqual([])
+
+    await page.keyboard.press('Tab')
+    await expect(page.locator(':focus')).toBeVisible()
+  })
+})
diff --git a/apps/web/lighthouserc.cjs b/apps/web/lighthouserc.cjs
index 42eff7e..335d249 100644
--- a/apps/web/lighthouserc.cjs
+++ b/apps/web/lighthouserc.cjs
@@ -12,7 +12,8 @@ module.exports = {
         startServerReadyTimeout: 120000,
       }),
       url: [`${baseUrl}${articlePath}`],
-      numberOfRuns: 1,
+      // 移动端 Lighthouse 单次采样抖动明显，使用聚合结果避免偶发误报；性能门槛仍保持 0.90。
+      numberOfRuns: 3,
       settings: {
         formFactor: 'mobile',
         throttlingMethod: 'provided',
diff --git a/apps/web/test/embedded-tool-lazy-load.test.ts b/apps/web/test/embedded-tool-lazy-load.test.ts
new file mode 100644
index 0000000..65dc054
--- /dev/null
+++ b/apps/web/test/embedded-tool-lazy-load.test.ts
@@ -0,0 +1,29 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const app = resolve(import.meta.dirname, '../app')
+
+describe('public embedded tool loading boundary', () => {
+  it('keeps every tool behind the static componentKey registry and out of the closed directory route', () => {
+    const page = readFileSync(resolve(app, 'pages/tools.vue'), 'utf8')
+    const registry = readFileSync(resolve(app, 'utils/embeddedTools.ts'), 'utf8')
+    expect(page).toContain('getEmbeddedToolComponent')
+    expect(page).not.toContain('JsonFormatTool.vue')
+    expect(registry).toContain("'json-format': defineAsyncComponent(() => import('~/components/tools/JsonFormatTool.vue'))")
+    expect(registry).toContain("'regex-test': defineAsyncComponent(() => import('~/components/tools/RegexTestTool.vue'))")
+    expect(registry).toContain('base64: defineAsyncComponent')
+    expect(registry).toContain("'url-codec': defineAsyncComponent")
+    expect(registry).toContain('timestamp: defineAsyncComponent')
+  })
+
+  it('uses text-node rendering and does not introduce execution or upload sinks', () => {
+    const tools = readFileSync(resolve(app, 'pages/tools.vue'), 'utf8')
+    const components = ['EmbeddedToolFrame.vue', 'JsonFormatTool.vue', 'Base64Tool.vue', 'UrlCodecTool.vue', 'TimestampTool.vue', 'RegexTestTool.vue']
+      .map(file => readFileSync(resolve(app, 'components/tools', file), 'utf8')).join('\n')
+    expect(`${tools}\n${components}`).not.toMatch(/v-html|\beval\s*\(|new Function\s*\(/)
+    expect(components).toContain('aria-live="polite"')
+    expect(components).toContain('<mark')
+    expect(components).not.toContain('fetch(')
+  })
+})
diff --git a/apps/web/test/embedded-tools.test.ts b/apps/web/test/embedded-tools.test.ts
new file mode 100644
index 0000000..b240a4b
--- /dev/null
+++ b/apps/web/test/embedded-tools.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EmbeddedWorkerClient } from '../app/composables/useEmbeddedWorker'
+import { runEmbeddedOperation } from '../app/utils/embeddedToolOperations'
+import { MAX_REGEX_TEXT_BYTES, MAX_TOOL_INPUT_BYTES, inputBytes, validateInput } from '../app/utils/embeddedToolUi'
+import { datetimeLocalToTimestamp, timestampToDate } from '../app/utils/timestampTool'
+
+describe('embedded tool operations', () => {
+  it('formats and compacts JSON without evaluating input', () => {
+    expect(runEmbeddedOperation('json-format', { input: '{"中文":[1,true]}', mode: 'format' }).output).toBe('{\n  "中文": [\n    1,\n    true\n  ]\n}')
+    expect(runEmbeddedOperation('json-format', { input: '{ "a": 1 }', mode: 'compact' }).output).toBe('{"a":1}')
+    expect(() => runEmbeddedOperation('json-format', { input: '{oops', mode: 'format' })).toThrow()
+  })
+
+  it('enforces byte limits, including Unicode bytes, before a task is sent', () => {
+    expect(inputBytes('🙂')).toBe(4)
+    expect(validateInput('a'.repeat(MAX_TOOL_INPUT_BYTES))).toBe('')
+    expect(validateInput('a'.repeat(MAX_TOOL_INPUT_BYTES + 1))).toMatch(/1 MiB/)
+    expect(validateInput('a'.repeat(MAX_REGEX_TEXT_BYTES + 1), MAX_REGEX_TEXT_BYTES, '测试文本')).toMatch(/100 KiB/)
+    expect(runEmbeddedOperation('base64', { input: '', mode: 'encode' }).output).toBe('')
+    expect(runEmbeddedOperation('url-codec', { input: '', mode: 'decode' }).output).toBe('')
+    expect(() => timestampToDate('')).toThrow()
+  })
+
+  it('round-trips Chinese UTF-8 text and rejects malformed Base64', () => {
+    const encoded = runEmbeddedOperation('base64', { input: '极夜观测站 / signal', mode: 'encode' }).output
+    expect(encoded).toBe('5p6B5aSc6KeC5rWL56uZIC8gc2lnbmFs')
+    expect(runEmbeddedOperation('base64', { input: encoded || '', mode: 'decode' }).output).toBe('极夜观测站 / signal')
+    expect(() => runEmbeddedOperation('base64', { input: 'abc', mode: 'decode' })).toThrow(/Base64/)
+    expect(() => runEmbeddedOperation('base64', { input: 'AB==', mode: 'decode' })).toThrow(/填充位/)
+  })
+
+  it('encodes Unicode URL components and explains invalid escapes', () => {
+    const encoded = runEmbeddedOperation('url-codec', { input: '极夜观测站?x=1', mode: 'encode' }).output
+    expect(encoded).toBe('%E6%9E%81%E5%A4%9C%E8%A7%82%E6%B5%8B%E7%AB%99%3Fx%3D1')
+    expect(runEmbeddedOperation('url-codec', { input: encoded || '', mode: 'decode' }).output).toBe('极夜观测站?x=1')
+    expect(() => runEmbeddedOperation('url-codec', { input: '%E0%A4%A', mode: 'decode' })).toThrow(/非法百分号转义/)
+  })
+
+  it('recognizes seconds and milliseconds and keeps the browser timezone in reverse conversion', () => {
+    expect(timestampToDate('0')).toMatchObject({ unit: '秒', milliseconds: 0, utc: '1970-01-01T00:00:00.000Z' })
+    expect(timestampToDate('1735689600000')).toMatchObject({ unit: '毫秒', milliseconds: 1735689600000, utc: '2025-01-01T00:00:00.000Z' })
+    expect(() => timestampToDate('8640000000000001')).toThrow(/Date|范围/)
+    expect(Number(datetimeLocalToTimestamp('1970-01-01T00:00'))).toBe(new Date(1970, 0, 1).getTime())
+    expect(() => datetimeLocalToTimestamp('2025-02-31T10:00')).toThrow(/有效的本地日期/)
+  })
+
+  it('returns flags, zero-length matches and at most 1000 matches', () => {
+    expect(runEmbeddedOperation('regex-test', { pattern: 'é', flags: 'giu', text: 'É é' }).matches).toHaveLength(2)
+    expect(runEmbeddedOperation('regex-test', { pattern: '^', flags: 'gm', text: 'a\nb' }).matches).toEqual([
+      { index: 0, end: 0, text: '' }, { index: 2, end: 2, text: '' },
+    ])
+    const result = runEmbeddedOperation('regex-test', { pattern: 'x', flags: 'g', text: 'x'.repeat(1001) })
+    expect(result.matches).toHaveLength(1000)
+    expect(result.truncated).toBe(true)
+  })
+})
+
+describe('embedded worker lifecycle', () => {
+  it('terminates and rebuilds a worker after a regex timeout', async () => {
+    class HangingWorker {
+      static instances: HangingWorker[] = []
+      onmessage: ((event: MessageEvent) => void) | null = null
+      onerror: (() => void) | null = null
+      terminated = false
+      constructor() { HangingWorker.instances.push(this) }
+      postMessage() {}
+      terminate() { this.terminated = true }
+    }
+    vi.stubGlobal('Worker', HangingWorker)
+    const client = new EmbeddedWorkerClient()
+    await expect(client.run('regex-test', { pattern: '(a+)+$', flags: '', text: 'a'.repeat(100) + '!' }, 10)).rejects.toThrow(/250ms/)
+    expect(HangingWorker.instances[0].terminated).toBe(true)
+    expect(HangingWorker.instances).toHaveLength(2)
+    client.destroy()
+    expect(HangingWorker.instances[1].terminated).toBe(true)
+    vi.unstubAllGlobals()
+  })
+
+  it('ignores a response that arrived after its request was removed', async () => {
+    class LateWorker {
+      static instance: LateWorker
+      onmessage: ((event: MessageEvent) => void) | null = null
+      onerror: (() => void) | null = null
+      constructor() { LateWorker.instance = this }
+      postMessage(message: { id: number }) { setTimeout(() => this.onmessage?.({ data: { id: message.id, ok: true, result: { output: 'late' } } } as MessageEvent), 20) }
+      terminate() {}
+    }
+    vi.stubGlobal('Worker', LateWorker)
+    const client = new EmbeddedWorkerClient()
+    const first = client.run('url-codec', { input: 'a', mode: 'encode' }, 5)
+    await expect(first).rejects.toThrow(/250ms/)
+    await new Promise(resolve => setTimeout(resolve, 30))
+    client.destroy()
+    vi.unstubAllGlobals()
+  })
+})

From 1b066e3c91038c4a292f86566d10c43dbf6ef221 Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 15:48:27 +0800
Subject: [PATCH 11/15] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=86=85=E5=B5=8C?=
 =?UTF-8?q?=E5=B7=A5=E5=85=B7=E9=AA=8C=E6=94=B6=E5=AE=9A=E4=BD=8D=E5=86=B2?=
 =?UTF-8?q?=E7=AA=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 apps/web/e2e/stage4.spec.ts | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/apps/web/e2e/stage4.spec.ts b/apps/web/e2e/stage4.spec.ts
index ba78d5a..f2cdb8f 100644
--- a/apps/web/e2e/stage4.spec.ts
+++ b/apps/web/e2e/stage4.spec.ts
@@ -135,6 +135,13 @@ test.describe('S4-08 embedded browser tools', () => {
     const payload = await response.json() as { items: Array<{ title: string; componentKey: string }> }
     const expected = ['json-format', 'base64', 'url-codec', 'timestamp', 'regex-test']
     expect(new Set(payload.items.map(item => item.componentKey))).toEqual(new Set(expected))
+    const seededTitles: Record<string, string> = {
+      'json-format': 'JSON 格式化',
+      base64: 'Base64 编解码',
+      'url-codec': 'URL 编解码',
+      timestamp: '时间戳转换',
+      'regex-test': '正则测试',
+    }
 
     await page.setViewportSize({ width: 360, height: 900 })
     await page.goto('/tools')
@@ -142,11 +149,11 @@ test.describe('S4-08 embedded browser tools', () => {
     const requests: string[] = []
     page.on('request', request => requests.push(request.url()))
 
-    const entryFor = (key: string) => page.locator('.tool-entry').filter({ has: page.locator(`[data-component-key="${key}"]`) })
-    for (const item of payload.items) {
-      const entry = page.locator('.tool-entry').filter({ hasText: item.title })
+    const entryFor = (key: string) => page.locator('.tool-entry').filter({ hasText: seededTitles[key] }).filter({ has: page.locator(`[data-component-key="${key}"]`) })
+    for (const key of expected) {
+      const entry = entryFor(key)
       await entry.getByRole('button', { name: 'UNFOLD' }).click()
-      await expect(entry.locator(`[data-component-key="${item.componentKey}"]`)).toBeVisible()
+      await expect(entry.locator(`[data-component-key="${key}"]`)).toBeVisible()
     }
 
     const json = entryFor('json-format')

From 57a03a4b04aeacd0d5b58071cdb5709fb0803bf8 Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 15:58:03 +0800
Subject: [PATCH 12/15] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=86=85=E5=B5=8C?=
 =?UTF-8?q?=E5=B7=A5=E5=85=B7=E5=B1=95=E5=BC=80=E5=89=8D=E7=9A=84=E6=B5=8B?=
 =?UTF-8?q?=E8=AF=95=E5=AE=9A=E4=BD=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 apps/web/e2e/stage4.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/e2e/stage4.spec.ts b/apps/web/e2e/stage4.spec.ts
index f2cdb8f..4cc153a 100644
--- a/apps/web/e2e/stage4.spec.ts
+++ b/apps/web/e2e/stage4.spec.ts
@@ -149,7 +149,7 @@ test.describe('S4-08 embedded browser tools', () => {
     const requests: string[] = []
     page.on('request', request => requests.push(request.url()))
 
-    const entryFor = (key: string) => page.locator('.tool-entry').filter({ hasText: seededTitles[key] }).filter({ has: page.locator(`[data-component-key="${key}"]`) })
+    const entryFor = (key: string) => page.locator('.tool-entry').filter({ hasText: seededTitles[key] })
     for (const key of expected) {
       const entry = entryFor(key)
       await entry.getByRole('button', { name: 'UNFOLD' }).click()

From 0b3b5b8400c308339d7ce53c007c13c4e4da8652 Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 16:21:40 +0800
Subject: [PATCH 13/15] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20URL=20=E8=A7=A3?=
 =?UTF-8?q?=E7=A0=81=E6=8C=89=E9=92=AE=E6=B5=8B=E8=AF=95=E5=AE=9A=E4=BD=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 apps/web/e2e/stage4.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/e2e/stage4.spec.ts b/apps/web/e2e/stage4.spec.ts
index 4cc153a..b61755f 100644
--- a/apps/web/e2e/stage4.spec.ts
+++ b/apps/web/e2e/stage4.spec.ts
@@ -168,7 +168,7 @@ test.describe('S4-08 embedded browser tools', () => {
 
     const url = entryFor('url-codec')
     await url.getByLabel('输入').fill('%E0%A4%A')
-    await url.getByRole('button', { name: '解码' }).click()
+    await url.getByRole('button', { name: '解码', exact: true }).click()
     await expect(url).toContainText('非法百分号转义')
 
     const timestamp = entryFor('timestamp')

From c246517ce7dfefbc72f8b2dd15e9429a25290111 Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 16:55:43 +0800
Subject: [PATCH 14/15] =?UTF-8?q?=E5=AE=8C=E6=88=90=20S4-09=20=E6=9C=80?=
 =?UTF-8?q?=E5=B0=8F=E6=96=87=E7=AB=A0=E6=90=9C=E7=B4=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../content/application/ArticleService.java   | 26 +++++++
 .../ArticleRevisionRepository.java            | 44 +++++++++++
 .../content/web/PublicSearchController.java   | 71 ++++++++++++++++++
 .../V15__article_search_trgm_index.sql        |  4 +
 .../test/java/io/haoblog/ContentModelIT.java  |  2 +-
 .../src/test/java/io/haoblog/PublicApiIT.java | 75 +++++++++++++++++++
 .../java/io/haoblog/PublicSearchTest.java     | 75 +++++++++++++++++++
 .../application/ArticleServiceTest.java       | 22 ++++++
 apps/web/app/assets/styles/articles.css       | 14 ++++
 .../components/articles/PublicArticleList.vue | 12 ++-
 apps/web/app/pages/articles/index.vue         |  1 +
 apps/web/app/pages/search.vue                 | 71 ++++++++++++++++++
 apps/web/app/utils/publicSearch.ts            | 20 +++++
 apps/web/e2e/stage4.spec.ts                   | 46 ++++++++++++
 apps/web/test/public-article-ssr.test.ts      | 19 +++++
 docs/openapi/public-api.yaml                  | 35 +++++++++
 packages/api-client/src/generated.ts          | 56 ++++++++++++++
 17 files changed, 589 insertions(+), 4 deletions(-)
 create mode 100644 apps/api/src/main/java/io/haoblog/content/web/PublicSearchController.java
 create mode 100644 apps/api/src/main/resources/db/migration/V15__article_search_trgm_index.sql
 create mode 100644 apps/api/src/test/java/io/haoblog/PublicSearchTest.java
 create mode 100644 apps/web/app/pages/search.vue
 create mode 100644 apps/web/app/utils/publicSearch.ts

diff --git a/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java b/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
index 5f03e18..958ca94 100644
--- a/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
+++ b/apps/api/src/main/java/io/haoblog/content/application/ArticleService.java
@@ -11,6 +11,7 @@
 import org.springframework.stereotype.Service;
 
 import java.time.Clock;
+import java.text.Normalizer;
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
@@ -59,6 +60,28 @@ public PublishedBatch listPublishedBatch(int page, int size) {
         var result = repository.findPublished(ArticleStatus.PUBLISHED, java.time.Instant.now(clock), PageRequest.of(page, size));
         return new PublishedBatch(result.getContent().stream().map(this::toPublicFeedArticle).toList(), result.hasNext());
     }
+
+    public SearchPage search(String query, int page, int size) {
+        String normalizedQuery = normalizeSearchQuery(query);
+        if (page < 0 || size < 1 || size > 20) throw new IllegalArgumentException("page/size out of range");
+        var result = repository.searchVisible(toLikePattern(normalizedQuery), java.time.Instant.now(clock),
+                PageRequest.of(page, size));
+        return new SearchPage(normalizedQuery, result.map(projection -> new PublicSearchArticle(
+                projection.getId(), projection.getSlug(), projection.getTitle(), projection.getExcerpt(),
+                projection.getPublishedAt(), projection.getCoverMediaId(), projection.getCommentsEnabled())));
+    }
+
+    public static String normalizeSearchQuery(String query) {
+        if (query == null) throw new IllegalArgumentException("query is required");
+        String normalized = Normalizer.normalize(query, Normalizer.Form.NFKC).strip();
+        int length = normalized.codePointCount(0, normalized.length());
+        if (length < 2 || length > 100) throw new IllegalArgumentException("query length out of range");
+        return normalized;
+    }
+
+    private static String toLikePattern(String query) {
+        return "%" + query.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_") + "%";
+    }
     public Map<UUID, String> publicCoverUrls(Collection<UUID> mediaIds) {
         if (mediaIds == null || mediaIds.isEmpty()) return Map.of();
         return mediaRepository.findAllByIdInAndStatus(mediaIds, MediaAssetStatus.AVAILABLE).stream()
@@ -88,4 +111,7 @@ public UUID articleId() {
     public record PageResult(Page<PublicArticle> page) {}
     public record PublishedBatch(List<PublicFeedArticle> items, boolean hasNext) {}
     public record PublicFeedArticle(UUID id, String slug, String title, String excerpt, java.time.Instant publishedAt) {}
+    public record SearchPage(String query, Page<PublicSearchArticle> page) {}
+    public record PublicSearchArticle(UUID id, String slug, String title, String excerpt,
+                                      java.time.Instant publishedAt, UUID coverMediaId, boolean commentsEnabled) {}
 }
diff --git a/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java b/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java
index 56c0a0a..8017597 100644
--- a/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java
+++ b/apps/api/src/main/java/io/haoblog/content/persistence/ArticleRevisionRepository.java
@@ -8,6 +8,7 @@
 import org.springframework.data.jpa.repository.Query;
 import org.springframework.data.repository.query.Param;
 
+import java.time.Instant;
 import java.util.Optional;
 import java.util.UUID;
 
@@ -66,6 +67,39 @@ Page<PublicArticleProjection> findPublished(@Param("published") ArticleStatus pu
                                                 @Param("now") java.time.Instant now,
                                                 Pageable pageable);
 
+    @Query(value = """
+            select a.id as id, r.slug as slug, r.title as title, r.excerpt as excerpt,
+                   a.published_at as "publishedAt", r.cover_media_id as "coverMediaId",
+                   a.comments_enabled as "commentsEnabled"
+            from article_revision r
+            join article a on a.published_revision_id = r.id
+            where a.status in ('PUBLISHED', 'SCHEDULED')
+              and a.published_revision_id is not null
+              and a.published_at is not null
+              and a.published_at <= :now
+              and (coalesce(r.title, '') || ' ' || coalesce(r.excerpt, '') || ' ' || r.markdown_source)
+                    ilike :pattern escape chr(92)
+            order by case
+                         when r.title ilike :pattern escape chr(92) then 0
+                         when coalesce(r.excerpt, '') ilike :pattern escape chr(92) then 1
+                         else 2
+                       end,
+                       a.published_at desc, a.id desc
+            """,
+            countQuery = """
+            select count(*)
+            from article_revision r
+            join article a on a.published_revision_id = r.id
+            where a.status in ('PUBLISHED', 'SCHEDULED')
+              and a.published_revision_id is not null
+              and a.published_at is not null
+              and a.published_at <= :now
+              and (coalesce(r.title, '') || ' ' || coalesce(r.excerpt, '') || ' ' || r.markdown_source)
+                    ilike :pattern escape chr(92)
+            """, nativeQuery = true)
+    Page<SearchProjection> searchVisible(@Param("pattern") String pattern, @Param("now") Instant now,
+                                         Pageable pageable);
+
     @Query("""
             select r as revision, a.publishedAt as publishedAt, a.commentsEnabled as commentsEnabled
             from ArticleRevision r, Article a
@@ -114,4 +148,14 @@ interface SummaryProjection {
     interface NotificationArticleProjection {
         String getTitle();
     }
+
+    interface SearchProjection {
+        UUID getId();
+        String getSlug();
+        String getTitle();
+        String getExcerpt();
+        Instant getPublishedAt();
+        UUID getCoverMediaId();
+        boolean getCommentsEnabled();
+    }
 }
diff --git a/apps/api/src/main/java/io/haoblog/content/web/PublicSearchController.java b/apps/api/src/main/java/io/haoblog/content/web/PublicSearchController.java
new file mode 100644
index 0000000..b31252c
--- /dev/null
+++ b/apps/api/src/main/java/io/haoblog/content/web/PublicSearchController.java
@@ -0,0 +1,71 @@
+package io.haoblog.content.web;
+
+import io.haoblog.content.application.ArticleService;
+import io.haoblog.site.application.SiteService;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.HexFormat;
+import java.util.Map;
+import java.util.UUID;
+import java.util.stream.Collectors;
+
+@RestController
+@RequestMapping("/api/v1/public/search")
+public class PublicSearchController {
+    private final ArticleService service;
+    private final SiteService siteService;
+
+    public PublicSearchController(ArticleService service, SiteService siteService) {
+        this.service = service;
+        this.siteService = siteService;
+    }
+
+    @GetMapping("/articles")
+    public ResponseEntity<PublicArticleController.ArticleListResponse> articles(
+            @RequestParam String q,
+            @RequestParam(defaultValue = "0") int page,
+            @RequestParam(defaultValue = "20") int size,
+            @RequestHeader(value = HttpHeaders.IF_NONE_MATCH, required = false) String ifNoneMatch) {
+        var result = service.search(q, page, size);
+        var searchPage = result.page();
+        Map<UUID, String> coverUrls = service.publicCoverUrls(searchPage.getContent().stream()
+                .map(ArticleService.PublicSearchArticle::coverMediaId)
+                .filter(java.util.Objects::nonNull)
+                .collect(Collectors.toSet()));
+        var site = siteService.get();
+        boolean globalCommentsEnabled = site == null || site.commentsEnabled();
+        var response = new PublicArticleController.ArticleListResponse(
+                searchPage.getContent().stream().map(article -> new PublicArticleController.ArticleSummary(
+                        article.id(), article.slug(), article.title(), article.excerpt(), article.publishedAt(),
+                        article.coverMediaId() == null ? null : coverUrls.get(article.coverMediaId()),
+                        article.commentsEnabled() && globalCommentsEnabled)).toList(),
+                searchPage.getNumber(), searchPage.getSize(), searchPage.getTotalElements());
+        return withCache(response, representationHash("search", result.query(), response), ifNoneMatch);
+    }
+
+    private <T> ResponseEntity<T> withCache(T body, String etag, String ifNoneMatch) {
+        var headers = new HttpHeaders();
+        headers.setETag(etag);
+        headers.setCacheControl("public, max-age=0, s-maxage=60, must-revalidate");
+        if (etag.equals(ifNoneMatch)) return ResponseEntity.status(304).headers(headers).build();
+        return ResponseEntity.ok().headers(headers).body(body);
+    }
+
+    private static String representationHash(Object... values) {
+        try {
+            var digest = MessageDigest.getInstance("SHA-256");
+            String stableInput = java.util.Arrays.deepToString(values);
+            return '"' + HexFormat.of().formatHex(digest.digest(stableInput.getBytes(StandardCharsets.UTF_8))) + '"';
+        } catch (Exception exception) {
+            throw new IllegalStateException("Unable to create article search representation ETag", exception);
+        }
+    }
+}
diff --git a/apps/api/src/main/resources/db/migration/V15__article_search_trgm_index.sql b/apps/api/src/main/resources/db/migration/V15__article_search_trgm_index.sql
new file mode 100644
index 0000000..4f20f56
--- /dev/null
+++ b/apps/api/src/main/resources/db/migration/V15__article_search_trgm_index.sql
@@ -0,0 +1,4 @@
+CREATE INDEX article_revision_search_trgm_idx
+    ON article_revision USING gin (
+        (COALESCE(title, '') || ' ' || COALESCE(excerpt, '') || ' ' || markdown_source) gin_trgm_ops
+    );
diff --git a/apps/api/src/test/java/io/haoblog/ContentModelIT.java b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
index d681245..7ca0255 100644
--- a/apps/api/src/test/java/io/haoblog/ContentModelIT.java
+++ b/apps/api/src/test/java/io/haoblog/ContentModelIT.java
@@ -57,7 +57,7 @@ static void database(DynamicPropertyRegistry registry) {
 
     @Test
     void migratesAllVersionsAndCreatesContentTables() {
-        assertEquals(14, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
+        assertEquals(15, jdbc.queryForObject("SELECT count(*) FROM flyway_schema_history", Integer.class));
         for (String table : List.of("article", "category", "tag", "article_tag", "article_revision",
                 "article_preview_token", "media_asset", "media_upload", "outbox_event", "comment")) {
             assertEquals(1, jdbc.queryForObject(
diff --git a/apps/api/src/test/java/io/haoblog/PublicApiIT.java b/apps/api/src/test/java/io/haoblog/PublicApiIT.java
index 87294ae..c252f7f 100644
--- a/apps/api/src/test/java/io/haoblog/PublicApiIT.java
+++ b/apps/api/src/test/java/io/haoblog/PublicApiIT.java
@@ -18,6 +18,7 @@
 import java.time.Instant;
 import java.time.temporal.ChronoUnit;
 import java.util.UUID;
+import java.util.List;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
 import static org.junit.jupiter.api.Assertions.*;
@@ -109,6 +110,77 @@ static void database(DynamicPropertyRegistry registry) {
                 .andExpect(jsonPath("$.title").value("HaoBlog"));
     }
 
+    @Test
+    void searchNormalizesUnicodeMatchesCaseInsensitivelyAndRanksFields() throws Exception {
+        seedPublished("search-title", "SIGNAL title", "no match", "# body", Instant.now().minus(3, ChronoUnit.HOURS), Instant.now());
+        seedPublished("search-excerpt", "Older title", "SIGNAL excerpt", "# body", Instant.now().minus(2, ChronoUnit.HOURS), Instant.now());
+        seedPublished("search-body", "Oldest title", "no match", "# SIGNAL body", Instant.now().minus(1, ChronoUnit.HOURS), Instant.now());
+
+        mvc.perform(get("/api/v1/public/search/articles").param("q", "  ＳＩＧＮＡＬ  "))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.total").value(3))
+                .andExpect(jsonPath("$.items[0].title").value("SIGNAL title"))
+                .andExpect(jsonPath("$.items[1].title").value("Older title"))
+                .andExpect(jsonPath("$.items[2].title").value("Oldest title"))
+                .andExpect(content().string(org.hamcrest.Matchers.not(org.hamcrest.Matchers.containsString("markdown"))));
+    }
+
+    @Test
+    void searchEscapesPercentUnderscoreAndBackslashAndKeepsOnlyPublishedSnapshot() throws Exception {
+        seedPublished("search-special", "Literal %_\\ path", "special token", "# special", Instant.now(), Instant.now());
+        UUID archivedId = seedPublished("search-archived", "Literal %_\\ archived", "special token", "# special", Instant.now(), Instant.now());
+        jdbc.update("UPDATE article SET status='ARCHIVED' WHERE id=?", archivedId);
+
+        mvc.perform(get("/api/v1/public/search/articles").param("q", "%_\\"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.total").value(1))
+                .andExpect(jsonPath("$.items[0].slug").value("search-special"));
+        mvc.perform(get("/api/v1/public/search/articles").param("q", "Future"))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.total").value(0));
+    }
+
+    @Test
+    void searchPaginatesEmptyResultsAndIsolatesUnpublishedWorkingChanges() throws Exception {
+        for (int index = 0; index < 21; index++) {
+            seedPublished("search-page-" + index, "Page match " + index, "page", "# page", Instant.now().minus(index, ChronoUnit.MINUTES), Instant.now());
+        }
+        mvc.perform(get("/api/v1/public/search/articles").param("q", "page").param("size", "20"))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.total").value(21)).andExpect(jsonPath("$.items.length()").value(20));
+        mvc.perform(get("/api/v1/public/search/articles").param("q", "page").param("page", "1").param("size", "20"))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.items.length()").value(1));
+        mvc.perform(get("/api/v1/public/search/articles").param("q", "no-such-signal"))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.total").value(0)).andExpect(jsonPath("$.items.length()").value(0));
+
+        UUID articleId = seedPublished("search-snapshot", "Published snapshot", "published", "# published", Instant.now(), Instant.now());
+        jdbc.update("UPDATE article SET title=?, excerpt=?, markdown_source=? WHERE id=?",
+                "Unpublished working copy", "unpublished", "# unpublished", articleId);
+        mvc.perform(get("/api/v1/public/search/articles").param("q", "Published"))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.total").value(1));
+        mvc.perform(get("/api/v1/public/search/articles").param("q", "Unpublished"))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.total").value(0));
+    }
+
+    @Test
+    void searchQueryUsesTheTrigramExpressionIndex() {
+        jdbc.execute("SET enable_seqscan = off");
+        try {
+            List<String> plan = jdbc.queryForList("""
+                    EXPLAIN (COSTS OFF)
+                    SELECT r.id
+                    FROM article_revision r
+                    JOIN article a ON a.published_revision_id = r.id
+                    WHERE a.status IN ('PUBLISHED', 'SCHEDULED')
+                      AND a.published_at IS NOT NULL
+                      AND a.published_at <= now()
+                      AND (coalesce(r.title, '') || ' ' || coalesce(r.excerpt, '') || ' ' || r.markdown_source)
+                            ILIKE '%Vis%' ESCAPE chr(92)
+                    """, String.class);
+            assertTrue(plan.stream().anyMatch(line -> line.contains("article_revision_search_trgm_idx")), plan.toString());
+        } finally {
+            jdbc.execute("RESET enable_seqscan");
+        }
+    }
+
     @Test void feedsContainOnlyPublishedArticlesAndSupportConditionalCaching() throws Exception {
         seedPublished("newer-feed", "Newer feed", "Newest", "# newer", Instant.now().minus(30, ChronoUnit.SECONDS), Instant.now());
         UUID archivedId = seedPublished("archived-feed", "Archived feed", "No", "# archived", Instant.now().minus(1, ChronoUnit.DAYS), Instant.now());
@@ -159,6 +231,9 @@ static void database(DynamicPropertyRegistry registry) {
         assertEquals(1, jdbc.queryForObject("SELECT count(*) FROM pg_index WHERE indexrelid='article_public_published_idx'::regclass AND indpred IS NOT NULL", Integer.class));
         String predicate = jdbc.queryForObject("SELECT pg_get_expr(indpred, indrelid) FROM pg_index WHERE indexrelid='article_public_published_idx'::regclass", String.class);
         assertTrue(predicate.contains("status") && predicate.contains("PUBLISHED") && predicate.contains("published_at"));
+        assertEquals(1, jdbc.queryForObject("SELECT count(*) FROM pg_indexes WHERE indexname='article_revision_search_trgm_idx'", Integer.class));
+        String searchIndex = jdbc.queryForObject("SELECT indexdef FROM pg_indexes WHERE indexname='article_revision_search_trgm_idx'", String.class);
+        assertTrue(searchIndex.contains("gin") && searchIndex.contains("gin_trgm_ops"));
     }
 
     @Test void applicationPersistsUuidV7WithoutDatabaseUuidDefault() {
diff --git a/apps/api/src/test/java/io/haoblog/PublicSearchTest.java b/apps/api/src/test/java/io/haoblog/PublicSearchTest.java
new file mode 100644
index 0000000..1f4cdd3
--- /dev/null
+++ b/apps/api/src/test/java/io/haoblog/PublicSearchTest.java
@@ -0,0 +1,75 @@
+package io.haoblog;
+
+import io.haoblog.content.application.ArticleService;
+import io.haoblog.content.web.PublicSearchController;
+import io.haoblog.shared.web.GlobalExceptionHandler;
+import io.haoblog.shared.web.ProblemResponseWriter;
+import io.haoblog.shared.web.TraceIdFilter;
+import io.haoblog.site.application.SiteService;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.time.Instant;
+import java.util.List;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(PublicSearchController.class)
+@Import({TraceIdFilter.class, GlobalExceptionHandler.class, ProblemResponseWriter.class})
+class PublicSearchTest {
+    @Autowired MockMvc mvc;
+    @MockitoBean ArticleService articleService;
+    @MockitoBean SiteService siteService;
+
+    @Test
+    void validatesSearchAndReturnsSafeProblemForInvalidInput() throws Exception {
+        when(articleService.search(any(), any(Integer.class), any(Integer.class)))
+                .thenThrow(new IllegalArgumentException("query/page/size out of range"));
+
+        for (String query : new String[]{"", "a", "a".repeat(101)}) {
+            mvc.perform(get("/api/v1/public/search/articles").param("q", query))
+                    .andExpect(status().isBadRequest())
+                    .andExpect(content().contentType("application/problem+json"))
+                    .andExpect(jsonPath("$.code").value("BAD_REQUEST"));
+        }
+        mvc.perform(get("/api/v1/public/search/articles").param("q", "valid").param("size", "21"))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value("BAD_REQUEST"));
+    }
+
+    @Test
+    void returnsSummaryOnlyAndSupportsSharedConditionalCaching() throws Exception {
+        var article = new ArticleService.PublicSearchArticle(
+                java.util.UUID.randomUUID(), "visible", "Visible result", "Excerpt", Instant.parse("2026-01-01T00:00:00Z"), null, true);
+        when(articleService.search("signal", 0, 20)).thenReturn(new ArticleService.SearchPage(
+                "signal", new PageImpl<>(List.of(article), PageRequest.of(0, 20), 1)));
+        when(articleService.publicCoverUrls(any())).thenReturn(java.util.Map.of());
+        when(siteService.get()).thenReturn(new SiteService.SiteResult("HaoBlog", "Night station", "https://blog.example.test", "Hao"));
+
+        var first = mvc.perform(get("/api/v1/public/search/articles").param("q", "signal"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.items[0].title").value("Visible result"))
+                .andExpect(jsonPath("$.items[0].excerpt").value("Excerpt"))
+                .andExpect(jsonPath("$.items[0].markdown").doesNotExist())
+                .andExpect(header().string("Cache-Control", "public, max-age=0, s-maxage=60, must-revalidate"))
+                .andExpect(header().exists("ETag"))
+                .andReturn();
+
+        mvc.perform(get("/api/v1/public/search/articles").param("q", "signal")
+                        .header("If-None-Match", first.getResponse().getHeader("ETag")))
+                .andExpect(status().isNotModified())
+                .andExpect(content().string(""));
+    }
+}
diff --git a/apps/api/src/test/java/io/haoblog/content/application/ArticleServiceTest.java b/apps/api/src/test/java/io/haoblog/content/application/ArticleServiceTest.java
index b2b20fa..2e16b4a 100644
--- a/apps/api/src/test/java/io/haoblog/content/application/ArticleServiceTest.java
+++ b/apps/api/src/test/java/io/haoblog/content/application/ArticleServiceTest.java
@@ -13,6 +13,7 @@
 import java.time.ZoneOffset;
 import java.util.List;
 import java.util.Optional;
+import org.mockito.ArgumentCaptor;
 
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertThrows;
@@ -80,4 +81,25 @@ void publicDetailUsesPublishedAndDueFilter() {
         assertEquals(publishedAt, result.publishedAt());
         verify(repository).findVisibleBySlug(eq("visible"), eq(ArticleStatus.PUBLISHED), eq(ArticleStatus.SCHEDULED), any(Instant.class));
     }
+
+    @Test
+    void normalizesUnicodeAndEscapesLikeWildcardsBeforeSearching() {
+        when(repository.searchVisible(any(), any(Instant.class), any())).thenReturn(new PageImpl<>(List.of()));
+
+        service.search("  Ａ%_\\  ", 0, 20);
+
+        var pattern = ArgumentCaptor.forClass(String.class);
+        verify(repository).searchVisible(pattern.capture(), eq(Instant.parse("2026-01-01T00:00:00Z")), any());
+        assertEquals("%A\\%\\_\\\\%", pattern.getValue());
+    }
+
+    @Test
+    void rejectsEmptyShortLongAndOversizedSearchRequestsBeforeRepository() {
+        for (String query : new String[]{null, "", "a", "a".repeat(101)}) {
+            assertThrows(IllegalArgumentException.class, () -> service.search(query, 0, 20));
+        }
+        assertThrows(IllegalArgumentException.class, () -> service.search("ok", -1, 20));
+        assertThrows(IllegalArgumentException.class, () -> service.search("ok", 0, 21));
+        verifyNoInteractions(repository, mediaRepository);
+    }
 }
diff --git a/apps/web/app/assets/styles/articles.css b/apps/web/app/assets/styles/articles.css
index 0e69f11..33eaf50 100644
--- a/apps/web/app/assets/styles/articles.css
+++ b/apps/web/app/assets/styles/articles.css
@@ -29,6 +29,19 @@
 .article-index { max-width: 68rem; }
 .article-index .signal-copy { margin-bottom: .75rem; }
 .index-note { margin: 0; }
+.article-search-entry { display: inline-block; margin-top: 1.2rem; color: var(--color-accent); font: var(--text-xs)/1.5 var(--font-mono); letter-spacing: .08em; text-decoration: none; }
+.article-search-entry:hover, .article-search-entry:focus-visible { text-decoration: underline; }
+.search-scene { max-width: 68rem; }
+.search-scene h1 { max-width: none; }
+.search-signal-form { max-width: 56rem; margin: 3rem 0 1rem; padding: .9rem 0; border-top: 1px solid var(--color-border); border-bottom: 1px solid var(--color-border); }
+.search-signal-form label, .search-readout { color: var(--color-text-muted); font: var(--text-xs)/1.5 var(--font-mono); letter-spacing: .08em; }
+.search-signal-form label { display: block; margin-bottom: .45rem; }
+.search-signal-controls { display: flex; gap: .5rem; }
+.search-signal-controls input { min-width: 0; flex: 1; padding: .65rem .7rem; border: 1px solid var(--color-border); border-radius: 0; background: var(--color-bg-sub); color: var(--color-text-main); font: var(--text-base)/1.4 var(--font-body); }
+.search-signal-controls input:focus { border-color: var(--color-accent); outline: 2px solid var(--color-accent); outline-offset: 1px; }
+.search-signal-controls button { padding: .65rem .8rem; border: 1px solid var(--color-accent); border-radius: 0; background: var(--color-accent); color: var(--color-accent-ink); font: var(--text-xs)/1.4 var(--font-mono); cursor: pointer; }
+.search-signal-controls button:hover, .search-signal-controls button:focus-visible { filter: brightness(1.1); }
+.search-readout { margin: 1.5rem 0 0; overflow-wrap: anywhere; }
 .observation-timeline { list-style: none; margin: 3rem 0 0; padding: 0 0 3rem 2rem; border-left: 1px solid var(--color-border); }
 .observation-entry { position: relative; display: grid; grid-template-columns: 7rem minmax(0, 1fr); gap: 2rem; padding: 0 0 3.5rem 1.5rem; }
 .observation-entry::before { content: ''; position: absolute; left: -0.35rem; top: 0.4rem; width: .6rem; height: .6rem; background: var(--color-bg-base); border: 1px solid var(--color-accent); }
@@ -134,6 +147,7 @@ html[data-theme='blueprint'] .safe-markdown .shiki span { color: var(--shiki-lig
 @media (max-width: 1023px) { .article-instrument { display: block; max-width: 45rem; margin-top: 6vh; }.article-signal { position: sticky; top: 0; z-index: 2; display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-items: center; gap: .75rem; height: auto; margin: 0 0 2rem; padding: .5rem 0; background: var(--color-bg-base); }.article-signal-track { width: 100%; height: 2px; }.article-signal-fill { width: var(--signal-progress); height: 100%; }.article-toc { position: static; margin-top: 3rem; padding: 1rem 0 0; border-left: 0; border-top: 1px solid var(--color-border); }.article-toc ol { padding-bottom: .25rem; } }
 @media (max-width: 767px) { .observation-entry { grid-template-columns: 1fr; gap: .4rem; padding-left: 1rem; }.article-pagination { padding-left: 1rem; }.recent-list li { grid-template-columns: 2rem 1fr; gap: .35rem .75rem; }.recent-list time { grid-column: 2; }.recent-list a { grid-column: 2; }.recent-list .recent-index { grid-row: 1 / span 2; }.home-calibration, .recent-heading { align-items: start; flex-direction: column; gap: .75rem; }.home-coordinate { text-align: left; }.observation-entry-heading { grid-template-columns: 2rem minmax(0, 1fr); }.article-cover-frame { grid-column: 2; width: min(12rem, 100%); }.observation-entry-content p { margin-top: .9rem; } }
 @media (max-width: 360px) { .home-overview h1 { font-size: clamp(3rem, 18vw, 4.5rem); } .home-overview::before { display: none; } .safe-markdown { font-size: 1rem; line-height: 1.8; } .observation-entry-heading { grid-template-columns: 1.5rem minmax(0, 1fr); gap: .5rem; } .observation-index { font-size: .68rem; } }
+@media (max-width: 480px) { .search-signal-controls { align-items: stretch; flex-direction: column; } .search-signal-controls button { align-self: start; } }
 @media (prefers-reduced-motion: reduce), (prefers-reduced-data: reduce) { .home-overview::before { opacity: .7; } .continue-reading span, .route-menu a { transition: none; } }
 .safe-markdown .katex { font-size: 1em; }
 .safe-markdown .katex-block { display: block; max-width: 100%; margin: 1.75rem 0; overflow-x: auto; padding: .25rem 0; text-align: center; }
diff --git a/apps/web/app/components/articles/PublicArticleList.vue b/apps/web/app/components/articles/PublicArticleList.vue
index c561bd2..327dfcc 100644
--- a/apps/web/app/components/articles/PublicArticleList.vue
+++ b/apps/web/app/components/articles/PublicArticleList.vue
@@ -2,6 +2,7 @@
 import type { components } from '@haoblog/api-client'
 import { computed } from 'vue'
 import { publicArticlePageUrl } from '../../utils/publicArticlePagination'
+import { publicSearchPageUrl } from '../../utils/publicSearch'
 import { useDataSaver } from '../../composables/useDataSaver'
 
 type ArticleList = components['schemas']['ArticleListResponse']
@@ -9,11 +10,16 @@ type ArticleList = components['schemas']['ArticleListResponse']
 const props = defineProps<{
   result: ArticleList
   page: number
+  searchQuery?: string
+  emptyMessage?: string
 }>()
 const { enabled: dataSaver } = useDataSaver()
 
 const hasPrevious = computed(() => props.page > 1)
 const hasNext = computed(() => props.page * props.result.size < props.result.total)
+const pageUrl = (page: number) => props.searchQuery === undefined
+  ? publicArticlePageUrl(page)
+  : publicSearchPageUrl(props.searchQuery, page)
 
 function formatDate(value: string) {
   return new Intl.DateTimeFormat('zh-CN', {
@@ -36,7 +42,7 @@ function httpsCoverUrl(value: string | null) {
 </script>
 
 <template>
-  <p v-if="result.items.length === 0" class="signal-note">当前没有已锁定的公开文章。</p>
+  <p v-if="result.items.length === 0" class="signal-note">{{ emptyMessage || '当前没有已锁定的公开文章。' }}</p>
   <template v-else>
     <ol class="observation-timeline" aria-label="公开文章列表">
       <li v-for="(article, index) in result.items" :key="article.id" class="observation-entry">
@@ -63,9 +69,9 @@ function httpsCoverUrl(value: string | null) {
     </ol>
 
     <nav v-if="hasPrevious || hasNext" class="article-pagination" aria-label="文章列表分页">
-      <a v-if="hasPrevious" :href="publicArticlePageUrl(page - 1)">上一页</a>
+      <a v-if="hasPrevious" :href="pageUrl(page - 1)">上一页</a>
       <span aria-current="page">第 {{ page }} 页</span>
-      <a v-if="hasNext" :href="publicArticlePageUrl(page + 1)">下一页</a>
+      <a v-if="hasNext" :href="pageUrl(page + 1)">下一页</a>
     </nav>
   </template>
 </template>
diff --git a/apps/web/app/pages/articles/index.vue b/apps/web/app/pages/articles/index.vue
index 70648ac..b674345 100644
--- a/apps/web/app/pages/articles/index.vue
+++ b/apps/web/app/pages/articles/index.vue
@@ -37,6 +37,7 @@ useHead(() => publicPageHead(buildPublicPageSeo(resolvedSite, page === 1 ? '/art
     <h1 id="articles-title">文章观测日志</h1>
     <p class="signal-copy">沿着时间线阅读正在演化的技术记录。</p>
     <p class="index-note"><span class="status-light" aria-hidden="true" /> 按发布时间排列 / PUBLIC SIGNALS ONLY</p>
+    <NuxtLink class="article-search-entry" to="/search">TEXT SEARCH / 检索文章信号 →</NuxtLink>
     <p v-if="pending" class="signal-note" role="status">正在接收文章信号…</p>
     <p v-else-if="error" class="signal-note" role="alert">文章信号暂时不可用，请稍后重试。</p>
     <PublicArticleList v-else-if="data" :result="data" :page="page" />
diff --git a/apps/web/app/pages/search.vue b/apps/web/app/pages/search.vue
new file mode 100644
index 0000000..746b1f9
--- /dev/null
+++ b/apps/web/app/pages/search.vue
@@ -0,0 +1,71 @@
+<script setup lang="ts">
+import type { components } from '@haoblog/api-client'
+import PublicArticleList from '~/components/articles/PublicArticleList.vue'
+import { buildPublicPageSeo, publicPageHead } from '~/utils/publicArticleSeo'
+import { isPublicSearchPageOutOfRange, normalizePublicSearchQuery, publicSearchPageUrl } from '~/utils/publicSearch'
+import { parsePublicArticlePage } from '~/utils/publicArticlePagination'
+import { defaultPublicSite, usePublicSite } from '~/utils/publicSite'
+
+type ArticleList = components['schemas']['ArticleListResponse']
+const emptyResult: ArticleList = { items: [], page: 0, size: 20, total: 0 }
+const route = useRoute()
+const rawQuery = typeof route.query.q === 'string' ? route.query.q : ''
+const query = normalizePublicSearchQuery(rawQuery)
+const hasQuery = rawQuery.length > 0
+const invalidQuery = hasQuery && !query
+const parsedPage = parsePublicArticlePage(route.query.page)
+
+if (!parsedPage) {
+  throw createError({ statusCode: 404, statusMessage: 'Search page not found', fatal: true })
+}
+
+const page = parsedPage.page
+const [{ data: site }, search] = await Promise.all([
+  usePublicSite(),
+  query && !invalidQuery
+    ? usePublicApi<ArticleList>('/api/v1/public/search/articles', { query: { q: query, page: page - 1, size: 20 } })
+    : Promise.resolve({ data: ref(emptyResult), pending: ref(false), error: ref(null) }),
+])
+
+if (query && !invalidQuery && !search.pending.value && !search.error.value && search.data.value && isPublicSearchPageOutOfRange(page, search.data.value)) {
+  throw createError({ statusCode: 404, statusMessage: 'Search page not found', fatal: true })
+}
+
+const resolvedSite = site.value || defaultPublicSite
+const searchPath = query ? publicSearchPageUrl(query, page) : '/search'
+useHead(() => publicPageHead(
+  buildPublicPageSeo(resolvedSite, searchPath, query ? `搜索「${query}」 · ${resolvedSite.title}` : `文章搜索 · ${resolvedSite.title}`, '在已发布的文章快照中检索标题、摘要和正文。'),
+  'noindex,follow',
+))
+</script>
+
+<template>
+  <section class="search-scene observation-scene" aria-labelledby="search-title">
+    <p class="instrument-label">SEARCH ARRAY / PUBLIC SNAPSHOTS</p>
+    <h1 id="search-title">文章搜索</h1>
+    <p class="signal-copy">只检索已经锁定的公开版本，标题、摘要和正文按命中层级排列。</p>
+
+    <form class="search-signal-form" action="/search" method="get">
+      <label for="search-query">检索词</label>
+      <div class="search-signal-controls">
+        <input id="search-query" name="q" type="search" :value="rawQuery" minlength="2" maxlength="100" required autocomplete="off" placeholder="中文 / PostgreSQL / pg_trgm">
+        <button type="submit">SEARCH →</button>
+      </div>
+    </form>
+
+    <p v-if="invalidQuery" class="signal-note" role="alert">请输入 2–100 个 Unicode 字符。</p>
+    <p v-else-if="!query" class="signal-note">输入至少 2 个字符，开始观测。</p>
+    <template v-else>
+      <p class="search-readout"><span class="status-light" aria-hidden="true" /> QUERY / {{ query }} / {{ search.data?.value?.total || 0 }} HITS</p>
+      <p v-if="search.pending?.value" class="signal-note" role="status">正在接收搜索信号…</p>
+      <p v-else-if="search.error?.value" class="signal-note" role="alert">搜索信号暂时不可用，请稍后重试。</p>
+      <PublicArticleList
+        v-else-if="search.data?.value"
+        :result="search.data.value"
+        :page="page"
+        :search-query="query"
+        empty-message="没有匹配的公开文章。"
+      />
+    </template>
+  </section>
+</template>
diff --git a/apps/web/app/utils/publicSearch.ts b/apps/web/app/utils/publicSearch.ts
new file mode 100644
index 0000000..f83f1bf
--- /dev/null
+++ b/apps/web/app/utils/publicSearch.ts
@@ -0,0 +1,20 @@
+import type { components } from '@haoblog/api-client'
+
+type ArticleList = components['schemas']['ArticleListResponse']
+
+export function normalizePublicSearchQuery(value: string | null | undefined) {
+  if (typeof value !== 'string') return null
+  const normalized = value.normalize('NFKC').trim()
+  const length = Array.from(normalized).length
+  return length >= 2 && length <= 100 ? normalized : null
+}
+
+export function publicSearchPageUrl(query: string, page: number) {
+  const params = new URLSearchParams({ q: query })
+  if (page > 1) params.set('page', String(page))
+  return `/search?${params.toString()}`
+}
+
+export function isPublicSearchPageOutOfRange(page: number, result: ArticleList) {
+  return page > 1 && result.items.length === 0
+}
diff --git a/apps/web/e2e/stage4.spec.ts b/apps/web/e2e/stage4.spec.ts
index b61755f..6bdf85f 100644
--- a/apps/web/e2e/stage4.spec.ts
+++ b/apps/web/e2e/stage4.spec.ts
@@ -188,3 +188,49 @@ test.describe('S4-08 embedded browser tools', () => {
     await expect(page.locator(':focus')).toBeVisible()
   })
 })
+
+test.describe('S4-09 minimal article search', () => {
+  test('renders normalized public search in SSR, supports no-JS, pagination links and 360px keyboard use', async ({ page, browser }) => {
+    const articles = await page.request.get('/api/v1/public/articles?size=1')
+    expect(articles.ok()).toBe(true)
+    const first = (await articles.json() as { items: Array<{ slug: string; title: string }> }).items[0]
+    expect(first?.slug).toBeTruthy()
+    const query = Array.from(first.title).slice(0, 3).join('')
+    expect(Array.from(query).length).toBeGreaterThanOrEqual(2)
+
+    const api = await page.request.get('/api/v1/public/search/articles', { params: { q: query } })
+    expect(api.ok()).toBe(true)
+    const payload = await api.json() as { items: Array<{ slug: string; title: string }>; total: number }
+    expect(payload.total).toBeGreaterThan(0)
+    expect(payload.items.some(item => item.slug === first.slug)).toBe(true)
+
+    const ssr = await page.request.get(`/search?q=${encodeURIComponent(query)}`)
+    expect(ssr.status()).toBe(200)
+    const html = await ssr.text()
+    expect(html).toContain(first.title)
+    expect(html).toContain('name="robots"')
+    expect(html).toContain('noindex,follow')
+    expect(html).toContain('name="q"')
+    expect(html).not.toContain('/sitemap.xml/search')
+
+    const noJs = await browser.newContext({ baseURL: process.env.HAOBLOG_BASE_URL || 'http://127.0.0.1', javaScriptEnabled: false })
+    const noJsPage = await noJs.newPage()
+    await noJsPage.setViewportSize({ width: 360, height: 900 })
+    const noJsResponse = await noJsPage.goto(`/search?q=${encodeURIComponent(query)}`)
+    expect(noJsResponse?.status()).toBe(200)
+    await expect(noJsPage.getByRole('heading', { name: '文章搜索' })).toBeVisible()
+    await expect(noJsPage.locator('input[name="q"]')).toHaveValue(query)
+    await expect(noJsPage.locator('a[href^="/articles/"]').first()).toBeVisible()
+    expect(await noJsPage.evaluate(() => document.documentElement.scrollWidth)).toBeLessThanOrEqual(360)
+    await noJs.close()
+
+    await page.setViewportSize({ width: 360, height: 900 })
+    await page.goto(`/search?q=${encodeURIComponent(query)}`)
+    await page.getByLabel('检索词').focus()
+    await page.keyboard.press('Tab')
+    await expect(page.getByRole('button', { name: 'SEARCH →' })).toBeFocused()
+
+    const sitemap = await page.request.get('/sitemap.xml')
+    expect(await sitemap.text()).not.toContain('/search')
+  })
+})
diff --git a/apps/web/test/public-article-ssr.test.ts b/apps/web/test/public-article-ssr.test.ts
index d895bc2..a6504c8 100644
--- a/apps/web/test/public-article-ssr.test.ts
+++ b/apps/web/test/public-article-ssr.test.ts
@@ -8,6 +8,7 @@ import PublicHomeOverview from '../app/components/home/PublicHomeOverview.vue'
 import { isPublicArticlePageOutOfRange, parsePublicArticlePage, publicArticlePageUrl } from '../app/utils/publicArticlePagination'
 import { buildPublicArticleJsonLd, buildPublicArticleSeo, buildPublicPageSeo, publicPageHead, serializeJsonLd } from '../app/utils/publicArticleSeo'
 import { buildPublicArticleContent } from '../server/utils/publicArticleContent'
+import { isPublicSearchPageOutOfRange, normalizePublicSearchQuery, publicSearchPageUrl } from '../app/utils/publicSearch'
 import type { components } from '@haoblog/api-client'
 
 type Article = components['schemas']['ArticleResponse']
@@ -106,6 +107,24 @@ describe('public article SSR contract', () => {
     expect(isPublicArticlePageOutOfRange(2, { items: [singleSummary()], page: 1, size: 20, total: 21 })).toBe(false)
   })
 
+  it('normalizes Unicode search terms and renders search pagination as plain links', async () => {
+    expect(normalizePublicSearchQuery('  ＰＧ＿ＴＲＧＭ  ')).toBe('PG_TRGM')
+    expect(normalizePublicSearchQuery('a')).toBeNull()
+    expect(normalizePublicSearchQuery('😀'.repeat(101))).toBeNull()
+    expect(publicSearchPageUrl('PG_TRGM', 2)).toBe('/search?q=PG_TRGM&page=2')
+    expect(isPublicSearchPageOutOfRange(2, { items: [], page: 1, size: 20, total: 20 })).toBe(true)
+
+    const result: ArticleList = {
+      items: [{ id: 'article-1', slug: 'search-signal', title: 'Search signal', excerpt: 'Excerpt only', publishedAt: article.publishedAt, coverImageUrl: null }],
+      page: 0,
+      size: 20,
+      total: 1,
+    }
+    const html = await renderPublic(PublicArticleList, { result, page: 1, searchQuery: 'signal' })
+    expect(html).toContain('href="/articles/search-signal"')
+    expect(html).not.toContain('markdown')
+  })
+
   it('renders title, excerpt and safe markdown into SSR HTML', async () => {
     const content = buildPublicArticleContent(article)
     const html = await renderToString(createSSRApp(PublicArticleBody, { content }))
diff --git a/docs/openapi/public-api.yaml b/docs/openapi/public-api.yaml
index c55609c..7227532 100644
--- a/docs/openapi/public-api.yaml
+++ b/docs/openapi/public-api.yaml
@@ -172,6 +172,41 @@ paths:
           $ref: '#/components/responses/ArticleNotFound'
         '500':
           $ref: '#/components/responses/InternalError'
+  /api/v1/public/search/articles:
+    get:
+      operationId: searchPublicArticles
+      security: []
+      parameters:
+        - name: q
+          in: query
+          required: true
+          description: NFKC-normalized search query; 2 to 100 Unicode code points
+          schema: { type: string, minLength: 2, maxLength: 100 }
+        - name: page
+          in: query
+          schema: { type: integer, minimum: 0, default: 0 }
+        - name: size
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 20, default: 20 }
+        - $ref: '#/components/parameters/IfNoneMatch'
+      responses:
+        '200':
+          description: Public article summaries matching the query
+          headers:
+            ETag: { $ref: '#/components/headers/ETag' }
+            Cache-Control: { schema: { type: string } }
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ArticleListResponse' }
+        '304':
+          description: Search representation has not changed
+          headers:
+            ETag: { $ref: '#/components/headers/ETag' }
+            Cache-Control: { schema: { type: string } }
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
   /api/v1/public/articles/{slug}/comments:
     get:
       operationId: listPublicArticleComments
diff --git a/packages/api-client/src/generated.ts b/packages/api-client/src/generated.ts
index 8812712..dc7f5fd 100644
--- a/packages/api-client/src/generated.ts
+++ b/packages/api-client/src/generated.ts
@@ -100,6 +100,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/public/search/articles": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["searchPublicArticles"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/public/articles/{slug}/comments": {
         parameters: {
             query?: never;
@@ -1564,6 +1580,46 @@ export interface operations {
             500: components["responses"]["InternalError"];
         };
     };
+    searchPublicArticles: {
+        parameters: {
+            query: {
+                /** @description NFKC-normalized search query; 2 to 100 Unicode code points */
+                q: string;
+                page?: number;
+                size?: number;
+            };
+            header?: {
+                "If-None-Match"?: components["parameters"]["IfNoneMatch"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Public article summaries matching the query */
+            200: {
+                headers: {
+                    ETag: components["headers"]["ETag"];
+                    "Cache-Control"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ArticleListResponse"];
+                };
+            };
+            /** @description Search representation has not changed */
+            304: {
+                headers: {
+                    ETag: components["headers"]["ETag"];
+                    "Cache-Control"?: string;
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            400: components["responses"]["BadRequest"];
+            500: components["responses"]["InternalError"];
+        };
+    };
     listPublicArticleComments: {
         parameters: {
             query?: {

From f0bfdac58e0f9821dd313e879892302eb971bc08 Mon Sep 17 00:00:00 2001
From: DDT <––1786035110@stu.gpnu.edu.cn>
Date: Sun, 23 Aug 2026 18:43:28 +0800
Subject: [PATCH 15/15] =?UTF-8?q?=E5=AE=8C=E6=88=90=E9=98=B6=E6=AE=B5?=
 =?UTF-8?q?=E5=9B=9B=E7=BB=BC=E5=90=88=E9=AA=8C=E6=94=B6=E5=B9=B6=E6=94=B6?=
 =?UTF-8?q?=E6=95=9B=E9=A1=B9=E7=9B=AE=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/ci.yml                      |   9 +-
 AGENTS.md                                     |   6 +
 README.md                                     |  64 +----
 .../comment/application/CommentService.java   |   8 +-
 .../persistence/CommentRepository.java        |  31 ++-
 apps/web/e2e/stage4.spec.ts                   | 258 +++++++++++++++++-
 ...57\345\212\250\346\214\207\345\215\227.md" |  22 +-
 ...56\346\240\207\344\273\273\345\212\241.md" |  97 +++++++
 ...06\345\205\245\346\270\205\345\215\225.md" |  82 ++++++
 9 files changed, 497 insertions(+), 80 deletions(-)
 create mode 100644 "docs/\347\254\254\345\233\233\351\230\266\346\256\265\347\233\256\346\240\207\344\273\273\345\212\241.md"
 create mode 100644 "docs/\351\230\266\346\256\265\345\233\233\345\207\206\345\205\245\346\270\205\345\215\225.md"

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ffce40e..b907484 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -6,7 +6,7 @@ on:
   pull_request:
 
 jobs:
-  stage-3-acceptance:
+  stage-4-acceptance:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -99,6 +99,13 @@ jobs:
         env:
           LHCI_EXISTING_SERVER: true
           LHCI_BASE_URL: http://localhost
+          LHCI_ARTICLE_PATH: /articles/s3-08-advanced-markdown
+        run: corepack pnpm web:lighthouse
+      - name: Lighthouse public tools budgets
+        env:
+          LHCI_EXISTING_SERVER: true
+          LHCI_BASE_URL: http://localhost
+          LHCI_ARTICLE_PATH: /tools
         run: corepack pnpm web:lighthouse
       - name: Reject whitespace errors
         run: git diff --check
diff --git a/AGENTS.md b/AGENTS.md
index 7e7dfd0..dc9e33a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -74,10 +74,16 @@ The current repository uses one root pnpm workspace and one Maven application. N
 - API tests (POSIX shell): `cd apps/api && ./mvnw test`
 - API package (Windows PowerShell): `cd apps/api; .\mvnw.cmd verify`
 - API package (POSIX shell): `cd apps/api && ./mvnw verify`
+- PostgreSQL/pgvector integration tests (Windows PowerShell): `cd apps/api; .\mvnw.cmd failsafe:integration-test failsafe:verify`
 - Web type check: `pnpm --dir apps/web typecheck`
 - Web tests: `pnpm --dir apps/web test`
 - Web production build: `pnpm --dir apps/web build`
+- Full Chromium E2E: `pnpm --dir apps/web e2e`
+- Article client bundle budget: `pnpm web:budget`
+- Lighthouse with an existing server: set `LHCI_EXISTING_SERVER=true`, `LHCI_BASE_URL=http://localhost` and `LHCI_ARTICLE_PATH` to `/articles/s3-08-advanced-markdown` or `/tools`, then run `pnpm web:lighthouse`; on Windows also use a task-local `TEMP`/`TMP` directory to avoid Chrome cleanup EPERM
 - Compose validation using placeholder environment values: `docker compose --env-file .env.example -f infra/compose/compose.dev.yml config`
+- Production Compose validation: `docker compose --env-file infra/compose/.env.ci.example -f infra/compose/compose.prod.yml config`
+- Compose resource and health-boundary verification: `pnpm compose:verify`
 - Local database startup: `docker compose --env-file .env -f infra/compose/compose.dev.yml up -d`
 
 The Maven Wrapper is `apps/api/mvnw` / `apps/api/mvnw.cmd`, with Maven distribution `3.9.11`. The pnpm version is pinned as `pnpm@11.16.0` in the root `package.json`; the workspace also permits the explicitly configured `esbuild` build script.
diff --git a/README.md b/README.md
index b45be83..2226014 100644
--- a/README.md
+++ b/README.md
@@ -1,65 +1,5 @@
 # HaoBlog
 
-HaoBlog is a Java 21 and Nuxt 4 modular-monolith developer blog. The public site is SSR-first; `/studio` is client-rendered. 阶段三已形成“极夜观测站”公开阅读体验，包含安全高级 Markdown、TOC、SEO/JSON-LD、RSS、Sitemap、无 JavaScript 与数据节省路径。
+HaoBlog 是一个面向开发者的低成本个人博客与数字花园，采用 Java 21、Spring Boot、Nuxt 4、Vue 3 和 PostgreSQL/pgvector 构建。项目使用模块化单体架构，公开站点以服务端渲染为核心，管理后台通过 `/studio` 提供内容运营能力。
 
-## Local prerequisites
-
-- Java 21
-- Maven Wrapper (included in `apps/api`)
-- Node.js 24 LTS
-- pnpm 11.16.0
-- Docker Desktop with Compose
-
-Copy `.env.example` to `.env` and replace the local database password before starting PostgreSQL.
-
-完整的环境准备、管理员 BCrypt 配置、Compose 启动、直接运行 API/Web、验证命令和故障排查请参阅：[本地启动指南](docs/本地启动指南.md)。
-
-## 最短命令
-
-Windows 11 PowerShell：
-
-```powershell
-Copy-Item .env.example .env
-docker compose --env-file .env -f infra/compose/compose.dev.yml up -d
-corepack pnpm install --frozen-lockfile
-corepack pnpm --filter @haoblog/api-client generate
-corepack pnpm --filter @haoblog/api-client check
-corepack pnpm compose:verify
-corepack pnpm --dir apps/web typecheck
-corepack pnpm --dir apps/web test
-corepack pnpm --dir apps/web build
-corepack pnpm web:budget
-corepack pnpm smoke
-docker compose --env-file .env -f infra/compose/compose.dev.yml logs --tail=100
-docker compose --env-file .env -f infra/compose/compose.dev.yml down -v
-cd apps/api; .\mvnw.cmd -DskipITs verify; .\mvnw.cmd failsafe:integration-test failsafe:verify; cd ../..
-```
-
-通用 Shell：
-
-```sh
-cp .env.example .env
-docker compose --env-file .env -f infra/compose/compose.dev.yml up -d
-corepack pnpm install --frozen-lockfile
-corepack pnpm --filter @haoblog/api-client generate
-corepack pnpm --filter @haoblog/api-client check
-corepack pnpm compose:verify
-corepack pnpm --dir apps/web typecheck && corepack pnpm --dir apps/web test && corepack pnpm --dir apps/web build
-corepack pnpm web:budget
-corepack pnpm smoke
-docker compose --env-file .env -f infra/compose/compose.dev.yml logs --tail=100
-docker compose --env-file .env -f infra/compose/compose.dev.yml down -v
-cd apps/api && ./mvnw -DskipITs verify && ./mvnw failsafe:integration-test failsafe:verify
-```
-
-开发 Compose 提供 PostgreSQL/pgvector、API 和 Web；API/Web 构建 context 均为仓库根目录。生产 Compose 只允许 Caddy 对外开放 80/443，数据库和 Actuator 不暴露宿主机端口。生产镜像、域名和密码必须通过外部 env 文件注入，不能使用仓库中的示例值。
-
-故障排查：
-
-- 端口占用：`Get-NetTCPConnection -LocalPort 3000,5432,8080`；Shell 使用 `ss -ltnp | grep -E ':3000|:5432|:8080'`。
-- 容器健康：`docker compose --env-file .env -f infra/compose/compose.dev.yml ps`。
-- 查看日志：`docker compose --env-file .env -f infra/compose/compose.dev.yml logs --tail=100 api web postgres`。
-- 数据库迁移失败：先查看 API 日志和 PostgreSQL 健康状态，再执行 `docker compose --env-file .env -f infra/compose/compose.dev.yml down -v` 清理本地开发 volume 后重试。
-- Web 无法连接 API：确认 API 健康后检查容器内地址 `http://api:8080`，不要在 Compose 内使用 `localhost`。
-
-阶段三验收顺序是 API `-DskipITs verify`、Web typecheck/test/build、OpenAPI 生成一致性、dev/prod Compose 配置、资源边界、PostgreSQL/pgvector Failsafe、生产四容器健康、Smoke、Chromium Playwright、文章客户端预算、Lighthouse 和 `git diff --check`。生产编排的可复制命令与实际完成状态见 [阶段三准入清单](docs/阶段三准入清单.md)。Playwright 使用仓库测试账号 `admin/password`，应配合 `infra/compose/.env.ci.example` 的临时栈运行，不能用于生产。评论、工具箱功能、AI、RAG、Three.js、终端和部署仍不在阶段三范围内。
+项目以“极夜观测站”为设计主题，关注长文阅读、内容可发现性和低性能主机上的稳定运行。它提供文章、中文搜索、评论、工具箱、RSS、Sitemap、目录和结构化数据等能力，并通过安全 Markdown、资源边界、无 JavaScript、Save-Data 与 reduced-motion 路径保持可访问和可持续的阅读体验。
diff --git a/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java b/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java
index 1720228..d7e8799 100644
--- a/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java
+++ b/apps/api/src/main/java/io/haoblog/comment/application/CommentService.java
@@ -80,8 +80,10 @@ public Page<AdminComment> listAdmin(CommentStatus status, UUID articleId, String
                                         int page, int size, Sort.Direction direction) {
         validatePage(page, size);
         String normalizedKeyword = normalizeKeyword(keyword);
-        var pageable = PageRequest.of(page, size, Sort.by(direction, "createdAt").and(Sort.by(direction, "id")));
-        return comments.findAdminComments(status, articleId, normalizedKeyword, pageable).map(this::adminListView);
+        var pageable = PageRequest.of(page, size);
+        return comments.findAdminComments(status == null ? null : status.name(),
+                articleId == null ? null : articleId.toString(), normalizedKeyword,
+                direction.name().toLowerCase(Locale.ROOT), pageable).map(this::adminListView);
     }
 
     @Transactional(readOnly = true)
@@ -142,7 +144,7 @@ private static String normalizeKeyword(String keyword) {
         if (keyword == null || keyword.isBlank()) return null;
         String normalized = keyword.strip();
         if (normalized.length() > 240) throw new IllegalArgumentException("keyword is too long");
-        return normalized;
+        return normalized.toLowerCase(Locale.ROOT);
     }
 
     private static String normalizeReason(String reason) {
diff --git a/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java b/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
index c6d36d0..c3b6b5d 100644
--- a/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
+++ b/apps/api/src/main/java/io/haoblog/comment/persistence/CommentRepository.java
@@ -13,16 +13,29 @@
 import java.util.UUID;
 
 public interface CommentRepository extends JpaRepository<Comment, UUID> {
-    @Query("""
-            select c from Comment c
-            where (:status is null or c.status = :status)
-              and (:articleId is null or c.articleId = :articleId)
-              and (:keyword is null or lower(c.nickname) like lower(concat('%', :keyword, '%'))
-                   or lower(c.content) like lower(concat('%', :keyword, '%')))
-            """)
-    Page<Comment> findAdminComments(@Param("status") CommentStatus status,
-                                    @Param("articleId") UUID articleId,
+    @Query(value = """
+            select c.* from comment c
+            where (cast(:status as varchar) is null or c.status = cast(:status as varchar))
+              and (cast(:articleId as uuid) is null or c.article_id = cast(:articleId as uuid))
+              and (cast(:keyword as text) is null or lower(c.nickname) like concat('%', cast(:keyword as text), '%')
+                   or lower(c.content) like concat('%', cast(:keyword as text), '%'))
+            order by
+              case when cast(:direction as varchar) = 'asc' then c.created_at end asc,
+              case when cast(:direction as varchar) <> 'asc' then c.created_at end desc,
+              case when cast(:direction as varchar) = 'asc' then c.id end asc,
+              case when cast(:direction as varchar) <> 'asc' then c.id end desc
+            """,
+            countQuery = """
+            select count(*) from comment c
+            where (cast(:status as varchar) is null or c.status = cast(:status as varchar))
+              and (cast(:articleId as uuid) is null or c.article_id = cast(:articleId as uuid))
+              and (cast(:keyword as text) is null or lower(c.nickname) like concat('%', cast(:keyword as text), '%')
+                   or lower(c.content) like concat('%', cast(:keyword as text), '%'))
+            """, nativeQuery = true)
+    Page<Comment> findAdminComments(@Param("status") String status,
+                                    @Param("articleId") String articleId,
                                     @Param("keyword") String keyword,
+                                    @Param("direction") String direction,
                                     Pageable pageable);
 
     Page<Comment> findByArticleIdAndStatusAndParentIdIsNullOrderByCreatedAtAscIdAsc(
diff --git a/apps/web/e2e/stage4.spec.ts b/apps/web/e2e/stage4.spec.ts
index 6bdf85f..8426e94 100644
--- a/apps/web/e2e/stage4.spec.ts
+++ b/apps/web/e2e/stage4.spec.ts
@@ -1,4 +1,4 @@
-import { expect, test } from '@playwright/test'
+import { expect, test, type APIRequestContext, type Browser } from '@playwright/test'
 
 test.describe('S4-03 article comment signal', () => {
   test('keeps the comment signal SSR-readable and submits through the lazy form context', async ({ page, browser }) => {
@@ -234,3 +234,259 @@ test.describe('S4-09 minimal article search', () => {
     expect(await sitemap.text()).not.toContain('/search')
   })
 })
+
+type ArticleAdminResponse = { id: string; version: number; title: string; commentsEnabled: boolean }
+type CommentSubmission = { id: string; status: string; deleteToken: string | null }
+type CommentFormContext = { csrfToken: string; challenge: string; commentsEnabled: boolean }
+
+const baseURL = () => process.env.HAOBLOG_BASE_URL || 'http://127.0.0.1'
+
+async function loginAcceptanceAdmin(request: APIRequestContext) {
+  const anonymousCsrf = await request.get('/api/v1/admin/csrf')
+  expect(anonymousCsrf.ok()).toBe(true)
+  const anonymousToken = (await anonymousCsrf.json() as { token: string }).token
+  const login = await request.post('/api/v1/admin/session', {
+    headers: { 'X-CSRF-TOKEN': anonymousToken },
+    data: { username: 'admin', password: 'password' },
+  })
+  expect(login.ok()).toBe(true)
+  const csrf = await request.get('/api/v1/admin/csrf')
+  expect(csrf.ok()).toBe(true)
+  return (await csrf.json() as { token: string }).token
+}
+
+async function createPublishedAcceptanceArticle(request: APIRequestContext, token: string, input: {
+  slug: string
+  title: string
+  excerpt: string
+  markdown: string
+  commentsEnabled?: boolean
+}) {
+  const created = await request.post('/api/v1/admin/articles', {
+    headers: { 'X-CSRF-TOKEN': token },
+    data: { ...input, commentsEnabled: input.commentsEnabled ?? true },
+  })
+  expect(created.status()).toBe(201)
+  const article = await created.json() as ArticleAdminResponse
+  const published = await request.post(`/api/v1/admin/articles/${article.id}/publish`, {
+    headers: { 'X-CSRF-TOKEN': token },
+    data: { version: article.version },
+  })
+  expect(published.ok()).toBe(true)
+  return article
+}
+
+async function getCommentForm(request: APIRequestContext, slug: string) {
+  const response = await request.get(`/api/v1/public/articles/${encodeURIComponent(slug)}/comments/form-context`)
+  expect(response.ok()).toBe(true)
+  return await response.json() as CommentFormContext
+}
+
+async function submitAcceptanceComment(browser: Browser, slug: string, input: { nickname: string; content: string; email?: string; parentId?: string }) {
+  const context = await browser.newContext({ baseURL: baseURL() })
+  const request = context.request
+  const form = await getCommentForm(request, slug)
+  await new Promise(resolve => setTimeout(resolve, 3_200))
+  const response = await request.post(`/api/v1/public/articles/${encodeURIComponent(slug)}/comments`, {
+    headers: { 'X-CSRF-TOKEN': form.csrfToken },
+    data: { ...input, challenge: form.challenge },
+  })
+  return { context, form, response, payload: await response.json() as CommentSubmission }
+}
+
+async function moderateAcceptanceComment(request: APIRequestContext, token: string, id: string, status: 'APPROVED' | 'SPAM' | 'REJECTED') {
+  const detailResponse = await request.get(`/api/v1/admin/comments/${id}`)
+  expect(detailResponse.ok()).toBe(true)
+  const detail = await detailResponse.json() as { version: number }
+  const response = await request.post(`/api/v1/admin/comments/${id}/moderation`, {
+    headers: { 'X-CSRF-TOKEN': token },
+    data: { version: detail.version, status, reason: 'S4-10 运行态验收' },
+  })
+  expect(response.ok()).toBe(true)
+}
+
+test.describe.serial('S4-10 full live contracts', () => {
+  test('establishes comment states, flags, security signals and Studio moderation', async ({ page, browser }) => {
+    test.setTimeout(120_000)
+    const batch = Date.now()
+    const token = await loginAcceptanceAdmin(page.request)
+    const openSlug = `s4-10-open-${batch}`
+    const closedSlug = `s4-10-closed-${batch}`
+    await createPublishedAcceptanceArticle(page.request, token, {
+      slug: openSlug,
+      title: `S4-10 开放评论文章 ${batch}`,
+      excerpt: 'S4-10 摘要验收命中。',
+      markdown: '# S4-10 开放评论文章\n\nS4-10 正文验收命中。',
+    })
+    await createPublishedAcceptanceArticle(page.request, token, {
+      slug: closedSlug,
+      title: `S4-10 关闭评论文章 ${batch}`,
+      excerpt: '关闭评论文章摘要。',
+      markdown: '# S4-10 关闭评论文章\n\n评论入口关闭。',
+      commentsEnabled: false,
+    })
+
+    const pending = await submitAcceptanceComment(browser, openSlug, { nickname: `S4-10 待审 ${batch}`, content: '待审核评论信号。', email: `s410-${batch}@example.test` })
+    expect(pending.response.status()).toBe(202)
+    expect(pending.payload.status).toBe('PENDING')
+
+    const replayContext = await browser.newContext({ baseURL: baseURL() })
+    const replayForm = await getCommentForm(replayContext.request, openSlug)
+    await new Promise(resolve => setTimeout(resolve, 3_200))
+    const firstReplay = await replayContext.request.post(`/api/v1/public/articles/${openSlug}/comments`, {
+      headers: { 'X-CSRF-TOKEN': replayForm.csrfToken },
+      data: { nickname: `S4-10 重放 ${batch}`, content: '第一次挑战提交。', challenge: replayForm.challenge },
+    })
+    expect(firstReplay.status()).toBe(202)
+    const replay = await replayContext.request.post(`/api/v1/public/articles/${openSlug}/comments`, {
+      headers: { 'X-CSRF-TOKEN': replayForm.csrfToken },
+      data: { nickname: `S4-10 重放 ${batch}`, content: '重复使用挑战。', challenge: replayForm.challenge },
+    })
+    expect(replay.status()).toBe(400)
+    await replayContext.close()
+
+    const maliciousContext = await browser.newContext({ baseURL: baseURL() })
+    const maliciousForm = await getCommentForm(maliciousContext.request, openSlug)
+    const malicious = await maliciousContext.request.post(`/api/v1/public/articles/${openSlug}/comments`, {
+      headers: { 'X-CSRF-TOKEN': maliciousForm.csrfToken },
+      data: { nickname: 'S4-10 安全', content: '<script>alert(1)</script>', challenge: maliciousForm.challenge },
+    })
+    expect(malicious.status()).toBe(400)
+    await maliciousContext.close()
+
+    const approved = await submitAcceptanceComment(browser, openSlug, { nickname: `S4-10 通过 ${batch}`, content: '将被审核通过。' })
+    expect(approved.response.status()).toBe(202)
+    await page.goto('/studio/comments')
+    await expect(page.getByRole('heading', { name: '评论审核' })).toBeVisible()
+    await expect(page.getByRole('button', { name: new RegExp(`S4-10 待审 ${batch}`) })).toBeVisible()
+    await page.getByRole('button', { name: new RegExp(`S4-10 待审 ${batch}`) }).click()
+    await page.locator('#moderation-status').selectOption('APPROVED')
+    await page.getByRole('button', { name: '写入审核结果' }).click()
+    await expect(page.locator('[data-status="APPROVED"]').first()).toBeVisible()
+    await moderateAcceptanceComment(page.request, token, approved.payload.id, 'APPROVED')
+
+    const spam = await submitAcceptanceComment(browser, openSlug, { nickname: `S4-10 垃圾 ${batch}`, content: '垃圾评论状态。' })
+    const rejected = await submitAcceptanceComment(browser, openSlug, { nickname: `S4-10 拒绝 ${batch}`, content: '拒绝评论状态。' })
+    const reply = await submitAcceptanceComment(browser, openSlug, { nickname: `S4-10 回复 ${batch}`, content: '一级回复评论状态。', parentId: pending.payload.id })
+    const deleted = await submitAcceptanceComment(browser, openSlug, { nickname: `S4-10 删除 ${batch}`, content: '用户将删除此评论。' })
+    for (const result of [spam, rejected, reply, deleted]) expect(result.response.status()).toBe(202)
+    await moderateAcceptanceComment(page.request, token, spam.payload.id, 'SPAM')
+    await moderateAcceptanceComment(page.request, token, rejected.payload.id, 'REJECTED')
+    await moderateAcceptanceComment(page.request, token, reply.payload.id, 'APPROVED')
+    const deletedResponse = await deleted.context.request.delete(`/api/v1/public/comments/${deleted.payload.id}`, {
+      headers: { 'X-CSRF-TOKEN': deleted.form.csrfToken, 'X-Comment-Delete-Token': deleted.payload.deleteToken || '' },
+    })
+    expect(deletedResponse.status()).toBe(204)
+    await deleted.context.close()
+    await pending.context.close(); await approved.context.close(); await spam.context.close(); await rejected.context.close(); await reply.context.close()
+
+    const publicComments = await page.request.get(`/api/v1/public/articles/${openSlug}/comments`)
+    expect(publicComments.ok()).toBe(true)
+    const publicPayload = await publicComments.json() as { items: Array<{ nickname: string; replies: Array<{ nickname: string }> }> }
+    expect(publicPayload.items.some(item => item.nickname.includes(`S4-10 待审 ${batch}`))).toBe(true)
+    expect(publicPayload.items.some(item => item.replies.some(replyItem => replyItem.nickname.includes(`S4-10 回复 ${batch}`)))).toBe(true)
+    expect(JSON.stringify(publicPayload)).not.toContain(`S4-10 删除 ${batch}`)
+
+    const closedForm = await getCommentForm(page.request, closedSlug)
+    expect(closedForm.commentsEnabled).toBe(false)
+    const site = await page.request.get('/api/v1/admin/site')
+    const siteSettings = await site.json() as { version: number }
+    const disabled = await page.request.put('/api/v1/admin/site', { headers: { 'X-CSRF-TOKEN': token }, data: { version: siteSettings.version, commentsEnabled: false } })
+    expect(disabled.ok()).toBe(true)
+    expect((await getCommentForm(page.request, openSlug)).commentsEnabled).toBe(false)
+    const restored = await page.request.put('/api/v1/admin/site', { headers: { 'X-CSRF-TOKEN': token }, data: { version: (await disabled.json() as { version: number }).version, commentsEnabled: true } })
+    expect(restored.ok()).toBe(true)
+
+    const rateContext = await browser.newContext({ baseURL: baseURL() })
+    const rateStatuses: number[] = []
+    for (let index = 0; index < 4; index += 1) {
+      const form = await getCommentForm(rateContext.request, openSlug)
+      await new Promise(resolve => setTimeout(resolve, 3_200))
+      const response = await rateContext.request.post(`/api/v1/public/articles/${openSlug}/comments`, {
+        headers: { 'X-CSRF-TOKEN': form.csrfToken },
+        data: { nickname: `S4-10 限频 ${batch}`, content: `限频测试 ${index}。`, challenge: form.challenge },
+      })
+      rateStatuses.push(response.status())
+    }
+    expect(rateStatuses.slice(0, 3)).toEqual([202, 202, 202])
+    expect(rateStatuses[3]).toBe(429)
+    await rateContext.close()
+  })
+
+  test('covers Studio tool CRUD and title/summary/body/public search boundaries', async ({ page }) => {
+    test.setTimeout(120_000)
+    const batch = Date.now()
+    const token = await loginAcceptanceAdmin(page.request)
+    await page.goto('/studio/tools')
+    await expect(page.getByRole('heading', { name: '工具控制台' })).toBeVisible()
+
+    const category = await page.request.post('/api/v1/admin/tool-categories', {
+      headers: { 'X-CSRF-TOKEN': token },
+      data: { name: `S4-10 工具分类 ${batch}`, slug: `s4-10-tools-${batch}`, description: 'S4-10 工具 CRUD 验收' },
+    })
+    expect(category.status()).toBe(201)
+    const categoryId = (await category.json() as { id: string }).id
+    const created = await page.request.post('/api/v1/admin/tools', {
+      headers: { 'X-CSRF-TOKEN': token },
+      data: { categoryId, type: 'LINK', status: 'ACTIVE', title: `S4-10 工具 ${batch}`, slug: `s4-10-tool-${batch}`, description: '工具 CRUD 验收', url: 'https://example.com/s4-10', tags: ['s4-10'], sortOrder: 0 },
+    })
+    expect(created.status()).toBe(201)
+    const tool = await created.json() as { id: string; version: number }
+    const showcaseCreated = await page.request.post('/api/v1/admin/tools', {
+      headers: { 'X-CSRF-TOKEN': token },
+      data: { categoryId, type: 'SHOWCASE', status: 'ACTIVE', title: `S4-10 展示 ${batch}`, slug: `s4-10-showcase-${batch}`, description: 'S4-10 展示工具验收', url: 'https://example.com/s4-10-showcase', imageUrl: 'https://example.com/s4-10-showcase.png', tags: ['s4-10', 'showcase'], sortOrder: 1 },
+    })
+    expect(showcaseCreated.status()).toBe(201)
+    const showcaseTool = await showcaseCreated.json() as { id: string; version: number }
+    const read = await page.request.get(`/api/v1/admin/tools/${tool.id}`)
+    expect(read.ok()).toBe(true)
+    const readTool = await read.json() as { version: number; title: string }
+    expect(readTool.title).toContain('S4-10 工具')
+    const updated = await page.request.put(`/api/v1/admin/tools/${tool.id}`, {
+      headers: { 'X-CSRF-TOKEN': token },
+      data: { version: readTool.version, categoryId, type: 'LINK', status: 'ACTIVE', title: `S4-10 工具已更新 ${batch}`, slug: `s4-10-tool-${batch}`, description: '工具 CRUD 更新', url: 'https://example.com/s4-10', tags: ['updated'], sortOrder: 1 },
+    })
+    expect(updated.ok()).toBe(true)
+    const updatedTool = await updated.json() as { version: number }
+    const directory = await page.request.get('/api/v1/public/tools')
+    const publicTools = await directory.json() as { items: Array<{ type: string; componentKey: string | null }> }
+    expect(publicTools.items.some(item => item.type === 'LINK')).toBe(true)
+    expect(publicTools.items.some(item => item.type === 'SHOWCASE')).toBe(true)
+    expect(new Set(publicTools.items.filter(item => item.type === 'EMBEDDED').map(item => item.componentKey))).toEqual(new Set(['json-format', 'base64', 'url-codec', 'timestamp', 'regex-test']))
+    const removed = await page.request.delete(`/api/v1/admin/tools/${tool.id}?version=${updatedTool.version}`, { headers: { 'X-CSRF-TOKEN': token } })
+    expect(removed.status()).toBe(204)
+    const removedShowcase = await page.request.delete(`/api/v1/admin/tools/${showcaseTool.id}?version=${showcaseTool.version}`, { headers: { 'X-CSRF-TOKEN': token } })
+    expect(removedShowcase.status()).toBe(204)
+
+    const searchArticles = [
+      ['阶段四标题命中', '无关摘要', '无关正文'],
+      ['无关标题', '阶段四摘要命中', '无关正文'],
+      ['无关标题正文', '无关摘要', '阶段四正文命中'],
+    ] as const
+    for (const [index, values] of searchArticles.entries()) {
+      await createPublishedAcceptanceArticle(page.request, token, {
+        slug: `s4-10-search-${Date.now()}-${index}`,
+        title: `${values[0]} ${batch}`,
+        excerpt: `${values[1]} ${batch}`,
+        markdown: `# ${values[0]}\n\n${values[2]} ${batch}`,
+      })
+    }
+    const hidden = await page.request.post('/api/v1/admin/articles', {
+      headers: { 'X-CSRF-TOKEN': token },
+      data: { slug: `s4-10-hidden-${batch}`, title: `阶段四不可公开 ${batch}`, excerpt: '不可公开摘要', markdown: '# 不可公开正文' },
+    })
+    expect(hidden.status()).toBe(201)
+    for (const query of ['标题命中', '摘要命中', '正文命中']) {
+      const response = await page.request.get('/api/v1/public/search/articles', { params: { q: `${query} ${batch}` } })
+      expect(response.ok()).toBe(true)
+      expect((await response.json() as { total: number }).total).toBeGreaterThan(0)
+    }
+    const special = await page.request.get('/api/v1/public/search/articles', { params: { q: '*[]()', page: 0, size: 1 } })
+    expect(special.ok()).toBe(true)
+    const paged = await page.request.get('/api/v1/public/search/articles', { params: { q: `阶段四 ${batch}`, page: 0, size: 1 } })
+    expect(paged.ok()).toBe(true)
+    const hiddenSearch = await page.request.get('/api/v1/public/search/articles', { params: { q: `不可公开 ${batch}` } })
+    expect(hiddenSearch.ok()).toBe(true)
+    expect((await hiddenSearch.json() as { total: number }).total).toBe(0)
+  })
+})
diff --git "a/docs/\346\234\254\345\234\260\345\220\257\345\212\250\346\214\207\345\215\227.md" "b/docs/\346\234\254\345\234\260\345\220\257\345\212\250\346\214\207\345\215\227.md"
index 063610c..1087f19 100644
--- "a/docs/\346\234\254\345\234\260\345\220\257\345\212\250\346\214\207\345\215\227.md"
+++ "b/docs/\346\234\254\345\234\260\345\220\257\345\212\250\346\214\207\345\215\227.md"
@@ -1,6 +1,6 @@
 # HaoBlog 本地启动指南
 
-本文适用于本地开发和阶段三公开阅读验收。默认使用 Docker Compose 提供 PostgreSQL/pgvector、Spring Boot API 和 Nuxt Web；生产 Compose 只用于与 CI 等价的本地验收或真实生产环境，不作为日常开发启动方式。
+本文适用于本地开发和阶段四综合验收。默认使用 Docker Compose 提供 PostgreSQL/pgvector、Spring Boot API 和 Nuxt Web；生产 Compose 只用于与 CI 等价的本地验收或真实生产环境，不作为日常开发启动方式。
 
 ## 最简启动
 
@@ -90,6 +90,8 @@ HAOBLOG_ADMIN_PASSWORD_HASH=BCrypt 哈希
 
 评论通知默认关闭。需要本地联调时，只在未提交的 `.env` 中设置 `HAOBLOG_COMMENT_NOTIFICATION_ENABLED=true`，并提供 SMTP 主机、端口、用户名、密码、TLS、站长接收地址和发件地址；仓库示例只使用占位值。API 会使用 5 秒连接、3 秒读取、5 秒写入超时。通知发送失败只进入 Outbox 重试，不会回滚评论提交或审核。
 
+阶段四使用的服务端环境变量分为数据库 `JDBC_DATABASE_*`、管理员 `HAOBLOG_ADMIN_*`、公共地址 `HAOBLOG_PUBLIC_BASE_URL`、评论安全 `HAOBLOG_COMMENT_SECURITY_KEY`、评论通知 `HAOBLOG_COMMENT_NOTIFICATION_*`、OSS `HAOBLOG_OSS_*` 和生产 Compose 的 `HAOBLOG_DOMAIN`/`HAOBLOG_API_IMAGE`/`HAOBLOG_WEB_IMAGE`。`HAOBLOG_COMMENT_SECURITY_KEY` 必须是稳定的高熵服务端密钥；SMTP 密码、OSS 密钥和生产域名只放在未提交的外部环境文件中。
+
 ### 2.2 安装 Web 依赖
 
 ```powershell
@@ -310,19 +312,31 @@ docker compose --env-file infra/compose/.env.ci.example -f infra/compose/compose
 corepack pnpm compose:verify
 ```
 
-### 阶段三生产编排验收
+### 阶段四生产编排验收
 
-完整命令见 [阶段三准入清单](阶段三准入清单.md)。验收时使用独立项目名 `haoblog-s3-acceptance`，构建 `haoblog-api:ci`、`haoblog-web:ci` 后启动生产 Compose，再依次运行 Smoke、Playwright、客户端预算和 Lighthouse。Playwright 使用测试账号 `admin/password`，必须配合 `infra/compose/.env.ci.example`，不能指向生产数据。
+阶段三公开阅读已作为阶段四前置条件完成。当前完整命令见 [阶段四准入清单](阶段四准入清单.md) 和 [第四阶段目标任务](第四阶段目标任务.md)。验收时使用独立项目名 `haoblog-s4-10-acceptance`，构建测试镜像后启动生产 Compose，再依次运行 Smoke、完整 Chromium Playwright、客户端预算和两条 Lighthouse 路由。Playwright 使用测试账号 `admin/password`，必须配合 `infra/compose/.env.ci.example`，不能指向生产数据。
 
 Lighthouse 审计已运行的 Caddy 时需要：
 
 ```powershell
 $env:LHCI_EXISTING_SERVER = 'true'
 $env:LHCI_BASE_URL = 'http://localhost'
+$env:LHCI_ARTICLE_PATH = '/articles/s3-08-advanced-markdown'
 corepack pnpm web:lighthouse
 ```
 
-本地验收不等于真实 OSS、域名 HTTPS、备案或部署通过；这些项目必须在具备真实配置后单独验收。
+工具页 Lighthouse 使用同一命令将 `LHCI_ARTICLE_PATH` 改为 `/tools`，两条命令应串行执行。Windows 若 Chrome 清理临时目录出现 EPERM，可使用工作区内一次性的专用目录：
+
+```powershell
+$lhTemp = Join-Path (Get-Location) '.tmp-lighthouse-s4-10'
+New-Item -ItemType Directory -Force -Path $lhTemp | Out-Null
+$env:TEMP = $lhTemp
+$env:TMP = $lhTemp
+```
+
+阶段四本地结果：API Surefire 78/78、PostgreSQL/pgvector Failsafe 53/53、Web Vitest 85/85、Chromium 14/14；文章初始客户端静态闭包 65,244 bytes gzip，工具组件和 Worker 不进入文章初始包；文章页与工具页 Lighthouse 的 Performance、Accessibility、SEO 均为 1.00。生产 Compose 的资源上限为 Caddy 64 MiB/0.2 CPU/64 PID、Web 320 MiB/0.6 CPU/128 PID、API 640 MiB/1.25 CPU/256 PID、PostgreSQL 480 MiB/0.8 CPU/128 PID。
+
+本地验收不等于真实 SMTP、OSS、域名 HTTPS、备案或部署通过；这些项目必须在具备真实配置后单独验收。本轮明确未执行真实 SMTP、真实域名、真实 OSS、部署和远端生产验收。
 
 ## 6. 停止和清理
 
diff --git "a/docs/\347\254\254\345\233\233\351\230\266\346\256\265\347\233\256\346\240\207\344\273\273\345\212\241.md" "b/docs/\347\254\254\345\233\233\351\230\266\346\256\265\347\233\256\346\240\207\344\273\273\345\212\241.md"
new file mode 100644
index 0000000..d3d8575
--- /dev/null
+++ "b/docs/\347\254\254\345\233\233\351\230\266\346\256\265\347\233\256\346\240\207\344\273\273\345\212\241.md"
@@ -0,0 +1,97 @@
+# 第四阶段目标任务：评论、工具箱、搜索与综合验收
+
+## 实际完成状态
+
+2026-08-23 在 Windows 11、Java 21.0.11、Node.js 24.14.0、pnpm 11.16.0、Docker Engine 29.7.2 和 Docker Compose 5.3.1 下完成本地 S4-10 综合验收。S4-01～S4-09 均已完成，S4-10 的本地契约、E2E、性能、安全和文档验收已完成。远端 CI、真实 SMTP、真实域名 HTTPS、真实 OSS、部署和远端生产验收未执行，不能据此宣称上线。
+
+| 任务 | 状态 | 验收结论 |
+| --- | --- | --- |
+| S4-01 评论模型与站点/文章开关 | [x] 完成 | Flyway、DTO、版本控制与全局/单篇开关可用。 |
+| S4-02 评论安全存储、通知 Outbox 与 SMTP 故障隔离 | [x] 完成 | 邮箱加密、IP HMAC、删除令牌摘要、Outbox 重试和 SMTP 失败不回滚提交通过单测与集成覆盖。 |
+| S4-03 游客评论挑战、限频、反重放、删除 | [x] 完成 | CSRF/挑战、3 秒窗口、挑战消费、恶意输入、限频和删除令牌流程通过运行态 E2E。 |
+| S4-04 文章 SSR 评论信号与游客交互 | [x] 完成 | 无 JavaScript 可读评论信号；真实文章评论接口与待审反馈通过 E2E。 |
+| S4-05 Studio 评论审核与审计 | [x] 完成 | 待审核、通过、垃圾、拒绝、一级回复和用户删除状态通过 Studio/API 验收。 |
+| S4-06 缓存窗口与评论开关即时生效 | [x] 完成 | 全局与单篇开关、ETag/缓存窗口和公开边界通过 E2E/集成测试。 |
+| S4-07 工具分类、LINK/SHOWCASE/EMBEDDED 管理 | [x] 完成 | Studio 工具 CRUD、公开目录、收藏和最常用排序通过 E2E。 |
+| S4-08 五个浏览器内嵌工具与 Worker 隔离 | [x] 完成 | JSON、Base64、URL、时间戳、正则五个输入输出、网络隔离、1 MiB/100 KiB 输入上限和 Worker 250ms 超时通过 E2E/单测。 |
+| S4-09 中文文章搜索 | [x] 完成 | 标题、摘要、正文、特殊字符、分页、无 JavaScript 和未公开文章边界通过 E2E/集成测试。 |
+| S4-10 综合验收 | [x] 完成 | 下方固定数据、全量 Chromium、资源、安全、Bundle 和 Lighthouse 均完成。 |
+
+## 固定验收数据
+
+S4-10 使用独立生产 Compose 项目和临时 PostgreSQL volume，每次重建，测试结束后删除。运行态测试固定建立：
+
+- 一篇开放评论文章和一篇关闭评论文章。
+- 待审核、已通过、垃圾、拒绝、一级回复和用户删除评论；测试邮箱、正文、IP 与删除令牌只通过接口验证，不写入日志。
+- LINK、SHOWCASE 和五个 `EMBEDDED` 工具：`json-format`、`base64`、`url-codec`、`timestamp`、`regex-test`。
+- 分别命中标题、摘要、正文的中文搜索文章，以及一篇未发布、不得公开命中的文章。
+
+## 验收数字
+
+- API `-DskipITs verify`：Surefire 78/78。
+- PostgreSQL/pgvector Failsafe：53/53。
+- Web：typecheck 通过，Vitest 19 个文件、85/85，通过 Nuxt production build。
+- Chromium Playwright：14/14，包含 S2、S3 和 S4 场景；S4-10 专项 2/2。
+- 文章初始客户端静态闭包：13 个静态 chunk，65,244 bytes gzip，小于 180 KiB；Mermaid 在异步 chunk。
+- Lighthouse（移动 360×800，3 次运行）：文章页 `/articles/s3-08-advanced-markdown` 与工具页 `/tools` 的 Performance、Accessibility、SEO 均为 1.00，阈值为 0.90。
+- 生产 Compose 资源上限：Caddy 64 MiB/0.2 CPU/64 PID、Web 320 MiB/0.6 CPU/128 PID、API 640 MiB/1.25 CPU/256 PID、PostgreSQL 480 MiB/0.8 CPU/128 PID。
+- 收口时运行态观察值：API 409.4 MiB、Caddy 16.79 MiB、PostgreSQL 47.93 MiB、Web 105.7 MiB；均未超过上限。
+
+## 验收命令
+
+```powershell
+java -version
+node --version
+corepack pnpm --version
+docker version --format '{{.Server.Version}}'
+docker compose version
+
+Push-Location apps/api
+.\mvnw.cmd -DskipITs verify
+.\mvnw.cmd failsafe:integration-test failsafe:verify
+Pop-Location
+
+corepack pnpm --dir apps/web typecheck
+corepack pnpm --dir apps/web test
+corepack pnpm --dir apps/web build
+corepack pnpm --filter @haoblog/api-client generate
+corepack pnpm --filter @haoblog/api-client check
+git diff --exit-code -- packages/api-client/src/generated.ts
+docker compose --env-file .env.example -f infra/compose/compose.dev.yml config
+docker compose --env-file infra/compose/.env.ci.example -f infra/compose/compose.prod.yml config
+corepack pnpm compose:verify
+
+docker build -f apps/api/Dockerfile -t haoblog-api:s4-10-final .
+docker build -f apps/web/Dockerfile -t haoblog-web:s4-10-final .
+$env:HAOBLOG_API_IMAGE = 'haoblog-api:s4-10-final'
+$env:HAOBLOG_WEB_IMAGE = 'haoblog-web:s4-10-final'
+$env:HAOBLOG_PUBLIC_BASE_URL = 'http://localhost'
+docker compose -p haoblog-s4-10-acceptance --env-file infra/compose/.env.ci.example -f infra/compose/compose.prod.yml up -d --wait --wait-timeout 180
+$env:HAOBLOG_BASE_URL = 'http://localhost'
+corepack pnpm smoke
+$env:CI = 'true'
+corepack pnpm --dir apps/web e2e
+corepack pnpm web:budget
+$env:LHCI_EXISTING_SERVER = 'true'
+$env:LHCI_BASE_URL = 'http://localhost'
+$env:LHCI_ARTICLE_PATH = '/articles/s3-08-advanced-markdown'
+corepack pnpm web:lighthouse
+$env:LHCI_ARTICLE_PATH = '/tools'
+corepack pnpm web:lighthouse
+git diff --check
+docker compose -p haoblog-s4-10-acceptance --env-file infra/compose/.env.ci.example -f infra/compose/compose.prod.yml down -v --remove-orphans
+```
+
+Windows Lighthouse 若清理临时目录偶发 EPERM，应在两次 Lighthouse 命令前设置一次工作区内专用 `TEMP`/`TMP` 目录；本轮该方式成功。
+
+## 安全与边界结论
+
+- 运行态 API 日志扫描未发现验收正文、邮箱、IP、删除令牌、评论安全密钥或 SMTP 密码。
+- SMTP 故障隔离由 `CommentNotificationMailerTest`、`CommentNotificationOutboxProcessorTest` 和 Outbox 集成覆盖；本地验收未连接真实 SMTP。
+- 大文本按字节数限制，正则在独立 Worker 中运行，超时后终止并重建 Worker；主线程不执行正则。
+- 生产拓扑仍只有 Caddy、Nuxt、Spring Boot 和 PostgreSQL/pgvector；只有 Caddy 暴露 80/443。
+- 未执行真实 SMTP、域名/HTTPS、OSS、部署、远端 CI 或远端生产验收；这些是剩余外部验收项，不是本地 S4-10 通过的推断结果。
+
+## 本轮修复
+
+验收发现 Studio 评论审核列表在 PostgreSQL 下对可选关键词、状态和文章 ID 的参数类型绑定不稳定，并且原生查询会错误追加 Java 属性名 `createdAt`。已将应用层筛选参数明确转为字符串，在 PostgreSQL 查询中显式转换并在 SQL 内处理升降序；未改变 OpenAPI 路径或 DTO 契约。修复后 API 78/78、Failsafe 53/53 和完整 Chromium 14/14 均通过。
diff --git "a/docs/\351\230\266\346\256\265\345\233\233\345\207\206\345\205\245\346\270\205\345\215\225.md" "b/docs/\351\230\266\346\256\265\345\233\233\345\207\206\345\205\245\346\270\205\345\215\225.md"
new file mode 100644
index 0000000..faed41d
--- /dev/null
+++ "b/docs/\351\230\266\346\256\265\345\233\233\345\207\206\345\205\245\346\270\205\345\215\225.md"
@@ -0,0 +1,82 @@
+# 阶段四准入清单：评论、工具箱、搜索与综合验收
+
+## S4-10 本地收口状态
+
+2026-08-23 本地综合验收完成。环境为 Java 21.0.11、Node.js 24.14.0、pnpm 11.16.0、Docker Engine 29.7.2、Compose 5.3.1。下面的勾选只表示本地可复现结果，不代表远端或真实生产已验收。
+
+### 契约、代码与数据库
+
+- [x] Java 21、Node.js 24、pnpm 11.16.0、Docker Engine 29.7.2、Compose 5.3.1 已确认。
+- [x] API `-DskipITs verify` 通过，Surefire 78/78。
+- [x] PostgreSQL/pgvector Testcontainers Failsafe 通过，53/53。
+- [x] Web typecheck、Vitest 85/85 和 production build 通过。
+- [x] OpenAPI generate、check 和生成文件无差异通过。
+- [x] dev/prod Compose config 与资源/健康边界校验通过。
+
+### 运行态与 E2E
+
+- [x] 独立项目 `haoblog-s4-10-acceptance` 使用测试镜像启动，Caddy、Web、API、PostgreSQL/pgvector 均 healthy。
+- [x] Smoke 通过，Actuator 未从 Caddy 公网路径暴露。
+- [x] 完整 Chromium Playwright 14/14 通过；覆盖四档视口、键盘、无 JavaScript、Save-Data、reduced-motion、SSR、评论、Studio、工具和搜索。
+- [x] 游客获取 CSRF/挑战、待审提交、挑战重放、恶意输入、限频、删除令牌、公共评论和全局/单篇开关通过。
+- [x] Studio 审核待审、已通过、垃圾、拒绝、一级回复和用户删除状态通过。
+- [x] Studio 工具 CRUD、LINK、SHOWCASE、五个 EMBEDDED、收藏/最常用排序、Worker 输入输出与网络隔离通过。
+- [x] 中文标题/摘要/正文搜索、特殊字符、分页、无 JavaScript 和公开边界通过。
+
+### 性能、资源与安全
+
+- [x] 文章初始客户端静态闭包 65,244 bytes gzip，小于 180 KiB；工具组件和 Worker 不进入文章初始包。
+- [x] 文章页和工具页 Lighthouse 三次运行的 Performance、Accessibility、SEO 均为 1.00，均不低于 0.90。
+- [x] Caddy/Web/API/PostgreSQL 的内存、CPU、PID 上限保持 64/320/640/480 MiB、0.2/0.6/1.25/0.8 CPU、64/128/256/128 PID。
+- [x] 收口观察值为 API 409.4 MiB、Caddy 16.79 MiB、PostgreSQL 47.93 MiB、Web 105.7 MiB。
+- [x] 日志未发现评论正文、邮箱、IP、删除令牌、安全密钥或 SMTP 密码。
+- [x] SMTP 故障隔离、大文本限制和正则 Worker 超时有单测/集成覆盖；正则 Worker 超时为 250ms。
+- [x] `git diff --check` 通过。
+
+## 阶段四验收命令
+
+依赖、代码、契约和配置：
+
+```powershell
+Push-Location apps/api
+.\mvnw.cmd -DskipITs verify
+.\mvnw.cmd failsafe:integration-test failsafe:verify
+Pop-Location
+corepack pnpm --dir apps/web typecheck
+corepack pnpm --dir apps/web test
+corepack pnpm --dir apps/web build
+corepack pnpm --filter @haoblog/api-client generate
+corepack pnpm --filter @haoblog/api-client check
+git diff --exit-code -- packages/api-client/src/generated.ts
+docker compose --env-file .env.example -f infra/compose/compose.dev.yml config
+docker compose --env-file infra/compose/.env.ci.example -f infra/compose/compose.prod.yml config
+corepack pnpm compose:verify
+```
+
+生产编排、Smoke、E2E、性能与清理：
+
+```powershell
+docker build -f apps/api/Dockerfile -t haoblog-api:s4-10-final .
+docker build -f apps/web/Dockerfile -t haoblog-web:s4-10-final .
+$env:HAOBLOG_API_IMAGE = 'haoblog-api:s4-10-final'
+$env:HAOBLOG_WEB_IMAGE = 'haoblog-web:s4-10-final'
+$env:HAOBLOG_PUBLIC_BASE_URL = 'http://localhost'
+docker compose -p haoblog-s4-10-acceptance --env-file infra/compose/.env.ci.example -f infra/compose/compose.prod.yml up -d --wait --wait-timeout 180
+$env:HAOBLOG_BASE_URL = 'http://localhost'
+corepack pnpm smoke
+$env:CI = 'true'
+corepack pnpm --dir apps/web e2e
+corepack pnpm web:budget
+$env:LHCI_EXISTING_SERVER = 'true'
+$env:LHCI_BASE_URL = 'http://localhost'
+$env:LHCI_ARTICLE_PATH = '/articles/s3-08-advanced-markdown'
+corepack pnpm web:lighthouse
+$env:LHCI_ARTICLE_PATH = '/tools'
+corepack pnpm web:lighthouse
+git diff --check
+docker compose -p haoblog-s4-10-acceptance --env-file infra/compose/.env.ci.example -f infra/compose/compose.prod.yml down -v --remove-orphans
+```
+
+## 未执行项目
+
+真实 SMTP 投递、真实域名与 HTTPS、真实 OSS、镜像推送、部署、远端 CI 和远端生产验收均未执行。`infra/compose/.env.ci.example` 的账号、密钥和 OSS 值只用于临时本地验收，不能用于生产。