左帮右臂 — 需求规格文档（优化方案）

版本: V1.0

日期: 2026-06-24

范围: 基于产品方案设计文档与代码现状差距分析，聚焦 V1.0 补齐 + V1.1 方向

原则: 只写未实现或需优化的具体需求，已完成的不再重复

1. 组件定位

1.1 核心职责

本组件负责补齐左帮右臂平台在语音驱动决策、三端协同、数字员工自动化、关系感知引擎四个维度的功能缺口，实现从"能跑"到"好用"的跃迁。

1.2 核心输入

1. 老板语音指令（小程序/飞书）→ ASR 文本 → 意图识别 → 业务操作
2. BOM Excel 文件 → AI 识别 → 结构化 BOM 树 → 关联匹配
3. 飞书卡片按钮回调 → 审批/确认操作 → 业务系统执行
4. 邮件内容 → 命令解析 → 自动触发采购/审批/通知流程

1.3 核心输出

1. 语音指令的结构化执行结果（决策卡片/审批状态/操作确认）
2. 三端（网页/小程序/飞书）统一的数据视图和操作体验
3. 数字员工间自动协作的任务链和执行报告
4. BOM/ECO/产品的自动关联图谱和完整性评分

1.4 职责边界

• 不做什么: 不实现一人一方体质检测（独立产品线，不在本平台范围）
• 不做什么: 不实现 MTCLAW 推理服务本身（外部服务，本平台只做客户端调用）
• 不做什么: 不实现数据资产交易市场（V2.0 方向，V1.x 只做数据采集和展示）
• 不做什么: 不重构已有架构（统一 Pipeline、SmartLLMRouter、规则引擎已验证通过）

2. 领域术语

语音决策链路

: 从老板说出指令到系统执行完毕的完整路径：语音 → ASR → NLU → 意图路由 → 业务操作 → 结果反馈。

三端统一

: 网页端（Vue 3 SPA）、小程序端（uni-app）、飞书端（Bot + 卡片）共享同一套后端 API 和业务逻辑，前端适配各自交互形态。

决策卡片

: 在飞书/小程序中呈现的结构化操作确认界面，包含关键信息摘要、操作按钮、风险提示。

协作链

: 数字员工之间自动触发的任务接力机制，一个员工完成任务后自动唤醒下一个相关员工。

关系感知

: 在创建/导入/修复 BOM、ECO、Part 时，自动发现已有对象并建立关联的能力。

邮件即指令

: 将收到的邮件内容解析为业务命令（如报价确认、审批通过），自动触发对应流程。

3. 角色与边界

3.1 核心角色

• 企业老板: 通过语音/飞书卡片进行决策审批，不直接操作复杂界面
• 业务操作员: 通过网页端进行 BOM 管理、内容生成、采购操作等深度工作
• 全员协作者: 通过飞书接收通知、执行审批、查看任务状态

3.2 外部系统

• 微信开放平台: 小程序登录授权、订阅消息推送
• 飞书开放平台: 机器人消息、卡片交互、审批流
• 讯飞 iFlytek: 语音识别（ASR）
• 1688 开放平台: 供应商寻源和报价
• SCSAI Agent: PLM 数据存储和业务流程

3.3 交互上下文

@startuml
left to right direction

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

actor "企业老板" as boss
actor "业务操作员" as operator
actor "全员协作者" as collaborator

boss --> platform : 语音指令 / 决策卡片
operator --> platform : BOM管理 / 采购 / 内容生成
collaborator --> platform : 飞书审批 / 通知确认

cloud "微信开放平台" as wechat
cloud "飞书开放平台" as feishu
cloud "讯飞 iFlytek" as iflytek
cloud "1688" as alibaba
database "SCSAI Agent" as SCSAI

platform --> wechat : 小程序登录/消息
platform --> feishu : Bot/卡片/审批
platform --> iflytek : 语音识别
platform --> alibaba : 供应商寻源
platform --> SCSAI : PLM数据读写

