文件
dayu-color/大鱼调色主APP开发交接.md

20 KiB

当前主 APP、本机安装与公测通道版本见 开发交接.md。本文件保留主 APP 的历史交付与设计记录。

2026-11-02 更新:主 APP 已交付 1.7.0(45)公测。自动更新和云端诊断已经接入,当前实现与部署/隐私/回滚说明见 Backend/README.md,发行与验证见 Packaging/Release-1.7.0.md 和 verification/BetaClientQA.json。下方原始交接保留作背景;登录、授权和业务加密仍未实施,不能把原规划当成已完成状态。

大鱼调色主 APP 开发交接

2026-11-02接续:主APP UI与自动注册已在1.6.1(44)实现,发布地址置顶、注册成功3秒倒计时、FCP由用户确认,外层沙盒按用户明确要求关闭。登录/授权/加密/更新及后端未实现;本文原接口盘点仍作为后续参考。最新行为见本轮说明,交付状态见verification/Delivery.json与MainApp1.6.1.json。

交接日期:2026-11-02(Asia/Shanghai)。下一阶段目标:优化现有主 APP,加入自动更新、登录验证及相应的账号与版本管理界面。本次只整理交接和只读盘点,尚未实现这些功能,未修改正式 APP、后台源码、账号绑定或线上更新清单。

1. 接手位置与可恢复基线

项目 已核实内容
项目根目录 /Volumes/备份/大鱼调色/大鱼调色
工程与方案 大鱼调色.xcodeproj;Wrapper Application,Release
源码远程 https://dayu.media/git/dayu/dayu-color.git,main;保持现有可见性
本次盘点前的已推送节点 46fb091479ef24c86c3706bdf36ca97e2597edd9,已回读远程确认
正式版本 1.6.0(39),实际编译源码 e5affd3f097fc96f87f41be8e1a3f131ed01daeb
发行标签 v1.6.0-print-looks-20261102,提交 0cc51149a6f21ebe09465b4fd7130451bedd57bb
唯一正式安装 /Library/Plug-Ins/FxPlug/大鱼调色.app
外层 APP / 内部服务 ID com.dayu.color / com.dayu.color.XPC
环境 Apple Silicon,macOS 14.6 或更新;上一轮 FCP 12.4 实测通过
固定构建缓存 /Users/mac/Library/Caches/CodexBuilds/com.dayu.color

“主 APP”指现有 FxPlug 外层包装 APP。它与嵌套的插件一起交付,后续将这个现有窗口扩展成产品入口。继续保持产品名称、Bundle ID 和正式安装位置,避免另建一个 /Applications/大鱼调色.app 与插件包装 APP 并存。

程序源码、标签、安装包与交付记录是不同节点。文档后续提交不会改变上述实际编译 SHA,也不需要仅为本次交接重编译、增加构建号或重新发布安装包。

2. 主 APP 当前实际实现

外层是 Objective-C / AppKit,手动内存管理;main.m 调用 NSApplicationMain,MainMenu.xib 创建窗口和代理。窗口内容在 AppDelegate.m 中以代码构建,目前为 540×280:产品名、安装说明和“打开 Final Cut Pro”按钮。最后一个窗口关闭后退出 APP。

文件入口 用途与接手注意点
AppDelegate.m 当前完整主窗口;扩展账号、版本、更新和插件状态的直接入口
main.m APP 启动入口
MainMenu.xib 主菜单、窗口及 AppDelegate 连线
APP Info.plist 版本 1.6.0 / 39,主 Nib 与身份
APP entitlements 当前仅有 com.apple.security.app-sandbox = true;正式安装 APP 实际签名也核对为此配置
Xcode 工程 外层 APP 和 XPC Service 两个目标;同时更新它们的身份与版本约定
插件入口 宿主状态冻结与渲染;当前没有接入账号授权
插件检查器 现有调色面板和网站链接;主 APP 的控制中心不应搬走这些调色控件

当前未发现产品已有的网络账号服务、Keychain 会话管理、主 APP / XPC 共享授权收据、更新客户端、Sparkle/appcast 配置或自有安装更新助手。不能把已有“更多插件访问 https://dayu.media”链接当作登录接入。

openHost: 当前只查找 com.apple.FinalCut。后续优化启动与宿主状态识别时,应覆盖打包指南中的四个 FCP/Motion 标识,并处理未安装、运行中和打开失败;不要用模糊应用名启动不明副本。

3. 后端现状:已只读查看生产源

2026-11-02 已核对目标共享由 smbfs 挂载,生产目录可读:

