# 文件清单与说明

## 📂 根目录文件

### 配置文件

| 文件 | 说明 |
|------|------|
| `package.json` | NPM 项目配置和依赖 |
| `vite.config.js` | Vite 构建配置 |
| `.env.example` | 环境变量示例 |
| `.env` | 环境变量（本地开发） |
| `.gitignore` | Git 忽略配置 |
| `index.html` | SPA 应用入口 |

### 源代码

| 文件夹 | 说明 |
|--------|------|
| `src/` | 源代码目录 |
| `dist/` | 生产构建输出 (执行 `npm run build` 生成) |
| `node_modules/` | 项目依赖 (执行 `npm install` 生成) |

### 后端示例

| 文件 | 说明 |
|------|------|
| `server-example.js` | Node.js + Express 后端示例 |

## 📁 src/ 目录详解

### `src/main.js`
- **用途**: Vite 应用入口点
- **功能**: 导入应用主逻辑和样式，初始化应用
- **关键**: 
  - 导入 `initApp` 从 `./js/app.js`
  - 导入全局样式
  - 监听 `DOMContentLoaded` 事件

```javascript
import { initApp } from './js/app.js';
import './styles/main.css';

document.addEventListener('DOMContentLoaded', initApp);
```

### `src/js/app.js` ⭐
- **用途**: 应用主逻辑和核心业务
- **关键函数**:
  - `initApp()` - 应用初始化入口
  - `handleAuthCallback()` - 处理 OAuth 回调
  - `handleUnauthorized()` - 处理未授权状态
  - `displayUserInfo()` - 显示用户信息
  - `handleGetCode()` - 处理获取密码
- **关键变量**:
  - `oauth` - OAuth 客户端实例
  - `apiClient` - HTTP 客户端实例
- **核心流程**:
  1. 初始化 OAuth 客户端
  2. 检查是否有授权码
  3. 根据认证状态显示相应 UI

### `src/js/wechat-oauth.js` 🔐
- **用途**: 企业微信 OAuth 2.0 客户端
- **主要类**: `WeChatOAuth`
- **关键方法**:
  - `getAuthUrl()` - 获取授权链接
  - `getAuthCode()` - 从 URL 获取授权码
  - `exchangeCodeForUserInfo(code)` - 交换用户信息
  - `getUserInfo()` - 获取缓存的用户信息
  - `isAuthorized()` - 检查是否已授权
  - `clearUserInfo()` - 清除用户信息
- **状态管理**: sessionStorage

### `src/js/wecom-config.js` ⚙️
- **用途**: 企业微信应用配置
- **导出**: `WECOM_CONFIG` 对象
- **必需字段**:
  - `corpId` - 企业 ID
  - `agentId` - 应用 ID
  - `redirectUri` - OAuth 回调地址
  - `apiBaseUrl` - API 基础路径
- **修改**: 根据实际应用填入

### `src/js/api-client.js` 🌐
- **用途**: HTTP 客户端和 API 通信
- **主要类**: `ApiClient`
- **关键方法**:
  - `get(endpoint)` - GET 请求
  - `post(endpoint, data)` - POST 请求
  - `getUserInfoByCode(code)` - 获取用户信息
  - `getWeChatUserDetail(userId)` - 获取用户详情
  - `verifyUserPermission(userId)` - 验证权限
- **特性**: 自动错误处理和响应解析

### `src/js/utils.js` 🛠️
- **用途**: 通用工具函数库
- **导出函数**:
  - `getHistoryFromStorage()` - 获取历史记录
  - `saveHistoryToStorage(history)` - 保存历史记录
  - `formatDateTime(date)` - 日期格式化
  - `isValid(expiryTime)` - 检查是否有效
  - `getRemainingTime(expiryTime)` - 获取剩余时间
  - `generateCode()` - 生成验证码
  - `generatePassword()` - 生成密码
  - `showMessage(message, type)` - 显示提示消息
  - `copyToClipboard(text)` - 复制到剪贴板
- **用途**: 复用最频繁的业务逻辑

### `src/styles/main.css` 🎨
- **用途**: 全局样式和响应式设计
- **主要样式类**:
  - `.container` - 容器
  - `.header-card` - 头部卡片
  - `.form-input` - 输入框
  - `.btn-primary` - 主按钮
  - `.history-table` - 历史表格
  - `.auth-prompt` - 授权提示
