danyang-match/docs/superpowers/plans/2026-10-19-demo-release-repair-plan.md

V1.1 演示发布修复实施计划

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: 在不依赖真实微信账号、生产证书、正式域名、真实用户 UAT 和外部备份介质的前提下，修复当前代码并形成可重复启动、可验证的 V1.1 演示版本。

Architecture: 保留现有模块化单体、Mock 微信 Provider、PostgreSQL、Redis、SeaweedFS、管理端和小程序结构。演示环境与生产环境配置分开；演示验收使用真实 HTTP、真实 PostgreSQL 和真实容器，不把 H2 或静态断言当作完整演示证据。

Tech Stack: Java 21 / Spring Boot 3 / Maven / PostgreSQL 16 / Redis 7 / SeaweedFS 4.47 / Docker Compose / Vue 3 / TypeScript / 微信原生小程序 / pytest。

Spec: AGENTS.md、README.md、docs/PHASE26-GO-LIVE-CHECKLIST.md、docs/善缘丹阳 V1.1 客户需求基线增量开发与修复计划.md。

Global Constraints

• 演示环境允许 Mock 微信登录，但必须显式使用演示 profile，不能让生产 profile 误启用 Mock。
• PostgreSQL 是 Source of Truth；演示 E2E 必须使用真实 PostgreSQL，不得以 H2 结果替代。
• 活动互选必须经过双方确认后才创建 Match；红娘权限必须由服务端分配范围控制。
• 不修改真实微信、生产证书、正式域名、真实用户 UAT、外部备份介质相关范围；这些作为正式发布前遗留项记录。
• 不清理或回滚用户现有未提交改动；发布候选树必须通过显式文件清单建立。
• 不新增依赖；优先使用已有 Maven、pnpm、npm、pytest 和 Compose 工具链。
• 每个任务完成后先跑该任务的最小测试，再进入下一任务；全量回归最后执行。

---

Task 1: 建立演示发布基线并隔离工作区变更

Files:

• Modify: docs/STATUS.md（追加本次演示修复批次状态）
• Modify: docs/REMAINING_WORK.md（把真实生产风险与演示阻塞分开）
• Create: docs/demo/DEMO-RELEASE-BASELINE-2026-10-19.md
• Inspect: git status --short、git diff --stat、VERSION、现有 release tag

Interfaces:

• Produces: 演示候选版本的文件清单、排除清单和验证命令。

• Later tasks consume: 候选版本范围，避免把 .mimosa/、.trae/、.wb_tmp_bcrypt/ 和未审查演示文件混入发布。

• Step 1: 记录当前失败基线

  记录当前命令及结果：

  git status --short
  git diff --stat
  mvn -B test -f backend/pom.xml
  pnpm --dir admin-web type-check
  pnpm --dir admin-web build
  npm --prefix miniapp run type-check
  python scripts/check-no-empty-tests.py
  

• Step 2: 建立候选文件清单

  将生产代码、测试、迁移、演示 Compose、E2E 和文档分组；明确机器临时目录、H5 演示目录和新增迁移是否纳入本批次。

• Step 3: 记录演示版接受边界

  在 DEMO-RELEASE-BASELINE-2026-10-19.md 写明：Mock 微信可用、HTTPS/正式域名不验收、演示账号不代表真实用户验收、备份只做本机可恢复性检查。

• Step 4: 验证文档不再互相矛盾

  检查 README、STATUS、REMAINING_WORK、PHASE26 清单中的演示状态一致；不得把历史全绿报告写成当前证据。

验收: 文档能准确指出当前失败项、演示范围和排除范围；不改业务代码。

---

Task 2: 修复后端当前 9 个失败门禁

Files:

• Modify: backend/src/main/java/com/danyang/match/platform/shared/config/SecurityConfig.java 或实际配置匿名路径的文件
• Modify: backend/src/main/java/com/danyang/match/platform/auth/controller/AuthController.java（仅在测试证明登录入口路径配置错误时）
• Modify: backend/src/main/java/com/danyang/match/platform/health/controller/HealthController.java（仅在映射存在但未放行时）
• Modify: backend/src/test/java/com/danyang/match/platform/auth/AuthControllerTest.java
• Modify: backend/src/test/java/com/danyang/match/platform/auth/HealthControllerTest.java
• Modify: backend/src/test/java/com/danyang/match/platform/auth/PublicMiniappApiTest.java