@enduml

4. DFX约束

4.1 性能

• 语音识别到意图路由的端到端延迟应当不超过 3 秒（ASR 1.5s + NLU 1.5s）
• 飞书卡片从按钮点击到结果返回应当不超过 5 秒
• BOM Excel 导入（1000 行）到生成 BOM 树应当不超过 30 秒
• 关系发现（100 个对象）的批量处理应当不超过 10 秒

4.2 可靠性

• 飞书 pendingActions 必须持久化，服务重启后不丢失未完成的审批状态
• 语音指令执行失败时，系统必须通过原通道（飞书/小程序）通知用户失败原因
• 邮件监听断连后必须自动重连，重连间隔不超过 30 秒

4.3 安全性

• 小程序微信登录的 JWT secret 禁止使用硬编码默认值
• 飞书事件订阅的加密/解密必须完整实现
• 多租户场景下，所有 SCSAI 查询必须注入 enterprise_id 过滤

4.4 可维护性

• 三端（网页/小程序/飞书）的 API 调用必须走统一的 Pipeline 入口 /api/pipeline/execute
• 所有新增 API 必须在 server.js 的 handleRequest 中注册
• 数字员工新增类型只需修改配置，不需要修改调度器代码

4.5 兼容性

• 微信发布服务的环境变量必须统一为 WECHAT_APP_ID / WECHAT_APP_SECRET，废弃 MINIPROGRAM_APPID / MINIPROGRAM_SECRET
• 小程序 API 必须兼容主服务器的 db-adapter 双后端（SQLite/MySQL）

5. 核心能力

5.1 语音决策链路

5.1.1 业务规则

1. 小程序语音输入接入 ASR: 当用户在小程序端按下"按住说话"按钮并松手后，系统应当录制音频、调用 ASR 服务识别文本、将识别结果发送到对话引擎。

a. 验收条件：[用户在小程序按下并松开语音按钮] → [系统调用 uni.getRecorderManager() 录制 PCM 音频] → [上传至 /api/asr/recognize 端点] → [返回识别文本并显示在聊天输入框]

1. 语音文本意图路由: 当 ASR 返回识别文本后，系统应当通过 ConversationEngine 的意图识别将文本路由到对应数字员工。

a. 验收条件：[ASR 返回"采购100套电机"] → [ConversationEngine 识别意图为 procurement] → [路由到 DS-PROC-001 采购助手] → [返回采购决策卡片]

1. 飞书语音审批执行: 当用户在飞书卡片点击"🎤 语音审批"按钮后，系统应当记录该审批操作并执行对应业务流程。

a. 验收条件：[用户点击飞书卡片"语音审批"按钮] → [系统从 pendingActions 取回挂起操作] → [执行审批（如 ECR 通过/BOM 发布/采购下单）] → [返回审批结果卡片]

1. 禁止项: 语音审批按钮不得出现在无挂起操作的卡片上。

a. 验收条件：[pendingActions 为空时渲染飞书卡片] → [卡片不包含"语音审批"按钮]

5.1.2 交互流程

@startuml
actor 老板
participant "小程序" as miniapp
participant "ASR服务" as asr
participant "对话引擎" as conv
participant "数字员工" as staff
participant "SCSAI" as SCSAI

老板 -> miniapp : 按住说话
miniapp -> miniapp : 录制PCM音频
老板 -> miniapp : 松手
miniapp -> asr : POST /api/asr/recognize (音频)
asr --> miniapp : 识别文本
miniapp -> conv : POST /api/digital-staff/chat (文本)
conv -> conv : 意图识别
conv -> staff : 路由到对应员工
staff -> SCSAI : 执行业务操作
SCSAI --> staff : 操作结果
staff --> conv : 生成回复
conv --> miniapp : 决策卡片/确认请求
miniapp --> 老板 : 展示结果
@enduml

