smart_grid_iot/.trae/specs/rebuild-project-management/spec.md

项目管理模块全栈重建 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 端直接消费。