# OA 审批实例评论 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在 OA 审批详情提供独立评论区：文字评论、引用表单附件、本人撤回；Web 管理端先交付，API 可供小程序复用。

**Architecture:** 新建 `oa_instance_comment` 表与服务模块 `oa_instance_comment.py`（附件枚举/校验复用 `oa_related_approval` 的 upload 遍历能力）；API 挂在 `/web/admin/oa-approval`；详情 `get_instance_detail` 注入 `comments`；前端抽 `OaCommentPanel.vue` 挂到详情页与只读详情弹窗。不改动审批意见 / 进度链。

**Tech Stack:** FastAPI · SQLAlchemy · pytest/unittest · Vue 3 · Element Plus · MinIO 既有 URL（仅引用）

**Spec:** `docs/superpowers/specs/2026-09-20-oa-instance-comment-design.md`

---

## File map

| Path | Responsibility |
|------|----------------|
| Create: `docs/sql/migrations/2026-09-20-oa-instance-comment.sql` | 建表 DDL |
| Modify: `backend/app/models/models.py` | 在 `OaInstanceEvent` 后新增 `OaInstanceComment` |
| Create: `backend/app/services/oa_instance_comment.py` | 附件枚举、校验、列表/发表/撤回、`_comment_to_dict` |
| Create: `backend/tests/test_oa_instance_comment.py` | 纯函数 + SQLite 集成测 |
| Modify: `backend/app/services/oa_engine.py` | `get_instance_detail` 注入 `comments` |
| Modify: `backend/app/api/oa_approval.py` | Body + 4 个路由 |
| Modify: `web-admin/src/api/oaApproval.ts` | 类型 + fetch 方法 |
| Create: `web-admin/src/components/oa-approval/OaCommentPanel.vue` | 评论 UI |
| Modify: `web-admin/src/views/oa-approval/instances/detail.vue` | 挂载评论区 |
| Modify: `web-admin/src/components/oa-approval/OaInstanceDetailDialog.vue` | 挂载评论区（只读关联详情也要能看；running 时可评） |

**Locked rules (from spec):**

- 评论 ≠ 审批意见；禁止写 `OaTask.comment_text`。
- 仅 `status=running` 可发/可撤；结束后只读。
- 撤回：`status=revoked`，保留 content（审计）；UI 对 revoked 不展示正文与附件。
- 撤回幂等：已撤回再撤 → 成功返回当前行。
- 无通知、无 @、无评论新上传。
- 可见性与现网详情一致：同租户 + 实例存在（`_get_instance`）。

---

### Task 1: SQL + Model

**Files:**
- Create: `docs/sql/migrations/2026-09-20-oa-instance-comment.sql`
- Modify: `backend/app/models/models.py`（在 `OaInstanceEvent` 类之后、`OaRelation` 之前插入）

- [ ] **Step 1: 写迁移 SQL**

```sql
-- OA 审批实例评论
CREATE TABLE IF NOT EXISTS `oa_instance_comment` (
  `id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '主键ID',
  `instance_id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '所属实例ID',
  `content` varchar(1024) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '评论正文',
  `attachment_refs_json` text COLLATE utf8mb4_unicode_ci COMMENT '引用表单附件快照 JSON',
  `status` varchar(16) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT 'normal' COMMENT 'normal/revoked',
  `revoked_time` datetime DEFAULT NULL COMMENT '撤回时间',
  `tenant_no` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT 'zkxw' COMMENT '租户编号',
  `order_num` int(11) DEFAULT NULL COMMENT '排序号',
  `remark` varchar(512) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '备注',
  `create_by` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '创建人id（评论作者）',
  `create_dept_id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '创建人部门ID',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_by` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '更新人id',
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `del_flag` smallint(6) NOT NULL DEFAULT '0' COMMENT '删除标记',
  PRIMARY KEY (`id`),
  KEY `idx_oa_comment_tenant_inst_time` (`tenant_no`,`instance_id`,`create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='OA审批实例评论';
```

- [ ] **Step 2: 新增 SQLAlchemy 模型**

在 `OaInstanceEvent` 与 `OaRelation` 之间插入：

```python
class OaInstanceComment(Base):
    """OA审批实例评论 oa_instance_comment"""

    __tablename__ = "oa_instance_comment"

    id = Column(String(64), primary_key=True, comment="主键ID")
    instance_id = Column(String(64), nullable=False, comment="所属实例ID")
    content = Column(String(1024), nullable=False, comment="评论正文")
    attachment_refs_json = Column(Text, nullable=True, comment="引用表单附件快照 JSON")
    status = Column(String(16), nullable=False, default="normal", comment="normal/revoked")
    revoked_time = Column(DateTime, nullable=True, comment="撤回时间")
    tenant_no = Column(String(64), nullable=False, default="zkxw", comment="租户编号")
    order_num = Column(Integer, nullable=True, comment="排序号")
    remark = Column(String(512), nullable=True, comment="备注")
    create_by = Column(String(64), nullable=True, comment="创建人id（评论作者）")
    create_dept_id = Column(String(64), nullable=False, default="", comment="创建人部门ID")
    create_time = Column(DateTime, nullable=False, default=datetime.now, comment="创建时间")
    update_by = Column(String(64), nullable=True, comment="更新人id")
    update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now, comment="更新时间")
    del_flag = Column(SmallInteger, nullable=False, default=0, comment="删除标记")
