Files
jinzuanwork/交接文档-2026-10.md
T

449 lines
40 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 金钻客栈 · 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` 首页、`gallery.html` 画展、`tools.html` 工具与开源、`universe.html` 金钻宇宙、`links.html` 平台入口、`about.html` 关于(**2026-10-06 起是多页,样子以设计预览站为准**)+ `assets/` `fonts/` `content/` `admin/` | 本文第 2.7、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 条也不重叠;删掉门户里旧启动仪式留下的死数据。
### 2.7 2026-10-06 · 全站按设计预览站重做 + 加载动画 + 宇宙开场星门 + 内容后台接住真实画展
- **门户从单页(`#/板块` 切换)改成六个独立页面**,标记、样式、交互全部照设计预览站(http://161.33.11.66/):
`index / gallery / tools / universe / links / about.html`,共用 `assets/site.css`(预览站原样式 + 末尾一段正式站补充)、`assets/site.js`(预览站原交互:流动背景、视差、卡片倾斜、滚动浮现、翻牌、手机「更多」)。
内容照旧全部读 `content/site.js`(内容后台发布的),由 `assets/pages.js` 按预览站的标记填进去;画展的真功能在 `assets/gallery.js`。
- **画展**(`gallery.js`):样子是预览站的作品墙 + 年份栏 + 白色毛玻璃大图层;原来的功能一样没少 ——
类型 / 谁做的 / 年份→月份筛选、最新 / 最早排序、看过的放前 / 放后 / 不显示、hd_cache 先轻后重的高清、本站 mp4(优先网页版副本)、B 站播放器、全景球面环视、动态壁纸时间轴、观展统计 `/hit` + `view_stats.json`、作品外链。
作品墙改成 JS 按「最矮的一列」投放(预览站用 CSS 分栏,330 件时顺序会竖着走)。
- **旧地址兼容**:`/#/gallery`、`/#/apps`、`/#/universe`、`/#0001` 等会自动跳到新页面(`universe.html#0001` 打开就飞到那条世界线)。
- **加载动画(新)** `assets/boot.js`:像素钻石一块块从底往上垒成形 → 白光扫过 →「金钻客栈」逐字弹出 → 光谱进度条跟真实加载走 → 幕布上收。只在同一个标签页第一次打开时放、最少 1.25 秒、最多等 3 秒、点一下可跳过、「减少动效」时不放。
- **金钻宇宙开场(新)** `assets/universe/gate.js`:three.js 下载 / 星系生成期间,星图窗里是一道「星门」(钻石 + 三圈光谱环 + 一排世界线格子按编号点亮);星系第一帧画好就光环外炸、格子散开、淡出,接上星系图自己的镜头俯冲。打不开 3D 时停在说明文字上。
- **站点固定信息只放一处**:`portal/assets/site-info.js`(`window.JZ_SITE`:域名 / QQ 群号 / 群名 / 加群链接 / 备案号 / 反馈邮箱)。门户六页、下单页、关于页都读它。
**仓库里是占位;正式服务器上只替换这一个文件**(以前要在好几个页面里改,容易漏 —— 10-06 就漏过)。
- **下单页**对齐预览站:全站同一个顶栏 / 底栏 / 页脚、宽版面、落地页改成「怎么下单?」两张路卡 + 「下过单了?」条 + 模板样图(用 400px 的 jpg)+ 分辨率;之后的步骤卡片照预览站的晶体面板。**按钮 id、下单逻辑、接口一个没动**(新样式在 `<style id="jz-site">`,放在 jz-2026 块后面)。
- **像素字体换成更全的子集** `portal/fonts/fusion-pixel-12.woff2`(114KB:ASCII + 常用 3755 字 + 当前全部内容;下单页也用这一份),删了旧的 `jz-pixel-12.woff2`。
- **内容后台能原样接住真实画展**(`cms.py`):文件名带空格、本站 mp4 视频(不填 B 站链接)+ `web` 网页版副本、作品外链 `link` / `links`、离线缩略图索引 `media`、世界线 `tone` / `sector` / `media` —— 以前校验时会报错或悄悄丢掉;`site_payload` 把 `media` 一起写进 `site.js`(以前一发布就丢缩略图,画展会直接拉几百张原图)。测试 +8(86 条)。
### 2.8 2026-10-06 晚 · 五个修复 + 点击光效回归 + 手机深色模式 + 维护页
- 下单页模板样图按原图 1:1 显示。
- 全景 / 动态壁纸:拖着拖出画框外松手,不会再被当成「点空白处」把大图关掉(按下和松手都在空白处才关)。
- 画展长图(宽高比 0.45 那种)在大图里整张放得下(按视口高度限,网格行高 auto 时百分比 max-height 不生效);列表缩略图还没下完时大图先铺缩略图。
- 点击光效:门户各页不加点击光效;下单页用它原来那套(按下发光、面板染色、邻按钮照亮)。(10-06 晚加过一版全站「彩虹边缘光段 + Q 弹」`fx.js`,店主看了说不要,已删。)
- **手机深色模式**:系统设成深色时,手机宽度(≤760px)整站换夜间版(门户六页、画展大图、宇宙页、加载动画、下单页、流动背景着色器 `uDark`);电脑宽度保持浅色。要让电脑也跟随,把 `site.css` / 下单页 `jz-site` 里那段媒体查询的 `(max-width:760px) and` 去掉,`site.js` 里 `mqDark` 同步改。
- **维护页** `portal/maintenance.html`:「钻石在打磨中」—— 钻石镐用 Minecraft 原版 16×16 物品图(`portal/assets/diamond-pickaxe.png`,取自 Minecraft Wiki,版权归 Mojang;本站是非官方粉丝向站点,别拿它做商品图),平时就是原版图标的样子(0°、3px 一格),挥的时候抡起、镐尖敲钻石、钻石一扁一弹、光谱像素火花、白光扫过;MC 方块进度条每敲一下亮一格、满了闪光谱色重来;点钻石也会敲一下;「下单 / 取图照常」按钮。上维护:`cp maintenance.html index.html`(先备份 index.html);撤维护:换回备份。
---
## 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 字体
- **标题**:缝合像素字体 12px(TakWolf,SIL OFL 1.1),子集 `portal/fonts/fusion-pixel-12.woff2`(门户和下单页共用;ASCII + GB2312 一级常用 3755 字 + 当前全部内容,114KB),协议原文 `portal/fonts/fusion-pixel-OFL.txt`。12 的整数倍字号最清楚,`-webkit-font-smoothing:none`。
- **正文**:OPPO Sans(可免费商用)。
- 常用字都在子集里,一般不用管;**用到生僻字(不在 3755 常用字里)才要重做子集**,否则那几个字会掉回正文字体:
```
# 文本 = 旧子集里已有的字 ∪ 页面 + config.js + galaxy.js 里所有字(只加不减)
python3 -m fontTools.subset fusion-pixel-12px-proportional-zh_hans.otf.woff2 \
--text-file=字表.txt --flavor=woff2 --layout-features='*' --no-hinting --output-file=portal/fonts/fusion-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 网站全貌
金钻客栈 = 一个线上「客栈」:画展、工具与开源、金钻宇宙、各平台入口都在里面;**自助模板渲染只是其中一家店**。
| 页面 | 内容 | 数据在哪 |
|---|---|---|
| `index.html` 首页 | 首屏 +「都有些什么」五间屋(桌面)/ 金刚区 + 最新作品(手机)+ 自助渲染服务台(渲染机状态、价格实时读)+ 常用平台 | `content/site.js`(hero / boards / gallery / apps / universe / links / about) |
| `gallery.html` 画展 | 图片 / 视频 / 全景 / 动态壁纸,按时间排、可筛选(脱敏版只有一张占位) | `content/site.js` 的 gallery + media,`hd_cache/manifest.json`,`view_stats.json` |
| `tools.html` 工具与开源 | 开源 / 在线使用 / 闭源三行,按类型筛选 | apps |
| `universe.html` 金钻宇宙 | 星门开场 → 星系图 + 世界线档案 | universe(兜底 `assets/universe/config.js`) |
| `links.html` 平台入口 | 按分组列出,外链新窗口打开 | linkGroups + links |
| `about.html` 关于 | 名字由来 + 署名卡片 | about |
各页之间是普通链接(整页跳转)。旧的单页地址 `/#/板块`、`/#0001` 会被首页自动跳到新页面。页脚、「更多」面板里的群号和备案号读 `assets/site-info.js`。
**加一条世界线**:`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/` 一起上;**`assets/site-info.js` 换成正式服务器那份(真实群号 / 备案号),别用仓库里的占位覆盖**;`content/` 是线上数据,**别用仓库里的占位覆盖**(内容后台管它) |
| `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 缓存与版本号
- 门户各页引用 `assets/*.js|css?v=1`:改了哪个就把六个页面里它的 `?v=` 一起加 1。HTML 本身要 `no-cache`(nginx 片段里给 `*.html` 加了)。
- 门户星系图:改了 JS / CSS 要换版本号,**一起换**:`portal/universe.html` 里 `universe-page.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` 的那段不在仓库里)都没有端到端测过。
- 下单页里的链接是站点根路径(`/index.html`、`/order/`、`/assets/site-info.js`、`/fonts/…`),本地要从 `portal/` 起服务、再把 `order/` 放到 `/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 次开始冷却(账号那档放宽,免得别人故意输错把店主锁在门外)。
- 内容后台碰不到卡密 / 订单。