feat: 促销系统完善、发票页重构、前端中文化、订单表迁移及多项优化

前端：

- 发票页完整重构：智能按钮状态、防重复开票、空态引导、订单多选

- 全局中文化：Ant Design Vue locale配置、清除残留英文UI文本

- 新增关于我们、联系我们页面

- 首页活动专区、搜索页、Skill详情等多处优化

后端：

- 订单模块：新增original_amount/promotion_deduct_amount字段及DB迁移

- 促销系统：完善促销规则、过期任务、批量查询等

- 新增RateLimit注解及拦截器、CORS过滤器、Health检查接口

- Logback日志配置、points枚举修复等

frontend/.env.development

@@ -1,2 +1,2 @@
-# 开发环境 API 基础地址
+# 开发环境 API 基础地址（使用相对路径，由 Vite proxy 转发到后端）
-VITE_API_BASE_URL=http://localhost:8080/api/v1
+VITE_API_BASE_URL=/api/v1

frontend/src/App.vue

@@ -1,8 +1,11 @@
 <template>
+  <a-config-provider :locale="zhCN">
     <router-view />
+  </a-config-provider>
 </template>
 
 <script setup>
+import zhCN from 'ant-design-vue/es/locale/zh_CN'
 </script>
 
 <style>

frontend/src/components/SkillCard.vue

@@ -19,7 +19,7 @@
         <div class="meta-left">
           <span class="rating">
             <StarFilled />
-            {{ skill.rating }}
+            {{ skill.rating ? Number(skill.rating).toFixed(1) : '-' }}
           </span>
           <span class="downloads">{{ formatNumber(skill.downloadCount) }} 次下载</span>
         </div>

frontend/src/layouts/MainLayout.vue

@@ -115,13 +115,13 @@
     <footer class="main-footer">
       <div class="footer-content">
         <a-space :size="[24, 16]" wrap class="footer-links">
-          <a href="javascript:;">关于我们</a>
+          <router-link to="/about">关于我们</router-link>
-          <a href="javascript:;">帮助中心</a>
+          <router-link to="/help">帮助中心</router-link>
-          <a href="javascript:;">用户协议</a>
+          <router-link to="/terms">用户协议</router-link>
-          <a href="javascript:;">隐私政策</a>
+          <router-link to="/privacy">隐私政策</router-link>
-          <a href="javascript:;">联系我们</a>
+          <router-link to="/contact">联系我们</router-link>
         </a-space>
-        <p class="footer-copyright">© 2024 OpenClaw Skills. All rights reserved.</p>
+        <p class="footer-copyright">© 2024 OpenClaw Skills 版权所有</p>
       </div>
     </footer>
 

frontend/src/router/index.js

@@ -78,6 +78,18 @@ const routes = [
         component: () => import('@/views/legal/privacy.vue'),
         meta: { title: '隐私政策' }
       },
