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

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 项目与补贴 — 项目 |
| 目标 | 对补贴类投资项目进行登记、查询、维护与进度状态管理，支撑项目台账与执行进展跟踪 |
| 关联系统 | 业务后台 |
| 修订依据 | 同目录 `项目与补贴-项目-草稿.md` |

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

---

## 2. 术语与枚举

### 2.1 执行状态（单选）

| 取值 | 含义概要 |
| --- | --- |
| **未开始** | 当前日期早于项目开始日期，或尚未进入实施阶段 |
| **进行中** | 已开工且尚未到达预计完成节点（见 **2.2** 自动规则） |
| **已完成** | 项目已完工；选手动「已完成」时须填写实际完成日期 |

### 2.2 状态推算与手工覆盖

**日期基准：** 「当前日期」指用户操作当日（按系统时区，自然日 `YYYY-MM-DD`）。

**自动推算规则（默认，保存/提交时执行）：**

在**未**将执行状态手工固定为「已完成」的前提下，系统按下列**优先级从高到低**判断（当前日期记为 T，开始日为 S，预计完成日为 E）：

| 优先级 | 条件 | 自动执行状态 |
| --- | --- | --- |
| 1 | T < S（今天早于项目开始日） | **未开始** |
| 2 | T = E（今天等于预计完成日） | **已完成** |
| 3 | T < E（今天早于预计完成日，且已满足 T ≥ S） | **进行中** |
| 4 | T > E（今天晚于预计完成日，草稿未单列） | **进行中**（超期未自动置为已完成，须手工确认完成） |

> 与草稿 **§1.1** 对齐：**今天 < 开始日 → 未开始**；**今天 < 预计完成日 → 进行中**（在已过开始日前提下）；**今天 = 预计完成日 → 已完成**。**不等于**「T ≥ E 即已完成」。

**自动变为「已完成」时：** 若按上表推算为 **已完成**（通常为 T = E），且未手工锁定，系统可将 **实际完成日期** 默认设为 **T**（当天），用户亦可事先手工填写。

**手工选择「已完成」：**

- 用户将执行状态**手工选为「已完成」**时，**实际完成日期**为**必填**；格式 `YYYY-MM-DD`。
- 实际完成日期默认不得晚于当前日期（若允许补录未来完成日须单独评审）。
- 手工标记为「已完成」后，再次保存时：若业务约定「已完成不再被自动改回进行中」，则自动推算**不再覆盖**执行状态，仅可人工修改；若允许在改期后重新推算，须在实现前与产品确认（**默认：已完成状态不被自动降级**）。

**提交后自动更新：**

- 新增、修改**保存成功**后，须按上表重新执行状态推算（受「已完成」手工锁定规则约束）。
- 列表进入、定时刷新或打开详情时，宜按同一规则展示**最新**执行状态（避免仅保存时更新、列表长期过期）。

### 2.3 发布状态（与执行状态独立）

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

下架后回到 **未发布**，可再编辑并再次发布，**无须新建**记录。

### 2.4 记录说明

本模块为**项目台账**，单条记录表示一个补贴类投资项目。除 **§2.1 执行状态** 外，另有 **§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.2** 推算执行状态。  
2. **维护**：**未发布** 下可修改；保存后重新推算执行状态。  
3. **发布**：**未发布** 且校验通过 → **已发布**。  
4. **下架**：**已发布** → **未发布**，可再编辑、再发布。  
5. **查询**：按名称/简介、执行状态、发布状态、开始日期范围筛选。  
6. **删除**：仅 **未发布** 可删（须先下架已发布记录）。

---

## 5. 详细功能需求

### 5.1 新增项目

| 字段 | 规则 |
| --- | --- |
| 项目名称 | **必填**；长度 **1～20** 个字符 |
| 项目简介 | **选填**；若有内容，长度不超过 **50 字** |
| 投资金额 | **必填**；须为**大于 0** 的数值；小数位数与项目金额规范一致（建议最多 **2** 位小数） |
| 项目开始日期 | **必填**；格式 `YYYY-MM-DD` |
| 预计完成日期 | **必填**；格式 `YYYY-MM-DD`；须 **≥ 项目开始日期** |
| 封面 | **选填**；**单个**图片上传；允许后缀 `jpg`、`jpeg`、`png`（可扩展 `webp`）；单文件 ≤ **10 MB** |
| 执行状态 | **必填**；单选，取值 **§2.1**；保存时与 **§2.2** 自动规则协同（见下） |
| 实际完成日期 | **条件必填**；当执行状态为 **已完成** 时必填；否则须为空或不提交 |

**保存时状态处理（摘要）：**

1. 校验日期、金额等字段。  
2. 若用户选择 **已完成** → 校验实际完成日期已填。  
3. 若用户**未**手工锁定为「已完成」→ 按 **§2.2** 自动写入执行状态。  
4. 若自动推算为 **已完成**（T = E）且用户未填实际完成日期 → **实际完成日期默认取当天（T）**；若用户已填则以用户值为准（须 ≤ 当天）。

