danyang-match/docs/superpowers/plans/2026-10-14-global-public-id-implementation.md

# 全平台业务展示编号统一实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 让所有面向用户或跨角色展示的人员、任务、活动和业务记录 ID 使用 13 位稳定业务编号，并确保 Web、小程序和运营 API 的展示一致。

**Architecture:** 保留 PostgreSQL UUID 主键、外键、权限与路由寻址；为公开展示实体持久化业务编号。以 PostgreSQL 原子计数器按前缀和上海日期分配编号，在实体创建事务中写入；后端 DTO 同时提供内部 ID 与公开展示字段，前端只渲染公开字段。

**Tech Stack:** Java 21、Spring Boot、MyBatis-Plus、PostgreSQL、Flyway、Vue 3、TypeScript、微信原生小程序、Node.js 行为测试、Docker Compose。

**Spec:** `docs/superpowers/specs/2026-10-14-global-public-id-design.md`

## Global Constraints

- 公开编号严格使用 `2 位大写字母前缀 + Asia/Shanghai YYYYMMDD + 3 位序号`，共 13 位。
- 用户 `YH` 按注册日和性别分别排名，男性序号奇数、女性序号偶数；红娘 `HN`，其他工作人员 `GL`，任务 `RW`，活动 `HD`。
- UUID 主键、外键、JWT subject、数据范围、权限校验、幂等语义和既有 UUID API 路由保持不变。
- 推荐对象、被推荐人、被举报人和活动参与者统一展示用户 `YH` 编号。
- 任意用户可见页面、弹窗、导出和小程序不得渲染原始 UUID；不可用中文占位掩盖接口漏字段，必须修 DTO/查询。
- 不覆盖或回滚开始任务前工作区的任何修改；只提交本计划涉及的新改动。
- 不添加第三方依赖；后端唯一编号由 PostgreSQL 并发安全地产生。

---

## 文件结构与责任

- `backend/src/main/resources/db/migration/V060__add_global_public_display_ids.sql`：为业务实体增加公开编号列/计数器，并为现存数据确定性回填和建立唯一索引。
- `backend/src/main/java/com/danyang/match/platform/shared/id/`：编号前缀、长度、日期与原子分配服务；只新增小型领域工具，不重构 UUID 基础设施。
- 各领域 Entity、Mapper、Service、DTO：在创建事务中写入公开编号；查询以 JOIN 取关联用户/操作员的展示编号。
- `backend/src/test/java/com/danyang/match/platform/shared/id/` 与领域测试：格式、奇偶、并发、迁移、DTO 白名单和越权行为测试。
- `admin-web/src/modules/`：替换直接渲染 UUID 的列、详情、表单和导出；交互继续传内部 ID。
- `miniapp/pages/` 与 `miniapp/services/`：只显示公开编号，动作请求继续用内部 ID。
- `docs/DEMO-VALIDATION-2026-10-13.md`：追加编号回填与双端展示验收证据，不改写历史记录。

## Task 1: 建立全仓公开 ID 展示清单与锁定测试

2026-10-14 执行结果：模板/关键动态文案盘点与检查器已完成，清单见 `../specs/2026-10-14-global-public-id-display-inventory.md`。检查器 7 项自检 PASS；114 个模板发现 31 个审查候选，全局展示检查仍 FAIL。Java 响应行为覆盖测试移至 Task 3，避免仅断言源码字符串。预约 YY 前缀待用户确认后进入迁移实现。

**Files:**
- Create: `backend/src/test/java/com/danyang/match/platform/shared/id/PublicDisplayIdCoverageTest.java`
- Create: `tests/public-id-display-coverage.cjs`
- Inspect: `admin-web/src/modules/`、`miniapp/pages/`、各模块 Controller/DTO/Mapper、Flyway 迁移

- [ ] **Step 1: 建立清单和失败测试**

清单至少逐项记录：实体、UUID 列/关系、创建入口、API DTO、管理端页面、用户小程序页面、编号前缀、是否包含既有用户隐私权限。覆盖 `users`、`operators`、`activities`、`review_tasks`、`reports`、`matchmaker_services`、`matchmaker_recommendations`、`matchmaker_contact_authorizations`、`matchmaker_assignments`、`matchmaker_followups`、转介实体，以及搜索中发现的任何其他实际展示 UUID 的实体。