+      {
+        path: 'about',
+        name: 'About',
+        component: () => import('@/views/legal/about.vue'),
+        meta: { title: '关于我们' }
+      },
+      {
+        path: 'contact',
+        name: 'Contact',
+        component: () => import('@/views/legal/contact.vue'),
+        meta: { title: '联系我们' }
+      },
       {
         path: 'user',
         name: 'UserCenter',

frontend/src/service/apiService.js

@@ -231,6 +231,7 @@ export const adminApi = {
   auditSkill: (skillId, action, rejectReason) => api.post(`/admin/skills/${skillId}/audit`, null, { params: { action, rejectReason } }),
   offlineSkill: (skillId) => api.post(`/admin/skills/${skillId}/offline`),
   createSkill: (data) => api.post('/admin/skills/create', data),
+  updateSkill: (skillId, data) => api.put(`/admin/skills/${skillId}`, data),
   getOrders: (params) => api.get('/admin/orders', { params }),
   getOrderDetail: (orderId) => api.get(`/admin/orders/${orderId}`),
   getRefunds: (params) => api.get('/admin/refunds', { params }),

frontend/src/stores/admin.js

@@ -1,6 +1,6 @@
 import { defineStore } from 'pinia'
 import { adminApi } from '@/service/apiService'
-import { getErrorMessage } from '@/service/dataAdapter'
+import { getErrorMessage, normalizeOrder } from '@/service/dataAdapter'
 
 const ADMIN_TOKEN_KEY = 'admin_token'
 const ADMIN_USER_KEY = 'admin_user'
@@ -91,8 +91,9 @@ export const useAdminStore = defineStore('admin', {
     async loadOrders(params = {}) {
       try {
         const result = await adminApi.getOrders(params)
-        this.orders = result.data?.records || []
+        const raw = result.data?.records || []
-        return result.data
+        this.orders = raw.map(normalizeOrder)
+        return { ...result.data, records: this.orders }
       } catch {
         this.orders = []
         return { records: [], total: 0 }
@@ -147,6 +148,15 @@ export const useAdminStore = defineStore('admin', {
       }
     },
 
+    async updateSkill(skillId, data) {
+      try {
+        const result = await adminApi.updateSkill(skillId, data)
+        return { success: true, data: result.data, message: 'Skill更新成功' }
+      } catch (error) {
+        return { success: false, message: getErrorMessage(error, 'Skill更新失败') }
+      }
+    },
+
     async approveSkill(skillId) {
       try {
         await adminApi.auditSkill(skillId, 'approve')

frontend/src/stores/skill.js

@@ -151,7 +151,8 @@ export const useSkillStore = defineStore('skill', {
       const query = mapFiltersToQuery(this.filters)
       const result = await skillApi.list(query)
       this.searchResults = normalizePageRecords(result.data, normalizeSkill)
-      return this.searchResults
+      const total = result.data?.total ?? result.data?.totalCount ?? this.searchResults.length
+      return { records: this.searchResults, total }
     },
 
     setFilters(filters) {

frontend/src/views/admin/comments.vue

@@ -55,15 +55,7 @@
           >
             删除
           </a-button>
-          <a-tooltip v-else title="恢复功能暂未开放">
+          <span v-else class="text-muted">-</span>
-            <a-button
-              type="link"
-              size="small"
-              disabled
-            >
-              恢复
-            </a-button>
-          </a-tooltip>
         </template>
       </a-table-column>
     </a-table>

frontend/src/views/admin/community.vue

@@ -117,7 +117,7 @@ const loadTemplates = async () => {
   templatesLoading.value = true
   try {
     const res = await adminApi.getCouponTemplates({ pageNum: 1, pageSize: 100 })
-    templates.value = (res.data?.records || []).filter(t => t.status === 'active')
+    templates.value = (res.data?.records || []).filter(t => t.status === 'active' || t.status === 'draft')
   } catch { /* ignore */ } finally {
     templatesLoading.value = false
   }

frontend/src/views/admin/promotions.vue

@@ -154,7 +154,7 @@
         <div v-for="(skill, index) in form.skills" :key="index" class="skill-row">
           <a-row :gutter="12" align="middle">
             <a-col :span="6">
-              <a-input-number v-model:value="skill.skillId" placeholder="Skill ID" style="width: 100%" :min="1" />
+              <a-input-number v-model:value="skill.skillId" placeholder="Skill编号" style="width: 100%" :min="1" />
             </a-col>
             <a-col :span="6">
               <a-input-number v-model:value="skill.promotionPrice" placeholder="促销价(元)" style="width: 100%" :min="0" :precision="2" />

frontend/src/views/admin/skills.vue

@@ -47,9 +47,10 @@
         </template>
       </a-table-column>
       <a-table-column title="创建时间" data-index="createdAt" :width="180" />
-      <a-table-column title="操作" fixed="right" :width="250">
+      <a-table-column title="操作" fixed="right" :width="280">
         <template #default="{ record }">
           <a-button type="link" size="small" @click="viewSkill(record)">查看</a-button>
+          <a-button type="link" size="small" @click="openEditDialog(record)">编辑</a-button>
           <template v-if="record.status === 'pending'">
             <a-button type="link" size="small" style="color: #52c41a" @click="approveSkill(record)">通过</a-button>
             <a-button type="link" danger size="small" @click="rejectSkill(record)">拒绝</a-button>
@@ -124,6 +125,72 @@
       </template>
     </a-modal>
 
+    <!-- 编辑Skill对话框 -->
+    <a-modal v-model:open="editDialogVisible" title="编辑Skill" :width="600">
+      <a-form :model="editForm" :rules="createRules" ref="editFormRef" :label-col="{ span: 5 }" :wrapper-col="{ span: 19 }">
+        <a-form-item label="Skill名称" name="name">
+          <a-input v-model:value="editForm.name" placeholder="请输入Skill名称" />
+        </a-form-item>
+        <a-form-item label="描述" name="description">
+          <a-textarea v-model:value="editForm.description" :rows="3" placeholder="请输入描述" />
+        </a-form-item>
+        <a-form-item label="分类" name="categoryId">
+          <a-select v-model:value="editForm.categoryId" placeholder="请选择分类" style="width: 100%">
+            <a-select-option v-for="cat in skillStore.categories" :key="cat.id" :value="cat.id">{{ cat.name }}</a-select-option>
+          </a-select>
+        </a-form-item>
+        <a-form-item label="价格" name="price">
+          <a-input-number v-model:value="editForm.price" :min="0" :precision="2" :step="1" />
+          <a-checkbox v-model:checked="editForm.isFree" style="margin-left: 12px">免费</a-checkbox>
+        </a-form-item>
+        <a-form-item label="版本">
+          <a-input v-model:value="editForm.version" placeholder="如 1.0.0" />
+        </a-form-item>
+        <a-form-item label="封面图">
+          <a-upload
+            :before-upload="beforeCoverUpload"
+            :show-upload-list="false"
+            :custom-request="handleEditCoverUpload"
+            accept="image/*"
+          >
+            <div v-if="editForm.coverImageUrl" class="upload-preview">
+              <img :src="editForm.coverImageUrl" class="preview-img" />
+              <div class="preview-mask">点击更换</div>
+            </div>
+            <a-button v-else :loading="editCoverUploading">
+              <upload-outlined /> 上传封面图
+            </a-button>
+          </a-upload>
+          <a-input v-model:value="editForm.coverImageUrl" placeholder="或直接输入图片URL" style="margin-top: 8px" />
+        </a-form-item>
+        <a-form-item label="Skill文件">
+          <a-upload
+            :before-upload="beforeFileUpload"
+            :show-upload-list="false"
+            :custom-request="handleEditFileUpload"
+          >
+            <a-button :loading="editFileUploading">
+              <upload-outlined /> 上传文件
+            </a-button>
+          </a-upload>
+          <div v-if="editForm.fileUrl" style="margin-top: 4px; color: #52c41a; font-size: 12px">✅ 已有文件</div>
+          <a-input v-model:value="editForm.fileUrl" placeholder="或直接输入文件URL" style="margin-top: 8px" />
+        </a-form-item>
+        <a-form-item label="状态">
+          <a-select v-model:value="editForm.status" style="width: 120px">
+            <a-select-option value="approved">已上架</a-select-option>
+            <a-select-option value="pending">待审核</a-select-option>
+            <a-select-option value="offline">已下架</a-select-option>
+            <a-select-option value="rejected">已拒绝</a-select-option>
+          </a-select>
+        </a-form-item>
+      </a-form>
+      <template #footer>
+        <a-button @click="editDialogVisible = false">取消</a-button>
+        <a-button type="primary" :loading="editLoading" @click="submitEditSkill">保存</a-button>
+      </template>
+    </a-modal>
+
     <a-modal v-model:open="skillDialogVisible" title="Skill详情" :width="600" :footer="null">
       <template v-if="currentSkill">
         <a-descriptions :column="2" bordered>
@@ -262,6 +329,96 @@ const toggleFeatured = async (skill) => {
   }
 }
 
+// ==================== 编辑Skill ====================
+const editDialogVisible = ref(false)
+const editLoading = ref(false)
+const editFormRef = ref(null)
+const editCoverUploading = ref(false)
+const editFileUploading = ref(false)
+const editingSkillId = ref(null)
+const editForm = ref({
+  name: '',
+  description: '',
+  categoryId: null,
+  price: 0,
+  isFree: false,
+  version: '',
+  coverImageUrl: '',
+  fileUrl: '',
+  status: ''
+})
+
+const openEditDialog = (skill) => {
+  editingSkillId.value = skill.id
+  editForm.value = {
+    name: skill.name || '',
+    description: skill.description || '',
+    categoryId: skill.categoryId || null,
+    price: skill.price || 0,
+    isFree: skill.price === 0,
+    version: skill.version || '',
+    coverImageUrl: skill.coverImageUrl || '',
+    fileUrl: skill.fileUrl || '',
+    status: skill.status || 'pending'
+  }
+  editDialogVisible.value = true
+}
+
+const handleEditCoverUpload = async ({ file }) => {
+  editCoverUploading.value = true
+  try {
+    const res = await uploadApi.uploadFile('skill', file)
+    if (res.data?.url) {
+      editForm.value.coverImageUrl = res.data.url
+      message.success('封面图上传成功')
+    }
+  } catch {
+    message.error('上传失败')
+  } finally {
+    editCoverUploading.value = false
+  }
+}
+
+const handleEditFileUpload = async ({ file }) => {
+  editFileUploading.value = true
+  try {
+    const res = await uploadApi.uploadFile('skill', file)
+    if (res.data?.url) {
+      editForm.value.fileUrl = res.data.url
+      message.success('文件上传成功')
+    }
+  } catch {
+    message.error('上传失败')
+  } finally {
+    editFileUploading.value = false
+  }
+}
+
+const submitEditSkill = async () => {
+  if (!editFormRef.value) return
+  try {
+    await editFormRef.value.validate()
+  } catch {
+    return
+  }
+  editLoading.value = true
+  try {
+    const data = { ...editForm.value }
+    if (data.isFree) data.price = 0
+    delete data.isFree
+    const result = await adminStore.updateSkill(editingSkillId.value, data)
+    if (result.success) {
+      message.success('Skill更新成功')
+      editDialogVisible.value = false
+      await adminStore.loadSkills()
+    } else {
+      message.error(result.message)
+    }
+  } finally {
+    editLoading.value = false
+  }
+}
+
 // ==================== 上传Skill ====================
 const coverUploading = ref(false)
 const fileUploading = ref(false)

frontend/src/views/customize/index.vue

@@ -191,8 +191,14 @@ const handleSubmit = async () => {
 
   submitting.value = true
   try {
-    await customizationApi.submitRequest(form)
+    await customizationApi.submitRequest({ ...form })
     message.success('提交成功')
+    form.name = ''
+    form.contact = ''
+    form.company = ''
+    form.industry = undefined
+    form.scenario = ''
+    form.budget = '待定'
     successDialogVisible.value = true
   } catch (error) {
     console.error('提交失败:', error)

frontend/src/views/help/article.vue

@@ -51,9 +51,18 @@ const article = ref(null)
 const loading = ref(false)
 const helpful = ref(false)
 
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
 const renderedContent = computed(() => {
   if (!article.value?.content) return ''
-  return article.value.content
+  return escapeHtml(article.value.content)
     .replace(/^### (.*$)/gim, '<h3>$1</h3>')
     .replace(/^## (.*$)/gim, '<h2>$1</h2>')
     .replace(/^# (.*$)/gim, '<h1>$1</h1>')

frontend/src/views/home/index.vue

@@ -13,7 +13,7 @@
                 <div class="banner-info">
                   <div class="hero-badge">
                     <span class="badge-dot"></span>
-                    <span>AI SKILL MARKETPLACE</span>
+                    <span>AI 数字员工市场</span>
                   </div>
                   <h1 class="banner-title">发现优质<span class="highlight">数字员工</span></h1>
                   <p class="banner-desc">{{ banner.title }}</p>
@@ -27,7 +27,7 @@
             <div class="banner-info">
               <div class="hero-badge">
                 <span class="badge-dot"></span>
-                <span>AI SKILL MARKETPLACE</span>
+                <span>AI 数字员工市场</span>
               </div>
               <h1 class="banner-title">发现优质<span class="highlight">数字员工</span></h1>
               <p class="banner-desc">探索数千款 AI 技能工具，提升工作效率，释放创造力</p>
@@ -238,6 +238,24 @@
       </a-row>
     </section>
 
+    <section class="community-section page-container">
+      <div class="community-card">
+        <div class="community-card-bg"></div>
+        <div class="community-card-content">
+          <div class="community-icon-wrap">
+            <TeamOutlined :style="{ fontSize: '36px' }" />
+          </div>
+          <div class="community-text">
+            <h3>加入技术交流社群</h3>
+            <p>与同行交流经验、获取最新动态，审核通过后还可领取专属优惠券</p>
+          </div>
+          <a-button type="primary" size="large" class="neon-btn-primary community-btn" :disabled="joinStatus === 'pending'" @click="handleJoinGroup">
+            {{ joinStatus === 'pending' ? '审核中' : joinStatus === 'approved' ? '已通过' : '立即加入' }}
+          </a-button>
+        </div>
+      </div>
+    </section>
+
     <section v-if="!userStore.isLoggedIn" class="cta-section page-container">
       <div class="cta-card">
         <div class="cta-bg-effect"></div>
@@ -259,7 +277,8 @@
 import { computed, onMounted, ref } from 'vue'
 import { useRouter } from 'vue-router'
 import { useSkillStore, useUserStore } from '@/stores'
-import { contentApi } from '@/service/apiService'
+import { contentApi, communityApi } from '@/service/apiService'
+import { message, Modal } from 'ant-design-vue'
 import SkillCard from '@/components/SkillCard.vue'
 import {
   SafetyCertificateOutlined,
@@ -269,6 +288,7 @@ import {
   TrophyOutlined,
   RightOutlined,
   NotificationOutlined,
+  TeamOutlined,
   LaptopOutlined,
   BarChartOutlined,
   EditOutlined,
@@ -281,6 +301,7 @@ const router = useRouter()
 const skillStore = useSkillStore()
 const userStore = useUserStore()
 
+const joinStatus = ref('none')
 const banners = ref([])
 const announcements = ref([])
 const activities = ref([])
@@ -369,8 +390,48 @@ onMounted(async () => {
     const actRes = await contentApi.getActiveActivities()
     activities.value = actRes.data || []
   } catch { /* ignore */ }
+  if (userStore.isLoggedIn) {
+    try {
+      const statusData = await userStore.getCommunityJoinStatus()
+      joinStatus.value = statusData.status || 'none'
+    } catch { /* ignore */ }
+  }
 })
 
+const handleJoinGroup = () => {
+  if (!userStore.isLoggedIn) {
+    message.warning('请先登录')
+    router.push('/login')
+    return
+  }
+  if (joinStatus.value === 'pending') {
+    message.info('您的申请正在审核中，请耐心等待')
+    return
+  }
+  if (joinStatus.value === 'approved') {
+    message.info('您已通过审核')
+    return
+  }
+  if (joinStatus.value === 'rejected') {
+    joinStatus.value = 'none'
+  }
+  Modal.confirm({
+    title: '加入社群',
+    content: '申请加入技术交流社群，管理员审核通过后将为您下发专属优惠券',
+    okText: '提交申请',
+    cancelText: '取消',
+    async onOk() {
+      try {
+        await communityApi.applyJoin()
+        message.success('申请已提交，请等待管理员审核')
+        joinStatus.value = 'pending'
+      } catch (error) {
+        message.error(error.response?.data?.message || '提交申请失败')
+      }
+    }
+  })
+}
+
 const getCategoryIcon = (iconName) => {
   const iconMap = {
     Document: FileTextOutlined,
@@ -992,6 +1053,70 @@ const goToCategory = (categoryId) => {
   }
 }
 
+.community-section {
+  padding-top: 16px;
+  padding-bottom: 16px;
+  position: relative;
+  z-index: 1;
+}
+
+.community-card {
+  border-radius: 24px;
+  border: 1px solid rgba(99, 102, 241, 0.15);
+  background: linear-gradient(135deg, rgba(99, 102, 241, 0.06) 0%, rgba(139, 92, 246, 0.04) 100%);
+  backdrop-filter: blur(8px);
+  position: relative;
+  overflow: hidden;
+  transition: all 0.3s ease;
+
+  &:hover {
+    border-color: rgba(99, 102, 241, 0.25);
+    box-shadow: 0 8px 32px rgba(99, 102, 241, 0.1);
+  }
+
+  .community-card-content {
+    display: flex;
+    align-items: center;
+    gap: 20px;
+    padding: 24px 32px;
+  }
+
+  .community-icon-wrap {
+    width: 64px;
+    height: 64px;
+    border-radius: 18px;
+    background: linear-gradient(135deg, rgba(99, 102, 241, 0.15), rgba(139, 92, 246, 0.1));
+    border: 1px solid rgba(99, 102, 241, 0.2);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--accent-blue);
+    flex-shrink: 0;
+  }
+
+  .community-text {
+    flex: 1;
+
+    h3 {
+      font-family: var(--font-heading);
+      font-size: 18px;
+      font-weight: 600;
+      color: var(--text-primary);
+      margin-bottom: 4px;
+    }
+
+    p {
+      color: var(--text-secondary);
+      font-size: 14px;
+      margin: 0;
+    }
+  }
+
+  .community-btn {
+    flex-shrink: 0;
+  }
+}
+
 .ranking-entry-section {
   padding-top: 16px;
   padding-bottom: 16px;

frontend/src/views/join-us/index.vue

@@ -204,12 +204,34 @@
             <div class="form-tip">支持 MP4/MOV/AVI/WEBM 格式，最大 100MB；也可粘贴网盘链接</div>
             <a-progress v-if="videoUploading" :percent="videoProgress" size="small" style="margin-top: 4px" />
           </a-form-item>
-          <a-form-item label="作品链接" name="portfolioUrl">
+          <a-form-item label="作品集" name="portfolioUrl">
-            <a-input v-model:value="form.portfolioUrl" placeholder="请输入个人作品集或GitHub链接（选填）">
+            <div class="upload-area">
-              <template #prefix>
+              <a-upload
-                <desktop-outlined />
+                :file-list="portfolioFileList"
-              </template>
+                :before-upload="beforePortfolioUpload"
+                :custom-request="handlePortfolioUpload"
+                :max-count="5"
+                multiple
+                accept=".zip,.rar,.7z,.tar.gz,.pdf,.doc,.docx,.ppt,.pptx,.png,.jpg,.jpeg,.gif"
+                @remove="handlePortfolioRemove"
+              >
+                <a-button :loading="portfolioUploading">
+                  <template #icon><upload-outlined /></template>
+                  {{ portfolioUploading ? '上传中...' : '选择作品文件' }}
+                </a-button>
+              </a-upload>
+              <div class="upload-or">或</div>
+              <a-input
+                v-model:value="form.portfolioUrl"
+                placeholder="粘贴作品集链接（GitHub、网盘等）"
+                :disabled="!!portfolioFileList.length"
+                style="flex: 1"
+              >
+                <template #prefix><link-outlined /></template>
               </a-input>
+            </div>
+            <div class="form-tip">支持 ZIP/RAR/PDF/图片等格式，单文件最大 50MB，最多 5 个；也可粘贴链接</div>
+            <a-progress v-if="portfolioUploading" :percent="portfolioProgress" size="small" style="margin-top: 4px" />
           </a-form-item>
 
           <a-form-item label="期望收益" name="expectedIncome">
@@ -325,12 +347,17 @@ import {
   ProjectOutlined,
   DollarCircleOutlined,
   CheckCircleFilled,
+  CheckCircleOutlined,
   TrophyOutlined,
   StarOutlined,
   UploadOutlined,
   VideoCameraOutlined,
   LinkOutlined,
-  DesktopOutlined
+  DesktopOutlined,
+  WalletOutlined,
+  RiseOutlined,
+  TeamOutlined,
+  RightOutlined
 } from '@ant-design/icons-vue'
 
 const formRef = ref(null)
@@ -347,6 +374,11 @@ const videoFileList = ref([])
 const videoUploading = ref(false)
 const videoProgress = ref(0)
 
+// 作品集上传状态
+const portfolioFileList = ref([])
+const portfolioUploading = ref(false)
+const portfolioProgress = ref(0)
+
 const form = reactive({
   realName: '',
   phone: '',
@@ -488,6 +520,50 @@ const handleVideoRemove = () => {
   videoProgress.value = 0
 }
 
+// 作品集上传前校验
+const beforePortfolioUpload = (file) => {
+  if (file.size > 50 * 1024 * 1024) {
+    message.error('单个文件大小不能超过 50MB')
+    return false
+  }
+  return true
+}
+
+// 作品集上传处理
+const handlePortfolioUpload = async ({ file, onSuccess, onError }) => {
+  portfolioUploading.value = true
+  portfolioProgress.value = 0
+  const progressTimer = setInterval(() => {
+    if (portfolioProgress.value < 90) portfolioProgress.value += 10
+  }, 200)
+  try {
+    const res = await uploadApi.uploadFile('portfolio', file)
+    clearInterval(progressTimer)
+    portfolioProgress.value = 100
+    const url = res.data?.url || res.data?.fileUrl
+    portfolioFileList.value = [...portfolioFileList.value, { uid: file.uid, name: file.name, status: 'done', url }]
+    // 将所有已上传文件URL用逗号拼接存入portfolioUrl
+    form.portfolioUrl = portfolioFileList.value.map(f => f.url).join(',')
+    onSuccess(res, file)
+    message.success('文件上传成功')
+  } catch (err) {
+    clearInterval(progressTimer)
+    onError(err)
+    message.error('文件上传失败：' + (err.response?.data?.message || err.message))
+  } finally {
+    portfolioUploading.value = false
+    portfolioProgress.value = 0
+  }
+}
+
+// 作品集文件删除
+const handlePortfolioRemove = (file) => {
+  portfolioFileList.value = portfolioFileList.value.filter(f => f.uid !== file.uid)
+  form.portfolioUrl = portfolioFileList.value.length
+    ? portfolioFileList.value.map(f => f.url).join(',')
+    : ''
+}
+
 const rules = {
   realName: [{ required: true, message: '请输入真实姓名', trigger: 'blur' }],
   phone: [
@@ -544,6 +620,8 @@ const resetForm = () => {
   resumeProgress.value = 0
   videoFileList.value = []
   videoProgress.value = 0
+  portfolioFileList.value = []
+  portfolioProgress.value = 0
 }
 </script>
 

frontend/src/views/legal/about.vue

@@ -0,0 +1,232 @@
+<template>
+  <div class="legal-page">
+    <div class="legal-container">
+      <a-card :bordered="false" class="legal-card">
+        <h1>关于我们</h1>
+        <p class="update-date">OpenClaw Skills · 数字员工交易平台</p>
+
+        <div class="about-hero">
+          <div class="hero-icon">
+            <rocket-outlined :style="{ fontSize: '48px', color: '#667eea' }" />
+          </div>
+          <p class="hero-text">让每个人都能拥有自己的数字员工</p>
+        </div>
+
+        <h2>平台简介</h2>
+        <p>OpenClaw Skills 是一个专注于数字员工（Skill）交易的创新平台。我们致力于连接优秀的 Skill 开发者与有需求的用户，打造一个高效、可信赖的数字技能交易生态。</p>
+        <p>在这里，开发者可以将自己的技术能力转化为可复用的 Skill 产品，获得持续收益；用户可以快速找到并获取满足需求的数字员工，提升工作效率。</p>
+
+        <h2>我们的愿景</h2>
+        <p>构建全球领先的数字员工交易平台，让技术创造更大的价值，让每个人都能享受数字化带来的便利。</p>
+
+        <h2>我们的使命</h2>
+        <div class="mission-grid">
+          <div class="mission-item">
+            <bulb-outlined :style="{ fontSize: '28px', color: '#e6a23c' }" />
+            <h4>技术创新</h4>
+            <p>持续推动数字员工技术的发展与应用</p>
+          </div>
+          <div class="mission-item">
+            <safety-outlined :style="{ fontSize: '28px', color: '#67c23a' }" />
+            <h4>品质保障</h4>
+            <p>严格审核每一个上架的 Skill 产品</p>
+          </div>
+          <div class="mission-item">
+            <team-outlined :style="{ fontSize: '28px', color: '#409eff' }" />
+            <h4>开发者赋能</h4>
+            <p>为开发者提供完善的工具与收益保障</p>
+          </div>
+          <div class="mission-item">
+            <heart-outlined :style="{ fontSize: '28px', color: '#f56c6c' }" />
+            <h4>用户至上</h4>
+            <p>以用户需求为核心驱动产品迭代</p>
+          </div>
+        </div>
+
+        <h2>核心优势</h2>
+        <p>1. <strong>丰富的 Skill 市场</strong>：涵盖办公自动化、数据处理、AI 应用等多个领域。</p>
+        <p>2. <strong>严格的品质审核</strong>：每个 Skill 上架前均经过技术审核与安全检测。</p>
+        <p>3. <strong>灵活的支付方式</strong>：支持积分兑换与微信支付，满足不同需求。</p>
+        <p>4. <strong>完善的开发者体系</strong>：提供开发者认证、收益分成、社区支持。</p>
+        <p>5. <strong>专业的客户服务</strong>：7×12 小时在线客服，及时解决用户问题。</p>
+
+        <h2>发展历程</h2>
+        <div class="timeline">
+          <div class="timeline-item">
+            <div class="timeline-dot"></div>
+            <div class="timeline-content">
+              <h4>2024 年 Q1</h4>
+              <p>平台立项，核心团队组建</p>
+            </div>
+          </div>
+          <div class="timeline-item">
+            <div class="timeline-dot"></div>
+            <div class="timeline-content">
+              <h4>2024 年 Q3</h4>
+              <p>平台 MVP 版本上线，首批开发者入驻</p>
+            </div>
+          </div>
+          <div class="timeline-item">
+            <div class="timeline-dot"></div>
+            <div class="timeline-content">
+              <h4>2025 年 Q1</h4>
+              <p>平台正式版发布，Skill 数量突破 500+</p>
+            </div>
+          </div>
+          <div class="timeline-item">
+            <div class="timeline-dot active"></div>
+            <div class="timeline-content">
+              <h4>2026 年</h4>
+              <p>全面升级，引入社区、会员、优惠券等功能体系</p>
+            </div>
+          </div>
+        </div>
+
+        <div class="back-link">
+          <a-button type="link" @click="$router.back()">返回上一页</a-button>
+        </div>
+      </a-card>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import {
+  RocketOutlined,
+  BulbOutlined,
+  SafetyOutlined,
+  TeamOutlined,
+  HeartOutlined
+} from '@ant-design/icons-vue'
+</script>
+
+<style lang="scss" scoped>
+.legal-page {
+  min-height: calc(100vh - 64px);
+  padding: 40px 20px;
+  background: #f5f7fa;
+}
+.legal-container {
+  max-width: 800px;
+  margin: 0 auto;
+}
+.legal-card {
+  border-radius: 16px;
+  :deep(.ant-card-body) { padding: 40px; }
+  h1 { font-size: 24px; margin-bottom: 8px; }
+  h2 { font-size: 18px; margin-top: 32px; margin-bottom: 12px; color: #303133; }
+  p { color: #606266; line-height: 1.8; margin-bottom: 8px; }
+  .update-date { color: #909399; font-size: 13px; margin-bottom: 24px; }
+  .back-link { text-align: center; margin-top: 32px; }
+}
+
+.about-hero {
+  text-align: center;
+  padding: 32px 0 16px;
+
+  .hero-icon {
+    width: 80px;
+    height: 80px;
+    background: linear-gradient(135deg, #667eea20, #764ba220);
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    margin: 0 auto 16px;
+  }
+
+  .hero-text {
+    font-size: 18px;
+    color: #303133;
+    font-weight: 500;
+  }
+}
+
+.mission-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 16px;
+  margin: 16px 0;
+
+  .mission-item {
+    background: #f5f7fa;
+    border-radius: 12px;
+    padding: 20px;
+    text-align: center;
+
+    h4 {
+      font-size: 15px;
+      color: #303133;
+      margin: 10px 0 6px;
+    }
+
+    p {
+      font-size: 13px;
+      color: #909399;
+      margin: 0;
+    }
+  }
+}
+
+.timeline {
+  position: relative;
+  padding-left: 24px;
+  margin: 16px 0;
+
+  &::before {
+    content: '';
+    position: absolute;
+    left: 7px;
+    top: 8px;
+    bottom: 8px;
+    width: 2px;
+    background: #e4e7ed;
+  }
+
+  .timeline-item {
+    position: relative;
+    padding-bottom: 20px;
+    display: flex;
+    align-items: flex-start;
+    gap: 16px;
+
+    &:last-child { padding-bottom: 0; }
+
+    .timeline-dot {
+      width: 12px;
+      height: 12px;
+      border-radius: 50%;
+      background: #c0c4cc;
+      border: 2px solid #fff;
+      box-shadow: 0 0 0 2px #e4e7ed;
+      margin-left: -22px;
+      margin-top: 4px;
+      flex-shrink: 0;
+
+      &.active {
+        background: #667eea;
+        box-shadow: 0 0 0 2px #667eea40;
+      }
+    }
+
+    .timeline-content {
+      h4 {
+        font-size: 14px;
+        color: #303133;
+        margin-bottom: 4px;
+      }
+      p {
+        font-size: 13px;
+        color: #909399;
+        margin: 0;
+      }
+    }
+  }
+}
+
+@media (max-width: 576px) {
+  .mission-grid {
+    grid-template-columns: 1fr;
+  }
+}
+</style>

frontend/src/views/legal/contact.vue

@@ -0,0 +1,189 @@
+<template>
+  <div class="legal-page">
+    <div class="legal-container">
+      <a-card :bordered="false" class="legal-card">
+        <h1>联系我们</h1>
+        <p class="update-date">我们期待您的反馈与建议</p>
+
+        <div class="contact-hero">
+          <customer-service-outlined :style="{ fontSize: '48px', color: '#667eea' }" />
+        </div>
+
+        <div class="contact-grid">
+          <div class="contact-item">
+            <div class="contact-icon">
+              <mail-outlined :style="{ fontSize: '24px', color: '#409eff' }" />
+            </div>
+            <h3>商务合作</h3>
+            <p>business@openclaw.com</p>
+            <span>合作洽谈、品牌推广</span>
+          </div>
+
+          <div class="contact-item">
+            <div class="contact-icon">
+              <mail-outlined :style="{ fontSize: '24px', color: '#67c23a' }" />
+            </div>
+            <h3>技术支持</h3>
+            <p>support@openclaw.com</p>
+            <span>产品问题、技术咨询</span>
+          </div>
+
+          <div class="contact-item">
+            <div class="contact-icon">
+              <mail-outlined :style="{ fontSize: '24px', color: '#e6a23c' }" />
+            </div>
+            <h3>开发者入驻</h3>
+            <p>developer@openclaw.com</p>
+            <span>开发者申请、合作咨询</span>
+          </div>
+
+          <div class="contact-item">
+            <div class="contact-icon">
+              <mail-outlined :style="{ fontSize: '24px', color: '#f56c6c' }" />
+            </div>
+            <h3>投诉建议</h3>
+            <p>feedback@openclaw.com</p>
+            <span>意见反馈、投诉举报</span>
+          </div>
+        </div>
+
+        <h2>其他联系方式</h2>
+        <div class="info-list">
+          <div class="info-row">
+            <phone-outlined :style="{ fontSize: '16px', color: '#409eff' }" />
+            <span>客服电话：400-888-0000（工作日 9:00-21:00）</span>
+          </div>
+          <div class="info-row">
+            <wechat-outlined :style="{ fontSize: '16px', color: '#67c23a' }" />
+            <span>官方微信：OpenClawSkills</span>
+          </div>
+          <div class="info-row">
+            <environment-outlined :style="{ fontSize: '16px', color: '#e6a23c' }" />
+            <span>公司地址：杭州市余杭区文一西路</span>
+          </div>
+          <div class="info-row">
+            <clock-circle-outlined :style="{ fontSize: '16px', color: '#909399' }" />
+            <span>工作时间：周一至周五 9:00 - 18:00</span>
+          </div>
+        </div>
+
+        <h2>在线反馈</h2>
+        <p>您也可以通过平台内的 <router-link to="/user/feedback">意见反馈</router-link> 功能直接提交问题（需登录），我们将在 1-3 个工作日内回复。</p>
+
+        <div class="back-link">
+          <a-button type="link" @click="$router.back()">返回上一页</a-button>
+        </div>
+      </a-card>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import {
+  CustomerServiceOutlined,
+  MailOutlined,
+  PhoneOutlined,
+  WechatOutlined,
+  EnvironmentOutlined,
+  ClockCircleOutlined
+} from '@ant-design/icons-vue'
+</script>
+
+<style lang="scss" scoped>
+.legal-page {
+  min-height: calc(100vh - 64px);
+  padding: 40px 20px;
+  background: #f5f7fa;
+}
+.legal-container {
+  max-width: 800px;
+  margin: 0 auto;
+}
+.legal-card {
+  border-radius: 16px;
+  :deep(.ant-card-body) { padding: 40px; }
+  h1 { font-size: 24px; margin-bottom: 8px; }
+  h2 { font-size: 18px; margin-top: 32px; margin-bottom: 12px; color: #303133; }
+  p { color: #606266; line-height: 1.8; margin-bottom: 8px; }
+  .update-date { color: #909399; font-size: 13px; margin-bottom: 24px; }
+  .back-link { text-align: center; margin-top: 32px; }
+}
+
+.contact-hero {
+  text-align: center;
+  padding: 16px 0 24px;
+}
+
+.contact-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 16px;
+  margin: 16px 0;
+
+  .contact-item {
+    background: #f5f7fa;
+    border-radius: 12px;
+    padding: 24px;
+    text-align: center;
+    transition: all 0.3s;
+
+    &:hover {
+      transform: translateY(-2px);
+      box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+    }
+
+    .contact-icon {
+      width: 48px;
+      height: 48px;
+      background: #fff;
+      border-radius: 50%;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      margin: 0 auto 12px;
+    }
+
+    h3 {
+      font-size: 16px;
+      color: #303133;
+      margin-bottom: 8px;
+    }
+
+    p {
+      font-size: 14px;
+      color: #409eff;
+      margin-bottom: 4px;
+    }
+
+    span {
+      font-size: 12px;
+      color: #909399;
+    }
+  }
+}
+
+.info-list {
+  margin: 16px 0;
+
+  .info-row {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 12px 0;
+    border-bottom: 1px solid #f0f0f0;
+
+    &:last-child { border-bottom: none; }
+
+    span {
+      font-size: 14px;
+      color: #606266;
+    }
+  }
+}
+
+@media (max-width: 576px) {
+  .contact-grid {
+    grid-template-columns: 1fr;
+  }
+}
+</style>

frontend/src/views/order/detail.vue

@@ -13,7 +13,7 @@
           <div class="order-info">
             <div class="info-row">
               <span class="label">订单号</span>
-              <span class="value">{{ order.id }}</span>
+              <span class="value">{{ order.orderNo || order.id }}</span>
             </div>
             <div class="info-row">
               <span class="label">创建时间</span>
@@ -68,7 +68,7 @@
               <a-button type="primary" @click="goPay">去支付</a-button>
               <a-button @click="cancelOrder">取消订单</a-button>
             </template>
-            <template v-else-if="order.status === 'paid' || order.status === 'completed'">
+            <template v-else-if="(order.status === 'paid' || order.status === 'completed') && Number(order.totalAmount) > 0">
               <a-button danger :loading="refundSubmitting" :disabled="refundSubmitting" @click="openRefundModal">申请退款</a-button>
             </template>
             <a-button @click="$router.push('/user/orders')">返回订单列表</a-button>
@@ -110,8 +110,10 @@ const refundSubmitting = ref(false)
 const refundReason = ref('')
 
 onMounted(async () => {
+  loading.value = true
   const orderId = route.params.id
   order.value = await orderStore.getOrderById(orderId)
+  loading.value = false
 })
 
 const getStatusColor = (status) => {

frontend/src/views/skill/detail.vue

@@ -295,7 +295,7 @@
 </template>
 
 <script setup>
-import { ref, computed, onMounted } from 'vue'
+import { ref, computed, onMounted, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useSkillStore, useUserStore, useOrderStore } from '@/stores'
 import { favoriteApi, couponApi } from '@/service/apiService'
@@ -358,6 +358,14 @@ onMounted(() => {
   loadSkill()
 })
 
+watch(() => route.params.id, (newId, oldId) => {
+  if (newId && newId !== oldId) {
+    activeTab.value = 'intro'
+    window.scrollTo(0, 0)
+    loadSkill()
+  }
+})
+
 const loadSkill = async () => {
   loading.value = true
   const skillId = parseInt(route.params.id)
@@ -530,6 +538,10 @@ const handleFavorite = async () => {
 }
 
 const submitComment = async () => {
+  if (!hasPurchased.value) {
+    message.warning('您尚未获取此Skill，无法评价')
+    return
+  }
   if (!commentForm.value.content.trim()) {
     message.warning('请输入评价内容')
     return

frontend/src/views/skill/list.vue

@@ -150,6 +150,7 @@ onMounted(() => {
 
 watch(() => route.query, () => {
   initFromRoute()
+  fetchSkills()
 })
 
 watch([currentPage, pageSize], () => {

frontend/src/views/skill/search.vue

@@ -24,7 +24,7 @@
           class="filter-select"
           placeholder="分类"
           :options="categoryOptions"
-          @change="doSearch"
+          @change="onFilterChange"
         />
         <a-select
           v-model:value="filters.priceType"
@@ -32,14 +32,14 @@
           class="filter-select"
           placeholder="价格"
           :options="priceOptions"
-          @change="doSearch"
+          @change="onFilterChange"
         />
         <a-select
           v-model:value="filters.sortBy"
           class="filter-select"
           placeholder="排序"
           :options="sortOptions"
-          @change="doSearch"
+          @change="onFilterChange"
         />
       </div>
 
@@ -53,7 +53,7 @@
             />
           </div>
         </template>
-        <template v-else>
+        <template v-else-if="!loading">
           <div class="empty-state">
             <a-empty description="没有找到相关Skill">
               <template #extra>
@@ -62,6 +62,14 @@
             </a-empty>
           </div>
         </template>
+        <div class="pagination-wrap" v-if="total > pageSize">
+          <a-pagination
+            v-model:current="pageNum"
+            :total="total"
+            :page-size="pageSize"
+            @change="onPageChange"
+          />
+        </div>
       </div>
     </div>
   </div>
@@ -81,6 +89,9 @@ const loading = ref(false)
 const keyword = ref('')
 const searchKeyword = ref('')
 const results = ref([])
+const pageNum = ref(1)
+const pageSize = ref(12)
+const total = ref(0)
 
 const filters = ref({
   categoryId: null,
@@ -134,13 +145,36 @@ const handleSearch = () => {
 
 const doSearch = async () => {
   loading.value = true
-  results.value = await skillStore.searchSkills(searchKeyword.value, filters.value).catch(() => [])
+  try {
+    const res = await skillStore.searchSkills(searchKeyword.value, {
+      ...filters.value,
+      pageNum: pageNum.value,
+      pageSize: pageSize.value
+    })
+    results.value = res.records || []
+    total.value = res.total || 0
+  } catch {
+    results.value = []
+    total.value = 0
+  }
   loading.value = false
 }
 
+const onFilterChange = () => {
+  pageNum.value = 1
+  doSearch()
+}
+
+const onPageChange = (page) => {
+  pageNum.value = page
+  doSearch()
+}
+
 const clearSearch = () => {
   searchKeyword.value = ''
   keyword.value = ''
+  pageNum.value = 1
+  total.value = 0
   filters.value = {
     categoryId: null,
     priceType: undefined,
@@ -196,6 +230,11 @@ const clearSearch = () => {
   .empty-state {
     padding: 60px 0;
   }
+
+  .pagination-wrap {
+    margin-top: 24px;
+    text-align: center;
+  }
 }
 
 @media (max-width: 1200px) {

frontend/src/views/user/favorites.vue

@@ -76,18 +76,12 @@ const loadFavorites = async () => {
       favoriteSkills.value = []
       return
     }
-    const skills = []
+    const results = await Promise.allSettled(
-    for (const id of skillIds) {
+      skillIds.map(id => skillApi.getDetail(id))
-      try {
+    )
-        const detail = await skillApi.getDetail(id)
+    favoriteSkills.value = results
-        if (detail.data) {
+      .filter(r => r.status === 'fulfilled' && r.value?.data)
-          skills.push(detail.data)
+      .map(r => r.value.data)
-        }
-      } catch {
-        /* skip deleted/offline skills */
-      }
-    }
-    favoriteSkills.value = skills
   } catch {
     favoriteSkills.value = []
   } finally {

frontend/src/views/user/forgot-password.vue

@@ -103,6 +103,7 @@ const currentStep = ref(0)
 const loading = ref(false)
 const smsSending = ref(false)
 const smsCountdown = ref(0)
+const smsSent = ref(false)
 let smsTimer = null
 
 const form = reactive({
@@ -171,6 +172,7 @@ const handleSendSmsCode = async () => {
 
   if (result.success) {
     message.success(result.message || '验证码已发送')
+    smsSent.value = true
     startSmsCountdown()
   } else {
     message.error(result.message)
@@ -181,6 +183,14 @@ const verifyPhone = async () => {
   try {
     await step1Ref.value?.validate()
   } catch { return }
+  if (!smsSent.value) {
+    message.warning('请先发送验证码')
+    return
+  }
+  if (!form.smsCode || form.smsCode.length < 4) {
+    message.warning('请输入完整的验证码')
+    return
+  }
   currentStep.value = 1
 }
 

frontend/src/views/user/invite.vue

@@ -132,14 +132,22 @@ onMounted(async () => {
   }
 })
 
-const copyInviteCode = () => {
+const copyInviteCode = async () => {
-  navigator.clipboard.writeText(myInviteCode.value)
+  try {
+    await navigator.clipboard.writeText(myInviteCode.value)
     message.success('邀请码已复制')
+  } catch {
+    message.warning('复制失败，请手动复制')
+  }
 }
 
-const copyInviteLink = () => {
+const copyInviteLink = async () => {
-  navigator.clipboard.writeText(inviteLink.value)
+  try {
+    await navigator.clipboard.writeText(inviteLink.value)
     message.success('邀请链接已复制')
+  } catch {
+    message.warning('复制失败，请手动复制')
+  }
 }
 </script>
 

frontend/src/views/user/invoices.vue

@@ -2,10 +2,21 @@
   <div class="invoices-page">
     <div class="page-header">
       <h2 class="page-title">我的发票</h2>
-      <a-button type="primary" @click="showApplyModal = true">
+      <div class="header-actions">
+        <span v-if="invoicableAmount > 0" class="invoicable-hint">
+          可开票 ¥{{ invoicableAmount.toFixed(2) }}
+        </span>
+        <a-tooltip v-if="invoicableOrders.length === 0" title="暂无可开票订单，完成订单支付后即可申请">
+          <a-button type="primary" disabled>
             <template #icon><plus-outlined /></template>
             申请发票
           </a-button>
+        </a-tooltip>
+        <a-button v-else type="primary" @click="openApplyModal">
+          <template #icon><plus-outlined /></template>
+          申请发票
+        </a-button>
+      </div>
     </div>
 
     <div class="filter-bar">
@@ -56,7 +67,23 @@
           </div>
         </div>
       </div>
-      <a-empty v-else description="暂无发票记录" />
+      <div v-else class="empty-state">
+        <a-empty description="">
+          <template #description>
+            <div class="empty-desc">
+              <p>暂无发票记录</p>
+              <p class="empty-hint" v-if="invoicableOrders.length === 0">完成订单支付后，可在此申请电子发票</p>
+              <p class="empty-hint" v-else>您有 {{ invoicableOrders.length }} 笔订单可申请发票</p>
+            </div>
+          </template>
+          <a-button v-if="invoicableOrders.length === 0" type="primary" @click="$router.push('/')">
+            去逛逛
+          </a-button>
+          <a-button v-else type="primary" @click="openApplyModal">
+            立即申请
+          </a-button>
+        </a-empty>
+      </div>
     </a-spin>
 
     <div class="pagination-wrap" v-if="total > pageSize">
@@ -76,9 +103,54 @@
       :confirm-loading="submitting"
       @ok="handleApply"
       @cancel="resetForm"
-      width="560px"
+      width="600px"
+      :ok-text="'提交申请'"
+      :ok-button-props="{ disabled: selectedOrderIds.length === 0 }"
     >
       <a-form :model="form" :rules="rules" ref="formRef" layout="vertical">
+        <!-- 关联订单（放在最前面，核心操作） -->
+        <a-form-item name="orderIds">
+          <template #label>
+            <div class="order-label">
+              <span>选择开票订单</span>
+              <a v-if="invoicableOrders.length > 1" class="select-all-link" @click="toggleSelectAll">
+                {{ isAllSelected ? '取消全选' : '全选' }}
+              </a>
+            </div>
+          </template>
+          <a-checkbox-group v-model:value="selectedOrderIds" style="width: 100%">
+            <div class="order-select-list">
+              <label
+                v-for="order in invoicableOrders"
+                :key="order.id"
+                class="order-select-item"
+                :class="{ selected: selectedOrderIds.includes(order.id) }"
+              >
+                <a-checkbox :value="order.id" />
+                <div class="order-info">
+                  <div class="order-main">
+                    <span class="order-name">{{ order.skillName }}</span>
+                    <span class="order-amount">¥{{ Number(order.totalAmount).toFixed(2) }}</span>
+                  </div>
+                  <div class="order-meta">
+                    <span>{{ order.orderNo }}</span>
+                    <span>{{ order.createdAt }}</span>
+                  </div>
+                </div>
+              </label>
+            </div>
+          </a-checkbox-group>
+        </a-form-item>
+
+        <!-- 开票金额汇总（只读） -->
+        <div class="amount-summary" v-if="selectedOrderIds.length > 0">
+          <span class="amount-label">开票金额</span>
+          <span class="amount-value">¥{{ selectedAmount.toFixed(2) }}</span>
+          <span class="amount-count">（{{ selectedOrderIds.length }} 笔订单）</span>
+        </div>
+
+        <a-divider />
+
         <a-form-item label="发票类型" name="type">
           <a-radio-group v-model:value="form.type">
             <a-radio value="personal">个人</a-radio>
@@ -108,28 +180,6 @@
           </a-form-item>
         </template>
 
-        <a-form-item label="开票金额" name="amount">
-          <a-input-number
-            v-model:value="form.amount"
-            :min="0.01"
-            :precision="2"
-            style="width: 100%"
-            placeholder="请输入开票金额"
-            prefix="¥"
-          />
-        </a-form-item>
-
-        <a-form-item label="关联订单" name="orderIds">
-          <a-checkbox-group v-model:value="selectedOrderIds" style="width: 100%">
-            <div v-if="paidOrders.length > 0" style="max-height: 200px; overflow-y: auto; display: flex; flex-direction: column; gap: 8px;">
-              <a-checkbox v-for="order in paidOrders" :key="order.id" :value="order.id">
-                {{ order.orderNo }} - {{ order.skillName }} (¥{{ order.totalAmount }})
-              </a-checkbox>
-            </div>
-            <a-empty v-else description="暂无可开票订单" :image="null" />
-          </a-checkbox-group>
-        </a-form-item>
-
         <a-form-item label="接收邮箱" name="email">
           <a-input v-model:value="form.email" placeholder="电子发票将发送至此邮箱" />
         </a-form-item>
@@ -179,8 +229,6 @@ const form = reactive({
 const rules = {
   type: [{ required: true, message: '请选择发票类型' }],
   titleName: [{ required: true, message: '请输入发票抬头' }],
-  amount: [{ required: true, message: '请输入开票金额' }],
-  orderIds: [{ required: true, message: '请选择关联订单' }],
   email: [
     { required: true, message: '请输入接收邮箱' },
     { type: 'email', message: '请输入有效邮箱地址' }
@@ -212,21 +260,61 @@ const fetchInvoices = async () => {
   }
 }
 
-const paidOrders = computed(() => {
+const invoicedOrderIds = computed(() => {
-  return orderStore.orders.filter(o => (o.status === 'paid' || o.status === 'completed') && Number(o.totalAmount) > 0)
+  const ids = new Set()
+  invoices.value
+    .filter(inv => inv.status === 'pending' || inv.status === 'approved')
+    .forEach(inv => {
+      if (inv.orderIds) {
+        String(inv.orderIds).split(',').forEach(id => ids.add(id.trim()))
+      }
+    })
+  return ids
 })
 
+const invoicableOrders = computed(() => {
+  return orderStore.orders.filter(o => {
+    const isPaid = o.status === 'paid' || o.status === 'completed'
+    const hasAmount = Number(o.totalAmount) > 0
+    const notInvoiced = !invoicedOrderIds.value.has(String(o.id))
+    return isPaid && hasAmount && notInvoiced
+  })
+})
+
+const invoicableAmount = computed(() => {
+  return invoicableOrders.value.reduce((sum, o) => sum + Number(o.totalAmount || 0), 0)
+})
+
+const selectedAmount = computed(() => {
+  return invoicableOrders.value
+    .filter(o => selectedOrderIds.value.includes(o.id))
+    .reduce((sum, o) => sum + Number(o.totalAmount || 0), 0)
+})
+
+const isAllSelected = computed(() => {
+  return invoicableOrders.value.length > 0 && selectedOrderIds.value.length === invoicableOrders.value.length
+})
+
+const toggleSelectAll = () => {
+  if (isAllSelected.value) {
+    selectedOrderIds.value = []
+  } else {
+    selectedOrderIds.value = invoicableOrders.value.map(o => o.id)
+  }
+}
+
 watch(selectedOrderIds, (ids) => {
   form.orderIds = ids.join(',')
-  const total = paidOrders.value
+  form.amount = selectedAmount.value > 0 ? Number(selectedAmount.value.toFixed(2)) : null
-    .filter(o => ids.includes(o.id))
-    .reduce((sum, o) => sum + Number(o.totalAmount || 0), 0)
-  form.amount = total > 0 ? Number(total.toFixed(2)) : null
 })
 
+const openApplyModal = () => {
+  showApplyModal.value = true
+}
+
 const handleApply = async () => {
   if (selectedOrderIds.value.length === 0) {
-    message.warning('请选择关联订单')
+    message.warning('请选择开票订单')
     return
   }
   try {
@@ -238,7 +326,7 @@ const handleApply = async () => {
   try {
     const res = await invoiceApi.apply({ ...form })
     if (res.code === 200) {
-      message.success('发票申请已提交')
+      message.success('发票申请已提交，请等待审核')
       showApplyModal.value = false
       resetForm()
       fetchInvoices()
@@ -246,7 +334,7 @@ const handleApply = async () => {
       message.error(res.message || '申请失败')
     }
   } catch (e) {
-    message.error('申请失败')
+    message.error('提交失败，请稍后重试')
   } finally {
     submitting.value = false
   }
@@ -270,7 +358,11 @@ const resetForm = () => {
 onMounted(async () => {
   fetchInvoices()
   if (userStore.user) {
+    try {
       await orderStore.loadUserOrders(userStore.user.id)
+    } catch (e) {
+      message.error('加载订单数据失败，请刷新页面重试')
+    }
   }
 })
 </script>
@@ -289,12 +381,42 @@ onMounted(async () => {
       color: #303133;
       margin: 0;
     }
+
+    .header-actions {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+
+      .invoicable-hint {
+        font-size: 13px;
+        color: #52c41a;
+        font-weight: 500;
+      }
+    }
   }
 
   .filter-bar {
     margin-bottom: 20px;
   }
 
+  .empty-state {
+    padding: 60px 0;
+    text-align: center;
+
+    .empty-desc {
+      p {
+        margin: 0;
+        color: #909399;
+        font-size: 14px;
+      }
+      .empty-hint {
+        font-size: 12px;
+        color: #c0c4cc;
+        margin-top: 4px;
+      }
+    }
+  }
+
   .invoice-list {
     display: flex;
     flex-direction: column;
@@ -374,4 +496,110 @@ onMounted(async () => {
     text-align: right;
   }
 }
+
+.order-label {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  width: 100%;
+
+  .select-all-link {
+    font-size: 12px;
+    font-weight: 400;
+    color: #1890ff;
+    cursor: pointer;
+  }
+}
+
+.order-select-list {
+  max-height: 240px;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.order-select-item {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 10px 12px;
+  border: 1px solid #f0f0f0;
+  border-radius: 6px;
+  cursor: pointer;
+  transition: all 0.2s;
+
+  &:hover {
+    border-color: #d9d9d9;
+    background: #fafafa;
+  }
+
+  &.selected {
+    border-color: #1890ff;
+    background: #e6f7ff;
+  }
+
+  .order-info {
+    flex: 1;
+    min-width: 0;
+
+    .order-main {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+
+      .order-name {
+        font-size: 14px;
+        color: #303133;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+
+      .order-amount {
+        font-size: 14px;
+        font-weight: 600;
+        color: #e6a23c;
+        flex-shrink: 0;
+        margin-left: 8px;
+      }
+    }
+
+    .order-meta {
+      display: flex;
+      gap: 12px;
+      margin-top: 4px;
+      font-size: 12px;
+      color: #909399;
+    }
+  }
+}
+
+.amount-summary {
+  display: flex;
+  align-items: baseline;
+  padding: 12px 16px;
+  background: #f6ffed;
+  border: 1px solid #b7eb8f;
+  border-radius: 6px;
+  margin-bottom: 16px;
+
+  .amount-label {
+    font-size: 14px;
+    color: #606266;
+    margin-right: 8px;
+  }
+
+  .amount-value {
+    font-size: 22px;
+    font-weight: 700;
+    color: #52c41a;
+  }
+
+  .amount-count {
+    font-size: 12px;
+    color: #909399;
+    margin-left: 8px;
+  }
+}
 </style>

frontend/src/views/user/notifications.vue

@@ -35,26 +35,34 @@
 </template>
 
 <script setup>
-import { computed, onMounted } from 'vue'
+import { computed, onMounted, ref } from 'vue'
 import { useUserStore } from '@/stores'
+import {
+  BellOutlined,
+  FileTextOutlined,
+  DollarOutlined,
+  MessageOutlined
+} from '@ant-design/icons-vue'
 
 const userStore = useUserStore()
 
-const loading = false
+const loading = ref(false)
 const notifications = computed(() => userStore.notifications)
 
-onMounted(() => {
+onMounted(async () => {
-  userStore.loadNotifications()
+  loading.value = true
+  await userStore.loadNotifications()
+  loading.value = false
 })
 
 const getIcon = (type) => {
   const icons = {
-    system: 'Bell',
+    system: BellOutlined,
-    order: 'Document',
+    order: FileTextOutlined,
-    point: 'Coin',
+    point: DollarOutlined,
-    interaction: 'ChatDotRound'
+    interaction: MessageOutlined
   }
-  return icons[type] || 'Bell'
+  return icons[type] || BellOutlined
 }
 
 const handleClick = (notification) => {

frontend/src/views/user/skills.vue

@@ -91,22 +91,24 @@ const loadFavorites = async () => {
     loading.value = true
     const res = await favoriteApi.getMyFavorites()
     const skillIds = res.data || []
-    const skills = []
+    if (skillIds.length === 0) {
-    for (const id of skillIds) {
+      favoriteSkillList.value = []
-      try {
+      return
-        const detail = await skillApi.getDetail(id)
+    }
-        if (detail.data) {
+    const results = await Promise.allSettled(
-          const s = detail.data
+      skillIds.map(id => skillApi.getDetail(id))
-          skills.push({
+    )
+    favoriteSkillList.value = results
+      .filter(r => r.status === 'fulfilled' && r.value?.data)
+      .map(r => {
+        const s = r.value.data
+        return {
           id: s.id,
           name: s.name || s.title,
           cover: s.coverImage || s.cover,
           description: s.description || s.subtitle || ''
+        }
       })
-        }
-      } catch { /* skip deleted skills */ }
-    }
-    favoriteSkillList.value = skills
   } catch {
     favoriteSkillList.value = []
   } finally {

openclaw-backend/openclaw-backend/.gitignore

@@ -0,0 +1,13 @@
+target/
+*.class
+*.jar
+*.war
+*.log
+.idea/
+*.iml
+.vscode/
+.settings/
+.project
+.classpath
+# 本地密钥配置（不提交）
+application-local.yml

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/OpenclawApplication.java

@@ -3,9 +3,10 @@ package com.openclaw;
 import org.mybatis.spring.annotation.MapperScan;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.boot.autoconfigure.security.servlet.UserDetailsServiceAutoConfiguration;
 import org.springframework.scheduling.annotation.EnableScheduling;
 
-@SpringBootApplication
+@SpringBootApplication(exclude = { UserDetailsServiceAutoConfiguration.class })
 @EnableScheduling
 @MapperScan({"com.openclaw.module.**.repository", "com.openclaw.common.leaf", "com.openclaw.common.compensation"})
 public class OpenclawApplication {

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/annotation/RateLimit.java

@@ -0,0 +1,24 @@
+package com.openclaw.annotation;
+
+import java.lang.annotation.*;
+
+/**
+ * 接口限流注解，基于Redis滑动窗口实现
+ * 可标注在Controller方法上，限制单个IP或用户的请求频率
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface RateLimit {
+    /** 时间窗口（秒） */
+    int window() default 60;
+
+    /** 窗口内最大请求数 */
+    int maxRequests() default 10;
+
+    /** 限流维度：ip / user / ip+uri（默认按IP+URI） */
+    String key() default "ip+uri";
+
+    /** 被限流时的提示消息 */
+    String message() default "请求过于频繁，请稍后再试";
+}

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/common/mq/consumer/InviteEventConsumer.java

@@ -30,6 +30,14 @@ public class InviteEventConsumer {
             log.info("[MQ] 邀请绑定成功: inviterId={}, inviteeId={}, code={}",
                     event.getInviterId(), event.getInviteeId(), event.getInviteCode());
 
+            // 幂等：检查奖励是否已发放，防止MQ重试导致重复发积分
+            InviteRecord record = inviteRecordRepo.selectById(event.getInviteRecordId());
+            if (record != null && Boolean.TRUE.equals(record.getRewardGiven())) {
+                log.info("[MQ] 邀请奖励已发放，跳过: recordId={}", event.getInviteRecordId());
+                channel.basicAck(tag, false);
+                return;
+            }
+
             // 发放邀请人积分
             if (event.getInviterPoints() != null && event.getInviterPoints() > 0) {
                 inviteService.addPointsDirectly(event.getInviterId(), event.getInviterPoints(),
@@ -43,7 +51,6 @@ public class InviteEventConsumer {
             }
 
             // 标记奖励已发放
-            InviteRecord record = inviteRecordRepo.selectById(event.getInviteRecordId());
             if (record != null) {
                 record.setRewardGiven(true);
                 record.setRewardedAt(java.time.LocalDateTime.now());
@@ -54,7 +61,8 @@ public class InviteEventConsumer {
         } catch (Exception e) {
             log.error("[MQ] 处理邀请积分发放失败: inviterId={}, inviteeId={}",
                     event.getInviterId(), event.getInviteeId(), e);
-            channel.basicNack(tag, false, false);
+            boolean redelivered = message.getMessageProperties().getRedelivered();
+            channel.basicNack(tag, false, !redelivered);
         }
     }
 
@@ -70,7 +78,8 @@ public class InviteEventConsumer {
             channel.basicAck(tag, false);
         } catch (Exception e) {
             log.error("[MQ] 处理邀请码过期失败: inviterId={}", event.getInviterId(), e);
-            channel.basicNack(tag, false, false);
+            boolean redelivered = message.getMessageProperties().getRedelivered();
+            channel.basicNack(tag, false, !redelivered);
         }
     }
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/common/mq/consumer/OrderEventConsumer.java

@@ -59,9 +59,16 @@ public class OrderEventConsumer {
             channel.basicAck(tag, false);
         } catch (Exception e) {
             log.error("[MQ] 处理订单支付失败: orderId={}", event.getOrderId(), e);
+            boolean redelivered = message.getMessageProperties().getRedelivered();
+            if (!redelivered) {
+                log.warn("[MQ] 订单支付消息将重入队重试: orderId={}", event.getOrderId());
+                channel.basicNack(tag, false, true);
+            } else {
+                log.error("[MQ] 订单支付消息重试仍失败，放弃: orderId={}", event.getOrderId());
                 channel.basicNack(tag, false, false);
             }
         }
+    }
 
     /**
      * 订单超时未支付 → 自动取消订单
@@ -75,7 +82,8 @@ public class OrderEventConsumer {
             channel.basicAck(tag, false);
         } catch (Exception e) {
             log.error("[MQ] 处理订单超时失败: orderId={}", event.getOrderId(), e);
-            channel.basicNack(tag, false, false);
+            boolean redelivered = message.getMessageProperties().getRedelivered();
+            channel.basicNack(tag, false, !redelivered);
         }
     }
 
@@ -92,7 +100,8 @@ public class OrderEventConsumer {
             channel.basicAck(tag, false);
         } catch (Exception e) {
             log.error("[MQ] 处理订单取消失败: orderNo={}", orderNo, e);
-            channel.basicNack(tag, false, false);
+            boolean redelivered = message.getMessageProperties().getRedelivered();
+            channel.basicNack(tag, false, !redelivered);
         }
     }
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/common/mq/consumer/PaymentEventConsumer.java

@@ -47,7 +47,8 @@ public class PaymentEventConsumer {
             channel.basicAck(tag, false);
         } catch (Exception e) {
             log.error("[MQ] 处理充值积分发放失败: rechargeOrderId={}", event.getRechargeOrderId(), e);
-            channel.basicNack(tag, false, false);
+            boolean redelivered = message.getMessageProperties().getRedelivered();
+            channel.basicNack(tag, false, !redelivered);
         }
     }
 
@@ -69,7 +70,8 @@ public class PaymentEventConsumer {
             channel.basicAck(tag, false);
         } catch (Exception e) {
             log.error("[MQ] 处理充值超时失败: rechargeOrderNo={}", rechargeOrderNo, e);
-            channel.basicNack(tag, false, false);
+            boolean redelivered = message.getMessageProperties().getRedelivered();
+            channel.basicNack(tag, false, !redelivered);
         }
     }
 
@@ -121,7 +123,8 @@ public class PaymentEventConsumer {
             channel.basicAck(tag, false);
         } catch (Exception e) {
             log.error("[MQ] 处理退款失败: refundId={}", event.getRefundId(), e);
-            channel.basicNack(tag, false, false);
+            boolean redelivered = message.getMessageProperties().getRedelivered();
+            channel.basicNack(tag, false, !redelivered);
         }
     }
 
@@ -137,7 +140,8 @@ public class PaymentEventConsumer {
             channel.basicAck(tag, false);
         } catch (Exception e) {
             log.error("[MQ] 处理退款超时提醒失败: refundId={}", refundIdStr, e);
-            channel.basicNack(tag, false, false);
+            boolean redelivered = message.getMessageProperties().getRedelivered();
+            channel.basicNack(tag, false, !redelivered);
         }
     }
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/common/mq/consumer/UserEventConsumer.java

@@ -45,7 +45,15 @@ public class UserEventConsumer {
             channel.basicAck(tag, false);
         } catch (Exception e) {
             log.error("[MQ] 处理用户注册失败: userId={}", event.getUserId(), e);
+            // 首次失败允许重入队重试，重试仍失败则放弃（进死信队列）
+            boolean redelivered = message.getMessageProperties().getRedelivered();
+            if (!redelivered) {
+                log.warn("[MQ] 用户注册消息将重入队重试: userId={}", event.getUserId());
+                channel.basicNack(tag, false, true);
+            } else {
+                log.error("[MQ] 用户注册消息重试仍失败，放弃处理: userId={}", event.getUserId());
                 channel.basicNack(tag, false, false);
             }
         }
+    }
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/config/CorsFilterConfig.java

@@ -0,0 +1,39 @@
+package com.openclaw.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.cors.CorsConfiguration;
+import org.springframework.web.cors.CorsConfigurationSource;
+import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
+
+import java.util.List;
+
+/**
+ * CORS 配置源（由 Spring Security 的 CorsFilter 统一处理）
+ * 解决 OPTIONS 预检请求被拦截导致跨域失败的问题
+ */
+@Configuration
+public class CorsFilterConfig {
+
+    @Bean
+    public CorsConfigurationSource corsConfigurationSource() {
+        CorsConfiguration config = new CorsConfiguration();
+        config.setAllowedOriginPatterns(List.of(
+            "http://localhost:*",
+            "http://127.0.0.1:*",
+            "http://192.168.*.*:*",
+            "http://10.*.*.*:*",
+            "http://172.16.*.*:*",
+            "https://*.openclaw.com"
+        ));
+        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"));
+        config.setAllowedHeaders(List.of("*"));
+        config.setExposedHeaders(List.of("Authorization", "Content-Disposition"));
+        config.setAllowCredentials(true);
+        config.setMaxAge(3600L);
+
+        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+        source.registerCorsConfiguration("/**", config);
+        return source;
+    }
+}

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/config/OpenApiConfig.java

@@ -3,9 +3,12 @@ package com.openclaw.config;
 import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.info.Contact;
 import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
 import io.swagger.v3.oas.models.security.SecurityRequirement;
 import io.swagger.v3.oas.models.security.SecurityScheme;
 import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.ExternalDocumentation;
+import org.springdoc.core.models.GroupedOpenApi;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
@@ -16,12 +19,23 @@ public class OpenApiConfig {
     public OpenAPI openAPI() {
         return new OpenAPI()
             .info(new Info()
-                .title("OpenClaw Skills Platform API")
+                .title("OpenClaw Skills 数字员工平台 API")
-                .description("数字员工交易平台后端接口文档")
+                .description("OpenClaw 数字员工交易平台完整后端接口文档。\n\n"
+                    + "## 认证方式\n"
+                    + "- 用户端接口：登录后获取 JWT Token，在请求头中添加 `Authorization: Bearer {token}`\n"
+                    + "- 管理端接口：管理员登录后获取 Admin Token，同样使用 Bearer 认证\n"
+                    + "- 公开接口：无需认证，如技能列表、分类、注册登录等\n\n"
+                    + "## 通用响应格式\n"
+                    + "```json\n{\"code\": 200, \"message\": \"success\", \"data\": {}}\n```")
                 .version("1.0.0")
                 .contact(new Contact()
                     .name("OpenClaw Team")
-                    .email("dev@openclaw.com")))
+                    .email("dev@openclaw.com"))
+                .license(new License()
+                    .name("MIT")))
+            .externalDocs(new ExternalDocumentation()
+                .description("OpenClaw Skills 平台文档")
+                .url("https://docs.openclaw.com"))
             .addSecurityItem(new SecurityRequirement().addList("Bearer Token"))
             .components(new Components()
                 .addSecuritySchemes("Bearer Token",
@@ -29,6 +43,32 @@ public class OpenApiConfig {
                         .type(SecurityScheme.Type.HTTP)
                         .scheme("bearer")
                         .bearerFormat("JWT")
-                        .description("JWT 认证令牌，登录后获取")));
+                        .description("JWT 认证令牌。用户调用 POST /api/v1/users/login 获取，"
+                            + "管理员调用 POST /api/v1/admin/login 获取。")));
+    }
+
+    @Bean
+    public GroupedOpenApi userApi() {
+        return GroupedOpenApi.builder()
+            .group("1-用户端接口")
+            .pathsToMatch("/api/v1/**")
+            .pathsToExclude("/api/v1/admin/**")
+            .build();
+    }
+
+    @Bean
+    public GroupedOpenApi adminApi() {
+        return GroupedOpenApi.builder()
+            .group("2-管理端接口")
+            .pathsToMatch("/api/v1/admin/**")
+            .build();
+    }
+
+    @Bean
+    public GroupedOpenApi allApi() {
+        return GroupedOpenApi.builder()
+            .group("0-全部接口")
+            .pathsToMatch("/api/**")
+            .build();
     }
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/config/SecurityConfig.java

@@ -2,6 +2,7 @@ package com.openclaw.config;
 
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.Customizer;
 import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
@@ -23,6 +24,7 @@ public class SecurityConfig {
     @Bean
     public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
         http
+            .cors(Customizer.withDefaults())
             .csrf(csrf -> csrf.disable())
             .sessionManagement(sm -> sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
             .authorizeHttpRequests(auth -> auth

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/config/WebMvcConfig.java

@@ -3,6 +3,7 @@ package com.openclaw.config;
 import com.openclaw.interceptor.AuthInterceptor;
 import com.openclaw.interceptor.OptionalAuthInterceptor;
 import com.openclaw.interceptor.PermissionCheckInterceptor;
+import com.openclaw.interceptor.RateLimitInterceptor;
 import com.openclaw.interceptor.RoleCheckInterceptor;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
@@ -15,6 +16,7 @@ import java.nio.file.Paths;
 @RequiredArgsConstructor
 public class WebMvcConfig implements WebMvcConfigurer {
 
+    private final RateLimitInterceptor rateLimitInterceptor;
     private final OptionalAuthInterceptor optionalAuthInterceptor;
     private final AuthInterceptor authInterceptor;
     private final RoleCheckInterceptor roleCheckInterceptor;
@@ -30,22 +32,15 @@ public class WebMvcConfig implements WebMvcConfigurer {
                 .addResourceLocations(absolutePath);
     }
 
-    @Override
+    // CORS 已移至 CorsFilterConfig（Servlet Filter 层级），避免被 Interceptor 拦截 OPTIONS 预检请求
-    public void addCorsMappings(CorsRegistry registry) {
-        registry.addMapping("/api/**")
-            .allowedOriginPatterns("http://localhost:*", "https://*.openclaw.com")
-            .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
-            .allowedHeaders("*")
-            .allowCredentials(true)
-            .maxAge(3600);
-        registry.addMapping("/uploads/**")
-            .allowedOriginPatterns("http://localhost:*", "https://*.openclaw.com")
-            .allowedMethods("GET")
-            .maxAge(3600);
-    }
 
     @Override
     public void addInterceptors(InterceptorRegistry registry) {
+        // 限流拦截器：最先执行，防止暴力攻击
+        registry.addInterceptor(rateLimitInterceptor)
+            .addPathPatterns("/api/**")
+            .order(-1);
+
         // 可选认证：公开接口中尝试提取用户身份（不阻断请求）
         registry.addInterceptor(optionalAuthInterceptor)
             .addPathPatterns("/api/**")
@@ -75,7 +70,9 @@ public class WebMvcConfig implements WebMvcConfigurer {
                 "/api/v1/config/**",       // 系统配置（充值档位、积分规则）
                 "/api/v1/share/**",        // 分享JS-SDK配置（公开）
                 "/api/v1/activities",      // 活动列表（公开）
-                "/api/v1/activities/*"     // 活动详情（公开）
+                "/api/v1/activities/*",    // 活动详情（公开）
+                "/api/v1/health",          // 健康检查（存活探针）
+                "/api/v1/health/**"        // 健康检查（就绪探针）
             );
 
         // 角色权限拦截器，在认证之后执行

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/constant/ErrorCode.java

@@ -18,6 +18,8 @@ public interface ErrorCode {
     BusinessError SKILL_NOT_FOUND      = new BusinessError(2001, "Skill不存在");
     BusinessError SKILL_OFFLINE        = new BusinessError(2002, "Skill已下架");
     BusinessError SKILL_ALREADY_OWNED  = new BusinessError(2003, "已拥有该Skill");
+    BusinessError REVIEW_NOT_ALLOWED    = new BusinessError(2004, "您尚未获取此Skill，无法评价");
+    BusinessError REVIEW_DUPLICATE      = new BusinessError(2005, "您已经评价过此Skill");
 
     // 积分模块 3xxx
     BusinessError POINTS_NOT_ENOUGH    = new BusinessError(3001, "积分不足");

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/interceptor/AuthInterceptor.java

@@ -6,6 +6,7 @@ import com.openclaw.util.JwtUtil;
 import com.openclaw.util.UserContext;
 import jakarta.servlet.http.*;
 import lombok.RequiredArgsConstructor;
+import org.springframework.data.redis.core.StringRedisTemplate;
 import org.springframework.stereotype.Component;
 import org.springframework.web.servlet.HandlerInterceptor;
 
@@ -14,6 +15,7 @@ import org.springframework.web.servlet.HandlerInterceptor;
 public class AuthInterceptor implements HandlerInterceptor {
 
     private final JwtUtil jwtUtil;
+    private final StringRedisTemplate redisTemplate;
 
     @Override
     public boolean preHandle(HttpServletRequest req,
@@ -24,9 +26,24 @@ public class AuthInterceptor implements HandlerInterceptor {
             throw new BusinessException(ErrorCode.UNAUTHORIZED);
         try {
             String token  = auth.substring(7);
+            // 检查 token 是否已被登出（Redis 黑名单）
+            if (Boolean.TRUE.equals(redisTemplate.hasKey("user:token:" + token))) {
+                throw new BusinessException(ErrorCode.UNAUTHORIZED);
+            }
             Long   userId = jwtUtil.getUserId(token);
             String role   = jwtUtil.getRole(token);
+            // 检查用户是否已换号（换号后所有旧 token 失效）
+            String phoneChanged = redisTemplate.opsForValue().get("user:phone_changed:" + userId);
+            if (phoneChanged != null) {
+                long changedAt = Long.parseLong(phoneChanged);
+                long tokenIssuedAt = jwtUtil.parse(token).getIssuedAt().getTime();
+                if (tokenIssuedAt < changedAt) {
+                    throw new BusinessException(ErrorCode.UNAUTHORIZED);
+                }
+            }
             UserContext.set(userId, role);
+        } catch (BusinessException e) {
+            throw e;
         } catch (Exception e) {
             throw new BusinessException(ErrorCode.UNAUTHORIZED);
         }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/interceptor/RateLimitInterceptor.java

@@ -0,0 +1,71 @@
+package com.openclaw.interceptor;
+
+import com.openclaw.annotation.RateLimit;
+import com.openclaw.exception.BusinessException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.stereotype.Component;
+import org.springframework.web.method.HandlerMethod;
+import org.springframework.web.servlet.HandlerInterceptor;
+
+import java.util.concurrent.TimeUnit;
+
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class RateLimitInterceptor implements HandlerInterceptor {
+
+    private final StringRedisTemplate redisTemplate;
+
+    @Override
+    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
+        if (!(handler instanceof HandlerMethod handlerMethod)) {
+            return true;
+        }
+        RateLimit rateLimit = handlerMethod.getMethodAnnotation(RateLimit.class);
+        if (rateLimit == null) {
+            return true;
+        }
+
+        String key = buildKey(request, rateLimit);
+        int window = rateLimit.window();
+        int maxRequests = rateLimit.maxRequests();
+
+        Long count = redisTemplate.opsForValue().increment(key);
+        if (count != null && count == 1) {
+            redisTemplate.expire(key, window, TimeUnit.SECONDS);
+        }
+        if (count != null && count > maxRequests) {
+            log.warn("限流触发: key={}, count={}, max={}", key, count, maxRequests);
+            throw new BusinessException(429, rateLimit.message());
+        }
+        return true;
+    }
+
+    private String buildKey(HttpServletRequest request, RateLimit rateLimit) {
+        String ip = getClientIp(request);
+        String uri = request.getRequestURI();
+        return switch (rateLimit.key()) {
+            case "ip" -> "rate_limit:" + ip;
+            case "user" -> "rate_limit:user:" + request.getAttribute("userId");
+            default -> "rate_limit:" + ip + ":" + uri;
+        };
+    }
+
+    private String getClientIp(HttpServletRequest request) {
+        String ip = request.getHeader("X-Forwarded-For");
+        if (ip != null && !ip.isEmpty()) {
+            ip = ip.split(",")[0].trim();
+        }
+        if (ip == null || ip.isEmpty()) {
+            ip = request.getHeader("X-Real-IP");
+        }
+        if (ip == null || ip.isEmpty()) {
+            ip = request.getRemoteAddr();
+        }
+        return ip;
+    }
+}

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/activity/controller/ActivityController.java

@@ -3,11 +3,13 @@ package com.openclaw.module.activity.controller;
 import com.openclaw.common.Result;
 import com.openclaw.module.activity.service.ActivityService;
 import com.openclaw.module.activity.vo.ActivityVO;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
+@Tag(name = "活动", description = "查询进行中的活动")
 @RestController
 @RequestMapping("/api/v1/activities")
 @RequiredArgsConstructor

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/activity/controller/AdminActivityController.java

@@ -8,9 +8,11 @@ import com.openclaw.module.activity.service.ActivityService;
 import com.openclaw.module.activity.vo.ActivityVO;
 import jakarta.validation.Valid;
 import com.openclaw.annotation.RequiresRole;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "[管理] 活动管理", description = "管理端-创建/编辑/删除/查询活动")
 @RestController
 @RequestMapping("/api/v1/admin/activities")
 @RequiresRole({"admin", "super_admin"})

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/admin/controller/AdminController.java

@@ -1,11 +1,13 @@
 package com.openclaw.module.admin.controller;
 
 import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.openclaw.annotation.RateLimit;
 import com.openclaw.annotation.RequiresRole;
 import com.openclaw.module.log.annotation.OpLog;
 import com.openclaw.common.Result;
 import com.openclaw.module.admin.dto.AdminLoginDTO;
 import com.openclaw.module.admin.dto.AdminSkillCreateDTO;
+import com.openclaw.module.admin.dto.AdminSkillUpdateDTO;
 import com.openclaw.module.admin.service.AdminService;
 import com.openclaw.module.admin.vo.*;
 import com.openclaw.module.customization.entity.CustomizationRequest;
@@ -14,9 +16,11 @@ import com.openclaw.module.developer.entity.DeveloperApplication;
 import com.openclaw.module.developer.service.DeveloperApplicationService;
 import com.openclaw.util.UserContext;
 import jakarta.validation.Valid;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "[管理] 后台总控", description = "管理员登录、用户/技能/订单/退款/开发者/定制需求管理")
 @RestController
 @RequestMapping("/api/v1/admin")
 @RequiredArgsConstructor
@@ -28,6 +32,7 @@ public class AdminController {
 
     // ==================== 登录（无需权限） ====================
 
+    @RateLimit(window = 60, maxRequests = 5, message = "登录请求过于频繁，请稍后再试")
     @PostMapping("/login")
     public Result<AdminLoginVO> login(@Valid @RequestBody AdminLoginDTO dto) {
         return Result.ok(adminService.login(dto));
@@ -152,6 +157,15 @@ public class AdminController {
         return Result.ok(adminService.createSkill(UserContext.getUserId(), dto));
     }
 
+    @PutMapping("/skills/{skillId}")
+    @RequiresRole("super_admin")
+    @OpLog(module = "skill", action = "update", description = "后台编辑Skill", targetType = "skill")
+    public Result<AdminSkillVO> updateSkill(
+            @PathVariable Long skillId,
+            @RequestBody AdminSkillUpdateDTO dto) {
+        return Result.ok(adminService.updateSkill(skillId, dto));
+    }
+
     // ==================== 订单管理 ====================
 
     @GetMapping("/orders")

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/admin/dto/AdminSkillUpdateDTO.java

@@ -0,0 +1,17 @@
+package com.openclaw.module.admin.dto;
+
+import lombok.Data;
+import java.math.BigDecimal;
+
+@Data
+public class AdminSkillUpdateDTO {
+    private String name;
+    private String description;
+    private String coverImageUrl;
+    private Integer categoryId;
+    private BigDecimal price;
+    private Boolean isFree;
+    private String version;
+    private String fileUrl;
+    private String status;
+}

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/admin/service/AdminService.java

@@ -3,6 +3,7 @@ package com.openclaw.module.admin.service;
 import com.baomidou.mybatisplus.core.metadata.IPage;
 import com.openclaw.module.admin.dto.AdminLoginDTO;
 import com.openclaw.module.admin.dto.AdminSkillCreateDTO;
+import com.openclaw.module.admin.dto.AdminSkillUpdateDTO;
 import com.openclaw.module.admin.vo.*;
 
 public interface AdminService {
@@ -27,6 +28,7 @@ public interface AdminService {
     void offlineSkill(Long skillId);
     void toggleFeatured(Long skillId);
     AdminSkillVO createSkill(Long adminUserId, AdminSkillCreateDTO dto);
+    AdminSkillVO updateSkill(Long skillId, AdminSkillUpdateDTO dto);
 
     // 订单管理
     IPage<AdminOrderVO> listOrders(String keyword, String status, int pageNum, int pageSize);

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/admin/service/impl/AdminServiceImpl.java

@@ -7,6 +7,7 @@ import com.openclaw.constant.ErrorCode;
 import com.openclaw.exception.BusinessException;
 import com.openclaw.module.admin.dto.AdminLoginDTO;
 import com.openclaw.module.admin.dto.AdminSkillCreateDTO;
+import com.openclaw.module.admin.dto.AdminSkillUpdateDTO;
 import com.openclaw.module.admin.service.AdminService;
 import com.openclaw.module.admin.vo.*;
 import com.openclaw.common.event.RefundApprovedEvent;
@@ -236,9 +237,14 @@ public class AdminServiceImpl implements AdminService {
         log.info("[Admin] 解封用户: userId={}", userId);
     }
 
+    private static final java.util.Set<String> VALID_ROLES = java.util.Set.of("user", "creator", "admin", "super_admin");
+
     @Override
     @Transactional
     public void changeUserRole(Long userId, String role) {
+        if (!VALID_ROLES.contains(role)) {
+            throw new BusinessException(ErrorCode.PARAM_ERROR.code(), "非法角色值: " + role);
+        }
         User user = userRepo.selectById(userId);
         if (user == null) throw new BusinessException(ErrorCode.USER_NOT_FOUND);
         user.setRole(role);
@@ -348,6 +354,32 @@ public class AdminServiceImpl implements AdminService {
         return toAdminSkillVO(skill);
     }
 
+    @Override
+    @Transactional
+    public AdminSkillVO updateSkill(Long skillId, AdminSkillUpdateDTO dto) {
+        Skill skill = skillRepo.selectById(skillId);
+        if (skill == null) throw new BusinessException(ErrorCode.SKILL_NOT_FOUND);
+
+        if (dto.getName() != null) skill.setName(dto.getName());
+        if (dto.getDescription() != null) skill.setDescription(dto.getDescription());
+        if (dto.getCoverImageUrl() != null) skill.setCoverImageUrl(dto.getCoverImageUrl());
+        if (dto.getCategoryId() != null) skill.setCategoryId(dto.getCategoryId());
+        if (dto.getPrice() != null) skill.setPrice(dto.getPrice());
+        if (dto.getIsFree() != null) skill.setIsFree(dto.getIsFree());
+        if (dto.getVersion() != null) skill.setVersion(dto.getVersion());
+        if (dto.getFileUrl() != null) skill.setFileUrl(dto.getFileUrl());
+        if (dto.getStatus() != null) {
+            if (!java.util.Set.of("draft", "pending", "approved", "rejected", "offline").contains(dto.getStatus())) {
+                throw new BusinessException(ErrorCode.PARAM_ERROR.code(), "非法Skill状态值: " + dto.getStatus());
+            }
+            skill.setStatus(dto.getStatus());
+        }
+
+        skillRepo.updateById(skill);
+        log.info("[Admin] 管理员编辑Skill: skillId={}, name={}", skill.getId(), skill.getName());
+        return toAdminSkillVO(skill);
+    }
+
     // ==================== 订单管理 ====================
 
     @Override

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/common/controller/ConfigController.java

@@ -4,6 +4,7 @@ import com.openclaw.common.Result;
 import com.openclaw.module.payment.config.RechargeConfig;
 import com.openclaw.module.points.entity.PointsRule;
 import com.openclaw.module.points.repository.PointsRuleRepository;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -14,6 +15,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
+@Tag(name = "公共配置", description = "充值选项、积分规则等公共配置")
 @RestController
 @RequestMapping("/api/v1/config")
 @RequiredArgsConstructor

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/common/controller/FileUploadController.java

@@ -7,6 +7,7 @@ import com.openclaw.util.UserContext;
 import com.qcloud.cos.COSClient;
 import com.qcloud.cos.model.ObjectMetadata;
 import com.qcloud.cos.model.PutObjectRequest;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -23,6 +24,7 @@ import java.util.Map;
 import java.util.Set;
 import java.util.UUID;
 
+@Tag(name = "文件上传", description = "图片/文件上传到COS")
 @Slf4j
 @RestController
 @RequestMapping("/api/v1/upload")

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/common/controller/HealthController.java

@@ -0,0 +1,70 @@
+package com.openclaw.module.common.controller;
+
+import com.openclaw.common.Result;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import javax.sql.DataSource;
+import java.sql.Connection;
+import java.time.LocalDateTime;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+@Tag(name = "健康检查", description = "服务健康状态、数据库/Redis连通性检查")
+@RestController
+@RequestMapping("/api/v1/health")
+@RequiredArgsConstructor
+public class HealthController {
+
+    private final DataSource dataSource;
+    private final StringRedisTemplate redisTemplate;
+
+    @Value("${spring.application.name:openclaw-backend}")
+    private String appName;
+
+    /** 基础存活探针（无依赖检查） */
+    @GetMapping
+    public Result<Map<String, Object>> health() {
+        Map<String, Object> info = new LinkedHashMap<>();
+        info.put("status", "UP");
+        info.put("app", appName);
+        info.put("time", LocalDateTime.now().toString());
+        return Result.ok(info);
+    }
+
+    /** 深度就绪探针（检查 DB + Redis） */
+    @GetMapping("/ready")
+    public Result<Map<String, Object>> readiness() {
+        Map<String, Object> info = new LinkedHashMap<>();
+        info.put("app", appName);
+        info.put("time", LocalDateTime.now().toString());
+
+        // DB check
+        try (Connection conn = dataSource.getConnection()) {
+            conn.createStatement().execute("SELECT 1");
+            info.put("db", "UP");
+        } catch (Exception e) {
+            info.put("db", "DOWN: " + e.getMessage());
+        }
+
+        // Redis check
+        try {
+            var factory = redisTemplate.getConnectionFactory();
+            if (factory == null) throw new IllegalStateException("Redis ConnectionFactory is null");
+            String pong = factory.getConnection().ping();
+            info.put("redis", pong != null ? "UP" : "DOWN");
+        } catch (Exception e) {
+            info.put("redis", "DOWN: " + e.getMessage());
+        }
+
+        boolean allUp = "UP".equals(info.get("db")) && "UP".equals(info.get("redis"));
+        info.put("status", allUp ? "UP" : "DEGRADED");
+
+        return Result.ok(info);
+    }
+}

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/common/controller/StatsController.java

@@ -5,6 +5,7 @@ import com.openclaw.common.Result;
 import com.openclaw.module.order.repository.OrderRepository;
 import com.openclaw.module.skill.repository.SkillRepository;
 import com.openclaw.module.user.repository.UserRepository;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -13,6 +14,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.HashMap;
 import java.util.Map;
 
+@Tag(name = "统计数据", description = "平台概览统计")
 @RestController
 @RequestMapping("/api/v1/stats")
 @RequiredArgsConstructor

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/community/controller/AdminCommunityController.java

@@ -10,6 +10,7 @@ import com.openclaw.module.community.repository.CommunityJoinRequestRepository;
 import com.openclaw.module.coupon.dto.CouponIssueDTO;
 import com.openclaw.module.coupon.service.CouponService;
 import com.openclaw.util.UserContext;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.*;
@@ -18,6 +19,7 @@ import java.time.LocalDateTime;
 import java.util.List;
 import java.util.Map;
 
+@Tag(name = "[管理] 社区管理", description = "管理端-社群申请审核、批量发券")
 @Slf4j
 @RestController
 @RequestMapping("/api/v1/admin/community")

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/community/controller/CommunityController.java

@@ -5,12 +5,14 @@ import com.openclaw.common.Result;
 import com.openclaw.module.community.entity.CommunityJoinRequest;
 import com.openclaw.module.community.repository.CommunityJoinRequestRepository;
 import com.openclaw.util.UserContext;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.time.LocalDateTime;
 import java.util.Map;
 
+@Tag(name = "社区", description = "社群加入申请")
 @RestController
 @RequestMapping("/api/v1/community")
 @RequiredArgsConstructor

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/content/controller/AnnouncementController.java

@@ -9,11 +9,13 @@ import com.openclaw.module.content.service.AnnouncementService;
 import com.openclaw.module.content.vo.AnnouncementVO;
 import com.openclaw.util.UserContext;
 import jakarta.validation.Valid;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
+@Tag(name = "公告管理", description = "公告列表、创建/编辑/删除公告")
 @RestController
 @RequiredArgsConstructor
 public class AnnouncementController {

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/content/controller/BannerController.java

@@ -9,11 +9,13 @@ import com.openclaw.module.content.service.BannerService;
 import com.openclaw.module.content.vo.BannerVO;
 import com.openclaw.util.UserContext;
 import jakarta.validation.Valid;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
+@Tag(name = "Banner管理", description = "轮播图列表、创建/编辑/删除")
 @RestController
 @RequiredArgsConstructor
 public class BannerController {

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/coupon/controller/AdminCouponController.java

@@ -9,9 +9,11 @@ import com.openclaw.module.coupon.dto.CouponTemplateUpdateDTO;
 import com.openclaw.module.coupon.service.CouponService;
 import com.openclaw.module.coupon.vo.CouponTemplateVO;
 import jakarta.validation.Valid;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "[管理] 优惠券管理", description = "管理端-券模板创建/编辑、手动发券")
 @RestController
 @RequestMapping("/api/v1/admin/coupons")
 @RequiresRole({"admin", "super_admin"})

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/coupon/controller/CouponController.java

@@ -6,13 +6,15 @@ import com.openclaw.module.coupon.service.CouponService;
 import com.openclaw.module.coupon.vo.CouponCalcResultVO;
 import com.openclaw.module.coupon.vo.CouponTemplateVO;
 import com.openclaw.module.coupon.vo.UserCouponVO;
-import jakarta.servlet.http.HttpServletRequest;
+import com.openclaw.util.UserContext;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.math.BigDecimal;
 import java.util.List;
 
+@Tag(name = "优惠券", description = "领取、查询、使用优惠券")
 @RestController
 @RequestMapping("/api/v1/coupons")
 @RequiredArgsConstructor
@@ -22,45 +24,41 @@ public class CouponController {
 
     /** 可领取的优惠券列表 */
     @GetMapping("/available")
-    public Result<List<CouponTemplateVO>> getAvailableTemplates(HttpServletRequest request) {
+    public Result<List<CouponTemplateVO>> getAvailableTemplates() {
-        Long userId = (Long) request.getAttribute("userId");
+        Long userId = UserContext.getUserId();
         return Result.ok(couponService.getAvailableTemplates(userId));
     }
 
     /** 领取优惠券 */
     @PostMapping("/receive/{templateId}")
-    public Result<UserCouponVO> receiveCoupon(HttpServletRequest request,
+    public Result<UserCouponVO> receiveCoupon(@PathVariable Long templateId) {
-                                               @PathVariable Long templateId) {
+        Long userId = UserContext.getUserId();
-        Long userId = (Long) request.getAttribute("userId");
         return Result.ok(couponService.receiveCoupon(userId, templateId));
     }
 
     /** 我的优惠券列表 */
     @GetMapping("/mine")
-    public Result<IPage<UserCouponVO>> getMyCoupons(HttpServletRequest request,
+    public Result<IPage<UserCouponVO>> getMyCoupons(@RequestParam(required = false) String status,
-                                                     @RequestParam(required = false) String status,
                                                      @RequestParam(defaultValue = "1") int pageNum,
                                                      @RequestParam(defaultValue = "10") int pageSize) {
-        Long userId = (Long) request.getAttribute("userId");
+        Long userId = UserContext.getUserId();
         pageSize = Math.min(pageSize, 50);
         return Result.ok(couponService.getMyCoupons(userId, status, pageNum, pageSize));
     }
 
     /** 下单时查询可用优惠券 */
     @GetMapping("/usable")
-    public Result<List<UserCouponVO>> getUsableCoupons(HttpServletRequest request,
+    public Result<List<UserCouponVO>> getUsableCoupons(@RequestParam List<Long> skillIds,
-                                                        @RequestParam List<Long> skillIds,
                                                         @RequestParam BigDecimal orderAmount) {
-        Long userId = (Long) request.getAttribute("userId");
+        Long userId = UserContext.getUserId();
         return Result.ok(couponService.getUsableCoupons(userId, skillIds, orderAmount));
     }
 
     /** 计算优惠券抵扣金额(预览) */
     @GetMapping("/calc")
-    public Result<CouponCalcResultVO> calcDiscount(HttpServletRequest request,
+    public Result<CouponCalcResultVO> calcDiscount(@RequestParam Long couponId,
-                                                    @RequestParam Long couponId,
                                                     @RequestParam BigDecimal orderAmount) {
-        Long userId = (Long) request.getAttribute("userId");
+        Long userId = UserContext.getUserId();
         return Result.ok(couponService.calcDiscount(userId, couponId, orderAmount));
     }
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/coupon/service/impl/CouponServiceImpl.java

@@ -360,6 +360,12 @@ public class CouponServiceImpl implements CouponService {
         if (template == null) {
             throw new BusinessException(ErrorCode.COUPON_TEMPLATE_NOT_FOUND);
         }
+        // 管理员发券时，自动激活草稿状态的模板
+        if ("draft".equals(template.getStatus())) {
+            template.setStatus("active");
+            templateRepo.updateById(template);
+            log.info("管理员发券时自动激活优惠券模板[{}]", template.getId());
+        }
 
         int issued = 0;
         for (Long userId : dto.getUserIds()) {

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/customization/controller/CustomizationController.java

@@ -4,10 +4,12 @@ import com.openclaw.common.Result;
 import com.openclaw.module.customization.dto.CustomizationRequestDTO;
 import com.openclaw.module.customization.service.CustomizationRequestService;
 import com.openclaw.util.UserContext;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "定制需求", description = "提交定制需求")
 @RestController
 @RequestMapping("/api/v1/customization")
 @RequiredArgsConstructor

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/developer/controller/DeveloperController.java

@@ -4,9 +4,11 @@ import com.openclaw.common.Result;
 import com.openclaw.module.developer.dto.DeveloperApplicationDTO;
 import com.openclaw.module.developer.service.DeveloperApplicationService;
 import com.openclaw.util.UserContext;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "开发者申请", description = "提交/查询开发者申请")
 @RestController
 @RequestMapping("/api/v1/developer")
 @RequiredArgsConstructor
@@ -18,7 +20,7 @@ public class DeveloperController {
      * 提交开发者申请
      */
     @PostMapping("/application")
-    public Result<Void> submitApplication(@RequestBody DeveloperApplicationDTO dto) {
+    public Result<Void> submitApplication(@jakarta.validation.Valid @RequestBody DeveloperApplicationDTO dto) {
         Long userId = UserContext.getUserId();
         applicationService.submitApplication(userId, dto);
         return Result.ok();

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/feedback/controller/FeedbackController.java

@@ -8,10 +8,12 @@ import com.openclaw.module.feedback.dto.FeedbackReplyDTO;
 import com.openclaw.module.feedback.service.FeedbackService;
 import com.openclaw.module.feedback.vo.FeedbackVO;
 import com.openclaw.util.UserContext;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "用户反馈", description = "提交反馈、查询反馈、管理端回复")
 @RestController
 @RequiredArgsConstructor
 public class FeedbackController {

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/feedback/service/impl/FeedbackServiceImpl.java

@@ -159,6 +159,9 @@ public class FeedbackServiceImpl implements FeedbackService {
 
     @Override
     public void changeStatus(Long id, String status) {
+        if (!STATUS_LABELS.containsKey(status)) {
+            throw new BusinessException(400, "无效的状态值: " + status);
+        }
         Feedback feedback = feedbackRepository.selectById(id);
         if (feedback == null) {
             throw new BusinessException(ErrorCode.NOT_FOUND);

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/help/controller/AdminHelpController.java

@@ -10,11 +10,13 @@ import com.openclaw.module.help.vo.HelpArticleVO;
 import com.openclaw.module.help.vo.HelpCategoryVO;
 import com.openclaw.annotation.RequiresRole;
 import jakarta.validation.Valid;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
+@Tag(name = "[管理] 帮助中心", description = "管理端-帮助分类和文章CRUD")
 @RestController
 @RequestMapping("/api/v1/admin/help")
 @RequiresRole({"admin", "super_admin"})

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/help/controller/HelpController.java

@@ -5,11 +5,13 @@ import com.openclaw.module.help.service.HelpService;
 import com.openclaw.module.help.vo.HelpArticleListVO;
 import com.openclaw.module.help.vo.HelpArticleVO;
 import com.openclaw.module.help.vo.HelpCategoryVO;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
+@Tag(name = "帮助中心", description = "帮助分类、文章列表、文章详情")
 @RestController
 @RequestMapping("/api/v1/help")
 @RequiredArgsConstructor

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/invite/controller/InviteController.java

@@ -6,10 +6,12 @@ import com.openclaw.module.invite.dto.BindInviteDTO;
 import com.openclaw.module.invite.service.InviteService;
 import com.openclaw.util.UserContext;
 import com.openclaw.module.invite.vo.*;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "邀请管理", description = "邀请码、邀请记录、绑定邀请码")
 @RestController
 @RequestMapping("/api/v1/invites")
 @RequiredArgsConstructor

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/invoice/controller/InvoiceController.java

@@ -8,10 +8,12 @@ import com.openclaw.module.invoice.dto.InvoiceReviewDTO;
 import com.openclaw.module.invoice.service.InvoiceService;
 import com.openclaw.module.invoice.vo.InvoiceVO;
 import com.openclaw.util.UserContext;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "发票管理", description = "申请发票、查询发票、审核发票")
 @RestController
 @RequiredArgsConstructor
 public class InvoiceController {

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/log/controller/OperationLogController.java

@@ -5,9 +5,11 @@ import com.openclaw.annotation.RequiresRole;
 import com.openclaw.common.Result;
 import com.openclaw.module.log.service.OperationLogService;
 import com.openclaw.module.log.vo.OperationLogVO;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "[管理] 操作日志", description = "管理端-操作日志查询")
 @RestController
 @RequestMapping("/api/v1/admin/logs")
 @RequiredArgsConstructor

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/member/controller/AdminMemberLevelController.java

@@ -4,11 +4,13 @@ import com.openclaw.annotation.RequiresRole;
 import com.openclaw.common.Result;
 import com.openclaw.module.member.entity.MemberLevelConfig;
 import com.openclaw.module.member.repository.MemberLevelConfigRepository;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
+@Tag(name = "[管理] 会员等级", description = "管理端-会员等级配置CRUD")
 @RestController
 @RequestMapping("/api/v1/admin/member-levels")
 @RequiresRole({"admin", "super_admin"})

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/member/controller/MemberController.java

@@ -8,12 +8,14 @@ import com.openclaw.module.member.entity.GrowthRecord;
 import com.openclaw.module.member.service.MemberService;
 import com.openclaw.module.member.vo.MemberLevelVO;
 import com.openclaw.util.UserContext;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
+@Tag(name = "会员等级", description = "等级详情、成长值记录")
 @RestController
 @RequestMapping("/api/v1/member")
 @RequiredArgsConstructor

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/notification/controller/NotificationController.java

@@ -5,9 +5,11 @@ import com.openclaw.common.Result;
 import com.openclaw.util.UserContext;
 import com.openclaw.module.notification.entity.Notification;
 import com.openclaw.module.notification.service.NotificationService;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "消息通知", description = "用户消息列表、读取、标记")
 @RestController
 @RequestMapping("/api/v1/notifications")
 @RequiredArgsConstructor
@@ -19,6 +21,7 @@ public class NotificationController {
     public Result<IPage<Notification>> list(
             @RequestParam(defaultValue = "1") int pageNum,
             @RequestParam(defaultValue = "20") int pageSize) {
+        pageSize = Math.min(Math.max(pageSize, 1), 50);
         Long userId = UserContext.getUserId();
         return Result.ok(notificationService.getUserNotifications(userId, pageNum, pageSize));
     }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/order/controller/OrderController.java

@@ -7,11 +7,14 @@ import com.openclaw.module.order.service.OrderService;
 import com.openclaw.annotation.RequiresRole;
 import com.openclaw.util.UserContext;
 import com.openclaw.module.order.vo.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.util.List;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "订单管理", description = "创建订单、支付、取消、退款")
 @RestController
 @RequestMapping("/api/v1/orders")
 @RequiredArgsConstructor
@@ -20,7 +23,7 @@ public class OrderController {
 
     private final OrderService orderService;
 
-    /** 订单预览（不创建订单，仅计算金额） */
+    @Operation(summary = "订单预览", description = "计算金额、优惠、积分抵扣，不创建订单")
     @GetMapping("/preview")
     public Result<OrderPreviewVO> previewOrder(
             @RequestParam List<Long> skillIds,
@@ -29,26 +32,28 @@ public class OrderController {
         return Result.ok(orderService.previewOrder(UserContext.getUserId(), skillIds, pointsToUse, couponId));
     }
 
+    @Operation(summary = "创建订单")
     @PostMapping
     public Result<OrderVO> createOrder(@Valid @RequestBody OrderCreateDTO dto) {
         return Result.ok(orderService.createOrder(UserContext.getUserId(), dto));
     }
 
-    /** 获取订单详情 */
+    @Operation(summary = "获取订单详情")
     @GetMapping("/{id}")
     public Result<OrderVO> getOrder(@PathVariable Long id) {
         return Result.ok(orderService.getOrderDetail(UserContext.getUserId(), id));
     }
 
-    /** 获取我的订单列表 */
+    @Operation(summary = "我的订单列表", description = "分页查询")
     @GetMapping
     public Result<IPage<OrderVO>> listOrders(
             @RequestParam(defaultValue = "1") int pageNum,
             @RequestParam(defaultValue = "10") int pageSize) {
+        pageSize = Math.min(Math.max(pageSize, 1), 50);
         return Result.ok(orderService.listMyOrders(UserContext.getUserId(), pageNum, pageSize));
     }
 
-    /** 支付订单 */
+    @Operation(summary = "支付订单")
     @PostMapping("/{id}/pay")
     public Result<Void> payOrder(
             @PathVariable Long id,
@@ -57,7 +62,7 @@ public class OrderController {
         return Result.ok();
     }
 
-    /** 取消订单 */
+    @Operation(summary = "取消订单")
     @PostMapping("/{id}/cancel")
     public Result<Void> cancelOrder(
             @PathVariable Long id,
@@ -66,7 +71,7 @@ public class OrderController {
         return Result.ok();
     }
 
-    /** 申请退款 */
+    @Operation(summary = "申请退款")
     @PostMapping("/{id}/refund")
     public Result<Void> applyRefund(
             @PathVariable Long id,

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/order/entity/Order.java

@@ -12,7 +12,9 @@ public class Order {
     private Long id;
     private String orderNo;
     private Long userId;
-    private BigDecimal totalAmount;
+    private BigDecimal originalAmount;       // 原价总额（促销前）
+    private BigDecimal totalAmount;            // 促销后总额
+    private BigDecimal promotionDeductAmount;  // 促销优惠金额
     private BigDecimal cashAmount;
     private Integer pointsUsed;
     private BigDecimal pointsDeductAmount;

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/order/entity/OrderItem.java

@@ -13,9 +13,11 @@ public class OrderItem {
     private Long skillId;
     private String skillName;    // 下单时快照
     private String skillCover;   // 下单时快照
-    private BigDecimal unitPrice;
+    private BigDecimal originalPrice;  // 原价（促销前）
+    private BigDecimal unitPrice;      // 实际单价（促销后）
     private Integer quantity;
     private BigDecimal totalPrice;
+    private Long promotionId;          // 关联的促销活动ID（NULL=无促销）
     @TableLogic(value = "0", delval = "1")
     private Integer deleted;
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/order/repository/OrderRepository.java

@@ -24,4 +24,12 @@ public interface OrderRepository extends BaseMapper<Order> {
     /** CAS方式更新订单状态（幂等性保护），返回受影响行数 */
     @Update("UPDATE orders SET status = #{newStatus}, paid_at = #{paidAt}, updated_at = NOW() WHERE id = #{orderId} AND status = #{expectedStatus} AND deleted = 0")
     int casUpdateStatus(@Param("orderId") Long orderId, @Param("expectedStatus") String expectedStatus, @Param("newStatus") String newStatus, @Param("paidAt") LocalDateTime paidAt);
+
+    /** CAS方式更新订单状态（不更新paidAt），用于取消等操作防止并发竞态 */
+    @Update("UPDATE orders SET status = #{newStatus}, cancel_reason = #{cancelReason}, updated_at = NOW() WHERE id = #{orderId} AND status = #{expectedStatus} AND deleted = 0")
+    int casCancel(@Param("orderId") Long orderId, @Param("expectedStatus") String expectedStatus, @Param("newStatus") String newStatus, @Param("cancelReason") String cancelReason);
+
+    /** CAS方式更新订单状态（通用），用于退款申请等场景防止并发竞态 */
+    @Update("UPDATE orders SET status = #{newStatus}, updated_at = NOW() WHERE id = #{orderId} AND status = #{expectedStatus} AND deleted = 0")
+    int casStatus(@Param("orderId") Long orderId, @Param("expectedStatus") String expectedStatus, @Param("newStatus") String newStatus);
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/order/service/impl/OrderServiceImpl.java

@@ -22,6 +22,8 @@ import com.openclaw.common.compensation.CompensationService;
 import com.openclaw.module.coupon.service.CouponService;
 import com.openclaw.module.coupon.vo.CouponCalcResultVO;
 import com.openclaw.module.notification.service.NotificationService;
+import com.openclaw.module.promotion.service.PromotionService;
+import com.openclaw.module.promotion.vo.SkillPromotionVO;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.amqp.rabbit.core.RabbitTemplate;
@@ -55,6 +57,7 @@ public class OrderServiceImpl implements OrderService {
     private final CompensationService compensationService;
     private final CouponService couponService;
     private final NotificationService notificationService;
+    private final PromotionService promotionService;
 
     @Override
     public OrderPreviewVO previewOrder(Long userId, List<Long> skillIds, Integer pointsToUse) {
@@ -67,14 +70,33 @@ public class OrderServiceImpl implements OrderService {
         List<Skill> skills = skillRepo.selectBatchIds(skillIds);
         if (skills.isEmpty()) throw new BusinessException(ErrorCode.SKILL_NOT_FOUND);
 
-        BigDecimal totalAmount = skills.stream()
+        // 1b. 批量查询促销信息
+        List<SkillPromotionVO> promotions = promotionService.batchGetSkillPromotions(skillIds);
+        Map<Long, SkillPromotionVO> promoMap = promotions.stream()
+            .filter(p -> p.getSkillId() != null)
+            .collect(Collectors.toMap(SkillPromotionVO::getSkillId, p -> p, (a, b) -> a));
+
+        // 1c. 计算原价总额和促销后总额
+        BigDecimal originalAmount = skills.stream()
             .map(Skill::getPrice)
             .reduce(BigDecimal.ZERO, BigDecimal::add);
 
+        BigDecimal totalAmount = BigDecimal.ZERO;
+        for (Skill s : skills) {
+            SkillPromotionVO promo = promoMap.get(s.getId());
+            if (promo != null) {
+                BigDecimal promoPrice = promotionService.calculatePromotionPrice(s.getId(), s.getPrice());
+                totalAmount = totalAmount.add(promoPrice);
+            } else {
+                totalAmount = totalAmount.add(s.getPrice());
+            }
+        }
+        BigDecimal promotionDeductAmount = originalAmount.subtract(totalAmount).max(BigDecimal.ZERO);
+
         // 2. 查询用户积分余额
         int availablePoints = pointsService.getBalance(userId).getAvailablePoints();
 
-        // 3. 计算最大可用积分
+        // 3. 计算最大可用积分（基于促销后总额）
         int maxPoints = totalAmount.multiply(BigDecimal.valueOf(POINTS_RATE)).intValue();
         maxPoints = Math.min(maxPoints, availablePoints);
 
@@ -108,11 +130,22 @@ public class OrderServiceImpl implements OrderService {
             item.setSkillId(s.getId());
             item.setSkillName(s.getName());
             item.setSkillCover(s.getCoverImageUrl());
+            SkillPromotionVO promo = promoMap.get(s.getId());
+            if (promo != null) {
+                BigDecimal promoPrice = promotionService.calculatePromotionPrice(s.getId(), s.getPrice());
+                item.setOriginalPrice(s.getPrice());
+                item.setUnitPrice(promoPrice);
+                item.setTotalPrice(promoPrice);
+                item.setPromotionTag(promo.getTagText());
+            } else {
                 item.setUnitPrice(s.getPrice());
-            item.setQuantity(1);
                 item.setTotalPrice(s.getPrice());
+            }
+            item.setQuantity(1);
             return item;
         }).collect(Collectors.toList()));
+        vo.setOriginalAmount(originalAmount);
+        vo.setPromotionDeductAmount(promotionDeductAmount);
         vo.setTotalAmount(totalAmount);
         vo.setPointsToUse(pointsToUse);
         vo.setPointsDeductAmount(deduct);
@@ -140,11 +173,38 @@ public class OrderServiceImpl implements OrderService {
             }
         }
 
-        // 2. 计算总金额
+        // 1b. 批量查询促销信息 & 校验用户限购
-        BigDecimal totalAmount = skills.stream()
+        List<Long> skillIds = skills.stream().map(Skill::getId).collect(Collectors.toList());
+        List<SkillPromotionVO> promotions = promotionService.batchGetSkillPromotions(skillIds);
+        Map<Long, SkillPromotionVO> promoMap = promotions.stream()
+            .filter(p -> p.getSkillId() != null)
+            .collect(Collectors.toMap(SkillPromotionVO::getSkillId, p -> p, (a, b) -> a));
+
+        java.util.Iterator<Map.Entry<Long, SkillPromotionVO>> it = promoMap.entrySet().iterator();
+        while (it.hasNext()) {
+            SkillPromotionVO promo = it.next().getValue();
+            if (!promotionService.checkUserLimit(promo.getPromotionId(), userId)) {
+                log.warn("用户超出促销限购: userId={}, promotionId={}", userId, promo.getPromotionId());
+                it.remove();
+            }
+        }
+
+        // 2. 计算原价总额和促销后总额
+        BigDecimal originalAmount = skills.stream()
             .map(Skill::getPrice)
             .reduce(BigDecimal.ZERO, BigDecimal::add);
 
+        BigDecimal totalAmount = BigDecimal.ZERO;
+        for (Skill s : skills) {
+            SkillPromotionVO promo = promoMap.get(s.getId());
+            if (promo != null) {
+                totalAmount = totalAmount.add(promotionService.calculatePromotionPrice(s.getId(), s.getPrice()));
+            } else {
+                totalAmount = totalAmount.add(s.getPrice());
+            }
+        }
+        BigDecimal promotionDeductAmount = originalAmount.subtract(totalAmount).max(BigDecimal.ZERO);
+
         // 3. 处理积分抵扣（校正上限，防止超额消耗）
         int pointsToUse = dto.getPointsToUse() != null ? dto.getPointsToUse() : 0;
         if (pointsToUse > 0) {
@@ -187,7 +247,9 @@ public class OrderServiceImpl implements OrderService {
         Order order = new Order();
         order.setOrderNo(idGenerator.generateOrderNo());
         order.setUserId(userId);
+        order.setOriginalAmount(originalAmount);
         order.setTotalAmount(totalAmount);
+        order.setPromotionDeductAmount(promotionDeductAmount);
         order.setCashAmount(cashAmount);
         order.setPointsUsed(pointsToUse);
         order.setPointsDeductAmount(pointsDeductAmount);
@@ -198,16 +260,25 @@ public class OrderServiceImpl implements OrderService {
         order.setExpiredAt(LocalDateTime.now().plusHours(1));
         orderRepo.insert(order);
 
-        // 6. 创建订单项
+        // 6. 创建订单项（含促销快照）
         for (Skill skill : skills) {
             OrderItem item = new OrderItem();
             item.setOrderId(order.getId());
             item.setSkillId(skill.getId());
             item.setSkillName(skill.getName());
             item.setSkillCover(skill.getCoverImageUrl());
+            item.setOriginalPrice(skill.getPrice());
+            SkillPromotionVO promo = promoMap.get(skill.getId());
+            if (promo != null) {
+                BigDecimal promoPrice = promotionService.calculatePromotionPrice(skill.getId(), skill.getPrice());
+                item.setUnitPrice(promoPrice);
+                item.setTotalPrice(promoPrice);
+                item.setPromotionId(promo.getPromotionId());
+            } else {
                 item.setUnitPrice(skill.getPrice());
-            item.setQuantity(1);
                 item.setTotalPrice(skill.getPrice());
+            }
+            item.setQuantity(1);
             orderItemRepo.insert(item);
         }
 
@@ -221,6 +292,16 @@ public class OrderServiceImpl implements OrderService {
             couponService.useCoupon(userId, couponId, order.getId());
         }
 
+        // 7c. 记录促销使用
+        for (Skill skill : skills) {
+            SkillPromotionVO promo = promoMap.get(skill.getId());
+            if (promo != null) {
+                BigDecimal promoPrice = promotionService.calculatePromotionPrice(skill.getId(), skill.getPrice());
+                BigDecimal discount = skill.getPrice().subtract(promoPrice).max(BigDecimal.ZERO);
+                promotionService.recordPromotionUsage(promo.getPromotionId(), userId, order.getId(), skill.getId(), discount);
+            }
+        }
+
         // 8. 免现金支付（纯积分 或 优惠券全额抵扣）：直接完成订单
         if (cashAmount.compareTo(BigDecimal.ZERO) == 0) {
             if (pointsToUse > 0) {
@@ -229,13 +310,21 @@ public class OrderServiceImpl implements OrderService {
             order.setStatus("completed");
             order.setPaidAt(LocalDateTime.now());
             orderRepo.updateById(order);
-            // 发放 Skill 访问权限
+            // 发放 Skill 访问权限（download_type ENUM: free/paid/points）
-            String grantSource = pointsToUse > 0 ? "points" : "coupon";
+            String grantSource;
+            if (totalAmount.compareTo(BigDecimal.ZERO) == 0) {
+                grantSource = "free";
+            } else if (pointsToUse > 0) {
+                grantSource = "points";
+            } else {
+                grantSource = "paid";
+            }
             for (Skill skill : skills) {
                 skillService.grantAccess(userId, skill.getId(), order.getId(), grantSource);
             }
-            log.info("免现金订单直接完成: orderId={}, points={}, couponId={}", order.getId(), pointsToUse, couponId);
+            log.info("免现金订单直接完成: orderId={}, points={}, couponId={}, promoDeduct={}",
-            return toVO(order, skills);
+                order.getId(), pointsToUse, couponId, promotionDeductAmount);
+            return toVO(order, skills, promoMap);
         }
 
         // 9. 非纯积分：事务提交后发送订单超时延迟消息（1小时后自动取消）
@@ -256,7 +345,7 @@ public class OrderServiceImpl implements OrderService {
             }
         });
 
-        return toVO(order, skills);
+        return toVO(order, skills, promoMap);
     }
 
     @Override
@@ -303,6 +392,11 @@ public class OrderServiceImpl implements OrderService {
         if (order == null || !order.getUserId().equals(userId)) {
             throw new BusinessException(ErrorCode.ORDER_NOT_FOUND);
         }
+        // 幂等处理：已支付/已完成的订单直接返回成功（免费订单创建时已自动完成）
+        if ("paid".equals(order.getStatus()) || "completed".equals(order.getStatus())) {
+            log.info("订单已完成，跳过重复支付: orderId={}, status={}", orderId, order.getStatus());
+            return;
+        }
         if (!"pending".equals(order.getStatus())) {
             throw new BusinessException(ErrorCode.ORDER_STATUS_ERROR);
         }
@@ -352,9 +446,11 @@ public class OrderServiceImpl implements OrderService {
         if (!"pending".equals(order.getStatus())) {
             throw new BusinessException(ErrorCode.ORDER_STATUS_ERROR);
         }
-        order.setStatus("cancelled");
+        // CAS更新：防止并发重复取消（用户手动取消 + 超时自动取消 竞态）
-        order.setCancelReason(reason);
+        int rows = orderRepo.casCancel(orderId, "pending", "cancelled", reason);
-        orderRepo.updateById(order);
+        if (rows == 0) {
+            throw new BusinessException(ErrorCode.ORDER_STATUS_ERROR);
+        }
 
         // 解冻积分
         if (order.getPointsUsed() != null && order.getPointsUsed() > 0) {
@@ -391,16 +487,15 @@ public class OrderServiceImpl implements OrderService {
         if (order == null || !order.getUserId().equals(userId)) {
             throw new BusinessException(ErrorCode.ORDER_NOT_FOUND);
         }
-        if (!"paid".equals(order.getStatus()) && !"completed".equals(order.getStatus())) {
+        String currentStatus = order.getStatus();
+        if (!"paid".equals(currentStatus) && !"completed".equals(currentStatus)) {
             throw new BusinessException(ErrorCode.ORDER_STATUS_ERROR);
         }
-        Long refundCount = refundRepo.selectCount(
+
-            new LambdaQueryWrapper<OrderRefund>()
+        // CAS原子更新订单状态为refunding，防止并发重复申请退款
-                .eq(OrderRefund::getOrderId, orderId)
+        int rows = orderRepo.casStatus(orderId, currentStatus, "refunding");
-                .in(OrderRefund::getStatus, "pending", "approved", "completed")
+        if (rows == 0) {
-        );
+            throw new BusinessException(409, "订单状态已变更或已有退款申请，请勿重复提交");
-        if (refundCount != null && refundCount > 0) {
-            throw new BusinessException(409, "该订单已有退款申请，请勿重复提交");
         }
 
         OrderRefund refund = new OrderRefund();
@@ -417,17 +512,16 @@ public class OrderServiceImpl implements OrderService {
             }
         }
         refund.setStatus("pending");
-        refund.setPreviousOrderStatus(order.getStatus());
+        refund.setPreviousOrderStatus(currentStatus);
         refundRepo.insert(refund);
-
-        order.setStatus("refunding");
-        orderRepo.updateById(order);
     }
 
-    private OrderVO toVO(Order order, List<Skill> skills) {
+    private OrderVO toVO(Order order, List<Skill> skills, Map<Long, SkillPromotionVO> promoMap) {
         OrderVO vo = new OrderVO();
         vo.setId(order.getId());
         vo.setOrderNo(order.getOrderNo());
+        vo.setOriginalAmount(order.getOriginalAmount());
+        vo.setPromotionDeductAmount(order.getPromotionDeductAmount());
         vo.setTotalAmount(order.getTotalAmount());
         vo.setCashAmount(order.getCashAmount());
         vo.setPointsUsed(order.getPointsUsed());
@@ -444,9 +538,18 @@ public class OrderServiceImpl implements OrderService {
             item.setSkillId(s.getId());
             item.setSkillName(s.getName());
             item.setSkillCover(s.getCoverImageUrl());
+            SkillPromotionVO promo = promoMap != null ? promoMap.get(s.getId()) : null;
+            if (promo != null) {
+                BigDecimal promoPrice = promotionService.calculatePromotionPrice(s.getId(), s.getPrice());
+                item.setOriginalPrice(s.getPrice());
+                item.setUnitPrice(promoPrice);
+                item.setTotalPrice(promoPrice);
+                item.setPromotionTag(promo.getTagText());
+            } else {
                 item.setUnitPrice(s.getPrice());
-            item.setQuantity(1);
                 item.setTotalPrice(s.getPrice());
+            }
+            item.setQuantity(1);
             return item;
         }).collect(Collectors.toList()));
         return vo;
@@ -457,6 +560,8 @@ public class OrderServiceImpl implements OrderService {
         OrderVO vo = new OrderVO();
         vo.setId(order.getId());
         vo.setOrderNo(order.getOrderNo());
+        vo.setOriginalAmount(order.getOriginalAmount());
+        vo.setPromotionDeductAmount(order.getPromotionDeductAmount());
         vo.setTotalAmount(order.getTotalAmount());
         vo.setCashAmount(order.getCashAmount());
         vo.setPointsUsed(order.getPointsUsed());
@@ -473,9 +578,11 @@ public class OrderServiceImpl implements OrderService {
             item.setSkillId(oi.getSkillId());
             item.setSkillName(oi.getSkillName());
             item.setSkillCover(oi.getSkillCover());
+            item.setOriginalPrice(oi.getOriginalPrice());
             item.setUnitPrice(oi.getUnitPrice());
             item.setQuantity(oi.getQuantity());
             item.setTotalPrice(oi.getTotalPrice());
+            item.setPromotionId(oi.getPromotionId());
             return item;
         }).collect(Collectors.toList()));
         return vo;

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/order/vo/OrderItemVO.java

@@ -8,7 +8,10 @@ public class OrderItemVO {
     private Long skillId;
     private String skillName;
     private String skillCover;
-    private BigDecimal unitPrice;
+    private BigDecimal originalPrice;   // 原价（促销前，NULL=无促销）
+    private BigDecimal unitPrice;       // 实际单价
     private Integer quantity;
     private BigDecimal totalPrice;
+    private String promotionTag;        // 促销标签（如"限时8折"）
+    private Long promotionId;           // 促销活动ID
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/order/vo/OrderPreviewVO.java

@@ -7,7 +7,9 @@ import java.util.List;
 @Data
 public class OrderPreviewVO {
     private List<OrderItemVO> items;
-    private BigDecimal totalAmount;
+    private BigDecimal originalAmount;        // 原价总额（促销前）
+    private BigDecimal promotionDeductAmount; // 促销优惠金额
+    private BigDecimal totalAmount;           // 促销后总额
     private Integer pointsToUse;
     private BigDecimal pointsDeductAmount;
     private Long couponId;

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/order/vo/OrderVO.java

@@ -9,6 +9,8 @@ import java.util.List;
 public class OrderVO {
     private Long id;
     private String orderNo;
+    private BigDecimal originalAmount;
+    private BigDecimal promotionDeductAmount;
     private BigDecimal totalAmount;
     private BigDecimal cashAmount;
     private Integer pointsUsed;

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/payment/controller/MockPaymentController.java

@@ -6,6 +6,7 @@ import com.openclaw.module.payment.service.PaymentService;
 import com.openclaw.module.order.service.OrderService;
 import com.openclaw.util.UserContext;
 import com.openclaw.annotation.RequiresRole;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.Data;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -18,6 +19,7 @@ import java.util.Map;
  * 仅在微信支付未启用时(wechat.pay.enabled=false)生效
  * 用于开发/测试环境模拟完整支付流程
  */
+@Tag(name = "模拟支付", description = "开发/测试环境模拟支付网关")
 @Slf4j
 @RestController
 @RequestMapping("/api/v1/mock-pay")

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/payment/controller/PaymentController.java

@@ -7,6 +7,8 @@ import com.openclaw.module.payment.service.PaymentService;
 import com.openclaw.annotation.RequiresRole;
 import com.openclaw.util.UserContext;
 import com.openclaw.module.payment.vo.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -16,6 +18,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.HashMap;
 import java.util.Map;
 
+@Tag(name = "支付与充值", description = "积分充值、支付记录、微信回调")
 @Slf4j
 @RestController
 @RequestMapping("/api/v1/payments")
@@ -24,14 +27,14 @@ public class PaymentController {
 
     private final PaymentService paymentService;
 
-    /** 发起充值 */
+    @Operation(summary = "发起充值", description = "创建积分充值订单")
     @RequiresRole("user")
     @PostMapping("/recharge")
     public Result<RechargeVO> createRecharge(@Valid @RequestBody RechargeDTO dto) {
         return Result.ok(paymentService.createRecharge(UserContext.getUserId(), dto));
     }
 
-    /** 获取支付记录 */
+    @Operation(summary = "支付记录列表", description = "分页查询")
     @RequiresRole("user")
     @GetMapping("/records")
     public Result<IPage<PaymentRecordVO>> listRecords(
@@ -40,13 +43,14 @@ public class PaymentController {
         return Result.ok(paymentService.listPaymentRecords(UserContext.getUserId(), pageNum, pageSize));
     }
 
-    /** 查询充值订单状态 */
+    @Operation(summary = "查询充值状态")
     @RequiresRole("user")
     @GetMapping("/recharge/{id}")
     public Result<RechargeVO> getRechargeStatus(@PathVariable Long id) {
         return Result.ok(paymentService.getRechargeStatus(UserContext.getUserId(), id));
     }
 
+    @Operation(summary = "微信支付回调", description = "微信V3回调通知，无需登录")
     /**
      * 微信支付V3回调（无需登录）
      * 微信V3使用JSON格式 + HTTP请求头传递签名信息

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/points/controller/PointsController.java

@@ -5,9 +5,11 @@ import com.openclaw.common.Result;
 import com.openclaw.module.points.service.PointsService;
 import com.openclaw.util.UserContext;
 import com.openclaw.module.points.vo.*;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "积分管理", description = "积分余额、积分流水")
 @RestController
 @RequestMapping("/api/v1/points")
 @RequiredArgsConstructor
@@ -26,6 +28,7 @@ public class PointsController {
     public Result<IPage<PointsRecordVO>> getRecords(
             @RequestParam(defaultValue = "1") int pageNum,
             @RequestParam(defaultValue = "20") int pageSize) {
+        pageSize = Math.min(Math.max(pageSize, 1), 50);
         return Result.ok(pointsService.getRecords(UserContext.getUserId(), pageNum, pageSize));
     }
 

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/points/service/impl/PointsServiceImpl.java

@@ -41,6 +41,10 @@ public class PointsServiceImpl implements PointsService {
     @Override
     @Transactional
     public void initUserPoints(Long userId) {
+        // 幂等：已存在则跳过，防止MQ重试导致唯一约束冲突
+        if (userPointsRepo.findByUserId(userId) != null) {
+            return;
+        }
         UserPoints up = new UserPoints();
         up.setUserId(userId);
         up.setAvailablePoints(0);
@@ -132,12 +136,31 @@ public class PointsServiceImpl implements PointsService {
         return points;
     }
 
+    /** 一次性来源：每个用户只能领取一次积分，防止重复刷取 */
+    private static final java.util.Set<String> ONE_TIME_SOURCES = java.util.Set.of(
+        "register", "join_community", "invited"
+    );
+
     @Override
     @Transactional
     public void earnPoints(Long userId, String source, Long relatedId, String relatedType) {
         PointsRule rule = ruleRepo.findBySource(source);
         if (rule == null || !rule.getEnabled()) return;
 
+        // 幂等：一次性来源检查是否已领取过，防止重复刷积分
+        if (ONE_TIME_SOURCES.contains(source)) {
+            Long existCount = recordRepo.selectCount(
+                new LambdaQueryWrapper<PointsRecord>()
+                    .eq(PointsRecord::getUserId, userId)
+                    .eq(PointsRecord::getSource, source)
+                    .eq(PointsRecord::getPointsType, "earn")
+            );
+            if (existCount != null && existCount > 0) {
+                log.info("一次性积分已领取，跳过: userId={}, source={}", userId, source);
+                return;
+            }
+        }
+
         UserPoints up = userPointsRepo.findByUserId(userId);
         if (up == null) {
             initUserPoints(userId);

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/promotion/controller/PromotionController.java

@@ -7,12 +7,14 @@ import com.openclaw.module.promotion.dto.PromotionCreateDTO;
 import com.openclaw.module.promotion.dto.PromotionUpdateDTO;
 import com.openclaw.module.promotion.service.PromotionService;
 import com.openclaw.module.promotion.vo.*;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
+@Tag(name = "促销活动", description = "促销活动管理与用户端查询")
 @RestController
 @RequestMapping("/api/v1/promotions")
 @RequiredArgsConstructor

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/promotion/dto/PromotionCreateDTO.java

@@ -20,8 +20,7 @@ public class PromotionCreateDTO {
     @NotNull
     private LocalDateTime endTime;
 
-    @NotBlank
+    private PromotionRules rules;
-    private String rules;           // JSON
 
     private String scopeType;       // all / category / skill
     private String scopeValues;     // JSON

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/promotion/dto/PromotionRules.java

@@ -0,0 +1,17 @@
+package com.openclaw.module.promotion.dto;
+
+import lombok.Data;
+
+import java.math.BigDecimal;
+
+@Data
+public class PromotionRules {
+    /** 固定促销价 */
+    private BigDecimal promotionPrice;
+    /** 折扣率 (0.8 = 八折, 0.5 = 五折) */
+    private BigDecimal discountRate;
+    /** 直减金额 */
+    private BigDecimal discountAmount;
+    /** 最低消费金额（满减门槛，可选） */
+    private BigDecimal minOrderAmount;
+}

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/promotion/dto/PromotionUpdateDTO.java

@@ -11,7 +11,7 @@ public class PromotionUpdateDTO {
     private String type;
     private LocalDateTime startTime;
     private LocalDateTime endTime;
-    private String rules;
+    private PromotionRules rules;
     private String scopeType;
     private String scopeValues;
     private String exclusiveGroup;

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/promotion/repository/PromotionRepository.java

@@ -16,4 +16,8 @@ public interface PromotionRepository extends BaseMapper<Promotion> {
     @Update("UPDATE promotion SET sold_count = GREATEST(sold_count - 1, 0) " +
             "WHERE id = #{id}")
     int decrementSoldCount(@Param("id") Long id);
+
+    @Update("UPDATE promotion SET status = 'ended', updated_at = NOW() " +
+            "WHERE status = 'active' AND end_time < NOW()")
+    int batchExpirePromotions();
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/promotion/service/PromotionService.java

@@ -51,4 +51,7 @@ public interface PromotionService {
 
     /** 检查用户是否超出活动限购 */
     boolean checkUserLimit(Long promotionId, Long userId);
+
+    /** 批量过期已结束的促销活动，返回影响行数 */
+    int batchExpirePromotions();
 }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/promotion/service/impl/PromotionServiceImpl.java

@@ -23,6 +23,9 @@ import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.openclaw.module.promotion.dto.PromotionRules;
+
 import java.math.BigDecimal;
 import java.math.RoundingMode;
 import java.time.LocalDateTime;
@@ -37,6 +40,8 @@ import java.util.stream.Collectors;
 @RequiredArgsConstructor
 public class PromotionServiceImpl implements PromotionService {
 
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
     private final PromotionRepository promotionRepository;
     private final PromotionSkillRepository promotionSkillRepository;
     private final PromotionRecordRepository promotionRecordRepository;
@@ -51,7 +56,7 @@ public class PromotionServiceImpl implements PromotionService {
         promotion.setStatus("draft");
         promotion.setStartTime(dto.getStartTime());
         promotion.setEndTime(dto.getEndTime());
-        promotion.setRules(dto.getRules());
+        promotion.setRules(serializeRules(dto.getRules()));
         promotion.setScopeType(dto.getScopeType() != null ? dto.getScopeType() : "all");
         promotion.setScopeValues(dto.getScopeValues());
         promotion.setExclusiveGroup(dto.getExclusiveGroup());
@@ -95,7 +100,7 @@ public class PromotionServiceImpl implements PromotionService {
         if (dto.getType() != null) promotion.setType(dto.getType());
         if (dto.getStartTime() != null) promotion.setStartTime(dto.getStartTime());
         if (dto.getEndTime() != null) promotion.setEndTime(dto.getEndTime());
-        if (dto.getRules() != null) promotion.setRules(dto.getRules());
+        if (dto.getRules() != null) promotion.setRules(serializeRules(dto.getRules()));
         if (dto.getScopeType() != null) promotion.setScopeType(dto.getScopeType());
         if (dto.getScopeValues() != null) promotion.setScopeValues(dto.getScopeValues());
         if (dto.getExclusiveGroup() != null) promotion.setExclusiveGroup(dto.getExclusiveGroup());
@@ -251,7 +256,7 @@ public class PromotionServiceImpl implements PromotionService {
         vo.setStatus(promotion.getStatus());
         vo.setStartTime(promotion.getStartTime());
         vo.setEndTime(promotion.getEndTime());
-        vo.setRules(promotion.getRules());
+        vo.setRules(parseRules(promotion.getRules()));
         vo.setScopeType(promotion.getScopeType());
         vo.setScopeValues(promotion.getScopeValues());
         vo.setExclusiveGroup(promotion.getExclusiveGroup());
@@ -312,48 +317,112 @@ public class PromotionServiceImpl implements PromotionService {
     @Override
     public SkillPromotionVO getSkillPromotion(Long skillId) {
         LocalDateTime now = LocalDateTime.now();
+        Skill skill = skillRepository.selectById(skillId);
+        if (skill == null) return null;
 
+        Promotion bestPromotion = null;
+        PromotionSkill bestPromotionSkill = null;
+        int bestPriority = Integer.MIN_VALUE;
+
+        // 1. 直接指定skill的促销 (via promotion_skills table)
         List<PromotionSkill> promotionSkills = promotionSkillRepository.selectList(
                 new LambdaQueryWrapper<PromotionSkill>().eq(PromotionSkill::getSkillId, skillId));
-
+        if (!promotionSkills.isEmpty()) {
-        if (promotionSkills.isEmpty()) return null;
-
             List<Long> promotionIds = promotionSkills.stream()
                     .map(PromotionSkill::getPromotionId).collect(Collectors.toList());
-
+            List<Promotion> directPromotions = promotionRepository.selectList(
-        List<Promotion> activePromotions = promotionRepository.selectList(
                     new LambdaQueryWrapper<Promotion>()
                             .in(Promotion::getId, promotionIds)
                             .eq(Promotion::getStatus, "active")
                             .le(Promotion::getStartTime, now)
                             .ge(Promotion::getEndTime, now)
                             .orderByDesc(Promotion::getPriority));
-
+            if (!directPromotions.isEmpty()) {
-        if (activePromotions.isEmpty()) return null;
+                Promotion dp = directPromotions.get(0);
-
+                int dpPriority = dp.getPriority() != null ? dp.getPriority() : 0;
-        Promotion bestPromotion = activePromotions.get(0);
+                bestPromotion = dp;
-        PromotionSkill matchedSkill = promotionSkills.stream()
+                bestPriority = dpPriority;
-                .filter(ps -> ps.getPromotionId().equals(bestPromotion.getId()))
+                final Long dpId = dp.getId();
+                bestPromotionSkill = promotionSkills.stream()
+                        .filter(ps -> ps.getPromotionId().equals(dpId))
                         .findFirst().orElse(null);
+            }
+        }
 
-        if (matchedSkill == null) return null;
+        // 2. scopeType=all 全场促销
+        List<Promotion> allPromotions = promotionRepository.selectList(
+                new LambdaQueryWrapper<Promotion>()
+                        .eq(Promotion::getScopeType, "all")
+                        .eq(Promotion::getStatus, "active")
+                        .le(Promotion::getStartTime, now)
+                        .ge(Promotion::getEndTime, now)
+                        .orderByDesc(Promotion::getPriority));
+        if (!allPromotions.isEmpty()) {
+            Promotion ap = allPromotions.get(0);
+            int apPriority = ap.getPriority() != null ? ap.getPriority() : 0;
+            if (apPriority > bestPriority) {
+                bestPromotion = ap;
+                bestPromotionSkill = null;
+                bestPriority = apPriority;
+            }
+        }
 
-        Skill skill = skillRepository.selectById(skillId);
+        // 3. scopeType=category 分类促销
+        if (skill.getCategoryId() != null) {
+            List<Promotion> catPromotions = promotionRepository.selectList(
+                    new LambdaQueryWrapper<Promotion>()
+                            .eq(Promotion::getScopeType, "category")
+                            .eq(Promotion::getStatus, "active")
+                            .le(Promotion::getStartTime, now)
+                            .ge(Promotion::getEndTime, now)
+                            .orderByDesc(Promotion::getPriority));
+            for (Promotion cp : catPromotions) {
+                int cpPriority = cp.getPriority() != null ? cp.getPriority() : 0;
+                if (cpPriority <= bestPriority) break;
+                if (matchesCategory(cp.getScopeValues(), skill.getCategoryId())) {
+                    bestPromotion = cp;
+                    bestPromotionSkill = null;
+                    bestPriority = cpPriority;
+                    break;
+                }
+            }
+        }
 
+        if (bestPromotion == null) return null;
+
+        // 检查 all/category 促销是否有针对此skill的PromotionSkill覆盖
+        if (bestPromotionSkill == null && !promotionSkills.isEmpty()) {
+            final Long bpId = bestPromotion.getId();
+            bestPromotionSkill = promotionSkills.stream()
+                    .filter(ps -> ps.getPromotionId().equals(bpId))
+                    .findFirst().orElse(null);
+        }
+
+        // 构建VO
         SkillPromotionVO vo = new SkillPromotionVO();
+        vo.setSkillId(skillId);
         vo.setPromotionId(bestPromotion.getId());
         vo.setPromotionName(bestPromotion.getName());
         vo.setPromotionType(bestPromotion.getType());
-        vo.setPromotionPrice(matchedSkill.getPromotionPrice());
-        vo.setDiscountRate(matchedSkill.getDiscountRate());
         vo.setTagText(bestPromotion.getTagText());
         vo.setEndTime(bestPromotion.getEndTime());
-        vo.setStockLimit(matchedSkill.getStockLimit());
-        vo.setSoldCount(matchedSkill.getSoldCount());
 
-        if (skill != null && skill.getPrice() != null) {
         BigDecimal originalPrice = skill.getPrice();
-            BigDecimal finalPrice = calculateFinalPrice(matchedSkill, originalPrice);
+        BigDecimal finalPrice = originalPrice;
+
+        if (bestPromotionSkill != null) {
+            vo.setPromotionPrice(bestPromotionSkill.getPromotionPrice());
+            vo.setDiscountRate(bestPromotionSkill.getDiscountRate());
+            vo.setStockLimit(bestPromotionSkill.getStockLimit());
+            vo.setSoldCount(bestPromotionSkill.getSoldCount());
+            if (originalPrice != null) {
+                finalPrice = calculateFinalPrice(bestPromotionSkill, originalPrice);
+            }
+        } else if (originalPrice != null) {
+            finalPrice = calculatePriceFromRules(bestPromotion.getRules(), originalPrice);
+        }
+
+        if (originalPrice != null && finalPrice != null) {
             vo.setDiscountAmount(originalPrice.subtract(finalPrice));
         }
 
@@ -363,11 +432,135 @@ public class PromotionServiceImpl implements PromotionService {
     @Override
     public List<SkillPromotionVO> batchGetSkillPromotions(List<Long> skillIds) {
         if (skillIds == null || skillIds.isEmpty()) return Collections.emptyList();
+        LocalDateTime now = LocalDateTime.now();
 
+        // 1. 批量加载Skill
+        List<Skill> skills = skillRepository.selectBatchIds(skillIds);
+        Map<Long, Skill> skillMap = skills.stream().collect(Collectors.toMap(Skill::getId, s -> s));
+
+        // 2. 批量加载所有相关的PromotionSkill
+        List<PromotionSkill> allPromotionSkills = promotionSkillRepository.selectList(
+                new LambdaQueryWrapper<PromotionSkill>().in(PromotionSkill::getSkillId, skillIds));
+        Map<Long, List<PromotionSkill>> psMap = allPromotionSkills.stream()
+                .collect(Collectors.groupingBy(PromotionSkill::getSkillId));
+
+        // 3. 收集所有关联的promotionId，一次性加载活跃促销
+        List<Long> directPromotionIds = allPromotionSkills.stream()
+                .map(PromotionSkill::getPromotionId).distinct().collect(Collectors.toList());
+
+        // 查询所有活跃促销（含direct/all/category三种scopeType）
+        LambdaQueryWrapper<Promotion> activeWrapper = new LambdaQueryWrapper<Promotion>()
+                .eq(Promotion::getStatus, "active")
+                .le(Promotion::getStartTime, now)
+                .ge(Promotion::getEndTime, now);
+        if (!directPromotionIds.isEmpty()) {
+            activeWrapper.and(w -> w
+                    .in(Promotion::getId, directPromotionIds)
+                    .or().eq(Promotion::getScopeType, "all")
+                    .or().eq(Promotion::getScopeType, "category"));
+        } else {
+            activeWrapper.and(w -> w
+                    .eq(Promotion::getScopeType, "all")
+                    .or().eq(Promotion::getScopeType, "category"));
+        }
+        activeWrapper.orderByDesc(Promotion::getPriority);
+        List<Promotion> activePromotions = promotionRepository.selectList(activeWrapper);
+
+        // 按ID索引 & 按scopeType分组
+        Map<Long, Promotion> promotionMap = activePromotions.stream()
+                .collect(Collectors.toMap(Promotion::getId, p -> p, (a, b) -> a));
+        List<Promotion> allScopePromotions = activePromotions.stream()
+                .filter(p -> "all".equals(p.getScopeType())).collect(Collectors.toList());
+        List<Promotion> catScopePromotions = activePromotions.stream()
+                .filter(p -> "category".equals(p.getScopeType())).collect(Collectors.toList());
+
+        // 4. 为每个skillId匹配最优促销
         List<SkillPromotionVO> result = new ArrayList<>();
         for (Long skillId : skillIds) {
-            SkillPromotionVO vo = getSkillPromotion(skillId);
+            Skill skill = skillMap.get(skillId);
-            if (vo != null) result.add(vo);
+            if (skill == null) continue;
+
+            Promotion bestPromotion = null;
+            PromotionSkill bestPs = null;
+            int bestPriority = Integer.MIN_VALUE;
+
+            // 4a. direct skill promotions
+            List<PromotionSkill> directPs = psMap.getOrDefault(skillId, Collections.emptyList());
+            for (PromotionSkill ps : directPs) {
+                Promotion p = promotionMap.get(ps.getPromotionId());
+                if (p == null) continue;
+                int pri = p.getPriority() != null ? p.getPriority() : 0;
+                if (pri > bestPriority) {
+                    bestPromotion = p;
+                    bestPs = ps;
+                    bestPriority = pri;
+                }
+            }
+
+            // 4b. all scope
+            if (!allScopePromotions.isEmpty()) {
+                Promotion ap = allScopePromotions.get(0); // already sorted by priority desc
+                int apPri = ap.getPriority() != null ? ap.getPriority() : 0;
+                if (apPri > bestPriority) {
+                    bestPromotion = ap;
+                    bestPs = null;
+                    bestPriority = apPri;
+                }
+            }
+
+            // 4c. category scope
+            if (skill.getCategoryId() != null) {
+                for (Promotion cp : catScopePromotions) {
+                    int cpPri = cp.getPriority() != null ? cp.getPriority() : 0;
+                    if (cpPri <= bestPriority) break;
+                    if (matchesCategory(cp.getScopeValues(), skill.getCategoryId())) {
+                        bestPromotion = cp;
+                        bestPs = null;
+                        bestPriority = cpPri;
+                        break;
+                    }
+                }
+            }
+
+            if (bestPromotion == null) continue;
+
+            // 检查PromotionSkill覆盖
+            if (bestPs == null && !directPs.isEmpty()) {
+                final Long bpId = bestPromotion.getId();
+                bestPs = directPs.stream()
+                        .filter(ps -> ps.getPromotionId().equals(bpId))
+                        .findFirst().orElse(null);
+            }
+
+            // 构建VO
+            SkillPromotionVO vo = new SkillPromotionVO();
+            vo.setSkillId(skillId);
+            vo.setPromotionId(bestPromotion.getId());
+            vo.setPromotionName(bestPromotion.getName());
+            vo.setPromotionType(bestPromotion.getType());
+            vo.setTagText(bestPromotion.getTagText());
+            vo.setEndTime(bestPromotion.getEndTime());
+
+            BigDecimal originalPrice = skill.getPrice();
+            BigDecimal finalPrice = originalPrice;
+
+            if (bestPs != null) {
+                vo.setPromotionPrice(bestPs.getPromotionPrice());
+                vo.setDiscountRate(bestPs.getDiscountRate());
+                vo.setStockLimit(bestPs.getStockLimit());
+                vo.setSoldCount(bestPs.getSoldCount());
+                if (originalPrice != null) {
+                    finalPrice = calculateFinalPrice(bestPs, originalPrice);
+                }
+            } else if (originalPrice != null) {
+                finalPrice = calculatePriceFromRules(bestPromotion.getRules(), originalPrice);
+            }
+
+            if (originalPrice != null && finalPrice != null) {
+                vo.setDiscountAmount(originalPrice.subtract(finalPrice));
+            }
+
+            result.add(vo);
         }
         return result;
     }
@@ -424,6 +617,75 @@ public class PromotionServiceImpl implements PromotionService {
         return usedCount < promotion.getUserLimit();
     }
 
+    /** 判断分类ID是否在scopeValues JSON数组中 */
+    private boolean matchesCategory(String scopeValues, Integer categoryId) {
+        if (scopeValues == null || scopeValues.isBlank() || categoryId == null) return false;
+        try {
+            List<?> ids = MAPPER.readValue(scopeValues, List.class);
+            return ids.stream().anyMatch(id -> {
+                if (id instanceof Number) return ((Number) id).intValue() == categoryId;
+                return String.valueOf(id).equals(String.valueOf(categoryId));
+            });
+        } catch (Exception e) {
+            log.warn("[Promotion] 解析scopeValues失败: {}", scopeValues, e);
+            return false;
+        }
+    }
+
+    /** PromotionRules -> JSON字符串 */
+    private String serializeRules(PromotionRules rules) {
+        if (rules == null) return null;
+        try {
+            return MAPPER.writeValueAsString(rules);
+        } catch (Exception e) {
+            log.warn("[Promotion] 序列化rules失败", e);
+            return null;
+        }
+    }
+
+    /** JSON字符串 -> PromotionRules */
+    private PromotionRules parseRules(String rulesJson) {
+        if (rulesJson == null || rulesJson.isBlank()) return null;
+        try {
+            return MAPPER.readValue(rulesJson, PromotionRules.class);
+        } catch (Exception e) {
+            log.warn("[Promotion] 反序列化rules失败: {}", rulesJson, e);
+            return null;
+        }
+    }
+
+    /** 从rules JSON解析折扣规则计算最终价格 */
+    @SuppressWarnings("unchecked")
+    private BigDecimal calculatePriceFromRules(String rulesJson, BigDecimal originalPrice) {
+        if (rulesJson == null || rulesJson.isBlank() || originalPrice == null) return originalPrice;
+        try {
+            Map<String, Object> rules = MAPPER.readValue(rulesJson, Map.class);
+            // 固定促销价
+            if (rules.containsKey("promotionPrice")) {
+                return new BigDecimal(String.valueOf(rules.get("promotionPrice")));
+            }
+            // 折扣率 (0.8 = 八折)
+            if (rules.containsKey("discountRate")) {
+                BigDecimal rate = new BigDecimal(String.valueOf(rules.get("discountRate")));
+                return originalPrice.multiply(rate).setScale(2, RoundingMode.HALF_UP);
+            }
+            // 直减金额
+            if (rules.containsKey("discountAmount")) {
+                BigDecimal amount = new BigDecimal(String.valueOf(rules.get("discountAmount")));
+                BigDecimal result = originalPrice.subtract(amount);
+                return result.compareTo(BigDecimal.ZERO) > 0 ? result : BigDecimal.ZERO;
+            }
+        } catch (Exception e) {
+            log.warn("[Promotion] 解析促销规则失败: {}", rulesJson, e);
+        }
+        return originalPrice;
+    }
+
+    @Override
+    public int batchExpirePromotions() {
+        return promotionRepository.batchExpirePromotions();
+    }
+
     private BigDecimal calculateFinalPrice(PromotionSkill ps, BigDecimal originalPrice) {
         if (ps.getPromotionPrice() != null) {
             return ps.getPromotionPrice();

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/promotion/task/PromotionExpireTask.java

@@ -0,0 +1,28 @@
+package com.openclaw.module.promotion.task;
+
+import com.openclaw.module.promotion.service.PromotionService;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class PromotionExpireTask {
+
+    private final PromotionService promotionService;
+
+    /** 每10分钟执行一次: 批量结束已过期的促销活动 */
+    @Scheduled(cron = "0 */10 * * * ?")
+    public void expirePromotions() {
+        try {
+            int count = promotionService.batchExpirePromotions();
+            if (count > 0) {
+                log.info("[PromotionExpireTask] 本次过期促销活动: {}个", count);
+            }
+        } catch (Exception e) {
+            log.error("[PromotionExpireTask] 执行失败", e);
+        }
+    }
+}

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/promotion/vo/PromotionDetailVO.java

@@ -1,5 +1,6 @@
 package com.openclaw.module.promotion.vo;
 
+import com.openclaw.module.promotion.dto.PromotionRules;
 import lombok.Data;
 
 import java.time.LocalDateTime;
@@ -13,7 +14,7 @@ public class PromotionDetailVO {
     private String status;
     private LocalDateTime startTime;
     private LocalDateTime endTime;
-    private String rules;
+    private PromotionRules rules;
     private String scopeType;
     private String scopeValues;
     private String exclusiveGroup;

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/promotion/vo/SkillPromotionVO.java

@@ -7,6 +7,7 @@ import java.time.LocalDateTime;
 
 @Data
 public class SkillPromotionVO {
+    private Long skillId;
     private Long promotionId;
     private String promotionName;
     private String promotionType;

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/skill/controller/CategoryController.java

@@ -5,6 +5,8 @@ import com.openclaw.common.Result;
 import com.openclaw.module.skill.entity.SkillCategory;
 import com.openclaw.module.skill.repository.SkillCategoryRepository;
 import com.openclaw.module.skill.vo.CategoryVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
@@ -13,6 +15,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
+@Tag(name = "分类管理", description = "技能分类树查询")
 @RestController
 @RequestMapping("/api/v1/categories")
 @RequiredArgsConstructor
@@ -20,7 +23,7 @@ public class CategoryController {
 
     private final SkillCategoryRepository categoryRepository;
 
-    /** 获取分类树（公开） */
+    @Operation(summary = "获取分类树", description = "公开接口，返回树形结构")
     @GetMapping
     public Result<List<CategoryVO>> listCategories() {
         List<SkillCategory> all = categoryRepository.selectList(
@@ -29,7 +32,7 @@ public class CategoryController {
         return Result.ok(buildTree(all));
     }
 
-    /** 获取单个分类 */
+    @Operation(summary = "获取单个分类")
     @GetMapping("/{id}")
     public Result<CategoryVO> getCategory(@PathVariable Integer id) {
         SkillCategory cat = categoryRepository.selectById(id);

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/skill/controller/SkillController.java

@@ -7,11 +7,14 @@ import com.openclaw.module.skill.service.SkillService;
 import com.openclaw.annotation.RequiresRole;
 import com.openclaw.util.UserContext;
 import com.openclaw.module.skill.vo.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 import java.util.List;
 
+@Tag(name = "技能商城", description = "Skill列表、详情、评价、榜单、CRUD")
 @RestController
 @RequestMapping("/api/v1/skills")
 @RequiredArgsConstructor
@@ -19,27 +22,27 @@ public class SkillController {
 
     private final SkillService skillService;
 
-    /** Skill列表（公开，支持分页/筛选/排序） */
+    @Operation(summary = "Skill列表", description = "公开接口，支持分页/分类/价格/排序筛选")
     @GetMapping
     public Result<IPage<SkillVO>> listSkills(SkillQueryDTO query) {
         Long userId = UserContext.getUserId();  // 未登录为null
         return Result.ok(skillService.listSkills(query, userId));
     }
 
-    /** Skill详情（公开） */
+    @Operation(summary = "Skill详情", description = "公开接口，获取单个Skill完整信息")
     @GetMapping("/{id}")
     public Result<SkillVO> getDetail(@PathVariable Long id) {
         return Result.ok(skillService.getSkillDetail(id, UserContext.getUserId()));
     }
 
-    /** 上传Skill（需登录，creator及以上） */
+    @Operation(summary = "创建Skill", description = "需creator及以上角色")
     @RequiresRole({"creator", "admin", "super_admin"})
     @PostMapping
     public Result<SkillVO> createSkill(@Valid @RequestBody SkillCreateDTO dto) {
         return Result.ok(skillService.createSkill(UserContext.getUserId(), dto));
     }
 
-    /** 更新Skill（创建者本人） */
+    @Operation(summary = "更新Skill")
     @RequiresRole({"creator", "admin", "super_admin"})
     @PutMapping("/{id}")
     public Result<SkillVO> updateSkill(
@@ -48,7 +51,7 @@ public class SkillController {
         return Result.ok(skillService.updateSkill(UserContext.getUserId(), id, dto));
     }
 
-    /** 删除Skill（创建者本人） */
+    @Operation(summary = "删除Skill")
     @RequiresRole({"creator", "admin", "super_admin"})
     @DeleteMapping("/{id}")
     public Result<Void> deleteSkill(@PathVariable Long id) {
@@ -56,7 +59,7 @@ public class SkillController {
         return Result.ok();
     }
 
-    /** 获取Skill评论列表（公开） */
+    @Operation(summary = "获取评论列表", description = "公开接口，分页")
     @GetMapping("/{id}/reviews")
     public Result<IPage<SkillReviewVO>> getReviews(
             @PathVariable Long id,
@@ -65,7 +68,7 @@ public class SkillController {
         return Result.ok(skillService.getReviews(id, UserContext.getUserId(), pageNum, pageSize));
     }
 
-    /** 发表评价（需登录且已拥有） */
+    @Operation(summary = "发表评价", description = "需登录且已购买")
     @RequiresRole("user")
     @PostMapping("/{id}/reviews")
     public Result<Void> submitReview(
@@ -75,7 +78,7 @@ public class SkillController {
         return Result.ok();
     }
 
-    /** 点赞评论 */
+    @Operation(summary = "点赞评论")
     @RequiresRole("user")
     @PostMapping("/reviews/{reviewId}/like")
     public Result<Void> likeReview(@PathVariable Long reviewId) {
@@ -83,7 +86,7 @@ public class SkillController {
         return Result.ok();
     }
 
-    /** 删除自己的评论 */
+    @Operation(summary = "删除评论")
     @RequiresRole("user")
     @DeleteMapping("/reviews/{reviewId}")
     public Result<Void> deleteReview(@PathVariable Long reviewId) {
@@ -91,7 +94,7 @@ public class SkillController {
         return Result.ok();
     }
 
-    /** 热门榜单（公开） */
+    @Operation(summary = "热门榜单", description = "公开接口，按下载/评分/最新排序")
     @GetMapping("/ranking")
     public Result<List<SkillVO>> getRanking(
             @RequestParam(defaultValue = "downloads") String sortBy,

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/skill/controller/SkillFavoriteController.java

@@ -5,6 +5,8 @@ import com.openclaw.common.Result;
 import com.openclaw.module.skill.entity.SkillFavorite;
 import com.openclaw.module.skill.repository.SkillFavoriteRepository;
 import com.openclaw.util.UserContext;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
@@ -13,6 +15,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
+@Tag(name = "收藏管理", description = "收藏/取消收藏Skill")
 @RestController
 @RequestMapping("/api/v1/favorites")
 @RequiredArgsConstructor
@@ -20,9 +23,7 @@ public class SkillFavoriteController {
 
     private final SkillFavoriteRepository favoriteRepository;
 
-    /**
+    @Operation(summary = "收藏/取消收藏", description = "切换收藏状态")
-     * 收藏/取消收藏
-     */
     @PostMapping("/{skillId}")
     public Result<Map<String, Object>> toggleFavorite(@PathVariable Long skillId) {
         Long userId = UserContext.getUserId();
@@ -48,9 +49,7 @@ public class SkillFavoriteController {
         return Result.ok(result);
     }
 
-    /**
+    @Operation(summary = "查询是否已收藏")
-     * 查询是否已收藏
-     */
     @GetMapping("/{skillId}")
     public Result<Map<String, Object>> checkFavorite(@PathVariable Long skillId) {
         Long userId = UserContext.getUserId();
@@ -60,9 +59,7 @@ public class SkillFavoriteController {
         return Result.ok(result);
     }
 
-    /**
+    @Operation(summary = "获取我的收藏列表", description = "返回收藏Skill ID列表")
-     * 获取我的收藏列表
-     */
     @GetMapping
     public Result<List<Long>> getMyFavorites() {
         Long userId = UserContext.getUserId();

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/skill/service/impl/SkillServiceImpl.java

@@ -13,6 +13,7 @@ import com.openclaw.module.user.entity.User;
 import com.openclaw.module.user.repository.UserRepository;
 import com.openclaw.module.skill.vo.*;
 import lombok.RequiredArgsConstructor;
+import org.springframework.data.redis.core.StringRedisTemplate;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
@@ -25,6 +26,7 @@ public class SkillServiceImpl implements SkillService {
     private final SkillReviewRepository reviewRepository;
     private final SkillDownloadRepository downloadRepository;
     private final UserRepository userRepository;
+    private final StringRedisTemplate redisTemplate;
 
     @Override
     public IPage<SkillVO> listSkills(SkillQueryDTO query, Long currentUserId) {
@@ -81,8 +83,14 @@ public class SkillServiceImpl implements SkillService {
     @Override
     @Transactional
     public void submitReview(Long skillId, Long userId, SkillReviewDTO dto) {
-        // 检查是否已购买
+        // 检查是否已获取
-        if (!hasOwned(userId, skillId)) throw new BusinessException(ErrorCode.SKILL_NOT_FOUND);
+        if (!hasOwned(userId, skillId)) throw new BusinessException(ErrorCode.REVIEW_NOT_ALLOWED);
+        // 检查是否已评价过
+        Long existCount = reviewRepository.selectCount(
+            new LambdaQueryWrapper<SkillReview>()
+                .eq(SkillReview::getSkillId, skillId)
+                .eq(SkillReview::getUserId, userId));
+        if (existCount > 0) throw new BusinessException(ErrorCode.REVIEW_DUPLICATE);
 
         SkillReview review = new SkillReview();
         review.setSkillId(skillId);
@@ -111,6 +119,10 @@ public class SkillServiceImpl implements SkillService {
     @Override
     @Transactional
     public void grantAccess(Long userId, Long skillId, Long orderId, String type) {
+        // 幂等：已拥有则跳过，防止唯一约束 uk_user_skill 冲突
+        if (hasOwned(userId, skillId)) {
+            return;
+        }
         SkillDownload d = new SkillDownload();
         d.setUserId(userId);
         d.setSkillId(skillId);
@@ -166,6 +178,14 @@ public class SkillServiceImpl implements SkillService {
     public void likeReview(Long reviewId, Long userId) {
         SkillReview review = reviewRepository.selectById(reviewId);
         if (review == null) throw new BusinessException(400, "评论不存在");
+        // 防刷：Redis Set 去重，每个用户对同一评论只能点赞一次
+        String key = "review:like:" + reviewId;
+        Boolean added = redisTemplate.opsForSet().add(key, String.valueOf(userId)) == 1;
+        if (Boolean.FALSE.equals(added)) {
+            throw new BusinessException(400, "您已点赞过该评论");
+        }
+        // 设置30天过期，避免Redis无限膨胀
+        redisTemplate.expire(key, 30, java.util.concurrent.TimeUnit.DAYS);
         review.setHelpfulCount(review.getHelpfulCount() == null ? 1 : review.getHelpfulCount() + 1);
         reviewRepository.updateById(review);
     }

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/user/controller/UserController.java

@@ -1,5 +1,6 @@
 package com.openclaw.module.user.controller;
 
+import com.openclaw.annotation.RateLimit;
 import com.openclaw.common.Result;
 import com.openclaw.module.log.annotation.OpLog;
 import com.openclaw.module.user.dto.*;
@@ -7,6 +8,8 @@ import com.openclaw.module.user.service.UserService;
 import com.openclaw.annotation.RequiresRole;
 import com.openclaw.util.UserContext;
 import com.openclaw.module.user.vo.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
@@ -14,6 +17,7 @@ import org.springframework.web.bind.annotation.*;
 
 import java.util.Map;
 
+@Tag(name = "用户账户", description = "注册、登录、个人信息、密码管理、换号")
 @RestController
 @RequestMapping("/api/v1/users")
 @RequiredArgsConstructor
@@ -21,7 +25,8 @@ public class UserController {
 
     private final UserService userService;
 
-    /** 发送短信验证码（注册/找回密码用） */
+    @Operation(summary = "发送短信验证码", description = "注册/找回密码时发送短信验证码，60秒内限1次")
+    @RateLimit(window = 60, maxRequests = 1, message = "短信发送过于频繁，请60秒后再试")
     @PostMapping("/sms/code")
     public Result<Void> sendSmsCode(@Valid @RequestBody SmsCodeDTO dto, HttpServletRequest request) {
         String ip = getClientIp(request);
@@ -46,19 +51,21 @@ public class UserController {
         return ip;
     }
 
-    /** 用户注册 */
+    @Operation(summary = "用户注册", description = "手机号+短信验证码注册，返回JWT令牌")
+    @RateLimit(window = 60, maxRequests = 5, message = "注册请求过于频繁，请稍后再试")
     @PostMapping("/register")
     public Result<LoginVO> register(@Valid @RequestBody UserRegisterDTO dto) {
         return Result.ok(userService.register(dto));
     }
 
-    /** 用户登录 */
+    @Operation(summary = "用户登录", description = "手机号+密码登录，返回JWT令牌")
+    @RateLimit(window = 60, maxRequests = 10, message = "登录请求过于频繁，请稍后再试")
     @PostMapping("/login")
     public Result<LoginVO> login(@Valid @RequestBody UserLoginDTO dto) {
         return Result.ok(userService.login(dto));
     }
 
-    /** 退出登录 */
+    @Operation(summary = "退出登录")
     @RequiresRole("user")
     @PostMapping("/logout")
     public Result<Void> logout(@RequestHeader("Authorization") String authorization) {
@@ -67,14 +74,14 @@ public class UserController {
         return Result.ok();
     }
 
-    /** 获取当前用户信息 */
+    @Operation(summary = "获取当前用户信息")
     @RequiresRole("user")
     @GetMapping("/profile")
     public Result<UserVO> getProfile() {
         return Result.ok(userService.getCurrentUser(UserContext.getUserId()));
     }
 
-    /** 更新个人信息 */
+    @Operation(summary = "更新个人信息", description = "修改昵称、头像、邮箱、简介等")
     @RequiresRole("user")
     @PutMapping("/profile")
     public Result<UserVO> updateProfile(@Valid @RequestBody UserUpdateDTO dto) {
@@ -90,7 +97,7 @@ public class UserController {
         return Result.ok();
     }
 
-    /** 获取当前用户脱敏手机号（换号页面初始化用） */
+    @Operation(summary = "获取脱敏手机号", description = "换号页面初始化用")
     @RequiresRole("user")
     @GetMapping("/phone/masked")
     public Result<Map<String, String>> getMaskedPhone() {
@@ -98,7 +105,7 @@ public class UserController {
         return Result.ok(Map.of("maskedPhone", masked));
     }
 
-    /** 换号 Step1：验证原手机号短信码 */
+    @Operation(summary = "换号Step1-验证原手机号", description = "验证原手机号短信码，返回ticket")
     @RequiresRole("user")
     @PostMapping("/phone/verify")
     @OpLog(module = "user", action = "update", description = "换号Step1-验证原手机号", targetType = "user")
@@ -106,7 +113,7 @@ public class UserController {
         return Result.ok(userService.verifyOldPhone(UserContext.getUserId(), dto));
     }
 
-    /** 换号 Step2：凭 ticket 绑定新手机号 */
+    @Operation(summary = "换号Step2-绑定新手机号", description = "凭ticket绑定新手机号")
     @RequiresRole("user")
     @PostMapping("/phone/bind")
     @OpLog(module = "user", action = "update", description = "换号Step2-绑定新手机号", targetType = "user")
@@ -115,7 +122,7 @@ public class UserController {
         return Result.ok();
     }
 
-    /** 修改密码 */
+    @Operation(summary = "修改密码", description = "需提供旧密码验证")
     @RequiresRole("user")
     @PutMapping("/password")
     public Result<Void> changePassword(@Valid @RequestBody ChangePasswordDTO dto) {
@@ -123,7 +130,8 @@ public class UserController {
         return Result.ok();
     }
 
-    /** 忘记密码 - 重置 */
+    @Operation(summary = "忘记密码-重置", description = "通过手机号+短信验证码重置密码")
+    @RateLimit(window = 60, maxRequests = 5, message = "密码重置请求过于频繁，请稍后再试")
     @PostMapping("/password/reset")
     public Result<Void> resetPassword(@Valid @RequestBody ResetPasswordDTO dto) {
         userService.resetPassword(dto.getPhone(), dto.getSmsCode(), dto.getNewPassword());

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/user/controller/WechatAuthController.java

@@ -6,12 +6,15 @@ import com.openclaw.module.user.dto.WechatBindPhoneDTO;
 import com.openclaw.module.user.dto.WechatLoginDTO;
 import com.openclaw.module.user.service.WechatAuthService;
 import com.openclaw.module.user.vo.WechatLoginVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.Map;
 
+@Tag(name = "微信认证", description = "微信扫码登录、绑定/解绑微信")
 @RestController
 @RequestMapping("/api/v1/wechat")
 @RequiredArgsConstructor
@@ -19,28 +22,28 @@ public class WechatAuthController {
 
     private final WechatAuthService wechatAuthService;
 
-    /** 获取微信扫码登录授权URL（无需登录） */
+    @Operation(summary = "获取微信扫码授权URL")
     @GetMapping("/authorize-url")
     public Result<Map<String, String>> getAuthorizeUrl() {
         String url = wechatAuthService.getAuthorizeUrl();
         return Result.ok(Map.of("authorizeUrl", url));
     }
 
-    /** 微信扫码回调登录（无需登录） */
+    @Operation(summary = "微信扫码登录", description = "凭code换取用户信息并登录")
     @PostMapping("/login")
     public Result<WechatLoginVO> login(@RequestBody @Valid WechatLoginDTO dto) {
         WechatLoginVO vo = wechatAuthService.loginByCode(dto.getCode(), dto.getState());
         return Result.ok(vo);
     }
 
-    /** 绑定手机号（无需登录，用bindTicket） */
+    @Operation(summary = "微信用户绑定手机号")
     @PostMapping("/bind-phone")
     public Result<WechatLoginVO> bindPhone(@RequestBody @Valid WechatBindPhoneDTO dto) {
         WechatLoginVO vo = wechatAuthService.bindPhone(dto);
         return Result.ok(vo);
     }
 
-    /** 已登录用户绑定微信（需登录） */
+    @Operation(summary = "已登录用户绑定微信")
     @PostMapping("/bind")
     public Result<Void> bindWechat(@RequestBody @Valid WechatLoginDTO dto) {
         Long userId = UserContext.getUserId();
@@ -48,7 +51,7 @@ public class WechatAuthController {
         return Result.ok();
     }
 
-    /** 已登录用户解绑微信（需登录） */
+    @Operation(summary = "解绑微信")
     @PostMapping("/unbind")
     public Result<Void> unbindWechat() {
         Long userId = UserContext.getUserId();

openclaw-backend/openclaw-backend/src/main/java/com/openclaw/module/user/entity/User.java

@@ -1,6 +1,7 @@
 package com.openclaw.module.user.entity;
 
 import com.baomidou.mybatisplus.annotation.*;
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import lombok.Data;
 import java.time.LocalDateTime;
 
@@ -10,6 +11,7 @@ public class User {
     @TableId(type = IdType.AUTO)
     private Long id;
     private String phone;
+    @JsonIgnore
     private String passwordHash;
     private String nickname;
     private String avatarUrl;