7.9 KiB
私有资料上传内部实现与验证
日期：2026-10-12；未上线，真实上传默认关闭。按已批准的简化范围完成上传照片、本人预览、本人删除，没有恢复复杂提案。融资28项、29页面、63任务保持；产品机构库、已回撤产品AI、短信默认关闭均保持。两仓既有未提交短信/协议改动保留，仅在协议读取控制器追加本人资料引用，无提交、推送、PR、生产连接、迁移、发布或真实短信/模型请求。
实现与边界
后端 PrivateDocuments 和 v1/Documents 提供三个接口：multipart POST /api/v1/documents（file、category、consentId）、Bearer GET /api/v1/documents/:id/content、JSON {} POST /api/v1/documents/:id/delete。返回附件ID字符串，不返回文件路径或公开地址。类别沿用身份证正反面、银行卡、收入证明、营业执照、银行流水、经营证明。
照片仅接收真实JPG/PNG，原图和处理后文件均不超过5MiB，长宽不超过4096、总像素不超过400万。沿用头像的图片解码及PNG重编码方法，去除用户文件名、元数据和尾随内容，再用已有Secret/AES-GCM密钥加密保存。fa_private_document 记录归属、随机storage_key、类别、格式/大小、同意ID及创建/删除时间，不进入公开attachment表。单表SQL同步到schema，仅安装于本轮合成隔离库。
存储配置 private_documents.enabled=false、directory=''。需操作者明确提供已存在且位于Web目录外的本地目录；目录不能与Web根重叠，也不能是Web根的祖先。未配置时拒绝，运行代码不创建正式目录。私有文件0600，正式目录ACL、备份、密钥托管及恢复方式仍需运营确认；本轮不拟定生产保留期限。
上传在用户锁内复核Token及本人未撤销的documents同意记录，与同意撤销使用相同锁顺序；撤销后禁止新上传，本人仍可读/删已有资料。明确的保存失败清理本次文件；提交回执未知保留加密文件并报DOCUMENT_SAVE_UNKNOWN，用户手动重试可能产生另一份照片，不自动重发。删除先提交不可读标记，再移除文件；只有确认文件不存在才报成功，失败保留同ID供重试。无云层、命令账本、租约、复杂状态机或清理worker。
小程序复用原资料卡片。复用现有协议服务取得服务端同意记录；未确认不得选图上传。保存失败显示“未上传·重试”，删除失败显示“删除未完成·重试”；上传成功后直接在原上传卡片显示所选照片缩略图，查看／删除从卡片菜单操作；同类多张先选择照片再管理，不在下方新增独立列表。重新进入资料步骤时按类别携带Bearer下载恢复缩略图，预览重新携带Bearer下载，不在URL中携带Token、不存相册。页面及会话守卫拒绝退出、换账户和离页后的迟到回包，清空临时路径引用，原生端尽力删除下载临时文件。查看协议时保留当前自填表单与服务端ID；文件路径不传给确认流程。
资料仍选填，照片单独保存、未核验、暂不参与评估，不做OCR、自动核验或外部查询。确认页明示边界；已取得合法服务端ID的照片不再触发旧“上传未开放”拒绝，但未上传/删除未完成的选择须先处理。评估JSON仍发送空documents/consentIds，只提交自填信息；服务端继续拒绝任何非空评估附件或授权。外部查询选择继续拒绝，不把本机路径当附件ID。
三个业务接口保持。复用现有GET /consents?scope=documents返回独立documents字段：按当前登录user_id读取全部资料ID／类别／consentId／deletePending，不暴露路径，不受同意分页、版本或撤销状态限制。已物理删除的ID不再显示，删除未完成且文件仍存在的ID可恢复重试。未启用时返回空引用，不查询未安装的资料表。普通离页、提交成功、刷新后重新进入均从服务端恢复，不把私密图片路径持久保存。同类全部ID可通过原卡片逐份管理，未上传项优先处理，未知回执后重新读取不会遮住本地重试／移除入口。未知保存回执若已提交入表可恢复ID；未入表的孤立加密文件仍需正式启用前明确运营处理方式，本轮不增加清理worker。
验证证据
本轮新建专属MySQL/Redis/ROOT/存储环境：D:/AAdesk/202609/airz-backups/private-documents/1791787367342。默认生产.env未读取，独立ENV_PREFIX与全新合成空库，Token/队列使用独立Redis DB15和命名空间；模型客户端被类替身拦截，短信关闭。只读取旧隔离工具的实现参考，没有复跑已清理协议runner。
| 验证 | 最终结果 |
|---|---|
| 私有照片真实HTTP/SQL/文件专项 | 168项、44次本机HTTP通过 |
| 公开头像回归 | 268项、76次本机HTTP通过 |
| 原有协议后端回归 | 351项、86次本机HTTP通过 |
| UTS服务/页面/评估边界 | 26组场景通过 |
| 既有协议纯源码 / 微信分包 | 30项 / 31项通过 |
| Android / 微信 | 当前29页编译通过；日志android.log / mp.log |
| 受控H5 | 58项、39合成API、12POST，0运行错误、0未知外呼 |
上传专项覆盖PNG/JPG、重编码/加密、非法图片/GIF、原大小/长宽/像素超限、缺少文件、未登录/跨用户、撤销同意、篡改密文、SQL插入失败与文件清理、物理删除失败后不可读与同ID重试、公开目录拒绝、评估附件拒绝和撤销Token。前端覆盖回执校验、Bearer下载、原会话401不得清除新账户、失败重试、离页/退出/换账户迟到响应、删除回执确认、协议往返保留表单、照片不进入评估JSON。
页面副本：C:/Users/JUN/AppData/Local/Temp/airz-private-documents-ui-1791787367342，仅副本配置改为synthetic.invalid；新建5181预览，导航前拦截全部网络，业务响应仅在进程内合成，原5174服务保持。Browser插件未提供，使用已有Playwright及非持久Chromium，无新增依赖。390×844和1280×900截图核对无横向裁切；三条console 503来自故意模拟一次上传关闭和两次删除失败，0未解释的业务错误。H5共享layout已有类型警告保持，不等同真机下载/临时文件清理验收。
Android最终编译15:57:08、微信15:58:32（2026-10-12，Asia/Shanghai）。独立审查先后发现离页丢失ID和恢复后遮住同类待上传项，均先复现红测试后修复；新增卡片缩略图／多份管理／迟到清理场景通过；自动缩略图不得删除手动预览的临时文件，同类多张菜单分组以满足微信六项限制。开发途中缺少接口红测试、缺少文件的错误处理、Android局部前向声明及匿名函数默认参数问题已定位修正；测试首次清理触发框架无条件删除保护、独立H5环境标记及页面选择器问题也已修正。失败或重复运行不累计。source-manifest.json仅绑定本次相关运行文件和测试入口，不是整仓或发行包摘要。最终verification与cleanup回执由本轮归档记录：29张合成表零行、Redis零键、私有目录零文件后删除精确合成库并停止所属MySQL／Redis；最后58项H5通过后关闭非持久浏览器及5181的所属进程和子进程。重启预览冷编译阶段曾加载超时并触发取DOM错误，已补全finally关闭保护，待编译完成后最终复验通过；失败或重复运行不累计。归档含合成私密配置，不整包共享。
正式启用条件
正式资料用途、协议正文/版本、保存期限、撤销后处理、实际私有目录及ACL、容量/备份/密钥恢复、孤立文件运营处理方式，以及微信/Android真机选择/下载/临时文件清理仍待确认。FILE-001保持阻塞；FILE-002/004仅内部开发完成，正式验收未完成；FILE-003原内部协议实现状态保持。附件绑定评估另做最小集成，不将上传成功或本轮编译当作已核验、已进入分析或正式上线。