Update server backend skill for upload flows
This commit is contained in:
parent
420baca63d
commit
694df5ac4c
@ -1,6 +1,6 @@
|
||||
---
|
||||
name: th1-server-backend
|
||||
description: TH1 project-specific server/backend guide for Aliyun Function Compute, OSS, Tablestore, Steam AuthTicket pre-verification/cache, STS token issuing, GameUploadFunction, Unity OSS upload clients, player bug reports, collect data downloads, and Tools/OSS pulled data. Use whenever Codex works on TH1 服务端, 阿里云函数计算, OSS/STS 上传失败, Steam 预校验, 表格存储缓存, game-upload-function, collectdata/ossdata/bugreport paths, player bug viewer, cloud save or telemetry upload bugs, server deploy/debug work, or analysis of Tools/OSS/Data files.
|
||||
description: TH1 project-specific server/backend guide for Aliyun Function Compute, OSS, Tablestore, Steam AuthTicket pre-verification/cache, STS token issuing, GameUploadFunction, Unity OSS upload clients, upload flow tests, player bug reports, multilingual reports, questionnaire answers, collect data downloads, and Tools/OSS pulled data. Use whenever Codex works on TH1 服务端, 阿里云函数计算, OSS/STS 上传失败, Steam 预校验, 表格存储缓存, game-upload-function, collectdata/ossdata/bugreport/multilingualreport/questionnaire paths, player bug/multilingual/questionnaire viewers, cloud save or telemetry upload bugs, server deploy/debug work, or analysis of Tools/OSS/Data files.
|
||||
---
|
||||
|
||||
# TH1 Server Backend
|
||||
@ -15,10 +15,14 @@ Use this skill for TH1 server-side upload/auth/data work in `F:\th1new`. Treat `
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Oss/OssManager.cs`
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Oss/StsTokenService.cs`
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Oss/OssUploadService.cs`
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Oss/PlayerBugReportService.cs` when working on player-submitted bug packages or save archive pairing
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Oss/PlayerBugReportService.cs` when working on player-submitted bug packages, multilingual report packages, or save archive pairing
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Questionnaire/QuestionnaireUploadService.cs` when working on questionnaire answer JSON upload payloads
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Editor/SteamEditorWindow.cs` when working on Steam-authenticated upload flow tests
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Editor/OssEditorWindow.cs` when working on collect downloads, upload tests, stats, or JSON export
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Editor/PlayerBugReportEditorWindow.cs` when working on the temporary Unity editor bug-report UI
|
||||
- `Tools/PlayerBugViewer/player_bug_viewer.py` when working on developer-side bug report browsing/restoring
|
||||
- `Tools/PlayerMultilingualReportViewer/player_multilingual_report_viewer.py` when working on developer-side multilingual report browsing
|
||||
- `Tools/PlayerQuestionnaireViewer/player_questionnaire_viewer.py` when working on developer-side questionnaire answer browsing
|
||||
|
||||
For the detailed service contract, data layout, and triage notes, read `references/server-map.md`.
|
||||
|
||||
@ -35,6 +39,8 @@ Keep the current single Function Compute service/file unless the user explicitly
|
||||
- Steam identity pre-verification: `action=steamauth`, cache key `{steamId}#steamauth`, 10-minute identity cache.
|
||||
- Standard uploads: `type=ossdata` and `type=collectdata`, 3 MB Post Policy limit, 5-minute STS credential cache.
|
||||
- Player bug reports: `type=bugreport`, 10 MB Post Policy limit, unique `.zip` object key, no STS credential cache to avoid overwrites.
|
||||
- Multilingual reports: `type=multilingualreport`, 1 MB Post Policy limit, unique `.zip` object key, no STS credential cache.
|
||||
- Questionnaire answers: `type=questionnaire`, 512 KB Post Policy limit, unique `.json` object key, no STS credential cache.
|
||||
|
||||
## Safety Rules
|
||||
|
||||
@ -57,23 +63,28 @@ Keep the current single Function Compute service/file unless the user explicitly
|
||||
2. Trace both sides of the contract.
|
||||
- Backend request/response shape lives in `index.js`.
|
||||
- Unity request serialization lives in `StsTokenService.cs`.
|
||||
- Unity credential caching, Steam auth warmup, and `ossdata`/`collectdata`/`bugreport` selection live in `OssManager.cs`.
|
||||
- Unity credential caching, Steam auth warmup, and `ossdata`/`collectdata`/`bugreport`/`multilingualreport`/`questionnaire` selection live in `OssManager.cs`.
|
||||
- Multipart PostObject field order and field names live in `OssUploadService.cs`.
|
||||
- Player bug zip creation and save archive selection live in `PlayerBugReportService.cs`.
|
||||
- Player bug zip creation, multilingual report zip creation, and save archive selection live in `PlayerBugReportService.cs`.
|
||||
- Questionnaire answer JSON creation lives in `QuestionnaireUploadService.cs`.
|
||||
|
||||
3. Check path semantics before changing data code.
|
||||
- `ossdata`: `{version}/{steamId}/{timestamp}.dat` or `common/{steamId}/{timestamp}.dat`.
|
||||
- `collectdata`: `collect/{version}/{steamId}/{timestamp}.dat` or `collect/common/{steamId}/{timestamp}.dat`.
|
||||
- `bugreport`: `bugreport/{version}/{steamId}/{timestamp}-{random}.zip` or `bugreport/common/{steamId}/{timestamp}-{random}.zip`.
|
||||
- `multilingualreport`: `multilingualreport/{version}/{steamId}/{timestamp}-{random}.zip` or `multilingualreport/common/{steamId}/{timestamp}-{random}.zip`.
|
||||
- `questionnaire`: `questionnaire/{version}/{steamId}/{timestamp}-{random}.json` or `questionnaire/common/{steamId}/{timestamp}-{random}.json`.
|
||||
- Local pulled collect files remove the `collect/` prefix and land under `Tools/OSS/Data/{version}/{steamId}/{timestamp}.dat`.
|
||||
- Local pulled player bug reports are managed by `Tools/PlayerBugViewer` under its ignored `Data/` folder.
|
||||
- Local pulled multilingual reports are managed by `Tools/PlayerMultilingualReportViewer` under its ignored `Data/` folder.
|
||||
- Local pulled questionnaire answers are managed by `Tools/PlayerQuestionnaireViewer` under its ignored `Data/` folder.
|
||||
|
||||
4. Treat Tablestore cache as a functional part of behavior.
|
||||
- STS credential cache key is `{steamId}#{type}` in table `Players`, primary key `PlayerId`.
|
||||
- Steam identity cache key is `{steamId}#steamauth` and only proves the player recently passed Steam Web API verification.
|
||||
- STS cache only hits when version matches, issued time is within 5 minutes, and STS has more than 2 minutes remaining.
|
||||
- If changing `type`, `version`, `objectKey`, or expiry logic, update both cache read and cache write paths.
|
||||
- Do not cache `bugreport` STS credentials; each bug report needs a unique object key.
|
||||
- Do not cache `bugreport`, `multilingualreport`, or `questionnaire` STS credentials; each player submission needs a unique object key.
|
||||
|
||||
5. Use production reports carefully.
|
||||
- CrashSight `UnityLogError` upload failures often indicate debug/environment noise rather than blocking crashes.
|
||||
@ -82,20 +93,24 @@ Keep the current single Function Compute service/file unless the user explicitly
|
||||
|
||||
## Common Tasks
|
||||
|
||||
- Backend code changes: edit `Tools/OSS/game-upload-function/index.js`, then run at least `npm install` if dependencies changed and a local smoke server check when env vars are available.
|
||||
- Backend code changes: edit `Tools/OSS/game-upload-function/index.js`, then run `npm run check` in `Tools/OSS/game-upload-function`. Run `npm install` only if dependencies changed or are missing, and a local smoke server check when env vars are available.
|
||||
- Unity upload/client changes: edit only the relevant `TH1_Logic/Oss` files, then run a Unity compile or targeted editor test when practical.
|
||||
- Player bug report changes: keep Unity-side package shape aligned with `Tools/PlayerBugViewer`; verify `manifest.json`, `description.txt`, device/time fields, `crashSightDeviceId`, and `saves/{single|multi}/...dat` entries.
|
||||
- Developer bug viewer changes: edit `Tools/PlayerBugViewer`; preserve local credential/cache ignores for `config.local.json` and `Data/`.
|
||||
- Multilingual report changes: keep Unity-side zip shape aligned with `Tools/PlayerMultilingualReportViewer`; verify `manifest.json`, selected text, resolved text, language, and player description.
|
||||
- Questionnaire changes: keep Unity-side JSON shape aligned with `Tools/PlayerQuestionnaireViewer`; verify `schema`, `questionnaireId`, `answerSheet.Answers[]`, 512 KB limit, and `questionnaire/*.json` object key validation.
|
||||
- Developer report viewer changes: edit the relevant `Tools/PlayerBugViewer`, `Tools/PlayerMultilingualReportViewer`, or `Tools/PlayerQuestionnaireViewer` folder; preserve local credential/cache ignores for `config.local.json` and `Data/`.
|
||||
- Collect data download/stat changes: use `OssEditorWindow.cs` and `OssDownloadService.cs`; verify the mapping from `collect/` OSS keys to `Tools/OSS/Data`.
|
||||
- Steam upload flow test changes: use `Unity/Assets/Scripts/TH1_Logic/Editor/SteamEditorWindow.cs`. The current end-to-end tester menu is `Tools/Steam 上传流程测试器`; it requires Play Mode Steam login/AuthTicket and covers `action=steamauth`, `type=ossdata`, `type=bugreport`, `type=multilingualreport`, and `type=questionnaire` in sequential test 1-5. It does not cover `collectdata`; use `OssEditorWindow.cs` for collect upload policy tests.
|
||||
- OSS data analysis: use `Tools/OSS/Data` for `.dat` files and `Tools/OSS/Data/JsonExport` for exported JSON; avoid hand-decoding MemoryPack outside Unity unless there is already a project utility for it.
|
||||
|
||||
## Checks Before Finishing
|
||||
|
||||
- Confirm request/response fields still match Unity `StsCredentials`, `SteamAuthWarmupResponse`, and `StsRequest`.
|
||||
- Confirm `ossdata`, `collectdata`, and `bugreport` still work, including cache keys, path prefixes, upload limits, and bugreport cache bypass.
|
||||
- Confirm security limits remain intentional: 1024-byte STS request body, 3 MB standard Post Policy/Unity upload guard, 10 MB bugreport limit.
|
||||
- Run `node -c Tools/OSS/game-upload-function/index.js` after backend edits.
|
||||
- Run `python -m py_compile Tools/PlayerBugViewer/player_bug_viewer.py` after player bug viewer edits.
|
||||
- Confirm `ossdata`, `collectdata`, `bugreport`, `multilingualreport`, and `questionnaire` still work, including cache keys, path prefixes, upload limits, and unique-key cache bypass for player submissions.
|
||||
- Confirm security limits remain intentional: 1024-byte STS request body, 3 MB standard Post Policy/Unity upload guard, 10 MB bugreport limit, 1 MB multilingual report limit, 512 KB questionnaire limit.
|
||||
- Run `npm run check` in `Tools/OSS/game-upload-function` after backend edits.
|
||||
- Run `python -m py_compile` on the changed viewer script after player report viewer edits.
|
||||
- Run `dotnet build Unity/TH1.Logic.Editor.csproj --no-restore` after Unity editor upload-flow or OSS tool edits when practical.
|
||||
- Confirm no secrets, raw tickets, or full STS credentials were added to files, logs, docs, or reports.
|
||||
- For CrashSight correlation, `CrashSightManager.GetCrashSightDeviceId()` is the shared source: prefer `SystemInfo.deviceUniqueIdentifier`; if unsupported, use a PlayerPrefs-persisted `th1-{guid}` fallback; if PlayerPrefs is unavailable, use a process-local `th1-device-id-unavailable-{guid}` fallback. Set the same value into CrashSight and bug-report manifests.
|
||||
- For CrashSight correlation, `CrashSightManager.GetCrashSightDeviceId()` is the shared source: prefer `SystemInfo.deviceUniqueIdentifier`; if unsupported, use a PlayerPrefs-persisted `th1-{guid}` fallback; if PlayerPrefs is unavailable, use a process-local `th1-device-id-unavailable-{guid}` fallback. Set the same value into CrashSight and player-submitted bug/multilingual/questionnaire payloads.
|
||||
- Report which side was changed: Function Compute code, Unity client upload code, editor OSS tooling, local OSS data, or documentation.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
interface:
|
||||
display_name: "TH1 Server Backend"
|
||||
short_description: "TH1 Aliyun Function Compute, OSS, and Tablestore guide"
|
||||
default_prompt: "Use $th1-server-backend for TH1 server, Aliyun Function Compute, OSS upload, Tablestore cache, or cloud save data work."
|
||||
short_description: "TH1 Aliyun Function Compute, OSS upload, Tablestore, and report viewer guide"
|
||||
default_prompt: "Use $th1-server-backend for TH1 server, Aliyun Function Compute, OSS upload flows, upload tests, Tablestore cache, player report viewers, questionnaire uploads, or cloud save data work."
|
||||
|
||||
@ -10,6 +10,8 @@ This reference covers the TH1 backend upload service and its local data/tooling:
|
||||
- Unity editor OSS tools: `Unity/Assets/Scripts/TH1_Logic/Editor/OssEditorWindow.cs` and `OssDownloadService.cs`
|
||||
- Pulled OSS collect data: `Tools/OSS/Data/`
|
||||
- Player bug report viewer/restorer: `Tools/PlayerBugViewer/`
|
||||
- Player multilingual report viewer: `Tools/PlayerMultilingualReportViewer/`
|
||||
- Player questionnaire answer viewer: `Tools/PlayerQuestionnaireViewer/`
|
||||
|
||||
## Function Compute Service
|
||||
|
||||
@ -257,6 +259,7 @@ Runtime files:
|
||||
- `StsTokenService.cs`: sends JSON to Function Compute and parses `StsCredentials` or `SteamAuthWarmupResponse`.
|
||||
- `OssUploadService.cs`: builds multipart PostObject requests to `https://{bucket}.{endpoint}`.
|
||||
- `PlayerBugReportService.cs`: builds player bug report zip packages and selects recent `start + continue/end` save pairs.
|
||||
- `QuestionnaireUploadService.cs`: builds questionnaire answer JSON payloads using schema `th1.questionnaire-answer.v1`.
|
||||
- `OssData.cs`: MemoryPack payload containing `StartMap`, `Actions`, and `CollectData`.
|
||||
|
||||
Important Unity details:
|
||||
@ -268,6 +271,7 @@ Important Unity details:
|
||||
- Multipart fields include `key`, `OSSAccessKeyId`, `policy`, `Signature`, `x-oss-security-token`, then `file` last.
|
||||
- `OssManager.UploadMapData` and `UploadCollectData` skip multiplayer uploads on non-lobby-owner clients.
|
||||
- `OssManager.UploadPlayerBugReportAsync` requests `type=bugreport` and uploads `application/zip`.
|
||||
- `OssManager.UploadPlayerMultilingualReportAsync` requests `type=multilingualreport` and uploads `application/zip`.
|
||||
- `OssManager.UploadQuestionnaireAnswerAsync` requests `type=questionnaire` and uploads `application/json`.
|
||||
|
||||
## Player Bug Report Tooling
|
||||
@ -300,17 +304,66 @@ Viewer capabilities:
|
||||
- Preview manifest fields, attached save files, and player description.
|
||||
- Replace local saves by deleting `map_archive_*.dat` / `map_archive_*.dat.bak` in the configured local Config directory, then copying archive files from the selected report.
|
||||
|
||||
## Player Multilingual Report Tooling
|
||||
|
||||
Unity temporary submit UI:
|
||||
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Editor/PlayerBugReportEditorWindow.cs`
|
||||
- Menu: `Tools/玩家多语言汇报`
|
||||
- Inputs: version, multilingual ID, selected text, language, and player description.
|
||||
|
||||
Standalone developer viewer:
|
||||
|
||||
- Folder: `Tools/PlayerMultilingualReportViewer/`
|
||||
- Entry point: `启动玩家多语言汇报查看器.bat`
|
||||
- Main script: `player_multilingual_report_viewer.py`
|
||||
- Local credentials: `config.local.json`, ignored by git.
|
||||
- Download cache: `Data/`, ignored by git.
|
||||
|
||||
Viewer capabilities:
|
||||
|
||||
- Pull `multilingualreport/` zip objects from OSS using OSS REST V1 HMAC-SHA1 signing.
|
||||
- Filter by version, SteamID, language, and multilingual ID.
|
||||
- Preview manifest fields, reported text, resolved text, and player description.
|
||||
|
||||
## Player Questionnaire Tooling
|
||||
|
||||
Unity client upload payload:
|
||||
|
||||
- `Unity/Assets/Scripts/TH1_Logic/Questionnaire/QuestionnaireUploadService.cs`
|
||||
- Schema: `th1.questionnaire-answer.v1`
|
||||
- Upload type: `questionnaire`
|
||||
- Content type: `application/json`
|
||||
- Max size: 512 KB
|
||||
- Expected object key: `questionnaire/{version}/{steamId}/{timestamp}-{random}.json`
|
||||
|
||||
Standalone developer viewer:
|
||||
|
||||
- Folder: `Tools/PlayerQuestionnaireViewer/`
|
||||
- Entry point: `启动玩家问卷查看器.bat`
|
||||
- Main script: `player_questionnaire_viewer.py`
|
||||
- Local credentials: `config.local.json`, ignored by git.
|
||||
- Download cache: `Data/`, ignored by git.
|
||||
|
||||
Viewer capabilities:
|
||||
|
||||
- Pull `questionnaire/` JSON objects from OSS using OSS REST V1 HMAC-SHA1 signing.
|
||||
- Filter by version, questionnaire ID, SteamID, and question ID.
|
||||
- Preview response metadata, device fields, and answer details under `answerSheet.Answers[]`.
|
||||
|
||||
## Unity Editor OSS Tooling
|
||||
|
||||
Editor files:
|
||||
|
||||
- `OssEditorWindow.cs`
|
||||
- `OssDownloadService.cs`
|
||||
- `SteamEditorWindow.cs`
|
||||
- `OssStatisticEditorWindow.cs` is deprecated and retained only for Unity `.meta` stability.
|
||||
|
||||
Menu items:
|
||||
|
||||
- `Tools/Oss 编辑器`
|
||||
- `Tools/Steam 上传流程测试器`
|
||||
- `Tools/OSS 导出 JSON (Dashboard)`
|
||||
|
||||
Editor capabilities:
|
||||
@ -321,6 +374,9 @@ Editor capabilities:
|
||||
- Deserialize collect `.dat` files with MemoryPack for statistics.
|
||||
- Export collect data JSON for the dashboard under `Tools/OSS/Data/JsonExport`.
|
||||
- Test STS request, upload success, wrong object key rejection, and oversized upload rejection.
|
||||
- Run the Steam-authenticated end-to-end upload sequence 1-5: `action=steamauth`, `type=ossdata`, `type=bugreport`, `type=multilingualreport`, and `type=questionnaire`.
|
||||
|
||||
`Tools/Steam 上传流程测试器` requires Play Mode with Steam initialized and a valid AuthTicket. Its questionnaire test constructs a small `th1.questionnaire-answer.v1` JSON payload, requests `type=questionnaire`, verifies the returned object key is under `questionnaire/` and ends in `.json`, then uploads with `application/json` and the 512 KB guard. This tester does not cover `collectdata`; keep using `Tools/Oss 编辑器` for collect upload policy checks.
|
||||
|
||||
`OssDownloadService` uses OSS REST V1 HMAC-SHA1 signing. Its `ListObjectsAsync` handles continuation tokens and `DownloadObjectAsync` encodes each object-key path segment while preserving slashes.
|
||||
|
||||
@ -344,6 +400,8 @@ Interpretation:
|
||||
- Cache issues: stale version/type/objectKey almost always mean cache normalization changed on only one side of read/write.
|
||||
- Slow upload credential requests after Steam is ready: verify the client is calling `action=steamauth`, Tablestore has `{steamId}#steamauth`, and `authExpireAt` is still in the future.
|
||||
- Player bug report upload overwrites: `bugreport` should bypass STS cache and object keys should include a random suffix.
|
||||
- Multilingual report upload overwrites: `multilingualreport` should bypass STS cache and object keys should include a random suffix.
|
||||
- Questionnaire upload failure after STS success: verify JSON is under 512 KB, content type is `application/json`, object key is `questionnaire/*.json`, and service/client are both using `type=questionnaire`.
|
||||
- Player bug viewer restore problems: inspect `manifest.json` archive `zipEntry`/`sourceFileName` fields and the configured local Config path.
|
||||
|
||||
## Deployment And Validation
|
||||
@ -351,10 +409,14 @@ Interpretation:
|
||||
Local code checks:
|
||||
|
||||
- In `Tools/OSS/game-upload-function`, run `npm install` only when dependencies are missing or changed.
|
||||
- In `Tools/OSS/game-upload-function`, run `npm run check` for the static upload contract check. It includes `node -c index.js` and verifies upload-type/path/limit policy snippets, including `questionnaire`.
|
||||
- There is no meaningful `npm test` currently; `package.json` has the default failing test stub.
|
||||
- A local server boot requires all required env vars; without them, HTTP requests should return a controlled `500` listing missing variables.
|
||||
- Backend syntax check: `node -c Tools/OSS/game-upload-function/index.js`.
|
||||
- Backend syntax/check command: `npm run check` from `Tools/OSS/game-upload-function`.
|
||||
- Player bug viewer syntax check: `python -m py_compile Tools/PlayerBugViewer/player_bug_viewer.py`.
|
||||
- Multilingual viewer syntax check: `python -m py_compile Tools/PlayerMultilingualReportViewer/player_multilingual_report_viewer.py`.
|
||||
- Questionnaire viewer syntax check: `python -m py_compile Tools/PlayerQuestionnaireViewer/player_questionnaire_viewer.py`.
|
||||
- Unity editor upload tester compile check: `dotnet build Unity/TH1.Logic.Editor.csproj --no-restore`.
|
||||
|
||||
Smoke checks when credentials are available:
|
||||
|
||||
@ -363,6 +425,7 @@ Smoke checks when credentials are available:
|
||||
- Test both `type: "ossdata"` and `type: "collectdata"`.
|
||||
- Test `action: "steamauth"` and confirm later uploads can skip realtime Steam API while cache is valid.
|
||||
- Test `type: "bugreport"` and confirm a unique `.zip` key under `bugreport/`.
|
||||
- Test `type: "multilingualreport"` and confirm a unique `.zip` key under `multilingualreport/`.
|
||||
- Test `type: "questionnaire"` and confirm a unique `.json` key under `questionnaire/`.
|
||||
- Attempt wrong objectKey upload with existing credential and confirm OSS rejects it.
|
||||
- Attempt oversized upload and confirm client/backend policy rejects it: 3 MB standard, 10 MB bugreport, 512 KB questionnaire.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user