Community-Center/系统规划书.md

# 社区服务中心综合管理平台 — 系统规划书

---

## 一、项目概述

### 1.1 项目背景

社区服务中心是基层社会治理的核心枢纽，承担着代理代办、代发代收、代销代购、代开证明、公益服务、民意反映与政策咨询等七大类数十项便民服务。当前业务多依赖纸质台账与人工流转，存在以下痛点：

- **流程不透明**：居民无法实时查询办理进度，需多次跑腿
- **数据孤岛**：各业务线台账独立，无法形成居民画像与数据联动
- **统计困难**：缺乏数字化手段，月度/年度统计依赖人工汇总
- **服务可及性差**：居民需到现场办理，缺少线上渠道

### 1.2 项目目标

建设一套基于 Django 的社区服务中心综合管理平台，实现：

1. **全业务线上化**：七大类服务全部纳入系统管理
2. **流程可追溯**：每笔业务从申请到办结全程留痕
3. **数据一体化**：居民信息统一管理，业务数据互通
4. **统计可视化**：提供多维度数据看板，辅助决策
5. **服务便捷化**：居民可通过微信小程序/网页提交申请、查询进度

### 1.3 项目范围

| 维度 | 范围 |
|------|------|
| 用户群体 | 普通居民（前端申请）、社区网格员（移动端核验）、社区管理员（后台管理）、街道审核员（跨社区审批）、系统管理员（系统运维） |
| 业务域 | 代理代办、代发代收、代销代购、代开证明、公益服务、民意反映、社区治理 |
| 技术栈 | Django 5.x + Django REST Framework + PostgreSQL + Redis + Vue 3 / 微信小程序 |
| 部署方式 | 初期单机部署，后期可容器化上云 |

---

## 二、系统架构设计

### 2.1 总体架构

```
┌─────────────────────────────────────────────────────────┐
│                      前端展示层                          │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ 管理后台  │  │  居民小程序   │  │   数据看板大屏    │  │
│  │ (Vue 3)  │  │ (WeChat Mini)│  │   (ECharts)      │  │
│  └────┬─────┘  └──────┬───────┘  └────────┬──────────┘  │
└───────┼───────────────┼───────────────────┼─────────────┘
        │               │                   │
        ▼               ▼                   ▼
┌─────────────────────────────────────────────────────────┐
│                     API 网关层                           │
│          Django REST Framework + JWT Auth               │
│          CORS / Rate Limit / API Versioning             │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    业务逻辑层 (Django)                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │代理代办   │ │代发代收   │ │代销代购   │ │代开证明   │  │
│  │模块       │ │模块       │ │模块       │ │模块       │  │
│  └──────────┘ └──────────┘ └──────────┘ └───────────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐               │
│  │公益服务   │ │民意反映   │ │社区治理   │               │
│  │模块       │ │模块       │ │模块       │               │
│  └──────────┘ └──────────┘ └──────────┘               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐               │
│  │用户权限   │ │通知消息   │ │数据统计   │               │
│  │模块       │ │模块       │ │模块       │               │
│  └──────────┘ └──────────┘ └──────────┘               │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                     数据持久层                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ PostgreSQL   │  │    Redis     │  │   MinIO/OSS  │  │
│  │ (主数据库)    │  │ (缓存/会话)  │  │ (文件存储)    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
```

### 2.2 技术选型与决策记录

| 决策项 | 选型 | 备选方案 | 选择理由 |
|--------|------|----------|----------|
| 后端框架 | Django 5.x + DRF | Flask, FastAPI | 自带 Admin、ORM 成熟、生态丰富、社区业务 CRUD 密集型适合 |
| 数据库 | PostgreSQL 15+ | MySQL, SQLite | JSON 字段支持好、扩展性强、社区版免费 |
| 缓存 | Redis 7+ | Memcached | 支持数据结构丰富，可用于会话、队列、缓存 |
| 前端管理后台 | Vue 3 + Element Plus | React, Ant Design | 国内生态好、组件丰富、上手快 |
| 居民端 | 微信小程序 | H5, 支付宝小程序 | 社区居民微信覆盖率高、无需安装 |
| 文件存储 | MinIO / 阿里云 OSS | 本地磁盘 | 初期 MinIO 自建，后期可迁移云存储 |
| 任务队列 | Celery + Redis | Django-Q, Huey | 生态成熟、支持定时任务、社区文档丰富 |
| 部署 | Docker Compose | K8s, 裸机 | 初期规模小，Docker Compose 足够，后期可平滑迁移 K8s |