5.1.3 异常场景

1. ASR 服务不可用

a. 触发条件：讯飞 API 超时或返回错误

b. 系统行为：降级到 Echo 模式，根据音频大小返回预设指令文本，同时在回复中标注"语音识别服务暂不可用，已使用模拟输入"

c. 用户感知：聊天界面显示降级提示，但功能不中断

1. 意图识别失败

a. 触发条件：ConversationEngine 无法将文本匹配到任何已知意图

b. 系统行为：路由到默认数字员工（DS-SYS-001），返回"我不太理解您的意思，您可以试试说：采购XXX、查看BOM、生成公告"

c. 用户感知：收到引导性回复，而非错误信息

5.2 小程序三端统一

5.2.1 业务规则

1. 微信登录完整实现: 当用户在小程序端点击"微信一键登录"时，系统应当通过微信 jscode2session 接口获取 openid，创建或查找用户，签发 JWT。

a. 验收条件：[用户点击微信登录] → [调用 uni.login() 获取 code] → [后端调用微信 jscode2session] → [openid 存入 users 表] → [签发 JWT 返回前端]

1. 小程序语音输入完整实现: VoiceInput 组件必须实现录音、上传、识别的完整流程。

a. 验收条件：[用户按下语音按钮] → [调用 uni.getRecorderManager().start() 开始录音] → [松手调用 stop()] → [获取临时音频文件路径] → [上传至 /api/asr/recognize] → [返回文本填入输入框]

1. 小程序页面数据对接: 小程序所有页面必须通过 miniappApi 调用后端真实数据，不得使用硬编码 mock 数据。

a. 验收条件：[打开小程序工作台页面] → [调用 getDashboard() 获取真实统计数据] → [页面显示真实产品数/变更数/规则数/员工数]

1. 三端消息同步: 当网页端/飞书端触发操作时，小程序必须能收到对应通知。

a. 验收条件：[网页端创建 ECR 变更] → [小程序通知列表出现新通知] → [点击通知跳转到变更详情页]

5.2.2 交互流程

@startuml
actor 用户
participant "小程序" as miniapp
participant "微信开放平台" as wx
participant "后端API" as api
participant "数据库" as db

用户 -> miniapp : 点击微信登录
miniapp -> wx : uni.login() → code
wx --> miniapp : code
miniapp -> api : POST /api/miniapp/login {code}
api -> wx : jscode2session(code)
wx --> api : {openid, session_key}
api -> db : INSERT/SELECT users
db --> api : user record
api --> miniapp : {token, user}
miniapp -> miniapp : 存储token到store
miniapp --> 用户 : 跳转到AI对话页
@enduml

5.2.3 异常场景

1. 微信登录配置缺失

a. 触发条件：_config.wx.appId 或 _config.wx.appSecret 未配置

b. 系统行为：使用 dev_ + code 作为 openid 降级登录，在服务端日志中记录警告

c. 用户感知：登录成功但日志标记为开发模式

1. 小程序后端连接失败

a. 触发条件：API 服务器地址不可达

b. 系统行为：显示"无法连接服务器，请检查服务器地址配置"，提供重新配置入口

c. 用户感知：看到错误提示和配置按钮

5.3 飞书集成完善

5.3.1 业务规则

1. pendingActions 持久化: 当飞书 Bot 创建 pendingAction 时，系统应当同时写入持久化存储（SQLite/JSONL），服务重启后自动恢复。

a. 验收条件：[创建 pendingAction] → [写入 feishu_pending_actions 表] → [服务重启] → [从数据库恢复未过期（10分钟内）的 pendingAction] → [用户点击卡片按钮仍可正常执行]

1. 飞书事件订阅加密解密: 当收到飞书事件回调时，系统应当验证签名并解密消息体。

a. 验收条件：[飞书发送加密事件] → [使用 Encrypt Key 解密] → [验证 Verification Token] → [处理事件] → [返回 challenge 响应]

