
    AiD                    "   d Z ddlmZ ddlmZmZ ddlmZmZm	Z	m
Z
 ddlmZmZ ddlmZmZmZmZmZ ddlmZ ddlmZ dd	lmZ dd
lmZ ddlmZ  ee          Z eddg          Z  G d de          Z! G d de          Z" G d de          Z# G d de          Z$e %                    de&e"         d          dd#            Z'e (                    d$d%&           e
d'd(d)d*+           e
d,d(d-d.+          fdd5            Z)e %                    d6e&e$         d7          dd9            Z*e (                    d:d;&          dd=            Z+e (                    d>d?&           e
d@dAB           e
d@dCB           e
d,d(dDE           e
d@dFB          fddL            Z, G dM dNe          Z- G dO dPe          Z.e (                    dQdR&           e
dSd(dTE          fddU            Z/e (                    dVdW&           e
dXd(dSE          fddZ            Z0e (                    d[d\&           e
dXd(dSE          fdd]            Z1e (                    d^d_&           e
d`d(daE          fddc            Z2 G dd dee          Z3 G df dge          Z4 G dh die          Z5 G dj dke          Z6 G dl dme          Z7 G dn doe          Z8 G dp dqe          Z9 G dr dse          Z: G dt due          Z; G dv dwe          Z<e (                    dxe&e3         dy           e
dzdad{|           e
d`d(daE          fdd            Z=e (                    de;d          dd            Z>e (                    de<d          dd            Z?d@S )u=  Knowledge-graph query endpoints for the graph explorer.

知识图谱查询接口模块。
提供实体搜索、实体详情与邻居子图、文档关联实体、文档推荐、
政策依据链、修订/废止历史、同主题文档，以及事项知识卡等功能，
供图谱浏览器和文档详情页调用。
    )annotations)	AnnotatedAny)	APIRouterDependsHTTPExceptionQuery)	BaseModelField)UserContextget_current_userget_neo4j_clientget_optional_permission_contextget_permission_context)GraphSubData)GraphQueryService)PermissionContext)Neo4jClient)
get_loggerz/graphgraph)prefixtagsc                      e Zd ZU dZ edddd          Zded<    ed	d
          Zded<    eddd          Zded<   d	S )EntitySearchRequestuL   Payload for ``POST /graph/search``.

    实体名称搜索请求体。
    .   d   u   实体名称搜索词)
min_length
max_lengthdescriptionstrnameNu:   限定节点标签 (如 Organization, Region, PolicyTheme)r   
str | Nonelabel   i  defaultgeleintlimit)	__name__
__module____qualname____doc__r   r!   __annotations__r$   r+        *D:\work\zm-rag\backend\app\api\v1\graph.pyr   r   '   s          
 caCE\]]]D]]]]P  E     raC000E000000r2   r   c                  T    e Zd ZU dZded<   ded<   ded<    ee          Zded	<   d
S )EntitySearchResultz(A single entity node returned by search.r    id	list[str]labelsr!   default_factorydict[str, Any]
propertiesN)r,   r-   r.   r/   r0   r   dictr<   r1   r2   r3   r5   r5   5   sT         22GGGIII!&t!<!<!<J<<<<<<r2   r5   c                      e Zd ZU dZ eddd          Zded<    edd	          Zded
<    eddd          Zded<   dS )RelatedDocsRequestua   Payload for ``POST /graph/related-docs``.

    通过实体查找关联文档的请求体。
    .r      )r   r   r    entity_nameu4   实体标签 (如 Organization, Region, PolicyTheme)r"   entity_labelr%   r   r&   r*   r+   N)	r,   r-   r.   r/   r   rA   r0   rB   r+   r1   r2   r3   r?   r?   >   s          
 uSQ3???K????J  L     raC000E000000r2   r?   c                  8    e Zd ZU ded<   ded<   ded<   ded<   dS )RelatedDocItemr    doc_idtitle
doc_numberrel_typeN)r,   r-   r.   r0   r1   r2   r3   rD   rD   L   s4         KKKJJJOOOMMMMMr2   rD   z/searchu   实体名称搜索)response_modelsummarybodyuser1Annotated[UserContext, Depends(get_current_user)]perm=Annotated[PermissionContext, Depends(get_permission_context)]neo4j1Annotated[Neo4jClient, Depends(get_neo4j_client)]returnlist[EntitySearchResult]c                   K   t          |          }|                    | j        | j        | j        |j                   d{V }d |D             S )zSearch entity nodes by name (partial match).

    Returns matched nodes across all entity labels unless ``label`` is
    specified.
    )r$   r+   
