📊 SmartCampus 项目结构说明

目录树

SmartCampus/
│
├── 📁 src/                          # 源代码主目录
│   │
│   ├── 📁 pages/                    # 页面模块（业务逻辑）
│   │   ├── 📁 index/                # 首页
│   │   │   ├── index.js             # 页面逻辑
│   │   │   ├── index.json           # 页面配置
│   │   │   ├── index.wxml           # 页面模板
│   │   │   └── index.wxss           # 页面样式
│   │   │
│   │   ├── 📁 login/                # 登录页面
│   │   │   └── (同上结构)
│   │   │
│   │   ├── 📁 alarm/                # 告警管理模块
│   │   │   ├── alarm.js/json/wxml/wxss
│   │   │   ├── detail.js            # 告警详情
│   │   │   └── detail.json/wxml/wxss
│   │   │
│   │   ├── 📁 chart/                # 图表展示模块
│   │   │   ├── chart.js/json/wxml/wxss
│   │   │   ├── detail.js
│   │   │   └── detail.json/wxml/wxss
│   │   │
│   │   ├── 📁 chart-detail/         # 图表详情（扩展页面）
│   │   │   └── chart-detail.js/json/wxml/wxss
│   │   │
│   │   ├── 📁 ticket/               # 工单管理模块
│   │   │   ├── list.js              # 工单列表
│   │   │   ├── detail.js            # 工单详情
│   │   │   ├── create.js            # 创建工单
│   │   │   └── (对应的 json/wxml/wxss)
│   │   │
│   │   └── 📁 profile/              # 个人中心
│   │       └── profile.js/json/wxml/wxss
│   │
│   ├── 📁 components/               # 可复用组件库
│   │   ├── 📁 chart-card/           # 图表卡片组件
│   │   │   ├── index.js             # 组件逻辑
│   │   │   ├── index.json           # 组件配置 {"component": true}
│   │   │   ├── index.wxml           # 组件模板
│   │   │   └── index.wxss           # 组件样式
│   │   │
│   │   ├── 📁 chart-selector/       # 图表选择器组件
│   │   │   └── (同上结构)
│   │   │
│   │   └── 📁 ec-canvas/            # ECharts 画布组件
│   │       ├── index.js
│   │       ├── ec-canvas.js         # 核心 canvas 逻辑
│   │       ├── wx-canvas.js         # 微信 Canvas 适配
│   │       ├── echarts.js           # ECharts 库
│   │       └── (json/wxml/wxss)
│   │
│   ├── 📁 services/                 # API 服务层
│   │   ├── api.js                   # API 接口定义（userApi, chartApi 等）
│   │   ├── api-config.js            # API 地址和配置（可扩展）
│   │   ├── request.js               # HTTP 请求拦截器（可扩展）
│   │   └── index.js                 # 服务入口（可扩展）
│   │
│   ├── 📁 utils/                    # 工具函数库
│   │   ├── common.js                # 通用工具
│   │   ├── date.js                  # 日期处理（可添加）
│   │   ├── storage.js               # 本地存储（可添加）
│   │   └── validators.js            # 验证函数（可添加）
│   │
│   ├── 📁 stores/                   # 全局状态管理（仅框架）
│   │   ├── user.js                  # 用户状态
│   │   ├── settings.js              # 应用设置状态
│   │   └── index.js                 # 状态管理入口
│   │
│   ├── 📁 constants/                # 常量定义（仅框架）
│   │   ├── api.js                   # API 常量
│   │   ├── config.js                # 应用配置常量
│   │   └── enums.js                 # 枚举定义
│   │
│   ├── 📁 styles/                   # 全局样式（仅框架）
│   │   ├── colors.wxss              # 颜色定义
│   │   ├── typography.wxss          # 排版规范
│   │   └── common.wxss              # 通用样式
│   │
│   ├── 📁 mockdata/                 # 测试/模拟数据
│   │   └── campus-energy.js         # 校园能源数据
│   │
│   ├── app.js                       # ⭐ 应用程序主文件（副本）
│   └── app.json                     # ⭐ 应用程序配置（副本）
│
│
├── 📁 docs/                         # 📚 项目文档
│   ├── DEVELOPMENT.md               # 开发指南
│   ├── API.md                       # API 文档
│   ├── PROJECT_STRUCTURE.md         # 本文件 - 结构说明
│   └── CHANGELOG.md                 # 版本更新日志
│
├── 📁 requirements/                 # 📋 需求文档（已迁移）
│   ├── 需求拆解/                   # 功能需求分解
│   ├── 方案/                        # 技术方案和设计
│   └── 团队流程/                    # 团队工作流程
│
├── ⚙️ 配置文件
│   ├── app.js                       # ⭐ 小程序入口（根目录）
│   ├── app.json                     # ⭐ 小程序配置（根目录）
│   ├── project.config.json          # 微信开发者工具配置
│   ├── project.private.config.json  # 私密配置（勿提交）
│   ├── package.json                 # NPM 项目配置
│   ├── .eslintrc.json               # ESLint 代码检查规则
│   ├── .prettierrc.json             # Prettier 代码格式化规则
│   ├── .gitignore                   # Git 忽略文件列表
│   └── .env.example                 # 环境变量模板
│
├── 📄 其他文件
│   ├── README.md                    # 项目概览
│   ├── package-lock.json            # NPM 依赖锁定文件
│   └── .git/                        # Git 版本控制目录

