# 铂林青少年视力筛查系统注意事项文档

## 开发注意事项

### 代码规范
1. 遵循UniApp开发规范
2. 统一使用Vuex进行状态管理
3. 组件命名采用帕斯卡命名法(PascalCase)
4. 变量命名采用驼峰命名法(camelCase)
5. CSS类名采用短横线分隔命名法(kebab-case)

### 项目结构规范
1. 页面文件统一放在[pages](file:///d:/work/bolinscreening/pages.json)目录下，每个页面作为一个独立文件夹
2. 公共组件放在[components](file:///d:/work/bolinscreening/components/u-charts/config-echarts.js)目录下
3. 公共资源（样式、工具函数等）放在[common](file:///d:/work/bolinscreening/common/utils/http.js)目录下
4. 静态资源放在[static](file:///d:/work/bolinscreening/static/h5/echarts.min.js)目录下

### 数据请求规范
1. 所有API请求需通过[common/apis](file:///d:/work/bolinscreening/common/apis/index.js)目录下的接口封装文件发起
2. 请求拦截器中统一处理token等认证信息
3. 响应拦截器中统一处理错误提示和异常情况

### 样式规范
1. 全局样式变量定义在[uni.scss](file:///d:/work/bolinscreening/uni.scss)中
2. 页面私有样式写在各自的样式文件中
3. 尽量使用flex布局实现响应式设计

## 实施部署注意事项

### 环境配置
1. 开发环境需要配置对应的API地址，在[env.js](file:///d:/work/bolinscreening/env.js)中切换
2. 不同环境的配置不应提交到代码仓库中，建议使用环境变量或配置文件忽略机制

### 发布流程
1. 确保所有功能测试通过后再进行发布
2. 先在测试环境中验证，再发布到生产环境
3. 发布前做好数据备份工作
4. 记录详细的发布日志和变更说明

### 版本控制
1. 严格按照Git分支模型进行开发和合并
2. 1.0U版本只在`master`/`develop`分支上操作
3. 1.0S版本只在`eye`/`eye-dev`分支上操作
4. 禁止跨版本分支合并操作
5. 每次提交需编写清晰的commit message

## 性能优化建议

### 图片资源优化
1. 使用适当的图片格式（jpg/png/webp）
2. 对大图进行压缩处理
3. 使用CDN加速静态资源加载

### 网络请求优化
1. 合理使用缓存机制减少重复请求
2. 对于频繁调用的接口增加防抖处理
3. 大数据量接口考虑分页加载

### 渲染性能优化
1. 长列表使用虚拟滚动技术
2. 避免不必要的组件重新渲染
3. 合理使用v-if和v-show指令

## 安全注意事项

### 数据安全
1. 敏感信息（如身份证号、手机号）需要脱敏显示
2. 所有网络请求必须使用HTTPS协议
3. 用户隐私数据不得非法泄露

### 认证鉴权
1. 前端存储的token需要设置合理的过期时间
2. 敏感操作需要二次验证
3. 接口访问需要校验用户权限

### 代码安全
1. 防止XSS攻击，对用户输入进行过滤和转义
2. 防止SQL注入，使用参数化查询
3. 避免在代码中硬编码敏感信息

## 常见问题及解决方案

### 编译问题
1. 如果遇到编译错误，请检查语法是否正确
2. 确认依赖包是否完整安装
3. 清除缓存后重新编译

### 运行时问题
1. 白屏问题可能由于JavaScript执行错误导致，需要检查控制台输出
2. 网络请求失败请检查API地址和网络连接状态
3. 页面渲染异常可能是数据格式不符合预期

### 兼容性问题
1. 在不同设备上测试确保显示效果一致
2. 注意微信小程序版本兼容性
3. 关注UniApp更新带来的兼容性变化

## 最佳实践

### 组件开发
1. 组件职责单一，提高复用性
2. 合理设计组件props和events
3. 组件内部状态尽量通过事件向上抛出

### 状态管理
1. 多个组件共享的状态放入Vuex中
2. 页面私有状态可使用组件内部data
3. 状态变更通过mutation进行，异步操作使用action

### 错误处理
1. 全局捕获未处理的异常
2. 网络请求错误需要友好提示用户
3. 记录关键操作的日志便于问题排查