Interfaces:

• Produces: 未认证健康检查和公开小程序接口返回约定的 200；受保护接口仍返回 401/403。

• Preserves: Authorization: Bearer、运营端和用户端角色隔离、统一响应体格式。

• Step 1: 先定位过滤链原因

  用失败测试和 SecurityConfig 的 request matcher 对照，列出每个失败 URI、期望状态、当前 matcher。不要通过降低测试断言来消除失败。

• Step 2: 写最小回归断言

  为每个公开 URI 保留匿名 200 用例，并为一个受保护业务 URI 保留匿名 401 用例，确保放行规则没有扩大到用户数据接口。

• Step 3: 修改一次共享安全配置

  在统一的 Security matcher 中补齐健康、版本、微信登录和公开小程序资源；不在各 Controller 增加重复鉴权绕过。

• Step 4: 运行专项测试

  mvn -B -f backend/pom.xml test `
    "-Dtest=AuthControllerTest,HealthControllerTest,PublicMiniappApiTest"
  

• Step 5: 运行权限回归

  mvn -B -f backend/pom.xml test `
    "-Dtest=SecurityPathCoverageTest,OperatorEndpointPermissionCoverageTest,V11PermissionMatrixContractTest"
  

验收: 上述专项测试全绿；匿名公开接口不泄露用户数据；受保护接口仍不能匿名访问。

---

Task 3: 修复 V061 迁移与基线守卫

Files:

• Modify: backend/src/main/resources/db/migration/V061__extend_matchmaker_assistance.sql
• Modify: backend/src/test/java/com/danyang/match/platform/deployment/MigrationValidationTest.java
• Modify: backend/src/test/resources/schema-h2.sql（只有实体/测试 SQL 需要同步时才改）
• Modify: docs/database/MIGRATION_GUIDE.md

Interfaces:

• Produces: 唯一、连续、可被 Flyway 识别的 V061 迁移；测试基线与生产迁移目录一致。

• Preserves: 已部署 V001-V060，不重写历史迁移，不复用已发布版本号。

• Step 1: 用现有正则定位失败原因

  现有守卫要求 V\\d{3}__[^_]+(?:_[^_]+)*\\.sql；确认 extend_matchmaker_assistance 中的双下划线是否导致描述段不符合当前规则，并记录选择。

• Step 2: 选择兼容命名方案

  优先把文件名改为满足现有命名规则的单下划线描述；如果业务确实需要允许双下划线，则修改守卫并新增正例/负例，不能只把 LATEST_MIGRATION 改成 61。

• Step 3: 更新迁移基线说明

  在测试注释和迁移指南中登记 V061 的用途、不可重复执行要求和 matchmaker_services 新字段。

