提交项目阻工申诉

根据你提供的项目前端代码（铁塔建设项目申诉管理系统）和后端项目结构（Node.js/MongoDB），我来为你设计一个项目阻工申诉的后端接口。

核心需求回顾：

申诉对象： 针对具体的项目。

申诉类型：

日期范围申诉： 选择一个开始日期和结束日期，在此期间免除考核。

长期申诉： 从项目订单导入时间开始，到指定结束日期，期间全部免除考核（特殊情况，前端逻辑已处理）。

申诉理由： 详细说明阻工原因。

审批流程： 需要管理员和领导审批。

状态管理： 申诉有不同的状态（未申诉、申诉中、审批中、已完成/已驳回）。

接口设计：项目阻工申诉

1. 接口路径 (Endpoint):

HTTP 方法: POST

路径: /api/projects/:projectId/appeals

:projectId 是要申诉的项目的唯一标识符。

2. 请求体 (Request Body):

该接口将接收一个 JSON 对象，包含申诉所需的所有信息。

{
  "appealType": "dateRange", // 或 "longTerm"
  "startDate": "2025-03-01", // 申诉开始日期 (YYYY-MM-DD)
  "endDate": "2025-03-05",   // 申诉结束日期 (YYYY-MM-DD)
  "reason": "由于当地村民阻工，导致项目无法正常施工，具体地点：XX村，阻工方：村民代表李四，阻工原因：土地纠纷。",
  "adminApproverId": "admin123", // 管理员用户ID
  "leaderApproverId": "leader456", // 领导用户ID
  "attachments": [ // 可选：申诉相关的附件，如照片、证明文件等
    {
      "fileName": "阻工照片1.jpg",
      "fileUrl": "https://your-oss-bucket.com/uploads/abc.jpg"
    },
    {
      "fileName": "情况说明.pdf",
      "fileUrl": "https://your-oss-bucket.com/uploads/def.pdf"
    }
  ]
}

字段说明:

appealType (String, 必填): 申诉类型。

"dateRange": 日期范围申诉。

"longTerm": 长期申诉。

startDate (String, 必填): 申诉的开始日期，格式为 YYYY-MM-DD。

endDate (String, 必填): 申诉的结束日期，格式为 YYYY-MM-DD。

reason (String, 必填): 详细的申诉理由。

adminApproverId (String, 必填): 选定的管理员审批人的用户ID。

leaderApproverId (String, 必填): 选定的领导审批人的用户ID。

attachments (Array of Objects, 可选): 附件列表。每个附件包含 fileName 和 fileUrl。fileUrl 应是文件上传服务（如腾讯云COS）返回的URL。

3. 响应体 (Response Body):

成功响应 (HTTP 201 Created):

{
  "code": 0,
  "message": "申诉提交成功",
  "data": {
    "appealId": "appeal789", // 新创建的申诉记录ID
    "projectId": "proj001",
    "appealType": "dateRange",
    "startDate": "2025-03-01",
    "endDate": "2025-03-05",
    "reason": "由于当地村民阻工...",
    "adminApproverId": "admin123",
    "leaderApproverId": "leader456",
    "status": "pending", // 初始状态为“待审批”
    "createdAt": "2025-03-01T10:00:00Z"
    // ... 其他申诉详情
  }
}

错误响应 (HTTP 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error):

{
  "code": 1001, // 错误码，具体定义
  "message": "请求参数无效：开始日期不能早于项目订单导入时间。",
  "details": {
    "field": "startDate",
    "value": "2025-01-01"
  }
}

4. 业务逻辑 (Backend Logic):

认证与授权 (Authentication & Authorization):

验证用户是否已登录。

验证用户是否有权限为该项目提交申诉（例如，是否是项目负责人或相关角色）。

参数校验 (Input Validation):

校验 projectId 是否存在。

校验 appealType 是否为 dateRange 或 longTerm。

校验 startDate 和 endDate 是否为有效的日期格式。

校验 reason 是否为空。

校验 adminApproverId 和 leaderApproverId 是否存在于用户数据库中，并且具有相应的角色。

业务规则校验：

startDate 不能早于项目的 importDate。

endDate 必须晚于 startDate。

如果 appealType 是 longTerm，则 startDate 必须等于项目的 importDate。

检查该项目在所选日期范围内是否已有其他“申诉中”或“已批准”的申诉，避免重复申诉。

