feat:系统框架

This commit is contained in:
wlx committed 2026-06-29 19:27:33 +08:00
commit c1f1b39e81
25 files changed
+7515

No files matched your search

+11
View File
@@ -0,0 +1,11 @@
.DS_Store
node_modules/
.env
.env.*
!.env.example
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.idea/
.vscode/*
!.vscode/extensions.json
+82
View File
@@ -0,0 +1,82 @@
# 模灵科技官网管理端前期设计
本目录用于承接 `mlkj-website` 官网与赛道页的管理端建设前期设计。设计基于当前同级项目 `mlkj-website` 的页面、静态资源、NestJS API、Prisma 数据模型和已有简版后台能力整理。
## 文档索引
| 文件 | 内容 |
| --- | --- |
| [docs/00-current-site-audit.md](docs/00-current-site-audit.md) | 当前官网项目审计、已有能力、缺口与设计约束 |
| [docs/01-prd.md](docs/01-prd.md) | 管理端 PRD、用户角色、功能范围、验收标准 |
| [docs/02-product-flow.md](docs/02-product-flow.md) | 产品流程图:内容发布、素材上传、作品管理、评选流程 |
| [docs/03-design-spec.md](docs/03-design-spec.md) | 管理端页面、交互、信息架构与权限设计 |
| [docs/04-system-architecture.md](docs/04-system-architecture.md) | 系统架构、模块划分、部署与安全设计 |
| [docs/05-er-diagram.md](docs/05-er-diagram.md) | E-R 图与核心实体关系 |
| [docs/06-database-schema.md](docs/06-database-schema.md) | 数据库字段设计与现有 Prisma 表扩展建议 |
| [docs/07-api-design.md](docs/07-api-design.md) | API 设计说明、接口分组、权限边界 |
| [docs/swagger/openapi.yaml](docs/swagger/openapi.yaml) | OpenAPI 3.0 Swagger 设计稿 |
| [docs/08-route-design.md](docs/08-route-design.md) | 管理端前端路由、页面状态和菜单结构 |
| [docs/09-development-plan.md](docs/09-development-plan.md) | 详细开发计划、阶段拆分、交付物与验收 |
| [docs/10-development-standards.md](docs/10-development-standards.md) | 前后端、数据库、接口、测试、协作开发规范 |
| [docs/11-development-requirements.md](docs/11-development-requirements.md) | 开发环境、质量、安全、性能、上线要求 |
| [docs/12-cloud-deployment.md](docs/12-cloud-deployment.md) | 云服务器、云数据库、OSS、CDN、安全与运维设计 |
## 管理端应用
当前目录已包含第一版管理端前端应用:
```text
app/
index.html
assets/admin-app.css
assets/admin-app.js
serve.mjs
```
本地启动:
```bash
cd ~/AI\ SoulMate/开发/mlkj-website-admin
npm run dev
```
默认访问:
```text
http://127.0.0.1:4173/
```
管理端会调用 `mlkj-website` 后端的 `/api/admin/*`。本地开发时请先启动后端:
```bash
cd ~/AI\ SoulMate/开发/mlkj-website
HOST=127.0.0.1 PORT=3001 ADMIN_INITIAL_USERNAME=admin ADMIN_INITIAL_PASSWORD=admin123 node backend/dist/main.js
```
静态构建:
```bash
npm run build
```
构建产物输出到:
```text
dist/
```
## 核心结论
1. 当前 `mlkj-website` 已有前台页面、NestJS 后端、Prisma 模型和一个极简 `admin.html` 管理页,可作为后续开发基础。
2. 现有后台已覆盖登录、控制台、作品、课程、咨询线索、文件登记,但官网文字内容、赛道页复杂区块、素材包、视频上传、评选打分尚未完整产品化。
3. 第一版管理端应优先解决运营高频问题:页面文案可编辑、图片和素材可上传、视频课程可发布、作品可维护、评委可打分、结果可汇总发布。
4. 技术上建议继续沿用现有 NestJS + Prisma + PostgreSQL + OSS 的方向,新增独立后台前端应用或替换当前 `frontend/public/admin.html` 为 Vite 管理端。
## 建议开发顺序
1. 完成后台基础工程:登录、JWT、RBAC、布局、文件上传。
2. 完成官网首页与赛道页内容区块管理:草稿、预览、发布。
3. 完成素材库、课程/视频、赛道资源包管理。
4. 完成作品管理:基础信息、图片、模型、附件、发布状态。
5. 完成作品评选:评审轮次、评委、指标、分配、打分、统计、获奖结果发布。
6. 前台页面逐步从静态 HTML/JSON 切换到 API 数据。
+485
View File
@@ -0,0 +1,485 @@
:root {
color-scheme: light;
--bg: #f5f7fb;
--panel: #ffffff;
--panel-soft: #f8fafc;
--text: #152033;
--muted: #687386;
--line: #dbe3ee;
--brand: #1b7f79;
--brand-strong: #0f5f5a;
--accent: #c9861b;
--danger: #c2413a;
--warning: #b7791f;
--success: #16835f;
--shadow: 0 14px 36px rgba(27, 39, 62, 0.08);
}
* {
box-sizing: border-box;
}
body {
margin: 0;
min-width: 1120px;
background: var(--bg);
color: var(--text);
font-family:
Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
font-size: 14px;
}
button,
input,
select,
textarea {
font: inherit;
}
button {
cursor: pointer;
}
.login-page {
min-height: 100vh;
display: grid;
place-items: center;
padding: 48px;
background:
linear-gradient(135deg, rgba(27, 127, 121, 0.12), transparent 38%),
linear-gradient(315deg, rgba(201, 134, 27, 0.12), transparent 42%),
var(--bg);
}
.login-panel {
width: 420px;
padding: 32px;
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
box-shadow: var(--shadow);
}
.login-panel h1 {
margin: 0;
font-size: 24px;
line-height: 1.2;
}
.login-panel p {
margin: 10px 0 24px;
color: var(--muted);
line-height: 1.7;
}
.field-stack {
display: grid;
gap: 16px;
}
.field {
display: grid;
gap: 7px;
}
.field label {
color: #364257;
font-weight: 650;
}
.field input,
.field select,
.field textarea {
width: 100%;
min-height: 40px;
border: 1px solid var(--line);
border-radius: 6px;
padding: 9px 11px;
color: var(--text);
background: #fff;
outline: none;
}
.field textarea {
min-height: 98px;
resize: vertical;
}
.field input:focus,
.field select:focus,
.field textarea:focus {
border-color: var(--brand);
box-shadow: 0 0 0 3px rgba(27, 127, 121, 0.12);
}
.btn {
min-height: 38px;
border: 1px solid var(--line);
border-radius: 6px;
padding: 8px 13px;
background: #fff;
color: var(--text);
font-weight: 650;
}
.btn:hover {
border-color: #b8c6d9;
}
.btn.primary {
border-color: var(--brand);
background: var(--brand);
color: #fff;
}
.btn.primary:hover {
border-color: var(--brand-strong);
background: var(--brand-strong);
}
.btn.danger {
border-color: rgba(194, 65, 58, 0.24);
color: var(--danger);
}
.btn.small {
min-height: 32px;
padding: 5px 10px;
font-size: 13px;
}
.shell {
min-height: 100vh;
display: grid;
grid-template-columns: 244px 1fr;
}
.sidebar {
position: sticky;
top: 0;
height: 100vh;
display: flex;
flex-direction: column;
border-right: 1px solid var(--line);
background: #101827;
color: #eef5ff;
}
.brand {
padding: 22px 20px 18px;
border-bottom: 1px solid rgba(255, 255, 255, 0.1);
}
.brand h1 {
margin: 0;
font-size: 20px;
line-height: 1.2;
}
.brand p {
margin: 7px 0 0;
color: rgba(238, 245, 255, 0.62);
line-height: 1.5;
}
.nav {
flex: 1;
padding: 14px 10px;
overflow-y: auto;
}
.nav-section {
margin: 13px 10px 7px;
color: rgba(238, 245, 255, 0.48);
font-size: 12px;
font-weight: 700;
}
.nav button {
width: 100%;
min-height: 38px;
border: 0;
border-radius: 6px;
margin: 2px 0;
padding: 8px 11px;
background: transparent;
color: rgba(238, 245, 255, 0.78);
text-align: left;
font-weight: 650;
}
.nav button:hover,
.nav button.active {
background: rgba(255, 255, 255, 0.1);
color: #fff;
}
.sidebar-footer {
padding: 14px;
border-top: 1px solid rgba(255, 255, 255, 0.1);
}
.sidebar-footer .btn {
width: 100%;
border-color: rgba(255, 255, 255, 0.18);
background: rgba(255, 255, 255, 0.08);
color: #fff;
}
.main {
min-width: 0;
padding: 24px;
}
.topbar {
display: flex;
align-items: flex-start;
justify-content: space-between;
gap: 24px;
margin-bottom: 18px;
}
.topbar h2 {
margin: 0;
font-size: 24px;
line-height: 1.2;
}
.topbar p {
margin: 7px 0 0;
color: var(--muted);
}
.user-chip {
display: flex;
align-items: center;
gap: 10px;
padding: 8px 10px;
border: 1px solid var(--line);
border-radius: 8px;
background: #fff;
}
.avatar {
width: 30px;
height: 30px;
display: grid;
place-items: center;
border-radius: 50%;
background: rgba(27, 127, 121, 0.12);
color: var(--brand-strong);
font-weight: 800;
}
.status-line {
min-height: 22px;
margin-top: 12px;
color: var(--muted);
line-height: 1.6;
}
.status-line.error {
color: var(--danger);
}
.status-line.success {
color: var(--success);
}
.kpis {
display: grid;
grid-template-columns: repeat(4, minmax(0, 1fr));
gap: 14px;
margin-bottom: 18px;
}
.kpi {
min-height: 104px;
padding: 18px;
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
box-shadow: 0 8px 18px rgba(27, 39, 62, 0.04);
}
.kpi .label {
color: var(--muted);
font-weight: 650;
}
.kpi .value {
margin-top: 13px;
font-size: 32px;
line-height: 1;
font-weight: 820;
}
.grid-two {
display: grid;
grid-template-columns: minmax(0, 1.4fr) minmax(360px, 0.8fr);
gap: 16px;
align-items: start;
}
.panel {
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
box-shadow: 0 8px 18px rgba(27, 39, 62, 0.04);
}
.panel-header {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
padding: 16px 18px;
border-bottom: 1px solid var(--line);
}
.panel-header h3 {
margin: 0;
font-size: 17px;
}
.panel-body {
padding: 18px;
}
.toolbar {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
margin-bottom: 14px;
}
.filters {
display: flex;
align-items: center;
gap: 8px;
}
.filters input,
.filters select {
min-height: 36px;
border: 1px solid var(--line);
border-radius: 6px;
padding: 7px 10px;
background: #fff;
}
.table-wrap {
overflow-x: auto;
}
.table {
width: 100%;
border-collapse: collapse;
}
.table th,
.table td {
border-bottom: 1px solid var(--line);
padding: 11px 10px;
text-align: left;
vertical-align: top;
}
.table th {
color: #4b586f;
font-size: 12px;
background: var(--panel-soft);
white-space: nowrap;
}
.table td {
line-height: 1.5;
}
.table tr:hover td {
background: #fbfcfe;
}
.muted {
color: var(--muted);
}
.badge {
display: inline-flex;
align-items: center;
min-height: 24px;
border-radius: 999px;
padding: 3px 9px;
background: #edf2f7;
color: #42526b;
font-size: 12px;
font-weight: 760;
white-space: nowrap;
}
.badge.published,
.badge.contacted {
background: rgba(22, 131, 95, 0.11);
color: var(--success);
}
.badge.draft,
.badge.pending {
background: rgba(183, 121, 31, 0.12);
color: var(--warning);
}
.badge.disabled,
.badge.closed,
.badge.archived {
background: rgba(104, 115, 134, 0.13);
color: #526071;
}
.empty {
padding: 34px 20px;
color: var(--muted);
text-align: center;
}
.form-actions {
display: flex;
gap: 10px;
justify-content: flex-end;
margin-top: 18px;
}
.section-grid {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 14px;
}
.content-card {
min-height: 132px;
padding: 16px;
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
}
.content-card h3 {
margin: 0 0 8px;
font-size: 16px;
}
.content-card p {
margin: 0;
color: var(--muted);
line-height: 1.6;
}
.notice {
padding: 12px 14px;
border: 1px solid rgba(27, 127, 121, 0.24);
border-radius: 8px;
background: rgba(27, 127, 121, 0.07);
color: #245d5a;
line-height: 1.7;
}
+774
View File
@@ -0,0 +1,774 @@
(function () {
"use strict";
var TOKEN_KEY = "mlkj-admin-token";
var DEFAULT_LOCAL_API = "http://127.0.0.1:3001/api";
function resolveApiBase() {
var saved = localStorage.getItem("mlkj-admin-api-base");
if (saved) return saved.replace(/\/$/, "");
if (location.protocol === "file:") return DEFAULT_LOCAL_API;
if (["4173", "5173", "8081"].indexOf(location.port) !== -1) return DEFAULT_LOCAL_API;
return "/api";
}
var state = {
apiBase: resolveApiBase(),
token: localStorage.getItem(TOKEN_KEY) || "",
user: null,
view: "dashboard",
loading: false,
message: "",
messageType: "",
dashboard: null,
works: [],
courses: [],
files: [],
inquiries: [],
editingWork: null,
editingCourse: null,
filters: {
worksKeyword: "",
worksStatus: "",
coursesKeyword: "",
coursesStatus: "",
inquiriesStatus: "",
},
};
var app = document.getElementById("app");
var menus = [
{ type: "section", label: "总览" },
{ key: "dashboard", label: "控制台", permission: "dashboard:read" },
{ type: "section", label: "内容" },
{ key: "site", label: "官网内容", permission: "site:read" },
{ key: "competition", label: "赛道内容", permission: "competition:read" },
{ key: "files", label: "素材库", permission: "file:read" },
{ type: "section", label: "运营" },
{ key: "works", label: "作品管理", permission: "work:read" },
{ key: "courses", label: "视频/课程", permission: "course:read" },
{ key: "evaluation", label: "作品评选", permission: "evaluation:manage" },
{ key: "inquiries", label: "咨询线索", permission: "inquiry:read" },
];
function escapeHtml(value) {
return String(value == null ? "" : value)
.replace(/&/g, "&")
.replace(/</g, "&lt;")
.replace(/>/g, "&gt;")
.replace(/"/g, "&quot;");
}
function hasPermission(permission) {
if (!permission) return true;
var permissions = (state.user && state.user.permissions) || [];
return permissions.indexOf(permission) !== -1;
}
function setMessage(message, type) {
state.message = message || "";
state.messageType = type || "";
}
function getHeaders(extra) {
var headers = Object.assign({ "Content-Type": "application/json" }, extra || {});
if (state.token) headers.Authorization = "Bearer " + state.token;
return headers;
}
async function request(path, options) {
var response = await fetch(state.apiBase + path, Object.assign({}, options || {}, { headers: getHeaders(options && options.headers) }));
var body = await response.json().catch(function () {
return {};
});
if (response.status === 401) {
logout(false);
throw new Error("登录已过期,请重新登录");
}
if (!response.ok || body.code !== 0) {
throw new Error(body.message || body.error || "请求失败:" + response.status);
}
return body.data;
}
function getFormData(form) {
return Object.fromEntries(new FormData(form).entries());
}
function field(name, label, value, type) {
return (
'<div class="field">' +
'<label for="' +
name +
'">' +
label +
"</label>" +
'<input id="' +
name +
'" name="' +
name +
'" type="' +
(type || "text") +
'" value="' +
escapeHtml(value || "") +
'" />' +
"</div>"
);
}
function textarea(name, label, value) {
return (
'<div class="field">' +
'<label for="' +
name +
'">' +
label +
"</label>" +
'<textarea id="' +
name +
'" name="' +
name +
'">' +
escapeHtml(value || "") +
"</textarea>" +
"</div>"
);
}
function select(name, label, value, options) {
return (
'<div class="field">' +
'<label for="' +
name +
'">' +
label +
"</label>" +
'<select id="' +
name +
'" name="' +
name +
'">' +
options
.map(function (item) {
return '<option value="' + item.value + '" ' + (item.value === value ? "selected" : "") + ">" + item.label + "</option>";
})
.join("") +
"</select>" +
"</div>"
);
}
function badge(status) {
return '<span class="badge ' + escapeHtml(status || "") + '">' + escapeHtml(status || "-") + "</span>";
}
function pageTitle() {
var item = menus.find(function (menu) {
return menu.key === state.view;
});
return item ? item.label : "管理端";
}
function renderLogin() {
app.innerHTML =
'<main class="login-page">' +
'<section class="login-panel">' +
"<h1>模灵科技管理端</h1>" +
"<p>管理公司官网、赛道页、作品、课程、素材和评选流程。</p>" +
'<form id="login-form" class="field-stack">' +
field("apiBase", "API 地址", state.apiBase) +
field("username", "账号", "admin") +
field("password", "密码", "", "password") +
'<button class="btn primary" type="submit">登录</button>' +
(state.message ? '<div class="status-line error">' + escapeHtml(state.message) + "</div>" : "") +
"</form>" +
"</section>" +
"</main>";
document.getElementById("login-form").addEventListener("submit", async function (event) {
event.preventDefault();
var data = getFormData(event.currentTarget);
state.apiBase = data.apiBase.replace(/\/$/, "");
localStorage.setItem("mlkj-admin-api-base", state.apiBase);
state.loading = true;
setMessage("");
renderLogin();
try {
var result = await request("/admin/auth/login", {
method: "POST",
body: JSON.stringify({ username: data.username, password: data.password }),
});
state.token = result.token || result.accessToken;
localStorage.setItem(TOKEN_KEY, state.token);
state.user = {
username: result.username,
displayName: result.displayName || result.username,
roles: result.roles || [],
permissions: result.permissions || [],
};
state.view = "dashboard";
await refreshView();
} catch (error) {
state.loading = false;
setMessage(error.message, "error");
renderLogin();
}
});
}
async function loadMe() {
if (!state.token) return null;
state.user = await request("/admin/me");
return state.user;
}
async function loadDashboard() {
state.dashboard = await request("/admin/dashboard");
}
async function loadWorks() {
var params = new URLSearchParams({ page: "1", pageSize: "50" });
if (state.filters.worksKeyword) params.set("keyword", state.filters.worksKeyword);
if (state.filters.worksStatus) params.set("status", state.filters.worksStatus);
var result = await request("/admin/works?" + params.toString());
state.works = result.list || [];
}
async function loadCourses() {
var params = new URLSearchParams({ page: "1", pageSize: "50" });
if (state.filters.coursesKeyword) params.set("keyword", state.filters.coursesKeyword);
if (state.filters.coursesStatus) params.set("status", state.filters.coursesStatus);
var result = await request("/admin/courses?" + params.toString());
state.courses = result.list || [];
}
async function loadFiles() {
state.files = await request("/admin/files");
}
async function loadInquiries() {
var params = new URLSearchParams({ page: "1", pageSize: "50" });
if (state.filters.inquiriesStatus) params.set("status", state.filters.inquiriesStatus);
var result = await request("/admin/inquiries?" + params.toString());
state.inquiries = result.list || [];
}
async function refreshView() {
try {
state.loading = true;
if (!state.user && state.token) await loadMe();
if (state.view === "dashboard") await loadDashboard();
if (state.view === "works") await loadWorks();
if (state.view === "courses") await loadCourses();
if (state.view === "files") await loadFiles();
if (state.view === "inquiries") await loadInquiries();
setMessage("");
} catch (error) {
setMessage(error.message, "error");
} finally {
state.loading = false;
render();
}
}
function renderShell(content) {
var nav = menus
.map(function (item) {
if (item.type === "section") return '<div class="nav-section">' + item.label + "</div>";
if (!hasPermission(item.permission)) return "";
return (
'<button type="button" data-view="' +
item.key +
'" class="' +
(state.view === item.key ? "active" : "") +
'">' +
item.label +
"</button>"
);
})
.join("");
var user = state.user || {};
app.innerHTML =
'<div class="shell">' +
'<aside class="sidebar">' +
'<div class="brand"><h1>模灵科技</h1><p>官网与赛道页管理端</p></div>' +
'<nav class="nav">' +
nav +
"</nav>" +
'<div class="sidebar-footer"><button class="btn" id="logout-btn" type="button">退出登录</button></div>' +
"</aside>" +
'<main class="main">' +
'<div class="topbar">' +
"<div><h2>" +
pageTitle() +
"</h2><p>API:" +
escapeHtml(state.apiBase) +
"</p></div>" +
'<div class="user-chip"><div class="avatar">' +
escapeHtml((user.displayName || user.username || "管").slice(0, 1)) +
'</div><div><strong>' +
escapeHtml(user.displayName || user.username || "管理员") +
'</strong><div class="muted">' +
escapeHtml((user.roles || []).join(", ") || "admin") +
"</div></div></div>" +
"</div>" +
(state.message ? '<div class="status-line ' + state.messageType + '">' + escapeHtml(state.message) + "</div>" : "") +
content +
"</main>" +
"</div>";
document.querySelectorAll("[data-view]").forEach(function (button) {
button.addEventListener("click", function () {
state.view = button.getAttribute("data-view");
setMessage("");
refreshView();
});
});
document.getElementById("logout-btn").addEventListener("click", function () {
logout(true);
});
}
function renderDashboard() {
var data = state.dashboard || {};
renderShell(
'<section class="kpis">' +
kpi("作品总数", data.worksCount) +
kpi("已发布作品", data.publishedWorks) +
kpi("课程/视频", data.coursesCount) +
kpi("咨询线索", data.inquiriesCount) +
"</section>" +
'<section class="panel"><div class="panel-header"><h3>建设进度</h3></div><div class="panel-body">' +
'<div class="notice">当前管理端前端已接入登录、权限、控制台、作品、课程、文件库和线索接口。下一步将继续补官网内容、赛道内容、OSS 直传和作品评选。</div>' +
"</div></section>",
);
}
function kpi(label, value) {
return '<div class="kpi"><div class="label">' + label + '</div><div class="value">' + (value == null ? "-" : value) + "</div></div>";
}
function renderWorks() {
var work = state.editingWork || {};
renderShell(
'<div class="grid-two">' +
'<section class="panel">' +
'<div class="panel-header"><h3>作品列表</h3><button class="btn primary small" id="new-work-btn" type="button">新建作品</button></div>' +
'<div class="panel-body">' +
renderWorksToolbar() +
'<div class="table-wrap"><table class="table"><thead><tr><th>编号</th><th>作品</th><th>作者/学校</th><th>状态</th><th>操作</th></tr></thead><tbody>' +
(state.works.length ? state.works.map(renderWorkRow).join("") : '<tr><td colspan="5"><div class="empty">暂无作品</div></td></tr>') +
"</tbody></table></div></div></section>" +
'<section class="panel"><div class="panel-header"><h3>' +
(work.id ? "编辑作品" : "新建作品") +
'</h3></div><div class="panel-body">' +
renderWorkForm(work) +
"</div></section>" +
"</div>",
);
bindWorksEvents();
}
function renderWorksToolbar() {
return (
'<div class="toolbar"><div class="filters">' +
'<input id="works-keyword" placeholder="搜索标题、编号、作者、学校" value="' +
escapeHtml(state.filters.worksKeyword) +
'" />' +
'<select id="works-status"><option value="">全部状态</option>' +
statusOptions(state.filters.worksStatus) +
"</select>" +
'<button class="btn small" id="works-search-btn" type="button">筛选</button>' +
'</div><button class="btn small" id="works-reload-btn" type="button">刷新</button></div>'
);
}
function renderWorkRow(item) {
var id = item.id || item.workNo;
return (
"<tr><td>" +
escapeHtml(item.workNo || id) +
"</td><td><strong>" +
escapeHtml(item.title) +
'</strong><br /><span class="muted">' +
escapeHtml(item.category || "") +
"</span></td><td>" +
escapeHtml(item.authorName || item.author || "") +
'<br /><span class="muted">' +
escapeHtml(item.school || "") +
"</span></td><td>" +
badge(item.status || "draft") +
'</td><td><button class="btn small" data-edit-work="' +
escapeHtml(id) +
'" type="button">编辑</button></td></tr>'
);
}
function renderWorkForm(work) {
return (
'<form id="work-form" class="field-stack">' +
field("workNo", "作品编号", work.workNo || work.id || "") +
field("title", "作品标题", work.title || "") +
field("category", "分类", work.category || "") +
field("direction", "方向", work.direction || "") +
field("authorName", "作者/团队", work.authorName || work.author || "") +
field("school", "学校/机构", work.school || "") +
field("coverUrl", "封面图 URL", work.coverUrl || "") +
field("modelUrl", "3D 模型 URL", work.modelUrl || "") +
textarea("summary", "作品概述", work.summary || "") +
textarea("aigcSummary", "AIGC 创作流程", work.aigcSummary || "") +
textarea("prompt", "提示词", work.prompt || "") +
field("voteCount", "点赞数", work.voteCount || work.votes || 0, "number") +
field("sortOrder", "排序", work.sortOrder || 0, "number") +
select("status", "发布状态", work.status || "published", publishStatusOptions()) +
'<div class="form-actions"><button class="btn" id="reset-work-btn" type="button">清空</button><button class="btn primary" type="submit">保存作品</button></div>' +
"</form>"
);
}
function bindWorksEvents() {
document.getElementById("new-work-btn").addEventListener("click", function () {
state.editingWork = null;
renderWorks();
});
document.getElementById("works-reload-btn").addEventListener("click", function () {
refreshView();
});
document.getElementById("works-search-btn").addEventListener("click", function () {
state.filters.worksKeyword = document.getElementById("works-keyword").value.trim();
state.filters.worksStatus = document.getElementById("works-status").value;
refreshView();
});
document.querySelectorAll("[data-edit-work]").forEach(function (button) {
button.addEventListener("click", async function () {
try {
state.editingWork = await request("/admin/works/" + encodeURIComponent(button.getAttribute("data-edit-work")));
renderWorks();
} catch (error) {
setMessage(error.message, "error");
renderWorks();
}
});
});
document.getElementById("reset-work-btn").addEventListener("click", function () {
state.editingWork = null;
renderWorks();
});
document.getElementById("work-form").addEventListener("submit", submitWorkForm);
}
async function submitWorkForm(event) {
event.preventDefault();
var data = normalizeNumeric(getFormData(event.currentTarget), ["voteCount", "sortOrder"]);
var id = state.editingWork && (state.editingWork.id || state.editingWork.workNo);
try {
await request(id ? "/admin/works/" + encodeURIComponent(id) : "/admin/works", {
method: id ? "PATCH" : "POST",
body: JSON.stringify(data),
});
state.editingWork = null;
setMessage("作品已保存", "success");
await loadWorks();
renderWorks();
} catch (error) {
setMessage(error.message, "error");
renderWorks();
}
}
function renderCourses() {
var course = state.editingCourse || {};
renderShell(
'<div class="grid-two">' +
'<section class="panel"><div class="panel-header"><h3>课程列表</h3><button class="btn primary small" id="new-course-btn" type="button">新建课程</button></div><div class="panel-body">' +
renderCoursesToolbar() +
'<div class="table-wrap"><table class="table"><thead><tr><th>编号</th><th>课程</th><th>类型</th><th>状态</th><th>操作</th></tr></thead><tbody>' +
(state.courses.length ? state.courses.map(renderCourseRow).join("") : '<tr><td colspan="5"><div class="empty">暂无课程</div></td></tr>') +
"</tbody></table></div></div></section>" +
'<section class="panel"><div class="panel-header"><h3>' +
(course.id ? "编辑课程" : "新建课程") +
'</h3></div><div class="panel-body">' +
renderCourseForm(course) +
"</div></section>" +
"</div>",
);
bindCoursesEvents();
}
function renderCoursesToolbar() {
return (
'<div class="toolbar"><div class="filters">' +
'<input id="courses-keyword" placeholder="搜索标题、编号、合作方" value="' +
escapeHtml(state.filters.coursesKeyword) +
'" />' +
'<select id="courses-status"><option value="">全部状态</option>' +
statusOptions(state.filters.coursesStatus) +
"</select>" +
'<button class="btn small" id="courses-search-btn" type="button">筛选</button>' +
'</div><button class="btn small" id="courses-reload-btn" type="button">刷新</button></div>'
);
}
function renderCourseRow(item) {
var id = item.id || item.courseNo;
return (
"<tr><td>" +
escapeHtml(item.courseNo || id) +
"</td><td><strong>" +
escapeHtml(item.title) +
'</strong><br /><span class="muted">' +
escapeHtml(item.partner || "") +
"</span></td><td>" +
escapeHtml(item.type || "") +
"</td><td>" +
badge(item.status || "draft") +
'</td><td><button class="btn small" data-edit-course="' +
escapeHtml(id) +
'" type="button">编辑</button></td></tr>'
);
}
function renderCourseForm(course) {
return (
'<form id="course-form" class="field-stack">' +
field("courseNo", "课程编号", course.courseNo || course.id || "") +
select("type", "课程类型", course.type || "training", [
{ value: "roadshow", label: "宣讲回放" },
{ value: "training", label: "赛道培训" },
]) +
field("title", "标题", course.title || "") +
textarea("summary", "简介", course.summary || "") +
textarea("description", "详情", course.description || "") +
field("coverUrl", "封面图 URL", course.coverUrl || "") +
field("videoUrl", "视频 URL", course.videoUrl || "") +
field("partner", "合作方", course.partner || "") +
field("durationText", "时长", course.durationText || "") +
field("sortOrder", "排序", course.sortOrder || 0, "number") +
select("status", "发布状态", course.status || "published", publishStatusOptions()) +
'<div class="form-actions"><button class="btn" id="reset-course-btn" type="button">清空</button><button class="btn primary" type="submit">保存课程</button></div>' +
"</form>"
);
}
function bindCoursesEvents() {
document.getElementById("new-course-btn").addEventListener("click", function () {
state.editingCourse = null;
renderCourses();
});
document.getElementById("courses-reload-btn").addEventListener("click", function () {
refreshView();
});
document.getElementById("courses-search-btn").addEventListener("click", function () {
state.filters.coursesKeyword = document.getElementById("courses-keyword").value.trim();
state.filters.coursesStatus = document.getElementById("courses-status").value;
refreshView();
});
document.querySelectorAll("[data-edit-course]").forEach(function (button) {
button.addEventListener("click", async function () {
try {
state.editingCourse = await request("/admin/courses/" + encodeURIComponent(button.getAttribute("data-edit-course")));
renderCourses();
} catch (error) {
setMessage(error.message, "error");
renderCourses();
}
});
});
document.getElementById("reset-course-btn").addEventListener("click", function () {
state.editingCourse = null;
renderCourses();
});
document.getElementById("course-form").addEventListener("submit", submitCourseForm);
}
async function submitCourseForm(event) {
event.preventDefault();
var data = normalizeNumeric(getFormData(event.currentTarget), ["sortOrder"]);
var id = state.editingCourse && (state.editingCourse.id || state.editingCourse.courseNo);
try {
await request(id ? "/admin/courses/" + encodeURIComponent(id) : "/admin/courses", {
method: id ? "PATCH" : "POST",
body: JSON.stringify(data),
});
state.editingCourse = null;
setMessage("课程已保存", "success");
await loadCourses();
renderCourses();
} catch (error) {
setMessage(error.message, "error");
renderCourses();
}
}
function renderFiles() {
renderShell(
'<section class="panel"><div class="panel-header"><h3>素材库</h3><button class="btn small" id="files-reload-btn" type="button">刷新</button></div><div class="panel-body">' +
'<div class="notice">当前版本先接入文件记录列表。下一步会按云部署设计接入 OSS 临时凭证直传。</div>' +
'<div class="table-wrap" style="margin-top:14px;"><table class="table"><thead><tr><th>文件名</th><th>类型</th><th>大小</th><th>存储</th><th>时间</th></tr></thead><tbody>' +
(state.files.length ? state.files.map(renderFileRow).join("") : '<tr><td colspan="5"><div class="empty">暂无文件</div></td></tr>') +
"</tbody></table></div></div></section>",
);
document.getElementById("files-reload-btn").addEventListener("click", refreshView);
}
function renderFileRow(item) {
return (
"<tr><td><strong>" +
escapeHtml(item.originalName) +
'</strong><br /><span class="muted">' +
escapeHtml(item.url || item.fileKey || "") +
"</span></td><td>" +
escapeHtml(item.mimeType || "") +
"</td><td>" +
escapeHtml(item.size || "") +
"</td><td>" +
escapeHtml(item.storageProvider || "") +
"</td><td>" +
escapeHtml(item.createdAt || "") +
"</td></tr>"
);
}
function renderInquiries() {
renderShell(
'<section class="panel"><div class="panel-header"><h3>咨询线索</h3><button class="btn small" id="inquiries-reload-btn" type="button">刷新</button></div><div class="panel-body">' +
'<div class="filters" style="margin-bottom:14px;"><select id="inquiries-status"><option value="">全部状态</option><option value="pending">待联系</option><option value="contacted">已联系</option><option value="closed">已关闭</option></select><button class="btn small" id="inquiries-search-btn" type="button">筛选</button></div>' +
'<div class="table-wrap"><table class="table"><thead><tr><th>机构</th><th>联系人</th><th>电话</th><th>状态</th><th>时间</th></tr></thead><tbody>' +
(state.inquiries.length ? state.inquiries.map(renderInquiryRow).join("") : '<tr><td colspan="5"><div class="empty">暂无线索</div></td></tr>') +
"</tbody></table></div></div></section>",
);
document.getElementById("inquiries-status").value = state.filters.inquiriesStatus;
document.getElementById("inquiries-reload-btn").addEventListener("click", refreshView);
document.getElementById("inquiries-search-btn").addEventListener("click", function () {
state.filters.inquiriesStatus = document.getElementById("inquiries-status").value;
refreshView();
});
}
function renderInquiryRow(item) {
return (
"<tr><td><strong>" +
escapeHtml(item.organization) +
'</strong><br /><span class="muted">' +
escapeHtml(item.role || "") +
"</span></td><td>" +
escapeHtml(item.contactName || "") +
"</td><td>" +
escapeHtml(item.phone || "") +
"</td><td>" +
badge(item.status || "pending") +
"</td><td>" +
escapeHtml(item.createdAt || "") +
"</td></tr>"
);
}
function renderPlaceholder(title, desc, items) {
renderShell(
'<section class="panel"><div class="panel-header"><h3>' +
title +
'</h3></div><div class="panel-body"><p class="muted">' +
desc +
'</p><div class="section-grid" style="margin-top:16px;">' +
items
.map(function (item) {
return '<article class="content-card"><h3>' + item.title + '</h3><p>' + item.desc + "</p></article>";
})
.join("") +
"</div></div></section>",
);
}
function renderSite() {
renderPlaceholder("官网内容", "下一阶段接入站点配置、首页区块、案例和合作咨询文案。", [
{ title: "站点配置", desc: "公司名、SEO、导航、Logo、备案和联系方式。" },
{ title: "首页 Hero", desc: "标题、副标题、按钮、背景图和产品说明。" },
{ title: "业务与案例", desc: "业务版图、产品矩阵、解决方案、客户案例。" },
{ title: "发布流程", desc: "草稿、预览、发布、下架和历史版本。" },
]);
}
function renderCompetition() {
renderPlaceholder("赛道内容", "下一阶段接入赛道基础信息、赛程、赛事说明、资源包和合作伙伴。", [
{ title: "赛道基础", desc: "标题、副标题、主题、报名入口、创作入口和 Hero 图。" },
{ title: "赛程安排", desc: "报名、提交、复评、决赛等节点维护。" },
{ title: "赛事说明", desc: "奖项设置、设计要求、参赛须知和提交材料。" },
{ title: "参考资源", desc: "PDF、ZIP、图片、链接和开放下载时间。" },
]);
}
function renderEvaluation() {
renderPlaceholder("作品评选", "下一阶段接入评审轮次、评分指标、评委分配、在线评分和结果发布。", [
{ title: "评审轮次", desc: "初评、复评、决赛配置和锁定。" },
{ title: "评分指标", desc: "指标、满分、权重和排序。" },
{ title: "评委任务", desc: "分配作品给评委,追踪完成进度。" },
{ title: "结果汇总", desc: "专家分、公众分、最终分、排名和奖项。" },
]);
}
function statusOptions(value) {
return publishStatusOptions()
.map(function (item) {
return '<option value="' + item.value + '" ' + (item.value === value ? "selected" : "") + ">" + item.label + "</option>";
})
.join("");
}
function publishStatusOptions() {
return [
{ value: "draft", label: "草稿" },
{ value: "published", label: "已发布" },
{ value: "disabled", label: "已下架" },
{ value: "archived", label: "已归档" },
];
}
function normalizeNumeric(data, keys) {
keys.forEach(function (key) {
if (data[key] !== "") data[key] = Number(data[key]);
else delete data[key];
});
return data;
}
function logout(showMessage) {
localStorage.removeItem(TOKEN_KEY);
state.token = "";
state.user = null;
state.dashboard = null;
state.works = [];
state.courses = [];
state.files = [];
state.inquiries = [];
if (showMessage) setMessage("已退出登录", "");
renderLogin();
}
function render() {
if (!state.token) {
renderLogin();
return;
}
if (state.view === "dashboard") return renderDashboard();
if (state.view === "site") return renderSite();
if (state.view === "competition") return renderCompetition();
if (state.view === "files") return renderFiles();
if (state.view === "works") return renderWorks();
if (state.view === "courses") return renderCourses();
if (state.view === "evaluation") return renderEvaluation();
if (state.view === "inquiries") return renderInquiries();
renderDashboard();
}
async function boot() {
if (!state.token) {
renderLogin();
return;
}
await refreshView();
}
boot();
})();
+14
View File
@@ -0,0 +1,14 @@
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>模灵科技官网管理端</title>
<meta name="description" content="模灵科技官网与赛道页内容管理端" />
<link rel="stylesheet" href="./assets/admin-app.css" />
</head>
<body>
<div id="app"></div>
<script src="./assets/admin-app.js"></script>
</body>
</html>
+62
View File
@@ -0,0 +1,62 @@
import { createServer } from 'node:http'
import { readFile } from 'node:fs/promises'
import { extname, join, normalize } from 'node:path'
import { fileURLToPath } from 'node:url'
const root = fileURLToPath(new URL('.', import.meta.url))
const port = Number(process.env.PORT || 4173)
const host = process.env.HOST || '127.0.0.1'
const types = {
'.html': 'text/html; charset=utf-8',
'.js': 'text/javascript; charset=utf-8',
'.css': 'text/css; charset=utf-8',
'.json': 'application/json; charset=utf-8',
'.png': 'image/png',
'.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg',
'.svg': 'image/svg+xml',
'.ico': 'image/x-icon',
}
function resolvePath(url) {
const pathname = decodeURIComponent((url || '/').split('?')[0])
const filePath = normalize(join(root, pathname === '/' ? 'index.html' : pathname))
if (!filePath.startsWith(root)) return null
return filePath
}
const server = createServer(async (request, response) => {
let filePath = resolvePath(request.url)
if (!filePath) {
response.writeHead(403)
response.end('Forbidden')
return
}
try {
const body = await readFile(filePath)
response.writeHead(200, {
'Content-Type': types[extname(filePath)] || 'application/octet-stream',
'Cache-Control': 'no-store',
})
response.end(body)
} catch {
try {
filePath = join(root, 'index.html')
const body = await readFile(filePath)
response.writeHead(200, {
'Content-Type': 'text/html; charset=utf-8',
'Cache-Control': 'no-store',
})
response.end(body)
} catch {
response.writeHead(404)
response.end('Not found')
}
}
})
server.listen(port, host, () => {
console.log(`MLKJ admin app: http://${host}:${port}/`)
})
+485
View File
@@ -0,0 +1,485 @@
:root {
color-scheme: light;
--bg: #f5f7fb;
--panel: #ffffff;
--panel-soft: #f8fafc;
--text: #152033;
--muted: #687386;
--line: #dbe3ee;
--brand: #1b7f79;
--brand-strong: #0f5f5a;
--accent: #c9861b;
--danger: #c2413a;
--warning: #b7791f;
--success: #16835f;
--shadow: 0 14px 36px rgba(27, 39, 62, 0.08);
}
* {
box-sizing: border-box;
}
body {
margin: 0;
min-width: 1120px;
background: var(--bg);
color: var(--text);
font-family:
Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
font-size: 14px;
}
button,
input,
select,
textarea {
font: inherit;
}
button {
cursor: pointer;
}
.login-page {
min-height: 100vh;
display: grid;
place-items: center;
padding: 48px;
background:
linear-gradient(135deg, rgba(27, 127, 121, 0.12), transparent 38%),
linear-gradient(315deg, rgba(201, 134, 27, 0.12), transparent 42%),
var(--bg);
}
.login-panel {
width: 420px;
padding: 32px;
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
box-shadow: var(--shadow);
}
.login-panel h1 {
margin: 0;
font-size: 24px;
line-height: 1.2;
}
.login-panel p {
margin: 10px 0 24px;
color: var(--muted);
line-height: 1.7;
}
.field-stack {
display: grid;
gap: 16px;
}
.field {
display: grid;
gap: 7px;
}
.field label {
color: #364257;
font-weight: 650;
}
.field input,
.field select,
.field textarea {
width: 100%;
min-height: 40px;
border: 1px solid var(--line);
border-radius: 6px;
padding: 9px 11px;
color: var(--text);
background: #fff;
outline: none;
}
.field textarea {
min-height: 98px;
resize: vertical;
}
.field input:focus,
.field select:focus,
.field textarea:focus {
border-color: var(--brand);
box-shadow: 0 0 0 3px rgba(27, 127, 121, 0.12);
}
.btn {
min-height: 38px;
border: 1px solid var(--line);
border-radius: 6px;
padding: 8px 13px;
background: #fff;
color: var(--text);
font-weight: 650;
}
.btn:hover {
border-color: #b8c6d9;
}
.btn.primary {
border-color: var(--brand);
background: var(--brand);
color: #fff;
}
.btn.primary:hover {
border-color: var(--brand-strong);
background: var(--brand-strong);
}
.btn.danger {
border-color: rgba(194, 65, 58, 0.24);
color: var(--danger);
}
.btn.small {
min-height: 32px;
padding: 5px 10px;
font-size: 13px;
}
.shell {
min-height: 100vh;
display: grid;
grid-template-columns: 244px 1fr;
}
.sidebar {
position: sticky;
top: 0;
height: 100vh;
display: flex;
flex-direction: column;
border-right: 1px solid var(--line);
background: #101827;
color: #eef5ff;
}
.brand {
padding: 22px 20px 18px;
border-bottom: 1px solid rgba(255, 255, 255, 0.1);
}
.brand h1 {
margin: 0;
font-size: 20px;
line-height: 1.2;
}
.brand p {
margin: 7px 0 0;
color: rgba(238, 245, 255, 0.62);
line-height: 1.5;
}
.nav {
flex: 1;
padding: 14px 10px;
overflow-y: auto;
}
.nav-section {
margin: 13px 10px 7px;
color: rgba(238, 245, 255, 0.48);
font-size: 12px;
font-weight: 700;
}
.nav button {
width: 100%;
min-height: 38px;
border: 0;
border-radius: 6px;
margin: 2px 0;
padding: 8px 11px;
background: transparent;
color: rgba(238, 245, 255, 0.78);
text-align: left;
font-weight: 650;
}
.nav button:hover,
.nav button.active {
background: rgba(255, 255, 255, 0.1);
color: #fff;
}
.sidebar-footer {
padding: 14px;
border-top: 1px solid rgba(255, 255, 255, 0.1);
}
.sidebar-footer .btn {
width: 100%;
border-color: rgba(255, 255, 255, 0.18);
background: rgba(255, 255, 255, 0.08);
color: #fff;
}
.main {
min-width: 0;
padding: 24px;
}
.topbar {
display: flex;
align-items: flex-start;
justify-content: space-between;
gap: 24px;
margin-bottom: 18px;
}
.topbar h2 {
margin: 0;
font-size: 24px;
line-height: 1.2;
}
.topbar p {
margin: 7px 0 0;
color: var(--muted);
}
.user-chip {
display: flex;
align-items: center;
gap: 10px;
padding: 8px 10px;
border: 1px solid var(--line);
border-radius: 8px;
background: #fff;
}
.avatar {
width: 30px;
height: 30px;
display: grid;
place-items: center;
border-radius: 50%;
background: rgba(27, 127, 121, 0.12);
color: var(--brand-strong);
font-weight: 800;
}
.status-line {
min-height: 22px;
margin-top: 12px;
color: var(--muted);
line-height: 1.6;
}
.status-line.error {
color: var(--danger);
}
.status-line.success {
color: var(--success);
}
.kpis {
display: grid;
grid-template-columns: repeat(4, minmax(0, 1fr));
gap: 14px;
margin-bottom: 18px;
}
.kpi {
min-height: 104px;
padding: 18px;
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
box-shadow: 0 8px 18px rgba(27, 39, 62, 0.04);
}
.kpi .label {
color: var(--muted);
font-weight: 650;
}
.kpi .value {
margin-top: 13px;
font-size: 32px;
line-height: 1;
font-weight: 820;
}
.grid-two {
display: grid;
grid-template-columns: minmax(0, 1.4fr) minmax(360px, 0.8fr);
gap: 16px;
align-items: start;
}
.panel {
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
box-shadow: 0 8px 18px rgba(27, 39, 62, 0.04);
}
.panel-header {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
padding: 16px 18px;
border-bottom: 1px solid var(--line);
}
.panel-header h3 {
margin: 0;
font-size: 17px;
}
.panel-body {
padding: 18px;
}
.toolbar {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
margin-bottom: 14px;
}
.filters {
display: flex;
align-items: center;
gap: 8px;
}
.filters input,
.filters select {
min-height: 36px;
border: 1px solid var(--line);
border-radius: 6px;
padding: 7px 10px;
background: #fff;
}
.table-wrap {
overflow-x: auto;
}
.table {
width: 100%;
border-collapse: collapse;
}
.table th,
.table td {
border-bottom: 1px solid var(--line);
padding: 11px 10px;
text-align: left;
vertical-align: top;
}
.table th {
color: #4b586f;
font-size: 12px;
background: var(--panel-soft);
white-space: nowrap;
}
.table td {
line-height: 1.5;
}
.table tr:hover td {
background: #fbfcfe;
}
.muted {
color: var(--muted);
}
.badge {
display: inline-flex;
align-items: center;
min-height: 24px;
border-radius: 999px;
padding: 3px 9px;
background: #edf2f7;
color: #42526b;
font-size: 12px;
font-weight: 760;
white-space: nowrap;
}
.badge.published,
.badge.contacted {
background: rgba(22, 131, 95, 0.11);
color: var(--success);
}
.badge.draft,
.badge.pending {
background: rgba(183, 121, 31, 0.12);
color: var(--warning);
}
.badge.disabled,
.badge.closed,
.badge.archived {
background: rgba(104, 115, 134, 0.13);
color: #526071;
}
.empty {
padding: 34px 20px;
color: var(--muted);
text-align: center;
}
.form-actions {
display: flex;
gap: 10px;
justify-content: flex-end;
margin-top: 18px;
}
.section-grid {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 14px;
}
.content-card {
min-height: 132px;
padding: 16px;
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
}
.content-card h3 {
margin: 0 0 8px;
font-size: 16px;
}
.content-card p {
margin: 0;
color: var(--muted);
line-height: 1.6;
}
.notice {
padding: 12px 14px;
border: 1px solid rgba(27, 127, 121, 0.24);
border-radius: 8px;
background: rgba(27, 127, 121, 0.07);
color: #245d5a;
line-height: 1.7;
}
+774
View File
@@ -0,0 +1,774 @@
(function () {
"use strict";
var TOKEN_KEY = "mlkj-admin-token";
var DEFAULT_LOCAL_API = "http://127.0.0.1:3001/api";
function resolveApiBase() {
var saved = localStorage.getItem("mlkj-admin-api-base");
if (saved) return saved.replace(/\/$/, "");
if (location.protocol === "file:") return DEFAULT_LOCAL_API;
if (["4173", "5173", "8081"].indexOf(location.port) !== -1) return DEFAULT_LOCAL_API;
return "/api";
}
var state = {
apiBase: resolveApiBase(),
token: localStorage.getItem(TOKEN_KEY) || "",
user: null,
view: "dashboard",
loading: false,
message: "",
messageType: "",
dashboard: null,
works: [],
courses: [],
files: [],
inquiries: [],
editingWork: null,
editingCourse: null,
filters: {
worksKeyword: "",
worksStatus: "",
coursesKeyword: "",
coursesStatus: "",
inquiriesStatus: "",
},
};
var app = document.getElementById("app");
var menus = [
{ type: "section", label: "总览" },
{ key: "dashboard", label: "控制台", permission: "dashboard:read" },
{ type: "section", label: "内容" },
{ key: "site", label: "官网内容", permission: "site:read" },
{ key: "competition", label: "赛道内容", permission: "competition:read" },
{ key: "files", label: "素材库", permission: "file:read" },
{ type: "section", label: "运营" },
{ key: "works", label: "作品管理", permission: "work:read" },
{ key: "courses", label: "视频/课程", permission: "course:read" },
{ key: "evaluation", label: "作品评选", permission: "evaluation:manage" },
{ key: "inquiries", label: "咨询线索", permission: "inquiry:read" },
];
function escapeHtml(value) {
return String(value == null ? "" : value)
.replace(/&/g, "&amp;")
.replace(/</g, "&lt;")
.replace(/>/g, "&gt;")
.replace(/"/g, "&quot;");
}
function hasPermission(permission) {
if (!permission) return true;
var permissions = (state.user && state.user.permissions) || [];
return permissions.indexOf(permission) !== -1;
}
function setMessage(message, type) {
state.message = message || "";
state.messageType = type || "";
}
function getHeaders(extra) {
var headers = Object.assign({ "Content-Type": "application/json" }, extra || {});
if (state.token) headers.Authorization = "Bearer " + state.token;
return headers;
}
async function request(path, options) {
var response = await fetch(state.apiBase + path, Object.assign({}, options || {}, { headers: getHeaders(options && options.headers) }));
var body = await response.json().catch(function () {
return {};
});
if (response.status === 401) {
logout(false);
throw new Error("登录已过期,请重新登录");
}
if (!response.ok || body.code !== 0) {
throw new Error(body.message || body.error || "请求失败:" + response.status);
}
return body.data;
}
function getFormData(form) {
return Object.fromEntries(new FormData(form).entries());
}
function field(name, label, value, type) {
return (
'<div class="field">' +
'<label for="' +
name +
'">' +
label +
"</label>" +
'<input id="' +
name +
'" name="' +
name +
'" type="' +
(type || "text") +
'" value="' +
escapeHtml(value || "") +
'" />' +
"</div>"
);
}
function textarea(name, label, value) {
return (
'<div class="field">' +
'<label for="' +
name +
'">' +
label +
"</label>" +
'<textarea id="' +
name +
'" name="' +
name +
'">' +
escapeHtml(value || "") +
"</textarea>" +
"</div>"
);
}
function select(name, label, value, options) {
return (
'<div class="field">' +
'<label for="' +
name +
'">' +
label +
"</label>" +
'<select id="' +
name +
'" name="' +
name +
'">' +
options
.map(function (item) {
return '<option value="' + item.value + '" ' + (item.value === value ? "selected" : "") + ">" + item.label + "</option>";
})
.join("") +
"</select>" +
"</div>"
);
}
function badge(status) {
return '<span class="badge ' + escapeHtml(status || "") + '">' + escapeHtml(status || "-") + "</span>";
}
function pageTitle() {
var item = menus.find(function (menu) {
return menu.key === state.view;
});
return item ? item.label : "管理端";
}
function renderLogin() {
app.innerHTML =
'<main class="login-page">' +
'<section class="login-panel">' +
"<h1>模灵科技管理端</h1>" +
"<p>管理公司官网、赛道页、作品、课程、素材和评选流程。</p>" +
'<form id="login-form" class="field-stack">' +
field("apiBase", "API 地址", state.apiBase) +
field("username", "账号", "admin") +
field("password", "密码", "", "password") +
'<button class="btn primary" type="submit">登录</button>' +
(state.message ? '<div class="status-line error">' + escapeHtml(state.message) + "</div>" : "") +
"</form>" +
"</section>" +
"</main>";
document.getElementById("login-form").addEventListener("submit", async function (event) {
event.preventDefault();
var data = getFormData(event.currentTarget);
state.apiBase = data.apiBase.replace(/\/$/, "");
localStorage.setItem("mlkj-admin-api-base", state.apiBase);
state.loading = true;
setMessage("");
renderLogin();
try {
var result = await request("/admin/auth/login", {
method: "POST",
body: JSON.stringify({ username: data.username, password: data.password }),
});
state.token = result.token || result.accessToken;
localStorage.setItem(TOKEN_KEY, state.token);
state.user = {
username: result.username,
displayName: result.displayName || result.username,
roles: result.roles || [],
permissions: result.permissions || [],
};
state.view = "dashboard";
await refreshView();
} catch (error) {
state.loading = false;
setMessage(error.message, "error");
renderLogin();
}
});
}
async function loadMe() {
if (!state.token) return null;
state.user = await request("/admin/me");
return state.user;
}
async function loadDashboard() {
state.dashboard = await request("/admin/dashboard");
}
async function loadWorks() {
var params = new URLSearchParams({ page: "1", pageSize: "50" });
if (state.filters.worksKeyword) params.set("keyword", state.filters.worksKeyword);
if (state.filters.worksStatus) params.set("status", state.filters.worksStatus);
var result = await request("/admin/works?" + params.toString());
state.works = result.list || [];
}
async function loadCourses() {
var params = new URLSearchParams({ page: "1", pageSize: "50" });
if (state.filters.coursesKeyword) params.set("keyword", state.filters.coursesKeyword);
if (state.filters.coursesStatus) params.set("status", state.filters.coursesStatus);
var result = await request("/admin/courses?" + params.toString());
state.courses = result.list || [];
}
async function loadFiles() {
state.files = await request("/admin/files");
}
async function loadInquiries() {
var params = new URLSearchParams({ page: "1", pageSize: "50" });
if (state.filters.inquiriesStatus) params.set("status", state.filters.inquiriesStatus);
var result = await request("/admin/inquiries?" + params.toString());
state.inquiries = result.list || [];
}
async function refreshView() {
try {
state.loading = true;
if (!state.user && state.token) await loadMe();
if (state.view === "dashboard") await loadDashboard();
if (state.view === "works") await loadWorks();
if (state.view === "courses") await loadCourses();
if (state.view === "files") await loadFiles();
if (state.view === "inquiries") await loadInquiries();
setMessage("");
} catch (error) {
setMessage(error.message, "error");
} finally {
state.loading = false;
render();
}
}
function renderShell(content) {
var nav = menus
.map(function (item) {
if (item.type === "section") return '<div class="nav-section">' + item.label + "</div>";
if (!hasPermission(item.permission)) return "";
return (
'<button type="button" data-view="' +
item.key +
'" class="' +
(state.view === item.key ? "active" : "") +
'">' +
item.label +
"</button>"
);
})
.join("");
var user = state.user || {};
app.innerHTML =
'<div class="shell">' +
'<aside class="sidebar">' +
'<div class="brand"><h1>模灵科技</h1><p>官网与赛道页管理端</p></div>' +
'<nav class="nav">' +
nav +
"</nav>" +
'<div class="sidebar-footer"><button class="btn" id="logout-btn" type="button">退出登录</button></div>' +
"</aside>" +
'<main class="main">' +
'<div class="topbar">' +
"<div><h2>" +
pageTitle() +
"</h2><p>API:" +
escapeHtml(state.apiBase) +
"</p></div>" +
'<div class="user-chip"><div class="avatar">' +
escapeHtml((user.displayName || user.username || "管").slice(0, 1)) +
'</div><div><strong>' +
escapeHtml(user.displayName || user.username || "管理员") +
'</strong><div class="muted">' +
escapeHtml((user.roles || []).join(", ") || "admin") +
"</div></div></div>" +
"</div>" +
(state.message ? '<div class="status-line ' + state.messageType + '">' + escapeHtml(state.message) + "</div>" : "") +
content +
"</main>" +
"</div>";
document.querySelectorAll("[data-view]").forEach(function (button) {
button.addEventListener("click", function () {
state.view = button.getAttribute("data-view");
setMessage("");
refreshView();
});
});
document.getElementById("logout-btn").addEventListener("click", function () {
logout(true);
});
}
function renderDashboard() {
var data = state.dashboard || {};
renderShell(
'<section class="kpis">' +
kpi("作品总数", data.worksCount) +
kpi("已发布作品", data.publishedWorks) +
kpi("课程/视频", data.coursesCount) +
kpi("咨询线索", data.inquiriesCount) +
"</section>" +
'<section class="panel"><div class="panel-header"><h3>建设进度</h3></div><div class="panel-body">' +
'<div class="notice">当前管理端前端已接入登录、权限、控制台、作品、课程、文件库和线索接口。下一步将继续补官网内容、赛道内容、OSS 直传和作品评选。</div>' +
"</div></section>",
);
}
function kpi(label, value) {
return '<div class="kpi"><div class="label">' + label + '</div><div class="value">' + (value == null ? "-" : value) + "</div></div>";
}
function renderWorks() {
var work = state.editingWork || {};
renderShell(
'<div class="grid-two">' +
'<section class="panel">' +
'<div class="panel-header"><h3>作品列表</h3><button class="btn primary small" id="new-work-btn" type="button">新建作品</button></div>' +
'<div class="panel-body">' +
renderWorksToolbar() +
'<div class="table-wrap"><table class="table"><thead><tr><th>编号</th><th>作品</th><th>作者/学校</th><th>状态</th><th>操作</th></tr></thead><tbody>' +
(state.works.length ? state.works.map(renderWorkRow).join("") : '<tr><td colspan="5"><div class="empty">暂无作品</div></td></tr>') +
"</tbody></table></div></div></section>" +
'<section class="panel"><div class="panel-header"><h3>' +
(work.id ? "编辑作品" : "新建作品") +
'</h3></div><div class="panel-body">' +
renderWorkForm(work) +
"</div></section>" +
"</div>",
);
bindWorksEvents();
}
function renderWorksToolbar() {
return (
'<div class="toolbar"><div class="filters">' +
'<input id="works-keyword" placeholder="搜索标题、编号、作者、学校" value="' +
escapeHtml(state.filters.worksKeyword) +
'" />' +
'<select id="works-status"><option value="">全部状态</option>' +
statusOptions(state.filters.worksStatus) +
"</select>" +
'<button class="btn small" id="works-search-btn" type="button">筛选</button>' +
'</div><button class="btn small" id="works-reload-btn" type="button">刷新</button></div>'
);
}
function renderWorkRow(item) {
var id = item.id || item.workNo;
return (
"<tr><td>" +
escapeHtml(item.workNo || id) +
"</td><td><strong>" +
escapeHtml(item.title) +
'</strong><br /><span class="muted">' +
escapeHtml(item.category || "") +
"</span></td><td>" +
escapeHtml(item.authorName || item.author || "") +
'<br /><span class="muted">' +
escapeHtml(item.school || "") +
"</span></td><td>" +
badge(item.status || "draft") +
'</td><td><button class="btn small" data-edit-work="' +
escapeHtml(id) +
'" type="button">编辑</button></td></tr>'
);
}
function renderWorkForm(work) {
return (
'<form id="work-form" class="field-stack">' +
field("workNo", "作品编号", work.workNo || work.id || "") +
field("title", "作品标题", work.title || "") +
field("category", "分类", work.category || "") +
field("direction", "方向", work.direction || "") +
field("authorName", "作者/团队", work.authorName || work.author || "") +
field("school", "学校/机构", work.school || "") +
field("coverUrl", "封面图 URL", work.coverUrl || "") +
field("modelUrl", "3D 模型 URL", work.modelUrl || "") +
textarea("summary", "作品概述", work.summary || "") +
textarea("aigcSummary", "AIGC 创作流程", work.aigcSummary || "") +
textarea("prompt", "提示词", work.prompt || "") +
field("voteCount", "点赞数", work.voteCount || work.votes || 0, "number") +
field("sortOrder", "排序", work.sortOrder || 0, "number") +
select("status", "发布状态", work.status || "published", publishStatusOptions()) +
'<div class="form-actions"><button class="btn" id="reset-work-btn" type="button">清空</button><button class="btn primary" type="submit">保存作品</button></div>' +
"</form>"
);
}
function bindWorksEvents() {
document.getElementById("new-work-btn").addEventListener("click", function () {
state.editingWork = null;
renderWorks();
});
document.getElementById("works-reload-btn").addEventListener("click", function () {
refreshView();
});
document.getElementById("works-search-btn").addEventListener("click", function () {
state.filters.worksKeyword = document.getElementById("works-keyword").value.trim();
state.filters.worksStatus = document.getElementById("works-status").value;
refreshView();
});
document.querySelectorAll("[data-edit-work]").forEach(function (button) {
button.addEventListener("click", async function () {
try {
state.editingWork = await request("/admin/works/" + encodeURIComponent(button.getAttribute("data-edit-work")));
renderWorks();
} catch (error) {
setMessage(error.message, "error");
renderWorks();
}
});
});
document.getElementById("reset-work-btn").addEventListener("click", function () {
state.editingWork = null;
renderWorks();
});
document.getElementById("work-form").addEventListener("submit", submitWorkForm);
}
async function submitWorkForm(event) {
event.preventDefault();
var data = normalizeNumeric(getFormData(event.currentTarget), ["voteCount", "sortOrder"]);
var id = state.editingWork && (state.editingWork.id || state.editingWork.workNo);
try {
await request(id ? "/admin/works/" + encodeURIComponent(id) : "/admin/works", {
method: id ? "PATCH" : "POST",
body: JSON.stringify(data),
});
state.editingWork = null;
setMessage("作品已保存", "success");
await loadWorks();
renderWorks();
} catch (error) {
setMessage(error.message, "error");
renderWorks();
}
}
function renderCourses() {
var course = state.editingCourse || {};
renderShell(
'<div class="grid-two">' +
'<section class="panel"><div class="panel-header"><h3>课程列表</h3><button class="btn primary small" id="new-course-btn" type="button">新建课程</button></div><div class="panel-body">' +
renderCoursesToolbar() +
'<div class="table-wrap"><table class="table"><thead><tr><th>编号</th><th>课程</th><th>类型</th><th>状态</th><th>操作</th></tr></thead><tbody>' +
(state.courses.length ? state.courses.map(renderCourseRow).join("") : '<tr><td colspan="5"><div class="empty">暂无课程</div></td></tr>') +
"</tbody></table></div></div></section>" +
'<section class="panel"><div class="panel-header"><h3>' +
(course.id ? "编辑课程" : "新建课程") +
'</h3></div><div class="panel-body">' +
renderCourseForm(course) +
"</div></section>" +
"</div>",
);
bindCoursesEvents();
}
function renderCoursesToolbar() {
return (
'<div class="toolbar"><div class="filters">' +
'<input id="courses-keyword" placeholder="搜索标题、编号、合作方" value="' +
escapeHtml(state.filters.coursesKeyword) +
'" />' +
'<select id="courses-status"><option value="">全部状态</option>' +
statusOptions(state.filters.coursesStatus) +
"</select>" +
'<button class="btn small" id="courses-search-btn" type="button">筛选</button>' +
'</div><button class="btn small" id="courses-reload-btn" type="button">刷新</button></div>'
);
}
function renderCourseRow(item) {
var id = item.id || item.courseNo;
return (
"<tr><td>" +
escapeHtml(item.courseNo || id) +
"</td><td><strong>" +
escapeHtml(item.title) +
'</strong><br /><span class="muted">' +
escapeHtml(item.partner || "") +
"</span></td><td>" +
escapeHtml(item.type || "") +
"</td><td>" +
badge(item.status || "draft") +
'</td><td><button class="btn small" data-edit-course="' +
escapeHtml(id) +
'" type="button">编辑</button></td></tr>'
);
}
function renderCourseForm(course) {
return (
'<form id="course-form" class="field-stack">' +
field("courseNo", "课程编号", course.courseNo || course.id || "") +
select("type", "课程类型", course.type || "training", [
{ value: "roadshow", label: "宣讲回放" },
{ value: "training", label: "赛道培训" },
]) +
field("title", "标题", course.title || "") +
textarea("summary", "简介", course.summary || "") +
textarea("description", "详情", course.description || "") +
field("coverUrl", "封面图 URL", course.coverUrl || "") +
field("videoUrl", "视频 URL", course.videoUrl || "") +
field("partner", "合作方", course.partner || "") +
field("durationText", "时长", course.durationText || "") +
field("sortOrder", "排序", course.sortOrder || 0, "number") +
select("status", "发布状态", course.status || "published", publishStatusOptions()) +
'<div class="form-actions"><button class="btn" id="reset-course-btn" type="button">清空</button><button class="btn primary" type="submit">保存课程</button></div>' +
"</form>"
);
}
function bindCoursesEvents() {
document.getElementById("new-course-btn").addEventListener("click", function () {
state.editingCourse = null;
renderCourses();
});
document.getElementById("courses-reload-btn").addEventListener("click", function () {
refreshView();
});
document.getElementById("courses-search-btn").addEventListener("click", function () {
state.filters.coursesKeyword = document.getElementById("courses-keyword").value.trim();
state.filters.coursesStatus = document.getElementById("courses-status").value;
refreshView();
});
document.querySelectorAll("[data-edit-course]").forEach(function (button) {
button.addEventListener("click", async function () {
try {
state.editingCourse = await request("/admin/courses/" + encodeURIComponent(button.getAttribute("data-edit-course")));
renderCourses();
} catch (error) {
setMessage(error.message, "error");
renderCourses();
}
});
});
document.getElementById("reset-course-btn").addEventListener("click", function () {
state.editingCourse = null;
renderCourses();
});
document.getElementById("course-form").addEventListener("submit", submitCourseForm);
}
async function submitCourseForm(event) {
event.preventDefault();
var data = normalizeNumeric(getFormData(event.currentTarget), ["sortOrder"]);
var id = state.editingCourse && (state.editingCourse.id || state.editingCourse.courseNo);
try {
await request(id ? "/admin/courses/" + encodeURIComponent(id) : "/admin/courses", {
method: id ? "PATCH" : "POST",
body: JSON.stringify(data),
});
state.editingCourse = null;
setMessage("课程已保存", "success");
await loadCourses();
renderCourses();
} catch (error) {
setMessage(error.message, "error");
renderCourses();
}
}
function renderFiles() {
renderShell(
'<section class="panel"><div class="panel-header"><h3>素材库</h3><button class="btn small" id="files-reload-btn" type="button">刷新</button></div><div class="panel-body">' +
'<div class="notice">当前版本先接入文件记录列表。下一步会按云部署设计接入 OSS 临时凭证直传。</div>' +
'<div class="table-wrap" style="margin-top:14px;"><table class="table"><thead><tr><th>文件名</th><th>类型</th><th>大小</th><th>存储</th><th>时间</th></tr></thead><tbody>' +
(state.files.length ? state.files.map(renderFileRow).join("") : '<tr><td colspan="5"><div class="empty">暂无文件</div></td></tr>') +
"</tbody></table></div></div></section>",
);
document.getElementById("files-reload-btn").addEventListener("click", refreshView);
}
function renderFileRow(item) {
return (
"<tr><td><strong>" +
escapeHtml(item.originalName) +
'</strong><br /><span class="muted">' +
escapeHtml(item.url || item.fileKey || "") +
"</span></td><td>" +
escapeHtml(item.mimeType || "") +
"</td><td>" +
escapeHtml(item.size || "") +
"</td><td>" +
escapeHtml(item.storageProvider || "") +
"</td><td>" +
escapeHtml(item.createdAt || "") +
"</td></tr>"
);
}
function renderInquiries() {
renderShell(
'<section class="panel"><div class="panel-header"><h3>咨询线索</h3><button class="btn small" id="inquiries-reload-btn" type="button">刷新</button></div><div class="panel-body">' +
'<div class="filters" style="margin-bottom:14px;"><select id="inquiries-status"><option value="">全部状态</option><option value="pending">待联系</option><option value="contacted">已联系</option><option value="closed">已关闭</option></select><button class="btn small" id="inquiries-search-btn" type="button">筛选</button></div>' +
'<div class="table-wrap"><table class="table"><thead><tr><th>机构</th><th>联系人</th><th>电话</th><th>状态</th><th>时间</th></tr></thead><tbody>' +
(state.inquiries.length ? state.inquiries.map(renderInquiryRow).join("") : '<tr><td colspan="5"><div class="empty">暂无线索</div></td></tr>') +
"</tbody></table></div></div></section>",
);
document.getElementById("inquiries-status").value = state.filters.inquiriesStatus;
document.getElementById("inquiries-reload-btn").addEventListener("click", refreshView);
document.getElementById("inquiries-search-btn").addEventListener("click", function () {
state.filters.inquiriesStatus = document.getElementById("inquiries-status").value;
refreshView();
});
}
function renderInquiryRow(item) {
return (
"<tr><td><strong>" +
escapeHtml(item.organization) +
'</strong><br /><span class="muted">' +
escapeHtml(item.role || "") +
"</span></td><td>" +
escapeHtml(item.contactName || "") +
"</td><td>" +
escapeHtml(item.phone || "") +
"</td><td>" +
badge(item.status || "pending") +
"</td><td>" +
escapeHtml(item.createdAt || "") +
"</td></tr>"
);
}
function renderPlaceholder(title, desc, items) {
renderShell(
'<section class="panel"><div class="panel-header"><h3>' +
title +
'</h3></div><div class="panel-body"><p class="muted">' +
desc +
'</p><div class="section-grid" style="margin-top:16px;">' +
items
.map(function (item) {
return '<article class="content-card"><h3>' + item.title + '</h3><p>' + item.desc + "</p></article>";
})
.join("") +
"</div></div></section>",
);
}
function renderSite() {
renderPlaceholder("官网内容", "下一阶段接入站点配置、首页区块、案例和合作咨询文案。", [
{ title: "站点配置", desc: "公司名、SEO、导航、Logo、备案和联系方式。" },
{ title: "首页 Hero", desc: "标题、副标题、按钮、背景图和产品说明。" },
{ title: "业务与案例", desc: "业务版图、产品矩阵、解决方案、客户案例。" },
{ title: "发布流程", desc: "草稿、预览、发布、下架和历史版本。" },
]);
}
function renderCompetition() {
renderPlaceholder("赛道内容", "下一阶段接入赛道基础信息、赛程、赛事说明、资源包和合作伙伴。", [
{ title: "赛道基础", desc: "标题、副标题、主题、报名入口、创作入口和 Hero 图。" },
{ title: "赛程安排", desc: "报名、提交、复评、决赛等节点维护。" },
{ title: "赛事说明", desc: "奖项设置、设计要求、参赛须知和提交材料。" },
{ title: "参考资源", desc: "PDF、ZIP、图片、链接和开放下载时间。" },
]);
}
function renderEvaluation() {
renderPlaceholder("作品评选", "下一阶段接入评审轮次、评分指标、评委分配、在线评分和结果发布。", [
{ title: "评审轮次", desc: "初评、复评、决赛配置和锁定。" },
{ title: "评分指标", desc: "指标、满分、权重和排序。" },
{ title: "评委任务", desc: "分配作品给评委,追踪完成进度。" },
{ title: "结果汇总", desc: "专家分、公众分、最终分、排名和奖项。" },
]);
}
function statusOptions(value) {
return publishStatusOptions()
.map(function (item) {
return '<option value="' + item.value + '" ' + (item.value === value ? "selected" : "") + ">" + item.label + "</option>";
})
.join("");
}
function publishStatusOptions() {
return [
{ value: "draft", label: "草稿" },
{ value: "published", label: "已发布" },
{ value: "disabled", label: "已下架" },
{ value: "archived", label: "已归档" },
];
}
function normalizeNumeric(data, keys) {
keys.forEach(function (key) {
if (data[key] !== "") data[key] = Number(data[key]);
else delete data[key];
});
return data;
}
function logout(showMessage) {
localStorage.removeItem(TOKEN_KEY);
state.token = "";
state.user = null;
state.dashboard = null;
state.works = [];
state.courses = [];
state.files = [];
state.inquiries = [];
if (showMessage) setMessage("已退出登录", "");
renderLogin();
}
function render() {
if (!state.token) {
renderLogin();
return;
}
if (state.view === "dashboard") return renderDashboard();
if (state.view === "site") return renderSite();
if (state.view === "competition") return renderCompetition();
if (state.view === "files") return renderFiles();
if (state.view === "works") return renderWorks();
if (state.view === "courses") return renderCourses();
if (state.view === "evaluation") return renderEvaluation();
if (state.view === "inquiries") return renderInquiries();
renderDashboard();
}
async function boot() {
if (!state.token) {
renderLogin();
return;
}
await refreshView();
}
boot();
})();
+14
View File
@@ -0,0 +1,14 @@
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>模灵科技官网管理端</title>
<meta name="description" content="模灵科技官网与赛道页内容管理端" />
<link rel="stylesheet" href="./assets/admin-app.css" />
</head>
<body>
<div id="app"></div>
<script src="./assets/admin-app.js"></script>
</body>
</html>
+96
View File
@@ -0,0 +1,96 @@
# 当前项目审计
## 1. 项目位置
已审阅项目:`/Users/max/AI SoulMate/开发/mlkj-website`
当前项目包含:
| 目录/文件 | 说明 |
| --- | --- |
| `frontend` | Vite 静态前台,包含官网首页、赛道页、作品详情、课程详情和一个简版管理页 |
| `backend` | NestJS API,包含 Swagger、Prisma、mock 数据兜底 |
| `backend/prisma/schema.prisma` | PostgreSQL 数据模型 |
| `frontend/public/locales` | 官网和赛道页多语言文案 JSON |
| `frontend/public/assets` | Logo、赛道图、奖项图标、页面 CSS/JS |
| `docs/admin-content-management-plan.md` | 已有简版管理端内容管理方案 |
## 2. 当前技术栈
| 层 | 技术 |
| --- | --- |
| 官网前台 | HTML + CSS + 原生 JS + Vite |
| 简版后台 | `frontend/public/admin.html` + `assets/admin.js` |
| 后端 API | NestJS |
| API 文档 | Swagger/OpenAPI |
| ORM | Prisma |
| 数据库 | PostgreSQL |
| 文件存储规划 | 阿里云 OSS |
| 部署 | Docker、Nginx、docker compose |
## 3. 当前前台页面
| 页面 | 文件 | 主要内容 |
| --- | --- | --- |
| 公司官网 | `frontend/index.html` | Hero、提案定位、业务版图、产品矩阵、解决方案、案例、合作咨询 |
| 赛道页 | `frontend/competition.html` | 大赛介绍、赛程、赛事说明、资源包、作品展示、在线学习、合作伙伴 |
| 作品详情 | `frontend/work-detail.html` | 作品基础信息、AIGC 过程、模型与附件展示 |
| 课程详情 | `frontend/course-detail.html` | 宣讲/培训视频详情 |
| 简版后台 | `frontend/admin.html` | 登录、控制台、作品、课程、线索、文件库 |
## 4. 当前后端能力
已存在的公开接口:
| 模块 | 接口 |
| --- | --- |
| 站点 | `GET /api/site/config`、`GET /api/site/home` |
| 大赛 | `GET /api/competition`、`GET /api/competition/schedule` |
| 作品 | `GET /api/works`、`GET /api/works/:id`、`POST /api/works/:id/vote` |
| 课程 | `GET /api/courses`、`GET /api/courses/:id` |
| 线索 | 前台提交能力在 `inquiries` 模块中已有骨架 |
已存在的后台接口:
| 模块 | 接口 |
| --- | --- |
| 登录 | `POST /api/admin/auth/login` |
| 控制台 | `GET /api/admin/dashboard` |
| 作品 | `GET/POST/PATCH/DELETE /api/admin/works` |
| 课程 | `GET/POST/PATCH/DELETE /api/admin/courses` |
| 线索 | `GET /api/admin/inquiries`、`PATCH /api/admin/inquiries/:id/status` |
| 文件 | `POST /api/admin/uploads`、`GET /api/admin/files` |
## 5. 当前数据模型
现有 Prisma 模型已经包含:
| 类型 | 表 |
| --- | --- |
| 官网配置 | `site_configs`、`home_sections` |
| 大赛 | `competitions`、`competition_schedules`、`competition_resources`、`partners` |
| 作品 | `works`、`work_images`、`work_files`、`work_votes` |
| 课程视频 | `courses` |
| 内容延展 | `cases`、`news` |
| 咨询线索 | `inquiries` |
| 文件 | `files` |
| 管理后台 | `admin_users`、`admin_roles`、`admin_user_roles`、`operation_logs` |
## 6. 主要缺口
| 缺口 | 影响 |
| --- | --- |
| 官网首页和赛道页大量文案仍在 HTML 或 locale JSON 中 | 运营无法自行修改页面内容 |
| 赛道页复杂区块没有完整后台模型 | 奖项、设计要求、参赛须知、资源包、合作伙伴等更新成本高 |
| 文件接口只是登记记录,不是完整上传流程 | 图片、视频、模型、资料包还不能在后台形成稳定闭环 |
| 作品评选只有投票表,无评委评分模型 | 无法支持评审轮次、指标打分、汇总排名、获奖发布 |
| 权限模型已建表但未完整接入 | 后续多角色运营、评委、管理员隔离不足 |
| 内容缺少版本/预览/发布流程 | 修改线上内容风险较高 |
## 7. 设计约束
1. 前台视觉和页面结构第一阶段尽量不大改,优先把数据来源从静态内容切到 API。
2. 管理端应兼容现有表,不推倒重来;新增表集中补足内容区块、评审和上传能力。
3. 所有后台写操作必须进入操作日志,尤其是发布、下架、评分、结果确认。
4. 文件本体放 OSS,数据库只保存元信息、业务归属和访问地址。
5. 作品评选与公众投票分开建模,避免把点赞数当作评委评分。
+212
View File
@@ -0,0 +1,212 @@
# 管理端 PRD
## 1. 产品名称
模灵科技官网与赛道页内容管理端,简称 `MLKJ Website Admin`。
## 2. 背景
现有官网和赛道页已经具备较完整的展示页面,但公司官网文案、赛道页说明、作品展示、视频课程、资源包等内容仍部分写死在 HTML、JS 或 JSON 文件中。随着赛道运营开始,后续会频繁更新报名信息、赛程、资源包、作品、视频、获奖结果和合作伙伴信息。若每次都由开发改代码,会造成发布慢、风险高、运营成本高。
因此需要建设一个 PC 管理端,让运营和赛事管理人员可以自行完成内容维护、素材上传、作品管理与评选流程。
## 3. 产品目标
| 目标 | 说明 |
| --- | --- |
| 内容可运营 | 公司官网和赛道页主要文案、图片、链接可在后台维护 |
| 资源可上传 | 图片、视频、模型、PDF、ZIP 等素材可上传并绑定到业务 |
| 作品可管理 | 支持作品新增、编辑、上下架、附件图集维护、投票数据查看 |
| 评选可闭环 | 支持评审轮次、评委、评分指标、评分、排名、获奖结果发布 |
| 发布可控 | 支持草稿、预览、发布、下架、操作日志 |
| 后续可扩展 | 保持和现有 NestJS + Prisma + PostgreSQL 架构兼容 |
## 4. 非目标
第一版不处理以下能力:
| 内容 | 原因 |
| --- | --- |
| 完整 CMS 页面搭建器 | 当前页面结构固定,不需要自由拖拽建站 |
| 复杂视频点播转码 | 第一版可用 OSS 或外链,播放量上来后再接 VOD |
| 参赛者自助报名系统 | 当前需求集中在管理端,不先建设选手端 |
| 财务、合同、订单 | 与官网内容运营无直接关系 |
| 多租户 | 只服务模灵科技官网和当前赛道 |
## 5. 用户角色
| 角色 | 使用场景 | 权限 |
| --- | --- | --- |
| 超级管理员 | 系统初始化、账号、角色、所有内容 | 全部权限 |
| 官网运营 | 修改官网首页、案例、Logo、咨询信息 | 官网内容、素材、线索 |
| 赛事运营 | 维护赛道页、赛程、资料包、课程、作品 | 赛道内容、作品、课程、素材 |
| 评审管理员 | 创建评审轮次、配置指标、分配评委、发布结果 | 评选配置和结果 |
| 评委 | 查看被分配作品并打分 | 只读作品、提交评分 |
| 只读观察员 | 查看数据和内容,不可写 | 只读 |
## 6. 功能范围
### 6.1 登录与权限
| 编号 | 功能 | 优先级 |
| --- | --- | --- |
| AUTH-01 | 管理员账号密码登录 | P0 |
| AUTH-02 | JWT 会话、退出登录、过期续签 | P0 |
| AUTH-03 | RBAC 菜单与接口权限 | P0 |
| AUTH-04 | 操作日志 | P0 |
| AUTH-05 | 管理员账号、角色管理 | P1 |
### 6.2 控制台
| 编号 | 功能 | 优先级 |
| --- | --- | --- |
| DASH-01 | 查看作品数、已发布作品数、课程数、素材数、线索数 | P0 |
| DASH-02 | 查看待处理项:草稿、待评作品、未联系线索 | P0 |
| DASH-03 | 查看最近操作日志 | P1 |
| DASH-04 | 查看投票和评审概览 | P1 |
### 6.3 官网内容管理
| 编号 | 功能 | 优先级 |
| --- | --- | --- |
| SITE-01 | 编辑站点基础信息:公司名、英文名、SEO、导航、备案等 | P0 |
| SITE-02 | 编辑首页 Hero 文案、按钮、背景图 | P0 |
| SITE-03 | 编辑业务版图、产品矩阵、解决方案 | P0 |
| SITE-04 | 编辑客户案例、合作咨询说明 | P1 |
| SITE-05 | 支持中英文内容切换 | P1 |
| SITE-06 | 草稿保存、预览、发布 | P0 |
### 6.4 赛道页内容管理
| 编号 | 功能 | 优先级 |
| --- | --- | --- |
| COMP-01 | 编辑赛道基础信息:标题、副标题、主办/承办、报名链接 | P0 |
| COMP-02 | 编辑大赛介绍、赛道介绍、赛道定位 | P0 |
| COMP-03 | 编辑赛程安排 | P0 |
| COMP-04 | 编辑奖项设置、设计要求、参赛须知 | P0 |
| COMP-05 | 管理参考资源包:PDF、ZIP、图片、链接 | P0 |
| COMP-06 | 管理合作伙伴:Logo、角色、链接、排序 | P1 |
| COMP-07 | 管理大赛动态/通知 | P1 |
| COMP-08 | 草稿、预览、发布、下架 | P0 |
### 6.5 素材与文件库
| 编号 | 功能 | 优先级 |
| --- | --- | --- |
| FILE-01 | 上传图片、视频、模型、PDF、ZIP | P0 |
| FILE-02 | 自动记录文件大小、MIME、宽高、时长、上传人 | P0 |
| FILE-03 | 按业务场景筛选:官网、赛道、作品、课程、资源包 | P0 |
| FILE-04 | 文件选择器可从内容编辑表单中调用 | P0 |
| FILE-05 | 删除或归档未使用文件 | P1 |
| FILE-06 | 支持 OSS 直传凭证 | P0 |
### 6.6 视频/课程管理
| 编号 | 功能 | 优先级 |
| --- | --- | --- |
| COURSE-01 | 新增宣讲回放、培训课程 | P0 |
| COURSE-02 | 上传视频或填写外部视频链接 | P0 |
| COURSE-03 | 上传课程封面 | P0 |
| COURSE-04 | 编辑讲师/合作方、简介、时长、排序 | P0 |
| COURSE-05 | 发布、下架、归档 | P0 |
| COURSE-06 | 前台课程详情读取真实数据 | P0 |
### 6.7 作品管理
| 编号 | 功能 | 优先级 |
| --- | --- | --- |
| WORK-01 | 新增、编辑、删除作品 | P0 |
| WORK-02 | 上传封面、图集、模型、说明书、附件包 | P0 |
| WORK-03 | 编辑作者、学校、分类、方向、AIGC 说明、提示词、工艺说明 | P0 |
| WORK-04 | 设置发布状态、排序、精选 | P0 |
| WORK-05 | 查看点赞数、浏览数、评分结果 | P1 |
| WORK-06 | 批量导入作品 | P1 |
| WORK-07 | 批量上下架、批量分配评审轮次 | P1 |
### 6.8 作品评选
| 编号 | 功能 | 优先级 |
| --- | --- | --- |
| EVAL-01 | 创建评审轮次:初评、复评、决赛 | P0 |
| EVAL-02 | 配置评分指标和权重 | P0 |
| EVAL-03 | 管理评委账号 | P0 |
| EVAL-04 | 分配作品给评委 | P0 |
| EVAL-05 | 评委在线评分和评语 | P0 |
| EVAL-06 | 自动汇总平均分、加权分、公众投票折算分 | P0 |
| EVAL-07 | 标记入围、获奖、淘汰 | P0 |
| EVAL-08 | 发布获奖结果到前台 | P1 |
| EVAL-09 | 导出评分表 | P1 |
### 6.9 咨询线索
| 编号 | 功能 | 优先级 |
| --- | --- | --- |
| INQ-01 | 查看官网提交的合作咨询 | P1 |
| INQ-02 | 标记待联系、已联系、已关闭 | P1 |
| INQ-03 | 维护跟进备注 | P1 |
| INQ-04 | 导出线索 | P2 |
## 7. 核心状态
### 7.1 内容状态
| 状态 | 说明 |
| --- | --- |
| `draft` | 草稿,仅后台可见 |
| `published` | 已发布,前台可见 |
| `disabled` | 已下架,前台不可见 |
| `archived` | 已归档,保留历史记录 |
### 7.2 作品评审状态
| 状态 | 说明 |
| --- | --- |
| `pending_submit` | 待补充材料 |
| `submitted` | 已提交待审核 |
| `qualified` | 材料合格,可进入评审 |
| `reviewing` | 评审中 |
| `finalist` | 入围 |
| `winner` | 获奖 |
| `rejected` | 未通过 |
### 7.3 评分状态
| 状态 | 说明 |
| --- | --- |
| `assigned` | 已分配未评分 |
| `scoring` | 评分中 |
| `submitted` | 已提交评分 |
| `locked` | 已锁定,不可修改 |
## 8. 验收标准
| 范围 | 验收标准 |
| --- | --- |
| 登录权限 | 未登录不能访问后台接口;不同角色只能看到授权菜单 |
| 官网内容 | 修改首页 Hero 文案和背景图后,发布即可在前台展示 |
| 赛道内容 | 可维护赛程、奖项、资源包、合作伙伴并在前台展示 |
| 文件上传 | 图片、视频、PDF、ZIP 上传后可在文件库检索并绑定业务 |
| 课程视频 | 新增课程并发布后,赛道页和课程详情页可访问 |
| 作品管理 | 新增作品及附件后,作品列表和详情页可展示 |
| 评选流程 | 可创建轮次、分配评委、提交评分、汇总排名 |
| 操作日志 | 发布、下架、删除、评分锁定等关键操作有日志 |
## 9. 里程碑
| 阶段 | 范围 | 预计结果 |
| --- | --- | --- |
| M1 基础后台 | 登录、布局、RBAC、文件上传、控制台 | 后台可用,素材可上传 |
| M2 内容 CMS | 官网内容、赛道内容、资源包、合作伙伴 | 运营可维护页面内容 |
| M3 作品与课程 | 作品 CRUD、课程视频、前台 API 接入 | 赛道运营闭环 |
| M4 评选 | 评委、轮次、评分、排名、结果发布 | 支持正式评审 |
| M5 稳定性 | 日志、导出、性能、安全、备份 | 可上线运行 |
## 10. 风险与对策
| 风险 | 对策 |
| --- | --- |
| 静态页面文案分散在 HTML 与 JSON 中 | 先建立内容区块表,再逐步替换前台数据来源 |
| 视频文件较大,OSS 播放体验不稳定 | 第一版支持 OSS 和外链,后续接阿里云 VOD |
| 评委评分数据敏感 | 评分提交后锁定,管理员操作留痕 |
| 刷票影响公众投票 | 公众投票只作为独立维度,保存 visitorId、IP hash、UA hash |
| 内容误发布 | 草稿、预览、发布确认、操作日志必做 |
+182
View File
@@ -0,0 +1,182 @@
# 产品流程图
## 1. 总体流程
```mermaid
flowchart TD
A["管理员/运营/评委访问管理端"] --> B{"是否登录"}
B -- "否" --> C["登录页"]
C --> D["权限校验"]
B -- "是" --> D
D --> E["控制台"]
E --> F["官网内容管理"]
E --> G["赛道内容管理"]
E --> H["素材与文件库"]
E --> I["课程/视频管理"]
E --> J["作品管理"]
E --> K["作品评选"]
E --> L["咨询线索"]
F --> M["预览/发布到官网"]
G --> N["预览/发布到赛道页"]
I --> N
J --> N
K --> O["发布评选结果"]
```
## 2. 内容编辑发布流程
适用于官网首页、公司信息、赛道页说明、奖项设置、参赛须知、资源说明等文字和图片内容。
```mermaid
flowchart LR
A["选择页面"] --> B["选择区块"]
B --> C["编辑文案、图片、链接"]
C --> D["保存草稿"]
D --> E{"需要预览"}
E -- "是" --> F["生成预览地址"]
F --> G["运营核对"]
E -- "否" --> H["提交发布"]
G --> H
H --> I{"权限校验"}
I -- "通过" --> J["写入 published 版本"]
I -- "不通过" --> K["提示无权限"]
J --> L["前台 API 返回最新发布内容"]
J --> M["记录操作日志"]
```
## 3. 素材上传流程
适用于官网图片、赛道页图片、资源包、视频、作品模型、作品附件。
```mermaid
sequenceDiagram
participant U as 管理员
participant A as 管理端
participant API as NestJS API
participant OSS as 阿里云 OSS
participant DB as PostgreSQL
U->>A: 选择文件和业务场景
A->>API: POST /admin/uploads/policy
API->>API: 校验 MIME、大小、权限
API-->>A: 返回 OSS 直传凭证和 fileKey
A->>OSS: 直传文件
OSS-->>A: 上传成功
A->>API: POST /admin/uploads/complete
API->>DB: 写入 files 表
API-->>A: 返回文件记录
A->>API: 绑定到页面、课程、作品或资源包
```
## 4. 官网内容管理流程
```mermaid
flowchart TD
A["官网运营进入官网内容管理"] --> B["站点基础配置"]
A --> C["首页内容区块"]
B --> D["SEO、导航、公司信息、联系方式"]
C --> E["Hero、业务版图、产品矩阵、案例、合作咨询"]
D --> F["保存草稿"]
E --> F
F --> G["预览"]
G --> H["发布"]
H --> I["首页接口读取 published 内容"]
```
## 5. 赛道页内容管理流程
```mermaid
flowchart TD
A["赛事运营进入赛道页管理"] --> B["赛道基础信息"]
A --> C["大赛与赛道介绍"]
A --> D["赛程安排"]
A --> E["赛事说明"]
A --> F["参考资源包"]
A --> G["合作伙伴"]
A --> H["在线学习"]
B --> I["保存草稿/发布"]
C --> I
D --> I
E --> I
F --> I
G --> I
H --> I
I --> J["赛道页 API 聚合输出"]
```
## 6. 课程/视频发布流程
```mermaid
flowchart LR
A["新建课程"] --> B["选择类型:宣讲/培训"]
B --> C["填写标题、简介、合作方、时长"]
C --> D{"视频来源"}
D -- "上传视频" --> E["OSS 上传"]
D -- "外部链接" --> F["填写视频 URL"]
E --> G["上传封面"]
F --> G
G --> H["保存草稿"]
H --> I["发布"]
I --> J["赛道页在线学习区展示"]
J --> K["课程详情页播放"]
```
## 7. 作品管理流程
```mermaid
flowchart TD
A["新建作品"] --> B["填写基础信息"]
B --> C["上传封面和图集"]
C --> D["上传模型和附件"]
D --> E["填写 AIGC 过程、提示词、工艺说明"]
E --> F{"材料是否完整"}
F -- "否" --> G["保存为待补充"]
F -- "是" --> H["标记已提交"]
H --> I["管理员审核"]
I -- "通过" --> J["发布到作品展示"]
I -- "不通过" --> G
J --> K["进入评审候选池"]
```
## 8. 作品评选流程
```mermaid
flowchart TD
A["评审管理员创建评审轮次"] --> B["配置评分指标与权重"]
B --> C["选择参评作品"]
C --> D["添加/选择评委"]
D --> E["分配作品给评委"]
E --> F["评委查看作品详情"]
F --> G["按指标打分并填写评语"]
G --> H["提交评分"]
H --> I{"所有评分完成"}
I -- "否" --> F
I -- "是" --> J["系统汇总加权分"]
J --> K["评审管理员确认排名"]
K --> L["标记入围/获奖/淘汰"]
L --> M["锁定结果"]
M --> N["发布前台结果"]
```
## 9. 公众投票与评委评分关系
```mermaid
flowchart LR
A["公众投票"] --> B["work_votes"]
B --> C["投票数统计"]
C --> D["按规则折算公众分"]
E["评委评分"] --> F["work_scores"]
F --> G["按指标权重汇总专家分"]
D --> H["总分计算"]
G --> H
H --> I["评选结果"]
```
默认建议:
| 分数来源 | 权重 |
| --- | --- |
| 评委评分 | 80% |
| 公众投票折算 | 20% |
权重应在每个评审轮次中可配置,避免后续赛制变化影响历史数据。
+282
View File
@@ -0,0 +1,282 @@
# 管理端设计文档
## 1. 设计原则
1. 以运营效率为主,不做通用建站器。
2. 页面结构固定,后台只暴露需要运营维护的字段。
3. 所有影响前台展示的内容都支持草稿、预览、发布。
4. 上传、选择、绑定文件是高频操作,文件选择器应在所有内容表单中复用。
5. 评委端保持简洁,只展示被分配作品和评分表单。
## 2. 信息架构
```mermaid
flowchart TD
A["管理端"] --> B["控制台"]
A --> C["官网内容"]
A --> D["赛道内容"]
A --> E["素材库"]
A --> F["视频/课程"]
A --> G["作品管理"]
A --> H["作品评选"]
A --> I["咨询线索"]
A --> J["系统设置"]
C --> C1["站点配置"]
C --> C2["首页区块"]
C --> C3["客户案例"]
D --> D1["赛道基础信息"]
D --> D2["大赛介绍"]
D --> D3["赛程安排"]
D --> D4["赛事说明"]
D --> D5["参考资源"]
D --> D6["合作伙伴"]
D --> D7["大赛动态"]
H --> H1["评审轮次"]
H --> H2["评分指标"]
H --> H3["评委管理"]
H --> H4["评分进度"]
H --> H5["结果发布"]
```
## 3. 全局布局
| 区域 | 说明 |
| --- | --- |
| 左侧导航 | 一级菜单固定展示,根据权限过滤 |
| 顶部栏 | 当前页面标题、搜索、预览入口、用户菜单 |
| 主内容区 | 列表、表单、详情、配置面板 |
| 右侧抽屉 | 文件选择器、预览、操作日志、快速编辑 |
| 底部固定栏 | 内容编辑页的保存草稿、预览、发布按钮 |
## 4. 页面设计
### 4.1 登录页
字段:
| 字段 | 说明 |
| --- | --- |
| 账号 | 管理员用户名 |
| 密码 | 管理员密码 |
| 记住登录 | 可选,默认不勾选 |
交互:
1. 登录成功进入控制台。
2. 登录失败显示错误,不透露账号是否存在。
3. Token 过期后跳回登录页。
### 4.2 控制台
模块:
| 模块 | 内容 |
| --- | --- |
| 数据概览 | 作品数、已发布作品、课程视频、素材数、咨询线索、待评作品 |
| 待办事项 | 未发布草稿、待审核作品、未完成评分、待联系线索 |
| 快捷入口 | 新建作品、上传素材、新建课程、创建评审轮次 |
| 最近操作 | 最近 20 条操作日志 |
### 4.3 官网内容管理
页面分组:
| 页面 | 可编辑内容 |
| --- | --- |
| 站点配置 | 公司名称、英文名、产品名、SEO、导航、Logo、社媒链接、备案信息 |
| 首页 Hero | 标语、标题、副标题、按钮、背景图 |
| 提案定位 | 价值主张、交付节奏 |
| 业务版图 | 四个业务卡片、商业全景图 |
| 产品矩阵 | 产品卡片、链接 |
| 解决方案 | 行业方案列表 |
| 客户案例 | 案例标题、行业、描述、结果、封面 |
| 合作咨询 | 适用客户说明、表单提示、提交成功文案 |
编辑方式:
1. 左侧区块列表,右侧表单。
2. 每个区块有「保存草稿」「预览」「发布」「下架」。
3. 富文本只用于长说明,短字段使用普通输入框,避免格式失控。
### 4.4 赛道内容管理
页面分组:
| 页面 | 可编辑内容 |
| --- | --- |
| 赛道基础 | 标题、副标题、主题、主办/承办、报名链接、创作入口、Hero 图 |
| 大赛介绍 | 大赛介绍、赛道介绍、赛道定位、支持单位 |
| 赛程安排 | 节点标题、时间文本、开始/结束时间、说明、排序 |
| 赛事说明 | 奖项设置、设计要求、参赛须知、提交材料 |
| 参考资源 | 资源名称、描述、附件、是否开放下载、排序 |
| 合作伙伴 | 名称、角色、Logo、链接、排序 |
| 大赛动态 | 通知标题、日期、正文、状态 |
| 在线学习 | 关联课程视频,按类型和排序展示 |
关键交互:
1. 赛程、资源、合作伙伴支持拖拽排序。
2. 资源下载可设置开放时间,未开放时前台展示「即将开放」。
3. Hero 图、合作伙伴 Logo、奖项图标都从文件库选择。
### 4.5 素材库
列表字段:
| 字段 | 说明 |
| --- | --- |
| 缩略图/图标 | 图片展示缩略图,视频和文件展示类型图标 |
| 文件名 | 原文件名 |
| 场景 | 官网、赛道、作品、课程、资源包 |
| 类型 | 图片、视频、模型、文档、压缩包 |
| 大小 | 文件大小 |
| 尺寸/时长 | 图片宽高、视频时长 |
| 上传人 | 管理员 |
| 上传时间 | 创建时间 |
操作:
| 操作 | 说明 |
| --- | --- |
| 上传 | 支持拖拽上传和选择文件 |
| 复制 URL | 复制公开访问地址 |
| 选择 | 在业务表单中绑定文件 |
| 归档 | 不直接物理删除,先归档 |
### 4.6 视频/课程管理
列表筛选:
| 筛选 | 说明 |
| --- | --- |
| 类型 | 宣讲回放、赛道培训 |
| 状态 | 草稿、已发布、已下架、归档 |
| 关键词 | 标题、课程编号、合作方 |
编辑字段:
| 字段 | 说明 |
| --- | --- |
| 课程编号 | 如 `rs-01`、`tr-01` |
| 类型 | 宣讲回放或培训课程 |
| 标题 | 前台展示标题 |
| 简介 | 列表摘要 |
| 详情 | 详情页介绍 |
| 封面图 | 文件库图片 |
| 视频 | OSS 视频或外部链接 |
| 合作方 | 如北京服装学院 / 模灵科技 |
| 时长 | 文本或自动识别 |
| 排序 | 前台排序 |
| 状态 | 发布状态 |
### 4.7 作品管理
列表字段:
| 字段 | 说明 |
| --- | --- |
| 作品编号 | `SMT-2026-018` |
| 封面 | 作品封面 |
| 标题 | 作品名 |
| 作者/学校 | 作者和学校 |
| 分类/方向 | 前台筛选和评审分组 |
| 材料状态 | 待补充、已提交、合格 |
| 展示状态 | 草稿、已发布、下架 |
| 点赞/浏览 | 前台统计 |
| 评审状态 | 未入评、评审中、入围、获奖 |
详情页 Tab:
| Tab | 内容 |
| --- | --- |
| 基础信息 | 标题、编号、作者、学校、分类、方向、摘要 |
| 作品内容 | AIGC 流程、提示词、生成参数、设计亮点、工艺说明 |
| 图片与模型 | 封面、图集、GLB/STL/ZIP |
| 附件 | PDF、说明书、提交材料 |
| 数据 | 点赞、浏览、评分、操作日志 |
### 4.8 作品评选
评审管理员页面:
| 页面 | 功能 |
| --- | --- |
| 评审轮次 | 创建初评、复评、决赛,配置时间和状态 |
| 评分指标 | 指标名称、说明、分值、权重 |
| 评委管理 | 评委账号、所属单位、联系方式、状态 |
| 作品分配 | 按分类、学校、随机或手动分配 |
| 评分进度 | 查看每位评委完成情况 |
| 结果汇总 | 排名、平均分、专家分、公众分、最终结果 |
评委页面:
| 页面 | 功能 |
| --- | --- |
| 我的评审 | 列出被分配作品 |
| 作品评分 | 作品详情、附件预览、按指标打分、评语 |
| 已提交 | 查看已提交评分,锁定后不可修改 |
评分规则:
1. 每个轮次可配置多个指标。
2. 每个指标有最大分值和权重。
3. 评委提交后可在轮次锁定前修改。
4. 轮次锁定后评分不可修改,只能由超级管理员走异常更正流程。
5. 公众投票折算分单独计算,不覆盖作品点赞数。
## 5. 权限设计
| 权限码 | 说明 |
| --- | --- |
| `site:read`、`site:write`、`site:publish` | 官网内容查看、编辑、发布 |
| `competition:read`、`competition:write`、`competition:publish` | 赛道内容查看、编辑、发布 |
| `file:read`、`file:upload`、`file:archive` | 文件查看、上传、归档 |
| `course:read`、`course:write`、`course:publish` | 课程查看、编辑、发布 |
| `work:read`、`work:write`、`work:publish` | 作品查看、编辑、发布 |
| `evaluation:manage` | 评审配置和结果管理 |
| `evaluation:score` | 评委评分 |
| `inquiry:read`、`inquiry:write` | 线索查看和状态更新 |
| `system:manage` | 用户、角色、日志 |
## 6. 表单与校验
| 类型 | 校验 |
| --- | --- |
| 文本 | 必填、长度限制、去除首尾空格 |
| URL | 校验协议,允许 `https://`、`http://localhost`、相对路径 |
| 图片 | 限制 MIME、大小、建议尺寸 |
| 视频 | 限制 MIME、大小,记录时长 |
| 模型 | 允许 GLB、GLTF、STL、OBJ、ZIP |
| 评分 | 不可超过指标最大分,不可为空 |
## 7. 预览与发布
| 动作 | 说明 |
| --- | --- |
| 保存草稿 | 不影响前台 |
| 预览 | 生成带 token 的预览地址,读取草稿内容 |
| 发布 | 把草稿写入发布版本,前台 API 读取 |
| 下架 | 前台不再展示,但后台可恢复 |
| 归档 | 历史保留,默认不出现在列表 |
## 8. 空状态与异常
| 场景 | 展示 |
| --- | --- |
| 列表无数据 | 显示空状态和新建按钮 |
| 上传失败 | 显示失败原因和重试 |
| 发布失败 | 保留草稿,提示错误 |
| 权限不足 | 显示无权限页面 |
| 评分已锁定 | 表单只读,显示锁定时间 |
## 9. 前台适配说明
前台第一阶段不重做视觉,只逐步替换数据来源:
1. `index.html` 从 `/api/site/config` 和 `/api/site/home` 读取官网内容。
2. `competition.html` 从 `/api/competition` 聚合读取赛道内容、赛程、资源、作品、课程。
3. `work-detail.html` 从 `/api/works/:id` 读取作品完整详情。
4. `course-detail.html` 从 `/api/courses/:id` 读取课程和视频。
+203
View File
@@ -0,0 +1,203 @@
# 系统架构设计
## 1. 架构目标
1. 复用当前 `mlkj-website/backend` 的 NestJS、Swagger、Prisma、PostgreSQL 基础。
2. 管理端前端独立开发,和官网前台分开构建、分开路由。
3. 内容管理、文件上传、作品管理、评选管理在后端保持模块化。
4. 前台只读取已发布内容;后台可读取草稿、预览和历史版本。
5. 所有文件上传到 OSS,数据库只保存元数据和业务绑定关系。
## 2. 总体架构
```mermaid
flowchart TD
BrowserAdmin["管理端浏览器"] --> AdminFE["Admin Frontend<br/>Vite + React/Vue + TS"]
BrowserSite["官网访问者"] --> SiteFE["现有官网前台<br/>HTML + JS"]
AdminFE --> AdminAPI["NestJS Admin API<br/>/api/admin/*"]
SiteFE --> PublicAPI["NestJS Public API<br/>/api/site /api/competition /api/works"]
AdminAPI --> Auth["Auth + RBAC"]
AdminAPI --> Content["Content CMS Module"]
AdminAPI --> Media["Media Upload Module"]
AdminAPI --> Work["Works Module"]
AdminAPI --> Eval["Evaluation Module"]
AdminAPI --> Log["Operation Log"]
PublicAPI --> Content
PublicAPI --> Work
PublicAPI --> Course["Courses Module"]
Content --> DB[("PostgreSQL")]
Work --> DB
Eval --> DB
Course --> DB
Media --> DB
Media --> OSS[("Aliyun OSS")]
SiteFE --> CDN["CDN/OSS 公开资源"]
OSS --> CDN
```
## 3. 推荐技术选型
| 层 | 推荐 | 说明 |
| --- | --- | --- |
| 管理端前端 | Vite + TypeScript + React 或 Vue | 当前前台已有 Vite,管理端可独立工程 |
| UI 组件 | Ant Design / Arco Design / Naive UI | 管理后台表格、表单、上传、权限页成熟 |
| 状态管理 | TanStack Query + 轻量 store | 列表、详情、缓存、刷新更顺手 |
| 后端 | 继续使用 NestJS | 当前已有模块和 Swagger 基础 |
| ORM | Prisma | 当前已使用 |
| 数据库 | PostgreSQL | 当前 schema 已按 PostgreSQL 设计 |
| 文件存储 | 阿里云 OSS | 图片、视频、模型、PDF、ZIP |
| API 文档 | Swagger/OpenAPI | 后端已有 `@nestjs/swagger` |
| 鉴权 | JWT + RBAC | 替换当前 env 简版登录 |
## 4. 后端模块划分
| 模块 | 主要职责 |
| --- | --- |
| `auth` | 登录、刷新 token、当前用户、密码修改 |
| `admin-users` | 管理员、角色、权限 |
| `content` | 官网和赛道页内容区块、草稿、发布、预览 |
| `site` | 前台官网配置和首页聚合读取 |
| `competition` | 赛道基础信息、赛程、资源、合作伙伴 |
| `media` | OSS 直传凭证、文件记录、文件绑定 |
| `courses` | 宣讲回放和培训视频 |
| `works` | 作品、图片、模型、附件、投票 |
| `evaluation` | 评审轮次、指标、评委分配、评分、结果 |
| `inquiries` | 合作咨询线索 |
| `operation-log` | 关键操作审计 |
## 5. 前台数据读取模式
### 5.1 官网首页
```mermaid
sequenceDiagram
participant FE as 官网首页
participant API as Public API
participant DB as PostgreSQL
FE->>API: GET /api/site/config
API->>DB: 查询 published 配置
API-->>FE: 站点配置
FE->>API: GET /api/site/home
API->>DB: 查询 published 首页区块
API-->>FE: 首页区块数组
```
### 5.2 赛道页
```mermaid
sequenceDiagram
participant FE as 赛道页
participant API as Public API
participant DB as PostgreSQL
FE->>API: GET /api/competition
API->>DB: 查询赛道基础信息、区块、赛程、资源、课程、作品
API-->>FE: 聚合后的赛道页数据
```
## 6. 内容版本与发布
推荐使用 `content_revisions` 记录草稿和发布版本。业务表保留当前展示字段,版本表保存完整 JSON 快照。
```mermaid
flowchart LR
A["编辑表单"] --> B["content_revisions: draft"]
B --> C["预览 API 读取 draft"]
B --> D["发布"]
D --> E["业务表更新 published 字段"]
D --> F["content_revisions: published"]
E --> G["前台 API 读取 published"]
```
好处:
1. 前台查询仍可保持高性能。
2. 后台能保留历史版本和回滚依据。
3. 不需要把所有前台页面一次性改成通用 CMS 渲染。
## 7. 文件上传架构
第一版建议使用 OSS Browser Direct Upload。
```mermaid
flowchart TD
A["管理端选择文件"] --> B["后端生成上传凭证"]
B --> C["管理端直传 OSS"]
C --> D["后端登记 files"]
D --> E["绑定业务对象"]
```
建议 OSS 路径:
```text
mlkj-website/
site/images/
competition/images/
competition/resources/
courses/covers/
courses/videos/
works/covers/
works/images/
works/models/
works/documents/
```
## 8. 鉴权与权限
1. 登录接口返回 `accessToken` 和 `refreshToken`。
2. 后台接口统一使用 `Authorization: Bearer <token>`。
3. JWT 中保存用户 ID、角色、权限码摘要。
4. 后端每个写接口校验权限码。
5. 管理端菜单也按权限码过滤,但以后端校验为准。
## 9. 缓存策略
| 数据 | 策略 |
| --- | --- |
| 前台站点配置 | 可缓存 5 分钟,发布后清理 |
| 前台赛道页聚合 | 可缓存 1 分钟,发布后清理 |
| 作品列表 | 按查询条件短缓存,投票后清理对应作品 |
| 后台列表 | 不做强缓存,使用前端请求缓存即可 |
| OSS 文件 | 由 CDN 控制,文件 key 使用 hash 避免覆盖 |
## 10. 部署建议
```mermaid
flowchart TD
A["Nginx"] --> B["官网前台静态文件"]
A --> C["管理端静态文件 /admin"]
A --> D["NestJS API /api"]
D --> E[("PostgreSQL RDS")]
D --> F[("Redis 可选")]
D --> G[("Aliyun OSS")]
```
第一版可以不引入 Redis;当预览 token、短缓存、限流压力上来后再加入。
## 11. 安全要求
| 方向 | 要求 |
| --- | --- |
| 登录 | 密码 bcrypt/argon2 哈希,失败次数限制 |
| Token | 短期 access token,长期 refresh token 可撤销 |
| 文件上传 | 限制 MIME、扩展名、大小,禁止可执行文件 |
| OSS | 管理端上传用临时凭证,避免暴露永久密钥 |
| XSS | 富文本白名单清洗,前台渲染转义 |
| 操作日志 | 发布、下架、删除、评分锁定、结果发布必须记录 |
| 评审数据 | 评委只能访问分配给自己的作品 |
## 12. 和现有项目的衔接
| 当前能力 | 后续动作 |
| --- | --- |
| `admin.html` 简版后台 | 可保留用于联调,正式后台建议独立前端替换 |
| `AdminController` 已有作品/课程/文件接口 | 保留并扩展 DTO、权限、上传、图片附件接口 |
| `site_configs/home_sections` | 可继续承载官网首页数据,补版本和发布流程 |
| `competition_*` 表 | 扩展赛道页区块、资源类型、开放时间 |
| `work_votes` | 继续承载公众投票,不与评委评分混用 |
| `AdminUser/AdminRole` | 接入真实登录和 RBAC |
+201
View File
@@ -0,0 +1,201 @@
# E-R 图
## 1. 说明
以下 E-R 图以当前 `mlkj-website/backend/prisma/schema.prisma` 为基础,标注现有实体并补充管理端需要新增的内容版本、文件绑定和作品评选实体。
图中的 `CONTENT_PAGE`、`CONTENT_SECTION`、`CONTENT_REVISION`、`FILE_BINDING`、`JUDGE_PROFILE`、`EVALUATION_*` 为建议新增表;其他多数表在现有 Prisma schema 中已经存在。
## 2. 核心 E-R 图
```mermaid
erDiagram
ADMIN_USER ||--o{ ADMIN_USER_ROLE : has
ADMIN_ROLE ||--o{ ADMIN_USER_ROLE : grants
ADMIN_USER ||--o{ OPERATION_LOG : writes
ADMIN_USER ||--o{ FILE : uploads
ADMIN_USER ||--o| JUDGE_PROFILE : may_be
CONTENT_PAGE ||--o{ CONTENT_SECTION : contains
CONTENT_SECTION ||--o{ CONTENT_REVISION : versions
ADMIN_USER ||--o{ CONTENT_REVISION : edits
SITE_CONFIG ||--o{ CONTENT_REVISION : versioned_by
HOME_SECTION ||--o{ CONTENT_REVISION : versioned_by
COMPETITION ||--o{ COMPETITION_SCHEDULE : has
COMPETITION ||--o{ COMPETITION_RESOURCE : has
COMPETITION ||--o{ PARTNER : has
COMPETITION ||--o{ COURSE : has
COMPETITION ||--o{ WORK : has
COMPETITION ||--o{ CONTENT_SECTION : maps_to
FILE ||--o{ FILE_BINDING : binds
FILE ||--o{ COMPETITION_RESOURCE : used_by
FILE ||--o{ WORK_IMAGE : image_of
FILE ||--o{ WORK_FILE : file_of
FILE ||--o{ COURSE : media_of
WORK ||--o{ WORK_IMAGE : has
WORK ||--o{ WORK_FILE : has
WORK ||--o{ WORK_VOTE : receives
WORK ||--o{ EVALUATION_ASSIGNMENT : assigned
WORK ||--o{ EVALUATION_RESULT : results
EVALUATION_ROUND ||--o{ EVALUATION_CRITERION : defines
EVALUATION_ROUND ||--o{ EVALUATION_ASSIGNMENT : includes
EVALUATION_ROUND ||--o{ EVALUATION_RESULT : produces
JUDGE_PROFILE ||--o{ EVALUATION_ASSIGNMENT : receives
EVALUATION_ASSIGNMENT ||--o{ WORK_SCORE : has
EVALUATION_CRITERION ||--o{ WORK_SCORE : scores
```
## 3. 内容发布关系
```mermaid
erDiagram
CONTENT_PAGE ||--o{ CONTENT_SECTION : contains
CONTENT_SECTION ||--o{ CONTENT_REVISION : has
ADMIN_USER ||--o{ CONTENT_REVISION : edited_by
CONTENT_PAGE {
bigint id PK
string page_key UK
string page_name
string page_type
string lang
string status
}
CONTENT_SECTION {
bigint id PK
bigint page_id FK
string section_key
string title
string status
int sort_order
}
CONTENT_REVISION {
bigint id PK
bigint section_id FK
string revision_status
json content_snapshot
bigint created_by FK
datetime published_at
}
```
## 4. 文件与业务绑定关系
```mermaid
erDiagram
FILE ||--o{ FILE_BINDING : has
FILE_BINDING }o--|| ADMIN_USER : created_by
FILE {
bigint id PK
string file_key UK
string original_name
string url
string mime_type
bigint size
string scene
string status
}
FILE_BINDING {
bigint id PK
bigint file_id FK
string target_type
bigint target_id
string usage
int sort_order
}
```
`target_type` 示例:
| target_type | target_id 指向 |
| --- | --- |
| `home_section` | `home_sections.id` |
| `competition` | `competitions.id` |
| `competition_resource` | `competition_resources.id` |
| `course` | `courses.id` |
| `work` | `works.id` |
| `work_image` | `work_images.id` |
| `work_file` | `work_files.id` |
## 5. 作品评选关系
```mermaid
erDiagram
ADMIN_USER ||--o| JUDGE_PROFILE : owns
EVALUATION_ROUND ||--o{ EVALUATION_CRITERION : has
EVALUATION_ROUND ||--o{ EVALUATION_ASSIGNMENT : has
JUDGE_PROFILE ||--o{ EVALUATION_ASSIGNMENT : assigned
WORK ||--o{ EVALUATION_ASSIGNMENT : assigned
EVALUATION_ASSIGNMENT ||--o{ WORK_SCORE : scores
EVALUATION_CRITERION ||--o{ WORK_SCORE : criterion
EVALUATION_ROUND ||--o{ EVALUATION_RESULT : produces
WORK ||--o{ EVALUATION_RESULT : ranked
EVALUATION_ROUND {
bigint id PK
bigint competition_id FK
string name
string round_type
string status
decimal expert_weight
decimal public_vote_weight
}
EVALUATION_CRITERION {
bigint id PK
bigint round_id FK
string name
decimal max_score
decimal weight
}
EVALUATION_ASSIGNMENT {
bigint id PK
bigint round_id FK
bigint work_id FK
bigint judge_id FK
string status
}
WORK_SCORE {
bigint id PK
bigint assignment_id FK
bigint criterion_id FK
decimal score
string comment
}
EVALUATION_RESULT {
bigint id PK
bigint round_id FK
bigint work_id FK
decimal expert_score
decimal public_vote_score
decimal final_score
int rank
string award_level
}
```
## 6. 当前表与新增表清单
| 类型 | 表 | 状态 |
| --- | --- | --- |
| 站点配置 | `site_configs`、`home_sections` | 已存在,建议扩展版本能力 |
| 通用内容 | `content_pages`、`content_sections`、`content_revisions` | 建议新增 |
| 大赛 | `competitions`、`competition_schedules`、`competition_resources`、`partners` | 已存在,建议扩展字段 |
| 作品 | `works`、`work_images`、`work_files`、`work_votes` | 已存在,建议扩展评审状态 |
| 课程 | `courses` | 已存在,建议扩展文件关联 |
| 文件 | `files` | 已存在,建议扩展上传人、场景、状态 |
| 文件绑定 | `file_bindings` | 建议新增 |
| 评选 | `judge_profiles`、`evaluation_rounds`、`evaluation_criteria`、`evaluation_assignments`、`work_scores`、`evaluation_results` | 建议新增 |
| 权限日志 | `admin_users`、`admin_roles`、`admin_user_roles`、`operation_logs` | 已存在,建议接入真实鉴权 |
+315
View File
@@ -0,0 +1,315 @@
# 数据库字段设计
## 1. 设计策略
1. 优先复用当前 Prisma 已有表。
2. 新增表集中解决三个缺口:通用内容版本、文件业务绑定、作品评选。
3. 不把文件内容写入数据库,只保存 OSS 元信息和业务关系。
4. 前台高频读取字段尽量保留在业务主表,历史版本放 `content_revisions`。
## 2. 枚举
### 2.1 发布状态
| 值 | 说明 |
| --- | --- |
| `draft` | 草稿 |
| `published` | 已发布 |
| `disabled` | 已下架 |
| `archived` | 已归档 |
### 2.2 文件状态
| 值 | 说明 |
| --- | --- |
| `active` | 正常 |
| `unused` | 未绑定 |
| `archived` | 已归档 |
| `deleted` | 已逻辑删除 |
### 2.3 评审轮次状态
| 值 | 说明 |
| --- | --- |
| `draft` | 未开始 |
| `open` | 可评分 |
| `closed` | 已结束 |
| `locked` | 已锁定 |
| `published` | 结果已发布 |
### 2.4 评分任务状态
| 值 | 说明 |
| --- | --- |
| `assigned` | 已分配 |
| `scoring` | 评分中 |
| `submitted` | 已提交 |
| `locked` | 已锁定 |
## 3. 现有表扩展建议
### 3.1 `files`
现有字段已包含 `fileKey`、`originalName`、`url`、`mimeType`、`extension`、`size`、`width`、`height`、`duration`、`storageProvider`、`createdAt`。
建议新增:
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `scene` | `varchar(80)` | 否 | `site`、`competition`、`course`、`work`、`resource` |
| `file_category` | `varchar(50)` | 否 | `image`、`video`、`model`、`document`、`archive` |
| `checksum` | `varchar(128)` | 否 | 文件 hash,用于去重 |
| `uploaded_by` | `bigint` | 否 | 上传管理员 ID |
| `status` | `varchar(32)` | 是 | 默认 `active` |
| `updated_at` | `timestamp` | 是 | 更新时间 |
### 3.2 `competition_resources`
建议新增:
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `resource_type` | `varchar(50)` | 是 | `pdf`、`zip`、`image`、`link`、`video` |
| `category` | `varchar(80)` | 否 | 资源分类,如设计模板、文化资源、提交规范 |
| `external_url` | `varchar(500)` | 否 | 外部资源链接 |
| `open_at` | `timestamp` | 否 | 开放下载时间 |
| `close_at` | `timestamp` | 否 | 关闭下载时间 |
### 3.3 `courses`
建议新增:
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `cover_file_id` | `bigint` | 否 | 课程封面文件 |
| `video_file_id` | `bigint` | 否 | OSS 视频文件 |
| `external_video_url` | `varchar(500)` | 否 | 外部视频链接 |
| `speaker` | `varchar(255)` | 否 | 主讲人 |
| `source_type` | `varchar(32)` | 是 | `oss` 或 `external` |
### 3.4 `works`
建议新增:
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `material_status` | `varchar(40)` | 是 | `pending_submit`、`submitted`、`qualified`、`rejected` |
| `review_status` | `varchar(40)` | 是 | `none`、`reviewing`、`finalist`、`winner`、`rejected` |
| `featured` | `boolean` | 是 | 是否精选展示 |
| `award_level` | `varchar(80)` | 否 | 奖项等级 |
| `cover_file_id` | `bigint` | 否 | 封面文件 |
| `model_file_id` | `bigint` | 否 | 主模型文件 |
## 4. 新增内容表
### 4.1 `content_pages`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `bigint` | 是 | 主键 |
| `page_key` | `varchar(100)` | 是 | 页面唯一键,如 `home`、`competition-smart-fashion` |
| `page_name` | `varchar(255)` | 是 | 页面名称 |
| `page_type` | `varchar(50)` | 是 | `site`、`competition`、`landing` |
| `business_id` | `bigint` | 否 | 关联业务 ID,如 competitionId |
| `lang` | `varchar(20)` | 是 | 默认 `zh-CN` |
| `seo` | `jsonb` | 否 | SEO 信息 |
| `status` | `PublishStatus` | 是 | 发布状态 |
| `created_at` | `timestamp` | 是 | 创建时间 |
| `updated_at` | `timestamp` | 是 | 更新时间 |
索引:
| 索引 | 字段 |
| --- | --- |
| 唯一 | `page_key`, `lang` |
| 普通 | `page_type`, `business_id`, `status` |
### 4.2 `content_sections`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `bigint` | 是 | 主键 |
| `page_id` | `bigint` | 是 | `content_pages.id` |
| `section_key` | `varchar(100)` | 是 | 区块键,如 `hero`、`business`、`awards` |
| `section_name` | `varchar(255)` | 是 | 区块显示名 |
| `title` | `varchar(255)` | 否 | 标题 |
| `subtitle` | `varchar(500)` | 否 | 副标题 |
| `content` | `jsonb` | 是 | 已发布内容 |
| `draft_content` | `jsonb` | 否 | 草稿内容 |
| `schema` | `jsonb` | 否 | 表单 schema |
| `sort_order` | `int` | 是 | 排序 |
| `status` | `PublishStatus` | 是 | 状态 |
| `published_at` | `timestamp` | 否 | 发布时间 |
| `created_at` | `timestamp` | 是 | 创建时间 |
| `updated_at` | `timestamp` | 是 | 更新时间 |
索引:
| 索引 | 字段 |
| --- | --- |
| 唯一 | `page_id`, `section_key` |
| 普通 | `status`, `sort_order` |
### 4.3 `content_revisions`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `bigint` | 是 | 主键 |
| `section_id` | `bigint` | 是 | `content_sections.id` |
| `revision_no` | `int` | 是 | 版本号 |
| `revision_status` | `varchar(32)` | 是 | `draft`、`published`、`rollback` |
| `content_snapshot` | `jsonb` | 是 | 内容快照 |
| `created_by` | `bigint` | 否 | 操作人 |
| `publish_note` | `varchar(500)` | 否 | 发布说明 |
| `published_at` | `timestamp` | 否 | 发布时间 |
| `created_at` | `timestamp` | 是 | 创建时间 |
索引:
| 索引 | 字段 |
| --- | --- |
| 唯一 | `section_id`, `revision_no` |
| 普通 | `revision_status`, `created_by`, `created_at` |
## 5. 文件绑定表
### 5.1 `file_bindings`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `bigint` | 是 | 主键 |
| `file_id` | `bigint` | 是 | `files.id` |
| `target_type` | `varchar(80)` | 是 | 业务类型 |
| `target_id` | `bigint` | 是 | 业务 ID |
| `usage` | `varchar(80)` | 是 | `cover`、`gallery`、`video`、`model`、`attachment`、`logo` |
| `sort_order` | `int` | 是 | 排序 |
| `created_by` | `bigint` | 否 | 操作人 |
| `created_at` | `timestamp` | 是 | 创建时间 |
索引:
| 索引 | 字段 |
| --- | --- |
| 普通 | `file_id` |
| 普通 | `target_type`, `target_id` |
| 普通 | `usage`, `sort_order` |
## 6. 评选相关表
### 6.1 `judge_profiles`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `bigint` | 是 | 主键 |
| `admin_user_id` | `bigint` | 是 | 关联管理员账号 |
| `name` | `varchar(100)` | 是 | 评委姓名 |
| `organization` | `varchar(255)` | 否 | 所属单位 |
| `title` | `varchar(120)` | 否 | 职称/身份 |
| `phone` | `varchar(50)` | 否 | 联系电话 |
| `email` | `varchar(120)` | 否 | 邮箱 |
| `status` | `varchar(32)` | 是 | `enabled`、`disabled` |
| `created_at` | `timestamp` | 是 | 创建时间 |
| `updated_at` | `timestamp` | 是 | 更新时间 |
### 6.2 `evaluation_rounds`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `bigint` | 是 | 主键 |
| `competition_id` | `bigint` | 是 | 大赛 ID |
| `name` | `varchar(120)` | 是 | 轮次名称 |
| `round_type` | `varchar(50)` | 是 | `preliminary`、`semi_final`、`final` |
| `description` | `text` | 否 | 说明 |
| `expert_weight` | `decimal(5,2)` | 是 | 评委分权重,默认 80 |
| `public_vote_weight` | `decimal(5,2)` | 是 | 公众投票权重,默认 20 |
| `start_at` | `timestamp` | 否 | 开始时间 |
| `end_at` | `timestamp` | 否 | 结束时间 |
| `status` | `varchar(32)` | 是 | 轮次状态 |
| `created_by` | `bigint` | 否 | 创建人 |
| `created_at` | `timestamp` | 是 | 创建时间 |
| `updated_at` | `timestamp` | 是 | 更新时间 |
### 6.3 `evaluation_criteria`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `bigint` | 是 | 主键 |
| `round_id` | `bigint` | 是 | 评审轮次 |
| `name` | `varchar(120)` | 是 | 指标名称 |
| `description` | `varchar(500)` | 否 | 指标说明 |
| `max_score` | `decimal(6,2)` | 是 | 满分 |
| `weight` | `decimal(5,2)` | 是 | 权重 |
| `sort_order` | `int` | 是 | 排序 |
| `created_at` | `timestamp` | 是 | 创建时间 |
| `updated_at` | `timestamp` | 是 | 更新时间 |
### 6.4 `evaluation_assignments`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `bigint` | 是 | 主键 |
| `round_id` | `bigint` | 是 | 评审轮次 |
| `work_id` | `bigint` | 是 | 作品 ID |
| `judge_id` | `bigint` | 是 | 评委 ID |
| `status` | `varchar(32)` | 是 | 评分任务状态 |
| `submitted_at` | `timestamp` | 否 | 提交时间 |
| `locked_at` | `timestamp` | 否 | 锁定时间 |
| `created_at` | `timestamp` | 是 | 创建时间 |
| `updated_at` | `timestamp` | 是 | 更新时间 |
约束:
| 约束 | 字段 |
| --- | --- |
| 唯一 | `round_id`, `work_id`, `judge_id` |
### 6.5 `work_scores`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `bigint` | 是 | 主键 |
| `assignment_id` | `bigint` | 是 | 评分任务 |
| `criterion_id` | `bigint` | 是 | 评分指标 |
| `score` | `decimal(6,2)` | 是 | 得分 |
| `comment` | `text` | 否 | 指标评语 |
| `created_at` | `timestamp` | 是 | 创建时间 |
| `updated_at` | `timestamp` | 是 | 更新时间 |
约束:
| 约束 | 字段 |
| --- | --- |
| 唯一 | `assignment_id`, `criterion_id` |
### 6.6 `evaluation_results`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `bigint` | 是 | 主键 |
| `round_id` | `bigint` | 是 | 评审轮次 |
| `work_id` | `bigint` | 是 | 作品 ID |
| `expert_score` | `decimal(8,2)` | 是 | 评委加权分 |
| `public_vote_score` | `decimal(8,2)` | 是 | 投票折算分 |
| `final_score` | `decimal(8,2)` | 是 | 最终分 |
| `rank` | `int` | 否 | 排名 |
| `result_status` | `varchar(40)` | 是 | `pending`、`finalist`、`winner`、`rejected` |
| `award_level` | `varchar(80)` | 否 | 特等奖、一等奖等 |
| `published_at` | `timestamp` | 否 | 结果发布时间 |
| `created_at` | `timestamp` | 是 | 创建时间 |
| `updated_at` | `timestamp` | 是 | 更新时间 |
约束:
| 约束 | 字段 |
| --- | --- |
| 唯一 | `round_id`, `work_id` |
## 7. 字段落地优先级
| 优先级 | 表 |
| --- | --- |
| P0 | `files` 扩展、`file_bindings`、`content_pages`、`content_sections`、`content_revisions` |
| P0 | `works` 扩展、`courses` 扩展、`competition_resources` 扩展 |
| P0 | `judge_profiles`、`evaluation_rounds`、`evaluation_criteria`、`evaluation_assignments`、`work_scores`、`evaluation_results` |
| P1 | 管理员真实 RBAC、操作日志细化、导出记录 |
| P2 | 内容审批流、文件物理删除任务、视频 VOD 字段 |
+242
View File
@@ -0,0 +1,242 @@
# API 接口设计
## 1. 设计说明
接口设计遵循当前 `mlkj-website/backend` 的风格:
1. 公开接口使用 `/api/site`、`/api/competition`、`/api/works`、`/api/courses`。
2. 后台接口统一使用 `/api/admin`。
3. 返回结构继续使用 `ApiResult` 风格。
4. 后台写接口必须带 JWT,并校验权限码。
5. Swagger 设计稿见 [swagger/openapi.yaml](swagger/openapi.yaml)。
## 2. 通用响应
成功:
```json
{
"code": 0,
"message": "ok",
"data": {}
}
```
分页:
```json
{
"code": 0,
"message": "ok",
"data": {
"list": [],
"page": 1,
"pageSize": 20,
"total": 100
}
}
```
失败:
```json
{
"code": 40001,
"message": "无权限",
"data": null
}
```
## 3. 权限分组
| 模块 | 权限码 |
| --- | --- |
| 登录 | 无 |
| 控制台 | `dashboard:read` |
| 官网内容 | `site:read`、`site:write`、`site:publish` |
| 赛道内容 | `competition:read`、`competition:write`、`competition:publish` |
| 素材库 | `file:read`、`file:upload`、`file:archive` |
| 课程 | `course:read`、`course:write`、`course:publish` |
| 作品 | `work:read`、`work:write`、`work:publish` |
| 评选 | `evaluation:manage`、`evaluation:score` |
| 线索 | `inquiry:read`、`inquiry:write` |
| 系统 | `system:manage` |
## 4. 后台接口分组
### 4.1 鉴权
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `POST` | `/api/admin/auth/login` | 登录 |
| `POST` | `/api/admin/auth/refresh` | 刷新 token |
| `POST` | `/api/admin/auth/logout` | 退出 |
| `GET` | `/api/admin/me` | 当前用户信息 |
### 4.2 内容管理
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/admin/site/config` | 获取站点配置 |
| `PATCH` | `/api/admin/site/config` | 更新站点配置草稿 |
| `GET` | `/api/admin/content/pages/:pageKey/sections` | 获取页面区块 |
| `POST` | `/api/admin/content/pages/:pageKey/sections` | 新建区块 |
| `GET` | `/api/admin/content/sections/:id` | 区块详情 |
| `PATCH` | `/api/admin/content/sections/:id` | 更新区块草稿 |
| `POST` | `/api/admin/content/sections/:id/publish` | 发布区块 |
| `DELETE` | `/api/admin/content/sections/:id` | 归档区块 |
### 4.3 赛道管理
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/admin/competitions` | 赛道列表 |
| `POST` | `/api/admin/competitions` | 新建赛道 |
| `GET` | `/api/admin/competitions/:id` | 赛道详情 |
| `PATCH` | `/api/admin/competitions/:id` | 更新赛道 |
| `GET` | `/api/admin/competitions/:id/schedules` | 赛程列表 |
| `POST` | `/api/admin/competitions/:id/schedules` | 新建赛程 |
| `PATCH` | `/api/admin/competition-schedules/:id` | 更新赛程 |
| `DELETE` | `/api/admin/competition-schedules/:id` | 删除赛程 |
| `GET` | `/api/admin/competitions/:id/resources` | 资源列表 |
| `POST` | `/api/admin/competitions/:id/resources` | 新建资源 |
| `PATCH` | `/api/admin/competition-resources/:id` | 更新资源 |
| `DELETE` | `/api/admin/competition-resources/:id` | 删除资源 |
### 4.4 素材上传
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `POST` | `/api/admin/uploads/policy` | 获取 OSS 上传凭证 |
| `POST` | `/api/admin/uploads/complete` | 上传完成登记 |
| `GET` | `/api/admin/files` | 文件列表 |
| `GET` | `/api/admin/files/:id` | 文件详情 |
| `PATCH` | `/api/admin/files/:id` | 更新文件元信息 |
| `POST` | `/api/admin/files/:id/archive` | 归档文件 |
### 4.5 课程视频
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/admin/courses` | 课程列表 |
| `POST` | `/api/admin/courses` | 新建课程 |
| `GET` | `/api/admin/courses/:id` | 课程详情 |
| `PATCH` | `/api/admin/courses/:id` | 更新课程 |
| `PATCH` | `/api/admin/courses/:id/status` | 更新状态 |
| `DELETE` | `/api/admin/courses/:id` | 删除课程 |
### 4.6 作品
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/admin/works` | 作品列表 |
| `POST` | `/api/admin/works` | 新建作品 |
| `GET` | `/api/admin/works/:id` | 作品详情 |
| `PATCH` | `/api/admin/works/:id` | 更新作品 |
| `PATCH` | `/api/admin/works/:id/status` | 更新发布状态 |
| `POST` | `/api/admin/works/:id/images` | 添加作品图片 |
| `DELETE` | `/api/admin/work-images/:id` | 删除作品图片 |
| `POST` | `/api/admin/works/:id/files` | 添加作品附件 |
| `DELETE` | `/api/admin/work-files/:id` | 删除作品附件 |
| `DELETE` | `/api/admin/works/:id` | 删除作品 |
### 4.7 评选
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/admin/evaluation/rounds` | 评审轮次列表 |
| `POST` | `/api/admin/evaluation/rounds` | 创建评审轮次 |
| `GET` | `/api/admin/evaluation/rounds/:id` | 轮次详情 |
| `PATCH` | `/api/admin/evaluation/rounds/:id` | 更新轮次 |
| `POST` | `/api/admin/evaluation/rounds/:id/lock` | 锁定轮次 |
| `GET` | `/api/admin/evaluation/rounds/:id/criteria` | 指标列表 |
| `POST` | `/api/admin/evaluation/rounds/:id/criteria` | 创建指标 |
| `GET` | `/api/admin/evaluation/rounds/:id/assignments` | 任务列表 |
| `POST` | `/api/admin/evaluation/rounds/:id/assignments` | 分配作品 |
| `GET` | `/api/admin/evaluation/my-assignments` | 评委查看自己的任务 |
| `POST` | `/api/admin/evaluation/assignments/:id/scores` | 提交评分 |
| `GET` | `/api/admin/evaluation/rounds/:id/results` | 查看结果汇总 |
| `POST` | `/api/admin/evaluation/rounds/:id/results/calculate` | 重新计算排名 |
| `POST` | `/api/admin/evaluation/rounds/:id/results/publish` | 发布结果 |
### 4.8 咨询线索
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/admin/inquiries` | 线索列表 |
| `GET` | `/api/admin/inquiries/:id` | 线索详情 |
| `PATCH` | `/api/admin/inquiries/:id/status` | 更新状态 |
| `PATCH` | `/api/admin/inquiries/:id/remark` | 更新备注 |
## 5. 公开接口扩展
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/site/config` | 官网基础配置 |
| `GET` | `/api/site/home` | 官网首页区块 |
| `GET` | `/api/competition` | 赛道页聚合数据 |
| `GET` | `/api/competition/schedule` | 赛程 |
| `GET` | `/api/competition/resources` | 资源包 |
| `GET` | `/api/courses` | 课程列表 |
| `GET` | `/api/courses/:id` | 课程详情 |
| `GET` | `/api/works` | 作品列表 |
| `GET` | `/api/works/:id` | 作品详情 |
| `POST` | `/api/works/:id/vote` | 公众投票 |
## 6. 上传接口约定
### 6.1 获取上传凭证
请求:
```json
{
"fileName": "cover.png",
"mimeType": "image/png",
"size": 204800,
"scene": "work",
"usage": "cover"
}
```
返回:
```json
{
"uploadUrl": "https://oss.example.com",
"method": "POST",
"fileKey": "mlkj-website/works/covers/2026/06/xxx.png",
"formData": {
"policy": "...",
"signature": "..."
},
"expiresAt": "2026-06-29T12:00:00.000Z"
}
```
### 6.2 上传完成登记
请求:
```json
{
"fileKey": "mlkj-website/works/covers/2026/06/xxx.png",
"originalName": "cover.png",
"url": "https://cdn.example.com/mlkj-website/works/covers/2026/06/xxx.png",
"mimeType": "image/png",
"extension": "png",
"size": 204800,
"width": 1200,
"height": 800,
"scene": "work",
"fileCategory": "image"
}
```
## 7. Swagger
完整 Swagger 设计稿位于:
```text
docs/swagger/openapi.yaml
```
+118
View File
@@ -0,0 +1,118 @@
# 路由设计
## 1. 管理端路由约定
| 类型 | 约定 |
| --- | --- |
| 登录页 | `/login` |
| 后台首页 | `/dashboard` |
| 业务页面 | 使用一级模块加二级路径 |
| 新建页 | `/new` |
| 编辑页 | `/:id/edit` |
| 详情页 | `/:id` |
| 评委端 | `/judge/*` |
## 2. 管理端菜单与路由
| 菜单 | 路由 | 页面 | 权限 |
| --- | --- | --- | --- |
| 登录 | `/login` | 登录页 | 无 |
| 控制台 | `/dashboard` | 数据概览 | `dashboard:read` |
| 官网内容/站点配置 | `/site/config` | 站点配置 | `site:read` |
| 官网内容/首页区块 | `/site/home` | 首页内容区块 | `site:read` |
| 官网内容/客户案例 | `/site/cases` | 案例管理 | `site:read` |
| 赛道内容/基础信息 | `/competition/basic` | 赛道基础信息 | `competition:read` |
| 赛道内容/页面区块 | `/competition/sections` | 大赛介绍、赛事说明等 | `competition:read` |
| 赛道内容/赛程安排 | `/competition/schedules` | 赛程管理 | `competition:read` |
| 赛道内容/参考资源 | `/competition/resources` | 资源包管理 | `competition:read` |
| 赛道内容/合作伙伴 | `/competition/partners` | 合作伙伴 | `competition:read` |
| 赛道内容/大赛动态 | `/competition/news` | 通知动态 | `competition:read` |
| 素材库 | `/media/files` | 文件列表 | `file:read` |
| 素材上传 | `/media/upload` | 上传中心 | `file:upload` |
| 视频/课程 | `/courses` | 课程列表 | `course:read` |
| 新建课程 | `/courses/new` | 新建课程 | `course:write` |
| 编辑课程 | `/courses/:id/edit` | 编辑课程 | `course:write` |
| 作品管理 | `/works` | 作品列表 | `work:read` |
| 新建作品 | `/works/new` | 新建作品 | `work:write` |
| 作品详情 | `/works/:id` | 作品详情 | `work:read` |
| 编辑作品 | `/works/:id/edit` | 编辑作品 | `work:write` |
| 作品素材 | `/works/:id/materials` | 图片、模型、附件 | `work:write` |
| 批量导入 | `/works/import` | 批量导入 | `work:write` |
| 评审轮次 | `/evaluation/rounds` | 轮次列表 | `evaluation:manage` |
| 新建轮次 | `/evaluation/rounds/new` | 创建轮次 | `evaluation:manage` |
| 轮次详情 | `/evaluation/rounds/:id` | 进度、指标、分配 | `evaluation:manage` |
| 评分结果 | `/evaluation/rounds/:id/results` | 汇总和发布 | `evaluation:manage` |
| 评委管理 | `/evaluation/judges` | 评委账号 | `evaluation:manage` |
| 我的评审 | `/judge/assignments` | 评委任务 | `evaluation:score` |
| 评委评分 | `/judge/assignments/:id` | 评分页 | `evaluation:score` |
| 咨询线索 | `/inquiries` | 线索列表 | `inquiry:read` |
| 线索详情 | `/inquiries/:id` | 线索详情 | `inquiry:read` |
| 系统/用户 | `/system/users` | 管理员账号 | `system:manage` |
| 系统/角色 | `/system/roles` | 角色权限 | `system:manage` |
| 系统/日志 | `/system/logs` | 操作日志 | `system:manage` |
## 3. 页面状态路由
| 场景 | 路由 |
| --- | --- |
| 无权限 | `/403` |
| 页面不存在 | `/404` |
| Token 过期 | 重定向 `/login?redirect=<current>` |
| 草稿预览 | `/preview/:pageKey?token=<previewToken>` |
## 4. 路由守卫
```mermaid
flowchart TD
A["进入路由"] --> B{"是否公开路由"}
B -- "是" --> C["渲染页面"]
B -- "否" --> D{"是否有 token"}
D -- "否" --> E["跳转 /login"]
D -- "是" --> F["请求 /api/admin/me"]
F --> G{"权限是否匹配"}
G -- "是" --> C
G -- "否" --> H["跳转 /403"]
```
## 5. 页面和 API 映射
| 页面 | 主要 API |
| --- | --- |
| `/dashboard` | `GET /api/admin/dashboard` |
| `/site/config` | `GET/PATCH /api/admin/site/config` |
| `/site/home` | `GET /api/admin/content/pages/home/sections`、`PATCH /api/admin/content/sections/:id` |
| `/competition/basic` | `GET/PATCH /api/admin/competitions/:id` |
| `/competition/sections` | `GET /api/admin/competitions/:id/sections`、`PATCH /api/admin/content/sections/:id` |
| `/competition/schedules` | `GET/POST /api/admin/competitions/:id/schedules` |
| `/competition/resources` | `GET/POST /api/admin/competitions/:id/resources` |
| `/media/files` | `GET /api/admin/files` |
| `/media/upload` | `POST /api/admin/uploads/policy`、`POST /api/admin/uploads/complete` |
| `/courses` | `GET /api/admin/courses` |
| `/courses/:id/edit` | `GET/PATCH /api/admin/courses/:id` |
| `/works` | `GET /api/admin/works` |
| `/works/:id/edit` | `GET/PATCH /api/admin/works/:id` |
| `/evaluation/rounds` | `GET /api/admin/evaluation/rounds` |
| `/evaluation/rounds/:id` | `GET/PATCH /api/admin/evaluation/rounds/:id` |
| `/evaluation/rounds/:id/results` | `GET /api/admin/evaluation/rounds/:id/results` |
| `/judge/assignments` | `GET /api/admin/evaluation/my-assignments` |
| `/judge/assignments/:id` | `POST /api/admin/evaluation/assignments/:id/scores` |
| `/inquiries` | `GET /api/admin/inquiries` |
## 6. 前台路由映射
当前前台仍保持静态路径:
| 页面 | 路径 | 数据来源 |
| --- | --- | --- |
| 官网首页 | `/`、`/index.html` | `/api/site/config`、`/api/site/home` |
| 赛道页 | `/competition.html` | `/api/competition` |
| 作品详情 | `/work-detail.html?id=SMT-2026-018` | `/api/works/:id` |
| 课程详情 | `/course-detail.html?type=roadshow&id=rs-01` | `/api/courses/:id` |
后续如改为 SPA 或 SSR,可映射为:
| 新路径 | 说明 |
| --- | --- |
| `/competition/smart-fashion` | 赛道页 |
| `/works/:workNo` | 作品详情 |
| `/courses/:courseNo` | 课程详情 |
+308
View File
@@ -0,0 +1,308 @@
# 详细开发计划
## 1. 开发目标
建设一个可正式运营的 PC 管理端,用于管理模灵科技公司官网和「智·造新时尚」赛道页内容,覆盖官网文案、图片素材、赛道资源、视频课程、作品管理、作品评选和咨询线索。
## 2. 开发原则
1. 先完成 P0 闭环,再补 P1/P2 能力。
2. 保持前台视觉不大改,优先把静态内容切到 API。
3. 管理端和前台解耦,后台 API 作为唯一数据源。
4. 所有发布到前台的内容都必须有草稿、预览、发布、下架能力。
5. 所有高风险操作必须记录操作日志。
## 3. 里程碑总览
| 阶段 | 名称 | 预计周期 | 目标 |
| --- | --- | --- | --- |
| M0 | 项目准备 | 1-2 天 | 明确工程结构、环境、任务拆分 |
| M1 | 后台基础工程 | 4-6 天 | 登录、权限、布局、控制台、API 基础 |
| M2 | 素材与内容管理 | 7-10 天 | 文件上传、官网内容、赛道内容、草稿发布 |
| M3 | 作品与课程管理 | 7-10 天 | 作品、图片、模型、附件、课程视频完整 CRUD |
| M4 | 作品评选 | 10-14 天 | 评审轮次、评委、指标、评分、排名、结果 |
| M5 | 前台数据接入 | 5-8 天 | 官网和赛道页读取真实发布数据 |
| M6 | 测试上线 | 5-7 天 | 联调、测试、部署、数据初始化 |
## 4. M0 项目准备
### 4.1 工作内容
| 类型 | 任务 |
| --- | --- |
| 工程 | 确认管理端前端放在 `mlkj-website/admin`、`frontend-admin` 或独立仓库 |
| 环境 | 准备 Node.js、PostgreSQL、OSS 测试 bucket、环境变量 |
| 任务 | 按模块拆分 issue:auth、content、media、works、courses、evaluation |
| 数据 | 确认当前静态文案、图片、作品、课程需要迁移的范围 |
| 规范 | 确认代码规范、接口规范、分支规范、发布流程 |
### 4.2 交付物
| 交付物 | 说明 |
| --- | --- |
| 工程目录结构 | 管理端前端和后端模块位置确定 |
| `.env.example` | 补齐数据库、JWT、OSS、CDN、管理员初始账号 |
| 任务拆分表 | 每个阶段的任务、负责人、依赖、验收 |
| 初始化数据清单 | 需要从 HTML/JSON 迁移到数据库的内容 |
### 4.3 验收标准
1. 本地前台、后端、数据库可启动。
2. Swagger 可访问。
3. Prisma schema 可 validate。
4. OSS 测试凭证可生成或已确定 mock 方案。
## 5. M1 后台基础工程
### 5.1 后端任务
| 编号 | 任务 | 说明 |
| --- | --- | --- |
| BE-M1-01 | 接入真实管理员登录 | 使用 `admin_users`,密码哈希,不再只依赖 `.env` 密码 |
| BE-M1-02 | JWT 鉴权 | access token + refresh token |
| BE-M1-03 | RBAC 权限 | 接入 `admin_roles.permissions` |
| BE-M1-04 | 管理端 Guard | 统一校验登录和权限码 |
| BE-M1-05 | 控制台接口 | 返回作品、课程、文件、线索、待评数据 |
| BE-M1-06 | 操作日志基础 | 写入登录、发布、删除、状态变更 |
| BE-M1-07 | Swagger 整理 | 所有后台接口有 tag、summary、DTO |
### 5.2 前端任务
| 编号 | 任务 | 说明 |
| --- | --- | --- |
| FE-M1-01 | 管理端脚手架 | Vite + TypeScript + 路由 + UI 组件库 |
| FE-M1-02 | 登录页 | 账号密码登录、错误提示、token 保存 |
| FE-M1-03 | 路由守卫 | 未登录跳登录、无权限跳 403 |
| FE-M1-04 | 基础布局 | 左侧菜单、顶部栏、用户菜单、内容区 |
| FE-M1-05 | 控制台 | KPI、待办、快捷入口、最近操作 |
| FE-M1-06 | API Client | 统一请求、错误拦截、token 刷新 |
### 5.3 数据库任务
| 编号 | 任务 |
| --- | --- |
| DB-M1-01 | 为 `admin_users` 添加初始超级管理员 seed |
| DB-M1-02 | 建立默认角色和权限 seed |
| DB-M1-03 | 如需要,新增 `admin_sessions` 或 refresh token 表 |
### 5.4 验收标准
1. 管理员可登录、退出、刷新页面后保持会话。
2. 不同角色看到不同菜单。
3. 未授权访问后台接口返回 401 或 403。
4. 控制台数据可正常展示。
## 6. M2 素材与内容管理
### 6.1 后端任务
| 编号 | 任务 | 说明 |
| --- | --- | --- |
| BE-M2-01 | 文件上传凭证 | `POST /admin/uploads/policy` |
| BE-M2-02 | 上传完成登记 | `POST /admin/uploads/complete` 写入 `files` |
| BE-M2-03 | 文件列表与筛选 | 支持场景、类型、关键词、分页 |
| BE-M2-04 | 文件绑定 | 新增 `file_bindings` |
| BE-M2-05 | 内容页面表 | 新增 `content_pages`、`content_sections`、`content_revisions` |
| BE-M2-06 | 官网内容接口 | 站点配置、首页区块草稿/发布 |
| BE-M2-07 | 赛道内容接口 | 基础信息、介绍、奖项、要求、须知、资源 |
| BE-M2-08 | 预览接口 | 支持读取草稿内容 |
### 6.2 前端任务
| 编号 | 任务 | 说明 |
| --- | --- | --- |
| FE-M2-01 | 文件库列表 | 缩略图、文件信息、筛选、复制 URL |
| FE-M2-02 | 上传组件 | 拖拽上传、进度、失败重试 |
| FE-M2-03 | 文件选择器 | 在表单中复用,支持单选/多选 |
| FE-M2-04 | 官网内容表单 | Hero、业务版图、产品矩阵、案例、咨询 |
| FE-M2-05 | 赛道内容表单 | Hero、介绍、赛程、赛事说明、资源、伙伴 |
| FE-M2-06 | 草稿发布操作 | 保存草稿、预览、发布、下架 |
### 6.3 数据库任务
| 编号 | 任务 |
| --- | --- |
| DB-M2-01 | 迁移 `files` 扩展字段 |
| DB-M2-02 | 新增 `file_bindings` |
| DB-M2-03 | 新增内容版本相关表 |
| DB-M2-04 | 初始化官网和赛道页默认区块数据 |
### 6.4 验收标准
1. 上传图片后可在文件库看到,并可绑定到官网 Hero。
2. 修改官网 Hero 文案,发布后前台接口返回新内容。
3. 修改赛道页赛程和资源,发布后前台接口返回新内容。
4. 草稿内容未发布前不影响前台。
## 7. M3 作品与课程管理
### 7.1 后端任务
| 编号 | 任务 | 说明 |
| --- | --- | --- |
| BE-M3-01 | 扩展课程 DTO | 支持封面文件、视频文件、外部链接、主讲人 |
| BE-M3-02 | 课程 CRUD | 列表、详情、新增、编辑、上下架 |
| BE-M3-03 | 扩展作品 DTO | 支持材料状态、评审状态、精选、附件 |
| BE-M3-04 | 作品 CRUD | 列表、详情、新增、编辑、删除 |
| BE-M3-05 | 作品图片接口 | 添加、排序、删除图片 |
| BE-M3-06 | 作品附件接口 | 模型、PDF、ZIP、说明书 |
| BE-M3-07 | 批量导入预留 | CSV/XLSX 可 P1 实现 |
### 7.2 前端任务
| 编号 | 任务 | 说明 |
| --- | --- | --- |
| FE-M3-01 | 课程列表 | 类型、状态、关键词筛选 |
| FE-M3-02 | 课程编辑 | 封面、视频、外链、详情、发布状态 |
| FE-M3-03 | 作品列表 | 搜索、筛选、批量操作、状态标识 |
| FE-M3-04 | 作品编辑 | 基础信息、AIGC、提示词、设计参数 |
| FE-M3-05 | 作品素材 | 封面、图集、模型、附件 |
| FE-M3-06 | 作品详情预览 | 后台查看前台展示效果 |
### 7.3 数据库任务
| 编号 | 任务 |
| --- | --- |
| DB-M3-01 | 扩展 `courses` 文件关联字段 |
| DB-M3-02 | 扩展 `works` 材料状态、评审状态、精选字段 |
| DB-M3-03 | 为作品列表常用筛选添加索引 |
### 7.4 验收标准
1. 新建课程并发布后,赛道页在线学习和课程详情页可读取。
2. 新建作品并发布后,作品列表和详情页可读取。
3. 作品封面、图集、模型、附件均能上传和展示。
4. 下架作品不在前台列表展示。
## 8. M4 作品评选
### 8.1 后端任务
| 编号 | 任务 | 说明 |
| --- | --- | --- |
| BE-M4-01 | 评委资料 | `judge_profiles` |
| BE-M4-02 | 评审轮次 | 初评、复评、决赛 |
| BE-M4-03 | 评分指标 | 指标、满分、权重、排序 |
| BE-M4-04 | 评分任务 | 作品分配给评委 |
| BE-M4-05 | 评委评分 | 暂存、提交、锁定 |
| BE-M4-06 | 结果计算 | 专家分、公众分、最终分、排名 |
| BE-M4-07 | 结果发布 | 写入 `evaluation_results` 并同步作品获奖状态 |
| BE-M4-08 | 导出预留 | 评分表导出可 P1 实现 |
### 8.2 前端任务
| 编号 | 任务 | 说明 |
| --- | --- | --- |
| FE-M4-01 | 轮次管理 | 创建、编辑、开启、关闭、锁定 |
| FE-M4-02 | 指标配置 | 动态增删指标,权重校验 |
| FE-M4-03 | 评委管理 | 评委账号和资料 |
| FE-M4-04 | 作品分配 | 手动选择、批量分配 |
| FE-M4-05 | 评分进度 | 按评委、作品、状态查看 |
| FE-M4-06 | 评委端评分页 | 作品详情、附件、评分表单 |
| FE-M4-07 | 结果汇总页 | 排名、分数、获奖等级、发布 |
### 8.3 数据库任务
| 编号 | 任务 |
| --- | --- |
| DB-M4-01 | 新增评选相关 6 张表 |
| DB-M4-02 | 添加唯一约束防止重复分配 |
| DB-M4-03 | 添加评分汇总查询索引 |
### 8.4 验收标准
1. 可创建评审轮次和评分指标。
2. 可把作品分配给评委。
3. 评委只能看到自己的任务。
4. 评委可提交评分,提交后系统能汇总排名。
5. 评审管理员可发布获奖结果。
## 9. M5 前台数据接入
### 9.1 工作内容
| 页面 | 改造内容 |
| --- | --- |
| 官网首页 | `site/config`、`site/home` 接口替换静态文案 |
| 赛道页 | `competition` 聚合接口替换静态区块 |
| 作品详情 | `works/:id` 接口补齐图片、附件、AIGC、模型 |
| 课程详情 | `courses/:id` 接口补齐视频和详情 |
| 投票 | 保留 `works/:id/vote`,加入错误提示和防重复 |
### 9.2 验收标准
1. 前台页面没有明显视觉回退。
2. API 失败时有 mock 或空状态兜底。
3. 已发布内容可展示,草稿内容不可展示。
4. 页面主要图片、视频、附件链接可访问。
## 10. M6 测试上线
### 10.1 测试范围
| 类型 | 内容 |
| --- | --- |
| 单元测试 | 权限、评分计算、内容发布、文件校验 |
| 接口测试 | 登录、内容、文件、作品、课程、评选 |
| 前端测试 | 登录、路由守卫、表单、上传、发布 |
| 回归测试 | 官网首页、赛道页、作品详情、课程详情 |
| 安全测试 | 未登录、越权、文件类型、XSS |
### 10.2 上线步骤
1. 备份数据库。
2. 执行 Prisma migration。
3. 初始化角色、权限、超级管理员。
4. 初始化官网和赛道页内容区块。
5. 配置 OSS、CDN、JWT、管理员密码。
6. 部署后端 API。
7. 部署管理端静态文件。
8. 部署前台静态文件。
9. 验证 Swagger、登录、上传、发布、前台展示。
### 10.3 上线验收
| 项目 | 标准 |
| --- | --- |
| 登录 | 超级管理员和普通运营账号可登录 |
| 内容发布 | 官网和赛道页各至少发布一个区块 |
| 文件上传 | 图片、视频、PDF、ZIP 至少各验证一种 |
| 作品 | 新增作品并前台展示 |
| 课程 | 新增课程并前台播放或跳转 |
| 评选 | 创建轮次、提交评分、生成排名 |
| 日志 | 关键操作有日志 |
## 11. 任务依赖
```mermaid
flowchart TD
M0["M0 项目准备"] --> M1["M1 后台基础工程"]
M1 --> M2["M2 素材与内容管理"]
M1 --> M3["M3 作品与课程管理"]
M2 --> M5["M5 前台数据接入"]
M3 --> M4["M4 作品评选"]
M3 --> M5
M4 --> M6["M6 测试上线"]
M5 --> M6
```
## 12. 优先级建议
第一轮上线必须完成:
1. 登录、权限、控制台。
2. 文件上传和文件库。
3. 官网首页关键文案和图片管理。
4. 赛道页基础信息、赛程、赛事说明、资源包。
5. 课程视频管理。
6. 作品管理和前台展示。
7. 基础评选流程:轮次、指标、评委、评分、排名。
第二轮迭代:
1. 内容审批流。
2. 批量导入作品。
3. 评分表导出。
4. 文件清理任务。
5. 视频点播 VOD。
6. 更完整的数据看板。
+353
View File
@@ -0,0 +1,353 @@
# 开发规范
## 1. 工程规范
### 1.1 推荐目录结构
如果继续在 `mlkj-website` 内开发,建议:
```text
mlkj-website/
backend/
src/modules/auth/
src/modules/admin-users/
src/modules/content/
src/modules/media/
src/modules/evaluation/
frontend/
...
admin/
src/
api/
assets/
components/
layouts/
pages/
routes/
stores/
utils/
```
如果管理端独立工程,可将 `admin/` 放到 `mlkj-website-admin/app/`,当前 `docs/` 保持为设计文档目录。
### 1.2 命名规范
| 类型 | 规范 | 示例 |
| --- | --- | --- |
| 文件夹 | kebab-case | `content-sections` |
| TS 文件 | kebab-case | `evaluation-round.service.ts` |
| 类名 | PascalCase | `EvaluationRoundService` |
| 变量/函数 | camelCase | `createEvaluationRound` |
| 常量 | UPPER_SNAKE_CASE | `TOKEN_KEY` |
| 数据库表 | snake_case 复数 | `evaluation_rounds` |
| API 路径 | kebab-case 或资源复数 | `/admin/evaluation/rounds` |
| 权限码 | `module:action` | `work:publish` |
## 2. TypeScript 规范
1. 后续新增代码必须使用 TypeScript。
2. 开启严格类型检查,避免 `any` 扩散。
3. API 入参和出参必须有类型定义。
4. 复杂 JSON 字段必须定义接口或 schema,不能只写 `Record<string, any>`。
5. 业务状态使用枚举或字面量联合类型,不使用散落字符串。
示例:
```ts
export const publishStatuses = ['draft', 'published', 'disabled', 'archived'] as const
export type PublishStatus = (typeof publishStatuses)[number]
```
## 3. 前端开发规范
### 3.1 页面组织
| 类型 | 规范 |
| --- | --- |
| 页面组件 | 只负责页面编排和数据请求 |
| 表单组件 | 独立封装,接收初始值和提交回调 |
| 列表组件 | 表格列、筛选条件、分页状态清晰 |
| 文件选择器 | 全局复用,不在每个业务页面重复实现 |
| 权限组件 | 通过权限码控制按钮显示 |
### 3.2 API 请求
1. 所有请求集中在 `src/api`。
2. 不在页面组件中拼接复杂 URL。
3. 统一处理错误提示、登录过期、403。
4. 分页参数统一使用 `page`、`pageSize`。
5. 时间统一使用 ISO 字符串,前端只负责展示格式化。
### 3.3 表单规范
| 场景 | 要求 |
| --- | --- |
| 必填字段 | 前端和后端都校验 |
| 长文本 | 显示字数限制 |
| 图片选择 | 展示预览、尺寸、文件大小 |
| 发布操作 | 二次确认 |
| 删除操作 | 二次确认,优先逻辑删除或归档 |
| 评分表单 | 保存草稿和提交分开 |
### 3.4 状态与权限
1. 菜单按后端返回的权限码过滤。
2. 按钮级权限也要控制。
3. 前端权限只用于体验,后端必须再次校验。
4. 路由守卫必须处理:未登录、无权限、token 过期、用户被禁用。
### 3.5 UI 规范
1. 后台界面以信息密度和效率为主。
2. 表格页必须提供关键词搜索、筛选、分页。
3. 重要状态使用统一 badge:草稿、已发布、下架、归档、评审中、已锁定。
4. 上传、发布、评分等长操作必须有 loading 状态。
5. 错误提示要说明原因和下一步,不只显示「失败」。
## 4. 后端开发规范
### 4.1 模块结构
每个业务模块建议保持:
```text
module-name/
module-name.controller.ts
module-name.service.ts
module-name.dto.ts
module-name.module.ts
```
复杂模块可增加:
```text
module-name/
policies/
helpers/
serializers/
```
### 4.2 Controller 规范
1. Controller 只处理 HTTP 入参、权限装饰器和返回结果。
2. 不在 Controller 写复杂业务逻辑。
3. 每个接口都加 Swagger 装饰器。
4. 后台接口统一在 `/admin` 下。
5. 公开接口不得返回草稿、禁用、归档内容。
### 4.3 Service 规范
1. Service 负责业务流程和事务边界。
2. 复杂写操作使用 Prisma transaction。
3. 发布、删除、锁定、评分提交必须写操作日志。
4. 删除优先逻辑删除或归档,除非明确是子资源硬删除。
5. 抛错使用 NestJS 标准异常,如 `BadRequestException`、`NotFoundException`、`ForbiddenException`。
### 4.4 DTO 规范
1. 请求 DTO 必须使用 `class-validator`。
2. 数字字段使用 `class-transformer` 转换。
3. DTO 字段必须写 Swagger 示例。
4. 状态字段必须用 `IsIn` 校验。
5. 长文本必须限制长度。
### 4.5 响应规范
继续沿用当前 `ApiResult`:
```json
{
"code": 0,
"message": "ok",
"data": {}
}
```
分页响应:
```json
{
"code": 0,
"message": "ok",
"data": {
"list": [],
"page": 1,
"pageSize": 20,
"total": 0
}
}
```
## 5. 数据库规范
### 5.1 Prisma 规范
1. 表名使用 `@@map("snake_case_plural")`。
2. 字段名在 Prisma 中使用 camelCase,数据库中用 snake_case。
3. 每张业务表必须有 `createdAt`、`updatedAt`,日志和关联表可按需只有 `createdAt`。
4. 常用筛选字段必须建索引。
5. 外键删除策略要明确,不能使用默认行为糊过去。
### 5.2 迁移规范
1. 每次 schema 改动必须生成 migration。
2. migration 名称描述业务,如 `add_evaluation_tables`。
3. 生产环境迁移前必须备份。
4. 不允许直接手改生产数据库结构。
5. JSON 字段结构变更必须给出兼容策略。
### 5.3 JSON 字段规范
| 场景 | 要求 |
| --- | --- |
| 内容区块 | 保存完整结构,字段命名稳定 |
| 设计参数 | 使用对象数组,不塞不可解析字符串 |
| SEO | `title`、`description`、`keywords`、`ogImage` |
| 版本快照 | 保留发布时完整内容 |
## 6. API 规范
### 6.1 REST 约定
| 操作 | 方法 |
| --- | --- |
| 查询列表 | `GET /resources` |
| 查询详情 | `GET /resources/:id` |
| 新建 | `POST /resources` |
| 更新 | `PATCH /resources/:id` |
| 删除/归档 | `DELETE /resources/:id` |
| 状态变更 | `PATCH /resources/:id/status` |
| 动作 | `POST /resources/:id/action` |
### 6.2 查询参数
| 参数 | 说明 |
| --- | --- |
| `page` | 页码,从 1 开始 |
| `pageSize` | 每页数量,最大 100 |
| `keyword` | 关键词 |
| `status` | 发布状态 |
| `lang` | 语言 |
| `sort` | 排序字段,必要时支持 |
### 6.3 时间与 ID
1. API 中 BigInt ID 统一返回字符串。
2. 时间统一返回 ISO 8601。
3. 前端传时间也使用 ISO 8601。
## 7. 文件上传规范
### 7.1 文件类型
| 类型 | 扩展名 |
| --- | --- |
| 图片 | `jpg`、`jpeg`、`png`、`webp`、`svg` |
| 视频 | `mp4`、`mov`、`webm` |
| 模型 | `glb`、`gltf`、`stl`、`obj`、`zip` |
| 文档 | `pdf`、`docx`、`xlsx` |
| 压缩包 | `zip` |
### 7.2 限制建议
| 类型 | 第一版限制 |
| --- | --- |
| 图片 | 单文件不超过 10MB |
| 视频 | 单文件不超过 500MB |
| 模型 | 单文件不超过 200MB |
| 文档 | 单文件不超过 50MB |
| ZIP | 单文件不超过 500MB |
实际限制以 OSS 和服务器配置为准。
### 7.3 OSS Key 规范
```text
mlkj-website/{scene}/{usage}/{yyyy}/{mm}/{hash}.{ext}
```
示例:
```text
mlkj-website/works/covers/2026/06/7f3a9c.png
```
## 8. 权限和安全规范
1. 后台接口默认需要登录,只有登录和公开接口例外。
2. 密码必须使用 bcrypt 或 argon2 哈希。
3. JWT secret 不得提交到代码仓库。
4. OSS 密钥不得暴露给前端,前端只拿临时上传凭证。
5. 富文本或 HTML 内容必须做白名单过滤。
6. 评委只能访问分配给自己的评分任务。
7. 评审轮次锁定后,评分不可修改。
8. 所有导出接口也要校验权限。
## 9. 测试规范
### 9.1 后端测试
必须覆盖:
1. 登录成功和失败。
2. 权限不足返回 403。
3. 内容草稿不影响前台。
4. 发布后前台可读取。
5. 文件类型和大小校验。
6. 评分计算权重。
7. 评委越权访问被拒绝。
### 9.2 前端测试
重点覆盖:
1. 登录和路由守卫。
2. 内容编辑保存和发布。
3. 文件上传失败重试。
4. 作品和课程表单校验。
5. 评委评分表单。
### 9.3 手工回归
每次上线前至少回归:
1. 官网首页。
2. 赛道页。
3. 作品列表和详情。
4. 课程列表和详情。
5. 后台登录、上传、发布。
6. 评选完整流程。
## 10. 文档规范
1. 新增接口必须同步 Swagger。
2. 新增环境变量必须同步 `.env.example`。
3. 新增数据库表必须同步数据库设计文档。
4. 重要业务流程变更必须同步 PRD 或设计文档。
5. 上线步骤必须记录在部署文档。
## 11. 代码提交规范
如果项目使用 Git,建议提交信息采用:
```text
type(scope): summary
```
类型:
| type | 说明 |
| --- | --- |
| `feat` | 新功能 |
| `fix` | 修复 |
| `docs` | 文档 |
| `refactor` | 重构 |
| `test` | 测试 |
| `chore` | 工程杂项 |
| `style` | 格式调整 |
示例:
```text
feat(evaluation): add scoring assignment API
```
+255
View File
@@ -0,0 +1,255 @@
# 开发要求
## 1. 环境要求
### 1.1 本地开发环境
| 项目 | 要求 |
| --- | --- |
| Node.js | 建议 20+,部署镜像可沿用当前 Node 22 |
| npm | 随 Node 安装 |
| PostgreSQL | 14+ |
| Prisma | 与后端依赖版本保持一致 |
| Docker | 用于本地联调和部署验证 |
| OSS | 阿里云 OSS 测试 bucket 或本地 mock |
### 1.2 必要环境变量
| 变量 | 说明 |
| --- | --- |
| `DATABASE_URL` | PostgreSQL 连接地址 |
| `JWT_ACCESS_SECRET` | access token 密钥 |
| `JWT_REFRESH_SECRET` | refresh token 密钥 |
| `JWT_ACCESS_EXPIRES_IN` | access token 过期时间 |
| `JWT_REFRESH_EXPIRES_IN` | refresh token 过期时间 |
| `ADMIN_INITIAL_USERNAME` | 初始化管理员账号 |
| `ADMIN_INITIAL_PASSWORD` | 初始化管理员密码 |
| `OSS_REGION` | OSS 区域 |
| `OSS_BUCKET` | OSS bucket |
| `OSS_ACCESS_KEY_ID` | OSS access key |
| `OSS_ACCESS_KEY_SECRET` | OSS secret |
| `OSS_PUBLIC_BASE_URL` | CDN 或 OSS 公开访问域名 |
| `UPLOAD_MAX_IMAGE_SIZE` | 图片大小限制 |
| `UPLOAD_MAX_VIDEO_SIZE` | 视频大小限制 |
## 2. 技术要求
| 模块 | 要求 |
| --- | --- |
| 管理端前端 | TypeScript、路由守卫、权限菜单、统一 API Client |
| 后端 | NestJS 模块化、DTO 校验、Swagger、RBAC Guard |
| 数据库 | Prisma migration、索引、外键、seed |
| 文件 | OSS 直传、上传完成登记、业务绑定 |
| 前台 | 只读取 published 内容 |
| 评选 | 分数计算可复现,结果锁定后不可随意变更 |
## 3. 质量要求
### 3.1 基础质量门槛
上线前必须满足:
1. 后端构建通过。
2. 前端构建通过。
3. Prisma schema validate 通过。
4. OpenAPI/Swagger 可正常访问。
5. 核心接口有测试或手工验收记录。
6. 没有明文密钥提交到代码。
7. 没有绕过权限的后台接口。
### 3.2 代码质量
| 项目 | 要求 |
| --- | --- |
| 类型 | 不新增明显 `any` 债务 |
| 格式 | 使用统一 formatter |
| 重复 | 业务表单、上传、权限组件应复用 |
| 错误处理 | 用户可理解,日志可追踪 |
| 可维护性 | 复杂逻辑拆到 service/helper |
### 3.3 数据质量
1. 必填字段必须前后端双重校验。
2. 发布内容必须有语言、状态、更新时间。
3. 文件记录必须包含 MIME、大小、URL、storage provider。
4. 作品编号、课程编号、赛道 slug 必须唯一。
5. 评分数据必须能追溯到轮次、评委、指标、作品。
## 4. 安全要求
### 4.1 登录与账号
1. 默认管理员首次登录后必须修改密码。
2. 管理员密码不能明文保存。
3. 连续登录失败需要限流或短暂锁定。
4. 禁用账号不能登录。
### 4.2 权限
1. 所有 `/api/admin/*` 接口默认需要鉴权。
2. 写操作必须校验具体权限码。
3. 评委账号只能访问自己的评分任务。
4. 操作日志不可由普通管理员删除。
### 4.3 文件
1. 禁止上传可执行文件。
2. SVG 如允许上传,前台展示前必须确认安全策略。
3. 文件大小必须在后端校验。
4. OSS 上传凭证必须短期有效。
5. 文件 URL 不应暴露 OSS 管理凭证。
### 4.4 内容安全
1. 富文本必须做 XSS 白名单过滤。
2. 前台渲染用户可编辑内容时默认转义。
3. 外部链接需要校验协议,只允许 `http`、`https` 和约定的本地开发地址。
4. 预览链接必须有过期时间。
## 5. 性能要求
| 场景 | 要求 |
| --- | --- |
| 后台列表 | 默认分页,单页最大 100 |
| 文件库 | 图片缩略图懒加载 |
| 作品列表 | 支持索引字段筛选,避免全表扫描 |
| 赛道页聚合接口 | 可在发布后清理缓存 |
| 上传 | 大文件直传 OSS,不经过业务服务器转发 |
| 评分汇总 | 轮次结果可预计算,不每次实时全量计算 |
目标参考:
| 指标 | 第一版目标 |
| --- | --- |
| 后台普通列表响应 | 1 秒内 |
| 前台公开接口响应 | 500ms 内,冷查询可放宽 |
| 管理端首屏加载 | 3 秒内 |
| 上传凭证生成 | 300ms 内 |
## 6. 可用性要求
1. 内容编辑页离开前提示未保存。
2. 上传中断可重试。
3. 发布失败不丢草稿。
4. 评分提交失败不丢已填分数。
5. 批量操作必须显示影响数量。
6. 删除、锁定、发布结果等操作必须二次确认。
## 7. 兼容性要求
| 端 | 要求 |
| --- | --- |
| 管理端 | PC 浏览器优先,兼容 Chrome、Edge、Safari 近两个大版本 |
| 前台 | 保持当前移动端和桌面端适配 |
| API | 保持当前公开接口尽量向后兼容 |
| 数据 | 旧 mock 数据可在数据库未配置时作为兜底 |
## 8. 日志与审计要求
必须记录:
| 操作 | 内容 |
| --- | --- |
| 登录 | 用户、时间、结果 |
| 内容发布 | 操作人、区块、前后数据 |
| 内容下架 | 操作人、原因 |
| 文件上传 | 文件、上传人、业务场景 |
| 作品删除 | 操作人、作品 ID、快照 |
| 评分提交 | 评委、作品、轮次 |
| 轮次锁定 | 操作人、轮次 |
| 结果发布 | 操作人、发布结果快照 |
日志要求:
1. 普通管理员只读。
2. 关键日志不可物理删除。
3. 日志中的敏感字段需要脱敏。
## 9. 备份与恢复要求
1. 上线前备份数据库。
2. 每次 migration 前备份生产库。
3. 文件删除第一版只做逻辑归档。
4. 内容发布保留历史版本。
5. 误发布可通过历史版本回滚。
6. 评审结果发布后,如需更正,必须记录更正原因。
## 10. 部署要求
### 10.1 构建要求
| 项目 | 命令参考 |
| --- | --- |
| 后端依赖 | `npm --prefix backend install` |
| Prisma | `npx prisma validate`、`npx prisma generate` |
| 后端构建 | `npm --prefix backend run build` |
| 前台构建 | `npm --prefix frontend run build` |
| 管理端构建 | 以后续管理端工程实际命令为准 |
### 10.2 发布顺序
1. 数据库备份。
2. 执行 migration。
3. 执行 seed。
4. 部署后端。
5. 部署管理端。
6. 部署前台。
7. 验证健康检查和 Swagger。
8. 验证登录、上传、发布、前台展示。
## 11. 验收要求
### 11.1 P0 功能验收
| 模块 | 验收项 |
| --- | --- |
| 登录权限 | 管理员可登录,不同角色权限正确 |
| 官网内容 | Hero 文案、图片可修改并发布 |
| 赛道内容 | 赛程、赛事说明、资源包可维护 |
| 素材库 | 图片、视频、文档、模型可上传和选择 |
| 课程 | 课程可新增、发布、前台展示 |
| 作品 | 作品可新增、发布、上传附件、前台展示 |
| 评选 | 可创建轮次、评委评分、汇总排名 |
| 日志 | 发布、删除、评分、结果发布有日志 |
### 11.2 P1 功能验收
| 模块 | 验收项 |
| --- | --- |
| 合作伙伴 | Logo、链接、排序可维护 |
| 大赛动态 | 通知可发布 |
| 批量导入 | 作品可批量导入 |
| 导出 | 评分结果可导出 |
| 线索 | 咨询线索可标记状态和备注 |
## 12. Definition of Done
一个功能只有满足以下条件才算完成:
1. 前端页面完成并可正常操作。
2. 后端接口完成并有 DTO 校验。
3. Swagger 已同步。
4. 数据库 migration 已提交。
5. 权限校验已接入。
6. 错误和空状态已处理。
7. 关键操作日志已记录。
8. 至少完成自测和核心路径联调。
9. 文档或说明已更新。
## 13. 上线前检查清单
| 检查项 | 状态 |
| --- | --- |
| 生产环境变量已配置 | 待检查 |
| 数据库已备份 | 待检查 |
| migration 已执行 | 待检查 |
| seed 已执行 | 待检查 |
| 超级管理员可登录 | 待检查 |
| OSS 上传可用 | 待检查 |
| 官网内容可发布 | 待检查 |
| 赛道内容可发布 | 待检查 |
| 作品和课程可展示 | 待检查 |
| 评选流程可完成 | 待检查 |
| 操作日志可查看 | 待检查 |
| Swagger 可访问 | 待检查 |
| 前台页面回归通过 | 待检查 |
+331
View File
@@ -0,0 +1,331 @@
# 云服务器、云数据库与 OSS 部署设计
## 1. 背景说明
管理端后续会部署到云服务器,不是只在本地开发环境运行。因此生产架构必须默认使用:
1. 云服务器承载 Nginx、官网静态文件、管理端静态文件、NestJS API。
2. 云数据库承载 PostgreSQL。
3. OSS 承载图片、视频、模型、PDF、ZIP 等文件。
4. 可选 CDN 加速公开静态资源。
本文档用于约束后续开发和部署,不再按纯本地单机方案设计。
## 2. 推荐云架构
```mermaid
flowchart TD
User["前台用户/管理员"] --> DNS["域名 DNS"]
DNS --> Nginx["云服务器 Nginx<br/>HTTPS 80/443"]
Nginx --> SiteStatic["官网静态文件"]
Nginx --> AdminStatic["管理端静态文件 /admin"]
Nginx --> API["NestJS API /api"]
API --> RDS[("云数据库 PostgreSQL")]
API --> OSS["阿里云 OSS"]
API --> Log["应用日志"]
AdminStatic --> OSSUpload["浏览器直传 OSS"]
OSSUpload --> OSS
SiteStatic --> CDN["CDN/OSS 公网访问域名"]
CDN --> OSS
```
## 3. 云资源规划
### 3.1 云服务器
| 项目 | 建议 |
| --- | --- |
| 类型 | 阿里云 ECS 或轻量应用服务器 |
| CPU/内存 | 测试期 2C4G,正式运营建议 2C4G 起 |
| 系统 | Ubuntu 22.04 LTS 或 Alibaba Cloud Linux |
| 运行服务 | Nginx、Node.js/NestJS API、静态文件 |
| 开放端口 | 80、443、必要时开放 SSH 22 |
| 不开放端口 | PostgreSQL、NestJS 内部端口、Redis 内部端口 |
### 3.2 云数据库 PostgreSQL
| 项目 | 建议 |
| --- | --- |
| 类型 | 阿里云 RDS PostgreSQL |
| 版本 | PostgreSQL 14+ |
| 网络 | 与云服务器同地域,优先同 VPC |
| 访问 | 只允许云服务器内网 IP 或安全组访问 |
| 备份 | 开启自动备份,保留至少 7 天 |
| 高可用 | 正式运营建议开启高可用版 |
| 字符集 | UTF-8 |
| 时区 | 统一使用 UTC 存储,前端按本地展示 |
### 3.3 OSS
| 项目 | 建议 |
| --- | --- |
| Bucket | 单独创建官网管理端 bucket |
| 地域 | 与云服务器、RDS 尽量同地域 |
| 权限 | 默认私有,公开展示资源通过 CDN 或受控公开 URL |
| 上传 | 管理端使用临时凭证或 Post Policy 直传 |
| 目录 | 按业务场景和用途分目录 |
| 生命周期 | 未绑定临时文件可定期清理 |
| 防盗链 | 正式上线建议配置 Referer 白名单 |
### 3.4 CDN
CDN 可选,但正式对外展示建议接入:
| 资源 | 是否建议 CDN |
| --- | --- |
| 官网图片 | 建议 |
| 赛道页图片 | 建议 |
| 课程封面 | 建议 |
| 大视频 | 建议,视频量大后升级 VOD |
| 作品模型 | 按访问量决定 |
| 评审内部附件 | 不建议公开 CDN,使用签名 URL |
## 4. 网络与安全组
### 4.1 访问边界
| 服务 | 访问来源 | 端口 | 说明 |
| --- | --- | --- | --- |
| Nginx | 公网 | 80/443 | 对外访问官网、管理端、API |
| SSH | 管理员固定 IP | 22 | 建议限制来源 IP |
| NestJS API | Nginx 本机反代 | 3001 或内部端口 | 不直接公网开放 |
| PostgreSQL RDS | 云服务器内网 IP | 5432 | 禁止公网全开放 |
| OSS | 浏览器和 API | HTTPS | 通过临时凭证和权限策略控制 |
### 4.2 安全要求
1. RDS 白名单只配置云服务器内网 IP 或安全组。
2. OSS AccessKey 只存在服务器环境变量中,不传给浏览器。
3. 管理端上传使用短期有效凭证。
4. Nginx 强制 HTTPS。
5. 管理端后台路径建议使用 `/admin`,API 使用 `/api`。
6. 后端内部端口不得暴露到公网。
## 5. OSS 文件策略
### 5.1 Bucket 权限策略
建议默认使用私有 bucket,并按资源类型决定访问方式。
| 资源类型 | 访问方式 |
| --- | --- |
| 官网公开图片 | CDN 或公开读 URL |
| 赛道页公开图片 | CDN 或公开读 URL |
| 课程公开视频 | CDN/OSS URL,播放量大后改 VOD |
| 作品公开封面/图集 | CDN 或公开读 URL |
| 作品模型 | 可公开展示的模型使用公开 URL,评审原始文件使用签名 URL |
| 评审附件 | 私有,后端鉴权后生成短期签名 URL |
| 管理端临时上传 | 私有,完成后登记并绑定业务 |
### 5.2 OSS Key 规范
```text
mlkj-website/
site/
images/{yyyy}/{mm}/{hash}.{ext}
competition/
images/{yyyy}/{mm}/{hash}.{ext}
resources/{yyyy}/{mm}/{hash}.{ext}
courses/
covers/{yyyy}/{mm}/{hash}.{ext}
videos/{yyyy}/{mm}/{hash}.{ext}
works/
covers/{yyyy}/{mm}/{hash}.{ext}
images/{yyyy}/{mm}/{hash}.{ext}
models/{yyyy}/{mm}/{hash}.{ext}
documents/{yyyy}/{mm}/{hash}.{ext}
tmp/
uploads/{yyyy}/{mm}/{hash}.{ext}
```
### 5.3 上传流程
```mermaid
sequenceDiagram
participant Admin as 管理端
participant API as 云服务器 API
participant OSS as OSS
participant DB as 云数据库
Admin->>API: POST /api/admin/uploads/policy
API->>API: 校验登录、权限、文件类型、大小
API-->>Admin: 返回短期上传凭证、fileKey
Admin->>OSS: 直传文件
OSS-->>Admin: 上传成功
Admin->>API: POST /api/admin/uploads/complete
API->>DB: 写入 files 和 file_bindings
API-->>Admin: 返回文件记录
```
## 6. 云数据库设计要求
### 6.1 连接方式
生产环境后端使用 RDS 内网地址:
```text
DATABASE_URL=postgresql://user:password@rds-internal-host:5432/mlkj_website?schema=public
```
要求:
1. 不在前端项目中出现数据库连接串。
2. 不在代码中硬编码数据库账号密码。
3. 生产数据库账号按最小权限创建。
4. Migration 只在部署流程中执行,不由普通请求触发。
### 6.2 连接池
| 项目 | 建议 |
| --- | --- |
| API 单实例 | Prisma 默认连接池可先使用 |
| 多实例部署 | 控制连接数,避免打满 RDS |
| 高并发 | 考虑 PgBouncer 或 RDS 连接池能力 |
### 6.3 备份与恢复
1. RDS 自动备份至少保留 7 天。
2. 每次上线 migration 前手动创建快照。
3. 评选开始前和结果发布前建议额外备份。
4. 重要内容发布保留 `content_revisions`,支持业务层回滚。
## 7. 环境变量
### 7.1 后端生产环境变量
```text
NODE_ENV=production
PORT=3001
DATABASE_URL=postgresql://...
JWT_ACCESS_SECRET=...
JWT_REFRESH_SECRET=...
JWT_ACCESS_EXPIRES_IN=2h
JWT_REFRESH_EXPIRES_IN=14d
ADMIN_INITIAL_USERNAME=admin
ADMIN_INITIAL_PASSWORD=change-me-before-production
OSS_REGION=oss-cn-beijing
OSS_BUCKET=mlkj-website-prod
OSS_ACCESS_KEY_ID=...
OSS_ACCESS_KEY_SECRET=...
OSS_PUBLIC_BASE_URL=https://static.example.com
OSS_INTERNAL_ENDPOINT=...
OSS_PUBLIC_ENDPOINT=...
UPLOAD_MAX_IMAGE_SIZE=10485760
UPLOAD_MAX_VIDEO_SIZE=524288000
UPLOAD_MAX_MODEL_SIZE=209715200
UPLOAD_MAX_DOCUMENT_SIZE=52428800
PUBLIC_SITE_ORIGIN=https://www.example.com
ADMIN_SITE_ORIGIN=https://www.example.com/admin
```
### 7.2 前端生产环境变量
```text
VITE_API_BASE_URL=/api
VITE_PUBLIC_ASSET_BASE_URL=https://static.example.com
```
## 8. Nginx 路由建议
```text
https://www.example.com/ -> 官网前台静态文件
https://www.example.com/competition.html -> 赛道页
https://www.example.com/admin/ -> 管理端静态文件
https://www.example.com/api/ -> NestJS API 反向代理
https://www.example.com/api-docs -> Swagger,可按环境限制访问
```
生产建议:
1. `/api-docs` 可仅允许白名单 IP 或加基础鉴权。
2. `/admin` 必须走 HTTPS。
3. 上传大文件时需要调整 Nginx 超时,但直传 OSS 后压力会小很多。
## 9. 部署流程
```mermaid
flowchart TD
A["准备云资源"] --> B["配置 RDS、OSS、安全组"]
B --> C["配置服务器环境变量"]
C --> D["构建后端和前端"]
D --> E["备份数据库"]
E --> F["执行 Prisma migration"]
F --> G["执行 seed 初始化权限和内容"]
G --> H["启动 NestJS API"]
H --> I["部署官网和管理端静态文件"]
I --> J["Nginx reload"]
J --> K["上线验证"]
```
上线验证:
| 项目 | 检查 |
| --- | --- |
| API | `/api/health` 正常 |
| Swagger | 可访问或白名单可访问 |
| 数据库 | 后端能读写 RDS |
| OSS | 管理端能上传文件 |
| CDN/OSS URL | 前台图片可访问 |
| 管理端 | 可登录、上传、发布 |
| 前台 | 已发布内容可展示 |
## 10. 运维要求
### 10.1 日志
| 日志 | 保存位置 |
| --- | --- |
| Nginx access/error | 云服务器 |
| NestJS 应用日志 | 云服务器或日志服务 |
| 操作日志 | PostgreSQL `operation_logs` |
| OSS 访问日志 | OSS 日志功能,可后续开启 |
### 10.2 监控
第一版至少关注:
1. 云服务器 CPU、内存、磁盘。
2. API 进程存活。
3. RDS CPU、连接数、慢查询。
4. OSS 流量和请求错误。
5. 磁盘日志是否过大。
### 10.3 备份
| 对象 | 策略 |
| --- | --- |
| PostgreSQL | RDS 自动备份 + 上线前手动快照 |
| OSS | 开启版本控制或关键目录定期备份 |
| 环境变量 | 安全保存,不进入代码仓库 |
| 静态包 | 保留最近 2-3 个发布包,便于回滚 |
## 11. 开发时需要提前适配的点
1. 文件上传接口从一开始就按 OSS 直传设计,不做本地磁盘上传作为正式方案。
2. 数据库字段和 Prisma migration 按云 PostgreSQL 生产环境设计。
3. 不把图片、视频、模型文件放进服务器项目目录。
4. API 返回文件 URL 时区分公开 URL 和签名 URL。
5. 评审附件、原始模型等敏感文件不能默认公开。
6. 环境变量必须区分 local、staging、production。
7. 所有上线步骤必须可重复执行,避免手工改库。
## 12. 成本与扩展建议
| 阶段 | 建议 |
| --- | --- |
| 初期 | 单台云服务器 + RDS PostgreSQL + OSS |
| 访问量上升 | 增加 CDN,前台静态资源全部走 CDN |
| 视频量上升 | 课程视频迁移到阿里云 VOD |
| 后台用户增多 | 增加 Redis,用于 session、限流、缓存 |
| API 压力上升 | API 多实例部署,前面加负载均衡 |
第一版不要过度复杂,但必须把云数据库和 OSS 的边界设计正确,避免后续上线时重构上传、文件路径和数据库连接方式。
File diff suppressed because it is too large. Load diff
+11
View File
@@ -0,0 +1,11 @@
{
"name": "mlkj-website-admin",
"version": "0.1.0",
"private": true,
"type": "module",
"scripts": {
"dev": "node app/serve.mjs",
"check": "node --check app/assets/admin-app.js && node --check app/serve.mjs",
"build": "node scripts/build.mjs"
}
}
+19
View File
@@ -0,0 +1,19 @@
import { copyFile, mkdir, rm } from 'node:fs/promises'
import { dirname, join } from 'node:path'
import { fileURLToPath } from 'node:url'
const files = ['index.html', 'assets/admin-app.css', 'assets/admin-app.js']
const root = new URL('../', import.meta.url)
const appRoot = new URL('./app/', root)
const distRoot = new URL('./dist/', root)
await rm(distRoot, { recursive: true, force: true })
for (const file of files) {
const source = new URL(file, appRoot)
const target = new URL(file, distRoot)
await mkdir(dirname(fileURLToPath(target)), { recursive: true })
await copyFile(source, target)
}
console.log(`Built ${files.length} files to ${join(fileURLToPath(root), 'dist')}`)