ai-engineering-init 1.1.0

package/.claude/docs//345/211/215/347/253/257/345/274/200/345/217/221/346/214/207/345/215/227.md

@@ -0,0 +1,599 @@
+# 前端开发指南
+
+> **适用于**: 腾云智慧食堂管理系统前端项目
+
+最后更新: 2026-02-18（修正 API 接口规范、补充 auth.js 函数）
+
+---
+
+## 项目架构
+
+### 技术栈
+
+| 技术 | 版本 | 说明 |
+|------|------|------|
+| Vue | 2.7.16 | 核心框架 |
+| Element UI | 2.15.9 | UI 组件库 |
+| Vuex | 3.4.0 | 状态管理 |
+| Vue Router | 3.2.0 | 路由管理 |
+| ECharts | 5.4.1 | 图表库 |
+| VXE-Table | 3.13.18 | 高级表格 |
+| axios | 0.19.2 | HTTP 请求 |
+| Sass | - | CSS 预处理器 |
+
+### 目录结构
+
+```
+src/
+├── api/                    # API 接口定义
+│   ├── marketing.js        # 营销相关接口
+│   ├── order.js            # 订单相关接口
+│   └── ...
+├── assets/                 # 静态资源
+├── components/             # 公共组件
+├── directive/              # 自定义指令
+├── lang/                   # 国际化
+│   ├── zh/                 # 中文
+│   └── en/                 # 英文
+├── layout/                 # 布局组件
+├── leniu-components/       # 业务组件
+├── leniuview/              # 业务模块页面
+├── mixins/                 # 混入
+├── router/                 # 路由配置
+├── store/                  # Vuex 状态管理
+├── styles/                 # 全局样式
+├── utils/                  # 工具函数
+├── App.vue                 # 根组件
+├── main.js                 # 入口文件
+└── permission.js           # 路由权限控制
+```
+
+---
+
+## 开发规范
+
+### 组件开发规范
+
+#### 文件头部注释
+
+```vue
+<!--
+ * @Author: 作者名
+ * @Date: 2026-01-01 10:00:00
+ * @Description: 组件功能描述
+-->
+```
+
+#### 组件结构
+
+```vue
+<template>
+  <div class="component-name">
+    <!-- 模板内容 -->
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'ComponentName',
+  components: {},
+  props: {},
+  data() {
+    return {}
+  },
+  computed: {},
+  watch: {},
+  created() {},
+  mounted() {},
+  methods: {}
+}
+</script>
+
+<style lang="scss" scoped>
+.component-name {
+  // 样式
+}
+</style>
+```
+
+#### 列表页模板
+
+```vue
+<template>
+  <page-slot>
+    <!-- 搜索区域 -->
+    <collapse-search slot="search">
+      <template v-slot:outerCol>
+        <el-col :span="6">
+          <el-form-item :label="$t('名称')">
+            <el-input v-model="listQuery.name" clearable />
+          </el-form-item>
+        </el-col>
+      </template>
+      <el-button slot="operate" type="primary" @click="handleQuery">
+        {{ $t('action.query') }}
+      </el-button>
+    </collapse-search>
+
+    <!-- 操作按钮 -->
+    <el-button slot="tableTopLeft" type="primary" v-hasPerm="['xxx:add']">
+      {{ $t('新增') }}
+    </el-button>
+
+    <!-- 表格 -->
+    <el-table slot="table" :data="tableData" v-loading="loading">
+      <el-table-column prop="name" label="名称" />
+      <el-table-column label="操作">
+        <template slot-scope="{ row }">
+          <el-button type="text" @click="handleEdit(row)">编辑</el-button>
+        </template>
+      </el-table-column>
+    </el-table>
+  </page-slot>
+</template>
+
+<script>
+import { getList } from '@/api/xxx'
+import commonList from '../mixins/common-list'
+
+export default {
+  name: 'XxxList',
+  mixins: [commonList],
+  data() {
+    return {
+      listQuery: {
+        name: ''
+      }
+    }
+  },
+  methods: {
+    async getData() {
+      this.loading = true
+      try {
+        const res = await getList(this.listQuery)
+        this.tableData = res.data || []
+      } finally {
+        this.loading = false
+      }
+    }
+  }
+}
+</script>
+```
+
+---
+
+## API 接口规范
+
+> ⚠️ **重要**：本项目接口大量使用 POST（包括查询！），请求体统一使用 `dataObj` 包装结构。
+
+### dataObj 标准结构
+
+每个 API 文件顶部定义 `dataObj`，业务参数放在 `content` 字段中：
+
+```javascript
+// src/api/xxx.js
+import request from '@/utils/request'
+
+// ⭐ 每个 API 文件都必须定义 dataObj
+const dataObj = {
+  version: '1.0',
+  nonceStr: '1212fsadf',    // 拦截器自动替换
+  timestamp: '2020-4-21',   // 拦截器自动替换
+  signType: 'md5',
+  content: {},
+  sign: 'dafdsf'            // 拦截器自动计算
+}
+```
+
+### 标准接口写法（两种等价写法）
+
+```javascript
+// ✅ 写法一（推荐，简洁）：展开 dataObj，覆盖 content
+export function getList(data) {
+  return request({
+    url: '/api/v2/xxx/list',
+    method: 'post',
+    data: { ...dataObj, content: data || {} }
+  })
+}
+
+// ✅ 写法二（兼容，深拷贝）：适合需要多次修改对象的场景
+export function getDetail(data) {
+  const obj = JSON.parse(JSON.stringify(dataObj))
+  if (data) obj.content = data
+  return request({
+    url: '/api/v2/xxx/detail',
+    method: 'post',
+    data: obj
+  })
+}
+```
+
+### 各类操作的 URL 命名规律
+
+```javascript
+// 分页列表查询
+export function getPageList(data) {
+  return request({ url: '/api/v2/xxx/page', method: 'post', data: { ...dataObj, content: data || {} } })
+}
+
+// 全量列表查询（不分页）
+export function getList(data) {
+  return request({ url: '/api/v2/xxx/list', method: 'post', data: { ...dataObj, content: data || {} } })
+}
+
+// 新增
+export function add(data) {
+  return request({ url: '/api/v2/xxx/add', method: 'post', data: { ...dataObj, content: data || {} } })
+}
+
+// 修改
+export function update(data) {
+  return request({ url: '/api/v2/xxx/update', method: 'post', data: { ...dataObj, content: data || {} } })
+}
+
+// 删除
+export function del(data) {
+  return request({ url: '/api/v2/xxx/delete', method: 'post', data: { ...dataObj, content: data || {} } })
+}
+
+// 导出（responseType: 'blob'）
+export function exportData(data) {
+  return request({
+    url: '/api/v2/xxx/export',
+    method: 'post',
+    data: { ...dataObj, content: data || {} },
+    responseType: 'blob'
+  })
+}
+```
+
+### noLoading 参数
+
+适用于轮询、静默请求等不需要显示 Loading 的场景：
+
+```javascript
+export function getState(data) {
+  return request({
+    url: '/tcp/v1/machine/state',
+    method: 'post',
+    data: { ...dataObj, content: data || {} },
+    noLoading: true   // 不显示全屏 Loading
+  })
+}
+```
+
+### 禁止事项
+
+```javascript
+// ❌ 禁止：查询接口使用 GET + params（本项目不用这种写法）
+request({ url: '/xxx/list', method: 'get', params: query })
+
+// ❌ 禁止：直接传业务数据，不包 content
+request({ url: '/xxx', method: 'post', data: { name: '张三' } })
+
+// ❌ 禁止：使用 PUT/DELETE 方法（本项目全用 POST）
+request({ url: '/xxx/1', method: 'delete' })
+request({ url: '/xxx', method: 'put', data })
+```
+
+---
+
+## Vuex Store 规范
+
+### Store 模块结构
+
+```javascript
+// src/store/modules/xxx.js
+const state = {
+  list: [],
+  current: null,
+  loading: false
+}
+
+const mutations = {
+  SET_LIST: (state, list) => {
+    state.list = list
+  },
+  SET_CURRENT: (state, current) => {
+    state.current = current
+  },
+  SET_LOADING: (state, loading) => {
+    state.loading = loading
+  }
+}
+
+const actions = {
+  // 获取列表
+  async fetchList({ commit }, params) {
+    commit('SET_LOADING', true)
+    try {
+      const res = await getList(params)
+      commit('SET_LIST', res.data || [])
+      return res
+    } finally {
+      commit('SET_LOADING', false)
+    }
+  },
+
+  // 获取详情
+  async fetchDetail({ commit }, id) {
+    const res = await getDetail(id)
+    commit('SET_CURRENT', res.data)
+    return res
+  }
+}
+
+const getters = {
+  list: state => state.list,
+  current: state => state.current,
+  loading: state => state.loading
+}
+
+export default {
+  namespaced: true,
+  state,
+  mutations,
+  actions,
+  getters
+}
+```
+
+### 组件中使用 Store
+
+```javascript
+// 使用 mapState
+import { mapState, mapActions } from 'vuex'
+
+export default {
+  computed: {
+    ...mapState('xxx', ['list', 'loading'])
+  },
+  methods: {
+    ...mapActions('xxx', ['fetchList'])
+  },
+  mounted() {
+    this.fetchList()
+  }
+}
+```
+
+---
+
+## 权限控制
+
+### 权限指令
+
+```vue
+<!-- 按钮权限 -->
+<el-button v-hasPerm="['xxx:add']">新增</el-button>
+<el-button v-hasPerm="['xxx:edit']">修改</el-button>
+<el-button v-hasPerm="['xxx:remove']">删除</el-button>
+
+<!-- 角色权限 -->
+<el-button v-hasRole="['admin']">管理员按钮</el-button>
+```
+
+### 权限命名规范
+
+```
+模块:功能:操作
+
+示例：
+- marketing:price:add      营销计费规则新增
+- marketing:price:edit     营销计费规则修改
+- marketing:price:remove   营销计费规则删除
+- marketing:price:list     营销计费规则列表
+```
+
+---
+
+## 国际化
+
+### 使用方式
+
+```vue
+<template>
+  <el-button>{{ $t('action.query') }}</el-button>
+  <span>{{ $t('规则名称') }}</span>
+</template>
+```
+
+### 语言文件
+
+```javascript
+// src/lang/zh/xxx.js
+export default {
+  '规则名称': '规则名称',
+  '规则类型': '规则类型',
+  'action.query': '查询'
+}
+```
+
+---
+
+## 常用工具函数
+
+### request - HTTP 请求
+
+```javascript
+import request from '@/utils/request'
+
+// GET
+request({ url: '/api/xxx', method: 'get', params: {} })
+
+// POST
+request({ url: '/api/xxx', method: 'post', data: {} })
+```
+
+### auth - Token 与租户管理
+
+```javascript
+import {
+  getToken, setToken, removeToken,
+  getTenant, setTenant, removeTenant,
+  getCustEffId, setCustEffId,
+  checkMenu
+} from '@/utils/auth'
+
+// Token 操作（存储在 localStorage 的 'Admin-Token' 中）
+const token = getToken()
+setToken('new-token')
+removeToken()
+
+// 租户 ID 操作（存储在 localStorage 的 'MERCHANT-ID' 中）
+const tenantId = getTenant()
+setTenant('merchant-xxx')
+removeTenant()
+
+// 检查当前用户是否有某个路由权限
+const hasAccess = checkMenu('/marketing/price')
+```
+
+### format - 格式化
+
+```javascript
+import { formatDate, formatMoney } from '@/utils/format'
+
+formatDate(new Date(), 'YYYY-MM-DD')
+formatMoney(1234.56)
+```
+
+---
+
+## Vue 全局原型方法
+
+> 这些方法/属性在 `main.js` 挂载到 `Vue.prototype`，所有组件内可直接通过 `this.xxx` 调用。
+
+### 金额与数值处理
+
+```javascript
+// 分转元（保留2位小数，添加千分位）
+this.money(1234)          // '12.34'
+this.money(null)          // ''
+
+// 精确乘法（避免浮点误差）
+this.accMul(1.1, 100)     // 110
+this.accMul(price, 0.01)  // 分 → 元
+
+// 保留2位小数
+// 可通过 import { toDecimal2 } from '@/utils' 导入使用
+```
+
+### 时间格式化
+
+```javascript
+// parseTime(timestamp, format)
+this.parseTime(Date.now())                    // '2026-02-18 10:30:00'
+this.parseTime(Date.now(), '{y}-{m}-{d}')    // '2026-02-18'
+this.parseTime(Date.now(), '{h}:{i}:{s}')    // '10:30:00'
+```
+
+### 权限判断
+
+```javascript
+// $hasPerm - 代码级权限判断（对应模板中 v-hasPerm 指令）
+if (this.$hasPerm(['marketing:price:edit'])) {
+  // 有权限时执行
+}
+```
+
+### 其他原型方法
+
+```javascript
+// Lodash（完整版）
+this._                      // 等同于 import _ from 'lodash'
+this._.cloneDeep(obj)
+this._.debounce(fn, 300)
+
+// ECharts 实例
+this.$echarts               // 等同于 import * as echarts from 'echarts'
+
+// 环境判断
+this.isDevEnv               // true / false（开发环境）
+
+// 延迟
+await this.$sleep(1000)     // 等待 1 秒
+```
+
+### 输入校验（validators / inputRules）
+
+```javascript
+// 在 el-form 中使用
+:rules="{ name: [{ validator: validators.required, trigger: 'blur' }] }"
+
+// 输入框实时过滤（inputRules）
+<el-input @input="form.phone = inputRules.phone(form.phone)" />
+```
+
+---
+
+## 业务组件
+
+### leniu-page - 页面容器
+
+```vue
+<page-slot>
+  <collapse-search slot="search">...</collapse-search>
+  <el-button slot="tableTopLeft">操作按钮</el-button>
+  <el-table slot="table">...</el-table>
+</page-slot>
+```
+
+### leniu-form-dialog - 弹窗表单
+
+```vue
+<leniu-form-dialog
+  :visible.sync="visible"
+  :title="title"
+  @submit="handleSubmit"
+>
+  <el-form>
+    <!-- 表单内容 -->
+  </el-form>
+</leniu-form-dialog>
+```
+
+---
+
+## 开发命令
+
+```bash
+# 安装依赖
+npm install
+
+# 开发环境
+npm run dev
+
+# 生产构建
+npm run build:prod
+
+# 代码检查
+npm run lint
+```
+
+---
+
+## 后端 API 配置
+
+在 `src/store/index.js` 中配置后端 API 地址：
+
+```javascript
+const store = new Vuex.Store({
+  state: {
+    baseURL: 'http://192.168.x.x:58300'
+  }
+})
+```
+
+---
+
+## 注意事项
+
+1. **使用 Vue 2 语法**，非 Vue 3
+2. **使用 Vuex**，非 Pinia
+3. **使用 Element UI**，非 Element Plus
+4. **国际化使用 `$t()`** 函数
+5. **权限使用 `v-hasPerm`** 指令
+6. **样式使用 scoped** 避免污染