256 lines
9.9 KiB
Markdown
256 lines
9.9 KiB
Markdown
# OA 审批实例评论（Web 先）设计文档
|
||
|
||
**日期**: 2026-09-20
|
||
**状态**: 已批准
|
||
**关联**: `docs/superpowers/specs/2026-07-14-oa-approval-dingtalk-design.md`（审批意见 ≠ 本能力）
|
||
**交付策略**: Web 管理端先实现 → 同一套 API 再推广到微信小程序 / 移动端
|
||
|
||
---
|
||
|
||
## 1. 目标与范围
|
||
|
||
### 1.1 目标
|
||
|
||
在 OA 审批实例详情中提供独立「讨论评论」能力：参与人可发表文字评论、引用流程表单中已有附件，并可撤回自己的评论。评论**不改变**审批结果、不推进流程。
|
||
|
||
### 1.2 V1 包含（Web）
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| 发表评论 | 纯文字，必填，最长 1024 字 |
|
||
| 引用表单附件 | 从当前实例 `form_data_json` 中 upload 类字段勾选已有文件；存引用快照，不复制对象存储文件 |
|
||
| 撤回自己的评论 | 仅作者；撤回后时间线保留「已撤回」痕迹 |
|
||
| 评论列表 | 详情页独立评论区展示；含正文、引用附件、人、时间 |
|
||
| 状态门禁 | 仅实例 `status=running` 可发表 / 撤回；结束后只读 |
|
||
| 权限 | 与「能打开该实例详情」同一套可见性；租户隔离 |
|
||
|
||
### 1.3 V1 明确不做
|
||
|
||
- 一键通知审批人 / 抄送人 / 参与人
|
||
- @ 某人
|
||
- 快捷回复词、表情面板
|
||
- 评论区**新上传**图片 / 附件（仅引用表单已有附件）
|
||
- 楼中楼回复、编辑已发评论
|
||
- 将讨论评论混入审批进度链（`OaProgressChain`）中的办理意见
|
||
- 本期不交付小程序 UI（接口按双端预留）
|
||
|
||
### 1.4 与「审批意见」的边界（SHALL）
|
||
|
||
| | 审批评论（本能力） | 审批意见（现有） |
|
||
|---|---|---|
|
||
| 存储 | `oa_instance_comment` | `oa_task.comment_text` / `oa_instance_event.comment_text` |
|
||
| 时机 | 详情评论区随时（running） | 同意 / 拒绝 / 打回 / 加签 / 转交 |
|
||
| 是否推进流程 | 否 | 是 |
|
||
| UI | 独立「评论」区块 | 办理弹窗 / 进度链「意见」 |
|
||
|
||
**禁止**把讨论评论写入 `OaTask.comment_text`。
|
||
|
||
---
|
||
|
||
## 2. 方案决策
|
||
|
||
曾对比：独立表 / 复用 `oa_instance_event` / 塞入实例 JSON。
|
||
|
||
**选定：独立表 `oa_instance_comment`。**
|
||
|
||
理由：发表 / 撤回 / 列表语义清晰；Web 与小程序共用同一 API；不污染办理事件模型。
|
||
|
||
---
|
||
|
||
## 3. 数据模型
|
||
|
||
### 3.1 表 `oa_instance_comment`
|
||
|
||
字段顺序：`id` → 业务字段 → 公共字段（`tenant_no` … `del_flag`），与工程 database-conventions 一致。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | VARCHAR(64) PK | UUID |
|
||
| `instance_id` | VARCHAR(64) NOT NULL | 所属 `oa_instance.id` |
|
||
| `content` | VARCHAR(1024) NOT NULL | 评论文本（撤回后仍保留原文，便于审计；前端对 revoked 不展示正文或仅展示占位） |
|
||
| `attachment_refs_json` | TEXT NULL | 引用快照 JSON 数组，见 §3.2 |
|
||
| `status` | VARCHAR(16) NOT NULL | `normal` \| `revoked`，默认 `normal` |
|
||
| `revoked_time` | DATETIME NULL | 撤回时间 |
|
||
| `tenant_no` | … | 公共 |
|
||
| `order_num` | … | 公共 |
|
||
| `remark` | … | 公共 |
|
||
| `create_by` | … | **评论作者 user_id**（与现网一致用 create_by） |
|
||
| `create_dept_id` | … | 公共 |
|
||
| `create_time` | … | 发表时间 |
|
||
| `update_by` / `update_time` | … | 撤回时更新 |
|
||
| `del_flag` | … | 默认 0；列表默认排除硬删；撤回用 `status=revoked`，**不**靠 del_flag 表示撤回 |
|
||
|
||
索引建议：`(tenant_no, instance_id, create_time)`。
|
||
|
||
SQL：新增迁移脚本 `docs/sql/migrations/2026-09-20-oa-instance-comment.sql`，并按仓库惯例评估是否同步全量 `docs/sql/zkxw.sql`。
|
||
|
||
### 3.2 `attachment_refs_json` 结构
|
||
|
||
数组元素：
|
||
|
||
```json
|
||
{
|
||
"fieldKey": "protocolFiles",
|
||
"fieldLabel": "协议附件",
|
||
"url": "https://minio.example/.../xx.pdf",
|
||
"fileName": "协议.pdf"
|
||
}
|
||
```
|
||
|
||
- 发表时服务端根据实例 `form_schema_json` + `form_data_json` 校验：每个 `url` **必须**出现在该实例某一 upload 类字段的当前值中（规范化逻辑对齐 `oa_related_approval._extract_upload_urls`）。
|
||
- 校验失败 → 400，中文错误（如「引用的附件不存在或不属于本表单」）。
|
||
- 快照在发表时刻固化；之后表单数据变更不影响已发表评论中的展示名 / url（若对象存储文件被删导致 404，属存储层问题，本期不处理）。
|
||
|
||
Upload 类字段类型（与现网一致）：`upload` / `fcUpload` / `image` / `oaAttachment`。
|
||
|
||
---
|
||
|
||
## 4. API 设计
|
||
|
||
前缀：现有 `/web/admin/oa-approval`（与 `backend/app/api/oa_approval.py` 一致）。
|
||
|
||
权限：调用方须通过与 `GET /instances/{instance_id}` **相同的实例可见性校验**；所有查询 / 写入强制 `tenant_no` = 当前用户租户。
|
||
|
||
### 4.1 可引用附件列表
|
||
|
||
`GET /instances/{instance_id}/form-attachments`
|
||
|
||
响应概念：
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"fieldKey": "protocolFiles",
|
||
"fieldLabel": "协议附件",
|
||
"files": [
|
||
{ "url": "...", "fileName": "协议.pdf" }
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
无附件时 `items: []`。
|
||
|
||
### 4.2 评论列表
|
||
|
||
`GET /instances/{instance_id}/comments`
|
||
|
||
- 返回该实例全部评论（含 `revoked`），按 `create_time` **升序**。
|
||
- 每条含：`id`、`content`、`attachmentRefs`、`status`、`revokedTime`、`createBy`、`createByName`（若详情已有用户名投影则对齐）、`createTime`、`canRevoke`（当前用户且 status=normal 且实例 running）。
|
||
|
||
另：`GET /instances/{instance_id}` 详情响应 **SHALL** 增加字段 `comments`（结构同列表项数组），Web 首屏少一次请求；独立列表接口供刷新 / 小程序复用。
|
||
|
||
### 4.3 发表评论
|
||
|
||
`POST /instances/{instance_id}/comments`
|
||
|
||
Body：
|
||
|
||
```json
|
||
{
|
||
"content": "请补充第二页签字页",
|
||
"attachmentRefs": [
|
||
{ "fieldKey": "protocolFiles", "url": "...", "fileName": "协议.pdf" }
|
||
]
|
||
}
|
||
```
|
||
|
||
规则：
|
||
|
||
- `content` trim 后非空，长度 ≤ 1024。
|
||
- `attachmentRefs` 可选；有则服务端补全 / 校验 `fieldLabel`，拒绝非法 url。
|
||
- 仅 `oa_instance.status == running`；否则 400「仅审批进行中可评论」。
|
||
- 成功返回新建评论对象（同列表项）。
|
||
|
||
### 4.4 撤回评论
|
||
|
||
`POST /instances/{instance_id}/comments/{comment_id}/revoke`
|
||
|
||
规则：
|
||
|
||
- 评论存在、未删、属于该实例与租户。
|
||
- 仅 `create_by == 当前用户`。
|
||
- 仅 `status == normal`；已撤回 → 幂等成功或 400（实现选一种，建议 **幂等成功**）。
|
||
- 仅实例 `running`；结束后不可撤回。
|
||
- 置 `status=revoked`、`revoked_time=now`，更新 `update_by` / `update_time`。
|
||
- **不**物理删除，**不**清空 `content` / `attachment_refs_json`（审计保留；UI 对 revoked 不展示正文与附件）。
|
||
|
||
---
|
||
|
||
## 5. 后端实现要点
|
||
|
||
| 位置 | 说明 |
|
||
|------|------|
|
||
| `backend/app/models/models.py` | 新增 `OaInstanceComment` |
|
||
| `backend/app/schemas/` | CreateBody / 列表项 Pydantic（camelCase 对外） |
|
||
| `backend/app/crud/` 或 `services/` | 列表、发表校验、撤回；附件枚举可放 `oa_related_approval` 旁或 `oa_instance_comment` 服务模块 |
|
||
| `backend/app/api/oa_approval.py` | 注册上述 4 个路由；详情组装注入 `comments` |
|
||
| 字段一致性 | `_row_to_dict` 为可读字段真相源；CreateBody 与之对齐可写字段 |
|
||
|
||
---
|
||
|
||
## 6. Web 管理端 UI
|
||
|
||
### 6.1 页面
|
||
|
||
- 主入口：`web-admin/src/views/oa-approval/instances/detail.vue`
|
||
- 若存在详情弹窗复用同一详情数据源：`OaInstanceDetailDialog.vue` 等亦需挂载同一面板（与现网详情入口对齐，避免漏入口）。
|
||
|
||
### 6.2 组件
|
||
|
||
新建 `web-admin/src/components/oa-approval/OaCommentPanel.vue`（建议）：
|
||
|
||
1. **列表区**：升序；normal 展示头像/姓名、时间、正文、引用附件芯片（预览/下载对齐现有附件交互）；revoked 展示灰条「{姓名} 撤回了一条评论」+ 撤回时间。
|
||
2. **操作**：本人 + normal + 实例 running → 「撤回」按钮（需确认框）。
|
||
3. **输入区**（仅 running）：`el-input` textarea；「引用附件」打开多选（数据来自 form-attachments）；「发送」。
|
||
4. 按钮带图标（ui-conventions）；遮罩无 blur；文案中文。
|
||
|
||
视觉：Fresh Mint；独立 `section`，**不要**并入 `OaProgressChain`。
|
||
|
||
> **2026-09-21 更新（钉钉对齐）**：展示已改为并入审批进度时间线，见 `docs/superpowers/specs/2026-09-21-oa-comment-in-progress-timeline-design.md`。`OaCommentPanel` 仅保留底部输入；列表/撤回在 `OaProgressChain`（`kind=comment`）。
|
||
|
||
### 6.3 API 模块
|
||
|
||
`web-admin/src/api/oaApproval.ts` 增加对应 fetch 方法。
|
||
|
||
---
|
||
|
||
## 7. 移动端 / 小程序（二期，本期仅约束）
|
||
|
||
- V1 不实现小程序页面。
|
||
- API 不得依赖仅 Web 才有的请求头或 Element 专用结构；响应字段稳定、camelCase。
|
||
- 二期在微信小程序审批详情复用：`form-attachments` / `comments` CRUD；UI 遵循 `docs/miniprogram-ui-spec-sanqiang.md`。
|
||
- 现有 `mobile-oa-h5` 若与小程序并行，二期可择一或双端同接，不在本设计展开。
|
||
|
||
---
|
||
|
||
## 8. 验收标准
|
||
|
||
1. 有详情可见权限的用户，在 running 实例详情可发表非空文字评论。
|
||
2. 可多选引用表单附件；非法 url 被拒绝；评论区可预览/下载引用文件。
|
||
3. 作者可撤回自己的 normal 评论；他人不可撤；撤回后见「已撤回」占位，正文与附件对用户隐藏。
|
||
4. 非 running（completed / rejected / cancelled / returned 等）不可发、不可撤，仍可读历史评论。
|
||
5. 同意/拒绝意见与进度链行为与改前一致。
|
||
6. 租户隔离：不可读写他租户实例评论。
|
||
|
||
---
|
||
|
||
## 9. 非目标与后续
|
||
|
||
- 评论通知、@、新上传附件、楼中楼 → 另开变更。
|
||
- 小程序 UI → V2。
|
||
- 是否把评论摘要打进打印 PDF → 不在 V1。
|
||
|
||
---
|
||
|
||
## 10. 实现顺序建议
|
||
|
||
1. SQL + Model + Schema
|
||
2. 服务：附件枚举、发表校验、撤回、列表
|
||
3. API 路由 + 详情注入 `comments`
|
||
4. 前端 API + `OaCommentPanel` + 挂到详情页
|
||
5. 手工验收（Web）
|
||
6. （可选）`./scripts/update-graph.sh backend` / `frontend`
|