实现制度签收轻量回执（05-28-oa-policy-acknowledgement-v1）

.trellis/spec/hyb-oa/backend-fastify-prisma.md

@@ -22,3 +22,73 @@ QA script patterns over new abstractions.
 - `cd server && node --check src/routes/workflow.js`
 - `cd server && ./scripts/regression-workflow-actions.sh`
 - `cd server && ./scripts/regression-all.sh`
+
+## Scenario: Portal Announcement Acknowledgement
+
+### 1. Scope / Trigger
+
+- Trigger: extending `announcements_v1` from read-only announcements into formal employee acknowledgement.
+- Applies to `server/prisma/schema.prisma`, `server/src/routes/announcements.js`, `client/src/api/announcements.ts`, employee `/announcements`, and admin `/system/announcements`.
+- Use this only for lightweight policy acknowledgement; do not treat it as electronic signature, CA signing, contract signing, or full policy CMS.
+
+### 2. Signatures
+
+- DB: `PortalAnnouncement` may carry `category`, `requires_acknowledgement`, `acknowledgement_statement`, `acknowledgement_due_at`.
+- DB: `PortalAnnouncementAcknowledgement` stores one receipt per `(announcement_id, employee_id)` with statement/title/summary snapshots and `actor_id`.
+- API: `GET /api/announcements?manage=0` returns visible announcements and the current employee's acknowledgement status.
+- API: `GET /api/announcements?manage=1` requires `system.settings` and returns acknowledgement summary plus minimal pending employees.
+- API: `POST /api/announcements/:id/acknowledge` accepts `{ "confirmed": true }`.
+
+### 3. Contracts
+
+- Required acknowledgement status values: `not_required`, `pending`, `acknowledged`, `overdue`.
+- Employee response must not include other employees' acknowledgement rows or pending lists.
+- Admin pending list may include only `id`, `employeeNo`, `name`, and `status`; do not include phone, email, WeCom userid, account identifiers, or sensitive profile fields.
+- Acknowledgement is explicit only: opening an announcement or clicking its link must never create a receipt.
+- Policy content changes after any acknowledgement require a new announcement version; do not mutate title, summary, category, required flag, or statement in place.
+
+### 4. Validation & Error Matrix
+
+- `announcements_v1` disabled -> `409 VALID_001`.
+- policy acknowledgement without statement -> `400 VALID_001`.
+- `manage=1` without `system.settings` -> `403 PERM_001`.
+- acknowledge invisible/missing announcement -> `404 ANN_404`.
+- acknowledge normal announcement -> `409 VALID_001`.
+- acknowledge without `{ confirmed: true }` -> `400 VALID_001`.
+- edit protected policy fields after acknowledgement exists -> `409 VALID_001`.
+
+### 5. Good/Base/Bad Cases
+
+- Good: admin creates a policy announcement, employee checks the confirmation box, server creates one receipt and one audit log.
+- Base: normal announcement remains compatible and returns `not_required`.
+- Bad: frontend displays another employee's receipt status on `/announcements`.
+- Bad: admin updates an acknowledged policy title instead of creating a new version.
+
+### 6. Tests Required
+
+- Prisma validate after schema/migration changes.
+- Route focused tests for required statement, permission, idempotency, normal/invisible announcement rejection, admin summary, and protected edit rejection.
+- Frontend typecheck and build.
+- Playwright flow for admin create -> employee acknowledge -> admin summary update when UI changes.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```js
+await prisma.portalAnnouncement.update({
+  where: { id },
+  data: { title: "制度 V2" },
+});
+```
+
+#### Correct
+
+```js
+const acknowledgementCount = await prisma.portalAnnouncementAcknowledgement.count({
+  where: { announcement_id: id },
+});
+if (acknowledgementCount > 0) {
+  throw new AppError({ code: "VALID_001", message: "参数校验失败", statusCode: 409 });
+}
+```