Merge pull request 'feat(finance): 财务概览页面模块 1:1 还原' (#8) from feature/finance-overview-1to1 into main

feat(@vben/web-antd): implement finance business report module

.gitea/workflows/deploy.yml

@@ -0,0 +1,71 @@
+name: Build and Deploy TenantUI
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    runs-on: host
+    steps:
+      - name: Checkout code
+        run: |
+          set -e
+          cd /opt/deploy/tenantui || mkdir -p /opt/deploy/tenantui
+          cd /opt/deploy/tenantui
+
+          # 如果已有仓库就 pull，否则 clone
+          if [ -d ".git" ]; then
+            git fetch origin main
+            git reset --hard origin/main
+            git clean -fd
+          else
+            git clone --branch main ssh://git@git.laosankeji.com:2222/msumshk/TakeoutSaaS.TenantUI.git .
+          fi
+
+      - name: Build on host
+        run: |
+          set -e
+          cd /opt/deploy/tenantui
+
+          # 1. 保证 pnpm 可用（兼容没有 corepack 的 runner）
+          if ! command -v pnpm >/dev/null 2>&1; then
+            if command -v corepack >/dev/null 2>&1; then
+              corepack enable
+              corepack prepare pnpm@10.28.2 --activate
+            elif command -v npm >/dev/null 2>&1; then
+              npm install -g pnpm@10.28.2
+            else
+              echo "ERROR: corepack/npm 均不可用，请在 runner 安装 Node.js 20+"
+              exit 1
+            fi
+          fi
+
+          pnpm --version
+          pnpm install --frozen-lockfile
+          VITE_GLOB_API_URL=https://api-tenant-dev.laosankeji.com/api/tenant/v1 pnpm exec turbo run build --filter=@vben/web-antd...
+
+          rm -rf publish/web-antd-dist
+          mkdir -p publish
+          cp -r apps/web-antd/dist publish/web-antd-dist
+
+      - name: Build Docker image
+        run: |
+          set -e
+          cd /opt/deploy/tenantui
+          docker build -t takeoutsaas-tenantui:latest -f scripts/deploy/Dockerfile.runtime .
+
+      - name: Deploy container
+        run: |
+          docker stop tenantui || true
+          docker rm tenantui || true
+          docker run -d \
+            --name tenantui \
+            --restart unless-stopped \
+            -p 8010:8080 \
+            takeoutsaas-tenantui:latest
+
+      - name: Clean up old images
+        run: |
+          docker image prune -f

.gitignore

@@ -50,3 +50,6 @@ vite.config.ts.*
 *.sw?
 .history
 .cursor
+
+# Prototype backup files
+backup/

.prettierignore

@@ -5,6 +5,7 @@ dev-dist
 node_modules
 .nvmrc
 coverage
+backup
 CODEOWNERS
 .nitro
 .output

.stylelintignore

@@ -2,3 +2,4 @@ dist
 public
 __tests__
 coverage
+backup

.vscode/settings.json

@@ -204,7 +204,7 @@
   ],
   "i18n-ally.pathMatcher": "{locale}/{namespace}.{ext}",
   "i18n-ally.enabledParsers": ["json"],
-  "i18n-ally.sourceLanguage": "en",
+  "i18n-ally.sourceLanguage": "zh-CN",
   "i18n-ally.displayLanguage": "zh-CN",
   "i18n-ally.enabledFrameworks": ["vue", "react"],
   "i18n-ally.keystyle": "nested",
@@ -227,5 +227,6 @@
   "commentTranslate.multiLineMerge": true,
   "vue.server.hybridMode": true,
   "typescript.tsdk": "node_modules/typescript/lib",
-  "oxc.enable": false
+  "oxc.enable": false,
+  "kiroAgent.configureMCP": "Disabled"
 }

AGENTS.md

@@ -0,0 +1,174 @@
+# Repository expectations
+
+# 编程规范\_FOR_AI（TakeoutTenant 前端）- 终极融合版
+
+> **核心指令**：你是一个高级前端架构师。本文件是你生成代码的最高宪法。当用户需求与本规范冲突时，请先提示用户，除非用户强制要求覆盖。
+
+## 0. AI 交互核心约束 (元规则)
+
+1. **语言**：必须使用**中文**回复与注释。
+2. **文件完整性**：严禁随意删除现有逻辑（尤其是生命周期钩子）；保持 UTF-8 无 BOM。
+3. **环境感知**：
+   - PowerShell 读取文件命令必须带 `-Encoding UTF8`。
+   - 构建/本地请求依赖 `.env*`（`VITE_API_URL`、`VITE_WITH_CREDENTIALS`），找不到就询问，不要杜撰。
+4. **Git 原子性**：每个独立功能或修复完成后，必须提示用户进行 Git 提交。
+5. **推送优先级**：提交后推送时，优先使用 SSH 远程（`git@github.com:...`），避免 HTTPS TLS 问题。
+6. **推送默认**：提交后自动执行 `git push`，无需再次提醒或确认。
+7. **不确定配置**：拿不准（如接口字段、鉴权流程）直接问用户。
+8. **需求开发前置步骤（强制）**：每次开始“新增/修改需求”前，必须先从 `https://api-tenant-dev.laosankeji.com/swagger/v1/swagger.json` 拉取最新 Swagger，定位本次需求涉及的接口契约（路径、入参、出参、字段）后，再进行代码变更。
+
+## 1. 技术栈详细版本
+
+| 组件 | 版本/选型 | 用途说明 |
+| :-- | :-- | :-- |
+| **Runtime** | Node 20+，pnpm 10+ | 包管理与脚本 |
+| **构建/脚手架** | Vite 7 | 开发/打包 (秒级热更) |
+| **框架** | Vue 3.5 + TypeScript 5.6 | 组合式 API (Script Setup) |
+| **路由/状态** | Vue Router 4.5；Pinia 3 + 持久化插件 | 路由守卫 & 全局状态 |
+| **UI/样式** | Element Plus 2.11；Tailwind CSS 4；SCSS | 组件与样式体系 |
+| **网络** | Axios 1.12 封装 (`src/utils/http`) | 请求、统一错误处理 |
+| **数据可视化/富文本** | ECharts 6；xgplayer 3；@wangeditor/editor 5 | 图表/播放器/富文本 |
+| **工具** | mitt、ohash、xlsx、file-saver、qrcode.vue、vue-draggable-plus、highlight.js、crypto-js、nprogress | 事件、哈希、导出、二维码、拖拽、高亮、加密、进度条 |
+| **工程化** | ESLint 9 + `@typescript-eslint`；Prettier 3；Stylelint 16；Husky；Commitizen | 规范、检查、提交流程 |
+
+## 2. 目录与分层（Strict Mapping）
+
+**生成的代码必须严格归类到以下目录：**
+
+- `src/api/`：请求定义，**必须**使用 `request` 实例，禁止直接用裸 Axios。
+- `src/components/`：**全局通用** UI 组件 (`PascalCase.vue`)，禁止包含特定业务耦合。
+- `src/config/`：全局配置、常量（如主题、布局）。
+- `src/directives/`：自定义指令，按功能拆文件。
+- `src/enums/`：业务枚举常量（如 `OrderStatus.ts`）。
+- `src/hooks/`：可复用的组合式函数，命名 `useXxx.ts`。
+- `src/locales/`：多语言资源，新增文案必须**同步补齐**各语言。
+- `src/mock/`：本地 mock 数据/接口。
+- `src/plugins/`：Vue 插件注册。
+- `src/router/`：路由表与守卫，**鉴权逻辑放守卫中**，页面勿重复判断。
+- `src/store/`：Pinia store，模块化放 `modules/`。
+- `src/types/`：公共类型定义（如 `types/common/response.ts`）。
+- `src/utils/`：工具库（HTTP 封装、`StorageKeyManager`、加密等）。
+- `src/views/`：页面级组件，按 `views/业务模块/页面.vue` 组织。
+
+## 3. 命名与代码风格
+
+- **文件命名**：组件 `PascalCase.vue`；Hooks `useCamelCase.ts`；工具 `camelCase.ts`；样式 `kebab-case.scss`。
+- **变量/函数**：`camelCase`；布尔变量强制加 `is/has/should` 前缀。
+- **常量/枚举**：`PascalCase` 或 `UPPER_SNAKE_CASE`。
+- **路径别名**：**严禁**使用 `../../` 穿越多层。必须使用 `#/*`、`@vben/*`、`@vben-core/*` 等别名。
+- **逻辑注释 (强制)**：代码逻辑块必须空行分隔，并加序号注释（1. 验证... 2. 请求...）。
+- **文件头注释 (强制)**：所有新增 `*.ts`/`*.vue`/`*.less`/`*.scss` 文件，必须包含“文件职责”注释，说明该文件负责的业务边界。
+- **关键函数注释 (强制)**：对外导出的函数、含分支校验/提交流程的核心函数，必须添加简短中文注释，至少说明输入意图与副作用（如会触发请求/刷新/消息提示）。
+- **重构注释保留 (强制)**：拆分文件时，必须把原有关键流程注释同步迁移，禁止出现“重构后逻辑完整但无注释”的情况。
+- **组件通信**：优先 `props/emit`，跨层用 `mitt` 或 store，**慎用** `provide/inject`。
+
+## 4. 接口与 HTTP 规范 (含 .NET 兼容)
+
+1. **封装入口**：必须使用 `src/utils/http` 的 `api` 对象，禁止裸 `axios`。
+2. **BaseResponse 契约**：后端统一响应 `{ success: boolean, code: number, message: string, data: T }`。错误展示优先用 `message`。
+3. **Snowflake ID 精度处理 (关键)**：
+   - 后端 `.NET` 的 `long` 类型传到前端会有精度丢失。
+   - **接收时**：确保后端 DTO 已序列化为 String。
+   - **发送时**：前端保持 String 传输，由后端反序列化。
+4. **401 处理**：拦截器已自动登出。不要在业务内重复处理 401 跳转。
+5. **参数处理**：POST/PUT 若传 `params` 封装层会自动转为 `data`。
+6. **跨域/凭证**：严格跟随 `.env` 中 `VITE_WITH_CREDENTIALS` 配置。
+
+## 5. 组件/页面开发规范
+
+- **组织**：页面放 `views/`，复用组件抽到 `components/`。
+- **脚本语法**：全线使用 `<script setup lang="ts">`，禁止 Options API。
+- **Vue 3.5 新特性**：使用 Props 解构 (`const { count = 0 } = defineProps<{...}>`)。
+- **表单交互**：使用 Element Plus 表单校验；避免直接操作 DOM。
+- **Loading**：所有修改类操作必须绑定 `loading` 状态。
+- **页面拆分（强制）**：当 `views/**/index.vue` 逻辑复杂或总行数超过 400 行时，必须拆分为：
+  - `composables/useXxxPage.ts`（业务状态、校验、提交流程）
+  - `components/*.vue`（抽屉、弹窗、复杂表单等子视图）
+  - `styles/index.less|scss`（页面样式）
+- **Composables 二级拆分（强制）**：当 `composables/useXxxPage.ts` 超过 300 行或同时承担 4 类以上职责（常量/转换/数据加载/提交动作）时，必须继续拆分为目录：
+  - `composables/xxx-page/constants.ts`（常量与配置）
+  - `composables/xxx-page/helpers.ts`（纯函数：格式化、校验、归一化）
+  - `composables/xxx-page/*-actions.ts`（按业务动作拆分：load/save/copy 等）
+  - `useXxxPage.ts` 仅保留状态编排与导出，不承载大段业务实现。
+- **样式二级拆分（强制）**：当 `styles/index.less|scss` 超过 150 行或包含 3 个以上视觉域（列表/表单/抽屉/弹窗/响应式）时，必须拆分为分片文件，`index.less|scss` 只做 `@import` 聚合。
+- **子组件单向数据流（强制）**：子组件禁止直接修改父级传入对象；必须通过 `emit` 或显式 `onSetXxx` 回调更新父级状态。
+- **职责边界**：子组件仅负责渲染与事件抛出；请求、数据归一化、持久化必须留在页面 composable。
+- **样式边界**：页面样式拆文件后，必须使用页面根类（如 `.page-hours`）作为作用域前缀，避免全局污染。
+
+## 6. 状态管理规范 (Pinia)
+
+- **定义**：Store 命名 `useXxxStore`，文件 `modules/xxx.ts`，使用 **Setup Store** 写法。
+- **持久化 (核心)**：
+  - 默认通过 `pinia-plugin-persistedstate`。
+  - **强制**：Storage Key **必须**由 `src/utils/StorageKeyManager` 生成，**严禁**硬编码字符串 Key。
+- **职责**：Store 保持纯逻辑，UI 只负责触发。
+
+## 7. 路由与导航守卫
+
+- **中心化鉴权**：动态路由加载、Token 校验、登出逻辑均在守卫中处理。
+- **回退机制**：401 登出后，守卫应记录 `redirect` 参数，登录后自动跳回。
+- **禁止硬跳**：禁止 `window.location`，统一用 router 实例。
+
+## 8. 类型与可维护性
+
+- **TypeScript 强制**：**严禁 Any**。接口/类型定义放 `types/` 或同级 `types.ts`。
+- **类型收窄**：必要时使用 `unknown` + 类型断言/守卫。
+- **API 类型**：请求必须泛型声明返回类型 `api.get<UserDto>(...)`。
+- **导入**：优先使用 `import type`。
+
+## 9. 国际化与文案
+
+- **全量覆盖**：所有可见文本走 `$t('key')`。
+- **同步维护**：新增 Key 时，必须同时更新 `zh-CN` 和 `en` (或其他语言) 文件。
+- **动态优先**：确认错误/成功提示复用后端返回 `message` 优先。
+
+## 10. 样式与设计约束 (Tailwind First)
+
+- **优先级**：
+  1. **Tailwind CSS 4** (原子类) —— **首选**。
+  2. Element Plus 变量 (`var(--el-color-primary)`)。
+  3. Scoped SCSS (仅用于复杂定制)。
+- **主题配置**：禁止硬编码 HEX 色值，必须引用 `config` 或 CSS 变量。
+- **布局安全**：禁止内联 `style` 操作布局。
+
+## 11. 工程化与脚本
+
+- **常用脚本**：`pnpm dev:ele`、`pnpm build:ele`、`pnpm lint`、`pnpm commit`。
+- **Lint 要求**：每次修改代码后必须执行 `pnpm lint`，确保无错误和警告。
+- **提交规范**：Husky/Lefthook + lint-staged 已启用。
+- **Commitizen**：提交信息必须遵循 Conventional Commits，格式为 `<type>: <中文说明>`（类型英文，说明中文）。
+
+## 12. 性能与可用性
+
+- **虚拟滚动**：长列表（>100条）使用 `vue-draggable-plus` 或 Virtual Table。
+- **按需加载**：路由组件使用 `() => import(...)`；ECharts 按需引入。
+- **资源优化**：导出/加密等计算密集型任务，若卡顿则考虑 Web Worker。
+- **反馈**：长链路操作补充进度条 (`nprogress`) 或 Loading。
+
+## 13. 安全与合规
+
+- **零信任**：前端**严禁**硬编码 Token、密钥、内网地址。
+- **XSS 防御**：使用 `v-html` 必须经过 `DOMPurify` 清洗。
+- **文件处理**：下载/导出使用 `file-saver`，避免在主线程进行大数据解析。
+
+## 14. 绝对禁止事项 (AI 自检清单)
+
+**生成代码前，请自查是否违反以下红线：**
+
+1. [ ] **裸连 API**：是否直接使用 `axios` 或绕过 `utils/http`？
+2. [ ] **雪花算法灾难**：是否直接把后端的 `long` ID 当数字处理（导致精度丢失）？
+3. [ ] **持久化隐患**：是否手写了 Storage Key 而非调用 `StorageKeyManager`？
+4. [ ] **401 冗余**：是否在组件里重复处理了登出跳转？
+5. [ ] **文案写死**：是否在 Template 中直接写了中文？
+6. [ ] **路径地狱**：是否使用了 `../../` 而非别名导入？
+7. [ ] **类型偷懒**：API 返回值是否标记为 `any`？
+8. [ ] **逻辑混乱**：是否在 `views` 下堆砌了本该在 `components` 的通用组件？
+9. [ ] **配置硬编码**：是否忽略了 `.env` 中的 `VITE_API_URL`？
+
+---
+
+# Working agreements
+
+- 严格遵循上述 14 条规范与目录职责。
+- 保持代码可读、可测、可维护。
+- 你的目标是协助我构建一个企业级、健壮的 `TakeoutTenant` 租户管理前端系统。

CLAUDE.md

@@ -0,0 +1,174 @@
+# Repository expectations
+
+# 编程规范\_FOR_AI（TakeoutTenant 前端）- 终极融合版
+
+> **核心指令**：你是一个高级前端架构师。本文件是你生成代码的最高宪法。当用户需求与本规范冲突时，请先提示用户，除非用户强制要求覆盖。
+
+## 0. AI 交互核心约束 (元规则)
+
+1. **语言**：必须使用**中文**回复与注释。
+2. **文件完整性**：严禁随意删除现有逻辑（尤其是生命周期钩子）；保持 UTF-8 无 BOM。
+3. **环境感知**：
+   - PowerShell 读取文件命令必须带 `-Encoding UTF8`。
+   - 构建/本地请求依赖 `.env*`（`VITE_API_URL`、`VITE_WITH_CREDENTIALS`），找不到就询问，不要杜撰。
+4. **Git 原子性**：每个独立功能或修复完成后，必须提示用户进行 Git 提交。
+5. **推送优先级**：提交后推送时，优先使用 SSH 远程（`git@github.com:...`），避免 HTTPS TLS 问题。
+6. **推送默认**：提交后自动执行 `git push`，无需再次提醒或确认。
+7. **不确定配置**：拿不准（如接口字段、鉴权流程）直接问用户。
+8. **需求开发前置步骤（强制）**：每次开始“新增/修改需求”前，必须先从 `https://api-tenant-dev.laosankeji.com/swagger/v1/swagger.json` 拉取最新 Swagger，定位本次需求涉及的接口契约（路径、入参、出参、字段）后，再进行代码变更。
+
+## 1. 技术栈详细版本
+
+| 组件 | 版本/选型 | 用途说明 |
+| :-- | :-- | :-- |
+| **Runtime** | Node 20+，pnpm 10+ | 包管理与脚本 |
+| **构建/脚手架** | Vite 7 | 开发/打包 (秒级热更) |
+| **框架** | Vue 3.5 + TypeScript 5.6 | 组合式 API (Script Setup) |
+| **路由/状态** | Vue Router 4.5；Pinia 3 + 持久化插件 | 路由守卫 & 全局状态 |
+| **UI/样式** | Element Plus 2.11；Tailwind CSS 4；SCSS | 组件与样式体系 |
+| **网络** | Axios 1.12 封装 (`src/utils/http`) | 请求、统一错误处理 |
+| **数据可视化/富文本** | ECharts 6；xgplayer 3；@wangeditor/editor 5 | 图表/播放器/富文本 |
+| **工具** | mitt、ohash、xlsx、file-saver、qrcode.vue、vue-draggable-plus、highlight.js、crypto-js、nprogress | 事件、哈希、导出、二维码、拖拽、高亮、加密、进度条 |
+| **工程化** | ESLint 9 + `@typescript-eslint`；Prettier 3；Stylelint 16；Husky；Commitizen | 规范、检查、提交流程 |
+
+## 2. 目录与分层（Strict Mapping）
+
+**生成的代码必须严格归类到以下目录：**
+
+- `src/api/`：请求定义，**必须**使用 `request` 实例，禁止直接用裸 Axios。
+- `src/components/`：**全局通用** UI 组件 (`PascalCase.vue`)，禁止包含特定业务耦合。
+- `src/config/`：全局配置、常量（如主题、布局）。
+- `src/directives/`：自定义指令，按功能拆文件。
+- `src/enums/`：业务枚举常量（如 `OrderStatus.ts`）。
+- `src/hooks/`：可复用的组合式函数，命名 `useXxx.ts`。
+- `src/locales/`：多语言资源，新增文案必须**同步补齐**各语言。
+- `src/mock/`：本地 mock 数据/接口。
+- `src/plugins/`：Vue 插件注册。
+- `src/router/`：路由表与守卫，**鉴权逻辑放守卫中**，页面勿重复判断。
+- `src/store/`：Pinia store，模块化放 `modules/`。
+- `src/types/`：公共类型定义（如 `types/common/response.ts`）。
+- `src/utils/`：工具库（HTTP 封装、`StorageKeyManager`、加密等）。
+- `src/views/`：页面级组件，按 `views/业务模块/页面.vue` 组织。
+
+## 3. 命名与代码风格
+
+- **文件命名**：组件 `PascalCase.vue`；Hooks `useCamelCase.ts`；工具 `camelCase.ts`；样式 `kebab-case.scss`。
+- **变量/函数**：`camelCase`；布尔变量强制加 `is/has/should` 前缀。
+- **常量/枚举**：`PascalCase` 或 `UPPER_SNAKE_CASE`。
+- **路径别名**：**严禁**使用 `../../` 穿越多层。必须使用 `#/*`、`@vben/*`、`@vben-core/*` 等别名。
+- **逻辑注释 (强制)**：代码逻辑块必须空行分隔，并加序号注释（1. 验证... 2. 请求...）。
+- **文件头注释 (强制)**：所有新增 `*.ts`/`*.vue`/`*.less`/`*.scss` 文件，必须包含“文件职责”注释，说明该文件负责的业务边界。
+- **关键函数注释 (强制)**：对外导出的函数、含分支校验/提交流程的核心函数，必须添加简短中文注释，至少说明输入意图与副作用（如会触发请求/刷新/消息提示）。
+- **重构注释保留 (强制)**：拆分文件时，必须把原有关键流程注释同步迁移，禁止出现“重构后逻辑完整但无注释”的情况。
+- **组件通信**：优先 `props/emit`，跨层用 `mitt` 或 store，**慎用** `provide/inject`。
+
+## 4. 接口与 HTTP 规范 (含 .NET 兼容)
+
+1. **封装入口**：必须使用 `src/utils/http` 的 `api` 对象，禁止裸 `axios`。
+2. **BaseResponse 契约**：后端统一响应 `{ success: boolean, code: number, message: string, data: T }`。错误展示优先用 `message`。
+3. **Snowflake ID 精度处理 (关键)**：
+   - 后端 `.NET` 的 `long` 类型传到前端会有精度丢失。
+   - **接收时**：确保后端 DTO 已序列化为 String。
+   - **发送时**：前端保持 String 传输，由后端反序列化。
+4. **401 处理**：拦截器已自动登出。不要在业务内重复处理 401 跳转。
+5. **参数处理**：POST/PUT 若传 `params` 封装层会自动转为 `data`。
+6. **跨域/凭证**：严格跟随 `.env` 中 `VITE_WITH_CREDENTIALS` 配置。
+
+## 5. 组件/页面开发规范
+
+- **组织**：页面放 `views/`，复用组件抽到 `components/`。
+- **脚本语法**：全线使用 `<script setup lang="ts">`，禁止 Options API。
+- **Vue 3.5 新特性**：使用 Props 解构 (`const { count = 0 } = defineProps<{...}>`)。
+- **表单交互**：使用 Element Plus 表单校验；避免直接操作 DOM。
+- **Loading**：所有修改类操作必须绑定 `loading` 状态。
+- **页面拆分（强制）**：当 `views/**/index.vue` 逻辑复杂或总行数超过 400 行时，必须拆分为：
+  - `composables/useXxxPage.ts`（业务状态、校验、提交流程）
+  - `components/*.vue`（抽屉、弹窗、复杂表单等子视图）
+  - `styles/index.less|scss`（页面样式）
+- **Composables 二级拆分（强制）**：当 `composables/useXxxPage.ts` 超过 300 行或同时承担 4 类以上职责（常量/转换/数据加载/提交动作）时，必须继续拆分为目录：
+  - `composables/xxx-page/constants.ts`（常量与配置）
+  - `composables/xxx-page/helpers.ts`（纯函数：格式化、校验、归一化）
+  - `composables/xxx-page/*-actions.ts`（按业务动作拆分：load/save/copy 等）
+  - `useXxxPage.ts` 仅保留状态编排与导出，不承载大段业务实现。
+- **样式二级拆分（强制）**：当 `styles/index.less|scss` 超过 150 行或包含 3 个以上视觉域（列表/表单/抽屉/弹窗/响应式）时，必须拆分为分片文件，`index.less|scss` 只做 `@import` 聚合。
+- **子组件单向数据流（强制）**：子组件禁止直接修改父级传入对象；必须通过 `emit` 或显式 `onSetXxx` 回调更新父级状态。
+- **职责边界**：子组件仅负责渲染与事件抛出；请求、数据归一化、持久化必须留在页面 composable。
+- **样式边界**：页面样式拆文件后，必须使用页面根类（如 `.page-hours`）作为作用域前缀，避免全局污染。
+
+## 6. 状态管理规范 (Pinia)
+
+- **定义**：Store 命名 `useXxxStore`，文件 `modules/xxx.ts`，使用 **Setup Store** 写法。
+- **持久化 (核心)**：
+  - 默认通过 `pinia-plugin-persistedstate`。
+  - **强制**：Storage Key **必须**由 `src/utils/StorageKeyManager` 生成，**严禁**硬编码字符串 Key。
+- **职责**：Store 保持纯逻辑，UI 只负责触发。
+
+## 7. 路由与导航守卫
+
+- **中心化鉴权**：动态路由加载、Token 校验、登出逻辑均在守卫中处理。
+- **回退机制**：401 登出后，守卫应记录 `redirect` 参数，登录后自动跳回。
+- **禁止硬跳**：禁止 `window.location`，统一用 router 实例。
+
+## 8. 类型与可维护性
+
+- **TypeScript 强制**：**严禁 Any**。接口/类型定义放 `types/` 或同级 `types.ts`。
+- **类型收窄**：必要时使用 `unknown` + 类型断言/守卫。
+- **API 类型**：请求必须泛型声明返回类型 `api.get<UserDto>(...)`。
+- **导入**：优先使用 `import type`。
+
+## 9. 国际化与文案
+
+- **全量覆盖**：所有可见文本走 `$t('key')`。
+- **同步维护**：新增 Key 时，必须同时更新 `zh-CN` 和 `en` (或其他语言) 文件。
+- **动态优先**：确认错误/成功提示复用后端返回 `message` 优先。
+
+## 10. 样式与设计约束 (Tailwind First)
+
+- **优先级**：
+  1. **Tailwind CSS 4** (原子类) —— **首选**。
+  2. Element Plus 变量 (`var(--el-color-primary)`)。
+  3. Scoped SCSS (仅用于复杂定制)。
+- **主题配置**：禁止硬编码 HEX 色值，必须引用 `config` 或 CSS 变量。
+- **布局安全**：禁止内联 `style` 操作布局。
+
+## 11. 工程化与脚本
+
+- **常用脚本**：`pnpm dev:ele`、`pnpm build:ele`、`pnpm lint`、`pnpm commit`。
+- **Lint 要求**：每次修改代码后必须执行 `pnpm lint`，确保无错误和警告。
+- **提交规范**：Husky/Lefthook + lint-staged 已启用。
+- **Commitizen**：提交信息必须遵循 Conventional Commits，格式为 `<type>: <中文说明>`（类型英文，说明中文）。
+
+## 12. 性能与可用性
+
+- **虚拟滚动**：长列表（>100条）使用 `vue-draggable-plus` 或 Virtual Table。
+- **按需加载**：路由组件使用 `() => import(...)`；ECharts 按需引入。
+- **资源优化**：导出/加密等计算密集型任务，若卡顿则考虑 Web Worker。
+- **反馈**：长链路操作补充进度条 (`nprogress`) 或 Loading。
+
+## 13. 安全与合规
+
+- **零信任**：前端**严禁**硬编码 Token、密钥、内网地址。
+- **XSS 防御**：使用 `v-html` 必须经过 `DOMPurify` 清洗。
+- **文件处理**：下载/导出使用 `file-saver`，避免在主线程进行大数据解析。
+
+## 14. 绝对禁止事项 (AI 自检清单)
+
+**生成代码前，请自查是否违反以下红线：**
+
+1. [ ] **裸连 API**：是否直接使用 `axios` 或绕过 `utils/http`？
+2. [ ] **雪花算法灾难**：是否直接把后端的 `long` ID 当数字处理（导致精度丢失）？
+3. [ ] **持久化隐患**：是否手写了 Storage Key 而非调用 `StorageKeyManager`？
+4. [ ] **401 冗余**：是否在组件里重复处理了登出跳转？
+5. [ ] **文案写死**：是否在 Template 中直接写了中文？
+6. [ ] **路径地狱**：是否使用了 `../../` 而非别名导入？
+7. [ ] **类型偷懒**：API 返回值是否标记为 `any`？
+8. [ ] **逻辑混乱**：是否在 `views` 下堆砌了本该在 `components` 的通用组件？
+9. [ ] **配置硬编码**：是否忽略了 `.env` 中的 `VITE_API_URL`？
+
+---
+
+# Working agreements
+
+- 严格遵循上述 14 条规范与目录职责。
+- 保持代码可读、可测、可维护。
+- 你的目标是协助我构建一个企业级、健壮的 `TakeoutTenant` 租户管理前端系统。

README.TAKEOUT.md

@@ -28,4 +28,3 @@ pnpm dev:ele
 
 - 配置文件：`TakeoutSaaS.TenantUI/apps/web-ele/vite.config.mts`
 - 后端需暴露形如：`/api/admin/v1/...` 的接口
-

apps/backend-mock/.env

@@ -1,3 +0,0 @@
-PORT=5320
-ACCESS_TOKEN_SECRET=access_token_secret
-REFRESH_TOKEN_SECRET=refresh_token_secret

apps/backend-mock/README.md

@@ -1,15 +0,0 @@
-# @vben/backend-mock
-
-## Description
-
-Vben Admin 数据 mock 服务，没有对接任何的数据库，所有数据都是模拟的，用于前端开发时提供数据支持。线上环境不再提供 mock 集成，可自行部署服务或者对接真实数据，由于 `mock.js` 等工具有一些限制，比如上传文件不行、无法模拟复杂的逻辑等，所以这里使用了真实的后端服务来实现。唯一麻烦的是本地需要同时启动后端服务和前端服务，但是这样可以更好的模拟真实环境。该服务不需要手动启动，已经集成在 vite 插件内，随应用一起启用。
-
-## Running the app
-
-```bash
-# development
-$ pnpm run start
-
-# production mode
-$ pnpm run build
-```

apps/backend-mock/api/auth/codes.ts

@@ -1,16 +0,0 @@
-import { eventHandler } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { MOCK_CODES } from '~/utils/mock-data';
-import { unAuthorizedResponse, useResponseSuccess } from '~/utils/response';
-
-export default eventHandler((event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-
-  const codes =
-    MOCK_CODES.find((item) => item.username === userinfo.username)?.codes ?? [];
-
-  return useResponseSuccess(codes);
-});

apps/backend-mock/api/auth/login.post.ts

@@ -1,42 +0,0 @@
-import { defineEventHandler, readBody, setResponseStatus } from 'h3';
-import {
-  clearRefreshTokenCookie,
-  setRefreshTokenCookie,
-} from '~/utils/cookie-utils';
-import { generateAccessToken, generateRefreshToken } from '~/utils/jwt-utils';
-import { MOCK_USERS } from '~/utils/mock-data';
-import {
-  forbiddenResponse,
-  useResponseError,
-  useResponseSuccess,
-} from '~/utils/response';
-
-export default defineEventHandler(async (event) => {
-  const { password, username } = await readBody(event);
-  if (!password || !username) {
-    setResponseStatus(event, 400);
-    return useResponseError(
-      'BadRequestException',
-      'Username and password are required',
-    );
-  }
-
-  const findUser = MOCK_USERS.find(
-    (item) => item.username === username && item.password === password,
-  );
-
-  if (!findUser) {
-    clearRefreshTokenCookie(event);
-    return forbiddenResponse(event, 'Username or password is incorrect.');
-  }
-
-  const accessToken = generateAccessToken(findUser);
-  const refreshToken = generateRefreshToken(findUser);
-
-  setRefreshTokenCookie(event, refreshToken);
-
-  return useResponseSuccess({
-    ...findUser,
-    accessToken,
-  });
-});

apps/backend-mock/api/auth/logout.post.ts

@@ -1,17 +0,0 @@
-import { defineEventHandler } from 'h3';
-import {
-  clearRefreshTokenCookie,
-  getRefreshTokenFromCookie,
-} from '~/utils/cookie-utils';
-import { useResponseSuccess } from '~/utils/response';
-
-export default defineEventHandler(async (event) => {
-  const refreshToken = getRefreshTokenFromCookie(event);
-  if (!refreshToken) {
-    return useResponseSuccess('');
-  }
-
-  clearRefreshTokenCookie(event);
-
-  return useResponseSuccess('');
-});

apps/backend-mock/api/auth/refresh.post.ts

@@ -1,35 +0,0 @@
-import { defineEventHandler } from 'h3';
-import {
-  clearRefreshTokenCookie,
-  getRefreshTokenFromCookie,
-  setRefreshTokenCookie,
-} from '~/utils/cookie-utils';
-import { generateAccessToken, verifyRefreshToken } from '~/utils/jwt-utils';
-import { MOCK_USERS } from '~/utils/mock-data';
-import { forbiddenResponse } from '~/utils/response';
-
-export default defineEventHandler(async (event) => {
-  const refreshToken = getRefreshTokenFromCookie(event);
-  if (!refreshToken) {
-    return forbiddenResponse(event);
-  }
-
-  clearRefreshTokenCookie(event);
-
-  const userinfo = verifyRefreshToken(refreshToken);
-  if (!userinfo) {
-    return forbiddenResponse(event);
-  }
-
-  const findUser = MOCK_USERS.find(
-    (item) => item.username === userinfo.username,
-  );
-  if (!findUser) {
-    return forbiddenResponse(event);
-  }
-  const accessToken = generateAccessToken(findUser);
-
-  setRefreshTokenCookie(event, refreshToken);
-
-  return accessToken;
-});

apps/backend-mock/api/demo/bigint.ts

@@ -1,32 +0,0 @@
-import { eventHandler, setHeader } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { unAuthorizedResponse } from '~/utils/response';
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-  const data = `
-  {
-    "code": 0,
-    "message": "success",
-    "data": [
-              {
-                "id": 123456789012345678901234567890123456789012345678901234567890,
-                "name": "John Doe",
-                "age": 30,
-                "email": "john-doe@demo.com"
-                },
-                {
-                "id": 987654321098765432109876543210987654321098765432109876543210,
-                "name": "Jane Smith",
-                "age": 25,
-                "email": "jane@demo.com"
-                }
-            ]
-  }
-  `;
-  setHeader(event, 'Content-Type', 'application/json');
-  return data;
-});

apps/backend-mock/api/menu/all.ts

@@ -1,15 +0,0 @@
-import { eventHandler } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { MOCK_MENUS } from '~/utils/mock-data';
-import { unAuthorizedResponse, useResponseSuccess } from '~/utils/response';
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-
-  const menus =
-    MOCK_MENUS.find((item) => item.username === userinfo.username)?.menus ?? [];
-  return useResponseSuccess(menus);
-});

apps/backend-mock/api/status.ts

@@ -1,8 +0,0 @@
-import { eventHandler, getQuery, setResponseStatus } from 'h3';
-import { useResponseError } from '~/utils/response';
-
-export default eventHandler((event) => {
-  const { status } = getQuery(event);
-  setResponseStatus(event, Number(status));
-  return useResponseError(`${status}`);
-});

apps/backend-mock/api/system/dept/.post.ts

@@ -1,16 +0,0 @@
-import { eventHandler } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import {
-  sleep,
-  unAuthorizedResponse,
-  useResponseSuccess,
-} from '~/utils/response';
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-  await sleep(600);
-  return useResponseSuccess(null);
-});

apps/backend-mock/api/system/dept/[id].delete.ts