```

确认文件顶部已 import `Text`（`OaInstance` 已用，应已有）。

- [ ] **Step 3: Commit**

```bash
git add docs/sql/migrations/2026-09-20-oa-instance-comment.sql backend/app/models/models.py
git commit -m "$(cat <<'EOF'
feat(oa): add oa_instance_comment table and model

EOF
)"
```

---

### Task 2: 附件枚举与引用校验（纯函数 TDD）

**Files:**
- Create: `backend/app/services/oa_instance_comment.py`
- Create: `backend/tests/test_oa_instance_comment.py`

- [ ] **Step 1: 写失败/行为测试（先写测）**

```python
"""OA 实例评论：附件枚举与引用校验"""
import unittest

from app.services.oa_instance_comment import (
    enumerate_form_attachments,
    normalize_attachment_refs,
)


class TestEnumerateFormAttachments(unittest.TestCase):
    def test_groups_upload_fields(self):
        schema = {
            "rule": [
                {
                    "type": "upload",
                    "field": "files",
                    "title": "附件",
                },
                {"type": "input", "field": "name", "title": "名称"},
            ]
        }
        form = {
            "files": [
                {"url": "https://x/a.pdf", "name": "a.pdf"},
                {"url": "https://x/b.pdf", "name": "b.pdf"},
            ],
            "name": "demo",
        }
        items = enumerate_form_attachments(schema, form)
        self.assertEqual(len(items), 1)
        self.assertEqual(items[0]["fieldKey"], "files")
        self.assertEqual(items[0]["fieldLabel"], "附件")
        self.assertEqual(len(items[0]["files"]), 2)
        self.assertEqual(items[0]["files"][0]["fileName"], "a.pdf")

    def test_skips_empty_upload(self):
        schema = {"rule": [{"type": "fcUpload", "field": "f", "title": "F"}]}
        self.assertEqual(enumerate_form_attachments(schema, {"f": []}), [])


class TestNormalizeAttachmentRefs(unittest.TestCase):
    def test_accepts_valid_ref(self):
        schema = {"rule": [{"type": "upload", "field": "files", "title": "附件"}]}
        form = {"files": [{"url": "https://x/a.pdf", "name": "a.pdf"}]}
        out = normalize_attachment_refs(
            schema,
            form,
            [{"fieldKey": "files", "url": "https://x/a.pdf", "fileName": "wrong"}],
        )
        self.assertEqual(out[0]["fileName"], "a.pdf")
        self.assertEqual(out[0]["fieldLabel"], "附件")

    def test_rejects_foreign_url(self):
        from app.services.oa_engine import OaEngineError

        schema = {"rule": [{"type": "upload", "field": "files", "title": "附件"}]}
        form = {"files": [{"url": "https://x/a.pdf", "name": "a.pdf"}]}
        with self.assertRaises(OaEngineError):
            normalize_attachment_refs(
                schema,
                form,
                [{"fieldKey": "files", "url": "https://evil/x.pdf"}],
            )
```

- [ ] **Step 2: Run 确认失败**

```bash
cd backend && source venv/bin/activate && pytest tests/test_oa_instance_comment.py -v
```

Expected: FAIL（模块不存在）

- [ ] **Step 3: 实现纯函数**

创建 `backend/app/services/oa_instance_comment.py`：

```python
"""OA 审批实例评论：附件枚举、校验、CRUD"""
from __future__ import annotations

import json
from datetime import datetime
from typing import Any, Dict, List, Optional

from sqlalchemy.orm import Session

from app.core.utils import generate_uuid
from app.models.models import OaAppVersion, OaInstance, OaInstanceComment
from app.services.oa_engine import OaEngineError, _get_instance, _loads, _user_name_map
from app.services.oa_related_approval import (
    UPLOAD_TYPES,
    _extract_upload_urls,
    _schema_rules,
    _upload_display_name,
)

CONTENT_MAX = 1024


