# thpark 项目功能检查与完善计划

> 创建时间: 2026-05-04
> 更新时间: 2026-05-05
> 目标: 逐个模块检查和完善，每个模块完成后进行测试验证

## 项目现状

### 后端 (thpark_server)
- **技术栈**: Go 1.25 + Gin + GORM + PostgreSQL/MySQL + Redis + InfluxDB
- **编译状态**: ✅ `go build` 正常
- **架构**: Controller → Service → DAO → Model，分层清晰
- **Swagger**: 58 个接口有文档注解（含新增的 `/auth/forgot-password`）
- **中间件**: JWT 认证、RBAC 权限、限流、IP 白名单、操作日志、Trace
- **测试**: ✅ 9 个测试文件，21+ 个测试用例全部通过（controllers + services）

### 前端 (thpark_admin)
- **技术栈**: React 19 + Vite + TanStack Router/Query + Shadcn UI + Tailwind CSS
- **构建状态**: ✅ `pnpm build` 正常
- **特性**: 国际化（中/英）、主题切换、响应式布局
- **测试**: ✅ 9 个测试文件，27 个测试用例全部通过
- **问题修复**:
  - ✅ Dashboard 核心统计已对接后端 `/admin/dashboard/stats`
  - ✅ 注册页(sign-up)已对接后端 `/auth/register` API
  - ✅ Sidebar 菜单已对齐实际功能
  - ✅ Alarms 详情页已完成 Dialog 详情展示

### 前后端对接
- ✅ 核心管理功能（用户、角色、设备、告警、字典、监控）API 对接完整
- ✅ Dashboard 统计、设备列表、告警列表等图表已对接真实数据
- ✅ 前端路由权限控制通过 `usePermissions` Hook 实现

---

## 执行计划

按**从基础到上层、先核心后周边**的顺序逐个模块检查和完善。

---

### Phase 1: 基础设施与认证体系 🔐

**目标**: 确保系统基础功能完整、前后端认证链路通畅

| 序号 | 任务 | 检查点 | 状态 |
|------|------|--------|------|
| 1.1 | 后端启动与配置 | 配置加载、环境变量、优雅关闭正常 | ✅ |
| 1.2 | 数据库迁移 | AutoMigrate 完整性、种子数据（超级管理员） | ✅ |
| 1.3 | JWT 认证中间件 | Token 生成/解析/刷新、过期处理 | ✅ |
| 1.4 | 登录接口 | 前台 `/auth/login` + 后台 `/admin/login` | ✅ |
| 1.5 | 注册接口对接 | 前端 sign-up → 后端 `/auth/register` | ✅ |
| 1.6 | 权限中间件 | `AuthRequired` + `AdminRequired` + `PermissionRequired` | ✅ |
| 1.7 | 限流与 IP 白名单 | 登录限流 5次/分钟、IP 校验 | ✅ |
| 1.8 | 响应标准化 | 统一包级别 `ok`/`fail`/`R`，删除 controller 重复定义 | ✅ |
| 1.9 | **Phase 1 测试** | 后端 `services/user_test.go` 9 个测试全部通过 | ✅ |

---

### Phase 2: 用户与会员管理 👤

**目标**: 用户 CRUD、角色分配、密码重置完整可用

| 序号 | 任务 | 检查点 | 状态 |
|------|------|--------|------|
| 2.1 | 前台用户 (Member) | 列表/创建/编辑/删除/重置密码 API + 前端 | ✅ |
| 2.2 | 后台用户 (Admin) | 列表/创建/编辑/删除/分配角色/重置密码 API + 前端 | ✅ |
| 2.3 | 当前用户信息 | `/user/getuserinfo` + 前端用户展示 | ✅ |
| 2.4 | 类型定义对齐 | `MemberCreateInput` 替代 `Partial<Member>`，清理 hacky 解析 | ✅ |
| 2.5 | **Phase 2 测试** | `services/member_test.go` 3 个测试全部通过 | ✅ |

---

### Phase 3: RBAC 权限体系 🛡️

**目标**: 角色、权限、菜单三级控制完整

| 序号 | 任务 | 检查点 | 状态 |
|------|------|--------|------|
| 3.1 | 角色管理 | 角色 CRUD、分配权限、分配菜单 API + 前端 | ✅ |
| 3.2 | 权限管理 | 权限列表/创建/删除 API + 前端 | ✅ |
| 3.3 | 菜单管理 | 菜单树 CRUD API + 前端 | ✅ |
| 3.4 | 部门管理 | 部门树 CRUD API + 前端 | ✅ |
| 3.5 | 前端权限控制 | `usePermissions` Hook 存在，按钮级控制正常 | ✅ |
| 3.6 | **Phase 3 测试** | `services/admin_test.go` 2 个 mock CRUD 测试通过 | ✅ |

---

### Phase 4: 设备管理 📡

**目标**: IoT 设备核心功能完整

