"""Authenticated, independent polygon + measured-cloud planar pose annotation."""
from __future__ import annotations

import argparse
from collections import Counter
from contextlib import closing
import csv
from datetime import datetime, timezone
import fcntl
import hashlib
import hmac
from http.cookies import CookieError, SimpleCookie
import io
import json
import logging
import os
from pathlib import Path
import secrets
import sqlite3
import threading
from urllib.parse import parse_qs, urlsplit
from zipfile import ZipFile, ZIP_DEFLATED

import numpy as np
from PIL import Image

from .cluster_targets import digest, load_dataset, protected_snapshot, target_id, target_key
from .pose_review_geometry import (GeometryEngine, canonical, polygon_value, pose_value,
    raster_mask, sensor_value)
from .pose_review_units import MetrePolicy
from .pose_review_axes import AxesPolicy,AXIS_FIELDS
from .pose_review_masks import MaskSuggestions
from .structure_review import ReviewError, ReviewHandler, ReviewServer, etag_matches

PROJECT = Path(__file__).resolve().parents[1]
ASSETS = Path(__file__).with_name('assets')/'pose_review'
DEFAULT_REVIEWS = PROJECT/'outputs/pallet_pose_human_review_v1'
COOKIE = 'pallet_pose_session_v1'
UI_VERSION = 'width-aligned-v14-mask-proposals'
LOG = logging.getLogger('pallet.pose_review')


def now():
    return datetime.now(timezone.utc).isoformat(timespec='milliseconds')


def boundary(directory, roots):
    directory = Path(directory).resolve()
    for root in roots:
        root = Path(root).resolve()
        if directory == root or directory.is_relative_to(root) or root.is_relative_to(directory):
            raise ValueError('位姿审核目录必须独立于受保护数据和已有审核库')


class PoseStore:
    def __init__(self, directory, binding):
        self.path = Path(directory)/'annotations.sqlite3'
        with closing(self.connect()) as db:
            db.execute('PRAGMA journal_mode=WAL')
            db.executescript('''
                CREATE TABLE IF NOT EXISTS metadata(key TEXT PRIMARY KEY,value TEXT NOT NULL);
                CREATE TABLE IF NOT EXISTS annotations(target_key TEXT PRIMARY KEY,revision INTEGER NOT NULL,payload TEXT NOT NULL);
                CREATE TABLE IF NOT EXISTS events(id INTEGER PRIMARY KEY AUTOINCREMENT,target_key TEXT NOT NULL,
                    revision INTEGER NOT NULL,payload TEXT NOT NULL, UNIQUE(target_key,revision));
            ''')
            old = db.execute("SELECT value FROM metadata WHERE key='binding'").fetchone()
            value = canonical(binding).decode()
            if old and old[0] != value:
                raise ValueError('标注库绑定了不同源数据，拒绝覆盖')
            db.execute('INSERT OR IGNORE INTO metadata VALUES (?,?)',('binding',value))
            if db.execute('PRAGMA quick_check').fetchone()[0] != 'ok':
                raise ValueError('标注库完整性检查失败')
        os.chmod(self.path,0o600)

    def connect(self):
        db = sqlite3.connect(self.path,timeout=20,isolation_level=None)
        db.execute('PRAGMA synchronous=FULL')
        return db

    def get(self,key):
        with closing(self.connect()) as db:
            row = db.execute('SELECT payload FROM annotations WHERE target_key=?',(key,)).fetchone()
        return json.loads(row[0]) if row else None

    def all(self):
        with closing(self.connect()) as db:
            return {key:json.loads(value) for key,value in db.execute('SELECT target_key,payload FROM annotations')}

    def history(self,key):
        with closing(self.connect()) as db:
            return [json.loads(row[0]) for row in db.execute(
                'SELECT payload FROM events WHERE target_key=? ORDER BY revision DESC LIMIT 50',(key,))]

    def latest(self,keys):
        """Latest committed human save in this queue, ordered by event ID, not clock."""
        allowed = set(keys)
        if not allowed: return None
        with closing(self.connect()) as db:
            cursor = db.execute('SELECT target_key,payload FROM events ORDER BY id DESC')
            for key,raw in cursor:
                if key in allowed and json.loads(raw).get('event_kind') not in ('unit_normalization','axes_normalization'): return key
        return None

    def save(self,key,expected,value,*,allow_deleted=False):
        with closing(self.connect()) as db:
            db.execute('BEGIN IMMEDIATE')
            old = db.execute('SELECT revision,payload FROM annotations WHERE target_key=?',(key,)).fetchone()
            if (old[0] if old else 0) != expected:
                db.rollback()
                raise ReviewError(409,'其他窗口已修改此目标，草稿仍在本机，请刷新比较后再保存')
            if old and json.loads(old[1]).get('state')=='deleted' and not allow_deleted:
                db.rollback()
                raise ReviewError(409,'此对象已删除，请先在“已删除”筛选中明确恢复；本机草稿仍保留')
            value = dict(value,revision=expected+1,updated_at=now())
            raw = canonical(value).decode()
            db.execute('INSERT INTO annotations VALUES (?,?,?) ON CONFLICT(target_key) DO UPDATE SET revision=excluded.revision,payload=excluded.payload',
                (key,expected+1,raw))
            db.execute('INSERT INTO events(target_key,revision,payload) VALUES (?,?,?)',(key,expected+1,raw))
            db.commit()
        return value


