# 共同富裕项目 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 共同富裕项目 |
| 目标 | 对共富类项目进行录入、查询、维护与发布管理，支撑面向使用方的项目展示与查阅 |
| 关联系统 | 业务后台；移动端「养殖资讯」等渠道可按产品约定展示已发布项目（见 **§8**） |
| 修订依据 | 同目录 `共同富裕项目-草稿.md` |

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

---

## 2. 术语与状态

### 2.1 项目类型（枚举，单选）

- **合作共赢**
- **农文旅融合**
- **认养农业**

### 2.2 发布状态（互斥，单值）

| 取值 | 含义概要 |
| --- | --- |
| **未发布** | 新建草稿或已下架回流；对外不可见（与产品「前台 / App 展示」定义一致）；在满足矩阵规则下可编辑、可删除、可发布 |
| **已发布** | 对外可见或可检索（与产品定义一致）；**不允许修改**；**不允许直接删除**，须先执行 **下架** |

**下架回流：** 对已发布项目执行「下架」后，发布状态回到 **未发布**，允许再次编辑并在校验通过后 **再次发布**，**无须新建**一条记录。

### 2.3 实施周期说明

「实施日期」由 **开始日期**、**结束日期** 两个自然日字段组成，表示项目计划实施的时间区间；校验规则见 **§5.1**。

---

## 3. 功能范围

- 共富项目的新增、修改、删除、分页列表查询、详情查看
- 运营图片（多张）、运营视频、封面等附件的上传、替换、展示及删除时的存储联动清理
- 发布、下架及发布状态约束下的操作权限控制
- 按项目名称、项目类型、发布状态等条件的组合查询
- 面向使用方的业务错误与校验提示（见第 **7** 章）

---

## 4. 业务流程概览

下列顺序描述**典型闭环**；具体操作禁忌以 **第 6 节矩阵** 为准。

1. **新建**：录入必填项，上传运营图片及可选的视频、封面 → 初始为 **未发布**。
2. **维护**：在 **未发布** 下可反复修改字段与附件，直至内容定稿。
3. **发布**：在 **未发布** 且满足发布前置校验时执行「发布」→ **已发布**。
4. **对外展示**：**已发布** 项目按产品约定在后台列表、移动端「共富项目」等渠道展示；后台详情为只读维护视角。
5. **下架**：在 **已发布** 下执行「下架」→ 回到 **未发布**，结束对外展示。
6. **再编辑 / 再发布**：下架后可修改并再次发布（重复步骤 2～3）。
7. **删除**：仅在 **未发布** 下允许删除整条记录及关联附件；**已发布** 须先下架。

```mermaid
stateDiagram-v2
    [*] --> 未发布: 新建
    未发布 --> 已发布: 发布
    已发布 --> 未发布: 下架
    未发布 --> [*]: 删除
```

---

## 5. 详细功能需求

### 5.1 新增共富项目

| 字段 | 规则 |
| --- | --- |
| 项目名称 | **必填**；长度 **1～20** 个字符（字符计数规则与项目全局一致） |
| 项目类型 | **必填**；单选，取值限定为第 **2.1** 节 |
| 项目简介 | **必填**；长度 **1～50** 个字符 |
| 项目内容 | **必填**；长度 **1～500** 个字符 |
| 实施开始日期 | **必填**；格式 **YYYY-MM-DD** |
| 实施结束日期 | **必填**；格式 **YYYY-MM-DD**；须 **≥ 实施开始日期** |
| 运营图片 | **必填**；**1～3 张**图片；每张通过独立上传；允许后缀：`jpg`、`jpeg`、`png`（若产品要求支持 `webp` 等可追加）；单张 ≤ **10 MB** |
| 运营视频 | **选填**；**单个**视频上传；允许后缀：`mp4`（若产品要求支持 `mov`、`webm` 等可追加）；单文件大小上限与项目视频上传规范一致（未单独约定时建议 ≤ **100 MB**，须在实现前与产品确认） |
| 封面 | **选填**；**单个**图片上传；允许后缀：`jpg`、`jpeg`、`png`；单文件 ≤ **10 MB** |

**必填字段汇总：** 项目名称、项目类型、项目简介、项目内容、实施开始日期、实施结束日期、运营图片（至少 1 张、最多 3 张）。

**校验：**

- 实施结束日期早于开始日期时，须拒绝保存并提示（如「结束日期不能早于开始日期」）。
- 运营图片数量少于 1 张或多于 3 张时，须拒绝保存并提示。
- 须校验附件类型（后缀与白名单 / 项目安全规范一致）与大小；超限或格式不符时给出**可区分**的错误提示。
- 若业务要求项目名称在适用范围（如租户 / 组织）内唯一，应在评审时单独约定并写入本节。

**初始状态：** 新建成功后，发布状态为 **未发布**。

---

### 5.2 查询共富项目列表

- **项目名称：** 对「项目名称」进行**模糊**匹配；名称为空时不按名称过滤。
- **项目类型：** **精确**匹配筛选；未选择时不按类型过滤。
- **发布状态（建议）：** 列表宜支持按 **未发布 / 已发布** 筛选，便于运营人员区分待发布与已上线内容。
- **分页：** 支持分页；默认 **每页 20 条**，默认首页为第一页；单页条数上限与项目列表通用规范一致（若有）。
- **排序：** 默认按 **创建时间倒序**（最新在前）；次要排序键与项目列表规范一致（若有）。

**列表宜展示：** 项目名称、项目类型、项目简介（可截断）、实施开始/结束日期、发布状态、封面缩略图（若有）、运营图片数量提示，以及当前状态下可执行的操作入口。

---

### 5.3 修改共富项目

