# 天河基地小程序 - 软件需求文档

**版本**：1.1
**日期**：2026-04-07
**状态**：草稿（已经 Spec Review 修订）

---

## 第一章 项目概述

### 1.1 项目背景与目标

**项目名称**：天河基地小程序
**委托方**：天河基地（甲方）
**开发方**：乙方技术团队

**项目背景**：天河基地是以企业服务为核心的产业园区，需要一个数字化服务平台，整合园区入驻、活动、会场预约、成果对接等服务，并结合 AI 智能能力提升服务效率。

**核心目标**：
- 为企业/个人用户提供一站式园区服务入口
- 通过飞书集成实现审批流程数字化
- 通过 AI 能力降低信息填写门槛、提升运营洞察

**交付时间**：合同签订后 **25 个工作日**内提交完整功能初版用于内部测试

---

### 1.2 技术架构选型

| 层级 | 技术选型 |
|------|---------|
| 前端 | 微信原生小程序（WXML / WXSS / JavaScript）|
| 后端 | Python（建议 FastAPI 或 Django REST Framework）|
| 数据库 | MySQL 8.0+（关系型）|
| 文件存储 | 腾讯云 COS 或微信云存储 |
| AI 能力 | 接入大模型 API（如 GPT / 文心 / 通义）|
| OCR | 腾讯云 OCR 或百度 OCR |
| 地图 | 微信内置地图 / 腾讯地图 API |
| 短信 | 腾讯云短信 / 阿里云短信 |
| 第三方集成 | 飞书开放平台 API |
| 消息推送 | 微信订阅消息 + 飞书机器人 |

---

### 1.3 开发周期与功能优先级

**优先级定义**：
- **P0（必须上线）**：基础功能，影响核心流程
- **P1（应该上线）**：常规功能，提升体验
- **P2（可延后）**：AI 增强功能，迭代优化

**交付计划建议**：

| 阶段 | 时间 | 目标 |
|------|------|------|
| 第1周 | Day 1-5 | 架构搭建、用户认证、首页、关于基地 |
| 第2周 | Day 6-10 | 企业服务中心（入驻申请、场地展示、成果供需）+ 飞书集成启动（不可晚于 Day 6，需与客户 IT 团队联调）|
| 第3周 | Day 11-15 | 活动与会场预约、飞书集成完成 |
| 第4周 | Day 16-20 | 平台管理后台、消息通知、SMS 集成 |
| 第5周 | Day 21-25 | AI 功能（P2 项目，可能延期至上线后迭代）、集成测试、联调 |

> **注意**：AI 增强功能（P2）时间预算紧张，建议与甲方确认：P2 功能可在正式上线后第一个迭代版本补齐，不影响25日交付验收。

---

## 第二章 用户角色与权限矩阵

### 2.1 角色定义

| 角色 | 标识 | 说明 |
|------|------|------|
| 游客 | GUEST | 未登录用户，只能浏览公开信息 |
| 注册用户 | USER | 微信登录后的普通用户 |
| 企业用户 | ENTERPRISE | 完成企业认证的用户，可发布需求、申请入驻 |
| 社区合伙人 | PARTNER | 审核通过后，拥有部分后台查看权限 |
| 管理员 | ADMIN | 后台全权管理，内容审核、数据统计 |

### 2.2 权限矩阵

| 功能模块 | 游客 | 注册用户 | 企业用户 | 合伙人 | 管理员 |
|---------|------|---------|---------|-------|-------|
| 首页浏览 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 活动报名 | ❌ | ✅ | ✅ | ✅ | ✅ |
| 活动报名信息查看 | ❌ | ❌ | ❌ | ✅ | ✅ |
| 入驻申请 | ❌ | ✅ | ✅ | ✅ | ✅ |
| 发布需求（找人才/资金）| ❌ | ❌ | ✅ | ✅ | ✅ |
| 提交其他需求 | ❌ | ✅ | ✅ | ✅ | ✅ |
| 问题反馈 | ❌ | ✅ | ✅ | ✅ | ✅ |
| 会场预约 | ❌ | ✅ | ✅ | ✅ | ✅ |
| 收藏/关注内容 | ❌ | ✅ | ✅ | ✅ | ✅ |
| 内容审核 | ❌ | ❌ | ❌ | ❌ | ✅ |
| 用户管理 | ❌ | ❌ | ❌ | ❌ | ✅ |
| 数据统计后台 | ❌ | ❌ | ❌ | ❌ | ✅ |
| 评分管理 | ❌ | ❌ | ❌ | ❌ | ✅ |

---

## 第三章 功能模块需求

### 3.1 平台首页

#### 用户故事
- 作为**游客**，我希望打开小程序就能看到基地动态、活动公告、空间介绍，了解园区
- 作为**注册用户**，我希望首页能展示与我相关的推荐内容
- 作为**企业用户**，我希望快速入口能直达入驻申请、需求发布等核心功能

#### 业务流程
```
用户打开小程序
  ├── 未登录 → 展示公开内容（Banner/活动/空间）
  └── 已登录 → 展示个性化内容 + 快捷入口
        ├── Banner 轮播（后台配置）
        ├── 活动公告栏（近2周活动）
        ├── 空间展示（办公/商业/会场）
        ├── 科技成果对接入口
        ├── 企业需求发布入口
        ├── 技术经理人平台入口
        └── 申请成为社区合伙人入口
```

