一、 项目全局看板

1. 产品愿景

针对美甲行业“试错成本高、效果不可预见”的痛点，开发一款基于生成式 AI 的虚拟试戴工具。用户通过 Web、H5 或 App 等多端前端上传手部照片和美甲款式图，系统利用 AI 技术将款式“穿”在用户手上，实现“所见即所得”，打造一款商业级的 AI 美甲虚拟试戴 SaaS 平台，连接 C 端用户“试色”需求与 B 端美甲店“引流”需求。

2. 总体需求迭代矩阵

阶段	核心目标	关键用户故事/功能清单	商业/技术价值
一期	核心能力验证 (POC)	1. 管理员后台可上传美甲款式图并打标签； 2. 系统能接收手部图片并记录任务； 3. AI 服务能生成逼真试戴图； 4. 内部后台查看结果与耗时。	验证技术可行性 (TR)，规避核心算法风险，搭建后端基座。
二期	核心能力优化	1. 优化手部Mask分割精度； 2. 调优光影融合算法，提升材质真实感； 3. 引入并发队列，提升生成速度； 4. 建立 AI 效果自动化评测指标。	重点攻坚：将“能用”提升至“商用”级别，确保生成效果逼真，消除“贴纸感”。
三期	多端前端发布 (MVP)	1. C端前端 (Web/H5) 上线； 2. 提供“拍照辅助线”引导； 3. 用户对比原图与效果图并保存； 4. 展示排队进度动画。	跑通 C 端用户体验，获取首批种子用户反馈，验证跨端架构。
四期	商业化 V1.0	1. 接入会员订阅与单次付费； 2. 接入通用支付渠道； 3. 每日免费次数限制； 4. 高并发队列优化 (Redis Stream)。	实现营收闭环，保证系统在高负载下的稳定性。
五期	B端赋能 (SaaS)	1. 美甲店商户入驻与专属色板上传； 2. C端用户一键导航至门店； 3. 生成“指尖流光”短视频 (SVD技术)。	拓展 B 端收入，通过视频传播实现社交裂变。

3. 当前进度

• 所处阶段：一期: 核心能力验证 (POC) - Day 3

• 本期冲刺路线图：

  • ✅ Day 1: 基础设施搭建与双核架构落地 [Java基座/环境初始化]

  • ✅ Day 2: 业务建模与低代码开发 [表结构设计/代码生成/Docker化]

  • 👉 Day 3: 算力服务基建 [Python FastAPI搭建/基础接口/Token鉴权]

  • ⬜ Day 4: AI 工作流攻坚 (上) [ComfyUI部署/手部Mask分割/基础生图]

  • ⬜ Day 5: AI 工作流攻坚 (下) [ControlNet手部结构控制/IP-Adapter风格迁移]

  • ⬜ Day 6: 异构系统联调 [Java异步调用Python/OSS图片流转/状态机]

  • ⬜ Day 7: 闭环验证与演示 [全流程跑通/内部验收/性能基准测试]

• 今日焦点：算力服务基建

  • 今日重点在 Python 端搭建轻量级算力网关，确立 Java 与 Python 之间的通讯契约。通过 Mock 模式先行打通业务全链路，并建立基于 Token 的安全鉴权机制。

---

二、 开发日记正文

CI/CD 状态：Python 工程本地环境配置完成 / 跨服务通讯 Mock 测试通过

1. 今日任务清单

核心策略：采用 FastAPI 异步框架构建高性能算力网关；通过定义统一的 JSON 协议实现跨语言协作；引入请求 Token 校验保证 GPU 资源安全。

ID	任务项	关联需求/业务价值	状态
T-05	Python 工程初始化 搭建基于 FastAPI 的项目结构，配置 Conda 虚拟环境及 Pydantic 模型。	一期-算力接入 建立稳定的算力服务运行环境，为后续加载大型 AI 模型做好准备。	✅ 完成
T-06	AI 生成接口定义 [Mock] 编写 POST /api/v1/generate 接口，定义原图 URL 及款式 URL 的入参规范。	一期-能力验证 实现业务逻辑预热，在 AI 算法部署前，先行让 Java 端跑通业务流。	✅ 完成
T-07	跨服务安全鉴权机制 实现基于 Header 的 API-Key 校验中间件，对 Java 端请求进行身份验证。	一期-系统安全 物理隔离 GPU 算力资源，防止 Python 接口暴露后被恶意刷量导致成本失控。	✅ 完成

2. 核心原理

今日工作确立了 Java 业务大脑与 Python 算力工人之间的“沟通标准”与“防御边界”。

(1) FastAPI 异步非阻塞架构

• 场景描述：AI 推理通常耗时数秒。如果使用传统同步框架，一旦显卡在计算，整个接口会进入阻塞状态，导致吞吐量极低。

• 技术原理/选型逻辑：

  • 协程调度：FastAPI 基于 asyncio。当请求进入等待 GPU 响应的阶段时，Python 进程可以释放控制权去处理其他心跳请求或排队逻辑。

  • Pydantic 数据验证：通过 Pydantic 定义请求体，在进入算法层前就拦截掉格式错误的 URL 或非法参数，保障算法运行的稳定性。

(2) 异构系统通讯契约 (Communication Contract)

• 场景描述：Java 工程师和 Python 工程师（或不同职责的模块）需要一套共同语言。

