- cms.py:没设 YS_PORTAL_DIR / YS_ORDER_DIR 或缺 content/site.json 时拒绝工作(不建空的第一版,免得一发布清空网站); 同时最多 2 个 scrypt(内存上限 256M);登录冷却记录定期清理;价格 / 付款只在这次发布真改了才写回 (不覆盖 admin.py price 的改动) - 后台页面:发布冲突二选一(丢掉我的草稿 / 确认后覆盖发布);草稿没存上、还有图在上传时不让发布 - layout.js:中圈排满后分档到外圈空槽之间找位置,40 条世界线也不重叠;去掉慢的 Math.hypot - config.js:后台把世界线删光也照实显示;门户删掉旧启动仪式留下的死数据;版本号 v=3 - 测试:内容后台 78 / 回归 27 / 数据库 38 全过;端到端浏览器 36 全过 - 文档同步(交接文档、内容后台设计「实现对照」、后端交接说明、交付清单) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
421 lines
33 KiB
Markdown
421 lines
33 KiB
Markdown
# 金钻客栈 · 2026-10 总交接文档(前端 + 后端)
|
||
|
||
> 这一份把 2026-10-05 这一轮**前后端所有改动**、**功能增删**、**设计规范**、**业务逻辑**和**部署运维**写在一处。
|
||
> 细节文档还在各自目录里(位置见第 1 节),这份是总目录 + 总说明。
|
||
>
|
||
> 占位值一律保持原样:`example.com` / `shop.example.com`、`123456789`、`备案号(已移除)`、`(本机路径)`、`<DATA_DIR>` / `<APP_DIR>` / `<WORKER_DIR>` / `<WIN-PATH>` 等。
|
||
> 署名不动(「苏达 · 大肥鱼」)。本文不含任何密钥、真实地址或截图。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [仓库里有什么](#1-仓库里有什么)
|
||
2. [变更清单(按提交)](#2-变更清单按提交)
|
||
3. [功能增加 / 删除一览](#3-功能增加--删除一览)
|
||
4. [⚠️ 接口与数据格式变更(单独列)](#4-️-接口与数据格式变更单独列)
|
||
5. [设计规范](#5-设计规范)
|
||
6. [业务逻辑](#6-业务逻辑)
|
||
7. [部署与运维](#7-部署与运维)
|
||
8. [测试与验证](#8-测试与验证)
|
||
9. [已知未验证 / 待确认](#9-已知未验证--待确认)
|
||
10. [内容后台(2026-10-05 晚实现)](#10-内容后台2026-10-05-晚实现)
|
||
|
||
---
|
||
|
||
## 1. 仓库里有什么
|
||
|
||
| 目录 / 文件 | 是什么 | 细节文档 |
|
||
|---|---|---|
|
||
| `portal/` | 门户(整个网站):首页 / 画展 / 工具与开源 / 金钻宇宙 / 平台入口 / 关于,单文件 `index.html` + 资源 | 本文第 5、6 节;`portal/assets/universe/交接说明.md`(星系图) |
|
||
| `order/` | 自助模板渲染(下单页)`index.html` + `skincheck.js` | 本文第 6.2 节 |
|
||
| `backend/backend-site/` | 网站后端:`server.py`(全部服务端逻辑)、`store.py`(数据库)、`admin.py`(命令行管理)、`pngcheck.py`(PNG 结构核验)、`tests/` | `backend/backend-site/交接说明.md`、`回执-Claude.md` |
|
||
| `backend/backend-tools/` | 店主电脑上的一整套:渲染机 `ys_worker.py`、开单后台 `ys_admin.py`、本机开单 `ys_local.py` + `local.html`、Blender 出图脚本 `make_order.py`、各种启动脚本 | `backend/backend-tools/交接说明.md`、`回执-Claude.md` |
|
||
| `backend/模板/` | 三个 Blender 模板工程(测试用) | `backend/模板/说明.md` |
|
||
| `backend/deploy/` | 反向代理路由与限流片段 | `backend/deploy/nginx-片段.md` |
|
||
| `backend/他应该知道的.md` | 生意背景 / 机器约束 / 数据边界 / 术语表 | — |
|
||
| `交接说明.md`(根目录) | 11eb16c 那一轮视觉改版的说明(**部分已过时**,以本文为准) | — |
|
||
|
||
---
|
||
|
||
## 2. 变更清单(按提交)
|
||
|
||
时间顺序。哈希以 `git log` 为准。
|
||
|
||
### 2.1 `11eb16c` · 前端 2026 改版「白光藏色 × MC 方块」
|
||
|
||
- 删掉上一轮的暗色覆盖块 `redesign-2026`(反馈不好看)。
|
||
- 两页 `</body>` 前新增 `<!-- jz-2026:start -->…<!-- jz-2026:end -->`:手机底栏 HTML + `<style id="jz-2026">` + `<script id="jz-2026-js">`;下单页 `<body>` 开头另加一段跟门户一样的顶栏。
|
||
- 浅色配色、流动淡彩背景(WebGL,降级为静态渐变)、MC 方块按钮、像素标题字(缝合像素字体子集,OFL)。
|
||
- 门户顶栏加「自助渲染」入口;手机端底部物品栏导航 + 「更多」面板(像开关一样再点就收)。
|
||
- 下单页页头改版;四段进度条 `.prog` 用 CSS 隐藏(DOM 和逻辑都还在)。
|
||
- 修了「工具与开源」卡片正文被挤成一指宽的问题。
|
||
- 这一轮**没改**任何原有 `<script>` / `<style>` 块(逐块比对过)。详见根目录 `交接说明.md`。
|
||
|
||
### 2.2 `651d21d` · 后端复查修复 + 回执
|
||
|
||
外部复查找到的问题,按会丢钱 / 丢数据的先修:
|
||
|
||
| 问题 | 改法 |
|
||
|---|---|
|
||
| 同一张码并发提交能成两单 | 查码和绑码放进同一把锁(`redeem_bind`) |
|
||
| 卡密规则只信前端报的张数 | 按 `max(前端张数, 实际模板数)` 和模板并集校验;不认识的模板 key 直接拒 |
|
||
| 爱发电回调重放 / 改单号能多发码、多激活 | 处理过的平台单号一律原样回;回调和账本读写串行(`HOOK_LOCK`) |
|
||
| `admin.py` 和服务器同时改 `codes.json` 互相覆盖(实测 200 张丢 185 张) | `LOCK` 加跨进程 `flock`;写文件用唯一临时名 + `fsync` |
|
||
| `sweep` 会删掉还在排队 / 等确认的单 | 只清走完流程的单 |
|
||
| 卡密 / 单号 / 取件码用 `random` 生成(可预测) | 改 `secrets` |
|
||
| 重渲换皮肤不过 PNG 核验 | 走同一套核验 |
|
||
| 反馈接口能灌爆磁盘和通知 | 限频 + 磁盘闸 + 只收图片 |
|
||
| 下载整个读进内存 | 边读边发;zip 同一时间只打一个 |
|
||
| 部分失败静默标「已完成」 | 记 `partial`,通知店主,页面说实话 |
|
||
| `H.finish` 和框架方法重名 | 改名 `finish_upload`(接口路径不变) |
|
||
| 本机开单工具接受任意来源的 POST | 只认本机页面(Host / Origin 校验) |
|
||
|
||
附 `tests/回执复现测试.py`(27 条;原版 13 条失败,改后全过)。
|
||
|
||
### 2.3 `51212a0` · 接入 SQLite + 开单后台重写
|
||
|
||
- 新增 `store.py`:卡密 / 订单信息 / 爱发电账本 / 呼叫记录 / 小块状态进 `<DATA_DIR>/ys.db`;第一次启动自动建库并导入旧 JSON(旧文件不动)。
|
||
- `server.py` / `admin.py` 的存取换到库上,路由逻辑不变;`calls.jsonl` 照旧追加(手机通知读它)。
|
||
- 管理接口新增 `calls` / `call-done` / `retry`,`codes` 加 `q` 搜索。
|
||
- `admin.py db check / backup / export`。
|
||
- `ys_admin.py`(开单后台)页面按功能重写:待处理 / 订单 / 卡密 / 福利券 / 呼叫·反馈 / 开单工具。
|
||
- 新增 `tests/数据库测试.py`(现编假数据)。
|
||
|
||
### 2.4 `3ae940d` · 本机开单页面重写
|
||
|
||
`backend-tools/local.html` 换成跟网站 / 后台同一套样子;补上原来没写样式的分辨率选择、没绑事件的「清空」;整页接收拖拽;按勾选顺序标号;预计耗时。`ys_local.py` 没动。
|
||
|
||
### 2.5 `09b229d` · 金钻宇宙换成星系图 + 推送前审查
|
||
|
||
- 门户「金钻宇宙」板块:**删掉**启动仪式、宇宙首屏晶体、盘符机架、读盘舱;**换成**星系图(three.js,懒加载)+ 窗下世界线卡片。
|
||
- 世界线数据只剩一份:`portal/assets/universe/config.js`(主脚本也读它)。
|
||
- 像素字子集按新文字重做(并保留了原来所有字)。
|
||
- 审查修掉的后端问题:`add_call` 写库失败会打断渲染机回传;多进程同时首启会重复导入呼叫记录;撤销「处理过了」没清时间。数据库测试加一条,共 38 条。
|
||
- 本文档。
|
||
|
||
### 2.6 内容后台 + 新世界线自动排位 + 星球预设
|
||
|
||
- **内容后台**(第 10 节):网站上所有展示内容在网页后台里改 —— 账号密码登录(首次 `admin/admin` 强制改密)、草稿自动保存、预览、发布、回滚、画展传图。
|
||
后端 `backend-site/cms.py`(挂在 `server.py` 的 `/api/cms/*`),页面 `portal/admin/`,命令行 `admin.py user …`。
|
||
- **门户 / 下单页改成读内容文件**:`portal/content/site.js`(`window.JZ_CONTENT`)、`order/content/order.js`(`window.JZ_ORDER`),后台发布时生成;代码里写死的数据降级为兜底。
|
||
- 门户顶栏最右边加内容后台入口:一个不带字的淡色铅笔图标(无边框,hover 稍亮)。
|
||
- **星系图排布** `layout.js`:新点亮的世界线自动排到中圈不挤的位置,补给线接到附近更靠里的星(不穿星);空槽按编号固定在外圈;**新加一条,已有的星和线都不动**。
|
||
- **星球预设**从 7 种加到 18 种:类地(卡通地球)/ 海洋 / 丛林 / 荒漠 / 冻原 / 熔岩 / 毒雾 / 荒芜岩球 / 冰巨星 / 带环巨星(光环只有这个预设才有)。
|
||
- 星图名牌 / 档案卡的文字一律转义(内容来自后台,不能当 HTML 拼)。
|
||
- 新增 `tests/内容后台测试.py`(78 条);端到端浏览器流程 36 条(第 8 节)。
|
||
- 推送后全量细审又修了:部署漏配(没设 `YS_PORTAL_DIR` / 缺 `content/site.json`)时内容后台拒绝工作,不会建空的第一版、一发布清空网站;同时最多 2 个 scrypt 在算(内存上限 256M);登录冷却记录定期清理;发布冲突给「丢掉我的草稿 / 用我的覆盖」二选一(原来会卡死在冲突里);草稿没存上、还有图在上传时不让发布;价格 / 付款文件只在这次真改了才写(不覆盖 `admin.py price` 的改动);排位在世界线很多时分档放宽、40 条也不重叠;删掉门户里旧启动仪式留下的死数据。
|
||
|
||
---
|
||
|
||
## 3. 功能增加 / 删除一览
|
||
|
||
### 增加
|
||
|
||
| 在哪 | 功能 |
|
||
|---|---|
|
||
| 门户 · 金钻宇宙 | 星系图:旋臂星系 + 星云 + 扇区 + 补给线;每条世界线一颗卡通星球(材质按设定:晶体 / 铅笔纸面 / 冰封 / 霓虹 / 善恶两半);点星系或下面卡片飞过去,档案卡和星球同时落定;五种运镜(推进 / 放大 / 升空俯冲 / 跃迁 / 绕行);全屏;`#0001` 深链可分享 |
|
||
| 门户 · 全站 | 「自助渲染」入口;手机底部物品栏 + 「更多」面板;流动淡彩背景 |
|
||
| 下单页 | 跟门户一致的顶栏 / 底栏 |
|
||
| 后端 | SQLite 数据库(自动建库、自动导入、导出回退、热备份、体检) |
|
||
| 后端 · 管理接口 | 呼叫记录列表、标「处理过了」、失败单退回重渲、卡密搜索 |
|
||
| 开单后台 | 待处理首页(要动手的事集中在一页)、订单搜索、卡密搜索 / 停用 / 启用 / 改张数、订单备注、呼叫·反馈页、失败单「退回重渲」按钮 |
|
||
| 本机开单 | 分辨率选择样式、清空、整页拖拽、出图顺序标号、预计耗时、复制买家说明 |
|
||
| **内容后台**(新) | 账号密码登录、首次强制改密、草稿 / 预览 / 发布 / 回滚、发布记录、操作日志、登录设备管理;可改:首页文案与公告、板块说明、画展(含传图)、工具与开源、金钻宇宙(档案 + 外观)、平台入口、关于、下单页模板上下架 / 名字 / 说明、页头与公告、价格档位、付款方式 |
|
||
| 门户 / 下单页 | 读后台发布的内容;首页公告条(可设起止日期);`?preview=1` 预览草稿(只有登录的人看得到) |
|
||
| 金钻宇宙 | 新世界线自动排位与连线;星球预设 18 种 |
|
||
|
||
### 删除
|
||
|
||
| 在哪 | 删了什么 | 为什么 |
|
||
|---|---|---|
|
||
| 门户 · 金钻宇宙 | 启动仪式(逐字 / 权限扫描 / 欢迎)、宇宙首屏晶体线框(`CrystalView`)、盘符机架(抽插 / 拖拽 / 导轨)、读盘舱(特写弹窗 / 拆解 / 翻页)、两枚只给插卡用的图标(白标 `--icd-logo`、火柴人 `--icd-people`)、相关 CSS | 被星系图取代;店主说机架「丑死了」 |
|
||
| 门户 · 装饰 | 英文 kicker、遥测数字条、时钟、`LINK // 已同步`(CSS 隐藏,DOM 还在) | 文案要说人话 |
|
||
| 下单页 | 四段进度条(CSS 隐藏,逻辑还在) | 店主觉得难看 |
|
||
| 前端 | 上一轮暗色覆盖块 `redesign-2026` | 不好看 |
|
||
|
||
保留:首页右侧晶钻徽记、`#0001` / `#rack` 旧链接(分别飞到那条世界线 / 打开宇宙板块)。
|
||
|
||
---
|
||
|
||
## 4. ⚠️ 接口与数据格式变更(单独列)
|
||
|
||
> 规矩:动了接口路径、请求 / 响应字段、数据格式的,必须单独标出来 —— 渲染机是另一台机器上的另一份代码,两边对不上会静默出不来图。
|
||
|
||
| 类别 | 变更 | 影响谁 |
|
||
|---|---|---|
|
||
| **数据格式** | 卡密 / 订单信息 / 爱发电账本 / 呼叫记录 / 小块状态从 JSON 文件挪进 `<DATA_DIR>/ys.db`。第一次启动自动导入,旧文件原样留着;`admin.py db export` 能导回旧格式 | 服务器、`admin.py`。**渲染机不受影响** |
|
||
| 新增接口 | `GET /api/admin/calls`、`POST /api/admin/call-done`、`POST /api/admin/retry` | 开单后台(新按钮要它们:**服务器先升级**) |
|
||
| 接口加参数 | `GET /api/admin/codes?q=`(可选,不传和以前一样) | 开单后台 |
|
||
| 新增字段 | `/api/claim` 回的订单里多一个 `terms_v`(只增不减) | 渲染机可以不理 |
|
||
| 开单后台本机接口 | 新增 `/api/codes` `/api/calls` `/api/retry` `/api/note` `/api/code-edit` `/api/call-done`(都要 PIN,原样转服务器) | 只有面板页面自己用 |
|
||
| 前端 | 门户的 `#rack` / `#bay` DOM 与 `window.__icd.open/close/flip/tray` 调试钩子删了;新增 `window.__jzUniverse.show()/fly(no)` | 只有页面自己和自动化脚本 |
|
||
| **新增接口** | `/api/cms/*`(登录 / 内容 / 草稿 / 发布 / 回滚 / 传图 / 预览),见 `cms.py` 开头;nginx 要加一节(`deploy/nginx-片段.md` ④) | 只有内容后台页面 |
|
||
| **数据格式** | 库里新增 `cms_users` / `cms_sessions` / `cms_draft` / `cms_versions` / `cms_audit` 五张表(启动时自动建);新增内容文件 `portal/content/site.{json,js}`、`order/content/order.{json,js}`;画展上传的图在 `portal/uploads/` | 服务器、门户、下单页 |
|
||
| 文件被谁写 | `prices.json` / `payinfo.json` 现在也由内容后台发布时写(**格式不变**,别的字段原样保留;只有这次发布真改了价格 / 付款才写)。`admin.py price` 还能用,但建议统一在后台改 | 服务器 |
|
||
| 前端 | 门户读 `window.JZ_CONTENT`、下单页读 `window.JZ_ORDER`(读不到用内置兜底);下单页 `TEMPLATES` 拆成 `TEMPLATES_ALL`(全部,用于显示老订单)和 `TEMPLATES`(上架的) | 页面自己 |
|
||
|
||
**没变**:所有买家接口、渲染机接口的路径和字段;本机开单的本机接口。
|
||
|
||
---
|
||
|
||
## 5. 设计规范
|
||
|
||
### 5.1 一句话
|
||
|
||
**白光藏色 × Minecraft 方块**:一眼看过去是白的,颜色藏在亮部和缓慢流动的淡彩光里;按钮是 MC Ore UI 那种方块按钮;标题用像素字;正文用 OPPO Sans。
|
||
|
||
### 5.2 颜色 token(门户 / 下单页写在 `jz-2026` 块的 `:root`;后台 / 本机开单各自复制一份)
|
||
|
||
| 用途 | 变量 | 值 |
|
||
|---|---|---|
|
||
| 页面底色 | `--bg` | `#F5F7FB` |
|
||
| 正文墨色(深→浅) | `--ink` / `--txt` · `--txt-2` · `--txt-3` · `--txt-4` | `#1E2440` · `#454B6B` · `#676D8A` · `#858AA2` |
|
||
| 发丝线 | `--line` / `--line-soft` | `rgba(30,36,64,.12)` / `.08` |
|
||
| 主色(草方块绿) | `--mc-green` / `-hi` / `-lo` | `#3C8527` / `#5BAA3C` / `#1D4D13` |
|
||
| 次按钮(石头白) | `--stone` / `--stone-lo` / `--stone-edge` | `#F3F4F6` / `#B4B7BE` / `#9EA2AA` |
|
||
| 面板 | `--panel-shadow` + 半透明白 | `inset 0 1px 0 #fff, 0 22px 44px -28px rgba(100,110,190,.38)`;底 `rgba(255,255,255,.74~.9)`,2px 白边 |
|
||
| 警告 / 错误文字 | `--warn-t` / `--bad-t` | `#9A6A0C` / `#B33A2E` |
|
||
| 首页板块卡的「矿石色」 | `--zc` | 画展金 `#F2C14D`、工具蓝 `#4F86E8`、宇宙紫 `#9A6BE0`、平台绿、关于红(只在悬停时从边缘亮出来) |
|
||
| 背景彩光 | `body::before` 四团 radial-gradient | 天蓝 / 粉 / 杏 / 薄荷,透明度 .22~.30;有 WebGL 时换成 `#jzBg` 流动彩光 |
|
||
| 星系图(唯一的深色区域) | `config.js → GALAXY.colors` | 深海军蓝 `#070B1C` + 蓝紫星云 + 一点青 + 暖金 `#FFD36E`(名牌 / 数字) |
|
||
|
||
### 5.3 字体
|
||
|
||
- **标题**:`JZ Pixel` = 缝合像素字体 12px(TakWolf,SIL OFL 1.1),**只含页面用到的字**(子集)。门户 `portal/fonts/jz-pixel-12.woff2`,下单页 `order/assets/jz-pixel-12.woff2`,协议原文在同目录。12 的整数倍字号最清楚,`-webkit-font-smoothing:none`。
|
||
- **正文**:OPPO Sans(可免费商用)。
|
||
- **加了新字(比如新世界线名字)要重做子集**,否则那几个字会掉回系统字体:
|
||
```
|
||
# 文本 = 旧子集里已有的字 ∪ 页面 + config.js + galaxy.js 里所有字(只加不减)
|
||
python3 -m fontTools.subset fusion-pixel-12px-proportional-zh_hans.otf.woff2 \
|
||
--text-file=字表.txt --flavor=woff2 --layout-features='*' --output-file=portal/fonts/jz-pixel-12.woff2
|
||
```
|
||
源字体从 fusion-pixel-font 的 release 取(12px proportional zh_hans)。
|
||
|
||
### 5.4 组件
|
||
|
||
| 组件 | 规则 |
|
||
|---|---|
|
||
| 按钮 | **全站统一一种**:MC 方块,`border-radius:4px`,2px 边,上亮下暗的内阴影;按下下沉 2px。绿 = 主操作,石头白 = 次操作,红字 = 危险操作(注销 / 停用 / 收摊) |
|
||
| 卡片 / 面板 | 半透明白 + 2px 白边 + `--panel-shadow`,圆角 8px(大块 12px)。**只有吸顶顶栏用 `backdrop-filter`**,面板不用(卡、而且显得死板) |
|
||
| 标签 / 状态 | 色块小标签(4px 圆角、浅底深字):绿 = 通过 / 已完成,黄 = 注意,红 = 失败,蓝 = 进行中,灰 = 停用 |
|
||
| 输入框 | 白底、2px 线、聚焦变绿 |
|
||
| 动效 | 只动 `transform` / `opacity`;缓动 `cubic-bezier(.23,1,.32,1)`;尊重 `prefers-reduced-motion` 和页面上的「动效」开关 |
|
||
|
||
### 5.5 移动端规则
|
||
|
||
- 窄屏(≤760 / 860px):顶栏只留 logo 和开关;底部浮动物品栏(首页 / 画展 / 渲染〔中间钻石〕 / 宇宙 / 更多),「更多」从底栏上方弹出一排格子,再点同一个按钮 / 点空白 / 返回键 / Esc 收起。
|
||
- 左右边距 16px 左右;**任何页面不许横向滚动**(每次改完都要在 390 宽度下检查)。
|
||
- 星系图在手机上:星图里的手势全归星图(拖动转、双指缩放,页面不跟着滑),窗户只占屏幕约 64%,上下留出滑页面的地方;档案卡是窗里的底部抽屉,星球挪到上半个窗。
|
||
|
||
### 5.6 口味禁区(每条都是看过预览之后的直接反馈)
|
||
|
||
- **不要暗色面板**、不要黑白强对比(星系图窗户是唯一例外);不要复古风。
|
||
- **文字 / 标题 / 名牌前面不要放小圆点、小方块色点**。
|
||
- 不要按钮扫光动画;不要六边形「三棱镜」按钮;全站按钮一个样子。
|
||
- 星系图:不要星球光环、不要每颗星外面一层大气「罩子」、辉光不能过曝;颜色只用那一套(深蓝 + 蓝紫 + 金),不要彩虹;装饰星球不能互相重叠、卫星不能反着转;开场 / 飞行运镜要连贯,档案卡要跟星球落定同时出来。
|
||
- 流动大背景要平滑,不要像素化;像素风只留在字、按钮、粒子上。
|
||
- **文案说人话**:不写「标签 · 解释」式的说明、不加英文小字装饰、不写解释界面怎么用的句子。
|
||
- 改一块就只动那一块,不要顺手改邻居(比如改顶栏时别动头图);小步改。
|
||
|
||
---
|
||
|
||
## 6. 业务逻辑
|
||
|
||
### 6.1 网站全貌
|
||
|
||
金钻客栈 = 一个线上「客栈」:画展、工具与开源、金钻宇宙、各平台入口都在里面;**自助模板渲染只是其中一家店**。
|
||
|
||
| 门户板块 | 内容 | 数据在哪 |
|
||
|---|---|---|
|
||
| 首页 | 欢迎首屏 + 五个板块卡 | `BOARDS` |
|
||
| 画展 | 图片 / 视频 / 全景 / 动态壁纸,按时间排、可筛选(脱敏版只有一张占位) | `GALLERY` + `hd_cache/manifest.json` |
|
||
| 工具与开源 | 开源一行 / 闭源一行,按类型筛选 | `APPS` |
|
||
| 金钻宇宙 | 星系图 + 世界线档案(0000 零号主宇宙、0001–0004 已点亮、0005–0010 空槽) | `portal/assets/universe/config.js` |
|
||
| 平台入口 | 视频 / 图文 / 模型创作 / 开源 / 小店 / 联系,外链新窗口打开 | `LINK_GROUPS` + `LINKS` |
|
||
| 关于 | 制作者、开源组件鸣谢、名字由来 | 静态 HTML |
|
||
|
||
路由:`#/板块`(单页切换,无整页刷新);`#0001` 这种编号直接飞到那条世界线;`#rack` 兼容到宇宙板块。
|
||
|
||
**加一条世界线**:`config.js` 里把空槽换成完整档案(`no / name / kind / tag / tags / desc`)+ 在 `LOOKS` 里给它一个外观(`style / r / orbit / accent / moons / enter`);名字里有新字记得重做像素字子集(5.3);改了 JS 要换版本号(7.2)。细节见 `portal/assets/universe/交接说明.md`。
|
||
|
||
### 6.2 下单页(`order/`)
|
||
|
||
两条路:
|
||
|
||
```
|
||
网页下单:传皮肤(本地质检)→ 选模板 / 分辨率 → 出订单号(待付款)→ 去爱发电付款
|
||
→ 爱发电回调确认 / 店主后台激活 → 排队 → 渲染机出图 → 买家看 512 预览 → 确认收货 → 下原图
|
||
卡密下单:传皮肤 → 填卡密(自动认模板 / 张数)→ 直接排队 → 出图 → 同上
|
||
凭票取图:拿单号 + 取件码(或卡密)回来看进度、下载
|
||
```
|
||
|
||
皮肤质检(`skincheck.js`,前端和本机开单共用):尺寸是否 64 网格的正方形、像素风检查、主体层完整、半透明、外层铺满、手臂粗细判定;PNG 结构核验防夹带(尾部追加 / 未知关键块 / APNG)。服务器落盘前还会再核一遍(`pngcheck.py`)并剥掉元数据块。
|
||
|
||
### 6.3 订单状态机
|
||
|
||
```
|
||
unpaid(待付款)──买家点「我付好了」──▶ paid(待激活)
|
||
│ │
|
||
└──── 爱发电回调确认 / 后台激活 / 买家用卡密激活 ───┘
|
||
▼
|
||
waiting(排队中)──渲染机 claim──▶ working(渲染中)
|
||
▲ │
|
||
后台「退回重渲」/ admin.py retry 一张一次 /finish 回传
|
||
│ ▼
|
||
failed(失败)◀── 水印没生成 ── done(已完成)
|
||
unpaid / paid ──后台注销──▶ void(已注销,不占卡密)
|
||
```
|
||
|
||
- 领单超过 45 分钟没交回 → 自动退回队列。4096 的「重单」高峰期给小单让路,最多让 30 分钟(防饿死)。
|
||
- 收满张数才算完成;渲染机显式收单但没收满 = **部分失败**:记 `partial`、页面说实话、通知店主。
|
||
- 预览水印没做出来的不许标完成(标 `failed`,等退回重渲)。
|
||
- 成品保留 72 小时(从开放下载算);`admin.py sweep` 清理时**先核销卡密再删文件**,排队 / 渲染中 / 待激活的单绝不删。清理后库里那一行留着做账。
|
||
|
||
### 6.4 卡密生命周期(**激活 ≠ 核销**)
|
||
|
||
```
|
||
active(可用)──买家提交──▶ bound(已激活:被这一单占住,还没核销)──开放下载满 72 小时──▶ used(已核销,终态)
|
||
inactive(停用:网页单等付款 / 手动停用)
|
||
```
|
||
|
||
卡密种类:固定 N 张 / 最多 N 张 / 不限张数;可锁模板;「直发」= 店主自己发的码,不用等确认收货。
|
||
防暴破:码空间 31¹² ≈ 7.9e17;同 IP 连错 15 次冷却 15 分钟;单 IP 10 分钟最多开 6 单。
|
||
|
||
### 6.5 爱发电回调
|
||
|
||
不验签(没有对方公钥),改成**拿开放接口反查这笔单**。处理顺序:
|
||
① 标题含「测试」只记账 → ② 同一平台单号重推:原样回上次结果(幂等)→ ③ 反查不到 / 没付款:只记账、标人工,**绝不发码** → ④ 金额:少付拦死、多付照常但记一笔 → ⑤ 认单:自定义订单号 > 留言里的卡密 > 留言里的单号 > 「只有一笔待付款单金额对得上」(两笔以上一律人工)。
|
||
|
||
### 6.6 渲染机(店主电脑,`ys_worker.py`)
|
||
|
||
只出站:定时 `claim`(领单)+ 独立线程 `hb`(心跳,默认 10 分钟一次,`hb_every`)→ 取皮肤 → Blender 后台渲染(**同一时刻只允许一个 Blender**)→ 中途 `progress` → 一张一次 `finish` 回传。心跳超过 1500 秒没更新 = 页面显示离线(所以 `OFFLINE_AFTER` 必须大于心跳间隔,两边一起改)。心跳顺带记下家里的出口 IP,管理接口只认这个 IP。
|
||
|
||
### 6.7 福利券
|
||
|
||
一批「免费、已激活」的码放在福利页让人自取:**每台设备 + 每个网络各限领 1 张**(服务器硬规则),领到后 N 天内要用;可锁模板、限张数、定种类(渲染图 / 立牌 / 钥匙扣 / 海报)、到期自动收摊;收摊后已领走的照常能用。
|
||
|
||
### 6.8 开单后台(`ys_admin.py`,店主电脑,局域网)
|
||
|
||
- PIN 锁(服务端校验,加盐 sha256,12 小时免输);调服务器管理接口要「令牌 + 家里出口 IP」两道门。
|
||
- 六页:**待处理**(买家说付好了的单、渲染失败的单、没处理的呼叫)/ 订单 / 卡密(生成 + 库)/ 福利券 / 呼叫·反馈 / 开单工具。
|
||
|
||
### 6.9 本机开单(`ys_local.py` + `local.html`)
|
||
|
||
给聊天里成交的平台单用:拖皮肤 → 同一套质检 → 勾模板 → 本机 Blender 出图 → 下载 / 打开留档文件夹。**不联网、不上传、不要卡密**,只监听本机,只认本机页面。
|
||
|
||
### 6.10 数据库
|
||
|
||
见 `backend/backend-site/交接说明.md` 第五节。要点:`ys.db` 里 5 张表(codes / orders / pay_orders / calls / kv),每张「能查的列 + 一列整条 JSON」;上层代码拿到的还是原来的 dict;`.lock` 文件锁照旧;WAL 模式。
|
||
|
||
---
|
||
|
||
## 7. 部署与运维
|
||
|
||
### 7.1 文件放哪
|
||
|
||
| 文件 | 放到 | 备注 |
|
||
|---|---|---|
|
||
| `portal/**` | 网站根目录 | 星系图要 `assets/universe/` 和 `assets/vendor/` 一起上 |
|
||
| `order/**` | 网站 `/order/` | |
|
||
| `server.py` + **`store.py`** + `admin.py` + `pngcheck.py` | `<APP_DIR>`(同一目录) | `server.py` 直接 `import store`,**少了 `store.py` 服务起不来** |
|
||
| `backend-tools/*` | 店主电脑 `<WORKER_DIR>` | `deploy.py` 推送;面板新按钮依赖服务器新接口,**先升服务器** |
|
||
| **`cms.py`** | `<APP_DIR>`(和 `server.py` 同一目录) | `server.py` 直接 `import cms` |
|
||
| `portal/admin/` | 网站 `/admin/` | 内容后台页面(静态) |
|
||
| `portal/content/`、`order/content/` | 随页面一起 | 后台发布时**由服务器进程覆盖写**:这两个目录和 `portal/uploads/` 要给服务进程写权限 |
|
||
|
||
**环境变量**(systemd 单元里加):`YS_PORTAL_DIR=<门户网站根目录>`、`YS_ORDER_DIR=<下单页目录>`(内容后台写内容文件和上传图用;`YS_ROOT` 照旧)。
|
||
|
||
### 7.1b 内容后台首次部署(⚠️ 照顺序做)
|
||
|
||
1. nginx 按 `deploy/nginx-片段.md` 第 ④ 节加配置(**必须带 `X-Forwarded-Proto`**,整站 http → https)。**没配好证书之前不要开放**:后端会拒绝所有非 https 请求。
|
||
2. 放好 `cms.py`、设好两个环境变量、给 `content/` `uploads/` 写权限,重启服务。第一次启动会自动建初始账号 `admin / admin`,日志里有一句提示。
|
||
3. **马上**打开 `https://<站点>/admin/`,用 `admin / admin` 登录 → 强制改密(至少 8 位、不能是 admin / 常见密码)→ 用新密码重新登录。
|
||
在改密之前,服务端只放行改密码和退出,其它接口一律 403;但这段空档里谁先登进去谁就能改密 —— 所以越快越好。
|
||
4. 第一次打开内容页时,后台把网站现有的 `content/` 文件当成第 1 版。
|
||
5. 账号管理(服务器上):
|
||
```
|
||
python3 admin.py user list # 有哪些账号、最近登录
|
||
python3 admin.py user add <用户名> [--email 邮箱] [--temp] # 建账号(--temp 发一次性临时密码,首次登录必须改)
|
||
python3 admin.py user passwd <账号> # 设新密码(所有会话作废)
|
||
python3 admin.py user reset <账号> [--to-admin] # 忘了密码:会话全作废 → 临时密码(只打印在终端)→ 下次登录必须改
|
||
python3 admin.py user disable|enable <账号>
|
||
python3 admin.py user sessions <账号> [--revoke-all]
|
||
```
|
||
|
||
### 7.2 缓存与版本号
|
||
|
||
- 门户星系图:改了 JS / CSS 要换版本号,**一起换**:`portal/index.html` 里 `universe.css?v=`、`config.js?v=`、底部模块脚本里 `galaxy.js?v=`,`galaxy.js` 里 `import './planets.js?v='` 和 `'./layout.js?v='`,以及 `portal/admin/index.html` 里 `planets.js?v=`。踩过:坏文件被缓存住,修好了打开还是「加载不出来」。
|
||
- 内容文件 `content/site.js` / `order.js` 文件名不变、内容会变:nginx 给 `/content/` `/order/content/` 加 `Cache-Control: no-cache`(片段里有)。
|
||
- 检查 ES 模块语法要拷成 `.mjs` 再 `node --check`(按普通脚本查会漏「重复声明」)。
|
||
- three.js 只在第一次打开「金钻宇宙」时下载(约 690KB,gzip 后约 170KB)。
|
||
|
||
### 7.3 数据库命令
|
||
|
||
```
|
||
python3 admin.py db check # 完整性 + 每张表几行 + 按状态计数
|
||
python3 admin.py db backup # 在线热备份到 <DATA_DIR>/backup/
|
||
python3 admin.py db export [目录] # 导回旧版 JSON(回退用)
|
||
```
|
||
|
||
回退:停服务 → `db export` → 换回旧版 `server.py` / `admin.py` → 启动。再切回来:挪走 `ys.db`,新版启动时从 JSON 重新导入。
|
||
权限:跑 `admin.py` 的账号要对 `<DATA_DIR>` **目录**有写权限(WAL 会建 `ys.db-wal` / `-shm`)。
|
||
|
||
### 7.4 常用
|
||
|
||
```
|
||
python3 admin.py ls waiting # 看排队
|
||
python3 admin.py retry <单号> # 失败单退回(后台也有按钮)
|
||
python3 admin.py calls # 呼叫记录(后台也有页面)
|
||
python3 admin.py sweep # 清过期成品 + 核销(建议每天跑一次)
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 测试与验证
|
||
|
||
| 测试 | 怎么跑 | 结果(2026-10-05) |
|
||
|---|---|---|
|
||
| 后端回归 + 漏洞复现 | `python3 backend/backend-site/tests/回执复现测试.py <server.py 所在目录>` | 27 / 27 |
|
||
| 数据库专项 | `python3 backend/backend-site/tests/数据库测试.py <server.py 所在目录>` | 38 / 38 |
|
||
| 开单后台 | 假数据起真服务器 + 真面板,headless 浏览器电脑宽 / 手机宽点全部页面 | 无报错、无横滚;无 PIN → 401、无令牌 → 403 |
|
||
| 本机开单 | 假本机服务(模拟渲染)+ headless 浏览器走完整流程 | 无报错、无横滚 |
|
||
| 门户 | headless 浏览器 1366 / 390:六个板块都切一遍;宇宙:星图就绪、点卡片飞过去出档案、`#0002` 深链、全屏开关、手机上拖星图页面不滚;首页不下载 three.js | 全过;除星系图板块外,其余板块和改动前**逐像素一致** |
|
||
| 下单页 | 打开截图 | 正常(本轮没改) |
|
||
| **内容后台(后端)** | `python3 backend/backend-site/tests/内容后台测试.py <server.py 所在目录> <仓库根目录>` | 78 / 78:部署漏配时拒绝工作、后台发布不覆盖命令行改过的价格、初始账号与强制改密(改密前 11 个接口全 403)、库里无明文、Cookie 属性、https / CSRF / 跨站来源 / 爆破冷却(按 IP 5 次、按账号合计 20 次)、内容校验、XSS 转义、发布写文件、冲突 409、回滚一致、预览要登录、传图核验与去元数据、会话撤销与过期、命令行、三进程同时首启只建一个账号 |
|
||
| **内容后台(端到端)** | 迷你反代模拟 nginx + 真服务器 + headless 浏览器 1366 / 390 | 36 / 36:门户入口 → 登录 → 强制改密 → 改文案 / 传图 / 点亮新地球 / 加入口 / 下架模板 / 加档位 → 预览(未登录看不到草稿)→ 发布 → 门户 / 星系图 / 下单页都变了 → 回滚复原 → 退出;无新增报错(只有交付副本本来就缺的 `view_stats.json` 和模板缩略图 404) |
|
||
|
||
后端测试数据全是测试脚本现编的,建在系统临时目录。⚠️ 交付副本里三个 URL 格式串被脱敏成 `http<WIN-PATH>`,要起服务器的测试得先在**测试副本**里换成能格式化的占位(这三处分别吃 1 / 2 / 0 个参数);线上原版直接跑。
|
||
|
||
---
|
||
|
||
## 9. 已知未验证 / 待确认
|
||
|
||
- **星系图帧率没在真机上测过**(只在无头浏览器的软件渲染里验证了画面和交互)。上线前用一台普通手机、一台集显笔记本各打开看一下;卡的话按 `universe/交接说明.md` 第 8 节降粒子数。
|
||
- **数据库没在真机器上跑过**(1.6G 内存 + systemd 内存上限)。部署后先跑一次 `admin.py db check`。
|
||
- 渲染机、真实 Blender、爱发电真实回调、手机通知脚本(读 `calls.jsonl` 的那段不在仓库里)都没有端到端测过。
|
||
- 下单页里的链接是站点根路径(`/#/home`、`/order/`),本地从仓库根目录起服务时「首页」会跳到仓库根,线上没问题。
|
||
- 署名按要求没改(「苏达 · 大肥鱼」)。
|
||
|
||
---
|
||
|
||
## 10. 内容后台(2026-10-05 晚实现)
|
||
|
||
网站前端所有展示内容在网页后台里改,不用再改代码。设计和每条安全规则的来由见根目录 **`内容后台设计.md`**;实现在:
|
||
|
||
| 部分 | 文件 |
|
||
|---|---|
|
||
| 服务端(账号 / 会话 / 草稿 / 发布 / 传图) | `backend/backend-site/cms.py`(`server.py` 把 `/api/cms/*` 交给它) |
|
||
| 后台页面 | `portal/admin/index.html`(入口:门户顶栏最右边的淡色铅笔) |
|
||
| 内容文件 | `portal/content/site.{json,js}`、`order/content/order.{json,js}`(发布时生成;`.json` 是正本,`.js` 给页面读) |
|
||
| 命令行 | `admin.py user …`(见 7.1b) |
|
||
| 测试 | `tests/内容后台测试.py`(75 条) |
|
||
|
||
要点(店主定的安全底线,别放松):
|
||
- 初始账号 `admin / admin`,**首次登录强制改密**;改密前服务端只放行改密码 / 退出,其它接口一律 403。
|
||
- 密码 `hashlib.scrypt`(没有就 `pbkdf2_hmac`)加盐存哈希,任何地方都不存明文;至少 8 位。
|
||
- 会话是服务端令牌(库里只存哈希),「记住我」30 天滑动过期;退出 / 改密 / 命令行重置 / 停用都会当场作废。
|
||
- Cookie:HttpOnly + SameSite=Strict,https 下 Secure;修改类请求要带 CSRF 头;跨站来源拒绝。
|
||
- 只走 https(反代没说 https 就拒);登录冷却:同一 IP 错 5 次 / 同一账号合计错 20 次开始冷却(账号那档放宽,免得别人故意输错把店主锁在门外)。
|
||
- 内容后台碰不到卡密 / 订单。
|