共同富裕项目功能需求.md 12KB
共同富裕项目 — 功能需求
1. 文档说明
| 项 | 说明 |
|---|---|
| 模块名称 | 共同富裕项目 |
| 目标 | 对共富类项目进行录入、查询、维护与发布管理，支撑面向使用方的项目展示与查阅 |
| 关联系统 | 业务后台；移动端「养殖资讯」等渠道可按产品约定展示已发布项目（见 §8） |
| 修订依据 | 同目录 共同富裕项目-草稿.md |
本文档仅描述功能需求与业务规则，不涉及库表结构、接口路径、请求体字段命名及技术栈选型。
2. 术语与状态
2.1 项目类型（枚举，单选）
- 合作共赢
- 农文旅融合
- 认养农业
2.2 发布状态（互斥，单值）
| 取值 | 含义概要 |
|---|---|
| 未发布 | 新建草稿或已下架回流；对外不可见（与产品「前台 / App 展示」定义一致）；在满足矩阵规则下可编辑、可删除、可发布 |
| 已发布 | 对外可见或可检索（与产品定义一致）；不允许修改；不允许直接删除，须先执行 下架 |
下架回流： 对已发布项目执行「下架」后，发布状态回到 未发布，允许再次编辑并在校验通过后 再次发布，无须新建一条记录。
2.3 实施周期说明
「实施日期」由 开始日期、结束日期 两个自然日字段组成，表示项目计划实施的时间区间；校验规则见 §5.1。
3. 功能范围
- 共富项目的新增、修改、删除、分页列表查询、详情查看
- 运营图片（多张）、运营视频、封面等附件的上传、替换、展示及删除时的存储联动清理
- 发布、下架及发布状态约束下的操作权限控制
- 按项目名称、项目类型、发布状态等条件的组合查询
- 面向使用方的业务错误与校验提示（见第 7 章）
4. 业务流程概览
下列顺序描述典型闭环；具体操作禁忌以 第 6 节矩阵 为准。
- 新建：录入必填项，上传运营图片及可选的视频、封面 → 初始为 未发布。
- 维护：在 未发布 下可反复修改字段与附件，直至内容定稿。
- 发布：在 未发布 且满足发布前置校验时执行「发布」→ 已发布。
- 对外展示：已发布 项目按产品约定在后台列表、移动端「共富项目」等渠道展示；后台详情为只读维护视角。
- 下架：在 已发布 下执行「下架」→ 回到 未发布，结束对外展示。
- 再编辑 / 再发布：下架后可修改并再次发布（重复步骤 2～3）。
- 删除：仅在 未发布 下允许删除整条记录及关联附件；已发布 须先下架。
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 呈现约定；技术栈移至技术方案文档 |