• 技术原理/选型逻辑：

  • RESTful 契约：使用 JSON 作为载体。Java 只传递 hand_url 和 style_url 两个字符串，Python 返回 task_id 和生成的 result_url。

  • Mock 驱动开发：在 Python 端返回预设的固定结果，让 Java 端的任务状态机（Pending -> Running -> Success）能够先行闭环调试。

(3) 算力访问控制中间件

• 场景描述：GPU 服务器租金昂贵，必须严防接口被爬虫抓取。

• 技术原理/选型逻辑：

  • Token 校验：在 FastAPI 中通过依赖注入 (Depends) 实现 Header 校验。

  • 流程：Java 请求头携带 X-API-KEY -> Python 中间件提取并比对环境变量 -> 校验通过进入业务层，否则直接返回 403。

(4) 跨服务异构通讯流程序列图

1） 异步非阻塞式交互原理 (Asynchronous & Non-blocking)

• 交互细节：当用户在前端点击“开始试戴”时，Java 后端（Ruoyi）在接收到请求后，第一动作并非调用 AI 算法，而是立即在数据库生成一条状态为 PENDING 的记录，并迅速将 TaskID 返回给前端。

• 底层逻辑：由于 AI 绘图通常需要 5~10 秒，远超 HTTP 请求的建议等待时间（通常为 3s 内）。通过这种**“先发证、再干活”**的模式，Java 服务可以保持极高的吞吐量，不会因为 GPU 推理慢而导致 Web 服务器线程池枯竭（Thread Pool Exhaustion）。

2） 基于“引用传递”的数据流转 (Data Pass-by-Reference)

• 交互细节：序列图中显示，Java 传给 Python 的并非图片文件本身，而是图片在 OSS（对象存储） 中的 URL。

• 底层逻辑：图片 Base64 或二进制流传输会极大消耗内网带宽，增加网络 IO 的延迟。我们采用 “引用传递” 的设计：Java 和 Python 共享一套 OSS 基础设施。Java 负责上传原图，Python 负责下载原图并上传结果。这种方式将跨语言通讯的负载降到了最低（仅几十个字节的字符串），确保了调用的极速响应。

3） 跨服务安全鉴权与“卫兵模式” (Security Handshake)

• 交互细节：在 Python 接收请求前，序列图展示了一个特殊的 Middleware 校验过程。Java 请求头中必须携带 X-API-KEY。

• 底层逻辑：GPU 算力是本项目最昂贵的成本。我们将 Python 算力网关设计为 “卫兵模式”：不直接暴露算法接口。所有请求必须经过 Token 校验，拦截未授权的恶意刷量。这种设计在物理层面隔离了业务压力与算力负载，保护了昂贵的计算资源。

4） 双向回调与状态同步机制 (Callback & State Sync)

• 交互细节：序列图的后半段展示了 Python 反向调用 Java 的过程。在 AI 绘图完成后，Python 会主动推送 SUCCESS 状态及结果 URL 到 Java 的指定接口。

• 底层逻辑：这是一种 “发布-订阅” 的变体。

  • Python 视角：我只管算，算完了通知业务大脑。

  • Java 视角：我平时不管进度，一旦收到通知，立即根据 TaskID 更新数据库状态机。

• 最终一致性：这种双向确认机制确保了即使网络出现瞬时抖动，任务状态也能通过补补偿逻辑（如 Day 6 规划的任务补偿）最终达成一致，为用户提供准确的生成反馈。

5） 轮询机制与用户感知 (Polling Logic)

• 交互细节：前端拿到 TaskID 后，会进入一个每 2-3 秒一次的轮询过程。

• 底层逻辑：在现阶段（第一期 POC），轮询是最简单的实现方案。它让前端能够“感知”后端状态机的跳变。当 Java 数据库状态被 Python 回调更新为 SUCCESS 时，前端的下一次轮询请求将直接带回结果图 URL，完成整个试戴闭环。

3. 今日成果

1. Python 算力网关：FastAPI 服务成功启动，本地 Swagger [docs] 页面可正常测试。

   ai_gateway/
   ├── .env                    # 环境配置
   ├── .env.example           # 环境配置模板
   ├── requirements.txt       # 依赖清单
   ├── start.bat             # 启动脚本
   ├── main.py               # 主应用入口
   ├── config/               # 配置模块
   ├── models/               # 数据模型
   ├── middleware/           # 鉴权中间件
   └── api/v1/              # API 路由

2. Mock 链路闭环：Java 后端成功通过 RestTemplate 调用 Python 接口，美甲任务状态能够正常流转。

3. 安全防护生效：尝试直接访问接口被成功拦截，API-Key 校验逻辑符合预期。
   

4. 代码仓库：

   • Git Repo: https://gitee.com/qqqq219/chroma-tip

   • Branch: feature/day3 已提交。

---

三、 明日预告

关联需求：一期 - “AI 服务能生成逼真的试戴效果图”。

技术焦点：ComfyUI 工作流部署。

关联任务：

• T-04: AI 工作流攻坚 [上] (对应冲刺路线图 Day 4)。

关键动作：

1. ComfyUI 环境部署：在 GPU 节点安装后端引擎及必要插件。

2. 手部分割节点测试：调试 MediaPipe/SAM 节点以精准定位指甲区域。

3. 工作流 API 导出：将图形化工作流导出为 JSON，对接 Python FastAPI。