# 项目与补贴 — 补贴 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 项目与补贴 — 补贴 |
| 目标 | 对补贴政策/补贴事项进行登记、查询与发放状态管理，支撑补贴明细留存与发放过程跟踪 |
| 关联系统 | 业务后台 |
| 修订依据 | 同目录 `项目与补贴-补贴-草稿.md` |

本文档仅描述**功能需求与业务规则**，不涉及库表结构、接口路径、请求体字段命名及技术栈选型。

---

## 2. 术语与枚举

### 2.1 发放状态（单选）

| 取值 | 含义概要 |
| --- | --- |
| **申请中** | 补贴处于申报、审核或待发放阶段，尚未完成发放 |
| **已发放** | 补贴已完成发放（与业务财务/发放确认流程一致） |

### 2.2 发布状态（与发放状态独立）

| 取值 | 含义概要 |
| --- | --- |
| **未发布** | 新建或下架回流；可编辑、可删除、可发布 |
| **已发布** | 对外可见；**不可修改**、**不可删除**，须先下架 |

下架后可再编辑、再发布，**无须新建**记录。

### 2.3 记录说明

本模块为**补贴事项台账**。**发放状态**（申请中/已发放）描述业务进度；**发布状态**控制对外展示与后台改删权限（二者独立）。

---

## 3. 功能范围

- 补贴的新增、修改、删除、分页列表查询、详情查看
- 补贴名称、简介、发放状态、补贴明细附件（必填）、封面（选填）的录入与校验
- **发布、下架**及发布状态约束
- 按补贴名称/简介、发放状态、**发布状态**的组合查询
- 删除记录时联动清理补贴明细附件与封面文件
- 面向使用方的业务错误与校验提示（见第 7 章）

---

## 4. 业务流程概览

```mermaid
flowchart LR
    A[新增补贴] --> B[登记申请中或已发放]
    B --> C[列表查询/筛选]
    C --> D[查看详情]
    C --> E[修改补贴]
    C --> F[删除补贴]
    E --> B
    F --> C
    B --> G[发布]
    G --> H[已发布]
    H --> I[下架]
    I --> B
```

1. **登记**：录入字段并上传明细附件（必填）→ 初始 **未发布**；发放状态默认多为 **申请中**。  
2. **维护**：**未发布** 下可修改；替换附件时清理旧文件。  
3. **发布 / 下架**：规则同项目模块 **§5.6**。  
4. **查询**：按名称/简介、发放状态、发布状态筛选。  
5. **删除**：仅 **未发布** 可删。

**发放状态（建议）：** 申请中 → 已发放；亦允许补录时直接选 **已发放**。

---

## 5. 详细功能需求

### 5.1 新增补贴

| 字段 | 规则 |
| --- | --- |
| 补贴名称 | **必填**；长度 **1～20** 个字符 |
| 补贴简介 | **选填**；若有内容，长度不超过 **50 字** |
| 发放状态 | **必填**；单选，取值 **§2.1**（**申请中** / **已发放**） |
| 补贴明细附件 | **必填**；**单个**非结构化文档；允许后缀：`pdf`、`md`、`doc`、`docx`、`xls`、`xlsx`、`ppt`、`pptx`；单文件 ≤ **30 MB** |
| 封面 | **选填**；**单个**图片；允许后缀 `jpg`、`jpeg`、`png`（可扩展 `webp`）；单文件 ≤ **10 MB** |

**必填字段汇总：** 补贴名称、发放状态、补贴明细附件。

**校验：**

- 须校验附件后缀与白名单、文件大小；不符时给出可区分提示。
- 若业务要求补贴名称在组织范围内唯一，应在评审时单独约定。

**初始建议：** 新建时发放状态默认 **申请中**（前端默认值；用户可改为 **已发放**）。

---

### 5.2 查询补贴列表