NAS_SERVER = 192.168.31.21
SMB_SHARE = dayumedia (存储空间1)
NAS_ROOT = /Volumes/dayumedia (存储空间1)/wwwroot/dayu_media
LOCAL_CONTEXT = /Users/mac/Downloads/dayumedia

LOCAL_CONTEXT 是有范围的专项工作资料,不是完整生产镜像。NAS 的 AGENTS.md 保留旧电脑 /Users/dayu 路径,执行时按本机全局规则适配,不能照搬旧路径。

本轮只读源码与公开接口形状,没有调用登录/授权接口、创建会话、读取数据库、签名私钥、设备记录或客户凭据。下面是生产源码盘点,不等同于“大鱼调色”已完成接口联调或已配置专属产品。

通用登录、权限与更新

主要生产文件:

macos-app-auth.php

本轮源码 SHA-256:8a4cb46bf33a88501da5cf48fa4059244dcffb5cfac55c7ecdf66152204cf493。约 12,518 行;下一次接手重新读取最新生产源,行号只作定位。

现有入口 本轮源码确认的行为
POST https://dayu.media/wp-json/dayu-app/v1/login/session app_create_login_session,约 6458 行;接收 device_uuid、app_name、client_version、client_build、client_bundle 等,返回临时会话、登录 URL、二维码和到期时间;使用现有微信登录
GET https://dayu.media/wp-json/dayu-app/v1/login/session/{session_key} app_get_login_session,约 6546 行;通用接口返回状态、说明和到期时间,不能假定这里直接返回访问令牌
https://dayu.media/wp-admin/admin-ajax.php,action=app_device_login app_device_login,约 510 行;按已绑定的标准 Mac 硬件 UUID 登录,返回账号、token、refresh_token 等;会记录登录及绑定状态,不是无副作用探针
同一 AJAX 入口,action=app_refresh_token 刷新令牌,约 1490 行;具体请求与失败码接手时重新核对
POST https://dayu.media/wp-json/dayu-app/v1/access rest_check_access,约 1440 行;验证 token,结合文章购买/会员查询权限,满足条件可附带签名设备授权
同一 AJAX 入口,action=app_check_update 约 1181 行;校验登录 token,按应用和 stable 等通道读取更新清单;接受当前版本/构建号,返回是否更新、目标版本/构建、包类型、安装方式、大小和 SHA-256 等
同一 AJAX 入口,action=app_download_update 约 1272 行;下载对应应用云空间的更新包;认证、重定向及请求参数仍需在下一阶段逐项联调

源码中已有 RS256 的 DAYU-OFFLINE-DEVICE 凭证:登录得到的 scope=device_binding 只表示设备身份;资源授权查询可生成 scope=app_access,并包含文章、权限原因、是否永久及到期信息。方法入口约 2200、2379、2413 行。不能用“已登录”“设备已绑定”或响应中自带的公钥,直接证明拥有本产品使用权。

通用源码中未发现 com.dayu.color / DayuColor / dayu-color 的字面定义;本轮没有检查数据库中的产品配置或创建专属更新空间,因此不能断言线上已有或没有相应配置。接续时核实稳定的产品标识、文章 ID、授权策略与更新通道,不使用缺省 default-app。

可参考但不能当作本产品接口的部分

  • dayu-downloader-auth.php:身份、试用和 /dayu-downloader/v1/update。当前硬绑定 DayuDownie、DayuDownie.DayuDownie、文章 14922 及其更新目录,不能给大鱼调色直接调用。
  • dayu-downloader-licenses.php:另一产品的注册码与授权桥接,不继承其试用期、设备限制和商业规则。
  • dayu-template-app-session.php:模板工作区已有 APP 身份换取网站会话的独立实现;不是本产品已完成登录的证据。
  • 本机 /Users/mac/Downloads/dayumedia/permission-fix 有购买授权修复记录与测试,可参考历史陷阱;使用前先与生产源比较。大鱼 Git 的登录令牌只用于代码仓库,不能打包成普通产品用户的账号凭据。

4. 下一阶段的实现拆分

主 APP 界面

在现有外层 APP 内组织产品信息、账号状态、更新状态、打开宿主、网站/帮助入口。账号区区分未登录、登录中、已登录但未授权、已授权、到期和离线;更新区区分检查、下载、校验、等待宿主退出、安装及失败。窗口保持可调整、中文信息清楚,技术日志放在单独诊断入口。

可以沿用 AppKit 或评估逐步引入 SwiftUI;本轮未选定 UI 框架、第三方更新库或新最低系统版本。重构时保留 Nib 启动与既有 Objective-C 生命周期,避免只替换窗口而漏掉应用代理或目标成员关系。

