Merge pull request #6 from tobenot/cursor/design-flexible-backend-project-structure-649c

tobenot · web-flow · commit 5807f7b98f17 · 2025-08-08T15:33:21.000+08:00
Design flexible backend project structure
diff --git a/.github/README_TEMPLATE.md b/.github/README_TEMPLATE.md
@@ -0,0 +1,5 @@
+This file exists in the template to remind consumers of the template update workflow.
+
+- Update via `scripts/update-from-template.sh`
+- See `MIGRATION.md` for controlled areas and safe-overwrite guidance.
+- Non-blocking pre-commit reminders can be installed via `bash scripts/install-git-hooks.sh`.
diff --git a/.gitignore b/.gitignore
@@ -142,4 +142,8 @@ vite.config.ts.timestamp-*
 /prisma/dev.db
 /prisma/dev.db-journal
 # Keep migrations in version control
-!/prisma/migrations
+!/prisma/migrations
+
+# Template update cache and backups
+.template-cache/
+.template-backup/
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,34 @@
+## Template Migration Guide
+
+This repository is used as a Git template. Projects may selectively copy updates.
+
+### Controlled (safe-to-overwrite) areas
+- `.github/`
+- `scripts/`
+- `src/framework/`
+- `src/server.ts` (only the marked template blocks)
+- `tsconfig.json`
+- `vercel.json`
+- Documentation files: `README.md`, `CONFIGURATION.md`, `CORS_GUIDE.md`, `CORS_SOLUTION_SUMMARY.md`
+
+Business-specific code should live outside these areas (e.g. `src/app/**`, `src/modules/**`).
+
+### Updating from template
+- Preview changes:
+  ```bash
+  bash scripts/update-from-template.sh            # latest
+  bash scripts/update-from-template.sh vX.Y.Z     # specific tag
+  ```
+- Apply with backup:
+  ```bash
+  APPLY=1 bash scripts/update-from-template.sh vX.Y.Z
+  ```
+  Backups are stored in `.template-backup/vX.Y.Z/`.
+
+- The current project records template source in `template.lock`.
+
+### Editing template-controlled code in a project
+If you need to modify controlled areas for a project, prefer sending changes back to the template and then updating via the script. A non-blocking pre-commit hook will remind you when you modify controlled paths.
+
+### Template blocks in files
+For files like `src/server.ts`, only the code inside the `// <template:...>` blocks is intended to be overwritten by template updates. Avoid custom edits within these blocks.
diff --git a/README.md b/README.md
@@ -179,4 +179,16 @@ If you have any questions or need help, please:
 
 **Made with ❤️ by [tobenot](https://github.com/tobenot)**
 
-*This project is maintained as an independent open-source effort to provide a solid foundation for web game backends.*
+*This project is maintained as an independent open-source effort to provide a solid foundation for web game backends.*
+
+## Template Updates
+
+- Use the bundled script to preview/apply template updates:
+  - Preview latest: `bash scripts/update-from-template.sh`
+  - Apply a specific tag with backup: `APPLY=1 bash scripts/update-from-template.sh vX.Y.Z`
+- The template source and version are recorded in `template.lock`.
+- Install a non-blocking pre-commit reminder:
+  ```bash
+  bash scripts/install-git-hooks.sh
+  ```
+- Controlled areas (prefer updating via template): `.github/`, `scripts/`, `src/framework/`, template-marked blocks in `src/server.ts`, `tsconfig.json`, `vercel.json`, and docs listed in `MIGRATION.md`.
diff --git a/package.json b/package.json
@@ -20,6 +20,10 @@
     "version:minor": "node scripts/update-version.js minor",
     "version:major": "node scripts/update-version.js major",
     "get-next-version": "node scripts/get-next-version.js",
+    "template:update": "bash scripts/update-from-template.sh",
+    "template:apply": "APPLY=1 bash scripts/update-from-template.sh",
+    "template:apply:blocks": "APPLY=1 BLOCKS_ONLY=1 bash scripts/update-from-template.sh",
+    "hooks:install": "bash scripts/install-git-hooks.sh",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "repository": {
diff --git a/scripts/apply-template-blocks.js b/scripts/apply-template-blocks.js
@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+function read(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+}
+
+function replaceBlock(target, source, name) {
+  const start = new RegExp(`// \\<template:${name}\\>`);
+  const end = new RegExp(`// \\</template:${name}\\>`);
+
+  const tStart = target.search(start);
+  const tEnd = target.search(end);
+  const sStart = source.search(start);
+  const sEnd = source.search(end);
+
+  if (tStart === -1 || tEnd === -1 || sStart === -1 || sEnd === -1) {
+    return { content: target, changed: false, reason: 'missing-markers' };
+  }
+
+  const tPre = target.slice(0, tStart);
+  const tPost = target.slice(target.indexOf('\n', tEnd) + 1 || tEnd + 1);
+
+  const sBlockStart = source.indexOf('\n', sStart) + 1;
+  const sBlockEnd = source.search(end);
+  const sBlock = source.slice(sBlockStart, sBlockEnd).replace(/^[\n\r]+|[\n\r]+$/g, '') + '\n';
+
+  const replaced = tPre + source.slice(sStart, sStart + ('// <template:'.length + name.length + 3)) // keep start marker line format
+    ? tPre + source.match(start)[0] + '\n' + sBlock + source.match(end)[0] + '\n' + tPost
+    : tPre + source.match(start)[0] + '\n' + sBlock + source.match(end)[0] + '\n' + tPost;
+
+  // Simpler: construct explicitly using markers from target to preserve comments spacing
+  const tStartLine = target.match(start)[0];
+  const tEndLine = target.match(end)[0];
+  const result = tPre + tStartLine + '\n' + sBlock + tEndLine + '\n' + tPost;
+
+  if (result !== target) {
+    return { content: result, changed: true };
+  }
+  return { content: target, changed: false };
+}
+
+function apply(templateFile, projectFile, blocks) {
+  const src = read(templateFile);
+  const dst = read(projectFile);
+  if (!src || !dst) {
+    console.error(`apply-template-blocks: skip (missing files). template=${!!src} target=${!!dst}`);
+    process.exit(0);
+  }
+
+  let updated = dst;
+  let anyChanged = false;
+  for (const b of blocks) {
+    const { content, changed } = replaceBlock(updated, src, b);
+    updated = content;
+    anyChanged = anyChanged || changed;
+  }
+
+  if (process.env.DRY_RUN === '1') {
+    if (anyChanged) {
+      console.log(`Would update blocks [${blocks.join(', ')}] in ${projectFile}`);
+    } else {
+      console.log(`No block changes needed for ${projectFile}`);
+    }
+    return;
+  }
+
+  if (anyChanged) {
+    fs.writeFileSync(projectFile, updated, 'utf8');
+    console.log(`Updated ${projectFile} blocks: ${blocks.join(', ')}`);
+  } else {
+    console.log(`No changes applied to ${projectFile}`);
+  }
+}
+
+function main() {
+  const [templateFile, projectFile] = process.argv.slice(2);
+  if (!templateFile || !projectFile) {
+    console.error('Usage: node scripts/apply-template-blocks.js <templateFile> <projectFile>');
+    process.exit(1);
+  }
+  apply(templateFile, projectFile, ['bootstrap', 'startup']);
+}
+
+if (require.main === module) {
+  main();
+}
diff --git a/scripts/git-hooks/pre-commit b/scripts/git-hooks/pre-commit
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Non-blocking pre-commit tip for template-controlled areas
+
+STAGED=$(git diff --name-only --cached)
+WARN=0
+
+if echo "$STAGED" | grep -E '^(scripts/|src/framework/|\.github/|tsconfig\.json|vercel\.json)$' >/dev/null; then
+  WARN=1
+fi
+if echo "$STAGED" | grep -E '^src/server\.ts$' >/dev/null; then
+  WARN=1
+fi
+
+if [ "$WARN" -eq 1 ]; then
+  echo "\n⚠️  Heads-up: You're committing changes in template-controlled areas."
+  echo "   Consider applying such changes in the template repo and syncing via scripts/update-from-template.sh."
+  echo "   This is only a reminder; commit will proceed.\n"
+fi
+
+exit 0
diff --git a/scripts/install-git-hooks.sh b/scripts/install-git-hooks.sh
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mkdir -p .git/hooks
+cp -f scripts/git-hooks/pre-commit .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+
+echo "Installed non-blocking pre-commit hook."
diff --git a/scripts/update-from-template.sh b/scripts/update-from-template.sh
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Lightweight template updater: preview with dry-run and apply with backup
+# Usage:
+#   bash scripts/update-from-template.sh            # preview latest
+#   APPLY=1 bash scripts/update-from-template.sh    # apply latest
+#   APPLY=1 bash scripts/update-from-template.sh v1.2.3  # apply specific tag
+# Env:
+#   BLOCKS_ONLY=1  # when applying, only update template blocks in certain files (e.g., src/server.ts)
+
+set -euo pipefail
+
+ROOT=$(pwd)
+CACHE="$ROOT/.template-cache"
+LOCK="$ROOT/template.lock"
+
+# shellcheck disable=SC1090
+source "$LOCK" 2>/dev/null || true
+REPO="${repo:-https://github.com/tobenot/Basic-Web-Game-Backend}"
+TARGET="${1:-${version:-latest}}"
+
+if [ ! -d "$CACHE" ]; then
+  git clone --depth=1 "$REPO" "$CACHE"
+fi
+
+git -C "$CACHE" fetch --tags --depth=1 origin
+
+if [ "$TARGET" = "latest" ]; then
+  LATEST_TAG=$(git -C "$CACHE" tag --sort=-v:refname | head -n1)
+  if [ -z "$LATEST_TAG" ]; then
+    TARGET=$(git -C "$CACHE" rev-parse --short HEAD)
+  else
+    TARGET="$LATEST_TAG"
+  fi
+fi
+
+echo "Using $REPO@$TARGET"
+
+git -C "$CACHE" checkout --force "$TARGET" >/dev/null 2>&1 || true
+
+# Preview changes
+RSYNC_COMMON=(
+  -av
+)
+
+INCLUDES=(
+  --include='.github/***'
+  --include='scripts/***'
+  --include='src/framework/***'
+  --include='src/server.ts'
+  --include='tsconfig.json'
+  --include='vercel.json'
+  --include='README.md'
+  --include='CONFIGURATION.md'
+  --include='CORS_GUIDE.md'
+  --include='CORS_SOLUTION_SUMMARY.md'
+  --exclude='*'
+)
+
+if [[ "${APPLY:-0}" = "1" ]]; then
+  echo "Applying updates..."
+  mkdir -p .template-backup/"$TARGET"
+  if [[ "${BLOCKS_ONLY:-0}" = "1" ]]; then
+    echo "BLOCKS_ONLY=1 -> replacing template blocks in specific files"
+    # Backup target file
+    mkdir -p ".template-backup/$TARGET/src"
+    cp -a src/server.ts ".template-backup/$TARGET/src/server.ts" || true
+    node scripts/apply-template-blocks.js "$CACHE/src/server.ts" "src/server.ts"
+    printf "repo=%s\nversion=%s\n" "$REPO" "$TARGET" > "$LOCK"
+    echo "Applied block updates. Backup at .template-backup/$TARGET"    
+  else
+    rsync "${RSYNC_COMMON[@]}" \
+      --delete \
+      --backup --backup-dir=".template-backup/$TARGET" \
+      "${INCLUDES[@]}" \
+      "$CACHE"/ "$ROOT"/
+    printf "repo=%s\nversion=%s\n" "$REPO" "$TARGET" > "$LOCK"
+    echo "Applied $TARGET. Backup stored in .template-backup/$TARGET"
+  fi
+else
+  echo "Previewing changes (no files will be modified). Set APPLY=1 to apply."
+  rsync -avnc --delete \
+    "${INCLUDES[@]}" \
+    "$CACHE"/ "$ROOT"/
+fi
diff --git a/src/framework/README.md b/src/framework/README.md
@@ -0,0 +1,4 @@
+This directory hosts framework/bootstrap code managed by the template.
+
+- Keep project-specific business logic in `src/app/**` or `src/modules/**`.
+- Changes here should usually be done in the template repository and synced into projects using `scripts/update-from-template.sh`.
diff --git a/src/server.ts b/src/server.ts
@@ -37,6 +37,7 @@ export async function createContext({ req }: { req: any }) {
   return { user: null };
 }
 
+// <template:bootstrap>
 // 3. 创建并配置 Fastify 服务器
 const server = fastify({ maxParamLength: 5000 });
 
@@ -95,7 +96,9 @@ server.register(require('@fastify/static'), {
   root: join(__dirname, '..'),
   prefix: '/'
 });
+// </template:bootstrap>
 
+// <template:startup>
 // 5. 启动服务器
 const start = async () => {
   console.log('🔍 Starting server...');
@@ -123,4 +126,5 @@ console.log('🔍 About to call start()...');
 start().catch(err => {
   console.error('❌ Unhandled error in start():', err);
   process.exit(1);
-}); 
+});
+// </template:startup> 
diff --git a/template.lock b/template.lock
@@ -0,0 +1,2 @@
+repo=https://github.com/tobenot/Basic-Web-Game-Backend
+version=v1.1.1
