整理 clean 目录结构说明和忽略规则

.gitignore

@@ -50,13 +50,15 @@ src/lang/source-use.json
 .vscode
 
 /share-binary/
-/electron/resources/extra/linux-arm64/
+/archive/
-/electron/resources/extra/linux-x86/
+/packaging/resources/linux-arm64/
-/electron/resources/extra/osx-arm64/
+/packaging/resources/linux-x86/
-/electron/resources/extra/osx-x86/
+/packaging/resources/osx/
-/electron/resources/extra/win-x86/
+/packaging/resources/osx-arm64/
-/electron/resources/extra/osx/
+/packaging/resources/osx-x86/
-/electron/resources/extra/common/playwright/chromium-1200/chrome-mac/
+/packaging/resources/win-x86-backup/
+/packaging/resources/common/chromium/
+/packaging/vendor/
 nul
 
 # Python cache
@@ -92,15 +94,30 @@ fix_server.py
 build/
 output/
 tmp/
-resources-bundles/
+/resources-bundles/
-/electron/resources/extra/win-x86-backup/
+/dist/
-/electron/resources/extra/common/playwright/
+/dist-ssr/
-/electron/resources/extra/common/python/
+/dist-electron/
-/electron/resources/extra/common/fonts/
+/dist-release/
-/electron/resources/extra/common/models/
+/dist-release-final/
-/electron/resources/extra/common/bgm/
+/dist-release-build/
-/electron/resources/extra/common/chromium/
+/dist-release-new/
-/electron/resources/extra/common/soundEffects/
+/release-assets/
+/win-unpacked/
+/builder-debug.yml
+/builder-effective-config.yaml
+*.blockmap
+*.nsis.7z
+/packaging/resources/common/playwright/
+/packaging/resources/common/python/
+/packaging/resources/common/fonts/
+/packaging/resources/common/models/
+/packaging/resources/common/bgm/
+/packaging/resources/common/soundEffects/
+/packaging/resources/common/python-scripts/
+/packaging/resources/stickers/
+/packaging/resources/common/config/* - 副本*.json
+/packaging/resources/common/config/*-backup-*.json
 
 # Clean repository: media/content packs are not source code
 *.mp3
@@ -134,10 +151,20 @@ active-run.json
 activation-server/*.db
 user-server/*.db
 user-server/_archive_old_versions/
-fonts/
+/fonts/
-bgm/
+/bgm/
-ziti/
+/ziti/
-resources/
+/resources/
-resources-bundles/
+/resources-bundles/
 tools/**/runs/
-electron/resources/voice-preview-cache/
+/packaging/resources/voice-preview-cache/*.wav
+
+# Clean repository: local auth/admin runtime data
+local-auth-data/
+server/local-auth-data/
+*.sqlite
+*.sqlite3
+users.json
+
+# Clean repository: large redistributable installers
+/packaging/build-resources/vc_redist*.exe

README-CLEAN.md

@@ -48,6 +48,27 @@ http://127.0.0.1:3302/admin/?api=http://127.0.0.1:3302
 npm.cmd run start:check
 ```
 
+## 打包客户端
+
+客户端安装包不包含本地认证服务和管理后台，只会连接你指定的认证服务地址。
+
+```bat
+npm.cmd run build:client:win -- --auth-url=https://auth.example.com
+```
+
+本地测试可以先只打包目录，速度更快：
+
+```bat
+npm.cmd run build:client:win -- --auth-url=http://127.0.0.1:3302 --dir
+```
+
+说明：
+
+- `--auth-url` 可以带或不带 `/api`，脚本会自动规范化。
+- 打包时会把该地址注入客户端默认配置。
+- 运行时仍可通过环境变量 `AUTH_SERVER_URL` 覆盖认证服务地址。
+- 打包配置已排除 `server/`、`admin-panel/`、`scripts/local-auth-server.cjs` 和 `local-auth-data/`。
+
 ## 系统 API Key 配置
 
 进入 `http://127.0.0.1:3302/admin/` 后，在“系统配置”里填写：
@@ -57,3 +78,14 @@ npm.cmd run start:check
 - 其他 OSS、RunningHub、火山引擎、云美颜配置也可以在这里维护
 
 这些配置会通过 `/api/system/config/public` 提供给本地应用作为兜底配置。
+
+## 目录结构约定
+
+clean 目录就是后续入库的项目根目录；外层 `aIzhinengti` 只作为临时整理和参考目录。
+
+- 源码放在 `src/`、`electron/`、`server/`、`admin-panel/`。
+- 打包相关资源统一放在 `packaging/`。
+- 大型本地依赖放在 `packaging/vendor/`，例如 Python runtime、FFmpeg、Playwright、模型、字体、BGM；这些内容默认不入库。
+- 构建输出、运行数据和历史整理残留分别由 `.gitignore` 和 `archive/` 隔离。
+
+更完整说明见 `docs/PROJECT_LAYOUT.md` 和 `packaging/README.md`。

docs/PROJECT_LAYOUT.md

@@ -0,0 +1,33 @@
+# Project Layout
+
+`aIzhinengti-clean` is the repository-ready project root. The parent `aIzhinengti` directory is only a temporary workspace/reference area.
+
+## Root
+
+- `src/`: renderer application source.
+- `electron/`: Electron main/preload code and app configuration source.
+- `server/`, `admin-panel/`: local auth/admin support code.
+- `scripts/`: development, packaging, release, and maintenance scripts.
+- `packaging/`: build resources and local packaging dependencies.
+- `docs/`: project notes and operational documentation.
+- `archive/`: preserved cleanup leftovers. Do not treat this as active source.
+
+## Packaging Split
+
+- Track small, intentional packaging assets such as icons and JSON config.
+- Keep large runtimes and media packs under `packaging/vendor` or ignored resource subdirectories.
+- Do not place Python runtimes, FFmpeg builds, Playwright browsers, models, fonts, BGM, or generated release output in the project root.
+
+## Generated Or Local-Only Directories
+
+The following root directories are local outputs or runtime data and should stay ignored:
+
+```text
+build/
+data/
+dist/
+dist-electron/
+dist-release-final/
+resources-bundles/
+node_modules/
+```

packaging/README.md

@@ -0,0 +1,20 @@
+# Packaging Layout
+
+`packaging/` keeps build-time assets separate from application source code.
+
+## Directories
+
+- `build-resources/`: Electron Builder icons and installer assets. Small icon files are source-controlled. Large redistributables such as `vc_redist*.exe` stay local and are ignored.
+- `resources/`: Files copied into the packaged app as `resources/extra`, such as config files, cover templates, tray assets, sound effects, and voice preview cache metadata.
+- `vendor/`: Local packaging dependencies and large runtime bundles, including Playwright, Python runtime, FFmpeg, models, fonts, ziti, and BGM. This directory is intentionally ignored by Git.
+
+## Restore Local Vendor Assets
+
+Use the existing preparation scripts when a fresh checkout needs local packaging dependencies:
+
+```bat
+npm.cmd run prepare-package
+node scripts\copy-playwright-browser.cjs
+```
+
+Dependency download helpers write into `packaging/vendor` instead of the project root.