docs: define reference-driven dual-client UI redesign

docs/superpowers/specs/2026-09-13-reference-driven-dual-client-ui-redesign-design.md

@@ -0,0 +1,356 @@
+# 善缘丹阳 V1.1 双端参考图驱动 UI 重设计规格
+
+日期：2026-09-13
+
+状态：待用户书面复核
+
+适用范围：管理端全局框架与工作台；小程序首批 11 个核心页面；旧 UI 代码与冲突文档治理
+
+## 1. 目标
+
+以用户确认的两张参考图为唯一视觉基准，在不改变现有业务接口、权限边界和核心业务不变量的前提下：
+
+1. 安全清理管理端和小程序端冗余、无用、废弃的旧 UI 代码；
+2. 清理或修订与本规格冲突的设计、规范、计划、进度和验收文档；
+3. 第一批严格重构管理端全局框架与工作台；
+4. 第一批严格重构小程序 11 个核心页面；
+5. 建立后续页面必须复用的单一设计基线和视觉验收门禁。
+
+## 2. 唯一视觉来源与优先级
+
+### 2.1 参考图
+
+- 管理端：`ChatGPT Image 2026年9月11日 10_34_34 (1).png`
+- 小程序端：`ChatGPT Image 2026年9月11日 12_46_40.png`
+
+参考图决定色彩关系、布局层级、卡片形态、信息密度、图片风格、图标语言和整体氛围。
+
+### 2.2 冲突裁决
+
+后续 UI 开发按以下顺序裁决：
+
+1. 用户最新明确指令；
+2. 本规格及上述两张参考图；
+3. `AGENTS.md` 中仍有效的产品红线、权限规则和业务不变量；
+4. 页面功能、API、数据库和业务流程文档中的非视觉契约；
+5. 当前代码行为。
+
+任何旧文档中的暖白小程序首页、浅色管理侧栏、通用 Element Plus 后台、旧 Phase 07 视觉验收结论、全量 63/64 页一次性重构要求，均不得覆盖本规格。
+
+## 3. 已确认范围
+
+### 3.1 管理端第一批
+
+- 页面外层公益主题背景；
+- 中央大圆角管理系统容器；
+- 深灰蓝侧栏与权限菜单；
+- 顶部搜索、通知和管理员区域；
+- 工作台欢迎区；
+- 六项指标卡；
+- 今日待办事项；
+- 近期公益活动；
+- 服务数据概览；
+- 项目服务成效；
+- `1366×768` 与 `1920×1080` 响应式适配。
+
+管理端其他业务页面本批次不进行逐页高保真重构，但必须继续在新框架中可用，且不得破坏路由、权限和操作流程。
+
+### 3.2 小程序第一批
+
+1. 首页；
+2. 找对象；
+3. 消息；
+4. 公益活动；
+5. 我的；
+6. 公益红娘；
+7. 婚恋咨询；
+8. 婚前辅导；
+9. 婚恋课堂；
+10. 婚恋反诈；
+11. 善缘服务站。
+
+其余页面不在第一批逐屏重构范围内，只处理会阻塞编译、路由或公共主题迁移的问题。
+
+### 3.3 首页入口裁决
+
+参考图首页展示 4 个快捷入口，但正式业务要求 8 个固定入口。用户已确认采用两行四列，并保持以下顺序：
+
+第一行：找对象、公益红娘、公益活动、婚恋咨询。
+
+第二行：婚恋课堂、婚前辅导、婚恋反诈、善缘服务站。
+
+## 4. 非目标
+
+- 不重写后端、数据库或 API；
+- 不改变现有角色、权限与 DataScope；
+- 不迁移 Vue 3、Element Plus 或微信原生小程序技术栈；
+- 不在第一批重构管理端所有业务页面；
+- 不在第一批重构小程序其余约 53 个页面；
+- 不增加付费、会员、外链 Banner 或参考图之外的新业务；
+- 不用虚构数据冒充接口成功；
+- 不以整目录覆盖、强制回滚或无引用证据的批量删除完成清理。
+
+## 5. 核心业务不变量
+
+视觉重构不得改变以下行为：
+
+- 用户永久免费；
+- Required 条件不可自动放宽；
+- Mutual Match 后才能聊天；
+- Block 双向优先于推荐、搜索、互动与聊天；
+- 红娘只能辅助推荐，不能替用户 Like；
+- 活动单向意向保密；
+- 活动互选必须经过双方分别确认后才能创建或复用 Match；
+- Counselor 只能访问 Assigned Service；
+- Content Editor 不得访问用户婚恋数据；
+- Service Station Operator 不得浏览全用户库；
+- 用户端入口由服务端 Capability 决定；
+- 敏感数据权限和审计逻辑保持不变。
+
+## 6. 旧代码清理设计
+
+### 6.1 清理分类
+
+所有候选文件必须进入以下一种状态：
+
+- `KEEP`：仍被运行时、构建、路由或业务流程使用；
+- `REFACTOR`：仍有效，但需迁入新设计系统；
+- `DELETE`：能够证明无引用、已被替代或属于失败视觉实现；
+- `REVIEW`：证据不足，暂不删除。
+
+### 6.2 清理顺序
+
+1. 建立路由、页面、组件、样式、素材和脚本引用图；
+2. 处理同名 `.ts/.js` 页面漂移，确认 TypeScript 是唯一手写源；
+3. 删除无路由、无配置、无 import 或无模板引用的页面与组件；
+4. 删除被新设计系统完全替代的局部样式和主题变量；
+5. 删除无引用图片、图标、字体、截图和临时预览产物；
+6. 每一批删除后立即执行对应静态检查、构建和页面启动验证。
+
+### 6.3 删除门禁
+
+删除必须同时满足：
+
+- 已完成全文引用、路由配置、组件注册和构建入口检查；
+- 替代实现覆盖原有有效行为；
+- 删除后构建与核心页面检查不退化；
+- Git 能单独展示删除范围并可恢复；
+- 不包含用户未授权清理的后端业务、数据库迁移或运维数据。
+
+## 7. 文档治理与防偏航设计
+
+### 7.1 单一事实源
+
+完成文档治理后：
+
+- `AGENTS.md` 必须将本规格列为唯一有效 UI 视觉基线；
+- `docs/STATUS.md` 只记录当前可验证状态；
+- `docs/JIRA_BACKLOG.md` 的 UI 任务状态与本轮实际验收一致；
+- 后续实现计划只能引用本规格，不能引用旧 UI 计划；
+- 文档中的“已完成”不能替代构建、截图和人工视觉验收。
+
+### 7.2 直接删除的冲突文档
+
+以下文件属于已被本规格替代的旧 UI 方向或执行计划，实施清理时直接删除，由 Git 历史保留追溯能力：
+
+- `docs/superpowers/specs/2026-09-10-ui-v11-fidelity-design.md`
+- `docs/superpowers/specs/2026-09-11-codex-baseline-cleanup-design.md`
+- `docs/superpowers/specs/2026-09-11-dual-client-full-ui-redesign-design.md`
+- `docs/superpowers/plans/2026-09-10-ui-v11-fidelity.md`
+- `docs/superpowers/plans/2026-09-11-codex-baseline-cleanup.md`
+- `docs/superpowers/plans/2026-09-11-admin-full-ui-redesign.md`
+- `docs/superpowers/plans/2026-09-11-miniapp-full-ui-redesign.md`
+- `docs/superpowers/plans/2026-09-11-ui-foundation-and-pilot.md`
+- `docs/UI-V11-Visual-Acceptance-2026-09-10.md`
+- 根目录 `design-qa.md`
+
+旧 Phase 07 对比截图和被否决的验收产物同步删除，不能继续作为视觉正确性的证据：
+
+- `artifacts/phase07-miniapp-home.png`
+- `artifacts/phase07-miniapp-discover.png`
+- `artifacts/phase07-home-comparison.png`
+- `artifacts/phase07-discover-comparison.png`
+
+### 7.3 修订而非删除的文档
+
+以下文件包含仍有效的业务或审计信息，必须修订，不能简单删除：
+
+- `AGENTS.md`：替换旧 UI 文档入口，写入本规格优先级和首批范围；
+- `docs/STATUS.md`：将旧 Phase 07 视觉结果改为“已否决，待重新实现”；
+- `docs/JIRA_BACKLOG.md`：重新打开对应 UI 任务，并拆分管理端第一批与小程序 11 页；
+- `docs/Phase-07-V11-Recovery-Completion-Report-2026-09-13.md`：保留业务测试证据，但明确视觉验收结论已失效；
+- `docs/UI_REDESIGN_PAGE_MATRIX_V1.1.md`：缩减为当前第一批范围，其他页面标为后续批次；
+- `docs/善缘丹阳 V1.1 客户需求基线增量开发与修复计划.md`：更新 UI 阶段入口，不保留“旧 Phase 07 视觉已完成”的表述；
+- `docs/善缘丹阳 V1.1 当前进度校正与严格Phase修复计划.md`：同步当前暂停点与新 UI 重构门禁。
+
+### 7.4 旧高保真规范处理
+
+`docs/善缘丹阳 V1.1 前端 UI-UX 高保真原型修订说明.md` 含有大量旧视觉处方，继续保留为活动规范会造成偏航。执行时必须：
+
+1. 将仍有效的业务状态、权限、页面流程和可访问性要求迁移到对应业务文档或本规格；
+2. 完成迁移核对后删除该旧高保真文件；
+3. 在 `AGENTS.md` 中移除对它的正式基线引用；
+4. 不创建带同等权威但内容重复的新旧双份规范。
+
+其他需求、API、数据库、安全和运维文档只清理与本轮视觉结论直接冲突的段落，不得因 UI 重构删除有效业务契约。
+
+### 7.5 文档验收门禁
+
+- `rg` 搜索旧规格文件名时，只允许在删除记录或新规格的治理清单中出现；
+- 有效文档不得再把旧 Phase 07 截图标记为 passed；
+- 有效 UI 计划不得再要求一次性改造全部 63/64 页；
+- `AGENTS.md`、`STATUS.md`、`JIRA_BACKLOG.md` 与本规格的范围、优先级和状态一致；
+- 所有活动 Markdown 文件必须为 UTF-8 且中文可正常读取。
+
+## 8. 管理端设计
+
+### 8.1 视觉语言
+
+- 外层为浅粉公益主题背景，包含低对比丹阳城市、塔、桥、爱心和人物剪影；
+- 主系统为居中的暖白大圆角容器；
+- 侧栏使用深灰蓝，当前菜单使用珊瑚红渐变或同色高亮；
+- 内容卡片使用暖白底、细边框、柔和阴影和统一圆角；
+- KPI 状态色使用低饱和粉、橙、蓝、绿、紫；
+- 字体使用本地系统中文字体栈，不依赖境外字体或运行时 CDN。
+
+### 8.2 信息架构
+
+侧栏按参考图保持一层清晰入口，并继续由权限控制可见性：工作台、用户管理、资料审核、匹配管理、公益红娘、公益咨询、活动管理、内容管理、善缘服务站、举报风控、数据统计、组织人员、系统设置。
+
+同一业务域存在多个现有路由时，可在进入模块后使用页面内标签或二级导航承载，不删除功能。
+
+### 8.3 工作台
+
+工作台必须呈现：欢迎信息、六项核心指标、今日待办、近期公益活动、服务数据概览和项目服务成效。所有数字来自现有 API；无数据时显示正式空状态，不使用参考图中的演示数字。
+
+### 8.4 响应式
+
+- `1920×1080`：完整展示背景氛围与工作台两列布局；
+- `1366×768`：保证侧栏、六项指标和首屏核心待办可读；
+- 窄于管理端支持宽度时允许侧栏收起和内容纵向重排，不采用整体缩放。
+
+## 9. 小程序设计
+
+### 9.1 全局视觉
+
+- 深靛蓝与紫色夜景作为顶部和品牌氛围；
+- 珊瑚粉用于主操作、当前 Tab、未读和重点提示；
+- 内容区使用白色或浅色卡片，正文保持高对比；
+- 图片、Logo、头像、活动封面和服务站封面使用正式本地资源或真实业务数据；
+- 不使用 Emoji、字符图标、CSS 拼图或临时占位图冒充正式资产；
+- 适配微信胶囊按钮、状态栏和底部安全区。
+
+### 9.2 底部导航
+
+固定为：首页、找对象、消息、活动、我的。五项均提供统一的普通态和选中态图标，不改变现有 Tab 路由语义。
+
+### 9.3 十一个页面
+
+- 首页：品牌状态、夜景 Banner、8 入口、今日推荐、公益服务、近期活动、服务站、课堂和安全提醒；
+- 找对象：顶部搜索与筛选、人物卡片、认证和兴趣信息、真实推荐状态；
+- 消息：新朋友、互动喜欢、我的关注、系统通知和会话列表；
+- 公益活动：分类、日历、活动大图卡、人数和报名状态；
+- 我的：个人摘要、统计、公益身份卡、红娘/咨询/活动/预约/设置入口；
+- 公益红娘：公益服务说明、申请、进度、红娘与服务记录；
+- 婚恋咨询：分类、预约、服务说明、预约记录与授权状态；
+- 婚前辅导：沟通、责任、财务、冲突等主题与预约状态；
+- 婚恋课堂：分类、内容列表、封面、发布时间与加载状态；
+- 婚恋反诈：风险类型、安全提醒、举报与求助入口；
+- 善缘服务站：站点封面、地址、电话、开放时间、服务项目、定位与预约。
+
+## 10. 状态、数据与错误处理
+
+所有页面必须使用真实接口或现有开发态数据适配层，并具备：
+
+- 加载与骨架状态；
+- 空数据状态；
+- 网络失败与重试；
+- 未登录引导；
+- 无权限与 Capability 禁用原因；
+- 提交中、成功和失败反馈；
+- Block、Unmatch、审核中、服务不可用等业务状态。
+
+视觉层只消费后端权限和关系事实，不在前端自行推导或修改事实。
+
+## 11. 实施阶段与门禁
+
+### Stage 0：可恢复基线
+
+记录 Git 状态，运行双端现有检查，建立代码和文档引用清单。
+
+门禁：基线报告完整，用户改动与本轮候选清理项可区分。
+
+### Stage 1：旧代码与冲突文档清理
+
+按第 6、7 章执行，先列清单，再分批删除或修订。
+
+门禁：构建不退化；有效文档只剩一个视觉事实源；输出清理报告后暂停等待用户确认。
+
+### Stage 2：双端设计基础
+
+建立管理端与小程序端 Token、基础组件、图标与正式素材。
+
+门禁：组件状态齐全，无境外运行时依赖，用户确认视觉样板。
+
+### Stage 3：管理端第一批
+
+依次实现全局框架、侧栏、顶部栏和工作台。
+
+门禁：两种目标分辨率截图通过人工验收，权限和路由回归通过。
+
+### Stage 4：小程序公共框架
+
+实现全局主题、五项 Tab、安全区、公共卡片和状态组件。
+
+门禁：五项 Tab 可达，八个入口顺序与 Capability 行为正确。
+
+### Stage 5：小程序 11 页
+
+- A 组：首页、找对象、消息、活动、我的；
+- B 组：公益红娘、婚恋咨询、婚前辅导；
+- C 组：婚恋课堂、婚恋反诈、善缘服务站。
+
+每组完成真实数据映射、状态处理、交互检查、截图对比和回归测试，验收后再进入下一组。
+
+### Stage 6：最终验收
+
+完成双端截图矩阵、功能回归、静态检查、构建和受影响后端测试。
+
+门禁：无旧主题混用、无无响应入口、无业务不变量回归，并输出剩余差异说明。
+
+## 12. 测试与验收
+
+### 12.1 管理端
+
+- TypeScript 类型检查；
+- Vite 生产构建；
+- 路由与权限菜单检查；
+- 搜索、通知、管理员菜单和退出登录检查；
+- `1366×768`、`1920×1080` 实际页面截图；
+- 工作台与参考图并排视觉检查。
+
+### 12.2 小程序
+
+- 项目现有 TypeScript 和静态契约检查；
+- 微信开发者工具编译；
+- 五项 Tab、八入口和 11 页主要操作检查；
+- 常见设备宽度和安全区截图；
+- 未登录、空数据、网络失败、无权限、Block 等状态检查；
+- 每个页面与参考图对应区域并排视觉检查。
+
+### 12.3 后端
+
+执行受影响的首页聚合、权限、推荐、关系、消息、活动、咨询和服务站测试。Docker 仅用于联调，不删除或重建现有数据库卷。
+
+## 13. 完成定义
+
+只有同时满足以下条件，第一批重设计才完成：
+
+1. 管理端框架与工作台达到参考图的视觉语言和信息密度；
+2. 小程序 11 页达到参考图的统一紫蓝粉视觉语言；
+3. 首页保留固定 8 入口与正式模块顺序；
+4. 当前代码和有效文档中不存在会把开发引回旧视觉的入口；
+5. 所有主要入口有真实交互反馈；
+6. 业务不变量和权限边界无回归；
+7. 双端构建、检查和受影响测试通过；
+8. 用户完成最终截图验收。