- **状态约束：** **仅未发布**（含新建后未发布、**已从已发布下架回流**）允许修改。**已发布**状态下**不允许修改**（列表 / 详情不提供可提交的编辑入口，或仅为只读；任何保存类修改须被拒绝并给出明确业务原因，如「已发布项目请先下架后再编辑」）。
- **可修改项：** 项目名称、项目类型、项目简介、项目内容、实施开始日期、实施结束日期、运营图片、运营视频、封面。
- **保存约束：** **§5.1** 中全部必填规则在修改时仍须满足；运营图片仍须保持 **1～3 张**；日期区间、附件格式与大小规则与新增一致。
- **附件替换：**
  - 替换、增删运营图片或更换封面、运营视频时，保存成功后须清理被移除的旧文件，避免存储残留。
  - 若用户将运营图片删至 0 张再提交，须按校验拒绝。

---

### 5.4 删除共富项目

- **允许删除：** 发布状态为 **未发布** 的记录。
- **不允许删除：** 发布状态为 **已发布** 的记录；须先执行「下架」（见 **5.6**）回到 **未发布** 后再删除。
- **删除后果：** 删除本条业务记录时，须**同步删除**关联存储中的全部运营图片、运营视频（若有）、封面（若有），避免存储残留。
- **确认：** 删除前宜弹出确认提示，避免误删。

---

### 5.5 查看共富项目详情

- **展示内容：** 项目名称、项目类型、项目简介、项目内容、实施开始日期、实施结束日期、运营图片（可预览）、运营视频（若有，可播放或下载入口）、封面（若有）、当前 **发布状态**；宜展示创建人、创建时间、发布时间、下架时间、最后修改人、最后修改时间（若系统有审计字段）。
- **权限与交互：**
  - **未发布：** 具备权限的用户可进入编辑流程（见 **5.3**）；可提供「发布」入口。
  - **已发布：** 详情为 **只读**（无保存类编辑）；可提供「下架」操作入口。
- **在线预览：** 运营图片、封面、运营视频的在线预览能力按项目通用附件组件约定；若 App 端仅展示已发布数据，须与后台发布状态联动。

---

### 5.6 发布与下架

#### 发布

- **前置条件：**
  - 当前发布状态为 **未发布**；
  - 必填字段均已满足 **5.1** 规则（含项目名称、项目类型、项目简介、项目内容、实施日期区间、至少 1 张且至多 3 张运营图片）。
- **操作结果：** 发布状态变为 **已发布**；记录发布时间；内容按产品约定对外可见（如移动端「共富项目」栏目可展示）。
- **失败处理：** 校验不通过时须给出明确原因（如必填项缺失、图片数量不符、日期非法等），不变更发布状态。

#### 下架

- **前置条件：** 当前发布状态为 **已发布**。
- **操作结果：**
  - 发布状态变为 **未发布**；
  - 对外展示 / 检索可见性结束（与产品「前台 / App 是否展示」定义一致）；
  - 记录下架时间（若系统支持）；
  - 允许用户再次修改（**5.3**）并在满足条件后 **再次发布**，**无须新建**记录。
- **说明：** 下架**不删除**业务记录与已上传附件，仅变更发布状态与对外可见性。

---

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

便于评审与测试用例编写。

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

**补充：** 从「已发布」下架后，记录回到 **未发布**，操作权限按上表第一行执行。

---

## 7. 错误与提示约定

- 业务与校验错误宜采用项目统一的 **`code`、`msg`、`data`** 结构呈现，便于前端统一处理（不涉及具体协议与路径设计）。
- 常见提示宜可区分，例如：
  - 必填项缺失、字段超长、实施日期区间不合法；
  - 运营图片数量不足或超出上限；
  - 图片 / 视频 / 封面格式不支持、文件大小超限、上传失败；
  - 已发布不可编辑、已发布不可删除须先下架；
  - 发布 / 下架操作失败原因。

---

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

| 类别 | 建议 |
| --- | --- |
| 权限 | 菜单与按钮级权限：新增、编辑、删除、发布、下架、查看等是否分角色 |
| 审计 | 关键操作记操作日志（新增、修改、发布、下架、删除） |
| 安全 | 上传文件类型校验、存储路径不可预测；视频与图片下载 / 预览鉴权 |
| 性能 | 列表查询响应时间满足后台通用体验；多图与视频若后续需直传或分片再扩展 |
| 多端展示 | 与 `ruoyi-ui-app` 等端「共富项目」栏目联动时，仅拉取 **已发布** 数据；下架后前台不再展示 |
| 双语 | 若前台面向藏汉双语用户，展示文案与后台字段标签须与项目 i18n 规范一致（具体范围在 UI 设计阶段确认） |

---

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

| 草稿问题 | 优化处理 |
| --- | --- |
| 第 6 条「已发布的**补贴**」 | 更正为 **已发布的共富项目** |
| 发布 / 下架与改删规则分散 | 增补 **§4 流程概览**、**§5.6 发布与下架**、**§6 操作矩阵**；明确已发布不可改、不可删 |
| 「修改：所有均可修改」与发布状态矛盾 | 明确 **仅未发布可改**；已发布须先下架 |
| 运营视频、封面是否必填未写清 | **运营图片必填（1～3 张）**；**运营视频、封面选填** |
| 项目名称仅写「不超过 20 字」 | 明确为 **1～20** 字符；简介、内容为 **1～50 / 1～500** |
| 实施日期未写先后关系 | 补充结束日期 **≥** 开始日期 |
| 查询条件较简略 | 补充发布状态筛选、默认排序、列表展示建议 |
| 删除 / 替换附件未写清理策略 | 在 **§5.3、§5.4** 明确须联动清理存储文件 |
| 第 7、8 条接口与技术栈 | 错误结构仅保留 **§7** 呈现约定；技术栈移至技术方案文档 |