feat: 初始化项目

apps/admin/README.md

@@ -0,0 +1,5 @@
+# Admin（待开发）
+
+预留独立管理后台位置。本次未选择前端框架、安装依赖或开发页面。
+
+后续在此添加独立 `package.json`、构建与部署配置，通过统一后端的管理 API 完成内容管理。服务端必须独立校验管理权限，不依赖前端隐藏按钮。

apps/server/.env.example

@@ -0,0 +1,3 @@
+NODE_ENV=development
+HOST=127.0.0.1
+PORT=3000

apps/server/nest-cli.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true,
+    "tsConfigPath": "tsconfig.build.json"
+  }
+}

apps/server/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@doodle/server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "commonjs",
+  "scripts": {
+    "dev": "nest start --watch",
+    "build": "nest build",
+    "start": "node dist/main.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js"
+  },
+  "dependencies": {
+    "@doodle/contracts": "workspace:*",
+    "@nestjs/common": "11.2.7",
+    "@nestjs/core": "11.2.7",
+    "@nestjs/platform-express": "11.2.7",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "11.0.24",
+    "@nestjs/testing": "11.2.7",
+    "@types/node": "24.19.2",
+    "typescript": "5.9.3"
+  }
+}

apps/server/prisma/README.md

@@ -0,0 +1,7 @@
+# 数据库结构预留目录
+
+后续用于 Prisma 数据模型与版本化数据库迁移。当前未安装 Prisma、未定义表结构，也未连接或创建数据库。
+
+数据库已确认使用 PostgreSQL + Prisma；具体兼容版本在实施时验证并锁定，保留原用户和题型的字符串 ID。目标设计见 [v3.5 数据库设计文档](../../../docs/v3.5/数据库设计文档.md)，当前尚未创建 Schema 或实施数据库迁移。
+
+本目录及未来 Prisma Client 只能由服务端使用，不能作为公共契约包被 admin、web 或小程序导入。

apps/server/scripts/README.md

@@ -0,0 +1,5 @@
+# 服务端脚本预留目录
+
+后续加入 CloudBase 数据导出/导入、七牛文件迁移、关联与计数审计、备份恢复等脚本。
+
+当前未执行任何迁移或外部写入。真实导出、文件和凭证不应提交源码仓库。

apps/server/src/app.module.ts

@@ -0,0 +1,7 @@
+import { Module } from '@nestjs/common';
+import { HealthController } from './health/health.controller';
+
+@Module({
+  controllers: [HealthController],
+})
+export class AppModule {}

apps/server/src/app.setup.ts

@@ -0,0 +1,6 @@
+import type { INestApplication } from '@nestjs/common';
+
+export function configureApplication(app: INestApplication): void {
+  app.setGlobalPrefix('api/v1');
+  app.enableShutdownHooks();
+}

apps/server/src/common/runtime-options.ts

@@ -0,0 +1,27 @@
+export interface RuntimeOptions {
+  host: string;
+  port: number;
+}
+
+export function getRuntimeOptions(
+  env: NodeJS.ProcessEnv = process.env,
+): RuntimeOptions {
+  const rawPort = env.PORT ?? '3000';
+  const port = Number(rawPort);
+  const host = (env.HOST ?? '127.0.0.1').trim();
+
+  if (
+    !/^\d+$/.test(rawPort) ||
+    !Number.isInteger(port) ||
+    port < 1 ||
+    port > 65535
+  ) {
+    throw new Error('PORT must be an integer between 1 and 65535');
+  }
+
+  if (!host) {
+    throw new Error('HOST must not be empty');
+  }
+
+  return { host, port };
+}

apps/server/src/health/health.controller.ts

@@ -0,0 +1,17 @@
+import { Controller, Get } from '@nestjs/common';
+import type { ApiSuccess, HealthStatus } from '@doodle/contracts';
+
+@Controller('health')
+export class HealthController {
+  @Get()
+  getHealth(): ApiSuccess<HealthStatus> {
+    return {
+      code: 0,
+      message: 'ok',
+      data: {
+        status: 'ok',
+        service: 'doodle-store-server',
+      },
+    };
+  }
+}