1. 飞书审批流集成: 当业务操作需要审批时，系统应当创建飞书审批实例而非仅发送卡片消息。

a. 验收条件：[ECR 变更需要审批] → [调用飞书审批 API 创建审批实例] → [审批人在飞书审批中心看到待审批项] → [审批通过后回调触发 SCSAI 状态变更]

5.3.2 交互流程

@startuml
participant "飞书" as feishu
participant "飞书Bot" as bot
participant "数据库" as db
participant "SCSAI" as SCSAI

feishu -> bot : 卡片按钮回调 {action, pending_id}
bot -> db : SELECT * FROM feishu_pending_actions WHERE id = pending_id
db --> bot : pendingAction 数据
bot -> bot : 验证未过期
bot -> SCSAI : 执行业务操作
SCSAI --> bot : 操作结果
bot -> db : DELETE FROM feishu_pending_actions WHERE id = pending_id
bot -> feishu : 更新卡片状态
@enduml

5.3.3 异常场景

1. pendingAction 已过期

a. 触发条件：用户点击卡片按钮时 pendingAction 已超过 10 分钟 TTL

b. 系统行为：返回"该操作已超时，请重新发起"

c. 用户感知：卡片更新为"已超时"状态

1. 飞书审批创建失败

a. 触发条件：飞书审批 API 返回错误

b. 系统行为：降级为卡片消息确认模式，记录降级原因

c. 用户感知：收到卡片消息而非审批中心通知

5.4 采购流程端到端

5.4.1 业务规则

1. 采购订单创建与跟踪: 当采购比价完成并获老板审批后，系统应当创建采购订单（PO）并跟踪交付状态。

a. 验收条件：[老板审批通过采购方案] → [系统创建 PO 记录（含供应商/数量/价格/交付日期）] → [PO 状态为"待确认"] → [供应商确认后状态变为"已确认"] → [交付后状态变为"已完成"]

1. 1688 降级体验优化: 当 1688 API Key 未配置或调用失败时，系统应当提供明确的降级提示而非静默降级到 Mock。

a. 验收条件：[1688 API 不可用] → [返回"1688 接口暂不可用，已使用 AI 智能寻源替代"] → [调用 SmartLLMRouter 的 LLM 寻源能力] → [结果标注"AI 推荐仅供参考"]

1. 报价邮件自动解析增强: 当收到供应商报价邮件时，系统应当自动提取结构化报价并关联到对应采购任务。

a. 验收条件：[收到报价邮件] → [EmailListener 触发 newEmail 事件] → [llm-quotation-service 解析结构化报价] → [报价数据关联到 staff_tasks 中的采购任务] → [任务看板更新为"已收到报价"]

5.4.2 交互流程

@startuml
actor 老板
participant "飞书/小程序" as client
participant "采购助手" as proc
participant "1688/LLM" as sourcing
participant "邮件服务" as email
participant "任务看板" as board

老板 -> client : "采购100套电机"
client -> proc : 路由到采购助手
proc -> sourcing : 发起寻源请求
sourcing --> proc : 供应商列表+报价
proc -> board : 创建采购任务(待审批)
proc -> client : 比价决策卡片
老板 -> client : 审批通过
client -> proc : 确认采购
proc -> email : 发送采购订单邮件
proc -> board : 更新任务状态(已下单)
@enduml

5.4.3 异常场景

1. 所有寻源渠道均不可用

a. 触发条件：1688 API、LLM 寻源、本地数据库均无法返回结果

b. 系统行为：返回"暂无供应商信息，建议手动添加供应商后重新询价"

c. 用户感知：收到明确提示和操作建议

5.5 BOM 管理增强

5.5.1 业务规则

1. BOM Excel 导入: 当用户上传 Excel/CSV 文件时，系统应当解析文件内容、通过 AI 识别列映射、生成结构化 BOM 数据。