#### 数据模型与字段

**Banner 表（`banner`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| title | VARCHAR(100) | 标题 |
| image_url | VARCHAR(255) | 图片链接 |
| link_type | ENUM('page','url','none') | 跳转类型 |
| link_target | VARCHAR(255) | 跳转目标路径或 URL |
| sort_order | INT | 排序权重 |
| is_active | BOOLEAN | 是否启用 |
| created_at | DATETIME | 创建时间 |

#### API 接口清单

| 方法 | 路径 | 说明 | 优先级 |
|------|------|------|-------|
| GET | `/api/v1/banners` | 获取首页 Banner 列表 | P0 |
| GET | `/api/v1/home/activities` | 获取近2周活动（最多10条）| P0 |
| GET | `/api/v1/home/spaces/summary` | 获取空间展示摘要 | P0 |
| GET | `/api/v1/home/achievements` | 获取科技成果展示列表 | P0 |
| POST | `/api/v1/partner/apply` | 提交社区合伙人申请 | P1 |
| GET | `/api/v1/admin/partner-applications` | 后台查看合伙人申请列表 | P1 |
| PUT | `/api/v1/admin/partner-applications/{id}/review` | 审核合伙人申请 | P1 |
| GET | `/api/v1/admin/activity-registrations` | 合伙人/管理员查看活动报名信息 | P1 |

---

### 3.2 企业服务中心

#### 用户故事
- 作为**企业用户**，我希望在线提交入驻申请，并实时追踪审批进度
- 作为**企业用户**，我希望发布招聘、融资等需求，让其他用户看到
- 作为**企业用户**，我希望对场地/设施问题进行反馈并跟踪处理进度
- 作为**管理员**，我希望在飞书内完成审批，结果自动同步到小程序

#### 业务流程

**入驻申请流程：**
```
企业用户填写多步骤申请表单
  → 上传营业执照等材料（OCR 自动识别填充）
  → 提交申请
  → 飞书审批流程触发（通知审批人）
  → 审批进度实时同步到小程序
  → 审批通过 → 企业状态升级为"入驻企业"
  → 审批拒绝 → 通知用户并说明原因
```

**成果供需发布流程：**
```
企业用户填写需求（找人才/找资金/找政策/找技术）
  → AI 辅助生成标题和描述（可选）
  → 提交审核
  → 管理员审核通过后公开展示
  → 其他用户可查看并联系
```

**问题反馈流程：**
```
用户提交反馈（场地/设施/服务）
  → AI 自动分类工单类型
  → 分配给对应处理人
  → 处理人更新进度（用户实时可见）
  → 问题解决 → 用户满意度评价
```

#### 数据模型与字段

**企业信息表（`enterprise`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| user_id | INT FK | 关联用户 |
| name | VARCHAR(100) | 企业名称 |
| unified_credit_code | VARCHAR(50) | 统一社会信用代码 |
| industry | VARCHAR(50) | 所属行业 |
| scale | ENUM('1-10','11-50','51-200','200+') | 企业规模 |
| business_license_url | VARCHAR(255) | 营业执照图片 |
| status | ENUM('pending','approved','rejected') | 认证状态 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

**入驻申请表（`settlement_application`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| user_id | INT FK | 提交用户（直接关联，支持快速查询"我的申请"）|
| enterprise_id | INT FK | 关联企业 |
| project_name | VARCHAR(100) | 项目名称 |
| project_desc | TEXT | 项目简介 |
| space_type | ENUM('office','commercial') | 需求空间类型 |
| space_area | DECIMAL(8,2) | 需求面积（㎡）|
| budget | DECIMAL(10,2) | 预算（元/月）|
| attachments | JSON | 附件 URL 列表 |
| feishu_approval_id | VARCHAR(100) | 飞书审批实例 ID（审批触发后填写）|
| status | ENUM('draft','submitted','reviewing','approved','rejected') | 申请状态 |
| reject_reason | TEXT | 拒绝原因 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

**场地表（`space`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| name | VARCHAR(100) | 场地名称 |
| type | ENUM('office','commercial') | 场地类型 |
| images | JSON | 图片列表 |
| floor | VARCHAR(20) | 楼层 |
| area | DECIMAL(8,2) | 面积（㎡）|
| price_per_month | DECIMAL(10,2) | 月租金（元）|
| description | TEXT | 详情描述 |
| is_available | BOOLEAN | 是否可租 |
| sort_order | INT | 排序 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

**成果供需表（`requirement_post`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| user_id | INT FK | 发布用户（所有用户可发布"其他需求"）|
| enterprise_id | INT FK NULLABLE | 发布企业（企业用户发布人才/资金等需求时填写）|
| type | ENUM('talent','funding','policy','technology','other') | 需求类型（'other' 类型无需企业认证）|
| title | VARCHAR(200) | 标题（可 AI 生成）|
| description | TEXT | 详细描述（可 AI 生成）|
| budget | DECIMAL(10,2) | 预算/金额（可选）|
| attachments | JSON | 附件 URL 列表 |
| status | ENUM('pending','published','rejected') | 审核状态 |
| view_count | INT | 浏览次数 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

