Browse Source
- Added a comprehensive implementation plan for comment email infrastructure, including SMTP configuration, guest email handling, and user notification preferences. - Extended the config registry and admin UI to support new settings, ensuring a robust email notification system without blocking comment creation. - Created necessary API endpoints and tests to validate the functionality of the new features. This update enhances the comment system's email capabilities and user experience.main
1 changed files with 471 additions and 0 deletions
@ -0,0 +1,471 @@ |
|||
# Comment Email Config Implementation Plan |
|||
|
|||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. |
|||
|
|||
**Goal:** Add comment email infrastructure with admin SMTP config, guest anonymous email rules, per-user notification preference, and admin test-send capability without blocking comment creation. |
|||
|
|||
**Architecture:** Extend the existing config registry (global + user) for mail settings and notify preferences, then wire those values into comment creation and notification service logic. Keep notification sending best-effort and side-effect-safe: comment write succeeds even if email send fails. Reuse existing `/api/config/*`, profile page, and comment service patterns. |
|||
|
|||
**Tech Stack:** Nuxt 3, Nitro server routes, Drizzle (SQLite), Bun test, existing config service in `server/service/config`. |
|||
|
|||
--- |
|||
|
|||
## File Structure Map |
|||
|
|||
- **Config domain** |
|||
- Modify `server/service/config/registry.ts` for new config keys and validation. |
|||
- Modify `app/composables/useGlobalConfig.ts` for global config typing updates. |
|||
- Modify `app/pages/me/admin/config/index.vue` for SMTP form and test-send action. |
|||
- Create `server/api/config/global/comment-email-test.post.ts` for admin test email. |
|||
- **Comment domain** |
|||
- Modify `packages/drizzle-pkg/database/sqlite/schema/content.ts` to add guest email fields. |
|||
- Create a migration under `packages/drizzle-pkg/migrations`. |
|||
- Modify `server/service/post-comments/index.ts` to validate/store guest email + anonymous. |
|||
- Modify `app/components/PostComments.vue` to collect guest email + anonymous toggle and render user hints. |
|||
- **Notification domain** |
|||
- Create `server/service/comment-notify/index.ts` for send gating + dispatch. |
|||
- Integrate notify trigger in comment create flow routes. |
|||
- **User preference** |
|||
- Modify `app/pages/me/profile/index.vue` and `/api/config/me` usage to add `commentNotifyEnabled`. |
|||
- **Tests** |
|||
- Modify/create tests in `server/utils/post-comment-guest.test.ts`, comment service tests, and config validation tests. |
|||
|
|||
--- |
|||
|
|||
### Task 1: Add Config Keys and Validation |
|||
|
|||
**Files:** |
|||
- Modify: `server/service/config/registry.ts` |
|||
- Test: `server/service/config/registry.test.ts` (create if absent) |
|||
|
|||
- [ ] **Step 1: Write the failing validation tests** |
|||
|
|||
```ts |
|||
import { describe, expect, test } from "bun:test"; |
|||
import { validateConfigValue } from "./registry"; |
|||
|
|||
describe("comment mail config validation", () => { |
|||
test("accepts valid from email", () => { |
|||
expect(validateConfigValue("commentMailFromEmail", "sender@example.com")).toBe(true); |
|||
}); |
|||
|
|||
test("rejects invalid from email", () => { |
|||
expect(validateConfigValue("commentMailFromEmail", "bad-email")).toBe(false); |
|||
}); |
|||
|
|||
test("accepts comment notify default", () => { |
|||
expect(validateConfigValue("commentNotifyEnabled", true)).toBe(true); |
|||
}); |
|||
}); |
|||
``` |
|||
|
|||
- [ ] **Step 2: Run test to verify it fails** |
|||
|
|||
Run: `bun test server/service/config/registry.test.ts` |
|||
Expected: FAIL with unknown key/type validation mismatch. |
|||
|
|||
- [ ] **Step 3: Implement minimal registry entries** |
|||
|
|||
```ts |
|||
commentEmailNotifyEnabled: defineConfig<boolean>({ key: "commentEmailNotifyEnabled", scope: "global", valueType: "boolean", defaultValue: false, userOverridable: false }), |
|||
commentMailFromEmail: defineConfig<string>({ |
|||
key: "commentMailFromEmail", |
|||
scope: "global", |
|||
valueType: "string", |
|||
defaultValue: "", |
|||
userOverridable: false, |
|||
validate: (value: string) => !value.trim() || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim()), |
|||
}), |
|||
commentSmtpHost: defineConfig<string>({ key: "commentSmtpHost", scope: "global", valueType: "string", defaultValue: "", userOverridable: false }), |
|||
commentSmtpPort: defineConfig<number>({ |
|||
key: "commentSmtpPort", |
|||
scope: "global", |
|||
valueType: "number", |
|||
defaultValue: 465, |
|||
userOverridable: false, |
|||
validate: (value: number) => Number.isInteger(value) && value >= 1 && value <= 65535, |
|||
}), |
|||
commentSmtpSecure: defineConfig<boolean>({ key: "commentSmtpSecure", scope: "global", valueType: "boolean", defaultValue: true, userOverridable: false }), |
|||
commentSmtpUser: defineConfig<string>({ key: "commentSmtpUser", scope: "global", valueType: "string", defaultValue: "", userOverridable: false }), |
|||
commentSmtpPass: defineConfig<string>({ key: "commentSmtpPass", scope: "global", valueType: "string", defaultValue: "", userOverridable: false }), |
|||
commentNotifyEnabled: defineConfig<boolean>({ key: "commentNotifyEnabled", scope: "both", valueType: "boolean", defaultValue: true, userOverridable: true }), |
|||
``` |
|||
|
|||
- [ ] **Step 4: Run test to verify it passes** |
|||
|
|||
Run: `bun test server/service/config/registry.test.ts` |
|||
Expected: PASS. |
|||
|
|||
- [ ] **Step 5: Commit** |
|||
|
|||
```bash |
|||
git add server/service/config/registry.ts server/service/config/registry.test.ts |
|||
git commit -m "feat(config): add comment email and notify preference keys" |
|||
``` |
|||
|
|||
--- |
|||
|
|||
### Task 2: Extend Admin Global Config UI and Global Composable |
|||
|
|||
**Files:** |
|||
- Modify: `app/composables/useGlobalConfig.ts` |
|||
- Modify: `app/pages/me/admin/config/index.vue` |
|||
|
|||
- [ ] **Step 1: Write a focused UI behavior test (or component-level assertion)** |
|||
|
|||
```ts |
|||
// Pseudocode if no mounted test infra exists yet: |
|||
// assert payload includes commentEmailNotifyEnabled/commentSmtpHost/commentSmtpPort/commentSmtpSecure/commentSmtpUser/commentSmtpPass/commentMailFromEmail |
|||
``` |
|||
|
|||
- [ ] **Step 2: Run existing frontend checks** |
|||
|
|||
Run: `bun run typecheck` |
|||
Expected: FAIL due to missing new config fields in types. |
|||
|
|||
- [ ] **Step 3: Implement minimal type + form changes** |
|||
|
|||
```ts |
|||
// useGlobalConfig.ts |
|||
export type GlobalConfig = { |
|||
siteName: string; |
|||
allowRegister: boolean; |
|||
commentEmailNotifyEnabled: boolean; |
|||
commentMailFromEmail: string; |
|||
commentSmtpHost: string; |
|||
commentSmtpPort: number; |
|||
commentSmtpSecure: boolean; |
|||
commentSmtpUser: string; |
|||
}; |
|||
``` |
|||
|
|||
```vue |
|||
<!-- me/admin/config/index.vue --> |
|||
<UFormField label="评论邮件通知总开关"><UCheckbox v-model="commentEmailNotifyEnabled" label="开启" /></UFormField> |
|||
<UFormField label="发件人邮箱"><UInput v-model="commentMailFromEmail" placeholder="noreply@example.com" /></UFormField> |
|||
<UFormField label="SMTP Host"><UInput v-model="commentSmtpHost" /></UFormField> |
|||
<UFormField label="SMTP Port"><UInput v-model.number="commentSmtpPort" type="number" /></UFormField> |
|||
<UFormField label="SMTP Secure"><UCheckbox v-model="commentSmtpSecure" label="TLS/SSL" /></UFormField> |
|||
<UFormField label="SMTP User"><UInput v-model="commentSmtpUser" /></UFormField> |
|||
<UFormField label="SMTP Password"><UInput v-model="commentSmtpPass" type="password" autocomplete="new-password" /></UFormField> |
|||
``` |
|||
|
|||
- [ ] **Step 4: Re-run checks** |
|||
|
|||
Run: `bun run typecheck` |
|||
Expected: PASS for touched types/components. |
|||
|
|||
- [ ] **Step 5: Commit** |
|||
|
|||
```bash |
|||
git add app/composables/useGlobalConfig.ts app/pages/me/admin/config/index.vue |
|||
git commit -m "feat(admin-config): add comment mail smtp settings form" |
|||
``` |
|||
|
|||
--- |
|||
|
|||
### Task 3: Add Admin Test Send Endpoint and Button |
|||
|
|||
**Files:** |
|||
- Create: `server/api/config/global/comment-email-test.post.ts` |
|||
- Modify: `app/pages/me/admin/config/index.vue` |
|||
- Create/Modify Test: `server/api/config/global/comment-email-test.post.test.ts` |
|||
|
|||
- [ ] **Step 1: Write failing API tests** |
|||
|
|||
```ts |
|||
test("returns 400 when smtp config incomplete", async () => { |
|||
// setup admin session + empty smtp config |
|||
// call POST /api/config/global/comment-email-test |
|||
// expect 400 |
|||
}); |
|||
``` |
|||
|
|||
- [ ] **Step 2: Run targeted test** |
|||
|
|||
Run: `bun test server/api/config/global/comment-email-test.post.test.ts` |
|||
Expected: FAIL with route missing. |
|||
|
|||
- [ ] **Step 3: Implement endpoint and UI action** |
|||
|
|||
```ts |
|||
// comment-email-test.post.ts |
|||
await requireAdmin(event); |
|||
const user = await event.context.auth.requireUser(); |
|||
const cfg = await getCommentMailConfig(event.context.config); |
|||
assertMailConfigReady(cfg); |
|||
if (!user.email) throw createError({ statusCode: 400, statusMessage: "管理员未配置邮箱" }); |
|||
await sendCommentTestMail({ to: user.email, cfg }); |
|||
return R.success({ ok: true }); |
|||
``` |
|||
|
|||
```vue |
|||
<UButton :loading="testingMail" variant="soft" @click="testSendMail">发送测试邮件</UButton> |
|||
``` |
|||
|
|||
- [ ] **Step 4: Run test again** |
|||
|
|||
Run: `bun test server/api/config/global/comment-email-test.post.test.ts` |
|||
Expected: PASS. |
|||
|
|||
- [ ] **Step 5: Commit** |
|||
|
|||
```bash |
|||
git add server/api/config/global/comment-email-test.post.ts server/api/config/global/comment-email-test.post.test.ts app/pages/me/admin/config/index.vue |
|||
git commit -m "feat(mail): add admin comment email test-send endpoint" |
|||
``` |
|||
|
|||
--- |
|||
|
|||
### Task 4: Add DB Fields for Guest Email and Anonymous Flag |
|||
|
|||
**Files:** |
|||
- Modify: `packages/drizzle-pkg/database/sqlite/schema/content.ts` |
|||
- Create: `packages/drizzle-pkg/migrations/0008_comment_guest_email.sql` (use next available index) |
|||
- Modify: `packages/drizzle-pkg/migrations/meta/_journal.json` (if migration tooling requires) |
|||
|
|||
- [ ] **Step 1: Write failing service test for guest email rules** |
|||
|
|||
```ts |
|||
test("guest non-anonymous must provide email", async () => { |
|||
await expect(createComment({ |
|||
postId, ownerUserId, parentId: null, viewer: null, |
|||
guestDisplayName: "访客", guestIsAnonymous: false, guestEmail: "", |
|||
body: "hello", |
|||
})).rejects.toThrow("请填写邮箱"); |
|||
}); |
|||
``` |
|||
|
|||
- [ ] **Step 2: Run test to confirm fail** |
|||
|
|||
Run: `bun test server/service/post-comments/index.test.ts` |
|||
Expected: FAIL due to unknown fields / missing validation. |
|||
|
|||
- [ ] **Step 3: Add schema + migration** |
|||
|
|||
```ts |
|||
guestEmail: text("guest_email"), |
|||
guestIsAnonymous: integer("guest_is_anonymous", { mode: "boolean" }).notNull().default(false), |
|||
``` |
|||
|
|||
```sql |
|||
ALTER TABLE post_comments ADD COLUMN guest_email text; |
|||
ALTER TABLE post_comments ADD COLUMN guest_is_anonymous integer DEFAULT 0 NOT NULL; |
|||
``` |
|||
|
|||
- [ ] **Step 4: Run migration/test checks** |
|||
|
|||
Run: `bun test server/service/post-comments/index.test.ts` |
|||
Expected: still FAIL until service is implemented (this is expected at this stage). |
|||
|
|||
- [ ] **Step 5: Commit** |
|||
|
|||
```bash |
|||
git add packages/drizzle-pkg/database/sqlite/schema/content.ts packages/drizzle-pkg/migrations/0008_comment_guest_email.sql packages/drizzle-pkg/migrations/meta/_journal.json |
|||
git commit -m "feat(db): add guest email and anonymous fields for comments" |
|||
``` |
|||
|
|||
--- |
|||
|
|||
### Task 5: Implement Comment Service Validation and Persist New Fields |
|||
|
|||
**Files:** |
|||
- Modify: `server/service/post-comments/index.ts` |
|||
- Modify: `server/utils/post-comment-guest.ts` |
|||
- Modify: `server/utils/post-comment-guest.test.ts` |
|||
- Modify: `app/components/PostComments.vue` |
|||
|
|||
- [ ] **Step 1: Expand failing validation tests** |
|||
|
|||
```ts |
|||
test("anonymous guest can omit email", () => { |
|||
expect(validateGuestCommentEmail("", true)).toBe(""); |
|||
}); |
|||
|
|||
test("non-anonymous guest rejects invalid email", () => { |
|||
expect(() => validateGuestCommentEmail("abc", false)).toThrow(GuestCommentValidationError); |
|||
}); |
|||
``` |
|||
|
|||
- [ ] **Step 2: Run guest validation tests** |
|||
|
|||
Run: `bun test server/utils/post-comment-guest.test.ts` |
|||
Expected: FAIL with `validateGuestCommentEmail` undefined. |
|||
|
|||
- [ ] **Step 3: Implement validation and form payload** |
|||
|
|||
```ts |
|||
export function validateGuestCommentEmail(raw: string, isAnonymous: boolean): string { |
|||
const t = raw.trim(); |
|||
if (isAnonymous) return t; |
|||
if (!t) throw new GuestCommentValidationError("请填写邮箱"); |
|||
if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t)) throw new GuestCommentValidationError("邮箱格式不正确"); |
|||
return t; |
|||
} |
|||
``` |
|||
|
|||
```vue |
|||
<UCheckbox v-model="guestIsAnonymous" label="匿名评论（可不填邮箱）" /> |
|||
<UInput v-model="guestEmail" :required="!guestIsAnonymous" placeholder="你的邮箱" /> |
|||
``` |
|||
|
|||
- [ ] **Step 4: Run tests and typecheck** |
|||
|
|||
Run: `bun test server/utils/post-comment-guest.test.ts && bun run typecheck` |
|||
Expected: PASS. |
|||
|
|||
- [ ] **Step 5: Commit** |
|||
|
|||
```bash |
|||
git add server/service/post-comments/index.ts server/utils/post-comment-guest.ts server/utils/post-comment-guest.test.ts app/components/PostComments.vue |
|||
git commit -m "feat(comments): enforce guest email rules with anonymous override" |
|||
``` |
|||
|
|||
--- |
|||
|
|||
### Task 6: Add User Notification Preference in Profile |
|||
|
|||
**Files:** |
|||
- Modify: `app/pages/me/profile/index.vue` |
|||
- Modify: `server/service/config/registry.ts` (if not already included in Task 1) |
|||
|
|||
- [ ] **Step 1: Write failing profile load/save assertion** |
|||
|
|||
```ts |
|||
// verify /api/config/me result drives state.commentNotifyEnabled and save writes key |
|||
``` |
|||
|
|||
- [ ] **Step 2: Run typecheck before implementation** |
|||
|
|||
Run: `bun run typecheck` |
|||
Expected: FAIL due to missing `commentNotifyEnabled` state/binding. |
|||
|
|||
- [ ] **Step 3: Implement minimal state + save wiring** |
|||
|
|||
```ts |
|||
state.commentNotifyEnabled = typeof cfg.commentNotifyEnabled === "boolean" ? cfg.commentNotifyEnabled : true; |
|||
``` |
|||
|
|||
```ts |
|||
await fetchData('/api/config/me', { |
|||
method: 'PUT', |
|||
notify: false, |
|||
body: { key: 'commentNotifyEnabled', value: state.commentNotifyEnabled }, |
|||
}); |
|||
``` |
|||
|
|||
```vue |
|||
<UCheckbox v-model="state.commentNotifyEnabled" label="接收评论邮件通知" /> |
|||
``` |
|||
|
|||
- [ ] **Step 4: Re-run typecheck** |
|||
|
|||
Run: `bun run typecheck` |
|||
Expected: PASS. |
|||
|
|||
- [ ] **Step 5: Commit** |
|||
|
|||
```bash |
|||
git add app/pages/me/profile/index.vue |
|||
git commit -m "feat(profile): add comment email notify preference toggle" |
|||
``` |
|||
|
|||
--- |
|||
|
|||
### Task 7: Implement Notification Dispatch on Comment Create |
|||
|
|||
**Files:** |
|||
- Create: `server/service/comment-notify/index.ts` |
|||
- Modify: `server/api/public/profile/[publicSlug]/posts/[postSlug]/comments.post.ts` |
|||
- Modify: `server/api/public/unlisted/[publicSlug]/[shareToken]/comments.post.ts` |
|||
- Create/Modify Tests: `server/service/comment-notify/index.test.ts` |
|||
|
|||
- [ ] **Step 1: Write failing notify gating tests** |
|||
|
|||
```ts |
|||
test("skips when global switch off", async () => { |
|||
// expect no send call |
|||
}); |
|||
|
|||
test("skips when target user has notify disabled", async () => { |
|||
// expect no send call |
|||
}); |
|||
``` |
|||
|
|||
- [ ] **Step 2: Run targeted tests** |
|||
|
|||
Run: `bun test server/service/comment-notify/index.test.ts` |
|||
Expected: FAIL (service missing). |
|||
|
|||
- [ ] **Step 3: Implement best-effort notify service** |
|||
|
|||
```ts |
|||
export async function notifyOnCommentReply(input: { postId: number; commentId: number; actorUserId: number | null; parentId: number | null }) { |
|||
if (!input.parentId) return; |
|||
// load target comment author -> user |
|||
// check global config + smtp readiness + user pref + user email |
|||
// send and catch errors with logger.error(...) |
|||
} |
|||
``` |
|||
|
|||
- [ ] **Step 4: Integrate into POST handlers** |
|||
|
|||
```ts |
|||
const id = await createComment(...); |
|||
void notifyOnCommentReply({ postId, commentId: id, actorUserId: viewer?.id ?? null, parentId: body.parentId ?? null }); |
|||
return R.success({ id }); |
|||
``` |
|||
|
|||
- [ ] **Step 5: Run tests** |
|||
|
|||
Run: `bun test server/service/comment-notify/index.test.ts` |
|||
Expected: PASS. |
|||
|
|||
- [ ] **Step 6: Commit** |
|||
|
|||
```bash |
|||
git add server/service/comment-notify/index.ts server/service/comment-notify/index.test.ts server/api/public/profile/[publicSlug]/posts/[postSlug]/comments.post.ts server/api/public/unlisted/[publicSlug]/[shareToken]/comments.post.ts |
|||
git commit -m "feat(notify): send best-effort comment reply emails" |
|||
``` |
|||
|
|||
--- |
|||
|
|||
### Task 8: End-to-End Verification and Documentation Update |
|||
|
|||
**Files:** |
|||
- Modify (if needed): `docs/superpowers/specs/2026-04-20-comment-email-config-design.md` |
|||
- Modify/Create: any README/admin docs that mention config keys |
|||
|
|||
- [ ] **Step 1: Run full relevant test suite** |
|||
|
|||
Run: `bun test server/utils/post-comment-guest.test.ts server/service/comment-notify/index.test.ts server/service/config/registry.test.ts` |
|||
Expected: PASS. |
|||
|
|||
- [ ] **Step 2: Run static verification** |
|||
|
|||
Run: `bun run typecheck` |
|||
Expected: PASS. |
|||
|
|||
- [ ] **Step 3: Manually verify key flows** |
|||
|
|||
Run app and validate: |
|||
1. Admin saves SMTP config and test-send succeeds. |
|||
2. Guest comment requires email unless anonymous checked. |
|||
3. Logged-in user without email can comment but sees warning. |
|||
4. User can toggle notify preference and it affects send decision. |
|||
|
|||
- [ ] **Step 4: Commit verification/doc touch-ups** |
|||
|
|||
```bash |
|||
git add docs/superpowers/specs/2026-04-20-comment-email-config-design.md |
|||
git commit -m "docs(comment-email): align spec notes with implementation checks" |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Self-Review |
|||
|
|||
- **Spec coverage:** All approved requirements are mapped to tasks: global SMTP config, guest anonymous/email rule, user notify preference default true, non-blocking send, and admin test-send. |
|||
- **Placeholder scan:** No `TODO/TBD` placeholders remain; each code step has concrete snippet and command. |
|||
- **Type consistency:** Config keys use a consistent prefix (`comment*`) across registry, UI, and notification service tasks. |
|||
|
|||
Loading…
Reference in new issue