a. 验收条件：[用户在 BomAssistant 页面上传 Excel 文件] → [后端解析 Excel（xlsx 库）] → [AI 识别列名到 BOM 字段的映射（item_number/name/quantity/material）] → [生成 BOM 树结构] → [前端展示 BOM 树]

1. BOM 多层级图形化展示: 当用户查看 BOM 详情时，系统应当提供图形化的树形结构展示。

a. 验收条件：[用户点击 BOM 条目] → [前端渲染可展开/收起的树形图（节点=零件，边=父子关系）] → [支持缩放和拖拽] → [点击节点显示零件详情]

1. BOM 与工业对象库自动匹配: 当导入 BOM 数据时，系统应当自动在 SCIOT 工业对象库中查找匹配对象。

a. 验收条件：[BOM 导入完成] → [RelationshipResolver.resolveExistence 对每个零件执行三级检测] → [匹配到的零件标注"已关联"并链接到 SCSAI 对象] → [未匹配的零件标注"待确认"]

5.5.2 交互流程

@startuml
actor 用户
participant "BomAssistant" as bom
participant "后端API" as api
participant "AI识别" as ai
participant "关系解析器" as resolver
participant "SCSAI" as SCSAI

用户 -> bom : 上传Excel文件
bom -> api : POST /api/bom/import/upload (file)
api -> ai : 解析Excel + 列映射识别
ai --> api : 结构化BOM数据
api -> resolver : resolveExistence(每个零件)
resolver -> SCSAI : 查询已存在对象
SCSAI --> resolver : 匹配结果
resolver --> api : 关联计划
api --> bom : BOM树 + 匹配状态
bom --> 用户 : 展示BOM树(已关联/待确认)
@enduml

5.5.3 异常场景

1. Excel 列名无法识别

a. 触发条件：AI 无法将 Excel 列名映射到 BOM 标准字段

b. 系统行为：返回列映射建议，让用户手动确认映射关系

c. 用户感知：看到映射确认界面，可手动调整

1. BOM 循环依赖检测

a. 触发条件：BOM 树中存在 A→B→A 的循环引用

b. 系统行为：拒绝导入并提示"检测到循环依赖：A→B→A，请检查数据"

c. 用户感知：收到明确的错误提示和循环路径

5.6 数字员工自动化协作

5.6.1 业务规则

1. 员工间自动协作编排: 当一个数字员工完成任务后，系统应当根据协作规则自动触发下一个相关员工。

a. 验收条件：[DS-PROC-001 采购助手完成询价] → [系统根据协作规则自动触发 DS-COST-001 成本优化师进行成本分析] → [成本优化师完成后触发 DS-VEN-001 供应商管家进行供应商评估] → [任务看板显示完整协作链]

1. 协作规则配置驱动: 协作链的触发规则应当通过 YAML 配置定义，不需要修改代码。

a. 验收条件：[在 digital-staff/collaboration-rules.yaml 中定义 DS-PROC-001 → DS-COST-001] → [采购任务完成后自动触发成本分析] → [修改 YAML 规则后无需重启服务即生效]

1. 协作链可视化: 当协作链执行时，任务看板应当显示完整的任务链路和当前执行节点。

a. 验收条件：[协作链启动] → [任务看板显示链路图：采购询价(✓) → 成本分析(进行中) → 供应商评估(待执行)] → [每个节点可点击查看详情]

5.6.2 交互流程

@startuml
participant "采购助手" as proc
participant "协作调度器" as scheduler
participant "成本优化师" as cost
participant "供应商管家" as vendor
participant "任务看板" as board

proc -> board : 完成询价任务
board -> scheduler : 触发协作规则
scheduler -> scheduler : 查找 DS-PROC-001 的后继规则
scheduler -> cost : 创建成本分析任务
cost -> board : 完成成本分析
board -> scheduler : 触发协作规则
scheduler -> vendor : 创建供应商评估任务
vendor -> board : 完成供应商评估
@enduml

