142 lines
8.3 KiB
Markdown
142 lines
8.3 KiB
Markdown
# 📚 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
|