feat(poll): add poll vote module backing @Haklex poll node

- PollVoteModel collection (poll_votes) with unique
  (pollId, voterFingerprint) index for one-shot dedup
- PollService: getState / batchGetStates / submit, with
  fingerprint = "r:<readerId>" for logged-in or
  sha256(ip+ua) for anonymous voters
- Endpoints (under /api/v2/polls):
  - GET /         — batch fetch (?ids=p_a,p_b,...)
  - GET /:pollId  — single state
  - POST /:pollId/vote — submit; idempotent via unique index

Author: Innei

apps/core/src/app.module.ts

@@ -47,6 +47,7 @@ import { OptionModule } from './modules/option/option.module'
 import { OwnerModule } from './modules/owner/owner.module'
 import { PageModule } from './modules/page/page.module'
 import { PageProxyModule } from './modules/pageproxy/pageproxy.module'
+import { PollModule } from './modules/poll/poll.module'
 import { PostModule } from './modules/post/post.module'
 import { ProjectModule } from './modules/project/project.module'
 import { ReaderModule } from './modules/reader/reader.module'
@@ -101,6 +102,7 @@ import { TaskQueueModule } from './processors/task-queue/task-queue.module'
     NoteModule,
     OptionModule,
     PageModule,
+    PollModule,
     PostModule,
     ProjectModule,
     RecentlyModule,

apps/core/src/constants/db.constant.ts

@@ -19,6 +19,7 @@ export const NOTE_COLLECTION_NAME = 'notes'
 export const OPTION_COLLECTION_NAME = 'options'
 export const OWNER_PROFILE_COLLECTION_NAME = 'owner_profiles'
 export const PAGE_COLLECTION_NAME = 'pages'
+export const POLL_VOTE_COLLECTION_NAME = 'poll_votes'
 export const POST_COLLECTION_NAME = 'posts'
 export const PROJECT_COLLECTION_NAME = 'projects'
 export const READER_COLLECTION_NAME = 'readers'

apps/core/src/modules/poll/poll-vote.model.ts

@@ -0,0 +1,20 @@
+import { index, modelOptions, prop } from '@typegoose/typegoose'
+
+import { POLL_VOTE_COLLECTION_NAME } from '~/constants/db.constant'
+import { BaseModel } from '~/shared/model/base.model'
+
+@modelOptions({
+  options: { customName: POLL_VOTE_COLLECTION_NAME },
+})
+@index({ pollId: 1, voterFingerprint: 1 }, { unique: true })
+@index({ pollId: 1 })
+export class PollVoteModel extends BaseModel {
+  @prop({ required: true })
+  pollId: string
+
+  @prop({ required: true })
+  voterFingerprint: string
+
+  @prop({ required: true, type: () => [String] })
+  optionIds: string[]
+}

apps/core/src/modules/poll/poll.controller.ts

@@ -0,0 +1,56 @@
+import { Body, Get, Param, Post, Query } from '@nestjs/common'
+
+import { ApiController } from '~/common/decorators/api-controller.decorator'
+import { CurrentReaderId } from '~/common/decorators/current-user.decorator'
+import { IpLocation, type IpRecord } from '~/common/decorators/ip.decorator'
+
+import { BatchPollQueryDto, PollIdDto, SubmitPollDto } from './poll.dto'
+import { PollService } from './poll.service'
+
+@ApiController('polls')
+export class PollController {
+  constructor(private readonly pollService: PollService) {}
+
+  @Get('/')
+  async batch(
+    @Query() query: BatchPollQueryDto,
+    @IpLocation() ipLocation: IpRecord,
+    @CurrentReaderId() readerId?: string,
+  ) {
+    const fingerprint = this.pollService.computeFingerprint({
+      readerId,
+      ip: ipLocation.ip,
+      agent: ipLocation.agent ?? '',
+    })
+    return this.pollService.batchGetStates(query.ids, fingerprint)
+  }
+
+  @Get('/:pollId')
+  async getOne(
+    @Param() params: PollIdDto,
+    @IpLocation() ipLocation: IpRecord,
+    @CurrentReaderId() readerId?: string,
+  ) {
+    const fingerprint = this.pollService.computeFingerprint({
+      readerId,
+      ip: ipLocation.ip,
+      agent: ipLocation.agent ?? '',
+    })
+    return this.pollService.getState(params.pollId, fingerprint)
+  }
+
+  @Post('/:pollId/vote')
+  async vote(
+    @Param() params: PollIdDto,
+    @Body() body: SubmitPollDto,
+    @IpLocation() ipLocation: IpRecord,
+    @CurrentReaderId() readerId?: string,
+  ) {
+    const fingerprint = this.pollService.computeFingerprint({
+      readerId,
+      ip: ipLocation.ip,
+      agent: ipLocation.agent ?? '',
+    })
+    return this.pollService.submit(params.pollId, fingerprint, body.optionIds)
+  }
+}

apps/core/src/modules/poll/poll.dto.ts

