左帮右臂 — P2 需求规格文档

版本: V1.0

日期: 2026-06-24

对应文档: spec-优化方案.md / design-优化方案.md / tasks-优化方案.md

范围: P2 方向细化为可执行编码任务（T33-T45）

原则: 只写 WHAT（业务行为），不写 HOW（实现细节）

1. 组件定位

1.1 核心职责

本组件负责补齐左帮右臂平台在协作可视化、租户配额、文章管理、循环依赖诊断、语音降级、实时通信六个维度的功能缺口，实现平台从"功能可用"到"运维可控"的跃迁。

1.2 核心输入

1. 协作链执行事件 → 调度器完成/失败信号 → 可视化流程图渲染
2. 租户资源创建请求 → 配额检查拦截 → 超限提示
3. 已发布文章查询请求 → 发布记录检索 → 发布链接返回
4. BOM 树结构数据 → 循环依赖检测 → 高亮路径渲染
5. 语音识别请求 → 阿里云 ASR 降级备选 → 识别文本返回
6. 三端操作事件 → WebSocket 推送 → 实时消息同步

1.3 核心输出

1. 协作链流程图：显示任务链路、当前执行节点、历史执行状态
2. 租户配额拦截：创建前检查 + 超限提示 + 管理界面
3. 已发布文章列表：含发布 ID、发布时间、发布链接
4. BOM 循环依赖高亮：在 BomTreeGraph 中标红循环路径
5. 阿里云 ASR 降级：讯飞不可用时自动切换阿里云
6. WebSocket 实时推送：替代轮询，三端消息即时同步

1.4 职责边界

• 不做什么: 不实现协作调度器本身的逻辑（已在 P1 T24 完成）
• 不做什么: 不实现租户中间件本身（已在 P0 T09 完成），只做配额层
• 不做什么: 不实现微信发布服务本身（已在 P0-P1 完成），只做发布记录管理
• 不做什么: 不实现 BomTreeGraph 组件本身（已在 P1 T22 完成），只做循环依赖高亮
• 不做什么: 不重构 ASR 服务架构，只在现有双后端模式上增加第三后端
• 不做什么: 不实现消息业务逻辑（已在 P1 T17 完成），只做传输层从轮询到 WebSocket 的升级

2. 领域术语

协作链可视化

: 在网页端以流程图形式展示数字员工之间的任务接力关系，包括已执行节点、当前执行节点和待执行节点。

租户配额

: 对租户可使用的资源数量（Part 数、BOM 数、用户数、月度任务数）设置上限，超限时阻止创建并提示管理员。

已发布文章

: 通过微信公众号发布服务成功发布的文章记录，包含微信返回的 publish_id 和可访问的发布链接。

循环依赖路径

: BOM 树中存在 A→B→...→A 的环形引用，导致无限递归，系统必须检测并高亮显示。

ASR 降级链

: 语音识别服务的多后端容错机制：讯飞（主）→ 阿里云（备）→ Echo（兜底），主后端不可用时自动切换。

WebSocket 实时推送

: 基于持久化连接的双向通信机制，替代 HTTP 轮询，实现网页端/飞书端/小程序端消息的即时同步。

3. 角色与边界

3.1 核心角色

• 企业老板: 通过协作链可视化查看任务执行进度，通过配额管理控制成本
• 系统管理员: 配置租户配额上限，管理已发布文章，监控 ASR 降级状态
• 业务操作员: 在 BomTreeGraph 中查看循环依赖，接收 WebSocket 实时通知

3.2 外部系统

• 阿里云智能语音服务: ASR 第二后端，提供语音识别能力
• WebSocket 客户端: 网页端原生 WebSocket / 小程序 wx.connectSocket

3.3 交互上下文

@startuml
left to right direction

rectangle "左帮右臂平台 P2" as platform {
}

actor "企业老板" as boss
actor "系统管理员" as admin
actor "业务操作员" as operator

boss --> platform : 查看协作链进度 / 配额超限提示
admin --> platform : 配置配额 / 管理文章 / 监控ASR
operator --> platform : 查看循环依赖 / 接收实时通知

cloud "阿里云ASR" as aliyun
cloud "WebSocket" as ws

platform --> aliyun : 语音识别（降级备选）
platform --> ws : 三端实时推送

@enduml

4. DFX约束

4.1 性能

• 协作链流程图渲染应当不超过 1 秒（10 个节点以内）
• 租户配额检查应当不超过 50ms（数据库查询）
• WebSocket 消息推送延迟应当不超过 200ms
• 阿里云 ASR 降级切换应当对用户透明，总延迟增加不超过 2 秒

4.2 可靠性

• WebSocket 断连后必须自动重连，重连间隔不超过 5 秒
• 阿里云 ASR 降级切换不得导致已发送音频丢失
• 租户配额数据必须与实际资源数量保持一致（日同步 + 创建时实时检查）

4.3 安全性

• WebSocket 连接必须经过 JWT 认证
• 租户配额管理接口必须限制管理员角色访问
• 配额超限日志必须记录到审计日志

4.4 可维护性

• ASR 后端切换应当通过配置驱动（config.yaml），不需要修改代码
• WebSocket 服务应当与现有 HTTP 服务共存于同一端口
• 协作链可视化组件应当独立可复用

4.5 兼容性

• WebSocket 推送必须兼容不支持 WebSocket 的客户端（降级为轮询）
• 阿里云 ASR 后端必须兼容现有 /api/asr/recognize 接口格式
• 租户配额功能必须兼容无配额记录的存量租户（使用默认配额）

5. 核心能力

5.1 协作链可视化（P2-1）

5.1.1 业务规则

1. 协作链流程图展示: When 用户在数字员工任务看板中查看协作任务时，the 系统 shall 以流程图形式展示完整的任务链路，包含已执行节点、当前执行节点和待执行节点。

a. 验收条件：[用户在任务看板点击协作任务] → [系统渲染流程图：采购询价(✓) → 成本分析(🔄进行中) → 供应商评估(⏳待执行)] → [每个节点显示员工名称和任务状态]

1. 协作链节点详情查看: When 用户点击流程图中的节点时，the 系统 shall 展示该节点的任务详情。

