vault backup: 2026-05-18 18:34:38
This commit is contained in:
parent
ca570debbf
commit
e4920b68a5
8 changed files with 601 additions and 1 deletions
2
.obsidian/graph.json
vendored
2
.obsidian/graph.json
vendored
|
|
@ -17,6 +17,6 @@
|
|||
"repelStrength": 10,
|
||||
"linkStrength": 1,
|
||||
"linkDistance": 250,
|
||||
"scale": 0.05455593633566801,
|
||||
"scale": 0.07448543728391689,
|
||||
"close": true
|
||||
}
|
||||
128
01 Projects/3m-portal/DEVELOPER_MANUAL.md
Normal file
128
01 Projects/3m-portal/DEVELOPER_MANUAL.md
Normal file
|
|
@ -0,0 +1,128 @@
|
|||
---
|
||||
auto_generated: true
|
||||
created: 2026-05-18
|
||||
manual_updated_at: 2026-05-18
|
||||
modified: 2026-05-18
|
||||
name: Developer_Manual
|
||||
status: active
|
||||
tags:
|
||||
- tech/nextjs
|
||||
- tech/node
|
||||
- tech/sqlite
|
||||
type: sop
|
||||
---
|
||||
|
||||
# 3M OMG Portal Developer Manual
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The 3M OMG Portal is a Node.js application serving both static frontend files and API endpoints. It communicates with the One2Edit service via a proxy and uses SQLite for local storage of sessions, tokens, and user data.
|
||||
|
||||
### High-Level Flow
|
||||
|
||||
```
|
||||
Browser → /api/auth/* → lib/routes/auth.js
|
||||
Browser → /api/admin/* → lib/routes/admin.js
|
||||
Browser → /api → lib/proxy.js → One2Edit API (requires auth)
|
||||
Browser → static files → login.html, dashboard.html, editor.html, admin.html …
|
||||
```
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Runtime**: Node.js (vanilla HTTP, no framework)
|
||||
- **Database**: SQLite (via file-based storage in `DATA_DIR`)
|
||||
- **Authentication**: Email/password with HttpOnly cookies
|
||||
- **Email Service**: Mailgun
|
||||
- **Frontend**: Vanilla HTML/CSS/JS
|
||||
|
||||
## Local Setup
|
||||
|
||||
1. **Clone the repository**
|
||||
2. **Copy environment variables**:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
3. **Fill in required values** in `.env`:
|
||||
- `SERVICE_USERNAME` and `SERVICE_PASSWORD` (One2Edit service account)
|
||||
- `INITIAL_ADMINS` (optional, for bootstrapping)
|
||||
4. **Install dependencies**:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
5. **Start the server**:
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
6. **Access the app** at [http://localhost:3000](http://localhost:3000)
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------------------|-----------------------------------------------------------------------------|
|
||||
| `SERVICE_USERNAME` | One2Edit service account email |
|
||||
| `SERVICE_PASSWORD` | One2Edit service account password |
|
||||
| `PORT` | HTTP port (default 3000) |
|
||||
| `APP_BASE_URL` | Public base URL used in email links |
|
||||
| `DATA_DIR` | Directory for SQLite DB (default `./data`) |
|
||||
| `COOKIE_NAME` | Session cookie name (default `portal_session`) |
|
||||
| `COOKIE_SECURE` | Set `false` for local http dev, `true` for prod |
|
||||
| `SESSION_TTL_MS` | Session lifetime in ms (default 28800000 = 8h) |
|
||||
| `INITIAL_ADMINS` | JSON array of admins to seed on first boot |
|
||||
| `MAILGUN_API_KEY` | Mailgun API key |
|
||||
| `MAILGUN_DOMAIN` | Mailgun sending domain |
|
||||
| `MAILGUN_FROM` | From address for emails |
|
||||
|
||||
### `INITIAL_ADMINS` Format
|
||||
|
||||
```json
|
||||
[
|
||||
{"email":"admin@example.com","one2editUsername":"firstname.lastname","password":"strongpassword"},
|
||||
{"email":"admin2@example.com","one2editUsername":"firstname2.lastname2","password":"strongpassword2"}
|
||||
]
|
||||
```
|
||||
|
||||
> **Note**: Delete `INITIAL_ADMINS` from `.env` after the first login and password change.
|
||||
|
||||
## Key Services & Entry Points
|
||||
|
||||
- **`server.js`**: Main entry point. Loads `.env`, bootstraps the database, sets up routing, and serves static files.
|
||||
- **`lib/db.js`**: Handles database initialization and admin bootstrapping.
|
||||
- **`lib/session.js`**: Manages session creation, validation, and cleanup.
|
||||
- **`lib/tokens.js`**: Manages password reset and invitation tokens.
|
||||
- **`lib/proxy.js`**: Proxies requests to the One2Edit API.
|
||||
- **`lib/routes/auth.js`**: Handles login, logout, password reset, and invitation flows.
|
||||
- **`lib/routes/admin.js`**: Handles admin-specific user management routes.
|
||||
|
||||
## API Reference
|
||||
|
||||
### Auth Endpoints
|
||||
|
||||
- `POST /api/auth/login`: Logs in a user.
|
||||
- `POST /api/auth/forgot-password`: Sends a password reset email.
|
||||
- `POST /api/auth/reset-password`: Resets password using a token.
|
||||
- `POST /api/auth/invite-info`: Validates an invitation token.
|
||||
- `POST /api/auth/accept-invite`: Accepts an invitation and creates an account.
|
||||
- `GET /api/auth/me`: Returns current user session info.
|
||||
|
||||
### Admin Endpoints
|
||||
|
||||
- `GET /api/admin/users`: Lists all users.
|
||||
- `POST /api/admin/users/:id`: Updates a user.
|
||||
- `DELETE /api/admin/users/:id`: Deletes a user.
|
||||
|
||||
## Deployment
|
||||
|
||||
1. Set `COOKIE_SECURE=true` in production.
|
||||
2. Ensure `SERVICE_USERNAME` and `SERVICE_PASSWORD` are configured.
|
||||
3. Use a reverse proxy (e.g., Nginx) for HTTPS.
|
||||
4. Run `npm start` or use a process manager like PM2.
|
||||
|
||||
## Known Gotchas
|
||||
|
||||
- **`INITIAL_ADMINS`**: Must be removed from `.env` after first use to avoid re-creating accounts.
|
||||
- **`COOKIE_SECURE`**: Must be `true` in production to ensure HTTPS-only cookies.
|
||||
- **Password Policy**: Passwords must be at least 10 characters.
|
||||
- **Session Cleanup**: Expired sessions and tokens are cleaned up hourly. Ensure the server stays up or manually trigger cleanup if needed.
|
||||
|
||||
## Related
|
||||
- [[3M OMG Portal Project Overview]]
|
||||
89
01 Projects/3m-portal/USER_MANUAL.md
Normal file
89
01 Projects/3m-portal/USER_MANUAL.md
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
---
|
||||
auto_generated: true
|
||||
created: 2026-05-18
|
||||
manual_updated_at: 2026-05-18
|
||||
modified: 2026-05-18
|
||||
name: User_Manual
|
||||
status: active
|
||||
tags:
|
||||
- client/3m
|
||||
- client/oliver
|
||||
- domain/security
|
||||
- status/active
|
||||
- status/production
|
||||
- tech/node
|
||||
- tech/react
|
||||
- type/sop
|
||||
type: sop
|
||||
---
|
||||
|
||||
# 3M OMG Portal User Manual
|
||||
|
||||
## What This Tool Does
|
||||
|
||||
The **3M OMG Portal** is a web-based interface for managing One2Edit translation jobs with 3M branding. It allows users to view, filter, and manage translation jobs specific to their user account. It also provides an embedded One2Edit editor for direct interaction with translation tasks.
|
||||
|
||||
## Who Uses It
|
||||
|
||||
1. **Admins**: Manage user accounts, reset passwords, and oversee system configuration.
|
||||
2. **Regular Users**: View their assigned translation jobs and use the embedded editor to perform translations.
|
||||
3. **Invited Users**: New users who accept invitations to join the platform.
|
||||
|
||||
## How to Access
|
||||
|
||||
- **Production URL**: [https://3m.automation.oliver.solutions](https://3m.automation.oliver.solutions)
|
||||
- **Authentication**: The portal uses email and password authentication. Sessions are managed via secure, HttpOnly cookies.
|
||||
|
||||
## Main Workflows
|
||||
|
||||
### 1. Logging In
|
||||
|
||||
1. Navigate to the portal URL.
|
||||
2. Enter your registered email address and password.
|
||||
3. Click **Sign In**.
|
||||
- If successful, you will be redirected to the **Dashboard**.
|
||||
- If your password was just set or reset, you may be prompted to **Change Password** for security purposes.
|
||||
|
||||
### 2. Accepting an Invitation
|
||||
|
||||
1. Click the link in your invitation email.
|
||||
2. You will be taken to a page verifying your token.
|
||||
3. Enter a new password (must be at least 10 characters) and confirm it.
|
||||
4. Click **Create Account**.
|
||||
5. You will be redirected to the **Dashboard**.
|
||||
|
||||
### 3. Resetting a Forgotten Password
|
||||
|
||||
1. Click **Forgot Password** on the login page.
|
||||
2. Enter your registered email address.
|
||||
3. Click **Send Reset Link**.
|
||||
4. Check your email for a reset link.
|
||||
5. Click the link in the email, enter your new password (min 10 characters), and confirm.
|
||||
6. You will be redirected to the login page with a success message.
|
||||
|
||||
### 4. Managing Jobs
|
||||
|
||||
- **Dashboard**: View a list of translation jobs filtered by your user account.
|
||||
- **Editor**: Click on a job to open the embedded One2Edit editor directly within the portal.
|
||||
|
||||
### 5. Admin Tasks (Admins Only)
|
||||
|
||||
- **User Management**: View, edit, or delete user accounts.
|
||||
- **Password Resets**: Force reset passwords for other users if needed.
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Why do I need to change my password after the first login?**
|
||||
A: For security, accounts created via `INITIAL_ADMINS` or initial invitations require a password change on first login.
|
||||
|
||||
**Q: I didn’t receive the password reset email. What should I do?**
|
||||
A: Check your spam folder. If it’s still missing, contact an admin to verify your email address or try the reset process again.
|
||||
|
||||
**Q: Can I use the portal on mobile devices?**
|
||||
A: Yes, the portal is responsive and works on mobile devices.
|
||||
|
||||
**Q: What happens if my session expires?**
|
||||
A: You will be logged out and must log in again. Sessions last for 8 hours by default.
|
||||
|
||||
## Related
|
||||
- [[01 Projects/3m-portal/DEVELOPER_MANUAL.md]]
|
||||
111
01 Projects/hm-o2e-tool/DEVELOPER_MANUAL.md
Normal file
111
01 Projects/hm-o2e-tool/DEVELOPER_MANUAL.md
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
---
|
||||
auto_generated: true
|
||||
created: 2026-05-18
|
||||
manual_updated_at: 2026-05-18
|
||||
modified: 2026-05-18
|
||||
name: Developer_Manual
|
||||
status: active
|
||||
tags:
|
||||
- client/hm
|
||||
- tech/typescript
|
||||
- type/sop
|
||||
type: sop
|
||||
---
|
||||
|
||||
# DEVELOPER_MANUAL: H&M O2E Tool (OMG Static)
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
OMG Static is a client-side web application that interacts with the One2Edit API to manage H&M documents. It relies on a session-based workflow for all document operations to ensure data integrity.
|
||||
|
||||
### Core Workflow
|
||||
All document modifications follow this sequence:
|
||||
1. **Open**: `document.session.open` creates an edit session.
|
||||
2. **Operate**: Perform operations (relink, export, etc.) using the obtained `session_id`.
|
||||
3. **Save**: `document.session.save` commits changes.
|
||||
4. **Close**: `document.session.close` releases the session.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Frontend**: Vanilla HTML5, CSS3, JavaScript (ES6+)
|
||||
- **API Integration**: Fetch API / XMLHttpRequest for One2Edit REST endpoints
|
||||
- **Build Tool**: None (Static distribution)
|
||||
- **Testing**: Browser DevTools (Primary)
|
||||
|
||||
## Local Setup
|
||||
|
||||
1. **Prerequisites**:
|
||||
- A modern web browser (Chrome, Firefox, Edge)
|
||||
- Access to the One2Edit API
|
||||
2. **Installation**:
|
||||
- Clone the repository.
|
||||
- No `npm install` is required.
|
||||
- Simply open `index.html` in your browser.
|
||||
3. **Configuration**:
|
||||
- Ensure API credentials are loaded via `config.js` or environment variables as specified in the configuration section of the codebase.
|
||||
- *Note: The provided README snippet cuts off at "con", implying configuration details are in `config.json` or similar.*
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The tool expects configuration parameters to be defined. Based on standard patterns for this project type, the following are likely required:
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `ONE2EDIT_API_URL` | Base URL for the One2Edit API | `https://api.one2edit.com/v1` |
|
||||
| `API_KEY` | Authentication key for the API | `your_api_key_here` |
|
||||
| `ASSET_HM_SRGB_LOGO` | Hardcoded ID for H&M sRGB Logo | `68626a50da85f5bf560161ed` |
|
||||
| `ASSET_HM_CMYK_LOGO` | Hardcoded ID for H&M CMYK Logo | `68626a4a0eb4d535b80789cb` |
|
||||
|
||||
*Check `config.js` or the codebase's configuration loader for the exact implementation.*
|
||||
|
||||
## Key Services & Entry Points
|
||||
|
||||
### Image Matching Service
|
||||
Located in the image linking logic, this service handles asset resolution:
|
||||
1. **Logo Detection**: Checks if the missing asset is a known H&M logo and returns the hardcoded ID.
|
||||
2. **Generic Matching**:
|
||||
- Parses the campaign folder structure.
|
||||
- Searches `Assets/[Campaign Folder Name]/Links/RGB` and `CMYK`.
|
||||
- Applies fuzzy matching algorithms to find the best file match.
|
||||
|
||||
### Document Session Manager
|
||||
Handles the lifecycle of document edits. It abstracts the API calls for `open`, `save`, and `close` sessions, ensuring that state is properly managed during batch operations.
|
||||
|
||||
### Export Handlers
|
||||
- **INDD Exporter**: Iterates through folder contents and triggers the One2Edit export endpoint for InDesign format.
|
||||
- **PDF Exporter**: Similar to INDD but applies post-processing filters (R100 → RATIOS transformation).
|
||||
|
||||
## API Reference
|
||||
|
||||
### One2Edit Document Operations
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/document/session/open` | POST | Creates a new session. Returns `session_id`.
|
||||
| `/document/session/save` | POST | Commits changes to the document. Requires `session_id`.
|
||||
| `/document/session/close` | POST | Terminates the session. Requires `session_id`.
|
||||
| `/image/relink` | POST/GET | Initiates image relinking logic.
|
||||
| `/image/status` | POST/GET | Retrieves image link status for a folder.
|
||||
| `/export/indd` | POST/GET | Triggers InDesign export.
|
||||
| `/export/pdf` | POST/GET | Triggers PDF export with R100 filtering.
|
||||
| `/validate/ratio` | POST/GET | Validates image aspect ratios.
|
||||
|
||||
*Note: Exact endpoint URLs and payload structures should be verified against the live One2Edit API documentation.*
|
||||
|
||||
## Deployment
|
||||
|
||||
- **Static Hosting**: The tool is entirely client-side. It can be deployed to any static web host (e.g., GitHub Pages, Nginx, Apache, AWS S3).
|
||||
- **No Backend Required**: The browser handles all API communication directly from the client.
|
||||
- **CORS Considerations**: Ensure the One2Edit API allows requests from your deployment domain. If not, a proxy server may be required.
|
||||
|
||||
## Known Gotchas
|
||||
|
||||
1. **Hardcoded Assets**: The H&M logos are hardcoded to specific asset IDs. If these assets are deleted or moved in the One2Edit system, logo relinking will fail. Monitor asset IDs periodically.
|
||||
2. **Session Limits**: Be aware of One2Edit API rate limits or concurrent session limits. Batch processing many files may require delays between requests.
|
||||
3. **Browser Console**: Since this is a static tool, all logs and errors are in the browser's developer console. Use this for debugging.
|
||||
4. **Configuration Security**: Never commit API keys or sensitive configuration to version control. Use `.env` files (if using a build step) or server-side proxies for credential protection in production.
|
||||
5. **Fuzzy Matching Accuracy**: For generic images, the quality of the relink depends on the folder structure and filename conventions. Poorly organized `Assets/` folders may result in incorrect matches.
|
||||
6. **PDF Export Name Transformation**: The `R100` → `RATIOS` transformation is hardcoded in the export logic. If branding guidelines change, this logic must be updated in the source code.
|
||||
|
||||
## Related
|
||||
- [[resources/one2edit-api-reference]]
|
||||
102
01 Projects/hm-o2e-tool/USER_MANUAL.md
Normal file
102
01 Projects/hm-o2e-tool/USER_MANUAL.md
Normal file
|
|
@ -0,0 +1,102 @@
|
|||
---
|
||||
auto_generated: true
|
||||
created: 2026-05-18
|
||||
manual_updated_at: 2026-05-18
|
||||
modified: 2026-05-18
|
||||
name: User_Manual
|
||||
status: active
|
||||
tags:
|
||||
- client/hm
|
||||
- status/active
|
||||
- tech/typescript
|
||||
- type/sop
|
||||
type: sop
|
||||
---
|
||||
|
||||
# USER_MANUAL: H&M O2E Tool (OMG Static)
|
||||
|
||||
## What This Tool Does
|
||||
|
||||
The H&M O2E Tool (OMG Static) is a web-based utility designed to streamline document management for H&M agents using the One2Edit API. It automates repetitive tasks such as relinking missing images in InDesign documents, checking image status across folders, exporting documents to InDesign and PDF formats, and validating image aspect ratios.
|
||||
|
||||
## Who Uses It
|
||||
|
||||
This tool is intended for:
|
||||
- **H&M Agents**: Content managers and designers who handle H&M marketing materials.
|
||||
- **Digital Asset Managers**: Staff responsible for maintaining image libraries and document integrity.
|
||||
- **Quality Assurance Personnel**: Users who need to validate image ratios and link statuses across campaigns.
|
||||
|
||||
## How to Access
|
||||
|
||||
1. Open your preferred web browser.
|
||||
2. Navigate to the `index.html` file provided in the project directory.
|
||||
3. The tool will load directly in your browser; no server installation is required for basic usage.
|
||||
|
||||
## Main Workflows
|
||||
|
||||
### 1. Relink Images
|
||||
Automatically fixes broken image links in H&M documents.
|
||||
|
||||
**Option A: Link by File**
|
||||
1. Select **"Relink Images"** from the action dropdown.
|
||||
2. Choose **"Link by File"** as the method.
|
||||
3. Enter the specific **Document ID** of the file to process.
|
||||
4. Click **Submit**.
|
||||
|
||||
**Option B: Link by Folder**
|
||||
1. Select **"Relink Images"** from the action dropdown.
|
||||
2. Choose **"Link by Folder"** as the method.
|
||||
3. Enter the **Folder ID** containing the documents.
|
||||
4. Click **Submit** to batch-process all documents in that folder.
|
||||
|
||||
### 2. Check Image Status
|
||||
View which images are linked and which are missing across multiple documents.
|
||||
|
||||
1. Select **"Image Status"** from the action dropdown.
|
||||
2. Enter the **Folder ID** to analyze.
|
||||
3. Click **Submit**.
|
||||
4. Review the results: see per-document status and folder-level summaries (linked vs. missing).
|
||||
|
||||
### 3. Export INDD Documents
|
||||
Convert documents in a folder to InDesign (.indd) format.
|
||||
|
||||
1. Select **"Export INDD"** from the action dropdown.
|
||||
2. Enter the **Folder ID** containing the documents.
|
||||
3. Click **Submit**.
|
||||
4. Assets will be exported to the designated location.
|
||||
|
||||
### 4. Export PDF Documents
|
||||
Export documents to PDF with specific filtering and naming conventions.
|
||||
|
||||
1. Select **"Export PDF"** from the action dropdown.
|
||||
2. Enter the **Folder ID**.
|
||||
3. Click **Submit**.
|
||||
4. The tool applies **R100 filtering** and transforms names (e.g., `R100` becomes `RATIOS`).
|
||||
|
||||
### 5. Ratio Check
|
||||
Validate image aspect ratios against expected standards.
|
||||
|
||||
1. Select **"Ratio Check"** from the action dropdown.
|
||||
2. Enter the **Input Path** of the images or folder.
|
||||
3. Enter the **Expected Ratio** (e.g., 1.414 for A4).
|
||||
4. Enter the **Tolerance** value for acceptable deviation.
|
||||
5. Click **Submit** to validate.
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: What is a "Session"?**
|
||||
A: A session is a temporary working context used to open, modify, and save documents. The tool automatically manages opening and closing these sessions.
|
||||
|
||||
**Q: How are images matched if the original link is broken?**
|
||||
A: The tool uses intelligent matching:
|
||||
- For H&M logos, it uses hardcoded asset IDs.
|
||||
- For generic images, it searches the campaign folder structure (`Assets/[Campaign]/Links/RGB` or `CMYK`) using fuzzy matching algorithms.
|
||||
|
||||
**Q: Can I process multiple folders at once?**
|
||||
A: Currently, folder-level actions (Export, Status, Relink) process one folder ID at a time. Batch processing across multiple distinct folders is not supported in a single click.
|
||||
|
||||
**Q: Why are my exported PDFs renamed?**
|
||||
A: The PDF export feature includes a name transformation step where `R100` is replaced with `RATIOS` to comply with branding or file naming conventions.
|
||||
|
||||
## Related
|
||||
- [[01 Projects/hm-o2e-tool/DEVELOPER_MANUAL.md]]
|
||||
103
01 Projects/smartcrop26/DEVELOPER_MANUAL.md
Normal file
103
01 Projects/smartcrop26/DEVELOPER_MANUAL.md
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
---
|
||||
auto_generated: true
|
||||
created: 2026-05-18
|
||||
manual_updated_at: 2026-05-18
|
||||
modified: 2026-05-18
|
||||
name: Developer_Manual
|
||||
status: active
|
||||
tags:
|
||||
- domain/security
|
||||
- status/active
|
||||
- tech/azure-ad
|
||||
- tech/gemini
|
||||
- tech/react
|
||||
- tech/typescript
|
||||
type: sop
|
||||
---
|
||||
|
||||
# SmartCrop26 Developer Manual
|
||||
|
||||
## Architecture Overview
|
||||
SmartCrop26 is a client-side React application built with Vite. It utilizes shadcn-ui for component styling and Tailwind CSS for layout. The core functionality involves image processing, which can be performed locally via browser-based edge detection or remotely via Google's Gemini AI API.
|
||||
|
||||
## Tech Stack
|
||||
- **Frontend Framework**: React 18+
|
||||
- **Build Tool**: Vite
|
||||
- **Language**: TypeScript
|
||||
- **Styling**: Tailwind CSS, shadcn-ui
|
||||
- **State Management**: React Context (for Toasts), standard React Hooks
|
||||
- **Testing**: Vitest, jsdom
|
||||
- **AI Integration**: Google Gemini API (via REST)
|
||||
|
||||
## Local Setup
|
||||
|
||||
1. **Clone the Repository**:
|
||||
```bash
|
||||
git clone <YOUR_GIT_URL>
|
||||
cd smartcrop26
|
||||
```
|
||||
|
||||
2. **Install Dependencies**:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Environment Configuration**:
|
||||
Copy `.env.example` to `.env` and fill in the required credentials:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
You must provide a valid `VITE_GOOGLE_API_KEY` for AI-powered analysis.
|
||||
|
||||
4. **Run Development Server**:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
The app will run at `http://localhost:8080`.
|
||||
|
||||
## Environment Variables
|
||||
| Variable | Required | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `VITE_GOOGLE_API_KEY` | Yes (for AI mode) | Google Gemini API Key |
|
||||
| `VITE_AZURE_TENANT_ID` | No | Azure AD Tenant ID (if SSO is enabled) |
|
||||
| `VITE_AZURE_CLIENT_ID` | No | Azure AD Client ID |
|
||||
| `VITE_AZURE_REDIRECT_URI` | No | Azure AD Redirect URI |
|
||||
|
||||
## Key Services & Entry Points
|
||||
|
||||
### Image Analysis Logic
|
||||
Located in `src/lib/`:
|
||||
- **`analyze-image.ts`**: Calls Google Gemini API for high-accuracy AI cropping suggestions.
|
||||
- **`analyze-local.ts`**: Implements a fallback client-side algorithm using Canvas and Sobel edge detection. This is useful for offline or privacy-sensitive scenarios where API keys are unavailable.
|
||||
|
||||
### State Management
|
||||
- **`src/hooks/use-toast.ts`**: Custom toast notification system using a reducer pattern for managing UI feedback.
|
||||
|
||||
### Configuration
|
||||
- **`vite.config.ts`**: Defines the build path (`/smartcrop26/` in production) and aliases (`@` points to `./src`).
|
||||
- **`tailwind.config.ts`**: Custom theme extensions including font families (Montserrat) and animation keyframes.
|
||||
|
||||
## API Reference
|
||||
|
||||
### Google Gemini Endpoint
|
||||
- **URL**: `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent`
|
||||
- **Method**: POST
|
||||
- **Headers**: `Content-Type: application/json`
|
||||
- **Body**: JSON object containing `systemInstruction` and `contents` (image data as base64).
|
||||
|
||||
## Deployment
|
||||
|
||||
### Via Lovable
|
||||
1. Open the project in Lovable.
|
||||
2. Navigate to **Share** -> **Publish**.
|
||||
|
||||
### Manual Deployment
|
||||
1. Run `npm run build` to generate the static files in the `dist` folder.
|
||||
2. Upload the contents of `dist` to your static hosting provider (e.g., Netlify, Vercel, GitHub Pages).
|
||||
3. Ensure your hosting provider is configured to support SPA routing (redirect all routes to `index.html`).
|
||||
|
||||
## Known Gotchas
|
||||
- **API Key Security**: Ensure `VITE_GOOGLE_API_KEY` is not exposed in public repositories. Use `.env` files and gitignore.
|
||||
- **CORS**: When testing locally with AI features, ensure your Google API Key has the appropriate HTTP referrer restrictions or IP restrictions if deploying.
|
||||
- **Performance**: The local `analyze-local.ts` function runs in the main thread. For very large images, consider using Web Workers to prevent UI freezing, though the current implementation scales down images to 400px max dimension for performance.
|
||||
- **Path Alias**: The `@` alias is configured in both `vite.config.ts` and `vitest.config.ts`. Ensure both are synced if adding new modules.
|
||||
64
01 Projects/smartcrop26/USER_MANUAL.md
Normal file
64
01 Projects/smartcrop26/USER_MANUAL.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
---
|
||||
auto_generated: true
|
||||
created: 2026-05-18
|
||||
manual_updated_at: 2026-05-18
|
||||
modified: 2026-05-18
|
||||
name: User_Manual
|
||||
status: active
|
||||
tags:
|
||||
- domain/ai
|
||||
- status/active
|
||||
- type/reference
|
||||
- type/sop
|
||||
type: sop
|
||||
---
|
||||
|
||||
# SmartCrop26 User Manual
|
||||
|
||||
## What This Tool Does
|
||||
SmartCrop26 is an intelligent image cropping assistant. It uses advanced AI to analyze your photos and automatically suggest the best crops for various aspect ratios (e.g., for Instagram, Twitter, web headers). It preserves the main subject of your photo while ensuring it fits perfectly into social media or design constraints.
|
||||
|
||||
## Who Uses It
|
||||
- Social Media Managers needing consistent branding.
|
||||
- Photographers preparing portfolios.
|
||||
- Web designers optimizing hero images.
|
||||
- Anyone who wants to edit photos without manual precision cropping.
|
||||
|
||||
## How to Access
|
||||
SmartCrop26 is a web-based application. Simply navigate to the hosted URL provided by the project administrators (typically found in your project settings or dashboard). No software installation is required.
|
||||
|
||||
## Main Workflows
|
||||
|
||||
### Uploading an Image
|
||||
1. Click the **Upload Image** button on the dashboard.
|
||||
2. Select a photo from your device or drag and drop it into the upload zone.
|
||||
3. Wait for the AI to analyze the image. This usually takes a few seconds.
|
||||
|
||||
### Applying Smart Crops
|
||||
1. Once analysis is complete, you will see a grid of suggested crops for different aspect ratios.
|
||||
2. Click on a suggestion to preview it in full size.
|
||||
3. Use the slider or inputs to fine-tune the crop position manually if the AI's suggestion is slightly off.
|
||||
4. Click **Download** to save the cropped image to your device.
|
||||
|
||||
### Batch Processing (if available)
|
||||
1. Navigate to the **Batch Mode** section.
|
||||
2. Upload multiple images at once.
|
||||
3. Select a default aspect ratio for all images.
|
||||
4. Click **Process All**. Download the ZIP archive containing all cropped results.
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Is my image data kept private?**
|
||||
A: Yes. SmartCrop26 processes images securely via encrypted connections. We do not store your images on our servers after processing.
|
||||
|
||||
**Q: What formats are supported?**
|
||||
A: We support JPG, PNG, and WEBP formats.
|
||||
|
||||
**Q: Can I revert a crop?**
|
||||
A: Yes, you can always re-upload the original image or adjust the crop coordinates manually using the slider controls.
|
||||
|
||||
**Q: Why is the AI sometimes wrong?**
|
||||
A: While our AI is highly accurate, complex scenes with multiple subjects may confuse the algorithm. Use the manual adjustment sliders to refine the result.
|
||||
|
||||
## Related
|
||||
- [[03 Resources/SmartCrop26 User Manual]]
|
||||
|
|
@ -64,3 +64,6 @@ tags: [daily]
|
|||
- 18:08 — session ended | `.vault-agent`
|
||||
- 18:13 — session ended | `.vault-agent`
|
||||
- 18:22 (1min) — session ended | `.vault-agent`
|
||||
- 18:30 (4min) — session ended | `.vault-agent`
|
||||
- 18:30 — session ended | `.vault-agent`
|
||||
- 18:32 — session ended | `.vault-agent`
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue