# ============================================================ # FastAPI 应用与路由（moduleId: gateway-app, 可重生 ✅） # 端点清单： # POST /api/chat 对话（SSE 流：meta/intent/token/command/block/done） # GET /api/world/summary KPI 摘要 # GET /api/world/gantt 甘特视图数据 # GET /api/world/load 负荷热力数据 # GET /api/world/due 交期承诺看板数据 # GET /api/orders 订单管理页数据（订单 + 成品选项） # POST /api/orders/stage 订单写入动作暂存确认卡（order.upsert/cancel/complete） # GET /api/master 主数据管理页数据（资源树/物料BOM/日历维保） # POST /api/master/stage 主数据写入动作暂存确认卡（master.*.upsert） # GET /api/mrp MRP 建议单（采购/委外，订单分解产物） # POST /api/mrp/decompose 订单分解（P1：产出 DRAFT 建议） # GET /api/timeline 时间线导轨（检查点 + 版本，§4.4） # POST /api/actions/confirm 确认卡回传（批准/驳回 P2 动作） # POST /api/actions/scenario/apply 采用某个沙盒方案（P1 正式排产） # GET /api/gov/pending 门禁管理台·待审批队列（§6.10.2） # GET /api/gov/audit 门禁管理台·审计链 + 完整性校验（§3.6） # GET /api/gov/modules 重生中心·可重生模块注册表（§6.10.3） # GET /api/gov/policy 门禁管理台·权力矩阵投影（M2.5，docs/architecture/harness.md 的 API 化） # GET /api/gov/tests 重生中心·黄金测试看板（M2.5，读缓存 / ?run=true 重跑） # GET /api/settings/llm 设置中心·LLM Provider 状态（M2.5） # GET /api/knowledge/assets 知识资产清单（M3 §8.1） # GET /api/knowledge/assets/{id} 单个知识资产全文（M3） # GET /api/reports/{type} 报告导出（Markdown 下载，M3 §9.10） # ⚠ 文档同步铁律（plan.md §12.9）：新增端点必同步 docs/architecture/harness.md 只读端点备案 # ============================================================ from __future__ import annotations # 前向类型引用 import asyncio # 流式分片的微延时 import json # SSE 载荷序列化 import uuid # 会话 ID 生成 from typing import Any, AsyncIterator # 类型标注 from fastapi import FastAPI # Web 框架 from fastapi.middleware.cors import CORSMiddleware # 跨域（开发期前端直连用） from fastapi.responses import StreamingResponse # SSE 响应 from pydantic import BaseModel, Field # 请求体契约 from server.agent_core import harness # 门禁（待审批队列投影） from server.agent_core.intent import recognize # 意图两级管线 from server.agent_core.registry import scan_modules, verify_audit_chain # 注册表与审计校验 from server.aps_domain.views import due_view, gantt_view, load_view, world_summary # 世界视图 from server.aps_domain.workflow import execute_confirmed, handle_intent # 工作流编排 from server.aps_domain.orders import confirmation_for_order_action, list_orders, list_products from server.aps_domain.masterdata import MASTER_ACTIONS, confirmation_for_master_action, master_overview from server.aps_domain.mrp import decompose_orders, list_mrp, summarize_decomposition from server.contracts import IntentResult # 方案采用时构造意图 from server.state.checkpoints import get_checkpoints # 成对快照仓（时间线） from server.state.store import get_store # 世界状态单例 # ---------------- 请求体契约 ---------------- class ChatRequest(BaseModel): """对话请求：会话 ID（可空=新会话）+ 用户文本。""" sessionId: str | None = None # 会话 ID（M1 仅作标识与审计维度） text: str = Field(min_length=1, max_length=500) # 用户口令（限长防滥用） class ConfirmRequest(BaseModel): """确认卡回传：确认 ID + 批准与否。""" sessionId: str | None = None # 会话 ID（审计维度） confirmId: str # 待确认动作的一次性令牌 approve: bool # True=批准执行 False=驳回 class ScenarioApplyRequest(BaseModel): """采用沙盒方案：策略 + 引擎（引擎确定性 → 重跑即得卡片同款结果）。""" sessionId: str | None = None # 会话 ID（审计维度） strategy: str # 选中方案的策略模板 engine: str = "RULE" # 引擎类型 class OrderStageRequest(BaseModel): """订单管理写入动作：只暂存确认卡，不直接改世界。""" sessionId: str | None = None # 发起会话 action: str # order.upsert / order.cancel / order.complete payload: dict[str, Any] = Field(default_factory=dict) # 订单载荷 class MasterStageRequest(BaseModel): """主数据维护写入动作：只暂存确认卡，不直接改世界（MD-01/02/03）。""" sessionId: str | None = None # 发起会话 action: str # master.line/material/maintenance/bom/routing.upsert payload: dict[str, Any] = Field(default_factory=dict) # 主数据载荷 class MrpDecomposeRequest(BaseModel): """订单分解请求（P1：产出 DRAFT 采购/委外建议）。""" sessionId: str | None = None # 发起会话 orderNo: str | None = None # 指定订单号；空=全部可排产订单 # ---------------- SSE 工具 ---------------- def _sse(payload: dict[str, Any]) -> str: """把一个事件对象编码为 SSE 帧（data: {json}\\n\\n）。""" return "data: " + json.dumps(payload, ensure_ascii=False) + "\n\n" # 标准 SSE 数据帧 def create_app() -> FastAPI: """应用工厂：注册中间件与全部路由。""" app = FastAPI(title="APS Planning Agent", version="0.1.0") # 应用实例 app.add_middleware( # 开发期放开跨域（生产由网关收紧） CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"]) # ---------------- 对话：SSE 会话流 ---------------- @app.post("/api/chat") async def chat(req: ChatRequest) -> StreamingResponse: """一轮对话（权力等级：随意图而定；本端点只编排不执行 P2）。""" store = get_store() # 世界状态 session_id = req.sessionId or uuid.uuid4().hex[:12] # 会话 ID（缺省新建） async def stream() -> AsyncIterator[str]: # SSE 事件生成器 yield _sse({"type": "meta", "sessionId": session_id}) # ① 会话元信息 try: intent = await recognize(req.text, store.data) # ② 意图识别（两级管线） yield _sse({"type": "intent", "intent": intent.model_dump()}) # ③ 意图作为协议证据下发 reply = await handle_intent(store, session_id, intent) # ④ 工作流执行（P0/P1 直通，P2 出卡） for i in range(0, len(reply.text), 24): # ⑤ 正文分片（打字机流式感） yield _sse({"type": "token", "text": reply.text[i:i + 24]}) # 24 字符一片 await asyncio.sleep(0.02) # 微延时（不阻塞事件循环） for cmd in reply.commands: # ⑥ 视口命令逐条下发 yield _sse({"type": "command", "command": cmd.model_dump()}) for block in reply.blocks: # ⑦ UI 块（确认卡等）逐条下发 yield _sse({"type": "block", "block": block.model_dump()}) except Exception as exc: # 兜底：任何异常转为 error 事件（连接不中断） yield _sse({"type": "error", "message": f"处理失败：{exc}"}) yield _sse({"type": "done"}) # ⑧ 结束标记 return StreamingResponse(stream(), media_type="text/event-stream", # SSE 响应 headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}) # ---------------- 世界视图（P0 只读） ---------------- @app.get("/api/world/summary") async def summary() -> dict: """KPI 摘要（视口工具栏）。""" return world_summary(get_store().data) # 直接投影 @app.get("/api/world/gantt") async def gantt() -> dict: """甘特视图数据（最新版本工单 + 骨架 + 标记）。""" return gantt_view(get_store().data) # 直接投影 @app.get("/api/world/load") async def load(days: int = 14) -> dict: """负荷热力数据（产线 × 未来 N 天）。""" return load_view(get_store().data, days=days) # 直接投影 @app.get("/api/world/due") async def due() -> dict: """交期承诺看板数据。""" return {"rows": due_view(get_store().data)} # 包一层便于扩展 # ---------------- 订单管理（P0 读；P2 写经确认卡） ---------------- @app.get("/api/orders") async def orders() -> dict: """订单管理页数据：销售订单列表 + 成品下拉选项。""" world = get_store().data return {"orders": list_orders(world), "products": list_products(world), "statuses": ["SUBMITTED", "CONFIRMED", "CANCELLED", "COMPLETED"], "levels": ["VIP", "A", "B", "C"]} @app.post("/api/orders/stage") async def order_stage(req: OrderStageRequest) -> dict: """订单写入动作暂存为确认卡（P2 唯一路径仍是 /api/actions/confirm）。""" if req.action not in ("order.upsert", "order.cancel", "order.complete"): return {"error": "不支持的订单动作"} store = get_store() title, lines = confirmation_for_order_action(store.data, req.action, req.payload) block = harness.stage_confirmation(req.sessionId or "web", req.action, req.payload, title=title, summary_lines=lines) write_action = req.action + ".stage" from server.agent_core.audit import write_audit write_audit(store.data, store.next_id, actor=req.sessionId or "web", category="GATE", action=write_action, target={"type": "SALES_ORDER", "id": req.payload.get("id")}, power="P2", rationale={"confirmId": block.props["confirmId"]}) store.save() return {"message": f"{title} 已进入 P2 确认队列。", "block": block.model_dump()} # ---------------- 主数据维护（MD-01/02/03：P0 读；P2 写经确认卡） ---------------- @app.get("/api/master") async def master() -> dict: """主数据管理页数据：资源树 + 物料/BOM/路线 + 日历/维保。""" return master_overview(get_store().data) @app.post("/api/master/stage") async def master_stage(req: MasterStageRequest) -> dict: """主数据写入动作暂存为确认卡（P2 唯一执行路径仍是 /api/actions/confirm）。""" if req.action not in MASTER_ACTIONS: return {"error": "不支持的主数据动作"} store = get_store() try: title, lines = confirmation_for_master_action(store.data, req.action, req.payload) except ValueError as exc: # 校验失败：不出卡，直接回错误 return {"error": str(exc)} block = harness.stage_confirmation(req.sessionId or "web", req.action, req.payload, title=title, summary_lines=lines) from server.agent_core.audit import write_audit write_audit(store.data, store.next_id, actor=req.sessionId or "web", category="GATE", action=req.action + ".stage", target={"type": "MASTER_DATA", "id": req.payload.get("id")}, power="P2", rationale={"confirmId": block.props["confirmId"]}) store.save() return {"message": f"{title} 已进入 P2 确认队列。", "block": block.model_dump()} # ---------------- MRP 订单分解（P0 读；P1 分解直通） ---------------- @app.get("/api/mrp") async def mrp() -> dict: """MRP 建议单投影：采购建议 + 委外建议。""" return list_mrp(get_store().data) @app.post("/api/mrp/decompose") async def mrp_decompose(req: MrpDecomposeRequest) -> dict: """订单分解（P1 直通：只写 DRAFT 建议表，经 harness.guard 校验权级）。""" store = get_store() try: result = harness.guard("order.decompose", {"orderNo": req.orderNo}, lambda: decompose_orders(store.data, store.next_id, req.orderNo)) except ValueError as exc: return {"error": str(exc)} from server.agent_core.audit import write_audit write_audit(store.data, store.next_id, actor=req.sessionId or "web", category="ALGO_RUN", action="order.decompose", target={"type": "MRP", "id": req.orderNo or "ALL"}, power="P1", rationale={"purchase": len(result["purchase"]), "outsource": len(result["outsource"])}) store.save() return {"message": summarize_decomposition(result), "result": result} # ---------------- 时间线导轨（§4.4 中观层数据源） ---------------- @app.get("/api/timeline") async def timeline() -> dict: """检查点 + 排产版本的时间线（前端导轨渲染；P0 只读）。""" world = get_store().data # 世界状态 versions = [{ # 版本投影（轻量字段） "id": v["id"], "versionNo": v["versionNo"], "status": v["status"], "createdAt": v["createdAt"], "conflictCount": v["conflictCount"], "engineType": v["engineType"], } for v in world["scheduleVersions"]] return {"checkpoints": get_checkpoints().list_meta(), "versions": versions} # 两类锚点 # ---------------- 采用沙盒方案（P1：正式排产） ---------------- @app.post("/api/actions/scenario/apply") async def scenario_apply(req: ScenarioApplyRequest) -> dict: """把沙盒对比中选中的策略落为正式排产（引擎确定性保证与卡片一致）。""" store = get_store() # 世界状态 intent = IntentResult(intent="schedule.run", # 构造等价的排产意图（复用同一执行路径） params={"strategy": req.strategy, "engine": req.engine}, confidence=1.0, source="RULE_FAST") reply = await handle_intent(store, req.sessionId or "web", intent) # 走标准工作流（含审计落盘） # 偏好信号：采用比试排权重更高（明确的方案选择 §8.3） from server.knowledge import get_preferences # 局部导入（避免循环） get_preferences().record(req.strategy, source="scenario.apply", actor=req.sessionId or "web") return {"message": reply.text, "refresh": True} # 前端刷新世界与时间线 # ---------------- 确认卡回传（P2 唯一执行通道） ---------------- @app.post("/api/actions/confirm") async def confirm(req: ConfirmRequest) -> dict: """批准/驳回一条 P2 动作（门禁放行后的执行入口，§3.3）。""" store = get_store() # 世界状态 message = execute_confirmed(store, req.confirmId, req.approve, # 执行（内部写审计+落盘） actor=req.sessionId or "planner") return {"message": message, "refresh": req.approve} # 批准后前端应刷新世界数据 # ---------------- 治理可视化（§6.10 门禁管理台 / 重生中心 数据源） ---------------- @app.get("/api/gov/pending") async def gov_pending() -> dict: """门禁管理台·待审批队列（聊天确认卡与此为同一数据的两个视图）。""" return {"pending": harness.list_pending()} # 待确认动作投影 @app.get("/api/gov/audit") async def gov_audit(limit: int = 50) -> dict: """门禁管理台·审计链（最近 N 条 + 全链完整性校验结果，§3.6）。""" events = get_store().data.get("auditEvents", []) # 全部审计事件 return {"events": events[-limit:], # 最近 N 条（新在后） "chain": verify_audit_chain(events)} # 哈希链完整性校验 @app.get("/api/gov/modules") async def gov_modules() -> dict: """重生中心·可重生模块注册表（扫描源码 moduleId 声明，§9.4/§6.10.3）。""" return {"modules": scan_modules()} # 注册表清单 @app.get("/api/gov/policy") async def gov_policy() -> dict: """门禁管理台·权力矩阵（_POWER_MAP 只读投影；P0）。""" return {"policy": harness.list_policy(), # 矩阵条目 "defaultPower": "P3"} # 未登记动作的默认等级（白名单原则） @app.get("/api/gov/tests") async def gov_tests(run: bool = False) -> dict: """重生中心·黄金测试看板（P0 只读缓存；?run=true 在线程池重跑，不阻塞事件循环）。""" import asyncio # 线程池调度 from server.gateway.golden import golden_status # 局部导入（避免启动即依赖 pytest） # 跑测是同步子进程（~10s）：必须扔线程池，否则会饿死其他请求（世界视图全超时） return await asyncio.to_thread(golden_status, run) # ---------------- 知识库与报告（M3 §8/§9.10，P0 只读） ---------------- @app.get("/api/knowledge/assets") async def knowledge_assets() -> dict: """知识资产元信息清单（知识面板/命令面板数据源）。""" from server.knowledge import get_knowledge # 局部导入 return {"assets": get_knowledge().list_meta()} # 元信息（不含正文） @app.get("/api/knowledge/assets/{asset_id}") async def knowledge_asset(asset_id: str) -> dict: """单个知识资产全文（出处点开查看）。""" from server.knowledge import get_knowledge # 局部导入 asset = get_knowledge().get(asset_id) # 按 ID 取 return asset or {"error": "资产不存在"} # 缺失给错误体（前端兜底） @app.get("/api/reports/{report_type}") async def report_export(report_type: str) -> Any: """报告导出：即时生成并以 Markdown 附件返回（daily / version-diff）。""" from urllib.parse import quote # 中文文件名 RFC5987 编码 from fastapi.responses import PlainTextResponse # 文本响应（附件头） from server.aps_domain.reports import build_report # 报告工厂 report = build_report(get_store().data, report_type) # 生成（数字取自冻结快照） filename = quote(f"{report['title'].replace(' ', '_')}.md") # 编码后的下载文件名 return PlainTextResponse(report["markdown"], media_type="text/markdown; charset=utf-8", headers={"Content-Disposition": f"attachment; filename*=UTF-8''{filename}"}) @app.get("/api/settings/llm") async def settings_llm() -> dict: """设置中心·LLM Provider 状态（P0 只读；不暴露密钥）。""" from server.agent_core.providers import get_provider # 单例 p = get_provider() # 当前配置 return { "provider": p.provider or None, # deepseek / kimi / None "model": p.model or None, # 模型名 "baseUrl": p.base_url or None, # 端点（无敏感信息） "enabled": p.enabled, # False = 降级为规则解析 "fallback": "规则快路解析器（离线可用）", # 降级去向（固定文案） } return app # 返回配置完成的应用