# NEON ATELIER 本地联调参考实现

版本：0.1.0｜日期：2026-11-20｜状态：**本地联调已验证，正式若依接入待实施**

本文说明当前仓库新增的可运行实现：后台接口、五个独立 Web 应用、统一管理后台、持久化数据与验证边界。产品规则以[主 PRD](PRD.md)为准；本文只记录实现事实，不新增产品承诺。

## 1. 定位与硬边界

- **正式业务后端仍是既有若依 Server**：本地服务按若依的 `code/msg/data`、分页、`Authorization` 令牌和权限标识习惯实现，用于联调与契约验证；它不是第二套对外生产业务后端。
- **本地账号仅用于演示**：本地开发默认种子账号见根目录 `README.md`；测试服务器部署时由脚本生成强随机密码，保存在服务器 root-only 文件，不在公开页面或文档展示。正式环境必须替换为若依 `sys_user` 与真实登录。
- **AI/3D/CAD 为演示适配器**：设计候选复用预置纯服装素材；三维为程序化轮廓网格；复核问题为固定教学样例；放码为确定性参数示意。未接入真实 Provider，也不把演示结果标为真实重建或生产 CAD。
- **管理后台为 RuoYi 风格本地控制台**：正式环境应挂载到既有若依管理端；当前页面不是若依 Vue 工程的一部分。

## 2. 运行

要求 Node.js ≥ 22.5。零第三方依赖，数据库使用内置 `node:sqlite`。

```bash
npm start                 # http://127.0.0.1:8787/
npm test                  # 需另开终端并已启动服务
npm run reset:demo        # 停止服务后执行；旧 data/storage 改名为时间戳备份
```

可选环境变量：`PORT`、`HOST`、`NEON_DATA_DIR`、`NEON_STORAGE_DIR`、`NEON_DB_FILE`、`NEON_DAILY_TASK_LIMIT`。陌生目录启动时会自动建库、建表、初始化种子并复制演示素材。

## 3. 目录

```text
server/
  src/index.js            HTTP 服务、静态资源、鉴权与路由分发
  src/auth.js             登录令牌、角色/应用/课程权限
  src/db.js               SQLite 建表、查询封装、审计
  src/seed.js             演示账号、课程、54 项面料、48 色、模板、Provider、示例作品
  src/repair.js           旧演示素材的一次性修复（纯服装化，未删除数据）
  src/files.js            上传意图、类型嗅探、签名下载、文件归属
  src/tasks.js            持久化任务状态机、阶段、重试、重启恢复
  src/routes/*.js         auth/common/projects/assets/tasks/garment/review/grading/gallery/admin
  test/smoke.js           27 项 API 端到端检查
  scripts/reset-demo.js   非破坏性重置（重命名备份）
  data/ storage/          运行时数据（gitignore）
web/
  shared/api.js           会话、请求、上传、下载、轮询、弹层与提示
  shared/ui.css           视觉系统与响应式布局
  shared/recolor.js       纯服装区域实时换色（客户端 Canvas）
  shared/viewer.js        程序化三维查看器（双轴旋转/平移/缩放/网格/环绕）
  portal/ login/ design/ garment/ review/ grading/ gallery/ admin/
prototype/                既有交互原型（保留，不替代独立验收）
```

## 4. 身份、角色与权限

| 维度 | 实现 |
|---|---|
| 登录 | `POST /login`：账号、密码、`appCode`、期望角色；返回 `token`、`user`、角色、权限、应用与课程 |
| 令牌 | HMAC 签名，默认 12 小时；每次请求重新读取用户状态，禁用立即失效 |
| 角色 | `student` / `teacher` / `admin`（平台管理员） |
| 应用范围 | `appCode` + `apps.enabled` + 应用许可角色 + 课程 `course_apps.enabled` |
| 资源归属 | 作品、资产、图片组、提交、放码任务按所有者；教师按授课课程；管理员按平台授权 |
| 前端 | 只做入口与体验控制；所有动作在 Server 再次校验，不接受 URL 参数赋权 |
| 访客 | 只能读取 `GET /fashion/public/exhibits*`；不能生成、不能访问下载接口 |

