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 =
+ '' +
+ '' +
+ "模灵科技管理端
" +
+ "管理公司官网、赛道页、作品、课程、素材和评选流程。
" +
+ '" +
+ "" +
+ "";
+
+ 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 '' + item.label + "
";
+ 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("") : '暂无作品 |
') +
+ "
" +
+ '
' +
+ 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 (
+ '"
+ );
+ }
+
+ 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("") : '暂无课程 |
') +
+ "
" +
+ '
' +
+ 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 (
+ '"
+ );
+ }
+
+ 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(
+ '' +
+ 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 =
+ '' +
+ '' +
+ "模灵科技管理端
" +
+ "管理公司官网、赛道页、作品、课程、素材和评选流程。
" +
+ '" +
+ "" +
+ "";
+
+ 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 '' + item.label + "
";
+ 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("") : '暂无作品 |
') +
+ "
" +
+ '
' +
+ 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 (
+ '"
+ );
+ }
+
+ 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("") : '暂无课程 |
') +
+ "
" +
+ '
' +
+ 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 (
+ '"
+ );
+ }
+
+ 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(
+ '' +
+ 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')}`)