class PoseApplication:
    def __init__(self, dataset, directory, protect=True,unit_policy=None,axes_policy=None):
        self.dataset, self.directory = Path(dataset).resolve(),Path(directory).resolve()
        boundary(self.directory,[self.dataset,PROJECT/'outputs/pallet_pose_dataset_v2',
            PROJECT/'outputs/pallet_pose_annotations_v1',PROJECT/'outputs/pallet_pose_training_v1',
            PROJECT/'outputs/pallet_structure_human_review_v1'])
        self.directory.mkdir(parents=True,exist_ok=True)
        annotations,self.sources = load_dataset(self.dataset)
        binding = {'schema':1,'formal_frames_sha256':digest(self.dataset/'frames.jsonl'),
            'formal_annotations_sha256':digest(self.dataset/'annotations/frames.jsonl'),
            'formal_manifest_sha256':digest(self.dataset/'manifest.json')}
        snapshot_path = self.directory/'protected_formal_snapshot.json'
        if protect:
            snapshot = protected_snapshot(self.dataset)
            frozen = json.loads((self.dataset/'manifest.json').read_text()).get('files',{})
            if any(name in frozen and frozen[name]!=sha for name,sha in snapshot.items()):
                raise ValueError('原标签/元数据与冻结清单不一致')
            if snapshot_path.exists():
                if json.loads(snapshot_path.read_text()) != snapshot:
                    raise ValueError('受保护标签/元数据已变化，请先核验')
            else:
                snapshot_path.write_bytes(canonical(snapshot))
        self.binding = hashlib.sha256(canonical(binding)).hexdigest()
        self.machine = {}
        proposals = PROJECT/'outputs/pallet_pose_annotations_v1/annotations/targets.jsonl'
        if proposals.is_file():
            with proposals.open() as stream:
                for line in stream:
                    value = json.loads(line)
                    if value.get('metric_pose_estimate'):
                        self.machine[value['target_key']] = value['metric_pose_estimate']
        self.rows = {}
        for a in annotations:
            source = self.sources[a['frame_id']]
            for i,box in enumerate(a['boxes']):
                key = target_key(a['frame_id'],i)
                self.rows[key] = {'target_key':key,'target_id':target_id(a['frame_id'],i),
                    'frame_id':a['frame_id'],'box_index':i,'bbox':box,'split':a['split'],
                    'group_id':a['group_id'],'size':source['size'],'policy_id':source['sensor_policy']['policy_id'],
                    'source_pcd_sha256':source['source_anchor_hash']}
        self.keys = sorted(self.rows,key=lambda k:(self.rows[k]['group_id'],self.rows[k]['target_id']))
        self.frame_keys = {}
        for key in self.keys:
            self.frame_keys.setdefault(self.rows[key]['frame_id'],[]).append(key)
        self.negative_frames = sum(not a['boxes'] for a in annotations)
        self.store = PoseStore(self.directory,binding)
        self.engine = GeometryEngine(self.dataset,self.directory/'geometry')
        self.units=unit_policy or MetrePolicy.load(PROJECT/'configs/pallet_pose_review_units_v1.json',self.dataset)
        self.axes=axes_policy or AxesPolicy.load(PROJECT/'configs/pallet_pose_review_axes_v1.json',self.dataset)
        self.masks=MaskSuggestions(PROJECT/'configs/active_mask_template_proposals.json',self.dataset)
        self.export_jobs = {}
        self.export_lock = threading.Lock()
        self.machine_update_lock = threading.Lock()
        self.machine_update_fingerprint = None
        self.machine_updates = {}
        key_path = self.directory/'access_key.txt'
        try:
            with open(key_path,'x',opener=lambda p,f:os.open(p,f,0o600)) as stream:
                stream.write(secrets.token_urlsafe(24)+'\n')
        except FileExistsError:
            pass
        self.access_key = key_path.read_text().strip()
        if len(self.access_key)<20:
            raise ValueError('访问码过短')
        self.cookie_token = hmac.new(self.access_key.encode(),b'pallet-pose-review-v1',hashlib.sha256).hexdigest()

    def row(self,key):
        if key not in self.rows:
            raise ReviewError(404,'目标不存在')
        return self.rows[key]

    def source(self,key):
        return self.sources[self.row(key)['frame_id']]

    def sensor(self,key,value=None):
        source=self.source(key)
        sensor=self.units.sensor(value,source) if self.units else sensor_value(value,source)
        return self.axes.sensor(sensor,source) if self.axes else sensor

    def effective_review(self,value):
        if value is None:return None
        source=self.source(value['target_key'])
        value=self.units.review(value,source,self.engine) if self.units else value
        return self.axes.review(value,source,self.engine) if self.axes else value

    def axes_info(self,key):
        return self.axes.info(self.source(key)) if self.axes else None

    def check_axes_client(self,key,data):
        if self.axes_info(key) and data.get('axes_policy_id')!=self.axes.id:
            raise ReviewError(409,'此采集组坐标轴已修正，请刷新新版页面；旧本机草稿仍保留')

    def draft_revisions(self,key):
        history=self.store.history(key)
        if not history:return [0]
        revisions=[history[0]['revision']]
        for value in history:
            if value['revision']!=revisions[-1]:break
            field={'unit_normalization':'unit_interpretation','axes_normalization':'axes_interpretation'}.get(value.get('event_kind'))
            parent=value.get(field,{}).get('source_revision') if field else None
            if parent is None:break
            revisions.append(parent)
        return revisions

    def adapt_draft(self,key,data):
        """Pure draft adaptation; never save to the live annotation database."""
        self.check_axes_client(key,data)
        draft=data['draft'];expected=draft.get('expected_revision')
        if data.get('binding')!=self.binding or type(expected) is not int or expected not in self.draft_revisions(key):
            raise ReviewError(409,'本机草稿与新的人工修订冲突，原稿保留，不自动覆盖')
        old=draft['edit']
        pseudo=dict(target_key=key,revision=expected,state='draft',polygon=old['polygon'],sensor=old['sensor'],
            geometry_token=old.get('geometry_token'),selected_faces=old.get('faces',[]),exclusions=old.get('exclusions',[]),
            ruler=old.get('ruler'),pose=None,view=draft.get('view'),pose_status='pending')
        value=self.effective_review(pseudo)
        converted=any(value['sensor'][k]!=old['sensor'][k] for k in AXIS_FIELDS)
        edit=dict(polygon=value['polygon'],sensor=value['sensor'],geometry_token=value['geometry_token'],
            faces=value['selected_faces'],exclusions=value['exclusions'],ruler=value['ruler'])
        return dict(draft=dict(draft,edit=edit,view=value.get('view'),poseConfirmed=False if converted else draft.get('poseConfirmed',False)),
                    axes_converted=converted,database_writes=0)

    def stats(self, reviews=None):
        reviews = self.store.all() if reviews is None else reviews
        counts = {'total':len(self.keys),'saved':0,'mask_confirmed':0,'pose_confirmed':0,'complete':0,
                  'draft':0,'deferred':0,'deleted':0,'negative_frames_unchanged':self.negative_frames}
        for key,value in reviews.items():
            if key not in self.rows:
                continue
            counts['saved'] += 1
            if value['state']=='deleted':
                counts['deleted'] += 1
                continue
            counts['mask_confirmed'] += value['mask_status']=='confirmed'
            counts['pose_confirmed'] += value['pose_status']=='confirmed'
            counts['complete'] += value['mask_status']==value['pose_status']=='confirmed'
            counts['deferred'] += value['state']=='deferred'
            counts['draft'] += value['state']=='draft'
        return counts

    def queue(self, query):
        state,group,split,term = (query.get(k,[''])[0] for k in ('state','group','split','q'))
        values = self.store.all(); keys=[]
        for key in self.keys:
            row = self.rows[key]; review=values.get(key)
            if group and row['group_id']!=group: continue
            if split and row['split']!=split: continue
            status = review['state'] if review else 'pending'
            if status=='deleted' and state!='deleted': continue
            if state=='mask_proposal':
                if not self.masks.get(key,review,row,values):continue
            elif state and state!='all' and (state=='pending' and status=='complete' or state!='pending' and status!=state): continue
            if term and term.lower() not in (row['target_id']+' '+key).lower(): continue
            keys.append(key)
        return {'keys':keys,'total':len(keys),'stats':self.stats(values)}

    def locate(self, query):
        """Read-only lookup in the same filtered, target-based navigation order."""
        mode = query.get('mode',['position'])[0]
        value = query.get('value',[''])[0].strip()
        if mode!='latest' and (not value or len(value)>300):
            raise ValueError('请输入有效的序号或图像名称（不超过300字）')
        if mode not in ('position','image','latest'):
            raise ValueError('无效跳转方式')
        keys = self.queue(query)['keys']
        if mode=='latest':
            key = self.store.latest(keys)
            if key is None:
                raise ReviewError(404,'当前筛选内还没有已保存的标注，请调整筛选或先保存标注')
            matches = [(keys.index(key)+1,key)]
        elif mode=='position':
            if not value.isascii() or not value.isdecimal() or not 1<=int(value)<=len(keys):
                raise ValueError(f'请输入当前筛选队列内的整数序号：1–{len(keys)}' if keys else '当前筛选没有目标，请先调整筛选')
            matches = [(int(value),keys[int(value)-1])]
        else:
            term = value.casefold()
            exact,partial = [],[]
            for position,key in enumerate(keys,1):
                row = self.rows[key];source = self.sources[row['frame_id']]
                image = source['image']
                names = [key,row['target_id'],row['frame_id'],image,Path(image).name,Path(image).stem,
                         Path(source['source_paths']['pcd']).name,Path(source['source_paths']['pcd']).stem]
                names = [name.casefold() for name in names]
                if term in names: exact.append((position,key))
                elif any(term in name for name in names): partial.append((position,key))
            matches = exact or partial
        if not matches:
            raise ReviewError(404,'当前筛选内未找到该图像或目标，请检查名称或调整筛选')
        return {'total':len(matches),'queue_total':len(keys),'truncated':len(matches)>50,
                'matches':[{'target_key':key,'position':position,
                            'frame_id':self.rows[key]['frame_id'],'target_id':self.rows[key]['target_id'],
                            'box_index':self.rows[key]['box_index'],
                            'image_name':Path(self.sources[self.rows[key]['frame_id']]['image']).name}
                           for position,key in matches[:50]]}

    def detail(self,key):
        row,source = self.row(key),self.source(key)
        b=row['bbox']; x,y,w,h=(b[k] for k in ('x','y','width','height'))
        raw_review=self.store.get(key);review=self.effective_review(raw_review)
        suggestion=self.machine_suggestion(key) if review is None else None
        if self.axes_info(key):suggestion=None
        if suggestion and self.units and suggestion['pose_estimate'].get('source_scale_to_m')!=self.sensor(key)['scale_to_m']:
            # Preserve the frozen proposal sidecar, but never render its old
            # native coordinates directly against a newly metre-scaled cloud.
            suggestion=None
        reviews=self.store.all()
        return {'target':row,'review':review,'history':[self.effective_review(v) for v in self.store.history(key)],
            'stats':self.stats(reviews),
            'frame_objects':[dict(target_key=k,box_index=self.rows[k]['box_index'],bbox=self.rows[k]['bbox'],
                deleted=reviews.get(k,{}).get('state')=='deleted') for k in self.frame_keys[row['frame_id']]],
            'initial_polygon':[[x,y],[x+w,y],[x+w,y+h],[x,y+h]],
            'sensor':self.sensor(key),'binding':self.binding,
            'unit_policy':self.units.info(source) if self.units else None,
            'axes_policy':self.axes_info(key),'draft_compatible_revisions':self.draft_revisions(key),
            'machine_reference':None if self.axes_info(key) else suggestion['pose_estimate'] if suggestion else self.machine.get(key),
            'machine_suggestion':suggestion,
            'mask_suggestion':self.masks.get(key,raw_review,row,self.store),
            'image_url':f'/media/{key}?v={source["files"][source["image"]]}'}

    def machine_suggestion(self,key):
        """Versioned proposal sidecars only; never write or replace a human review."""
        active=PROJECT/'configs/active_pose_refinement.json'
        if not active.exists():return None
        fingerprint=(active.stat().st_mtime_ns,active.stat().st_size)
        with self.machine_update_lock:
            if fingerprint!=self.machine_update_fingerprint:
                try:
                    config=json.loads(active.read_text())
                    path=(PROJECT/config['targets']).resolve()
                    if not path.is_relative_to((PROJECT/'outputs').resolve()):raise ValueError('Proposal path is outside outputs')
                    if digest(path)!=config['targets_sha256']:raise ValueError('Machine proposal hash differs')
                    if config['formal_manifest_sha256']!=digest(self.dataset/'manifest.json'):
                        raise ValueError('Machine update belongs to another formal dataset')
                    updates={}
                    with path.open() as stream:
                        for line in stream:
                            value=json.loads(line);k=value['target_key']
                            if value.get('pose_estimate') is not None:
                                updates[k]={name:value.get(name) for name in ('target_key','source_pcd_sha256','bbox',
                                    'pose_estimate','ruler_suggestion','review_flags','model_family','branch')}
                                updates[k]['version']=config['version']
                    self.machine_updates=updates;self.machine_update_fingerprint=fingerprint
                except (ValueError,KeyError,OSError):
                    LOG.exception('Refusing invalid machine proposal update')
                    return None
            value=self.machine_updates.get(key)
            if value and value['source_pcd_sha256']==self.row(key)['source_pcd_sha256'] and value['bbox']==self.row(key)['bbox']:
                return value
        return None

    def compute(self,key,data):
        source=self.source(key);sensor=self.sensor(key,data.get('sensor'))
        polygon=polygon_value(data['polygon'],*source['size'])
        token=data.get('geometry_token')
        if self.units and token:
            meta=self.engine.load(token,key)
            if meta['polygon']==polygon:
                if meta['sensor']==sensor:return meta
                fields=('forward_axis','up_axis','forward_sign','up_sign','axes_confirmed')
                if meta['sensor']['scale_to_m'] is None and all(meta['sensor'][k]==sensor[k] for k in fields):
                    return self.units.geometry(self.engine,meta,source,sensor)
        if self.axes_info(key) and token:
            meta=self.engine.load(token,key)
            if meta['polygon']==polygon and meta['sensor']['scale_to_m']==sensor['scale_to_m']:
                return self.axes.geometry(self.engine,meta,source,sensor)
        return self.engine.compute(key,source,polygon,sensor)

    def save(self,key,data):
        self.check_axes_client(key,data)
        if self.axes_info(key) and any(data.get('sensor',{}).get(k)!=self.axes.config['axes'][k] for k in AXIS_FIELDS):
            raise ReviewError(409,'旧坐标轴草稿须先转换，不得直接按新坐标轴保存')
        if data.get('binding')!=self.binding:
            raise ReviewError(409,'数据绑定不一致，请刷新')
        if self.units and data.get('unit_policy_id')!=self.units.id:
            raise ReviewError(409,'位置单位已统一为米，请刷新新版页面；旧本机草稿仍保留，不按旧步长保存')
        expected=data.get('expected_revision')
        if type(expected) is not int or expected<0:
            raise ValueError('缺少有效修订版本')
        source=self.source(key); w,h=source['size']
        polygon=polygon_value(data['polygon'],w,h)
        sensor=self.sensor(key,data.get('sensor'))
        mask_status,pose_status=(data.get(k,'pending') for k in ('mask_status','pose_status'))
        if mask_status not in ('pending','confirmed') or pose_status not in ('pending','confirmed'):
            raise ValueError('无效确认状态')
        reviewer,note = data.get('reviewer','').strip(),data.get('note','').strip()
        if not 1<=len(reviewer)<=80 or len(note)>2000:
            raise ValueError('请填写标注人（1–80字），备注不超过2000字')
        token=data.get('geometry_token'); ids=data.get('selected_faces',[])
        exclusions=data.get('exclusions',[]); ruler=data.get('ruler')
        selected_count=0; pose=None; artifact=None
        if token:
            meta=self.engine.load(token,key)
            if meta['polygon']!=polygon or meta['sensor']!=sensor:
                raise ValueError('区域/传感器已变化，请重新提取点云后保存')
            if ids:
                selected=self.engine.selected(meta,ids,exclusions)
                selected_count=int(selected['selected'].sum())
                if ruler:
                    pose=pose_value(ruler,sensor)
            elif pose_status=='confirmed':
                raise ValueError('确认位姿前须选择叉取面')
        if pose_status=='confirmed' and (not pose or selected_count<3 or not sensor['axes_confirmed']):
            raise ValueError('确认位姿前须有至少3个选定实测点、有效标尺，并确认坐标轴')
        if mask_status=='confirmed' or pose_status=='confirmed':
            mask=raster_mask(polygon,w,h)
            content={'key':key,'polygon':polygon,'token':token,'ids':ids,'exclusions':exclusions}
            artifact=hashlib.sha256(canonical(content)).hexdigest()
            folder=self.directory/'artifacts'; folder.mkdir(exist_ok=True)
            path=folder/(artifact+'.npz')
            if not path.exists():
                if token:
                    if not ids:
                        selected=self.engine.selected(meta,[0],exclusions)
                        selected['selected'][:]=False
                    arrays={'region_source_indices':selected['source_indices'],
                        'face_source_indices':selected['source_indices'][selected['selected']],
                        'region_uv':selected['uv']}
                else:
                    points,mapping=self.engine.registered(canonical(source).decode())
                    yy,xx=np.nonzero(mask); source_ids=mapping[yy,xx]
                    valid=np.isfinite(points[source_ids,:3]).all(axis=1)&(np.linalg.norm(np.nan_to_num(points[source_ids,:3]),axis=1)>1e-8)
                    arrays={'region_source_indices':source_ids[valid],
                        'face_source_indices':np.empty(0,np.int32),'region_uv':np.c_[xx[valid],yy[valid]]}
                stream=io.BytesIO(); np.savez_compressed(stream,mask=mask,**arrays)
                # Content-addressed write is atomic; concurrent identical writes are safe.
                tmp=folder/(artifact+'.'+secrets.token_hex(4)+'.tmp'); tmp.write_bytes(stream.getvalue()); tmp.replace(path)
        state='complete' if mask_status==pose_status=='confirmed' else 'deferred' if data.get('deferred') else 'draft'
        value={'target_key':key,'source':self.row(key),'binding':self.binding,'polygon':polygon,
            'mask_semantics':'coarse_outer_region_including_internal_apertures',
            'sensor':sensor,'geometry_token':token,'selected_faces':ids,'exclusions':exclusions,
            'ruler':ruler,'pose':pose,'selected_measured_points':selected_count,
            'mask_status':mask_status,'pose_status':pose_status,'state':state,
            'reviewer':reviewer,'note':note,'artifact':artifact,
            'human_mask_confirmed':mask_status=='confirmed','human_pose_confirmed':pose_status=='confirmed',
            'metric_pose_confirmed':pose_status=='confirmed' and sensor['scale_to_m'] is not None,
            'automatic_training_eligible':False,'robot_command_eligible':False,'full_six_dof':False,
            'view':data.get('view')}
        if self.units:value['unit_policy']=self.units.info(source)
        if self.axes_info(key):value['axes_policy']=self.axes_info(key)
        old=self.store.get(key)
        if data.get('mask_proposal_id'):
            proposal=self.masks.get(key,old,self.row(key),self.store)
            if not proposal or proposal['proposal_id']!=data['mask_proposal_id']:
                raise ReviewError(409,'掩膜建议或人工修订已变化，请刷新；本机草稿保留')
            value['mask_proposal_provenance']=dict(proposal,adoption='explicit_human_action_pending_review',
                original_polygon=proposal['polygon'],original_review_revision=expected)
            value['mask_semantics']=proposal['mask_semantics']
        elif old and old.get('mask_proposal_provenance'):
            value['mask_proposal_provenance']=old['mask_proposal_provenance']
            value['mask_semantics']=old['mask_semantics']
        return self.store.save(key,expected,value)

    def object_presence(self,key,data,*,restore=False):
        """Target-scoped tombstone, never delete a frame, source box or history row."""
        self.check_axes_client(key,data)
        if data.get('binding')!=self.binding:
            raise ReviewError(409,'数据绑定不一致，请刷新')
        expected=data.get('expected_revision')
        if type(expected) is not int or expected<0:
            raise ValueError('缺少有效修订版本')
        if data.get('confirm_target')!=key:
            raise ValueError('请明确确认当前目标对象；不支持整图或批量删除')
        reviewer=data.get('reviewer','');reason=data.get('reason','')
        if not isinstance(reviewer,str) or not isinstance(reason,str):raise ValueError('标注人与原因必须为文本')
        reviewer,reason=reviewer.strip(),reason.strip()
        if not 1<=len(reviewer)<=80 or not 1<=len(reason)<=500:
            raise ValueError('请填写标注人（1–80字）和删除/恢复原因（1–500字）')
        row=self.row(key);old=self.store.get(key)
        if (old['revision'] if old else 0)!=expected:
            raise ReviewError(409,'其他窗口已修改此目标，草稿仍在本机，请刷新比较后再保存')
        deleted=old is not None and old.get('state')=='deleted'
        if restore!=deleted:
            raise ReviewError(409,'此对象尚未删除，无需恢复' if restore else '此对象已删除，请勿重复提交')
        if restore:
            # Confirmations never automatically return when undoing a deletion.
            retained=dict(old['retained_annotation'])
            retained.setdefault('state','draft')
            value=dict(self.effective_review(retained))
            value.update(state='draft',object_status='active',deletion=None,
                restoration=dict(reason=reason,reviewer=reviewer,restored_at=now(),deleted_revision=expected))
        else:
            b=row['bbox'];x,y,w,h=(b[k] for k in ('x','y','width','height'))
            value=dict(self.effective_review(old)) if old else dict(target_key=key,source=row,binding=self.binding,
                polygon=[[x,y],[x+w,y],[x+w,y+h],[x,y+h]],sensor=self.sensor(key),
                geometry_token=None,selected_faces=[],exclusions=[],ruler=None,pose=None,
                selected_measured_points=0,artifact=None,view=None,note='',
                mask_semantics='coarse_outer_region_including_internal_apertures')
            retained={k:v for k,v in value.items() if k not in (
                'revision','updated_at','deletion','restoration','retained_annotation')}
            value.update(state='deleted',object_status='deleted',
                deletion=dict(reason=reason,reviewer=reviewer,deleted_at=now(),previous_revision=expected,
                              scope='single_target_only',original_source_unchanged=True),
                retained_annotation=retained,geometry_token=None,selected_faces=[],exclusions=[],
                ruler=None,pose=None,selected_measured_points=0,artifact=None,view=None)
        value.update(reviewer=reviewer,event_kind='object_restore' if restore else 'object_deletion',mask_status='pending',pose_status='pending',
            human_mask_confirmed=False,human_pose_confirmed=False,metric_pose_confirmed=False,
            automatic_training_eligible=False,robot_command_eligible=False,full_six_dof=False)
        if self.units:value['unit_policy']=self.units.info(self.source(key))
        if self.axes_info(key):value['axes_policy']=self.axes_info(key)
        # Stale concurrent autosaves cannot resurrect a tombstone, even if the
        # caller somehow supplies its current revision to the ordinary save API.
        return self.store.save(key,expected,value,allow_deleted=True)

    def export_zip(self, keys=None, destination=None, snapshot=None):
        reviews=self.store.all() if snapshot is None else snapshot
        keys=sorted(reviews) if keys is None else keys
        stream=io.BytesIO() if destination is None else destination
        with ZipFile(stream,'w',ZIP_DEFLATED) as z:
            records=[]
            original_records=[]
            for key in keys:
                value=reviews.get(key)
                if not value: continue
                original_records.append(value)
                value=self.effective_review(value)
                records.append(value)
                z.writestr(f'annotations/{key}.json',canonical(value))
                if value.get('state')=='deleted': continue
                source=self.source(key); w,h=source['size']
                poly=value['polygon']; mask=raster_mask(poly,w,h)
                document={'version':'5.0.0','flags':{'mask_human_confirmed':value['human_mask_confirmed']},
                    'imagePath':source['image'],'imageData':None,'imageWidth':w,'imageHeight':h,
                    'shapes':[{'label':'pallet','shape_type':'polygon','points':poly,'group_id':0,
                        'flags':{'human_confirmed':value['human_mask_confirmed']},'pose_annotation':value['pose']}],
                    'source_pcd_sha256':source['source_anchor_hash']}
                z.writestr(f'labelme/{key}.json',canonical(document))
                raw=io.BytesIO(); Image.fromarray(mask.astype(np.uint8)*255).save(raw,format='PNG')
                z.writestr(f'masks/{key}.png',raw.getvalue())
                # COCO uncompressed RLE, Fortran order, explicit original dimensions.
                flat=mask.ravel(order='F').astype(np.int8)
                counts=[]; current=0; count=0
                for bit in flat:
                    if bit==current: count+=1
                    else: counts.append(count); count=1; current=int(bit)
                counts.append(count)
                z.writestr(f'rle/{key}.json',canonical({'size':[h,w],'counts':counts,
                    'human_confirmed':value['human_mask_confirmed']}))
                if value['artifact']:
                    z.write(self.directory/'artifacts'/(value['artifact']+'.npz'),f'point_indices/{key}.npz')
            z.writestr('annotations.jsonl',b''.join(canonical(r)+b'\n' for r in records))
            z.writestr('source_review_payloads.jsonl',b''.join(canonical(r)+b'\n' for r in original_records))
            active=[r for r in records if r.get('state')!='deleted']
            deleted=[r for r in records if r.get('state')=='deleted']
            z.writestr('effective_annotations.jsonl',b''.join(canonical(r)+b'\n' for r in active))
            z.writestr('deleted_targets.jsonl',b''.join(canonical(r)+b'\n' for r in deleted))
            z.writestr('poses.csv',self.csv(records))
            z.writestr('README_zh.txt','独立人工标注快照。原图/PCD不重复包含；按source重连。仅confirmed项为人工确认，draft/pending不是GT。state=deleted为单目标删除标记，不生成掩膜/LabelMe/RLE/实测点标签；effective_annotations.jsonl仅含未删除的已保存目标。annotations.jsonl及deleted_targets.jsonl保留删除审计和恢复证据，不能直接作为有效标签。删除一个目标绝不表示整张图是负例，同图其他目标及原框保留。保留原划分；不自动回流训练。位姿参考点为叉取面宽度中心，非完整6D，不能直接用于机器人控制。')
            z.writestr('manifest.json',canonical({'binding':self.binding,'exported_at':now(),
                'targets':len(records),'active_targets':len(active),'deleted_targets':len(deleted),
                'original_target_denominator':len(self.keys),'deletion_scope':'single_target_not_frame',
                'position_unit':'m' if self.units else 'per_record',
                'unit_policy':self.units.info() if self.units else None,
                'axes_policy':self.axes.info() if self.axes else None,
                'original_data_modified':False,'contains_original_images':False}))
        return stream.getvalue() if destination is None else None

    def start_export(self):
        snapshot=self.store.all()
        token=hashlib.sha256(canonical({'binding':self.binding,'export_code':digest(__file__),
            'unit_policy':self.units.id if self.units else None,
            'axes_policy':self.axes.id if self.axes else None,
            'revisions':{k:v['revision'] for k,v in snapshot.items()}})).hexdigest()
        folder=self.directory/'exports';folder.mkdir(exist_ok=True)
        path=folder/(token+'.zip')
        with self.export_lock:
            if path.exists(): return {'token':token,'state':'complete','targets':len(snapshot)}
            if token in self.export_jobs: return dict(self.export_jobs[token],token=token)
            if sum(v['state']=='running' for v in self.export_jobs.values())>=1:
                raise ReviewError(429,'已有导出正在生成，请稍后重试')
            self.export_jobs[token]={'state':'running','targets':len(snapshot)}
        def work():
            try:
                temporary=folder/(token+'.tmp')
                self.export_zip(destination=temporary,snapshot=snapshot)
                temporary.replace(path)
                with self.export_lock: self.export_jobs[token]['state']='complete'
            except Exception:
                LOG.exception('Export job failed')
                with self.export_lock: self.export_jobs[token]['state']='failed'
        threading.Thread(target=work,daemon=True).start()
        return {'token':token,'state':'running','targets':len(snapshot)}

    def csv(self,records):
        columns=['target_key','frame_id','split','state','mask_status','pose_status','x','y','theta_degrees',
            'position_unit','reviewer','revision','robot_command_eligible','deleted','deletion_reason',
            'workplane_forward','workplane_width','workplane_theta_degrees','forward_axis','forward_sign','up_axis','up_sign']
        stream=io.StringIO(newline=''); writer=csv.DictWriter(stream,fieldnames=columns); writer.writeheader()
        for r in records:
            r=self.effective_review(r)
            row={k:r[k] for k in ('target_key','state','mask_status','pose_status','reviewer','revision','robot_command_eligible')}
            row.update(frame_id=r['source']['frame_id'],split=r['source']['split'])
            row.update(deleted=r.get('state')=='deleted',deletion_reason=(r.get('deletion') or {}).get('reason',''))
            row.update({k:(r.get('pose') or {}).get(k) for k in ('x','y','theta_degrees','position_unit')})
            pose=r.get('pose') or {};position=pose.get('workplane_position') or [None,None]
            row.update(workplane_forward=position[0],workplane_width=position[1],workplane_theta_degrees=pose.get('workplane_theta_degrees'))
            row.update({k:r['sensor'][k] for k in AXIS_FIELDS})
            for k,v in row.items():
                if isinstance(v,str) and v.lstrip().startswith(('=','+','-','@')): row[k]="'"+v
            writer.writerow(row)
        return b'\xef\xbb\xbf'+stream.getvalue().encode()