def enumerate_form_attachments(
    schema: Any, form_data: Optional[Dict[str, Any]]
) -> List[Dict[str, Any]]:
    data = form_data or {}
    items: List[Dict[str, Any]] = []
    for rule in _schema_rules(schema):
        t = str(rule.get("type") or "")
        if t not in UPLOAD_TYPES:
            continue
        field = str(rule.get("field") or rule.get("name") or "").strip()
        if not field:
            continue
        label = str(rule.get("title") or rule.get("label") or field).strip() or field
        raw = data.get(field)
        files: List[Dict[str, str]] = []
        if isinstance(raw, list):
            for it in raw:
                urls = _extract_upload_urls(it if not isinstance(it, list) else it)
                # prefer per-item
                if isinstance(it, dict):
                    u = (_extract_upload_urls(it) or [""])[0]
                    if not u:
                        continue
                    files.append(
                        {
                            "url": u,
                            "fileName": _upload_display_name(it, u),
                        }
                    )
                else:
                    for u in _extract_upload_urls(it):
                        files.append({"url": u, "fileName": _upload_display_name(it, u)})
        else:
            for u in _extract_upload_urls(raw):
                files.append({"url": u, "fileName": _upload_display_name(raw, u)})
        if not files:
            continue
        items.append({"fieldKey": field, "fieldLabel": label, "files": files})
    return items


def _allowed_url_index(
    schema: Any, form_data: Optional[Dict[str, Any]]
) -> Dict[str, Dict[str, str]]:
    """url -> {fieldKey, fieldLabel, fileName}"""
    index: Dict[str, Dict[str, str]] = {}
    for group in enumerate_form_attachments(schema, form_data):
        for f in group["files"]:
            u = str(f.get("url") or "").strip()
            if not u:
                continue
            index[u] = {
                "fieldKey": group["fieldKey"],
                "fieldLabel": group["fieldLabel"],
                "fileName": str(f.get("fileName") or "").strip() or u,
            }
    return index


def normalize_attachment_refs(
    schema: Any,
    form_data: Optional[Dict[str, Any]],
    refs: Optional[List[Dict[str, Any]]],
) -> List[Dict[str, str]]:
    if not refs:
        return []
    if not isinstance(refs, list):
        raise OaEngineError("attachmentRefs 格式无效")
    index = _allowed_url_index(schema, form_data)
    out: List[Dict[str, str]] = []
    seen = set()
    for raw in refs:
        if not isinstance(raw, dict):
            raise OaEngineError("引用的附件不存在或不属于本表单")
        url = str(raw.get("url") or "").strip()
        if not url or url not in index:
            raise OaEngineError("引用的附件不存在或不属于本表单")
        if url in seen:
            continue
        seen.add(url)
        meta = index[url]
        out.append(
            {
                "fieldKey": meta["fieldKey"],
                "fieldLabel": meta["fieldLabel"],
                "url": url,
                "fileName": meta["fileName"],
            }
        )
    return out
```

（CRUD 函数在 Task 3 追加；本任务先保证上述纯函数可测。）

- [ ] **Step 4: Run 确认通过**

```bash
cd backend && source venv/bin/activate && pytest tests/test_oa_instance_comment.py::TestEnumerateFormAttachments tests/test_oa_instance_comment.py::TestNormalizeAttachmentRefs -v
```

Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add backend/app/services/oa_instance_comment.py backend/tests/test_oa_instance_comment.py
git commit -m "$(cat <<'EOF'
feat(oa): enumerate and validate comment form attachment refs

EOF
)"
```

---

### Task 3: 评论 CRUD 服务 + 集成测

**Files:**
- Modify: `backend/app/services/oa_instance_comment.py`
- Modify: `backend/tests/test_oa_instance_comment.py`

- [ ] **Step 1: 追加集成测试**

在同测试文件追加（对齐 `TestTransferTask` 的内存 SQLite 风格）：