### 2.3 Django 项目结构

```
community_center/
├── manage.py
├── config/
│   ├── settings/
│   │   ├── base.py
│   │   ├── development.py
│   │   └── production.py
│   ├── urls.py
│   ├── wsgi.py
│   └── celery.py
├── apps/
│   ├── accounts/          # 用户与权限
│   ├── residents/         # 居民信息管理
│   ├── agency/            # 代理代办服务
│   ├── distribution/      # 代发代收服务
│   ├── legal_psych/       # 代销代购（法律与心理援助）
│   ├── certification/     # 代开证明
│   ├── public_service/    # 公益服务
│   ├── feedback/          # 民意反映与政策咨询
│   ├── governance/        # 社区治理
│   ├── notification/      # 通知消息
│   └── statistics/        # 数据统计
├── templates/
├── static/
├── media/
├── requirements/
│   ├── base.txt
│   ├── development.txt
│   └── production.txt
├── docker-compose.yml
├── Dockerfile
└── .env.example
```

---

## 三、功能模块详细设计

### 3.1 用户与权限模块 (accounts)

#### 3.1.1 用户角色

| 角色 | 主要职责 | 典型权限范围 |
|------|----------|--------------|
| 普通居民 | 浏览服务事项、提交申请、查询进度、评价反馈、提意见建议 | 本人信息、本人申请单、公共服务查询 |
| 社区网格员 | 初步审核申请、上门核验、代填代报、通知领取物资/证明 | 辖区居民信息、待办任务、物资发放登记 |
| 社区管理员 | 事项配置、审批流转、统计报表、志愿者管理、活动发布 | 全部居民数据、审批权限、系统配置 |
| 街道审核员 | 对需上级审批的事项（如低保申请、医疗救助）进行终审 | 跨社区申请单、特殊事项审核 |
| 系统管理员 | 用户管理、角色权限、日志审计、数据备份 | 全部系统功能 |

#### 3.1.2 核心功能

- 用户注册/登录（居民支持微信授权登录）
- 基于 Django Guardian 的对象级权限控制
- 角色分配与权限管理
- 操作日志审计

#### 3.1.3 数据模型

```python
ROLE_CHOICES = [
    ('resident', '普通居民'),
    ('grid_worker', '社区网格员'),
    ('community_admin', '社区管理员'),
    ('street_auditor', '街道审核员'),
    ('system_admin', '系统管理员'),
]

class User(AbstractBaseUser):
    phone = models.CharField(max_length=11, unique=True)
    name = models.CharField(max_length=50)
    id_card = models.CharField(max_length=18, blank=True)
    role = models.CharField(choices=ROLE_CHOICES)
    community = models.ForeignKey('Community')
    is_staff = models.BooleanField(default=False)

class Community(models.Model):
    name = models.CharField(max_length=100)
    address = models.CharField(max_length=300)
    contact_phone = models.CharField(max_length=11)
    director = models.ForeignKey(User)
```

### 3.2 居民信息管理模块 (residents)

#### 3.2.1 核心功能

- 居民档案 CRUD（姓名、身份证、住址、联系方式、家庭成员关系）
- 居民标签体系（低保户、残疾人、退役军人、独居老人等）
- 家庭关系图谱
- 居民信息变更记录

#### 3.2.2 数据模型

```python
class Resident(models.Model):
    name = models.CharField(max_length=50)
    id_card = models.CharField(max_length=18, unique=True)
    gender = models.CharField(choices=GENDER_CHOICES)
    birth_date = models.DateField()
    phone = models.CharField(max_length=11)
    address = models.TextField()
    community = models.ForeignKey(Community)
    tags = models.ManyToManyField('ResidentTag')
    family = models.ForeignKey('Family', null=True)

class ResidentTag(models.Model):
    name = models.CharField(max_length=30)
    category = models.CharField(choices=TAG_CATEGORY_CHOICES)

class Family(models.Model):
    head = models.ForeignKey(Resident)
    address = models.TextField()
```

### 3.3 代理代办服务模块 (agency)

#### 3.3.1 业务分类与流程

```
居民提交申请 → 经办人受理 → 审核材料 → 办理/代办 → 结果通知 → 归档
```

#### 3.3.2 业务子类

