一、 项目全局看板

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. 接入通用支付渠道 (微信/支付宝/Stripe)； 3. 每日免费次数限制逻辑； 4. 高并发队列优化 (Redis Stream)。	实现营收闭环，保证系统在高负载下的稳定性。
五期	B端赋能 (SaaS)	1. 美甲店商户入驻与专属色板上传； 2. C端用户一键导航至门店； 3. 生成“指尖流光”短视频 (SVD技术)。	拓展 B 端收入，通过视频传播实现社交裂变。

3. 当前进度

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

• 本期冲刺路线图：

  • 👉 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: 闭环验证与演示 [全流程跑通/内部验收/性能基准测试]

• 今日焦点：基础设施搭建与双核架构落地

  • 为了支撑后续高强度的开发以及未来多端适配的需求，今日重点构建了基于 Java 的业务中台基座，并确立了与 Python AI 算力服务的分离架构，确保地基稳固。

---

二、 开发日记正文

CI/CD 状态：本地环境初始化

1. 今日任务清单

核心策略：采用成熟的 Ruoyi-Vue-Pro 框架作为业务基座，通过裁剪冗余模块实现快速启动；同时确立“Java管业务，Python管算力”的异构架构，为 AI 能力接入做准备。

ID	任务项	关联需求/业务价值	状态
T-01	技术架构选型与落地 确定使用 Ruoyi-Vue-Pro (精简版)。	一期 全局 提供现成的管理员登录、RBAC 权限和文件上传能力，节省 3-5 天基础功能开发时间。	✅ 完成
T-02	后端环境搭建与裁剪 移除 BPM/ERP 模块，启动 yudao-server。	一期-非功能需求 减轻系统体积，确保开发环境启动速度 <10s，提升迭代效率。	✅ 完成
T-03	数据基座初始化 配置 MySQL 业务库、Redis 缓存库。	一期-款式管理 为后续存储美甲数据和 AI 任务队列做好数据持久化准备，配置 Redis DB 5 实现物理隔离。	✅ 完成
T-04	管理前端启动 配置 Node 环境，启动 yudao-ui-admin。	一期-管理后台 确保运营人员有可视化界面可以上传测试用的美甲图片。	✅ 完成
T-05	版本控制与规范 Git 初始化，推送 feature/day1。	CI/CD 前置 代码入库是自动化流水线的第一步，规范协作流程。	✅ 完成

2. 核心原理

今日工作重点在于确立系统的“双核架构”以及基座的选型落地。我们摒弃了纯 Python 或纯 Java 的单一技术栈，而是采用了 “Java 负责业务调度，Python 负责 AI 算力” 的异构分离模式。

(1) 框架选型深度解析：为什么选择 Ruoyi-Vue-Pro (芋道)？

• 场景描述：项目需要快速进入 AI 核心业务开发，但又必须具备商业化 SaaS 平台的基础设施（用户、支付、多租户）。

• 技术原理/选型逻辑：

  • MVP 加速器 (Time-to-Market)：一期的核心是验证 AI。芋道内置了成熟的 system 模块（RBAC权限、审计日志），让我们直接跳过基础开发，开箱即用。

  • 基础设施抽象：AI 项目重度依赖图片。芋道的 infra 模块完美封装了 OSS (对象存储)，支持通过 YAML 配置切换阿里/腾讯/MinIO，降低了文件处理复杂度。

  • SaaS 基因 (Future Proofing)：项目规划在五期做 B 端 SaaS。芋道原生支持多租户架构和支付模块，这意味着现在的架构选择，已经为未来的商业化扩展扫平了障碍，避免中期重构。

(2) 架构原理：Java 与 Python 的异构协同

• 场景描述：Java 不擅长 AI 推理，Python 不擅长复杂企业级业务逻辑与高并发调度。

• 技术原理/选型逻辑：

  • 业务调度 (Java)：作为“大脑”，负责用户鉴权、任务状态流转、并发限流。它不进行任何图片处理，只负责“发号施令”。

  • 算力节点 (Python)：作为“工人”，无状态运行。通过 FastAPI 暴露接口，专注于加载 PyTorch 模型执行推理。

  • 解耦优势：两者通过 HTTP (初期) 或 Redis 队列 (后期) 通信。当算力不足时，只需横向扩展 Python GPU 节点，无需重启 Java 服务。