> **业务规则**：type 为 'talent'/'funding'/'technology' 时，`enterprise_id` 必填（需企业用户权限）；type 为 'other'/'policy' 时，`enterprise_id` 可为 NULL（注册用户即可发布）。

**技术成果表（`tech_achievement`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| title | VARCHAR(200) | 成果名称 |
| institution | VARCHAR(100) | 来源高校/院所 |
| description | TEXT | 成果描述 |
| images | JSON | 图片列表 |
| contact_name | VARCHAR(50) | 联系人 |
| contact_phone | VARCHAR(20) | 联系电话 |
| status | ENUM('pending','published','archived') | 状态（archived 表示已下架）|
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

**技术经理人表（`tech_manager`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| name | VARCHAR(50) | 姓名 |
| avatar_url | VARCHAR(255) | 头像 |
| title | VARCHAR(100) | 职称/头衔 |
| expertise | VARCHAR(200) | 擅长领域 |
| description | TEXT | 个人简介 |
| contact_phone | VARCHAR(20) | 联系电话 |
| is_active | BOOLEAN | 是否展示 |
| sort_order | INT | 排序 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

> 技术经理人为管理员维护的静态数据，通过后台 CRUD 管理。

**用户收藏表（`user_favorite`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| user_id | INT FK | 关联用户 |
| target_type | ENUM('activity','requirement','achievement','tech_manager','policy') | 收藏内容类型 |
| target_id | INT | 被收藏内容的 ID |
| created_at | DATETIME | 收藏时间 |

> UNIQUE 约束：`(user_id, target_type, target_id)`，防止重复收藏。

**社区合伙人申请表（`partner_application`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| user_id | INT FK | 申请用户 |
| name | VARCHAR(50) | 姓名 |
| company | VARCHAR(100) | 单位 |
| reason | TEXT | 申请理由 |
| status | ENUM('pending','approved','rejected') | 审核状态 |
| reject_reason | TEXT | 拒绝原因 |
| created_at | DATETIME | 申请时间 |
| updated_at | DATETIME | 更新时间 |

**问题工单表（`feedback_ticket`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| user_id | INT FK | 提交用户 |
| category | ENUM('space','facility','service','other') | 问题分类（AI 自动分类）|
| title | VARCHAR(200) | 问题标题 |
| content | TEXT | 问题详情 |
| attachments | JSON | 图片附件 |
| assignee_id | INT FK | 处理人 |
| status | ENUM('pending','processing','resolved','closed') | 工单状态 |
| satisfaction | TINYINT | 满意度评分（1-5）|
| created_at | DATETIME | 创建时间 |
| resolved_at | DATETIME | 解决时间 |
| updated_at | DATETIME | 更新时间 |

#### API 接口清单

| 方法 | 路径 | 说明 | 优先级 |
|------|------|------|-------|
| POST | `/api/v1/settlement/apply` | 提交入驻申请 | P0 |
| GET | `/api/v1/settlement/status` | 查询我的申请状态 | P0 |
| GET | `/api/v1/spaces` | 获取场地列表 | P0 |
| GET | `/api/v1/spaces/{id}` | 获取场地详情 | P0 |
| GET | `/api/v1/achievements` | 获取科技成果列表 | P0 |
| GET | `/api/v1/tech-managers` | 获取技术经理人列表 | P0 |
| GET | `/api/v1/requirements` | 获取成果供需列表 | P0 |
| POST | `/api/v1/requirements` | 发布需求（人才/资金等）| P0 |
| GET | `/api/v1/requirements/{id}` | 需求详情 | P0 |
| POST | `/api/v1/feedback` | 提交问题反馈 | P0 |
| GET | `/api/v1/feedback/mine` | 查看我的反馈工单列表 | P0 |
| GET | `/api/v1/feedback/{id}` | 查看工单详情及进度 | P0 |
| POST | `/api/v1/feedback/{id}/rate` | 提交满意度评价 | P0 |
| POST | `/api/v1/favorites` | 添加收藏 | P1 |
| DELETE | `/api/v1/favorites/{target_type}/{target_id}` | 取消收藏 | P1 |
| GET | `/api/v1/favorites` | 我的收藏列表（可按 target_type 筛选）| P1 |
| POST | `/api/v1/ai/generate-content` | AI 辅助生成需求标题/描述 | P2 |
| POST | `/api/v1/ocr/business-license` | 营业执照 OCR 识别 | P1 |
| POST | `/api/v1/ai/classify-feedback` | AI 自动分类工单 | P2 |
| GET | `/api/v1/ai/recommend-spaces` | AI 智能推荐场地（别名同 recommend-venues）| P2 |

---

### 3.3 活动与会场

#### 用户故事
- 作为**注册用户**，我希望浏览活动列表并在线报名，收到活动提醒
- 作为**注册用户**，我希望查看会场详情并在线预约会议室
- 作为**管理员**，我希望审批会场申请并自动推送门禁密码给预约人

