Project Flow 前端接口对接文档

本文档对应插件目录：

  • plugins/project-flow

当前前端接口实现位置：

当前删除记录模型位置：

路由命名说明

当前项目里的插件前端路由并不统一都走 frontend.controllers...。

project-flow 当前控制器文件位于：

  • plugins/project-flow/src/frontend/ProjectController.php

因此文档按当前项目实际风格，使用以下路由前缀：

  • plugin.project-flow.frontend.project

即：

  • plugin.project-flow.frontend.project.list
  • plugin.project-flow.frontend.project.apply
  • plugin.project-flow.frontend.project.my-applies

如果后续你们在项目里另外注册了 frontend.controllers 风格别名，再单独同步调整这份文档。

统一说明

  • 接口成功返回：
{
  "result": 1,
  "msg": "获取成功",
  "data": {}
}
  • 接口失败返回：
{
  "result": 0,
  "msg": "错误信息"
}
  • 当前文档按“项目管理”页面 4 个板块整理：
    • 项目申请
    • 结项申请
    • 汇总表单
    • 删除记录

状态说明

Apply 主流程状态

状态值 主流程含义 前端展示文案
0 项目申请待审核 待审核
1 项目申请通过，待结项 待结项
2 项目申请驳回 待修改
3 结项申请待审核 待审核
4 结项申请驳回 待修改
5 结项审核通过 已结项

DeleteAudit 删除申请状态

状态值 含义 前端展示文案
0 删除待审核 待审核
1 删除审核通过 已删除
2 删除审核驳回 审核驳回

DeleteAudit 删除申请类型

类型值 含义
1 项目申请删除
2 结项申请删除

1. 项目管理首页

接口

  • 方法：list()
  • 路由：plugin.project-flow.frontend.project.list

用途

  • 顶部会员信息
  • 项目申请说明
  • 结项申请说明
  • 申请模板下载
  • 结项模板下载
  • 首页各按钮数量统计
  • 基金级别列表

返回字段

{
  "member_info": {
    "avatar": "",
    "nickname": "",
    "level_name": ""
  },
  "apply_guide_name": "项目申请使用说明",
  "apply_guide_content": "",
  "settle_guide_name": "结项申请使用说明",
  "settle_guide_content": "",
  "apply_template": {
    "name": "",
    "url": "",
    "full_url": ""
  },
  "settle_template": {
    "name": "",
    "url": "",
    "full_url": ""
  },
  "counts": {
    "pending_apply": 0,
    "rejected_apply": 0,
    "pending_settle": 0,
    "pending_settle_audit": 0,
    "rejected_settle": 0,
    "delete_records": 0
  },
  "actions": {
    "apply": {
      "to_apply": "go_apply",
      "pending_modify": 0,
      "pending_audit": 0
    },
    "settle": {
      "to_apply": 0,
      "pending_modify": 0,
      "pending_audit": 0
    }
  },
  "fund_levels": [
    {
      "id": 1,
      "name": "基金级别A"
    }
  ]
}

前端说明

  • apply_template.full_url 可用于“下载项目申请表”
  • settle_template.full_url 可用于“下载结项申请表”
  • fund_levels 用于申请表/结项表的基金级别选择

2. 提交项目申请

接口

  • 方法：apply()
  • 路由：plugin.project-flow.frontend.project.apply

用途

  • 新增项目申请
  • 项目申请驳回后重新提交

入参

字段 类型 必填 说明
id int 否 重新提交时传申请记录 id，新建可不传
project_name string 是 项目名称
fund_level_id int 是 基金级别 id
fund_level_name string 否 可选，后端会优先使用传入值
city_name string 否 市
district_name string 否 区
street_name string 否 街道
community_name string 否 社区名称
attachments array 是 申请附件数组

规则

  • project_name 不能为空
  • 基金级别不能为空
  • attachments 必填
  • 重新提交仅允许当前申请状态为：
    • 2 项目申请驳回
  • 当前代码里也放开了 4，但前端项目申请不要对结项驳回调用这个接口

3. 项目申请列表

接口

  • 方法：myApplies()
  • 路由：plugin.project-flow.frontend.project.my-applies

入参

字段 类型 必填 说明
type string 是 固定传 apply
status string 否 pending 或 rejected
keyword string 否 项目名称搜索

状态口径

  • status=pending：只返回 0 待审核
  • status=rejected：只返回 2 待修改
  • 不传 status：返回 0 + 2

