feat(quality-owner): 增加开通协议与强制阅读

frontend/src/features/admin/components/QualityOwnerConfigDialog.vue

@@ -19,6 +19,9 @@ const form = reactive({
   depositYuan: 200,
   insurancePercent: 8,
   premiumInsurancePercent: 4,
+  agreementTitle: '',
+  agreementContent: '',
+  agreementReadSeconds: 15,
   description: '',
   saving: false,
 })
@@ -32,10 +35,18 @@ watch(
       form.depositYuan = Number(parsed.deposit_amount_cent || 20000) / 100
       form.insurancePercent = Number(parsed.insurance_fee_bps || 800) / 100
       form.premiumInsurancePercent = Number(parsed.premium_insurance_fee_bps || 400) / 100
+      form.agreementTitle =
+        typeof parsed.agreement_title === 'string' ? parsed.agreement_title : '优质号主服务协议'
+      form.agreementContent =
+        typeof parsed.agreement_content === 'string' ? parsed.agreement_content : ''
+      form.agreementReadSeconds = Math.max(15, Number(parsed.agreement_read_seconds || 15))
     } catch {
       form.depositYuan = 200
       form.insurancePercent = 8
       form.premiumInsurancePercent = 4
+      form.agreementTitle = '优质号主服务协议'
+      form.agreementContent = ''
+      form.agreementReadSeconds = 15
     }
     form.description = props.config.description || ''
   },
@@ -55,6 +66,14 @@ async function save() {
     ElMessage.warning('极品专区费率不能高于普通保险费率')
     return
   }
+  if (!form.agreementTitle.trim() || !form.agreementContent.trim()) {
+    ElMessage.warning('请填写优质号主协议标题和正文')
+    return
+  }
+  if (form.agreementReadSeconds < 15 || form.agreementReadSeconds > 300) {
+    ElMessage.warning('强制阅读时长必须在 15-300 秒之间')
+    return
+  }
   form.saving = true
   try {
     await updateSystemConfig(props.config.key, {
@@ -62,6 +81,9 @@ async function save() {
         deposit_amount_cent: Math.round(form.depositYuan * 100),
         insurance_fee_bps: Math.round(form.insurancePercent * 100),
         premium_insurance_fee_bps: Math.round(form.premiumInsurancePercent * 100),
+        agreement_title: form.agreementTitle.trim(),
+        agreement_content: form.agreementContent.trim(),
+        agreement_read_seconds: Math.round(form.agreementReadSeconds),
       }),
       description: form.description,
     })
