OPC 商事代理：智能体操作指南
版本：2026.09
适用对象：Hermes Agent、OPC 大模型工具编排人员、项目运营人员、审批人、管理员和集成工程师

一、定位与原则
OPC 商事代理是 AI-OPC 体系面向现实商业世界的受控编排层，连接项目、法律主体、账户、交易、税务台账和商务通信，但不替代工商、银行、支付、财税、法律或审计机构。
核心原则：智能体可以理解和起草，系统负责约束，授权自然人负责决定，现实服务商负责执行，平台负责留下证据。
生产环境必须有真实合同、生产凭据、沙箱 UAT、恢复演练和发布审批。未满足条件时，写能力保持阻断或转人工代办。

二、入口与统一登录
1. PC 用户端：https://opcshangshi.yizhangkj.com/pc/；项目运营人员使用。
2. PC 管理后台：https://opcshangshi.yizhangkj.com/admin/；合规、财务和管理员使用。
3. 移动 H5：https://opcshangshi.yizhangkj.com/uniapp/；审批和移动值守使用。
三个入口共用商事代理会话和租户边界，不要创建或拼接另一套用户 ID、租户 ID 或角色。

正式微信认证流程：
1. 前端 POST /api/v1/commercial/auth/wechat/h5/start，带 surface=pc、admin 或 mobile。
2. 服务端生成一次性 session_token、client_state 和场景值，跳转 AI-OPC 社区/IAM 与授权中心 shouquan_new。
3. 授权回调后，前端只提交 code、client_state、scene 和本次 session_token 到 POST /api/v1/commercial/auth/platform-login。
4. 服务端校验场景、会话、有效期和签名，向社区 IAM 交换统一身份后签发商事代理 JWT。
5. 前端以 /auth/me 验证会话，再加载业务数据。
PC 和管理后台配置允许时可使用：
POST /api/v1/commercial/auth/wechat/qr/start
POST /api/v1/commercial/auth/wechat/qr/poll
POST /api/v1/commercial/auth/wechat/qr/cancel
二维码 token 绑定发起端指纹，过期、取消或确认后不能重放。生产禁止用户名/密码直登；不要记录 token、授权 code 或密钥。

统一身份字段：
- subject_id：跨项目统一用户主体。
- tenant_id：商事数据隔离边界。
- roles/scopes：服务端计算的角色和权限，客户端不能追加。

角色：
- commercial_operator：commercial:read、commercial:write；建档、发起操作和读取本租户事实。
- commercial_approver：commercial:read、commercial:approve；查看审批并批准/驳回。
- commercial_admin：以上全部及 commercial:admin；冻结/释放、Outbox、集成状态和审计。
管理后台不会因 surface=admin 自动授予管理员权限，IAM 必须明确授权；审批人不能审批自己发起的高风险操作。

三、智能体运行链路
用户目标/Agent 提案 -> 参数规范化 -> 租户、权限、项目校验 -> 参数哈希与幂等键 -> L1/L2 本地记录或 L3/L4 待审批 -> 授权自然人复核 -> approved/rejected/frozen -> 生产 gate 通过后交给 Naive/持牌服务商 -> webhook 验签、轮询对账 -> operation、台账、Outbox 和审计链沉淀。
“已提交”“处理中”“结果未知”“已完成”不可混用；没有可核验回执时必须保留 processing/unknown。

四、能力与风险
- commercial.project.upsert：L1，local；建立项目引用，同租户 project_ref 幂等更新。
- commercial.legal_entity.create：L4，legal；只提交申请，等待独立审批，不得声称已完成登记。
- commercial.account.open：L4，legal；校验主体和币种后申请开户。
- commercial.transaction.collect：L2/L3，local/payment；小额可本地入账，超过阈值或涉及外部支付需审批。
- commercial.transaction.payment：L4，payment；授权自然人批准，金额、收款方、用途变化须重新审批。
- commercial.communication.send：L3，communication；内容、接收方和模板固定后申请审批，默认不直发。
- commercial.tax_ledger.upsert：L2，local；归集事实和凭证，不等同于自动报税。
登录后通过 GET /api/v1/commercial/mcp/tools 获取能力清单。