• Step 4: 做源码和构建产物双重验证

  mvn -B -f backend/pom.xml -DskipTests package
  mvn -B -f backend/pom.xml test `
    "-Dtest=MigrationValidationTest,EntityMigrationParityTest,DeploymentTests"
  

验收: V061 命名守卫通过；构建产物中无重复版本；空库 Flyway 可从头执行到 V061。

---

Task 4: 修复并验证演示 Compose

Files:

• Modify: infrastructure/docker-compose.yml
• Modify: infrastructure/docker-compose.staging.yml
• Modify: infrastructure/docker-compose.prod.yml（只修语法和清晰的演示/生产边界，不把生产风险伪装成已解决）
• Modify: infrastructure/.env.example
• Modify: infrastructure/nginx.conf
• Modify: h5-demo/（仅当容器构建或 /h5/ 路由失败时）
• Create: infrastructure/.env.demo.example（若现有 .env.example 无法表达演示必需变量）

Interfaces:

• Produces: danyang-demo 项目可独立启动，端口、容器名、健康检查和演示 Mock 配置一致。

• Preserves: 生产 Compose 使用必需变量和 secret；不把演示密码复制进生产文件。

• Step 1: 修正生产 Compose 插值语法

  把 ${MINIO_PUBLIC_ENDPOINT:http://seaweedfs:8333} 改成 Compose 合法形式 ${MINIO_PUBLIC_ENDPOINT:-http://seaweedfs:8333}，并扫描同类错误。

• Step 2: 固化演示环境变量

  演示 .env 至少提供 DB_PASSWORD、REDIS_PASSWORD、MINIO_ACCESS_KEY、MINIO_SECRET_KEY、JWT_ACCESS_SECRET、JWT_REFRESH_SECRET、ENCRYPTION_KEY 和 WECHAT_MOCK_OPENID；文件中的值只用于本机演示。

• Step 3: 隔离 Compose 项目名

  所有演示命令统一使用：

  docker compose -p danyang-demo -f infrastructure/docker-compose.yml config --quiet
  docker compose -p danyang-demo -f infrastructure/docker-compose.yml up -d --build
  

• Step 4: 验证容器健康和路由

  检查 PostgreSQL、Redis、SeaweedFS、storage-init、backend、admin-web、h5-web、nginx；验证 /api/v1/health/live、/admin/、/h5/。

• Step 5: 清理演示栈

  docker compose -p danyang-demo -f infrastructure/docker-compose.yml down
  

  仅删除演示项目容器，不使用跨项目的 --remove-orphans。

验收: 本地 Compose 解析成功；演示栈可重复启动和停止；生产 Compose 至少能在提供必需变量后解析成功。

---

Task 5: 修复演示 E2E 运行条件并完成核心闭环

Files:

• Modify: tests/e2e/conftest.py（仅修环境变量、URL 或账号种子问题）
• Modify: tests/e2e/sql/seed_e2e_operators.sql
• Modify: tests/e2e/home_v11_test.py
• Modify: tests/e2e/local_eligibility_test.py
• Modify: tests/e2e/activity_mutual_consent_test.py
• Modify: tests/e2e/service_appointment_test.py
• Modify: tests/e2e/referral_v11_test.py
• Modify: tests/e2e/service_station_permission_test.py
• Modify: tests/e2e/counseling_permission_test.py
• Modify: tests/e2e/content_e2e_test.py
• Inspect: tests/e2e/run_v11_tests.py（不得把未收集脚本算作 pytest 通过）

Interfaces:

• Produces: 面向演示栈的真实 HTTP + PostgreSQL E2E 结果。

• Preserves: 活栈不可达退出码 4；不使用 skip 伪装未执行；Mock 只替代微信登录。

• Step 1: 先验证活栈失败路径

  在未启动栈时运行 python -m pytest tests/e2e -q，确认是明确的活栈退出，而不是大量测试被跳过。

• Step 2: 启动演示栈并初始化 E2E 账号

  使用隔离 Compose 项目名；通过 SQL seed 创建 e2e_admin、e2e_platform、e2e_counselor、e2e_station、e2e_matchmaker、e2e_content，密码仅通过环境变量传入。

• Step 3: 运行 E2E

  $env:E2E_BASE_URL='http://localhost:8085/api/v1'
  $env:E2E_OPERATOR_PASSWORD='演示环境密码'
  python -m pytest tests/e2e -q
  

• Step 4: 修复真实失败根因

  按失败类型处理：登录/fixture 配置、权限范围、迁移数据、HTTP 状态码、业务状态机。禁止直接放宽断言或给测试增加 skip。

• Step 5: 验证核心跨端路径

  至少保留一条可复现证据：运营端分配红娘服务 → 用户端看到服务记录 → 用户提交服务操作 → Web 查询结果；确认服务端依据 matchmaker_assignments 判定范围。

验收: tests/e2e 在演示活栈中通过；活栈停止时套件明确失败；核心红娘跨端链路有日志和结果记录。

---

Task 6: 演示功能冒烟与前端构建收口

Files:

• Modify: infrastructure/scripts/smoke-test.sh（仅补演示端口或健康接口）
• Modify: docs/DEMO-VALIDATION-2026-10-13.md（更新为当前命令和结果）
• Modify: docs/PHASE26-GO-LIVE-CHECKLIST.md（增加演示版状态，不删除正式发布要求）
• Inspect: admin-web/src/、miniapp/、h5-demo/

Interfaces:

• Produces: 管理端、小程序静态检查、H5 演示和后端健康检查的统一演示报告。

• Preserves: 不把 CSS 警告或构建成功误报为完整 UI 验收。

• Step 1: 运行前端门禁

  pnpm --dir admin-web type-check
  pnpm --dir admin-web build
  npm --prefix miniapp run type-check
  node ui-tests/ui-document-baseline-contracts.mjs
  python scripts/check-no-empty-tests.py
  

• Step 2: 做演示端人工路径

  用浏览器验证 /admin/ 登录、首页、红娘工作台、咨询、服务站、内容管理；用微信开发者工具验证 Mock 登录、首页、推荐、活动、服务记录和退出登录。

• Step 3: 记录构建警告

  CSS url(var(--...)) 警告和大 chunk 先作为 P2 记录；只有造成页面空白、资源加载失败或路由不可用时才提升为 P0。

• Step 4: 输出演示验收报告

  报告按 PASS / PARTIAL / FAIL / NOT_VERIFIED 分类，附命令、时间、环境、失败截图或日志路径。

验收: 所有演示核心路径可操作；未通过项明确列出，不用“构建通过”替代人工路径。

---

Task 7: 演示版冻结与回归门禁

Files:

• Create: docs/demo/DEMO-RELEASE-REPORT-2026-10-19.md
• Modify: VERSION（仅在验收通过后）
• Inspect: git diff --check、git status --short、发布 tag 和 bundle

Interfaces:

• Produces: 一个干净、可追溯、可重新部署的演示版本。

• Preserves: 不宣称正式生产发布；正式风险继续列在独立的 release blocker 区域。

• Step 1: 执行全量回归

  mvn -B -f backend/pom.xml test
  pnpm --dir admin-web type-check
  pnpm --dir admin-web build
  npm --prefix miniapp run type-check
  python -m pytest tests/e2e -q
  docker compose -p danyang-demo -f infrastructure/docker-compose.yml config --quiet
  git diff --check
  

• Step 2: 检查发布候选树

  只允许本次修复和必要测试/文档进入候选树；临时目录、密码、token、数据库 dump 不得进入。

• Step 3: 生成演示 tag 和 bundle

  git tag demo-v1.1.0-20261019 <release-commit>
  git bundle create demo-v1.1.0-20261019.bundle demo-v1.1.0-20261019
  git show demo-v1.1.0-20261019 --stat
  

• Step 4: 回读验证 tag 和 bundle

  git tag --verify demo-v1.1.0-20261019
  git bundle verify demo-v1.1.0-20261019.bundle
  git status --short
  

验收: 全量门禁满足演示版标准；tag、bundle、报告三者指向同一提交；工作区没有未解释的发布变更。

---

依赖关系

Task 1
  ↓
Task 2 ──┐
Task 3 ──┼─> Task 4 ─> Task 5 ─> Task 6 ─> Task 7
         ┘

演示版最终门禁

• PASS: 后端全量测试 0 failure / 0 error。
• PASS: 演示 Compose 解析、启动、健康检查、停止均成功。
• PASS: E2E 使用真实 PostgreSQL，核心场景通过，未使用 skip 伪绿。
• PASS: Admin 类型检查和构建、小程序类型检查、UI 契约守卫通过。
• PASS: Mock 微信登录只在演示 profile 生效。
• PASS: 演示账号、密钥和数据库数据均与生产隔离。
• NOT_VERIFIED（允许保留）: 真实微信、生产证书、正式域名、真实用户 UAT、外部备份介质。

本计划明确跳过的内容

本批次不接入真实微信、不申请或验证生产证书、不配置正式域名、不进行真实用户验收、不验证外部备份介质恢复，也不借此宣称正式生产可发布。