# 项目与补贴 — 补贴 — 技术方案

> 依据：同目录 `项目与补贴-补贴功能需求.md`。台账 **CRUD** + 明细附件/封面管理 + **发布/下架**。

---

## 1. 技术架构

| 项 | 说明 |
| --- | --- |
| **后端** | RuoYi **v3.9.2**（**springboot2** 分支）：JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid |
| **数据库** | MySQL **5.7.39**，InnoDB，`utf8mb4` |
| **前端** | 若依 Vue2；上传复用 `POST /common/upload` |
| **文件** | 表存 URL、存储路径、明细附件原始名；**不入库**文件大小 |

**分层**：`Controller` → `Service`（字段校验、替换/删除物理文件）→ `Mapper`/XML → `domain`。

**业务特征（摘要）**

| 场景 | 行为 |
| --- | --- |
| 新增/修改 | 校验必填；明细附件三元组必填；替换附件成功后删旧 `detail_file_path`、`cover_file_path` |
| 列表/详情 | 默认 `create_time DESC, id DESC`；不区分发放状态限制删改 |
| 删除 | 删库表记录 + 明细附件 + 封面物理文件 |

**发放状态**：用户维护，`1` 申请中、`2` 已发放；新建未传时默认 `1`。

**发布状态**：与项目模块一致；`publish_status` `0`/`1`；未发布可改删发布，已发布仅查看/下架。

---

## 2. 数据库设计

### 2.1 表 `biz_subsidy_matter`（补贴事项台账）

| 字段 | 类型 | 非空 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | `bigint(20)` | Y | 自增 | 主键 |
| `subsidy_name` | `varchar(64)` | Y | — | 补贴名称（**1～20** 字） |
| `introduction` | `varchar(200)` | N | NULL | 补贴简介，选填（≤50 字） |
| `grant_status` | `tinyint(4)` | Y | `1` | `1` 申请中，`2` 已发放 |
| `detail_file_url` | `varchar(512)` | Y | — | 补贴明细附件访问 URL |
| `detail_file_path` | `varchar(512)` | Y | — | 明细附件存储路径 |
| `detail_file_name` | `varchar(256)` | Y | — | 明细附件原始文件名 |
| `cover_file_url` | `varchar(512)` | N | NULL | 封面 URL |
| `cover_file_path` | `varchar(512)` | N | NULL | 封面存储路径 |
| `publish_status` | `tinyint(4)` | Y | `0` | `0` 未发布 `1` 已发布 |
| `publish_time` | `datetime` | N | NULL | 发布时间 |
| `offline_time` | `datetime` | N | NULL | 下架时间 |
| `create_by` / `create_time` / `update_by` / `update_time` | 若依惯例 | — | — | 审计 |
| `remark` | `varchar(500)` | N | NULL | 备注 |

**索引**：`PRIMARY KEY (id)`；`KEY idx_grant_status (grant_status)`；`KEY idx_create_time (create_time)`；`KEY idx_publish (publish_status)`。

**DDL（MySQL 5.7）**