数据持久化 (Data Persistence):

在 MongoDB 中创建一个新的 Appeal 文档。

Appeal 文档应包含以下字段：

_id (ObjectId): 申诉ID。

projectId (ObjectId): 关联的项目ID。

projectName (String): 项目名称 (冗余存储，方便查询)。

submitterId (ObjectId): 提交申诉的用户ID。

submitterName (String): 提交人姓名。

appealType (String): 申诉类型 (dateRange / longTerm)。

startDate (Date): 申诉开始日期。

endDate (Date): 申诉结束日期。

reason (String): 申诉理由。

adminApproverId (ObjectId): 管理员审批人ID。

adminApproverName (String): 管理员审批人姓名。

leaderApproverId (ObjectId): 领导审批人ID。

leaderApproverName (String): 领导审批人姓名。

status (String): 申诉状态 (pending, approved, rejected, cancelled)。初始为 pending。

adminApprovalStatus (String): 管理员审批状态 (pending, approved, rejected)。

leaderApprovalStatus (String): 领导审批状态 (pending, approved, rejected)。

adminApprovalDate (Date, Optional): 管理员审批时间。

leaderApprovalDate (Date, Optional): 领导审批时间。

adminApprovalComment (String, Optional): 管理员审批意见。

leaderApprovalComment (String, Optional): 领导审批意见。

attachments (Array of Objects, Optional): 附件列表。

createdAt (Date): 申诉创建时间。

updatedAt (Date): 申诉最后更新时间。

状态更新 (Project Status Update):

更新对应项目的 appealStatus 字段为 1 (申诉中) 和 appealProgress 字段为 33 (申诉提交)。

通知 (Notifications):

向 adminApproverId 和 leaderApproverId 发送通知（例如，站内信、邮件、钉钉消息），告知有新的申诉待审批。

审计日志 (Audit Logging):

记录申诉提交操作到审计日志中，包括操作人、操作时间、项目ID、申诉详情等。

5. 后端文件结构建议 (基于你提供的 src 目录):

src/models/appeal.js: 定义 MongoDB 的 Appeal Schema 和 Model。

src/controller/appeal/api.js: 处理申诉相关的业务逻辑。

src/routes/appeals.js: 定义路由。

src/routes.js: 在主路由文件中引入并使用 appeals 路由。

6. 进一步考虑：

审批流程：

需要额外的接口来处理管理员和领导的审批操作（例如 PUT /api/appeals/:appealId/approve 或 PUT /api/appeals/:appealId/reject）。

审批接口需要验证审批人身份和权限。

审批通过后，可能需要更新项目的考核规则，例如在指定日期范围内免除扣分。

审批状态的流转：pending -> adminApproved -> leaderApproved -> approved 或 rejected。

申诉列表/详情：

GET /api/appeals：获取所有申诉列表（可能需要分页、过滤、排序）。

GET /api/appeals/:appealId：获取单个申诉的详细信息。

文件上传： 前端上传附件时，应先调用一个文件上传接口（例如 POST /api/upload），将文件存储到腾讯云COS等对象存储服务，然后将返回的URL和文件名包含在申诉请求体中。你的 src/utils/txCOS.js 看起来就是用于此目的。

用户管理： 确保 User 模型包含 name 字段和可能的 dingtalkId 字段，以便于审批人选择和通知。

错误处理： 完善错误码和错误消息，提供更友好的提示。

性能优化： 对于频繁查询的字段，考虑添加索引。

这个设计涵盖了前端提交申诉所需的所有信息，并考虑了后端处理的认证、验证、持久化、状态更新和通知等关键环节。

application/json

Body

示例

示例 1已存在

{
    "code": 0,
    "message": "申诉提交成功",
    "data": {
        "appealId": "appeal789",
        "projectId": "proj001",
        "appealType": "dateRange",
        "startDate": "2025-03-01",
        "endDate": "2025-03-05",
        "reason": "由于当地村民阻工...",
        "adminApproverId": "admin123",
        "leaderApproverId": "leader456",
        "status": "pending",
        "createdAt": "2025-03-01T10:00:00Z"
    }
}

提交项目阻工申诉

接口设计：项目阻工申诉

请求参数

请求示例代码

返回响应

提交项目阻工申诉

接口设计：项目阻工申诉#

请求参数

请求示例代码

返回响应

接口设计：项目阻工申诉