# 📚 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