# 项目注意事项文档

## 1. 注意事项

### 1.1 技术注意事项

#### 兼容性问题
- 项目使用的 webpack-dev-server 版本较老（^2.9.1），而 Node.js 版本为 14.2.0，可能存在兼容性风险
- 旧版本 webpack-dev-server 对高版本 Node.js 支持不佳，建议升级或替换开发服务器

#### 命名规范问题
- 存在拼写错误的目录名：`Layoutileads1` 应为 `LayoutLeads1` 或类似命名
- 需要确认是否为笔误并在后续版本中修复

#### 代码质量问题
- 项目中存在两个相同的 README.md 内容重复，可能为冗余文件
- 建议清理冗余文件以保持项目整洁

#### 安全注意事项
- 敏感操作需验证 token 或 mobile 参数
- 避免 XSS 风险（注意 mixin 中的规则注入）
- 不应在前端暴露敏感接口密钥

### 1.2 性能注意事项

#### 加载性能
- 系统需支持移动端快速加载
- 使用 webpack 分离公共代码优化首屏性能
- 图片资源建议压缩处理

#### 浏览器兼容性
- 支持现代主流浏览器
- 不支持 IE <= 8 版本

### 1.3 业务注意事项

#### 参数处理
- 所有 URL 参数都需要进行合法性校验
- token 和 mobile 是互斥的身份验证方式
- topic_id 和 result_id 不能同时为空

#### 数据一致性
- 同一用户对同一 topic_id 只能有一份有效的表单结果
- 表单提交后不可修改，只能重新填写

## 2. 实施指南

### 2.1 环境搭建

#### 开发环境要求
1. 安装 Node.js 14.2.0
2. 安装 npm >=6.14.4 或 Yarn
3. 安装 Git（推荐）

#### 项目初始化步骤
1. 克隆项目到本地目录
2. 打开终端进入项目根目录
3. 安装依赖：
   ```bash
   yarn install
   ```
   或
   ```bash
   npm install
   ```

4. 启动本地开发服务器：
   ```bash
   npm run dev
   ```
   默认访问地址：http://localhost:8080

### 2.2 部署指南

#### 生产环境部署
1. 构建生产环境代码：
   ```bash
   npm run build
   ```

2. 查看打包分析报告（可选）：
   ```bash
   npm run build --report
   ```

3. 将 `dist/` 目录下的文件部署至 Web 服务器（如 Nginx、Apache）

#### 部署注意事项
- 确保服务器支持静态文件服务
- 配置正确的路径重定向以支持 Vue Router 的 history 模式
- 设置合适的缓存策略提高加载速度

## 3. 最佳实践

### 3.1 开发实践

#### 组件开发
- 优先使用现有的公共组件
- 遵循单一职责原则，每个组件只负责一个功能点
- 使用 mixin 复用校验规则和布局逻辑

#### 状态管理
- 合理划分 Vuex 模块（header、manager、user）
- 避免在组件中直接修改 store 数据
- 使用 getter 获取派生状态

#### 路由管理
- 利用路由守卫（`router/permission.js`）实现访问权限控制
- 合理组织路由结构，便于维护

#### HTTP 请求
- 通过 `api/index.js` 统一管理接口调用
- 使用 `utils/http` 封装的 axios 处理拦截和基础配置
- 对请求和响应进行适当的错误处理

### 3.2 Git 工作流实践

#### 分支管理
1. 严格按照版本分支策略执行：
   - 1.0U 版本：生产(master)、测试(develop)，只能 develop 合并到 master
   - 1.0S 版本：生产(eye)、测试(eye-dev)，只能 eye-dev 合并到 eye
   - 不同版本分支相互独立，不能相互合并

2. 功能开发流程：
   - 从测试分支创建功能分支
   - 在功能分支上进行开发
   - 提交 Pull Request/Merge Request 进行代码审查
   - 审查通过后合并回测试分支

#### 提交规范
- 使用清晰明确的提交信息
- 每次提交只包含一个功能点的变更
- 关联相关的任务或问题编号

### 3.3 代码质量实践

#### 代码审查要点
- 检查是否存在潜在的安全漏洞
- 确认代码符合项目编码规范
- 验证功能实现是否满足需求
- 检查是否有冗余或无用的代码

#### 性能优化建议
- 减少不必要的组件重新渲染
- 合理使用 computed 和 watch
- 对大列表进行虚拟滚动优化
- 压缩图片和其他静态资源

#### 测试建议
- 对核心业务逻辑编写单元测试
- 对复杂组件编写集成测试
- 进行跨浏览器兼容性测试
- 定期进行性能基准测试

## 4. 常见问题及解决方案

### 4.1 开发环境问题

#### 依赖安装失败
- 清除缓存后重新安装：`npm cache clean --force` 然后 `npm install`
- 确认 Node.js 版本是否匹配要求（14.2.0）

#### 启动失败
- 检查端口是否被占用，默认使用 8080 端口
- 确认配置文件是否正确

### 4.2 部署问题

#### 页面空白
- 检查构建过程是否有错误
- 确认服务器配置是否支持 Vue Router 的 history 模式

#### 静态资源加载失败
- 检查资源路径配置
- 确认服务器静态资源配置是否正确

### 4.3 业务逻辑问题

#### 表单验证不生效
- 检查 rules.js 中的验证规则配置
- 确认表单字段名称是否匹配

#### 数据加载异常
- 检查网络请求是否正常
- 确认参数传递是否正确
- 查看浏览器控制台错误信息