- **响应式断点**:
  - 768px - 平板
  - 480px - 手机
  - 360px - 小屏手机

## 📄 根目录文档文件

| 文件 | 内容 | 用途 |
|------|------|------|
| `README_VITE.md` | 项目总体介绍 | 项目概览 |
| `WECOM_INTEGRATION_GUIDE.md` | 集成步骤和故障排查 | 实现指南 |
| `WECOM_OAUTH_GUIDE.md` | OAuth 后端实现 | 后端参考 |
| `PROJECT_SUMMARY.md` | 项目完成总结 | 项目总结 |
| `QUICK_START.md` | 快速参考 | 快速查阅 |
| `FILE_INVENTORY.md` | 本文件 | 文件说明 |

## 🔄 数据流向

```
用户输入 (input)
    ↓
验证 (validate)
    ↓
业务逻辑 (app.js)
    ↓
API 调用 (api-client.js)
    ↓
后端处理 (server-example.js)
    ↓
数据返回 (response)
    ↓
存储 (localStorage/sessionStorage)
    ↓
显示 (UI update)
```

## 🔐 认证流程详解

```
client/index.html
    ↓
wechat-oauth.js (getAuthCode)
    ↓
[检查 URL 中的 code 参数]
    ├─ 如果有 code → exchangeCodeForUserInfo
    ├─ 如果无 code → getAuthUrl (重定向)
    └─ 如果已授权 → getUserInfo (sessionStorage)
    ↓
app.js (displayUserInfo)
    ↓
UI 显示用户信息
```

## 📊 模块依赖关系

```
main.js
  ├── app.js
  │   ├── wechat-oauth.js
  │   ├── api-client.js
  │   ├── wecom-config.js
  │   └── utils.js
  └── styles/main.css

server-example.js
  ├── axios (HTTP)
  ├── dotenv (配置)
  └── express (框架)
```

## 🚀 构建输出

执行 `npm run build` 后生成 `dist/` 目录：

```
dist/
├── index.html          # 优化后的 HTML
├── assets/
│   ├── index-xxx.js    # 打包后的 JavaScript
│   └── index-xxx.css   # 打包后的 CSS
└── (其他资源)
```

## ✅ 完整性检查表

使用此清单确保所有文件都已配置：

- [ ] `src/js/wecom-config.js` - 已填入企业 ID 和 AgentID
- [ ] `.env` - 已创建和配置
- [ ] `WECOM_CORP_ID` - 已设置
- [ ] `WECOM_APP_SECRET` - 已设置
- [ ] 企业微信后台 - 已配置回调地址
- [ ] 企业微信后台 - 已添加可信域名
- [ ] `server-example.js` - 已根据需要自定义
- [ ] HTTPS - 已配置
- [ ] 防火墙 - 已允许必要的端口

## 🔍 常见文件修改

### 添加新的 API 端点

1. 在 `server-example.js` 中添加路由
2. 在 `src/js/api-client.js` 中添加对应方法
3. 在 `src/js/app.js` 中调用方法

### 修改样式

1. 编辑 `src/styles/main.css`
2. Vite 会自动热更新

### 添加新功能

1. 创建新的 `.js` 文件在 `src/js/`
2. 在 `src/js/app.js` 中导入
3. 调用相应函数

### 自定义用户信息显示

编辑 `src/js/app.js` 中的 `displayUserInfo()` 函数

## 📦 依赖说明

### 前端依赖

仅有 Vite (开发依赖)：
```json
{
  "devDependencies": {
    "vite": "^5.0.0"
  }
}
```

**特点**: 零运行时依赖，轻量级应用

### 后端依赖 (可选)

如使用 `server-example.js`:
```bash
npm install express axios cors dotenv morgan
```

## 🎯 文件使用场景

| 场景 | 涉及文件 |
|------|---------|
| 用户登录 | app.js, wechat-oauth.js |
| 获取用户信息 | api-client.js, server-example.js |
| 管理密码 | app.js, utils.js |
| UI 显示 | main.css, index.html |
| 配置 | wecom-config.js, .env |

---

**此清单定期更新以保持准确性**

最后更新: 2025年12月9日