```python
class TestCommentCrud(unittest.TestCase):
    def setUp(self):
        from sqlalchemy import create_engine
        from sqlalchemy.orm import sessionmaker
        from app.models.models import OaAppVersion, OaInstance, OaInstanceComment, SysUser

        self.engine = create_engine("sqlite:///:memory:")
        OaAppVersion.__table__.create(self.engine)
        OaInstance.__table__.create(self.engine)
        OaInstanceComment.__table__.create(self.engine)
        SysUser.__table__.create(self.engine)
        Session = sessionmaker(bind=self.engine, autoflush=False, autocommit=False)
        self.db = Session()
        now = datetime.now()
        schema = {
            "rule": [
                {"type": "upload", "field": "files", "title": "附件"},
            ]
        }
        self.db.add(
            OaAppVersion(
                id="v1",
                app_id="app1",
                version_no=1,
                status="published",
                is_latest_published="1",
                form_schema_json=json.dumps(schema, ensure_ascii=False),
                flow_tree_json="{}",
                advanced_settings_json="{}",
                tenant_no="zkxw",
                create_dept_id="",
                create_time=now,
                update_time=now,
                del_flag=0,
            )
        )
        self.db.add(
            OaInstance(
                id="i1",
                app_id="app1",
                app_version_id="v1",
                title="t",
                status="running",
                initiator_user_id="u0",
                initiator_dept_id="d1",
                form_data_json=json.dumps(
                    {"files": [{"url": "https://x/a.pdf", "name": "a.pdf"}]},
                    ensure_ascii=False,
                ),
                tenant_no="zkxw",
                create_dept_id="d1",
                create_time=now,
                update_time=now,
                del_flag=0,
                current_round=1,
            )
        )
        self.db.add(
            SysUser(
                id="u1",
                tenant_no="zkxw",
                user_no="u1",
                nick_name="张三",
                status="1",
                del_flag=0,
                create_time=now,
                update_time=now,
            )
        )
        self.db.commit()

    def test_create_list_revoke(self):
        from app.services import oa_instance_comment as svc

        row = svc.create_comment(
            self.db,
            instance_id="i1",
            tenant_no="zkxw",
            user_id="u1",
            dept_id="d1",
            content="请看附件",
            attachment_refs=[{"fieldKey": "files", "url": "https://x/a.pdf"}],
        )
        self.assertEqual(row["status"], "normal")
        self.assertTrue(row["canRevoke"])
        self.assertEqual(len(row["attachmentRefs"]), 1)

        listed = svc.list_comments(
            self.db, instance_id="i1", tenant_no="zkxw", viewer_user_id="u1"
        )
        self.assertEqual(len(listed), 1)

        revoked = svc.revoke_comment(
            self.db,
            instance_id="i1",
            comment_id=row["id"],
            tenant_no="zkxw",
            user_id="u1",
        )
        self.assertEqual(revoked["status"], "revoked")
        self.assertFalse(revoked["canRevoke"])

        # 幂等
        again = svc.revoke_comment(
            self.db,
            instance_id="i1",
            comment_id=row["id"],
            tenant_no="zkxw",
            user_id="u1",
        )
        self.assertEqual(again["status"], "revoked")

    def test_cannot_comment_when_not_running(self):
        from app.services import oa_instance_comment as svc
        from app.services.oa_engine import OaEngineError
        from app.models.models import OaInstance

        inst = self.db.query(OaInstance).filter(OaInstance.id == "i1").one()
        inst.status = "completed"
        self.db.commit()
        with self.assertRaises(OaEngineError):
            svc.create_comment(
                self.db,
                instance_id="i1",
                tenant_no="zkxw",
                user_id="u1",
                dept_id="d1",
                content="x",
                attachment_refs=None,
            )
```

文件顶部补：`import json`、`from datetime import datetime`。

- [ ] **Step 2: Run 确认失败**

```bash
cd backend && source venv/bin/activate && pytest tests/test_oa_instance_comment.py::TestCommentCrud -v
```

Expected: FAIL（缺 create_comment 等）

- [ ] **Step 3: 实现 CRUD**

在 `oa_instance_comment.py` 追加：