#### 业务流程

**活动报名流程：**
```
用户浏览活动列表（支持卡片/瀑布流）
  → 查看活动详情（图片/时间/地点定位）
  → 选择报名方式
      ├── 扫二维码报名
      └── 小程序内填写信息报名
  → 报名成功 → 微信订阅消息通知
  → 活动开始前3天自动提醒
```

**会场预约流程：**
```
用户浏览会场列表（按时间/容量/设施筛选）
  → 查看会场详情（图片/规格/租金）
  → 选择预约类型
      ├── 共享会议室 → 直接选时间段预约
      └── 大型会场 → 填写申请资料 + 上传文件
  → 提交预约
  → 管理员审批（大型会场）或直接确认（共享会议室）
  → 预约成功 → 推送确认通知 + 门禁密码
  → 使用后自动统计会场使用率
```

#### 数据模型与字段

**活动表（`activity`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| title | VARCHAR(200) | 活动名称 |
| cover_image | VARCHAR(255) | 封面图 |
| images | JSON | 活动图片列表 |
| content | TEXT | 活动详情（富文本）|
| start_time | DATETIME | 开始时间 |
| end_time | DATETIME | 结束时间 |
| location | VARCHAR(200) | 活动地点 |
| latitude | DECIMAL(10,7) | 纬度 |
| longitude | DECIMAL(10,7) | 经度 |
| signup_type | ENUM('qrcode','inapp','both') | 报名方式 |
| qrcode_url | VARCHAR(255) | 二维码图片 |
| max_participants | INT | 最大报名人数（0为不限）|
| current_participants | INT | 当前报名人数 |
| status | ENUM('draft','published','cancelled','ended') | 活动状态 |
| created_by | INT FK | 创建管理员 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

**活动报名表（`activity_registration`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| activity_id | INT FK | 关联活动 |
| user_id | INT FK | 报名用户 |
| name | VARCHAR(50) | 姓名 |
| phone | VARCHAR(20) | 手机号 |
| company | VARCHAR(100) | 单位（可选）|
| extra_info | JSON | 自定义报名字段 |
| status | ENUM('registered','cancelled') DEFAULT 'registered' | 报名状态 |
| registered_at | DATETIME | 报名时间 |
| updated_at | DATETIME | 更新时间 |

> UNIQUE 约束：`(activity_id, user_id)`，防止重复报名。取消报名通过 status 字段标记，不删除记录。

**会场表（`venue`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| name | VARCHAR(100) | 会场名称 |
| type | ENUM('meeting_room','conference','hall') | 类型 |
| images | JSON | 图片列表 |
| capacity | INT | 容纳人数 |
| area | DECIMAL(8,2) | 面积（㎡）|
| floor | VARCHAR(20) | 楼层 |
| price_per_hour | DECIMAL(8,2) | 每小时租金 |
| facilities | JSON | 设施列表（投影/白板/空调等）|
| is_shared | BOOLEAN | 是否共享会议室（直接预约）|
| is_active | BOOLEAN | 是否可预约 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

**会场预约表（`venue_booking`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| venue_id | INT FK | 关联会场 |
| user_id | INT FK | 预约用户 |
| enterprise_id | INT FK NULLABLE | 关联企业（可选）|
| start_time | DATETIME | 预约开始时间 |
| end_time | DATETIME | 预约结束时间 |
| purpose | TEXT | 使用目的 |
| participants_count | INT | 参与人数 |
| attachments | JSON | 申请附件（大型会场）|
| feishu_approval_id | VARCHAR(100) NULLABLE | 飞书审批实例 ID（大型会场审批触发后填写）|
| access_code | VARCHAR(20) | 门禁密码（审批通过后生成）|
| status | ENUM('pending','approved','rejected','cancelled','completed') | 预约状态 |
| reject_reason | TEXT | 拒绝原因 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

#### API 接口清单

| 方法 | 路径 | 说明 | 优先级 |
|------|------|------|-------|
| GET | `/api/v1/activities` | 活动列表（分页+筛选）| P0 |
| GET | `/api/v1/activities/{id}` | 活动详情 | P0 |
| POST | `/api/v1/activities/{id}/register` | 活动报名 | P0 |
| PUT | `/api/v1/activities/{id}/cancel-registration` | 取消报名 | P0 |
| GET | `/api/v1/my/activity-registrations` | 我的报名记录 | P0 |
| GET | `/api/v1/venues` | 会场列表（支持筛选）| P0 |
| GET | `/api/v1/venues/{id}` | 会场详情 | P0 |
| GET | `/api/v1/venues/{id}/availability` | 查询会场可用时间段 | P0 |
| POST | `/api/v1/venues/{id}/book` | 提交会场预约 | P0 |
| GET | `/api/v1/my/venue-bookings` | 我的预约记录 | P0 |
| GET | `/api/v1/ai/recommend-activities` | AI 推荐活动 | P2 |

---

### 3.4 AI 智能助手

#### 用户故事
- 作为**用户**，我希望发布需求时 AI 能根据关键词自动生成标题和描述
- 作为**用户**，我希望活动开始前3天收到自动提醒
- 作为**管理员**，我希望 AI 自动分类反馈工单，减少人工分拣