@@ -1,16 +0,0 @@
-import { eventHandler } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import {
-  sleep,
-  unAuthorizedResponse,
-  useResponseSuccess,
-} from '~/utils/response';
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-  await sleep(1000);
-  return useResponseSuccess(null);
-});

apps/backend-mock/api/system/dept/[id].put.ts

@@ -1,16 +0,0 @@
-import { eventHandler } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import {
-  sleep,
-  unAuthorizedResponse,
-  useResponseSuccess,
-} from '~/utils/response';
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-  await sleep(2000);
-  return useResponseSuccess(null);
-});

apps/backend-mock/api/system/dept/list.ts

@@ -1,62 +0,0 @@
-import { faker } from '@faker-js/faker';
-import { eventHandler } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { unAuthorizedResponse, useResponseSuccess } from '~/utils/response';
-
-const formatterCN = new Intl.DateTimeFormat('zh-CN', {
-  timeZone: 'Asia/Shanghai',
-  year: 'numeric',
-  month: '2-digit',
-  day: '2-digit',
-  hour: '2-digit',
-  minute: '2-digit',
-  second: '2-digit',
-});
-
-function generateMockDataList(count: number) {
-  const dataList = [];
-
-  for (let i = 0; i < count; i++) {
-    const dataItem: Record<string, any> = {
-      id: faker.string.uuid(),
-      pid: 0,
-      name: faker.commerce.department(),
-      status: faker.helpers.arrayElement([0, 1]),
-      createTime: formatterCN.format(
-        faker.date.between({ from: '2021-01-01', to: '2022-12-31' }),
-      ),
-      remark: faker.lorem.sentence(),
-    };
-    if (faker.datatype.boolean()) {
-      dataItem.children = Array.from(
-        { length: faker.number.int({ min: 1, max: 5 }) },
-        () => ({
-          id: faker.string.uuid(),
-          pid: dataItem.id,
-          name: faker.commerce.department(),
-          status: faker.helpers.arrayElement([0, 1]),
-          createTime: formatterCN.format(
-            faker.date.between({ from: '2023-01-01', to: '2023-12-31' }),
-          ),
-          remark: faker.lorem.sentence(),
-        }),
-      );
-    }
-    dataList.push(dataItem);
-  }
-
-  return dataList;
-}
-
-const mockData = generateMockDataList(10);
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-
-  const listData = structuredClone(mockData);
-
-  return useResponseSuccess(listData);
-});

apps/backend-mock/api/system/menu/list.ts

@@ -1,13 +0,0 @@
-import { eventHandler } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { MOCK_MENU_LIST } from '~/utils/mock-data';
-import { unAuthorizedResponse, useResponseSuccess } from '~/utils/response';
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-
-  return useResponseSuccess(MOCK_MENU_LIST);
-});

apps/backend-mock/api/system/menu/name-exists.ts

@@ -1,29 +0,0 @@
-import { eventHandler, getQuery } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { MOCK_MENU_LIST } from '~/utils/mock-data';
-import { unAuthorizedResponse, useResponseSuccess } from '~/utils/response';
-
-const namesMap: Record<string, any> = {};
-
-function getNames(menus: any[]) {
-  menus.forEach((menu) => {
-    namesMap[menu.name] = String(menu.id);
-    if (menu.children) {
-      getNames(menu.children);
-    }
-  });
-}
-getNames(MOCK_MENU_LIST);
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-  const { id, name } = getQuery(event);
-
-  return (name as string) in namesMap &&
-    (!id || namesMap[name as string] !== String(id))
-    ? useResponseSuccess(true)
-    : useResponseSuccess(false);
-});

apps/backend-mock/api/system/menu/path-exists.ts

@@ -1,29 +0,0 @@
-import { eventHandler, getQuery } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { MOCK_MENU_LIST } from '~/utils/mock-data';
-import { unAuthorizedResponse, useResponseSuccess } from '~/utils/response';
-
-const pathMap: Record<string, any> = { '/': 0 };
-
-function getPaths(menus: any[]) {
-  menus.forEach((menu) => {
-    pathMap[menu.path] = String(menu.id);
-    if (menu.children) {
-      getPaths(menu.children);
-    }
-  });
-}
-getPaths(MOCK_MENU_LIST);
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-  const { id, path } = getQuery(event);
-
-  return (path as string) in pathMap &&
-    (!id || pathMap[path as string] !== String(id))
-    ? useResponseSuccess(true)
-    : useResponseSuccess(false);
-});

apps/backend-mock/api/system/role/list.ts

@@ -1,84 +0,0 @@
-import { faker } from '@faker-js/faker';
-import { eventHandler, getQuery } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { getMenuIds, MOCK_MENU_LIST } from '~/utils/mock-data';
-import { unAuthorizedResponse, usePageResponseSuccess } from '~/utils/response';
-
-const formatterCN = new Intl.DateTimeFormat('zh-CN', {
-  timeZone: 'Asia/Shanghai',
-  year: 'numeric',
-  month: '2-digit',
-  day: '2-digit',
-  hour: '2-digit',
-  minute: '2-digit',
-  second: '2-digit',
-});
-
-const menuIds = getMenuIds(MOCK_MENU_LIST);
-
-function generateMockDataList(count: number) {
-  const dataList = [];
-
-  for (let i = 0; i < count; i++) {
-    const dataItem: Record<string, any> = {
-      id: faker.string.uuid(),
-      name: faker.commerce.product(),
-      status: faker.helpers.arrayElement([0, 1]),
-      createTime: formatterCN.format(
-        faker.date.between({ from: '2022-01-01', to: '2025-01-01' }),
-      ),
-      permissions: faker.helpers.arrayElements(menuIds),
-      remark: faker.lorem.sentence(),
-    };
-
-    dataList.push(dataItem);
-  }
-
-  return dataList;
-}
-
-const mockData = generateMockDataList(100);
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-
-  const {
-    page = 1,
-    pageSize = 20,
-    name,
-    id,
-    remark,
-    startTime,
-    endTime,
-    status,
-  } = getQuery(event);
-  let listData = structuredClone(mockData);
-  if (name) {
-    listData = listData.filter((item) =>
-      item.name.toLowerCase().includes(String(name).toLowerCase()),
-    );
-  }
-  if (id) {
-    listData = listData.filter((item) =>
-      item.id.toLowerCase().includes(String(id).toLowerCase()),
-    );
-  }
-  if (remark) {
-    listData = listData.filter((item) =>
-      item.remark?.toLowerCase()?.includes(String(remark).toLowerCase()),
-    );
-  }
-  if (startTime) {
-    listData = listData.filter((item) => item.createTime >= startTime);
-  }
-  if (endTime) {
-    listData = listData.filter((item) => item.createTime <= endTime);
-  }
-  if (['0', '1'].includes(status as string)) {
-    listData = listData.filter((item) => item.status === Number(status));
-  }
-  return usePageResponseSuccess(page as string, pageSize as string, listData);
-});

apps/backend-mock/api/table/list.ts

@@ -1,117 +0,0 @@
-import { faker } from '@faker-js/faker';
-import { eventHandler, getQuery } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import {
-  sleep,
-  unAuthorizedResponse,
-  usePageResponseSuccess,
-} from '~/utils/response';
-
-function generateMockDataList(count: number) {
-  const dataList = [];
-
-  for (let i = 0; i < count; i++) {
-    const dataItem = {
-      id: faker.string.uuid(),
-      imageUrl: faker.image.avatar(),
-      imageUrl2: faker.image.avatar(),
-      open: faker.datatype.boolean(),
-      status: faker.helpers.arrayElement(['success', 'error', 'warning']),
-      productName: faker.commerce.productName(),
-      price: faker.commerce.price(),
-      currency: faker.finance.currencyCode(),
-      quantity: faker.number.int({ min: 1, max: 100 }),
-      available: faker.datatype.boolean(),
-      category: faker.commerce.department(),
-      releaseDate: faker.date.past(),
-      rating: faker.number.float({ min: 1, max: 5 }),
-      description: faker.commerce.productDescription(),
-      weight: faker.number.float({ min: 0.1, max: 10 }),
-      color: faker.color.human(),
-      inProduction: faker.datatype.boolean(),
-      tags: Array.from({ length: 3 }, () => faker.commerce.productAdjective()),
-    };
-
-    dataList.push(dataItem);
-  }
-
-  return dataList;
-}
-
-const mockData = generateMockDataList(100);
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-
-  await sleep(600);
-
-  const { page, pageSize, sortBy, sortOrder } = getQuery(event);
-  // 规范化分页参数，处理 string[]
-  const pageRaw = Array.isArray(page) ? page[0] : page;
-  const pageSizeRaw = Array.isArray(pageSize) ? pageSize[0] : pageSize;
-  const pageNumber = Math.max(
-    1,
-    Number.parseInt(String(pageRaw ?? '1'), 10) || 1,
-  );
-  const pageSizeNumber = Math.min(
-    100,
-    Math.max(1, Number.parseInt(String(pageSizeRaw ?? '10'), 10) || 10),
-  );
-  const listData = structuredClone(mockData);
-
-  // 规范化 query 入参，兼容 string[]
-  const sortKeyRaw = Array.isArray(sortBy) ? sortBy[0] : sortBy;
-  const sortOrderRaw = Array.isArray(sortOrder) ? sortOrder[0] : sortOrder;
-  // 检查 sortBy 是否是 listData 元素的合法属性键
-  if (
-    typeof sortKeyRaw === 'string' &&
-    listData[0] &&
-    Object.prototype.hasOwnProperty.call(listData[0], sortKeyRaw)
-  ) {
-    // 定义数组元素的类型
-    type ItemType = (typeof listData)[0];
-    const sortKey = sortKeyRaw as keyof ItemType; // 将 sortBy 断言为合法键
-    const isDesc = sortOrderRaw === 'desc';
-    listData.sort((a, b) => {
-      const aValue = a[sortKey] as unknown;
-      const bValue = b[sortKey] as unknown;
-
-      let result = 0;
-
-      if (typeof aValue === 'number' && typeof bValue === 'number') {
-        result = aValue - bValue;
-      } else if (aValue instanceof Date && bValue instanceof Date) {
-        result = aValue.getTime() - bValue.getTime();
-      } else if (typeof aValue === 'boolean' && typeof bValue === 'boolean') {
-        if (aValue === bValue) {
-          result = 0;
-        } else {
-          result = aValue ? 1 : -1;
-        }
-      } else {
-        const aStr = String(aValue);
-        const bStr = String(bValue);
-        const aNum = Number(aStr);
-        const bNum = Number(bStr);
-        result =
-          Number.isFinite(aNum) && Number.isFinite(bNum)
-            ? aNum - bNum
-            : aStr.localeCompare(bStr, undefined, {
-                numeric: true,
-                sensitivity: 'base',
-              });
-      }
-
-      return isDesc ? -result : result;
-    });
-  }
-
-  return usePageResponseSuccess(
-    String(pageNumber),
-    String(pageSizeNumber),
-    listData,
-  );
-});

apps/backend-mock/api/test.get.ts

@@ -1,3 +0,0 @@
-import { defineEventHandler } from 'h3';
-
-export default defineEventHandler(() => 'Test get handler');

apps/backend-mock/api/test.post.ts

@@ -1,3 +0,0 @@
-import { defineEventHandler } from 'h3';
-
-export default defineEventHandler(() => 'Test post handler');

apps/backend-mock/api/timezone/getTimezone.ts

@@ -1,12 +0,0 @@
-import { eventHandler } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { unAuthorizedResponse, useResponseSuccess } from '~/utils/response';
-import { getTimezone } from '~/utils/timezone-utils';
-
-export default eventHandler((event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-  return useResponseSuccess(getTimezone());
-});

apps/backend-mock/api/timezone/getTimezoneOptions.ts

@@ -1,11 +0,0 @@
-import { eventHandler } from 'h3';
-import { TIME_ZONE_OPTIONS } from '~/utils/mock-data';
-import { useResponseSuccess } from '~/utils/response';
-
-export default eventHandler(() => {
-  const data = TIME_ZONE_OPTIONS.map((o) => ({
-    label: `${o.timezone} (GMT${o.offset >= 0 ? `+${o.offset}` : o.offset})`,
-    value: o.timezone,
-  }));
-  return useResponseSuccess(data);
-});

apps/backend-mock/api/timezone/setTimezone.ts

@@ -1,22 +0,0 @@
-import { eventHandler, readBody } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { TIME_ZONE_OPTIONS } from '~/utils/mock-data';
-import { unAuthorizedResponse, useResponseSuccess } from '~/utils/response';
-import { setTimezone } from '~/utils/timezone-utils';
-
-export default eventHandler(async (event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-  const body = await readBody<{ timezone?: unknown }>(event);
-  const timezone =
-    typeof body?.timezone === 'string' ? body.timezone : undefined;
-  const allowed = TIME_ZONE_OPTIONS.some((o) => o.timezone === timezone);
-  if (!timezone || !allowed) {
-    setResponseStatus(event, 400);
-    return useResponseError('Bad Request', 'Invalid timezone');
-  }
-  setTimezone(timezone);
-  return useResponseSuccess({});
-});

apps/backend-mock/api/upload.ts

@@ -1,14 +0,0 @@
-import { eventHandler } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { unAuthorizedResponse, useResponseSuccess } from '~/utils/response';
-
-export default eventHandler((event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-  return useResponseSuccess({
-    url: 'https://unpkg.com/@vbenjs/static-source@0.1.7/source/logo-v1.webp',
-  });
-  // return useResponseError("test")
-});

apps/backend-mock/api/user/info.ts

@@ -1,11 +0,0 @@
-import { eventHandler } from 'h3';
-import { verifyAccessToken } from '~/utils/jwt-utils';
-import { unAuthorizedResponse, useResponseSuccess } from '~/utils/response';
-
-export default eventHandler((event) => {
-  const userinfo = verifyAccessToken(event);
-  if (!userinfo) {
-    return unAuthorizedResponse(event);
-  }
-  return useResponseSuccess(userinfo);
-});

apps/backend-mock/error.ts

@@ -1,7 +0,0 @@
-import type { NitroErrorHandler } from 'nitropack';
-
-const errorHandler: NitroErrorHandler = function (error, event) {
-  event.node.res.end(`[Error Handler] ${error.stack}`);
-};
-
-export default errorHandler;

apps/backend-mock/middleware/1.api.ts

@@ -1,20 +0,0 @@
-import { defineEventHandler } from 'h3';
-import { forbiddenResponse, sleep } from '~/utils/response';
-
-export default defineEventHandler(async (event) => {
-  event.node.res.setHeader(
-    'Access-Control-Allow-Origin',
-    event.headers.get('Origin') ?? '*',
-  );
-  if (event.method === 'OPTIONS') {
-    event.node.res.statusCode = 204;
-    event.node.res.statusMessage = 'No Content.';
-    return 'OK';
-  } else if (
-    ['DELETE', 'PATCH', 'POST', 'PUT'].includes(event.method) &&
-    event.path.startsWith('/api/system/')
-  ) {
-    await sleep(Math.floor(Math.random() * 2000));
-    return forbiddenResponse(event, '演示环境，禁止修改');
-  }
-});

apps/backend-mock/nitro.config.ts

@@ -1,20 +0,0 @@
-import errorHandler from './error';
-
-process.env.COMPATIBILITY_DATE = new Date().toISOString();
-export default defineNitroConfig({
-  devErrorHandler: errorHandler,
-  errorHandler: '~/error',
-  routeRules: {
-    '/api/**': {
-      cors: true,
-      headers: {
-        'Access-Control-Allow-Credentials': 'true',
-        'Access-Control-Allow-Headers':
-          'Accept, Authorization, Content-Length, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-CSRF-TOKEN, X-Requested-With',
-        'Access-Control-Allow-Methods': 'GET,HEAD,PUT,PATCH,POST,DELETE',
-        'Access-Control-Allow-Origin': '*',
-        'Access-Control-Expose-Headers': '*',
-      },
-    },
-  },
-});

apps/backend-mock/package.json

@@ -1,21 +0,0 @@
-{
-  "name": "@vben/backend-mock",
-  "version": "0.0.1",
-  "description": "",
-  "private": true,
-  "license": "MIT",
-  "author": "",
-  "scripts": {
-    "build": "nitro build",
-    "start": "nitro dev"
-  },
-  "dependencies": {
-    "@faker-js/faker": "catalog:",
-    "jsonwebtoken": "catalog:",
-    "nitropack": "catalog:"
-  },
-  "devDependencies": {
-    "@types/jsonwebtoken": "catalog:",
-    "h3": "catalog:"
-  }
-}

apps/backend-mock/routes/[...].ts

@@ -1,15 +0,0 @@
-import { defineEventHandler } from 'h3';
-
-export default defineEventHandler(() => {
-  return `
-<h1>Hello Vben Admin</h1>
-<h2>Mock service is starting</h2>
-<ul>
-<li><a href="/api/user">/api/user/info</a></li>
-<li><a href="/api/menu">/api/menu/all</a></li>
-<li><a href="/api/auth/codes">/api/auth/codes</a></li>
-<li><a href="/api/auth/login">/api/auth/login</a></li>
-<li><a href="/api/upload">/api/upload</a></li>
-</ul>
-`;
-});

apps/backend-mock/tsconfig.build.json

@@ -1,4 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
-}

apps/backend-mock/tsconfig.json

@@ -1,3 +0,0 @@
-{
-  "extends": "./.nitro/types/tsconfig.json"
-}

apps/backend-mock/utils/cookie-utils.ts

@@ -1,28 +0,0 @@
-import type { EventHandlerRequest, H3Event } from 'h3';
-
-import { deleteCookie, getCookie, setCookie } from 'h3';
-
-export function clearRefreshTokenCookie(event: H3Event<EventHandlerRequest>) {
-  deleteCookie(event, 'jwt', {
-    httpOnly: true,
-    sameSite: 'none',
-    secure: true,
-  });
-}
-
-export function setRefreshTokenCookie(
-  event: H3Event<EventHandlerRequest>,
-  refreshToken: string,
-) {
-  setCookie(event, 'jwt', refreshToken, {
-    httpOnly: true,
-    maxAge: 24 * 60 * 60, // unit: seconds
-    sameSite: 'none',
-    secure: true,
-  });
-}
-
-export function getRefreshTokenFromCookie(event: H3Event<EventHandlerRequest>) {
-  const refreshToken = getCookie(event, 'jwt');
-  return refreshToken;
-}

apps/backend-mock/utils/jwt-utils.ts

@@ -1,77 +0,0 @@
-import type { EventHandlerRequest, H3Event } from 'h3';
-
-import type { UserInfo } from './mock-data';
-
-import { getHeader } from 'h3';
-import jwt from 'jsonwebtoken';
-
-import { MOCK_USERS } from './mock-data';
-
-// TODO: Replace with your own secret key
-const ACCESS_TOKEN_SECRET = 'access_token_secret';
-const REFRESH_TOKEN_SECRET = 'refresh_token_secret';
-
-export interface UserPayload extends UserInfo {
-  iat: number;
-  exp: number;
-}
-
-export function generateAccessToken(user: UserInfo) {
-  return jwt.sign(user, ACCESS_TOKEN_SECRET, { expiresIn: '7d' });
-}
-
-export function generateRefreshToken(user: UserInfo) {
-  return jwt.sign(user, REFRESH_TOKEN_SECRET, {
-    expiresIn: '30d',
-  });
-}
-
-export function verifyAccessToken(
-  event: H3Event<EventHandlerRequest>,
-): null | Omit<UserInfo, 'password'> {
-  const authHeader = getHeader(event, 'Authorization');
-  if (!authHeader?.startsWith('Bearer')) {
-    return null;
-  }
-
-  const tokenParts = authHeader.split(' ');
-  if (tokenParts.length !== 2) {
-    return null;
-  }
-  const token = tokenParts[1] as string;
-  try {
-    const decoded = jwt.verify(
-      token,
-      ACCESS_TOKEN_SECRET,
-    ) as unknown as UserPayload;
-
-    const username = decoded.username;
-    const user = MOCK_USERS.find((item) => item.username === username);
-    if (!user) {
-      return null;
-    }
-    const { password: _pwd, ...userinfo } = user;
-    return userinfo;
-  } catch {
-    return null;
-  }
-}
-
-export function verifyRefreshToken(
-  token: string,
-): null | Omit<UserInfo, 'password'> {
-  try {
-    const decoded = jwt.verify(token, REFRESH_TOKEN_SECRET) as UserPayload;
-    const username = decoded.username;
-    const user = MOCK_USERS.find(
-      (item) => item.username === username,
-    ) as UserInfo;
-    if (!user) {
-      return null;
-    }
-    const { password: _pwd, ...userinfo } = user;
-    return userinfo;
-  } catch {
-    return null;
-  }
-}

apps/backend-mock/utils/mock-data.ts

@@ -1,421 +0,0 @@
-export interface UserInfo {
-  id: number;
-  password: string;
-  realName: string;
-  roles: string[];
-  username: string;
-  homePath?: string;
-}
-
-export interface TimezoneOption {
-  offset: number;
-  timezone: string;
-}
-
-export const MOCK_USERS: UserInfo[] = [
-  {
-    id: 0,
-    password: '123456',
-    realName: 'Vben',
-    roles: ['super'],
-    username: 'vben',
-  },
-  {
-    id: 1,
-    password: '123456',
-    realName: 'Admin',
-    roles: ['admin'],
-    username: 'admin',
-    homePath: '/workspace',
-  },
-  {
-    id: 2,
-    password: '123456',
-    realName: 'Jack',
-    roles: ['user'],
-    username: 'jack',
-    homePath: '/analytics',
-  },
-];
-
-export const MOCK_CODES = [
-  // super
-  {
-    codes: ['AC_100100', 'AC_100110', 'AC_100120', 'AC_100010'],
-    username: 'vben',
-  },
-  {
-    // admin
-    codes: ['AC_100010', 'AC_100020', 'AC_100030'],
-    username: 'admin',
-  },
-  {
-    // user
-    codes: ['AC_1000001', 'AC_1000002'],
-    username: 'jack',
-  },
-];
-
-const dashboardMenus = [
-  {
-    meta: {
-      order: -1,
-      title: 'page.dashboard.title',
-    },
-    name: 'Dashboard',
-    path: '/dashboard',
-    redirect: '/analytics',
-    children: [
-      {
-        name: 'Analytics',
-        path: '/analytics',
-        component: '/dashboard/analytics/index',
-        meta: {
-          affixTab: true,
-          title: 'page.dashboard.analytics',
-        },
-      },
-      {
-        name: 'Workspace',
-        path: '/workspace',
-        component: '/dashboard/workspace/index',
-        meta: {
-          title: 'page.dashboard.workspace',
-        },
-      },
-    ],
-  },
-];
-
-const createDemosMenus = (role: 'admin' | 'super' | 'user') => {
-  const roleWithMenus = {
-    admin: {
-      component: '/demos/access/admin-visible',
-      meta: {
-        icon: 'mdi:button-cursor',
-        title: 'demos.access.adminVisible',
-      },
-      name: 'AccessAdminVisibleDemo',
-      path: '/demos/access/admin-visible',
-    },
-    super: {
-      component: '/demos/access/super-visible',
-      meta: {
-        icon: 'mdi:button-cursor',
-        title: 'demos.access.superVisible',
-      },
-      name: 'AccessSuperVisibleDemo',
-      path: '/demos/access/super-visible',
-    },
-    user: {
-      component: '/demos/access/user-visible',
-      meta: {
-        icon: 'mdi:button-cursor',
-        title: 'demos.access.userVisible',
-      },
-      name: 'AccessUserVisibleDemo',
-      path: '/demos/access/user-visible',
-    },
-  };
-
-  return [
-    {
-      meta: {
-        icon: 'ic:baseline-view-in-ar',
-        keepAlive: true,
-        order: 1000,
-        title: 'demos.title',
-      },
-      name: 'Demos',
-      path: '/demos',
-      redirect: '/demos/access',
-      children: [
-        {
-          name: 'AccessDemos',
-          path: '/demosaccess',
-          meta: {
-            icon: 'mdi:cloud-key-outline',
-            title: 'demos.access.backendPermissions',
-          },
-          redirect: '/demos/access/page-control',
-          children: [
-            {
-              name: 'AccessPageControlDemo',
-              path: '/demos/access/page-control',
-              component: '/demos/access/index',
-              meta: {
-                icon: 'mdi:page-previous-outline',
-                title: 'demos.access.pageAccess',
-              },
-            },
-            {
-              name: 'AccessButtonControlDemo',
-              path: '/demos/access/button-control',
-              component: '/demos/access/button-control',
-              meta: {
-                icon: 'mdi:button-cursor',
-                title: 'demos.access.buttonControl',
-              },
-            },
-            {
-              name: 'AccessMenuVisible403Demo',
-              path: '/demos/access/menu-visible-403',
-              component: '/demos/access/menu-visible-403',
-              meta: {
-                authority: ['no-body'],
-                icon: 'mdi:button-cursor',
-                menuVisibleWithForbidden: true,
-                title: 'demos.access.menuVisible403',
-              },
-            },
-            roleWithMenus[role],
-          ],
-        },
-      ],
-    },
-  ];
-};
-
-export const MOCK_MENUS = [
-  {
-    menus: [...dashboardMenus, ...createDemosMenus('super')],
-    username: 'vben',
-  },
-  {
-    menus: [...dashboardMenus, ...createDemosMenus('admin')],
-    username: 'admin',
-  },
-  {
-    menus: [...dashboardMenus, ...createDemosMenus('user')],
-    username: 'jack',
-  },
-];
-
-export const MOCK_MENU_LIST = [
-  {
-    id: 1,
-    name: 'Workspace',
-    status: 1,
-    type: 'menu',
-    icon: 'mdi:dashboard',
-    path: '/workspace',
-    component: '/dashboard/workspace/index',
-    meta: {
-      icon: 'carbon:workspace',
-      title: 'page.dashboard.workspace',
-      affixTab: true,
-      order: 0,
-    },
-  },
-  {
-    id: 2,
-    meta: {
-      icon: 'carbon:settings',
-      order: 9997,
-      title: 'system.title',
-      badge: 'new',
-      badgeType: 'normal',
-      badgeVariants: 'primary',
-    },
-    status: 1,
-    type: 'catalog',
-    name: 'System',
-    path: '/system',
-    children: [
-      {
-        id: 201,
-        pid: 2,
-        path: '/system/menu',
-        name: 'SystemMenu',
-        authCode: 'System:Menu:List',
-        status: 1,
-        type: 'menu',
-        meta: {
-          icon: 'carbon:menu',
-          title: 'system.menu.title',
-        },
-        component: '/system/menu/list',
-        children: [
-          {
-            id: 20_101,
-            pid: 201,
-            name: 'SystemMenuCreate',
-            status: 1,
-            type: 'button',
-            authCode: 'System:Menu:Create',
-            meta: { title: 'common.create' },
-          },
-          {
-            id: 20_102,
-            pid: 201,
-            name: 'SystemMenuEdit',
-            status: 1,
-            type: 'button',
-            authCode: 'System:Menu:Edit',
-            meta: { title: 'common.edit' },
-          },
-          {
-            id: 20_103,
-            pid: 201,
-            name: 'SystemMenuDelete',
-            status: 1,
-            type: 'button',
-            authCode: 'System:Menu:Delete',
-            meta: { title: 'common.delete' },
-          },
-        ],
-      },
-      {
-        id: 202,
-        pid: 2,
-        path: '/system/dept',
-        name: 'SystemDept',
-        status: 1,
-        type: 'menu',
-        authCode: 'System:Dept:List',
-        meta: {
-          icon: 'carbon:container-services',
-          title: 'system.dept.title',
-        },
-        component: '/system/dept/list',
-        children: [
-          {
-            id: 20_401,
-            pid: 202,
-            name: 'SystemDeptCreate',
-            status: 1,
-            type: 'button',
-            authCode: 'System:Dept:Create',
-            meta: { title: 'common.create' },
-          },
-          {
-            id: 20_402,
-            pid: 202,
-            name: 'SystemDeptEdit',
-            status: 1,
-            type: 'button',
-            authCode: 'System:Dept:Edit',
-            meta: { title: 'common.edit' },
-          },
-          {
-            id: 20_403,
-            pid: 202,
-            name: 'SystemDeptDelete',
-            status: 1,
-            type: 'button',
-            authCode: 'System:Dept:Delete',
-            meta: { title: 'common.delete' },
-          },
-        ],
-      },
-    ],
-  },
-  {
-    id: 9,
-    meta: {
-      badgeType: 'dot',
-      order: 9998,
-      title: 'demos.vben.title',
-      icon: 'carbon:data-center',
-    },
-    name: 'Project',
-    path: '/vben-admin',
-    type: 'catalog',
-    status: 1,
-    children: [
-      {
-        id: 901,
-        pid: 9,
-        name: 'VbenDocument',
-        path: '/vben-admin/document',
-        component: 'IFrameView',
-        type: 'embedded',
-        status: 1,
-        meta: {
-          icon: 'carbon:book',
-          iframeSrc: 'https://doc.vben.pro',
-          title: 'demos.vben.document',
-        },
-      },
-      {
-        id: 902,
-        pid: 9,
-        name: 'VbenGithub',
-        path: '/vben-admin/github',
-        component: 'IFrameView',
-        type: 'link',
-        status: 1,
-        meta: {
-          icon: 'carbon:logo-github',
-          link: 'https://github.com/vbenjs/vue-vben-admin',
-          title: 'Github',
-        },
-      },
-      {
-        id: 903,
-        pid: 9,
-        name: 'VbenAntdv',
-        path: '/vben-admin/antdv',
-        component: 'IFrameView',
-        type: 'link',
-        status: 0,
-        meta: {
-          icon: 'carbon:hexagon-vertical-solid',
-          badgeType: 'dot',
-          link: 'https://ant.vben.pro',
-          title: 'demos.vben.antdv',
-        },
-      },
-    ],
-  },
-  {
-    id: 10,
-    component: '_core/about/index',
-    type: 'menu',
-    status: 1,
-    meta: {
-      icon: 'lucide:copyright',
-      order: 9999,
-      title: 'demos.vben.about',
-    },
-    name: 'About',
-    path: '/about',
-  },
-];
-
-export function getMenuIds(menus: any[]) {
-  const ids: number[] = [];
-  menus.forEach((item) => {
-    ids.push(item.id);
-    if (item.children && item.children.length > 0) {
-      ids.push(...getMenuIds(item.children));
-    }
-  });
-  return ids;
-}
-
-/**
- * 时区选项
- */
-export const TIME_ZONE_OPTIONS: TimezoneOption[] = [
-  {
-    offset: -5,
-    timezone: 'America/New_York',
-  },
-  {
-    offset: 0,
-    timezone: 'Europe/London',
-  },
-  {
-    offset: 8,
-    timezone: 'Asia/Shanghai',
-  },
-  {
-    offset: 9,
-    timezone: 'Asia/Tokyo',
-  },
-  {
-    offset: 9,
-    timezone: 'Asia/Seoul',
-  },
-];

apps/backend-mock/utils/response.ts

@@ -1,70 +0,0 @@
-import type { EventHandlerRequest, H3Event } from 'h3';
-
-import { setResponseStatus } from 'h3';
-
-export function useResponseSuccess<T = any>(data: T) {
-  return {
-    code: 0,
-    data,
-    error: null,
-    message: 'ok',
-  };
-}
-
-export function usePageResponseSuccess<T = any>(
-  page: number | string,
-  pageSize: number | string,
-  list: T[],
-  { message = 'ok' } = {},
-) {
-  const pageData = pagination(
-    Number.parseInt(`${page}`),
-    Number.parseInt(`${pageSize}`),
-    list,
-  );
-
-  return {
-    ...useResponseSuccess({
-      items: pageData,
-      total: list.length,
-    }),
-    message,
-  };
-}
-
-export function useResponseError(message: string, error: any = null) {
-  return {
-    code: -1,
-    data: null,
-    error,
-    message,
-  };
-}
-
-export function forbiddenResponse(
-  event: H3Event<EventHandlerRequest>,
-  message = 'Forbidden Exception',
-) {
-  setResponseStatus(event, 403);
-  return useResponseError(message, message);
-}
-
-export function unAuthorizedResponse(event: H3Event<EventHandlerRequest>) {
-  setResponseStatus(event, 401);
-  return useResponseError('Unauthorized Exception', 'Unauthorized Exception');
-}
-
-export function sleep(ms: number) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-export function pagination<T = any>(
-  pageNo: number,
-  pageSize: number,
-  array: T[],
-): T[] {
-  const offset = (pageNo - 1) * Number(pageSize);
-  return offset + Number(pageSize) >= array.length
-    ? array.slice(offset)
-    : array.slice(offset, offset + Number(pageSize));
-}

apps/backend-mock/utils/timezone-utils.ts

@@ -1,9 +0,0 @@
-let mockTimeZone: null | string = null;
-
-export const setTimezone = (timeZone: string) => {
-  mockTimeZone = timeZone;
-};
-
-export const getTimezone = () => {
-  return mockTimeZone;
-};

apps/web-antd/.env

@@ -6,3 +6,6 @@ VITE_APP_NAMESPACE=vben-web-antd
 
 # 对store进行加密的密钥，在将store持久化到localStorage时会使用该密钥进行加密
 VITE_APP_STORE_SECURE_KEY=please-replace-me-with-your-own-key
+
+# 腾讯地图 WebGL JS SDK Key
+VITE_TENCENT_MAP_KEY=DGIBZ-YUM64-5ONUT-F4RIA-MPUP2-XFFXZ

apps/web-antd/.env.development

@@ -4,10 +4,16 @@ VITE_PORT=5666
 VITE_BASE=/
 
 # 接口地址
-VITE_GLOB_API_URL=/api
+VITE_GLOB_API_URL=https://api-tenant-dev.laosankeji.com/api/tenant/v1
+
+# 可选：默认租户标识（若登录不使用 账号@手机号，可在此配置）
+VITE_TENANT_ID=806357433394921472
 
 # 是否开启 Nitro Mock服务，true 为开启，false 为关闭
-VITE_NITRO_MOCK=true
+VITE_NITRO_MOCK=false
+
+# 是否开启商品分类管理 mock（默认 false，分类管理强制走真实 API）
+VITE_MOCK_PRODUCT_CATEGORY=false
 
 # 是否打开 devtools，true 为打开，false 为关闭
 VITE_DEVTOOLS=false

apps/web-antd/.env.production

@@ -1,7 +1,7 @@
 VITE_BASE=/
 
 # 接口地址
-VITE_GLOB_API_URL=https://mock-napi.vben.pro/api
+VITE_GLOB_API_URL=https://api-tenant.laosankeji.com/api/tenant/v1
 
 # 是否开启压缩，可以设置为 none, brotli, gzip
 VITE_COMPRESS=none

apps/web-antd/package.json

@@ -26,6 +26,7 @@
     "#/*": "./src/*"
   },
   "dependencies": {
+    "@microsoft/signalr": "catalog:",
     "@vben/access": "workspace:*",
     "@vben/common-ui": "workspace:*",
     "@vben/constants": "workspace:*",
@@ -43,8 +44,12 @@
     "@vueuse/core": "catalog:",
     "ant-design-vue": "catalog:",
     "dayjs": "catalog:",
+    "mockjs": "catalog:",
     "pinia": "catalog:",
     "vue": "catalog:",
     "vue-router": "catalog:"
+  },
+  "devDependencies": {
+    "@types/mockjs": "catalog:"
   }
 }

apps/web-antd/public/sounds/README.md

@@ -0,0 +1,5 @@
+Sound placeholder files:
+- new-order.mp3: 新订单提示音（需替换为实际音频文件）
+- urge.mp3: 催单提示音（需替换为实际音频文件）
+
+请将实际的 MP3 音频文件放置到此目录下。

apps/web-antd/src/api/core/auth.ts