```python
def _fmt_time(dt: Optional[datetime]) -> str:
    return dt.strftime("%Y-%m-%d %H:%M:%S") if dt else ""


def _comment_to_dict(
    row: OaInstanceComment,
    *,
    name_map: Dict[str, str],
    viewer_user_id: str,
    instance_status: str,
) -> Dict[str, Any]:
    refs = _loads(row.attachment_refs_json, [])
    if not isinstance(refs, list):
        refs = []
    status = (row.status or "normal").strip() or "normal"
    can_revoke = (
        status == "normal"
        and instance_status == "running"
        and (row.create_by or "") == (viewer_user_id or "")
    )
    return {
        "id": row.id,
        "instanceId": row.instance_id,
        "content": row.content or "",
        "attachmentRefs": refs,
        "status": status,
        "revokedTime": _fmt_time(row.revoked_time),
        "createBy": row.create_by or "",
        "createByName": name_map.get(row.create_by or "", row.create_by or ""),
        "createTime": _fmt_time(row.create_time),
        "canRevoke": can_revoke,
    }


def _load_version_schema(db: Session, inst: OaInstance) -> Any:
    ver = (
        db.query(OaAppVersion)
        .filter(OaAppVersion.id == inst.app_version_id, OaAppVersion.del_flag == 0)
        .first()
    )
    if not ver:
        return {}
    return _loads(ver.form_schema_json, {})


def list_comments(
    db: Session,
    *,
    instance_id: str,
    tenant_no: str,
    viewer_user_id: str,
) -> List[Dict[str, Any]]:
    inst = _get_instance(db, instance_id, tenant_no)
    rows = (
        db.query(OaInstanceComment)
        .filter(
            OaInstanceComment.instance_id == instance_id,
            OaInstanceComment.tenant_no == tenant_no,
            OaInstanceComment.del_flag == 0,
        )
        .order_by(OaInstanceComment.create_time.asc())
        .all()
    )
    name_map = _user_name_map(db, [r.create_by for r in rows if r.create_by])
    return [
        _comment_to_dict(
            r,
            name_map=name_map,
            viewer_user_id=viewer_user_id,
            instance_status=inst.status or "",
        )
        for r in rows
    ]


def list_form_attachments(
    db: Session, *, instance_id: str, tenant_no: str
) -> List[Dict[str, Any]]:
    inst = _get_instance(db, instance_id, tenant_no)
    schema = _load_version_schema(db, inst)
    form = _loads(inst.form_data_json, {})
    if not isinstance(form, dict):
        form = {}
    return enumerate_form_attachments(schema, form)


def create_comment(
    db: Session,
    *,
    instance_id: str,
    tenant_no: str,
    user_id: str,
    dept_id: str,
    content: str,
    attachment_refs: Optional[List[Dict[str, Any]]],
) -> Dict[str, Any]:
    inst = _get_instance(db, instance_id, tenant_no)
    if (inst.status or "") != "running":
        raise OaEngineError("仅审批进行中可评论")
    text = (content or "").strip()
    if not text:
        raise OaEngineError("评论内容不能为空")
    if len(text) > CONTENT_MAX:
        raise OaEngineError(f"评论内容不能超过{CONTENT_MAX}字")
    schema = _load_version_schema(db, inst)
    form = _loads(inst.form_data_json, {})
    if not isinstance(form, dict):
        form = {}
    refs = normalize_attachment_refs(schema, form, attachment_refs)
    now = datetime.now()
    row = OaInstanceComment(
        id=generate_uuid(),
        instance_id=instance_id,
        content=text,
        attachment_refs_json=json.dumps(refs, ensure_ascii=False) if refs else None,
        status="normal",
        revoked_time=None,
        tenant_no=tenant_no,
        create_by=user_id,
        create_dept_id=dept_id or "",
        create_time=now,
        update_by=user_id,
        update_time=now,
        del_flag=0,
    )
    db.add(row)
    db.commit()
    db.refresh(row)
    name_map = _user_name_map(db, [user_id])
    return _comment_to_dict(
        row,
        name_map=name_map,
        viewer_user_id=user_id,
        instance_status=inst.status or "",
    )


def revoke_comment(
    db: Session,
    *,
    instance_id: str,
    comment_id: str,
    tenant_no: str,
    user_id: str,
) -> Dict[str, Any]:
    inst = _get_instance(db, instance_id, tenant_no)
    if (inst.status or "") != "running":
        raise OaEngineError("仅审批进行中可撤回评论")
    row = (
        db.query(OaInstanceComment)
        .filter(
            OaInstanceComment.id == comment_id,
            OaInstanceComment.instance_id == instance_id,
            OaInstanceComment.tenant_no == tenant_no,
            OaInstanceComment.del_flag == 0,
        )
        .first()
    )
    if not row:
        raise OaEngineError("评论不存在")
    if (row.create_by or "") != (user_id or ""):
        raise OaEngineError("只能撤回自己的评论")
    now = datetime.now()
    if (row.status or "") != "revoked":
        row.status = "revoked"
        row.revoked_time = now
        row.update_by = user_id
        row.update_time = now
        db.add(row)
        db.commit()
        db.refresh(row)
    name_map = _user_name_map(db, [row.create_by] if row.create_by else [])
    return _comment_to_dict(
        row,
        name_map=name_map,
        viewer_user_id=user_id,
        instance_status=inst.status or "",
    )
```

注意：`_loads` / `_get_instance` / `_user_name_map` 若为 `oa_engine` 私有导出，现网其它服务已在用（见 `oa_related_approval`），保持一致即可。

- [ ] **Step 4: Run 全文件测试**

```bash
cd backend && source venv/bin/activate && pytest tests/test_oa_instance_comment.py -v
```

Expected: PASS（若 SysUser 必填列不足，按报错补全 setUp，对齐 `test_oa_engine.py` 中 SysUser 构造）

- [ ] **Step 5: Commit**

```bash
git add backend/app/services/oa_instance_comment.py backend/tests/test_oa_instance_comment.py
git commit -m "$(cat <<'EOF'
feat(oa): add instance comment create list and revoke service

EOF
)"
```

---

### Task 4: 详情注入 + HTTP API