apps/server/src/main.ts

@@ -0,0 +1,31 @@
+import 'reflect-metadata';
+import { Logger } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { configureApplication } from './app.setup';
+import { getRuntimeOptions } from './common/runtime-options';
+
+async function bootstrap(): Promise<void> {
+  try {
+    process.loadEnvFile();
+  } catch (error) {
+    if (!(
+      error instanceof Error &&
+      'code' in error &&
+      error.code === 'ENOENT'
+    )) {
+      throw error;
+    }
+  }
+
+  const { port, host } = getRuntimeOptions();
+  const app = await NestFactory.create(AppModule);
+  configureApplication(app);
+  await app.listen(port, host);
+  Logger.log(`Listening on http://${host}:${port}/api/v1/health`, 'Bootstrap');
+}
+
+void bootstrap().catch((error: unknown) => {
+  Logger.error(error, undefined, 'Bootstrap');
+  process.exit(1);
+});

apps/server/src/modules/README.md

@@ -0,0 +1,5 @@
+# 业务模块预留目录
+
+后续按迁移方案逐步加入 auth、users、worksheets、categories、favorites、downloads、content、assets 和 legacy 模块。
+
+当前没有创建任何业务 Controller、Service、数据库模型或伪接口。健康检查独立放在 `src/health`，不代表业务迁移已完成。

apps/server/test/health.test.ts

@@ -0,0 +1,37 @@
+import 'reflect-metadata';
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { Test } from '@nestjs/testing';
+import { AppModule } from '../src/app.module';
+import { configureApplication } from '../src/app.setup';
+
+test('服务可以启动并通过带版本前缀的 HTTP 健康检查', async (context) => {
+  const testingModule = await Test.createTestingModule({
+    imports: [AppModule],
+  }).compile();
+  const app = testingModule.createNestApplication({ logger: false });
+  context.after(async () => {
+    await app.close();
+  });
+  configureApplication(app);
+  await app.listen(0, '127.0.0.1');
+  const origin = await app.getUrl();
+
+  const response = await fetch(`${origin}/api/v1/health`, {
+    signal: AbortSignal.timeout(5000),
+  });
+  assert.equal(response.status, 200);
+  assert.deepEqual(await response.json(), {
+    code: 0,
+    message: 'ok',
+    data: {
+      status: 'ok',
+      service: 'doodle-store-server',
+    },
+  });
+
+  const unversioned = await fetch(`${origin}/health`, {
+    signal: AbortSignal.timeout(5000),
+  });
+  assert.equal(unversioned.status, 404);
+});

apps/server/test/runtime-options.test.ts

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { getRuntimeOptions } from '../src/common/runtime-options';
+
+test('使用本地默认 host 和 port', () => {
+  assert.deepEqual(getRuntimeOptions({}), {
+    host: '127.0.0.1',
+    port: 3000,
+  });
+});
+
+test('读取显式 host 和 port', () => {
+  assert.deepEqual(getRuntimeOptions({ HOST: '0.0.0.0', PORT: '4000' }), {
+    host: '0.0.0.0',
+    port: 4000,
+  });
+});
+
+test('拒绝非法端口', () => {
+  for (const port of ['', '0', '65536', '-1', '3000abc', '3.5', '1e3']) {
+    assert.throws(() => getRuntimeOptions({ PORT: port }), /PORT/);
+  }
+});
+
+test('拒绝空 host', () => {
+  assert.throws(() => getRuntimeOptions({ HOST: '  ' }), /HOST/);
+});

apps/server/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "dist-test", "test"]
+}

apps/server/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "sourceMap": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"],
+  "exclude": ["node_modules", "dist", "dist-test"]
+}

apps/server/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist-test",
+    "sourceMap": false
+  }
+}

apps/web/README.md

@@ -0,0 +1,5 @@
+# Web（待开发）
+
+预留面向国内中文家长的用户网站位置。本次未选择前端框架、安装依赖或开发页面。
+
+后续根据 SEO 需求确定 SSR/预渲染方案，添加独立 `package.json`、构建与部署配置，复用统一后端 API。私有练习纸生成逻辑不导入浏览器代码。