| 子类编码 | 业务名称 | 所需材料 | 办理时限 |
|----------|----------|----------|----------|
| A01 | 生育服务证代办 | 身份证、结婚证、户口本 | 5个工作日 |
| A02 | 独生子女证代办 | 身份证、户口本、出生证明 | 5个工作日 |
| A03 | 老年优待证代办 | 身份证、照片 | 3个工作日 |
| A04 | 暂住证代办 | 身份证、居住证明 | 5个工作日 |
| A05 | 残疾证代办 | 身份证、医院诊断证明 | 7个工作日 |
| A06 | 最低生活保障金申请 | 身份证、收入证明、困难证明 | 15个工作日 |
| A07 | 困难人员临时救助申请 | 身份证、困难说明 | 10个工作日 |
| A08 | 重残生活困难补助申请 | 身份证、残疾证 | 10个工作日 |
| A09 | 特困人员医疗救助申请 | 身份证、医疗费用清单 | 10个工作日 |
| A10 | 低保/优抚对象租房申请 | 身份证、低保证/优抚证明 | 15个工作日 |
| A11 | 失业/求职登记代理 | 身份证、学历证明 | 3个工作日 |
| A12 | 新生儿登记代理 | 出生证明、父母身份证 | 3个工作日 |
| A13 | 丧偶登记代理 | 身份证、配偶死亡证明 | 3个工作日 |
| A14 | 养犬登记代理 | 身份证、犬只免疫证明 | 5个工作日 |
| A15 | 出租房屋登记代理 | 房产证、租赁合同 | 5个工作日 |
| A16 | 流动人口婚育证明验证 | 身份证、原籍婚育证明 | 3个工作日 |
| A17 | 子女入托/借读证明代办 | 身份证、居住证明 | 3个工作日 |
| A18 | 党团组织关系转接代办 | 身份证、组织关系介绍信 | 5个工作日 |
| A19 | 退休人员医保关系转移代办 | 身份证、退休证明 | 7个工作日 |
| A20 | 退休人员医疗费报销代办 | 身份证、医疗费用清单 | 10个工作日 |

#### 3.3.3 数据模型

```python
class AgencyServiceCategory(models.Model):
    code = models.CharField(max_length=10, unique=True)
    name = models.CharField(max_length=100)
    required_docs = models.JSONField(default=list)
    processing_days = models.IntegerField()
    description = models.TextField(blank=True)

class AgencyApplication(models.Model):
    STATUS_CHOICES = [
        ('draft', '草稿'),
        ('submitted', '已提交'),
        ('accepted', '已受理'),
        ('processing', '办理中'),
        ('completed', '已办结'),
        ('rejected', '已退回'),
    ]
    applicant = models.ForeignKey(Resident)
    category = models.ForeignKey(AgencyServiceCategory)
    status = models.CharField(choices=STATUS_CHOICES, default='draft')
    submitted_at = models.DateTimeField()
    accepted_at = models.DateTimeField(null=True)
    completed_at = models.DateTimeField(null=True)
    handler = models.ForeignKey(User, null=True)
    remarks = models.TextField(blank=True)

class AgencyDocument(models.Model):
    application = models.ForeignKey(AgencyApplication)
    doc_type = models.CharField(max_length=50)
    file = models.FileField(upload_to='agency_docs/')
    uploaded_at = models.DateTimeField(auto_now_add=True)

class AgencyStatusLog(models.Model):
    application = models.ForeignKey(AgencyApplication)
    from_status = models.CharField(max_length=20)
    to_status = models.CharField(max_length=20)
    operator = models.ForeignKey(User)
    created_at = models.DateTimeField(auto_now_add=True)
    note = models.TextField(blank=True)
```

### 3.4 代发代收服务模块 (distribution)

#### 3.4.1 业务子类

| 子类编码 | 业务名称 | 类型 |
|----------|----------|------|
| D01 | 避孕药具发放 | 代发 |
| D02 | 除"四害"药品代售 | 代售 |
| D03 | 爱心捐赠物品代收 | 代收 |

#### 3.4.2 数据模型

