diff --git a/superpowers/specs/2026-06-06-api-collaboration-design.md b/superpowers/specs/2026-06-06-api-collaboration-design.md
new file mode 100644
index 0000000..ef5cf89
--- /dev/null
+++ b/superpowers/specs/2026-06-06-api-collaboration-design.md
@@ -0,0 +1,483 @@
+# 前后端智能协作方案设计文档
+
+> **文档版本**: v1.0  
+> **创建日期**: 2026-06-06  
+> **适用范围**: rui-frontend 所有前端项目（admin-ui、cashier-mobile、cashier-customer）
+
+---
+
+## 一、问题背景
+
+### 1.1 当前痛点
+
+admin-ui 项目中存在**表单字段与后台 API 不同步**的问题：
+
+1. **表单字段硬编码** - 19 个 FormDialog 组件全部采用手动定义字段（如 `UserFormDialog.vue` 中的 `username`, `password`, `userType` 等）
+2. **缺少 TypeScript 类型** - Service 层大量使用 `any` 类型，没有与后端 DTO 对应的接口定义
+3. **BaseService 泛型未充分利用** - `BaseService<T>` 定义了泛型，但子类没有传入具体类型
+4. **API 文档未利用** - 后端已提供 `/v3/api-docs`（SpringDoc OpenAPI），但前端未使用
+
+### 1.2 影响
+
+- 后端字段变更时，前端需要手动修改所有相关表单
+- 缺少编译时类型检查，运行时容易出错
+- 前后端协作效率低，沟通成本高
+
+---
+
+## 二、设计目标
+
+1. **类型安全** - 前端类型与后端 API 自动同步
+2. **减少样板代码** - 表单配置化，减少 70% 重复代码
+3. **支持自定义扩展** - 复杂表单可自定义字段和逻辑
+4. **多模块支持** - 适配微服务架构（聚合启动器 + 独立服务）
+5. **自动化检测** - 防止前后端不同步上线
+
+---
+
+## 三、架构设计
+
+### 3.1 整体架构
+
+```
+API设计规范.md (单一事实来源)
+    │
+    ├── 包含所有 api-docs 地址
+    └── 由后端团队维护
+    
+    ↓ 自动解析
+
+scripts/parse-api-config.ts
+    │
+    └── 读取并解析 Markdown 中的 URL
+    └── 识别聚合启动器和独立服务
+    
+    ↓ 动态配置
+
+scripts/generate-api.ts
+    │
+    ├── 聚合启动器模块（通过 group 参数获取）
+    ├── 独立服务模块（直接访问）
+    ├── 生成类型定义文件
+    ├── 生成统一导出
+    └── 生成模块映射
+    
+    ↓ 类型文件
+
+src/types/
+    ├── system-api.d.ts      # 系统服务类型
+    ├── user-api.d.ts        # 用户服务类型
+    ├── cashier-api.d.ts     # 收银服务类型
+    ├── api.d.ts             # 统一导出
+    └── api-modules.json     # 模块映射
+    
+    ↓ 类型驱动
+
+前端代码
+    │
+    ├── Service 层（类型安全）
+    ├── useApiForm() 组合式函数
+    ├── ApiFormDialog 组件
+    └── 自定义扩展（插槽机制）
+```
+
+### 3.2 核心组件
+
+| 组件 | 职责 | 说明 |
+|------|------|------|
+| `parse-api-config.ts` | 解析 API 规范文档 | 从 Markdown 读取 api-docs 地址 |
+| `generate-api.ts` | 生成类型定义 | 调用 openapi-typescript 生成 .d.ts |
+| `useApiForm()` | 类型驱动表单管理 | 组合式函数，自动生成表单配置 |
+| `ApiFormDialog` | 配置化表单组件 | 根据字段配置自动渲染表单 |
+| `BaseService<T>` | 类型安全 Service 基类 | 保留现有架构，增强类型 |
+
+---
+
+## 四、详细设计
+
+### 4.1 API 配置解析（parse-api-config.ts）
+
+**核心功能**：从 `API设计规范.md` 自动读取 api-docs 地址
+
+**聚合启动器识别规则**：
+- 端口 9399 → 聚合启动器，包含多个模块（/user, /system）
+- 通过 `?group=xxx` 参数获取子模块
+- 其他端口 → 独立服务
+
+**配置结构**：
+
+```typescript
+interface ApiModuleConfig {
+  name: string        // 模块名：user, system, cashier
+  url: string         // api-docs URL
+  output: string      // 输出路径
+  prefix: string      // API 路径前缀
+  description: string // 模块描述
+  aggregator?: string // 所属聚合器（如果有）
+}
+```
+
+**解析示例**：
+
+```markdown
+# API设计规范.md
+
+http://localhost:9399/v3/api-docs  # 聚合启动器 API 文档（开发调试）
+http://localhost:9601/v3/api-docs  # 收银服务 API 文档
+```
+
+解析结果：
+- `9399` → 聚合启动器 → 展开为 user、system 两个模块
+- `9601` → 独立服务 → cashier 模块
+
+### 4.2 类型生成（generate-api.ts）
+
+**生成流程**：
+
+1. 读取 API设计规范.md
+2. 识别聚合启动器和独立服务
+3. 为每个模块生成类型文件
+4. 生成统一导出文件
+5. 生成模块映射文件
+
+**输出文件结构**：
+
+```
+src/types/
+├── user-api.d.ts         # 用户服务类型（来自聚合启动器）
+├── system-api.d.ts       # 系统服务类型（来自聚合启动器）
+├── cashier-api.d.ts      # 收银服务类型（独立服务）
+├── api.d.ts              # 统一导出
+│   └── export type * from './user-api'
+│   └── export type * from './system-api'
+│   └── export type * from './cashier-api'
+└── api-modules.json      # 模块映射（用于运行时）
+    └── {
+    └──   "aggregator": [
+    └──     { "name": "user", "prefix": "/user" },
+    └──     { "name": "system", "prefix": "/system" }
+    └──   ]
+    └── }
+```
+
+### 4.3 类型驱动表单（useApiForm）
+
+**核心功能**：根据 TypeScript 类型自动生成表单配置
+
+**接口设计**：
+
+```typescript
+interface FieldConfig<T = any> {
+  key: keyof T           // 字段名（类型安全）
+  label: string          // 字段标签
+  type: FieldType        // 字段类型
+  required?: boolean     // 是否必填
+  rules?: any[]          // 验证规则
+  options?: Option[]     // 选项（select/radio/checkbox）
+  disabled?: boolean | ((form: T) => boolean)
+  placeholder?: string
+  props?: Record<string, any>
+}
+
+interface FormConfig<T> {
+  initial?: Partial<T>   // 初始值
+  fields: FieldConfig<T>[] // 字段配置
+  onSubmit: (data: T) => Promise<void>
+  beforeSubmit?: (data: T) => boolean | string
+}
+
+function useApiForm<T extends Record<string, any>>(
+  config: FormConfig<T>
+): {
+  formRef: Ref<FormInstance>
+  form: Ref<Partial<T>>
+  rules: ComputedRef<Record<string, any[]>>
+  loading: Ref<boolean>
+  handleSubmit: () => Promise<boolean>
+  resetForm: (initial?: Partial<T>) => void
+}
+```
+
+### 4.4 配置化表单组件（ApiFormDialog）
+
+**核心功能**：根据字段配置自动渲染表单元素
+
+**支持的字段类型**：
+
+| 类型 | 组件 | 说明 |
+|------|------|------|
+| `input` | ElInput | 文本输入 |
+| `textarea` | ElInput(type="textarea") | 多行文本 |
+| `select` | ElSelect | 下拉选择 |
+| `radio` | ElRadioGroup | 单选按钮 |
+| `checkbox` | ElCheckboxGroup | 多选框 |
+| `number` | ElInputNumber | 数字输入 |
+| `tree-select` | ElTreeSelect | 树形选择 |
+| `date` | ElDatePicker | 日期选择 |
+| `datetime` | ElDatePicker | 日期时间选择 |
+
+**自定义扩展机制**：
+
+```vue
+<ApiFormDialog
+  v-model:visible="visible"
+  v-model:form="form"
+  :fields="fields"
+  :rules="rules"
+  @submit="handleSubmit"
+>
+  <!-- 自定义字段插槽 -->
+  <template #custom-fields="{ form }">
+    <el-form-item label="自定义部门">
+      <el-tree-select v-model="customDeptIds" :data="deptTree" />
+    </el-form-item>
+  </template>
+</ApiFormDialog>
+```
+
+### 4.5 Service 层增强
+
+**保留现有 BaseService 架构**，增强类型安全：
+
+```typescript
+// 现有架构保持不变
+class BaseService<T = any> {
+  protected baseUrl: string
+  
+  async page(params: PageParams & Record<string, any>): Promise<PageResult<T>>
+  async list(params?: Record<string, any>): Promise<T[]>
+  async getById(id: number | string): Promise<T>
+  async add(data: Partial<T>): Promise<T>
+  async update(data: Partial<T> & { id: number | string }): Promise<boolean>
+  async remove(id: number | string): Promise<boolean>
+}
+
+// 使用时传入具体类型
+class UserService extends BaseService<UserDTO> {
+  constructor() {
+    super('/user/admin/user')
+  }
+}
+```
+
+---
+
+## 五、使用示例
+
+### 5.1 标准表单（完全配置化）
+
+```vue
+<script setup lang="ts">
+import { useApiForm } from '@/composables/useApiForm'
+import { userService } from '@/service/user/userService'
+import type { components } from '@/types/user-api'
+
+type UserDTO = components['schemas']['UserDTO']
+
+const { formRef, form, rules, loading, handleSubmit, resetForm } = useApiForm<UserDTO>({
+  initial: { userType: 1, status: 1 },
+  fields: [
+    { key: 'username', label: '用户名', type: 'input', required: true },
+    { key: 'password', label: '密码', type: 'input', required: true, props: { type: 'password' } },
+    { key: 'userType', label: '用户类型', type: 'select', options: [
+      { label: '普通用户', value: 1 },
+      { label: '管理员', value: 2 }
+    ]},
+    { key: 'status', label: '状态', type: 'radio', options: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 }
+    ]}
+  ],
+  onSubmit: async (data) => {
+    await userService.add(data)
+  }
+})
+</script>
+
+<template>
+  <ApiFormDialog
+    v-model:visible="visible"
+    v-model:form="form"
+    title="新增用户"
+    :fields="fields"
+    :rules="rules"
+    :loading="loading"
+    @submit="handleSubmit"
+  />
+</template>
+```
+
+### 5.2 自定义扩展表单
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+import { useApiForm } from '@/composables/useApiForm'
+import { roleService } from '@/service/system/roleService'
+import type { components } from '@/types/system-api'
+
+type RoleDTO = components['schemas']['RoleDTO']
+
+const selectedDeptIds = ref<number[]>([])
+const showCustomDept = computed(() => form.value.dataScope === 5)
+
+const { form, fields, rules, handleSubmit } = useApiForm<RoleDTO>({
+  fields: [
+    { key: 'roleCode', label: '角色编码', type: 'input', required: true },
+    { key: 'roleName', label: '角色名称', type: 'input', required: true },
+    { key: 'dataScope', label: '数据范围', type: 'select', options: [
+      { label: '全部', value: 1 },
+      { label: '自定义', value: 5 }
+    ]}
+  ],
+  onSubmit: async (data) => {
+    // 自定义验证
+    if (data.dataScope === 5 && selectedDeptIds.value.length === 0) {
+      throw new Error('请选择部门')
+    }
+    await roleService.add(data)
+  }
+})
+</script>
+
+<template>
+  <ApiFormDialog
+    v-model:visible="visible"
+    v-model:form="form"
+    :fields="fields"
+    :rules="rules"
+    @submit="handleSubmit"
+  >
+    <template #custom-fields>
+      <el-form-item v-if="showCustomDept" label="选择部门" required>
+        <el-tree-select v-model="selectedDeptIds" :data="deptTree" />
+      </el-form-item>
+    </template>
+  </ApiFormDialog>
+</template>
+```
+
+---
+
+## 六、自动化机制
+
+### 6.1 Git Hook（提交前检查）
+
+```typescript
+// scripts/check-api-changes.ts
+function checkApiChanges() {
+  const currentHash = execSync('git hash-object src/types/*.d.ts').toString()
+  
+  try {
+    execSync('pnpm api:generate', { stdio: 'pipe' })
+    const newHash = execSync('git hash-object src/types/*.d.ts').toString()
+    
+    if (currentHash !== newHash) {
+      console.error('❌ API types have changed!')
+      console.error('Please run "pnpm api:generate" and commit the changes.')
+      process.exit(1)
+    }
+  } catch (error) {
+    console.warn('⚠️ Could not check API changes')
+  }
+}
+```
+
+### 6.2 脚本命令
+
+```json
+{
+  "scripts": {
+    "api:generate": "tsx scripts/generate-api.ts",
+    "api:check": "tsx scripts/check-api-changes.ts",
+    "api:watch": "nodemon --watch ../docs/standards/API设计规范.md --exec 'pnpm api:generate'"
+  }
+}
+```
+
+---
+
+## 七、扩展性设计
+
+### 7.1 新增模块
+
+当后端新增模块时，只需在 `API设计规范.md` 中添加：
+
+```markdown
+http://localhost:9399/v3/api-docs?group=订单服务  # 订单服务 API 文档
+http://localhost:9701/v3/api-docs                  # 新独立服务 API 文档
+```
+
+前端自动识别：
+- 端口 9399 → 聚合启动器，通过 `group` 参数获取
+- 新端口 9701 → 独立服务，直接访问
+
+### 7.2 新增字段类型
+
+在 `ApiFormDialog.vue` 中添加新的字段类型渲染逻辑即可。
+
+---
+
+## 八、实施计划
+
+### Phase 1: 基础搭建（1-2 天）
+
+1. 安装依赖：`openapi-typescript`, `tsx`, `nodemon`
+2. 创建 `scripts/parse-api-config.ts` - 解析 API 规范
+3. 创建 `scripts/generate-api.ts` - 生成类型
+4. 配置 package.json 脚本
+
+### Phase 2: 类型生成（1 天）
+
+1. 运行 `pnpm api:generate` 生成初始类型
+2. 验证类型正确性
+3. 提交生成的类型文件
+
+### Phase 3: 表单工具（2-3 天）
+
+1. 创建 `useApiForm()` 组合式函数
+2. 创建 `ApiFormDialog.vue` 组件
+3. 编写单元测试
+
+### Phase 4: 试点迁移（2-3 天）
+
+1. 选择 2-3 个简单表单进行迁移
+2. 验证方案可行性
+3. 收集反馈优化
+
+### Phase 5: 全面推广（1-2 周）
+
+1. 迁移所有标准表单
+2. 保留自定义表单的特殊逻辑
+3. 编写迁移文档
+
+### Phase 6: 自动化（1 天）
+
+1. 配置 Git Hook
+2. 配置 CI/CD 检查
+3. 编写使用文档
+
+---
+
+## 九、风险评估
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|---------|
+| 后端 API 文档不准确 | 生成的类型错误 | 建立 API 文档审核机制 |
+| 聚合启动器不可用 | 无法生成类型 | 支持独立服务直接访问 |
+| 复杂表单迁移困难 | 影响进度 | 保留自定义扩展机制 |
+| 团队成员学习成本 | 初期效率下降 | 提供详细文档和示例 |
+
+---
+
+## 十、成功标准
+
+1. ✅ 所有 Service 层使用具体类型替代 `any`
+2. ✅ 标准表单代码量减少 70%
+3. ✅ 后端字段变更时，前端编译期即可发现
+4. ✅ 新增模块时，类型自动生成
+5. ✅ 提交时自动检测 API 变更
+
+---
+
+> **下一步**: 编写实现计划（implementation plan）