Jarvis

LYNCA AI 图像处理模型 - Engineer Build Spec

归档于 2026-09-30；原路径：02_ACTIVE_SYSTEMS/WEBTOOL/LYNCA_AI_IMAGE_TOOL_BUILD_FLOW.md。早期本地原型的复刻交接，保留原有 API、env、数据字段、UI 和安全约束；不是当前 Production 合同或部署指令。

本文件是 LYNCA AI 图像处理模型 的工程复刻与云部署交接文档。

目标不是重新设计一个类似工具，而是让 engineer 能尽量 1:1 复刻当前本地 prototype 的主视觉、页面结构、交互、文案、按钮、文本框、状态逻辑，并部署到 LYNCA 现有域名下，对接真实 auth、storage、database 和 OpenAI API。

0. 交付目标

工程交付结果：

在 LYNCA 现有域名下上线一个 invite-only AI image processing tool。

建议线上路径：

https://<LYNCA_EXISTING_DOMAIN>/ai-image
https://<LYNCA_EXISTING_DOMAIN>/ai-image/login

如果现有官网已有 route convention，可以调整路径，但必须保留：

一个明确的官网入口按钮
一个 invite-only login page
一个 upload / process / review / download 主页面
server-side OpenAI image processing API

工具名称必须保持：

LYNCA AI 图像处理模型

1. 当前本地 prototype 来源

本地项目：

/Users/ommi/lynca-image-pipeline

当前本地启动：

python web_app.py

本地 URL：

http://127.0.0.1:8787

本地 mock login：

User: Fei
Password: 123456

生产环境不能使用 mock login。生产必须接入 LYNCA official auth 或手动发放 invite-only account。

核心参考文件：

web_app.py：当前 UI、route、mock auth、upload、process、rerun、download 的完整 prototype。
run.py：Image Pipeline 调用、prompt loading、batch processing、logging。
lynca/prompts/run.txt：active prompt single source of truth。
lynca/standards/image2_v1.5.md：Image2 Preview Standard。
docs/ENGINEERING_HANDOFF.md：原本地工程交接说明。

2. UI 预览图

工程实现必须以以下截图为视觉基准。

2.1 登录页

!LYNCA AI 图像处理工具登录页

2.2 上传 / 处理主页面

!LYNCA AI 图像处理工具主页面

3. 产品边界

这个工具只做一件事：

用户登录
-> 上传卡片 / slab / holder 原图
-> 点击开始处理
-> 后端调用 Image Pipeline
-> 页面展示原图与处理后图片
-> 用户下载结果或单张重新处理

第一版不做：

public signup
self-serve registration
payment
marketplace
social feed
full admin console
多 AI workflow 平台
直接浏览器调用 OpenAI
自动替代人工 authenticity review

4. 线上部署形态

5. Route / API 设计

生产 route 可以按现有工程规范命名，但必须覆盖以下能力。

5.1 Page routes

GET /ai-image/login
GET /ai-image

行为：

未登录访问 /ai-image，redirect 到 /ai-image/login。
登录成功后进入 /ai-image。
不提供公开注册入口。

5.2 API routes

建议：

POST /api/ai-image/login
POST /api/ai-image/upload
POST /api/ai-image/process
POST /api/ai-image/rerun
GET  /api/ai-image/files?batch_id=:batch_id
GET  /api/ai-image/runs/:run_id
GET  /api/ai-image/media/:image_id/original
GET  /api/ai-image/media/:image_id/processed
GET  /api/ai-image/download/:image_id

如果使用现有 auth system，POST /api/ai-image/login 可由现有 login/session route 替代。

5.3 Upload API

Input:

multipart/form-data
files[]

Rules:

支持 .jpg、.jpeg、.png、.webp。
同时检查 extension 和 MIME type。
限制单张文件大小。
限制单批文件数量。
上传成功后创建 batch_id。
每个文件创建 image record。

Response:

{
  "batch_id": "20260507TxxxxxxZ-xxxxxxxx",
  "uploaded": ["file-a.jpg"],
  "files": [
    {
      "id": "img_xxx",
      "filename": "file-a.jpg",
      "input_url": "/api/ai-image/media/img_xxx/original",
      "output_url": "",
      "output_exists": false,
      "status": "uploaded"
    }
  ]
}

