THAMO 阶段1接口与运行说明

状态：本地开发实现，端口18874，schema v4；不是已部署的公网THAMO版本。旧AGLO公网接口/数据库保持原状。启用需要显式THAMO_STAGE1=1及已迁移的独立数据库；默认关闭是后端版本/迁移边界，不是客户端隐藏功能或审核分流。

启动与凭据

使用仓库.venv（requirements包含Pillow13）。AGLO_CONFIG_DIR指向受控配置目录，AGLO_PORT=18874，THAMO_STAGE1=1；开发演示额外THAMO_SYNTHETIC_FIXTURES=1标明合成样本。当前本地配置在.stage1/private/，被Git忽略且0700/0600。管理员凭据在该目录admin-access.json，不写入报告或APK。数据库为thamo_stage1，测试为thamo_stage1_test，分析账号仅SELECT指定表；不连接贷款库。

旧/v1/sms/*仍使用原密文表；新THAMO三类数据使用下述显式同意与明文业务字段。没有自动解密/迁移旧短信。正式迁移与上线另走后续阶段，现有APK尚未切换这些新接口。

账户与设备

复用/v1/auth/otp、/v1/auth/verify、/v1/me、/v1/logout、/v1/session/refresh。Bearer会话在服务端绑定账户和installation，不能通过请求中的user_id切换所有者。开发服务只使用模拟器运输；自动测试/演示采用受控捕获的随机码，没有固定公共验证码或测试登录入口，没有商业短信发送。

三类记录

kind为sms/apps/calls。

• POST /v1/records/{kind}/consent：enabled布尔、policy_version=thamo-v1；返回revision。

• POST /v1/records/{kind}/sync：batch_id、consent_revision、cursor、scan_status=completed或partial、complete布尔、records列表（0–100）。完整扫描才允许complete=true。每批上限1MB。

• GET /v1/records/{kind}?page=1：当前账户当前设备，每页50。

• POST /v1/records/{kind}/delete：confirm=true；删除当前设备对应记录和ACK并关闭该类同步。

record公共字段source_id、event_time（Unix秒）；SMS为body/address/direction，App为package_name/version/signature_sha256或null/install_source，call为number/direction/duration_seconds/可选line。额外传身份字段会拒绝；字段长度/类型/时间与批次整体校验。body/address为可查询业务列，其他类型字段存JSON payload，可用MySQL JSON函数查询。

ACK含batch_id、kind、acknowledged_cursor、server_time、complete及inserted/updated/duplicates/excluded。首次请求完成事务后返回；同key异内容409；同key同内容返回原ACK和replayed。撤销再授权后revision改变，新旧batch都必须使用新的同意版本；旧队列不接受。最新ACK按数据库递增序号，不按客户端batch_id或秒级时间排序。

状态与100分

GET/POST /v1/protection/status；POST仅接受claims对象，布尔字段为sms_role/sms_permission/sms_detector_ready、phone_role/call_permission/screening_role/call_service_ready、app_visibility_complete/app_scan_complete/app_intelligence_valid。

当前有效账户10分；每类需角色/功能就绪、当前同意版本、完成扫描的服务端ACK，且ACK在24小时内才得30分。状态过24小时无更新显示stale/上次分数；无活跃设备会话显示signed_out/0。角色信息来自设备声明，服务器只直接证明会话和ACK，不把它称OS独立认证。合成演示设备声明均未就绪，所以实际显示10分而不是假100。

举报与信任

• POST /v1/reports：JSON文字/URL，或有界multipart图片；Idempotency-Key必填。kind=sms/url/image，text、note，submit_consent=true、policy_version=report-v1；图片字段attachment。

• 图片PNG/JPEG，输入5MB以内、最多16MP，重编码为去EXIF JPEG并缩至2000边长以内；原始字节及处理后字节均受限。单进程图片解码最多1个，举报解析最多2个；忙时503。当前报告预算60/小时300/天，为单进程保护而非计费硬额度；单用户另有数据库每小时20条限制，解码前先检查身份/限额。

• 返回202 received仅证明内容和任务已持久化；分析工作进程在阶段3接入，当前真实记录保持queued，不假造Gemini结论。

• GET /v1/reports、GET /v1/reports/{id}、GET /v1/reports/{id}/attachment：仅当前账户。

• DELETE /v1/reports/{id}：取消任务、抹除正文/派生文本，附件进入持久清理队列，删除失败可重试；已删idempotency key返回410，晚到结果不能复活。

• GET/POST /v1/trust-rules/personal、DELETE /v1/trust-rules/personal/{id}：只允许个人作用域，不能写全局身份白名单。个人放行不关闭内容检测。

• POST /v1/account/delete，confirm=true：清理账户关联记录、会话、旧档案、本人信任和手机号锁，图片清理任务不依赖已删除的账户FK。

后台与维护

/admin登录；/admin/thamo为只读工作台，可按view、user_id、installation_id、q、page、since/until（UTC日期）和适用risk筛选。短信/举报正文不在列表自动显示；/admin/thamo/raw读取时记录管理会话指纹、目的、记录和对象，不记原始cookie。只有管理身份可访问；/admin/thamo/health列出队列与阶段边界。

附件不在公开静态目录。每60秒维护一次到期清理：截图30天、原始记录/举报180天、审计365天；失败文件在thamo_file_gc中保留待重试。任务租约超时可恢复，最多3次尝试（2次重试）后failed；这里只交付队列和状态保护，不运行真实图像分析。全局指标发布、界面编辑规则和版本下发在阶段3补齐，不把只读页当全部运营功能已交付。

迁移：tools/migrate_thamo.py需显式schema-owner配置与thamo_库名；应用DML账号不运行DDL。回退v4会删除新增表及新增数据，运行版本回退应先停THAMO扩展并保留表；使用回退脚本前先备份，不能用删除表代替业务回滚。已在独立迁移测试库完成新建、回退至v3、重加v4，不触原AGLO库。

备份：tools/backup_thamo.py使用私有defaults文件调用本机MySQL8.4客户端，密码不在命令行；gzip校验并保留14天。本地已执行一次，不声称已配置生产定时备份或异地容灾。

复验

THAMO_TEST_DB_CONFIG显式指向thamo_stage1_test，AGLO_TEST_DB_CONFIG显式指向既有隔离aglo_account_test，再用.venv/bin/python -m unittest discover -s backend -v。测试会清理这两个指定测试schema；不得连接业务数据库。真实模型、运营商、实际设备与Play结果在后续阶段单独验收。