关键规则：
- 作品草稿默认私人；教师不能读取学生私人草稿，只读取已提交快照。
- 公开下载必须登录并校验对象/课程/文件状态；公开展厅只提供预览签名地址。
- 应用停用后阻止新任务与新请求；既有结果保留。

## 5. 接口清单

统一前缀 `/fashion`；普通响应 `{code,msg,data}`，列表 `{code,msg,rows,total}`。除标注“公开”外均需 `Authorization: Bearer <token>`。

### 5.1 身份与公共配置

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/login` | 公开；应用/角色登录 |
| GET | `/captchaImage` | 公开；本地关闭验证码，返回 `captchaEnabled:false` |
| POST | `/logout` | 退出并记录审计 |
| GET | `/getInfo` | 当前用户、角色、权限、许可应用、课程 |
| GET | `/getRouters` | RuoYi 风格菜单树（本地前端不依赖） |
| GET | `/fashion/me` | 当前身份 |
| GET | `/fashion/apps` | 当前账号可用应用 |
| GET | `/fashion/courses` | 当前账号课程与课程角色 |
| GET | `/fashion/config` | 三种风格、品类、面料分类/纹理枚举 |
| GET | `/fashion/palettes` | 48 预设色 + 6 组合方案 |

### 5.2 课程与面料

| 方法 | 路径 | 权限要点 |
|---|---|---|
| GET | `/fashion/materials?courseId=` | 登录；公共面料 + 本人课程 |
| POST | `/fashion/materials` | 授课教师/管理员；名称、分类、成分、说明、纹理、克重校验；同名 409 |
| PUT | `/fashion/materials/:id` | 授课教师/管理员；更新前写 `material_history` 并递增版本 |
| POST | `/fashion/materials/:id/disable` | 同上；保留历史快照 |
| POST | `/fashion/courses` | 管理员；创建课程并自动加入授课教师 |
| GET | `/fashion/courses/:id/members` | 授课教师/管理员 |
| POST | `/fashion/courses/:id/members` | 授课教师/管理员；按账号加入 |
| DELETE | `/fashion/courses/:id/members/:userId` | 授课教师/管理员；移出不迁移历史 |

### 5.3 资产与文件

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/fashion/assets/upload-intents` | 校验应用/课程权限、类型与大小，返回一次性上传令牌 |
| PUT | `/fashion/assets/upload/:token` | 公开能力令牌；原始二进制上传，服务端嗅探 PNG/JPEG/WebP/SVG/GLB/ZIP/OBJ/MTL |
| GET | `/fashion/assets/:id` | 资产元数据与归属 |
| GET | `/fashion/assets/:id/url` | 签发 10 分钟文件地址 |
| GET | `/fashion/assets/:id/download` | 登录 + 归属校验；返回附件并记录导出 |
| GET | `/fashion/assets/:id/file?token=` | 公开签名能力地址；只校验签名，不再要求会话 |

大小上限：图片 20MB，模型/包 200MB。上传不会写入 `storage/` 之外的路径；文件名清理，内容与声明的 MIME 不符时拒绝。

### 5.4 作品、草稿与版本

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/fashion/projects` | 学生/教师仅本人；管理员可查全部 |
| POST | `/fashion/projects` | 课程成员；标题 1–40 字 |
| GET | `/fashion/projects/:id` | 所有者/管理员；含草稿与全部版本 |
| PUT | `/fashion/projects/:id/draft` | 所有者；风格仅三类、品类枚举、三色 HEX、面料可见性 |
| POST | `/fashion/projects/:id/versions` | 所有者；从任务成功结果或已上传图片保存不可变 Vn，快照面料/配色/模板/模型 |

### 5.5 生成任务

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/fashion/tasks` | `design_generate` / `image_to_3d` / `review_analyze`；幂等键、配额、输入归属 |
| GET | `/fashion/tasks` | 本人任务；管理员全部 |
| GET | `/fashion/tasks/:id` | 状态、阶段、进度、输入快照、结果、事件 |
| POST | `/fashion/tasks/:id/cancel` | 排队/执行中可取消（提示可能已产生供应商成本） |
| POST | `/fashion/tasks/:id/retry` | 失败/取消后新建任务并记录 `retryOf` |