#### AI 能力清单与调用策略

| AI 功能 | 触发时机 | 调用方式 | 降级方案 | 优先级 |
|---------|---------|---------|---------|-------|
| 智能表单填写 | OCR 识别营业执照后 | 同步调用 | 用户手动填写 | P1 |
| 需求内容生成 | 用户输入关键词时 | 异步调用 | 用户自行编写 | P2 |
| 智能场地推荐 | 用户进入找场地页面 | 异步调用 | 展示全部列表 | P2 |
| 工单自动分类 | 用户提交反馈后 | 异步调用 | 默认分类"其他" | P2 |
| 活动智能推荐 | 用户进入活动列表 | 异步调用 | 按时间排序 | P2 |
| AI 数据分析报告 | 管理员触发/定时任务 | 异步调用 | 展示原始数据 | P2 |
| 满意度分析 | 评价数据积累后 | 定时批处理 | 跳过 | P2 |

#### 数据模型与字段

**AI 调用日志表（`ai_call_log`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| user_id | INT FK | 调用用户 |
| feature | VARCHAR(50) | 功能标识 |
| input | TEXT | 输入内容 |
| output | TEXT | AI 输出内容 |
| tokens_used | INT | Token 消耗 |
| latency_ms | INT | 响应时长（ms）|
| status | ENUM('success','failed','fallback') | 调用状态 |
| created_at | DATETIME | 调用时间 |

#### API 接口清单

| 方法 | 路径 | 说明 | 优先级 |
|------|------|------|-------|
| POST | `/api/v1/ai/generate-content` | AI 生成需求标题/描述 | P2 |
| POST | `/api/v1/ai/classify-feedback` | AI 分类工单 | P2 |
| POST | `/api/v1/ai/recommend-venues` | 智能推荐场地（统一入口）| P2 |
| GET | `/api/v1/ai/recommend-activities` | 推荐活动列表 | P2 |
| POST | `/api/v1/ai/analysis-report` | 生成数据分析报告 | P2 |

---

### 3.5 系统集成

#### 3.5.1 飞书集成

**审批流程集成**：

```
入驻申请提交
  → 后端调用飞书审批 API 创建审批实例
  → 飞书推送审批任务给审批人
  → 审批人在飞书完成审批
  → 飞书回调 Webhook 通知后端
  → 后端更新申请状态
  → 微信订阅消息通知申请人结果
```

**飞书集成配置（环境变量 + 运营配置表）**

> **安全说明**：飞书 `app_id` 和 `app_secret` 通过环境变量注入（`FEISHU_APP_ID` / `FEISHU_APP_SECRET`），不存入数据库，与 Section 5.2 安全要求保持一致。

数据库仅存储非敏感运营配置：

**飞书运营配置表（`feishu_config`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键（单行）|
| approval_code | VARCHAR(100) | 审批定义 Code |
| webhook_token | VARCHAR(100) | 回调验证 Token |
| is_active | BOOLEAN | 是否启用飞书集成 |
| updated_at | DATETIME | 最后更新时间 |

#### 3.5.2 OCR 识别

| 识别场景 | 文件类型 | 提取字段 |
|---------|---------|---------|
| 营业执照 | 图片/PDF | 企业名称、统一社会信用代码、法人姓名、注册地址 |
| 项目计划书 | PDF/Word | 项目名称、团队规模（辅助填写）|

#### 3.5.3 短信服务

短信服务用于手机号验证码绑定，作为微信授权的补充渠道。

| 使用场景 | 说明 |
|---------|------|
| 手机号绑定验证码 | 用户绑定手机号时发送 6 位验证码，有效期 5 分钟 |
| 关键审批结果备用通知 | 当用户未订阅微信模板消息时，可通过短信通知审批结果（可选）|

**验证码记录表（`sms_verification`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| phone | VARCHAR(20) | 手机号 |
| code | VARCHAR(10) | 验证码 |
| purpose | VARCHAR(50) | 用途（当前值：bind_phone；预留扩展）|
| is_used | BOOLEAN | 是否已使用 |
| expired_at | DATETIME | 过期时间 |
| created_at | DATETIME | 创建时间 |

#### 3.5.4 消息通知策略

| 通知场景 | 通知方式 | 接收方 |
|---------|---------|-------|
| 入驻申请审批结果 | 微信订阅消息 | 申请人 |
| 新入驻申请待审批 | 飞书消息 | 管理员 |
| 活动报名成功 | 微信订阅消息 | 报名人 |
| 活动开始前3天提醒 | 微信订阅消息 | 报名人 |
| 会场预约审批结果 | 微信订阅消息 | 预约人 |
| 会场门禁密码 | 微信订阅消息 | 预约人 |
| 反馈工单状态变更 | 微信订阅消息 | 提交人 |
| 需求审核结果 | 微信订阅消息 | 发布企业 |
| 手机号绑定验证码 | 短信 | 绑定用户 |

#### API 接口清单

