71 lines
6.1 KiB
Markdown
71 lines
6.1 KiB
Markdown
# 项目管理模块全栈重建 Spec
|
||
|
||
## Why
|
||
|
||
项目管理模块（勘察派单/方案/合同/安装/验收/回访）后端代码已存在但前端页面未按系统设计稿实现，安装派单（install_order）全栈缺失；同时需要系统性补齐接口鉴权、SQL 注入防护、前端 XSS 防护与操作日志，并保证同一套 API 可被 APP 直接复用。
|
||
|
||
## What Changes
|
||
|
||
- **前端重建**：按设计稿重建勘察台账页（参考 `系统设计/UI/项目勘察台帐/code.html`）与勘察派单页（参考 `系统设计/UI/项目勘察派单/code.html`）；方案/合同/验收/安装/回访页按客户拜访管理台账（`client/src/views/customer/visit/index.vue`）的交互与样式体系重建。
|
||
- **安装派单全栈新增**：install_order 的 entity / dto / service / controller / 前端台账页 / API / 路由，功能深度为台账式完整 CRUD + 状态流转（0已派发 → 1已完成）。
|
||
- **安全加固**：
|
||
- 接口鉴权补全：项目管理所有接口统一走 JWT 认证 + RBAC 权限点（复用现有 `RbacMiddleware`，按 path 匹配 permission code）。
|
||
- SQL 注入防护审查：全部查询走 Sequelize 参数化，禁止字符串拼接 SQL；DTO 层用 class-validator 全量校验入参。
|
||
- 前端 XSS 防护：用户输入的备注/说明/意见等文本字段渲染时禁止 `v-html`，统一文本插值；富文本场景如需 HTML 必须经白名单消毒。
|
||
- 操作日志埋点：创建/更新/删除/指派/状态流转/取消/复核等关键动作写入 `sys_operation_log`。
|
||
- **APP 兼容**：不新增命名空间，Web 与 APP 共用现有 `/api/project-*` 系列接口；统一响应结构 `{ code, message, data }`，分页结构统一为 `{ list, total, page, pageSize }`；字段命名与时间格式（ISO 8601）保持稳定。
|
||
|
||
## Impact
|
||
|
||
- Affected specs: 项目管理（新建）、系统安全（加固）
|
||
- Affected code:
|
||
- server：`src/entity/install_order.entity.ts`（新增）、`src/dto/install_order.dto.ts`（新增）、`src/service/install_order.service.ts`（新增）、`src/controller/install_order.controller.ts`（新增）、既有 project_plan / contract / survey_order / acceptance / visit_record 的 controller/service（安全审查与日志埋点）
|
||
- client：`src/views/project/**`（全部重建）、`src/api/installOrder.ts`（新增）、`src/router/index.ts`（补安装派单路由）、`src/layouts/index.vue`（菜单补项）
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: 安装派单管理（install_order 全栈）
|
||
系统 SHALL 提供安装派单的台账式完整 CRUD 与状态流转：列表分页筛选（关键字/客户/状态/派单日期范围）、新建、编辑、详情、删除、标记完成。单号自动生成（格式与勘察单号规则一致，如 `WH-INST-YYYY-NNNN`）。
|
||
|
||
#### Scenario: 创建安装派单
|
||
- **WHEN** 授权用户提交合法派单表单（customerId、planId、installer、dispatchDate 必填）
|
||
- **THEN** 系统生成唯一 install_no，状态为 0（已派发），写入操作日志，返回统一成功响应
|
||
|
||
#### Scenario: 状态流转
|
||
- **WHEN** 授权用户对已派发工单执行「标记完成」
|
||
- **THEN** 状态从 0 流转为 1，记录完成时间，写入操作日志；已完成工单禁止再次流转
|
||
|
||
### Requirement: 勘察台账页按设计稿重建
|
||
系统 SHALL 按 `系统设计/UI/项目勘察台帐/code.html` 重建勘察台账页：统计卡片（待指派/勘察中等待复核/已归档）、状态筛选 Tab、高级筛选（优先级/业务员/电工/时间窗口）、列表列（工单编号+优先级、关联客户与项目、空间位置、测绘回路规格、责任业务员、指派电工、期望时效/SLA、预估劳务费、状态、操作）、批量指派、催办、智能派单入口。
|
||
|
||
#### Scenario: 台账筛选
|
||
- **WHEN** 用户组合使用状态 Tab 与高级筛选条件
|
||
- **THEN** 列表与统计卡片按筛选结果刷新，分页保持统一响应结构
|
||
|
||
### Requirement: 勘察派单页按设计稿重建
|
||
系统 SHALL 按 `系统设计/UI/项目勘察派单/code.html` 重建派单表单页：关联客户选择、任务标题、空间位置、回路规格/数量、优先级（特急P1/加急P2/常规P3）、计划到场窗口、SLA、预估劳务费自动报价（复用 `/api/survey-orders/quote`）、指派电工、草稿保存与正式派发。
|
||
|
||
### Requirement: 方案/合同/验收/回访页重建
|
||
系统 SHALL 按客户拜访台账的交互体系（筛选区 + 表格 + 分页 + 新建/编辑弹窗或表单页 + 状态标签）重建项目方案（含设备明细）、合同（含金额/支付周期/合同文件）、项目验收（含验收意见/文件）、回访记录四个台账页。
|
||
|
||
### Requirement: 接口鉴权补全
|
||
系统 SHALL 保证 `/api/survey-orders`、`/api/project-plans`、`/api/contracts`、`/api/install-orders`、`/api/acceptances`、`/api/visit-records` 全部端点强制 JWT 认证并校验对应 RBAC 权限点（`project:survey`、`project:plan`、`project:contract`、`project:install`、`project:acceptance`、`project:visit`）。
|
||
|
||
#### Scenario: 未认证访问被拒
|
||
- **WHEN** 请求未携带有效 JWT
|
||
- **THEN** 返回 401 统一错误结构；无权限点返回 403
|
||
|
||
### Requirement: SQL 注入防护审查
|
||
系统 SHALL 保证项目管理模块所有数据库访问经由 Sequelize 参数化；关键字模糊搜索使用绑定参数的 `Op.like`，排序字段白名单校验，禁止任何字符串拼接 SQL。
|
||
|
||
### Requirement: 前端 XSS 防护
|
||
系统 SHALL 禁止对后端返回的用户输入文本使用 `v-html`；表格/详情中的备注、说明、意见字段使用文本插值渲染。
|
||
|
||
### Requirement: 操作日志埋点
|
||
系统 SHALL 在创建/更新/删除/指派/批量指派/状态流转/取消/复核/催办动作中写入 `sys_operation_log`（操作人、动作、目标单号、摘要）。
|
||
|
||
## MODIFIED Requirements
|
||
|
||
### Requirement: 统一响应结构（APP 兼容）
|
||
项目管理全部接口 SHALL 返回 `{ code, message, data }`；列表 data 统一为 `{ list, total, page, pageSize }`；时间字段序列化为 ISO 8601 字符串；错误码语义稳定（401 未认证 / 403 无权限 / 422 参数校验失败 / 500 服务器错误），供 APP 端直接消费。
|