class PoseHandler(ReviewHandler):
    server_version='PalletPoseReview/1.0'

    def authenticated(self):
        try:
            cookie=SimpleCookie(self.headers.get('Cookie',''))
            return hmac.compare_digest(cookie[COOKIE].value if COOKIE in cookie else '',self.app.cookie_token)
        except (ValueError,TypeError,CookieError): return False

    def body(self):
        if self.headers.get('Content-Type','').split(';')[0]!='application/json':
            raise ReviewError(415,'需要JSON请求')
        origin=self.headers.get('Origin')
        if (self.headers.get('X-Review-Request')!='1' or self.headers.get('Sec-Fetch-Site')=='cross-site'
                or origin and (urlsplit(origin).netloc!=self.headers.get('Host') or urlsplit(origin).scheme not in ('https','http'))):
            raise ReviewError(403,'不允许跨站提交，请从标注页面操作')
        try: length=int(self.headers.get('Content-Length','0'))
        except ValueError: raise ReviewError(400,'请求长度无效')
        if not 0<length<=65536: raise ReviewError(413,'请求为空或过大')
        try: value=json.loads(self.rfile.read(length))
        except (ValueError,UnicodeError): raise ReviewError(400,'JSON格式无效')
        if not isinstance(value,dict): raise ReviewError(400,'需要JSON对象')
        return value

    def dispatch(self):
        try: self.route()
        except ReviewError as exc: self.send_json({'error':exc.message},exc.status)
        except (ValueError,KeyError,TypeError) as exc: self.send_json({'error':str(exc)},400)
        except (BrokenPipeError,ConnectionResetError): pass
        except Exception:
            LOG.exception('Pose review request failed')
            self.send_json({'error':'服务处理失败；请保留本机草稿并重试'},500)

    def route(self):
        parsed=urlsplit(self.path); path=parsed.path; query=parse_qs(parsed.query)
        reading=self.command in ('GET','HEAD')
        assets={'/':('index.html','text/html; charset=utf-8'),'/app.js':('app.js','text/javascript; charset=utf-8'),
                '/app.css':('app.css','text/css; charset=utf-8'),'/ui-font.otf':('ui-font.otf','font/otf'),
                '/FONT_LICENSE.txt':('FONT_LICENSE.txt','text/plain; charset=utf-8')}
        if reading and path in assets:
            name,mime=assets[path]; self.respond(200,(ASSETS/name).read_bytes(),mime); return
        if reading and path=='/healthz':
            self.send_json({'status':'ok','service':'pallet_pose_review','version':UI_VERSION}); return
        if self.command=='POST' and path=='/api/login':
            data=self.body(); key=data.get('key','')
            if not isinstance(key,str) or not hmac.compare_digest(key.encode(),self.app.access_key.encode()):
                raise ReviewError(401,'访问码不正确')
            secure='; Secure' if self.headers.get('X-Forwarded-Proto')=='https' else ''
            self.send_json({'ok':True},headers={'Set-Cookie':f'{COOKIE}={self.app.cookie_token}; Path=/; HttpOnly; SameSite=Strict; Max-Age=2592000{secure}'}); return
        if not self.authenticated(): raise ReviewError(401,'请先输入访问码')
        if reading and path=='/api/bootstrap':
            groups=Counter(r['group_id'] for r in self.app.rows.values())
            self.send_json({'groups':[{'id':g,'count':n} for g,n in sorted(groups.items())],
                'stats':self.app.stats(),'binding':self.app.binding,'ui_version':UI_VERSION,
                'unit_policy':self.app.units.info() if self.app.units else None})
        elif reading and path=='/api/queue': self.send_json(self.app.queue(query))
        elif reading and path=='/api/locate': self.send_json(self.app.locate(query))
        elif reading and path.startswith('/api/targets/'):
            self.send_json(self.app.detail(path.removeprefix('/api/targets/')))
        elif self.command=='POST' and path.startswith('/api/geometry/'):
            key=path.removeprefix('/api/geometry/'); self.app.row(key)
            data=self.body()
            self.app.check_axes_client(key,data)
            if self.app.units and data.get('unit_policy_id')!=self.app.units.id:
                raise ReviewError(409,'位置单位界面已更新，请刷新；旧本机草稿保留')
            self.send_json(self.app.compute(key,data))
        elif self.command=='POST' and path.startswith('/api/adapt-draft/'):
            key=path.removeprefix('/api/adapt-draft/');self.app.row(key)
            self.send_json(self.app.adapt_draft(key,self.body()))
        elif self.command=='POST' and path.startswith('/api/annotations/'):
            key=path.removeprefix('/api/annotations/'); self.app.row(key)
            value=self.app.save(key,self.body())
            self.send_json({'review':value,'stats':self.app.stats()})
        elif self.command=='POST' and (path.startswith('/api/delete-object/') or path.startswith('/api/restore-object/')):
            restore=path.startswith('/api/restore-object/')
            key=path.rsplit('/',1)[-1];self.app.row(key)
            value=self.app.object_presence(key,self.body(),restore=restore)
            self.send_json({'review':value,'stats':self.app.stats()})
        elif reading and path.startswith('/cloud/'):
            parts=path.split('/')
            if len(parts)!=4: raise ReviewError(404,'点云不存在')
            self.app.row(parts[2]); self.app.engine.load(parts[3],parts[2])
            raw=(self.app.engine.cache/(parts[3]+'.bin')).read_bytes()
            etag='"'+hashlib.sha256(raw).hexdigest()+'"'
            headers={'ETag':etag,'Cache-Control':'private, max-age=86400, immutable'}
            self.respond(304 if etag_matches(self.headers.get('If-None-Match',''),etag) else 200,
                raw,'application/octet-stream',headers)
        elif reading and path.startswith('/media/'):
            key=path.removeprefix('/media/'); source=self.app.source(key)
            raw=(self.app.dataset/source['image']).read_bytes()
            if hashlib.sha256(raw).hexdigest()!=source['files'][source['image']]: raise ValueError('原图哈希变化')
            etag='"'+hashlib.sha256(raw).hexdigest()+'"'
            self.respond(304 if etag_matches(self.headers.get('If-None-Match',''),etag) else 200,
                raw,'image/png',{'ETag':etag,'Cache-Control':'private, max-age=86400, immutable'})
        elif reading and path=='/api/export.zip':
            key=query.get('target',[''])[0]
            if key: self.app.row(key)
            self.respond(200,self.app.export_zip([key] if key else None),'application/zip',
                {'Content-Disposition':'attachment; filename="pallet-pose-human-annotations.zip"'})
        elif self.command=='POST' and path=='/api/export-jobs':
            self.body();self.send_json(self.app.start_export())
        elif reading and (path.startswith('/api/export-jobs/') or path.startswith('/downloads/')):
            token=path.rsplit('/',1)[-1]
            if len(token)!=64 or any(c not in '0123456789abcdef' for c in token): raise ReviewError(404,'导出不存在')
            file=self.app.directory/'exports'/(token+'.zip')
            if path.startswith('/api/'):
                self.send_json({'token':token,'state':'complete' if file.is_file() else
                    self.app.export_jobs.get(token,{}).get('state','missing')})
            elif not file.is_file(): raise ReviewError(404,'导出尚未生成')
            else:
                self.send_response(200);self.send_header('Content-Type','application/zip')
                self.send_header('Content-Length',str(file.stat().st_size));self.send_header('Cache-Control','no-store')
                self.send_header('X-Content-Type-Options','nosniff');self.send_header('Content-Disposition','attachment; filename="pallet-pose-human-annotations.zip"');self.end_headers()
                if self.command!='HEAD':
                    with file.open('rb') as stream:
                        for block in iter(lambda:stream.read(1024*1024),b''): self.wfile.write(block)
        elif reading and path=='/api/export':
            fmt=query.get('format',['jsonl'])[0]; records=[self.app.effective_review(v) for v in self.app.store.all().values()]
            raw=self.app.csv(records) if fmt=='csv' else b''.join(canonical(r)+b'\n' for r in records)
            self.respond(200,raw,'text/csv; charset=utf-8' if fmt=='csv' else 'application/x-ndjson',
                {'Content-Disposition':f'attachment; filename="pallet-pose-annotations.{"csv" if fmt=="csv" else "jsonl"}"'})
        else: raise ReviewError(404,'页面或接口不存在')


