---
slug: tech-v1-1-extension
---

# 「伴享」技术方案 V1.1 — 扩展架构

**版本**: V1.1  
**对应PRD**: PRD-V1.1-体验优化版  
**更新日期**: 2026-02-16  

---

## 1. 架构变更概述

V1.1在V1.0基础上新增：社区队长、会员订阅、家政服务、日常消费。无架构层面重大变更，主要是新增数据表和API端点。

### 1.1 变更影响矩阵

| 层级 | 变更 | 影响范围 |
|------|------|----------|
| 数据库 | 新增6张表 | 队长/会员/服务商/服务人员/商品/购物车 |
| API | 新增4组端点 | /captains, /membership, /services, /products |
| Flutter | 新增4个Feature模块 | captain/, membership/, housekeeping/, shopping/ |
| 第三方 | 无新增 | - |
| 部署 | 无变更 | 同V1.0 Docker Compose |

---

## 2. 新增数据库表

### 2.1 增量DDL

```sql
-- ===========================
-- V1.1 增量DDL
-- ===========================

-- 1. 队长相关
CREATE TABLE captain_applications (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT REFERENCES users(id),
  bio TEXT,
  specialties TEXT[],
  serving_area VARCHAR(50),
  contact_info JSONB,
  status VARCHAR(20) DEFAULT 'pending'
    CHECK (status IN ('pending', 'approved', 'rejected')),
  reviewer_note TEXT,
  reviewed_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE captains (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT UNIQUE REFERENCES users(id),
  level VARCHAR(20) DEFAULT 'trainee'
    CHECK (level IN ('trainee', 'silver', 'gold', 'honor')),
  bio TEXT,
  specialties TEXT[],
  serving_area VARCHAR(50),
  total_activities INTEGER DEFAULT 0,
  total_participants INTEGER DEFAULT 0,
  total_new_users INTEGER DEFAULT 0,
  avg_rating DECIMAL(2,1) DEFAULT 0,
  monthly_subsidy DECIMAL(10,2) DEFAULT 0,
  status VARCHAR(20) DEFAULT 'active',
  approved_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- 2. 会员
CREATE TABLE memberships (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT REFERENCES users(id),
  plan VARCHAR(20) NOT NULL CHECK (plan IN ('monthly', 'yearly')),
  price DECIMAL(10,2) NOT NULL,
  paid_by_user_id BIGINT REFERENCES users(id),
  starts_at TIMESTAMP NOT NULL,
  expires_at TIMESTAMP NOT NULL,
  auto_renew BOOLEAN DEFAULT FALSE,
  status VARCHAR(20) DEFAULT 'active'
    CHECK (status IN ('active', 'expired', 'cancelled')),
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_membership_user ON memberships(user_id, status);

-- 用户表新增字段
ALTER TABLE users ADD COLUMN is_member BOOLEAN DEFAULT FALSE;
ALTER TABLE users ADD COLUMN member_expires_at TIMESTAMP;
ALTER TABLE users ADD COLUMN is_captain BOOLEAN DEFAULT FALSE;
ALTER TABLE users ADD COLUMN captain_level VARCHAR(20);

-- 3. 服务商
CREATE TABLE service_providers (
  id BIGSERIAL PRIMARY KEY,
  company_name VARCHAR(100),
  category VARCHAR(50),
  contact_phone VARCHAR(20),
  license_no VARCHAR(50),
  address TEXT,
  lat DECIMAL(10,7),
  lng DECIMAL(10,7),
  rating DECIMAL(2,1) DEFAULT 5.0,
  status VARCHAR(20) DEFAULT 'active',
  created_at TIMESTAMP DEFAULT NOW()
);

-- 4. 服务人员
CREATE TABLE service_workers (
  id BIGSERIAL PRIMARY KEY,
  provider_id BIGINT REFERENCES service_providers(id),
  name VARCHAR(50),
  avatar_url TEXT,
  skills TEXT[],
  rating DECIMAL(2,1) DEFAULT 5.0,
  service_count INTEGER DEFAULT 0,
  hourly_rate DECIMAL(10,2),
  status VARCHAR(20) DEFAULT 'available',
  created_at TIMESTAMP DEFAULT NOW()
);

-- 5. 服务订单
CREATE TABLE service_orders (
  id BIGSERIAL PRIMARY KEY,
  order_no VARCHAR(20) UNIQUE NOT NULL,
  user_id BIGINT REFERENCES users(id),
  worker_id BIGINT REFERENCES service_workers(id),
  service_type VARCHAR(50),
  scheduled_date DATE,
  scheduled_time TIME,
  duration_hours DECIMAL(3,1),
  address TEXT,
  requirements TEXT,
  amount DECIMAL(10,2),
  platform_fee DECIMAL(10,2),
  status VARCHAR(20) DEFAULT 'pending',
  rating INTEGER CHECK (rating BETWEEN 1 AND 5),
  review TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

-- 6. 商品
CREATE TABLE products (
  id BIGSERIAL PRIMARY KEY,
  provider_id BIGINT REFERENCES service_providers(id),
  name VARCHAR(100),
  category VARCHAR(50),
  description TEXT,
  image_url TEXT,
  price DECIMAL(10,2),
  unit VARCHAR(20),
  stock INTEGER DEFAULT 0,
  status VARCHAR(20) DEFAULT 'available',
  created_at TIMESTAMP DEFAULT NOW()
);

-- 7. 购物车
CREATE TABLE cart_items (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT REFERENCES users(id),
  product_id BIGINT REFERENCES products(id),
  quantity INTEGER DEFAULT 1,
  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(user_id, product_id)
);

-- 8. 配送订单
CREATE TABLE delivery_orders (
  id BIGSERIAL PRIMARY KEY,
  order_no VARCHAR(20) UNIQUE NOT NULL,
  user_id BIGINT REFERENCES users(id),
  provider_id BIGINT REFERENCES service_providers(id),
  items JSONB,
  total_amount DECIMAL(10,2),
  delivery_fee DECIMAL(10,2) DEFAULT 0,
  delivery_address TEXT,
  delivery_phone VARCHAR(11),
  estimated_delivery TIMESTAMP,
  status VARCHAR(20) DEFAULT 'pending',
  created_at TIMESTAMP DEFAULT NOW()
);

-- 9. 队长排行榜物化视图
CREATE MATERIALIZED VIEW captain_monthly_ranking AS
SELECT 
  c.user_id,
  u.nickname,
  u.avatar_url,
  c.level,
  COUNT(a.id) AS monthly_activities,
  c.avg_rating
FROM captains c
JOIN users u ON c.user_id = u.id
LEFT JOIN activities a ON a.creator_id = c.user_id 
  AND a.start_time >= date_trunc('month', CURRENT_DATE)
WHERE c.status = 'active'
GROUP BY c.user_id, u.nickname, u.avatar_url, c.level, c.avg_rating
ORDER BY monthly_activities DESC;
```