```python
class DistributionCategory(models.Model):
    code = models.CharField(max_length=10, unique=True)
    name = models.CharField(max_length=100)
    dist_type = models.CharField(choices=[('issue', '代发'), ('sell', '代售'), ('collect', '代收')])

class DistributionRecord(models.Model):
    category = models.ForeignKey(DistributionCategory)
    resident = models.ForeignKey(Resident)
    operator = models.ForeignKey(User)
    quantity = models.IntegerField()
    unit = models.CharField(max_length=10)
    record_date = models.DateField()
    remarks = models.TextField(blank=True)

class DonationItem(models.Model):
    donor_name = models.CharField(max_length=50)
    donor_phone = models.CharField(max_length=11)
    item_name = models.CharField(max_length=100)
    item_count = models.IntegerField()
    received_at = models.DateTimeField(auto_now_add=True)
    receiver = models.ForeignKey(User)
    status = models.CharField(choices=[('received', '已接收'), ('distributed', '已发放')])
```

### 3.5 代销代购（法律与心理援助）模块 (legal_psych)

#### 3.5.1 业务子类

| 子类编码 | 业务名称 |
|----------|----------|
| L01 | 法律援助联系 |
| L02 | 民事调解 |
| L03 | 消费者权益维护 |
| L04 | 心理咨询服务 |

#### 3.5.2 数据模型

```python
class LegalPsychService(models.Model):
    SERVICE_TYPE_CHOICES = [
        ('legal_aid', '法律援助'),
        ('mediation', '民事调解'),
        ('consumer_rights', '消费者权益'),
        ('psychology', '心理咨询'),
    ]
    applicant = models.ForeignKey(Resident)
    service_type = models.CharField(choices=SERVICE_TYPE_CHOICES)
    description = models.TextField()
    status = models.CharField(choices=STATUS_CHOICES)
    assigned_counselor = models.ForeignKey('Counselor', null=True)
    created_at = models.DateTimeField(auto_now_add=True)
    closed_at = models.DateTimeField(null=True)

class Counselor(models.Model):
    name = models.CharField(max_length=50)
    specialty = models.CharField(max_length=100)
    phone = models.CharField(max_length=11)
    is_active = models.BooleanField(default=True)
```

### 3.6 代开证明模块 (certification)

#### 3.6.1 业务子类

| 子类编码 | 证明类型 |
|----------|----------|
| C01 | 居住证明 |
| C02 | 残疾证明 |
| C03 | 流动人口证明 |
| C04 | 抚恤金申请证明 |
| C05 | 残疾保障金申请证明 |
| C06 | 子女助学金申请证明 |
| C07 | 减免学费证明 |

#### 3.6.2 数据模型

```python
class CertType(models.Model):
    code = models.CharField(max_length=10, unique=True)
    name = models.CharField(max_length=100)
    template = models.FileField(upload_to='cert_templates/')
    required_fields = models.JSONField(default=list)

class CertApplication(models.Model):
    applicant = models.ForeignKey(Resident)
    cert_type = models.ForeignKey(CertType)
    purpose = models.TextField()
    status = models.CharField(choices=STATUS_CHOICES)
    cert_number = models.CharField(max_length=30, unique=True, null=True)
    issued_at = models.DateTimeField(null=True)
    issuer = models.ForeignKey(User, null=True)
    pdf_file = models.FileField(upload_to='certs/', null=True)
```

### 3.7 公益服务模块 (public_service)

#### 3.7.1 业务子类

| 子类编码 | 业务名称 |
|----------|----------|
| P01 | 志愿者登记 |
| P02 | 志愿服务时间储蓄证明 |
| P03 | 志愿者培训及社区服务安排 |
| P04 | 邻里互助组织 |
| P05 | 书画展/合唱队/秧歌队等兴趣小组 |
| P06 | 棋牌/阅览/健身/聚会设施预约 |
| P07 | 轮椅借用 |
| P08 | 市民学校课程 |
| P09 | 医疗保健服务 |
| P10 | 社区单位资源共享 |

#### 3.7.2 数据模型

