12306 退改签 Agent · 五层领域架构设计 (ARCHITECTURE.md)

1. 五层领域架构视图

TicketAgent 采用严格的单向依赖分层架构 (UI -> API Router -> State Graph -> Domain Rules -> Mock DB)

第 1 层 · Client UI

控制台 UI 交互层

src/app/page.tsx, globals.css

↓ HTTP POST (JSON / SSE)

第 2 层 · API Router

API 路由控制层

src/app/api/chat/route.ts, execute/route.ts

↓ State Invocation

第 3 层 · State Graph

Agent 状态图编排层 (LangGraph-like Loop)

src/lib/agentGraph.ts (Classifier/Extractor/Validator)

↓ Rule / Evaluation Call

第 4 层 · Domain Rules (财务算费唯一真理源)

领域规则与策略引擎

src/lib/rulesEngine.ts, ticketPolicyService.ts, foundationModelClient.ts

↓ Data Query / Update

第 5 层 · Mock DB

内存车票资产库与种子工厂

src/lib/mockDb.ts, ticketSeeds.ts

2. C4 模型结构分解

基于 C4 Model 表达 TicketAgent 组件分工与边界关系。

C4 Level 3: 组件图 (Component Diagram - Next.js System Boundary)

flowchart TB
    subgraph UI_Layer["第 1 层：控制台 UI 交互层 (src/app/)"]
        PageUI["React Console / Glassmorphic Panel
src/app/page.tsx"]
    end

    subgraph API_Layer["第 2 层：API 路由控制层 (src/app/api/)"]
        ChatRoute["/api/chat/route.ts
(会话路由与安全包装)"]
        ExecRoute["/api/ticket/execute/route.ts
(退改签落库与幂等执行)"]
    end

    subgraph Graph_Layer["第 3 层：Agent 状态图编排层 (src/lib/)"]
        AgentGraph["LangGraph Workflow
src/lib/agentGraph.ts
(Classifier -> Extractor -> Validator)"]
    end

    subgraph Domain_Layer["第 4 层：领域规则与策略引擎 (src/lib/)"]
        RulesEngine["12306 退改签计算引擎
src/lib/rulesEngine.ts
【财务红线唯一真理源】"]
        PolicyService["退改签策略核验服务
src/lib/ticketPolicyService.ts"]
        ModelClient["基础模型接入层
src/lib/foundationModelClient.ts"]
        TimeContext["时间上下文工厂
src/lib/timeContext.ts"]
    end

    subgraph DB_Layer["第 5 层：内存车票资产库 (src/lib/)"]
        MockDB["车票数据库与种子数据
src/lib/mockDb.ts + ticketSeeds.ts"]
    end

    PageUI -->|"HTTP POST"| ChatRoute
    PageUI -->|"HTTP POST (Idempotency-Key)"| ExecRoute

    ChatRoute --> AgentGraph
    ExecRoute --> PolicyService
    ExecRoute --> MockDB

    AgentGraph --> ModelClient
    AgentGraph --> PolicyService
    PolicyService --> RulesEngine
    PolicyService --> TimeContext
    PolicyService --> MockDB

组件图明确展示了 5 层单向依赖链路：UI -> API Router -> Agent Graph -> Domain Rules -> Mock DB。

3. 核心设计原则

四大架构核心红线，奠定合规性与财务可推导性

⚖️

财务算费唯一真理源

所有退改签手续费、取整舍入算法（5角取整、广深港截断、中老四舍五入）仅收口于 src/lib/rulesEngine.ts，禁止在 UI 或 Agent 编排层重复计算。

🔒

服务端严密计算

财务规则与敏感校验只在服务端 API 执行，前端不得直接进行扣费决策或篡改票据资产状态。

⏰

显式时间上下文注入

所有发车时间差、购票时间差的计算，必须显式传入 TimeContext 参数，严禁在业务深度逻辑中硬编码 new Date()。

🌱

Mock 数据种子隔离

Mock DB 在应用启动和测试时必须通过统一的工厂函数生成种子数据，确保测试可复现与并发隔离。

4. 对话调用链路 (/api/chat)

处理用户对话提问，安全护栏拦截与意图路由处理

Chat Execution Flow

sequenceDiagram
    autonumber
    actor User as 🧑 用户
    participant UI as 🖥️ Client UI (page.tsx)
    participant API as 🌐 /api/chat/route.ts
    participant Graph as 🔄 agentGraph.ts
    participant LLM as 🧠 foundationModelClient.ts
    participant Policy as ⚖️ ticketPolicyService.ts
    participant Rules as 🧮 rulesEngine.ts (真理源)

    User->>UI: 输入退改签指令/提问
    UI->>API: POST /api/chat { message, history }
    API->>Graph: runAgentGraph(message, history, tickets)
    Graph->>LLM: 语义解析与提示词提取 (Classifier/Extractor)
    LLM-->>Graph: 返回意图 Hints与护栏分类
    alt 触发 Prompt 注入 / 违规护栏
        Graph-->>API: 返回拦截并拒绝回答
    else 安全校验通过
        Graph->>Policy: 评估车票退改策略 (evaluateRefund/Rebook)
        Policy->>Rules: 精确计算扣费与退款
        Rules-->>Policy: 返回算费明细
        Policy-->>Graph: 返回策略建议
    end
    Graph-->>API: 返回响应 JSON / SSE Stream
    API-->>UI: 渲染对话气泡与确认卡片

5. 交易执行链路 (/api/ticket/execute)

带有 Idempotency-Key 幂等校验与二次策略阻断校验的底层落库交易

Transaction Execution Flow (Idempotent)

sequenceDiagram
    autonumber
    actor User as 🧑 用户
    participant UI as 🖥️ Client UI
    participant API as 🌐 /api/ticket/execute
    participant Idem as 🔒 idempotencyStore.ts
    participant Policy as ⚖️ ticketPolicyService.ts
    participant DB as 💾 mockDb.ts

    User->>UI: 点击确认退票 / 提交改签
    UI->>API: POST /api/ticket/execute (Header: Idempotency-Key)
    API->>Idem: 检查幂等 Key 记录
    alt 已处理过相同 Key
        Idem-->>API: 返回缓存的响应结果
        API-->>UI: 返回 200 (x-idempotency-replayed: true)
    else 首次提交
        API->>Policy: 二次策略判定校验
        alt 校验被阻断 (BLOCKED)
            Policy-->>API: 返回阻断原因
            API-->>UI: 返回 200 { success: false, message }
        else 校验通过 (READY)
            API->>DB: 更新车票状态 (已退票 / 已改签)
            DB-->>API: 落库成功
            API->>Idem: 保存幂等记录
            API-->>UI: 返回交易成功明细
        end
    end

6. 关键领域对象

定义在 src/types/index.ts 的领域类型规范

实体 / 结构	包含字段	职责说明
`Ticket`	`id, trainNo, from, to, departureTime, price, status, ticketType`	车票资产核心实体，支持普通票、跨境票及积分兑换票。
`AgentState`	`message, history, tickets, nextNode, actionStatus, params`	LangGraph 状态图流转上下文状态容器。
`TimeContext`	`currentTime, referenceTime`	显式时间上下文，用于提供可靠的相对时间窗口判断。

7. 必须恪守的核心工程红线

🚫
禁止在前端或 Agent 编排层重复实现算费
退改签扣费计算只能存在于 rulesEngine.ts 纯函数中。
🚫
禁止在业务深度逻辑中硬编码 new Date()
必须使用 TimeContext 显式注入发车与购票时间差。
🚫
禁止使用隐式 any
必须保持全量强 TypeScript 类型约束，代码通过 npx tsc --noEmit 校验。