acl_tokensNc           
         g | ]A}t          |d          |d         |d                             dd          |d                   BS )r6   r8   r<   r!    )r6   r8   r!   r<   )r5   get).0ns     r3   
<listcomp>z#search_entities.<locals>.<listcomp>o   se         	wX;<$$VR00		
 	
 	
  r2   )r   search_entitiesr!   r$   r+   rU   )rK   rL   rN   rP   svcnodess         r3   r\   r\   X   s        E
"
"C%%	jj?	 &        E     r2   z/entity/{entity_id}u!   获取实体节点详情与邻居)rJ      r      u   图遍历深度)r'   r(   r)   r   r@   i  u   最大返回节点数	entity_idr    depthr*   	max_nodesr;   c                   K   t          |          }|                    | |j                   d{V }|t          dd|  d          |                    | |||j                   d{V }||dS )	u0  Return a single entity node and its neighbourhood subgraph.

    Parameters
    ----------
    entity_id:
        Neo4j element ID of the entity.
    depth:
        BFS depth for neighbourhood traversal (1–3).
    max_nodes:
        Maximum number of nodes to return in the neighbourhood subgraph.
    rU   N  zEntity '' not foundstatus_codedetail)rb   rc   rU   )entityr   )r   
get_entityrU   r   get_entity_neighborhood)	ra   rL   rN   rP   rb   rc   r]   nodeneighborhoods	            r3   rl   rl   z   s      . E
"
"C	doFFFFFFFFD|4Uy4U4U4UVVVV 44?	 5        L   r2   z/related-docsu   通过实体查找相关文档list[RelatedDocItem]c                   K   t          |          }|                    | j        | j        | j        |j                   d{V }d |D             S )u~   Return all documents connected to a specific entity node.

    Useful for the "关联文档" panel in the graph explorer.
    r+   rU   Nc           	     d    g | ]-}t          |d          |d         |d         |d                   .S )rE   rF   rG   rH   )rE   rF   rG   rH   )rD   rY   ds     r3   r[   z$get_related_docs.<locals>.<listcomp>   sU         	X;G*z]		
 	
 	
  r2   )r   get_docs_by_entityrA   rB   r+   rU   )rK   rL   rN   rP   r]   docss         r3   get_related_docsrx      s       E
