# 清道夫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)

在任意页面/组件中使用：
```html
<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
```html
<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
```html
<uni-card title="卡片标题" extra="额外信息" icon="uniui-flag-filled">
  <view>卡片内容</view>
  <template #footer>
    <button>操作按钮</button>
  </template>
</uni-card>
```

#### uni-segmented-control (顶部Tab栏)
```html
<uni-segmented-control 
  :current="currentIndex" 
  :values="['全部', '待办', '已完成']"
  style-type="text"
  active-color="#4f8ef7"
  @clickItem="onTabChange"
/>
```

#### uni-swipe-action (左滑删除)
```html
<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 样式问题

1. **Tailwind CSS 编译** - 已解决：PostCSS 配置移至 vite.config.ts
2. **小程序不支持 `*` 选择器** - global.scss 中避免使用
3. **uni-icons 字体** - 已配置 @font-face，全局可用

### 6.2 兼容性问题

1. **uni.navigateTo** 页面栈限制为 10 层 - 首页使用 `uni.reLaunch`
2. **图片上传** - 使用 `uni.chooseImage` 而非原生 input
3. **本地存储** - 使用 `uni.setStorageSync` 而非 localStorage

### 6.3 性能优化

1. 列表页使用分页加载
2. 图片使用懒加载
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 | 实时定位/消息推送框架就绪*