公共状态：`queued → processing → succeeded / failed / cancelled`。执行器以持久化记录、领取租约和事件表工作；服务重启时把 `processing` 重新排队。重试创建新任务，历史不覆盖。默认每用户每日 20 次（演示配置）。

### 5.6 三维成衣

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/fashion/garment/views` | 视角、显示名与用途角色 |
| POST | `/fashion/garment/sets` | 2–7 张、视角唯一、正背校验所需资产归属 |
| PUT | `/fashion/garment/sets/:id` | 所有者；替换图片后旧模型视为过期 |
| GET | `/fashion/garment/sets` `/sets/:id` | 图片组与签名预览 |
| GET | `/fashion/garment/sets/:id/export?format=obj` | 需已有成功的三维任务；ZIP 含 OBJ/MTL/正背纹理/README，明确尺度未标定 |

### 5.7 教学复核

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/fashion/assignments` | 教师本人课程；学生已发布作业 |
| POST | `/fashion/assignments` | 授课教师/管理员；草稿 |
| PUT | `/fashion/assignments/:id` | 未发布草稿；发布后禁止原地改标准 |
| POST | `/fashion/assignments/:id/publish` | 需标准图；封存标准版本 |
| GET | `/fashion/assignments/:id` | 学生仅本人提交；教师含提交队列 |
| POST | `/fashion/assignments/:id/submissions` | 本课程学生；截止后默认拒绝；生成提交版本 |
| GET | `/fashion/submissions/:id` | 本人/授课教师/管理员 |
| GET | `/fashion/reviews?submissionId=` | 教师看草稿；学生未发布时问题被遮蔽 |
| GET | `/fashion/reviews/:id` | 学生未发布时返回锁定摘要 |
| POST | `/fashion/reviews/:id/decisions` | 授课教师；逐项 keep/dismiss/pending |
| POST | `/fashion/reviews/:id/publish` | 全部问题已裁定后才可发布 |
| GET | `/fashion/reviews/:id/report` | ZIP（HTML+JSON）；学生仅已发布；教师草稿标记 |

### 5.8 智能放码

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/fashion/grading/standards?garmentType=` | 课程可用的课程标准 |
| POST | `/fashion/grading/standards` | 授课教师/管理员；创建标准 |
| PUT | `/fashion/grading/standards/:id` | 授课教师/管理员；历史任务保留原快照 |
| POST | `/fashion/grading/jobs` | 只接受勾选改动项；未勾选项继承；裤装长度关系校验 |
| GET | `/fashion/grading/jobs` `/jobs/:id` | 本人结果；管理员全部 |
| GET | `/fashion/grading/jobs/:id/export?format=csv|json` | 参数对照导出；图形 SVG 由前端从同一快照生成 |

### 5.9 作品展厅

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/fashion/public/exhibits` | 公开；已发布快照、风格筛选、搜索、分页 |
| GET | `/fashion/public/exhibits/:id` | 公开；未公开 404 |
| GET | `/fashion/exhibits` | 学生本人；教师课程范围；管理员全部 |
| POST | `/fashion/exhibits` | 学生；标题/展示名/说明/授权校验；同一版本待审或已发布时拒绝 |
| POST | `/fashion/exhibits/:id/submit` | 作者重新提交 |
| POST | `/fashion/exhibits/:id/review` | 授课教师/管理员；通过/退回（理由 5–200 字） |
| POST | `/fashion/exhibits/:id/withdraw` | 作者、授课教师或管理员；立即从公开查询消失 |