登录、授权与插件进程

  1. 先核实网站产品策略:固定产品名/slug、文章 ID、会员或单独购买条件;由可信配置约束产品与权限对应关系,不接受任意客户端文章 ID 就当作“大鱼调色授权”。
  2. 对照现有通用流程实现会话创建、默认浏览器/二维码登录、状态轮询、设备登录、token 刷新和退出。支持过期、取消、网络失败及重复点击;日志不记录临时会话 URL、令牌、完整设备 UUID。
  3. 在线 token / refresh token 使用 Keychain。当前 APP 仅有沙盒权限,需按实际联网、Keychain 与跨进程方案配置权限;不要假定现有签名已开放网络访问。
  4. APP 和插件是不同进程,外层关闭后 FCP 仍可启动服务。若用户要限制插件使用,需要设计 XPC 也能验证的产品授权收据与状态更新机制;只在主 APP 上挡一个登录页面不足以限制插件。
  5. 核实服务器签名凭证的产品、scope、设备、文章、期限和可信公钥合同。客户端只携带验证公钥,私钥留在服务器。响应随附的任意公钥不能自行成为信任根;轮换须有明确的可信路径。
  6. 凭据共享方式尚未决定。当前没有 App Group / Keychain Access Group 配置,需要核对外层、服务的实际权限与部署要求,再选共享位置;禁止把长期令牌塞进 MOEF、用户预设或时间线载荷。
  7. 网络检查和账号刷新放在渲染之外。帧渲染/跟踪任务只读取已经验证的状态快照,不逐帧联网或等待主 APP 窗口。

自动更新

本产品外层 APP 在 /Library/Plug-Ins/FxPlug,PKG 还安装用户模板与预览图。先复用完整的正式 PKG 路径设计更新流程,不能只下载 APP 替换而漏掉模板、内部服务登记或旧进程。

实现顺序:检查专属通道 → 比较版本与构建 → 后台下载 → 校验大小/SHA-256 → 核验包签名、团队和预期产品 → 等待宿主与用户任务安全退出 → 通过系统授权安装 → 核对固定路径、版本与 PluginKit → 正常重开并报告结果。客户端自己退出后谁负责完成安装、接收取消/失败结果及重新启动,也需要明确实现。

更新过程中不能强杀 FCP/Motion;沙盒 APP 不应尝试直接静默覆盖 /Library。系统安装授权、用户取消、宿主未保存、磁盘不足、断线续传、损坏包、安装失败和重启恢复应有明确状态。先核实当前 macOS 与安装机制的官方文档再实现特权/辅助进程,不因要“自动更新”而取消签名、公证或系统授权。

现有 Release373 是发行包归档,不是已接入的 APP 更新源。后台专属更新清单尚未部署。新增 feed 时保持 APP、模板、最终 PKG、网站更新清单与 Git Release 关联同一发布记录;更新清单不能指向另一候选构建。

5. 尚待确定的产品规则

这些是后续实际开发前需要确定的业务条件,本交接不替用户决定,也不因此阻止当前文档交付:

  • 登录只服务账号与更新,还是也决定插件可否渲染;未登录、到期后新实例和已保存工程分别如何表现。
  • 大鱼调色对应的商品文章 ID、产品 slug、会员/单购关系;是否提供试用、试用期限及设备数。
  • 离线使用期限、联网复核周期、会员到期、设备解绑、退出账号的生效方式;不得照搬其它产品的永久/24 小时试用策略。
  • 自动更新的检查/下载默认设置、稳定或测试通道、是否允许降级;维护主 APP 与插件完整包的一致性。

“到期后把老工程变黑/加水印”或“永远离线放行”都不是用户已经确认的要求,不应在实现时自行加入。

6. 必须保留的现有产品行为

完整调色、CST、蜘蛛盘、LUT 浏览、胶片六页(含八种印片)、通道混合器、独立叠层、蒙版与轨迹都继续使用当前实现。不得为账号/更新 UI 重排旧参数 ID、改变 Uniform 布局或清空用户设置。

当前完整 Uniform 为 1312 字节;八印片追加前 1296 字节前缀保留。完整预设 v6 读取 v1–v5,工具状态、LUT 路径、蜘蛛盘与蒙版轨迹另有归档合同。

MOEF 目前为 5.11 / Motion 5.4.5,作者和网站两行已移除,主标题内保留用户要求的可点击网站链接。不要恢复旧版权 Rig。全局技能检查器对 5.11 的版本 guard 不支持,项目级原生样本检查及当前宿主通过;不能把 guard 结果伪造成技能检查通过,也不能为此随意升高模板版本。