守卫测试扫描已登记的 Web Vue 与小程序 WXML/TS/JS 文件，拒绝把 `operatorId`、`userId`、`targetUserId`、`activityId`、`serviceId`、`recommendationId` 等内部 UUID 直接插值到可见模板；允许它们用于事件、路由和 API 参数。测试对明确的 display 字段白名单断言。

- [ ] **Step 2: 运行测试确认暴露当前差距**

Run: `node tests/public-id-display-coverage.cjs`
Expected: FAIL，报告仍直接显示 UUID 的具体文件与模板位置。

- [ ] **Step 3: 固化清单与覆盖测试**

将前置检查清单保存到 `docs/superpowers/specs/2026-10-14-global-public-id-display-inventory.md`；确认每个展示 ID 均映射到规格中已有前缀。若发现需新增前缀或改变既有 API 路由参数，暂停后续实现并修订规格等产品确认。

- [ ] **Step 4: 运行测试**

Run: `node tests/public-id-display-coverage.cjs`
Expected: 检查器自检 PASS；展示扫描在遗留问题修复前保持 FAIL，不将已知问题豁免为全局 PASS。

## Task 2: 编号分配器、字段迁移和历史回填

**Files:**
- Create: `backend/src/main/resources/db/migration/V060__add_global_public_display_ids.sql`
- Create: `backend/src/main/java/com/danyang/match/platform/shared/id/PublicDisplayId.java`
- Create: `backend/src/main/java/com/danyang/match/platform/shared/id/PublicDisplayIdAllocator.java`
- Create: `backend/src/main/java/com/danyang/match/platform/shared/id/PublicDisplayIdMapper.java`
- Modify: `backend/src/main/java/com/danyang/match/platform/user/UserDisplayNumber.java`
- Modify: 相关 entity，至少 `User.java`、`Operator.java`、`Activity.java`、审核/举报/红娘相关 entity
- Create: `backend/src/test/java/com/danyang/match/platform/shared/id/PublicDisplayIdTest.java`
- Create: `backend/src/test/java/com/danyang/match/platform/shared/id/PublicDisplayIdAllocatorTest.java`
- Modify: `backend/src/test/java/com/danyang/match/platform/deployment/MigrationValidationTest.java`
- Modify: `backend/src/test/resources/schema-h2.sql`

- [ ] **Step 1: 编写编号格式和分配器失败测试**

测试 `YH20261014001`、`YH20261014002` 的用户奇偶规则，普通记录格式 `RW20261014001`；非法前缀、日期、序号、用户性别、序号越过 999 必须拒绝。PostgreSQL mapper 测试以并发任务申请同一前缀同一天的编号，断言数量一致且全部唯一；禁止使用 `COUNT(*) + 1`。

- [ ] **Step 2: 运行定向测试确认失败**

Run: `cd backend; mvn -Dtest=PublicDisplayIdTest,PublicDisplayIdAllocatorTest test`
Expected: FAIL，因编号工具和 mapper 尚未实现。

- [ ] **Step 3: 添加持久化编号字段与回填**

新增迁移为清单内公开实体添加 `display_id`（用户沿用 `display_number`，工作人员沿用 `display_id`），建立 `public_display_id_counters(prefix, local_date, sequence_group, last_sequence)` 计数器表。迁移按 `Asia/Shanghai` 注册/创建日期及稳定次序回填：用户按实名性别分别排名并写入男奇女偶尾号；工作人员按角色决定 `HN/GL`；任务 `RW`；活动 `HD`；其余业务表按规格与覆盖清单中的前缀分表排名。回填完成后设置非空和部分唯一约束；软删除记录也保留其编号唯一性，不得复用。初始化计数器到每组已使用的最大序号。

- [ ] **Step 4: 实现原子分配器**

Mapper 使用 PostgreSQL 原子 UPSERT：普通编号按 `sequence_group=''` 每次加 1；用户编号按 `sequence_group=gender` 分别加 2，男性首值 1、女性首值 2。更新前检查生成值不超过 999；无返回值时抛明确容量异常。日期由 `Clock` 注入并按 `Asia/Shanghai` 转换。`UserDisplayNumber` 调整为接受已分配奇偶序号且支持三位尾号，避免自行计数。

- [ ] **Step 5: 运行后端定向测试与迁移验证**

Run: `cd backend; mvn -Dtest=PublicDisplayIdTest,PublicDisplayIdAllocatorTest,MigrationValidationTest test`
Expected: PASS；并发下无重复编号，迁移在空 H2 测试结构与 PostgreSQL 演示数据库验证通过。