5.6.3 异常场景

1. 协作链中某环节失败

a. 触发条件：成本优化师执行失败

b. 系统行为：暂停协作链，通知发起人"成本分析失败，协作链已暂停"，提供重试和跳过选项

c. 用户感知：收到飞书/小程序通知，可选择重试或跳过该环节

1. 协作规则循环检测

a. 触发条件：YAML 配置了 A→B→A 的循环规则

b. 系统行为：启动时校验规则图，检测到环则拒绝加载并记录错误日志

c. 用户感知：服务启动时日志显示"协作规则存在循环：A→B→A，已跳过"

5.7 关系感知引擎（V1.1）

5.7.1 业务规则

1. BOM 自动关联: 当创建或导入 BOM 时，系统应当自动发现已有的 Part 对象并建立 BOM 关系。

a. 验收条件：[导入包含"电机-A"的 BOM] → [RelationshipResolver.resolveExistence 检测到 SCSAI 中已存在"电机-A"] → [自动创建 BOM 关系而非重复创建 Part] → [日志记录关联操作]

1. ECO 自动关联: 当创建工程变更订单（ECO）时，系统应当自动关联受影响的 BOM、Part 和文档。

a. 验收条件：[创建 ECO 变更"修改电机-A 规格"] → [RelationshipCapability.identifyRelations 识别到关联的 BOM 和 Part] → [自动创建 ECO→BOM、ECO→Part 关系] → [变更影响分析报告包含所有关联对象]

1. 产品自动关联: 当创建产品时，系统应当自动关联其下的所有 BOM、文档和供应商。

a. 验收条件：[创建产品"磷化工设备-A"] → [discoverRelations 发现关联的 3 个 BOM 和 5 个文档] → [buildLinkPlan 生成关联执行计划] → [执行后产品详情页显示完整关联图谱]

1. 关系完整性评分: 当对象创建完成后，系统应当根据 RelationshipChecklist 计算完整性评分。

a. 验收条件：[Part 创建完成] → [postValidate 检查必需关系（BOM 父件、文档、供应商）] → [3/5 必需关系已建立 → 完整性评分 60%] → [提示"建议补充：供应商关联、质量文档" ]

5.7.2 交互流程

@startuml
actor 用户
participant "创建能力" as create
participant "关系解析器" as resolver
participant "关系能力" as relCap
participant "检查清单" as checklist
participant "SCSAI" as SCSAI

用户 -> create : 创建BOM/ECO/产品
create -> resolver : resolveExistence(对象数据)
resolver -> SCSAI : 三级检测(精确→模糊→私有库)
SCSAI --> resolver : 存在性结果
create -> resolver : discoverRelations(批量对象)
resolver -> relCap : identifyRelations
relCap --> resolver : 候选关系列表
create -> resolver : buildLinkPlan(对象+关系)
resolver --> create : 关联执行计划
create -> SCSAI : 执行关联AML
create -> checklist : postValidate(已创建对象)
checklist --> create : 完整性评分+建议
create --> 用户 : 创建结果+关联状态+完整性评分
@enduml

5.7.3 异常场景

1. 关系发现无结果

a. 触发条件：新创建的对象在 SCSAI 中无任何匹配

b. 系统行为：标记为"孤立对象"，完整性评分为 0%，提示"建议手动关联"

c. 用户感知：看到"孤立对象"标记和关联建议

1. 批量关联部分失败

a. 触发条件：批量创建 10 个关系，其中 3 个因 SCSAI 权限问题失败

b. 系统行为：成功 7 个，失败 3 个记录错误日志，返回部分成功结果和失败原因

c. 用户感知：看到"7/10 关联成功"和失败项的错误详情

5.8 邮件即指令（V1.2 方向）

5.8.1 业务规则

1. 通用邮件命令解析: 当收到邮件时，系统应当尝试将邮件内容解析为业务命令，而非仅限于采购报价识别。