各层级功能说明

📄 Pages（页面层）

职责： 业务逻辑实现和 UI 交互

特点：

一个页面一个文件夹
包含四个文件：.js, .json, .wxml, .wxss
直接计入小程序大小，不可复用
对应应用的一条业务流程或功能模块

示例：

pages/alarm/
├── alarm.js         # 列表逻辑
├── detail.js        # 详情逻辑（嵌套路由）
└── (配置和样式文件)

🧩 Components（组件层）

职责： 提供可复用的 UI 和功能组件

特点：

一个组件一个文件夹
通常不用于业务逻辑，只处理展示和交互
可在多个页面和组件中复用
减少代码重复，提高开发效率

示例：

components/chart-card/
├── index.js         # Component 定义
├── index.json       # {"component": true}
├── index.wxml       # 模板（prop: title, value 等）
└── index.wxss       # 卡片样式

🔌 Services（服务层）

职责： 封装所有 API 调用和网络请求

特点：

统一管理 API 地址
处理请求和响应拦截
提供标准化的接口
便于 API 版本管理和切换

结构：

// api.js
export const userApi = { /* 用户相关接口 */ };
export const chartApi = { /* 图表相关接口 */ };
export const alarmApi = { /* 告警相关接口 */ };

🛠️ Utils（工具层）

职责： 提供通用的工具函数

示例工具：

formatDate() - 日期格式化
debounce() - 防抖
throttle() - 节流
deepClone() - 深拷贝
storage - 本地存储操作

使用方式：

import { formatDate, storage } from '/src/utils/common';

💾 Stores（状态管理）

职责： 管理全局应用状态

说明： 当前项目在 app.js 中使用 getApp().globalData 管理状态，此文件夹为扩展准备。

未来升级： 可迁移到状态管理库（如 Redux、Zustand 等）

⚙️ Constants（常量定义）

职责： 集中管理常量值

示例：

// constants/config.js
export const API_TIMEOUT = 5000;
export const MAX_RETRY = 3;

// constants/enums.js
export const ALARM_STATUS = {
  ACTIVE: 'active',
  RESOLVED: 'resolved',
  IGNORED: 'ignored'
};

🎨 Styles（全局样式）

职责： 定义应用级别的样式规范

内容：

颜色定义和调色板
排版规范和字体大小
通用的布局和间距规范

📋 Mockdata（模拟数据）

职责： 提供开发和测试时的模拟数据

用途：

开发阶段无法连接真实后端
前后端并行开发
测试和演示

文件类型说明

文件类型	用途	示例
`.js`	页面或组件的业务逻辑	`page.js`, `index.js`
`.json`	配置文件（页面样式、权限等）	`page.json`
`.wxml`	页面或组件的模板语言	类似 HTML
`.wxss`	样式文件	类似 CSS