## Task 3: 后端创建写入与展示 DTO 收口

**Files:**
- Modify: 各展示实体的 Mapper/Service/Controller/DTO，按 Task 1 清单逐项列出
- Modify: `backend/src/main/java/com/danyang/match/platform/matchmaker/mapper/MatchmakerContactAuthorizationMapper.java`
- Modify: `backend/src/main/java/com/danyang/match/platform/matchmaker/service/ContactAuthorizationService.java`
- Modify: `backend/src/main/java/com/danyang/match/platform/matchmaker/service/MatchmakerManagementService.java`
- Modify: 活动、审核、举报、审计、转介等清单中 Mapper 查询和响应 DTO
- Create: `backend/src/test/java/com/danyang/match/platform/shared/id/PublicDisplayIdResponseTest.java`
- Modify: 对应领域测试与 `backend/src/test/resources/schema-h2.sql`

- [ ] **Step 1: 为创建流程写回归测试**

对每类清单实体调用真实 Service 创建入口，断言同事务持久化 UUID 主键和正确前缀的公开编号；模拟编号分配失败，断言领域实体未写入。用户和工作人员 API 输出同时断言 `id` 仍为既有 UUID、`displayNumber/displayId` 是业务编号。

- [ ] **Step 2: 运行测试确认失败**

Run: `cd backend; mvn -Dtest=PublicDisplayIdResponseTest,MatchmakerContactAuthorizationTest,MatchmakerManagementReadTest test`
Expected: 新增编号断言失败，既有权限测试保持可执行。

- [ ] **Step 3: 接入创建事务与关联编号查询**

对每个实体创建 Service，在已有 `@Transactional` 中先分配编号再 insert；操作员编号依实际角色用 `HN/GL`。Mapper 查询只额外 JOIN 公开编号字段；DTO 增加语义明确的 `displayId`/`displayNumber` 和关联对象 `operatorDisplayId`、`userDisplayNumber`、`targetUserDisplayNumber`。contact authorization 不再把底层 `operatorId/userId` 作为展示字段使用。

推荐对象、被举报人、活动参与者和审核对象关联到 user profile 时，复用 `users.display_number`；查询必须保留现有数据范围、用户隐私白名单和防探测条件。列表只补展示字段，不扩大查询可见范围。

- [ ] **Step 4: 检查未覆盖 API 和 UUID 响应泄漏**

运行后端静态覆盖测试和针对 Controller JSON 的响应断言；确认审计记录实体引用只在有权限且可映射时返回业务编号，否则返回实体类型脱敏说明。搜索所有列表 DTO 对 UUID 的输出使用，逐项按清单修复，不修改内部写请求。

- [ ] **Step 5: 运行相关后端回归**

Run: `cd backend; mvn -Dtest=PublicDisplayId*,MatchmakerContactAuthorizationTest,MatchmakerAssignmentA1Test,MatchmakerManagementReadTest,Activity*,Review*,Report*,MigrationValidationTest test`
Expected: PASS；既有权限、事务、隐藏/软删除与错误语义不变。

## Task 4: 管理端只展示业务编号

**Files:**
- Modify: `admin-web/src/modules/matchmaker/MatchmakerManagementView.vue`
- Modify: `admin-web/src/modules/activity/ActivityInterestView.vue`
- Modify: `admin-web/src/modules/activity/ActivityCheckinView.vue`
- Modify: `admin-web/src/modules/operator/OperatorManagementView.vue`
- Modify: `admin-web/src/modules/audit/AuditLogView.vue`
- Modify: Task 1 清单识别的用户、举报、安全、审核、报名、活动、联系授权、转介等视图
- Modify: 对应 API 类型定义与 service adapter
- Modify: `tests/public-id-display-coverage.cjs`

- [ ] **Step 1: 为目标页面写展示行为测试**

使用虚拟 API fixture 分别提供 UUID 与展示编号；渲染断言应见 `HN...`、`YH...`、`HD...`、`RW...` 等展示编号且不见 UUID，点击详情/审批/筛选后请求仍携带原内部 UUID。

- [ ] **Step 2: 修复模板和交互控件**

表格/详情使用 DTO 的公开编号字段；推荐对象输入改为可搜索用户选择器，按公开用户编号和允许公开的基础资料搜索，提交时仍传选中对象内部 UUID。若缺展示编号，展示“编号待生成”并在接口测试中判为缺陷，不允许回退 UUID。