```python
class Volunteer(models.Model):
    resident = models.ForeignKey(Resident)
    registered_at = models.DateField()
    skills = models.CharField(max_length=200, blank=True)
    total_hours = models.FloatField(default=0)
    is_active = models.BooleanField(default=True)

class VolunteerServiceRecord(models.Model):
    volunteer = models.ForeignKey(Volunteer)
    activity = models.ForeignKey('Activity')
    hours = models.FloatField()
    date = models.DateField()
    verified = models.BooleanField(default=False)
    verified_by = models.ForeignKey(User, null=True)

class Activity(models.Model):
    title = models.CharField(max_length=200)
    activity_type = models.CharField(choices=ACTIVITY_TYPE_CHOICES)
    description = models.TextField()
    start_time = models.DateTimeField()
    end_time = models.DateTimeField()
    location = models.CharField(max_length=200)
    max_participants = models.IntegerField(null=True)
    current_participants = models.IntegerField(default=0)
    status = models.CharField(choices=ACTIVITY_STATUS_CHOICES)
    organizer = models.ForeignKey(User)

class FacilityBooking(models.Model):
    facility = models.ForeignKey('Facility')
    resident = models.ForeignKey(Resident)
    booking_date = models.DateField()
    start_time = models.TimeField()
    end_time = models.TimeField()
    status = models.CharField(choices=[('pending', '待确认'), ('confirmed', '已确认'), ('cancelled', '已取消')])

class Facility(models.Model):
    name = models.CharField(max_length=100)
    facility_type = models.CharField(choices=FACILITY_TYPE_CHOICES)
    description = models.TextField(blank=True)
    is_available = models.BooleanField(default=True)
```

### 3.8 民意反映与政策咨询模块 (feedback)

#### 3.8.1 业务子类

| 子类编码 | 业务名称 |
|----------|----------|
| F01 | 向部门/单位提意见、要求、困难、建议 |
| F02 | 向政府部门咨询政策、办事手续 |

#### 3.8.2 数据模型

```python
class Feedback(models.Model):
    FEEDBACK_TYPE_CHOICES = [
        ('opinion', '意见'),
        ('demand', '要求'),
        ('difficulty', '困难'),
        ('suggestion', '建议'),
        ('policy_inquiry', '政策咨询'),
        ('procedure_inquiry', '办事手续咨询'),
    ]
    submitter = models.ForeignKey(Resident)
    feedback_type = models.CharField(choices=FEEDBACK_TYPE_CHOICES)
    title = models.CharField(max_length=200)
    content = models.TextField()
    target_department = models.CharField(max_length=100, blank=True)
    status = models.CharField(choices=[
        ('submitted', '已提交'),
        ('forwarded', '已转交'),
        ('replied', '已回复'),
        ('closed', '已关闭'),
    ])
    reply = models.TextField(blank=True)
    replier = models.ForeignKey(User, null=True)
    created_at = models.DateTimeField(auto_now_add=True)
    replied_at = models.DateTimeField(null=True)
```

### 3.9 社区治理模块 (governance)

#### 3.9.1 核心功能

- 社区治理目标管理（文明向上、健康安全、生活便利、环境整洁、民主自治）
- "一窗式"服务窗口管理
- 公共服务/公益服务/便民服务整合调度
- 居民自治事务管理

#### 3.9.2 数据模型

```python
class GovernanceGoal(models.Model):
    title = models.CharField(max_length=200)
    category = models.CharField(choices=[
        ('civilized', '文明向上'),
        ('healthy', '健康安全'),
        ('convenient', '生活便利'),
        ('clean', '环境整洁'),
        ('democratic', '民主自治'),
    ])
    description = models.TextField()
    target_date = models.DateField()
    responsible_person = models.ForeignKey(User)
    progress = models.IntegerField(default=0)
    status = models.CharField(choices=[('in_progress', '进行中'), ('completed', '已完成')])

class OneWindowService(models.Model):
    window_number = models.CharField(max_length=10)
    staff = models.ForeignKey(User)
    service_categories = models.ManyToManyField(AgencyServiceCategory)
    is_active = models.BooleanField(default=True)

class ServiceIntegration(models.Model):
    service_type = models.CharField(choices=[
        ('public', '公共服务'),
        ('welfare', '公益服务'),
        ('convenience', '便民服务'),
    ])
    name = models.CharField(max_length=200)
    provider = models.CharField(max_length=100)
    contact = models.CharField(max_length=11)
    description = models.TextField()
```

### 3.10 通知消息模块 (notification)

#### 3.10.1 核心功能

- 站内消息推送
- 微信模板消息通知
- 短信通知（对接短信网关）
- 公告管理

#### 3.10.2 数据模型

```python
class Notification(models.Model):
    recipient = models.ForeignKey(User)
    title = models.CharField(max_length=200)
    content = models.TextField()
    notification_type = models.CharField(choices=[
        ('system', '系统通知'),
        ('business', '业务通知'),
        ('announcement', '公告'),
    ])
    is_read = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

class Announcement(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    is_pinned = models.BooleanField(default=False)
    published_at = models.DateTimeField()
    publisher = models.ForeignKey(User)
```

### 3.11 数据统计模块 (statistics)