@@ -0,0 +1,38 @@
+import { createZodDto } from 'nestjs-zod'
+import { z } from 'zod'
+
+const PollIdSchema = z
+  .string()
+  .trim()
+  .min(3)
+  .max(64)
+  .regex(/^p_[\da-z]+$/i)
+
+const OptionIdSchema = z
+  .string()
+  .trim()
+  .min(3)
+  .max(64)
+  .regex(/^o_[\da-z]+$/i)
+
+const PollIdParam = z.object({ pollId: PollIdSchema })
+export class PollIdDto extends createZodDto(PollIdParam) {}
+
+const SubmitPollSchema = z.object({
+  optionIds: z.array(OptionIdSchema).min(1).max(20),
+})
+export class SubmitPollDto extends createZodDto(SubmitPollSchema) {}
+
+const BatchPollQuerySchema = z.object({
+  ids: z
+    .string()
+    .min(3)
+    .transform((s) =>
+      s
+        .split(',')
+        .map((v) => v.trim())
+        .filter(Boolean),
+    )
+    .pipe(z.array(PollIdSchema).min(1).max(50)),
+})
+export class BatchPollQueryDto extends createZodDto(BatchPollQuerySchema) {}

apps/core/src/modules/poll/poll.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common'
+
+import { PollController } from './poll.controller'
+import { PollService } from './poll.service'
+
+@Module({
+  controllers: [PollController],
+  providers: [PollService],
+  exports: [PollService],
+})
+export class PollModule {}

apps/core/src/modules/poll/poll.service.ts

@@ -0,0 +1,101 @@
+import { createHash } from 'node:crypto'
+
+import { Injectable, Logger } from '@nestjs/common'
+
+import { InjectModel } from '~/transformers/model.transformer'
+
+import { PollVoteModel } from './poll-vote.model'
+
+export interface PollState {
+  tallies: Record<string, number>
+  totalVotes: number
+  userVote?: string[]
+  status: 'ready' | 'error'
+  closed: boolean
+  canVote: boolean
+  errorMessage?: string
+}
+
+interface FingerprintInput {
+  readerId?: string | null
+  ip: string
+  agent: string
+}
+
+@Injectable()
+export class PollService {
+  private readonly logger = new Logger(PollService.name)
+
+  constructor(
+    @InjectModel(PollVoteModel)
+    private readonly model: MongooseModel<PollVoteModel>,
+  ) {}
+
+  /**
+   * Stable identity for vote dedup. Logged-in readers map to `r:<id>`;
+   * anonymous voters hash IP + UA into `a:<hex>`.
+   */
+  computeFingerprint({ readerId, ip, agent }: FingerprintInput): string {
+    if (readerId) return `r:${readerId}`
+    const digest = createHash('sha256')
+      .update(`${ip}|${agent}`)
+      .digest('hex')
+      .slice(0, 32)
+    return `a:${digest}`
+  }
+
+  async getState(pollId: string, voterFingerprint: string): Promise<PollState> {
+    const [tallyDocs, vote, totalVotes] = await Promise.all([
+      this.model
+        .aggregate<{
+          _id: string
+          count: number
+        }>([{ $match: { pollId } }, { $unwind: '$optionIds' }, { $group: { _id: '$optionIds', count: { $sum: 1 } } }])
+        .exec(),
+      this.model.findOne({ pollId, voterFingerprint }).lean().exec(),
+      this.model.countDocuments({ pollId }).exec(),
+    ])
+
+    const tallies: Record<string, number> = {}
+    for (const doc of tallyDocs) tallies[doc._id] = doc.count
+
+    return {
+      tallies,
+      totalVotes,
+      userVote: vote?.optionIds,
+      status: 'ready',
+      closed: false,
+      canVote: !vote,
+    }
+  }
+
+  async batchGetStates(
+    pollIds: string[],
+    voterFingerprint: string,
+  ): Promise<Record<string, PollState>> {
+    const out: Record<string, PollState> = {}
+    await Promise.all(
+      pollIds.map(async (pollId) => {
+        out[pollId] = await this.getState(pollId, voterFingerprint)
+      }),
+    )
+    return out
+  }
+
+  async submit(
+    pollId: string,
+    voterFingerprint: string,
+    optionIds: string[],
+  ): Promise<PollState> {
+    try {
+      await this.model.create({ pollId, voterFingerprint, optionIds })
+    } catch (err: any) {
+      if (err?.code === 11_000) {
+        const state = await this.getState(pollId, voterFingerprint)
+        return { ...state, status: 'error', errorMessage: 'Already voted' }
+      }
+      throw err
+    }
+    return this.getState(pollId, voterFingerprint)
+  }
+}

apps/core/src/processors/database/database.models.ts

@@ -15,6 +15,7 @@ import { MetaPresetModel } from '~/modules/meta-preset/meta-preset.model'
 import { NoteModel } from '~/modules/note/note.model'
 import { OwnerProfileModel } from '~/modules/owner/owner-profile.model'
 import { PageModel } from '~/modules/page/page.model'
+import { PollVoteModel } from '~/modules/poll/poll-vote.model'
 import { PostModel } from '~/modules/post/post.model'
 import { ProjectModel } from '~/modules/project/project.model'
 import { ReaderModel } from '~/modules/reader/reader.model'
@@ -47,6 +48,7 @@ export const databaseModels = [
   NoteModel,
   OptionModel,
   PageModel,
+  PollVoteModel,
   PostModel,
   ProjectModel,
   ReaderModel,