5.4 Process API

Input:

{
  "batch_id": "..."
}

Behavior:

创建 run record。
将 batch 中的 images 推入 worker / queue。
返回 run_id。
前端开始 polling。

Response:

{
  "run_id": "run_xxx"
}

5.5 Run status API

Response shape:

{
  "run_id": "run_xxx",
  "batch_id": "batch_xxx",
  "status": "running",
  "total": 3,
  "in_process": 1,
  "results": {
    "success": 2,
    "skipped": 0,
    "moderation_blocked": 0,
    "invalid_image_file": 0,
    "api_error": 0,
    "unknown_error": 0
  },
  "records": [],
  "average_latency": 1.234,
  "billable_images": 2,
  "estimated_usd": 0.0,
  "estimate_configured": false
}

5.6 Rerun API

Input:

{
  "batch_id": "...",
  "image_id": "img_xxx"
}

Behavior:

只重新处理单张图片。
创建新的 run record 或 rerun record。
不覆盖历史 status。
受 usage limit 限制。

6. Database model

6.1 `ai_image_batches`

id
user_id
status
created_at
updated_at

6.2 `ai_image_runs`

id
batch_id
user_id
status
total
in_process
prompt_file
prompt_version
standard_version
workflow_version
model
quality
size
output_format
average_latency_seconds
billable_images
estimated_api_spend
created_at
completed_at
error_message

6.3 `ai_image_records`

id
batch_id
run_id
user_id
filename
original_storage_url
processed_storage_url
status
error_message
latency_seconds
created_at
updated_at

Status values must include:

uploaded
processing
success
skipped
moderation_blocked
invalid_image_file
api_error
unknown_error

7. Image Pipeline integration

使用当前 pipeline 的思想，不要让 engineer 自己重新发明 prompt。

必须接入：

lynca/prompts/run.txt
lynca/standards/image2_v1.5.md

当前 model：

gpt-image-2

调用方式：

后端读取 active prompt。
将 standard 文本填入 {STANDARD}。
使用 OpenAI Images API server-side processing。
保存 original image。
保存 processed image。
记录 prompt version / standard version / workflow version。

核心 guardrails：

这是 cleanup，不是 generation。
Do NOT recreate, redesign, or reinterpret the card。
Preserve grading label、barcode、QR code、certification number、grade、serial number、face、autograph、patch、logo、printed text。
Geometry Lock 优先。
如果 cleanup 需要 invent / repair / complete 内容，则不要做。

8. UI 复刻标准

这一节是重点。工程师应尽量复刻当前 prototype，而不是重新设计。

8.1 全局视觉

整体风格：

dark mode
black / near-black background
blue-purple lighting
subtle cyan accent
grid texture
glass panel
8px radius for controls
small, restrained, premium tool feel

核心 color tokens：

--ink: #f7f8fb;
--muted: #8f96a8;
--line: rgba(255,255,255,.12);
--paper: #10111a;
--panel: rgba(17,18,27,.82);
--surface: #05060b;
--surface-2: #0b0c15;
--accent: #7a4dff;
--accent-2: #27d9ff;
--gold: #d9b36a;
--good: #62e5a8;
--warn: #f0b862;
--bad: #ff7169;

背景参考：