"
"C''j?	 (        D     r2   z/document/{doc_id}/entitiesu   获取文档关联实体rE   c                r   K   t          |          }|                    | |j                   d{V }| |dS )zReturn all entity nodes directly connected to a document.

    Results are grouped by label (Organization, Person, Region, etc.).
    re   N)rE   entities)r   get_document_entitiesrU   )rE   rL   rN   rP   r]   groupeds         r3   r{   r{      sO       E
"
"C--f-QQQQQQQQG'222r2   z	/overviewu-   图谱概览 (最多连接的文档或主题)Nu   实体名称过滤r"   u   实体标签过滤i  r&   u   分页游标（偏移量）rA   r#   r$   r+   cursorc                r   K   t          |          }|                    |||||j                   d{V }|S )a  Return a graph overview for the explorer home page.

    When ``entity_name`` is provided, shows documents connected to that entity.
    Otherwise, shows the most-connected documents.

    Supports cursor-based pagination for progressive loading of large graphs.
    )r$   rA   r+   r}   rU   N)r   get_docs_overviewrU   )	rL   rN   rP   rA   r$   r+   r}   r]   results	            r3   graph_overviewr      se      ( E
"
"C((? )        F Mr2   c                      e Zd ZU dZded<   dZded<   dZded<   dZded<   dZded<   dZ	ded	<   dZ
ded
<   dZded<   dS )
DocRefItemz7A document reference in recommendation / chain results.r    rE   rW   rF   doc_codepublish_dateshared_entity
theme_namestatusFboolis_placeholderN)r,   r-   r.   r/   r0   rF   r   r   r   r   r   r   r1   r2   r3   r   r      s         AAKKKEOOOOHLMJF N      r2   r   c                  2    e Zd ZU dZded<   ded<   ded<   dS )	ChainEdgez+An edge in policy chain / revision history.r    from_doc_id	to_doc_idrH   N)r,   r-   r.   r/   r0   r1   r2   r3   r   r   
  s4         55NNNMMMMMr2   r   z"/document/{doc_id}/recommendationsu/   文档推荐（同机构/同主题/同地域）
   2   c                j   K   t          |          }|                    | ||j                   d{V S )znReturn recommended documents that share Organization, PolicyTheme,
    or Region with the given document.
    rr   N)r   get_document_recommendationsrU   rE   rL   rN   rP   r+   r]   s         r3   r   r     s[       E
"
"C11? 2         r2   z/document/{doc_id}/policy-chainu   政策依据链   	max_depthc                j   K   t          |          }|                    | ||j                   d{V S )zTraverse BASED_ON relationships to show the full policy dependency chain.

    Returns the ancestor documents that this document was based on,
    and the edges between them.
    r   rU   N)r   get_policy_chainrU   rE   rL   rN   rP   r   r]   s         r3   r   r   (  s[        E
"
"C%%? &         r2   z#/document/{doc_id}/revision-historyu   修订/废止历史c                j   K   t          |          }|                    | ||j                   d{V S )zReturn the amendment (AMENDS) and repeal (REPEALS) history.

    Shows all documents connected through AMENDS or REPEALS relationships,
    forming a revision timeline.
    r   N)r   get_revision_historyrU   r   s         r3   r   r   @  s[        E
"
"C))? *         r2   z/document/{doc_id}/same-themeu   同主题文档r%   r   list[dict[str, Any]]c                j   K   t          |          }|                    | ||j                   d{V S )z4Return documents that share the same PolicyTheme(s).rr   N)r   get_same_theme_documentsrU   r   s         r3   r   r   X  s[       E
"
"C--? .         r2   c                  t    e Zd ZU dZded<   ded<   dZded<   dZded<   dZded<    ee		          Z
d
ed<   dS )MatterListItemz&Summary item in matter search results.r    	matter_idr!   rW   r   matter_typer   r9   r7   sample_doc_idsN)r,   r-   r.   r/   r0   r   r   r   r   listr   r1   r2   r3   r   r   r  s{         00NNNIIIKKF %d ; ; ;N;;;;;;r2   r   c                  d    e Zd ZU dZded<   dZded<   dZded<   dZded<   dZded	<   dZ	ded
<   dS )ConditionItemNr#   condition_idrW   r    r!   r   condition_typestructured_valueoperator)
r,   r-   r.   r   r0   r!   r   r   r   r   r1   r2   r3   r   r   }  su         #L####DNNNNKNHr2   r   c                  r    e Zd ZU dZded<   dZded<   dZded<   dZded<   dZded	<   dZ	d
ed<   dZ
ded<   dS )MaterialItemNr#   material_idrW   r    r!   normalized_namer   material_typezbool | Noneis_requiredformat_requirement)r,   r-   r.   r   r0   r!   r   r   r   r   r   r1   r2   r3   r   r     s         "K""""DNNNNOKM#K####       r2   r   c                  d    e Zd ZU dZded<   dZded<   dZded<   dZded<   dZded	<   dZ	ded
<   dS )TimeLimitItemNr#   time_limit_idrW   r    r!   durationunitcontext	time_type)
r,   r-   r.   r   r0   r!   r   r   r   r   r1   r2   r3   r   r     sp          $M$$$$DNNNNHDNNNNGIr2   r   c                  V    e Zd ZU dZded<   dZded<   dZded<   dZded<   dZded	<   dS )
TargetGroupItemNr#   target_group_idrW   r    r!   r   
group_typer   )	r,   r-   r.   r   r0   r!   r   r   r   r1   r2   r3   r   r     sc         "&O&&&&DNNNNOJKr2   r   c                  >    e Zd ZU dZdZded<   dZded<   dZded<   dS )OrganizationRefz5Lightweight Organization reference in matter context.rW   r    r!   
short_nameorg_typeN)r,   r-   r.   r/   r!   r0   r   r   r1   r2   r3   r   r     sG         ??DNNNNJHr2   r   c                  0    e Zd ZU dZdZded<   dZded<   dS )	RegionRefz/Lightweight Region reference in matter context.rW   r    r!   	full_nameN)r,   r-   r.   r/   r!   r0   r   r1   r2   r3   r   r     s6         99DNNNNIr2   r   c                  R    e Zd ZU ded<   dZded<   dZded<   dZded<   dZded<   dS )	GoverningDocItemr    rE   rW   rF   r   r   r   N)r,   r-   r.   r0   rF   r   r   r   r1   r2   r3   r   r     s[         KKKEOOOOHLFr2   r   c                  @   e Zd ZU dZded<   ded<   dZded<   dZded<   dZded<    ee		          Z
d
ed<    ee		          Zded<    ee		          Zded<    ee		          Zded<    ee		          Zded<    ee		          Zded<    ee		          Zded<   dS )MatterCardResponseu   Full matter knowledge card.

    事项知识卡完整响应，汇聚条件、材料、时限、目标群体、
    承办机构、依据文档和适用地域等信息。
    r    r   r!   rW   r   r   r   r9   list[ConditionItem]