- **关键字：** 对「补贴名称」或「补贴简介」**模糊**匹配（**OR**）；为空则不过滤。  
- **发放状态：** **精确**匹配；未选择则不过滤。  
- **发布状态：** **精确**匹配；未选择则不过滤。  
- **说明：** 草稿查询「补贴类型」与 **§5.1** 字段不一致，正式以 **发放状态** 筛选；补贴类型若后续增加须同步修订。  
- **分页：** 默认 **每页 20 条**，首页为第一页。  
- **排序：** 默认按 **创建时间倒序**（最新在前）；次要排序键与项目列表规范一致（若有）。

**列表宜展示：** 补贴名称、简介、发放状态、**发布状态**、明细附件名、封面、发布时间、创建时间，及操作列。

---

### 5.3 修改补贴

- **可修改项：** 全部字段（同 **§5.1**）；**仅未发布** 时可保存。  
- **已发布：** 不可修改（须先下架）。  
- **保存约束：** **补贴名称、发放状态、补贴明细附件** 始终保持有效（不可保存为无明细附件）；校验规则同 **§5.1**。  
- **附件替换：** 更换补贴明细附件或封面并保存成功后，须删除旧文件，避免存储残留。  
- **状态变更：** 允许 **申请中** ↔ **已发放** 互相变更（默认）；若「已发放」后禁止回退，须在评审时约定并限制界面与保存逻辑。

---

### 5.4 删除补贴

- **允许删除：** **未发布** 且具备删除权限。  
- **不允许删除：** **已发布**；须先下架。  
- **删除后果：** 删除明细附件与封面物理文件。  
- **确认：** 删除前宜二次确认。

---

### 5.5 查看补贴详情

- **展示内容：** 补贴名称、简介、发放状态、明细附件、封面、**发布状态**、发布/下架时间；宜含审计字段。  
- **交互：** **未发布** 可编辑；**已发布** 只读，可提供下架。

---

### 5.6 发布与下架

规则与「项目与补贴 — 项目」**§5.6** 一致：发布前 **未发布** 且 **§5.1** 校验通过（含明细附件必填）；下架不删附件，回到 **未发布** 后可再编辑、再发布。

---

## 6. 状态与操作矩阵（汇总）

| 当前发布状态 | 查看 | 修改 | 发布 | 下架 | 删除 |
| --- | --- | --- | --- | --- | --- |
| 未发布 | ✓ | ✓ | ✓ | — | ✓ |
| 已发布 | ✓ | ✗ | — | ✓ | ✗ |

---

## 7. 错误与提示约定

- 业务与校验错误采用项目统一 **`code`、`msg`、`data`** 结构。  
- 宜可区分：必填缺失、字段超长、明细附件缺失/格式/大小不符、封面格式/大小不符、无权限等。

---

## 8. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 权限 | 菜单与按钮：查询、新增、修改、删除、发布、下架、导出（若需要） |
| 审计 | 新增、修改、删除及发放状态变更记操作日志 |
| 安全 | 上传校验；明细附件下载/预览鉴权 |
| 性能 | 列表查询满足后台通用体验 |
| 双语 | 字段标签与提示符合项目 i18n（汉语 + 藏文） |
| 关联扩展 | 与「项目与补贴 — 项目」「补贴发放记录」等模块的关联关系若需建立，单独出关联需求 |

---

## 9. 修订说明（相对草稿）

| 草稿问题 | 优化处理 |
| --- | --- |
| 查询写「补贴类型」但新增无该字段 | 筛选改为 **发放状态**；补贴类型留作扩展说明 |
| 「查看补」 | 更正为 **查看补贴** |
| 补贴简介是否必填 | 明确为 **选填**，≤50 字 |
| 补贴名称长度 | **1～20** 字符 |
| 发放状态仅列枚举 | 补充典型流转、默认建议申请中 |
| 删除是否清文件 | 明确删明细附件 + 封面 |
| 第 6、7 条技术栈与接口 | 技术栈移除；错误约定保留 **§7** |
| 明细附件「必填」 | 新增/修改保存时均不可为空 |
| 草稿 §6 发布/下架 | 新增 **§2.2、§5.6** 与矩阵；与发放状态独立 |
| 「产互」/「查看补」 | 更正为 **删除** / **查看补贴** |
