desktop-team-doc 0.1.0

package/content/docs/knowledge/component-library/frontend-develop/references/type-safety.md

@@ -0,0 +1,493 @@
+# Type Safety Guidelines
+
+This document provides comprehensive guidelines for type safety in TypeScript/React projects, including enum standards, extensibility patterns, and generics usage.
+
+## Core Principles
+
+### Avoid `any` Type
+
+**Rule**: Never use `any` unless absolutely necessary. Use specific types or `unknown` when the type is truly unknown.
+
+**Bad**:
+
+```typescript
+function processData(data: any): any {
+  return data.value;
+}
+```
+
+**Good**:
+
+```typescript
+interface DataWithValue {
+  value: string;
+}
+
+function processData(data: DataWithValue): string {
+  return data.value;
+}
+
+// When type is truly unknown
+function processUnknown(data: unknown): string {
+  if (typeof data === 'object' && data !== null && 'value' in data) {
+    return String((data as { value: unknown }).value);
+  }
+  throw new Error('Invalid data');
+}
+```
+
+### Strict Type Checking
+
+Always enable strict mode in TypeScript configuration:
+
+- `noImplicitAny: true`
+- `strictNullChecks: true`
+- `strictFunctionTypes: true`
+
+## Enum Standards
+
+### Enum Naming Convention
+
+**Rule**: Use `PascalCase` for enum names, `camelCase` for enum values.
+
+**Example**:
+
+```typescript
+enum LicenseType {
+  trial = 'trial',
+  standard = 'standard',
+  professional = 'professional',
+}
+
+enum MenuType {
+  amp = 'amp',
+  cab = 'cab',
+  fx = 'fx',
+}
+```
+
+### Enum Best Practices
+
+1. **Use String Enums for Extensibility**: String enums are more maintainable and allow for easier serialization.
+
+**Good**:
+
+```typescript
+enum SortOrder {
+  ascend = 'ascend',
+  descend = 'descend',
+  none = null,
+}
+```
+
+2. **Export Enums**: Make enums available for reuse across modules.
+
+```typescript
+export enum Status {
+  idle = 'idle',
+  loading = 'loading',
+  success = 'success',
+  error = 'error',
+}
+```
+
+3. **Use Const Assertions for Read-only Arrays**: When creating arrays of enum-like values, use `as const`.
+
+```typescript
+export const MIDI_TYPE_OPTIONS = [
+  { name: 'Power', value: 'toggle' },
+  { name: 'Parameter', value: 'parameter' },
+] as const;
+
+export type MidiType = (typeof MIDI_TYPE_OPTIONS)[number]['value'];
+```
+
+### Enum Extensibility Patterns
+
+When designing enums that may need to be extended:
+
+**Pattern 1: Union Types for Extensibility**
+
+```typescript
+type BaseStatus = 'idle' | 'loading' | 'success' | 'error';
+
+// Can be extended in other modules
+type ExtendedStatus = BaseStatus | 'pending' | 'cancelled';
+```
+
+**Pattern 2: Const Objects with Type Inference**
+
+```typescript
+const Status = {
+  idle: 'idle',
+  loading: 'loading',
+  success: 'success',
+  error: 'error',
+} as const;
+
+type Status = (typeof Status)[keyof typeof Status];
+
+// Easy to extend
+const ExtendedStatus = {
+  ...Status,
+  pending: 'pending',
+  cancelled: 'cancelled',
+} as const;
+```
+
+## Type Extensibility Design
+
+### Interface Extension
+
+**Rule**: Use interfaces for object shapes that may be extended.
+
+**Example**:
+
+```typescript
+export interface BaseComponentProps {
+  className?: string;
+  id?: string;
+}
+
+export interface ButtonProps extends BaseComponentProps {
+  onClick: () => void;
+  disabled?: boolean;
+}
+
+export interface IconButtonProps extends ButtonProps {
+  icon: React.ReactNode;
+  label: string;
+}
+```
+
+### Type Intersection for Composition
+
+**Rule**: Use type intersections for composing multiple types.
+
+**Example**:
+
+```typescript
+type Clickable = {
+  onClick: () => void;
+};
+
+type Hoverable = {
+  onMouseEnter: () => void;
+  onMouseLeave: () => void;
+};
+
+type InteractiveButton = Clickable &
+  Hoverable & {
+    label: string;
+  };
+```
+
+### Discriminated Unions for Type Safety
+
+**Rule**: Use discriminated unions for type-safe handling of different variants.
+
+**Example**:
+
+```typescript
+type LoadingState = {
+  status: 'loading';
+};
+
+type SuccessState<T> = {
+  status: 'success';
+  data: T;
+};
+
+type ErrorState = {
+  status: 'error';
+  error: string;
+};
+
+type AsyncState<T> = LoadingState | SuccessState<T> | ErrorState;
+
+function handleState<T>(state: AsyncState<T>): void {
+  switch (state.status) {
+    case 'loading':
+      // TypeScript knows state is LoadingState
+      console.log('Loading...');
+      break;
+    case 'success':
+      // TypeScript knows state is SuccessState<T>
+      console.log('Data:', state.data);
+      break;
+    case 'error':
+      // TypeScript knows state is ErrorState
+      console.error('Error:', state.error);
+      break;
+  }
+}
+```
+
+## Generics Usage
+
+### When to Use Generics
+
+Use generics when:
+
+1. Creating reusable components or functions that work with multiple types
+2. Maintaining type relationships between function parameters and return values
+3. Creating type-safe data structures
+
+### Generic Naming Conventions
+
+**Rule**: Use descriptive generic names, typically single uppercase letters.
+
+- `<T>` - Generic type
+- `<TItem>` - Generic item type
+- `<TData>` - Generic data type
+- `<TKey>` - Generic key type
+- `<TValue>` - Generic value type
+
+### Generic Constraints
+
+**Rule**: Always constrain generics when possible to ensure type safety.
+
+**Example**:
+
+```typescript
+// Unconstrained (less safe)
+function getValue<T>(obj: T, key: string): unknown {
+  return (obj as Record<string, unknown>)[key];
+}
+
+// Constrained (safer)
+function getValue<T extends Record<string, unknown>>(obj: T, key: keyof T): T[keyof T] {
+  return obj[key];
+}
+```
+
+### Generic Component Example
+
+**Example**: Generic table column component
+
+```typescript
+export interface ColumnType<T = Record<string, unknown>> {
+  title: React.ReactNode;
+  dataIndex?: string | string[];
+  key?: string;
+  width?: number | string;
+  align?: 'left' | 'center' | 'right';
+  sorter?: boolean | ((a: T, b: T) => number);
+  sortOrder?: SortOrder;
+  render?: (value: unknown, record: T, index: number) => React.ReactNode;
+  onCell?: (record: T, index: number) => React.HTMLAttributes<HTMLTableCellElement>;
+}
+
+interface TableProps<T> {
+  dataSource: T[];
+  columns: ColumnType<T>[];
+  rowKey: (record: T) => string | number;
+}
+
+function Table<T extends Record<string, unknown>>({ dataSource, columns, rowKey }: TableProps<T>): JSX.Element {
+  // Implementation
+}
+```
+
+### Generic Function Example
+
+**Example**: Generic input component
+
+```typescript
+type GenericInputProps = {
+  currentName?: string;
+  onConfirm: (value: string) => boolean;
+  onExit: () => void;
+  maximum?: number;
+};
+
+const GenericInput = <T extends PopupComponent & GenericInputProps>(props: T): JSX.Element => {
+  const { currentName = '', onConfirm, onExit, maximum = 20 } = props;
+
+  // Implementation
+};
+```
+
+### Advanced Generic Patterns
+
+**Pattern 1: Conditional Types**
+
+```typescript
+type ValueType<T> = T extends Record<any, infer V> ? (V extends Record<any, infer V2> ? V2 : V) : never;
+
+type KeyType<T> = T extends Record<infer K, any> ? K : never;
+```
+
+**Pattern 2: Mapped Types**
+
+```typescript
+type Partial<T> = {
+  [P in keyof T]?: T[P];
+};
+
+type Readonly<T> = {
+  readonly [P in keyof T]: T[P];
+};
+```
+
+## Type Imports
+
+**Rule**: Use `import type` for type-only imports to improve build performance.
+
+**Example**:
+
+```typescript
+import React, { useState } from 'react';
+import type { MousePos } from '@/src/utils/mouseRx/types';
+import type { AppButtonProps } from './types';
+```
+
+## Function Return Types
+
+**Rule**: Always explicitly define return types for functions.
+
+**Example**:
+
+```typescript
+const processData = (input: string): string => {
+  return input.toUpperCase();
+};
+
+const fetchData = async (url: string): Promise<Response> => {
+  return await fetch(url);
+};
+```
+
+## Interface vs Type Alias
+
+### Use Interfaces For:
+
+- Object shapes, especially props and public APIs
+- When you need declaration merging
+- When defining contracts that may be extended
+
+**Example**:
+
+```typescript
+export interface AppButtonProps {
+  disable?: boolean;
+  selected?: boolean;
+  className?: string;
+}
+```
+
+### Use Type Aliases For:
+
+- Unions, intersections, and complex types
+- When you need computed types
+- When defining types that won't be extended
+
+**Example**:
+
+```typescript
+export type TKnobProps = {
+  config: KnobConfig;
+};
+
+export type SortOrder = 'ascend' | 'descend' | null;
+```
+
+## Common Patterns and Anti-patterns
+
+### ✅ Good Patterns
+
+**Pattern 1: Type Guards**
+
+```typescript
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+function process(value: unknown): void {
+  if (isString(value)) {
+    // TypeScript knows value is string here
+    console.log(value.toUpperCase());
+  }
+}
+```
+
+**Pattern 2: Branded Types**
+
+```typescript
+type UserId = string & { readonly __brand: unique symbol };
+type ProductId = string & { readonly __brand: unique symbol };
+
+function getUser(id: UserId): User {
+  // Implementation
+}
+
+// Prevents mixing UserId and ProductId
+const userId = '123' as UserId;
+const productId = '456' as ProductId;
+// getUser(productId); // Type error!
+```
+
+### ❌ Anti-patterns
+
+**Anti-pattern 1: Overusing `any`**
+
+```typescript
+// Bad
+function process(data: any): any {
+  return data.value;
+}
+
+// Good
+function process<T extends { value: string }>(data: T): string {
+  return data.value;
+}
+```
+
+**Anti-pattern 2: Type Assertions Without Validation**
+
+```typescript
+// Bad
+const data = response as UserData;
+processUser(data);
+
+// Good
+function isUserData(data: unknown): data is UserData {
+  return typeof data === 'object' && data !== null && 'id' in data && 'name' in data;
+}
+
+if (isUserData(response)) {
+  processUser(response);
+}
+```
+
+**Anti-pattern 3: Ignoring Type Errors**
+
+```typescript
+// Bad
+const value = data.value as string; // @ts-ignore
+
+// Good
+if (typeof data.value === 'string') {
+  const value = data.value;
+  // Use value safely
+}
+```
+
+## Summary Checklist
+
+When writing TypeScript code, ensure:
+
+- [ ] No `any` types used (use `unknown` if truly unknown)
+- [ ] Enums follow naming convention (PascalCase enum, camelCase values)
+- [ ] Types are designed for extensibility
+- [ ] Generics are used when appropriate with proper constraints
+- [ ] Function return types are explicitly defined
+- [ ] `import type` is used for type-only imports
+- [ ] Interfaces are used for object shapes, types for unions/intersections
+- [ ] Type guards are used for runtime type checking
+- [ ] Discriminated unions are used for type-safe variant handling
+
+## References
+
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
+- Project Coding Standards: `desktop-team-documentation/instructions/coding-conventions/frontend.md`