### 5.10 管理后台

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/fashion/admin/overview` | 用户/课程/作品/任务/审核/存储/最近审计 |
| GET/PUT | `/fashion/admin/apps` `/apps/:code` | 启停与许可角色 |
| GET | `/fashion/admin/users` | 账号列表 |
| PUT | `/fashion/admin/users/:id/status` | 启用/禁用；禁用立即阻断后续请求 |
| GET/POST | `/fashion/admin/courses` `/fashion/courses` | 课程概览/创建 |
| GET | `/fashion/admin/courses/:id` | 成员、课程应用授权 |
| PUT | `/fashion/admin/courses/:id/apps/:code` | 课程级应用启停 |
| GET | `/fashion/admin/tasks` | 全部任务；支持状态/应用过滤 |
| POST | `/fashion/admin/tasks/:id/retry` `/cancel` | 按原归属创建重试/取消 |
| GET/POST/PUT | `/fashion/admin/prompt-templates` | 模板版本；草稿可编辑 |
| POST | `/fashion/admin/prompt-templates/:id/activate` `/disable` | 启用同用途新版本并停用旧版本 |
| GET/PUT | `/fashion/admin/providers` `/providers/:id` | 能力、别名、超时、额度；密钥只保存引用 |
| GET | `/fashion/admin/reviews` `/exhibits` `/exports` `/audits` | 审查与追溯 |

## 6. 数据模型

SQLite 表：`users`、`courses`、`enrollments`、`apps`、`course_apps`、`materials`、`material_history`、`palette_colors`、`palette_schemes`、`projects`、`project_versions`、`assets`、`upload_intents`、`image_sets`、`image_set_items`、`tasks`、`task_events`、`assignments`、`submissions`、`reviews`、`review_issues`、`grading_standards`、`grading_jobs`、`exhibits`、`prompt_templates`、`providers`、`audits`、`exports`。

核心不变量：
- 版本不可变；作品/导出/提交/展品引用具体版本，不引用“最新版”。
- 生成候选先于版本；保存时服务端校验任务归属、成功状态、图片就绪与所有者。
- 展品发布生成快照；撤回后公开查询立即排除。
- 面料被编辑/停用时保留历史 `material_history`，版本快照不回写。
- 审计记录动作、应用、对象与操作者；不记录密码、令牌或完整私人图片。

## 7. 演示生成逻辑

| 任务 | 行为 | 明确标记 |
|---|---|---|
| `design_generate` | 按风格选择预置纯服装素材（`pureGarment:true`），记录模板 `P02@1` 与演示模型；不包含人物、衣架或道具 | 候选面板与接口结果 `demo:true` |
| `image_to_3d` | 校验 2–7 张、正面/背面各一张；返回轮廓演示模型；OBJ 包由参数化网格生成 | 查看器与导出 README 标注“尺度未标定、非生产” |
| `review_analyze` | 生成固定 3 条教学问题（袖窿/肩线/腰省），含归一化区域、依据、建议 | 报告标注“预置样例，不是真实测量” |
| 放码 | 确定性合并目标参数、锁定其余项、校验裤装长度关系；输出差值表 | `mode: illustration`，页面标注非 CAD |

## 8. Web 应用实现

| 应用 | 已实现 | 未实现 |
|---|---|---|
| D01 设计 | 作品/草稿、三风格、品类、48 色/6 方案/自定义 HEX、课程面料（教师可新增）、纯服装实时换色、参考图上传、生成候选、不可变版本、PNG 下载 | 同款正背套图编排、多视图 ZIP、AI 图像编辑 |
| D02 三维 | 独立 2–7 图上传、视角/用途、正背校验、任务进度、双轴旋转/平移/缩放/视角/网格/环绕、OBJ 材质包 | 真实图生 3D、GLB、真实几何质量 |
| D03 复核 | 作业创建/发布、标准图、学生提交、分析任务、区域标注、逐项裁定、发布、HTML+JSON 报告 | 真实测量、CAD 版片、通知 |
| D04 放码 | 标准选择、勾选改动项、锁定继承、约束校验、新图与差值、CSV/SVG | 真实 CAD、档差/缝份规则引擎 |
| D05 展厅 | 公开列表/搜索/筛选、详情三维示意、学生提交/撤回/重交、教师通过/退回/应急撤回 | 独立模型上传与 GLB/OBJ 在线预览、真实发布缓存失效 |
| 后台 | 概览、应用、课程成员、面料、色板、模板、Provider、任务、复核、展厅、导出、审计 | 若依菜单/按钮权限集成、生产监控告警 |
| 门户/登录 | 五个独立入口、教师/学生/管理员登录、访客展厅、权限拒绝页 | 若依 SSO、找回密码、真实验证码 |

## 9. 与若依正式接入的映射

正式实施时保留当前 Web 契约，替换服务端：
1. 在既有若依工程新增 `ruoyi-fashion` 模块，Controller 挂入现有启动应用；登录、令牌、用户、角色、菜单、日志复用若依。
2. 按第 5 节实现同名接口；`/login`、`/getInfo`、`/getRouters` 复用若依认证服务的返回结构。
3. 权限标识采用 `fashion:design:*`、`fashion:garment:*`、`fashion:review:*`、`fashion:grading:*`、`fashion:gallery:*`、`fashion:admin:*`；同时校验 `appCode`、课程成员与资源归属。
4. 文件接入既有存储设施，Key 由服务端生成；下载签发短期 URL 并审计。数据库表按既有若依规范迁移，不复用 `sys_user` 存业务数据。
5. Provider 适配器在 Java 侧实现；浏览器不持密钥。真实图生 3D/CAD 通过内部执行服务或已批准供应商完成。
6. 管理后台页面迁移到若依 Vue 管理端；当前 HTML 控制台作为交互参考，不作为正式后台。

## 10. 验证记录（2026-11-20）

- `node --check`：`server/src`、`server/src/routes`、`web/shared`、各应用 JS 全部通过。
- API 冒烟：`node server/test/smoke.js <base>`，**27 项通过**，覆盖登录/角色错配拒绝、对象归属、面料新增与重名、上传/签名下载、作品/草稿/版本、设计任务、三维图片组与 OBJ、复核分析/裁定/发布/报告、放码与 CSV、展厅提交/发布/撤回、应用停用、禁用账号即时失效、后台模板/Provider/课程管理。
- 浏览器冒烟（Chrome headless + CDP，脚本位于工作区 `.tmp/browser-check.mjs`，不纳入源码）：**10 步通过**，覆盖门户、学生设计（三风格主色换色/生成/保存版本）、三维上传与查看、教师复核发布、放码新图、访客展厅、管理员登录与 11 个后台菜单、无运行时异常/控制台错误/HTTP 错误。
- 截图保存在 `.tmp/shots/`（不作为正式视觉签收）。

未验证：真实若依 Server、真实 Provider、专业 CAD/OBJ 兼容、生产性能、跨浏览器矩阵、360px 真机、并发与恢复演练、数据保留/未成年人政策。

## 11. 已知差距与后续任务

1. **正式若依接入**：需要现有 Server 版本、模块结构、认证、数据库、文件与测试环境。
2. **真实 Provider**：文字/图片/三维/CAD 适配、回调签名、幂等对账、成本与地域。
3. **设计套图**：正背必选、可选视角、逐图重试、整套版本与 ZIP。
4. **展厅模型**：独立 OBJ/GLB 上传、服务端校验、在线查看与真实渲染封面。
5. **跨应用传递**：用户明确的“发送至…”资产版本协议与 `transferId`。
6. **生产化**：HTTPS、限流、CSRF/CORS 策略、对象存储、备份恢复、监控告警、审计留存、密钥管理。
7. **通知与运营**：个人任务通知、失败告警、配额申请与成本对账界面。

以上未完成项不因本地演示可运行而计为正式验收；对应需求与门禁仍按 PRD 第 16、20、22、24 章执行。