```sql
CREATE TABLE `biz_subsidy_matter` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
  `subsidy_name` varchar(64) NOT NULL COMMENT '补贴名称',
  `introduction` varchar(200) DEFAULT NULL COMMENT '补贴简介',
  `grant_status` tinyint(4) NOT NULL DEFAULT '1' COMMENT '1申请中 2已发放',
  `detail_file_url` varchar(512) NOT NULL COMMENT '明细附件URL',
  `detail_file_path` varchar(512) NOT NULL COMMENT '明细附件存储路径',
  `detail_file_name` varchar(256) NOT NULL COMMENT '明细附件原始文件名',
  `cover_file_url` varchar(512) DEFAULT NULL COMMENT '封面URL',
  `cover_file_path` varchar(512) DEFAULT NULL COMMENT '封面存储路径',
  `publish_status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '0未发布 1已发布',
  `publish_time` datetime DEFAULT NULL COMMENT '发布时间',
  `offline_time` datetime DEFAULT NULL COMMENT '下架时间',
  `create_by` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT '' COMMENT '更新者',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
  PRIMARY KEY (`id`),
  KEY `idx_grant_status` (`grant_status`),
  KEY `idx_create_time` (`create_time`),
  KEY `idx_publish` (`publish_status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='项目与补贴-补贴';
```

### 2.2 枚举常量

| 字段 | 值 | 含义 |
| --- | --- | --- |
| `grant_status` | `1` | 申请中 |
| | `2` | 已发放 |
| `publish_status` | `0` | 未发布 |
| | `1` | 已发布 |

---

## 3. 接口设计

**统一响应**：`AjaxResult` / 分页 `TableDataInfo`（`rows`、`total`）。

**权限标识（示例）**：`industryPolicy:subsidyMatter:list|query|add|edit|remove|publish|offline|export`

**Base Path（示例）**：`/industryPolicy/subsidyMatter`

| # | 说明 | Method | URI | 权限 | 要点 |
| --- | --- | --- | --- | --- | --- |
| 3.1 | 分页列表 | GET | `/industryPolicy/subsidyMatter/list` | `industryPolicy:subsidyMatter:list` | Query **3.1.1**；排序 `create_time DESC, id DESC` |
| 3.2 | 详情 | GET | `/industryPolicy/subsidyMatter/{id}` | `industryPolicy:subsidyMatter:query` | 全字段；附件下载/预览鉴权 |
| 3.3 | 新增 | POST | `/industryPolicy/subsidyMatter` | `industryPolicy:subsidyMatter:add` | Body **3.3.1**；`publish_status=0`；`grantStatus` 缺省 `1` |
| 3.4 | 修改 | PUT | `/industryPolicy/subsidyMatter` | `industryPolicy:subsidyMatter:edit` | **仅** `publish_status=0`；替换附件删旧 |
| 3.5 | 删除 | DELETE | `/industryPolicy/subsidyMatter/{ids}` | `industryPolicy:subsidyMatter:remove` | **仅** `publish_status=0`；删附件与封面 |
| 3.6 | 发布 | POST | `/industryPolicy/subsidyMatter/publish/{id}` | `industryPolicy:subsidyMatter:publish` | 前置 `0`；校验明细附件等 |
| 3.7 | 下架 | POST | `/industryPolicy/subsidyMatter/offline/{id}` | `industryPolicy:subsidyMatter:offline` | 前置 `1`；`publish_status=0` |

#### 3.1.1 列表 Query

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pageNum` / `pageSize` | int | N | 默认 `1` / `20` |
| `keyword` | string | N | 补贴名称 / 简介 **OR** 模糊；空不过滤 |
| `grantStatus` | int | N | `1` / `2` 精确；空不过滤 |
| `publishStatus` | int | N | `0` / `1` 精确；空不过滤 |

#### 3.3.1 新增 / 修改 Body（驼峰）

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `id` | 修改 Y | 主键 |
| `subsidyName` | Y | 1～20 字符 |
| `introduction` | N | ≤50 字 |
| `grantStatus` | Y | `1` 或 `2` |
| `detailFileUrl` / `detailFilePath` / `detailFileName` | Y | 上传后填入，三者同时有效 |
| `coverFileUrl` / `coverFilePath` | N | 封面成对；可空 |
| `remark` | N | 备注 |

**列表行字段（示例）**：`id`、`subsidyName`、`introduction`、`grantStatus`、`detailFileName`、`coverFileUrl`、`createTime`。

### 3.4 附件流程

1. 前端 `POST /common/upload` → 取 `url`、`fileName`（path）、`originalFilename`（明细附件作 `detailFileName`）。  
2. 提交新增/修改时带上 URL + path + 原始名。  
3. 修改替换或删除记录时，Service 删除旧 `detail_file_path`、`cover_file_path` 物理文件。

### 3.5 服务端校验（摘要）

| 项 | 规则 |
| --- | --- |
| 补贴名称 | 非空，1～20 字符 |
| 补贴简介 | 可空；有值 ≤50 字 |
| 发放状态 | ∈ {1, 2} |
| 明细附件 | 必填；后缀 `pdf,md,doc,docx,xls,xlsx,ppt,pptx`；≤30MB |
| 封面 | 可空；有则 `jpg,jpeg,png`（可扩展 `webp`）；≤10MB |

---

## 4. 菜单与权限 SQL（示例）

| 类型 | 名称 | 权限标识 |
| --- | --- | --- |
| 菜单 | 项目与补贴-补贴 | `industryPolicy:subsidyMatter:list` |
| 按钮 | 查询/新增/修改/删除/发布/下架/导出 | `…:query` `…:add` `…:edit` `…:remove` `…:publish` `…:offline` `…:export` |

组件路径建议：`policy/subsidyMatter/index`。

---

## 5. 交付清单

- [ ] `biz_subsidy_matter` DDL、菜单权限 SQL  
- [ ] `BizSubsidyMatter` Domain / Mapper / Service / Controller  
- [ ] 明细附件/封面上传校验、替换与删除联动  
- [ ] 前端：关键字 + 发放状态筛选、附件必填、列表展示文件名  

---

## 6. 修订记录

| 日期 | 说明 |
| --- | --- |
| — | 初稿：对齐功能需求；台账 CRUD；`grant_status` 1/2；明细附件必填 |
| 1.1 | 草稿 §6：新增发布/下架字段与接口；已发布不可改删 |