package/content/docs/knowledge/development/aws-storage.md

@@ -0,0 +1,95 @@
+# Desktop Team AWS Storage
+
+*Last Updated: 2025-10-16*
+
+This document provides access information and usage instructions for the Desktop Team's AWS S3 storage infrastructure.
+
+## Access Information
+
+### AWS Console Login
+
+- **URL**: https://positivegrid-aws.signin.aws.amazon.com/console
+- **Account ID/Alias**: `positivegrid-aws`
+- **Username**: Contact IT department to request account
+- **Password**: Contact IT department to request account
+- **AWS Credentials** (`Access key ID`, `Secret access key`): Contact IT department
+
+### S3 Bucket
+
+**Bucket Name**: `positivegrid-bias`
+
+## Connecting via Cyberduck
+
+[Cyberduck](https://cyberduck.io/) is the recommended S3 client for accessing the Desktop Team storage.
+
+### Setup Instructions
+
+1. **Download and Install**
+   - Download [Cyberduck](https://cyberduck.io/) for your platform
+   - Install the application
+
+2. **Configure Connection**
+   - Open Cyberduck
+   - Create a new connection with the AWS credentials provided by IT
+   - Use the configuration shown below:
+
+![Cyberduck AWS Credentials Configuration](./assets/cyberduck-aws-credentials.png)
+
+### Connection Parameters
+
+- **Protocol**: Amazon S3
+- **Server**: s3.amazonaws.com
+- **Access Key ID**: Provided by IT department
+- **Secret Access Key**: Provided by IT department
+- **Path**: `/positivegrid-bias` (or leave blank to browse all buckets)
+
+## Security Guidelines
+
+- **Never commit credentials** to source control
+- **Store credentials securely** using your system's keychain or password manager
+- **Request separate credentials** for each team member (no shared accounts)
+- **Rotate credentials** if compromised immediately and notify IT
+
+## Common Use Cases
+
+- Storing build artifacts and release packages
+- Sharing large files between team members
+- Backup storage for important project resources
+- Hosting static assets for testing
+
+## Troubleshooting
+
+### Connection Issues
+
+If you cannot connect to the S3 bucket:
+
+1. Verify credentials are correct (Access Key ID and Secret Access Key)
+2. Check network connectivity and firewall settings
+3. Ensure your AWS account has proper S3 permissions
+4. Contact IT if credentials need to be regenerated
+
+### Permission Errors
+
+If you can connect but receive permission errors:
+
+1. Verify you're accessing the correct bucket (`positivegrid-bias`)
+2. Check that your account has read/write permissions
+3. Contact IT to verify IAM policy settings
+
+## Related Resources
+
+- [AWS S3 Documentation](https://docs.aws.amazon.com/s3/)
+- [Cyberduck Documentation](https://docs.cyberduck.io/)
+- [Tech Stack Overview](./tech-stack.md)
+
+## Support
+
+For AWS access issues or questions:
+
+- **IT Department**: Contact for credentials and account setup
+- **Team Lead**: For bucket organization and usage policies
+
+---
+
+**Maintained by**: Desktop Team
+**Contact**: IT Department for access, Team Lead for usage questions

package/content/docs/knowledge/development/crm-system.md

@@ -0,0 +1,22 @@
+# Positive Grid Desktop 產品 CRM 系統
+
+*Last Updated: 2025-10-16*
+
+## 系統連結
+
+### Production
+
+https://crm-console.positivegrid.com/login
+
+### Staging
+
+https://crm-console-staging.positivegrid.com/login
+
+## 登入方式
+
+使用公司帳號即可登入
+
+---
+
+**Maintained by**: Desktop Team
+**Contact**: IT Department for account access, Backend Team for CRM system issues