class PoseServer(ReviewServer):
    def __init__(self,address,application):
        self.application=application
        # Use the common threaded HTTP lifecycle with this application's routes.
        super(ReviewServer,self).__init__(address,PoseHandler)


def main():
    parser=argparse.ArgumentParser(description=__doc__)
    parser.add_argument('--host',default='127.0.0.1'); parser.add_argument('--port',type=int,default=3390)
    parser.add_argument('--reviews',type=Path,default=DEFAULT_REVIEWS)
    parser.add_argument('--dataset',type=Path)
    args=parser.parse_args()
    dataset=args.dataset or Path(json.loads((PROJECT/'configs/active_formal_dataset.json').read_text())['dataset'])
    boundary(args.reviews,[dataset,PROJECT/'outputs/pallet_structure_human_review_v1',
        PROJECT/'outputs/pallet_pose_annotations_v1',PROJECT/'outputs/pallet_pose_dataset_v2',PROJECT/'outputs/pallet_pose_training_v1'])
    args.reviews.mkdir(parents=True,exist_ok=True)
    logging.basicConfig(level=logging.INFO,format='%(asctime)s %(levelname)s %(message)s')
    with (args.reviews/'server.lock').open('a') as lock:
        fcntl.flock(lock,fcntl.LOCK_EX|fcntl.LOCK_NB)
        app=PoseApplication(dataset,args.reviews); server=PoseServer((args.host,args.port),app)
        (args.reviews/'runtime.json').write_bytes(canonical({'pid':os.getpid(),'port':server.server_port,
            'started_at':now(),'targets':len(app.keys),'binding':app.binding,'database':str(app.store.path)}))
        LOG.info('Pose editor ready on %s:%s; %s targets',args.host,args.port,len(app.keys))
        try: server.serve_forever(poll_interval=.5)
        except KeyboardInterrupt: pass
        finally: server.server_close()


if __name__=='__main__': main()