a. 验收条件：[用户点击"成本分析"节点] → [系统弹出详情面板，显示任务描述、执行结果、耗时信息] → [关闭面板后流程图不变]

1. 协作链实时状态更新: While 协作链正在执行中，When 某节点状态发生变化时，the 系统 shall 自动更新流程图中对应节点的状态显示。

a. 验收条件：[成本分析任务完成] → [流程图中"成本分析"节点从"进行中"变为"已完成"] → ["供应商评估"节点从"待执行"变为"进行中"]

5.1.2 交互流程

@startuml
actor 用户
participant "任务看板" as board
participant "协作链API" as api
participant "协作调度器" as scheduler
participant "流程图组件" as graph

用户 -> board : 查看协作任务
board -> api : GET /api/digital-staff/collaboration/chain/:taskId
api -> scheduler : getCollaborationChain(taskId)
scheduler --> api : 链路数据
api --> board : { chain: [...] }
board -> graph : 渲染流程图
graph --> 用户 : 显示链路图

用户 -> graph : 点击节点
graph --> 用户 : 弹出任务详情
@enduml

5.1.3 异常场景

1. 协作链数据不完整

a. 触发条件：某个协作任务缺少 collaboration_chain 字段

b. 系统行为：显示单节点视图，标注"该任务无协作链信息"

c. 用户感知：看到单个节点而非链路图

1. 协作链 API 超时

a. 触发条件：协作链查询接口响应超过 5 秒

b. 系统行为：显示"加载中"骨架屏，后台重试一次

c. 用户感知：看到加载状态，最终显示数据或"加载失败，请重试"

5.2 租户配额限制（P2-2）

5.2.1 业务规则

1. 配额创建前检查: When 租户创建资源（Part/BOM/用户/数字员工任务）时，the 系统 shall 检查该租户当前资源数量是否超过配额上限。

a. 验收条件：[租户 A 已创建 10000 个 Part（配额上限）] → [尝试创建第 10001 个] → [返回"已达到 Part 数据配额上限（10000），请联系管理员升级"] → [记录配额超限日志]

1. 配额超限提示: When 租户资源数量达到配额上限的 80% 时，the 系统 shall 在创建成功响应中附加警告信息。