background:
  linear-gradient(128deg, rgba(122,77,255,.25) 0 13%, transparent 34%),
  linear-gradient(218deg, rgba(39,217,255,.22) 0 11%, transparent 32%),
  linear-gradient(180deg, #05060b 0, #090a12 320px, #06070c 100%);

网格 overlay：

background-size: 72px 72px;

字体：

font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
letter-spacing: 0;

8.2 登录页 UI spec

Page title:

LYNCA 私享通道

Card container:

width: min(440px, 100%)
border radius: 12px
border: 1px solid rgba(255,255,255,.13)
backdrop blur: 22px
padding desktop: 30px
mobile padding: 24px 18px

Brand block:

LYN
LYNCA AI 图像处理模型
Private Preview Access

Hero title:

私享处理通道

Intro copy:

仅限受邀用户访问。请输入专属身份凭证与私密访问秘钥，进入 LYNCA 内测图像处理空间。

Field labels and placeholders:

专属身份凭证
placeholder: 请输入受邀账号

私密访问秘钥
placeholder: 请输入访问秘钥

Button:

进入私享空间

Seal:

Invite-only · VIP · Confidential

身份凭证或访问秘钥不匹配，请确认后重试。

Input style:

height: 48px
border radius: 8px
background: rgba(255,255,255,.055)
focus border: rgba(39,217,255,.56)
focus shadow: 0 0 0 3px rgba(39,217,255,.12)

Primary button style:

background: linear-gradient(135deg, rgba(122,77,255,.96), rgba(39,217,255,.88));
height: 48px;
border-radius: 8px;
font-weight: 720;

8.3 主页面 UI spec

Page title:

LYNCA AI 图像处理模型

Header note:

本地内部工作流。API 凭证仅保存在服务器端。

生产环境可以改为：

私享内测工具。图像处理由 LYNCA 安全服务完成。

Header logo:

text mark: LYN
size: 42px x 36px
radius: 10px
gradient: dark base → purple → cyan

Toolbar layout desktop:

[file label full width] [上传图片] [开始处理]

Toolbar layout mobile:

[file label]
[上传图片]
[开始处理]

File input:

hidden native input
visible label acts as upload selector

Default file label:

选择卡片照片，支持 JPG / PNG / WEBP

After selection:

已选择 X 张图片

Buttons:

上传图片
开始处理

开始处理 button must use purple-cyan gradient and stronger visual emphasis.

8.4 Metrics

主页面必须展示 6 个 metric cards，顺序不可随意调整：

图像队列
处理中
处理成功
需排查
平均耗时
预估 API 成本

Metric details:

图像队列: 已成功上传
需排查: 合规边界复核
平均耗时: 仅统计已处理图片
预估 API 成本: 可配置粗略成本估算

Desktop:

6 columns
each metric min-height 82px

Mobile:

horizontal scroll strip
each metric width about 142px
hide scrollbar

8.5 Empty state

无上传文件时，gallery 显示：

上传卡片照片，开始一次新的干净流程。

8.6 Image card

每张图片一个 card。

Card structure:

filename + status pill
原图 | 处理后
下载 / 重新处理
explanation note

Desktop image pair:

two columns
image height: 300px
object-fit: contain

Mobile image pair:

single column
image height: clamp(260px, 82vw, 430px)

Captions:

原图
处理后

Action buttons:

下载
重新处理

When download starts:

下载已开始

If no processed image:

处理完成后，预览图会显示在这里。

9. Frontend interaction logic

9.1 State variables

Frontend should maintain:

batchId
activeRunId
pollTimer
files[]

9.2 Upload flow

User selects files
-> file label changes to 已选择 X 张图片
-> user clicks 上传图片
-> POST upload API
-> receive batch_id and files[]
-> reset activeRunId
-> refresh UI

9.3 Process flow

User clicks 开始处理
-> disable process button
-> POST process API with batch_id
-> receive run_id
-> refresh immediately
-> start polling every 2500ms

Polling interval:

2500ms

When run status is completed or failed:

enable process button
stop polling

9.4 Rerun flow

User clicks 重新处理
-> disable clicked button
-> POST rerun API with batch_id and image id / filename
-> receive new run_id
-> refresh immediately
-> start polling

Rerun must be usage-limited in production.

10. Status copy

Backend statuses can remain English, but frontend copy must stay Chinese and user-facing.

No record, no active run:

请上传图片并开始处理。

No record, active run running:

已收到请求，图片正在处理中。

success or skipped:

图片处理成功

Failure / blocked:

图片暂时无法处理，请查看说明。

11. Explanation copy

No record:

图片已成功上传。原图已准备就绪，点击开始处理后会生成预览图。

Success:

处理已完成。建议在交付客户或上传数据库前，复核卡片、评级标签和签名等真实性细节。若浏览器没有下载提示，可在本地 output 文件夹中查看结果。

Production can remove “本地 output 文件夹” and replace with:

处理已完成。建议在交付客户或上传数据库前，复核卡片、评级标签和签名等真实性细节。

Skipped:

系统检测到已有处理结果，因此复用了现有预览图，未额外消耗一次图像请求。

Moderation blocked:

该图片未被处理，因为安全系统将请求标记为需要合规复核。常见原因包括受保护 IP、品牌内容，或运动员/人物肖像识别相关限制。原始文件已保留。

Invalid image:

该文件无法处理，因为图片格式或文件模式被拒绝。通常重新导出为标准 JPG 或 PNG 后即可解决。

API error:

图像请求已到达处理服务，但未成功完成。这通常是临时问题；确认原图无误后可点击重新处理。

Unknown error:

该图片因未分类原因未能完成处理。请保留原图，可重新处理，或结合运行日志交由技术团队排查。

12. Production implementation requirements

12.1 Auth

Must have:

invite-only accounts
no public signup
session / cookie auth
all API routes protected
manual account disable ability

12.2 Storage

Must store:

original image
processed image
filename
storage URL
owner user id
retention metadata

Storage should be private by default.

12.3 Worker

Do not process images inside the frontend request lifecycle.

Use:

queue
worker
retry policy
per-image timeout
per-run status aggregation

12.4 Usage limit

Minimum controls:

max images per batch
max file size
daily image request limit per account
rerun limit
admin usage visibility

12.5 Observability

Log:

run id
image id
user id
model
prompt version
standard version
latency
status
error category

Do not log:

API key
raw private filenames in public logs
private image URLs in client-visible error messages

13. Acceptance criteria

Engineer delivery is not accepted unless all items pass:

Existing LYNCA domain has working /ai-image entry.
Unauthenticated user is redirected to login.
Login page visually matches screenshot direction.
Login page uses exact title, labels, placeholders, button text and seal copy.
Main page visually matches screenshot direction.
Upload button and file label behavior match prototype.
Metrics appear in same order and with same labels.
Image cards show original / processed comparison.
Status copy matches this document.
Explanation copy matches this document.
Process button triggers server-side Image Pipeline.
Browser never receives OpenAI API key.
Download works only for authenticated owner.
Rerun works per image and creates new status.
Run polling stops on completed / failed.
Original and processed files are stored privately.
DB records include prompt version and standard version.
Production does not use mock Fei / 123456 login.

14. Non-negotiables

Do not redesign the UI from scratch.
Do not turn this into a generic SaaS dashboard.
Do not expose OpenAI API key to browser.
Do not skip invite-only access.
Do not remove Geometry Lock.
Do not let AI alter card identity, grading label, text, serial number, face, autograph, patch, logo, or holder.
Do not ship without private storage and access control.

15. Founder intent

这个工具的价值不是“上传图片然后 AI 处理”。

它是 LYNCA 的第一个可用 AI workflow 样板，应该体现：

私享入口
收藏级信任感
对真实资产身份的保护
可追踪 prompt / standard / run record
原图与处理图的人工 review
未来接入 LYNCA Archive / Collector Profile 的可能性

Engineer 应优先复刻这个体验和 workflow，再考虑平台化扩展。

LYNCA_AI_IMAGE_TOOL_BUILD_FLOW.md

LYNCA AI 图像处理模型 - Engineer Build Spec

0. 交付目标

1. 当前本地 prototype 来源

2. UI 预览图

2.1 登录页

2.2 上传 / 处理主页面

3. 产品边界

4. 线上部署形态

5. Route / API 设计

5.1 Page routes

5.2 API routes

5.3 Upload API

5.4 Process API

5.5 Run status API

5.6 Rerun API

6. Database model

6.1 ai_image_batches

6.2 ai_image_runs

6.3 ai_image_records

7. Image Pipeline integration

8. UI 复刻标准

8.1 全局视觉

8.2 登录页 UI spec

8.3 主页面 UI spec

8.4 Metrics

8.5 Empty state

8.6 Image card

9. Frontend interaction logic

9.1 State variables

9.2 Upload flow

9.3 Process flow

9.4 Rerun flow

10. Status copy

11. Explanation copy

12. Production implementation requirements

12.1 Auth

12.2 Storage

12.3 Worker

12.4 Usage limit

12.5 Observability

13. Acceptance criteria

14. Non-negotiables

15. Founder intent

6.1 `ai_image_batches`

6.2 `ai_image_runs`

6.3 `ai_image_records`