conditionslist[MaterialItem]	materialslist[TimeLimitItem]time_limitszlist[TargetGroupItem]target_groupszlist[OrganizationRef]
handled_byzlist[GoverningDocItem]governing_docszlist[RegionRef]regionsN)r,   r-   r.   r/   r0   r   r   r   r   r   r   r   r   r   r   r   r   r1   r2   r3   r   r     s5          NNNIIIKKF&+eD&A&A&AJAAAA$)E$$?$?$?I????',uT'B'B'BKBBBB+05+F+F+FMFFFF(-d(C(C(CJCCCC-2U4-H-H-HNHHHH$uT:::G::::::r2   r   c                      e Zd ZU dZded<   ded<    ee          Zded<    ee          Zded	<    ee          Z	d
ed<   dS )MatterRequirementsResponsez>Focused view of matter conditions, materials, and time limits.r    r   r!   r9   r   r   r   r   r   r   N)
r,   r-   r.   r/   r0   r   r   r   r   r   r1   r2   r3   r   r     s         HHNNNIII&+eD&A&A&AJAAAA$)E$$?$?$?I????',uT'B'B'BKBBBBBBr2   r   z/mattersu   事项搜索rW   u   事项名称搜索词)r   r   MAnnotated[PermissionContext | None, Depends(get_optional_permission_context)]querylist[MatterListItem]c                   K   |                                 sg S t          |          }|                    |                                 || | j        ng            d{V }d |D             S )zlSearch Matter nodes by name (partial match).

    Returns a list of matching matters with summary info.
    Nrr   c                &    g | ]}t          d i |S r1   )r   rY   rs     r3   r[   z"search_matters.<locals>.<listcomp>  s&    111ANQ111r2   )stripr   search_mattersrU   )rN   rP   r   r+   r]   resultss         r3   r   r     s       ;;== 	
E
"
"C&&&*&64??B '        G
 211111r2   z/matters/{matter_id}u   事项知识卡r   c                  K   t          |          }|                    | ||j        ng            d{V }|t          dd|  d          t	          |d         |d         |                    d	d
          |                    dd
          |                    dd
          d |                    dg           D             d |                    dg           D             d |                    dg           D             d |                    dg           D             d |                    dg           D             d |                    dg           D             d |                    dg           D                       S )zReturn the full knowledge card for a matter.

    Includes conditions, materials, time limits, target groups,
    handling organizations, governing documents, and applicable regions.
    Nre   rf   Matter 'rg   rh   r   r!   r   rW   r   r   c                &    g | ]}t          d i |S r   r   rY   cs     r3   r[   z#get_matter_card.<locals>.<listcomp>  s&    KKK1M&&A&&KKKr2   r   c                &    g | ]}t          d i |S r   r   rY   ms     r3   r[   z#get_matter_card.<locals>.<listcomp>  s&    HHH<$$!$$HHHr2   r   c                &    g | ]}t          d i |S r   r   rY   ts     r3   r[   z#get_matter_card.<locals>.<listcomp>  s&    MMMA]''Q''MMMr2   r   c                &    g | ]}t          d i |S r   )r   r   s     r3   r[   z#get_matter_card.<locals>.<listcomp>  s&    SSS++++SSSr2   r   c                &    g | ]}t          d i |S r   )r   )rY   os     r3   r[   z#get_matter_card.<locals>.<listcomp>  s&    MMMQO((a((MMMr2   r   c                &    g | ]}t          d i |S r   )r   rt   s     r3   r[   z#get_matter_card.<locals>.<listcomp>  s'    VVV!(--1--VVVr2   r   c                &    g | ]}t          d i |S r   )r   r   s     r3   r[   z#get_matter_card.<locals>.<listcomp>  s"    AAAAQAAAr2   r   )r   r!   r   r   r   r   r   r   r   r   r   r   )r   get_matter_cardrU   r   r   rX   )r   rN   rP   r]   cards        r3   r   r     s      E
"
"C$$&*&64??B %        D |4Uy4U4U4UVVVV{#&\HH]B//HH]B//xx"%%KKr0J0JKKKHHdhh{B.G.GHHHMM-1L1LMMMSSTXXor5R5RSSSMM$((<2L2LMMMVVtxx@PRT7U7UVVVAA)R)@)@AAA   r2   z!/matters/{matter_id}/requirementsu   事项办理条件与材料c                  K   t          |          }|                    | ||j        ng            d{V }|t          dd|  d          t	          |d         |d         d	 |                    d
g           D             d |                    dg           D             d |                    dg           D                       S )z;Return conditions, materials, and time limits for a matter.Nre   rf   r   rg   rh   r   r!   c                &    g | ]}t          d i |S r   r   r   s     r3   r[   z+get_matter_requirements.<locals>.<listcomp>,  s&    MMM1M&&A&&MMMr2   r   c                &    g | ]}t          d i |S r   r   r   s     r3   r[   z+get_matter_requirements.<locals>.<listcomp>-  s&    JJJ<$$!$$JJJr2   r   c                &    g | ]}t          d i |S r   r   r   s     r3   r[   z+get_matter_requirements.<locals>.<listcomp>.  s&    OOOA]''Q''OOOr2   r   )r   r!   r   r   r   )r   get_matter_requirementsrU   r   r   rX   )r   rN   rP   r]   r   s        r3   r   r     s      E
"
"C..&*&64??B /        F ~4Uy4U4U4UVVVV%%F^MM