a. 验收条件：[收到标题为"ECR-2026-001 审批通过"的邮件] → [EmailListener 触发] → [命令解析器识别为"审批通过"命令] → [自动执行 ECR 状态变更] → [通知相关人]

1. 邮件命令模板配置: 邮件命令的匹配规则应当通过 YAML 配置定义。

a. 验收条件：[在 email-commands.yaml 中定义 subject.contains("审批通过") → action: ecr_approve] → [收到匹配邮件时自动触发审批] → [修改 YAML 后无需重启即生效]

1. 邮件监听 IMAP 配置化: EmailListener 的 IMAP 服务器地址应当从配置读取，而非硬编码 imap.sina.com。

a. 验收条件：[config.yaml 中配置 email.imap.host: imap.qq.com] → [EmailListener 连接到 imap.qq.com] → [未配置时使用默认 imap.sina.com]

5.8.2 交互流程

@startuml
participant "邮件服务器" as imap
participant "邮件监听" as listener
participant "命令解析器" as parser
participant "业务执行器" as executor
participant "通知服务" as notify

imap -> listener : 新邮件推送
listener -> parser : 解析邮件内容
parser -> parser : 匹配命令模板
parser -> executor : 执行对应业务操作
executor --> parser : 执行结果
parser -> notify : 发送执行结果通知
notify --> listener : 飞书/小程序通知
@enduml

5.8.3 异常场景

1. 邮件命令无法匹配

a. 触发条件：邮件内容不匹配任何已知命令模板

b. 系统行为：将邮件归档为"未识别"，不触发任何操作

c. 用户感知：无感知（静默处理，管理员可在日志中查看）

1. IMAP 连接持续失败

a. 触发条件：连续 5 次重连均失败

b. 系统行为：停止重连，发送飞书告警给管理员"邮件监听服务已停止"

c. 用户感知：管理员收到飞书告警

5.9 多租户安全加固

5.9.1 业务规则

1. 租户中间件自动注入: 当 API 请求到达时，系统应当从 JWT 中提取 enterprise_id 并自动注入到所有 SCSAI 查询中。

a. 验收条件：[租户 A 的用户查询 Part 列表] → [中间件从 JWT 提取 enterprise_id=ent_A] → [SCSAI 查询 AML 自动添加 ent_A 过滤] → [只返回租户 A 的数据]

1. 租户数据隔离验证: 当执行任何数据操作时，系统应当验证操作对象的 enterprise_id 与当前用户的 enterprise_id 一致。

a. 验收条件：[租户 A 的用户尝试访问 enterprise_id=ent_B 的 Part] → [中间件拦截] → [返回 403 Forbidden] → [记录越权访问审计日志]

1. 租户配额限制: 当租户创建数据时，系统应当检查是否超过配额限制。

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

5.9.2 交互流程

@startuml
participant "客户端" as client
participant "租户中间件" as middleware
participant "业务处理" as handler
participant "SCSAI" as SCSAI

client -> middleware : 请求 (JWT含enterprise_id)
middleware -> middleware : 提取enterprise_id
middleware -> middleware : 验证数据隔离
middleware -> handler : 注入enterprise_id上下文
handler -> SCSAI : 查询(含enterprise_id过滤)
SCSAI --> handler : 结果(仅当前租户数据)
handler --> client : 响应
@enduml

5.9.3 异常场景

1. JWT 中无 enterprise_id

a. 触发条件：用户 JWT 中未包含 enterprise_id 字段

b. 系统行为：标记为"公共租户"，使用默认 enterprise_id=default

c. 用户感知：正常使用，但只能看到公共数据

5.10 微信发布服务统一

5.10.1 业务规则

1. 环境变量统一: 当系统启动时，微信发布相关的环境变量必须统一为 WECHAT_APP_ID / WECHAT_APP_SECRET，废弃 MINIPROGRAM_APPID / MINIPROGRAM_SECRET。