| 方法 | 路径 | 说明 | 优先级 |
|------|------|------|-------|
| POST | `/api/v1/feishu/callback` | 飞书审批回调 Webhook | P1 |
| POST | `/api/v1/ocr/business-license` | 营业执照 OCR | P1 |
| POST | `/api/v1/sms/send` | 发送手机号验证码 | P1 |
| POST | `/api/v1/notify/send` | 内部触发通知（系统调用）| P1 |

---

### 3.6 平台管理后台

#### 用户故事
- 作为**管理员**，我希望管理所有用户、审核内容、配置 Banner
- 作为**管理员**，我希望看到运营数据看板并生成报告

#### 数据模型与字段

**用户表（`user`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| openid | VARCHAR(100) UNIQUE | 微信 OpenID（应用维度唯一标识）|
| union_id | VARCHAR(100) NULLABLE | 微信 UnionID（跨应用唯一标识，有开放平台时填写）|
| nickname | VARCHAR(50) | 微信昵称 |
| avatar_url | VARCHAR(255) | 头像 |
| phone | VARCHAR(20) | 手机号（加密存储）|
| role | ENUM('user','enterprise','partner','admin') | 角色 |
| is_active | BOOLEAN | 是否启用 |
| created_at | DATETIME | 注册时间 |
| last_login_at | DATETIME | 最后登录时间 |

**评分配置表（`score_config`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| category | ENUM('settlement','development') | 评分类别（入驻/发展）|
| dimension | VARCHAR(100) | 评分维度名称 |
| weight | DECIMAL(5,2) | 权重（%）|
| description | TEXT | 维度说明 |

**项目评分表（`enterprise_score`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| enterprise_id | INT FK | 关联企业 |
| config_id | INT FK | 评分维度 |
| score | DECIMAL(5,2) | 得分 |
| remark | TEXT | 备注 |
| scored_by | INT FK | 评分管理员 |
| scored_at | DATETIME | 评分时间 |
| updated_at | DATETIME | 更新时间 |

#### API 接口清单（后台）

| 方法 | 路径 | 说明 | 优先级 |
|------|------|------|-------|
| GET | `/api/v1/admin/users` | 用户列表 | P0 |
| PUT | `/api/v1/admin/users/{id}/role` | 修改用户角色 | P0 |
| GET | `/api/v1/admin/applications` | 入驻申请列表 | P0 |
| PUT | `/api/v1/admin/applications/{id}/review` | 审核入驻申请 | P0 |
| GET | `/api/v1/admin/requirements` | 需求列表审核 | P0 |
| PUT | `/api/v1/admin/requirements/{id}/review` | 审核需求发布 | P0 |
| GET | `/api/v1/admin/feedback` | 工单列表 | P0 |
| PUT | `/api/v1/admin/feedback/{id}/assign` | 分配工单 | P0 |
| PUT | `/api/v1/admin/feedback/{id}/resolve` | 标记工单解决 | P0 |
| GET | `/api/v1/admin/bookings` | 会场预约列表 | P0 |
| PUT | `/api/v1/admin/bookings/{id}/review` | 审批会场预约 | P0 |
| POST | `/api/v1/admin/banners` | 新增 Banner | P0 |
| GET | `/api/v1/admin/banners` | 后台 Banner 列表（含未启用）| P0 |
| PUT | `/api/v1/admin/banners/{id}` | 编辑 Banner | P0 |
| DELETE | `/api/v1/admin/banners/{id}` | 删除 Banner | P0 |
| POST | `/api/v1/admin/activities` | 新增活动 | P0 |
| PUT | `/api/v1/admin/activities/{id}` | 编辑活动 | P0 |
| GET | `/api/v1/admin/stats/overview` | 运营数据概览 | P1 |
| GET | `/api/v1/admin/stats/venues` | 会场使用统计 | P1 |
| GET | `/api/v1/admin/scores` | 企业评分列表 | P1 |
| POST | `/api/v1/admin/scores` | 录入评分 | P1 |
| GET | `/api/v1/admin/ai/insight-report` | AI 生成洞察报告 | P2 |
| POST | `/api/v1/admin/applications/{id}/export-materials` | 一键生成企业完整申报材料（附件下载）| P1 |
| POST | `/api/v1/admin/tech-managers` | 新增技术经理人 | P0 |
| PUT | `/api/v1/admin/tech-managers/{id}` | 编辑技术经理人 | P0 |
| DELETE | `/api/v1/admin/tech-managers/{id}` | 删除技术经理人 | P0 |
| POST | `/api/v1/admin/spaces` | 新增场地 | P0 |
| PUT | `/api/v1/admin/spaces/{id}` | 编辑场地 | P0 |
| DELETE | `/api/v1/admin/spaces/{id}` | 删除场地 | P0 |
| POST | `/api/v1/admin/venues` | 新增会场 | P0 |
| PUT | `/api/v1/admin/venues/{id}` | 编辑会场 | P0 |
| DELETE | `/api/v1/admin/venues/{id}` | 删除会场 | P0 |
| PUT | `/api/v1/admin/activities/{id}/status` | 变更活动状态（发布/取消/结束）| P0 |
| POST | `/api/v1/admin/achievements` | 新增科技成果 | P0 |
| GET | `/api/v1/admin/achievements` | 后台科技成果列表（含待审核）| P0 |
| PUT | `/api/v1/admin/achievements/{id}` | 编辑科技成果 | P0 |
| DELETE | `/api/v1/admin/achievements/{id}` | 删除/下架科技成果 | P0 |