**Files:**
- Modify: `backend/app/services/oa_engine.py`（`get_instance_detail` 返回前）
- Modify: `backend/app/api/oa_approval.py`

- [ ] **Step 1: 详情注入 comments**

在 `get_instance_detail` 末尾 `return data` 前：

```python
    from app.services import oa_instance_comment as oa_comment

    # viewer 在 API 层注入更准；此处无 user_id 时 canRevoke 一律 false
    data["comments"] = oa_comment.list_comments(
        db,
        instance_id=instance_id,
        tenant_no=tenant_no,
        viewer_user_id="",
    )
```

更好做法：给 `get_instance_detail` 增加可选参数 `viewer_user_id: str = ""`，并在 `get_oa_instance` 传入 `user.get("user_id") or ""`，以便 `canRevoke` 正确。

```python
def get_instance_detail(
    db: Session,
    instance_id: str,
    *,
    tenant_no: str,
    viewer_user_id: str = "",
) -> Dict[str, Any]:
    ...
    from app.services import oa_instance_comment as oa_comment

    data["comments"] = oa_comment.list_comments(
        db,
        instance_id=instance_id,
        tenant_no=tenant_no,
        viewer_user_id=viewer_user_id or "",
    )
    return data
```

API：

```python
return success_response(
    get_instance_detail(
        db,
        instance_id,
        tenant_no=tenant_no,
        viewer_user_id=user.get("user_id") or "",
    )
)
```

检查其它调用 `get_instance_detail` 的地方：新增参数有默认值，无需全改。

- [ ] **Step 2: 增加 Body 与路由**

在 `oa_approval.py` 靠近 `OaTransferBody` 处：

```python
class OaCommentCreateBody(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    content: str
    attachment_refs: Optional[List[Dict[str, Any]]] = Field(
        None, alias="attachmentRefs"
    )
```

在 `get_oa_instance` 附近增加：

```python
@router.get("/instances/{instance_id}/form-attachments")
async def list_oa_form_attachments(
    instance_id: str,
    user: dict = Depends(require_admin_or_super_admin),
    db: Session = Depends(get_db),
):
    from app.services import oa_instance_comment as oa_comment
    from app.services.oa_engine import OaEngineError

    try:
        tenant_no = _get_tenant_no(db, user)
        items = oa_comment.list_form_attachments(
            db, instance_id=instance_id, tenant_no=tenant_no
        )
        return success_response({"items": items})
    except OaEngineError as e:
        return error_response(400, str(e))


@router.get("/instances/{instance_id}/comments")
async def list_oa_comments(
    instance_id: str,
    user: dict = Depends(require_admin_or_super_admin),
    db: Session = Depends(get_db),
):
    from app.services import oa_instance_comment as oa_comment
    from app.services.oa_engine import OaEngineError

    try:
        tenant_no = _get_tenant_no(db, user)
        items = oa_comment.list_comments(
            db,
            instance_id=instance_id,
            tenant_no=tenant_no,
            viewer_user_id=user.get("user_id") or "",
        )
        return success_response({"list": items})
    except OaEngineError as e:
        return error_response(400, str(e))


@router.post("/instances/{instance_id}/comments")
async def create_oa_comment(
    instance_id: str,
    body: OaCommentCreateBody,
    user: dict = Depends(require_admin_or_super_admin),
    db: Session = Depends(get_db),
):
    from app.services import oa_instance_comment as oa_comment
    from app.services.oa_engine import OaEngineError

    try:
        tenant_no = _get_tenant_no(db, user)
        row = oa_comment.create_comment(
            db,
            instance_id=instance_id,
            tenant_no=tenant_no,
            user_id=user.get("user_id") or "",
            dept_id=user.get("dept_id") or "",
            content=body.content,
            attachment_refs=body.attachment_refs,
        )
        return success_response(row)
    except OaEngineError as e:
        return error_response(400, str(e))


@router.post("/instances/{instance_id}/comments/{comment_id}/revoke")
async def revoke_oa_comment(
    instance_id: str,
    comment_id: str,
    user: dict = Depends(require_admin_or_super_admin),
    db: Session = Depends(get_db),
):
    from app.services import oa_instance_comment as oa_comment
    from app.services.oa_engine import OaEngineError

    try:
        tenant_no = _get_tenant_no(db, user)
        row = oa_comment.revoke_comment(
            db,
            instance_id=instance_id,
            comment_id=comment_id,
            tenant_no=tenant_no,
            user_id=user.get("user_id") or "",
        )
        return success_response(row)
    except OaEngineError as e:
        return error_response(400, str(e))
```

确认 `user` dict 是否含 `dept_id`：若无，用 `""` 或现有 `_get_dept_id` 辅助（搜同文件其它 create 用法）。