JSON 文件分类

页面配置（page.json）：

{
  "navigationBarTitleText": "页面标题",
  "navigationBarBackgroundColor": "#00539C",
  "enablePullDownRefresh": true
}

组件配置（component.json）：

{
  "component": true,
  "usingComponents": {}
}

app.json 作用：

{
  "pages": [...],      // 注册所有页面
  "window": {...},     // 全局窗口配置
  "tabBar": {...}      // 底部导航栏配置
}

依赖关系图

┌─────────────────────────────────────┐
│           app.js (入口)              │
├─────────────────────────────────────┤
│  globalData / 初始化逻辑             │
└────────────┬────────────────────────┘
             │
             ├─→ Pages (各业务模块)
             │    ├─→ Services (API 调用)
             │    ├─→ Components (UI 组件)
             │    └─→ Utils (工具函数)
             │
             ├─→ Stores (全局状态) ← Utils
             │
             └─→ Constants (常量定义)

路径引用规范

✅ 推荐用法

// 使用相对路径或绝对路径
import { api } from '/src/services/api';
import { formatDate } from '/src/utils/common';
import { COLORS } from '/src/constants/config';

// 页面 JSON 中的引用
{
  "usingComponents": {
    "chart-card": "/src/components/chart-card/index"
  }
}

❌ 避免用法

// 避免深度相对路径
import { api } from '../../../../services/api';

文件大小和性能

小程序包大小限制

主包大小限制： 2MB (体验版)
分包大小限制： 2MB
总大小限制： 20MB

优化建议

减少图片体积
- 使用 WebP 格式
- 压缩图片大小
- 考虑使用 Base64 内联小图
代码分离
- 使用分包加载（subpackages）
- 延迟加载数据
组件优化
- 避免不必要的重新渲染
- 合理使用 wx:if vs hidden

扩展建议

Phase 1（当前）

✅ 基础结构搭建

✅ 页面模块化
✅ 组件复用库
✅ API 服务层
✅ 工具函数库

Phase 2（建议）

📋 增强开发体验

TypeScript 支持
单元测试框架
自动化构建流程
状态管理库集成

Phase 3（可选）

🚀 高级功能

云开发集成
分包加载
离线缓存策略
灰度发布系统

常见问题

Q: 为什么 app.js 和 app.json 同时在根目录和 src 下？ A: 微信小程序要求这两个文件在项目根目录。src 下的副本用于逻辑备份和版本控制。

Q: 如何在多个页面中共享数据？ A: 推荐使用 getApp().globalData 或独立的 store 文件。

Q: 组件和页面的区别是什么？ A: 组件可复用，页面不可复用；组件不占用路由，页面占用。

最后更新： 2026 年 2 月 5 日

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📊 SmartCampus 项目结构说明

目录树

各层级功能说明

📄 Pages（页面层）

🧩 Components（组件层）

🔌 Services（服务层）

🛠️ Utils（工具层）

💾 Stores（状态管理）

⚙️ Constants（常量定义）

🎨 Styles（全局样式）

📋 Mockdata（模拟数据）

文件类型说明

JSON 文件分类

依赖关系图

路径引用规范

✅ 推荐用法

❌ 避免用法

文件大小和性能

小程序包大小限制

优化建议

扩展建议

Phase 1（当前）

Phase 2（建议）

Phase 3（可选）

常见问题

FilesExpand file tree

PROJECT_STRUCTURE.md

Latest commit

History

PROJECT_STRUCTURE.md

File metadata and controls

📊 SmartCampus 项目结构说明

目录树

各层级功能说明

📄 Pages（页面层）

🧩 Components（组件层）

🔌 Services（服务层）

🛠️ Utils（工具层）

💾 Stores（状态管理）

⚙️ Constants（常量定义）

🎨 Styles（全局样式）

📋 Mockdata（模拟数据）

文件类型说明

JSON 文件分类

依赖关系图

路径引用规范

✅ 推荐用法

❌ 避免用法

文件大小和性能

小程序包大小限制

优化建议

扩展建议

Phase 1（当前）

Phase 2（建议）

Phase 3（可选）

常见问题