五、操作前检查
- 当前 JWT 有效，tenant_id 与项目一致。
- project_id、entity_id、account_id 属于当前租户。
- 高风险请求包含目的、金额/币种、对象、期限和责任人。
- 写请求使用稳定 idempotency_key；同一键只能同参数重放。
- 不把身份证、完整银行卡号、微信 token、授权 code 或密钥放入 prompt、日志或正文。
- 先读状态再重试；unknown 不得盲目重复扣款或发信。

六、推荐提案字段
{
  "name": "commercial.transaction.payment",
  "tenant_id": "从当前会话读取",
  "project_id": "project-id",
  "entity_id": "entity-id",
  "account_id": "account-id",
  "arguments": {"amount": "12800.00", "currency": "CNY", "destination": "供应商账户引用", "purpose": "2026-09 园区运维服务费"},
  "idempotency_key": "payment-project-id-202609-001",
  "expected_risk_level": "L4",
  "requires_human_approval": true
}
accepted 只代表接收和初步校验，不代表已付款。

七、审批复核
1. 核对项目、主体、账户和租户。
2. 核对金额、币种、收款方、用途、通信接收方和税务期间。
3. 确认发起人和审批人分离、审批未过期。
4. 核对 parameter_hash；参数变化应驳回原单并重新发起。
5. 明确批准或驳回，驳回写明原因。
服务端以 JWT 主体写入 approver_id，忽略客户端冒名字段；审批只能决定一次。

八、状态与异常
- pending_approval：等待审批，告知编号，不重试。
- approved：已批准，等待执行/回执。
- processing：执行中，等待回执，不能宣称完成。
- succeeded：有可核验回执，引用 operation、receipt、trace_id。
- rejected：展示原因，修改后生成新键。
- expired：重新发起，不复用旧 code/token。
- frozen：停止重试，联系管理员。
- unknown：转异常对账，禁止重复副作用。

常见错误：
- WEB_AUTH_DISABLED：认证关闭，联系运维。
- WECHAT_CONTEXT_REQUIRED/WECHAT_EXCHANGE_EXPIRED：清理授权状态后重新登录。
- ADMIN_AUTHORIZATION_REQUIRED：当前身份没有管理员授权。
- SELF_APPROVAL_FORBIDDEN：更换独立审批人。
- OPERATION_IDEMPOTENCY_CONFLICT：参数变化需新幂等键。
- AUTH_REVOKED 或 401：清理会话并重新授权。
- *_SIGNATURE_INVALID：停止接收/重试，检查密钥、原始请求体和时钟。
- webhook 缺失或 unknown：不重复扣款/发信，进入对账。

九、协同项目边界
- opcdamoxing：Hermes Agent、多智能体和 FastGPT；只生成结构化提案。
- aiopcshequ：统一 IAM、用户、租户和项目上下文。
- bangong：任务、文档、会议、审批和通知；Office 事件必须签名并带幂等键。
- Naive/持牌服务商：工商、银行、支付、财税和通信执行；请求签名、Webhook 验签、防重放、轮询对账。
智能体不得绕过商事代理直接写 Naive 或数据库。跨项目调用保留 trace_id、operation_id、租户引用和来源系统。

十、安全红线
- 禁止 AI 完全自治设立企业、开户、付款、报税、开票或发送正式商务承诺。
- 禁止客户端覆盖 tenant_id、approver_id、actor_id。
- 禁止跨租户读取或猜测资源 ID。
- 禁止复用微信 code、client state、二维码 token 或审批单。
- 禁止把 mock、未签合同或未完成 UAT 展示为生产成功。
- 禁止公开 token、签名密钥、完整账户和个人信息。

十一、学习验收
1. 了解提案、校验、审批、执行、沉淀责任链。
2. 在三个入口用微信/IAM 登录，确认同一 subject_id 和租户。
3. 只读查看能力和状态，练习区分 pending_approval、processing、unknown、succeeded。
4. 隔离租户中用固定幂等键重复提交，确认不重复建单。
5. 用两个账号演练审批分离、过期、驳回、冻结和释放。
6. 沙箱验证签名回调、Webhook 重放、Outbox redrive 和审计导出。
7. 通过生产预检、恢复演练、合同和 UAT 后再开放真实写能力。

官网：https://opcshangshi.yizhangkj.com/
能力清单（登录后）：GET /api/v1/commercial/mcp/tools
健康状态：GET /health/live、GET /health/ready

本指南是操作和学习材料，不构成法律、税务、审计、投资或支付建议。