<0L0LMMMJJfjjb.I.IJJJOOM21N1NOOO   r2   )
rK   r   rL   rM   rN   rO   rP   rQ   rR   rS   )ra   r    rL   rM   rN   rO   rP   rQ   rb   r*   rc   r*   rR   r;   )
rK   r?   rL   rM   rN   rO   rP   rQ   rR   rp   )
rE   r    rL   rM   rN   rO   rP   rQ   rR   r;   )rL   rM   rN   rO   rP   rQ   rA   r#   r$   r#   r+   r*   r}   r#   rR   r;   )rE   r    rL   rM   rN   rO   rP   rQ   r+   r*   rR   r;   )rE   r    rL   rM   rN   rO   rP   rQ   r   r*   rR   r;   )rE   r    rL   rM   rN   rO   rP   rQ   r+   r*   rR   r   )
rN   r   rP   rQ   r   r    r+   r*   rR   r   )r   r    rN   r   rP   rQ   rR   r   )r   r    rN   r   rP   rQ   rR   r   )@r/   
__future__r   typingr   r   fastapir   r   r   r	   pydanticr
   r   app.api.depsr   r   r   r   r   app.api.schemas.documentr   app.core.graph_query_servicer   app.core.permissionr   app.infrastructure.neo4j_clientr   app.utils.loggerr   r,   loggerrouterr   r5   r?   rD   postr   r\   rX   rl   rx   r{   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r1   r2   r3   <module>r     s    # " " " " " ! ! ! ! ! ! ! ! < < < < < < < < < < < < % % % % % % % %              2 1 1 1 1 1 : : : : : : 1 1 1 1 1 1 7 7 7 7 7 7 ' ' ' ' ' '	H			('	3	3	31 1 1 1 1) 1 1 1= = = = = = = =1 1 1 1 1 1 1 1    Y    *+    
   
: /    qQ1:KLLLU31CZ[[[# # # #	 #L ',   
   
8 !&   3 3 3	 3 ;    $eD6JKKKd0DEEEsqT222t1NOOO   	 B
! 
! 
! 
! 
! 
! 
! 
!    	    (=    raB///   	 $ %    U1r222   	 ( )!    U1r222   	 ( #    raC000   	 ,< < < < <Y < < <    I   ! ! ! ! !9 ! ! !    I       i       i       	       y   ; ; ; ; ; ; ; ;*C C C C C C C C '    rc7NOOOraC000	2 2 2 2 
2* %   
   
B '-)   
   
  r2   