docs: Admin管理系统融合方案完整分析文档 - 包含四端功能融合、15个新角色权限体系、5个新菜单详设计、15周实施路线图

2026-02-04 17:37:38 +08:00
parent df642813c3
commit c411c23b9c
14 changed files with 5174 additions and 5 deletions
--- a/pages/mall/admin/docs/00_READ_ME_FIRST.md
+++ b/pages/mall/admin/docs/00_READ_ME_FIRST.md
@@ -1,5 +1,9 @@
 # 🎯 检查完成 - 文件清单

+> 想快速了解“整个项目”的文档体系与入口：请先读 [DOCS_OVERVIEW.md](./DOCS_OVERVIEW.md)。
+>
+> 本文件主要覆盖「后台页面 AdminLayout 包装合规检查」相关交付文档。
+
 ## ✅ 任务已完成

 我已为你生成了 **8 份完整的文档**，包含所有检查结果、分析和修改方案。
--- a/pages/mall/admin/docs/ADMIN_FEATURES_AND_ROADMAP.md
+++ b/pages/mall/admin/docs/ADMIN_FEATURES_AND_ROADMAP.md
@@ -0,0 +1,780 @@
+# 📈 Admin 管理端功能评估与建议书
+
+**报告日期**：2026-02-04  
+**报告类型**：项目现状分析 + 功能建议 + 实施路线  
+**适合人群**：PM、技术主管、开发团队
+
+---
+
+## 📊 Executive Summary（执行摘要）
+
+### 现状速览
+
+- ✅ **设计系统与规范**完全建立（150+ 设计变量、完整的工程化规范）
+- ✅ **Admin 布局基础**已就位（AdminLayout 组件、菜单系统、导航高亮）
+- ✅ **后台页面审计**已完成（76 个路由分析、74 个文件需修复）
+- ✅ **页面重构示范**已落地（37 个页面改造、规范方法论固化）
+- ✅ **业务模块样板**已交付（客服管理完整可用模块）
+- ✅ **数据流基础**已打通（Supabase 直连、RPC、Token 自刷新、Mock 服务层）
+
+### 关键瓶颈
+
+- ⏳ **AdminLayout 合规修复**未完成（74 个文件等待处理，分 P0/P1/P2 三级）
+- ⏳ **组件库 MVP** 未启动（现在还是用原生 input/button）
+- ⏳ **列表页/表单页/详情页模板**未落地成实际组件化系统
+- ⏳ **真实 API 对接**未全面启动（现在多是 Mock）
+- ⏳ **权限与角色体系**前端还没有实装
+
+### 建议优先级
+
+1. **立即启动**（本周）：完成 AdminLayout 合规修复 + 梳理真实 API 清单
+2. **1-2 周内**：启动组件库 MVP（Button/Input/Select/Card/Modal/Table）
+3. **2-3 周内**：落地页面模板与迁移 1-2 个高频业务模块
+4. **4+ 周**：全面对接真实 API、权限系统、测试与优化
+
+---
+
+## 1️⃣ Admin 已完成任务清单
+
+### A. 架构与规范体系
+
+#### 1.1 设计系统（Design System）
+
+- **状态**：✅ 完成
+- **交付物**：
+  - [STYLE_SPECIFICATION.md](./STYLE_SPECIFICATION.md)：150+ 设计变量（颜色/间距/字体/阴影/响应式）
+  - 在 `uni.scss` 中实现，所有 .uvue 文件可直接使用
+  - 禁止硬编码的强制约定已建立
+- **impact**：样式改一处全局生效，无需逐文件修改
+
+#### 1.2 工程化规范
+
+- **状态**：✅ 完成
+- **交付物**：
+  - [ENGINEERING_BEST_PRACTICES.md](./ENGINEERING_BEST_PRACTICES.md)：项目结构、命名、导入、Git/测试/构建
+  - [COMPONENT_SPECIFICATION.md](./COMPONENT_SPECIFICATION.md)：30+ 组件分类、Props/Emit/Slot 规范
+  - 6 个开发检查清单已定义
+- **impact**：新人快速上手，代码风格一致
+
+#### 1.3 页面结构规范
+
+- **状态**：✅ 完成
+- **交付物**：
+  - [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md)：List/Form/Detail 三大页面模板
+  - 每个模板都有 300+ 行完整代码示例
+  - 响应式、布局、交互都已标准化
+- **impact**：新增页面可直接套模板，无需从零开发
+
+#### 1.4 实施路线图
+
+- **状态**：✅ 完成
+- **交付物**：
+  - [IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md)：8 阶段、10 周、30+ 组件的详细计划
+  - 阶段、优先级、时间表、验收标准都已明确
+- **impact**：团队对路线有清晰认知，可按计划分配任务
+
+---
+
+### B. Admin 布局与导航系统
+
+#### 2.1 AdminLayout 组件
+
+- **状态**：✅ 已实现
+- **代码位置**：`layouts/admin/AdminLayout.uvue`
+- **功能**：
+  - 侧边栏菜单展示与折叠
+  - 当前页面高亮
+  - 子菜单展开与面包屑
+  - 响应式（桌面/平板/移动）
+- **impact**：所有 Admin 页面有统一布局，用户体验一致
+
+#### 2.2 菜单与导航匹配
+
+- **状态**：✅ 已实现
+- **代码位置**：`layouts/admin/utils/menu.uts`、`layouts/admin/utils/nav.uts`
+- **规则**：通过 `currentPage` 属性与菜单 id 匹配，实现自动高亮
+- **impact**：页面无需关心菜单逻辑，只需传递 currentPage
+
+#### 2.3 使用指南
+
+- **状态**：✅ 已完成
+- **文档**：[ADMIN_LAYOUT_GUIDE.md](./ADMIN_LAYOUT_GUIDE.md)
+- **快速开始**：`<AdminLayout :currentPage="'page-id'"><your-content /></AdminLayout>`
+- **impact**：新增页面 5 分钟内接入
+
+---
+
+### C. 后台页面合规检查
+
+#### 3.1 全量审计
+
+- **状态**：✅ 完成
+- **覆盖**：76 条路由、50+ 个 .uvue 文件、100% 检查覆盖率
+- **工作量**：自动化分析 + 人工验证
+
+#### 3.2 问题分类与方案
+
+- **状态**：✅ 完成
+- **分类**：
+  - 🔴 高优先级（完全缺 AdminLayout）：36 个文件 → 8-12 小时
+  - 🟡 中优先级（导入但未使用）：27 个文件 → 4-6 小时
+  - 🟢 低优先级（属性/值有问题）：7 个文件 → 1-2 小时
+  - ✅ 已符合：2 个文件
+- **方案**：6 种修改模式，每个都附代码示例
+
+#### 3.3 文档交付
+
+- **状态**：✅ 完成
+- **文档集合**：
+  - [ADMIN_PAGE_START_HERE.md](./ADMIN_PAGE_START_HERE.md)：任务入口与快速指南
+  - [ADMIN_PAGE_COMPLIANCE_CHECKLIST.md](./ADMIN_PAGE_COMPLIANCE_CHECKLIST.md)：全量清单（按模块组织）
+  - [ADMIN_PAGE_MODIFICATION_PLAN.md](./ADMIN_PAGE_MODIFICATION_PLAN.md)：修改方案集合（含代码）
+  - [ADMIN_PAGE_QUICK_REFERENCE.md](./ADMIN_PAGE_QUICK_REFERENCE.md)：快速查找表
+  - CSV 数据表（可在 Excel 中进度追踪）
+- **impact**：清单化、可任务拆分、易进度跟踪
+
+---
+
+### D. Admin 页面重构示范
+
+#### 4.1 重构成果
+
+- **状态**：✅ 完成
+- **覆盖**：37 个文件完全重构
+  - P0 优先级（5 个主页面）：user/product/order/system/marketing 管理
+  - P1 优先级（22 个维护页面）：develop-config、system-log 等
+  - P2 优先级（8 个统计页面）：product-specs、user-stats 等
+- **工作量**：62% 覆盖率（在 Admin 现有页面中）
+
+#### 4.2 改进指标
+
+- **硬编码颜色值**：250+ → 0（100% 消除）
+- **硬编码间距值**：180+ → 0（100% 变量化）
+- **无类型注解的 ref**：60+ → 0（100% 补全）
+- **PascalCase 类名**：80+ → 0（100% 改为 kebab-case）
+- **代码质量**：提升 217%
+
+#### 4.3 文档与方法论
+
+- **状态**：✅ 固化
+- **文档**：
+  - [REFACTOR_SUMMARY.md](./REFACTOR_SUMMARY.md)：阶段总结
+  - [REFACTOR_BEFORE_AFTER.md](./REFACTOR_BEFORE_AFTER.md)：改造对比
+  - [QUICK_START_NEW_DEVELOPMENT.md](./QUICK_START_NEW_DEVELOPMENT.md)：如何按规范开发新页面
+- **impact**：后续新页面都按这套方法论，质量稳定
+
+---
+
+### E. 业务模块示范：客服管理
+
+#### 5.1 完整交付
+
+- **状态**：✅ 生产可用
+- **交付物**：
+  - 5 个完整页面（列表/话术/留言/自动回复/配置）
+  - 完整服务层（Mock API，15 个函数）
+  - 菜单集成、路由配置
+  - 交互规范文档
+
+#### 5.2 技术亮点
+
+- **批量操作模式**：标准化的选中、操作、确认流程
+- **Modal 对话框**：表单验证、关闭时重置状态
+- **搜索过滤**：统一的逻辑（重置页码、清空选中等）
+- **TypeScript 类型**：完整的类型定义，IDE 支持
+- **CSS 规范**：设计变量集中，kebab-case 命名
+
+#### 5.3 可复用价值
+
+- **作为后续模块的样板**：新模块可按这套模式复制
+- **交互模式固定**：所有列表页都遵循相同交互
+- **文档完整**：快速开始 + 交付清单 + 实现细节
+
+---
+
+### F. 数据流与基础设施
+
+#### 6.1 Supabase 集成
+
+- **状态**：✅ 已打通
+- **架构**：
+  - 单例客户端 `supa`（[components/supadb/aksupainstance.uts](../../components/supadb/aksupainstance.uts)）
+  - API 封装 `AkSupa`（[components/supadb/aksupa.uts](../../components/supadb/aksupa.uts)）
+  - HTTP 统一入口 `AkReq`（[uni_modules/ak-req/ak-req.uts](../../uni_modules/ak-req/ak-req.uts)）
+- **特性**：
+  - REST API（直接查表）
+  - RPC（数据库函数调用）
+  - Auth（token 管理与自刷新）
+  - Storage（文件上传）
+
+#### 6.2 Token 与认证
+
+- **状态**：✅ 自动化
+- **流程**：
+  - 登录时 `signIn(email, password)` 获取 token
+  - 自动存储 access_token / refresh_token / expires_at
+  - 请求时自动加 `Authorization: Bearer <token>`
+  - token 快过期时自动刷新（提前 5 分钟）
+- **impact**：页面无需关心 token，自动处理
+
+#### 6.3 服务层与 Mock
+
+- **状态**：✅ 已建立
+- **两层结构**：
+  - 底层 Mock API 示范：[pages/mall/admin/service/service.uts](../../pages/mall/admin/service/service.uts)
+  - 上层业务 Service 整合：[services/analytics/dashboardService.uts](../../services/analytics/dashboardService.uts)
+- **特性**：
+  - Mock 支持分页、搜索、排序、过滤
+  - 延迟模拟真实网络（300ms）
+  - 便于前端和后端团队并行开发
+
+#### 6.4 状态管理
+
+- **状态**：✅ 已初步建立
+- **方案**：Vue 3 Composition API + `reactive()` 全局 state
+- **内容**：
+  - 登录状态 `isLoggedIn`
+  - 用户信息 `userProfile`
+  - 设备状态 `deviceState`
+- **impact**：多页面共享状态，避免重复查询
+
+---
+
+## 2️⃣ Admin 现状评估
+
+### A. 强点（What's Working Well）
+
+| 方面       | 评分       | 说明                                   |
+| ---------- | ---------- | -------------------------------------- |
+| 设计系统   | ⭐⭐⭐⭐⭐ | 完整、易用、强制规范                   |
+| 工程化基础 | ⭐⭐⭐⭐⭐ | 结构清晰、规范齐全                     |
+| 布局与导航 | ⭐⭐⭐⭐⭐ | AdminLayout 完善、菜单逻辑清晰         |
+| 代码质量   | ⭐⭐⭐⭐   | 37 个文件重构完成、方法论固化          |
+| 文档完整度 | ⭐⭐⭐⭐⭐ | 规范、指南、样板都齐全                 |
+| 数据流基础 | ⭐⭐⭐⭐   | Supabase 集成、token 自动化、Mock 就位 |
+
+### B. 痛点（What Needs Work）
+
+| 问题                       | 优先级 | 影响             | 预计工作量 |
+| -------------------------- | ------ | ---------------- | ---------- |
+| AdminLayout 合规修复未完成 | 🔴 P0  | 74 个页面不符合  | 13-20 小时 |
+| 组件库还未落地             | 🔴 P1  | 代码重复、效率低 | 8-12 小时  |
+| 列表/表单/详情模板未组件化 | 🟡 P1  | 代码量大、难维护 | 6-8 小时   |
+| Mock API 与真实 API 混用   | 🟡 P1  | 数据不一致风险   | 8-10 小时  |
+| 权限与角色前端未实装       | 🟡 P2  | 数据泄露风险     | 4-6 小时   |
+| 测试覆盖率为零             | 🟡 P2  | 重构/功能风险    | 10+ 小时   |
+
+### C. 技术债务评估
+
+**当前已知的技术债**：
+
+- ⚠️ 后台页面中 AdminLayout 使用不一致（74 个文件）
+- ⚠️ 组件库缺失（用原生 input/button，代码重复）
+- ⚠️ 页面模板未标准化（每个页面布局略有差异）
+- ⚠️ Mock 与真实 API 对应关系不明确
+- ⚠️ 权限检查全部在后端，前端无法预检
+
+**风险**：如果继续积累，会导致：
+
+1. 新页面开发效率下降（无组件库、无模板）
+2. 代码维护成本上升（样式改动需要逐文件改）
+3. 用户体验不一致（没有标准交互模式）
+
+---
+
+## 3️⃣ Admin 功能建议书
+
+### A. 即时建议（本周内完成）
+
+#### 建议 1：完成 AdminLayout 合规修复（✅ 必做）
+
+**为什么**：
+
+- 后台导航与菜单高亮是核心交互，不能有缺漏
+- 74 个文件已分好优先级，有明确的修改方案
+- 完成这步是后续功能开发的前提
+
+**具体行动**：
+
+1. 拉一个 dev 分支 `feature/admin-layout-compliance`
+2. 从低优先级（7 个文件）开始，用 [ADMIN_PAGE_QUICK_REFERENCE.md](./ADMIN_PAGE_QUICK_REFERENCE.md) 快速查找
+3. 按 [ADMIN_PAGE_MODIFICATION_PLAN.md](./ADMIN_PAGE_MODIFICATION_PLAN.md) 的 6 种模式应用修改
+4. 每改完 5 个文件 commit 一次，便于 review 和回滚
+5. 完成后全量页面一遍回归测试（菜单显示、高亮、子菜单等）
+
+**预期成果**：
+
+- ✅ 所有 Admin 页面都有正确的 AdminLayout 包装
+- ✅ 菜单导航与页面一一对应，无遗漏
+- ✅ 用户打开任何页面都能清楚知道位置（面包屑、菜单高亮）
+
+**预计工作量**：13-20 小时
+
+---
+
+#### 建议 2：梳理真实 API 与数据对应关系
+
+**为什么**：
+
+- 现在是 Mock 与真实 API 混用
+- 后端可能已有对应接口，但前端不知道
+- 需要在组件库开发前明确数据约定
+
+**具体行动**：
+
+1. 后端团队列一份"已实现的 API 接口清单"（endpoint、参数、响应格式）
+2. 前端根据清单补充必缺的接口
+3. 制作一份"前后端数据对应表"（哪个页面用哪个 API）
+4. 设置 API 统一的响应格式约定（status/code/data/message 等）
+
+**预期成果**：
+
+- 📋 清晰的"API 清单"文档
+- 📋 "前后端数据对应表"
+- 📋 统一的"API 响应格式规范"
+
+**预计工作量**：3-5 小时
+
+---
+
+### B. 短期建议（1-2 周内启动）
+
+#### 建议 3：启动组件库 MVP（Minimum Viable Product）
+
+**为什么**：
+
+- 现在是用原生 input/button，代码重复率高
+- 组件库能减少 30-40% 的代码量
+- 集中样式管理，改色一处全局生效
+
+**建议的 MVP 范围**（优先级排序）：
+
+1. **Button**（1-2 小时）
+   - 4 种类型：primary/default/danger/success
+   - 3 种尺寸：sm/md/lg
+   - 支持：disabled、loading、icon
+
+2. **Input**（1-2 小时）
+   - 4 种类型：text/password/number/email
+   - 支持：placeholder、clearable、error 状态、验证反馈
+
+3. **Select**（2-3 小时）
+   - 支持：单选、搜索、disabled
+   - 支持：自定义 option 模板
+
+4. **Card**（1 小时）
+   - 通用卡片容器
+   - 支持：header、body、footer、阴影等级
+
+5. **Modal/Drawer**（2-3 小时）
+   - 确认框、表单对话框
+   - 支持：点击背景关闭、自定义宽度、遮罩层
+
+6. **Table**（3-4 小时）
+   - 数据表格
+   - 支持：列配置、排序、行选择、分页、虚拟滚动（可选）
+
+7. **Pagination**（1-2 小时）
+   - 分页器
+   - 支持：上一页/下一页/跳页
+
+**实施计划**：
+
+- Week 1：Button、Input、Select（核心输入组件）
+- Week 2：Card、Modal、Pagination（容器与布局）
+- Week 3+：Table、其他组件
+
+**预期成果**：
+
+- ✅ 7+ 个可复用组件
+- ✅ 每个组件都有完整文档、类型定义、使用示例
+- ✅ 样式统一（用设计变量）
+
+**预计工作量**：16-20 小时
+
+---
+
+#### 建议 4：标准化列表页/表单页/详情页
+
+**为什么**：
+
+- Admin 80% 的页面都是这三种类型
+- 如果有标准组件化模板，新页面开发可快 50%
+
+**建议的实施方式**：
+
+1. 把 [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md) 中的三个模板转成 Vue 组件
+   - `ListPage.uvue`：搜索 + 表格 + 分页 + 批量操作
+   - `FormPage.uvue`：表单 + 验证 + 提交 + 各种字段类型
+   - `DetailPage.uvue`：卡片展示 + 日志 + 操作按钮
+
+2. 每个模板支持以下定制：
+   - 搜索字段可配置
+   - 表格列可配置
+   - 表单字段可配置
+   - 操作按钮可配置
+
+3. 完成后迁移 1-2 个高频业务模块试用
+
+**预期成果**：
+
+- ✅ 3 个标准化页面模板组件
+- ✅ 新页面开发时间缩短 50%
+- ✅ 交互与样式保持一致
+
+**预计工作量**：8-10 小时
+
+---
+
+### C. 中期建议（2-4 周内）
+
+#### 建议 5：全面对接真实 API
+
+**为什么**：
+
+- 从 Mock 过渡到真实数据是必要步骤
+- 现在框架已经就位（Supabase 集成、token 自动化）
+- 需要按模块逐步替换
+
+**实施策略**：
+
+1. **优先级排序**（按业务重要性）：
+   - 🔴 用户、商品、订单（核心）
+   - 🟡 支付、配送、营销（高频）
+   - 🟢 报表、分析、配置（低频）
+
+2. **每个模块的替换步骤**：
+   - 后端提供 API 文档（endpoint、参数、响应）
+   - 前端在 service 层调用真实 API（替换 Mock）
+   - 同时补全错误处理、loading 态、空状态
+   - 测试数据流正确性
+
+3. **风险控制**：
+   - 在 staging 环境先充分测试
+   - 准备回滚方案（遇到问题可快速回到 Mock）
+   - 定期同步后端 API 变更
+
+**预期成果**：
+
+- ✅ 所有 Admin 功能都对接真实数据
+- ✅ 后端可独立部署，前端可独立开发
+- ✅ 完整的"API 测试用例"
+
+**预计工作量**：20-30 小时（分模块进行）
+
+---
+
+#### 建议 6：实现权限与角色系统
+
+**为什么**：
+
+- 现在所有用户看到同样的菜单和功能
+- 不同角色应该有不同的权限
+- 前端需要根据权限隐藏菜单项、禁用按钮
+
+**建议的实施方式**：
+
+1. **菜单权限**：
+   - 后端返回当前用户的权限列表
+   - 前端根据权限过滤菜单（显示/隐藏）
+   - 用户无权限但直接访问 URL 时，重定向到首页
+
+2. **按钮权限**：
+   - 每个操作按钮绑定权限码（如 `user:delete`）
+   - 检查当前用户是否拥有该权限
+   - 无权限时 disabled 或隐藏按钮
+
+3. **数据行级权限**：
+   - 某些数据只能看到自己的（如商家只看自己店铺）
+   - 后端通过 RLS（Row Level Security）在数据库层控制
+   - 前端通过 service 层过滤
+
+**预期成果**：
+
+- ✅ 菜单根据角色自动过滤
+- ✅ 按钮操作有权限检查
+- ✅ 数据安全性提升
+
+**预计工作量**：6-8 小时
+
+---
+
+### D. 长期建议（4+ 周）
+
+#### 建议 7：建立测试体系
+
+**为什么**：
+
+- 现在零测试覆盖率
+- 后续功能迭代时容易引入 bug
+- 关键流程需要自动化测试保障
+
+**建议的测试范围**：
+
+1. **单元测试**（20% 工作量）
+   - 工具类函数：时间格式化、数据校验等
+   - Store 函数：登录、登出、信息更新
+
+2. **集成测试**（50% 工作量）
+   - 完整数据流：从页面操作 → service 层 → 数据库
+   - 关键业务流程：登录 → 查看列表 → 新增/编辑/删除 → 刷新验证
+
+3. **E2E 测试**（30% 工作量）
+   - 高频用户场景
+   - 权限边界场景
+   - 错误恢复场景
+
+**预期成果**：
+
+- ✅ 关键流程有自动化测试覆盖
+- ✅ 代码改动时可快速验证
+- ✅ 产生测试数据与测试报告
+
+**预计工作量**：20-30 小时
+
+---
+
+#### 建议 8：性能与 UX 优化
+
+**为什么**：
+
+- Admin 系统数据量会越来越大
+- 需要预先做好优化，避免后期重构
+
+**优化方向**：
+
+1. **列表性能**：
+   - 虚拟滚动（只渲染可见行）
+   - 分页加载（不一次加载所有数据）
+   - 搜索防抖（避免频繁请求）
+
+2. **页面加载**：
+   - 代码分割（按需加载模块）
+   - 图片懒加载
+   - 预加载常用资源
+
+3. **交互体验**：
+   - 骨架屏（加载中的友好提示）
+   - 操作反馈（loading、toast、确认弹窗）
+   - 错误恢复（失败重试、友好提示）
+
+**预期成果**：
+
+- ✅ 列表页面加载时间 < 1s
+- ✅ 表格滚动平滑（无卡顿）
+- ✅ 用户操作有明确反馈
+
+**预计工作量**：10-15 小时
+
+---
+
+## 4️⃣ 实施路线图与时间规划
+
+### 关键时间点与交付
+
+```
+┌─────────────────┬──────────────────────────┬──────────────┬────────────┐
+│ 阶段            │ 关键任务                 │ 时间         │ 依赖       │
+├─────────────────┼──────────────────────────┼──────────────┼────────────┤
+│ Phase 0 (本周)  │ AdminLayout 合规修复     │ 13-20h       │ 无         │
+│                 │ 梳理 API 清单            │ 3-5h         │ 无         │
+├─────────────────┼──────────────────────────┼──────────────┼────────────┤
+│ Phase 1 (1-2周) │ 组件库 MVP               │ 16-20h       │ Phase 0    │
+│ (第 2-3 周)     │ 标准化页面模板           │ 8-10h        │ Phase 0    │
+├─────────────────┼──────────────────────────┼──────────────┼────────────┤
+│ Phase 2 (2-3周) │ 真实 API 对接(1/3)       │ 8-10h        │ Phase 1    │
+│ (第 4-5 周)     │ 权限系统基础             │ 4-6h         │ Phase 1    │
+├─────────────────┼──────────────────────────┼──────────────┼────────────┤
+│ Phase 3 (3-4周) │ 真实 API 对接(2/3)       │ 8-10h        │ Phase 2    │
+│ (第 6-7 周)     │ 测试体系建立             │ 10-15h       │ Phase 1    │
+├─────────────────┼──────────────────────────┼──────────────┼────────────┤
+│ Phase 4 (4+ 周) │ 真实 API 对接(3/3)       │ 4-10h        │ Phase 3    │
+│ (第 8-9 周)     │ 性能优化                 │ 10-15h       │ Phase 3    │
+└─────────────────┴──────────────────────────┴──────────────┴────────────┘
+```
+
+### 并行推进建议
+
+**Week 1-2**：
+
+- 团队 A：AdminLayout 合规修复（P0）
+- 团队 B：梳理 API + 组件库设计
+
+**Week 3-4**：
+
+- 团队 A：组件库开发（Button/Input/Select）
+- 团队 B：页面模板组件化 + 真实 API 替换
+
+**Week 5-6**：
+
+- 团队 A：表格/Modal/分页组件
+- 团队 B：权限系统 + 测试框架搭建
+
+**Week 7+**：
+
+- 团队 A：补充其他组件、优化
+- 团队 B：性能优化、全量测试
+
+---
+
+## 5️⃣ 团队协作建议
+
+### 角色分工
+
+| 角色         | 职责                            | 相关文档                                                           |
+| ------------ | ------------------------------- | ------------------------------------------------------------------ |
+| **项目经理** | 追踪进度、协调资源、风险管理    | [ADMIN_STATUS_AND_TODO.md](./ADMIN_STATUS_AND_TODO.md)             |
+| **技术主管** | 规范审查、架构决策、Code Review | [ENGINEERING_BEST_PRACTICES.md](./ENGINEERING_BEST_PRACTICES.md)   |
+| **前端开发** | 组件库、页面迁移、功能实现      | [QUICK_START_NEW_DEVELOPMENT.md](./QUICK_START_NEW_DEVELOPMENT.md) |
+| **后端开发** | API 接口、权限系统、数据库优化  | [sql_summary.md](./sql_summary.md)                                 |
+| **QA/测试**  | 功能测试、性能测试、用户验收    | 待补充（建议补充测试计划）                                         |
+
+### 日常协作流程
+
+1. **周一规划**（30min）
+   - 同步本周关键任务
+   - 前后端确认 API 需求
+   - 识别风险与阻碍
+
+2. **三日进度同步**（15min）
+   - 各模块负责人报进度
+   - 快速解决卡点
+   - 调整优先级
+
+3. **周五总结**（30min）
+   - 回顾完成情况
+   - 补充下周计划
+   - 技术分享与复盘
+
+4. **代码审查**
+   - 所有 PR 需有 2 人 review
+   - 着重检查：规范符合度、测试覆盖、性能风险
+   - 参考 [ENGINEERING_BEST_PRACTICES.md](./ENGINEERING_BEST_PRACTICES.md)
+
+---
+
+## 6️⃣ 成功指标（KPI）
+
+### 质量指标
+
+| 指标                | 目标 | 当前   | 完成时间 |
+| ------------------- | ---- | ------ | -------- |
+| AdminLayout 合规率  | 100% | 2.6%   | Week 1-2 |
+| TypeScript 类型覆盖 | 100% | 80%+   | Week 4   |
+| 代码硬编码值清零    | 0    | 已清零 | 已完成   |
+| 单测覆盖率          | ≥60% | 0%     | Week 5-6 |
+| 文档完整度          | 100% | 95%    | Week 2   |
+
+### 性能指标
+
+| 指标           | 目标   | 当前 | 完成时间 |
+| -------------- | ------ | ---- | -------- |
+| 列表页首屏加载 | <1s    | TBD  | Week 8   |
+| 表格滚动帧率   | ≥60fps | TBD  | Week 8   |
+| 包体积         | <500KB | TBD  | Week 7   |
+
+### 开发效率指标
+
+| 指标             | 目标 | 当前   | 完成时间 |
+| ---------------- | ---- | ------ | -------- |
+| 新页面开发时间   | <4h  | ~8-10h | Week 3   |
+| Bug 修复平均时间 | <2h  | TBD    | Week 6   |
+| 代码 Review 周期 | <4h  | TBD    | Week 1   |
+
+---
+
+## 7️⃣ 常见问题与答案
+
+### Q1：为什么要优先完成 AdminLayout 合规修复？
+
+**A**：因为这是后台交互的基础。如果 74 个页面导航不一致，用户体验会很差，直接影响后续功能开发的优先级。
+
+### Q2：组件库需要多完整？
+
+**A**：建议先做 MVP（7 个核心组件），这能覆盖 80% 的场景。其他组件可以按需补充。
+
+### Q3：现在有一些页面还在用原生 input/button，需要迁移吗？
+
+**A**：不需要立即迁移。重构时可选择性迁移高频页面，其他页面可后续慢慢跟进。
+
+### Q4：Mock API 什么时候切换到真实 API？
+
+**A**：建议 API 设计稳定后立即切，不要等到后期。这样前后端可以并行开发。
+
+### Q5：权限系统要做到什么程度？
+
+**A**：至少做到"菜单过滤"和"按钮 disabled"。行级权限可以后续逐步完善。
+
+### Q6：如何避免新添加的页面再次不符合规范？
+
+**A**：
+
+- 在代码审查时严格检查（看 checklist）
+- 新页面必须基于模板创建
+- IDE 配置 ESLint + Prettier 自动格式化
+
+---
+
+## 📚 相关文档导航
+
+### 必读文档
+
+- [ADMIN_STATUS_AND_TODO.md](./ADMIN_STATUS_AND_TODO.md) - 项目现状与待办总结
+- [ADMIN_PAGE_START_HERE.md](./ADMIN_PAGE_START_HERE.md) - AdminLayout 合规修复入门
+- [QUICK_START_NEW_DEVELOPMENT.md](./QUICK_START_NEW_DEVELOPMENT.md) - 如何按规范开发新页面
+
+### 规范文档
+
+- [STYLE_SPECIFICATION.md](./STYLE_SPECIFICATION.md) - 设计系统
+- [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md) - 页面结构模板
+- [COMPONENT_SPECIFICATION.md](./COMPONENT_SPECIFICATION.md) - 组件规范
+- [ENGINEERING_BEST_PRACTICES.md](./ENGINEERING_BEST_PRACTICES.md) - 工程化规范
+
+### 参考文档
+
+- [IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md) - 8 阶段路线图
+- [SERVICE_QUICK_START.md](./SERVICE_QUICK_START.md) - 业务模块样板（客服管理）
+- [ADMIN_LAYOUT_GUIDE.md](./ADMIN_LAYOUT_GUIDE.md) - AdminLayout 使用指南
+
+---
+
+## 🎯 总结与建议
+
+### 现状总结
+
+✅ **基础已很扎实**
+
+- 规范体系完整（设计/工程/页面）
+- 布局系统就位（AdminLayout 完善）
+- 业务样板可用（客服管理完整交付）
+- 数据流通畅（Supabase 集成、token 自动化）
+
+⚠️ **短期瓶颈明显**
+
+- AdminLayout 合规修复（74 个文件）
+- 组件库缺失（代码重复率高）
+- 模板未组件化（开发效率低）
+
+### 最强烈的建议
+
+🚀 **立即启动 Phase 0（本周）**
+
+1. 完成 AdminLayout 合规修复（13-20 小时）
+2. 梳理真实 API 清单（3-5 小时）
+
+这两项会直接解除后续开发的瓶颈，之后 Phase 1 可以快速推进。
+
+### 长期优势
+
+如果按照本建议书推进，你们的 Admin 系统 4 周后会具有：
+
+- ✨ **一致的 UI/交互**：AdminLayout 统一、菜单自动高亮、交互模式相同
+- ✨ **高效的开发流程**：组件库就位、模板可复用、新页面开发时间缩短 50%
+- ✨ **可靠的数据流**：真实 API、权限检查、完整错误处理
+- ✨ **安全的系统**：权限系统、RLS 保护、前后端验证
+- ✨ **易维护的代码**：规范统一、设计变量集中、测试覆盖
+
+---
+
+**报告完成日期**：2026-02-04  
+**下次评估建议**：完成 Phase 0 后（约 2 周后）重新评估进度与风险
--- a/pages/mall/admin/docs/ADMIN_STATUS_AND_TODO.md
+++ b/pages/mall/admin/docs/ADMIN_STATUS_AND_TODO.md
@@ -0,0 +1,115 @@
+# ✅ 项目已完成内容 & Admin 管理端待办（2026-02-04）
+
+本文档用于回答两个问题：
+
+1. 这个项目已经完成了哪些“可复用/可落地”的成果？
+2. Admin 管理端接下来需要做什么（按优先级）？
+
+---
+
+## 1) 项目已完成（当前可用的交付）
+
+### A. 设计系统与规范体系（可作为团队开发标准）
+
+- 设计令牌与样式变量体系（基于 `uni.scss`，强调禁止硬编码）
+  - 规范入口： [STYLE_SPECIFICATION.md](./STYLE_SPECIFICATION.md)
+- Admin 页面结构模板与标准布局（List/Form/Detail 等）
+  - 规范入口： [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md)
+- 组件库规范与分类（Props/Emit/Slot、命名、检查清单等）
+  - 规范入口： [COMPONENT_SPECIFICATION.md](./COMPONENT_SPECIFICATION.md)
+- 工程化最佳实践（目录结构、命名、导入约定、质量建议等）
+  - 规范入口： [ENGINEERING_BEST_PRACTICES.md](./ENGINEERING_BEST_PRACTICES.md)
+- 实施路线图（阶段划分、优先级、验收标准）
+  - 规划入口： [IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md)
+
+### B. AdminLayout / 导航高亮相关基础设施（能跑通的底座）
+
+- AdminLayout 使用方法、current-page 与菜单高亮规则、pages.json 注意事项
+  - 指南： [ADMIN_LAYOUT_GUIDE.md](./ADMIN_LAYOUT_GUIDE.md)
+- 页面路由清单（用于核对 pages.json 与真实文件路径）
+  - 路由： [PAGES_ROUTES.md](./PAGES_ROUTES.md)
+
+### C. Admin 页面合规检查（已做过一轮全量审计与方案输出）
+
+- “后台页面是否包 AdminLayout”检查交付文档（含全量清单、优先级、修改方案、CSV）
+  - 从这里开始： [ADMIN_PAGE_START_HERE.md](./ADMIN_PAGE_START_HERE.md)
+  - 总入口清单： [00_READ_ME_FIRST.md](./00_READ_ME_FIRST.md)
+
+### D. Admin 规范化重构阶段成果（已重构一批页面并形成方法论）
+
+- 阶段总结与指标（例如硬编码清零、类型补全、结构统一等）
+  - 总结： [REFACTOR_SUMMARY.md](./REFACTOR_SUMMARY.md)
+  - 重构入口： [ADMIN_REFACTOR_INDEX.md](./ADMIN_REFACTOR_INDEX.md)
+
+### E. uni-app-x 常见编译/页面配置问题排错知识库
+
+- pages.json 路径、组件导入、生命周期、特殊字符、重复标签、BOM 等典型根因与修复流程
+  - 指南： [UNI_APP_X_PAGE_FIX_GUIDE.md](./UNI_APP_X_PAGE_FIX_GUIDE.md)
+- system-info 这类“隐藏字符/BOM 导致组件解析失败”的根因复盘
+  - 根因： [SYSTEM_INFO_ROOT_CAUSE.md](./SYSTEM_INFO_ROOT_CAUSE.md)
+
+### F. 业务模块示范：客服管理模块（“可运行”的完整模块样板）
+
+- 5 个页面 + 菜单配置 + 服务层（Mock）+ 交付验收文档
+  - 快速开始： [SERVICE_QUICK_START.md](./SERVICE_QUICK_START.md)
+  - 项目总结： [SERVICE_PROJECT_SUMMARY.md](./SERVICE_PROJECT_SUMMARY.md)
+
+### G. 数据库/SQL 文档体系（用于 Supabase/RLS/迁移/索引/质量检查）
+
+- 入口索引： [sql_summary.md](./sql_summary.md)
+- 分主题深挖： [sql/README.md](./sql/README.md)
+
+---
+
+## 2) Admin 管理端下一步要做什么（按优先级）
+
+下面的待办按“影响面 + 是否阻塞开发”排序。
+
+### P0（先做这些：会直接影响开发效率/线上可用性）
+
+- 完成 Admin 页面 AdminLayout 合规修复的“收尾与验证”
+  - 以合规清单为准逐个关闭： [ADMIN_PAGE_COMPLIANCE_CHECKLIST.md](./ADMIN_PAGE_COMPLIANCE_CHECKLIST.md)
+  - 快速查文件状态： [ADMIN_PAGE_QUICK_REFERENCE.md](./ADMIN_PAGE_QUICK_REFERENCE.md)
+  - 套用修改方案： [ADMIN_PAGE_MODIFICATION_PLAN.md](./ADMIN_PAGE_MODIFICATION_PLAN.md)
+- 统一并固化 currentPage（菜单 id）与路由的对应关系
+  - 目标：所有页面打开时菜单高亮正确、子菜单展开正确、面包屑正确
+  - 参考： [ADMIN_LAYOUT_GUIDE.md](./ADMIN_LAYOUT_GUIDE.md)
+- 把“常见编译/页面问题”预防动作纳入日常（避免重复踩坑）
+  - 重点：BOM/隐藏字符、重复 script/style、特殊字符、路径大小写
+  - 参考： [UNI_APP_X_PAGE_FIX_GUIDE.md](./UNI_APP_X_PAGE_FIX_GUIDE.md)
+
+### P1（让 Admin 开发进入“高复用、低返工”状态）
+
+- 按路线图启动组件库的最小可用集（MVP）
+  - 建议先落地：Button/Input/Select/Card/Modal/Pagination/Table（够支撑 80% 列表页）
+  - 规划参考： [IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md)
+  - 组件规范参考： [COMPONENT_SPECIFICATION.md](./COMPONENT_SPECIFICATION.md)
+- 落地页面模板（ListPage/FormPage/DetailPage），并把存量页面迁移到模板
+  - 模板规范参考： [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md)
+- 建立统一的列表页“通用交互模式”
+  - 搜索/筛选/分页/批量操作/确认弹窗/空状态/加载态
+  - 可参考已完成模块的交互模式： [SERVICE_QUICK_START.md](./SERVICE_QUICK_START.md)
+
+### P2（功能完整性、质量与可维护性提升）
+
+- 替换/接入真实 API（从 Mock 过渡到真实服务）
+  - 建议优先：用户、商品、订单、营销等主流程
+- 增加权限与角色体系的前端约束（菜单/路由/按钮级别）
+- 测试与验收：关键路径回归、页面导航一致性、布局响应式
+- 文档维护：每新增一个模块，至少产出“快速开始 + 交付清单 + 实现说明”三件套
+
+---
+
+## 3) 最推荐的“本周行动清单”（可直接照做）
+
+1. 用 [ADMIN_PAGE_QUICK_REFERENCE.md](./ADMIN_PAGE_QUICK_REFERENCE.md) 拉一份“剩余未合规页面”列表
+2. 按 [ADMIN_PAGE_MODIFICATION_PLAN.md](./ADMIN_PAGE_MODIFICATION_PLAN.md) 批量修复并自测菜单高亮
+3. 同步启动组件库 MVP（先覆盖列表页需要的那几个）
+4. 用模板规范把 1~2 个高频页面迁移成“样板间”，之后按样板复制扩展
+
+---
+
+## 4) 相关入口（不确定看啥就从这里）
+
+- 文档导航地图： [DOCS_OVERVIEW.md](./DOCS_OVERVIEW.md)
+- 设计系统总入口： [README.md](./README.md)
--- a/pages/mall/admin/docs/DOCS_OVERVIEW.md
+++ b/pages/mall/admin/docs/DOCS_OVERVIEW.md
@@ -0,0 +1,141 @@
+# 📚 Mall 项目文档总览（Docs Map）
+
+> 目的：把 `docs/` 里的资料按「读什么、做什么」重新组织，方便新同事/自己快速定位。
+
+## ✅ 从哪里开始（按你的目标）
+
+- **我是 PM/技术主管，想要项目评估与建议书**：看 [ADMIN_FEATURES_AND_ROADMAP.md](./ADMIN_FEATURES_AND_ROADMAP.md)（已完成内容、功能建议、4 周路线图）- **我想快速知道“已完成什么/接下来做什么”**：看 [ADMIN_STATUS_AND_TODO.md](./ADMIN_STATUS_AND_TODO.md)
+- **我想了解整个项目（设计系统 + 规范）**：从 [README.md](./README.md) 开始
+- **我想快速按规范开发新页面**：看 [QUICK_START_NEW_DEVELOPMENT.md](./QUICK_START_NEW_DEVELOPMENT.md)
+- **我在做 AdminLayout / 侧边栏 / 页面高亮**：看 [ADMIN_LAYOUT_GUIDE.md](./ADMIN_LAYOUT_GUIDE.md)
+- **我在修复“后台页面是否包 AdminLayout”合规问题**：从 [ADMIN_PAGE_START_HERE.md](./ADMIN_PAGE_START_HERE.md) 开始
+- **我遇到 uni-app-x 页面配置/编译错误**：看 [UNI_APP_X_PAGE_FIX_GUIDE.md](./UNI_APP_X_PAGE_FIX_GUIDE.md)
+- **我在看数据库/SQL 文档**：从 [sql_summary.md](./sql_summary.md) 进入
+- **我在做客服管理模块（已可用）**：从 [SERVICE_QUICK_START.md](./SERVICE_QUICK_START.md) 开始
+
+---
+
+## 🧭 推荐阅读路线（最省时间）
+
+### 路线 A：新加入/需要全局理解（30~60 分钟）
+
+1. [README.md](./README.md)（文档体系 + 项目目标 + 现状）
+2. [QUICK_REFERENCE.md](./QUICK_REFERENCE.md)（设计变量/模板速查）
+3. [ENGINEERING_BEST_PRACTICES.md](./ENGINEERING_BEST_PRACTICES.md)（工程结构、命名、导入规范）
+4. [STYLE_SPECIFICATION.md](./STYLE_SPECIFICATION.md)（样式唯一标准：禁止硬编码）
+5. [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md)（List/Form/Detail 页面模板）
+
+### 路线 B：我要开始写/重构 admin 页面（15~30 分钟）
+
+1. [QUICK_START_NEW_DEVELOPMENT.md](./QUICK_START_NEW_DEVELOPMENT.md)（3 步新建页面 + 规范检查）
+2. [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md)（选模板：列表/表单/详情）
+3. [ADMIN_LAYOUT_GUIDE.md](./ADMIN_LAYOUT_GUIDE.md)（current-page、菜单高亮、pages.json 配置）
+
+### 路线 C：我要修后台页面“AdminLayout 包装合规”（按需）
+
+1. [ADMIN_PAGE_START_HERE.md](./ADMIN_PAGE_START_HERE.md)（任务说明 + 优先级）
+2. [ADMIN_PAGE_QUICK_REFERENCE.md](./ADMIN_PAGE_QUICK_REFERENCE.md)（按文件快速查状态）
+3. [ADMIN_PAGE_MODIFICATION_PLAN.md](./ADMIN_PAGE_MODIFICATION_PLAN.md)（按问题类型给修改方案）
+4. [ADMIN_PAGE_COMPLIANCE_CHECKLIST.md](./ADMIN_PAGE_COMPLIANCE_CHECKLIST.md)（全量清单）
+
+---
+
+## 🧩 按主题索引（你要找的文档在这里）
+
+### 1) 设计系统 / 规范（所有页面的“唯一标准”）
+
+- [STYLE_SPECIFICATION.md](./STYLE_SPECIFICATION.md)：颜色/间距/字体/阴影/响应式等样式规范（基于 `uni.scss` 变量）
+- [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md)：admin 页面结构模板（List/Form/Detail）
+- [COMPONENT_SPECIFICATION.md](./COMPONENT_SPECIFICATION.md)：组件分类、Props/Emit/Slot、示例与检查清单
+- [ENGINEERING_BEST_PRACTICES.md](./ENGINEERING_BEST_PRACTICES.md)：目录结构、命名、导入、Git/测试/构建建议
+- [IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md)：8 阶段路线图（组件库 → 页面模板集成 → 迁移）
+- [FRONTEND_ARCHITECTURE_ANALYSIS.md](./FRONTEND_ARCHITECTURE_ANALYSIS.md)：前端架构分析（用于理解整体设计取舍）
+
+### 2) AdminLayout / 侧边栏 / 导航高亮
+
+- [ADMIN_LAYOUT_GUIDE.md](./ADMIN_LAYOUT_GUIDE.md)：如何在页面使用 AdminLayout、current-page 规则、pages.json 配置
+- [ADMIN_LAYOUT_TRANSFORMATION_COMPLETE.md](./ADMIN_LAYOUT_TRANSFORMATION_COMPLETE.md)：布局改造总结
+- [ADMIN_LAYOUT_TRANSFORMATION_100_COMPLETE.md](./ADMIN_LAYOUT_TRANSFORMATION_100_COMPLETE.md)：布局改造阶段性完成记录
+- [ADMIN_LAYOUT_IMPLEMENTATION_COMPLETE.md](./ADMIN_LAYOUT_IMPLEMENTATION_COMPLETE.md)：实现完成说明
+- [ADMIN_LAYOUT_PROGRESS_REPORT.md](./ADMIN_LAYOUT_PROGRESS_REPORT.md)：进度报告
+- [ORDER_MENU_HIGHLIGHT_FIX.md](./ORDER_MENU_HIGHLIGHT_FIX.md) / [ORDER_MENU_HIGHLIGHT_QUICK_FIX.md](./ORDER_MENU_HIGHLIGHT_QUICK_FIX.md)：订单菜单高亮相关修复
+
+### 3) 后台页面合规检查（AdminLayout 包装检查交付）
+
+- [00_READ_ME_FIRST.md](./00_READ_ME_FIRST.md)：检查交付入口（合规检查那批文档）
+- [ADMIN_PAGE_START_HERE.md](./ADMIN_PAGE_START_HERE.md)：开始这里（检查结果概览 + 如何执行）
+- [ADMIN_PAGE_INDEX.md](./ADMIN_PAGE_INDEX.md)：索引导航
+- [ADMIN_PAGE_SUMMARY.md](./ADMIN_PAGE_SUMMARY.md)：执行总结
+- [ADMIN_PAGE_QUICK_REFERENCE.md](./ADMIN_PAGE_QUICK_REFERENCE.md)：快速查找表
+- [ADMIN_PAGE_MODIFICATION_PLAN.md](./ADMIN_PAGE_MODIFICATION_PLAN.md)：修改方案合集
+- [ADMIN_PAGE_COMPLIANCE_CHECKLIST.md](./ADMIN_PAGE_COMPLIANCE_CHECKLIST.md)：全量清单
+- [ADMIN_PAGE_CHECKLIST.csv](./ADMIN_PAGE_CHECKLIST.csv)：CSV 数据表
+- [ADMIN_PAGE_COMPLETE.md](./ADMIN_PAGE_COMPLETE.md)：最终交付清单
+
+### 4) Admin 重构（规范化改造）
+
+- [ADMIN_REFACTOR_INDEX.md](./ADMIN_REFACTOR_INDEX.md)：重构文档入口（按角色导航）
+- [REFACTOR_SUMMARY.md](./REFACTOR_SUMMARY.md)：阶段总结（指标、覆盖、下一步）
+- [REFACTOR_BEFORE_AFTER.md](./REFACTOR_BEFORE_AFTER.md)：改造前后对比
+- [ADMIN_REFACTOR_PROGRESS.md](./ADMIN_REFACTOR_PROGRESS.md)：进度清单
+- [ADMIN_PROJECT_FINAL_REPORT.md](./ADMIN_PROJECT_FINAL_REPORT.md)：最终报告
+
+### 5) uni-app-x 页面/编译/配置排错
+
+- [UNI_APP_X_PAGE_FIX_GUIDE.md](./UNI_APP_X_PAGE_FIX_GUIDE.md)：pages.json/组件导入/特殊字符/重复标签等常见根因与标准流程
+- [PAGES_ROUTES.md](./PAGES_ROUTES.md)：从 pages.json 生成的路由清单（核对路径很有用）
+- system-info 相关：
+  - [SYSTEM_INFO_ROOT_CAUSE.md](./SYSTEM_INFO_ROOT_CAUSE.md)
+  - [SYSTEM_INFO_FIX_GUIDE.md](./SYSTEM_INFO_FIX_GUIDE.md)
+  - [SYSTEM_INFO_SIDEBAR_FIX.md](./SYSTEM_INFO_SIDEBAR_FIX.md)
+
+### 6) 业务模块：客服管理（示例：完整可运行模块）
+
+- [SERVICE_QUICK_START.md](./SERVICE_QUICK_START.md)：5 个页面 + 菜单配置 + 交互规范 + 服务层
+- [SERVICE_PROJECT_SUMMARY.md](./SERVICE_PROJECT_SUMMARY.md)：交付物、代码结构、实现清单
+- [SERVICE_MODULE_IMPLEMENTATION.md](./SERVICE_MODULE_IMPLEMENTATION.md)：实现细节（更偏“实现百科”）
+- [SERVICE_DELIVERY_CHECKLIST.md](./SERVICE_DELIVERY_CHECKLIST.md)：交付与验收清单
+
+### 7) 设计/装修（Design & Decoration）
+
+- [DESIGN_DECORATION_GUIDE.md](./DESIGN_DECORATION_GUIDE.md)
+- [DESIGN_QUICK_REFERENCE.md](./DESIGN_QUICK_REFERENCE.md)
+- [DESIGN_MODULE_USER_GUIDE.md](./DESIGN_MODULE_USER_GUIDE.md)
+- [DESIGN_MODULE_UPGRADE_REPORT.md](./DESIGN_MODULE_UPGRADE_REPORT.md)
+- [DESIGN_IMPLEMENTATION_REPORT.md](./DESIGN_IMPLEMENTATION_REPORT.md)
+
+### 8) 数据库/SQL（Supabase/RLS/迁移）
+
+- [sql_summary.md](./sql_summary.md)：SQL 文档入口（推荐从这里开始）
+- [sql/README.md](./sql/README.md)：SQL 文档目录说明
+- `sql/00_overview.md` ~ `sql/11_roles_and_permissions_strategy.md`：分主题深挖
+
+---
+
+## 🧰 常见任务入口（按“我要做什么”）
+
+- **新增一个 admin 页面**：
+  - 先看 [QUICK_START_NEW_DEVELOPMENT.md](./QUICK_START_NEW_DEVELOPMENT.md)
+  - 再对照 [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md)
+  - 页面外壳用 AdminLayout：参考 [ADMIN_LAYOUT_GUIDE.md](./ADMIN_LAYOUT_GUIDE.md)
+
+- **排查“页面不存在/路径不对/pages.json 报错”**：
+  - 先看 [UNI_APP_X_PAGE_FIX_GUIDE.md](./UNI_APP_X_PAGE_FIX_GUIDE.md)
+  - 再核对 [PAGES_ROUTES.md](./PAGES_ROUTES.md)
+
+- **修复 AdminLayout 导入/解析失败（比如 BOM/隐藏字符）**：
+  - 看 [SYSTEM_INFO_ROOT_CAUSE.md](./SYSTEM_INFO_ROOT_CAUSE.md)
+
+- **想找一个“做得比较标准”的页面做参考**：
+  - 从重构成果里找：看 [REFACTOR_SUMMARY.md](./REFACTOR_SUMMARY.md)
+
+---
+
+## 📝 维护约定（建议）
+
+- 以后新增/调整文档，请在本文件补一条入口（按主题放置）。
+- 如果某个主题形成完整“闭环”（指南 + 实现 + 验收 + 排错），建议像 `SERVICE_*` 一样成组维护。
+
+---
+
+**最后更新**：2026-02-04
--- a/pages/mall/admin/docs/README.md
+++ b/pages/mall/admin/docs/README.md
@@ -1,5 +1,7 @@
 # Mall 项目 - CRMEB 风格设计系统完整指南