@@ -80,7 +102,8 @@ async function save() {
   <el-dialog
     :model-value="modelValue"
     title="优质号主与无忧租号保险"
-    width="560px"
+    width="900px"
+    class="quality-owner-config-dialog"
     @update:model-value="emit('update:modelValue', $event)"
   >
     <el-form label-position="top">
@@ -105,6 +128,27 @@ async function save() {
           :step="0.5"
         />
       </el-form-item>
+      <el-form-item label="开通协议标题">
+        <el-input v-model="form.agreementTitle" placeholder="优质号主服务协议" />
+      </el-form-item>
+      <el-form-item label="强制阅读时长（秒）">
+        <el-input-number
+          v-model="form.agreementReadSeconds"
+          :min="15"
+          :max="300"
+          :step="1"
+          :precision="0"
+        />
+        <span class="agreement-config-hint">最低 15 秒，用户阅读完成并勾选同意后才能继续。</span>
+      </el-form-item>
+      <el-form-item label="开通协议正文">
+        <el-input
+          v-model="form.agreementContent"
+          type="textarea"
+          :rows="20"
+          placeholder="支持 Markdown 标题、列表和表格"
+        />
+      </el-form-item>
       <el-form-item label="配置说明">
         <el-input v-model="form.description" type="textarea" :rows="3" />
       </el-form-item>
@@ -112,7 +156,7 @@ async function save() {
     <el-alert
       type="info"
       :closable="false"
-      title="费率按号主实际到手租金计算，并在订单结算时扣减；历史订单保留下单时费率快照。"
+      title="费率按号主实际到手租金计算，并在订单结算时扣减；历史订单保留下单时费率快照。协议正文支持 Markdown 表格。"
     />
     <template #footer>
       <el-button @click="emit('update:modelValue', false)">取消</el-button>
@@ -120,3 +164,17 @@ async function save() {
     </template>
   </el-dialog>
 </template>
+
+<style scoped>
+:global(.quality-owner-config-dialog .el-dialog__body) {
+  max-height: 72vh;
+  overflow-y: auto;
+  padding-right: 18px;
+}
+
+.agreement-config-hint {
+  margin-left: 10px;
+  color: #64748b;
+  font-size: 12px;
+}
+</style>

frontend/src/features/admin/views/AdminSystemConfigsView.vue

@@ -660,12 +660,11 @@ function formatConfigValue(row: SystemConfig) {
           <p class="eyebrow">Premium Owner</p>
           <h2>优质号主与无忧租号保险</h2>
           <span>
-            配置优质号主保证金，以及普通发布和「优质号主 + 极品专区」的无忧租号保险服务费率。
+            配置优质号主保证金、开通协议，以及普通发布和「优质号主 +
+            极品专区」的无忧租号保险服务费率。
           </span>
         </div>
-        <el-button type="primary" @click="openEdit(qualityOwnerConfig)">
-          编辑保证金与费率
-        </el-button>
+        <el-button type="primary" @click="openEdit(qualityOwnerConfig)"> 编辑配置 </el-button>
       </div>
       <div class="publish-stat-grid home-stat-grid">
         <div class="publish-stat">

frontend/src/features/auth/views/MobileProfileView.css

@@ -882,6 +882,77 @@
   min-width: 72px;
 }
 
+.quality-owner-agreement-popup {
+  overflow: hidden;
+}
+
+.quality-owner-agreement-shell {
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr) auto;
+  height: 100%;
+  background: #fff;
+}
+
+.quality-owner-agreement-header {
+  padding: 18px 46px 12px 16px;
+  border-bottom: 1px solid #eef1f5;
+}
+
+.quality-owner-agreement-header h3 {
+  margin: 0;
+  color: #20242a;
+  font-size: 17px;
+  font-weight: 900;
+}
+
+.quality-owner-agreement-header p {
+  margin: 5px 0 0;
+  color: #858c96;
+  font-size: 11px;
+}
+
+.quality-owner-agreement-scroll {
+  overflow-y: auto;
+  padding: 12px 16px 16px;
+  overscroll-behavior: contain;
+}
+
+.quality-owner-agreement-actions {
+  display: grid;
+  gap: 10px;
+  padding: 12px 16px calc(12px + env(safe-area-inset-bottom));
+  border-top: 1px solid #eef1f5;
+  background: #fff;
+}
+
+.quality-owner-agreement-actions :deep(.van-checkbox__label) {
+  color: #7c2d12;
+  font-size: 11px;
+  font-weight: 700;
+  line-height: 1.5;
+}
+
+.quality-owner-agreement-submit {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 12px;
+}
+
+.quality-owner-agreement-submit > span {
+  color: #c2410c;
+  font-size: 11px;
+  font-weight: 800;
+}
+
+.quality-owner-agreement-submit > span.is-ready {
+  color: #15803d;
+}
+
+.quality-owner-agreement-submit :deep(.van-button) {
+  min-width: 132px;
+}
+
 /* ========== 响应式适配 ========== */
 @media (min-width: 520px) {
   .mobile-profile-shell {

frontend/src/features/auth/views/MobileProfileView.vue

@@ -26,6 +26,8 @@ import {
   startQualityOwnerPayment,
   type QualityOwnerStatus,
 } from '@/features/quality-owner/api/qualityOwner'
+import QualityOwnerAgreementContent from '@/features/quality-owner/components/QualityOwnerAgreementContent.vue'
+import { useQualityOwnerAgreement } from '@/features/quality-owner/composables/useQualityOwnerAgreement'
 import type { PaymentPayWay } from '@/features/orders/api/orders'
 import { useMobilePayWaySelect } from '@/features/orders/composables/useMobilePayWaySelect'
 import { useMobilePaymentCashier } from '@/features/orders/composables/useMobilePaymentCashier'
@@ -50,6 +52,15 @@ const qualityOwnerStatus = ref<QualityOwnerStatus | null>(null)
 const qualityOwnerLoading = ref(false)
 const qualityOwnerOnlineLoading = ref(false)
 const qualityOwnerCancelling = ref(false)
+const {
+  visible: qualityOwnerAgreementVisible,
+  accepted: qualityOwnerAgreementAccepted,
+  remainingSeconds: qualityOwnerAgreementRemainingSeconds,
+  canConfirm: qualityOwnerAgreementCanConfirm,
+  open: openQualityOwnerAgreement,
+  close: closeQualityOwnerAgreement,
+  confirm: confirmQualityOwnerAgreement,
+} = useQualityOwnerAgreement()
 const qualityOwnerPayWaySelect = useMobilePayWaySelect()
 const qualityOwnerCashier = useMobilePaymentCashier({
   queryPayment: () => queryQualityOwnerPayment(),
@@ -164,22 +175,13 @@ async function loadQualityOwnerStatus() {
   }
 }
 
-async function handleActivateQualityOwner() {
+function handleActivateQualityOwner() {
   const status = qualityOwnerStatus.value
   if (!status || status.active) return
-  try {
-    await showDialog({
-      title: '开通优质号主',
-      message: `确认从可用余额中扣除 ¥${formatCent(
-        status.required_deposit_cent
-      )} 作为保证金？取消资格时会退回余额。`,
-      showCancelButton: true,
-      confirmButtonText: '确认缴纳',
-      cancelButtonText: '取消',
-    })
-  } catch {
-    return
-  }
+  openQualityOwnerAgreement(status, activateQualityOwnerByBalance)
+}
+
+async function activateQualityOwnerByBalance() {
   qualityOwnerLoading.value = true
   try {
     qualityOwnerStatus.value = await activateQualityOwner()
@@ -193,7 +195,13 @@ async function handleActivateQualityOwner() {
   }
 }
 
-async function handleOnlineQualityOwnerPayment() {
+function handleOnlineQualityOwnerPayment() {
+  const status = qualityOwnerStatus.value
+  if (!status || status.active) return
+  openQualityOwnerAgreement(status, continueOnlineQualityOwnerPayment)
+}
+
+async function continueOnlineQualityOwnerPayment() {
   const payWay = await qualityOwnerPayWaySelect.select()
   if (!payWay) return
   qualityOwnerOnlineLoading.value = true
@@ -760,6 +768,51 @@ function resolveAvatarURL(url: string | undefined | null) {
       @refresh="qualityOwnerCashier.refreshPaymentStatus(false)"
     />
 
+    <van-popup
+      v-model:show="qualityOwnerAgreementVisible"
+      position="bottom"
+      round
+      closeable
+      :close-on-click-overlay="false"
+      class="quality-owner-agreement-popup"
+      :style="{ height: '86%' }"
+      @closed="closeQualityOwnerAgreement"
+    >
+      <div class="quality-owner-agreement-shell">
+        <header class="quality-owner-agreement-header">
+          <h3>{{ qualityOwnerStatus?.agreement_title || '优质号主服务协议' }}</h3>
+          <p>请完整阅读后勾选同意并继续开通</p>
+        </header>
+        <div class="quality-owner-agreement-scroll">
+          <QualityOwnerAgreementContent :content="qualityOwnerStatus?.agreement_content || ''" />
+        </div>
+        <footer class="quality-owner-agreement-actions">
+          <van-checkbox v-model="qualityOwnerAgreementAccepted" icon-size="18px">
+            本人已详细阅读并充分理解本协议全部内容，同意遵守上述条款
+          </van-checkbox>
+          <div class="quality-owner-agreement-submit">
+            <span v-if="qualityOwnerAgreementRemainingSeconds > 0">
+              还需阅读 {{ qualityOwnerAgreementRemainingSeconds }} 秒
+            </span>
+            <span v-else class="is-ready">已完成强制阅读</span>
+            <van-button
+              round
+              type="primary"
+              color="#7c3aed"
+              :disabled="!qualityOwnerAgreementCanConfirm"
+              @click="confirmQualityOwnerAgreement"
+            >
+              {{
+                qualityOwnerAgreementRemainingSeconds > 0
+                  ? `还需阅读 ${qualityOwnerAgreementRemainingSeconds} 秒`
+                  : '同意并继续'
+              }}
+            </van-button>
+          </div>
+        </footer>
+      </div>
+    </van-popup>
+
     <!-- 账单明细 Popup -->
     <van-popup
       v-model:show="showLedgers"

frontend/src/features/auth/views/ProfileView.vue

@@ -29,6 +29,8 @@ import {
   startQualityOwnerPayment,
   type QualityOwnerStatus,
 } from '@/features/quality-owner/api/qualityOwner'
+import QualityOwnerAgreementContent from '@/features/quality-owner/components/QualityOwnerAgreementContent.vue'
+import { useQualityOwnerAgreement } from '@/features/quality-owner/composables/useQualityOwnerAgreement'
 import { formatCent } from '@/shared/utils/money'
 import type { PaymentPayWay } from '@/features/orders/api/orders'
 import { useOrderPaymentCashier } from '@/features/orders/composables/useOrderPaymentCashier'
@@ -42,6 +44,15 @@ const qualityOwnerOnlineLoading = ref(false)
 const qualityOwnerCancelling = ref(false)
 const qualityOwnerPayWayVisible = ref(false)
 const qualityOwnerStatus = ref<QualityOwnerStatus | null>(null)
+const {
+  visible: qualityOwnerAgreementVisible,
+  accepted: qualityOwnerAgreementAccepted,
+  remainingSeconds: qualityOwnerAgreementRemainingSeconds,
+  canConfirm: qualityOwnerAgreementCanConfirm,
+  open: openQualityOwnerAgreement,
+  close: closeQualityOwnerAgreement,
+  confirm: confirmQualityOwnerAgreement,
+} = useQualityOwnerAgreement()
 const uploadingAvatar = ref(false)
 const avatarFileInput = ref<HTMLInputElement | null>(null)
 const form = reactive({
@@ -101,23 +112,13 @@ async function loadQualityOwnerStatus() {
   }
 }
 
-async function handleActivateQualityOwner() {
+function handleActivateQualityOwner() {
   const status = qualityOwnerStatus.value
   if (!status || status.active) return
-  const deposit = formatCent(status.required_deposit_cent)
-  try {
-    await ElMessageBox.confirm(
-      `确认从可用余额中扣除 ¥${deposit} 作为优质号主保证金？保证金会冻结，取消优质号主资格时退回。`,
-      '开通优质号主',
-      {
-        type: 'warning',
-        confirmButtonText: '确认缴纳',
-        cancelButtonText: '取消',
-      }
-    )
-  } catch {
-    return
-  }
+  openQualityOwnerAgreement(status, activateQualityOwnerByBalance)
+}
+
+async function activateQualityOwnerByBalance() {
   qualityOwnerLoading.value = true
   try {
     qualityOwnerStatus.value = await activateQualityOwner()
@@ -131,6 +132,12 @@ async function handleActivateQualityOwner() {
 }
 
 function openQualityOwnerOnlinePayment() {
+  const status = qualityOwnerStatus.value
+  if (!status || status.active) return
+  openQualityOwnerAgreement(status, continueQualityOwnerOnlinePayment)
+}
+
+function continueQualityOwnerOnlinePayment() {
   qualityOwnerPayWayVisible.value = true
 }
 
@@ -507,7 +514,11 @@ async function savePassword() {
           >
             余额支付开通
           </el-button>
-          <el-button :loading="qualityOwnerOnlineLoading" @click="openQualityOwnerOnlinePayment">
+          <el-button
+            :loading="qualityOwnerOnlineLoading"
+            :disabled="!qualityOwnerStatus"
+            @click="openQualityOwnerOnlinePayment"
+          >
             微信 / 支付宝支付开通
           </el-button>
         </div>
@@ -527,6 +538,43 @@ async function savePassword() {
 
     <PayWaySelectDialog v-model="qualityOwnerPayWayVisible" @choose="chooseQualityOwnerPayWay" />
 
+    <el-dialog
+      v-model="qualityOwnerAgreementVisible"
+      :title="qualityOwnerStatus?.agreement_title || '优质号主服务协议'"
+      width="760px"
+      append-to-body
+      :close-on-click-modal="false"
+      class="quality-owner-agreement-dialog"
+      @closed="closeQualityOwnerAgreement"
+    >
+      <div class="quality-owner-agreement-body">
+        <QualityOwnerAgreementContent :content="qualityOwnerStatus?.agreement_content || ''" />
+        <div class="quality-owner-agreement-consent">
+          <el-checkbox v-model="qualityOwnerAgreementAccepted">
+            本人已详细阅读并充分理解本协议全部内容，同意遵守上述条款
+          </el-checkbox>
+          <span v-if="qualityOwnerAgreementRemainingSeconds > 0">
+            还需阅读 {{ qualityOwnerAgreementRemainingSeconds }} 秒
+          </span>
+          <span v-else class="is-ready">已完成强制阅读</span>
+        </div>
+      </div>
+      <template #footer>
+        <el-button @click="closeQualityOwnerAgreement">取消</el-button>
+        <el-button
+          type="primary"
+          :disabled="!qualityOwnerAgreementCanConfirm"
+          @click="confirmQualityOwnerAgreement"
+        >
+          {{
+            qualityOwnerAgreementRemainingSeconds > 0
+              ? `还需阅读 ${qualityOwnerAgreementRemainingSeconds} 秒`
+              : '同意并继续'
+          }}
+        </el-button>
+      </template>
+    </el-dialog>
+
     <el-dialog
       v-model="qualityOwnerPaymentVisible"
       title="优质号主保证金支付"
@@ -1165,6 +1213,45 @@ async function savePassword() {
   margin-left: 0;
 }
 
+.quality-owner-agreement-body {
+  display: grid;
+  gap: 16px;
+}
+
+.quality-owner-agreement-body > :first-child {
+  max-height: 58vh;
+  overflow-y: auto;
+  padding: 4px 18px 16px 4px;
+}
+
+.quality-owner-agreement-consent {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 12px 14px;
+  border: 1px solid #fed7aa;
+  border-radius: 8px;
+  background: #fff7ed;
+}
+
+.quality-owner-agreement-consent :deep(.el-checkbox__label) {
+  color: #7c2d12;
+  font-size: 13px;
+  font-weight: 700;
+}
+
+.quality-owner-agreement-consent > span {
+  flex-shrink: 0;
+  color: #c2410c;
+  font-size: 12px;
+  font-weight: 800;
+}
+
+.quality-owner-agreement-consent > span.is-ready {
+  color: #15803d;
+}
+
 .quality-owner-pay-dialog-body {
   display: grid;
   gap: 14px;

frontend/src/features/quality-owner/api/qualityOwner.ts

@@ -15,11 +15,19 @@ export interface QualityOwnerStatus {
   required_deposit_cent: number
   insurance_fee_bps: number
   premium_insurance_fee_bps: number
+  agreement_title: string
+  agreement_content: string
+  agreement_read_seconds: number
 }
 
 export async function fetchQualityOwnerStatus() {
   const { data } = await apiClient.get<ApiResponse<QualityOwnerStatus>>('/quality-owner/status')
-  return data.data
+  return {
+    ...data.data,
+    agreement_title: data.data.agreement_title || '优质号主服务协议',
+    agreement_content: data.data.agreement_content || '',
+    agreement_read_seconds: Math.max(15, Number(data.data.agreement_read_seconds || 15)),
+  }
 }
 
 export async function activateQualityOwner() {

frontend/src/features/quality-owner/components/QualityOwnerAgreementContent.vue

@@ -0,0 +1,79 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+import AnnouncementContent from '@/features/announcement/components/AnnouncementContent.vue'
+import { renderAnnouncementMarkdown } from '@/features/announcement/utils/markdown'
+
+const props = defineProps<{ content: string }>()
+
+const html = computed(() => renderAnnouncementMarkdown(props.content))
+</script>
+
+<template>
+  <AnnouncementContent class="quality-owner-agreement-content" :html="html" />
+</template>
+
+<style scoped>
+.quality-owner-agreement-content {
+  color: #334155;
+  font-size: 13px;
+  line-height: 1.8;
+  overflow-wrap: anywhere;
+}
+
+.quality-owner-agreement-content :deep(h1),
+.quality-owner-agreement-content :deep(h2),
+.quality-owner-agreement-content :deep(h3) {
+  margin: 18px 0 8px;
+  color: #1f2937;
+  font-weight: 800;
+  line-height: 1.45;
+}
+
+.quality-owner-agreement-content :deep(p) {
+  margin: 8px 0;
+}
+
+.quality-owner-agreement-content :deep(ul),
+.quality-owner-agreement-content :deep(ol) {
+  margin: 8px 0;
+  padding-left: 22px;
+}
+
+.quality-owner-agreement-content :deep(table) {
+  display: block;
+  width: 100%;
+  max-width: 100%;
+  margin: 12px 0;
+  overflow-x: auto;
+  border-collapse: collapse;
+}
+
+.quality-owner-agreement-content :deep(th),
+.quality-owner-agreement-content :deep(td) {
+  min-width: 110px;
+  padding: 8px 10px;
+  border: 1px solid #e2e8f0;
+  text-align: left;
+  vertical-align: top;
+}
+
+.quality-owner-agreement-content :deep(th) {
+  background: #f8fafc;
+  color: #1f2937;
+  font-weight: 800;
+}
+
+@media (max-width: 640px) {
+  .quality-owner-agreement-content {
+    font-size: 12px;
+    line-height: 1.7;
+  }
+
+  .quality-owner-agreement-content :deep(th),
+  .quality-owner-agreement-content :deep(td) {
+    min-width: 96px;
+    padding: 7px 8px;
+  }
+}
+</style>

frontend/src/features/quality-owner/composables/__tests__/useQualityOwnerAgreement.spec.ts

@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { QualityOwnerStatus } from '@/features/quality-owner/api/qualityOwner'
+import { useQualityOwnerAgreement } from '../useQualityOwnerAgreement'
+
+function status(readSeconds = 15): QualityOwnerStatus {
+  return {
+    user_id: 1,
+    active: false,
+    status: 'none',
+    can_cancel: false,
+    active_premium_listing_count: 0,
+    deposit_amount_cent: 0,
+    deposit_source: '',
+    available_balance_cent: 20000,
+    required_deposit_cent: 20000,
+    insurance_fee_bps: 800,
+    premium_insurance_fee_bps: 400,
+    agreement_title: '优质号主服务协议',
+    agreement_content: '协议正文',
+    agreement_read_seconds: readSeconds,
+  }
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('useQualityOwnerAgreement', () => {
+  it('阅读满 15 秒且勾选后才能确认', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-11-05T00:00:00Z'))
+    const action = vi.fn()
+    const agreement = useQualityOwnerAgreement()
+
+    agreement.open(status(), action)
+    agreement.accepted.value = true
+    expect(agreement.canConfirm.value).toBe(false)
+
+    vi.advanceTimersByTime(14_999)
+    expect(agreement.remainingSeconds.value).toBe(1)
+    expect(agreement.canConfirm.value).toBe(false)
+
+    vi.advanceTimersByTime(1)
+    expect(agreement.remainingSeconds.value).toBe(0)
+    expect(agreement.canConfirm.value).toBe(true)
+
+    await agreement.confirm()
+    expect(action).toHaveBeenCalledOnce()
+    expect(agreement.visible.value).toBe(false)
+  })
+
+  it('关闭后重新打开会重新计时并清除同意状态', () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-11-05T00:00:00Z'))
+    const agreement = useQualityOwnerAgreement()
+
+    agreement.open(status(20), vi.fn())
+    agreement.accepted.value = true
+    vi.advanceTimersByTime(5000)
+    agreement.close()
+    agreement.open(status(), vi.fn())
+
+    expect(agreement.remainingSeconds.value).toBe(15)
+    expect(agreement.accepted.value).toBe(false)
+    expect(agreement.canConfirm.value).toBe(false)
+    agreement.close()
+  })
+})

frontend/src/features/quality-owner/composables/useQualityOwnerAgreement.ts

@@ -0,0 +1,72 @@
+import { computed, getCurrentInstance, onUnmounted, ref } from 'vue'
+
+import type { QualityOwnerStatus } from '@/features/quality-owner/api/qualityOwner'
+
+type AgreementAction = () => void | Promise<void>
+
+export function useQualityOwnerAgreement() {
+  const visible = ref(false)
+  const accepted = ref(false)
+  const remainingSeconds = ref(0)
+  const totalSeconds = ref(15)
+  let pendingAction: AgreementAction | null = null
+  let startedAt = 0
+  let timer: ReturnType<typeof setInterval> | null = null
+
+  const canConfirm = computed(() => visible.value && accepted.value && remainingSeconds.value <= 0)
+
+  function stopTimer() {
+    if (timer) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+
+  function updateRemaining() {
+    const elapsed = Math.floor((Date.now() - startedAt) / 1000)
+    remainingSeconds.value = Math.max(totalSeconds.value - elapsed, 0)
+    if (remainingSeconds.value <= 0) stopTimer()
+  }
+
+  function open(status: QualityOwnerStatus, action: AgreementAction) {
+    stopTimer()
+    totalSeconds.value = Math.max(15, Math.floor(Number(status.agreement_read_seconds || 15)))
+    remainingSeconds.value = totalSeconds.value
+    startedAt = Date.now()
+    accepted.value = false
+    pendingAction = action
+    visible.value = true
+    timer = setInterval(updateRemaining, 250)
+  }
+
+  function close() {
+    stopTimer()
+    visible.value = false
+    accepted.value = false
+    remainingSeconds.value = 0
+    pendingAction = null
+  }
+
+  async function confirm() {
+    if (!canConfirm.value) return false
+    const action = pendingAction
+    close()
+    await action?.()
+    return true
+  }
+
+  if (getCurrentInstance()) {
+    onUnmounted(stopTimer)
+  }
+
+  return {
+    visible,
+    accepted,
+    remainingSeconds,
+    totalSeconds,
+    canConfirm,
+    open,
+    close,
+    confirm,
+  }
+}