a. 验收条件：[租户 A 已创建 8000 个 Part（配额上限 10000）] → [创建第 8001 个] → [创建成功，响应包含 quotaWarning: "Part 数量已达配额 80%，请关注""]

1. 配额数据自动同步: When 系统启动时，the 系统 shall 自动统计各租户当前资源数量并更新配额表。

a. 验收条件：[系统启动] → [统计租户 A 的 Part 数量为 8234] → [更新 tenant_quotas 表 currentParts = 8234] → [后续创建前检查使用实时数据]

1. 禁止项: 配额检查不得阻断系统管理员角色的操作。

a. 验收条件：[管理员创建第 10001 个 Part] → [创建成功，响应包含 quotaExceeded: true 警告但不阻断]

5.2.2 交互流程

@startuml
participant "客户端" as client
participant "租户中间件" as middleware
participant "配额服务" as quota
participant "业务处理" as handler

client -> middleware : 创建资源请求 (JWT含enterprise_id)
middleware -> quota : checkQuota(enterpriseId, resourceType)
quota -> quota : 查询 currentCount vs maxQuota
alt 未超限
    quota --> middleware : { allowed: true }
    middleware -> handler : 继续创建
    handler --> client : 创建成功 (+ quotaWarning if 80%+)
else 已超限
    quota --> middleware : { allowed: false, reason: "..." }
    middleware --> client : 403 配额超限提示
end
@enduml

5.2.3 异常场景

1. 配额表无记录

a. 触发条件：新租户在 tenant_quotas 表中无配额记录

b. 系统行为：使用默认配额（maxParts=10000, maxBoms=1000, maxUsers=50, maxStaffTasks=5000）

c. 用户感知：正常使用，不受影响

1. 配额统计与实际不一致

a. 触发条件：tenant_quotas.currentParts 与实际 Part 数量不一致

b. 系统行为：每日凌晨自动执行全量同步，创建时实时 +1 保证准确性

c. 用户感知：配额检查可能暂时偏松，但不会偏严

5.3 已发布文章管理（P2-3）

5.3.1 业务规则

1. 发布记录自动保存: When 文章通过微信发布服务成功发布后，the 系统 shall 自动保存发布记录，包含 publish_id、发布时间和文章元数据。

a. 验收条件：[文章发布成功] → [系统写入 published_articles 表：{ article_id, publish_id, publish_time, title, media_id }] → [后续可查询]

1. 已发布文章列表查看: When 用户在内容管理页面查看已发布文章时，the 系统 shall 展示所有已发布文章的列表，包含标题、发布时间和发布链接。

a. 验收条件：[用户打开内容管理页面] → [系统展示已发布文章列表] → [每条记录包含标题、发布时间、发布链接] → [点击链接可在新窗口查看文章]

1. 发布状态标记: When 文章处于不同发布阶段时，the 系统 shall 在内容列表中标记对应状态。

a. 验收条件：[草稿文章标记为"草稿"] → [已发布文章标记为"已发布"并显示发布链接] → [发布失败文章标记为"发布失败"并显示重试按钮]

5.3.2 交互流程

@startuml
actor 用户
participant "内容管理页面" as page
participant "内容API" as api
participant "微信发布服务" as wechat

用户 -> page : 查看已发布文章
page -> api : GET /api/content/published-articles
api --> page : 文章列表
page --> 用户 : 展示列表（标题+时间+链接）

用户 -> page : 点击发布链接
page --> 用户 : 新窗口打开微信文章
@enduml

5.3.3 异常场景

1. 发布记录写入失败

a. 触发条件：published_articles 表写入失败

b. 系统行为：文章已发布成功，但记录缺失，日志记录错误

c. 用户感知：文章列表中可能缺少该条记录，需手动补录

1. 发布链接失效

a. 触发条件：微信文章被删除或链接过期

b. 系统行为：点击链接后微信返回 404，系统无法控制

c. 用户感知：看到"页面不存在"，需联系管理员

5.4 BOM 循环依赖可视化（P2-4）

5.4.1 业务规则

1. 循环依赖路径高亮: When BOM 树中存在循环依赖时，the 系统 shall 在 BomTreeGraph 中高亮显示循环路径的所有节点和边。

a. 验收条件：[BOM 树存在 A→B→C→A 循环] → [BomTreeGraph 中 A、B、C 三个节点标红] → [A→B、B→C、C→A 三条边标红并加粗] → [节点旁显示"⚠️ 循环依赖"标签]

1. 循环依赖路径提示: When 用户点击循环依赖节点时，the 系统 shall 显示完整的循环路径信息。

a. 验收条件：[用户点击循环依赖节点 A] → [弹出提示"检测到循环依赖：A → B → C → A"] → [提供"查看完整路径"和"忽略"选项]

1. 循环依赖阻止操作: When BOM 导入检测到循环依赖时，the 系统 shall 阻止导入并显示循环路径。

a. 验收条件：[导入包含循环依赖的 BOM] → [系统拒绝导入] → [BomTreeGraph 预览中高亮循环路径] → [提示"请修正循环依赖后重新导入"]

5.4.2 交互流程

@startuml
actor 用户
participant "BomAssistant" as bom
participant "BomTreeGraph" as graph
participant "BOM导入服务" as importSvc

用户 -> bom : 上传含循环依赖的BOM
bom -> importSvc : importBom(buffer)
importSvc -> importSvc : DFS检测循环
importSvc --> bom : { cycleDetected: true, cyclePath: [A,B,C,A] }
bom -> graph : 渲染预览（含循环高亮）
graph --> 用户 : 循环节点标红 + 路径提示

用户 -> graph : 点击循环节点
graph --> 用户 : 显示完整循环路径
@enduml

5.4.3 异常场景

1. 循环路径过长

a. 触发条件：循环路径超过 10 个节点

b. 系统行为：截断显示前 10 个节点，标注"...等 N 个节点形成循环"

c. 用户感知：看到截断的循环路径提示

1. 多个独立循环

a. 触发条件：BOM 树中存在多个不相关的循环

b. 系统行为：所有循环路径均高亮，用不同颜色区分（红/橙/紫）

c. 用户感知：看到多条高亮路径，点击可查看各自的循环信息

5.5 阿里云 ASR 第二后端（P2-5）

5.5.1 业务规则

1. 阿里云 ASR 降级备选: When 讯飞 ASR 服务不可用时，the 系统 shall 自动切换到阿里云智能语音服务进行识别。

a. 验收条件：[讯飞 ASR 返回超时或错误] → [系统自动调用阿里云 ASR] → [返回识别文本] → [响应标注 asrProvider: 'aliyun']

1. ASR 后端配置驱动: When 管理员在 config.yaml 中配置 ASR 后端优先级时，the 系统 shall 按配置顺序尝试各后端。

a. 验收条件：[config.yaml 配置 asr.providers: [iflytek, aliyun, echo]] → [讯飞不可用时自动尝试阿里云] → [阿里云不可用时降级到 Echo] → [每次降级记录日志]

1. ASR 后端健康检查: While 系统运行中，the 系统 shall 定期检查各 ASR 后端的可用性。

a. 验收条件：[系统每 5 分钟检查一次讯飞和阿里云的健康状态] → [健康状态记录到内存] → [请求时优先使用最近一次健康检查通过的后端]

5.5.2 交互流程

@startuml
participant "客户端" as client
participant "ASR服务" as asr
participant "讯飞" as iflytek
participant "阿里云" as aliyun
participant "Echo" as echo

client -> asr : POST /api/asr/recognize (音频)
asr -> iflytek : 调用讯飞识别
alt 讯飞成功
    iflytek --> asr : 识别文本
    asr --> client : { text, provider: 'iflytek' }
else 讯飞失败
    iflytek --> asr : 错误
    asr -> aliyun : 调用阿里云识别
    alt 阿里云成功
        aliyun --> asr : 识别文本
        asr --> client : { text, provider: 'aliyun' }
    else 阿里云失败
        aliyun --> asr : 错误
        asr -> echo : Echo 模式
        echo --> asr : 模拟文本
        asr --> client : { text, provider: 'echo', degraded: true }
    end
end
@enduml

5.5.3 异常场景

1. 阿里云 ASR 配置缺失

a. 触发条件：config.yaml 中未配置 aliyun.appKey / aliyun.accessKeyId

b. 系统行为：跳过阿里云后端，直接降级到 Echo 模式

c. 用户感知：识别结果标注"语音识别服务暂不可用，已使用模拟输入"

1. 所有 ASR 后端均不可用

a. 触发条件：讯飞、阿里云、Echo 均无法返回结果

b. 系统行为：返回错误"语音识别服务暂时不可用，请稍后重试"

c. 用户感知：看到错误提示，建议稍后重试

5.6 WebSocket 实时推送（P2-6）

5.6.1 业务规则

1. WebSocket 连接建立: When 客户端发起 WebSocket 连接请求时，the 系统 shall 验证 JWT 后建立持久化连接。

a. 验收条件：[客户端发送 ws://host/ws?token=xxx] → [系统验证 JWT] → [建立 WebSocket 连接] → [返回连接成功确认]

1. 三端消息实时推送: When 系统产生通知消息时，the 系统 shall 通过 WebSocket 推送到所有已连接的客户端。

a. 验收条件：[网页端创建 ECR 变更] → [系统通过 WebSocket 推送通知到该租户所有在线用户] → [小程序端和网页端即时收到通知] → [延迟不超过 200ms]

1. WebSocket 断连自动重连: When WebSocket 连接意外断开时，the 客户端 shall 自动尝试重连。

a. 验收条件：[网络波动导致 WebSocket 断开] → [客户端等待 2 秒后重连] → [重连成功后补发断连期间的消息] → [最多重试 5 次]

1. 轮询降级兼容: Where 客户端不支持 WebSocket，the 系统 shall 自动降级为 HTTP 轮询模式。

a. 验收条件：[旧版浏览器不支持 WebSocket] → [客户端自动切换到 5 秒轮询] → [功能不受影响，仅实时性降低]

5.6.2 交互流程

@startuml
participant "网页端" as web
participant "WebSocket服务" as ws
participant "通知服务" as notify
participant "小程序" as miniapp

web -> ws : ws://host/ws?token=jwt
ws -> ws : 验证JWT
ws --> web : 连接成功

miniapp -> ws : wx.connectSocket(url?token=jwt)
ws --> miniapp : 连接成功

notify -> ws : 新通知(userId, message)
ws -> ws : 查找userId的连接
ws -> web : 推送通知
ws -> miniapp : 推送通知

note over web : 网络断开
web -> ws : 2秒后重连
ws --> web : 重连成功 + 补发消息
@enduml

5.6.3 异常场景

1. JWT 验证失败

a. 触发条件：WebSocket 连接携带的 JWT 无效或过期

b. 系统行为：关闭连接，返回 4001 错误码

c. 用户感知：需要重新登录获取新 token

1. 大量连接导致内存压力

a. 触发条件：同时在线 WebSocket 连接超过 1000

b. 系统行为：对新连接返回 503 "服务繁忙，请稍后重试"

c. 用户感知：无法建立连接，降级为轮询模式

1. 消息推送失败

a. 触发条件：WebSocket 推送时客户端已断开但服务端未感知

b. 系统行为：将消息暂存到 notifications 表，客户端重连后补发

c. 用户感知：重连后收到断连期间的所有未读消息

5.7 租户配额管理界面（P2-7）

5.7.1 业务规则

1. 配额上限配置: When 管理员在配额管理界面修改租户配额上限时，the 系统 shall 保存新配额并立即生效。

a. 验收条件：[管理员将租户 A 的 maxParts 从 10000 修改为 20000] → [保存成功] → [租户 A 下次创建 Part 时使用新配额 20000] → [操作记录到审计日志]

1. 配额使用情况展示: When 管理员查看租户配额时，the 系统 shall 展示各资源类型的当前使用量和配额上限。

a. 验收条件：[管理员打开配额管理页面] → [显示租户列表] → [每个租户显示：Part 8234/10000 (82%)、BOM 456/1000 (46%)、用户 23/50 (46%)、月任务 3200/5000 (64%)] → [超过 80% 的指标标黄]

1. 配额批量初始化: When 管理员首次启用配额功能时，the 系统 shall 支持为所有租户批量设置默认配额。

a. 验收条件：[管理员点击"批量初始化"] → [系统为所有无配额记录的租户创建默认配额] → [默认值：maxParts=10000, maxBoms=1000, maxUsers=50, maxStaffTasks=5000] → [操作记录到审计日志]

1. 禁止项: 非管理员角色不得访问配额管理界面。

a. 验收条件：[普通用户访问 /admin/quotas] → [返回 403 Forbidden] → [页面显示"无权访问"]

5.7.2 交互流程

@startuml
actor 管理员
participant "配额管理页面" as page
participant "配额API" as api
participant "配额服务" as quota

管理员 -> page : 打开配额管理
page -> api : GET /api/admin/quotas
api -> quota : getAllQuotas()
quota --> api : 配额列表
api --> page : { quotas: [...] }
page --> 管理员 : 展示配额使用情况

管理员 -> page : 修改租户A的maxParts为20000
page -> api : PUT /api/admin/quotas/:enterpriseId
api -> quota : updateQuota(enterpriseId, { maxParts: 20000 })
quota --> api : 更新成功
api --> page : { success: true }
page --> 管理员 : 显示更新成功
@enduml

5.7.3 异常场景

1. 配额上限低于当前使用量

a. 触发条件：管理员将 maxParts 从 10000 修改为 5000，但当前已有 8234 个 Part

b. 系统行为：允许修改，但弹出警告"当前使用量(8234)已超过新配额(5000)，已有数据不受影响但无法新增"

c. 用户感知：看到警告提示，确认后修改生效

1. 并发修改冲突

a. 触发条件：两个管理员同时修改同一租户的配额

b. 系统行为：后提交的修改覆盖先提交的，记录两次修改的审计日志

c. 用户感知：最终生效的是最后一次提交的值

6. 数据约束

6.1 租户配额（TenantQuota）

1. enterpriseId: 租户唯一标识，主键
2. maxParts: Part 数量上限，默认 10000，必须大于 0
3. maxBoms: BOM 数量上限，默认 1000，必须大于 0
4. maxUsers: 用户数量上限，默认 50，必须大于 0
5. maxStaffTasks: 月度数字员工任务上限，默认 5000，必须大于 0
6. currentParts: 当前 Part 数量，系统自动维护，必须大于等于 0
7. currentBoms: 当前 BOM 数量，系统自动维护，必须大于等于 0
8. currentUsers: 当前用户数量，系统自动维护，必须大于等于 0
9. currentStaffTasks: 当月数字员工任务数量，系统自动维护，每月重置
10. updatedAt: 最后更新时间，管理员修改或系统同步时更新

6.2 已发布文章（PublishedArticle）

1. id: 唯一标识，自增主键
2. articleId: 文章内容 ID，关联内容表
3. publishId: 微信返回的发布 ID，发布成功后必填
4. mediaId: 草稿媒体 ID，发布前必填
5. title: 文章标题，必填
6. publishTime: 发布时间，发布成功后必填
7. publishUrl: 发布链接，发布成功后由微信返回
8. status: 枚举值：draft / publishing / published / failed
9. retryCount: 发布重试次数，默认 0
10. enterpriseId: 租户 ID，用于多租户隔离

6.3 ASR 后端配置（AsrProviderConfig）

1. name: 后端名称，枚举值：iflytek / aliyun / echo
2. priority: 优先级，数字越小越优先
3. enabled: 是否启用
4. aliyunAccessKeyId: 阿里云 AccessKey ID（环境变量覆盖）
5. aliyunAccessKeySecret: 阿里云 AccessKey Secret（环境变量覆盖）
6. aliyunAppKey: 阿里云智能语音 AppKey（环境变量覆盖）

7. 编码任务拆解

依赖关系总览

P2 任务依赖图（→ 表示依赖）:

T33 ──────────────┐
T34 ──→ T35 ──→ T36 (配额链路)
T37 ──→ T38       (文章管理链路)
T39               (BOM循环可视化，独立)
T40 ──→ T41       (ASR降级链路)
T42 ──→ T43 ──→ T44 (WebSocket链路)
T45 ──→ T36       (配额管理界面→配额API)

T33. 协作链可视化组件 — CollaborationChainGraph.vue

• 优先级: P2
• 预估工时: 2 天
• 依赖: T24（协作调度器需先就绪）、T25（协作链 API 需先就绪）
• 涉及文件:
• src/components/digital-staff/CollaborationChainGraph.vue (新增)
• src/views/DigitalStaff.vue (修改 — 集成协作链图)
• 编码步骤:

1. 新增 src/components/digital-staff/CollaborationChainGraph.vue
2. 使用 SVG 渲染水平流程图：

• 节点 = 数字员工任务卡片（员工名称/任务状态/耗时）
• 边 = 协作触发关系线（带箭头）

1. 节点状态标记：✅ 已完成(绿) / 🔄 进行中(蓝+脉冲动画) / ⏳ 待执行(灰) / ❌ 失败(红)
2. 交互功能：

• 点击节点 → emit('node-click') → 显示任务详情面板
• 鼠标悬停 → 显示简要信息 tooltip

1. Props 设计：

• chain: 协作链数据数组 [{ taskId, assignedTo, status, title, result }]
• currentTaskId: 当前执行中的任务 ID（用于高亮）

1. 修改 src/views/DigitalStaff.vue：在任务看板区域集成 CollaborationChainGraph

• 从 GET /api/digital-staff/collaboration/chain/:taskId 获取链路数据

1. 添加自动刷新：协作链执行中时每 5 秒轮询更新状态

• 验证方法:
• 在数字员工页面触发协作链，确认流程图正确渲染
• 确认节点状态颜色和动画正确
• 点击节点确认显示任务详情
• 协作链执行中确认自动刷新
• 可并行: 否（依赖 T24+T25）

T34. 租户配额后端服务 — tenant-quota-service.js

• 优先级: P2
• 预估工时: 1.5 天
• 依赖: T09（租户中间件需先就绪）、T15（数据库表需先就绪）
• 涉及文件:
• server/services/tenant-quota-service.js (新增)
• server/db-adapter.js (修改 — 新增 tenant_quotas 建表)
• 编码步骤:

1. 新增 server/services/tenant-quota-service.js，导出类 TenantQuotaService
2. 实现 ensureTable() — CREATE TABLE IF NOT EXISTS tenant_quotas（见数据约束 6.1）
3. 实现 checkQuota(enterpriseId, resourceType)：

• 查询 tenant_quotas 获取配额上限和当前数量
• 若无记录 → 使用默认配额
• 返回 { allowed: boolean, current: number, max: number, warning: string|null }

1. 实现 incrementUsage(enterpriseId, resourceType, delta = 1)：

• UPDATE tenant_quotas SET current_{resourceType} = current_{resourceType} + delta
• 若行不存在 → INSERT 默认配额行 + increment

1. 实现 syncQuotaUsage(enterpriseId)：

• 统计实际 Part/BOM/User/StaffTask 数量
• UPDATE tenant_quotas SET currentParts=..., currentBoms=..., currentUsers=..., currentStaffTasks=...

1. 实现 syncAllQuotas()：

• 遍历所有租户执行 syncQuotaUsage
• 启动时调用一次，每日凌晨定时调用

1. 实现 getQuota(enterpriseId) — 返回完整配额信息
2. 实现 updateQuota(enterpriseId, fields) — 管理员修改配额上限
3. 实现 getAllQuotas() — 管理员查看所有租户配额
4. 修改 server/db-adapter.js：在 createDatabase() 中新增 tenant_quotas 建表语句

• 验证方法:
• 调用 checkQuota('ent_A', 'parts') 确认返回配额状态
• 调用 incrementUsage('ent_A', 'parts') 确认计数增加
• 调用 syncQuotaUsage('ent_A') 确认与实际数据一致
• 无配额记录时确认使用默认配额
• 可并行: 是（与 T33/T37/T39/T40/T42 无依赖）

T35. 租户配额检查中间件集成

• 优先级: P2
• 预估工时: 1 天
• 依赖: T34（配额服务需先就绪）
• 涉及文件:
• server/middleware/tenant-middleware.js (修改 — 增加 quotaGuard)
• server.js (修改 — 在创建类路由中增加配额检查)
• 编码步骤:

1. 在 tenant-middleware.js 中新增 quotaGuard(resourceType) 方法：

• 从 req.tenantContext.enterpriseId 获取租户 ID
• 调用 tenantQuotaService.checkQuota(enterpriseId, resourceType)
• 若 allowed === false → 403 + 配额超限提示
• 若 warning !== null → 在响应头中附加 X-Quota-Warning
• 管理员角色跳过阻断（仅附加警告）

1. 修改 server.js：在以下创建路由中增加配额检查：

• Part 创建 → quotaGuard('parts')
• BOM 创建 → quotaGuard('boms')
• 用户创建 → quotaGuard('users')
• 数字员工任务创建 → quotaGuard('staffTasks')

1. 在创建成功后调用 tenantQuotaService.incrementUsage(enterpriseId, resourceType)
2. 配额超限时记录审计日志：{ action: 'quota_exceeded', enterprise_id, resource_type, current, max }

• 验证方法:
• 租户 A 达到 Part 配额上限后尝试创建，确认返回 403
• 租户 A 达到 80% 配额后创建，确认响应包含警告
• 管理员角色达到配额后创建，确认成功但有警告
• 确认审计日志记录配额超限事件
• 可并行: 否（依赖 T34）

T36. 租户配额管理 API

• 优先级: P2
• 预估工时: 0.5 天
• 依赖: T34（配额服务需先就绪）
• 涉及文件:
• server/routes/admin-quota.js (新增)
• server.js (修改 — 注册路由)
• 编码步骤:

1. 新增 server/routes/admin-quota.js，导出 handleAdminQuotaRoute(req, res, pathname, query, bodyStr)
2. 实现 API 路由：

• GET /api/admin/quotas — 获取所有租户配额列表
• GET /api/admin/quotas/:enterpriseId — 获取指定租户配额
• PUT /api/admin/quotas/:enterpriseId — 修改配额上限
• POST /api/admin/quotas/init — 批量初始化默认配额
• POST /api/admin/quotas/:enterpriseId/sync — 手动同步配额使用量

1. 所有接口需验证管理员角色（req.userRole === 'admin'）
2. 修改 server.js：在 handleRequest 中注册 /api/admin/quotas 路由前缀

• 验证方法:
• 调用 GET /api/admin/quotas 确认返回配额列表
• 调用 PUT /api/admin/quotas/:enterpriseId 确认修改生效
• 非管理员调用确认返回 403
• 调用 POST /api/admin/quotas/init 确认批量初始化
• 可并行: 否（依赖 T34，但可与 T35 并行）

T37. 已发布文章后端 — published-articles 服务与 API

• 优先级: P2
• 预估工时: 1.5 天
• 依赖: T11（微信环境变量统一需先就绪）、T31（发布重试需先就绪）
• 涉及文件:
• server/services/published-article-service.js (新增)
• server/routes/content-api.js (修改 — 新增已发布文章 API)
• server/services/wechat-publish.js (修改 — 发布成功后写入记录)
• server/db-adapter.js (修改 — 新增 published_articles 建表)
• 编码步骤:

1. 新增 server/services/published-article-service.js，导出类 PublishedArticleService
2. 实现 ensureTable() — CREATE TABLE IF NOT EXISTS published_articles（见数据约束 6.2）
3. 实现 recordPublish(data) — 发布成功后记录：INSERT INTO published_articles
4. 实现 getPublishedArticles(filters) — 分页查询已发布文章列表
5. 实现 getPublishedArticle(id) — 获取单条发布记录
6. 实现 updatePublishStatus(id, status, extra) — 更新发布状态
7. 修改 server/services/wechat-publish.js：

• 在 publishArticle() 成功后调用 publishedArticleService.recordPublish()
• 在发布失败后调用 publishedArticleService.updatePublishStatus(id, 'failed')

1. 修改 server/routes/content-api.js：新增 API 路由：

• GET /api/content/published-articles — 已发布文章列表
• GET /api/content/published-articles/:id — 单条发布记录

1. 修改 server/db-adapter.js：新增 published_articles 建表语句

• 验证方法:
• 发布文章成功后确认 published_articles 表有记录
• 调用 GET /api/content/published-articles 确认返回列表
• 发布失败后确认状态标记为"failed"
• 确认发布链接可访问
• 可并行: 是（与 T33/T34/T39/T40/T42 无依赖）

T38. 已发布文章前端管理界面

• 优先级: P2
• 预估工时: 1 天
• 依赖: T37（已发布文章 API 需先就绪）
• 涉及文件:
• src/views/ContentManager.vue (修改 — 增加"已发布"标签页)
• src/api/content.js (修改 — 新增已发布文章 API 调用)
• 编码步骤:

1. 修改 src/views/ContentManager.vue：增加"已发布"标签页
2. 在标签页中调用 GET /api/content/published-articles 获取列表
3. 实现文章列表 UI：

• 表格列：标题、发布时间、发布状态、操作
• 状态标记：🟢已发布 / 🟡发布中 / 🔴发布失败

1. 操作按钮：

• "查看链接" → 新窗口打开微信文章
• "重新发布" → 仅对失败状态显示

1. 修改 src/api/content.js：新增 getPublishedArticles() 和 getPublishedArticle(id) 方法
2. 添加分页和搜索功能

• 验证方法:
• 打开内容管理页面，切换到"已发布"标签页，确认显示文章列表
• 点击"查看链接"确认在新窗口打开微信文章
• 发布失败的文章确认显示"重新发布"按钮
• 分页和搜索功能正常
• 可并行: 否（依赖 T37）

T39. BOM 循环依赖可视化增强

• 优先级: P2
• 预估工时: 1.5 天
• 依赖: T22（BomTreeGraph 需先就绪）、T07（BOM 导入需先就绪）
• 涉及文件:
• src/components/bom/BomTreeGraph.vue (修改 — 增加循环依赖高亮)
• server/services/bom-import-service.js (修改 — 返回循环路径数据)
• 编码步骤:

1. 修改 BomTreeGraph.vue：

• 新增 prop cyclePaths: 循环路径数组 [[nodeId1, nodeId2, ...], ...]
• 新增 computed cycleNodeIds: 从 cyclePaths 提取所有循环节点 ID
• 修改 flattenTree()：循环节点增加 status: 'cycle' 标记
• 新增 CSS 类 .node-cycle .node-rect：红色填充 + 红色边框 + 脉冲动画
• 修改边渲染：循环路径的边使用红色加粗线条
• 新增点击循环节点的交互：弹出循环路径信息

1. 新增循环路径提示组件：

• 显示完整循环路径：A → B → C → A
• 提供"查看完整路径"和"忽略"按钮

1. 修改 server/services/bom-import-service.js：

• 在 buildBomTree() 的循环检测逻辑中，记录完整的循环路径
• 返回值增加 cyclePaths 字段：[[id1, id2, id3, id1], ...]

1. 修改 BomAssistant.vue（如有需要）：传递 cyclePaths 到 BomTreeGraph

• 验证方法:
• 导入包含循环依赖的 BOM，确认循环节点标红
• 确认循环路径的边使用红色加粗线条
• 点击循环节点确认显示完整循环路径
• 多个独立循环确认使用不同颜色区分
• 可并行: 是（与 T33/T34/T37/T40/T42 无依赖）

T40. 阿里云 ASR 后端实现

• 优先级: P2
• 预估工时: 1.5 天
• 依赖: T01（VoiceInput 需先就绪，确保 ASR 接口可用）
• 涉及文件:
• server/services/asr-service.js (修改 — 增加阿里云后端 + 降级链)
• config.yaml (修改 — 新增 asr.aliyun 配置节)
• 编码步骤:

1. 在 asr-service.js 中新增 recognizeAliyun(audioBuffer, format, sampleRate) 方法：

• 阿里云智能语音 REST API 调用
• 使用 AccessKeyId / AccessKeySecret / AppKey 认证
• 支持 PCM/WAV 格式，采样率 16000
• 返回识别文本

1. 修改 asr-service.js 的 recognize() 方法，实现降级链：

• 从 config.yaml 读取 asr.providers 配置（默认 ['iflytek', 'aliyun', 'echo']）
• 按优先级顺序尝试各后端
• 每次降级记录日志：[ASR] 讯飞识别失败，切换到阿里云: ${error.message}

1. 新增 checkProviderHealth(providerName) 方法：

• 对讯飞/阿里云发送轻量级健康检查请求
• 缓存健康状态（5 分钟有效期）
• 请求时优先使用健康检查通过的后端

1. 修改 config.yaml：新增 asr.aliyun 配置节：

     asr:
       provider: iflytek
       providers:
         - name: iflytek
           priority: 1
           enabled: true
         - name: aliyun
           priority: 2
           enabled: true
         - name: echo
           priority: 3
           enabled: true
       aliyun:
         access_key_id: ""
         access_key_secret: ""
         app_key: ""
     

1. 环境变量覆盖：ALIYUN_ASR_ACCESS_KEY_ID / ALIYUN_ASR_ACCESS_KEY_SECRET / ALIYUN_ASR_APP_KEY
2. 保持 /api/asr/recognize 接口格式不变，响应增加 provider 字段

• 验证方法:
• 配置阿里云 ASR 后，讯飞不可用时确认自动切换到阿里云
• 阿里云也不可用时确认降级到 Echo 模式
• 确认响应中 provider 字段正确标注实际使用的后端
• 确认 config.yaml 中 asr.providers 配置生效
• 健康检查日志确认定期执行
• 可并行: 是（与 T33/T34/T37/T39/T42 无依赖）

T41. ASR 降级链路测试与监控

• 优先级: P2
• 预估工时: 0.5 天
• 依赖: T40（阿里云 ASR 后端需先就绪）
• 涉及文件:
• server/services/asr-service.js (修改 — 增加降级统计日志)
• 编码步骤:

1. 在 asr-service.js 中新增降级统计：

• degradeStats = { iflytek: { success: 0, fail: 0 }, aliyun: { success: 0, fail: 0 }, echo: { count: 0 } }
• 每次识别成功/失败时更新统计

1. 新增 GET /api/asr/stats API：返回降级统计数据
2. 新增 console.log 汇总：每 100 次识别输出一次统计摘要
3. 在浏览器 console 中增加详细日志（满足用户偏好 PREFERENCE_2）

• 验证方法:
• 连续调用 ASR 接口，确认降级统计正确
• 调用 GET /api/asr/stats 确认返回统计数据
• 确认浏览器 console 显示 ASR 降级详细日志
• 可并行: 否（依赖 T40）

T42. WebSocket 服务端实现

• 优先级: P2
• 预估工时: 2 天
• 依赖: T17（通知同步服务需先就绪）
• 涉及文件:
• server/services/websocket-service.js (新增)
• server.js (修改 — 集成 WebSocket 升级)
• 编码步骤:

1. 安装 ws 依赖：npm install ws
2. 新增 server/services/websocket-service.js，导出类 WebSocketService
3. 实现 init(httpServer)：

• 创建 WebSocket.Server({ noServer: true })
• 监听 httpServer 的 upgrade 事件，匹配 /ws 路径
• 验证 JWT（从 req.url 的 query 参数或 Sec-WebSocket-Protocol 头获取 token）

1. 实现 handleConnection(ws, req)：

• 从 JWT 解析 userId 和 enterpriseId
• 维护连接映射：connections = Map>
• 维护租户连接映射：tenantConnections = Map>

1. 实现 broadcastToUser(userId, message)：

• 查找 connections.get(userId) 的所有 WebSocket
• 发送 JSON 格式消息：{ type, data, timestamp }

1. 实现 broadcastToTenant(enterpriseId, message)：

• 查找租户下所有在线用户
• 逐用户推送

1. 实现 handleDisconnect(ws)：

• 从连接映射中移除
• 日志记录断连

1. 实现消息补发机制：

• 客户端重连时发送 lastMessageId
• 服务端从 notifications 表查询该 ID 之后的消息并补发

1. 实现心跳保活：

• 服务端每 30 秒发送 ping
• 客户端 10 秒内未响应 pong → 关闭连接

1. 实现连接数限制：

• 单用户最多 5 个连接
• 全局最多 1000 个连接

1. 修改 server.js：

• 在 HTTP 服务器创建后调用 websocketService.init(server)
• 在通知推送时调用 websocketService.broadcastToUser()
• 验证方法:
• 使用 WebSocket 客户端连接 ws://host/ws?token=xxx，确认连接成功
• 发送通知后确认 WebSocket 客户端收到消息
• JWT 无效时确认连接被拒绝
• 断连后重连确认消息补发
• 确认心跳保活正常
• 可并行: 是（与 T33/T34/T37/T39/T40 无依赖）

T43. WebSocket 前端集成

• 优先级: P2
• 预估工时: 1.5 天
• 依赖: T42（WebSocket 服务端需先就绪）
• 涉及文件:
• src/composables/useWebSocket.js (新增)
• src/store/notification.js (修改 — 使用 WebSocket 接收通知)
• src/App.vue (修改 — 初始化 WebSocket 连接)
• 编码步骤:

1. 新增 src/composables/useWebSocket.js：

• 实现 connect(token) — 建立 WebSocket 连接
• 实现 disconnect() — 关闭连接
• 实现 onMessage(handler) — 注册消息处理函数
• 实现 send(data) — 发送消息
• 实现自动重连：断连后 2 秒重试，最多 5 次，指数退避
• 实现降级检测：连接失败后标记 usePolling = true

1. 新增轮询降级逻辑：

• 当 usePolling = true 时，每 5 秒调用 GET /api/notifications 轮询
• WebSocket 重连成功后切换回实时模式

1. 修改 src/store/notification.js：

• 在 store 初始化时调用 useWebSocket.connect(token)
• WebSocket 消息到达时更新 store 状态
• 新通知到达时播放提示音（可选）

1. 修改 src/App.vue：

• 在 onMounted 中初始化 WebSocket 连接
• 在 onUnmounted 中断开连接

1. 添加浏览器 console 详细日志（满足用户偏好 PREFERENCE_2）

• 验证方法:
• 登录后确认 WebSocket 连接建立
• 收到通知后确认 store 状态实时更新
• 断网后确认自动重连
• WebSocket 不可用时确认降级为轮询
• 浏览器 console 显示 WebSocket 连接/断连/重连日志
• 可并行: 否（依赖 T42）

T44. 小程序 WebSocket 集成

• 优先级: P2
• 预估工时: 1 天
• 依赖: T42（WebSocket 服务端需先就绪）、T04（小程序登录需先就绪）
• 涉及文件:
• bossagents-miniapp/src/utils/websocket.js (新增)
• bossagents-miniapp/src/store/index.js (修改 — 集成 WebSocket)
• 编码步骤:

1. 新增 bossagents-miniapp/src/utils/websocket.js：

• 使用 uni.connectSocket() 建立连接
• 实现 connect(token) — uni.connectSocket({ url: 'ws://host/ws?token=xxx' })
• 实现 onMessage(callback) — uni.onSocketMessage(callback)
• 实现自动重连：uni.onSocketError + uni.onSocketClose 触发重连

1. 修改 bossagents-miniapp/src/store/index.js：

• 在 useNotificationStore 中集成 WebSocket
• WebSocket 消息到达时更新通知列表
• 新通知到达时显示 uni.showToast 提示

1. 添加降级逻辑：WebSocket 连接失败时切换到 5 秒轮询

• 验证方法:
• 小程序登录后确认 WebSocket 连接建立
• 收到通知后确认通知列表实时更新
• 断网后确认自动重连
• WebSocket 不可用时确认降级为轮询
• 可并行: 否（依赖 T42，但可与 T43 并行）

T45. 租户配额管理前端界面

• 优先级: P2
• 预估工时: 1.5 天
• 依赖: T36（配额管理 API 需先就绪）
• 涉及文件:
• src/views/AdminQuotaManager.vue (新增)
• src/router/index.js (修改 — 新增配额管理路由)
• src/api/admin.js (新增或修改 — 配额管理 API 调用)
• 编码步骤:

1. 新增 src/views/AdminQuotaManager.vue：

• 顶部：租户选择下拉框 + "批量初始化"按钮
• 主体：配额使用情况表格
• 列：租户名称、Part(当前/上限/占比)、BOM(当前/上限/占比)、用户(当前/上限/占比)、月任务(当前/上限/占比)、操作
• 占比超过 80% 的单元格标黄，超过 100% 标红
• 操作：编辑配额上限（弹窗表单）

1. 实现编辑弹窗：

• 表单字段：maxParts、maxBoms、maxUsers、maxStaffTasks
• 保存时调用 PUT /api/admin/quotas/:enterpriseId
• 新配额低于当前使用量时弹出警告

1. 实现批量初始化：

• 点击"批量初始化" → 确认弹窗
• 调用 POST /api/admin/quotas/init
• 显示初始化结果（新增 N 个租户配额）

1. 实现手动同步：

• 每行操作列增加"同步"按钮
• 调用 POST /api/admin/quotas/:enterpriseId/sync

1. 新增或修改 src/api/admin.js：

• getQuotas() — GET /api/admin/quotas
• getQuota(enterpriseId) — GET /api/admin/quotas/:enterpriseId
• updateQuota(enterpriseId, data) — PUT /api/admin/quotas/:enterpriseId
• initQuotas() — POST /api/admin/quotas/init
• syncQuota(enterpriseId) — POST /api/admin/quotas/:enterpriseId/sync

1. 修改 src/router/index.js：新增 /admin/quotas 路由，需 admin 角色守卫

• 验证方法:
• 管理员打开配额管理页面，确认显示所有租户配额
• 修改配额上限后确认保存成功
• 占比超过 80% 的指标确认标黄
• 非管理员访问确认返回 403
• 批量初始化和手动同步功能正常
• 可并行: 否（依赖 T36）

8. 任务统计与执行计划

8.1 任务统计

| 编号 | 任务名称 | 优先级 | 预估工时 | 依赖 | 可并行 |

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

| T33 | 协作链可视化组件 | P2 | 2天 | T24+T25 | 否 |

| T34 | 租户配额后端服务 | P2 | 1.5天 | T09+T15 | 是 |

| T35 | 租户配额检查中间件集成 | P2 | 1天 | T34 | 否 |

| T36 | 租户配额管理 API | P2 | 0.5天 | T34 | 否(可与T35并行) |

| T37 | 已发布文章后端 | P2 | 1.5天 | T11+T31 | 是 |

| T38 | 已发布文章前端界面 | P2 | 1天 | T37 | 否 |

| T39 | BOM 循环依赖可视化 | P2 | 1.5天 | T22+T07 | 是 |

| T40 | 阿里云 ASR 后端实现 | P2 | 1.5天 | T01 | 是 |

| T41 | ASR 降级链路测试与监控 | P2 | 0.5天 | T40 | 否 |

| T42 | WebSocket 服务端实现 | P2 | 2天 | T17 | 是 |

| T43 | WebSocket 前端集成 | P2 | 1.5天 | T42 | 否 |

| T44 | 小程序 WebSocket 集成 | P2 | 1天 | T42+T04 | 否(可与T43并行) |

| T45 | 租户配额管理前端界面 | P2 | 1.5天 | T36 | 否 |

P2 总工时: 约 16.5 天（单人全栈）

并行执行: 约 6 天（3 条并行轨道）

8.2 推荐执行顺序

第一周（P2 核心，3 条并行轨道）

关键里程碑

8.3 与 P0/P1 的衔接

附录：EARS 验收条件索引

文档状态: 已完成

文件路径: C:\bossagents\docs\spec-p2.md`

下一步: 基于 spec-p2.md 生成 design-p2.md 技术设计文档