- [ ] **Step 3: 更新覆盖守卫并运行管理端检查**

Run: `cd admin-web; pnpm run type-check; pnpm run build; cd ..; node tests/public-id-display-coverage.cjs`
Expected: 类型检查、构建和 ID 展示守卫 PASS。

## Task 5: 小程序只展示业务编号

**Files:**
- Modify: Task 1 清单中用户卡片、活动详情/报名/签到、红娘工作台/服务详情/推荐进展、举报与安全、个人资料/认证等页面
- Modify: 必要的 `miniapp/services/*.js` response adapter
- Modify: `miniapp/types/index.ts` 与 `miniapp/types/index.d.ts` 的展示字段
- Create: `tests/miniapp/public_id_display_behavior_test.cjs`
- Modify: `tests/public-id-display-coverage.cjs`

- [ ] **Step 1: 写小程序字段展示失败测试**

使用接口响应 fixture 注入 `id/userId/targetUserId` UUID 和对应 `displayId/displayNumber`，断言 WXML 页面绑定展示字段、服务跳转和 Like/Pass/报名/举报动作仍提交 UUID；无展示编号时不把 UUID 作为空态回退值。

- [ ] **Step 2: 修正响应类型和页面绑定**

更新 TS 声明和各页面 WXML/JS，让列表、详情、确认弹窗、活动页面和举报确认中的公开文本只用业务编号；保留内部 ID 用于请求和路由。

- [ ] **Step 3: 运行小程序行为与结构检查**

Run: `node tests/miniapp/public_id_display_behavior_test.cjs; node tests/public-id-display-coverage.cjs; pnpm --dir miniapp run type-check`
Expected: PASS；另运行项目现有 WXML/WXSS 结构守卫和 matchmaker/活动相关测试。

## Task 6: 全量迁移、运行验收和文档证据

**Files:**
- Modify: `docs/DEMO-VALIDATION-2026-10-13.md`
- Modify: `docs/STATUS.md`
- Inspect: `infrastructure/docker-compose.yml`、运行中的 danyang Docker 服务

- [ ] **Step 1: 执行完整后端测试及迁移检查**

Run: `cd backend; mvn test`
Expected: 记录总数、失败、错误、跳过；全部失败/错误为 0。PostgreSQL 演示库迁移完成，检查每表编号无空值、无重复、长度正确，用户奇偶规则正确，计数器不小于已分配最大尾号。

- [ ] **Step 2: 执行 Web、小程序回归**

Run: `cd admin-web; pnpm run type-check; pnpm run build; cd ..; pnpm --dir miniapp run type-check; node tests/public-id-display-coverage.cjs`
Expected: 全部 PASS；执行现有小程序结构与相关行为测试。

- [ ] **Step 3: 演示环境 HTTP 和页面检查**

以演示账号读取联系授权、红娘服务/推荐、用户、活动、审核、举报接口，逐类抽查 UUID 与业务编号关系；确认权限拒绝样本仍拒绝。检查浏览器常用视图及微信开发者工具小程序核心页，页面无 UUID 可见文本，动作正常。

- [ ] **Step 4: 记录证据并完成阶段报告**

在 `docs/DEMO-VALIDATION-2026-10-13.md` 追加编号格式、各类数量、重复检测、旧号映射、测试输出摘要和目视验收结果；在 `docs/STATUS.md` 仅追加当前结论，不覆盖历史状态。运行 `git diff --check`，最终报告逐项 `PASS/PARTIAL/FAIL/NOT_VERIFIED`。

## 完成门禁

- 六个任务均有实现与独立测试证据；不得因前端隐藏列而遗漏后端公开 DTO。
- 演示 PostgreSQL 中公开编号检查 SQL 返回 0 空值（仅规格明确允许的未实名用户可空）、0 重复、0 格式错误。
- 联系授权截图展示 `HN...` 与 `YH...`；跨模块推荐、举报和活动同一用户编号相同。
- 所有 UUID 保留作内部键但不出现在面向用户的可见文本、导出或通知。
- 若既有客户端依赖公开 UUID 字段作为用户输入，应提供公开编号解析适配并做兼容测试；权限判断仍基于解析后的 UUID。
- 最终说明未执行的微信真机验收或不可执行测试，不将历史测试结果写成本轮证据。