#### 3.11.1 核心功能

- 业务量统计（按类型、时间段、经办人）
- 居民画像分析（年龄分布、标签分布、家庭结构）
- 办理时效分析（平均办理时长、超时率）
- 满意度统计
- 数据导出（Excel/PDF）

#### 3.11.2 实现方式

- 使用 Django ORM 聚合查询 + Celery 定时任务预计算
- 前端 ECharts 可视化
- 关键指标缓存至 Redis，定时刷新

---

## 四、数据库设计

### 4.1 ER 关系概览

```
Community 1──N User
Community 1──N Resident
Resident 1──N AgencyApplication
Resident 1──N DistributionRecord
Resident 1──N LegalPsychService
Resident 1──N CertApplication
Resident 1──N Feedback
Resident 1──1 Volunteer
Resident N──1 Family
AgencyApplication N──1 AgencyServiceCategory
AgencyApplication 1──N AgencyDocument
AgencyApplication 1──N AgencyStatusLog
Volunteer 1──N VolunteerServiceRecord
Activity 1──N VolunteerServiceRecord
Activity 1──N ActivityRegistration
Facility 1──N FacilityBooking
```

### 4.2 公共字段约定

所有业务表均包含以下公共字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| created_at | DateTimeField | 创建时间，auto_now_add |
| updated_at | DateTimeField | 更新时间，auto_now |
| created_by | ForeignKey(User) | 创建人 |
| is_deleted | BooleanField | 逻辑删除标记，default=False |

### 4.3 索引策略

- 所有外键字段自动建索引
- `id_card` 字段建唯一索引
- `status` + `created_at` 联合索引（用于按状态筛选+排序）
- `resident_id` + `created_at` 联合索引（用于查询某居民的业务记录）

---

## 五、接口设计

### 5.1 API 规范

- 遵循 RESTful 风格
- 统一响应格式：

```json
{
    "code": 200,
    "message": "success",
    "data": { }
}
```

- 分页响应格式：

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "count": 100,
        "next": "/api/v1/agency/applications/?page=2",
        "previous": null,
        "results": [ ]
    }
}
```

### 5.2 核心 API 列表

| 模块 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 认证 | POST | /api/v1/auth/login/ | 登录 |
| 认证 | POST | /api/v1/auth/wechat/ | 微信授权登录 |
| 认证 | POST | /api/v1/auth/refresh/ | 刷新Token |
| 居民 | GET/POST | /api/v1/residents/ | 居民列表/新增 |
| 居民 | GET/PUT | /api/v1/residents/{id}/ | 居民详情/修改 |
| 代理代办 | GET/POST | /api/v1/agency/applications/ | 申请列表/新增 |
| 代理代办 | GET/PATCH | /api/v1/agency/applications/{id}/ | 申请详情/更新状态 |
| 代理代办 | POST | /api/v1/agency/applications/{id}/accept/ | 受理 |
| 代理代办 | POST | /api/v1/agency/applications/{id}/complete/ | 办结 |
| 代发代收 | GET/POST | /api/v1/distribution/records/ | 发放/收取记录 |
| 法律心理 | GET/POST | /api/v1/legal-psych/services/ | 服务申请列表/新增 |
| 代开证明 | GET/POST | /api/v1/cert/applications/ | 证明申请列表/新增 |
| 代开证明 | POST | /api/v1/cert/applications/{id}/issue/ | 开具证明 |
| 公益服务 | GET/POST | /api/v1/public/activities/ | 活动列表/发布 |
| 公益服务 | POST | /api/v1/public/activities/{id}/register/ | 活动报名 |
| 公益服务 | GET/POST | /api/v1/public/facilities/bookings/ | 设施预约 |
| 民意反映 | GET/POST | /api/v1/feedback/ | 意见/咨询列表/提交 |
| 民意反映 | POST | /api/v1/feedback/{id}/reply/ | 回复 |
| 统计 | GET | /api/v1/statistics/overview/ | 总览数据 |
| 统计 | GET | /api/v1/statistics/agency/ | 代理代办统计 |
| 统计 | GET | /api/v1/statistics/resident-profile/ | 居民画像 |
| 通知 | GET | /api/v1/notifications/ | 通知列表 |
| 公告 | GET | /api/v1/announcements/ | 公告列表 |

### 5.3 认证与权限

- 管理后台：JWT Token 认证（Access Token 2h + Refresh Token 7d）
- 小程序端：微信 OpenID 关联 + JWT Token
- 权限控制：基于 Django Guardian 的对象级权限
- API 限流：DRF Throttling（匿名 100次/h，认证 1000次/h）

---

## 六、非功能性需求

### 6.1 性能要求

| 指标 | 目标值 |
|------|--------|
| API 平均响应时间 | < 200ms |
| 并发用户数 | ≥ 200 |
| 数据库查询 | 单次 < 50ms |
| 文件上传 | 支持 ≤ 20MB |

### 6.2 安全要求

| 项目 | 措施 |
|------|------|
| 传输安全 | 全站 HTTPS |
| 认证安全 | JWT + 黑名单机制 |
| 数据安全 | 敏感字段加密存储（身份证号等） |
| SQL 注入 | ORM 参数化查询 |
| XSS | 模板自动转义 + CSP 头 |
| CSRF | Django 内置 CSRF 中间件 |
| 日志审计 | 关键操作全量记录 |
| 备份策略 | 每日全量备份 + 实时 WAL 归档 |

### 6.3 可用性要求

| 指标 | 目标值 |
|------|--------|
| 系统可用率 | ≥ 99.5% |
| 故障恢复时间 | < 2h |
| 数据恢复点 | < 1h |

---

## 七、部署架构

### 7.1 初期部署方案（单机 Docker Compose）

```yaml
# docker-compose.yml 概要
services:
  web:
    build: .
    command: gunicorn config.wsgi:application --bind 0.0.0.0:8000
    volumes:
      - ./media:/app/media
    depends_on:
      - db
      - redis
    environment:
      - DATABASE_URL=postgres://...
      - REDIS_URL=redis://...

  celery-worker:
    build: .
    command: celery -A config worker -l info
    depends_on:
      - db
      - redis

  celery-beat:
    build: .
    command: celery -A config beat -l info
    depends_on:
      - redis

  db:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./static:/app/static
      - ./media:/app/media

