公开完整前后端的代码

2026-02-26 19:22:38 +08:00
commit 193de8a34f
161 changed files with 17373 additions and 0 deletions
--- a/back/doc/API/newRepairTrace.md
+++ b/back/doc/API/newRepairTrace.md
@@ -0,0 +1,149 @@
+# 添加维修记录 (New Repair Trace) API
+
+- **路径**: `/api/v3/new_repair_trace`
+- **方法**: `POST`
+- **功能**: 网维人员为工单添加处理记录、更新状态或修改其他属性。
+
+## 描述
+
+此接口是网维人员的核心工具，用于记录对报修工单的每一次操作。无论是状态变更（如“改日修”、“已完成”）、优先级调整，还是添加备注，都通过此接口完成。每一次调用都会在工单下生成一条新的追踪记录 (trace)。
+
+## 认证
+
+- **需要 JWT**: 是
+- **权限要求**:
+  - 必须是网维人员 (`operator` 或更高权限) 才能调用此 API。
+  - 只有管理员 (`admin`) 才能修改工单的 `priority` (优先级)。
+
+## 请求
+
+### 请求头
+
+| Header          | 类型   | 描述                      |
+| --------------- | ------ | ------------------------- |
+| `Authorization` | string | `Bearer <your_jwt_token>` |
+| `Content-Type`  | string | 必须是 `application/json` |
+
+### 请求体 (JSON)
+
+| 字段             | 类型     | 描述                                                                 | 校验规则     |
+| ---------------- | -------- | -------------------------------------------------------------------- | ------------ |
+| `tid`            | integer  | 要更新的工单 ID                                                      | `required`   |
+| `remark`         | string   | 本次操作的备注信息，例如                     | `required`   |
+| `new_status`     | string   | 工单的新状态          | (可选)       |
+| `new_priority`   | string   | **(仅管理员)** 工单的新优先级        | (可选)       |
+| `new_appointment`| string   | 新的预约上门日期 (RFC3339 日期格式, 例如: "2025-12-08T00:00:00Z")     | (可选)       |
+| `new_category`   | string   | 新工单类型                                                          | （可选）      |
+
+**请求示例 (更新状态和备注)**:
+
+```json
+{
+  "tid": 123,
+  "remark": "已电话联系用户，指导其重启路由器后网络恢复正常。工单完成。",
+  "new_status": "solved"
+}
+```
+
+**请求示例 (重新安排上门时间)**:
+
+```json
+{
+  "tid": 124,
+  "remark": "用户今天没空，改约明天下午。",
+  "new_status": "scheduled",
+  "new_appointment": "2025-12-08T00:00:00Z"
+}
+```
+
+## 响应
+
+### 成功响应 (200 OK)
+
+| 字段    | 类型    | 描述                 |
+| ------- | ------- | -------------------- |
+| `success` | boolean | `true` 表示操作成功  |
+| `msg`     | string  | 成功的提示信息     |
+
+**响应示例**:
+
+```json
+{
+  "success": true,
+  "msg": "new trace added"
+}
+```
+
+### 失败响应
+
+#### 400 Bad Request (请求错误)
+
+- 请求体绑定失败、格式错误或未通过验证。
+- 当设置了 `new_appointment` 但 `new_status` 不是 `scheduled` 时。
+
+```json
+{
+  "success": false,
+  "msg": "invalid request body: ...",
+  "errType": 2
+}
+```
+
+```json
+{
+  "success": false,
+  "msg": "only appointed status can set appointment time",
+  "errType": 2
+}
+```
+
+#### 400 Bad Request (业务逻辑错误)
+
+| `msg` 内容              | `errType` | 描述                                       |
+| ----------------------- | --------- | ------------------------------------------ |
+|"无法找到对应的工单"       | `logic`   | 提供的 `tid` 对应的工单不存在。            |
+| "无法找到对应的网维成员"       | `logic`   | 操作者（网维人员）信息不存在。             |
+|"您的工单状态更新请求不符合逻辑"| `logic`   | 新状态不符合工单状态流转规则 |
+
+#### 403 Forbidden (权限错误)
+
+- 当非网维人员尝试调用此接口时。
+- 当非管理员尝试修改 `new_priority` 时。
+
+```json
+{
+  "success": false,
+  "msg": "only Network Support staff can access this API",
+  "errType": 3
+}
+```
+
+```json
+{
+  "success": false,
+  "msg": "only admin can change ticket priority",
+  "errType": 3
+}
+```
+
+#### 500 Internal Server Error (服务器内部错误)
+
+当发生未预料到的数据库错误或其他内部错误时返回。
+
+```json
+{
+  "success": false,
+  "msg": "system met a uncaught error,please view logs.",
+  "errType": 1
+}
+```
+
+## 注意事项
+
+- 这是网维人员更新工单的主要方式。
+- `remark` 字段是必填的，用于记录每次操作的内容。
+- 只有在 `new_status` 设置为 `scheduled` 时，才能提供 `new_appointment` 字段。
+- 工单状态的变更必须遵循预定义的逻辑流程。
+- 只有管理员有权限调整工单的优先级。
+- 这个 API 的底层实现是 `logic.AppendTrace`，与 `cancelTicket` API 共享部分逻辑。
+