- [ ] **Step 3: 跑引擎相关测确保未破**

```bash
cd backend && source venv/bin/activate && pytest tests/test_oa_instance_comment.py tests/test_oa_engine.py -v --tb=line -q
```

Expected: PASS（或仅既有无关失败）

- [ ] **Step 4: Commit**

```bash
git add backend/app/services/oa_engine.py backend/app/api/oa_approval.py
git commit -m "$(cat <<'EOF'
feat(oa): expose instance comment APIs and embed comments in detail

EOF
)"
```

---

### Task 5: 前端 API

**Files:**
- Modify: `web-admin/src/api/oaApproval.ts`

- [ ] **Step 1: 增加类型与方法**

在 `fetchOaInstanceDetail` 附近追加：

```typescript
export type OaCommentAttachmentRef = {
  fieldKey: string
  fieldLabel?: string
  url: string
  fileName: string
}

export type OaInstanceComment = {
  id: string
  instanceId?: string
  content: string
  attachmentRefs: OaCommentAttachmentRef[]
  status: 'normal' | 'revoked' | string
  revokedTime?: string
  createBy: string
  createByName?: string
  createTime: string
  canRevoke?: boolean
}

export function fetchOaFormAttachments(instanceId: string) {
  return request.get<{ items: Array<{ fieldKey: string; fieldLabel: string; files: OaCommentAttachmentRef[] }> }>({
    url: `${BASE}/instances/${instanceId}/form-attachments`
  })
}

export function fetchOaInstanceComments(instanceId: string) {
  return request.get<{ list: OaInstanceComment[] }>({
    url: `${BASE}/instances/${instanceId}/comments`
  })
}

export function fetchCreateOaComment(
  instanceId: string,
  data: { content: string; attachmentRefs?: OaCommentAttachmentRef[] }
) {
  return request.post<OaInstanceComment>({
    url: `${BASE}/instances/${instanceId}/comments`,
    data
  })
}

export function fetchRevokeOaComment(instanceId: string, commentId: string) {
  return request.post<OaInstanceComment>({
    url: `${BASE}/instances/${instanceId}/comments/${commentId}/revoke`
  })
}
```

- [ ] **Step 2: Commit**

```bash
git add web-admin/src/api/oaApproval.ts
git commit -m "$(cat <<'EOF'
feat(web-admin): add OA instance comment API clients

EOF
)"
```

---

### Task 6: `OaCommentPanel.vue`

**Files:**
- Create: `web-admin/src/components/oa-approval/OaCommentPanel.vue`

- [ ] **Step 1: 实现组件**

Props：

- `instanceId: string`
- `instanceStatus: string`
- `comments: OaInstanceComment[]`（可由父传入；发送/撤回后 `emit('refresh')`）

行为要点：

- `running` 才显示输入区与撤回。
- 列表升序展示；`revoked` 显示「{createByName} 撤回了一条评论」。
- 「引用附件」：`el-dialog` + `el-checkbox-group`，数据来自 `fetchOaFormAttachments`。
- 引用芯片点击：`window.open(url)`（对齐 `OaFcUpload` preview）。
- 撤回：`ElMessageBox.confirm` → `fetchRevokeOaComment` → emit refresh。
- 发送：trim 非空 → `fetchCreateOaComment` → 清空输入与已选引用 → emit refresh。
- 按钮带 `el-icon`（ChatDotRound / Paperclip / Promotion / RefreshLeft 等）。

骨架：

```vue
<template>
  <section class="oa-comment-panel">
    <h3 class="oa-comment-panel__title">评论</h3>
    <div v-if="!comments.length" class="oa-comment-panel__empty">暂无评论</div>
    <ul class="oa-comment-panel__list">
      <li v-for="c in comments" :key="c.id" class="oa-comment-panel__item">
        <template v-if="c.status === 'revoked'">
          <span class="oa-comment-panel__revoked">
            {{ c.createByName || c.createBy }} 撤回了一条评论
            <span v-if="c.revokedTime" class="oa-comment-panel__time">{{ c.revokedTime }}</span>
          </span>
        </template>
        <template v-else>
          <div class="oa-comment-panel__meta">
            <strong>{{ c.createByName || c.createBy }}</strong>
            <span class="oa-comment-panel__time">{{ c.createTime }}</span>
            <el-button
              v-if="c.canRevoke"
              link
              type="danger"
              @click="onRevoke(c)"
            >
              <el-icon><RefreshLeft /></el-icon>
              撤回
            </el-button>
          </div>
          <div class="oa-comment-panel__content">{{ c.content }}</div>
          <div v-if="c.attachmentRefs?.length" class="oa-comment-panel__refs">
            <el-tag
              v-for="(f, idx) in c.attachmentRefs"
              :key="idx"
              class="oa-comment-panel__ref"
              size="small"
              @click="openUrl(f.url)"
            >
              {{ f.fileName || f.url }}
            </el-tag>
          </div>
        </template>
      </li>
    </ul>
    <div v-if="instanceStatus === 'running'" class="oa-comment-panel__composer">
      <el-input
        v-model="draft"
        type="textarea"
        :rows="3"
        maxlength="1024"
        show-word-limit
        placeholder="填写评论"
      />
      <div v-if="picked.length" class="oa-comment-panel__picked">
        <el-tag
          v-for="(f, idx) in picked"
          :key="idx"
          closable
          size="small"
          @close="picked.splice(idx, 1)"
        >
          {{ f.fileName }}
        </el-tag>
      </div>
      <div class="oa-comment-panel__actions">
        <el-button class="btn-ghost" @click="openAttach">
          <el-icon><Paperclip /></el-icon>
          引用附件
        </el-button>
        <el-button type="primary" class="btn-main" :loading="sending" @click="onSend">
          <el-icon><Promotion /></el-icon>
          发送
        </el-button>
      </div>
    </div>
    <!-- 引用附件弹窗：多选 field 下 files -->
  </section>
</template>
```