volumes:
  pgdata:
```

### 7.2 后期扩展方案

- 应用层：Docker Swarm / K8s 水平扩展
- 数据库：读写分离 + 连接池 (PgBouncer)
- 缓存：Redis Sentinel 高可用
- 文件存储：迁移至阿里云 OSS
- 监控：Prometheus + Grafana
- 日志：ELK Stack

---

## 八、开发计划

### 8.1 阶段划分

| 阶段 | 内容 | 交付物 |
|------|------|--------|
| 第一阶段 | 基础框架搭建 + 用户权限 + 居民管理 | 可运行的基础系统 |
| 第二阶段 | 代理代办 + 代开证明（核心业务） | 核心业务可用 |
| 第三阶段 | 代发代收 + 法律心理 + 公益服务 | 业务全覆盖 |
| 第四阶段 | 民意反映 + 社区治理 + 通知消息 | 功能完善 |
| 第五阶段 | 数据统计 + 小程序端 | 全功能交付 |
| 第六阶段 | 测试优化 + 部署上线 | 生产环境运行 |

### 8.2 技术债务管理

- 每个阶段结束进行代码审查
- 核心模块单元测试覆盖率 ≥ 80%
- API 集成测试覆盖核心流程
- 性能测试在第五阶段完成后执行

---

## 九、风险与应对

| 风险 | 影响 | 概率 | 应对措施 |
|------|------|------|----------|
| 居民隐私数据泄露 | 高 | 低 | 加密存储、权限最小化、审计日志 |
| 业务流程变更频繁 | 中 | 高 | 状态机可配置化、模板化证明 |
| 并发量超预期 | 中 | 低 | Redis 缓存、数据库连接池、限流 |
| 微信接口变动 | 低 | 中 | 抽象微信服务层、接口版本化 |
| 第三方短信服务不可用 | 低 | 低 | 多供应商备选、消息队列缓冲 |

---

## 十、术语表

| 术语 | 说明 |
|------|------|
| 一窗式服务 | 居民到一个窗口即可办理所有业务的服务模式 |
| 居民标签 | 对居民分类标记，如低保户、残疾人、独居老人等 |
| 时间储蓄 | 志愿者服务时长记录，可用于兑换社区服务 |
| WAL | Write-Ahead Logging，PostgreSQL 事务日志 |
| DRF | Django REST Framework |
| ADR | Architecture Decision Record，架构决策记录 |

---

*文档版本：v1.0*
*编写日期：2026年5月18日*