西藏巴青项目

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

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. 业务流程概览

flowchart LR
    A[新增项目] --> B[保存并推算状态]
    B --> C[列表查询/筛选]
    C --> D[查看详情]
    C --> E[修改项目]
    C --> F[删除项目]
    E --> B
    F --> C
    B --> G[发布]
    G --> H[已发布]
    H --> I[下架]
    I --> B

新建：录入必填项与封面（可选）→ 初始 未发布；保存后按 §2.2 推算执行状态。
维护：未发布 下可修改；保存后重新推算执行状态。
发布：未发布 且校验通过 → 已发布。
下架：已发布 → 未发布，可再编辑、再发布。
查询：按名称/简介、执行状态、发布状态、开始日期范围筛选。
删除：仅 未发布 可删（须先下架已发布记录）。

5. 详细功能需求

5.1 新增项目

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

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

校验日期、金额等字段。
若用户选择 已完成 → 校验实际完成日期已填。
若用户未手工锁定为「已完成」→ 按 §2.2 自动写入执行状态。
若自动推算为 已完成（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 矩阵；已发布不可改删
「产互」	更正为删除

项目与补贴-项目功能需求.md 11KB Histórico Raw