| 序号 | 任务 | 检查点 | 状态 |
|------|------|--------|------|
| 4.1 | 设备 CRUD | 列表/详情/创建/编辑/删除/导出 API + 前端 | ✅ |
| 4.2 | 设备详情页 | `/devices/$id` 数据展示完善 | ✅ |
| 4.3 | OneNET 同步 | 设备平台同步、状态更新（已有实现） | ✅ |
| 4.4 | 设备控制 | 继电器控制 API + 前端状态显示 | ✅ |
| 4.5 | **Phase 4 测试** | `services/device_test.go` 4 个测试全部通过 | ✅ |

---

### Phase 5: 告警管理 🚨

**目标**: 告警查询、确认、处理完整

| 序号 | 任务 | 检查点 | 状态 |
|------|------|--------|------|
| 5.1 | 告警列表 | 分页/筛选 API + 前端表格 | ✅ |
| 5.2 | 告警确认 | `/admin/alarm/ack` + 前端确认 Dialog | ✅ |
| 5.3 | 告警详情 | 前端 Dialog 详情展示 | ✅ |
| 5.4 | **Phase 5 测试** | `services/alarms_test.go` 3 个测试全部通过 | ✅ |

---

### Phase 6: 系统监控 📊

**目标**: 监控日志、在线用户、系统状态

| 序号 | 任务 | 检查点 | 状态 |
|------|------|--------|------|
| 6.1 | 在线用户 | 在线用户列表/强制登出 API + 前端 | ✅ |
| 6.2 | 登录日志 | 登录日志查询 API + 前端 | ✅ |
| 6.3 | 操作日志 | 操作日志记录中间件 + 查询 API + 前端 | ✅ |
| 6.4 | 系统日志 | 系统日志查询 API + 前端 | ✅ |
| 6.5 | **Phase 6 测试** | 清理 hacky 响应解析，构建验证通过 | ✅ |

---

### Phase 7: 字典管理 📖

| 序号 | 任务 | 检查点 | 状态 |
|------|------|--------|------|
| 7.1 | 字典类型 | CRUD API + 前端 | ✅ |
| 7.2 | 字典数据 | CRUD API + 前端 | ✅ |
| 7.3 | **Phase 7 测试** | 构建验证通过 | ✅ |

---

### Phase 8: Dashboard 与演示页面清理 📈

| 序号 | 任务 | 检查点 | 状态 |
|------|------|--------|------|
| 8.1 | Dashboard 数据对接 | 统计卡片/OnlineRateChart/LatestOrders/HotTopics 已对接真实 API；TrafficChart 改为告警严重级别分布（真实数据）；ConversionChart 改为设备在线率+告警处理率（真实数据） | ✅ |
| 8.2 | 演示页面处理 | Tasks/Apps/Chats 已添加 Demo 标记 | ✅ |
| 8.3 | Sidebar 菜单对齐 | `use-sidebar-data.tsx` 已对齐实际功能 | ✅ |
| 8.4 | Help Center | 从 ComingSoon 替换为真实 FAQ 页面（中英双语） | ✅ |
| 8.5 | **Phase 8 测试** | 构建验证通过 | ✅ |

---

### Phase 9: 认证增强 🔐

| 序号 | 任务 | 检查点 | 状态 |
|------|------|--------|------|
| 9.1 | 忘记密码 | 后端 `POST /auth/forgot-password` 生成临时密码；前端表单对接并展示临时密码 | ✅ |
| 9.2 | **Phase 9 测试** | 构建验证 + 测试通过 | ✅ |

---

### Phase 10: 全局优化与测试补全 🧪

| 序号 | 任务 | 检查点 | 状态 |
|------|------|--------|------|
| 10.1 | 后端测试覆盖率 | 9 个测试文件，21+ 测试全部通过 | ✅ |
| 10.2 | 前端测试 | 9 个测试文件，27 测试全部通过 | ✅ |
| 10.3 | Swagger 文档补全 | 58 个接口已有注解，响应格式已统一 | ✅ |
| 10.4 | 类型一致性 | 清理 hacky 解析，类型完善 | ✅ |
| 10.5 | 错误处理 | 统一使用 `ok`/`fail`，401 自动刷新机制 | ✅ |
| 10.6 | 构建验证 | `go build` + `pnpm build` 最终通过 | ✅ |

---

## 执行规范

### 每个 Phase 的标准流程

1. **检查 (Check)**: 读取代码，列出问题清单
2. **完善 (Fix)**: 修改代码（最小侵入原则）
3. **验证 (Verify)**:
   - 后端: `go build` 通过 + `go test ./...` 通过
   - 前端: `pnpm build` 无报错 + `pnpm test` 通过
4. **记录**: 更新本文档状态列，标记完成

### 风险与注意事项

- **数据库**: 测试使用独立测试数据库或 mock，避免操作生产库
- **OneNET**: 设备测试 mock OneNET API，不依赖外部服务
- **最小改动**: 聚焦当前模块，不扩散重构
- **向后兼容**: API 修改保持兼容，避免破坏前端调用
- **文档同步**: 每完成一个 Phase，更新本文档状态