自动映射的新 FCP 效果、全部还原及新独立一级层默认开启。FCP 沿用模板默认的旧主效果也会跟随开启;手动关闭可保存并冷重开保持。后续不得再把“修改默认值”当作一定不会改变旧工程的无风险操作。详情见现有 FxPlug 交接。

7. 构建、发布与验收入口

入口 当前作用
tools/deliver.py Release 构建、逐层签名、公证、票据、唯一安装、正式路径自检和等待宿主验收;验收成功后输入 complete
Packaging/build_pkg.py 从已验证正式安装生成完整 FxPlug PKG,调用 PKG 工坊签名/公证及展开验包
Packaging/publish_release.py 对已推送标签上传最终包,草稿及正式完整下载校验
tools/build_template.py 仅在模型确有变更时重新导出参数/模板;变更后同步静态检查和摘要
tools/checkpoint.py 对已审查的明确文件提交、推送和回读 SHA,使用仓库锁

正式身份:Developer ID Application: zhong luo (B3W25FX5H5) 与对应 Installer 身份,公证 profile codex-dayu-notary-B3W25FX5H5。每次发布重新验证有效性,不复制私钥/账户专用密码。正式 APP 公证 ID 5d74c04c-8a30-47e9-822d-4f616dfdee56;PKG 公证 ID 4716e3c7-8199-4dc1-940c-2376dd647e9b,均 Accepted。

当前正式 PKG:/Volumes/备份/大鱼调色/发行包/大鱼调色-1.6.0.pkg,40,833,847 字节,SHA-256 13821631b5d54f1b9c1934c513a9cc7e92641208e20219839a63e23865f21cca。Release373 / 附件18已完成真实完整下载核对,标签296文件独立恢复通过。当前无 LFS/子模块。

产品交付锁 /Users/mac/.codex/app-delivery-locks/com.dayu.color.lock 覆盖最终构建到清理。仓库锁按全局规范使用远程 URL 的 SHA-256。不要在已持有同一把锁时嵌套调用会自行取锁的工具。

后续验收至少覆盖:

  • 主 APP:未安装/运行中的宿主、账号所有状态、二维码到期取消、重开恢复、退出与设备解绑,以及窗口缩放与基础无障碍操作。
  • 授权:登录但未购买、会员到期、单购、离线与伪造/错产品/错设备凭证;APP 关闭后从 FCP 直接启动插件仍得到正确结果。
  • 更新:同版本不同构建、无更新、损坏或错误团队/产品包、下载中断、用户取消安装、宿主未保存、安装失败及完成后正常重开;唯一正式 APP 和模板版本一致。
  • 调色回归:既有395项原生检查按变更运行、关键旧预设与轨迹保存、FCP 实际加载和导出;复用136项印片对照结果的前提是相关数学/Metal确实未改变。
  • 交付:正式路径的已签名、公证、粘附版本;PKG 验包、Release完整下载;按本轮范围清理生成 APP,保留媒体、用户 LUT/预设和历史发行包。

原有验收证据集中在 verification:Delivery.json、InstalledSelfTest.json、HostPrintLooks1.6.0.json、HostPrimaryDefaults1.6.0.json、Package.json、Release.json、PrintLooksReleaseRecovery.json。

8. 若需修改线上接口

下一阶段若确有后端改动,先在 /Users/mac/Downloads/dayumedia 下确定本专项的最小本地工程,记录 LOCAL_PROJECT、NAS_ROOT 和文件相对路径映射;比较并保护本地未部署改动,再从生产同步目标文件、保存基线、本地修改和测试。部署前在原文件同目录创建分钟时间戳旁路备份、逐字节核对后才覆盖,最后核对生产文件及实际接口。

本轮没有创建这个后端专项工作副本,没有部署文件,也没有把 NAS 源码或密钥复制进大鱼调色仓库。不要在 SMB 上直接改源码、跑依赖或构建,不上传整份 dayumedia 目录;不要把产品 Git Release 上传误认为网站更新源已经发布。

9. 可直接用于下一段聊天的接续说明

阅读 /Volumes/备份/大鱼调色/大鱼调色/大鱼调色主APP开发交接.md 和现有 FxPlug 交接,从当前正式 1.6.0(39)接续优化现有主 APP,加入自动更新、登录验证和账号/版本界面。先核实生产通用接口与本产品的文章、产品标识、授权范围及离线策略,再实现;保留已有调色、蒙版、跟踪、叠层和低版本 MOEF。保持唯一安装位置和 Bundle ID,按本机规则完成正式交付、宿主验收、PKG Release 与远程备份。主 APP 窗口与插件授权是不同层面,不把登录成功等同于产品使用权,不在渲染回调联网。