返回列表字段

字段 说明
id 申请记录 id
project_id 项目 id，当前多为 0
project_name 项目名称
fund_level_name 基金级别
status 主流程状态值
status_name 前端展示状态
created_at 创建时间
reject_reason 项目申请驳回原因
settle_reject_reason 结项驳回原因
can_delete 是否可删除
can_reapply 是否可重新申请
can_submit_settle 是否可提交结项
readonly 是否只读
delete_status 删除状态，普通列表一般为 null

4. 结项申请可选项目

接口

  • 方法：settleOptions()
  • 路由：plugin.project-flow.frontend.project.settle-options

用途

  • “提交结项申请”弹窗里选择项目

入参

字段 类型 必填 说明
keyword string 否 项目名称搜索

规则

  • 只返回当前会员 status = 1 的项目，也就是“待结项”的项目
  • 前端选择项目后，可直接把返回内容回填到结项表单

返回字段

字段 说明
id 申请记录 id
project_name 项目名称
fund_level_id 基金级别 id
fund_level_name 基金级别名称
city_name 市
district_name 区
street_name 街道
community_name 社区名称
apply_time 项目申请时间
status 当前状态
status_name 状态名称

5. 获取申请详情

接口

  • 方法：detail()
  • 路由：plugin.project-flow.frontend.project.detail
  • 方法：applyDetail()
  • 路由：plugin.project-flow.frontend.project.apply-detail

当前这两个接口返回结构相同。

入参

字段 类型 必填 说明
id int 是 申请记录 id

返回字段

字段 说明
id 申请记录 id
project_id 项目 id
project_name 项目名称
fund_level_id 基金级别 id
fund_level_name 基金级别名称
city_name 市
district_name 区
street_name 街道
community_name 社区名称
apply_time 项目申请时间
settle_apply_time 结项申请时间
status 当前状态值
status_name 当前状态名
reject_reason 项目申请驳回原因
settle_reject_reason 结项驳回原因
apply_attachments 项目申请附件
settle_attachments 结项申请附件
can_delete 是否可删除
editable_for_apply 项目申请是否可编辑
editable_for_settle 结项申请是否可编辑
readonly_for_settle 结项申请是否只读查看

前端使用建议

  • 项目申请待修改弹窗：
    • 判断 editable_for_apply = true
  • 结项申请待修改弹窗：
    • 判断 editable_for_settle = true
  • 结项申请待审核详情：
    • 判断 readonly_for_settle = true

6. 提交结项申请

接口

  • 方法：submitSettlement()
  • 路由：plugin.project-flow.frontend.project.submit-settlement

入参

字段 类型 必填 说明
id int 是 申请记录 id
attachments array 是 结项附件
city_name string 否 市
district_name string 否 区
street_name string 否 街道
community_name string 否 社区名称

规则

  • 仅允许以下状态提交结项：
    • 1 待结项
    • 4 结项驳回
  • 提交后状态改为：
    • 3 待结项审核

7. 结项申请列表

接口

  • 方法：myApplies()
  • 路由：plugin.project-flow.frontend.project.my-applies

入参

字段 类型 必填 说明
type string 是 固定传 settle
status string 否 available / pending / rejected
keyword string 否 项目名称搜索

状态口径

  • status=available：只返回 1 待结项
  • status=pending：只返回 3 待结项审核
  • status=rejected：只返回 4 结项驳回
  • 不传 status：返回 1 + 3 + 4

8. 汇总表单

接口

  • 方法：myApplies()
  • 路由：plugin.project-flow.frontend.project.my-applies

入参

字段 类型 必填 说明
type string 是 固定传 summary
summary_type string 是 apply 或 settle
keyword string 否 项目名称搜索

8.1 项目申请 tab

  • summary_type=apply

显示状态

  • 待审核
  • 待修改
  • 待结项
  • 已删除

操作规则

  • 待审核 / 待修改 / 待结项
    • 可以删除，看 can_delete
  • 待修改
    • 可以重新申请，看 can_reapply
  • 待结项
    • 可以提交结项，看 can_submit_settle

8.2 结项申请 tab

  • summary_type=settle

显示状态

  • 待审核
  • 待修改
  • 已结项
  • 已删除

操作规则

  • 待审核 / 待修改
    • 是否可删除看 can_delete
  • 待修改
    • 可重新申请，看 can_reapply
  • 已结项
    • 不可删除