---

### 3.7 关于基地

#### 数据模型

**基地信息表（`base_info`）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键（单行配置）|
| name | VARCHAR(100) | 基地名称 |
| intro | TEXT | 图文介绍（富文本）|
| images | JSON | 图片列表 |
| contact_phone | VARCHAR(20) | 客服电话 |
| address | VARCHAR(200) | 地址 |
| latitude | DECIMAL(10,7) | 纬度 |
| longitude | DECIMAL(10,7) | 经度 |
| updated_at | DATETIME | 最后更新时间 |

#### API 接口清单

| 方法 | 路径 | 说明 | 优先级 |
|------|------|------|-------|
| GET | `/api/v1/base-info` | 获取基地介绍 | P0 |
| PUT | `/api/v1/admin/base-info` | 后台更新基地介绍 | P0 |

---

## 第四章 通用能力

### 4.1 认证与授权

#### 登录流程
```
用户点击微信授权登录
  → 小程序调用 wx.login() 获取 code
  → 后端用 code + AppID + AppSecret 换取 openid + session_key（+ union_id 如有）
  → 后端生成 access_token（7天）和 refresh_token（30天）返回前端
  → 前端将两个 token 存入 wx.setStorageSync
  → 后续请求携带 Authorization: Bearer <access_token>
  → access_token 过期 → 前端用 refresh_token 静默换取新 access_token
  → refresh_token 过期 → 要求用户重新登录
```

#### JWT Token 设计

**access_token**（有效期7天）：

| 字段 | 说明 |
|------|------|
| sub | 用户 ID |
| role | 用户角色 |
| exp | 过期时间（7天）|
| iat | 签发时间 |

> 注意：`openid` 不写入 JWT payload（openid 是敏感的稳定标识符，JWT payload 仅 base64 编码非加密；后端通过 `sub` 查 user 表获取 openid）。

**refresh_token**（有效期30天）：独立生成的不透明随机字符串，存储于后端 Redis，与 `user_id` 关联。

**`POST /api/v1/auth/refresh` 请求体**：
```json
{ "refresh_token": "<refresh_token_value>" }
```
返回新的 `access_token`（不更新 refresh_token）。

#### API 接口清单

| 方法 | 路径 | 说明 | 优先级 |
|------|------|------|-------|
| POST | `/api/v1/auth/wx-login` | 微信登录，返回 JWT | P0 |
| POST | `/api/v1/auth/refresh` | 刷新 Token | P0 |
| GET | `/api/v1/auth/profile` | 获取当前用户信息 | P0 |
| PUT | `/api/v1/auth/profile` | 更新个人/企业信息 | P0 |
| POST | `/api/v1/auth/phone` | 绑定手机号（微信授权）| P0 |

#### 权限中间件设计

```python
# 后端统一鉴权中间件
# 装饰器 @require_role(roles=['admin', 'enterprise'])
# → 解析 JWT → 校验 role → 通过/拒绝（403）
```

---

### 4.2 消息通知

#### 微信订阅消息模板

| 消息模板 | 触发事件 | 关键字段 |
|---------|---------|---------|
| 审批结果通知 | 入驻申请/会场预约审批完成 | 申请类型、结果、时间、备注 |
| 活动报名成功 | 用户报名后 | 活动名称、时间、地点 |
| 活动提醒 | 活动开始前3天定时任务触发 | 活动名称、开始时间、地点 |
| 工单状态变更 | 反馈工单处理进度更新 | 工单编号、状态、处理说明 |
| 门禁密码通知 | 会场预约通过后 | 会场名称、使用时间、门禁密码 |

**定时任务设计（APScheduler / Celery）**：

| 任务 | 触发方式 | 频率 |
|------|---------|------|
| 活动开始前3天提醒 | Cron 每日上午9点 | 每天 |
| AI 数据洞察报告生成 | Cron 每周一 | 每周 |
| 会场使用率统计 | Cron 每日凌晨 | 每天 |

---

### 4.3 文件上传

#### 上传策略

```
前端直传腾讯云 COS：
  → 前端请求后端获取预签名 URL
  → 前端直接上传文件到 COS
  → 上传成功后将文件 URL 保存到业务字段

支持的文件类型：
  - 图片：JPG / PNG / WEBP（最大 10MB）
  - 文档：PDF / DOC / DOCX（最大 20MB）
  - 压缩包：ZIP（最大 50MB）
```

#### 文件记录表（`file_record`）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| user_id | INT FK | 上传用户 |
| file_name | VARCHAR(200) | 原始文件名 |
| file_url | VARCHAR(255) | COS 存储 URL |
| file_size | INT | 文件大小（字节）|
| file_type | VARCHAR(50) | 文件 MIME 类型 |
| business_type | VARCHAR(50) | 业务用途标识 |
| created_at | DATETIME | 上传时间 |

#### API 接口清单

| 方法 | 路径 | 说明 | 优先级 |
|------|------|------|-------|
| POST | `/api/v1/upload/presign` | 获取 COS 预签名上传 URL | P0 |