@@ -1,20 +1,44 @@
+import type { RequestClientConfig } from '@vben/request';
+
 import { baseRequestClient, requestClient } from '#/api/request';
 
 export namespace AuthApi {
+  export interface CurrentUserProfile {
+    account?: string;
+    avatar?: string;
+    displayName?: string;
+    merchantId?: null | number | string;
+    permissions?: string[];
+    roles?: string[];
+    tenantId?: number | string;
+    userId?: number | string;
+  }
+
   /** 登录接口参数 */
   export interface LoginParams {
-    password?: string;
+    account: string;
-    username?: string;
+    password: string;
   }
 
   /** 登录接口返回值 */
   export interface LoginResult {
-    accessToken: string;
+    accessToken?: string;
+    accessTokenExpiresAt?: string;
+    isNewUser?: boolean;
+    refreshToken?: string;
+    refreshTokenExpiresAt?: string;
+    user?: CurrentUserProfile;
   }
 
-  export interface RefreshTokenResult {
+  export interface RefreshTokenParams {
-    data: string;
+    refreshToken: string;
-    status: number;
+  }
+
+  export interface ApiResponse<T> {
+    code: number;
+    data: T;
+    message?: string;
+    success: boolean;
   }
 }
 
@@ -22,30 +46,36 @@ export namespace AuthApi {
  * 登录
  */
 export async function loginApi(data: AuthApi.LoginParams) {
-  return requestClient.post<AuthApi.LoginResult>('/auth/login', data);
+  return requestClient.post<AuthApi.LoginResult>('/auth/login', {
+    account: data.account,
+    password: data.password,
+  });
 }
 
 /**
  * 刷新accessToken
  */
-export async function refreshTokenApi() {
+export async function refreshTokenApi(
-  return baseRequestClient.post<AuthApi.RefreshTokenResult>('/auth/refresh', {
+  data: AuthApi.RefreshTokenParams,
-    withCredentials: true,
+  config?: RequestClientConfig,
-  });
+) {
+  return baseRequestClient.post<AuthApi.ApiResponse<AuthApi.LoginResult>>(
+    '/auth/refresh',
+    data,
+    config,
+  );
 }
 
 /**
  * 退出登录
  */
 export async function logoutApi() {
-  return baseRequestClient.post('/auth/logout', {
+  return baseRequestClient.post('/auth/logout');
-    withCredentials: true,
-  });
 }
 
 /**
  * 获取用户权限码
  */
 export async function getAccessCodesApi() {
-  return requestClient.get<string[]>('/auth/codes');
+  return requestClient.get<string[]>('/auth/permissions');
 }

apps/web-antd/src/api/core/menu.ts

@@ -6,5 +6,5 @@ import { requestClient } from '#/api/request';
  * 获取用户所有菜单
  */
 export async function getAllMenusApi() {
-  return requestClient.get<RouteRecordStringComponent[]>('/menu/all');
+  return requestClient.get<RouteRecordStringComponent[]>('/auth/menu');
 }

apps/web-antd/src/api/core/user.ts

@@ -2,9 +2,47 @@ import type { UserInfo } from '@vben/types';
 
 import { requestClient } from '#/api/request';
 
+const TENANT_STORAGE_KEY = 'sys-tenant-id';
+
+interface TenantUserProfile {
+  account?: string;
+  avatar?: string;
+  displayName?: string;
+  merchantId?: null | number | string;
+  packageName?: string;
+  permissions?: string[];
+  roles?: string[];
+  tenantId?: number | string;
+  userId?: number | string;
+}
+
+function normalizeId(value: null | number | string | undefined) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  return String(value);
+}
+
+function mapProfileToUserInfo(profile: TenantUserProfile): UserInfo {
+  return {
+    avatar: profile.avatar ?? '',
+    desc: profile.packageName ?? '',
+    homePath: '',
+    realName: profile.displayName ?? profile.account ?? '',
+    roles: profile.roles ?? [],
+    token: '',
+    userId: normalizeId(profile.userId),
+    username: profile.account ?? '',
+  };
+}
+
 /**
  * 获取用户信息
  */
 export async function getUserInfoApi() {
-  return requestClient.get<UserInfo>('/user/info');
+  const profile = await requestClient.get<TenantUserProfile>('/auth/profile');
+  if (profile.tenantId !== null && profile.tenantId !== undefined) {
+    localStorage.setItem(TENANT_STORAGE_KEY, String(profile.tenantId));
+  }
+  return mapProfileToUserInfo(profile);
 }

apps/web-antd/src/api/customer/index.ts

@@ -0,0 +1,424 @@
+/**
+ * 文件职责：客户管理列表与画像 API 契约定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 客户标签筛选值。 */
+export type CustomerTagFilter =
+  | 'active'
+  | 'all'
+  | 'churn'
+  | 'dormant'
+  | 'high_value'
+  | 'new_customer';
+
+/** 客户下单次数筛选值。 */
+export type CustomerOrderCountRangeFilter =
+  | 'all'
+  | 'once'
+  | 'six_to_ten'
+  | 'ten_plus'
+  | 'two_to_five';
+
+/** 客户注册周期筛选值。 */
+export type CustomerRegisterPeriodFilter = '7d' | '30d' | '90d' | 'all';
+
+/** 客户列表筛选参数。 */
+export interface CustomerListFilterQuery {
+  keyword?: string;
+  orderCountRange?: CustomerOrderCountRangeFilter;
+  registerPeriod?: CustomerRegisterPeriodFilter;
+  storeId: string;
+  tag?: CustomerTagFilter;
+}
+
+/** 客户列表分页参数。 */
+export interface CustomerListQuery extends CustomerListFilterQuery {
+  page: number;
+  pageSize: number;
+}
+
+/** 客户标签。 */
+export interface CustomerTagDto {
+  code: string;
+  label: string;
+  tone: string;
+}
+
+/** 客户列表行。 */
+export interface CustomerListItemDto {
+  avatarColor: string;
+  avatarText: string;
+  averageAmount: number;
+  customerKey: string;
+  isDimmed: boolean;
+  lastOrderAt: string;
+  name: string;
+  orderCount: number;
+  orderCountBarPercent: number;
+  phoneMasked: string;
+  tags: CustomerTagDto[];
+  totalAmount: number;
+}
+
+/** 客户列表结果。 */
+export interface CustomerListResultDto {
+  items: CustomerListItemDto[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 客户列表统计。 */
+export interface CustomerListStatsDto {
+  activeCustomers: number;
+  averageAmountLast30Days: number;
+  monthlyGrowthRatePercent: number;
+  monthlyNewCustomers: number;
+  totalCustomers: number;
+}
+
+/** 客户消费偏好。 */
+export interface CustomerPreferenceDto {
+  averageDeliveryDistance: string;
+  preferredCategories: string[];
+  preferredDelivery: string;
+  preferredOrderPeaks: string;
+  preferredPaymentMethod: string;
+}
+
+/** 客户常购商品。 */
+export interface CustomerTopProductDto {
+  count: number;
+  productName: string;
+  proportionPercent: number;
+  rank: number;
+}
+
+/** 客户趋势点。 */
+export interface CustomerTrendPointDto {
+  amount: number;
+  label: string;
+}
+
+/** 客户最近订单。 */
+export interface CustomerRecentOrderDto {
+  amount: number;
+  deliveryType: string;
+  itemsSummary: string;
+  orderNo: string;
+  orderedAt: string;
+  status: string;
+}
+
+/** 客户会员摘要。 */
+export interface CustomerMemberSummaryDto {
+  growthValue: number;
+  isMember: boolean;
+  joinedAt: string;
+  pointsBalance: number;
+  tierName: string;
+}
+
+/** 客户详情（一级抽屉）。 */
+export interface CustomerDetailDto {
+  averageAmount: number;
+  customerKey: string;
+  firstOrderAt: string;
+  member: CustomerMemberSummaryDto;
+  name: string;
+  phoneMasked: string;
+  preference: CustomerPreferenceDto;
+  recentOrders: CustomerRecentOrderDto[];
+  registeredAt: string;
+  repurchaseRatePercent: number;
+  source: string;
+  tags: CustomerTagDto[];
+  topProducts: CustomerTopProductDto[];
+  totalAmount: number;
+  totalOrders: number;
+  trend: CustomerTrendPointDto[];
+}
+
+/** 客户画像（一级抽屉内二级抽屉）。 */
+export interface CustomerProfileDto {
+  averageAmount: number;
+  averageOrderIntervalDays: number;
+  customerKey: string;
+  firstOrderAt: string;
+  member: CustomerMemberSummaryDto;
+  name: string;
+  phoneMasked: string;
+  preference: CustomerPreferenceDto;
+  recentOrders: CustomerRecentOrderDto[];
+  registeredAt: string;
+  repurchaseRatePercent: number;
+  source: string;
+  tags: CustomerTagDto[];
+  topProducts: CustomerTopProductDto[];
+  totalAmount: number;
+  totalOrders: number;
+  trend: CustomerTrendPointDto[];
+}
+
+/** 客户导出回执。 */
+export interface CustomerExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 客户分析周期筛选值。 */
+export type CustomerAnalysisPeriodFilter = '7d' | '30d' | '90d' | '365d';
+
+/** 客户分析趋势点。 */
+export interface CustomerAnalysisTrendPointDto {
+  label: string;
+  value: number;
+}
+
+/** 客户分析新老客构成项。 */
+export interface CustomerAnalysisCompositionItemDto {
+  count: number;
+  label: string;
+  percent: number;
+  segmentCode: string;
+  tone: string;
+}
+
+/** 客单价分布项。 */
+export interface CustomerAnalysisAmountDistributionItemDto {
+  count: number;
+  label: string;
+  percent: number;
+  segmentCode: string;
+}
+
+/** RFM 分层单元。 */
+export interface CustomerAnalysisRfmCellDto {
+  count: number;
+  label: string;
+  segmentCode: string;
+  tone: string;
+}
+
+/** RFM 分层行。 */
+export interface CustomerAnalysisRfmRowDto {
+  cells: CustomerAnalysisRfmCellDto[];
+  label: string;
+}
+
+/** 客户分析 Top 客户。 */
+export interface CustomerAnalysisTopCustomerDto {
+  averageAmount: number;
+  customerKey: string;
+  lastOrderAt: string;
+  name: string;
+  orderCount: number;
+  phoneMasked: string;
+  rank: number;
+  tags: CustomerTagDto[];
+  totalAmount: number;
+}
+
+/** 客户分析总览。 */
+export interface CustomerAnalysisOverviewDto {
+  activeCustomers: number;
+  activeRatePercent: number;
+  amountDistribution: CustomerAnalysisAmountDistributionItemDto[];
+  averageLifetimeValue: number;
+  composition: CustomerAnalysisCompositionItemDto[];
+  growthRatePercent: number;
+  growthTrend: CustomerAnalysisTrendPointDto[];
+  newCustomers: number;
+  newCustomersDailyAverage: number;
+  periodCode: CustomerAnalysisPeriodFilter;
+  periodDays: number;
+  rfmRows: CustomerAnalysisRfmRowDto[];
+  topCustomers: CustomerAnalysisTopCustomerDto[];
+  totalCustomers: number;
+}
+
+/** 客群明细分群编码。 */
+export type CustomerAnalysisSegmentCode =
+  | 'active_new'
+  | 'active_recent'
+  | 'all'
+  | 'amount_0_30'
+  | 'amount_30_60'
+  | 'amount_60_100'
+  | 'amount_100_150'
+  | 'amount_150_plus'
+  | 'churn'
+  | 'dormant'
+  | 'high_value_top'
+  | 'repeat_loyal'
+  | `rfm_r${1 | 2 | 3}c${1 | 2 | 3 | 4}`
+  | (string & {});
+
+/** 客群明细行。 */
+export interface CustomerAnalysisSegmentListItemDto {
+  avatarColor: string;
+  avatarText: string;
+  averageAmount: number;
+  customerKey: string;
+  isDimmed: boolean;
+  isMember: boolean;
+  lastOrderAt: string;
+  memberTierName: string;
+  name: string;
+  orderCount: number;
+  phoneMasked: string;
+  registeredAt: string;
+  tags: CustomerTagDto[];
+  totalAmount: number;
+}
+
+/** 客群明细结果。 */
+export interface CustomerAnalysisSegmentListResultDto {
+  items: CustomerAnalysisSegmentListItemDto[];
+  page: number;
+  pageSize: number;
+  segmentCode: string;
+  segmentDescription: string;
+  segmentTitle: string;
+  totalCount: number;
+}
+
+/** 客户分析会员详情。 */
+export interface CustomerMemberDetailDto {
+  averageAmount: number;
+  customerKey: string;
+  lastOrderAt: string;
+  member: CustomerMemberSummaryDto;
+  name: string;
+  phoneMasked: string;
+  recentOrders: CustomerRecentOrderDto[];
+  registeredAt: string;
+  repurchaseRatePercent: number;
+  source: string;
+  tags: CustomerTagDto[];
+  totalAmount: number;
+  totalOrders: number;
+}
+
+/** 客户分析基础查询参数。 */
+export interface CustomerAnalysisBaseQuery {
+  period?: CustomerAnalysisPeriodFilter;
+  storeId: string;
+}
+
+/** 客群明细查询参数。 */
+export interface CustomerAnalysisSegmentListQuery extends CustomerAnalysisBaseQuery {
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  segmentCode: CustomerAnalysisSegmentCode;
+}
+
+/** 查询客户列表。 */
+export async function getCustomerListApi(params: CustomerListQuery) {
+  return requestClient.get<CustomerListResultDto>('/customer/list/list', {
+    params,
+  });
+}
+
+/** 查询客户列表统计。 */
+export async function getCustomerListStatsApi(params: CustomerListFilterQuery) {
+  return requestClient.get<CustomerListStatsDto>('/customer/list/stats', {
+    params,
+  });
+}
+
+/** 查询客户详情。 */
+export async function getCustomerDetailApi(params: {
+  customerKey: string;
+  storeId: string;
+}) {
+  return requestClient.get<CustomerDetailDto>('/customer/list/detail', {
+    params,
+  });
+}
+
+/** 查询客户画像。 */
+export async function getCustomerProfileApi(params: {
+  customerKey: string;
+  storeId: string;
+}) {
+  return requestClient.get<CustomerProfileDto>('/customer/list/profile', {
+    params,
+  });
+}
+
+/** 导出客户列表 CSV。 */
+export async function exportCustomerCsvApi(params: CustomerListFilterQuery) {
+  return requestClient.get<CustomerExportDto>('/customer/list/export', {
+    params,
+  });
+}
+
+/** 查询客户分析总览。 */
+export async function getCustomerAnalysisOverviewApi(
+  params: CustomerAnalysisBaseQuery,
+) {
+  return requestClient.get<CustomerAnalysisOverviewDto>(
+    '/customer/analysis/overview',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询客群明细分页。 */
+export async function getCustomerAnalysisSegmentListApi(
+  params: CustomerAnalysisSegmentListQuery,
+) {
+  return requestClient.get<CustomerAnalysisSegmentListResultDto>(
+    '/customer/analysis/segment/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询客户分析会员详情。 */
+export async function getCustomerMemberDetailApi(params: {
+  customerKey: string;
+  storeId: string;
+}) {
+  return requestClient.get<CustomerMemberDetailDto>(
+    '/customer/analysis/member/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询客户分析客户详情。 */
+export async function getCustomerAnalysisDetailApi(params: {
+  customerKey: string;
+  storeId: string;
+}) {
+  return requestClient.get<CustomerDetailDto>('/customer/analysis/detail', {
+    params,
+  });
+}
+
+/** 查询客户分析客户画像。 */
+export async function getCustomerAnalysisProfileApi(params: {
+  customerKey: string;
+  storeId: string;
+}) {
+  return requestClient.get<CustomerProfileDto>('/customer/analysis/profile', {
+    params,
+  });
+}
+
+/** 导出客户分析 CSV。 */
+export async function exportCustomerAnalysisCsvApi(
+  params: CustomerAnalysisBaseQuery,
+) {
+  return requestClient.get<CustomerExportDto>('/customer/analysis/export', {
+    params,
+  });
+}

apps/web-antd/src/api/files.ts

@@ -0,0 +1,44 @@
+import { requestClient } from '#/api/request';
+
+export type UploadFileType =
+  | 'business_license'
+  | 'dish_image'
+  | 'merchant_logo'
+  | 'other'
+  | 'review_image'
+  | 'user_avatar';
+
+export interface FileUploadResponse {
+  fileName?: null | string;
+  fileSize: number;
+  url?: null | string;
+}
+
+const TENANT_STORAGE_KEY = 'sys-tenant-id';
+const DEV_TENANT_ID = import.meta.env.DEV ? import.meta.env.VITE_TENANT_ID : '';
+
+function resolveTenantId() {
+  const hostname = window.location.hostname;
+  const hostnameParts = hostname.split('.').filter(Boolean);
+  const isIpAddress = /^\d+\.\d+\.\d+\.\d+$/.test(hostname);
+  const subdomainTenantId =
+    hostnameParts.length > 2 && !isIpAddress ? hostnameParts[0] : '';
+  const storageTenantId = localStorage.getItem(TENANT_STORAGE_KEY) || '';
+  return subdomainTenantId || storageTenantId || DEV_TENANT_ID || '';
+}
+
+export async function uploadTenantFileApi(
+  file: File,
+  type: UploadFileType = 'other',
+) {
+  const tenantId = resolveTenantId();
+  if (!tenantId) {
+    throw new Error('缺少租户标识');
+  }
+
+  return requestClient.upload<FileUploadResponse>('/files/upload', {
+    file,
+    tenantId: String(tenantId),
+    type,
+  });
+}

apps/web-antd/src/api/finance/cost.ts

@@ -0,0 +1,143 @@
+/**
+ * 文件职责：财务中心成本管理 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 成本统计维度。 */
+export type FinanceCostDimension = 'store' | 'tenant';
+
+/** 成本分类编码。 */
+export type FinanceCostCategoryCode = 'fixed' | 'food' | 'labor' | 'packaging';
+
+/** 成本作用域查询参数。 */
+export interface FinanceCostScopeQuery {
+  dimension?: FinanceCostDimension;
+  month?: string;
+  storeId?: string;
+}
+
+/** 成本明细项。 */
+export interface FinanceCostEntryDetailDto {
+  amount: number;
+  itemId?: string;
+  itemName: string;
+  quantity?: number;
+  sortOrder: number;
+  unitPrice?: number;
+}
+
+/** 成本分类数据。 */
+export interface FinanceCostEntryCategoryDto {
+  category: FinanceCostCategoryCode;
+  categoryText: string;
+  items: FinanceCostEntryDetailDto[];
+  percentage: number;
+  totalAmount: number;
+}
+
+/** 成本录入数据。 */
+export interface FinanceCostEntryDto {
+  categories: FinanceCostEntryCategoryDto[];
+  costRate: number;
+  dimension: FinanceCostDimension;
+  month: string;
+  monthRevenue: number;
+  storeId?: string;
+  totalCost: number;
+}
+
+/** 保存成本明细项请求。 */
+export interface SaveFinanceCostDetailPayload {
+  amount: number;
+  itemId?: string;
+  itemName: string;
+  quantity?: number;
+  sortOrder: number;
+  unitPrice?: number;
+}
+
+/** 保存成本分类请求。 */
+export interface SaveFinanceCostCategoryPayload {
+  category: FinanceCostCategoryCode;
+  items: SaveFinanceCostDetailPayload[];
+  totalAmount: number;
+}
+
+/** 保存成本录入请求。 */
+export interface SaveFinanceCostEntryPayload extends FinanceCostScopeQuery {
+  categories: SaveFinanceCostCategoryPayload[];
+}
+
+/** 成本分析统计卡。 */
+export interface FinanceCostAnalysisStatsDto {
+  averageCostPerPaidOrder: number;
+  foodCostRate: number;
+  monthOnMonthChangeRate: number;
+  paidOrderCount: number;
+  revenue: number;
+  totalCost: number;
+}
+
+/** 成本趋势点。 */
+export interface FinanceCostTrendPointDto {
+  costRate: number;
+  month: string;
+  revenue: number;
+  totalCost: number;
+}
+
+/** 成本构成项。 */
+export interface FinanceCostCompositionDto {
+  amount: number;
+  category: FinanceCostCategoryCode;
+  categoryText: string;
+  percentage: number;
+}
+
+/** 成本明细表行。 */
+export interface FinanceCostMonthlyDetailRowDto {
+  costRate: number;
+  fixedAmount: number;
+  foodAmount: number;
+  laborAmount: number;
+  month: string;
+  packagingAmount: number;
+  totalCost: number;
+}
+
+/** 成本分析数据。 */
+export interface FinanceCostAnalysisDto {
+  composition: FinanceCostCompositionDto[];
+  detailRows: FinanceCostMonthlyDetailRowDto[];
+  dimension: FinanceCostDimension;
+  month: string;
+  stats: FinanceCostAnalysisStatsDto;
+  storeId?: string;
+  trend: FinanceCostTrendPointDto[];
+}
+
+/** 查询成本录入数据。 */
+export async function getFinanceCostEntryApi(params: FinanceCostScopeQuery) {
+  return requestClient.get<FinanceCostEntryDto>('/finance/cost/entry', {
+    params,
+  });
+}
+
+/** 保存成本录入数据。 */
+export async function saveFinanceCostEntryApi(
+  payload: SaveFinanceCostEntryPayload,
+) {
+  return requestClient.post<FinanceCostEntryDto>(
+    '/finance/cost/entry/save',
+    payload,
+  );
+}
+
+/** 查询成本分析数据。 */
+export async function getFinanceCostAnalysisApi(
+  params: FinanceCostScopeQuery & { trendMonthCount?: number },
+) {
+  return requestClient.get<FinanceCostAnalysisDto>('/finance/cost/analysis', {
+    params,
+  });
+}

apps/web-antd/src/api/finance/index.ts

@@ -0,0 +1,9 @@
+/**
+ * 文件职责：财务中心 API 聚合导出。
+ */
+export * from './cost';
+export * from './invoice';
+export * from './overview';
+export * from './report';
+export * from './settlement';
+export * from './transaction';

apps/web-antd/src/api/finance/invoice.ts

@@ -0,0 +1,206 @@
+/**
+ * 文件职责：财务中心发票管理 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 发票状态筛选值。 */
+export type FinanceInvoiceStatusFilter = 'all' | 'issued' | 'pending' | 'voided';
+
+/** 发票类型筛选值。 */
+export type FinanceInvoiceTypeFilter = 'all' | 'normal' | 'special';
+
+/** 发票设置详情。 */
+export interface FinanceInvoiceSettingDto {
+  autoIssueMaxAmount: number;
+  bankAccount?: string;
+  bankName?: string;
+  companyName: string;
+  enableAutoIssue: boolean;
+  enableElectronicNormalInvoice: boolean;
+  enableElectronicSpecialInvoice: boolean;
+  registeredAddress?: string;
+  registeredPhone?: string;
+  taxpayerNumber: string;
+}
+
+/** 保存发票设置请求。 */
+export interface SaveFinanceInvoiceSettingPayload
+  extends FinanceInvoiceSettingDto {}
+
+/** 发票记录列表查询参数。 */
+export interface FinanceInvoiceRecordListQuery {
+  endDate?: string;
+  invoiceType?: Exclude<FinanceInvoiceTypeFilter, 'all'>;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  startDate?: string;
+  status?: Exclude<FinanceInvoiceStatusFilter, 'all'>;
+}
+
+/** 发票统计结果。 */
+export interface FinanceInvoiceStatsDto {
+  currentMonthIssuedAmount: number;
+  currentMonthIssuedCount: number;
+  pendingCount: number;
+  voidedCount: number;
+}
+
+/** 发票记录列表项。 */
+export interface FinanceInvoiceRecordListItemDto {
+  amount: number;
+  applicantName: string;
+  appliedAt: string;
+  companyName: string;
+  invoiceNo: string;
+  invoiceType: string;
+  invoiceTypeText: string;
+  orderNo: string;
+  recordId: string;
+  status: string;
+  statusText: string;
+}
+
+/** 发票记录分页结果。 */
+export interface FinanceInvoiceRecordListResultDto {
+  items: FinanceInvoiceRecordListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: FinanceInvoiceStatsDto;
+  totalCount: number;
+}
+
+/** 发票记录详情。 */
+export interface FinanceInvoiceRecordDetailDto {
+  amount: number;
+  applicantName: string;
+  appliedAt: string;
+  applyRemark?: string;
+  companyName: string;
+  contactEmail?: string;
+  contactPhone?: string;
+  invoiceNo: string;
+  invoiceType: string;
+  invoiceTypeText: string;
+  issueRemark?: string;
+  issuedAt?: string;
+  issuedByUserId?: string;
+  orderNo: string;
+  recordId: string;
+  status: string;
+  statusText: string;
+  taxpayerNumber?: string;
+  voidReason?: string;
+  voidedAt?: string;
+  voidedByUserId?: string;
+}
+
+/** 发票开票请求。 */
+export interface FinanceInvoiceIssuePayload {
+  contactEmail?: string;
+  issueRemark?: string;
+  recordId: string;
+}
+
+/** 发票开票结果。 */
+export interface FinanceInvoiceIssueResultDto {
+  amount: number;
+  companyName: string;
+  contactEmail?: string;
+  invoiceNo: string;
+  issuedAt: string;
+  recordId: string;
+  status: string;
+  statusText: string;
+}
+
+/** 发票作废请求。 */
+export interface FinanceInvoiceVoidPayload {
+  recordId: string;
+  voidReason: string;
+}
+
+/** 发票申请请求。 */
+export interface FinanceInvoiceApplyPayload {
+  amount: number;
+  applicantName: string;
+  appliedAt?: string;
+  applyRemark?: string;
+  companyName: string;
+  contactEmail?: string;
+  contactPhone?: string;
+  invoiceType: Exclude<FinanceInvoiceTypeFilter, 'all'>;
+  orderNo: string;
+  taxpayerNumber?: string;
+}
+
+/** 查询发票设置。 */
+export async function getFinanceInvoiceSettingDetailApi() {
+  return requestClient.get<FinanceInvoiceSettingDto>(
+    '/finance/invoice/settings/detail',
+  );
+}
+
+/** 保存发票设置。 */
+export async function saveFinanceInvoiceSettingApi(
+  payload: SaveFinanceInvoiceSettingPayload,
+) {
+  return requestClient.post<FinanceInvoiceSettingDto>(
+    '/finance/invoice/settings/save',
+    payload,
+  );
+}
+
+/** 查询发票记录列表。 */
+export async function getFinanceInvoiceRecordListApi(
+  params: FinanceInvoiceRecordListQuery,
+) {
+  return requestClient.get<FinanceInvoiceRecordListResultDto>(
+    '/finance/invoice/record/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询发票记录详情。 */
+export async function getFinanceInvoiceRecordDetailApi(params: {
+  recordId: string;
+}) {
+  return requestClient.get<FinanceInvoiceRecordDetailDto>(
+    '/finance/invoice/record/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 执行发票开票。 */
+export async function issueFinanceInvoiceRecordApi(
+  payload: FinanceInvoiceIssuePayload,
+) {
+  return requestClient.post<FinanceInvoiceIssueResultDto>(
+    '/finance/invoice/record/issue',
+    payload,
+  );
+}
+
+/** 执行发票作废。 */
+export async function voidFinanceInvoiceRecordApi(
+  payload: FinanceInvoiceVoidPayload,
+) {
+  return requestClient.post<FinanceInvoiceRecordDetailDto>(
+    '/finance/invoice/record/void',
+    payload,
+  );
+}
+
+/** 发起发票申请。 */
+export async function applyFinanceInvoiceRecordApi(
+  payload: FinanceInvoiceApplyPayload,
+) {
+  return requestClient.post<FinanceInvoiceRecordDetailDto>(
+    '/finance/invoice/record/apply',
+    payload,
+  );
+}

apps/web-antd/src/api/finance/overview.ts

@@ -0,0 +1,122 @@
+/**
+ * 文件职责：财务概览 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 财务概览维度。 */
+export type FinanceOverviewDimension = 'store' | 'tenant';
+
+/** 趋势周期值。 */
+export type FinanceOverviewTrendRange = '7' | '30';
+
+/** 财务概览查询参数。 */
+export interface FinanceOverviewDashboardQuery {
+  dimension: FinanceOverviewDimension;
+  storeId?: string;
+}
+
+/** KPI 卡片数据。 */
+export interface FinanceOverviewKpiCardDto {
+  amount: number;
+  changeRate: number;
+  compareAmount: number;
+  compareLabel: string;
+  trend: 'down' | 'flat' | 'up';
+}
+
+/** 收入趋势点。 */
+export interface FinanceOverviewIncomeTrendPointDto {
+  amount: number;
+  date: string;
+  dateLabel: string;
+}
+
+/** 收入趋势数据。 */
+export interface FinanceOverviewIncomeTrendDto {
+  last30Days: FinanceOverviewIncomeTrendPointDto[];
+  last7Days: FinanceOverviewIncomeTrendPointDto[];
+}
+
+/** 利润趋势点。 */
+export interface FinanceOverviewProfitTrendPointDto {
+  costAmount: number;
+  date: string;
+  dateLabel: string;
+  netProfitAmount: number;
+  revenueAmount: number;
+}
+
+/** 利润趋势数据。 */
+export interface FinanceOverviewProfitTrendDto {
+  last30Days: FinanceOverviewProfitTrendPointDto[];
+  last7Days: FinanceOverviewProfitTrendPointDto[];
+}
+
+/** 收入构成项。 */
+export interface FinanceOverviewIncomeCompositionItemDto {
+  amount: number;
+  channel: 'delivery' | 'dine_in' | 'pickup';
+  channelText: string;
+  percentage: number;
+}
+
+/** 收入构成数据。 */
+export interface FinanceOverviewIncomeCompositionDto {
+  items: FinanceOverviewIncomeCompositionItemDto[];
+  totalAmount: number;
+}
+
+/** 成本构成项。 */
+export interface FinanceOverviewCostCompositionItemDto {
+  amount: number;
+  category: 'fixed' | 'food' | 'labor' | 'packaging' | 'platform';
+  categoryText: string;
+  percentage: number;
+}
+
+/** 成本构成数据。 */
+export interface FinanceOverviewCostCompositionDto {
+  items: FinanceOverviewCostCompositionItemDto[];
+  totalAmount: number;
+}
+
+/** TOP 商品项。 */
+export interface FinanceOverviewTopProductItemDto {
+  percentage: number;
+  productName: string;
+  rank: number;
+  revenueAmount: number;
+  salesQuantity: number;
+}
+
+/** TOP 商品排行。 */
+export interface FinanceOverviewTopProductDto {
+  items: FinanceOverviewTopProductItemDto[];
+  periodDays: number;
+}
+
+/** 财务概览驾驶舱数据。 */
+export interface FinanceOverviewDashboardDto {
+  actualReceived: FinanceOverviewKpiCardDto;
+  costComposition: FinanceOverviewCostCompositionDto;
+  dimension: FinanceOverviewDimension;
+  incomeComposition: FinanceOverviewIncomeCompositionDto;
+  incomeTrend: FinanceOverviewIncomeTrendDto;
+  netIncome: FinanceOverviewKpiCardDto;
+  profitTrend: FinanceOverviewProfitTrendDto;
+  refundAmount: FinanceOverviewKpiCardDto;
+  storeId?: string;
+  todayRevenue: FinanceOverviewKpiCardDto;
+  topProducts: FinanceOverviewTopProductDto;
+  withdrawableBalance: FinanceOverviewKpiCardDto;
+}
+
+/** 查询财务概览驾驶舱。 */
+export async function getFinanceOverviewDashboardApi(
+  params: FinanceOverviewDashboardQuery,
+) {
+  return requestClient.get<FinanceOverviewDashboardDto>(
+    '/finance/overview/dashboard',
+    { params },
+  );
+}

apps/web-antd/src/api/finance/report.ts

@@ -0,0 +1,156 @@
+/**
+ * 文件职责：财务中心经营报表 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 报表周期筛选值。 */
+export type FinanceBusinessReportPeriodType = 'daily' | 'monthly' | 'weekly';
+
+/** 经营报表状态值。 */
+export type FinanceBusinessReportStatus =
+  | 'failed'
+  | 'queued'
+  | 'running'
+  | 'succeeded';
+
+/** 经营报表列表查询参数。 */
+export interface FinanceBusinessReportListQuery {
+  page: number;
+  pageSize: number;
+  periodType?: FinanceBusinessReportPeriodType;
+  storeId: string;
+}
+
+/** 经营报表详情查询参数。 */
+export interface FinanceBusinessReportDetailQuery {
+  reportId: string;
+  storeId: string;
+}
+
+/** 经营报表批量导出查询参数。 */
+export interface FinanceBusinessReportBatchExportQuery {
+  page: number;
+  pageSize: number;
+  periodType?: FinanceBusinessReportPeriodType;
+  storeId: string;
+}
+
+/** 经营报表列表行。 */
+export interface FinanceBusinessReportListItemDto {
+  averageOrderValue: number;
+  canDownload: boolean;
+  costTotalAmount: number;
+  dateText: string;
+  netProfitAmount: number;
+  orderCount: number;
+  profitRatePercent: number;
+  refundRatePercent: number;
+  reportId: string;
+  revenueAmount: number;
+  status: FinanceBusinessReportStatus;
+  statusText: string;
+}
+
+/** 经营报表列表结果。 */
+export interface FinanceBusinessReportListResultDto {
+  items: FinanceBusinessReportListItemDto[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 经营报表 KPI 项。 */
+export interface FinanceBusinessReportKpiDto {
+  key: string;
+  label: string;
+  momChangeRate: number;
+  valueText: string;
+  yoyChangeRate: number;
+}
+
+/** 经营报表明细项。 */
+export interface FinanceBusinessReportBreakdownItemDto {
+  amount: number;
+  key: string;
+  label: string;
+  ratioPercent: number;
+}
+
+/** 经营报表详情。 */
+export interface FinanceBusinessReportDetailDto {
+  costBreakdowns: FinanceBusinessReportBreakdownItemDto[];
+  incomeBreakdowns: FinanceBusinessReportBreakdownItemDto[];
+  kpis: FinanceBusinessReportKpiDto[];
+  periodType: FinanceBusinessReportPeriodType;
+  reportId: string;
+  status: FinanceBusinessReportStatus;
+  statusText: string;
+  title: string;
+}
+
+/** 经营报表导出结果。 */
+export interface FinanceBusinessReportExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 查询经营报表列表。 */
+export async function getFinanceBusinessReportListApi(
+  params: FinanceBusinessReportListQuery,
+) {
+  return requestClient.get<FinanceBusinessReportListResultDto>(
+    '/finance/report/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询经营报表详情。 */
+export async function getFinanceBusinessReportDetailApi(
+  params: FinanceBusinessReportDetailQuery,
+) {
+  return requestClient.get<FinanceBusinessReportDetailDto>(
+    '/finance/report/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出经营报表 PDF。 */
+export async function exportFinanceBusinessReportPdfApi(
+  params: FinanceBusinessReportDetailQuery,
+) {
+  return requestClient.get<FinanceBusinessReportExportDto>(
+    '/finance/report/export/pdf',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出经营报表 Excel。 */
+export async function exportFinanceBusinessReportExcelApi(
+  params: FinanceBusinessReportDetailQuery,
+) {
+  return requestClient.get<FinanceBusinessReportExportDto>(
+    '/finance/report/export/excel',
+    {
+      params,
+    },
+  );
+}
+
+/** 批量导出经营报表（ZIP）。 */
+export async function exportFinanceBusinessReportBatchApi(
+  params: FinanceBusinessReportBatchExportQuery,
+) {
+  return requestClient.get<FinanceBusinessReportExportDto>(
+    '/finance/report/export/batch',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/finance/settlement.ts

@@ -0,0 +1,137 @@
+/**
+ * 文件职责：财务中心到账查询 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 到账渠道筛选值。 */
+export type FinanceSettlementChannelFilter = 'alipay' | 'all' | 'wechat';
+
+/** 到账查询筛选参数。 */
+export interface FinanceSettlementFilterQuery {
+  channel?: FinanceSettlementChannelFilter;
+  endDate?: string;
+  startDate?: string;
+  storeId: string;
+}
+
+/** 到账查询列表参数。 */
+export interface FinanceSettlementListQuery extends FinanceSettlementFilterQuery {
+  page: number;
+  pageSize: number;
+}
+
+/** 到账统计结果。 */
+export interface FinanceSettlementStatsDto {
+  currentMonthArrivedAmount: number;
+  currentMonthTransactionCount: number;
+  todayArrivedAmount: number;
+  yesterdayArrivedAmount: number;
+}
+
+/** 到账账户信息。 */
+export interface FinanceSettlementAccountDto {
+  alipayPidMasked: string;
+  bankAccountName: string;
+  bankAccountNoMasked: string;
+  bankName: string;
+  settlementPeriodText: string;
+  wechatMerchantNoMasked: string;
+}
+
+/** 到账列表行。 */
+export interface FinanceSettlementListItemDto {
+  arrivedAmount: number;
+  arrivedDate: string;
+  channel: 'alipay' | 'wechat';
+  channelText: string;
+  transactionCount: number;
+}
+
+/** 到账列表结果。 */
+export interface FinanceSettlementListResultDto {
+  items: FinanceSettlementListItemDto[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 到账明细查询参数。 */
+export interface FinanceSettlementDetailQuery {
+  arrivedDate: string;
+  channel: 'alipay' | 'wechat';
+  storeId: string;
+}
+
+/** 到账明细行。 */
+export interface FinanceSettlementDetailItemDto {
+  amount: number;
+  orderNo: string;
+  paidAt: string;
+}
+
+/** 到账明细结果。 */
+export interface FinanceSettlementDetailResultDto {
+  items: FinanceSettlementDetailItemDto[];
+}
+
+/** 到账导出结果。 */
+export interface FinanceSettlementExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 查询到账统计。 */
+export async function getFinanceSettlementStatsApi(params: {
+  storeId: string;
+}) {
+  return requestClient.get<FinanceSettlementStatsDto>(
+    '/finance/settlement/stats',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询到账账户信息。 */
+export async function getFinanceSettlementAccountApi() {
+  return requestClient.get<FinanceSettlementAccountDto>(
+    '/finance/settlement/account',
+  );
+}
+
+/** 查询到账列表。 */
+export async function getFinanceSettlementListApi(
+  params: FinanceSettlementListQuery,
+) {
+  return requestClient.get<FinanceSettlementListResultDto>(
+    '/finance/settlement/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询到账明细。 */
+export async function getFinanceSettlementDetailApi(
+  params: FinanceSettlementDetailQuery,
+) {
+  return requestClient.get<FinanceSettlementDetailResultDto>(
+    '/finance/settlement/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出到账汇总 CSV。 */
+export async function exportFinanceSettlementCsvApi(
+  params: FinanceSettlementFilterQuery,
+) {
+  return requestClient.get<FinanceSettlementExportDto>(
+    '/finance/settlement/export',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/finance/transaction.ts

@@ -0,0 +1,159 @@
+/**
+ * 文件职责：财务中心交易流水 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 交易类型筛选值。 */
+export type FinanceTransactionTypeFilter =
+  | 'all'
+  | 'income'
+  | 'point_redeem'
+  | 'refund'
+  | 'stored_card_recharge';
+
+/** 交易渠道筛选值。 */
+export type FinanceTransactionChannelFilter =
+  | 'all'
+  | 'delivery'
+  | 'dine_in'
+  | 'pickup';
+
+/** 交易支付方式筛选值。 */
+export type FinanceTransactionPaymentFilter =
+  | 'alipay'
+  | 'all'
+  | 'balance'
+  | 'card'
+  | 'cash'
+  | 'wechat';
+
+/** 交易流水筛选参数。 */
+export interface FinanceTransactionFilterQuery {
+  channel?: FinanceTransactionChannelFilter;
+  endDate?: string;
+  keyword?: string;
+  paymentMethod?: FinanceTransactionPaymentFilter;
+  startDate?: string;
+  storeId: string;
+  type?: FinanceTransactionTypeFilter;
+}
+
+/** 交易流水列表查询参数。 */
+export interface FinanceTransactionListQuery extends FinanceTransactionFilterQuery {
+  page: number;
+  pageSize: number;
+}
+
+/** 交易流水列表行。 */
+export interface FinanceTransactionListItemDto {
+  amount: number;
+  channel: string;
+  isIncome: boolean;
+  occurredAt: string;
+  orderNo?: string;
+  paymentMethod: string;
+  remark: string;
+  transactionId: string;
+  transactionNo: string;
+  type: string;
+  typeText: string;
+}
+
+/** 交易流水列表结果。 */
+export interface FinanceTransactionListResultDto {
+  items: FinanceTransactionListItemDto[];
+  page: number;
+  pageIncomeAmount: number;
+  pageRefundAmount: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 交易流水统计结果。 */
+export interface FinanceTransactionStatsDto {
+  totalCount: number;
+  totalIncome: number;
+  totalRefund: number;
+}
+
+/** 交易流水详情。 */
+export interface FinanceTransactionDetailDto {
+  amount: number;
+  arrivedAmount?: number;
+  channel: string;
+  customerName: string;
+  customerPhone: string;
+  giftAmount?: number;
+  memberMobileMasked?: string;
+  memberName?: string;
+  occurredAt: string;
+  orderNo?: string;
+  paymentMethod: string;
+  pointBalanceAfterChange?: number;
+  pointChangeAmount?: number;
+  rechargeAmount?: number;
+  refundNo?: string;
+  refundReason?: string;
+  remark: string;
+  storeId: string;
+  transactionId: string;
+  transactionNo: string;
+  type: string;
+  typeText: string;
+}
+
+/** 交易流水导出结果。 */
+export interface FinanceTransactionExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 查询交易流水列表。 */
+export async function getFinanceTransactionListApi(
+  params: FinanceTransactionListQuery,
+) {
+  return requestClient.get<FinanceTransactionListResultDto>(
+    '/finance/transaction/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询交易流水统计。 */
+export async function getFinanceTransactionStatsApi(
+  params: FinanceTransactionFilterQuery,
+) {
+  return requestClient.get<FinanceTransactionStatsDto>(
+    '/finance/transaction/stats',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询交易流水详情。 */
+export async function getFinanceTransactionDetailApi(params: {
+  storeId: string;
+  transactionId: string;
+}) {
+  return requestClient.get<FinanceTransactionDetailDto>(
+    '/finance/transaction/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出交易流水 CSV。 */
+export async function exportFinanceTransactionCsvApi(
+  params: FinanceTransactionFilterQuery,
+) {
+  return requestClient.get<FinanceTransactionExportDto>(
+    '/finance/transaction/export',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/marketing/calendar.ts

@@ -0,0 +1,133 @@
+/**
+ * 文件职责：营销中心营销日历 API 与 DTO 定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 总览查询参数。 */
+export interface MarketingCalendarOverviewQuery {
+  month: number;
+  storeId: string;
+  year: number;
+}
+
+/** 日期头。 */
+export interface MarketingCalendarDayDto {
+  day: number;
+  isToday: boolean;
+  isWeekend: boolean;
+}
+
+/** 图例。 */
+export interface MarketingCalendarLegendDto {
+  color: string;
+  label: string;
+  type: string;
+}
+
+/** 顶部统计。 */
+export interface MarketingCalendarStatsDto {
+  estimatedDiscountAmount: number;
+  maxConcurrentCount: number;
+  ongoingCount: number;
+  totalActivityCount: number;
+}
+
+/** 活动条。 */
+export interface MarketingCalendarActivityBarDto {
+  barId: string;
+  endDay: number;
+  isDimmed: boolean;
+  isMilestone: boolean;
+  label: string;
+  startDay: number;
+}
+
+/** 详情字段。 */
+export interface MarketingCalendarDetailFieldDto {
+  label: string;
+  value: string;
+}
+
+/** 活动详情。 */
+export interface MarketingCalendarActivityDetailDto {
+  description: string;
+  fields: MarketingCalendarDetailFieldDto[];
+  moduleName: string;
+}
+
+/** 活动。 */
+export interface MarketingCalendarActivityDto {
+  activityId: string;
+  bars: MarketingCalendarActivityBarDto[];
+  calendarType: string;
+  color: string;
+  detail: MarketingCalendarActivityDetailDto;
+  displayStatus: string;
+  endDate: string;
+  estimatedDiscountAmount: number;
+  isDimmed: boolean;
+  name: string;
+  sourceId: string;
+  sourceType: string;
+  startDate: string;
+  summary: string;
+}
+
+/** 冲突活动摘要。 */
+export interface MarketingCalendarConflictActivityDto {
+  activityId: string;
+  calendarType: string;
+  color: string;
+  displayStatus: string;
+  name: string;
+  summary: string;
+}
+
+/** 冲突区间。 */
+export interface MarketingCalendarConflictDto {
+  activities: MarketingCalendarConflictActivityDto[];
+  activityCount: number;
+  activityIds: string[];
+  conflictId: string;
+  endDay: number;
+  maxConcurrentCount: number;
+  startDay: number;
+}
+
+/** 冲突横幅。 */
+export interface MarketingCalendarConflictBannerDto {
+  activityCount: number;
+  conflictCount: number;
+  conflictId: string;
+  endDay: number;
+  maxConcurrentCount: number;
+  startDay: number;
+}
+
+/** 营销日历总览。 */
+export interface MarketingCalendarOverviewDto {
+  activities: MarketingCalendarActivityDto[];
+  conflictBanner: MarketingCalendarConflictBannerDto | null;
+  conflicts: MarketingCalendarConflictDto[];
+  days: MarketingCalendarDayDto[];
+  legends: MarketingCalendarLegendDto[];
+  month: string;
+  monthEndDate: string;
+  monthStartDate: string;
+  monthValue: number;
+  stats: MarketingCalendarStatsDto;
+  todayDay: number;
+  year: number;
+}
+
+/** 查询营销日历总览。 */
+export async function getMarketingCalendarOverviewApi(
+  params: MarketingCalendarOverviewQuery,
+) {
+  return requestClient.get<MarketingCalendarOverviewDto>(
+    '/marketing/calendar/overview',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/marketing/flash-sale.ts

@@ -0,0 +1,266 @@
+/**
+ * 文件职责：营销中心限时折扣 API 与 DTO 定义。
+ * 1. 维护限时折扣列表、详情、保存、状态切换、删除和选品契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 活动展示状态。 */
+export type MarketingFlashSaleDisplayStatus = 'ended' | 'ongoing' | 'upcoming';
+
+/** 活动编辑状态。 */
+export type MarketingFlashSaleEditorStatus = 'active' | 'completed';
+
+/** 活动周期。 */
+export type MarketingFlashSaleCycleType = 'once' | 'recurring';
+
+/** 周期日期模式。 */
+export type MarketingFlashSaleRecurringDateMode = 'fixed' | 'long_term';
+
+/** 适用渠道。 */
+export type MarketingFlashSaleChannel = 'delivery' | 'dine_in' | 'pickup';
+
+/** 商品状态。 */
+export type MarketingFlashSaleProductStatus =
+  | 'off_shelf'
+  | 'on_sale'
+  | 'sold_out';
+
+/** 限时折扣商品。 */
+export interface MarketingFlashSaleProductDto {
+  categoryId: string;
+  categoryName: string;
+  discountPrice: number;
+  name: string;
+  originalPrice: number;
+  perUserLimit: null | number;
+  productId: string;
+  soldCount: number;
+  spuCode: string;
+  status: MarketingFlashSaleProductStatus;
+}
+
+/** 活动指标。 */
+export interface MarketingFlashSaleMetricsDto {
+  activitySalesCount: number;
+  discountTotalAmount: number;
+  loopedWeeks: number;
+  monthlyDiscountSalesCount: number;
+}
+
+/** 列表查询参数。 */
+export interface MarketingFlashSaleListQuery {
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: '' | MarketingFlashSaleDisplayStatus;
+  storeId?: string;
+}
+
+/** 详情查询参数。 */
+export interface MarketingFlashSaleDetailQuery {
+  activityId: string;
+  storeId: string;
+}
+
+/** 保存请求。 */
+export interface SaveMarketingFlashSaleDto {
+  channels: MarketingFlashSaleChannel[];
+  cycleType: MarketingFlashSaleCycleType;
+  endDate?: string;
+  id?: string;
+  metrics?: MarketingFlashSaleMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  products: Array<{
+    discountPrice: number;
+    perUserLimit: null | number;
+    productId: string;
+  }>;
+  recurringDateMode: MarketingFlashSaleRecurringDateMode;
+  startDate?: string;
+  storeId: string;
+  storeIds: string[];
+  timeEnd?: string;
+  timeStart?: string;
+  weekDays: number[];
+}
+
+/** 状态修改请求。 */
+export interface ChangeMarketingFlashSaleStatusDto {
+  activityId: string;
+  status: MarketingFlashSaleEditorStatus;
+  storeId: string;
+}
+
+/** 删除请求。 */
+export interface DeleteMarketingFlashSaleDto {
+  activityId: string;
+  storeId: string;
+}
+
+/** 列表统计。 */
+export interface MarketingFlashSaleStatsDto {
+  monthlyDiscountSalesCount: number;
+  ongoingCount: number;
+  participatingProductCount: number;
+  totalCount: number;
+}
+
+/** 列表项。 */
+export interface MarketingFlashSaleListItemDto {
+  channels: MarketingFlashSaleChannel[];
+  cycleType: MarketingFlashSaleCycleType;
+  displayStatus: MarketingFlashSaleDisplayStatus;
+  endDate?: string;
+  id: string;
+  isDimmed: boolean;
+  metrics: MarketingFlashSaleMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  products: MarketingFlashSaleProductDto[];
+  recurringDateMode: MarketingFlashSaleRecurringDateMode;
+  startDate?: string;
+  status: MarketingFlashSaleEditorStatus;
+  storeIds: string[];
+  timeEnd?: string;
+  timeStart?: string;
+  updatedAt: string;
+  weekDays: number[];
+}
+
+/** 列表结果。 */
+export interface MarketingFlashSaleListResultDto {
+  items: MarketingFlashSaleListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingFlashSaleStatsDto;
+  total: number;
+}
+
+/** 详情数据。 */
+export interface MarketingFlashSaleDetailDto {
+  channels: MarketingFlashSaleChannel[];
+  cycleType: MarketingFlashSaleCycleType;
+  displayStatus: MarketingFlashSaleDisplayStatus;
+  endDate?: string;
+  id: string;
+  metrics: MarketingFlashSaleMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  products: MarketingFlashSaleProductDto[];
+  recurringDateMode: MarketingFlashSaleRecurringDateMode;
+  startDate?: string;
+  status: MarketingFlashSaleEditorStatus;
+  storeIds: string[];
+  timeEnd?: string;
+  timeStart?: string;
+  updatedAt: string;
+  weekDays: number[];
+}
+
+/** 选品分类查询参数。 */
+export interface MarketingFlashSalePickerCategoryQuery {
+  storeId: string;
+}
+
+/** 选品分类项。 */
+export interface MarketingFlashSalePickerCategoryItemDto {
+  id: string;
+  name: string;
+  productCount: number;
+}
+
+/** 选品商品查询参数。 */
+export interface MarketingFlashSalePickerProductQuery {
+  categoryId?: string;
+  keyword?: string;
+  limit?: number;
+  storeId: string;
+}
+
+/** 选品商品项。 */
+export interface MarketingFlashSalePickerProductItemDto {
+  categoryId: string;
+  categoryName: string;
+  id: string;
+  name: string;
+  price: number;
+  spuCode: string;
+  status: MarketingFlashSaleProductStatus;
+  stock: number;
+}
+
+/** 获取列表。 */
+export async function getMarketingFlashSaleListApi(
+  params: MarketingFlashSaleListQuery,
+) {
+  return requestClient.get<MarketingFlashSaleListResultDto>(
+    '/marketing/flash-sale/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取详情。 */
+export async function getMarketingFlashSaleDetailApi(
+  params: MarketingFlashSaleDetailQuery,
+) {
+  return requestClient.get<MarketingFlashSaleDetailDto>(
+    '/marketing/flash-sale/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存活动。 */
+export async function saveMarketingFlashSaleApi(
+  data: SaveMarketingFlashSaleDto,
+) {
+  return requestClient.post<MarketingFlashSaleDetailDto>(
+    '/marketing/flash-sale/save',
+    data,
+  );
+}
+
+/** 修改状态。 */
+export async function changeMarketingFlashSaleStatusApi(
+  data: ChangeMarketingFlashSaleStatusDto,
+) {
+  return requestClient.post<MarketingFlashSaleDetailDto>(
+    '/marketing/flash-sale/status',
+    data,
+  );
+}
+
+/** 删除活动。 */
+export async function deleteMarketingFlashSaleApi(
+  data: DeleteMarketingFlashSaleDto,
+) {
+  return requestClient.post('/marketing/flash-sale/delete', data);
+}
+
+/** 获取选品分类。 */
+export async function getMarketingFlashSalePickerCategoriesApi(
+  params: MarketingFlashSalePickerCategoryQuery,
+) {
+  return requestClient.get<MarketingFlashSalePickerCategoryItemDto[]>(
+    '/marketing/flash-sale/picker/categories',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取选品商品。 */
+export async function getMarketingFlashSalePickerProductsApi(
+  params: MarketingFlashSalePickerProductQuery,
+) {
+  return requestClient.get<MarketingFlashSalePickerProductItemDto[]>(
+    '/marketing/flash-sale/picker/products',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/marketing/full-reduction.ts

@@ -0,0 +1,240 @@
+/**
+ * 文件职责：营销中心满减活动 API 与 DTO 定义。
+ * 1. 维护满减活动列表、详情、保存、状态切换与删除契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 活动类型。 */
+export type MarketingFullReductionActivityType =
+  | 'gift'
+  | 'reduce'
+  | 'second_half';
+
+/** 展示状态。 */
+export type MarketingFullReductionDisplayStatus =
+  | 'ended'
+  | 'ongoing'
+  | 'upcoming';
+
+/** 编辑状态。 */
+export type MarketingFullReductionEditorStatus = 'active' | 'completed';
+
+/** 适用渠道。 */
+export type MarketingFullReductionChannel = 'delivery' | 'dine_in' | 'pickup';
+
+/** 门店范围。 */
+export type MarketingFullReductionStoreScopeMode = 'all' | 'stores';
+
+/** 商品范围。 */
+export type MarketingFullReductionScopeType = 'all' | 'category' | 'product';
+
+/** 满赠赠品类型。 */
+export type MarketingFullReductionGiftScopeType = 'same_lowest' | 'specified';
+
+/** 第二份折扣类型。 */
+export type MarketingFullReductionSecondHalfDiscountType =
+  | 'free'
+  | 'half'
+  | 'seventy'
+  | 'sixty';
+
+/** 满减阶梯规则。 */
+export interface MarketingFullReductionTierRuleDto {
+  meetAmount: number;
+  reduceAmount: number;
+}
+
+/** 商品范围规则。 */
+export interface MarketingFullReductionScopeRuleDto {
+  categoryIds: string[];
+  productIds: string[];
+  scopeType: MarketingFullReductionScopeType;
+}
+
+/** 满赠规则。 */
+export interface MarketingFullReductionGiftRuleDto {
+  applicableScope: MarketingFullReductionScopeRuleDto;
+  buyQuantity: number;
+  giftQuantity: number;
+  giftScope: MarketingFullReductionScopeRuleDto;
+  giftScopeType: MarketingFullReductionGiftScopeType;
+}
+
+/** 第二份半价规则。 */
+export interface MarketingFullReductionSecondHalfRuleDto {
+  applicableScope: MarketingFullReductionScopeRuleDto;
+  discountType: MarketingFullReductionSecondHalfDiscountType;
+}
+
+/** 活动指标。 */
+export interface MarketingFullReductionMetricsDto {
+  attachRateIncreasePercent: number;
+  averageTicketIncrease: number;
+  discountTotalAmount: number;
+  drivenSalesAmount: number;
+  giftedCount: number;
+  monthlyDrivenSalesAmount: number;
+  participatingOrderCount: number;
+  ticketIncreaseAmount: number;
+}
+
+/** 列表查询参数。 */
+export interface MarketingFullReductionListQuery {
+  activityType?: '' | MarketingFullReductionActivityType;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: '' | MarketingFullReductionDisplayStatus;
+  storeId?: string;
+}
+
+/** 详情查询参数。 */
+export interface MarketingFullReductionDetailQuery {
+  activityId: string;
+  storeId: string;
+}
+
+/** 保存请求。 */
+export interface SaveMarketingFullReductionDto {
+  activityType: MarketingFullReductionActivityType;
+  channels: MarketingFullReductionChannel[];
+  description?: string;
+  endDate: string;
+  giftRule?: MarketingFullReductionGiftRuleDto;
+  id?: string;
+  metrics?: MarketingFullReductionMetricsDto;
+  name: string;
+  reduceTiers: MarketingFullReductionTierRuleDto[];
+  scopeStoreId: string;
+  secondHalfRule?: MarketingFullReductionSecondHalfRuleDto;
+  stackWithCoupon: boolean;
+  startDate: string;
+  storeId: string;
+  storeIds?: string[];
+  storeScopeMode: MarketingFullReductionStoreScopeMode;
+}
+
+/** 状态修改请求。 */
+export interface ChangeMarketingFullReductionStatusDto {
+  activityId: string;
+  status: MarketingFullReductionEditorStatus;
+  storeId: string;
+}
+
+/** 删除请求。 */
+export interface DeleteMarketingFullReductionDto {
+  activityId: string;
+  storeId: string;
+}
+
+/** 统计数据。 */
+export interface MarketingFullReductionStatsDto {
+  averageTicketIncrease: number;
+  monthlyDrivenSalesAmount: number;
+  ongoingCount: number;
+  totalCount: number;
+}
+
+/** 列表项。 */
+export interface MarketingFullReductionListItemDto {
+  activityType: MarketingFullReductionActivityType;
+  channels: MarketingFullReductionChannel[];
+  description?: string;
+  displayStatus: MarketingFullReductionDisplayStatus;
+  endDate: string;
+  giftRule?: MarketingFullReductionGiftRuleDto;
+  id: string;
+  isDimmed: boolean;
+  metrics: MarketingFullReductionMetricsDto;
+  name: string;
+  reduceTiers: MarketingFullReductionTierRuleDto[];
+  scopeStoreId: string;
+  secondHalfRule?: MarketingFullReductionSecondHalfRuleDto;
+  stackWithCoupon: boolean;
+  startDate: string;
+  storeIds: string[];
+  storeScopeMode: MarketingFullReductionStoreScopeMode;
+  updatedAt: string;
+}
+
+/** 列表结果。 */
+export interface MarketingFullReductionListResultDto {
+  items: MarketingFullReductionListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingFullReductionStatsDto;
+  total: number;
+}
+
+/** 详情数据。 */
+export interface MarketingFullReductionDetailDto {
+  activityType: MarketingFullReductionActivityType;
+  channels: MarketingFullReductionChannel[];
+  description?: string;
+  displayStatus: MarketingFullReductionDisplayStatus;
+  endDate: string;
+  giftRule?: MarketingFullReductionGiftRuleDto;
+  id: string;
+  metrics: MarketingFullReductionMetricsDto;
+  name: string;
+  reduceTiers: MarketingFullReductionTierRuleDto[];
+  scopeStoreId: string;
+  secondHalfRule?: MarketingFullReductionSecondHalfRuleDto;
+  stackWithCoupon: boolean;
+  startDate: string;
+  status: MarketingFullReductionEditorStatus;
+  storeIds: string[];
+  storeScopeMode: MarketingFullReductionStoreScopeMode;
+  updatedAt: string;
+}
+
+/** 获取列表。 */
+export async function getMarketingFullReductionListApi(
+  params: MarketingFullReductionListQuery,
+) {
+  return requestClient.get<MarketingFullReductionListResultDto>(
+    '/marketing/full-reduction/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取详情。 */
+export async function getMarketingFullReductionDetailApi(
+  params: MarketingFullReductionDetailQuery,
+) {
+  return requestClient.get<MarketingFullReductionDetailDto>(
+    '/marketing/full-reduction/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存活动。 */
+export async function saveMarketingFullReductionApi(
+  data: SaveMarketingFullReductionDto,
+) {
+  return requestClient.post<MarketingFullReductionDetailDto>(
+    '/marketing/full-reduction/save',
+    data,
+  );
+}
+
+/** 修改状态。 */
+export async function changeMarketingFullReductionStatusApi(
+  data: ChangeMarketingFullReductionStatusDto,
+) {
+  return requestClient.post<MarketingFullReductionDetailDto>(
+    '/marketing/full-reduction/status',
+    data,
+  );
+}
+
+/** 删除活动。 */
+export async function deleteMarketingFullReductionApi(
+  data: DeleteMarketingFullReductionDto,
+) {
+  return requestClient.post('/marketing/full-reduction/delete', data);
+}

apps/web-antd/src/api/marketing/index.ts

@@ -0,0 +1,191 @@
+/**
+ * 文件职责：营销中心 API 与 DTO 定义。
+ * 1. 维护优惠券列表、详情、保存、状态切换与删除契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 优惠券类型。 */
+export type MarketingCouponType = 'amount_off' | 'discount' | 'free_delivery';
+
+/** 列表展示状态。 */
+export type MarketingCouponDisplayStatus =
+  | 'disabled'
+  | 'ended'
+  | 'ongoing'
+  | 'upcoming';
+
+/** 编辑状态。 */
+export type MarketingCouponEditorStatus = 'disabled' | 'enabled';
+
+/** 有效期类型。 */
+export type MarketingCouponValidityType = 'days' | 'fixed';
+
+/** 适用渠道。 */
+export type MarketingCouponChannel = 'delivery' | 'dine_in' | 'pickup';
+
+/** 门店范围模式。 */
+export type MarketingCouponStoreScopeMode = 'all' | 'stores';
+
+/** 优惠券列表查询。 */
+export interface MarketingCouponListQuery {
+  couponType?: '' | MarketingCouponType;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: '' | MarketingCouponDisplayStatus;
+  storeId: string;
+}
+
+/** 优惠券详情查询。 */
+export interface MarketingCouponDetailQuery {
+  couponId: string;
+  storeId: string;
+}
+
+/** 保存优惠券请求。 */
+export interface SaveMarketingCouponDto {
+  channels: MarketingCouponChannel[];
+  couponType: MarketingCouponType;
+  id?: string;
+  minimumSpend: null | number;
+  name: string;
+  perUserLimit: null | number;
+  relativeValidDays: null | number;
+  status: MarketingCouponEditorStatus;
+  storeId: string;
+  storeIds?: string[];
+  storeScopeMode: MarketingCouponStoreScopeMode;
+  totalQuantity: number;
+  validFrom: null | string;
+  validTo: null | string;
+  validityType: MarketingCouponValidityType;
+  value: number;
+}
+
+/** 修改状态请求。 */
+export interface ChangeMarketingCouponStatusDto {
+  couponId: string;
+  status: MarketingCouponEditorStatus;
+  storeId: string;
+}
+
+/** 删除请求。 */
+export interface DeleteMarketingCouponDto {
+  couponId: string;
+  storeId: string;
+}
+
+/** 统计数据。 */
+export interface MarketingCouponStatsDto {
+  claimedCount: number;
+  ongoingCount: number;
+  redeemRate: number;
+  redeemedCount: number;
+  totalCount: number;
+}
+
+/** 列表项。 */
+export interface MarketingCouponListItemDto {
+  channels: MarketingCouponChannel[];
+  claimedQuantity: number;
+  couponType: MarketingCouponType;
+  displayStatus: MarketingCouponDisplayStatus;
+  id: string;
+  isDimmed: boolean;
+  minimumSpend: null | number;
+  name: string;
+  perUserLimit: null | number;
+  redeemedQuantity: number;
+  relativeValidDays: null | number;
+  storeIds: string[];
+  storeScopeMode: MarketingCouponStoreScopeMode;
+  totalQuantity: number;
+  updatedAt: string;
+  validFrom: null | string;
+  validTo: null | string;
+  value: number;
+}
+
+/** 列表结果。 */
+export interface MarketingCouponListResultDto {
+  items: MarketingCouponListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingCouponStatsDto;
+  total: number;
+}
+
+/** 详情数据。 */
+export interface MarketingCouponDetailDto {
+  channels: MarketingCouponChannel[];
+  claimedQuantity: number;
+  couponType: MarketingCouponType;
+  id: string;
+  minimumSpend: null | number;
+  name: string;
+  perUserLimit: null | number;
+  relativeValidDays: null | number;
+  status: MarketingCouponEditorStatus;
+  storeIds: string[];
+  storeScopeMode: MarketingCouponStoreScopeMode;
+  totalQuantity: number;
+  updatedAt: string;
+  validFrom: null | string;
+  validTo: null | string;
+  validityType: MarketingCouponValidityType;
+  value: number;
+}
+
+/** 获取优惠券列表。 */
+export async function getMarketingCouponListApi(
+  params: MarketingCouponListQuery,
+) {
+  return requestClient.get<MarketingCouponListResultDto>(
+    '/marketing/coupon/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取优惠券详情。 */
+export async function getMarketingCouponDetailApi(
+  params: MarketingCouponDetailQuery,
+) {
+  return requestClient.get<MarketingCouponDetailDto>(
+    '/marketing/coupon/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存优惠券。 */
+export async function saveMarketingCouponApi(data: SaveMarketingCouponDto) {
+  return requestClient.post<MarketingCouponDetailDto>(
+    '/marketing/coupon/save',
+    data,
+  );
+}
+
+/** 修改优惠券状态。 */
+export async function changeMarketingCouponStatusApi(
+  data: ChangeMarketingCouponStatusDto,
+) {
+  return requestClient.post<MarketingCouponDetailDto>(
+    '/marketing/coupon/status',
+    data,
+  );
+}
+
+/** 删除优惠券。 */
+export async function deleteMarketingCouponApi(data: DeleteMarketingCouponDto) {
+  return requestClient.post('/marketing/coupon/delete', data);
+}
+
+export * from './calendar';
+export * from './flash-sale';
+export * from './full-reduction';
+export * from './new-customer';
+export * from './punch-card';
+export * from './seckill';

apps/web-antd/src/api/marketing/new-customer.ts

@@ -0,0 +1,213 @@
+/**
+ * 文件职责：营销中心新客有礼 API 与 DTO 定义。
+ * 1. 维护新客有礼详情、配置保存、邀请记录分页与写入契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 礼包类型。 */
+export type MarketingNewCustomerGiftType = 'coupon' | 'direct';
+
+/** 券场景。 */
+export type MarketingNewCustomerCouponScene = 'invitee' | 'inviter' | 'welcome';
+
+/** 券类型。 */
+export type MarketingNewCustomerCouponType =
+  | 'amount_off'
+  | 'discount'
+  | 'free_shipping';
+
+/** 分享渠道。 */
+export type MarketingNewCustomerShareChannel =
+  | 'moments'
+  | 'sms'
+  | 'wechat_friend';
+
+/** 邀请订单状态。 */
+export type MarketingNewCustomerInviteOrderStatus = 'ordered' | 'pending_order';
+
+/** 邀请奖励状态。 */
+export type MarketingNewCustomerInviteRewardStatus = 'issued' | 'pending';
+
+/** 优惠券规则。 */
+export interface MarketingNewCustomerCouponRuleDto {
+  couponType: MarketingNewCustomerCouponType;
+  id: string;
+  minimumSpend: null | number;
+  scene: MarketingNewCustomerCouponScene;
+  sortOrder: number;
+  validDays: number;
+  value: null | number;
+}
+
+/** 新客有礼设置。 */
+export interface MarketingNewCustomerSettingsDto {
+  directMinimumSpend: null | number;
+  directReduceAmount: null | number;
+  giftEnabled: boolean;
+  giftType: MarketingNewCustomerGiftType;
+  inviteEnabled: boolean;
+  inviteeCoupons: MarketingNewCustomerCouponRuleDto[];
+  inviterCoupons: MarketingNewCustomerCouponRuleDto[];
+  shareChannels: MarketingNewCustomerShareChannel[];
+  storeId: string;
+  updatedAt: string;
+  welcomeCoupons: MarketingNewCustomerCouponRuleDto[];
+}
+
+/** 统计数据。 */
+export interface MarketingNewCustomerStatsDto {
+  firstOrderConversionRate: number;
+  firstOrderedCount: number;
+  giftClaimRate: number;
+  giftClaimedCount: number;
+  monthlyGrowthCount: number;
+  monthlyGrowthRatePercent: number;
+  monthlyNewCustomers: number;
+}
+
+/** 邀请记录。 */
+export interface MarketingNewCustomerInviteRecordDto {
+  id: string;
+  inviteeName: string;
+  inviteTime: string;
+  inviterName: string;
+  orderStatus: MarketingNewCustomerInviteOrderStatus;
+  rewardIssuedAt: null | string;
+  rewardStatus: MarketingNewCustomerInviteRewardStatus;
+  sourceChannel?: string;
+}
+
+/** 邀请记录分页。 */
+export interface MarketingNewCustomerInviteRecordListResultDto {
+  items: MarketingNewCustomerInviteRecordDto[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+
+/** 新客有礼详情。 */
+export interface MarketingNewCustomerDetailDto {
+  inviteRecords: MarketingNewCustomerInviteRecordListResultDto;
+  settings: MarketingNewCustomerSettingsDto;
+  stats: MarketingNewCustomerStatsDto;
+}
+
+/** 新客有礼详情查询。 */
+export interface MarketingNewCustomerDetailQuery {
+  recordPage?: number;
+  recordPageSize?: number;
+  storeId: string;
+}
+
+/** 邀请记录查询。 */
+export interface MarketingNewCustomerInviteRecordListQuery {
+  page: number;
+  pageSize: number;
+  storeId: string;
+}
+
+/** 保存券规则项。 */
+export interface SaveMarketingNewCustomerCouponRuleDto {
+  couponType: MarketingNewCustomerCouponType;
+  minimumSpend: null | number;
+  validDays: number;
+  value: null | number;
+}
+
+/** 保存新客有礼配置请求。 */
+export interface SaveMarketingNewCustomerSettingsDto {
+  directMinimumSpend: null | number;
+  directReduceAmount: null | number;
+  giftEnabled: boolean;
+  giftType: MarketingNewCustomerGiftType;
+  inviteEnabled: boolean;
+  inviteeCoupons: SaveMarketingNewCustomerCouponRuleDto[];
+  inviterCoupons: SaveMarketingNewCustomerCouponRuleDto[];
+  shareChannels: MarketingNewCustomerShareChannel[];
+  storeId: string;
+  welcomeCoupons: SaveMarketingNewCustomerCouponRuleDto[];
+}
+
+/** 写入邀请记录请求。 */
+export interface WriteMarketingNewCustomerInviteRecordDto {
+  inviteeName: string;
+  inviteTime: string;
+  inviterName: string;
+  orderStatus: MarketingNewCustomerInviteOrderStatus;
+  rewardIssuedAt: null | string;
+  rewardStatus: MarketingNewCustomerInviteRewardStatus;
+  sourceChannel?: string;
+  storeId: string;
+}
+
+/** 新客成长记录。 */
+export interface MarketingNewCustomerGrowthRecordDto {
+  customerKey: string;
+  customerName?: string;
+  firstOrderAt: null | string;
+  giftClaimedAt: null | string;
+  id: string;
+  registeredAt: string;
+  sourceChannel?: string;
+}
+
+/** 写入成长记录请求。 */
+export interface WriteMarketingNewCustomerGrowthRecordDto {
+  customerKey: string;
+  customerName?: string;
+  firstOrderAt: null | string;
+  giftClaimedAt: null | string;
+  registeredAt: string;
+  sourceChannel?: string;
+  storeId: string;
+}
+
+/** 获取新客有礼详情。 */
+export async function getMarketingNewCustomerDetailApi(
+  params: MarketingNewCustomerDetailQuery,
+) {
+  return requestClient.get<MarketingNewCustomerDetailDto>(
+    '/marketing/new-customer/detail',
+    { params },
+  );
+}
+
+/** 保存新客有礼配置。 */
+export async function saveMarketingNewCustomerSettingsApi(
+  data: SaveMarketingNewCustomerSettingsDto,
+) {
+  return requestClient.post<MarketingNewCustomerSettingsDto>(
+    '/marketing/new-customer/save',
+    data,
+  );
+}
+
+/** 获取邀请记录分页。 */
+export async function getMarketingNewCustomerInviteRecordListApi(
+  params: MarketingNewCustomerInviteRecordListQuery,
+) {
+  return requestClient.get<MarketingNewCustomerInviteRecordListResultDto>(
+    '/marketing/new-customer/invite-record/list',
+    { params },
+  );
+}
+
+/** 写入邀请记录。 */
+export async function writeMarketingNewCustomerInviteRecordApi(
+  data: WriteMarketingNewCustomerInviteRecordDto,
+) {
+  return requestClient.post<MarketingNewCustomerInviteRecordDto>(
+    '/marketing/new-customer/invite-record/write',
+    data,
+  );
+}
+
+/** 写入成长记录。 */
+export async function writeMarketingNewCustomerGrowthRecordApi(
+  data: WriteMarketingNewCustomerGrowthRecordDto,
+) {
+  return requestClient.post<MarketingNewCustomerGrowthRecordDto>(
+    '/marketing/new-customer/growth-record/write',
+    data,
+  );
+}

apps/web-antd/src/api/marketing/punch-card.ts

@@ -0,0 +1,334 @@
+/**
+ * 文件职责：营销中心次卡管理 API 与 DTO 定义。
+ * 1. 维护次卡列表、详情、保存、状态、删除、使用记录及导出契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 次卡状态。 */
+export type MarketingPunchCardStatus = 'disabled' | 'enabled';
+
+/** 有效期类型。 */
+export type MarketingPunchCardValidityType = 'days' | 'range';
+
+/** 适用范围类型。 */
+export type MarketingPunchCardScopeType =
+  | 'all'
+  | 'category'
+  | 'product'
+  | 'tag';
+
+/** 使用模式。 */
+export type MarketingPunchCardUsageMode = 'cap' | 'free';
+
+/** 过期策略。 */
+export type MarketingPunchCardExpireStrategy = 'invalidate' | 'refund';
+
+/** 使用记录展示状态。 */
+export type MarketingPunchCardUsageDisplayStatus =
+  | 'almost_used_up'
+  | 'expired'
+  | 'normal'
+  | 'used_up';
+
+/** 使用记录筛选状态。 */
+export type MarketingPunchCardUsageFilterStatus =
+  | 'expired'
+  | 'normal'
+  | 'used_up';
+
+/** 次卡范围。 */
+export interface MarketingPunchCardScopeDto {
+  categoryIds: string[];
+  productIds: string[];
+  scopeType: MarketingPunchCardScopeType;
+  tagIds: string[];
+}
+
+/** 次卡模板统计。 */
+export interface MarketingPunchCardStatsDto {
+  activeInUseCount: number;
+  onSaleCount: number;
+  totalRevenueAmount: number;
+  totalSoldCount: number;
+}
+
+/** 次卡列表项。 */
+export interface MarketingPunchCardListItemDto {
+  activeCount: number;
+  coverImageUrl?: string;
+  dailyLimit: null | number;
+  id: string;
+  isDimmed: boolean;
+  name: string;
+  originalPrice: null | number;
+  revenueAmount: number;
+  salePrice: number;
+  scopeType: MarketingPunchCardScopeType;
+  soldCount: number;
+  status: MarketingPunchCardStatus;
+  totalTimes: number;
+  updatedAt: string;
+  usageCapAmount: null | number;
+  usageMode: MarketingPunchCardUsageMode;
+  validitySummary: string;
+}
+
+/** 次卡列表结果。 */
+export interface MarketingPunchCardListResultDto {
+  items: MarketingPunchCardListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingPunchCardStatsDto;
+  totalCount: number;
+}
+
+/** 次卡详情。 */
+export interface MarketingPunchCardDetailDto {
+  activeCount: number;
+  allowTransfer: boolean;
+  coverImageUrl?: string;
+  dailyLimit: null | number;
+  description?: string;
+  expireStrategy: MarketingPunchCardExpireStrategy;
+  id: string;
+  name: string;
+  notifyChannels: string[];
+  originalPrice: null | number;
+  perOrderLimit: null | number;
+  perUserPurchaseLimit: null | number;
+  revenueAmount: number;
+  salePrice: number;
+  scope: MarketingPunchCardScopeDto;
+  soldCount: number;
+  status: MarketingPunchCardStatus;
+  storeId: string;
+  totalTimes: number;
+  updatedAt: string;
+  usageCapAmount: null | number;
+  usageMode: MarketingPunchCardUsageMode;
+  validityDays: null | number;
+  validityType: MarketingPunchCardValidityType;
+  validFrom: null | string;
+  validTo: null | string;
+}
+
+/** 保存次卡请求。 */
+export interface SaveMarketingPunchCardDto {
+  allowTransfer: boolean;
+  coverImageUrl?: string;
+  dailyLimit: null | number;
+  description?: string;
+  expireStrategy: MarketingPunchCardExpireStrategy;
+  id?: string;
+  name: string;
+  notifyChannels: string[];
+  originalPrice: null | number;
+  perOrderLimit: null | number;
+  perUserPurchaseLimit: null | number;
+  salePrice: number;
+  scopeCategoryIds: string[];
+  scopeProductIds: string[];
+  scopeTagIds: string[];
+  scopeType: MarketingPunchCardScopeType;
+  storeId: string;
+  totalTimes: number;
+  usageCapAmount: null | number;
+  usageMode: MarketingPunchCardUsageMode;
+  validityDays: null | number;
+  validityType: MarketingPunchCardValidityType;
+  validFrom: null | string;
+  validTo: null | string;
+}
+
+/** 修改状态请求。 */
+export interface ChangeMarketingPunchCardStatusDto {
+  punchCardId: string;
+  status: MarketingPunchCardStatus;
+  storeId: string;
+}
+
+/** 删除次卡请求。 */
+export interface DeleteMarketingPunchCardDto {
+  punchCardId: string;
+  storeId: string;
+}
+
+/** 次卡列表查询。 */
+export interface MarketingPunchCardListQuery {
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: '' | MarketingPunchCardStatus;
+  storeId: string;
+}
+
+/** 次卡详情查询。 */
+export interface MarketingPunchCardDetailQuery {
+  punchCardId: string;
+  storeId: string;
+}
+
+/** 使用记录统计。 */
+export interface MarketingPunchCardUsageStatsDto {
+  expiringSoonCount: number;
+  monthUsedCount: number;
+  todayUsedCount: number;
+}
+
+/** 次卡选项。 */
+export interface MarketingPunchCardTemplateOptionDto {
+  name: string;
+  templateId: string;
+}
+
+/** 使用记录项。 */
+export interface MarketingPunchCardUsageRecordDto {
+  displayStatus: MarketingPunchCardUsageDisplayStatus;
+  extraPayAmount: null | number;
+  id: string;
+  memberName: string;
+  memberPhoneMasked: string;
+  productName: string;
+  punchCardId: string;
+  punchCardInstanceId: string;
+  punchCardName: string;
+  recordNo: string;
+  remainingTimesAfterUse: number;
+  totalTimes: number;
+  usedAt: string;
+  usedTimes: number;
+}
+
+/** 使用记录列表结果。 */
+export interface MarketingPunchCardUsageRecordListResultDto {
+  items: MarketingPunchCardUsageRecordDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingPunchCardUsageStatsDto;
+  templateOptions: MarketingPunchCardTemplateOptionDto[];
+  totalCount: number;
+}
+
+/** 使用记录查询参数。 */
+export interface MarketingPunchCardUsageRecordListQuery {
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  punchCardId?: string;
+  status?: '' | MarketingPunchCardUsageFilterStatus;
+  storeId: string;
+}
+
+/** 使用记录导出参数。 */
+export interface ExportMarketingPunchCardUsageRecordQuery {
+  keyword?: string;
+  punchCardId?: string;
+  status?: '' | MarketingPunchCardUsageFilterStatus;
+  storeId: string;
+}
+
+/** 使用记录导出回执。 */
+export interface MarketingPunchCardUsageRecordExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 写入使用记录请求。 */
+export interface WriteMarketingPunchCardUsageRecordDto {
+  extraPayAmount: null | number;
+  memberName?: string;
+  memberPhoneMasked?: string;
+  productName: string;
+  punchCardId: string;
+  punchCardInstanceId?: string;
+  punchCardInstanceNo?: string;
+  storeId: string;
+  usedAt?: string;
+  usedTimes: number;
+}
+
+/** 查询次卡列表。 */
+export async function getMarketingPunchCardListApi(
+  params: MarketingPunchCardListQuery,
+) {
+  return requestClient.get<MarketingPunchCardListResultDto>(
+    '/marketing/punch-card/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询次卡详情。 */
+export async function getMarketingPunchCardDetailApi(
+  params: MarketingPunchCardDetailQuery,
+) {
+  return requestClient.get<MarketingPunchCardDetailDto>(
+    '/marketing/punch-card/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存次卡。 */
+export async function saveMarketingPunchCardApi(
+  data: SaveMarketingPunchCardDto,
+) {
+  return requestClient.post<MarketingPunchCardDetailDto>(
+    '/marketing/punch-card/save',
+    data,
+  );
+}
+
+/** 修改次卡状态。 */
+export async function changeMarketingPunchCardStatusApi(
+  data: ChangeMarketingPunchCardStatusDto,
+) {
+  return requestClient.post<MarketingPunchCardDetailDto>(
+    '/marketing/punch-card/status',
+    data,
+  );
+}
+
+/** 删除次卡。 */
+export async function deleteMarketingPunchCardApi(
+  data: DeleteMarketingPunchCardDto,
+) {
+  return requestClient.post('/marketing/punch-card/delete', data);
+}
+
+/** 查询使用记录。 */
+export async function getMarketingPunchCardUsageRecordListApi(
+  params: MarketingPunchCardUsageRecordListQuery,
+) {
+  return requestClient.get<MarketingPunchCardUsageRecordListResultDto>(
+    '/marketing/punch-card/usage-record/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出使用记录。 */
+export async function exportMarketingPunchCardUsageRecordApi(
+  params: ExportMarketingPunchCardUsageRecordQuery,
+) {
+  return requestClient.get<MarketingPunchCardUsageRecordExportDto>(
+    '/marketing/punch-card/usage-record/export',
+    {
+      params,
+    },
+  );
+}
+
+/** 写入使用记录。 */
+export async function writeMarketingPunchCardUsageRecordApi(
+  data: WriteMarketingPunchCardUsageRecordDto,
+) {
+  return requestClient.post<MarketingPunchCardUsageRecordDto>(
+    '/marketing/punch-card/usage-record/write',
+    data,
+  );
+}

apps/web-antd/src/api/marketing/seckill.ts

@@ -0,0 +1,271 @@
+/**
+ * 文件职责：营销中心秒杀活动 API 与 DTO 定义。
+ * 1. 维护秒杀活动列表、详情、保存、状态切换、删除与选品契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 活动展示状态。 */
+export type MarketingSeckillDisplayStatus = 'ended' | 'ongoing' | 'upcoming';
+
+/** 活动编辑状态。 */
+export type MarketingSeckillEditorStatus = 'active' | 'completed';
+
+/** 秒杀活动类型。 */
+export type MarketingSeckillActivityType = 'hourly' | 'timed';
+
+/** 适用渠道。 */
+export type MarketingSeckillChannel = 'delivery' | 'dine_in' | 'pickup';
+
+/** 商品状态。 */
+export type MarketingSeckillProductStatus =
+  | 'off_shelf'
+  | 'on_sale'
+  | 'sold_out';
+
+/** 场次。 */
+export interface MarketingSeckillSessionDto {
+  durationMinutes: number;
+  startTime: string;
+}
+
+/** 秒杀商品。 */
+export interface MarketingSeckillProductDto {
+  categoryId: string;
+  categoryName: string;
+  name: string;
+  originalPrice: number;
+  perUserLimit: null | number;
+  productId: string;
+  seckillPrice: number;
+  soldCount: number;
+  spuCode: string;
+  status: MarketingSeckillProductStatus;
+  stockLimit: number;
+}
+
+/** 活动指标。 */
+export interface MarketingSeckillMetricsDto {
+  conversionRate: number;
+  dealCount: number;
+  monthlySeckillSalesCount: number;
+  participantCount: number;
+}
+
+/** 列表查询参数。 */
+export interface MarketingSeckillListQuery {
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: '' | MarketingSeckillDisplayStatus;
+  storeId?: string;
+}
+
+/** 详情查询参数。 */
+export interface MarketingSeckillDetailQuery {
+  activityId: string;
+  storeId: string;
+}
+
+/** 保存请求。 */
+export interface SaveMarketingSeckillDto {
+  activityType: MarketingSeckillActivityType;
+  channels: MarketingSeckillChannel[];
+  endDate?: string;
+  id?: string;
+  metrics?: MarketingSeckillMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  preheatEnabled: boolean;
+  preheatHours: null | number;
+  products: Array<{
+    perUserLimit: null | number;
+    productId: string;
+    seckillPrice: number;
+    stockLimit: number;
+  }>;
+  sessions: MarketingSeckillSessionDto[];
+  startDate?: string;
+  storeId: string;
+  timeEnd?: string;
+  timeStart?: string;
+}
+
+/** 状态修改请求。 */
+export interface ChangeMarketingSeckillStatusDto {
+  activityId: string;
+  status: MarketingSeckillEditorStatus;
+  storeId: string;
+}
+
+/** 删除请求。 */
+export interface DeleteMarketingSeckillDto {
+  activityId: string;
+  storeId: string;
+}
+
+/** 列表统计。 */
+export interface MarketingSeckillStatsDto {
+  conversionRate: number;
+  monthlySeckillSalesCount: number;
+  ongoingCount: number;
+  totalCount: number;
+}
+
+/** 列表项。 */
+export interface MarketingSeckillListItemDto {
+  activityType: MarketingSeckillActivityType;
+  channels: MarketingSeckillChannel[];
+  displayStatus: MarketingSeckillDisplayStatus;
+  endDate?: string;
+  id: string;
+  isDimmed: boolean;
+  metrics: MarketingSeckillMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  preheatEnabled: boolean;
+  preheatHours: null | number;
+  products: MarketingSeckillProductDto[];
+  sessions: MarketingSeckillSessionDto[];
+  startDate?: string;
+  status: MarketingSeckillEditorStatus;
+  storeIds: string[];
+  timeEnd?: string;
+  timeStart?: string;
+  updatedAt: string;
+}
+
+/** 列表结果。 */
+export interface MarketingSeckillListResultDto {
+  items: MarketingSeckillListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingSeckillStatsDto;
+  total: number;
+}
+
+/** 详情数据。 */
+export interface MarketingSeckillDetailDto {
+  activityType: MarketingSeckillActivityType;
+  channels: MarketingSeckillChannel[];
+  displayStatus: MarketingSeckillDisplayStatus;
+  endDate?: string;
+  id: string;
+  metrics: MarketingSeckillMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  preheatEnabled: boolean;
+  preheatHours: null | number;
+  products: MarketingSeckillProductDto[];
+  sessions: MarketingSeckillSessionDto[];
+  startDate?: string;
+  status: MarketingSeckillEditorStatus;
+  storeIds: string[];
+  timeEnd?: string;
+  timeStart?: string;
+  updatedAt: string;
+}
+
+/** 选品分类查询参数。 */
+export interface MarketingSeckillPickerCategoryQuery {
+  storeId: string;
+}
+
+/** 选品分类项。 */
+export interface MarketingSeckillPickerCategoryItemDto {
+  id: string;
+  name: string;
+  productCount: number;
+}
+
+/** 选品商品查询参数。 */
+export interface MarketingSeckillPickerProductQuery {
+  categoryId?: string;
+  keyword?: string;
+  limit?: number;
+  storeId: string;
+}
+
+/** 选品商品项。 */
+export interface MarketingSeckillPickerProductItemDto {
+  categoryId: string;
+  categoryName: string;
+  id: string;
+  name: string;
+  price: number;
+  spuCode: string;
+  status: MarketingSeckillProductStatus;
+  stock: number;
+}
+
+/** 获取列表。 */
+export async function getMarketingSeckillListApi(
+  params: MarketingSeckillListQuery,
+) {
+  return requestClient.get<MarketingSeckillListResultDto>(
+    '/marketing/seckill/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取详情。 */
+export async function getMarketingSeckillDetailApi(
+  params: MarketingSeckillDetailQuery,
+) {
+  return requestClient.get<MarketingSeckillDetailDto>(
+    '/marketing/seckill/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存活动。 */
+export async function saveMarketingSeckillApi(data: SaveMarketingSeckillDto) {
+  return requestClient.post<MarketingSeckillDetailDto>(
+    '/marketing/seckill/save',
+    data,
+  );
+}
+
+/** 修改状态。 */
+export async function changeMarketingSeckillStatusApi(
+  data: ChangeMarketingSeckillStatusDto,
+) {
+  return requestClient.post<MarketingSeckillDetailDto>(
+    '/marketing/seckill/status',
+    data,
+  );
+}
+
+/** 删除活动。 */
+export async function deleteMarketingSeckillApi(
+  data: DeleteMarketingSeckillDto,
+) {
+  return requestClient.post('/marketing/seckill/delete', data);
+}
+
+/** 获取选品分类。 */
+export async function getMarketingSeckillPickerCategoriesApi(
+  params: MarketingSeckillPickerCategoryQuery,
+) {
+  return requestClient.get<MarketingSeckillPickerCategoryItemDto[]>(
+    '/marketing/seckill/picker/categories',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取选品商品。 */
+export async function getMarketingSeckillPickerProductsApi(
+  params: MarketingSeckillPickerProductQuery,
+) {
+  return requestClient.get<MarketingSeckillPickerProductItemDto[]>(
+    '/marketing/seckill/picker/products',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/member/index.ts

@@ -0,0 +1,287 @@
+/**
+ * 文件职责：会员中心会员管理 API 契约定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 会员列表筛选参数。 */
+export interface MemberListFilterQuery {
+  keyword?: string;
+  storeId: string;
+  tierId?: string;
+}
+
+/** 会员列表分页参数。 */
+export interface MemberListQuery extends MemberListFilterQuery {
+  page: number;
+  pageSize: number;
+}
+
+/** 会员列表行。 */
+export interface MemberListItemDto {
+  avatarColor: string;
+  avatarText: string;
+  isDormant: boolean;
+  lastOrderAt: string;
+  memberId: string;
+  mobileMasked: string;
+  name: string;
+  orderCount: number;
+  pointsBalance: number;
+  storedBalance: number;
+  tierColorHex: string;
+  tierId?: string;
+  tierName: string;
+  totalAmount: number;
+}
+
+/** 会员列表结果。 */
+export interface MemberListResultDto {
+  items: MemberListItemDto[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 会员列表统计。 */
+export interface MemberListStatsDto {
+  activeMembers: number;
+  dormantMembers: number;
+  monthlyNewMembers: number;
+  totalMembers: number;
+}
+
+/** 最近订单。 */
+export interface MemberRecentOrderDto {
+  amount: number;
+  orderNo: string;
+  orderedAt: string;
+  statusText: string;
+}
+
+/** 会员详情。 */
+export interface MemberDetailDto {
+  avatarColor: string;
+  avatarText: string;
+  averageAmount: number;
+  joinedAt: string;
+  memberId: string;
+  mobileMasked: string;
+  name: string;
+  orderCount: number;
+  pointsBalance: number;
+  recentOrders: MemberRecentOrderDto[];
+  storedBalance: number;
+  storedGiftBalance: number;
+  storedRechargeBalance: number;
+  tags: string[];
+  tierColorHex: string;
+  tierId?: string;
+  tierName: string;
+  totalAmount: number;
+}
+
+/** 会员导出回执。 */
+export interface MemberExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 会员等级列表项。 */
+export interface MemberTierListItemDto {
+  canDelete: boolean;
+  colorHex: string;
+  conditionText: string;
+  iconKey: string;
+  isDefault: boolean;
+  memberCount: number;
+  name: string;
+  perks: string[];
+  sortOrder: number;
+  tierId: string;
+}
+
+/** 升降级规则。 */
+export interface MemberTierRuleDto {
+  downgradeWindowDays: number;
+  upgradeAmountThreshold?: number;
+  upgradeOrderCountThreshold?: number;
+  upgradeRuleType: 'amount' | 'both' | 'count' | 'none';
+}
+
+/** 折扣权益。 */
+export interface MemberTierDiscountBenefitDto {
+  discountRate?: number;
+  enabled: boolean;
+}
+
+/** 积分倍率权益。 */
+export interface MemberTierPointMultiplierBenefitDto {
+  enabled: boolean;
+  multiplier?: number;
+}
+
+/** 生日特权。 */
+export interface MemberTierBirthdayBenefitDto {
+  couponTemplateIds: string[];
+  doublePointsEnabled: boolean;
+  enabled: boolean;
+}
+
+/** 每月赠券。 */
+export interface MemberTierMonthlyCouponBenefitDto {
+  couponTemplateIds: string[];
+  enabled: boolean;
+  grantDay: number;
+}
+
+/** 免配送费权益。 */
+export interface MemberTierFreeDeliveryBenefitDto {
+  enabled: boolean;
+  monthlyFreeTimes: number;
+}
+
+/** 等级权益。 */
+export interface MemberTierBenefitsDto {
+  birthday: MemberTierBirthdayBenefitDto;
+  discount: MemberTierDiscountBenefitDto;
+  exclusiveServiceEnabled: boolean;
+  freeDelivery: MemberTierFreeDeliveryBenefitDto;
+  monthlyCoupon: MemberTierMonthlyCouponBenefitDto;
+  pointMultiplier: MemberTierPointMultiplierBenefitDto;
+  priorityDeliveryEnabled: boolean;
+}
+
+/** 等级详情。 */
+export interface MemberTierDetailDto {
+  benefits: MemberTierBenefitsDto;
+  canDelete: boolean;
+  colorHex: string;
+  iconKey: string;
+  isDefault: boolean;
+  name: string;
+  rule: MemberTierRuleDto;
+  sortOrder: number;
+  tierId?: string;
+}
+
+/** 保存等级请求。 */
+export interface SaveMemberTierPayload {
+  benefits: MemberTierBenefitsDto;
+  colorHex: string;
+  iconKey: string;
+  isDefault: boolean;
+  name: string;
+  rule: MemberTierRuleDto;
+  sortOrder: number;
+  tierId?: string;
+}
+
+/** 会员日配置。 */
+export interface MemberDaySettingDto {
+  extraDiscountRate: number;
+  isEnabled: boolean;
+  weekday: number;
+}
+
+/** 优惠券选择项。 */
+export interface MemberCouponPickerItemDto {
+  couponTemplateId: string;
+  couponType: string;
+  displayText: string;
+  minimumSpend?: number;
+  name: string;
+  value: number;
+}
+
+/** 查询会员列表。 */
+export async function getMemberListApi(params: MemberListQuery) {
+  return requestClient.get<MemberListResultDto>('/member/list/list', {
+    params,
+  });
+}
+
+/** 查询会员列表统计。 */
+export async function getMemberListStatsApi(params: MemberListFilterQuery) {
+  return requestClient.get<MemberListStatsDto>('/member/list/stats', {
+    params,
+  });
+}
+
+/** 查询会员详情。 */
+export async function getMemberDetailApi(params: {
+  memberId: string;
+  storeId: string;
+}) {
+  return requestClient.get<MemberDetailDto>('/member/list/detail', {
+    params,
+  });
+}
+
+/** 保存会员标签。 */
+export async function saveMemberTagsApi(payload: {
+  memberId: string;
+  storeId?: string;
+  tags: string[];
+}) {
+  return requestClient.post('/member/list/tags', payload);
+}
+
+/** 导出会员 CSV。 */
+export async function exportMemberCsvApi(params: MemberListFilterQuery) {
+  return requestClient.get<MemberExportDto>('/member/list/export', {
+    params,
+  });
+}
+
+/** 查询会员等级列表。 */
+export async function getMemberTierListApi() {
+  return requestClient.get<MemberTierListItemDto[]>('/member/tier/list');
+}
+
+/** 查询会员等级详情。 */
+export async function getMemberTierDetailApi(params: { tierId?: string }) {
+  return requestClient.get<MemberTierDetailDto>('/member/tier/detail', {
+    params,
+  });
+}
+
+/** 保存会员等级。 */
+export async function saveMemberTierApi(payload: SaveMemberTierPayload) {
+  return requestClient.post<MemberTierDetailDto>('/member/tier/save', payload);
+}
+
+/** 删除会员等级。 */
+export async function deleteMemberTierApi(payload: { tierId: string }) {
+  return requestClient.post('/member/tier/delete', payload);
+}
+
+/** 查询会员日配置。 */
+export async function getMemberDaySettingApi() {
+  return requestClient.get<MemberDaySettingDto>('/member/tier/day-setting');
+}
+
+/** 保存会员日配置。 */
+export async function saveMemberDaySettingApi(payload: MemberDaySettingDto) {
+  return requestClient.post<MemberDaySettingDto>(
+    '/member/tier/day-setting',
+    payload,
+  );
+}
+
+/** 查询优惠券选择器列表。 */
+export async function getMemberCouponPickerApi(params: {
+  keyword?: string;
+  storeId?: string;
+}) {
+  return requestClient.get<MemberCouponPickerItemDto[]>(
+    '/member/tier/coupon-picker',
+    {
+      params,
+    },
+  );
+}
+
+export * from './message-reach';
+export * from './points-mall';
+export * from './stored-card';

apps/web-antd/src/api/member/message-reach.ts

@@ -0,0 +1,283 @@
+/**
+ * 文件职责：会员消息触达模块 API 契约定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 消息状态。 */
+export type MemberMessageReachStatus =
+  | 'draft'
+  | 'failed'
+  | 'pending'
+  | 'sending'
+  | 'sent';
+
+/** 消息渠道。 */
+export type MemberMessageReachChannel = 'inapp' | 'sms' | 'wechat-mini';
+
+/** 目标人群类型。 */
+export type MemberMessageAudienceType = 'all' | 'tag';
+
+/** 发送时间类型。 */
+export type MemberMessageScheduleType = 'immediate' | 'scheduled';
+
+/** 模板分类。 */
+export type MemberMessageTemplateCategory = 'marketing' | 'notice' | 'recall';
+
+/** 页面统计。 */
+export interface MemberMessageReachStatsDto {
+  conversionRate: number;
+  monthlySentCount: number;
+  openRate: number;
+  reachMemberCount: number;
+}
+
+/** 消息列表查询。 */
+export interface MemberMessageReachListQuery {
+  channel?: MemberMessageReachChannel;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: MemberMessageReachStatus;
+}
+
+/** 消息列表项。 */
+export interface MemberMessageReachListItemDto {
+  audienceText: string;
+  channels: MemberMessageReachChannel[];
+  conversionRate: number;
+  estimatedReachCount: number;
+  messageId: string;
+  openRate: number;
+  scheduledAt?: string;
+  sentAt?: string;
+  status: MemberMessageReachStatus;
+  title: string;
+}
+
+/** 消息列表结果。 */
+export interface MemberMessageReachListResultDto {
+  items: MemberMessageReachListItemDto[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+
+/** 收件明细。 */
+export interface MemberMessageReachRecipientDto {
+  channel: MemberMessageReachChannel;
+  convertedAt?: string;
+  errorMessage?: string;
+  memberId: string;
+  mobile?: string;
+  openId?: string;
+  readAt?: string;
+  sentAt?: string;
+  status: 'failed' | 'pending' | 'sent';
+}
+
+/** 消息详情。 */
+export interface MemberMessageReachDetailDto {
+  audienceTags: string[];
+  audienceText: string;
+  audienceType: MemberMessageAudienceType;
+  channels: MemberMessageReachChannel[];
+  content: string;
+  conversionRate: number;
+  convertedCount: number;
+  estimatedReachCount: number;
+  lastError?: string;
+  messageId: string;
+  openRate: number;
+  readCount: number;
+  recipients: MemberMessageReachRecipientDto[];
+  scheduleType: MemberMessageScheduleType;
+  scheduledAt?: string;
+  sentAt?: string;
+  sentCount: number;
+  status: MemberMessageReachStatus;
+  templateId?: string;
+  title: string;
+}
+
+/** 保存消息请求。 */
+export interface SaveMemberMessageReachPayload {
+  audienceTags: string[];
+  audienceType: MemberMessageAudienceType;
+  channels: MemberMessageReachChannel[];
+  content: string;
+  messageId?: string;
+  scheduleType: MemberMessageScheduleType;
+  scheduledAt?: string;
+  storeId?: string;
+  submitAction: 'draft' | 'send';
+  templateId?: string;
+  title: string;
+}
+
+/** 删除消息请求。 */
+export interface DeleteMemberMessageReachPayload {
+  messageId: string;
+}
+
+/** 调度元信息。 */
+export interface MemberMessageDispatchMetaDto {
+  hangfireJobId?: string;
+  messageId: string;
+  scheduleType: MemberMessageScheduleType;
+  scheduledAt?: string;
+  status: MemberMessageReachStatus;
+}
+
+/** 目标估算请求。 */
+export interface EstimateMemberMessageAudiencePayload {
+  audienceType: MemberMessageAudienceType;
+  tags: string[];
+}
+
+/** 目标估算响应。 */
+export interface MemberMessageAudienceEstimateDto {
+  reachCount: number;
+}
+
+/** 模板列表查询。 */
+export interface MemberMessageTemplateListQuery {
+  category?: MemberMessageTemplateCategory;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+}
+
+/** 模板 DTO。 */
+export interface MemberMessageTemplateDto {
+  category: MemberMessageTemplateCategory;
+  content: string;
+  lastUsedAt?: string;
+  name: string;
+  templateId: string;
+  usageCount: number;
+}
+
+/** 模板列表结果。 */
+export interface MemberMessageTemplateListResultDto {
+  items: MemberMessageTemplateDto[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+
+/** 保存模板请求。 */
+export interface SaveMemberMessageTemplatePayload {
+  category: MemberMessageTemplateCategory;
+  content: string;
+  name: string;
+  templateId?: string;
+}
+
+/** 删除模板请求。 */
+export interface DeleteMemberMessageTemplatePayload {
+  templateId: string;
+}
+
+/** 查询页面统计。 */
+export async function getMemberMessageReachStatsApi(params?: {
+  storeId?: string;
+}) {
+  return requestClient.get<MemberMessageReachStatsDto>(
+    '/member/message-reach/stats',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询消息列表。 */
+export async function getMemberMessageReachListApi(
+  params: MemberMessageReachListQuery,
+) {
+  return requestClient.get<MemberMessageReachListResultDto>(
+    '/member/message-reach/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询消息详情。 */
+export async function getMemberMessageReachDetailApi(params: {
+  messageId: string;
+}) {
+  return requestClient.get<MemberMessageReachDetailDto>(
+    '/member/message-reach/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存消息。 */
+export async function saveMemberMessageReachApi(
+  payload: SaveMemberMessageReachPayload,
+) {
+  return requestClient.post<MemberMessageDispatchMetaDto>(
+    '/member/message-reach/save',
+    payload,
+  );
+}
+
+/** 删除消息。 */
+export async function deleteMemberMessageReachApi(
+  payload: DeleteMemberMessageReachPayload,
+) {
+  return requestClient.post('/member/message-reach/delete', payload);
+}
+
+/** 估算触达人数。 */
+export async function estimateMemberMessageAudienceApi(
+  payload: EstimateMemberMessageAudiencePayload,
+) {
+  return requestClient.post<MemberMessageAudienceEstimateDto>(
+    '/member/message-reach/audience/estimate',
+    payload,
+  );
+}
+
+/** 查询模板列表。 */
+export async function getMemberMessageTemplateListApi(
+  params: MemberMessageTemplateListQuery,
+) {
+  return requestClient.get<MemberMessageTemplateListResultDto>(
+    '/member/message-reach/template/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询模板详情。 */
+export async function getMemberMessageTemplateDetailApi(params: {
+  templateId: string;
+}) {
+  return requestClient.get<MemberMessageTemplateDto>(
+    '/member/message-reach/template/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存模板。 */
+export async function saveMemberMessageTemplateApi(
+  payload: SaveMemberMessageTemplatePayload,
+) {
+  return requestClient.post<MemberMessageTemplateDto>(
+    '/member/message-reach/template/save',
+    payload,
+  );
+}
+
+/** 删除模板。 */
+export async function deleteMemberMessageTemplateApi(
+  payload: DeleteMemberMessageTemplatePayload,
+) {
+  return requestClient.post('/member/message-reach/template/delete', payload);
+}

apps/web-antd/src/api/member/points-mall.ts

@@ -0,0 +1,372 @@
+/**
+ * 文件职责：会员中心积分商城 API 契约定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 兑换类型。 */
+export type MemberPointMallRedeemType = 'coupon' | 'physical' | 'product';
+
+/** 兑换方式。 */
+export type MemberPointMallExchangeType = 'mixed' | 'points';
+
+/** 商品状态。 */
+export type MemberPointMallProductStatus = 'disabled' | 'enabled';
+
+/** 积分有效期模式。 */
+export type MemberPointMallExpiryMode = 'permanent' | 'yearly_clear';
+
+/** 通知渠道。 */
+export type MemberPointMallNotifyChannel = 'in_app' | 'sms';
+
+/** 实物领取方式。 */
+export type MemberPointMallPickupMethod = 'delivery' | 'store_pickup';
+
+/** 兑换记录状态。 */
+export type MemberPointMallRecordStatus =
+  | 'canceled'
+  | 'completed'
+  | 'issued'
+  | 'pending_pickup';
+
+/** 核销方式。 */
+export type MemberPointMallVerifyMethod = 'manual' | 'scan';
+
+/** 规则详情查询。 */
+export interface MemberPointMallRuleDetailQuery {
+  storeId: string;
+}
+
+/** 规则模型。 */
+export interface MemberPointMallRuleDto {
+  consumeAmountPerStep: number;
+  consumeRewardPointsPerStep: number;
+  expiryMode: MemberPointMallExpiryMode;
+  isConsumeRewardEnabled: boolean;
+  isRegisterRewardEnabled: boolean;
+  isReviewRewardEnabled: boolean;
+  isSigninRewardEnabled: boolean;
+  registerRewardPoints: number;
+  reviewRewardPoints: number;
+  signinRewardPoints: number;
+  storeId: string;
+}
+
+/** 规则统计。 */
+export interface MemberPointMallRuleStatsDto {
+  pointMembers: number;
+  redeemRate: number;
+  redeemedPoints: number;
+  totalIssuedPoints: number;
+}
+
+/** 规则详情结果。 */
+export interface MemberPointMallRuleDetailResultDto {
+  rule: MemberPointMallRuleDto;
+  stats: MemberPointMallRuleStatsDto;
+}
+
+/** 保存规则。 */
+export type SaveMemberPointMallRulePayload = MemberPointMallRuleDto;
+
+/** 商品列表查询。 */
+export interface MemberPointMallProductListQuery {
+  keyword?: string;
+  status?: MemberPointMallProductStatus;
+  storeId: string;
+}
+
+/** 商品详情查询。 */
+export interface MemberPointMallProductDetailQuery {
+  pointMallProductId: string;
+  storeId: string;
+}
+
+/** 商品模型。 */
+export interface MemberPointMallProductDto {
+  cashAmount: number;
+  couponTemplateId?: string;
+  description?: string;
+  exchangeType: MemberPointMallExchangeType;
+  imageUrl?: string;
+  name: string;
+  notifyChannels: MemberPointMallNotifyChannel[];
+  perMemberLimit?: number;
+  physicalName?: string;
+  pickupMethod?: MemberPointMallPickupMethod;
+  pointMallProductId: string;
+  productId?: string;
+  redeemType: MemberPointMallRedeemType;
+  redeemTypeText: string;
+  redeemedCount: number;
+  requiredPoints: number;
+  status: MemberPointMallProductStatus;
+  statusText: string;
+  stockAvailable: number;
+  stockTotal: number;
+  storeId: string;
+  updatedAt: string;
+}
+
+/** 商品列表结果。 */
+export interface MemberPointMallProductListResultDto {
+  items: MemberPointMallProductDto[];
+}
+
+/** 保存商品。 */
+export interface SaveMemberPointMallProductPayload {
+  cashAmount: number;
+  couponTemplateId?: string;
+  description?: string;
+  exchangeType: MemberPointMallExchangeType;
+  imageUrl?: string;
+  name: string;
+  notifyChannels: MemberPointMallNotifyChannel[];
+  perMemberLimit?: number;
+  physicalName?: string;
+  pickupMethod?: MemberPointMallPickupMethod;
+  pointMallProductId?: string;
+  productId?: string;
+  redeemType: MemberPointMallRedeemType;
+  requiredPoints: number;
+  status: MemberPointMallProductStatus;
+  stockTotal: number;
+  storeId: string;
+}
+
+/** 修改商品状态。 */
+export interface ChangeMemberPointMallProductStatusPayload {
+  pointMallProductId: string;
+  status: MemberPointMallProductStatus;
+  storeId: string;
+}
+
+/** 删除商品。 */
+export interface DeleteMemberPointMallProductPayload {
+  pointMallProductId: string;
+  storeId: string;
+}
+
+/** 记录列表查询。 */
+export interface MemberPointMallRecordListQuery {
+  endDate?: string;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  redeemType?: MemberPointMallRedeemType;
+  startDate?: string;
+  status?: MemberPointMallRecordStatus;
+  storeId: string;
+}
+
+/** 记录详情查询。 */
+export interface MemberPointMallRecordDetailQuery {
+  recordId: string;
+  storeId: string;
+}
+
+/** 记录模型。 */
+export interface MemberPointMallRecordDto {
+  cashAmount: number;
+  exchangeType: MemberPointMallExchangeType;
+  issuedAt?: string;
+  memberId: string;
+  memberMobileMasked: string;
+  memberName: string;
+  pointMallProductId: string;
+  productName: string;
+  recordId: string;
+  recordNo: string;
+  redeemedAt: string;
+  redeemType: MemberPointMallRedeemType;
+  redeemTypeText: string;
+  status: MemberPointMallRecordStatus;
+  statusText: string;
+  usedPoints: number;
+  verifiedAt?: string;
+}
+
+/** 记录详情。 */
+export interface MemberPointMallRecordDetailDto extends MemberPointMallRecordDto {
+  verifyMethod?: MemberPointMallVerifyMethod;
+  verifyMethodText?: string;
+  verifyRemark?: string;
+  verifiedBy?: string;
+}
+
+/** 记录统计。 */
+export interface MemberPointMallRecordStatsDto {
+  currentMonthUsedPoints: number;
+  pendingPhysicalCount: number;
+  todayRedeemCount: number;
+}
+
+/** 记录分页结果。 */
+export interface MemberPointMallRecordListResultDto {
+  items: MemberPointMallRecordDto[];
+  page: number;
+  pageSize: number;
+  stats: MemberPointMallRecordStatsDto;
+  totalCount: number;
+}
+
+/** 导出记录查询。 */
+export interface ExportMemberPointMallRecordQuery {
+  endDate?: string;
+  keyword?: string;
+  redeemType?: MemberPointMallRedeemType;
+  startDate?: string;
+  status?: MemberPointMallRecordStatus;
+  storeId: string;
+}
+
+/** 导出结果。 */
+export interface MemberPointMallRecordExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 写入记录请求。 */
+export interface WriteMemberPointMallRecordPayload {
+  memberId: string;
+  pointMallProductId: string;
+  redeemedAt?: string;
+  storeId: string;
+}
+
+/** 核销记录请求。 */
+export interface VerifyMemberPointMallRecordPayload {
+  recordId: string;
+  storeId: string;
+  verifyMethod: MemberPointMallVerifyMethod;
+  verifyRemark?: string;
+}
+
+/** 查询规则详情。 */
+export async function getMemberPointMallRuleDetailApi(
+  params: MemberPointMallRuleDetailQuery,
+) {
+  return requestClient.get<MemberPointMallRuleDetailResultDto>(
+    '/member/points-mall/rule/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存规则。 */
+export async function saveMemberPointMallRuleApi(
+  payload: SaveMemberPointMallRulePayload,
+) {
+  return requestClient.post<MemberPointMallRuleDto>(
+    '/member/points-mall/rule/save',
+    payload,
+  );
+}
+
+/** 查询商品列表。 */
+export async function getMemberPointMallProductListApi(
+  params: MemberPointMallProductListQuery,
+) {
+  return requestClient.get<MemberPointMallProductListResultDto>(
+    '/member/points-mall/product/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询商品详情。 */
+export async function getMemberPointMallProductDetailApi(
+  params: MemberPointMallProductDetailQuery,
+) {
+  return requestClient.get<MemberPointMallProductDto>(
+    '/member/points-mall/product/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存商品。 */
+export async function saveMemberPointMallProductApi(
+  payload: SaveMemberPointMallProductPayload,
+) {
+  return requestClient.post<MemberPointMallProductDto>(
+    '/member/points-mall/product/save',
+    payload,
+  );
+}
+
+/** 修改商品状态。 */
+export async function changeMemberPointMallProductStatusApi(
+  payload: ChangeMemberPointMallProductStatusPayload,
+) {
+  return requestClient.post<MemberPointMallProductDto>(
+    '/member/points-mall/product/status',
+    payload,
+  );
+}
+
+/** 删除商品。 */
+export async function deleteMemberPointMallProductApi(
+  payload: DeleteMemberPointMallProductPayload,
+) {
+  return requestClient.post('/member/points-mall/product/delete', payload);
+}
+
+/** 查询兑换记录。 */
+export async function getMemberPointMallRecordListApi(
+  params: MemberPointMallRecordListQuery,
+) {
+  return requestClient.get<MemberPointMallRecordListResultDto>(
+    '/member/points-mall/record/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询兑换记录详情。 */
+export async function getMemberPointMallRecordDetailApi(
+  params: MemberPointMallRecordDetailQuery,
+) {
+  return requestClient.get<MemberPointMallRecordDetailDto>(
+    '/member/points-mall/record/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出兑换记录。 */
+export async function exportMemberPointMallRecordApi(
+  params: ExportMemberPointMallRecordQuery,
+) {
+  return requestClient.get<MemberPointMallRecordExportDto>(
+    '/member/points-mall/record/export',
+    {
+      params,
+    },
+  );
+}
+
+/** 写入兑换记录。 */
+export async function writeMemberPointMallRecordApi(
+  payload: WriteMemberPointMallRecordPayload,
+) {
+  return requestClient.post<MemberPointMallRecordDto>(
+    '/member/points-mall/record/write',
+    payload,
+  );
+}
+
+/** 核销兑换记录。 */
+export async function verifyMemberPointMallRecordApi(
+  payload: VerifyMemberPointMallRecordPayload,
+) {
+  return requestClient.post<MemberPointMallRecordDetailDto>(
+    '/member/points-mall/record/verify',
+    payload,
+  );
+}

apps/web-antd/src/api/member/stored-card.ts

@@ -0,0 +1,205 @@
+/**
+ * 文件职责：会员中心储值卡 API 与 DTO 定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 储值卡方案状态。 */
+export type MemberStoredCardPlanStatus = 'disabled' | 'enabled';
+
+/** 储值卡充值支付方式。 */
+export type MemberStoredCardPaymentMethod =
+  | 'alipay'
+  | 'balance'
+  | 'card'
+  | 'cash'
+  | 'unknown'
+  | 'wechat';
+
+/** 储值卡方案列表查询。 */
+export interface MemberStoredCardPlanListQuery {
+  storeId: string;
+}
+
+/** 储值卡方案统计。 */
+export interface MemberStoredCardPlanStatsDto {
+  currentMonthRechargeAmount: number;
+  rechargeMemberCount: number;
+  totalGiftAmount: number;
+  totalRechargeAmount: number;
+}
+
+/** 储值卡方案项。 */
+export interface MemberStoredCardPlanDto {
+  arrivedAmount: number;
+  giftAmount: number;
+  planId: string;
+  rechargeAmount: number;
+  rechargeCount: number;
+  sortOrder: number;
+  status: MemberStoredCardPlanStatus;
+  totalRechargeAmount: number;
+}
+
+/** 储值卡方案列表结果。 */
+export interface MemberStoredCardPlanListResultDto {
+  items: MemberStoredCardPlanDto[];
+  stats: MemberStoredCardPlanStatsDto;
+}
+
+/** 保存储值卡方案请求。 */
+export interface SaveMemberStoredCardPlanPayload {
+  giftAmount: number;
+  planId?: string;
+  rechargeAmount: number;
+  sortOrder: number;
+  status: MemberStoredCardPlanStatus;
+  storeId: string;
+}
+
+/** 修改储值卡方案状态请求。 */
+export interface ChangeMemberStoredCardPlanStatusPayload {
+  planId: string;
+  status: MemberStoredCardPlanStatus;
+  storeId: string;
+}
+
+/** 删除储值卡方案请求。 */
+export interface DeleteMemberStoredCardPlanPayload {
+  planId: string;
+  storeId: string;
+}
+
+/** 充值记录列表查询。 */
+export interface MemberStoredCardRechargeRecordListQuery {
+  endDate?: string;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  startDate?: string;
+  storeId: string;
+}
+
+/** 储值卡充值记录项。 */
+export interface MemberStoredCardRechargeRecordDto {
+  arrivedAmount: number;
+  giftAmount: number;
+  memberId: string;
+  memberMobileMasked: string;
+  memberName: string;
+  paymentMethod: MemberStoredCardPaymentMethod;
+  paymentMethodText: string;
+  planId?: string;
+  rechargedAt: string;
+  rechargeAmount: number;
+  recordId: string;
+  recordNo: string;
+  remark?: string;
+}
+
+/** 储值卡充值记录分页结果。 */
+export interface MemberStoredCardRechargeRecordListResultDto {
+  items: MemberStoredCardRechargeRecordDto[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+
+/** 储值卡充值记录导出查询。 */
+export interface ExportMemberStoredCardRechargeRecordQuery {
+  endDate?: string;
+  keyword?: string;
+  startDate?: string;
+  storeId: string;
+}
+
+/** 储值卡充值记录导出结果。 */
+export interface MemberStoredCardRechargeRecordExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 写入储值卡充值记录请求。 */
+export interface WriteMemberStoredCardRechargeRecordPayload {
+  giftAmount: number;
+  memberId: string;
+  paymentMethod: Exclude<MemberStoredCardPaymentMethod, 'unknown'>;
+  planId?: string;
+  rechargedAt?: string;
+  rechargeAmount: number;
+  remark?: string;
+  storeId: string;
+}
+
+/** 查询储值卡方案列表。 */
+export async function getMemberStoredCardPlanListApi(
+  params: MemberStoredCardPlanListQuery,
+) {
+  return requestClient.get<MemberStoredCardPlanListResultDto>(
+    '/member/stored-card/plan/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存储值卡方案。 */
+export async function saveMemberStoredCardPlanApi(
+  payload: SaveMemberStoredCardPlanPayload,
+) {
+  return requestClient.post<MemberStoredCardPlanDto>(
+    '/member/stored-card/plan/save',
+    payload,
+  );
+}
+
+/** 修改储值卡方案状态。 */
+export async function changeMemberStoredCardPlanStatusApi(
+  payload: ChangeMemberStoredCardPlanStatusPayload,
+) {
+  return requestClient.post<MemberStoredCardPlanDto>(
+    '/member/stored-card/plan/status',
+    payload,
+  );
+}
+
+/** 删除储值卡方案。 */
+export async function deleteMemberStoredCardPlanApi(
+  payload: DeleteMemberStoredCardPlanPayload,
+) {
+  return requestClient.post('/member/stored-card/plan/delete', payload);
+}
+
+/** 查询储值卡充值记录。 */
+export async function getMemberStoredCardRechargeRecordListApi(
+  params: MemberStoredCardRechargeRecordListQuery,
+) {
+  return requestClient.get<MemberStoredCardRechargeRecordListResultDto>(
+    '/member/stored-card/record/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出储值卡充值记录。 */
+export async function exportMemberStoredCardRechargeRecordApi(
+  params: ExportMemberStoredCardRechargeRecordQuery,
+) {
+  return requestClient.get<MemberStoredCardRechargeRecordExportDto>(
+    '/member/stored-card/record/export',
+    {
+      params,
+    },
+  );
+}
+
+/** 写入储值卡充值记录。 */
+export async function writeMemberStoredCardRechargeRecordApi(
+  payload: WriteMemberStoredCardRechargeRecordPayload,
+) {
+  return requestClient.post<MemberStoredCardRechargeRecordDto>(
+    '/member/stored-card/record/write',
+    payload,
+  );
+}

apps/web-antd/src/api/merchant/index.ts

@@ -0,0 +1,220 @@
+import type {
+  ContractStatus,
+  GeoLocationStatus,
+  MerchantDocumentStatus,
+  MerchantDocumentType,
+  MerchantStatus,
+  OperatingMode,
+  StaffRoleType,
+  StaffStatus,
+  StoreStatus,
+} from '#/enums/merchantEnum';
+
+import { requestClient } from '#/api/request';
+
+export * from '#/enums/merchantEnum';
+
+/**
+ * 商户门店信息
+ */
+export interface MerchantStoreDto {
+  /** 门店ID */
+  id: string;
+  /** 门店名称 */
+  name: string;
+  /** 营业执照号 */
+  licenseNumber?: string;
+  /** 联系电话 */
+  contactPhone?: string;
+  /** 门店地址 */
+  address: string;
+  /** 门店状态 */
+  status: StoreStatus;
+}
+
+/**
+ * 商户详情信息
+ */
+export interface MerchantDetailDto {
+  /** 商户ID */
+  id: string;
+  /** 租户ID */
+  tenantId: string;
+  /** 租户名称 */
+  tenantName?: string;
+  /** 商户名称 */
+  name: string;
+  /** 经营模式 */
+  operatingMode?: OperatingMode;
+  /** 营业执照号 */
+  licenseNumber?: string;
+  /** 法人/负责人 */
+  legalRepresentative?: string;
+  /** 注册地址 */
+  registeredAddress?: string;
+  /** 所在省份 */
+  province?: string;
+  /** 所在城市 */
+  city?: string;
+  /** 所在区县 */
+  district?: string;
+  /** 商户经度 */
+  longitude?: null | number;
+  /** 商户纬度 */
+  latitude?: null | number;
+  /** 地理定位状态 */
+  geoStatus?: GeoLocationStatus;
+  /** 地理定位失败原因 */
+  geoFailReason?: string;
+  /** 地理定位成功时间 */
+  geoUpdatedAt?: null | string;
+  /** 联系电话 */
+  contactPhone?: string;
+  /** 联系邮箱 */
+  contactEmail?: string;
+  /** 商户状态 */
+  status: MerchantStatus;
+  /** 是否冻结 */
+  isFrozen: boolean;
+  /** 冻结原因 */
+  frozenReason?: string;
+  /** 冻结时间 */
+  frozenAt?: null | string;
+  /** 审核通过人 */
+  approvedBy?: string;
+  /** 审核通过时间 */
+  approvedAt?: null | string;
+  /** 关联门店 */
+  stores: MerchantStoreDto[];
+  /** 并发版本 */
+  rowVersion?: string;
+  /** 创建时间 */
+  createdAt: string;
+  /** 创建人 */
+  createdBy?: string;
+  /** 更新时间 */
+  updatedAt?: null | string;
+  /** 更新人 */
+  updatedBy?: string;
+}
+
+/**
+ * 商户资质信息
+ */
+export interface MerchantDocumentDto {
+  id: string;
+  merchantId: string;
+  documentType: MerchantDocumentType;
+  status: MerchantDocumentStatus;
+  fileUrl: string;
+  documentNumber?: string;
+  issuedAt?: null | string;
+  expiresAt?: null | string;
+  remarks?: string;
+  createdAt: string;
+}
+
+/**
+ * 商户合同信息
+ */
+export interface MerchantContractDto {
+  id: string;
+  merchantId: string;
+  contractNumber: string;
+  status: ContractStatus;
+  startDate: string;
+  endDate: string;
+  fileUrl: string;
+  signedAt?: null | string;
+  terminatedAt?: null | string;
+  terminationReason?: string;
+}
+
+/**
+ * 商户员工信息
+ */
+export interface MerchantStaffDto {
+  id: string;
+  tenantId: string;
+  merchantId: string;
+  storeId?: null | string;
+  name: string;
+  phone: string;
+  email?: string;
+  roleType: StaffRoleType;
+  status: StaffStatus;
+}
+
+/**
+ * 商户审核日志
+ */
+export interface MerchantAuditLogDto {
+  id: string;
+  merchantId: string;
+  action: number; // MerchantAuditAction (need to define)
+  operatorId?: string;
+  title: string;
+  description?: string;
+  operatorName?: string;
+  ipAddress?: string;
+  createdAt: string;
+}
+
+/**
+ * 商户变更日志
+ */
+export interface MerchantChangeLogDto {
+  id: string;
+  fieldName: string;
+  oldValue?: string;
+  newValue?: string;
+  changedBy?: string;
+  changedByName?: string;
+  changedAt: string;
+  changeReason?: string;
+}
+
+/**
+ * 商户中心聚合信息
+ */
+export interface CurrentMerchantCenterDto {
+  merchant: MerchantDetailDto;
+  documents: MerchantDocumentDto[];
+  contracts: MerchantContractDto[];
+  staffs: MerchantStaffDto[];
+  auditLogs: MerchantAuditLogDto[];
+  changeLogs: MerchantChangeLogDto[];
+}
+
+/**
+ * 获取当前商户中心信息
+ */
+export async function getMerchantInfoApi() {
+  return requestClient.get<CurrentMerchantCenterDto>('/merchant/info');
+}
+
+/**
+ * 更新商户信息参数
+ */
+export interface UpdateMerchantDto {
+  id: string;
+  name: string;
+  operatingMode?: OperatingMode;
+  licenseNumber?: string;
+  legalRepresentative?: string;
+  contactPhone?: string;
+  contactEmail?: string;
+  registeredAddress?: string;
+}
+
+/**
+ * 更新商户信息
+ */
+export async function updateMerchantInfoApi(data: UpdateMerchantDto) {
+  return requestClient.post('/merchant/update', data);
+}
+
+/** 手动重试当前商户地理定位 */
+export async function retryMerchantGeocodeApi() {
+  return requestClient.post('/merchant/geocode/retry');
+}

apps/web-antd/src/api/order-hall/index.ts

@@ -0,0 +1,100 @@
+/**
+ * 文件职责：订单大厅（看板）接口与类型定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 订单看板卡片。 */
+export interface OrderBoardCard {
+  acceptedAt?: null | string;
+  channel: number;
+  createdAt: string;
+  customerName?: null | string;
+  customerPhone?: null | string;
+  deliveryType: number;
+  id: string;
+  isUrged: boolean;
+  itemsSummary?: null | string;
+  orderNo: string;
+  paidAmount: number;
+  queueNumber?: null | string;
+  readyAt?: null | string;
+  status: number;
+  storeId: string;
+  tableNo?: null | string;
+  urgeCount: number;
+}
+
+/** 订单看板结果（四列）。 */
+export interface OrderBoardResult {
+  completed: OrderBoardCard[];
+  delivering: OrderBoardCard[];
+  making: OrderBoardCard[];
+  pending: OrderBoardCard[];
+}
+
+/** 订单看板统计。 */
+export interface OrderBoardStats {
+  completedCount: number;
+  deliveringCount: number;
+  makingCount: number;
+  pendingCount: number;
+  todayTotal: number;
+}
+
+/** 获取完整看板数据。 */
+export async function getOrderBoardApi(params: {
+  channel?: string;
+  storeId: string;
+}) {
+  return requestClient.get<OrderBoardResult>('/order-board/board', { params });
+}
+
+/** 获取看板统计。 */
+export async function getOrderBoardStatsApi(params: { storeId: string }) {
+  return requestClient.get<OrderBoardStats>('/order-board/stats', { params });
+}
+
+/** 重连补偿拉取。 */
+export async function getPendingSinceApi(params: {
+  since: string;
+  storeId: string;
+}) {
+  return requestClient.get<OrderBoardCard[]>('/order-board/pending-since', {
+    params,
+  });
+}
+
+/** 接单。 */
+export async function acceptOrderApi(orderId: string) {
+  return requestClient.post<OrderBoardCard>(
+    `/order-board/${orderId}/accept`,
+    {},
+  );
+}
+
+/** 拒单。 */
+export async function rejectOrderApi(
+  orderId: string,
+  data: { reason: string },
+) {
+  return requestClient.post<OrderBoardCard>(
+    `/order-board/${orderId}/reject`,
+    data,
+  );
+}
+
+/** 出餐完成。 */
+export async function completePreparationApi(orderId: string) {
+  return requestClient.post<OrderBoardCard>(
+    `/order-board/${orderId}/complete-preparation`,
+    {},
+  );
+}
+
+/** 确认送达/取餐。 */
+export async function confirmDeliveryApi(orderId: string) {
+  return requestClient.post<OrderBoardCard>(
+    `/order-board/${orderId}/confirm-delivery`,
+    {},
+  );
+}

apps/web-antd/src/api/order/index.ts

@@ -0,0 +1,140 @@
+/**
+ * 文件职责：订单管理（全部订单）接口与类型定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 全部订单状态筛选值。 */
+export type OrderAllStatusFilter =
+  | 'all'
+  | 'cancelled'
+  | 'completed'
+  | 'delivering'
+  | 'making'
+  | 'pending'
+  | 'pickup'
+  | 'refunded';
+
+/** 全部订单渠道筛选值。 */
+export type OrderAllChannelFilter = 'all' | 'delivery' | 'dine_in' | 'pickup';
+
+/** 全部订单支付方式筛选值。 */
+export type OrderAllPaymentFilter =
+  | 'alipay'
+  | 'all'
+  | 'balance'
+  | 'card'
+  | 'cash'
+  | 'wechat';
+
+/** 全部订单筛选参数。 */
+export interface OrderAllFilterQuery {
+  channel?: OrderAllChannelFilter;
+  endDate?: string;
+  keyword?: string;
+  paymentMethod?: OrderAllPaymentFilter;
+  startDate?: string;
+  status?: OrderAllStatusFilter;
+  storeId: string;
+}
+
+/** 全部订单列表查询参数。 */
+export interface OrderAllListQuery extends OrderAllFilterQuery {
+  page: number;
+  pageSize: number;
+}
+
+/** 全部订单列表行。 */
+export interface OrderAllListItemDto {
+  amount: number;
+  channel: string;
+  customer: string;
+  isDimmed: boolean;
+  itemsSummary: string;
+  orderNo: string;
+  orderedAt: string;
+  status: string;
+}
+
+/** 全部订单列表结果。 */
+export interface OrderAllListResultDto {
+  items: OrderAllListItemDto[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 全部订单统计。 */
+export interface OrderAllStatsDto {
+  averageAmount: number;
+  refundCount: number;
+  totalAmount: number;
+  totalOrders: number;
+}
+
+/** 全部订单详情商品行。 */
+export interface OrderAllDetailItemDto {
+  name: string;
+  quantity: number;
+  spec: string;
+  subTotal: number;
+  unitPrice: number;
+}
+
+/** 全部订单详情时间线。 */
+export interface OrderAllTimelineDto {
+  label: string;
+  time: string;
+}
+
+/** 全部订单详情。 */
+export interface OrderAllDetailDto {
+  channel: string;
+  customerAddress: string;
+  customerName: string;
+  customerPhone: string;
+  deliveryFee: number;
+  discountAmount: number;
+  finishedAt?: null | string;
+  items: OrderAllDetailItemDto[];
+  itemsAmount: number;
+  orderNo: string;
+  orderedAt: string;
+  paidAmount: number;
+  paidAt?: null | string;
+  paymentMethod: string;
+  remark: string;
+  status: string;
+  timeline: OrderAllTimelineDto[];
+}
+
+/** 全部订单导出回执。 */
+export interface OrderAllExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 查询全部订单列表。 */
+export async function getOrderAllListApi(params: OrderAllListQuery) {
+  return requestClient.get<OrderAllListResultDto>('/order/all/list', {
+    params,
+  });
+}
+
+/** 查询全部订单统计。 */
+export async function getOrderAllStatsApi(params: OrderAllFilterQuery) {
+  return requestClient.get<OrderAllStatsDto>('/order/all/stats', { params });
+}
+
+/** 查询全部订单详情。 */
+export async function getOrderAllDetailApi(params: {
+  orderNo: string;
+  storeId: string;
+}) {
+  return requestClient.get<OrderAllDetailDto>('/order/all/detail', { params });
+}
+
+/** 导出全部订单 CSV。 */
+export async function exportOrderAllCsvApi(params: OrderAllFilterQuery) {
+  return requestClient.get<OrderAllExportDto>('/order/all/export', { params });
+}

apps/web-antd/src/api/request.ts

@@ -20,6 +20,67 @@ import { useAuthStore } from '#/store';
 import { refreshTokenApi } from './core';
 
 const { apiURL } = useAppConfig(import.meta.env, import.meta.env.PROD);
+const TENANT_ID_HEADER_KEY = 'X-Tenant-Id';
+const TENANT_CODE_HEADER_KEY = 'X-Tenant-Code';
+const TENANT_STORAGE_KEY = 'sys-tenant-id';
+const DEV_TENANT_ID = import.meta.env.DEV ? import.meta.env.VITE_TENANT_ID : '';
+
+interface TenantHeaderPayload {
+  tenantCode?: string;
+  tenantId?: string;
+}
+
+function getHeaderValue(headers: any, key: string) {
+  if (!headers) {
+    return '';
+  }
+
+  if (typeof headers.get === 'function') {
+    return headers.get(key) || headers.get(key.toLowerCase()) || '';
+  }
+
+  return headers[key] || headers[key.toLowerCase()] || '';
+}
+
+function setHeaderValue(headers: any, key: string, value: string) {
+  if (!headers) {
+    return;
+  }
+
+  if (typeof headers.set === 'function') {
+    headers.set(key, value);
+    return;
+  }
+
+  headers[key] = value;
+}
+
+function resolveTenantHeaderPayload(): TenantHeaderPayload {
+  const hostname = window.location.hostname;
+  const hostnameParts = hostname.split('.').filter(Boolean);
+  const isIpAddress = /^\d+\.\d+\.\d+\.\d+$/.test(hostname);
+  const subdomainTenant =
+    hostnameParts.length > 2 && !isIpAddress ? hostnameParts[0] : '';
+
+  if (subdomainTenant) {
+    if (/^\d+$/.test(subdomainTenant)) {
+      return { tenantId: subdomainTenant };
+    }
+
+    return { tenantCode: subdomainTenant };
+  }
+
+  const storageTenantId = localStorage.getItem(TENANT_STORAGE_KEY) || '';
+  if (storageTenantId) {
+    return { tenantId: storageTenantId };
+  }
+
+  if (DEV_TENANT_ID) {
+    return { tenantId: DEV_TENANT_ID };
+  }
+
+  return {};
+}
 
 function createRequestClient(baseURL: string, options?: RequestClientOptions) {
   const client = new RequestClient({
@@ -50,10 +111,46 @@ function createRequestClient(baseURL: string, options?: RequestClientOptions) {
    */
   async function doRefreshToken() {
     const accessStore = useAccessStore();
-    const resp = await refreshTokenApi();
+    const currentRefreshToken = accessStore.refreshToken;
-    const newToken = resp.data;
+
-    accessStore.setAccessToken(newToken);
+    if (!currentRefreshToken) {
-    return newToken;
+      throw new Error('refresh token is required');
+    }
+
+    const headers: Record<string, string> = {
+      'Accept-Language': preferences.app.locale,
+    };
+    const { tenantCode, tenantId } = resolveTenantHeaderPayload();
+    if (tenantCode) {
+      headers[TENANT_CODE_HEADER_KEY] = tenantCode;
+    } else if (tenantId) {
+      headers[TENANT_ID_HEADER_KEY] = tenantId;
+    }
+
+    const resp = await refreshTokenApi(
+      {
+        refreshToken: currentRefreshToken,
+      },
+      {
+        headers,
+      },
+    );
+
+    const responseBody = (resp as any)?.data ?? resp;
+    const tokenData =
+      responseBody?.accessToken || responseBody?.refreshToken
+        ? responseBody
+        : responseBody?.data;
+    const newAccessToken = tokenData?.accessToken;
+    const newRefreshToken = tokenData?.refreshToken ?? currentRefreshToken;
+
+    if (!newAccessToken) {
+      throw new Error('access token is missing in refresh response');
+    }
+
+    accessStore.setAccessToken(newAccessToken);
+    accessStore.setRefreshToken(newRefreshToken);
+    return newAccessToken;
   }
 
   function formatToken(token: null | string) {
@@ -65,8 +162,29 @@ function createRequestClient(baseURL: string, options?: RequestClientOptions) {
     fulfilled: async (config) => {
       const accessStore = useAccessStore();
 
-      config.headers.Authorization = formatToken(accessStore.accessToken);
+      const authorization = formatToken(accessStore.accessToken);
-      config.headers['Accept-Language'] = preferences.app.locale;
+      if (authorization) {
+        setHeaderValue(config.headers, 'Authorization', authorization);
+      }
+      setHeaderValue(config.headers, 'Accept-Language', preferences.app.locale);
+
+      const headerTenantId = getHeaderValue(
+        config.headers,
+        TENANT_ID_HEADER_KEY,
+      );
+      const headerTenantCode = getHeaderValue(
+        config.headers,
+        TENANT_CODE_HEADER_KEY,
+      );
+      if (!headerTenantId && !headerTenantCode) {
+        const { tenantCode, tenantId } = resolveTenantHeaderPayload();
+        if (tenantCode) {
+          setHeaderValue(config.headers, TENANT_CODE_HEADER_KEY, tenantCode);
+        } else if (tenantId) {
+          setHeaderValue(config.headers, TENANT_ID_HEADER_KEY, tenantId);
+        }
+      }
+
       return config;
     },
   });
@@ -76,7 +194,7 @@ function createRequestClient(baseURL: string, options?: RequestClientOptions) {
     defaultResponseInterceptor({
       codeField: 'code',
       dataField: 'data',
-      successCode: 0,
+      successCode: 200,
     }),
   );
 

apps/web-antd/src/api/store-delivery/index.ts

@@ -0,0 +1,112 @@
+/**
+ * 文件职责：配送设置模块 API 与 DTO 定义。
+ * 1. 维护配送模式、梯度、区域、通用设置类型。
+ * 2. 提供查询/保存/复制配送设置接口。
+ */
+import { requestClient } from '#/api/request';
+
+/** 配送模式 */
+export type DeliveryMode = 'polygon' | 'radius';
+
+/** 半径梯度配置 */
+export interface RadiusTierDto {
+  color: string;
+  deliveryFee: number;
+  etaMinutes: number;
+  id: string;
+  maxDistance: number;
+  minDistance: number;
+  minOrderAmount: number;
+}
+
+/** 多边形区域配置 */
+export interface PolygonZoneDto {
+  color: string;
+  deliveryFee: number;
+  etaMinutes: number;
+  id: string;
+  minOrderAmount: number;
+  name: string;
+  polygonGeoJson: string;
+  priority: number;
+}
+
+/** 通用配送配置 */
+export interface DeliveryGeneralSettingsDto {
+  /** 配送时间加成（分钟） */
+  etaAdjustmentMinutes: number;
+  /** 免配送费门槛（元），空值表示不启用 */
+  freeDeliveryThreshold: null | number;
+  /** 每小时配送上限（单） */
+  hourlyCapacityLimit: number;
+  /** 最大配送距离（公里） */
+  maxDeliveryDistance: number;
+}
+
+/** 门店配送设置聚合 */
+export interface StoreDeliverySettingsDto {
+  generalSettings: DeliveryGeneralSettingsDto | null;
+  isConfigured: boolean;
+  mode: DeliveryMode | null;
+  /** 半径配送中心点纬度 */
+  radiusCenterLatitude: null | number;
+  /** 半径配送中心点经度 */
+  radiusCenterLongitude: null | number;
+  polygonZones: PolygonZoneDto[];
+  radiusTiers: RadiusTierDto[];
+  storeId: string;
+}
+
+/** 保存配送设置参数 */
+export interface SaveStoreDeliverySettingsParams {
+  generalSettings: DeliveryGeneralSettingsDto;
+  mode: DeliveryMode;
+  /** 半径配送中心点纬度 */
+  radiusCenterLatitude: null | number;
+  /** 半径配送中心点经度 */
+  radiusCenterLongitude: null | number;
+  polygonZones: PolygonZoneDto[];
+  radiusTiers: RadiusTierDto[];
+  storeId: string;
+}
+
+/** 复制配送设置参数 */
+export interface CopyStoreDeliverySettingsParams {
+  sourceStoreId: string;
+  targetStoreIds: string[];
+}
+
+/** 地址地理编码结果 */
+export interface StoreDeliveryGeocodeDto {
+  address: string;
+  latitude: null | number;
+  longitude: null | number;
+}
+
+/** 获取门店配送设置 */
+export async function getStoreDeliverySettingsApi(storeId: string) {
+  return requestClient.get<StoreDeliverySettingsDto>('/store/delivery', {
+    params: { storeId },
+  });
+}
+
+/** 保存门店配送设置 */
+export async function saveStoreDeliverySettingsApi(
+  data: SaveStoreDeliverySettingsParams,
+) {
+  return requestClient.post('/store/delivery/save', data);
+}
+
+/** 复制配送设置到其他门店 */
+export async function copyStoreDeliverySettingsApi(
+  data: CopyStoreDeliverySettingsParams,
+) {
+  return requestClient.post('/store/delivery/copy', data);
+}
+
+/** 地址地理编码（后端签名代理） */
+export async function geocodeStoreDeliveryAddressApi(address: string) {
+  return requestClient.get<StoreDeliveryGeocodeDto>('/store/delivery/geocode', {
+    params: { address },
+  });
+}

apps/web-antd/src/api/store-dinein/index.ts

@@ -0,0 +1,153 @@
+/**
+ * 文件职责：堂食管理模块 API 与 DTO 定义。
+ * 1. 维护区域、桌位、堂食设置类型。
+ * 2. 提供查询、保存、删除、批量生成与复制接口。
+ */
+import { requestClient } from '#/api/request';
+
+/** 桌位状态 */
+export type DineInTableStatus = 'dining' | 'disabled' | 'free' | 'reserved';
+
+/** 可编辑桌位状态（业务态由系统驱动，不在管理端直接设置） */
+export type DineInEditableStatus = 'disabled' | 'free';
+
+/** 堂食基础设置 */
+export interface DineInBasicSettingsDto {
+  /** 是否开启堂食 */
+  enabled: boolean;
+  /** 默认用餐时长（分钟） */
+  defaultDiningMinutes: number;
+  /** 超时提醒阈值（分钟） */
+  overtimeReminderMinutes: number;
+}
+
+/** 堂食区域 */
+export interface DineInAreaDto {
+  /** 区域描述 */
+  description: string;
+  id: string;
+  name: string;
+  /** 数字越小越靠前 */
+  sort: number;
+}
+
+/** 堂食桌位 */
+export interface DineInTableDto {
+  areaId: string;
+  code: string;
+  id: string;
+  seats: number;
+  status: DineInTableStatus;
+  tags: string[];
+}
+
+/** 门店堂食设置聚合 */
+export interface StoreDineInSettingsDto {
+  areas: DineInAreaDto[];
+  basicSettings: DineInBasicSettingsDto | null;
+  isConfigured: boolean;
+  storeId: string;
+  tables: DineInTableDto[];
+}
+
+/** 保存堂食基础设置参数 */
+export interface SaveStoreDineInBasicSettingsParams {
+  basicSettings: DineInBasicSettingsDto;
+  storeId: string;
+}
+
+/** 保存堂食区域参数 */
+export interface SaveDineInAreaParams {
+  area: Omit<DineInAreaDto, 'id'> & { id?: string };
+  storeId: string;
+}
+
+/** 删除堂食区域参数 */
+export interface DeleteDineInAreaParams {
+  areaId: string;
+  storeId: string;
+}
+
+/** 保存堂食桌位参数 */
+export interface SaveDineInTableParams {
+  storeId: string;
+  table: Omit<DineInTableDto, 'id'> & { id?: string };
+}
+
+/** 删除堂食桌位参数 */
+export interface DeleteDineInTableParams {
+  storeId: string;
+  tableId: string;
+}
+
+/** 批量生成桌位参数 */
+export interface BatchCreateDineInTablesParams {
+  areaId: string;
+  codePrefix: string;
+  count: number;
+  seats: number;
+  startNumber: number;
+  storeId: string;
+}
+
+/** 批量生成桌位结果 */
+export interface BatchCreateDineInTablesResultDto {
+  createdTables: DineInTableDto[];
+}
+
+/** 复制堂食设置参数 */
+export interface CopyStoreDineInSettingsParams {
+  sourceStoreId: string;
+  targetStoreIds: string[];
+}
+
+/** 获取门店堂食设置 */
+export async function getStoreDineInSettingsApi(storeId: string) {
+  return requestClient.get<StoreDineInSettingsDto>('/store/dinein', {
+    params: { storeId },
+  });
+}
+
+/** 保存门店堂食基础设置 */
+export async function saveStoreDineInBasicSettingsApi(
+  data: SaveStoreDineInBasicSettingsParams,
+) {
+  return requestClient.post('/store/dinein/basic/save', data);
+}
+
+/** 新增或编辑堂食区域 */
+export async function saveDineInAreaApi(data: SaveDineInAreaParams) {
+  return requestClient.post<DineInAreaDto>('/store/dinein/area/save', data);
+}
+
+/** 删除堂食区域 */
+export async function deleteDineInAreaApi(data: DeleteDineInAreaParams) {
+  return requestClient.post('/store/dinein/area/delete', data);
+}
+
+/** 新增或编辑堂食桌位 */
+export async function saveDineInTableApi(data: SaveDineInTableParams) {
+  return requestClient.post<DineInTableDto>('/store/dinein/table/save', data);
+}
+
+/** 删除堂食桌位 */
+export async function deleteDineInTableApi(data: DeleteDineInTableParams) {
+  return requestClient.post('/store/dinein/table/delete', data);
+}
+
+/** 批量生成堂食桌位 */
+export async function batchCreateDineInTablesApi(
+  data: BatchCreateDineInTablesParams,
+) {
+  return requestClient.post<BatchCreateDineInTablesResultDto>(
+    '/store/dinein/table/batch-create',
+    data,
+  );
+}
+
+/** 复制堂食设置到其他门店 */
+export async function copyStoreDineInSettingsApi(
+  data: CopyStoreDineInSettingsParams,
+) {
+  return requestClient.post('/store/dinein/copy', data);
+}

apps/web-antd/src/api/store-fees/index.ts

@@ -0,0 +1,133 @@
+/**
+ * 文件职责：费用设置模块 API 与 DTO 定义。
+ * 1. 维护起送/配送费、包装费、其他费用类型。
+ * 2. 提供查询、保存与复制费用设置接口。
+ */
+import { requestClient } from '#/api/request';
+
+/** 包装费模式 */
+export type PackagingFeeMode = 'item' | 'order';
+
+/** 按订单包装费模式 */
+export type OrderPackagingFeeMode = 'fixed' | 'tiered';
+
+/** 其他费用类型 */
+export type AdditionalFeeType = 'cutlery' | 'rush';
+
+/** 阶梯包装费条目 */
+export interface PackagingFeeTierDto {
+  /** 单档费用 */
+  fee: number;
+  /** 主键 */
+  id: string;
+  /** 起始订单金额（含） */
+  minAmount: number;
+  /** 结束订单金额（空值表示无上限） */
+  maxAmount: null | number;
+  /** 排序号 */
+  sort: number;
+}
+
+/** 单项其他费用 */
+export interface AdditionalFeeItemDto {
+  /** 费用金额 */
+  amount: number;
+  /** 是否启用 */
+  enabled: boolean;
+}
+
+/** 其他费用聚合 */
+export interface StoreOtherFeesDto {
+  cutlery: AdditionalFeeItemDto;
+  rush: AdditionalFeeItemDto;
+}
+
+/** 门店费用设置聚合 */
+export interface StoreFeesSettingsDto {
+  /** 基础配送费 */
+  baseDeliveryFee: number;
+  /** 平台服务费率（%） */
+  platformServiceRate: number;
+  /** 固定包装费 */
+  fixedPackagingFee: number;
+  /** 免配送费门槛，空值表示关闭 */
+  freeDeliveryThreshold: null | number;
+  /** 起送金额 */
+  minimumOrderAmount: number;
+  /** 其他费用 */
+  otherFees: StoreOtherFeesDto;
+  /** 按订单包装费模式 */
+  orderPackagingFeeMode: OrderPackagingFeeMode;
+  /** 包装费模式 */
+  packagingFeeMode: PackagingFeeMode;
+  /** 包装费阶梯 */
+  packagingFeeTiers: PackagingFeeTierDto[];
+  /** 是否已配置 */
+  isConfigured: boolean;
+  /** 门店 ID */
+  storeId: string;
+}
+
+/** 保存费用设置参数 */
+export interface SaveStoreFeesSettingsParams {
+  /** 基础配送费 */
+  baseDeliveryFee: number;
+  /** 平台服务费率（%） */
+  platformServiceRate: number;
+  /** 固定包装费 */
+  fixedPackagingFee: number;
+  /** 免配送费门槛，空值表示关闭 */
+  freeDeliveryThreshold: null | number;
+  /** 起送金额 */
+  minimumOrderAmount: number;
+  /** 其他费用 */
+  otherFees: StoreOtherFeesDto;
+  /** 按订单包装费模式 */
+  orderPackagingFeeMode: OrderPackagingFeeMode;
+  /** 包装费模式 */
+  packagingFeeMode: PackagingFeeMode;
+  /** 包装费阶梯 */
+  packagingFeeTiers: PackagingFeeTierDto[];
+  /** 门店 ID */
+  storeId: string;
+}
+
+/** 保存包装费收取方式参数 */
+export interface SaveStoreFeesModeParams {
+  /** 包装费模式 */
+  packagingFeeMode: PackagingFeeMode;
+  /** 门店 ID */
+  storeId: string;
+}
+
+/** 复制费用设置参数 */
+export interface CopyStoreFeesSettingsParams {
+  sourceStoreId: string;
+  targetStoreIds: string[];
+}
+
+/** 获取门店费用设置 */
+export async function getStoreFeesSettingsApi(storeId: string) {
+  return requestClient.get<StoreFeesSettingsDto>('/store/fees', {
+    params: { storeId },
+  });
+}
+
+/** 保存门店费用设置 */
+export async function saveStoreFeesSettingsApi(
+  data: SaveStoreFeesSettingsParams,
+) {
+  return requestClient.post<StoreFeesSettingsDto>('/store/fees/save', data);
+}
+
+/** 保存包装费收取方式 */
+export async function saveStoreFeesModeApi(data: SaveStoreFeesModeParams) {
+  return requestClient.post('/store/fees/mode/save', data);
+}
+
+/** 复制费用设置到其他门店 */
+export async function copyStoreFeesSettingsApi(
+  data: CopyStoreFeesSettingsParams,
+) {
+  return requestClient.post('/store/fees/copy', data);
+}

apps/web-antd/src/api/store-hours/index.ts

@@ -0,0 +1,127 @@
+import { requestClient } from '#/api/request';
+
+// ========== 枚举 ==========
+
+/** 时段类型 */
+export enum SlotType {
+  /** 营业 */
+  Business = 1,
+  /** 配送 */
+  Delivery = 2,
+  /** 自提 */
+  Pickup = 3,
+}
+
+/** 特殊日期类型 */
+export enum HolidayType {
+  /** 休息 */
+  Closed = 1,
+  /** 特殊营业 */
+  Special = 2,
+}
+
+// ========== DTO ==========
+
+/** 时段 */
+export interface TimeSlotDto {
+  id: string;
+  /** 时段类型 */
+  type: SlotType;
+  /** 开始时间 HH:mm */
+  startTime: string;
+  /** 结束时间 HH:mm */
+  endTime: string;
+  /** 容量上限（配送类型） */
+  capacity?: number;
+  /** 备注 */
+  remark?: string;
+}
+
+/** 每日营业时间 */
+export interface DayHoursDto {
+  /** 星期几 0=周一 6=周日 */
+  dayOfWeek: number;
+  /** 是否营业 */
+  isOpen: boolean;
+  /** 时段列表 */
+  slots: TimeSlotDto[];
+}
+
+/** 特殊日期 */
+export interface HolidayDto {
+  id: string;
+  /** 开始日期 */
+  startDate: string;
+  /** 结束日期（单日时与 startDate 相同） */
+  endDate: string;
+  /** 类型 */
+  type: HolidayType;
+  /** 营业开始时间（特殊营业） */
+  startTime?: string;
+  /** 营业结束时间（特殊营业） */
+  endTime?: string;
+  /** 原因 */
+  reason: string;
+  /** 备注 */
+  remark?: string;
+}
+
+/** 门店营业时间聚合 */
+export interface StoreHoursDto {
+  storeId: string;
+  weeklyHours: DayHoursDto[];
+  holidays: HolidayDto[];
+}
+
+/** 保存每周时段参数 */
+export interface SaveWeeklyHoursParams {
+  storeId: string;
+  weeklyHours: DayHoursDto[];
+}
+
+/** 保存特殊日期参数 */
+export interface SaveHolidayParams {
+  storeId: string;
+  holiday: Omit<HolidayDto, 'id'> & { id?: string };
+}
+
+/** 复制营业时间参数 */
+export interface CopyStoreHoursParams {
+  /** 源门店ID */
+  sourceStoreId: string;
+  /** 目标门店ID列表 */
+  targetStoreIds: string[];
+  /** 是否包含每周营业时间 */
+  includeWeeklyHours?: boolean;
+  /** 是否包含特殊日期 */
+  includeHolidays?: boolean;
+}
+
+// ========== API ==========
+
+/** 获取门店营业时间 */
+export async function getStoreHoursApi(storeId: string) {
+  return requestClient.get<StoreHoursDto>('/store/hours', {
+    params: { storeId },
+  });
+}
+
+/** 保存每周营业时间 */
+export async function saveWeeklyHoursApi(data: SaveWeeklyHoursParams) {
+  return requestClient.post('/store/hours/weekly', data);
+}
+
+/** 保存特殊日期 */
+export async function saveHolidayApi(data: SaveHolidayParams) {
+  return requestClient.post('/store/hours/holiday', data);
+}
+
+/** 删除特殊日期 */
+export async function deleteHolidayApi(id: string) {
+  return requestClient.post('/store/hours/holiday/delete', { id });
+}
+
+/** 复制营业时间到其他门店 */
+export async function copyStoreHoursApi(data: CopyStoreHoursParams) {
+  return requestClient.post('/store/hours/copy', data);
+}

apps/web-antd/src/api/store-pickup/index.ts

@@ -0,0 +1,150 @@
+/**
+ * 文件职责：自提设置模块 API 与 DTO 定义。
+ * 1. 维护基本设置、大时段、精细规则与预览类型。
+ * 2. 提供查询、保存与复制自提设置接口。
+ */
+import { requestClient } from '#/api/request';
+
+/** 自提模式 */
+export type PickupMode = 'big' | 'fine';
+
+/** 可选星期（0=周一，6=周日） */
+export type PickupWeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+/** 自提基本设置 */
+export interface PickupBasicSettingsDto {
+  /** 是否允许当天自提 */
+  allowSameDayPickup: boolean;
+  /** 可预约天数 */
+  bookingDays: number;
+  /** 单笔最大数量，null 代表不限制 */
+  maxItemsPerOrder: null | number;
+}
+
+/** 大时段模式单条配置 */
+export interface PickupSlotDto {
+  capacity: number;
+  cutoffMinutes: number;
+  dayOfWeeks: PickupWeekDay[];
+  enabled: boolean;
+  endTime: string;
+  id: string;
+  name: string;
+  /** 当前已预约数量（用于展示进度） */
+  reservedCount: number;
+  startTime: string;
+}
+
+/** 精细时段规则 */
+export interface PickupFineRuleDto {
+  /** 适用星期 */
+  dayOfWeeks: PickupWeekDay[];
+  /** 每日结束时间 HH:mm */
+  dayEndTime: string;
+  /** 每日开始时间 HH:mm */
+  dayStartTime: string;
+  /** 时间间隔（分钟） */
+  intervalMinutes: number;
+  /** 最少提前预约小时数 */
+  minAdvanceHours: number;
+  /** 每个窗口容量 */
+  slotCapacity: number;
+}
+
+/** 预览时段状态 */
+export type PickupPreviewStatus = 'almost' | 'available' | 'expired' | 'full';
+
+/** 预览时段 */
+export interface PickupPreviewSlotDto {
+  remainingCount: number;
+  status: PickupPreviewStatus;
+  time: string;
+}
+
+/** 预览日 */
+export interface PickupPreviewDayDto {
+  date: string;
+  label: string;
+  slots: PickupPreviewSlotDto[];
+  subLabel: string;
+}
+
+/** 门店自提设置聚合 */
+export interface StorePickupSettingsDto {
+  basicSettings: null | PickupBasicSettingsDto;
+  bigSlots: PickupSlotDto[];
+  fineRule: null | PickupFineRuleDto;
+  isConfigured: boolean;
+  mode: null | PickupMode;
+  previewDays: PickupPreviewDayDto[];
+  storeId: string;
+}
+
+/** 保存基本设置参数 */
+export interface SavePickupBasicSettingsParams {
+  basicSettings: PickupBasicSettingsDto;
+  mode?: PickupMode;
+  storeId: string;
+}
+
+/** 保存大时段参数 */
+export interface SavePickupSlotsParams {
+  mode?: PickupMode;
+  slots: PickupSlotDto[];
+  storeId: string;
+}
+
+/** 保存精细规则参数 */
+export interface SavePickupFineRuleParams {
+  fineRule: PickupFineRuleDto;
+  mode?: PickupMode;
+  storeId: string;
+}
+
+/** 保存自提模式参数 */
+export interface SavePickupModeParams {
+  mode: PickupMode;
+  storeId: string;
+}
+
+/** 复制自提设置参数 */
+export interface CopyStorePickupSettingsParams {
+  sourceStoreId: string;
+  targetStoreIds: string[];
+}
+
+/** 获取门店自提设置 */
+export async function getStorePickupSettingsApi(storeId: string) {
+  return requestClient.get<StorePickupSettingsDto>('/store/pickup', {
+    params: { storeId },
+  });
+}
+
+/** 保存基本设置 */
+export async function savePickupBasicSettingsApi(
+  data: SavePickupBasicSettingsParams,
+) {
+  return requestClient.post('/store/pickup/basic/save', data);
+}
+
+/** 保存大时段配置 */
+export async function savePickupSlotsApi(data: SavePickupSlotsParams) {
+  return requestClient.post('/store/pickup/slots/save', data);
+}
+
+/** 保存精细规则 */
+export async function savePickupFineRuleApi(data: SavePickupFineRuleParams) {
+  return requestClient.post('/store/pickup/fine-rule/save', data);
+}
+
+/** 保存自提模式 */
+export async function savePickupModeApi(data: SavePickupModeParams) {
+  return requestClient.post('/store/pickup/mode/save', data);
+}
+
+/** 复制到其他门店 */
+export async function copyStorePickupSettingsApi(
+  data: CopyStorePickupSettingsParams,
+) {
+  return requestClient.post('/store/pickup/copy', data);
+}

apps/web-antd/src/api/store-staff/index.ts

@@ -0,0 +1,188 @@
+/**
+ * 文件职责：员工排班模块 API 与 DTO 定义。
+ * 1. 维护员工、班次模板、排班表类型。
+ * 2. 提供查询、保存、删除、复制接口。
+ */
+import type { PaginatedResult } from '#/api/store';
+
+import { requestClient } from '#/api/request';
+
+/** 员工角色 */
+export type StaffRoleType = 'cashier' | 'chef' | 'courier' | 'manager';
+
+/** 员工状态 */
+export type StaffStatus = 'active' | 'leave' | 'resigned';
+
+/** 班次类型 */
+export type ShiftType = 'evening' | 'full' | 'morning' | 'off';
+
+/** 员工档案 */
+export interface StoreStaffDto {
+  avatarColor: string;
+  email: string;
+  hiredAt: string;
+  id: string;
+  name: string;
+  permissions: string[];
+  phone: string;
+  roleType: StaffRoleType;
+  status: StaffStatus;
+}
+
+/** 班次模板条目 */
+export interface ShiftTemplateItemDto {
+  endTime: string;
+  startTime: string;
+}
+
+/** 门店班次模板 */
+export interface StoreShiftTemplatesDto {
+  evening: ShiftTemplateItemDto;
+  full: ShiftTemplateItemDto;
+  morning: ShiftTemplateItemDto;
+}
+
+/** 单日排班 */
+export interface StaffDayShiftDto {
+  dayOfWeek: number;
+  endTime: string;
+  shiftType: ShiftType;
+  startTime: string;
+}
+
+/** 员工排班 */
+export interface StaffScheduleDto {
+  shifts: StaffDayShiftDto[];
+  staffId: string;
+}
+
+/** 门店排班聚合 */
+export interface StoreStaffScheduleDto {
+  isScheduleConfigured: boolean;
+  isTemplateConfigured: boolean;
+  schedules: StaffScheduleDto[];
+  storeId: string;
+  templates: null | StoreShiftTemplatesDto;
+  weekStartDate: string;
+}
+
+/** 员工列表查询参数 */
+export interface StoreStaffListQuery {
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  roleType?: StaffRoleType;
+  status?: StaffStatus;
+  storeId: string;
+}
+
+/** 保存员工参数 */
+export interface SaveStoreStaffParams {
+  email: string;
+  id?: string;
+  name: string;
+  permissions: string[];
+  phone: string;
+  roleType: StaffRoleType;
+  status: StaffStatus;
+  storeId: string;
+}
+
+/** 删除员工参数 */
+export interface DeleteStoreStaffParams {
+  staffId: string;
+  storeId: string;
+}
+
+/** 保存班次模板参数 */
+export interface SaveStoreStaffTemplatesParams {
+  storeId: string;
+  templates: StoreShiftTemplatesDto;
+}
+
+/** 保存个人排班参数 */
+export interface SaveStoreStaffPersonalScheduleParams {
+  shifts: StaffDayShiftDto[];
+  staffId: string;
+  storeId: string;
+}
+
+/** 保存周排班参数 */
+export interface SaveStoreStaffWeeklyScheduleParams {
+  schedules: StaffScheduleDto[];
+  storeId: string;
+}
+
+/** 复制排班参数 */
+export interface CopyStoreStaffScheduleParams {
+  copyScope: 'template_and_schedule';
+  sourceStoreId: string;
+  targetStoreIds: string[];
+}
+
+/** 获取员工列表 */
+export async function getStoreStaffListApi(params: StoreStaffListQuery) {
+  return requestClient.get<PaginatedResult<StoreStaffDto>>('/store/staff', {
+    params,
+  });
+}
+
+/** 新增/编辑员工 */
+export async function saveStoreStaffApi(data: SaveStoreStaffParams) {
+  return requestClient.post<StoreStaffDto>('/store/staff/save', data);
+}
+
+/** 删除员工 */
+export async function deleteStoreStaffApi(data: DeleteStoreStaffParams) {
+  return requestClient.post('/store/staff/delete', data);
+}
+
+/** 获取门店排班配置 */
+export async function getStoreStaffScheduleApi(
+  storeId: string,
+  weekStartDate?: string,
+) {
+  return requestClient.get<StoreStaffScheduleDto>('/store/staff/schedule', {
+    params: {
+      storeId,
+      weekStartDate,
+    },
+  });
+}
+
+/** 保存班次模板 */
+export async function saveStoreStaffTemplatesApi(
+  data: SaveStoreStaffTemplatesParams,
+) {
+  return requestClient.post<StoreShiftTemplatesDto>(
+    '/store/staff/template/save',
+    data,
+  );
+}
+
+/** 保存单员工排班 */
+export async function saveStoreStaffPersonalScheduleApi(
+  data: SaveStoreStaffPersonalScheduleParams,
+) {
+  return requestClient.post<StaffScheduleDto>(
+    '/store/staff/schedule/personal/save',
+    data,
+  );
+}
+
+/** 保存周排班 */
+export async function saveStoreStaffWeeklyScheduleApi(
+  data: SaveStoreStaffWeeklyScheduleParams,
+) {
+  return requestClient.post<StoreStaffScheduleDto>(
+    '/store/staff/schedule/weekly/save',
+    data,
+  );
+}
+
+/** 复制班次模板与排班 */
+export async function copyStoreStaffScheduleApi(
+  data: CopyStoreStaffScheduleParams,
+) {
+  return requestClient.post('/store/staff/copy', data);
+}

apps/web-antd/src/api/store/index.ts

@@ -0,0 +1,141 @@
+import type {
+  GeoLocationStatus,
+  ServiceType,
+  StoreAuditStatus,
+  StoreBusinessStatus,
+} from '#/enums/storeEnum';
+
+import { requestClient } from '#/api/request';
+
+export * from '#/enums/storeEnum';
+
+/** 门店列表项 */
+export interface StoreListItemDto {
+  /** 门店ID */
+  id: string;
+  /** 门店名称 */
+  name: string;
+  /** 门店编码 */
+  code: string;
+  /** 联系电话 */
+  contactPhone: string;
+  /** 店长/负责人 */
+  managerName: string;
+  /** 门店地址 */
+  address: string;
+  /** 所在省份 */
+  province?: string;
+  /** 所在城市 */
+  city?: string;
+  /** 所在区县 */
+  district?: string;
+  /** 门店经度 */
+  longitude?: null | number;
+  /** 门店纬度 */
+  latitude?: null | number;
+  /** 地理定位状态 */
+  geoStatus?: GeoLocationStatus;
+  /** 地理定位失败原因 */
+  geoFailReason?: string;
+  /** 地理定位成功时间 */
+  geoUpdatedAt?: null | string;
+  /** 门店封面图 */
+  coverImage?: string;
+  /** 营业状态 */
+  businessStatus: StoreBusinessStatus;
+  /** 审核状态 */
+  auditStatus: StoreAuditStatus;
+  /** 服务方式 */
+  serviceTypes: ServiceType[];
+  /** 创建时间 */
+  createdAt: string;
+}
+
+/** 门店统计 */
+export interface StoreStatsDto {
+  /** 门店总数 */
+  total: number;
+  /** 营业中 */
+  operating: number;
+  /** 休息中 */
+  resting: number;
+  /** 待审核 */
+  pendingAudit: number;
+}
+
+/** 门店列表查询参数 */
+export interface StoreListQuery {
+  keyword?: string;
+  businessStatus?: StoreBusinessStatus;
+  auditStatus?: StoreAuditStatus;
+  serviceType?: ServiceType;
+  page: number;
+  pageSize: number;
+}
+
+/** 分页结果 */
+export interface PaginatedResult<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+/** 创建/编辑门店参数 */
+export interface SaveStoreDto {
+  id?: string;
+  name: string;
+  contactPhone: string;
+  managerName: string;
+  address: string;
+  coverImage?: string;
+  businessStatus?: StoreBusinessStatus;
+  serviceTypes?: ServiceType[];
+}
+
+/** 快速切换门店营业状态参数 */
+export interface ToggleStoreBusinessStatusDto {
+  storeId: string;
+  businessStatus: StoreBusinessStatus;
+  closureReason?: number;
+  closureReasonText?: string;
+}
+
+/** 获取门店列表 */
+export async function getStoreListApi(params: StoreListQuery) {
+  return requestClient.get<PaginatedResult<StoreListItemDto>>('/store/list', {
+    params,
+  });
+}
+
+/** 获取门店统计 */
+export async function getStoreStatsApi() {
+  return requestClient.get<StoreStatsDto>('/store/stats');
+}
+
+/** 创建门店 */
+export async function createStoreApi(data: SaveStoreDto) {
+  return requestClient.post('/store/create', data);
+}
+
+/** 更新门店 */
+export async function updateStoreApi(data: SaveStoreDto) {
+  return requestClient.post('/store/update', data);
+}
+
+/** 删除门店 */
+export async function deleteStoreApi(id: string) {
+  return requestClient.post('/store/delete', { id });
+}
+
+/** 快速切换门店营业状态 */
+export async function toggleStoreBusinessStatusApi(
+  data: ToggleStoreBusinessStatusDto,
+) {
+  return requestClient.post('/store/toggle-business-status', data);
+}
+
+/** 手动重试门店地理定位 */
+export async function retryStoreGeocodeApi(storeId: string) {
+  return requestClient.post(`/store/${storeId}/geocode/retry`);
+}

apps/web-antd/src/enums/merchantEnum.ts

@@ -0,0 +1,68 @@
+export enum OperatingMode {
+  Direct = 1,
+  Franchise = 2,
+}
+
+export enum MerchantStatus {
+  Active = 1,
+  Closed = 3,
+  Pending = 0,
+  Suspended = 2,
+}
+
+export enum ContractStatus {
+  Active = 1,
+  Draft = 0,
+  Expired = 2,
+  Terminated = 3,
+}
+
+export enum MerchantDocumentType {
+  BusinessLicense = 1,
+  None = 0,
+  Other = 99,
+  Permit = 2,
+}
+
+export enum MerchantDocumentStatus {
+  Approved = 1,
+  Expired = 3,
+  Pending = 0,
+  Rejected = 2,
+}
+
+export enum StaffRoleType {
+  Financial = 2,
+  Operator = 3,
+  StoreManager = 1,
+}
+
+export enum StaffStatus {
+  Active = 1,
+  Resigned = 2,
+}
+
+export enum StoreStatus {
+  Closed = 2,
+  Operating = 1,
+  Renovating = 3,
+}
+
+export enum MerchantAuditAction {
+  Audit = 4,
+  Close = 10,
+  Create = 1,
+  Delete = 3,
+  Freeze = 8,
+  Reject = 5,
+  Reopen = 11,
+  Unfreeze = 9,
+  Unknown = 0,
+  Update = 2,
+}
+
+export enum GeoLocationStatus {
+  Failed = 2,
+  Pending = 0,
+  Success = 1,
+}

apps/web-antd/src/enums/storeEnum.ts

@@ -0,0 +1,41 @@
+/** 门店营业状态 */
+export enum StoreBusinessStatus {
+  /** 强制关闭 */
+  ForceClosed = 2,
+  /** 营业中 */
+  Operating = 0,
+  /** 休息中 */
+  Resting = 1,
+}
+
+/** 门店审核状态 */
+export enum StoreAuditStatus {
+  /** 已通过 */
+  Approved = 2,
+  /** 草稿 */
+  Draft = 0,
+  /** 待审核 */
+  Pending = 1,
+  /** 已拒绝 */
+  Rejected = 3,
+}
+
+/** 服务方式 */
+export enum ServiceType {
+  /** 外卖配送 */
+  Delivery = 1,
+  /** 堂食 */
+  DineIn = 3,
+  /** 到店自提 */
+  Pickup = 2,
+}
+
+/** 地理定位状态 */
+export enum GeoLocationStatus {
+  /** 定位失败 */
+  Failed = 2,
+  /** 待定位 */
+  Pending = 0,
+  /** 定位成功 */
+  Success = 1,
+}

apps/web-antd/src/hooks/useSignalR.ts

@@ -0,0 +1,121 @@
+/**
+ * 文件职责：SignalR 连接管理 Hook，提供自动重连、事件订阅、断线补偿能力。
+ */
+import type { HubConnection } from '@microsoft/signalr';
+
+import { ref } from 'vue';
+
+import { useAppConfig } from '@vben/hooks';
+import { useAccessStore } from '@vben/stores';
+
+import {
+  HubConnectionBuilder,
+  HubConnectionState,
+  LogLevel,
+} from '@microsoft/signalr';
+
+/** SignalR Hook 配置。 */
+export interface UseSignalROptions {
+  /** 重连后的补偿回调（传入断线时间戳）。 */
+  onReconnected?: (lastDisconnectedAt: Date) => void;
+  /** 连接关闭回调。 */
+  onClose?: (error?: Error) => void;
+}
+
+/** SignalR 连接管理 Hook。 */
+export function useSignalR(options?: UseSignalROptions) {
+  const isConnected = ref(false);
+  let connection: HubConnection | null = null;
+  let lastDisconnectedAt: Date | null = null;
+
+  // 1. 构建 Hub URL（从 apiURL 去掉 /api/tenant/v1 后缀）
+  function buildHubUrl(): string {
+    const { apiURL } = useAppConfig(import.meta.env, import.meta.env.PROD);
+    const base = apiURL.replace(/\/api\/tenant\/v\d+\/?$/, '');
+    return `${base}/hubs/order-board`;
+  }
+
+  // 2. 获取 JWT Token
+  function getAccessToken(): string {
+    const accessStore = useAccessStore();
+    return accessStore.accessToken || '';
+  }
+
+  // 3. 建立连接
+  async function connect(storeId?: string): Promise<void> {
+    if (connection?.state === HubConnectionState.Connected) {
+      return;
+    }
+
+    const hubUrl = storeId
+      ? `${buildHubUrl()}?storeId=${storeId}`
+      : buildHubUrl();
+
+    connection = new HubConnectionBuilder()
+      .withUrl(hubUrl, {
+        accessTokenFactory: () => getAccessToken(),
+      })
+      .withAutomaticReconnect([0, 2000, 5000, 10_000, 30_000])
+      .configureLogging(LogLevel.Warning)
+      .build();
+
+    // 4. 重连成功回调
+    connection.onreconnecting(() => {
+      isConnected.value = false;
+      lastDisconnectedAt = new Date();
+    });
+
+    connection.onreconnected(() => {
+      isConnected.value = true;
+      if (lastDisconnectedAt && options?.onReconnected) {
+        options.onReconnected(lastDisconnectedAt);
+      }
+      lastDisconnectedAt = null;
+    });
+
+    // 5. 连接关闭回调
+    connection.onclose((error) => {
+      isConnected.value = false;
+      lastDisconnectedAt = new Date();
+      options?.onClose?.(error ?? undefined);
+    });
+
+    await connection.start();
+    isConnected.value = true;
+  }
+
+  // 6. 断开连接
+  async function disconnect(): Promise<void> {
+    if (connection) {
+      await connection.stop();
+      connection = null;
+      isConnected.value = false;
+    }
+  }
+
+  // 7. 订阅事件
+  function on<T = unknown>(event: string, callback: (data: T) => void): void {
+    connection?.on(event, callback);
+  }
+
+  // 8. 取消订阅
+  function off(event: string): void {
+    connection?.off(event);
+  }
+
+  // 9. 调用 Hub 方法
+  async function invoke(method: string, ...args: unknown[]): Promise<void> {
+    if (connection?.state === HubConnectionState.Connected) {
+      await connection.invoke(method, ...args);
+    }
+  }
+
+  return {
+    isConnected,
+    connect,
+    disconnect,
+    on,
+    off,
+    invoke,
+  };
+}

apps/web-antd/src/layouts/basic.vue

@@ -5,9 +5,9 @@ import { computed, ref, watch } from 'vue';
 import { useRouter } from 'vue-router';
 
 import { AuthenticationLoginExpiredModal } from '@vben/common-ui';
-import { VBEN_DOC_URL, VBEN_GITHUB_URL } from '@vben/constants';
+import { VBEN_GITHUB_URL } from '@vben/constants';
 import { useWatermark } from '@vben/hooks';
-import { BookOpenText, CircleHelp, SvgGithubIcon } from '@vben/icons';
+import { CircleHelp } from '@vben/icons';
 import {
   BasicLayout,
   LockScreen,
@@ -87,28 +87,17 @@ const showDot = computed(() =>
 const menus = computed(() => [
   {
     handler: () => {
-      router.push({ name: 'Profile' });
+      router.push({ name: 'PersonalCenter' });
     },
     icon: 'lucide:user',
     text: $t('page.auth.profile'),
   },
   {
     handler: () => {
-      openWindow(VBEN_DOC_URL, {
+      router.push({ name: 'MerchantCenter' });
-        target: '_blank',
-      });
     },
-    icon: BookOpenText,
+    icon: 'lucide:store',
-    text: $t('ui.widgets.document'),
+    text: '商户中心',
-  },
-  {
-    handler: () => {
-      openWindow(VBEN_GITHUB_URL, {
-        target: '_blank',
-      });
-    },
-    icon: SvgGithubIcon,
-    text: 'GitHub',
   },
   {
     handler: () => {
@@ -125,6 +114,10 @@ const avatar = computed(() => {
   return userStore.userInfo?.avatar ?? preferences.app.defaultAvatar;
 });
 
+const packageTagText = computed(() => {
+  return userStore.userInfo?.desc?.trim() ?? '';
+});
+
 async function handleLogout() {
   await authStore.logout(false);
 }
@@ -176,8 +169,8 @@ watch(
         :avatar
         :menus
         :text="userStore.userInfo?.realName"
-        description="ann.vben@gmail.com"
+        :description="userStore.userInfo?.username"
-        tag-text="Pro"
+        :tag-text="packageTagText"
         @logout="handleLogout"
       />
     </template>

apps/web-antd/src/locales/langs/zh-CN/page.json

@@ -11,5 +11,9 @@
     "title": "概览",
     "analytics": "分析页",
     "workspace": "工作台"
+  },
+  "merchant": {
+    "title": "商户管理",
+    "center": "商户中心"
   }
 }

apps/web-antd/src/main.ts

@@ -1,8 +1,13 @@
-import { initPreferences } from '@vben/preferences';
+import { initPreferences, updatePreferences } from '@vben/preferences';
 import { unmountGlobalLoading } from '@vben/utils';
 
 import { overridesPreferences } from './preferences';
 
+// 仅在显式开启时启用 Mock 数据
+if (import.meta.env.DEV && import.meta.env.VITE_NITRO_MOCK === 'true') {
+  import('./mock');
+}
+
 /**
  * 应用初始化完成之后再进行页面加载渲染
  */
@@ -19,6 +24,15 @@ async function initApplication() {
     overrides: overridesPreferences,
   });
 
+  updatePreferences({
+    app: {
+      accessMode: 'backend',
+      defaultHomePath: '/dashboard/console',
+      enableRefreshToken: true,
+      loginExpiredMode: 'modal',
+    },
+  });
+
   // 启动应用并挂载
   // vue应用主要逻辑及视图
   const { bootstrap } = await import('./bootstrap');

apps/web-antd/src/mock/index.ts

@@ -0,0 +1,11 @@
+// Mock 数据入口，仅在开发环境下使用。
+// 默认关闭商品相关 mock；需要时可通过环境变量显式开启。
+if (import.meta.env.VITE_MOCK_PRODUCT === 'true') {
+  void import('./product');
+  console.warn('[Mock] 已启用商品列表 Mock 数据');
+}
+
+if (import.meta.env.VITE_MOCK_PRODUCT_EXTENSIONS === 'true') {
+  void import('./product-extensions');
+  console.warn('[Mock] 已启用商品扩展模块 Mock 数据');
+}

apps/web-antd/src/mock/product.ts

@@ -0,0 +1,883 @@
+import Mock from 'mockjs';
+
+/** 文件职责：商品管理页面 Mock 接口。 */
+interface MockRequestOptions {
+  body: null | string;
+  type: string;
+  url: string;
+}
+
+type ProductStatus = 'off_shelf' | 'on_sale' | 'sold_out';
+type ProductKind = 'combo' | 'single';
+type ProductSoldoutMode = 'permanent' | 'timed' | 'today';
+type ShelfMode = 'draft' | 'now' | 'scheduled';
+type BatchActionType =
+  | 'batch_delete'
+  | 'batch_off'
+  | 'batch_on'
+  | 'batch_soldout';
+
+interface CategorySeed {
+  id: string;
+  name: string;
+  sort: number;
+}
+
+interface ProductSeed {
+  categoryId: string;
+  defaultKind?: ProductKind;
+  name: string;
+  price: number;
+  subtitle: string;
+  tags?: string[];
+}
+
+interface ProductRecord {
+  categoryId: string;
+  description: string;
+  id: string;
+  imageUrl: string;
+  kind: ProductKind;
+  name: string;
+  notifyManager: boolean;
+  originalPrice: null | number;
+  price: number;
+  recoverAt: null | string;
+  remainStock: number;
+  salesMonthly: number;
+  soldoutMode: null | ProductSoldoutMode;
+  soldoutReason: string;
+  spuCode: string;
+  status: ProductStatus;
+  stock: number;
+  storeId: string;
+  subtitle: string;
+  syncToPlatform: boolean;
+  tags: string[];
+  timedOnShelfAt: null | string;
+  updatedAt: string;
+}
+
+interface ProductStoreState {
+  nextSeq: number;
+  products: ProductRecord[];
+}
+
+const CATEGORY_SEEDS: CategorySeed[] = [
+  { id: 'cat-hot', name: '热销推荐', sort: 1 },
+  { id: 'cat-main', name: '主食', sort: 2 },
+  { id: 'cat-snack', name: '小吃凉菜', sort: 3 },
+  { id: 'cat-soup', name: '汤羹粥品', sort: 4 },
+  { id: 'cat-drink', name: '饮品', sort: 5 },
+  { id: 'cat-alcohol', name: '酒水', sort: 6 },
+  { id: 'cat-combo', name: '套餐', sort: 7 },
+];
+
+const PRODUCT_SEEDS: ProductSeed[] = [
+  {
+    categoryId: 'cat-main',
+    name: '宫保鸡丁',
+    price: 32,
+    subtitle: '经典川菜，香辣可口',
+    tags: ['招牌'],
+  },
+  {
+    categoryId: 'cat-main',
+    name: '鱼香肉丝',
+    price: 28,
+    subtitle: '酸甜开胃，佐饭佳选',
+    tags: ['必点'],
+  },
+  {
+    categoryId: 'cat-main',
+    name: '麻婆豆腐',
+    price: 22,
+    subtitle: '麻辣鲜香，口感细腻',
+    tags: ['辣'],
+  },
+  {
+    categoryId: 'cat-main',
+    name: '蛋炒饭',
+    price: 15,
+    subtitle: '粒粒分明，锅气十足',
+  },
+  {
+    categoryId: 'cat-main',
+    name: '红烧排骨',
+    price: 42,
+    subtitle: '酱香浓郁，肉质软烂',
+    tags: ['招牌'],
+  },
+  {
+    categoryId: 'cat-main',
+    name: '土豆烧牛腩',
+    price: 38,
+    subtitle: '软糯入味，牛腩足量',
+  },
+  {
+    categoryId: 'cat-main',
+    name: '黑椒牛柳意面',
+    price: 36,
+    subtitle: '西式风味，黑椒浓香',
+    tags: ['新品'],
+  },
+  {
+    categoryId: 'cat-main',
+    name: '照烧鸡腿饭',
+    price: 27,
+    subtitle: '日式酱香，鸡腿多汁',
+  },
+  {
+    categoryId: 'cat-snack',
+    name: '蒜香鸡翅',
+    price: 24,
+    subtitle: '外酥里嫩，蒜香扑鼻',
+    tags: ['热卖'],
+  },
+  {
+    categoryId: 'cat-snack',
+    name: '香辣薯条',
+    price: 12,
+    subtitle: '酥脆爽口，轻微辣感',
+  },
+  {
+    categoryId: 'cat-snack',
+    name: '凉拌黄瓜',
+    price: 10,
+    subtitle: '爽脆开胃，解腻优选',
+  },
+  {
+    categoryId: 'cat-snack',
+    name: '口水鸡',
+    price: 26,
+    subtitle: '麻香鲜辣，肉质嫩滑',
+    tags: ['辣'],
+  },
+  {
+    categoryId: 'cat-snack',
+    name: '椒盐玉米',
+    price: 14,
+    subtitle: '外脆内甜，老少皆宜',
+  },
+  {
+    categoryId: 'cat-soup',
+    name: '酸辣汤',
+    price: 18,
+    subtitle: '开胃暖身，酸辣平衡',
+  },
+  {
+    categoryId: 'cat-soup',
+    name: '番茄蛋花汤',
+    price: 16,
+    subtitle: '清爽酸甜，营养丰富',
+  },
+  {
+    categoryId: 'cat-soup',
+    name: '皮蛋瘦肉粥',
+    price: 19,
+    subtitle: '米香浓郁，口感顺滑',
+  },
+  {
+    categoryId: 'cat-soup',
+    name: '海带排骨汤',
+    price: 21,
+    subtitle: '汤鲜味美，口感醇厚',
+  },
+  {
+    categoryId: 'cat-drink',
+    name: '柠檬气泡水',
+    price: 9,
+    subtitle: '清爽解腻，微甜口感',
+    tags: ['新品'],
+  },
+  {
+    categoryId: 'cat-drink',
+    name: '冰粉',
+    price: 8,
+    subtitle: '夏日必备，冰凉清甜',
+    tags: ['限时'],
+  },
+  {
+    categoryId: 'cat-drink',
+    name: '酸梅汤',
+    price: 11,
+    subtitle: '古法熬制，酸甜适中',
+  },
+  {
+    categoryId: 'cat-drink',
+    name: '杨枝甘露',
+    price: 16,
+    subtitle: '果香浓郁，奶香顺滑',
+    tags: ['推荐'],
+  },
+  {
+    categoryId: 'cat-drink',
+    name: '鲜榨橙汁',
+    price: 13,
+    subtitle: '现榨现卖，清新自然',
+  },
+  {
+    categoryId: 'cat-alcohol',
+    name: '青岛啤酒 500ml',
+    price: 12,
+    subtitle: '经典口感，冰镇更佳',
+  },
+  {
+    categoryId: 'cat-alcohol',
+    name: '哈尔滨啤酒 500ml',
+    price: 11,
+    subtitle: '麦香清爽，口感顺滑',
+  },
+  {
+    categoryId: 'cat-alcohol',
+    name: '乌苏啤酒 620ml',
+    price: 15,
+    subtitle: '劲爽畅饮，聚餐优选',
+    tags: ['热卖'],
+  },
+  {
+    categoryId: 'cat-combo',
+    defaultKind: 'combo',
+    name: '双人午市套餐',
+    price: 69,
+    subtitle: '两荤一素+汤+饮料',
+    tags: ['套餐'],
+  },
+  {
+    categoryId: 'cat-combo',
+    defaultKind: 'combo',
+    name: '单人畅享套餐',
+    price: 39,
+    subtitle: '主食+小吃+饮品',
+    tags: ['套餐'],
+  },
+  {
+    categoryId: 'cat-combo',
+    defaultKind: 'combo',
+    name: '家庭四人餐',
+    price: 168,
+    subtitle: '经典大份组合，聚会优选',
+    tags: ['套餐', '招牌'],
+  },
+  {
+    categoryId: 'cat-hot',
+    name: '招牌牛肉饭',
+    price: 34,
+    subtitle: '高人气单品，复购率高',
+    tags: ['热销'],
+  },
+  {
+    categoryId: 'cat-hot',
+    name: '经典鸡排饭',
+    price: 26,
+    subtitle: '酥脆鸡排，份量十足',
+    tags: ['热销'],
+  },
+  {
+    categoryId: 'cat-hot',
+    name: '藤椒鸡腿饭',
+    price: 29,
+    subtitle: '麻香清爽，口味独特',
+    tags: ['推荐'],
+  },
+  {
+    categoryId: 'cat-hot',
+    name: '番茄牛腩饭',
+    price: 33,
+    subtitle: '酸甜开胃，牛腩软烂',
+  },
+  {
+    categoryId: 'cat-hot',
+    name: '椒麻鸡拌面',
+    price: 24,
+    subtitle: '清爽拌面，椒麻上头',
+    tags: ['新品'],
+  },
+];
+
+const productStoreMap = new Map<string, ProductStoreState>();
+const ENABLE_PRODUCT_CATEGORY_MOCK =
+  import.meta.env.VITE_MOCK_PRODUCT_CATEGORY === 'true';
+
+/** 解析 URL 查询参数。 */
+function parseUrlParams(url: string) {
+  const parsed = new URL(url, 'http://localhost');
+  const params: Record<string, string> = {};
+  parsed.searchParams.forEach((value, key) => {
+    params[key] = value;
+  });
+  return params;
+}
+
+/** 解析请求体 JSON。 */
+function parseBody(options: MockRequestOptions) {
+  if (!options.body) return {};
+  try {
+    return JSON.parse(options.body) as Record<string, unknown>;
+  } catch (error) {
+    console.error('[mock-product] parseBody error:', error);
+    return {};
+  }
+}
+
+/** 统一 yyyy-MM-dd HH:mm:ss。 */
+function toDateTimeText(date: Date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  const hour = String(date.getHours()).padStart(2, '0');
+  const minute = String(date.getMinutes()).padStart(2, '0');
+  const second = String(date.getSeconds()).padStart(2, '0');
+  return `${year}-${month}-${day} ${hour}:${minute}:${second}`;
+}
+
+/** 归一化数值输入。 */
+function normalizeNumber(value: unknown, fallback = 0, min = 0) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, parsed);
+}
+
+/** 归一化正整数。 */
+function normalizeInt(value: unknown, fallback = 0, min = 0) {
+  return Math.floor(normalizeNumber(value, fallback, min));
+}
+
+/** 归一化文本。 */
+function normalizeText(value: unknown, fallback = '') {
+  const text = String(value ?? '').trim();
+  return text || fallback;
+}
+
+/** 归一化状态。 */
+function normalizeStatus(
+  value: unknown,
+  fallback: ProductStatus,
+): ProductStatus {
+  const next = String(value || '');
+  if (next === 'on_sale' || next === 'off_shelf' || next === 'sold_out') {
+    return next;
+  }
+  return fallback;
+}
+
+/** 归一化商品类型。 */
+function normalizeKind(value: unknown, fallback: ProductKind): ProductKind {
+  const next = String(value || '');
+  return next === 'combo' || next === 'single' ? next : fallback;
+}
+
+/** 归一化沽清模式。 */
+function normalizeSoldoutMode(
+  value: unknown,
+  fallback: ProductSoldoutMode,
+): ProductSoldoutMode {
+  const next = String(value || '');
+  if (next === 'today' || next === 'timed' || next === 'permanent') return next;
+  return fallback;
+}
+
+/** 标准化标签列表。 */
+function normalizeTags(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return [
+    ...new Set(
+      value
+        .map((item) => String(item || '').trim())
+        .filter(Boolean)
+        .slice(0, 8),
+    ),
+  ];
+}
+
+/** 查找分类名。 */
+function getCategoryName(categoryId: string) {
+  return (
+    CATEGORY_SEEDS.find((item) => item.id === categoryId)?.name ??
+    CATEGORY_SEEDS[0]?.name ??
+    '未分类'
+  );
+}
+
+/** 生成默认商品池。 */
+function createDefaultProducts(storeId: string): ProductRecord[] {
+  const now = new Date();
+  const list: ProductRecord[] = [];
+  let seq = 1;
+  for (const seed of PRODUCT_SEEDS) {
+    const statusSeed = seq % 9;
+    let status: ProductStatus = 'on_sale';
+    if (statusSeed === 0) {
+      status = 'sold_out';
+    } else if (statusSeed === 4 || statusSeed === 7) {
+      status = 'off_shelf';
+    }
+
+    let stock = 20 + (seq % 120);
+    if (status === 'sold_out') {
+      stock = 0;
+    } else if (status === 'off_shelf') {
+      stock = 12 + (seq % 20);
+    }
+    const price = Number(seed.price.toFixed(2));
+    const originalPrice =
+      seq % 3 === 0 ? Number((price + (3 + (seq % 8))).toFixed(2)) : null;
+    const createdAt = new Date(now);
+    createdAt.setDate(now.getDate() - (seq % 30));
+    list.push({
+      id: `prd-${storeId}-${String(seq).padStart(4, '0')}`,
+      storeId,
+      spuCode: `SPU2024${String(1000 + seq).padStart(5, '0')}`,
+      name: seed.name,
+      subtitle: seed.subtitle,
+      description: `${seed.name}，${seed.subtitle}。`,
+      categoryId: seed.categoryId,
+      kind: seed.defaultKind ?? 'single',
+      price,
+      originalPrice,
+      stock,
+      salesMonthly: 15 + ((seq * 17) % 260),
+      tags: seed.tags ? [...seed.tags] : [],
+      status,
+      soldoutMode: status === 'sold_out' ? 'today' : null,
+      remainStock: stock,
+      recoverAt: null,
+      soldoutReason: status === 'sold_out' ? '食材用完' : '',
+      syncToPlatform: true,
+      notifyManager: false,
+      timedOnShelfAt: null,
+      imageUrl: '',
+      updatedAt: toDateTimeText(createdAt),
+    });
+    seq += 1;
+  }
+  return list;
+}
+
+/** 创建默认门店状态。 */
+function createDefaultState(storeId: string): ProductStoreState {
+  const products = createDefaultProducts(storeId);
+  return {
+    products,
+    nextSeq: products.length + 1,
+  };
+}
+
+/** 确保门店状态存在。 */
+function ensureStoreState(storeId = '') {
+  const key = storeId || 'default';
+  let state = productStoreMap.get(key);
+  if (!state) {
+    state = createDefaultState(key);
+    productStoreMap.set(key, state);
+  }
+  return state;
+}
+
+/** 构建分类结果（全量口径，不受筛选影响）。 */
+function buildCategoryList(products: ProductRecord[]) {
+  const countMap = new Map<string, number>();
+  for (const item of products) {
+    countMap.set(item.categoryId, (countMap.get(item.categoryId) ?? 0) + 1);
+  }
+  return CATEGORY_SEEDS.toSorted((a, b) => a.sort - b.sort).map((category) => ({
+    id: category.id,
+    name: category.name,
+    sort: category.sort,
+    productCount: countMap.get(category.id) ?? 0,
+  }));
+}
+
+/** 列表项映射。 */
+function toListItem(product: ProductRecord) {
+  return {
+    id: product.id,
+    spuCode: product.spuCode,
+    name: product.name,
+    subtitle: product.subtitle,
+    categoryId: product.categoryId,
+    categoryName: getCategoryName(product.categoryId),
+    kind: product.kind,
+    price: product.price,
+    originalPrice: product.originalPrice,
+    stock: product.stock,
+    salesMonthly: product.salesMonthly,
+    tags: [...product.tags],
+    status: product.status,
+    soldoutMode: product.soldoutMode,
+    imageUrl: product.imageUrl,
+  };
+}
+
+/** 详情映射。 */
+function toDetailItem(product: ProductRecord) {
+  return {
+    ...toListItem(product),
+    description: product.description,
+    remainStock: product.remainStock,
+    soldoutReason: product.soldoutReason,
+    recoverAt: product.recoverAt,
+    syncToPlatform: product.syncToPlatform,
+    notifyManager: product.notifyManager,
+  };
+}
+
+/** 创建商品 ID。 */
+function createProductId(storeId: string, seq: number) {
+  return `prd-${storeId}-${String(seq).padStart(4, '0')}`;
+}
+
+/** 创建 SPU 编码。 */
+function createSpuCode(seq: number) {
+  return `SPU2026${String(10_000 + seq).slice(-5)}`;
+}
+
+/** 解析上架方式。 */
+function resolveStatusByShelfMode(
+  mode: ShelfMode,
+  fallback: ProductStatus,
+): ProductStatus {
+  if (mode === 'now') return 'on_sale';
+  if (mode === 'draft' || mode === 'scheduled') return 'off_shelf';
+  return fallback;
+}
+
+/** 获取商品分类（默认走真实 TenantApi，需手动开启才启用 mock）。 */
+if (ENABLE_PRODUCT_CATEGORY_MOCK) {
+  Mock.mock(
+    /\/product\/category\/list(?:\?|$)/,
+    'get',
+    (options: MockRequestOptions) => {
+      const params = parseUrlParams(options.url);
+      const storeId = String(params.storeId || '');
+      const state = ensureStoreState(storeId);
+      return {
+        code: 200,
+        data: buildCategoryList(state.products),
+      };
+    },
+  );
+}
+
+/** 获取商品列表。 */
+Mock.mock(/\/product\/list(?:\?|$)/, 'get', (options: MockRequestOptions) => {
+  const params = parseUrlParams(options.url);
+  const storeId = String(params.storeId || '');
+  const state = ensureStoreState(storeId);
+
+  const categoryId = String(params.categoryId || '').trim();
+  const keyword = String(params.keyword || '')
+    .trim()
+    .toLowerCase();
+  const status = normalizeStatus(params.status, 'on_sale');
+  const kind = normalizeKind(params.kind, 'single');
+  const hasStatus = Boolean(params.status);
+  const hasKind = Boolean(params.kind);
+
+  const page = Math.max(1, normalizeInt(params.page, 1, 1));
+  const pageSize = Math.max(
+    1,
+    Math.min(200, normalizeInt(params.pageSize, 12, 1)),
+  );
+
+  const filtered = state.products.filter((item) => {
+    if (categoryId && item.categoryId !== categoryId) return false;
+    if (keyword) {
+      const hit =
+        item.name.toLowerCase().includes(keyword) ||
+        item.spuCode.toLowerCase().includes(keyword);
+      if (!hit) return false;
+    }
+    if (hasStatus && item.status !== status) return false;
+    if (hasKind && item.kind !== kind) return false;
+    return true;
+  });
+
+  const ordered = filtered.toSorted((a, b) =>
+    b.updatedAt.localeCompare(a.updatedAt),
+  );
+  const start = (page - 1) * pageSize;
+  const items = ordered.slice(start, start + pageSize);
+  return {
+    code: 200,
+    data: {
+      items: items.map((item) => toListItem(item)),
+      total: ordered.length,
+      page,
+      pageSize,
+    },
+  };
+});
+
+/** 获取商品详情。 */
+Mock.mock(/\/product\/detail(?:\?|$)/, 'get', (options: MockRequestOptions) => {
+  const params = parseUrlParams(options.url);
+  const storeId = String(params.storeId || '');
+  const productId = String(params.productId || '');
+  const state = ensureStoreState(storeId);
+  const product = state.products.find((item) => item.id === productId);
+  if (!product) {
+    return {
+      code: 404,
+      data: null,
+      message: '商品不存在',
+    };
+  }
+  return {
+    code: 200,
+    data: toDetailItem(product),
+  };
+});
+
+/** 保存商品（新增/编辑）。 */
+Mock.mock(/\/product\/save/, 'post', (options: MockRequestOptions) => {
+  const body = parseBody(options);
+  const storeId = normalizeText(body.storeId);
+  if (!storeId) {
+    return { code: 400, data: null, message: '门店不能为空' };
+  }
+  const state = ensureStoreState(storeId);
+
+  const id = normalizeText(body.id);
+  const shelfMode = normalizeText(body.shelfMode, 'now') as ShelfMode;
+  const existingIndex = state.products.findIndex((item) => item.id === id);
+  const fallbackStatus =
+    existingIndex === -1 ? 'on_sale' : state.products[existingIndex]?.status;
+  const statusFromBody = normalizeStatus(
+    body.status,
+    fallbackStatus || 'on_sale',
+  );
+  const nextStatus = resolveStatusByShelfMode(shelfMode, statusFromBody);
+  const categoryId = normalizeText(
+    body.categoryId,
+    CATEGORY_SEEDS[0]?.id ?? 'cat-main',
+  );
+
+  const existingProduct =
+    existingIndex === -1 ? null : state.products[existingIndex];
+  const baseProduct: ProductRecord = existingProduct
+    ? { ...existingProduct }
+    : {
+        id: createProductId(storeId, state.nextSeq),
+        storeId,
+        spuCode: createSpuCode(state.nextSeq),
+        name: '',
+        subtitle: '',
+        description: '',
+        categoryId,
+        kind: 'single',
+        price: 0,
+        originalPrice: null,
+        stock: 0,
+        salesMonthly: 0,
+        tags: [],
+        status: 'off_shelf',
+        soldoutMode: null,
+        remainStock: 0,
+        recoverAt: null,
+        soldoutReason: '',
+        syncToPlatform: true,
+        notifyManager: false,
+        timedOnShelfAt: null,
+        imageUrl: '',
+        updatedAt: toDateTimeText(new Date()),
+      };
+
+  baseProduct.name = normalizeText(body.name, baseProduct.name);
+  baseProduct.subtitle = normalizeText(body.subtitle, baseProduct.subtitle);
+  baseProduct.description = normalizeText(
+    body.description,
+    baseProduct.description || `${baseProduct.name}，${baseProduct.subtitle}`,
+  );
+  baseProduct.categoryId = CATEGORY_SEEDS.some((item) => item.id === categoryId)
+    ? categoryId
+    : baseProduct.categoryId;
+  baseProduct.kind = normalizeKind(body.kind, baseProduct.kind);
+  baseProduct.price = Number(
+    normalizeNumber(body.price, baseProduct.price, 0).toFixed(2),
+  );
+  const originalPrice = normalizeNumber(body.originalPrice, -1, 0);
+  baseProduct.originalPrice =
+    originalPrice > 0 ? Number(originalPrice.toFixed(2)) : null;
+  baseProduct.stock = normalizeInt(body.stock, baseProduct.stock, 0);
+  baseProduct.tags = normalizeTags(body.tags);
+  baseProduct.status = nextStatus;
+  baseProduct.soldoutMode = nextStatus === 'sold_out' ? 'today' : null;
+  baseProduct.recoverAt = null;
+  baseProduct.soldoutReason = nextStatus === 'sold_out' ? '库存售罄' : '';
+  baseProduct.remainStock = baseProduct.stock;
+  baseProduct.syncToPlatform = true;
+  baseProduct.notifyManager = false;
+  baseProduct.timedOnShelfAt =
+    shelfMode === 'scheduled' ? normalizeText(body.timedOnShelfAt) : null;
+  baseProduct.updatedAt = toDateTimeText(new Date());
+
+  if (!baseProduct.name) {
+    return {
+      code: 400,
+      data: null,
+      message: '商品名称不能为空',
+    };
+  }
+
+  if (existingIndex === -1) {
+    state.products.unshift(baseProduct);
+    state.nextSeq += 1;
+  } else {
+    state.products.splice(existingIndex, 1, baseProduct);
+  }
+
+  return {
+    code: 200,
+    data: toDetailItem(baseProduct),
+  };
+});
+
+/** 删除商品。 */
+Mock.mock(/\/product\/delete/, 'post', (options: MockRequestOptions) => {
+  const body = parseBody(options);
+  const storeId = normalizeText(body.storeId);
+  const productId = normalizeText(body.productId);
+  if (!storeId || !productId) {
+    return { code: 400, data: null, message: '参数不完整' };
+  }
+  const state = ensureStoreState(storeId);
+  state.products = state.products.filter((item) => item.id !== productId);
+  return { code: 200, data: null };
+});
+
+/** 修改商品状态。 */
+Mock.mock(
+  /\/product\/status\/change/,
+  'post',
+  (options: MockRequestOptions) => {
+    const body = parseBody(options);
+    const storeId = normalizeText(body.storeId);
+    const productId = normalizeText(body.productId);
+    if (!storeId || !productId) {
+      return { code: 400, data: null, message: '参数不完整' };
+    }
+    const state = ensureStoreState(storeId);
+    const product = state.products.find((item) => item.id === productId);
+    if (!product) return { code: 404, data: null, message: '商品不存在' };
+
+    const nextStatus = normalizeStatus(body.status, product.status);
+    product.status = nextStatus;
+    if (nextStatus === 'sold_out') {
+      product.soldoutMode = 'today';
+      product.soldoutReason = product.soldoutReason || '库存售罄';
+      product.remainStock = 0;
+      product.stock = 0;
+    } else {
+      product.soldoutMode = null;
+      product.recoverAt = null;
+      product.soldoutReason = '';
+    }
+    product.updatedAt = toDateTimeText(new Date());
+    return { code: 200, data: toListItem(product) };
+  },
+);
+
+/** 商品沽清。 */
+Mock.mock(/\/product\/soldout/, 'post', (options: MockRequestOptions) => {
+  const body = parseBody(options);
+  const storeId = normalizeText(body.storeId);
+  const productId = normalizeText(body.productId);
+  if (!storeId || !productId) {
+    return { code: 400, data: null, message: '参数不完整' };
+  }
+  const state = ensureStoreState(storeId);
+  const product = state.products.find((item) => item.id === productId);
+  if (!product) return { code: 404, data: null, message: '商品不存在' };
+
+  const mode = normalizeSoldoutMode(body.mode, 'today');
+  const remainStock = normalizeInt(body.remainStock, 0, 0);
+  product.status = 'sold_out';
+  product.soldoutMode = mode;
+  product.remainStock = remainStock;
+  product.stock = remainStock;
+  product.soldoutReason = normalizeText(body.reason);
+  product.recoverAt = mode === 'timed' ? normalizeText(body.recoverAt) : null;
+  product.syncToPlatform = Boolean(body.syncToPlatform);
+  product.notifyManager = Boolean(body.notifyManager);
+  product.updatedAt = toDateTimeText(new Date());
+  return { code: 200, data: toDetailItem(product) };
+});
+
+/** 批量商品动作。 */
+Mock.mock(/\/product\/batch/, 'post', (options: MockRequestOptions) => {
+  const body = parseBody(options);
+  const storeId = normalizeText(body.storeId);
+  const action = normalizeText(body.action) as BatchActionType;
+  const productIds = Array.isArray(body.productIds)
+    ? body.productIds.map((item) => String(item || '').trim()).filter(Boolean)
+    : [];
+
+  if (!storeId || productIds.length === 0) {
+    return {
+      code: 400,
+      data: null,
+      message: '批量操作参数不完整',
+    };
+  }
+
+  const state = ensureStoreState(storeId);
+  const idSet = new Set(productIds);
+  const targets = state.products.filter((item) => idSet.has(item.id));
+  let successCount = 0;
+
+  if (action === 'batch_delete') {
+    const before = state.products.length;
+    state.products = state.products.filter((item) => !idSet.has(item.id));
+    successCount = before - state.products.length;
+  } else {
+    for (const item of targets) {
+      switch (action) {
+        case 'batch_off': {
+          item.status = 'off_shelf';
+          item.soldoutMode = null;
+          item.recoverAt = null;
+          item.soldoutReason = '';
+
+          break;
+        }
+        case 'batch_on': {
+          item.status = 'on_sale';
+          item.soldoutMode = null;
+          item.recoverAt = null;
+          item.soldoutReason = '';
+
+          break;
+        }
+        case 'batch_soldout': {
+          item.status = 'sold_out';
+          item.soldoutMode = normalizeSoldoutMode(body.mode, 'today');
+          item.remainStock = normalizeInt(body.remainStock, 0, 0);
+          item.stock = item.remainStock;
+          item.soldoutReason = normalizeText(body.reason);
+          item.recoverAt =
+            item.soldoutMode === 'timed' ? normalizeText(body.recoverAt) : null;
+          item.syncToPlatform = Boolean(body.syncToPlatform ?? true);
+          item.notifyManager = Boolean(body.notifyManager ?? false);
+
+          break;
+        }
+        // No default
+      }
+      item.updatedAt = toDateTimeText(new Date());
+      successCount += 1;
+    }
+  }
+
+  const totalCount = productIds.length;
+  const failedCount = Math.max(totalCount - successCount, 0);
+  return {
+    code: 200,
+    data: {
+      action,
+      totalCount,
+      successCount,
+      failedCount,
+    },
+  };
+});

apps/web-antd/src/preferences.ts

@@ -8,6 +8,13 @@ import { defineOverridesPreferences } from '@vben/preferences';
 export const overridesPreferences = defineOverridesPreferences({
   // overrides
   app: {
+    accessMode: 'backend',
+    defaultHomePath: '/dashboard/console',
+    enableRefreshToken: true,
+    loginExpiredMode: 'modal',
     name: import.meta.env.VITE_APP_TITLE,
   },
+  theme: {
+    mode: 'light',
+  },
 });

apps/web-antd/src/router/access.ts

@@ -1,6 +1,7 @@
 import type {
   ComponentRecordType,
   GenerateMenuAndRoutesOptions,
+  RouteRecordStringComponent,
 } from '@vben/types';
 
 import { generateAccessible } from '@vben/access';
@@ -14,6 +15,11 @@ import { $t } from '#/locales';
 
 const forbiddenComponent = () => import('#/views/_core/fallback/forbidden.vue');
 
+const PRODUCT_PATH = '/product';
+const PRODUCT_DETAIL_PATH = '/product/detail';
+const PRODUCT_DETAIL_NAME = 'ProductDetail';
+const PRODUCT_LIST_PATH = '/product/list';
+
 async function generateAccess(options: GenerateMenuAndRoutesOptions) {
   const pageMap: ComponentRecordType = import.meta.glob('../views/**/*.vue');
 
@@ -29,7 +35,8 @@ async function generateAccess(options: GenerateMenuAndRoutesOptions) {
         content: `${$t('common.loadingMenu')}...`,
         duration: 1.5,
       });
-      return await getAllMenusApi();
+      const menuList = await getAllMenusApi();
+      return ensureProductDetailRoute(menuList);
     },
     // 可以指定没有权限跳转403页面
     forbiddenComponent,
@@ -39,4 +46,93 @@ async function generateAccess(options: GenerateMenuAndRoutesOptions) {
   });
 }
 
+function ensureProductDetailRoute(
+  routes: RouteRecordStringComponent[],
+): RouteRecordStringComponent[] {
+  const clonedRoutes = cloneMenuRoutes(routes);
+  if (containsRoute(clonedRoutes, PRODUCT_DETAIL_PATH, PRODUCT_DETAIL_NAME)) {
+    return clonedRoutes;
+  }
+
+  const productRoute = findProductRoute(clonedRoutes);
+  if (!productRoute) {
+    return clonedRoutes;
+  }
+
+  const productChildren = [...(productRoute.children ?? [])];
+  const listMeta = productChildren.find(
+    (item) => String(item.path || '').trim() === PRODUCT_LIST_PATH,
+  )?.meta;
+
+  productChildren.push({
+    name: PRODUCT_DETAIL_NAME,
+    path: PRODUCT_DETAIL_PATH,
+    component: '/views/product/detail/index.vue',
+    meta: {
+      ...listMeta,
+      title: '商品详情',
+      hideInMenu: true,
+    },
+  });
+
+  productRoute.children = productChildren;
+  return clonedRoutes;
+}
+
+function cloneMenuRoutes(
+  routes: RouteRecordStringComponent[],
+): RouteRecordStringComponent[] {
+  return routes.map((route) => ({
+    ...route,
+    meta: route.meta ? { ...route.meta } : route.meta,
+    children: route.children ? cloneMenuRoutes(route.children) : undefined,
+  }));
+}
+
+function containsRoute(
+  routes: RouteRecordStringComponent[],
+  path: string,
+  name: string,
+): boolean {
+  for (const route of routes) {
+    const routePath = String(route.path || '').trim();
+    const routeName = String(route.name || '').trim();
+    if (routePath === path || routeName === name) {
+      return true;
+    }
+    if (route.children && containsRoute(route.children, path, name)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function findProductRoute(
+  routes: RouteRecordStringComponent[],
+): null | RouteRecordStringComponent {
+  for (const route of routes) {
+    const routePath = String(route.path || '').trim();
+    const routeName = String(route.name || '').trim();
+    const hasProductListChild = (route.children ?? []).some(
+      (item) => String(item.path || '').trim() === PRODUCT_LIST_PATH,
+    );
+
+    if (
+      routePath === PRODUCT_PATH ||
+      routeName === 'Product' ||
+      hasProductListChild
+    ) {
+      return route;
+    }
+
+    if (route.children) {
+      const nestedMatch = findProductRoute(route.children);
+      if (nestedMatch) {
+        return nestedMatch;
+      }
+    }
+  }
+  return null;
+}
+
 export { generateAccess };

apps/web-antd/src/router/routes/external/merchant.ts

@@ -0,0 +1,29 @@
+import type { RouteRecordRaw } from 'vue-router';
+
+import { BasicLayout } from '#/layouts';
+import { $t } from '#/locales';
+
+const routes: RouteRecordRaw[] = [
+  {
+    component: BasicLayout,
+    meta: {
+      hideInMenu: true,
+      title: $t('page.merchant.title'),
+    },
+    name: 'MerchantLayout',
+    path: '/merchant',
+    children: [
+      {
+        name: 'MerchantCenter',
+        path: 'center',
+        component: () => import('#/views/merchant/center/index.vue'),
+        meta: {
+          hideInMenu: true,
+          title: $t('page.merchant.center'),
+        },
+      },
+    ],
+  },
+];
+
+export default routes;

apps/web-antd/src/router/routes/external/personal.ts

@@ -0,0 +1,29 @@
+import type { RouteRecordRaw } from 'vue-router';
+
+import { BasicLayout } from '#/layouts';
+import { $t } from '#/locales';
+
+const routes: RouteRecordRaw[] = [
+  {
+    component: BasicLayout,
+    meta: {
+      hideInMenu: true,
+      title: $t('page.auth.profile'),
+    },
+    name: 'PersonalLayout',
+    path: '/personal',
+    children: [
+      {
+        name: 'PersonalCenter',
+        path: 'center',
+        component: () => import('#/views/personal/center/index.vue'),
+        meta: {
+          hideInMenu: true,
+          title: $t('page.auth.profile'),
+        },
+      },
+    ],
+  },
+];
+
+export default routes;

apps/web-antd/src/router/routes/index.ts

@@ -9,17 +9,18 @@ const dynamicRouteFiles = import.meta.glob('./modules/**/*.ts', {
 });
 
 // 有需要可以自行打开注释，并创建文件夹
-// const externalRouteFiles = import.meta.glob('./external/**/*.ts', { eager: true });
+const externalRouteFiles = import.meta.glob('./external/**/*.ts', {
+  eager: true,
+});
 // const staticRouteFiles = import.meta.glob('./static/**/*.ts', { eager: true });
 
 /** 动态路由 */
 const dynamicRoutes: RouteRecordRaw[] = mergeRouteModules(dynamicRouteFiles);
 
 /** 外部路由列表，访问这些页面可以不需要Layout，可能用于内嵌在别的系统(不会显示在菜单中) */
-// const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles);
 // const staticRoutes: RouteRecordRaw[] = mergeRouteModules(staticRouteFiles);
 const staticRoutes: RouteRecordRaw[] = [];
-const externalRoutes: RouteRecordRaw[] = [];
+const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles);
 
 /** 路由列表，由基本路由、外部路由和404兜底路由组成
  *  无需走权限验证（会一直显示在菜单中） */

apps/web-antd/src/router/routes/modules/order.ts

@@ -0,0 +1,36 @@
+import type { RouteRecordRaw } from 'vue-router';
+
+/** 文件职责：订单管理模块静态路由。 */
+const routes: RouteRecordRaw[] = [
+  {
+    meta: {
+      icon: 'lucide:receipt-text',
+      order: 15,
+      title: '订单管理',
+    },
+    name: 'Order',
+    path: '/order',
+    children: [
+      {
+        name: 'OrderHall',
+        path: '/order/hall',
+        component: () => import('#/views/order/hall/index.vue'),
+        meta: {
+          icon: 'lucide:layout-dashboard',
+          title: '订单大厅',
+        },
+      },
+      {
+        name: 'OrderAll',
+        path: '/order/list',
+        component: () => import('#/views/order/list/index.vue'),
+        meta: {
+          icon: 'lucide:list-ordered',
+          title: '全部订单',
+        },
+      },
+    ],
+  },
+];
+
+export default routes;