ai-sdd 是一个面向 AI 产品经理 / 独立开发者的 SDD（Spec-Driven Development，规范驱动开发）样例仓库。它不是只展示一个小工具，而是展示如何把一个模糊业务需求，拆成 PRD、规格文档、接口契约、实现代码和测试验收等可追踪产物。
当前样例项目是 AI 智能工牌生成系统：员工上传生活照，系统自动生成统一风格证件照，并合成企业工牌 PNG。
核心流程不是简单生成一张图片，而是把证件照处理、工牌模板合成、字段校验和 PNG 导出串成一个可控工作流：
员工照片上传
→ AI 证件照标准化
→ 工牌模板合成
→ 信息确认 / 质量检查
→ PNG 导出
01 需求澄清
→ 02 PRD 定义
→ 03 规格沉淀
→ 04 原型定稿
→ 05 接口契约
→ 06 前后端实现
→ 07 联调验收
文档地图：
| 阶段 | 文档 |
|---|---|
| 产品定义 | 流程总览 · 需求澄清 · PRD |
| 方案定稿 | 原型定稿 · 接口契约 |
| 开发交付 | 后端逻辑 · 前后端联调 · 交付验收 |
本仓库用 specs/ + changes/ 的方式组织产物，让需求不是停留在聊天记录或单份 PRD 里，而是沉淀成可验证、可迭代、可追踪的规格：
openspec/
├── specs/ # 当前系统能力，作为 source of truth
└── changes/ # 本次 AI 工牌 Demo 的变更包和交付记录
specs/ 记录系统当前应该具备的能力，changes/ai-badge-demo/ 记录从需求到实现的完整交付过程。后续新增“多模板切换”“批量生成”等功能时，也先进入 changes/，再同步到主规格。
| Change | 状态 | 说明 |
|---|---|---|
ai-badge-demo |
已完成 | 跑通上传照片、证件照标准化、工牌合成和 PNG 导出基础闭环 |
support-multiple-templates |
规划中 | 下一步支持企业选择不同工牌模板，降低定制成本 |
add-batch-generation |
规划中 | 后续支持批量导入员工信息和照片，提高 HR 入职场景效率 |
- 照片上传：支持上传员工生活照或头像照片。
- 证件照标准化：对接 HivisionIDPhotos，完成头像检测、裁剪、背景替换和证件照规格化。
- 工牌模板合成：使用 HTML/CSS 工牌模板，将头像、姓名、部门、岗位、工号等信息动态写入。
- PNG 导出：后端通过浏览器渲染模板并输出最终工牌图片。
- 管理端预览：提供 HR 风格的任务查看页面，用于展示生成记录和处理状态。
这个项目重点展示三个产品判断：
- 可控性：AI 负责重复性的图像标准化，人事字段仍然保留人工确认和修改空间。
- 一致性：所有工牌输出遵循统一模板，避免不同员工照片风格差异过大。
- 流程适配：产品定位是企业内部 HR / 行政提效工具，不是泛用图片生成玩具。
- 前端：React + Vite
- 后端：Python HTTP service
- 图像处理：HivisionIDPhotos API / Docker service
- 模板渲染：HTML/CSS badge template + headless browser screenshot export
先在本地运行 HivisionIDPhotos，并确认 API 可访问：
curl http://localhost:8080/docscd xianma-badge
python3 server.py默认后端地址：
http://localhost:8888
cd xianma-badge/figma-make-export
npm install
npm run dev然后打开终端里显示的 Vite 本地地址。
curl -X POST http://localhost:8888/api/generate \
-F 'name=Demo User' \
-F 'department=Product' \
-F 'position=AI Product Manager' \
-F 'employeeId=XM-2026-001' \
-F 'photo=@/path/to/demo-photo.png'返回字段：
id_photo 标准化证件照 base64
badge_png 最终工牌 PNG base64
task_id 生成任务 ID
xianma-badge/
├── docs/ # 标准产研流程文档
├── openspec/ # 规格与变更包
├── figma-make-export/ # React 前端原型
├── server.py # 本地 API 服务
├── templates/ # 工牌 HTML/CSS 模板
├── assets/ # 公开安全的视觉资源
└── README.md
仓库只保留 Demo 图片和匿名样例数据，不提交真实员工照片、真实工牌、日志、上传文件或本地生成结果。