---

## 3. 新增API端点

### 3.1 队长模块 `/captains`

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /captains/apply | 申请成为队长 |
| GET | /captains/application-status | 查看申请状态 |
| GET | /captains/me/dashboard | 队长数据面板 |
| GET | /captains/ranking | 队长排行榜 |
| GET | /captains/:userId | 查看队长主页 |

**管理端（内部）**:
| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /admin/captains/applications | 待审核列表 |
| POST | /admin/captains/applications/:id/approve | 审核通过 |
| POST | /admin/captains/applications/:id/reject | 审核拒绝 |

### 3.2 会员模块 `/membership`

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /membership/plans | 会员方案列表 |
| GET | /membership/status | 当前会员状态 |
| POST | /membership/subscribe | 开通会员 |
| POST | /membership/generate-pay-link | 生成子女代付链接 |
| GET | /membership/pay/:token | 子女代付页面数据 |
| POST | /membership/pay/:token/confirm | 子女确认支付 |

### 3.3 家政服务 `/services/housekeeping`

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /services/housekeeping/workers | 服务人员列表 |
| GET | /services/housekeeping/workers/:id | 人员详情 |
| POST | /services/housekeeping/orders | 预约下单 |
| GET | /services/housekeeping/orders | 我的服务订单 |
| POST | /services/housekeeping/orders/:id/cancel | 取消 |
| POST | /services/housekeeping/orders/:id/review | 评价 |

### 3.4 日常消费 `/shopping`

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /shopping/providers | 商家列表 |
| GET | /shopping/products | 商品列表 |
| GET | /shopping/cart | 购物车 |
| POST | /shopping/cart/add | 加入购物车 |
| PUT | /shopping/cart/:id | 修改数量 |
| DELETE | /shopping/cart/:id | 删除 |
| POST | /shopping/orders | 配送下单 |
| GET | /shopping/orders | 配送订单列表 |

