张胜宇
e239eb778b
1) 客服 Agent 四份交付文档 + 构建脚手架：品牌由包装占位 XX科技 / 旧名 南方财富 统一为南方基金（热线 400-889-8899 / 官网 nffund.com），系统名改为「智能服务系统」； 同步追加 §0.4 修订记录行，工程记录行保留原占位字面以支撑硬编码扫描验收。 2) 开发文档：清理 28 份已作废/残留文档（14 份移出归档 + 14 份仓库副本）， 新增《文档规整方案与开发前待决事项-2026-09-17》。 3) 客服agent 四份交付文档首次纳入本分支。
81 lines
3.4 KiB
Python
81 lines
3.4 KiB
Python
"""图模型定义：节点类型、主属性与关系语义（**单一来源**）。
|
|
|
|
为什么必须集中定义：
|
|
|
|
1. **标签与属性名要拼进 Cypher**（Neo4j 的标签不能用查询参数占位），因此它们**必须**来自
|
|
受控常量，绝不能接受调用方传入的任意字符串，否则就是 Cypher 注入。
|
|
2. 读服务（`RelationshipService`）与投影侧需要就"客户节点长什么样"达成一致。此前投影写
|
|
`:Entity {entity_id}`、读服务查 `:Customer {customer_id}`，两边各写各的，结果是**写进去的
|
|
关系永远读不出来**。把节点规格放在一处，两边都从这里取，才不会再次漂移。
|
|
3. `RELATION_SEMANTICS` 记录每种关系连接哪两类节点，用于在投影时拒绝无意义的边
|
|
（例如把 `TRADED` 写成 Customer→Tag）。底座已有关系白名单（8 种），这里补的是
|
|
"谁指向谁"的语义约束。
|
|
"""
|
|
|
|
from dataclasses import dataclass
|
|
from typing import Any
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class NodeSpec:
|
|
"""一个节点类型的规格。`cast` 决定主键类型：客户 id 是整数（与读服务查询一致）。"""
|
|
|
|
type_key: str
|
|
label: str
|
|
property: str
|
|
cast: type
|
|
|
|
|
|
# payload 里使用的类型名 → 节点规格。未登记的类型一律拒绝。
|
|
NODE_SPECS: dict[str, NodeSpec] = {
|
|
"customer": NodeSpec("customer", "Customer", "customer_id", int),
|
|
"product": NodeSpec("product", "Product", "product_code", str),
|
|
"tag": NodeSpec("tag", "Tag", "tag_key", str),
|
|
"industry": NodeSpec("industry", "Industry", "category", str),
|
|
"event": NodeSpec("event", "Event", "event_id", str),
|
|
}
|
|
|
|
# 关系 → (允许的源节点类型, 允许的目标节点类型)
|
|
RELATION_SEMANTICS: dict[str, tuple[tuple[str, ...], tuple[str, ...]]] = {
|
|
"PREFERS": (("customer",), ("tag",)),
|
|
"HAS_GOAL": (("customer",), ("tag",)),
|
|
"INTERESTED_IN": (("customer",), ("product", "industry")),
|
|
"TRADED": (("customer",), ("product",)),
|
|
"HOLDS": (("customer",), ("product",)),
|
|
"TRIGGERED_RISK": (("customer",), ("event",)),
|
|
"BELONGS_TO_CATEGORY": (("product",), ("tag",)),
|
|
"EXPOSED_TO_INDUSTRY": (("product", "customer"), ("industry",)),
|
|
}
|
|
|
|
|
|
def node_spec(type_key: object) -> NodeSpec:
|
|
"""按类型名取节点规格；未登记的类型抛 `ValueError`（宁可失败也不拼出任意标签）。"""
|
|
key = str(type_key or "").strip().lower()
|
|
spec = NODE_SPECS.get(key)
|
|
if spec is None:
|
|
raise ValueError(f"node type is not allowed: {type_key!r}")
|
|
return spec
|
|
|
|
|
|
def node_id(spec: NodeSpec, value: Any) -> Any:
|
|
"""把主键值转成该节点应有的类型。"""
|
|
return value if spec.cast is str else spec.cast(value)
|
|
|
|
|
|
def relation_allowed(relation: str, source_type: str, target_type: str) -> bool:
|
|
"""该关系是否允许连接这两类节点。"""
|
|
expected = RELATION_SEMANTICS.get(relation)
|
|
if expected is None:
|
|
return False
|
|
sources, targets = expected
|
|
return source_type in sources and target_type in targets
|
|
|
|
|
|
def merge_node_clause(variable: str, spec: NodeSpec, id_parameter: str) -> str:
|
|
"""生成 `MERGE (a:Label {prop: $param})` 子句。
|
|
|
|
只有 `spec` 里的标签与属性名会进入查询文本（它们来自本模块常量），`$param` 走参数绑定，
|
|
因此调用方无法通过数据影响 Cypher 结构。
|
|
"""
|
|
return f"MERGE ({variable}:{spec.label} {{{spec.property}: ${id_parameter}}})"
|