a. 验收条件：[配置 WECHAT_APP_ID 和 WECHAT_APP_SECRET] → [wechat-publish.js 和 content-api.js 均使用统一变量] → [MINIPROGRAM_* 变量不再生效] → [启动时日志提示"微信配置已统一"]

1. 发布失败自动重试: 当微信发布失败时，系统应当自动重试最多 3 次。

a. 验收条件：[微信 API 返回 500 错误] → [系统等待 5 秒后重试] → [最多重试 3 次] → [3 次均失败后标记为"发布失败"并通知用户]

1. 已发布文章管理: 当文章发布成功后，系统应当记录发布 ID，支持后续查询和管理。

a. 验收条件：[文章发布成功] → [记录 publish_id 和 publish_time] → [内容列表页显示"已发布"状态] → [支持查看发布链接]

5.10.2 异常场景

1. 微信 Token 刷新失败

a. 触发条件：微信 access_token 刷新接口返回错误

b. 系统行为：使用缓存的旧 token（如未过期），若旧 token 也过期则暂停发布功能

c. 用户感知：发布按钮显示"微信服务暂不可用"

6. 数据约束

6.1 采购订单（PurchaseOrder）

1. poId: 唯一标识，格式 PO-{YYYYMMDD}-{seq4}
2. supplierId: 关联供应商 ID，必填
3. items: 采购项列表（JSON 数组），每项含 partNumber/quantity/unitPrice/currency
4. status: 枚举值：draft / pending_approval / approved / confirmed / shipped / completed / cancelled
5. totalAmount: 自动计算自 items 的汇总金额
6. approvedBy: 审批人 ID，审批后必填
7. approvedAt: 审批时间，审批后必填
8. deliveryDate: 预计交付日期，格式 ISO 8601

6.2 飞书挂起操作（FeishuPendingAction）

1. id: UUID，主键
2. action: 操作类型，枚举值：approve / reject / confirm / cancel
3. businessType: 业务类型，枚举值：ecr / bom / procurement / vendor
4. businessId: 业务对象 ID
5. userId: 发起人 ID
6. feishuUserId: 飞书用户 open_id
7. cardMessageId: 飞书卡片消息 ID
8. payload: 操作参数（JSON）
9. createdAt: 创建时间
10. expiresAt: 过期时间，createdAt + 10 分钟
11. consumedAt: 消费时间，消费后必填

6.3 协作规则（CollaborationRule）

1. sourceStaffId: 触发员工 ID，如 DS-PROC-001
2. targetStaffId: 目标员工 ID，如 DS-COST-001
3. triggerCondition: 触发条件，如 task_status=completed
4. triggerEvent: 触发事件，枚举值：task_completed / task_failed / task_escalated
5. delaySeconds: 延迟执行秒数，默认 0
6. enabled: 是否启用，布尔值

6.4 邮件命令模板（EmailCommandTemplate）

1. name: 模板名称，如 ecr_approve
2. subjectPattern: 主题匹配正则，如 /审批通过/
3. bodyPattern: 正文匹配正则（可选）
4. action: 触发动作，如 ecr.approve
5. params: 动作参数模板（支持从邮件内容提取变量）
6. priority: 优先级，数字越小越先匹配
7. enabled: 是否启用

6.5 租户配额（TenantQuota）

1. enterpriseId: 租户 ID
2. maxParts: Part 数量上限，默认 10000
3. maxBoms: BOM 数量上限，默认 1000
4. maxUsers: 用户数量上限，默认 50
5. maxStaffTasks: 月度数字员工任务上限，默认 5000
6. currentParts: 当前 Part 数量（系统自动维护）
7. currentBoms: 当前 BOM 数量（系统自动维护）

附录：需求优先级总览

P0 总工时: 约 21.5 天

P1 总工时: 约 24 天

P2 总工时: 约 6 天

总计: 约 51.5 天（单人全栈）