---

## 4. Flutter新增模块

### 4.1 新增Feature模块

```
features/
├── captain/                 # 社区队长
│   ├── captain_apply_page.dart
│   ├── captain_dashboard_page.dart
│   ├── captain_ranking_page.dart
│   └── captain_profile_page.dart
├── membership/              # 会员中心
│   ├── membership_page.dart
│   ├── pay_link_page.dart
│   └── widgets/
├── housekeeping/            # 家政服务
│   ├── worker_list_page.dart
│   ├── worker_detail_page.dart
│   ├── booking_page.dart
│   └── widgets/
├── shopping/                # 日常消费
│   ├── provider_list_page.dart
│   ├── product_list_page.dart
│   ├── cart_page.dart
│   ├── checkout_page.dart
│   └── widgets/
└── onboarding/              # 新手引导
    ├── onboarding_page.dart
    └── guide_overlay.dart
```

### 4.2 微信分享集成

```dart
// 使用 fluwx 插件
dependencies:
  fluwx: ^4.x

// 活动分享
Future<void> shareActivity(Activity activity) async {
  await fluwx.shareToWeChat(
    WeChatShareWebPageModel(
      webPage: 'https://h5.banxiang.com/activity/${activity.id}',
      title: activity.title,
      description: '来「伴享」一起参加吧！还剩${activity.remainingSlots}个名额',
      thumbnail: WeChatImage.network(activity.coverImage),
      scene: WeChatScene.session,
    ),
  );
}
```

---

## 5. 队长等级自动计算

```javascript
// 定时任务：每日凌晨更新队长等级
async function updateCaptainLevels() {
  const captains = await db.query('SELECT * FROM captains WHERE status = $1', ['active']);
  
  for (const captain of captains.rows) {
    let newLevel = 'trainee';
    
    if (captain.total_activities >= 50 && captain.avg_rating >= 4.75 && captain.total_new_users >= 100) {
      newLevel = 'gold';
    } else if (captain.total_activities >= 20 && captain.avg_rating >= 4.5 && captain.total_new_users >= 20) {
      newLevel = 'silver';
    }
    
    if (newLevel !== captain.level) {
      await db.query('UPDATE captains SET level = $1, updated_at = NOW() WHERE id = $2', [newLevel, captain.id]);
      // 发送升级通知
      await sendNotification(captain.user_id, 'CAPTAIN_LEVEL_UP', { newLevel });
    }
  }
  
  // 刷新排行榜
  await db.query('REFRESH MATERIALIZED VIEW captain_monthly_ranking');
}
```

---

## 6. 会员权限中间件

```javascript
// middleware/membership.js
function requireMembership(req, res, next) {
  if (!req.user.is_member || new Date(req.user.member_expires_at) < new Date()) {
    return res.status(403).json({
      success: false,
      error: {
        code: 'MEMBERSHIP_REQUIRED',
        message: '此功能需要开通会员',
        upgrade_url: '/membership/plans'
      }
    });
  }
  next();
}

// 免费用户限额检查
function checkFreeLimit(type) {
  return async (req, res, next) => {
    if (req.user.is_member) return next();
    
    const limits = {
      ai_chat: 20,       // 每天20条
      activity_join: 3,   // 每月3次
    };
    
    const count = await getUsageCount(req.user.id, type);
    if (count >= limits[type]) {
      return res.status(403).json({
        success: false,
        error: {
          code: 'FREE_LIMIT_EXCEEDED',
          message: type === 'ai_chat' 
            ? '今日AI对话次数已用完，开通会员享无限对话' 
            : '本月活动次数已用完，开通会员享无限参与',
          upgrade_url: '/membership/plans'
        }
      });
    }
    next();
  };
}
```

---

## 7. 子女代付H5页面

```
技术栈：Vue 3 + Vant（H5页面，微信内置浏览器打开）

流程：
1. 父母端生成代付链接 → 分享到微信
2. 子女点击链接 → 打开H5页面
3. H5页面展示：父母信息 + 会员方案 + 价格
4. 子女点击支付 → 调起微信支付JSAPI
5. 支付成功 → 后端更新会员状态 → Push通知父母
```

---

**文档结束**