From c1f1b39e81e091fa6d0de22bca913cbf1658ebfb Mon Sep 17 00:00:00 2001 From: WLinX <519407855@qq.com> Date: Mon, 29 Jun 2026 19:27:33 +0800 Subject: [PATCH] =?UTF-8?q?feat:=E7=B3=BB=E7=BB=9F=E6=A1=86=E6=9E=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 11 + README.md | 82 ++ app/assets/admin-app.css | 485 ++++++++ app/assets/admin-app.js | 774 ++++++++++++ app/index.html | 14 + app/serve.mjs | 62 + dist/assets/admin-app.css | 485 ++++++++ dist/assets/admin-app.js | 774 ++++++++++++ dist/index.html | 14 + docs/00-current-site-audit.md | 96 ++ docs/01-prd.md | 212 ++++ docs/02-product-flow.md | 182 +++ docs/03-design-spec.md | 282 +++++ docs/04-system-architecture.md | 203 ++++ docs/05-er-diagram.md | 201 ++++ docs/06-database-schema.md | 315 +++++ docs/07-api-design.md | 242 ++++ docs/08-route-design.md | 118 ++ docs/09-development-plan.md | 308 +++++ docs/10-development-standards.md | 353 ++++++ docs/11-development-requirements.md | 255 ++++ docs/12-cloud-deployment.md | 331 ++++++ docs/swagger/openapi.yaml | 1686 +++++++++++++++++++++++++++ package.json | 11 + scripts/build.mjs | 19 + 25 files changed, 7515 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 app/assets/admin-app.css create mode 100644 app/assets/admin-app.js create mode 100644 app/index.html create mode 100644 app/serve.mjs create mode 100644 dist/assets/admin-app.css create mode 100644 dist/assets/admin-app.js create mode 100644 dist/index.html create mode 100644 docs/00-current-site-audit.md create mode 100644 docs/01-prd.md create mode 100644 docs/02-product-flow.md create mode 100644 docs/03-design-spec.md create mode 100644 docs/04-system-architecture.md create mode 100644 docs/05-er-diagram.md create mode 100644 docs/06-database-schema.md create mode 100644 docs/07-api-design.md create mode 100644 docs/08-route-design.md create mode 100644 docs/09-development-plan.md create mode 100644 docs/10-development-standards.md create mode 100644 docs/11-development-requirements.md create mode 100644 docs/12-cloud-deployment.md create mode 100644 docs/swagger/openapi.yaml create mode 100644 package.json create mode 100644 scripts/build.mjs diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..41f186c --- /dev/null +++ b/.gitignore @@ -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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..288a625 --- /dev/null +++ b/README.md @@ -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 数据。 diff --git a/app/assets/admin-app.css b/app/assets/admin-app.css new file mode 100644 index 0000000..ec07348 --- /dev/null +++ b/app/assets/admin-app.css @@ -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; +} diff --git a/app/assets/admin-app.js b/app/assets/admin-app.js new file mode 100644 index 0000000..1efe5f1 --- /dev/null +++ b/app/assets/admin-app.js @@ -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, ">") + .replace(/"/g, """); + } + + 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 ( + '
' + + '" + + '' + + "
" + ); + } + + function textarea(name, label, value) { + return ( + '
' + + '" + + '" + + "
" + ); + } + + function select(name, label, value, options) { + return ( + '
' + + '" + + '" + + "
" + ); + } + + function badge(status) { + return '' + escapeHtml(status || "-") + ""; + } + + function pageTitle() { + var item = menus.find(function (menu) { + return menu.key === state.view; + }); + return item ? item.label : "管理端"; + } + + function renderLogin() { + app.innerHTML = + '
' + + '
' + + "

模灵科技管理端

" + + "

管理公司官网、赛道页、作品、课程、素材和评选流程。

" + + '
' + + field("apiBase", "API 地址", state.apiBase) + + field("username", "账号", "admin") + + field("password", "密码", "", "password") + + '' + + (state.message ? '
' + escapeHtml(state.message) + "
" : "") + + "
" + + "
" + + "
"; + + 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 '"; + if (!hasPermission(item.permission)) return ""; + return ( + '" + ); + }) + .join(""); + + var user = state.user || {}; + app.innerHTML = + '
' + + '" + + '
' + + '
' + + "

" + + pageTitle() + + "

API:" + + escapeHtml(state.apiBase) + + "

" + + '
' + + escapeHtml((user.displayName || user.username || "管").slice(0, 1)) + + '
' + + escapeHtml(user.displayName || user.username || "管理员") + + '
' + + escapeHtml((user.roles || []).join(", ") || "admin") + + "
" + + "
" + + (state.message ? '
' + escapeHtml(state.message) + "
" : "") + + content + + "
" + + "
"; + + 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( + '
' + + kpi("作品总数", data.worksCount) + + kpi("已发布作品", data.publishedWorks) + + kpi("课程/视频", data.coursesCount) + + kpi("咨询线索", data.inquiriesCount) + + "
" + + '

建设进度

' + + '
当前管理端前端已接入登录、权限、控制台、作品、课程、文件库和线索接口。下一步将继续补官网内容、赛道内容、OSS 直传和作品评选。
' + + "
", + ); + } + + function kpi(label, value) { + return '
' + label + '
' + (value == null ? "-" : value) + "
"; + } + + function renderWorks() { + var work = state.editingWork || {}; + renderShell( + '
' + + '
' + + '

作品列表

' + + '
' + + renderWorksToolbar() + + '
' + + (state.works.length ? state.works.map(renderWorkRow).join("") : '') + + "
编号作品作者/学校状态操作
暂无作品
" + + '

' + + (work.id ? "编辑作品" : "新建作品") + + '

' + + renderWorkForm(work) + + "
" + + "
", + ); + bindWorksEvents(); + } + + function renderWorksToolbar() { + return ( + '
' + + '' + + '" + + '' + + '
' + ); + } + + function renderWorkRow(item) { + var id = item.id || item.workNo; + return ( + "" + + escapeHtml(item.workNo || id) + + "" + + escapeHtml(item.title) + + '
' + + escapeHtml(item.category || "") + + "" + + escapeHtml(item.authorName || item.author || "") + + '
' + + escapeHtml(item.school || "") + + "" + + badge(item.status || "draft") + + '' + ); + } + + function renderWorkForm(work) { + return ( + '
' + + 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()) + + '
' + + "
" + ); + } + + 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( + '
' + + '

课程列表

' + + renderCoursesToolbar() + + '
' + + (state.courses.length ? state.courses.map(renderCourseRow).join("") : '') + + "
编号课程类型状态操作
暂无课程
" + + '

' + + (course.id ? "编辑课程" : "新建课程") + + '

' + + renderCourseForm(course) + + "
" + + "
", + ); + bindCoursesEvents(); + } + + function renderCoursesToolbar() { + return ( + '
' + + '' + + '" + + '' + + '
' + ); + } + + function renderCourseRow(item) { + var id = item.id || item.courseNo; + return ( + "" + + escapeHtml(item.courseNo || id) + + "" + + escapeHtml(item.title) + + '
' + + escapeHtml(item.partner || "") + + "" + + escapeHtml(item.type || "") + + "" + + badge(item.status || "draft") + + '' + ); + } + + function renderCourseForm(course) { + return ( + '
' + + 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()) + + '
' + + "
" + ); + } + + 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( + '

素材库

' + + '
当前版本先接入文件记录列表。下一步会按云部署设计接入 OSS 临时凭证直传。
' + + '
' + + (state.files.length ? state.files.map(renderFileRow).join("") : '') + + "
文件名类型大小存储时间
暂无文件
", + ); + document.getElementById("files-reload-btn").addEventListener("click", refreshView); + } + + function renderFileRow(item) { + return ( + "" + + escapeHtml(item.originalName) + + '
' + + escapeHtml(item.url || item.fileKey || "") + + "" + + escapeHtml(item.mimeType || "") + + "" + + escapeHtml(item.size || "") + + "" + + escapeHtml(item.storageProvider || "") + + "" + + escapeHtml(item.createdAt || "") + + "" + ); + } + + function renderInquiries() { + renderShell( + '

咨询线索

' + + '
' + + '
' + + (state.inquiries.length ? state.inquiries.map(renderInquiryRow).join("") : '') + + "
机构联系人电话状态时间
暂无线索
", + ); + 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 ( + "" + + escapeHtml(item.organization) + + '
' + + escapeHtml(item.role || "") + + "" + + escapeHtml(item.contactName || "") + + "" + + escapeHtml(item.phone || "") + + "" + + badge(item.status || "pending") + + "" + + escapeHtml(item.createdAt || "") + + "" + ); + } + + function renderPlaceholder(title, desc, items) { + renderShell( + '

' + + title + + '

' + + desc + + '

' + + items + .map(function (item) { + return '

' + item.title + '

' + item.desc + "

"; + }) + .join("") + + "
", + ); + } + + 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 '"; + }) + .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(); +})(); diff --git a/app/index.html b/app/index.html new file mode 100644 index 0000000..f3aa45e --- /dev/null +++ b/app/index.html @@ -0,0 +1,14 @@ + + + + + + 模灵科技官网管理端 + + + + +
+ + + diff --git a/app/serve.mjs b/app/serve.mjs new file mode 100644 index 0000000..363b668 --- /dev/null +++ b/app/serve.mjs @@ -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}/`) +}) diff --git a/dist/assets/admin-app.css b/dist/assets/admin-app.css new file mode 100644 index 0000000..ec07348 --- /dev/null +++ b/dist/assets/admin-app.css @@ -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; +} diff --git a/dist/assets/admin-app.js b/dist/assets/admin-app.js new file mode 100644 index 0000000..1efe5f1 --- /dev/null +++ b/dist/assets/admin-app.js @@ -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, ">") + .replace(/"/g, """); + } + + 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 ( + '
' + + '" + + '' + + "
" + ); + } + + function textarea(name, label, value) { + return ( + '
' + + '" + + '" + + "
" + ); + } + + function select(name, label, value, options) { + return ( + '
' + + '" + + '" + + "
" + ); + } + + function badge(status) { + return '' + escapeHtml(status || "-") + ""; + } + + function pageTitle() { + var item = menus.find(function (menu) { + return menu.key === state.view; + }); + return item ? item.label : "管理端"; + } + + function renderLogin() { + app.innerHTML = + '
' + + '
' + + "

模灵科技管理端

" + + "

管理公司官网、赛道页、作品、课程、素材和评选流程。

" + + '
' + + field("apiBase", "API 地址", state.apiBase) + + field("username", "账号", "admin") + + field("password", "密码", "", "password") + + '' + + (state.message ? '
' + escapeHtml(state.message) + "
" : "") + + "
" + + "
" + + "
"; + + 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 '"; + if (!hasPermission(item.permission)) return ""; + return ( + '" + ); + }) + .join(""); + + var user = state.user || {}; + app.innerHTML = + '
' + + '" + + '
' + + '
' + + "

" + + pageTitle() + + "

API:" + + escapeHtml(state.apiBase) + + "

" + + '
' + + escapeHtml((user.displayName || user.username || "管").slice(0, 1)) + + '
' + + escapeHtml(user.displayName || user.username || "管理员") + + '
' + + escapeHtml((user.roles || []).join(", ") || "admin") + + "
" + + "
" + + (state.message ? '
' + escapeHtml(state.message) + "
" : "") + + content + + "
" + + "
"; + + 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( + '
' + + kpi("作品总数", data.worksCount) + + kpi("已发布作品", data.publishedWorks) + + kpi("课程/视频", data.coursesCount) + + kpi("咨询线索", data.inquiriesCount) + + "
" + + '

建设进度

' + + '
当前管理端前端已接入登录、权限、控制台、作品、课程、文件库和线索接口。下一步将继续补官网内容、赛道内容、OSS 直传和作品评选。
' + + "
", + ); + } + + function kpi(label, value) { + return '
' + label + '
' + (value == null ? "-" : value) + "
"; + } + + function renderWorks() { + var work = state.editingWork || {}; + renderShell( + '
' + + '
' + + '

作品列表

' + + '
' + + renderWorksToolbar() + + '
' + + (state.works.length ? state.works.map(renderWorkRow).join("") : '') + + "
编号作品作者/学校状态操作
暂无作品
" + + '

' + + (work.id ? "编辑作品" : "新建作品") + + '

' + + renderWorkForm(work) + + "
" + + "
", + ); + bindWorksEvents(); + } + + function renderWorksToolbar() { + return ( + '
' + + '' + + '" + + '' + + '
' + ); + } + + function renderWorkRow(item) { + var id = item.id || item.workNo; + return ( + "" + + escapeHtml(item.workNo || id) + + "" + + escapeHtml(item.title) + + '
' + + escapeHtml(item.category || "") + + "" + + escapeHtml(item.authorName || item.author || "") + + '
' + + escapeHtml(item.school || "") + + "" + + badge(item.status || "draft") + + '' + ); + } + + function renderWorkForm(work) { + return ( + '
' + + 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()) + + '
' + + "
" + ); + } + + 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( + '
' + + '

课程列表

' + + renderCoursesToolbar() + + '
' + + (state.courses.length ? state.courses.map(renderCourseRow).join("") : '') + + "
编号课程类型状态操作
暂无课程
" + + '

' + + (course.id ? "编辑课程" : "新建课程") + + '

' + + renderCourseForm(course) + + "
" + + "
", + ); + bindCoursesEvents(); + } + + function renderCoursesToolbar() { + return ( + '
' + + '' + + '" + + '' + + '
' + ); + } + + function renderCourseRow(item) { + var id = item.id || item.courseNo; + return ( + "" + + escapeHtml(item.courseNo || id) + + "" + + escapeHtml(item.title) + + '
' + + escapeHtml(item.partner || "") + + "" + + escapeHtml(item.type || "") + + "" + + badge(item.status || "draft") + + '' + ); + } + + function renderCourseForm(course) { + return ( + '
' + + 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()) + + '
' + + "
" + ); + } + + 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( + '

素材库

' + + '
当前版本先接入文件记录列表。下一步会按云部署设计接入 OSS 临时凭证直传。
' + + '
' + + (state.files.length ? state.files.map(renderFileRow).join("") : '') + + "
文件名类型大小存储时间
暂无文件
", + ); + document.getElementById("files-reload-btn").addEventListener("click", refreshView); + } + + function renderFileRow(item) { + return ( + "" + + escapeHtml(item.originalName) + + '
' + + escapeHtml(item.url || item.fileKey || "") + + "" + + escapeHtml(item.mimeType || "") + + "" + + escapeHtml(item.size || "") + + "" + + escapeHtml(item.storageProvider || "") + + "" + + escapeHtml(item.createdAt || "") + + "" + ); + } + + function renderInquiries() { + renderShell( + '

咨询线索

' + + '
' + + '
' + + (state.inquiries.length ? state.inquiries.map(renderInquiryRow).join("") : '') + + "
机构联系人电话状态时间
暂无线索
", + ); + 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 ( + "" + + escapeHtml(item.organization) + + '
' + + escapeHtml(item.role || "") + + "" + + escapeHtml(item.contactName || "") + + "" + + escapeHtml(item.phone || "") + + "" + + badge(item.status || "pending") + + "" + + escapeHtml(item.createdAt || "") + + "" + ); + } + + function renderPlaceholder(title, desc, items) { + renderShell( + '

' + + title + + '

' + + desc + + '

' + + items + .map(function (item) { + return '

' + item.title + '

' + item.desc + "

"; + }) + .join("") + + "
", + ); + } + + 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 '"; + }) + .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(); +})(); diff --git a/dist/index.html b/dist/index.html new file mode 100644 index 0000000..f3aa45e --- /dev/null +++ b/dist/index.html @@ -0,0 +1,14 @@ + + + + + + 模灵科技官网管理端 + + + + +
+ + + diff --git a/docs/00-current-site-audit.md b/docs/00-current-site-audit.md new file mode 100644 index 0000000..3125843 --- /dev/null +++ b/docs/00-current-site-audit.md @@ -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. 作品评选与公众投票分开建模,避免把点赞数当作评委评分。 diff --git a/docs/01-prd.md b/docs/01-prd.md new file mode 100644 index 0000000..60e5139 --- /dev/null +++ b/docs/01-prd.md @@ -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 | +| 内容误发布 | 草稿、预览、发布确认、操作日志必做 | diff --git a/docs/02-product-flow.md b/docs/02-product-flow.md new file mode 100644 index 0000000..77a89ef --- /dev/null +++ b/docs/02-product-flow.md @@ -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% | + +权重应在每个评审轮次中可配置,避免后续赛制变化影响历史数据。 diff --git a/docs/03-design-spec.md b/docs/03-design-spec.md new file mode 100644 index 0000000..e57ecfe --- /dev/null +++ b/docs/03-design-spec.md @@ -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` 读取课程和视频。 diff --git a/docs/04-system-architecture.md b/docs/04-system-architecture.md new file mode 100644 index 0000000..192c4a8 --- /dev/null +++ b/docs/04-system-architecture.md @@ -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
Vite + React/Vue + TS"] + BrowserSite["官网访问者"] --> SiteFE["现有官网前台
HTML + JS"] + + AdminFE --> AdminAPI["NestJS Admin API
/api/admin/*"] + SiteFE --> PublicAPI["NestJS Public API
/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 `。 +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 | diff --git a/docs/05-er-diagram.md b/docs/05-er-diagram.md new file mode 100644 index 0000000..d2ee719 --- /dev/null +++ b/docs/05-er-diagram.md @@ -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` | 已存在,建议接入真实鉴权 | diff --git a/docs/06-database-schema.md b/docs/06-database-schema.md new file mode 100644 index 0000000..6f11c7d --- /dev/null +++ b/docs/06-database-schema.md @@ -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 字段 | diff --git a/docs/07-api-design.md b/docs/07-api-design.md new file mode 100644 index 0000000..33032bc --- /dev/null +++ b/docs/07-api-design.md @@ -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 +``` diff --git a/docs/08-route-design.md b/docs/08-route-design.md new file mode 100644 index 0000000..8ff031f --- /dev/null +++ b/docs/08-route-design.md @@ -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=` | +| 草稿预览 | `/preview/:pageKey?token=` | + +## 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` | 课程详情 | diff --git a/docs/09-development-plan.md b/docs/09-development-plan.md new file mode 100644 index 0000000..4d6e82d --- /dev/null +++ b/docs/09-development-plan.md @@ -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. 更完整的数据看板。 diff --git a/docs/10-development-standards.md b/docs/10-development-standards.md new file mode 100644 index 0000000..4898029 --- /dev/null +++ b/docs/10-development-standards.md @@ -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`。 +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 +``` diff --git a/docs/11-development-requirements.md b/docs/11-development-requirements.md new file mode 100644 index 0000000..a85eda1 --- /dev/null +++ b/docs/11-development-requirements.md @@ -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 可访问 | 待检查 | +| 前台页面回归通过 | 待检查 | diff --git a/docs/12-cloud-deployment.md b/docs/12-cloud-deployment.md new file mode 100644 index 0000000..9e49269 --- /dev/null +++ b/docs/12-cloud-deployment.md @@ -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
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 的边界设计正确,避免后续上线时重构上传、文件路径和数据库连接方式。 diff --git a/docs/swagger/openapi.yaml b/docs/swagger/openapi.yaml new file mode 100644 index 0000000..3a4e747 --- /dev/null +++ b/docs/swagger/openapi.yaml @@ -0,0 +1,1686 @@ +openapi: 3.0.3 +info: + title: MLKJ Website Admin API + version: 0.1.0 + description: 模灵科技官网与赛道页管理端 API 设计稿 +servers: + - url: /api + description: Same origin API + - url: http://127.0.0.1:3001/api + description: Local development +security: + - bearerAuth: [] +tags: + - name: Auth + description: 管理端鉴权 + - name: Dashboard + description: 控制台 + - name: SiteContent + description: 官网内容管理 + - name: CompetitionAdmin + description: 赛道内容管理 + - name: Media + description: 素材与上传 + - name: CoursesAdmin + description: 课程视频管理 + - name: WorksAdmin + description: 作品管理 + - name: Evaluation + description: 作品评选 + - name: InquiriesAdmin + description: 咨询线索 + - name: PublicSite + description: 前台公开接口 + +paths: + /admin/auth/login: + post: + tags: [Auth] + summary: 管理员登录 + security: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/LoginRequest' + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ApiResponse' + - type: object + properties: + data: + $ref: '#/components/schemas/LoginResponse' + + /admin/auth/refresh: + post: + tags: [Auth] + summary: 刷新访问令牌 + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [refreshToken] + properties: + refreshToken: + type: string + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/auth/logout: + post: + tags: [Auth] + summary: 退出登录 + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/me: + get: + tags: [Auth] + summary: 当前管理员信息 + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ApiResponse' + - type: object + properties: + data: + $ref: '#/components/schemas/AdminUser' + + /admin/dashboard: + get: + tags: [Dashboard] + summary: 管理后台首页数据 + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ApiResponse' + - type: object + properties: + data: + $ref: '#/components/schemas/Dashboard' + + /admin/site/config: + get: + tags: [SiteContent] + summary: 获取站点基础配置草稿和发布内容 + responses: + '200': + $ref: '#/components/responses/Ok' + patch: + tags: [SiteContent] + summary: 更新站点基础配置草稿 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SiteConfigInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/content/pages/{pageKey}/sections: + get: + tags: [SiteContent] + summary: 获取页面内容区块 + parameters: + - $ref: '#/components/parameters/PageKey' + - $ref: '#/components/parameters/Lang' + responses: + '200': + $ref: '#/components/responses/Ok' + post: + tags: [SiteContent] + summary: 新建页面内容区块 + parameters: + - $ref: '#/components/parameters/PageKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ContentSectionInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/content/sections/{id}: + get: + tags: [SiteContent] + summary: 内容区块详情 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + patch: + tags: [SiteContent] + summary: 更新内容区块草稿 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ContentSectionInput' + responses: + '200': + $ref: '#/components/responses/Ok' + delete: + tags: [SiteContent] + summary: 归档内容区块 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/content/sections/{id}/publish: + post: + tags: [SiteContent] + summary: 发布内容区块 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/PublishRequest' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/competitions: + get: + tags: [CompetitionAdmin] + summary: 赛道列表 + parameters: + - $ref: '#/components/parameters/Page' + - $ref: '#/components/parameters/PageSize' + - $ref: '#/components/parameters/Status' + responses: + '200': + $ref: '#/components/responses/Paged' + post: + tags: [CompetitionAdmin] + summary: 新建赛道 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CompetitionInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/competitions/{id}: + get: + tags: [CompetitionAdmin] + summary: 赛道详情 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + patch: + tags: [CompetitionAdmin] + summary: 更新赛道 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CompetitionInput' + responses: + '200': + $ref: '#/components/responses/Ok' + delete: + tags: [CompetitionAdmin] + summary: 删除或归档赛道 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/competitions/{id}/sections: + get: + tags: [CompetitionAdmin] + summary: 获取赛道页内容区块 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + post: + tags: [CompetitionAdmin] + summary: 新建赛道页内容区块 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ContentSectionInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/competitions/{id}/schedules: + get: + tags: [CompetitionAdmin] + summary: 赛程列表 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + post: + tags: [CompetitionAdmin] + summary: 新建赛程 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/competition-schedules/{id}: + patch: + tags: [CompetitionAdmin] + summary: 更新赛程 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleInput' + responses: + '200': + $ref: '#/components/responses/Ok' + delete: + tags: [CompetitionAdmin] + summary: 删除赛程 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/competitions/{id}/resources: + get: + tags: [CompetitionAdmin] + summary: 赛道资源列表 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + post: + tags: [CompetitionAdmin] + summary: 新建赛道资源 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/competition-resources/{id}: + patch: + tags: [CompetitionAdmin] + summary: 更新赛道资源 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceInput' + responses: + '200': + $ref: '#/components/responses/Ok' + delete: + tags: [CompetitionAdmin] + summary: 删除赛道资源 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/uploads/policy: + post: + tags: [Media] + summary: 获取 OSS 上传凭证 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UploadPolicyRequest' + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ApiResponse' + - type: object + properties: + data: + $ref: '#/components/schemas/UploadPolicyResponse' + + /admin/uploads/complete: + post: + tags: [Media] + summary: 上传完成登记 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UploadCompleteRequest' + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ApiResponse' + - type: object + properties: + data: + $ref: '#/components/schemas/FileRecord' + + /admin/files: + get: + tags: [Media] + summary: 文件列表 + parameters: + - $ref: '#/components/parameters/Page' + - $ref: '#/components/parameters/PageSize' + - name: scene + in: query + schema: + type: string + - name: fileCategory + in: query + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Paged' + + /admin/courses: + get: + tags: [CoursesAdmin] + summary: 课程列表 + parameters: + - $ref: '#/components/parameters/Page' + - $ref: '#/components/parameters/PageSize' + - $ref: '#/components/parameters/Status' + responses: + '200': + $ref: '#/components/responses/Paged' + post: + tags: [CoursesAdmin] + summary: 新建课程 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CourseInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/courses/{id}: + get: + tags: [CoursesAdmin] + summary: 课程详情 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + patch: + tags: [CoursesAdmin] + summary: 更新课程 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CourseInput' + responses: + '200': + $ref: '#/components/responses/Ok' + delete: + tags: [CoursesAdmin] + summary: 删除课程 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/courses/{id}/status: + patch: + tags: [CoursesAdmin] + summary: 更新课程发布状态 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StatusUpdate' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/works: + get: + tags: [WorksAdmin] + summary: 作品列表 + parameters: + - $ref: '#/components/parameters/Page' + - $ref: '#/components/parameters/PageSize' + - $ref: '#/components/parameters/Status' + - name: keyword + in: query + schema: + type: string + - name: reviewStatus + in: query + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Paged' + post: + tags: [WorksAdmin] + summary: 新建作品 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/WorkInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/works/{id}: + get: + tags: [WorksAdmin] + summary: 作品详情 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + patch: + tags: [WorksAdmin] + summary: 更新作品 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/WorkInput' + responses: + '200': + $ref: '#/components/responses/Ok' + delete: + tags: [WorksAdmin] + summary: 删除作品 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/works/{id}/status: + patch: + tags: [WorksAdmin] + summary: 更新作品发布状态 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StatusUpdate' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/works/{id}/images: + post: + tags: [WorksAdmin] + summary: 添加作品图片 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/WorkImageInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/work-images/{id}: + delete: + tags: [WorksAdmin] + summary: 删除作品图片 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/works/{id}/files: + post: + tags: [WorksAdmin] + summary: 添加作品附件 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/WorkFileInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/work-files/{id}: + delete: + tags: [WorksAdmin] + summary: 删除作品附件 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/evaluation/rounds: + get: + tags: [Evaluation] + summary: 评审轮次列表 + parameters: + - name: competitionId + in: query + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Paged' + post: + tags: [Evaluation] + summary: 创建评审轮次 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationRoundInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/evaluation/rounds/{id}: + get: + tags: [Evaluation] + summary: 评审轮次详情 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + patch: + tags: [Evaluation] + summary: 更新评审轮次 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationRoundInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/evaluation/rounds/{id}/lock: + post: + tags: [Evaluation] + summary: 锁定评审轮次 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/evaluation/rounds/{id}/criteria: + get: + tags: [Evaluation] + summary: 评分指标列表 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + post: + tags: [Evaluation] + summary: 创建评分指标 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationCriterionInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/evaluation/rounds/{id}/assignments: + get: + tags: [Evaluation] + summary: 评分任务列表 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Paged' + post: + tags: [Evaluation] + summary: 分配作品给评委 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationAssignmentInput' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/evaluation/my-assignments: + get: + tags: [Evaluation] + summary: 评委查看自己的评分任务 + responses: + '200': + $ref: '#/components/responses/Paged' + + /admin/evaluation/assignments/{id}/scores: + post: + tags: [Evaluation] + summary: 提交评分 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ScoreSubmitRequest' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/evaluation/rounds/{id}/results: + get: + tags: [Evaluation] + summary: 评审结果汇总 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Paged' + + /admin/evaluation/rounds/{id}/results/calculate: + post: + tags: [Evaluation] + summary: 重新计算评分排名 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/evaluation/rounds/{id}/results/publish: + post: + tags: [Evaluation] + summary: 发布评审结果 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/inquiries: + get: + tags: [InquiriesAdmin] + summary: 咨询线索列表 + parameters: + - $ref: '#/components/parameters/Page' + - $ref: '#/components/parameters/PageSize' + - name: status + in: query + schema: + $ref: '#/components/schemas/InquiryStatus' + responses: + '200': + $ref: '#/components/responses/Paged' + + /admin/inquiries/{id}: + get: + tags: [InquiriesAdmin] + summary: 咨询线索详情 + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /admin/inquiries/{id}/status: + patch: + tags: [InquiriesAdmin] + summary: 更新咨询状态 + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/InquiryStatusUpdate' + responses: + '200': + $ref: '#/components/responses/Ok' + + /site/config: + get: + tags: [PublicSite] + summary: 获取站点基础配置 + security: [] + responses: + '200': + $ref: '#/components/responses/Ok' + + /site/home: + get: + tags: [PublicSite] + summary: 获取首页内容配置 + security: [] + responses: + '200': + $ref: '#/components/responses/Ok' + + /competition: + get: + tags: [PublicSite] + summary: 获取赛道页聚合配置 + security: [] + responses: + '200': + $ref: '#/components/responses/Ok' + + /competition/schedule: + get: + tags: [PublicSite] + summary: 获取赛程安排 + security: [] + responses: + '200': + $ref: '#/components/responses/Ok' + + /competition/resources: + get: + tags: [PublicSite] + summary: 获取参考资源 + security: [] + responses: + '200': + $ref: '#/components/responses/Ok' + + /courses: + get: + tags: [PublicSite] + summary: 获取课程列表 + security: [] + parameters: + - $ref: '#/components/parameters/Page' + - $ref: '#/components/parameters/PageSize' + - name: type + in: query + schema: + $ref: '#/components/schemas/CourseType' + responses: + '200': + $ref: '#/components/responses/Paged' + + /courses/{id}: + get: + tags: [PublicSite] + summary: 获取课程详情 + security: [] + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /works: + get: + tags: [PublicSite] + summary: 获取作品列表 + security: [] + parameters: + - $ref: '#/components/parameters/Page' + - $ref: '#/components/parameters/PageSize' + - name: keyword + in: query + schema: + type: string + - name: category + in: query + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Paged' + + /works/{id}: + get: + tags: [PublicSite] + summary: 获取作品详情 + security: [] + parameters: + - $ref: '#/components/parameters/Id' + responses: + '200': + $ref: '#/components/responses/Ok' + + /works/{id}/vote: + post: + tags: [PublicSite] + summary: 公众投票 + security: [] + parameters: + - $ref: '#/components/parameters/Id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/VoteRequest' + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ApiResponse' + - type: object + properties: + data: + $ref: '#/components/schemas/VoteResponse' + +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + + parameters: + Id: + name: id + in: path + required: true + schema: + type: string + example: '1' + PageKey: + name: pageKey + in: path + required: true + schema: + type: string + example: home + Lang: + name: lang + in: query + required: false + schema: + type: string + default: zh-CN + Page: + name: page + in: query + required: false + schema: + type: integer + minimum: 1 + default: 1 + PageSize: + name: pageSize + in: query + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + Status: + name: status + in: query + required: false + schema: + $ref: '#/components/schemas/PublishStatus' + + responses: + Ok: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ApiResponse' + Paged: + description: Paged result + content: + application/json: + schema: + $ref: '#/components/schemas/PagedResponse' + Unauthorized: + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + schemas: + ApiResponse: + type: object + required: [code, message, data] + properties: + code: + type: integer + example: 0 + message: + type: string + example: ok + data: + nullable: true + + PagedResponse: + type: object + required: [code, message, data] + properties: + code: + type: integer + example: 0 + message: + type: string + example: ok + data: + type: object + required: [list, page, pageSize, total] + properties: + list: + type: array + items: + type: object + page: + type: integer + example: 1 + pageSize: + type: integer + example: 20 + total: + type: integer + example: 100 + + ErrorResponse: + type: object + properties: + code: + type: integer + example: 40001 + message: + type: string + example: 无权限 + data: + nullable: true + + PublishStatus: + type: string + enum: [draft, published, disabled, archived] + + InquiryStatus: + type: string + enum: [pending, contacted, closed] + + CourseType: + type: string + enum: [roadshow, training] + + LoginRequest: + type: object + required: [username, password] + properties: + username: + type: string + example: admin + password: + type: string + format: password + example: admin123 + + LoginResponse: + type: object + properties: + accessToken: + type: string + refreshToken: + type: string + expiresAt: + type: string + format: date-time + user: + $ref: '#/components/schemas/AdminUser' + + AdminUser: + type: object + properties: + id: + type: string + example: '1' + username: + type: string + example: admin + displayName: + type: string + example: 超级管理员 + roles: + type: array + items: + type: string + example: [super_admin] + permissions: + type: array + items: + type: string + example: ['site:read', 'site:write', 'work:read'] + + Dashboard: + type: object + properties: + worksCount: + type: integer + publishedWorks: + type: integer + coursesCount: + type: integer + inquiriesCount: + type: integer + filesCount: + type: integer + pendingScores: + type: integer + + SiteConfigInput: + type: object + properties: + name: + type: string + example: 模灵科技 + englishName: + type: string + example: Soul of Model Technology + productName: + type: string + example: AI SoulMate + seo: + type: object + navigation: + type: array + items: + type: object + contact: + type: object + + ContentSectionInput: + type: object + required: [sectionKey, sectionName, content] + properties: + sectionKey: + type: string + example: hero + sectionName: + type: string + example: 首页 Hero + title: + type: string + subtitle: + type: string + content: + type: object + description: 区块内容 JSON + sortOrder: + type: integer + default: 0 + status: + $ref: '#/components/schemas/PublishStatus' + + PublishRequest: + type: object + properties: + publishNote: + type: string + example: 更新赛程时间 + + CompetitionInput: + type: object + required: [code, slug, title] + properties: + code: + type: string + example: smart-new-fashion-2026 + slug: + type: string + example: smart-fashion + title: + type: string + example: 智·造新时尚 + subtitle: + type: string + description: + type: string + coverUrl: + type: string + officialUrl: + type: string + organizer: + type: string + contractor: + type: string + startAt: + type: string + format: date-time + endAt: + type: string + format: date-time + lang: + type: string + default: zh-CN + status: + $ref: '#/components/schemas/PublishStatus' + + ScheduleInput: + type: object + required: [title] + properties: + title: + type: string + example: 报名与命题发布 + dateText: + type: string + example: 2026.04 + startAt: + type: string + format: date-time + endAt: + type: string + format: date-time + description: + type: string + sortOrder: + type: integer + default: 0 + status: + $ref: '#/components/schemas/PublishStatus' + + ResourceInput: + type: object + required: [title, resourceType] + properties: + title: + type: string + example: 作品提交模板 + description: + type: string + resourceType: + type: string + enum: [pdf, zip, image, link, video] + category: + type: string + fileId: + type: string + fileUrl: + type: string + externalUrl: + type: string + isDownloadable: + type: boolean + default: false + openAt: + type: string + format: date-time + sortOrder: + type: integer + default: 0 + status: + $ref: '#/components/schemas/PublishStatus' + + UploadPolicyRequest: + type: object + required: [fileName, mimeType, size, scene, usage] + properties: + fileName: + type: string + example: cover.png + mimeType: + type: string + example: image/png + size: + type: integer + example: 204800 + scene: + type: string + enum: [site, competition, course, work, resource] + usage: + type: string + enum: [cover, gallery, video, model, attachment, logo, resource] + + UploadPolicyResponse: + type: object + properties: + uploadUrl: + type: string + method: + type: string + example: POST + fileKey: + type: string + formData: + type: object + expiresAt: + type: string + format: date-time + + UploadCompleteRequest: + type: object + required: [fileKey, originalName, url, mimeType, size] + properties: + fileKey: + type: string + originalName: + type: string + url: + type: string + mimeType: + type: string + extension: + type: string + size: + type: integer + width: + type: integer + height: + type: integer + duration: + type: integer + scene: + type: string + fileCategory: + type: string + + FileRecord: + type: object + properties: + id: + type: string + fileKey: + type: string + originalName: + type: string + url: + type: string + mimeType: + type: string + extension: + type: string + size: + type: string + width: + type: integer + nullable: true + height: + type: integer + nullable: true + duration: + type: integer + nullable: true + scene: + type: string + fileCategory: + type: string + storageProvider: + type: string + example: aliyun-oss + createdAt: + type: string + format: date-time + + CourseInput: + type: object + required: [type, title] + properties: + courseNo: + type: string + example: rs-01 + type: + $ref: '#/components/schemas/CourseType' + title: + type: string + example: 北服 × 模灵联合宣讲回放 + summary: + type: string + description: + type: string + coverUrl: + type: string + coverFileId: + type: string + videoUrl: + type: string + videoFileId: + type: string + externalVideoUrl: + type: string + sourceType: + type: string + enum: [oss, external] + partner: + type: string + speaker: + type: string + durationText: + type: string + sortOrder: + type: integer + status: + $ref: '#/components/schemas/PublishStatus' + + StatusUpdate: + type: object + required: [status] + properties: + status: + $ref: '#/components/schemas/PublishStatus' + + WorkInput: + type: object + required: [title] + properties: + competitionId: + type: string + workNo: + type: string + example: SMT-2026-018 + title: + type: string + example: 青金缕 · 可穿戴胸针 + category: + type: string + direction: + type: string + authorName: + type: string + school: + type: string + coverUrl: + type: string + coverFileId: + type: string + modelUrl: + type: string + modelFileId: + type: string + summary: + type: string + designSpec: + type: object + aigcSummary: + type: string + prompt: + type: string + generationParams: + type: object + materialStatus: + type: string + enum: [pending_submit, submitted, qualified, rejected] + reviewStatus: + type: string + enum: [none, reviewing, finalist, winner, rejected] + featured: + type: boolean + voteCount: + type: integer + sortOrder: + type: integer + status: + $ref: '#/components/schemas/PublishStatus' + + WorkImageInput: + type: object + required: [imageUrl] + properties: + fileId: + type: string + imageUrl: + type: string + altText: + type: string + sortOrder: + type: integer + default: 0 + + WorkFileInput: + type: object + required: [fileName, fileUrl] + properties: + fileId: + type: string + fileName: + type: string + fileUrl: + type: string + fileType: + type: string + fileSize: + type: integer + sortOrder: + type: integer + default: 0 + + EvaluationRoundInput: + type: object + required: [competitionId, name, roundType] + properties: + competitionId: + type: string + name: + type: string + example: 初评 + roundType: + type: string + enum: [preliminary, semi_final, final] + description: + type: string + expertWeight: + type: number + format: float + example: 80 + publicVoteWeight: + type: number + format: float + example: 20 + startAt: + type: string + format: date-time + endAt: + type: string + format: date-time + status: + type: string + enum: [draft, open, closed, locked, published] + + EvaluationCriterionInput: + type: object + required: [name, maxScore, weight] + properties: + name: + type: string + example: 创意表达 + description: + type: string + maxScore: + type: number + format: float + example: 100 + weight: + type: number + format: float + example: 30 + sortOrder: + type: integer + default: 0 + + EvaluationAssignmentInput: + type: object + required: [workIds, judgeIds] + properties: + workIds: + type: array + items: + type: string + judgeIds: + type: array + items: + type: string + mode: + type: string + enum: [manual, random, category] + default: manual + + ScoreSubmitRequest: + type: object + required: [scores] + properties: + scores: + type: array + items: + type: object + required: [criterionId, score] + properties: + criterionId: + type: string + score: + type: number + format: float + comment: + type: string + overallComment: + type: string + submit: + type: boolean + description: true 表示提交并进入 submitted 状态,false 表示暂存 + + InquiryStatusUpdate: + type: object + required: [status] + properties: + status: + $ref: '#/components/schemas/InquiryStatus' + remark: + type: string + + VoteRequest: + type: object + required: [visitorId] + properties: + visitorId: + type: string + example: browser-fingerprint-id + + VoteResponse: + type: object + properties: + workId: + type: string + voteCount: + type: integer + voted: + type: boolean diff --git a/package.json b/package.json new file mode 100644 index 0000000..935af9d --- /dev/null +++ b/package.json @@ -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" + } +} diff --git a/scripts/build.mjs b/scripts/build.mjs new file mode 100644 index 0000000..76eb29d --- /dev/null +++ b/scripts/build.mjs @@ -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')}`)