验收管家 - 系统架构设计文档 v1.0

graph TB
    subgraph Browser["浏览器（验收人/管理员）"]
        HTML["uat.html
单文件前端（零构建）"]
        LS["LocalStorage
离线缓存 + 身份持久化"]
    end
    subgraph CF["Cloudflare Pages"]
        PF["Pages Functions
后端 API（14+ 端点）"]
        D1["D1 (SQLite)
生产数据库"]
    end
    HTML -- "fetch /api/*" --> PF
    PF -- "SQL 查询" --> D1
    HTML -- "读写缓存" --> LS
    LS -. "离线/弱网兜底" .-> HTML

erDiagram
    projects ||--o{ testers : "1:N 按项目隔离"
    projects ||--o{ test_cases : "1:N 用例模板"
    projects ||--o{ shares : "1:N 分享链接"
    testers ||--o{ results : "1:N 验收结果"

    projects {
        TEXT id PK "项目唯一标识"
        TEXT name "项目名称"
        TEXT description "描述"
        TEXT owner "负责人"
        TEXT status "active/archived"
    }
    testers {
        INTEGER id PK "自增主键"
        TEXT project_id FK "所属项目"
        TEXT name "验收人姓名"
        TEXT emp_id "工号"
        TEXT org2 "二级机构"
        TEXT org3 "三级机构"
    }
    results {
        INTEGER id PK "自增主键"
        TEXT project_id "所属项目"
        TEXT tester_name "验收人姓名"
        TEXT case_id "用例标识"
        TEXT status "pass/fail/partial"
        TEXT remark "备注（含截图）"
        TEXT sync_time "同步时间"
    }
    test_cases {
        INTEGER id PK "自增主键"
        TEXT project_id FK "所属项目"
        TEXT module "功能模块"
        TEXT sub_module "二级模块"
        TEXT scenario "验证场景"
        TEXT expected "预期结果"
        INTEGER sort_order "排序"
    }
    shares {
        TEXT id PK "8位短链ID"
        TEXT project_id "所属项目"
        TEXT cases_data "用例JSON"
        TEXT expires_at "过期时间"
    }

sequenceDiagram
    participant U as 用户浏览器
    participant API as Pages Functions
    participant D1 as D1 数据库

    U->>API: POST /api/login {name, empId}
    API->>API: 匹配 ADMIN_WHITELIST
（姓名或工号）
    alt 命中白名单
        API->>API: HMAC-SHA256 签发 token
（12h 有效期）
        API-->>U: {isAdmin: true, token, name}
        U->>U: 存储 token + testerInfo 到 LocalStorage
    else 普通验收人
        API-->>U: {isAdmin: false, name}
        U->>U: 仅存储 testerInfo
    end

sequenceDiagram
    participant U as 用户浏览器
    participant LS as LocalStorage
    participant API as Pages Functions
    participant D1 as D1 数据库

    Note over U,D1: 上传（防抖 30s）
    U->>LS: saveResults() 写入本地
    U->>API: POST /api/data {results, testerInfo, testData}
    API->>D1: INSERT OR REPLACE results（批量）
    API-->>U: {success: true}

    Note over U,D1: 加载（页面初始化）
    U->>API: GET /api/data?project=X&tester=Y
    API->>D1: SELECT FROM results
    D1-->>API: rows
    API-->>U: {results, testerInfo, syncTime}
    U->>LS: 缓存到本地

    Note over U,D1: 定时轮询（每 5 分钟）
    U->>API: GET /api/meta?project=X&tester=Y
    API-->>U: {syncTime, resultCount}
    U->>U: 比较 syncTime 判断是否有更新

sequenceDiagram
    participant Admin as 管理员
    participant UI as 前端
    participant API as Pages Functions
    participant D1 as D1 数据库

    Admin->>UI: 概览页点击"详情"
    UI->>API: GET /api/data?project=X&tester=张三
    API->>D1: SELECT FROM results WHERE tester_name='张三'
    D1-->>API: rows
    API-->>UI: {results, testerInfo}
    UI->>UI: 保存 _originalResults
    UI->>UI: 设置 _viewingOtherMode=true
    UI->>UI: 替换 results 为张三的数据
    UI->>UI: renderTable()（只读模式）
    Note over UI: 返回列表时 resetViewingOtherMode() 恢复

sequenceDiagram
    participant Admin as 管理员
    participant API as Pages Functions
    participant D1 as D1 数据库
    participant User as 被分享人

    Admin->>API: POST /api/share {cases: [...]}
    API->>API: 生成 8 位 shareId
    API->>D1: INSERT INTO shares (id, cases_data, expires_at)
    API-->>Admin: {shareId: "abc12345"}
    Admin->>Admin: 拼接分享 URL

    Note over User,D1: 被分享人访问
    User->>API: GET /api/share/abc12345
    API->>D1: SELECT FROM shares WHERE id='abc12345'
    D1-->>API: row
    API->>API: 检查 expires_at 是否过期
    API-->>User: {cases: [...], createdAt}
    User->>User: 加载用例模板到页面