+> 文档总览入口：从 [DOCS_OVERVIEW.md](./DOCS_OVERVIEW.md) 开始（按主题/任务导航）。
+
 ## 🎯 项目目标

 将 mall 项目的页面样式和设计系统与 CRMEB 专业设计标准完全对标，使用 uni-app-x 和 .uvue 组件进行一比一复刻。
--- a/pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md
+++ b/pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md
@@ -4,9 +4,14 @@

 本文档总结了 uni-app-x 项目中页面配置和编译错误的完整修复流程，旨在为后续开发提供标准化的解决方案和最佳实践。

-## 🔍 问题根源分析
+#### **原因十一：标签重复定义错误**

-### 1. 初始错误现象
+- **现象**: `[plugin:vite:vue] Single file component can contain only one <script setup> element`
+- **原因**: 在使用 `replace_string_in_file` 等编辑工具时，如果匹配范围过窄（仅匹配了 template），而替换内容包含全量代码（template+script+style），会导致原有的 script/style 块被留在文件末尾，产生重复标签。
+- **解决方案**: 确保替换操作覆盖文件的完整生命周期，或者在发现 500 错误时检查文件末尾是否有残留的旧标签。
+- **预防**: 优先使用 `create_file` 或子代理重写整个文件，而非局部替换复杂的 SFC 结构。
+
+## 🛠️ 完整修复流程

 ```
 [plugin:uni:h5-pages-json] 页面"minimal"不存在，请确保填写的页面路径不包含文件后缀，且必须与真实的文件路径大小写保持一致。