# 杜康好客 · 开发计划功能开发文档 v3.4.11



> 对应 PRD §3.10 · REQ-H-026 ~ REQ-H-028  

> 后端模块：`server/dukang-api/src/modules/dev-plan/`  

> 前端：`apps/admin-web` 开发计划三页面 + 技术支持改造



---



## 1. 数据模型



| 表 | 说明 |

|----|------|

| `dev_plan_task` | 任务池；可选 `support_ticket_id` |

| `dev_plan_version` | 版本；状态与时间戳 |

| `dev_plan_version_task` | 版本-任务多对多 |

| `dev_plan_settings` | 单例：审核助手配置（LLM/知识库/提示词） |
| `dev_plan_task_dispatch` | 派发审计 |
| `wecom_message_push` | 企微群 Webhook 多实例；推送条件 JSON 数组 |



枚举与 DTO：`packages/shared-types/src/dev-plan.ts`、`wecom-message-push.ts`



**任务派发**：不再存于 `dev_plan_settings`；改由 HQ「消息推送」勾选 `dev_plan.task_dispatch`。



---



## 2. Admin API



| 路由 | 说明 |

|------|------|

| `GET/POST /admin/dev-plan/tasks` | 任务列表 / 创建 |

| `GET/PUT/DELETE /admin/dev-plan/tasks/:id` | 任务 CRUD |

| `POST /admin/dev-plan/tasks/dispatch` | 评审派发（无需 devBotId） |

| `GET/POST /admin/dev-plan/versions` | 版本列表 / 创建 |

| `GET/PUT/DELETE /admin/dev-plan/versions/:id` | 版本 CRUD |

| `PUT /admin/dev-plan/versions/:id/tasks` | 替换关联任务 |

| `GET/PUT /admin/dev-plan/settings` | 开发设置（审核助手） |

| `GET/POST/PUT/DELETE /admin/wecom-message-pushes` | 消息推送 CRUD |

| `POST /admin/wecom-message-pushes/:id/test` | 测试消息推送 |



权限：`dev_plan`（`packages/shared-types/src/hq-permissions.ts`）



---



## 3. 技术支持联动



| 路由 | 说明 |

|------|------|

| `POST /admin/support-tickets/:id/review` | 统一审批（SuperAdmin） |

| `POST /admin/support-tickets/batch-review/preview` | 批量 AI 预审 |

| `POST /admin/support-tickets/batch-review/confirm` | 批量确认落库 |



审批通过：`decision=APPROVE` + `tasks[]`（≥1）→ 工单 `DEVELOPING` + 创建 `dev_plan_task`。



---



## 4. 企微与开发计划分工



| 能力 | 入口 | 说明 |
|------|------|------|
| **消息推送** | Admin `/wecom/pushes` | Webhook 多实例 + 条件勾选；运营告警 / 工单 / 任务派发 |
| **智能机器人** | Admin `/wecom/bots` | 四类角色 + 模块化权限；审计 `/logs/wecom-bots` |
| **任务评审派发** | 任务列表 · 评审 | 匹配 `dev_plan.task_dispatch` 的推送实例（可多条） |

DevPlan Agent（HTTP 回调对话）已移除，避免与「企微机器人」重复。

---

## 附录 A · 企微机器人能力矩阵（v3.4.11 重构）

| 模块 | 权限 | 指令示例 |
|------|------|----------|
| 订单 | `order.read` | `查订单 DK123` |
| 配送 | `delivery.read` | `快递 DK123` |
| 门店 | `store.read` | `查门店 杜康` |
| 核销 | `redeem.read` | `核销 门店名` |
| 售后工单 | `ticket.read` / `ticket.create` | `售后工单 TK…` / `工单 订单号 仅退款` |
| 用户 | `user.read` / `user.read_sms` | `用户号 U…` / `查用户 手机号` |
| 财务 | `finance.*.read` | `门店账单` / `合伙人账单` / `门店打款` |
| 技术支持 | `support_ticket.*` | `提单 BUG …` / `通过 ST…` / `驳回 ST… 理由` |
| 开发计划 | `dev_plan.task.read` / `dev_plan.version.read` | `开发任务` / `版本 v3.4.11` |

**审批**：`support_ticket.review` + 机器人级 `reviewSuperAdminWecomUserIds` 白名单；通过自动建 1 条 dev_plan_task。

**废弃**：`api.read.all`、`db.read`、`TEAM_ASSISTANT`（迁移为 `OPERATIONS`）。



---



## 5. 验收（ACC）



- [ ] 侧边栏「开发计划」三子页；无 `dev_plan` 权限不可见
- [ ] 侧边栏「企微机器人」：智能机器人 / 消息推送 / 日志
- [ ] 消息推送 CRUD + 测试；条件勾选生效
- [ ] 任务/版本 CRUD；版本多选关联任务
- [ ] 版本状态流转写时间戳；用时正确
- [ ] 新建技术支持工单 → `support_ticket.created` 推送；`alert.ops` 可并行
- [ ] 技术支持：单一审批、通过创建任务、批量 AI 审核
- [ ] 任务勾选评审派发（走消息推送 @ userid）
- [ ] 系统设置无企微告警开关；运行时不再读 `WECOM_ALERT_WEBHOOK_URL`
- [ ] mutation 有 HQ 操作审计



---



## 6. 发版



1. `pnpm db:generate` + `prisma db push`（`wecom_message_push` 表；删除 `dev_plan_settings.task_dispatch_*`）
2. `pnpm prisma:migrate-wecom-push`（发版前，在 drop `task_dispatch_*` 之前）或 API 启动 `ensureDefaults`
3. staging 验证消息推送 + 任务派发 + 工单通知
4. tag **`v3.4.11`**