**必填字段汇总：** 项目名称、投资金额、项目开始日期、预计完成日期、执行状态。

---

### 5.2 查询项目列表

- **关键字：** 对「项目名称」或「项目简介」**模糊**匹配（**OR**）；为空则不过滤。  
- **执行状态：** **精确**匹配；未选择则不过滤。  
- **发布状态：** **精确**匹配（未发布 / 已发布）；未选择则不过滤。  
- **项目开始日期范围：** 支持 **开始日期（startDate）**、**结束日期（endDate）** 闭区间筛选（针对「项目开始日期」字段）；仅填其一则按 ≥ / ≤ 处理；均未填则不过滤。  
  - **区间合法性：** 同时填写时 `startDate` ≤ `endDate`，否则提示错误且不查询。  
- **分页：** 默认 **每页 20 条**，首页为第一页。  
- **排序：** 默认按 **项目开始日期倒序**（最近开始在前）；相同则按 **创建时间倒序**。

**列表宜展示：** 项目名称、简介、投资金额、开始/预计完成日、**执行状态**、**发布状态**、发布时间、封面缩略图、实际完成日期（已完成时），及操作列。

---

### 5.3 修改项目

- **可修改项：** 全部字段（同 **5.1**）；**仅发布状态为未发布** 时允许进入修改并保存。  
- **已发布：** 不可修改（须先下架）。  
- **保存约束：** 校验规则与新增一致；保存成功后重新执行 **§2.2** 状态推算。  
- **封面替换：** 更换封面并保存成功后，删除旧封面文件，避免存储残留。  
- **已完成锁定：** 若记录已为「已完成」且产品采用「不自动降级」策略，修改计划日期时仍保持「已完成」，除非用户主动改状态。

---

### 5.4 删除项目

- **允许删除：** 发布状态为 **未发布** 且具备删除权限。  
- **不允许删除：** **已发布** 记录；须先 **下架**（**§5.6**）。  
- **删除后果：** 删除记录同时删除关联封面存储文件。  
- **确认：** 删除前宜二次确认。

---

### 5.5 查看项目详情

- **展示内容：** 项目名称、简介、投资金额、开始/预计完成日、执行状态、实际完成日期、封面、**发布状态**、发布时间、下架时间；宜含审计字段。  
- **状态展示：** 执行状态按 **§2.2** 与列表一致。  
- **交互：** **未发布** 可编辑；**已发布** 只读，可提供下架入口。

---

### 5.6 发布与下架

#### 发布

- **前置：** 当前 **未发布**；必填项满足 **§5.1**。  
- **结果：** 变为 **已发布**；记录发布时间。

#### 下架

- **前置：** 当前 **已发布**。  
- **结果：** 变为 **未发布**；结束对外展示；**不删**记录与封面；可再编辑、再发布。

---

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

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

下架后按「未发布」行权限执行。

---

## 7. 错误与提示约定

- 业务与校验错误采用项目统一 **`code`、`msg`、`data`** 结构。  
- 宜可区分：必填缺失、字段超长、投资金额非法、开始日晚于完成日、封面格式/大小不符、已完成未填实际完成日期、查询日期区间非法、状态与日期矛盾等。

---

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

| 类别 | 建议 |
| --- | --- |
| 权限 | 菜单与按钮：查询、新增、修改、删除、发布、下架、导出（若需要） |
| 审计 | 新增、修改、删除记操作日志 |
| 安全 | 上传封面类型与大小校验；下载/预览鉴权 |
| 性能 | 列表按开始日期、执行状态筛选满足通用体验 |
| 双语 | 字段标签与提示符合项目 i18n（汉语 + 藏文） |

---

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

| 草稿问题 | 优化处理 |
| --- | --- |
| 标题写「新增补贴发放记录」 | 更正为 **新增项目** |
| 查询条件为姓名/补贴类型/发放日期 | 更正为 **项目名称或简介、执行状态、项目开始日期范围** |
| 「修改/删除/查看补贴发放记录宣传」 | 更正为 **项目** |
| 执行状态自动规则表述不清 | 整理为 **§2.2** 优先级表；**T=E→已完成**（非 T≥E）；超期 T>E 默认仍为进行中 |
| 草稿查询条仍为发放记录字段 | 正式需求仍校正为 **项目名称/简介、执行状态、项目开始日范围**（见 §5.2） |
| 提交后自动更新 | 明确保存成功及列表/详情展示时刷新推算 |
| 投资金额、日期先后关系 | 补充金额 >0、预计完成 ≥ 开始 |
| 第 6、7 条技术栈与接口 | 技术栈移除；错误约定保留于 **§7** |
| 草稿 §6 发布/下架 | 新增 **§2.3、§5.6** 与 **§6** 矩阵；已发布不可改删 |
| 「产互」 | 更正为 **删除** |