样式：Fresh Mint；section 间距与 `oa-detail__section` 一致；**不要**改 `OaProgressChain`。

- [ ] **Step 2: Commit**

```bash
git add web-admin/src/components/oa-approval/OaCommentPanel.vue
git commit -m "$(cat <<'EOF'
feat(web-admin): add OaCommentPanel for instance discussion comments

EOF
)"
```

---

### Task 7: 挂到详情页与只读弹窗

**Files:**
- Modify: `web-admin/src/views/oa-approval/instances/detail.vue`
- Modify: `web-admin/src/components/oa-approval/OaInstanceDetailDialog.vue`

- [ ] **Step 1: detail.vue**

在表单 section 与 progress section **之间**插入：

```vue
<section class="oa-detail__section">
  <OaCommentPanel
    v-if="detail?.id"
    :instance-id="detail.id"
    :instance-status="detail.status || ''"
    :comments="detail.comments || []"
    @refresh="load"
  />
</section>
```

`import OaCommentPanel from '@/components/oa-approval/OaCommentPanel.vue'`。确认 `load` 会刷新详情（含 `comments`）。

- [ ] **Step 2: OaInstanceDetailDialog.vue**

同样在表单与进度之间挂载 `OaCommentPanel`，`@refresh` 重新 `fetchOaInstanceDetail`。

- [ ] **Step 3: 手工验收清单**

1. 本地执行迁移 SQL 后启动 backend + `pnpm dev`。
2. 打开一张 `running` 审批详情 → 可见评论区。
3. 发纯文字评论 → 列表出现。
4. 引用表单附件 → 评论下可点开。
5. 本人撤回 → 变灰条；他人无撤回按钮。
6. 完成后的单 → 无输入区、不可撤，历史仍可见。
7. 同意/拒绝意见与进度链无回归。

- [ ] **Step 4: 更新图谱（改了 backend + web-admin）**

```bash
./scripts/update-graph.sh all
```

- [ ] **Step 5: Commit**

```bash
git add web-admin/src/views/oa-approval/instances/detail.vue \
  web-admin/src/components/oa-approval/OaInstanceDetailDialog.vue \
  backend/graphify-out web-admin/graphify-out
git commit -m "$(cat <<'EOF'
feat(web-admin): mount instance comment panel on OA detail views

EOF
)"
```

---

## Spec coverage check

| Spec 要求 | Task |
|-----------|------|
| 独立表 + 模型 | T1 |
| 文字评论 ≤1024 | T3 create_comment |
| 引用表单附件 + 服务端校验 | T2–T3 |
| 本人撤回 + 留痕 + 幂等 | T3 |
| 仅 running 可发/撤 | T3 |
| GET form-attachments / comments / POST create / revoke | T4 |
| 详情注入 comments | T4 |
| Web CommentPanel + 详情挂载 | T6–T7 |
| 不混入进度链 / 不改审批意见 | 全任务未触碰 |
| 无通知/@/新上传 | 未实现 |
| 小程序预留 API | T4–T5 无 Web 专用字段 |

## Placeholder scan

无 TBD /「类似 Task N」悬空步骤。

---

## Execution handoff

Plan complete and saved to `docs/superpowers/plans/2026-09-20-oa-instance-comment.md`.

**Two execution options:**

1. **Subagent-Driven（推荐）** — 每个 Task 开新子代理，任务间复审，迭代快  
2. **Inline Execution** — 本会话按 executing-plans 连续执行，设检查点  

**Which approach?**