JPwise-docs

Appearance

JPwise-Web 最佳实践 - Claude Code ​

🎯 代码规范最佳实践 ​

命名规范 ​

javascript
// ✅ 好的命名
const userList = [];
const isLoading = false;
const handleUserSelect = () => {};

// ❌ 避免的命名  
const list1 = [];
const flag = false;
const doSth = () => {};

组件结构规范 ​

vue
<template>
  <!-- 模板内容简洁，逻辑在 script 中处理 -->
</template>

<script>
// 导入顺序：第三方库 → 组件 → 工具函数
import { mapState } from 'vuex'
import CustomComponent from './CustomComponent'
import { formatDate } from '@/utils'

export default {
  name: 'PageName',  // 组件名称
  components: { CustomComponent },
  mixins: [listMixin],  // 必须使用项目 mixin
  data() {
    return {
      // 数据定义
    }
  },
  computed: {
    ...mapState(['user'])
  },
  methods: {
    // 方法定义
  }
}
</script>

🚀 性能优化最佳实践 ​

列表页面优化 ​

javascript
// ✅ 正确的列表配置
data() {
  return {
    listQuery: {
      currentPage: 1,
      pageSize: 20,        // 合理的分页大小
      sort: 'desc',
      sidx: 'CREATEDATE'
    },
    query: {
      $LK$NAME: '',        // 使用查询操作符
      $EQ$STATUS: ''
    }
  }
}

表单性能优化 ​

javascript
// ✅ 使用 v-show 而不是 v-if（频繁切换）
<el-form-item v-show="showAdvanced" label="高级选项">

// ✅ 延迟加载大量选项数据
async loadOptions() {
  if (!this.optionsLoaded) {
    this.options = await api.getOptions();
    this.optionsLoaded = true;
  }
}

🔧 API 调用最佳实践 ​

统一 API 调用模式 ​

javascript
// ✅ 正确的 API 文件结构
import { doGet, doPost, doDelete } from '@/api/basic'

// 统一的方法命名
export function getList(data) {
  return doGet('/api/module/list', data)
}

export function saveData(data) {
  return doPost('/api/module/save', data)
}

export function deleteData(data) {
  return doDelete('/api/module/delete', data)
}

错误处理 ​

javascript
// ✅ 统一错误处理
try {
  const result = await api.getData()
  // 处理成功结果
} catch (error) {
  console.error('API调用失败:', error)
  this.$message.error('操作失败，请重试')
}

🎨 界面交互最佳实践 ​

弹窗使用规范 ​

javascript
// ✅ 标准弹窗调用
openWindow({
  url: "views/basic/dynamicModel/list/Form",
  title: "数据编辑",
  width: "800px",
  data: {
    TmplCode: this.tmplCode,  // 确保有效
    formType: 2,              // 使用配置模式
    id: row.id                // 编辑时传 ID
  },
  onDestroy: {
    confirm: ({ data }) => {
      this.$message.success('操作成功')
      this.refresh()          // 刷新父页面
    }
  }
})

表单操作规范 ​

javascript
// ✅ 表单脚本中的标准操作
// onLoad 事件
setFormData("FIELD_NAME", "默认值")
setShowOrHide("FIELD_NAME", true)
setRequired("FIELD_NAME", true)

// 根据权限控制显示
if (this.jnpf.hasFormP('FIELD_CODE')) {
  setShowOrHide("FIELD_NAME", true)
}

🔐 权限控制最佳实践 ​

页面级权限 ​

javascript
// ✅ 在 mixin 中统一处理
mixins: [btnPermission],

computed: {
  ...mapGetters(['buttonAuthList'])
}

字段级权限 ​

javascript
// ✅ 表单字段权限控制
if (this.jnpf.hasFormP('SALARY_FIELD')) {
  setShowOrHide("SALARY", true)
} else {
  setShowOrHide("SALARY", false)
}

📱 响应式设计最佳实践 ​

CSS 响应式写法 ​

scss
// ✅ 移动端适配
.data-table {
  @media (max-width: 768px) {
    font-size: 12px;
    
    .el-table__cell {
      padding: 8px 4px;
    }
  }
}

组件适配 ​

javascript
// ✅ 根据设备类型调整
computed: {
  isMobile() {
    return this.jnpf.isPC() === false
  }
},

data() {
  return {
    dialogWidth: this.isMobile ? '95%' : '800px'
  }
}

🔍 调试和测试最佳实践 ​

开发环境调试 ​

javascript
// ✅ 条件调试输出
if (process.env.NODE_ENV === 'development') {
  console.log('Debug Info:', {
    formData,
    userState,
    flowTaskInfo
  })
}

生产环境错误监控 ​

javascript
// ✅ 全局错误处理
Vue.config.errorHandler = (err, vm, info) => {
  console.error('Vue Error:', err, info)
  // 发送到监控系统
}

📚 文档和注释最佳实践 ​

组件文档 ​

javascript
/**
 * 用户选择组件
 * @props {Array} value - 已选用户 ID 数组
 * @props {Boolean} multiple - 是否多选
 * @props {Array} ableIds - 可选用户 ID 范围
 * @emit {Function} input - 选择变化事件
 */
export default {
  name: 'UserSelect',
  // ...
}

复杂逻辑注释 ​

javascript
// ✅ 关键业务逻辑加注释
// 根据流程状态判断字段是否可编辑
if (flowTaskInfo.thisStepCode === 'approval') {
  // 审批节点：只有审批人可以编辑审批意见
  setDisabled("APPROVAL_COMMENT", !isApprover)
}

🚦 Git 提交最佳实践 ​

提交信息规范 ​

bash
# ✅ 清晰的提交信息
git commit -m "feat: 添加用户权限管理功能"
git commit -m "fix: 修复列表分页显示问题"
git commit -m "refactor: 重构API调用逻辑"
git commit -m "docs: 更新组件使用文档"

提交前检查 ​

bash
# 必须执行的检查
npm run lint        # 代码格式检查
npm run test:unit   # 单元测试
npm run build       # 构建验证

🎪 业务场景最佳实践 ​

流程表单处理 ​

javascript
// ✅ 流程表单标准处理
// onLoad 事件中
if (flowTaskInfo) {
  const { thisStepCode, taskOperates } = flowTaskInfo
  
  // 根据当前步骤设置字段状态
  if (thisStepCode === 'submit') {
    setRequired("REASON", true)
  } else if (thisStepCode === 'approval') {
    setShowOrHide("APPROVAL_SECTION", true)
  }
}

数据字典处理 ​

javascript
// ✅ 标准枚举处理
// 在列表中显示
:formatter="jnpf.tableDicFormat"

// 在脚本中转换
const statusText = this.jnpf.getEnumText(statusCode, statusEnumList)

最佳实践核心：规范统一 + 性能优化 + 错误处理 + 可维护性