---

### 4.4 AI 能力集成

#### 集成架构

```
业务逻辑层
  → AI 服务层（统一封装）
      ├── 调用大模型 API（GPT / 文心 / 通义，可配置切换）
      ├── 超时控制（5秒 timeout，在 8秒端到端 SLA 预算内）
      ├── 失败重试（最多2次）
      └── 降级处理（返回空结果，前端展示默认态）
```

> **时间预算说明**：AI 接口端到端 SLA 为 ≤ 8s（Section 5.1）。其中大模型调用 timeout 设为 5s，加上重试和降级逻辑，总时间仍在 8s 以内。

#### Prompt 模板

| 功能 | Prompt 策略 |
|------|------------|
| 生成需求标题/描述 | System: 你是企业服务助手；User: 基于以下关键词生成{type}需求的标题和描述：{keywords} |
| 工单自动分类 | System: 对问题反馈进行分类，输出 JSON；User: {feedback_content} |
| 场地推荐 | System: 根据企业特��推荐合适场地；User: 企业规模{scale}，行业{industry}，预算{budget} |
| 数据分析报告 | System: 你是数据分析师；User: 基于以下运营数据生成洞察报告：{stats_data} |

---

### 4.5 通用列表接口规范

所有分页列表接口��一使用以下参数和响应格式：

**请求查询参数**：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|-------|------|
| page | INT | 1 | 页码（从1开始）|
| page_size | INT | 20 | 每页条数（最大50）|

**标准响应格式**：
```json
{
  "total": 100,
  "page": 1,
  "page_size": 20,
  "items": [...]
}
```

筛选参数各接口独立定义（如 `status`、`type`、`start_date` 等），在各模块 API 清单中标注。

---

## 第五章 非功能需求

### 5.1 性能要求

| 指标 | 要求 |
|------|------|
| 普通接口响应时间 | ≤ 500ms（P95）|
| 列表接口响应时间 | ≤ 1s（P95）|
| AI 接口响应时间 | ≤ 8s（含超时降级）|
| OCR 接口响应时间 | ≤ 3s |
| 并发用户支持 | 初期支持 200 并发 |
| 小程序首屏加载 | ≤ 2s（4G 网络）|

### 5.2 安全要求

| 类别 | 要求 |
|------|------|
| 接口鉴权 | 所有非公开接口必须携带有效 JWT |
| 权限校验 | 后端强制校验 role，不依赖前端隐藏 |
| 敏感数据 | 飞书 Secret、数据库密码等通过环境变量注入，不写入代码 |
| 文件安全 | 上传文件类型白名单校验，限制文件大小 |
| SQL 注入 | 使用 ORM（SQLAlchemy）参数化查询，禁止拼接 SQL |
| 手机号 | 数据库中加密存储，仅展示时脱敏（138****8888）|
| HTTPS | 所有接口强制 HTTPS |
| 频率限制 | AI 接口每用户每分钟最多10次 |

### 5.3 兼容性要求

| 类别 | 要求 |
|------|------|
| 微信基础库 | ≥ 2.20.0 |
| 微信版本 | 支持近2年主流版本 |
| 手机系统 | iOS 13+ / Android 8+ |
| 屏幕适配 | 375px 基准，支持主流机型（iPhone SE ~ Pro Max）|

### 5.4 数据备份

| 类别 | 要求 |
|------|------|
| 数据库备份 | 每日自动备份，保留30天 |
| 文件存储 | COS 开启跨区域复制 |
| 备份恢复 | RTO ≤ 4小时，RPO ≤ 24小时 |

### 5.5 部署要求

| 组件 | 建议方案 |
|------|---------|
| 后端服务 | 腾讯云 CVM / 容器（Docker + Nginx）|
| 数据库 | 腾讯云 MySQL（RDS）|
| 文件存储 | 腾讯云 COS |
| 缓存 | Redis（Session / 接口缓存）|
| 任务队列 | Celery + Redis（异步任务 / 定时任务）|
| 日志 | 结构化日志 + 腾讯云日志服务 |

---

## 附录：数据库表清单

| 表名 | 说明 |
|------|------|
| `user` | 用户信息 |
| `enterprise` | 企业信息 |
| `settlement_application` | 入驻申请 |
| `space` | 场地信息 |
| `requirement_post` | 成果供需发布 |
| `tech_achievement` | 科技成果 |
| `tech_manager` | 技术经理人 |
| `feedback_ticket` | 问题工单 |
| `activity` | 活动信息 |
| `activity_registration` | 活动报名 |
| `venue` | 会场信息 |
| `venue_booking` | 会场预约 |
| `banner` | 首页 Banner |
| `base_info` | 基地介绍 |
| `score_config` | 评分维度配置 |
| `enterprise_score` | 企业评分记录 |
| `feishu_config` | 飞书运营配置（非敏感字段）|
| `file_record` | 文件上传记录 |
| `ai_call_log` | AI 调用日志 |
| `user_favorite` | 用户收藏/关注 |
| `partner_application` | 社区合伙人申请 |
| `sms_verification` | 短信验证码记录 |