清道夫App 开发文档
项目: 清道夫系统 (环境服务管理平台)
技术栈: uni-app + Vue 3 + Vite + TypeScript + Tailwind CSS + Pinia
创建时间: 2026-06-22
原型参考: 清道夫系统原型_完整版_V21_SOP.html
一、项目结构
清道夫App/
├── src/
│ ├── api/ # 后端API接口
│ ├── components/ # 公共组件
│ │ ├── common/ # 通用组件
│ │ │ ├── BottomNav.vue
│ │ │ ├── TopBar.vue
│ │ │ ├── EmptyState.vue
│ │ │ └── StatusTag.vue
│ │ ├── uni-list/ # 列表组件 (小程序风格)
│ │ │ ├── uni-list.vue
│ │ │ └── uni-list-item.vue
│ │ ├── uni-card/ # 卡片组件 (小程序风格)
│ │ │ └── uni-card.vue
│ │ ├── uni-segmented-control/ # 分段器/Tab
│ │ │ └── uni-segmented-control.vue
│ │ ├── uni-swipe-action/ # 左滑操作
│ │ │ └── uni-swipe-action.vue
│ │ └── task/
│ │ └── TaskCard.vue
│ ├── pages/ # 页面
│ ├── stores/ # Pinia状态管理
│ ├── styles/ # 样式文件
│ │ ├── global.scss
│ │ ├── variables.scss
│ │ ├── tailwind.css
│ │ └── uni-icons.css # uni-icons字体图标
│ ├── static/fonts/ # 字体文件
│ │ └── uniicons.ttf
│ ├── types/ # TypeScript类型
│ ├── utils/ # 工具函数
│ ├── App.vue
│ ├── main.ts
│ └── pages.json
├── package.json
├── vite.config.ts
├── tailwind.config.js
└── tsconfig.json
二、开发规范
2.1 样式规范
- 不使用 emoji 表情符号，统一使用
uni-icons 字体图标
- 小程序优先设计，避免使用 Web 专属特性
- 移动端最大宽度 430px，居中显示
- 圆角统一使用
12px (卡片) / 8px (按钮) / 20px (标签)
- 阴影统一使用
0 2px 8px rgba(0,0,0,0.06)
2.2 图标使用 (uni-icons)
在任意页面/组件中使用：
<text class="uni-icons uniui-home-filled text-blue-500 text-lg"></text>
常用图标对照：
| 功能 | 类名 |
|------|------|
| 首页 | uniui-home-filled |
| 用户/人员 | uniui-person-filled |
| 通知/铃铛 | uniui-notification-filled |
| 设置/齿轮 | uniui-gear-filled |
| 搜索 | uniui-search |
| 返回 | uniui-back |
| 添加 | uniui-plusempty |
| 删除 | uniui-trash |
| 完成/勾选 | uniui-checkmarkempty |
| 关闭 | uniui-close |
| 电话 | uniui-phone-filled |
| 日历 | uniui-calendar-filled |
| 地图/位置 | uniui-location-filled |
| 车辆 | uniui-cart-filled |
| 文件夹/项目 | uniui-folder-add-filled |
| 任务/旗帜 | uniui-flag-filled |
| 消息/聊天 | uniui-chatbubble-filled |
| 眼睛/查看 | uniui-eye-filled |
| 锁定 | uniui-locked-filled |
| 上传/相机 | uniui-camera-filled |
| 帮助 | uniui-help-filled |
| 更多/箭头 | uniui-arrowright |
2.3 组件使用规范
uni-list / uni-list-item
<uni-list border>
<uni-list-item
title="标题"
note="描述信息"
right-text="右侧文字"
show-arrow
@click="onClick"
>
<template #header>
<text class="uni-icons uniui-person-filled"></text>
</template>
</uni-list-item>
</uni-list>
uni-card
<uni-card title="卡片标题" extra="额外信息" icon="uniui-flag-filled">
<view>卡片内容</view>
<template #footer>
<button>操作按钮</button>
</template>
</uni-card>
uni-segmented-control (顶部Tab栏)
<uni-segmented-control
:current="currentIndex"
:values="['全部', '待办', '已完成']"
style-type="text"
active-color="#4f8ef7"
@clickItem="onTabChange"
/>
uni-swipe-action (左滑删除)
<uni-swipe-action :actions="[{text:'删除', color:'#ff3b30'}]" @click="onDelete">
<uni-list-item title="标题" note="描述" />
</uni-swipe-action>
2.4 命名规范
- 页面文件名: 小驼峰，如
projectList.vue
- 组件名: 大驼峰，如
BottomNav.vue
- Store: 小驼峰，如
auth.ts
- API 函数: 小驼峰，如
getProjectList
- 类型定义: 大驼峰，如
TaskStatus
三、原型页面清单 (54页)
来源: 原型功能清单_完整详细版(含登录).md
3.1 登录模块 (1页)
| 页面ID |
页面名称 |
状态 |
备注 |
| loginPage |
清道夫系统登录 |
✅ |
账号密码 + 角色切换 |
3.2 销售端 - SalesApp (21页)
| # |
页面ID |
页面名称 |
状态 |
备注 |
| 1 |
salesPage |
首页 |
✅ |
统计卡片 + 快捷入口 |
| 2 |
taskPage |
我的任务 |
✅ |
状态筛选 + 列表 |
| 3 |
profilePage |
个人中心 |
✅ |
用户信息 + 菜单 |
| 4 |
sales_basicInfoPage |
基本信息 |
✅ |
已重构为uni-card+uni-list |
| 5 |
sales_changePasswordPage |
修改密码 |
✅ |
已重构为uni-card |
| 6 |
sales_notificationPage |
消息通知 |
✅ |
分类: 任务/系统 |
| 7 |
sales_helpCenterPage |
帮助中心 |
✅ |
共用组件 |
| 8 |
sales_taskReminderPage |
任务提醒 |
✅ |
提醒列表 |
| 9 |
projectListPage |
项目库 |
✅ |
筛选: 全部/季度/包年/月付/单次 |
| 10 |
addProjectPage |
新增项目 |
✅ |
完整表单 |
| 11 |
projectDetailPage |
项目详情 |
✅ |
信息区块展示 |
| 12 |
messageListPage |
消息通知列表 |
✅ |
分类筛选 + 左滑删除 |
| 13 |
messageDetailPage |
消息详情 |
✅ |
标记已读 + 关联任务 |
| 14 |
changePasswordPage |
修改密码(通用) |
✅ |
可复用组件 |
| 15 |
helpCenterPage |
帮助中心(通用) |
✅ |
FAQ + 指南 |
| 16 |
noticeListPage |
通知公告列表 |
✅ |
列表展示 |
| 17 |
noticeDetailPage |
公告详情 |
✅ |
详情展示 |
| 18 |
knowledgeListPage |
行业知识列表 |
✅ |
分类 + 搜索 |
| 19 |
knowledgeDetailPage |
知识详情 |
✅ |
内容 + 附件 |
| 20 |
publishTaskPage |
发布任务 |
✅ |
完整表单 + 图片上传 |
| 21 |
taskDetailPage |
任务详情 |
✅ |
进度条 + 时间线 + SOP |
3.3 调度端 - DispatchApp (19页)
| # |
页面ID |
页面名称 |
状态 |
备注 |
| 1 |
dispatch_homePage |
首页 |
✅ |
统计 + 资源状态 |
| 2 |
dispatch_schedulePage |
排班管理 |
✅ |
日历 + 排班列表 |
| 3 |
dispatch_taskPage |
任务管理 |
✅ |
筛选: 全部/进行中/已完成/待审核/待排班/已驳回 |
| 4 |
dispatch_myPage |
个人中心 |
✅ |
共用profile |
| 5 |
dispatch_basicInfoPage |
基本信息 |
✅ |
已重构为uni-card+uni-list |
| 6 |
dispatch_changePasswordPage |
修改密码 |
✅ |
已重构为uni-card |
| 7 |
dispatch_helpCenterPage |
帮助中心 |
✅ |
共用 |
| 8 |
dispatch_noticeListPage |
通知公告 |
✅ |
共用 |
| 9 |
dispatch_noticeDetailPage |
公告详情 |
✅ |
共用 |
| 10 |
dispatch_onDutyStaffPage |
在岗人员 |
✅ |
人员状态展示 |
| 11 |
dispatch_availableVehiclesPage |
可用车辆 |
✅ |
状态筛选 + 统计卡片 |
| 12 |
dispatch_emergencyStandbyPage |
应急待命 |
✅ |
应急班组 |
| 13 |
dispatch_publishTaskPage |
发布任务 |
✅ |
完整表单 |
| 14 |
dispatch_taskDetailPage |
任务详情 |
✅ |
调度审核/安排/驳回 |
| 15 |
dispatch_personnelPage |
人员列表 |
✅ |
状态筛选 |
| 16 |
dispatch_vehicleListPage |
车辆列表 |
✅ |
状态筛选 |
| 17 |
dispatch_emergencyTeamPage |
应急班组 |
✅ |
班组信息 |
| 18 |
dispatch_notificationPage |
消息通知 |
✅ |
分类: 全部/审核结果/任务分配/系统 |
| 19 |
dispatch_visualizationPage |
可视化大屏 |
✅ |
统计图表 + 排班 |
3.4 施工端 - ConstructionApp (13页)
| # |
页面ID |
页面名称 |
状态 |
备注 |
| 1 |
construction_homePage |
首页 |
✅ |
统计 + 快捷入口 |
| 2 |
construction_dailyTaskPage |
每日任务 |
✅ |
车辆检查清单 |
| 3 |
construction_taskPage |
我的任务 |
✅ |
筛选: 待出车/已出车/施工中/待验收/待确认 |
| 4 |
construction_taskDetailPage |
任务详情 |
✅ |
SOP流程: 出车→现场→勘验→施工 |
| 5 |
construction_myPage |
个人中心 |
✅ |
共用profile |
| 6 |
construction_basicInfoPage |
个人信息 |
✅ |
已重构为uni-card+uni-list |
| 7 |
construction_changePasswordPage |
修改密码 |
✅ |
已重构为uni-card |
| 8 |
construction_helpCenterPage |
帮助中心 |
✅ |
共用 |
| 9 |
construction_noticeListPage |
通知公告 |
✅ |
共用 |
| 10 |
construction_noticeDetailPage |
公告详情 |
✅ |
共用 |
| 11 |
construction_notificationPage |
消息通知 |
✅ |
分类: 系统/任务/全部 |
| 12 |
construction_historyTaskPage |
历史任务 |
✅ |
已完成任务列表 |
| 13 |
construction_tomorrowTaskPage |
明日任务 |
✅ |
预约/取消/催单 |
四、开发进度总览
4.1 基础架构 ✅ 已完成
| 模块 |
功能 |
状态 |
备注 |
| 项目初始化 |
uni-app + Vue3 + Vite + TS |
✅ |
2026-06-22 |
| 样式配置 |
Tailwind CSS + 全局样式 |
✅ |
2026-06-22 |
| 后端对接 |
request封装 + 所有API模块 |
✅ |
2026-06-22 |
| Pinia Store |
auth/project/task/notification |
✅ |
2026-06-22 |
| 公共组件 |
BottomNav/TopBar/EmptyState/StatusTag |
✅ |
2026-06-22 |
| uni-icons |
字体图标CSS + ttf文件 |
✅ |
2026-06-22 |
| emoji清理 |
38个文件全部清理 |
✅ |
2026-06-22 |
| uni-list |
列表组件 + 列表项 |
✅ |
2026-06-22 |
| uni-card |
卡片组件 |
✅ |
2026-06-22 |
| uni-segmented-control |
顶部Tab分段器 |
✅ |
2026-06-22 |
| uni-swipe-action |
左滑操作组件 |
✅ |
2026-06-22 |
4.2 阶段一：页面重构 (✅ 已完成)
将已有页面重构为小程序风格 (uni-card/uni-list/uni-icons):
| 页面 |
状态 |
备注 |
| sales/home.vue |
✅ |
uni-card统计卡片 + uni-icons快捷入口 |
| dispatch/home.vue |
✅ |
uni-card + uni-list |
| construction/home.vue |
✅ |
uni-card + uni-icons |
| common/projectList.vue |
✅ |
uni-segmented-control + uni-list + uni-swipe-action |
| common/taskList.vue |
✅ |
uni-segmented-control + uni-list |
| dispatch/personnel.vue |
✅ |
uni-segmented-control + uni-list |
| dispatch/vehicleList.vue |
✅ |
uni-segmented-control + uni-list |
| common/noticeList.vue |
✅ |
uni-segmented-control + uni-list + uni-swipe-action |
| common/profile.vue |
✅ |
uni-card + uni-list + uni-icons |
| common/taskDetail.vue |
✅ |
uni-card布局 + 进度时间轴 |
| common/projectDetail.vue |
✅ |
uni-card列表 + 服务点 |
| common/addProject.vue |
✅ |
uni-card表单区块 + uni-icons |
| dispatch/schedule.vue |
✅ |
日历 + uni-list排班 |
| sales/taskReminder.vue |
✅ |
uni-card + uni-icons |
| dispatch/visualization.vue |
✅ |
uni-card统计 + uni-list |
| construction/dailyTask.vue |
✅ |
uni-card + uni-list检查项 |
| construction/tomorrowTask.vue |
✅ |
uni-list |
| construction/historyTask.vue |
✅ |
uni-list |
| dispatch/dutyPersonnel.vue |
✅ |
uni-segmented-control + uni-list |
| dispatch/emergencyTeam.vue |
✅ |
uni-card统计 + uni-list |
| sales/notification.vue |
✅ |
uni-list + 未读红点 |
| dispatch/notification.vue |
✅ |
uni-list + 未读红点 |
| construction/notification.vue |
✅ |
uni-list + 未读红点 |
| construction/helpCenter.vue |
✅ |
uni-card + uni-list + uni-icons |
| 阶段一完成 |
✅ |
24个页面全部重构完成 |
4.3 阶段二：补充缺失页面 (✅ 已完成)
根据原型清单，以下页面已补充/重构：
| 优先级 |
页面 |
所属角色 |
状态 |
备注 |
| 🔴 高 |
sales_basicInfoPage |
销售端 |
✅ |
基本信息查看 uni-card |
| 🔴 高 |
sales_changePasswordPage |
销售端 |
✅ |
修改密码 uni-card |
| 🔴 高 |
dispatch_basicInfoPage |
调度端 |
✅ |
基本信息查看 uni-card |
| 🔴 高 |
dispatch_changePasswordPage |
调度端 |
✅ |
修改密码 uni-card |
| 🔴 高 |
construction_basicInfoPage |
施工端 |
✅ |
个人信息编辑 uni-card |
| 🔴 高 |
construction_changePasswordPage |
施工端 |
✅ |
修改密码 uni-card |
| 🟡 中 |
messageListPage |
销售端 |
✅ |
消息分类筛选 + 左滑删除 |
| 🟡 中 |
messageDetailPage |
销售端 |
✅ |
消息详情 + 标记已读 |
| 🟡 中 |
knowledgeListPage |
销售端 |
✅ |
行业知识分类 + 搜索 |
| 🟡 中 |
knowledgeDetailPage |
销售端 |
✅ |
知识内容 + 附件下载 |
| 🟡 中 |
dispatch_publishTaskPage |
调度端 |
✅ |
调度发布任务表单 |
| 🟡 中 |
dispatch_availableVehiclesPage |
调度端 |
✅ |
可用车辆筛选 + 统计 |
阶段二完成：12个缺失页面全部补充完成！
4.4 阶段三：高级功能 (✅ 已完成)
| 功能 |
优先级 |
技术方案 |
状态 |
备注 |
| 图片/视频上传 |
🔴 高 |
uni.chooseImage + 自定义ImageUploader组件 |
✅ |
任务详情/发布任务页面集成 |
| 地图定位 |
🟡 中 |
<map>组件 + uni.openLocation |
✅ |
任务详情展示项目位置 |
| 电子签名 |
🟡 中 |
Canvas手写签名 + uni.canvasToTempFilePath |
✅ |
施工完成客户签字 |
| 图表可视化 |
🟢 低 |
自定义Canvas图表组件(饼图/柱状图/折线图) |
✅ |
可视化大屏页面集成 |
| 实时定位 |
🟢 低 |
uni.getLocation |
⏳ 待接入真实设备 |
框架已就绪 |
| 消息推送 |
🟢 低 |
uni-push |
⏳ 需后端配合 |
框架已就绪 |
4.5 阶段三新增组件
| 组件 |
路径 |
功能 |
使用页面 |
| ImageUploader |
components/common/ImageUploader.vue |
图片选择/预览/删除 |
taskDetail, publishTask |
| MapView |
components/common/MapView.vue |
地图展示/导航 |
taskDetail |
| SignaturePad |
components/common/SignaturePad.vue |
Canvas手写签名 |
taskDetail |
| ChartView |
components/common/ChartView.vue |
饼图/柱状图/折线图 |
visualization |
五、后端接口对接
5.1 基础信息
- Base URL:
http://localhost:8080/api
- Auth Header:
Bearer {token}
- Response Format:
{ code: 200, msg: "success", data: T, timestamp }
5.2 接口列表
| 模块 |
接口 |
方法 |
说明 |
| 认证 |
/auth/login |
POST |
账号密码登录 |
| 项目 |
/project/list |
GET |
项目列表 |
| 项目 |
/project/{id} |
GET |
项目详情 |
| 项目 |
/project |
POST |
新增项目 |
| 任务 |
/task/list |
GET |
任务列表 |
| 任务 |
/task/{id} |
GET |
任务详情 |
| 任务 |
/task/{id}/status |
PUT |
更新任务状态 |
| 车辆 |
/vehicle/list |
GET |
车辆列表 |
| 人员 |
/staff/list |
GET |
人员列表 |
| 排班 |
/schedule/list |
GET |
排班列表 |
| 公告 |
/notice/list |
GET |
公告列表 |
| 统计 |
/dashboard/stats |
GET |
统计数据 |
5.3 角色映射
| 前端角色 |
后端 roleType |
说明 |
| sales |
front |
前端销售 |
| dispatch |
dispatch |
调度管理员 |
| construction |
construction |
施工人员 |
六、已知问题与注意事项
6.1 样式问题
- Tailwind CSS 编译 - 已解决：PostCSS 配置移至 vite.config.ts
- 小程序不支持
* 选择器 - global.scss 中避免使用
- uni-icons 字体 - 已配置 @font-face，全局可用
6.2 兼容性问题
- uni.navigateTo 页面栈限制为 10 层 - 首页使用
uni.reLaunch
- 图片上传 - 使用
uni.chooseImage 而非原生 input
- 本地存储 - 使用
uni.setStorageSync 而非 localStorage
6.3 性能优化
- 列表页使用分页加载
- 图片使用懒加载
- 避免在 v-for 中使用复杂表达式
七、Git 提交规范
feat: 新增功能
fix: 修复bug
docs: 文档更新
style: 样式调整
refactor: 代码重构
perf: 性能优化
test: 测试相关
chore: 构建/工具相关
八、开发人员
- 开发: AI Assistant
- 确认: Ethan
九、Bug修复记录
2026-06-22 用户反馈修复
| # |
问题 |
原因 |
修复方案 |
状态 |
| 1 |
底部TabBar图标显示为文字 |
缺少 uni-icons 字体类名 |
BottomNav.vue 添加 class="uni-icons" |
✅ 已修复 |
| 2 |
退出登录不生效 |
仅调用store.logout，未跳转页面 |
profile.vue 添加 uni.reLaunch 跳转到登录页 |
✅ 已修复 |
| 3 |
缺少顶部操作栏 |
部分子页面缺少 TopBar 组件 |
projectList.vue、profile.vue 添加 TopBar |
✅ 已修复 |
最后更新: 2026-06-22
原型页面总数: 54页 | 全部实现: ✅ 54/54
阶段一(页面重构): ✅ 完成 | 阶段二(补充页面): ✅ 完成 | 阶段三(高级功能): ✅ 完成
高级组件: ImageUploader / MapView / SignaturePad / ChartView | 实时定位/消息推送框架就绪