汇总表单显隐规则

  • 用户点击删除后：
    • 项目会立即从汇总表单隐藏
  • 删除记录状态为 待审核 或 已删除：
    • 汇总表单都不显示
  • 只有在删除记录里“取消删除”后：
    • 项目才会重新出现在汇总表单

9. 提交删除申请

接口

  • 方法：applyDelete()
  • 路由：plugin.project-flow.frontend.project.apply-delete

入参

字段 类型 必填 说明
id int 是 申请记录 id

当前已实现规则

  • 允许状态：
    • 0 待审核
    • 1 待结项
    • 2 待修改

删除申请类型判定

  • 当前状态 1：
    • 写入 audit_type = 2，表示结项申请删除
  • 其他允许状态：
    • 写入 audit_type = 1，表示项目申请删除

提交后效果

  • 写入删除审核表 yz_project_flow_delete_audit
  • 当前项目立即从汇总表单隐藏

10. 删除记录列表

接口

  • 方法：deleteRecords()
  • 路由：plugin.project-flow.frontend.project.delete-records

入参

字段 类型 必填 说明
type string 是 apply 或 settle
keyword string 否 项目名称搜索

返回字段

字段 说明
id 删除记录 id
apply_id 关联申请记录 id
project_name 项目名称
fund_level_name 基金级别
status 删除审核状态
status_name 删除状态文案
reject_reason 驳回原因
created_at 提交时间
audit_type 删除类型
audit_type_name 删除类型名称
can_cancel 是否可取消删除
can_reapply 是否可再次提交删除申请

状态口径

  • 0 -> 待审核
  • 1 -> 已删除
  • 2 -> 审核驳回

11. 取消删除申请

接口

  • 方法：cancelDelete()
  • 路由：plugin.project-flow.frontend.project.cancel-delete

入参

字段 类型 必填 说明
id int 是 删除记录 id

规则

  • 仅允许删除记录状态为 0 待审核
  • 成功后会直接删除这条删除记录
  • 原项目重新回到汇总表单

12. 再次提交删除申请

接口

  • 方法：reapplyDelete()
  • 路由：plugin.project-flow.frontend.project.reapply-delete

入参

字段 类型 必填 说明
id int 是 删除记录 id

规则

  • 仅允许删除记录状态为 2 审核驳回
  • 调用后状态重置为 0 待审核
  • 驳回原因清空

13. 当前已知限制

以下是当前代码里已经确认的注意点，前端联调时需要知晓：

  1. applyDelete() 目前只允许删除 status in [0,1,2]

    • 也就是说：
    • 项目申请 tab 的删除已支持
    • 结项申请 tab 如果要删除 3/4 状态，后端还需要再放开

  2. 汇总表单当前是：

    • 先查 Apply 分页
    • 再补已删除记录
    • 再做前端最终展示
      所以 total 与最终页面展示条数理论上可能不完全一致

  3. 项目名称目前优先从：

    • project.title
    • 否则从 apply_data.project_name 提取

  4. 基金级别、地区、街道、社区名称目前主要从 apply_data 读取，不是独立数据库列

14. 建议前端使用方式

项目申请 tab

  • 首页：
    • 调 list()
  • 去申请：
    • 调 apply()
  • 待修改：
    • 调 myApplies(type=apply,status=rejected)
  • 待审核：
    • 调 myApplies(type=apply,status=pending)
  • 点单条卡片：
    • 调 applyDetail() 或 detail()

结项申请 tab

  • 首页：
    • 调 list()
  • 去申请弹窗项目选择：
    • 调 settleOptions()
  • 提交结项：
    • 调 submitSettlement()
  • 待修改：
    • 调 myApplies(type=settle,status=rejected)
  • 待审核：
    • 调 myApplies(type=settle,status=pending)

汇总表单 tab

  • 项目申请：
    • 调 myApplies(type=summary,summary_type=apply)
  • 结项申请：
    • 调 myApplies(type=summary,summary_type=settle)
  • 删除：
    • 调 applyDelete()

删除记录 tab

  • 项目申请删除记录：
    • 调 deleteRecords(type=apply)
  • 结项申请删除记录：
    • 调 deleteRecords(type=settle)
  • 取消删除：
    • 调 cancelDelete()
  • 再次提交：
    • 调 reapplyDelete()