e39bc862cc
Significant performance improvements to the 'Loading media...' phase: - Reduced client-server round trips by consolidating the initial handshake (diagnostics + media fetch) into a single backend call: getMediaManagerInitialState. - Implemented batched Google Drive metadata retrieval in GASDriveService using the Advanced Drive API, eliminating per-file property fetching calls. - Switched to HtmlService templates in showMediaManager to pass initial SKU/Title data directly, enabling the UI shell to appear instantly upon opening. - Updated documentation (ARCHITECTURE.md, MEMORY.md) to clarify Webpack global assignment requirements for GAS functions. - Verified with comprehensive updates to unit and integration tests.
52 lines
3.7 KiB
Markdown
52 lines
3.7 KiB
Markdown
# Project Memory
|
|
|
|
## Project Context
|
|
This project (`product_inventory`) integrates Google Sheets with Shopify. It serves as a master inventory management tool where users edit product data in a Google Sheet, and scripts automatically sync those changes to Shopify.
|
|
|
|
**Critical Components:**
|
|
- **Google Apps Script**: Runs the logic.
|
|
- **"vars" Sheet**: Holds all configuration and API keys. NEVER hardcode credentials.
|
|
- **Shopify Admin API**: Used for syncing. REST for Orders, GraphQL for Products.
|
|
|
|
## Work Patterns & Agreements
|
|
1. **Documentation First**: Before implementing complex features, we update the plan and often the documentation (README/ARCHITECTURE).
|
|
2. **Safety First**: We use `SafeToAutoRun: false` for commands that deploy or modify external state until verified.
|
|
3. **Strict Typing**: We use TypeScript. No `any` unless absolutely necessary (and even then, we try to avoid it).
|
|
4. **TDD**: We follow Test Driven Development (Red/Green/Refactor). Write failing tests before implementing features.
|
|
5. **Artifact Usage**: We use `task.md`, `implementation_plan.md`, and `walkthrough.md` to track state.
|
|
|
|
## Key Technical Decisions
|
|
- **Queue System**: We implemented `onEditQueue.ts` to batch edits. This prevents hitting Shopify API rate limits and Google Apps Script execution limits during rapid manual edits.
|
|
- **Hybrid API**: We use REST for retrieving Orders (legacy/easier for flat data) and GraphQL for Products (more efficient/flexible).
|
|
- **Global Exports**: Functions in `src/global.ts` must be explicitly assigned to the `global` object (e.g., `(global as any).func = func`). This is required because Webpack bundles code into an IIFE, making top-level module functions unreachable from the frontend `google.script.run` or Apps Script triggers unless exposed this way.
|
|
|
|
## User Preferences
|
|
- **OS**: Windows.
|
|
- **Shell**: PowerShell.
|
|
- **Node Manager**: `fnm`.
|
|
28:
|
|
29: ## Integrated Media Manager
|
|
30: We implemented a "Sidebar-First" architecture for product media (Option 2):
|
|
31: - **Frontend**: `MediaSidebar.html` uses Glassmorphism CSS and Client-Side Polling to detect SKU changes.
|
|
32: - **Google Picker**: Integrated via `picker.js` using an API Key and OAuth Token passed securely from backend.
|
|
33: - **Drive as Source of Truth**: All uploads go to Drive first (Folder structure: `Root/SKU/Files`).
|
|
34: - **Shopify Sync**: `MediaService` orchestrates the complex `Staged Uploads` -> `Create Media` mutation flow.
|
|
35: - **Security**: `appsscript.json` requires explicit scopes for `userinfo.email` (Picker), `drive` (Files), and `drive` (Advanced Service). API Keys are stored in `vars` sheet, never hardcoded.
|
|
|
|
### Media Handling Quirks
|
|
- **Google Photos Picker**:
|
|
- The `baseUrl` returned by the Picker API is hidden inside `mediaFile.baseUrl` (not top-level).
|
|
- Downloading this URL requires an **Authorization header** with the script's OAuth token, or it returns 403.
|
|
1. Sanitize with `Utilities.newBlob()`.
|
|
2. Fallback to **Advanced Drive Service** (`Drive.Files.create` / `v3`) if standard creation fails.
|
|
- **Video Previews**:
|
|
- **Video Previews**:
|
|
- Use `document.createElement('video')` to inject video tags. Avoid template strings (`<video src="...">`) as the parser sanitizes them aggressively.
|
|
- Fallback to `<iframe>` only if native playback fails.
|
|
- **Client-Side Syntax**:
|
|
- **ES5 ONLY**: Do not use `class` in client-side HTML files. The Apps Script sanitizer often fails to parse them. Use `function` constructors.
|
|
|
|
## Troubleshooting
|
|
- **Test Output**: When running tests, use `npm run test:log` to capture full output to `test_output.txt`. This avoids terminal truncation and allows agents to read the full results without manual redirection.
|
|
|