• 架构图：

架构设计核心解读 (Architecture Core Insights)

1）物理隔离与异构协同 (Physical Isolation & Heterogeneous Synergy)

• 设计逻辑：系统采用了 Java (CPU密集型) 与 Python (GPU密集型) 的物理分离部署架构。

• 核心优势：

  • 成本最优：Java 业务服务可以运行在廉价的通用 CPU 服务器上；只有 Python AI 服务需要部署在昂贵的 GPU 服务器（如 RTX 4090）上。

  • 独立扩容：当用户量暴增时，只需扩展 Java 节点；当绘图排队过长时，只需扩展 Python 节点。两者互不干扰，避免了“一荣俱荣，一损俱损”的单体瓶颈。

2）全链路异步非阻塞调度 (Asynchronous Non-blocking Scheduling)

• 设计逻辑：鉴于 SDXL 生成一张高清图耗时通常在 3s~10s，前端 HTTP 请求无法长时间保持连接。

• 交互模式：

  1. 用户提交：Java 接收请求，立即生成 TaskID 并返回状态 PENDING，结束 HTTP 连接。

  2. 后台调度：Task_Scheduler 异步将任务派发给 Python。

  3. 前端轮询：小程序端通过 TaskID 每隔几秒查询一次状态，直到状态变为 SUCCESS。

• 价值：保证了高并发下 Web 服务的吞吐量，不会因为 AI 生成慢而拖垮业务网关。

3）基于 OSS 的“引用传递” (OSS Pass-by-Reference)

• 设计逻辑：Java 与 Python 之间严禁直接传输图片二进制流 (Base64/Binary)。

• 数据流向：

  • Java 上传原图到 OSS -> 仅传递 URL 给 Python。

  • Python 下载处理 -> 上传结果图到 OSS -> 仅返回 URL 给 Java。

• 价值：极大降低了内网 IO 和带宽压力，避免了大文件传输导致的超时问题。

4）领域驱动的高内聚设计 (DDD High Cohesion)

• 模块划分：

  • infra/system：作为通用底座，负责脏活累活（鉴权、日志、文件），业务开发人员无需关注。

  • yudao-module-nail：作为核心域（Core Domain），我们设计了 nail-style（静态资产）、nail-task（动态流程）和 nail-integ（防腐层）三个子模块。

  • nail-integ 的作用：专门负责与 Python 的 HTTP 通信。如果未来 Python 接口变动，或者我们要换成 Go 语言写 AI 服务，只需要修改这个模块，业务逻辑层（Task/Style）完全不需要改动。

(3) Spring Boot 多模块 Maven 聚合原理

• 场景描述：为了避免系统过于臃肿，我们在 pom.xml 中注释掉了 bpm (工作流) 和 report 模块。

• 技术原理/选型逻辑：

  • Maven 反应堆 (Reactor)：父工程通过 <modules> 标签管理子模块。移除模块后，Maven 在构建时会跳过这些模块的编译。

  • 自动装配 (AutoConfiguration)：Spring Boot 启动时扫描 ClassPath。移除 jar 包后，相关的配置类不加载，Spring IoC 容器不需要实例化原本庞大的 Bean（如 Activiti 引擎），从而将启动时间从 30s+ 压缩至 8s。

3. 今日成果

1. 管理后台就绪：
   访问 http://localhost:80，使用默认账号 admin 登录成功，RBAC 权限验证通过。
   

2. API 服务就绪：
   访问 http://localhost:48080/doc.html (Knife4j)，接口文档正常加载，Swagger 调试通畅。
   

3. 代码仓库：

   • 仓库地址：https://gitee.com/qqqq219/chroma-tip

   • 分支feature，代码已提交，标签：day1

---

三、 明日预告

关联需求：一期 - “管理员可上传美甲款式图”、“系统记录任务”。

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

技术焦点：ORM 映射与代码生成。

关键动作：

1. 业务建模：设计 nail_style (款式表) 和 nail_task (任务表) 的 ER 关系。

2. 低代码开发：利用芋道代码生成器（基于 Velocity 模板引擎）自动生成 Java 和 Vue 的 CRUD 代码。

3. 容器化：编写 Dockerfile，构建后端镜像，为接入 CI/CD 流水线做准备。