@scemoon/cdh 1.0.8 → 1.0.9-beta.2

package/ai-dlc-skill/providers/aliyun/services/database.md

@@ -0,0 +1,319 @@
+# Aliyun Database (RDS + TableStore)
+
+## When to Use Each Database Type
+
+**Use RDS MySQL/PostgreSQL when:**
+- Need ACID transactions
+- Complex SQL queries with joins
+- Fixed, well-defined schema
+- Data integrity is critical
+- Reporting and analytics
+- Traditional web application data
+
+**Use TableStore when:**
+- Massive scale (petabyte level)
+- Time-series data
+- Wide-column storage needs
+- High write throughput
+- No complex joins needed
+- Event logs, sensor data, analytics
+
+## Agent Decision Guide
+
+```
+Need to store data?
+├── Relational, SQL needed → RDS (MySQL/PostgreSQL)
+├── Massive scale, time-series → TableStore
+├── Flexible schema, JSON → TableStore (OTS)
+└── Both → Use both (RDS for transactions, OTS for logs)
+```
+
+## RDS (Relational Database Service)
+
+### Connection
+
+```bash
+# Using MySQL client
+mysql -h ${RDS_HOST} -P 3306 -u ${RDS_USER} -p${RDS_PASSWORD}
+
+# Using PostgreSQL client
+psql -h ${RDS_HOST} -P 5432 -U ${RDS_USER} -d ${RDS_DATABASE}
+```
+
+### Schema Design
+
+```sql
+-- Users table
+CREATE TABLE users (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  user_id VARCHAR(64) UNIQUE NOT NULL,
+  nickname VARCHAR(128),
+  avatar_url VARCHAR(512),
+  status TINYINT DEFAULT 1,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  INDEX idx_status (status),
+  INDEX idx_created (created_at)
+);
+
+-- Orders table
+CREATE TABLE orders (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  order_no VARCHAR(64) UNIQUE NOT NULL,
+  user_id BIGINT NOT NULL,
+  amount DECIMAL(10, 2) NOT NULL,
+  status VARCHAR(32) NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (user_id) REFERENCES users(id),
+  INDEX idx_user (user_id),
+  INDEX idx_order_no (order_no)
+);
+```
+
+### Transaction Support
+
+```javascript
+const mysql = require('mysql2/promise');
+
+const connection = await mysql.createConnection({
+  host: process.env.RDS_HOST,
+  port: process.env.RDS_PORT,
+  user: process.env.RDS_USER,
+  password: process.env.RDS_PASSWORD,
+  database: process.env.RDS_DATABASE
+});
+
+await connection.beginTransaction();
+try {
+  await connection.execute(
+    'INSERT INTO orders (order_no, user_id, amount) VALUES (?, ?, ?)',
+    [orderNo, userId, amount]
+  );
+  await connection.execute(
+    'UPDATE users SET status = ? WHERE id = ?',
+    ['active', userId]
+  );
+  await connection.commit();
+} catch (error) {
+  await connection.rollback();
+  throw error;
+}
+```
+
+## TableStore (OTS)
+
+### Data Model
+
+- **Instance** = Database
+- **Table** = Collection
+- **Row** = Document
+- **Column** = Field (dynamic, no fixed schema)
+
+### Table Structure
+
+```javascript
+// Primary key structure (required)
+const tableSchema = {
+  tableName: 'user_events',
+  primaryKey: [
+    { name: 'user_id', type: 'STRING' },
+    { name: 'event_time', type: 'STRING' }  // Sort key
+  ],
+  // Defined columns (optional - for indexing)
+  definedColumns: [
+    { name: 'event_type', type: 'STRING' },
+    { name: 'event_data', type: 'STRING' }
+  ],
+  // Reserved throughput
+  reservedThroughput: {
+    capacityUnit: { read: 1, write: 1 }
+  }
+};
+```
+
+### Query Syntax
+
+```javascript
+const { client, Long } = require('aliyun-sdk');
+
+constOTS = new client.OTS({
+  accessKeyId: process.env.ALICLOUD_ACCESS_KEY,
+  accessKeySecret: process.env.ALICLOUD_SECRET_KEY,
+  endpoint: `https://${process.env.OTS_REGION}.ots.aliyuncs.com`,
+  instanceName: process.env.OTS_INSTANCE
+});
+
+// Put row
+await otsClient.putRow({
+  tableName: 'user_events',
+  primaryKey: [{ user_id: 'user-123' }, { event_time: '2024-01-01T00:00:00Z' }],
+  attributeColumns: [
+    { event_type: 'click' },
+    { event_data: JSON.stringify({ page: '/home' }) }
+  ]
+});
+
+// Get row
+const result = await otsClient.getRow({
+  tableName: 'user_events',
+  primaryKey: [{ user_id: 'user-123' }, { event_time: '2024-01-01T00:00:00Z' }]
+});
+
+// Query with filter
+const queryResult = await otsClient.search({
+  tableName: 'user_events',
+  indexName: 'event_type_index',
+  searchQuery: {
+    offset: 0,
+    limit: 10,
+    query: {
+      terms: [{ event_type: 'click' }]
+    }
+  }
+});
+```
+
+## CLI Reference (RDS)
+
+| Command | Description |
+|---------|-------------|
+| `aliyun rds DescribeDBInstances` | List RDS instances |
+| `aliyun rds CreateDatabase --DBInstanceId xxx` | Create database |
+| `aliyun rds CreateAccount --DBInstanceId xxx` | Create account |
+| `mysqldump -h ${HOST} -u ${USER} -p` | Backup database |
+
+## CLI Reference (TableStore)
+
+| Command | Description |
+|---------|-------------|
+| `ots shell --instance xxx` | Interactive OTS shell |
+| `ots listTable --instance xxx` | List tables |
+| `ots describeTable --instance xxx --table xxx` | Table schema |
+
+## Limits and Quotas
+
+| Limit | RDS | TableStore |
+|-------|-----|------------|
+| Storage | 200GB (max) | Unlimited |
+| Max connections | 1000 (MySQL) | N/A |
+| Max query result | 10000 | 1000 (client pagination) |
+| Throughput | Instance size dependent | Pay per request |
+
+## Database Selection Flow
+
+```
+                    ┌─────────────────┐
+                    │ Need to store   │
+                    │     data?       │
+                    └────────┬────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              │              │              │
+              ▼              ▼              ▼
+      ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+      │ Relational, │ │ Massive     │ │ Flexible    │
+      │    SQL      │ │ scale, time │ │  schema     │
+      │             │ │   series    │ │  (JSON)     │
+      └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
+             │               │               │
+             ▼               ▼               ▼
+        RDS MySQL      TableStore      TableStore
+        (PG also)      (OTS)           (OTS)
+```
+
+## Indexing Strategy
+
+### RDS Indexes
+
+```sql
+-- Single column
+CREATE INDEX idx_email ON users(email);
+
+-- Composite (for WHERE status = ? AND created_at > ?)
+CREATE INDEX idx_status_created ON users(status, created_at);
+
+-- Covering index
+CREATE INDEX idx_status_created_covering ON users(status, created_at, id, nickname);
+```
+
+### TableStore Indexes
+
+```javascript
+// Create search index
+await otsClient.createSearchIndex({
+  tableName: 'user_events',
+  indexName: 'event_type_index',
+  schema: {
+    fieldSchemas: [
+      { fieldName: 'event_type', fieldType: 'KEYWORD' },
+      { fieldName: 'event_time', fieldType: 'TIMESTAMP' },
+      { fieldName: 'event_data', fieldType: 'TEXT' }
+    ]
+  }
+});
+```
+
+## Best Practices
+
+### RDS
+
+1. **Normalize for write integrity** - Use proper relations
+2. **Index wisely** - Too many indexes slow writes
+3. **Use connection pooling** - Don't create new connection per request
+4. **Parameterize queries** - Prevent SQL injection
+5. **Use transactions** - For operations affecting multiple tables
+6. **Enable slow query log** - Monitor and optimize
+
+### TableStore
+
+1. **Design primary key** - Hotspot avoidance (spread writes)
+2. **Use search index** - For non-primary key queries
+3. **Batch operations** - Use batchWrite for efficiency
+4. **Partition by time** - For time-series data
+5. **Monitor throughput** - Adjust reserved capacity
+
+## Accessing Databases from Functions
+
+### From Function Compute
+
+```javascript
+const mysql = require('mysql2/promise');
+
+module.exports.handler = async (event, context) => {
+  // RDS connection
+  const connection = await mysql.createConnection({
+    host: process.env.RDS_HOST,
+    port: process.env.RDS_PORT,
+    user: process.env.RDS_USER,
+    password: process.env.RDS_PASSWORD,
+    database: process.env.RDS_DATABASE
+  });
+
+  const [rows] = await connection.execute('SELECT * FROM users LIMIT 10');
+  return { users: rows };
+};
+```
+
+```javascript
+// TableStore from FC
+const OTS = require('ali-oss');
+
+const otsClient = new OTS({
+  region: process.env.ALICLOUD_REGION,
+  accessKeyId: process.env.ALICLOUD_ACCESS_KEY,
+  accessKeySecret: process.env.ALICLOUD_SECRET_KEY,
+  bucket: process.env.OTS_INSTANCE
+});
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Connection refused | Wrong host/port | Check RDS/OTS endpoint |
+| Access denied | Wrong credentials | Verify RAM permissions |
+| Query timeout | Large dataset, no index | Add index, paginate |
+| TableStore throttle | Throughput exceeded | Increase reserved capacity |
+| SQL syntax error | Invalid SQL | Check MySQL syntax |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`

package/ai-dlc-skill/providers/aliyun/services/function-compute.md

@@ -0,0 +1,273 @@
+# Function Compute (FC)
+
+## When to Use Function Compute
+
+**Use Function Compute when:**
+- Responding to HTTP requests (API endpoints)
+- Processing events (OSS uploads, timers, queue messages)
+- Running short-lived, stateless computations (< 600s)
+- Needing automatic scaling without managing servers
+
+**Do NOT use Function Compute when:**
+- Execution time exceeds 600 seconds → Use SAE
+- Need persistent connections or background workers
+- Require very large memory (> 3GB)
+- Stateful computation requiring local disk persistence
+
+## Agent Decision Guide
+
+```
+Need serverless compute?
+├── Short task (<600s), event-driven → Function Compute
+├── Long-running (>600s) → Serverless App Engine (SAE)
+├── Custom container image → Function Compute (custom runtime)
+└── Containerized workload → Serverless App Engine (SAE)
+```
+
+## Function Types
+
+### HTTP Functions
+
+Responding to HTTP requests via API Gateway.
+
+```javascript
+module.exports.handler = async (req, resp, context) => {
+  // req: HTTP request { headers, queries, path, method, body }
+  // context: FC context info
+  return {
+    statusCode: 200,
+    body: JSON.stringify({ message: "Hello World" })
+  };
+};
+```
+
+**Access URL pattern:** `https://{service}.{region}.fc.devs.com/{functionName}`
+
+### Event Functions
+
+Triggered by various event sources.
+
+```javascript
+module.exports.handler = async (event, context) => {
+  // event: varies by trigger type
+  // e.g., OSS event: { bucket, object, operation }
+  // e.g., Timer event: { triggerTime, ... }
+  return { processed: true };
+};
+```
+
+### WebSocket Functions
+
+For real-time bidirectional communication.
+
+```javascript
+module.exports.handler = async (event, context) => {
+  // event: { type: 'connect' | 'message' | 'disconnect', connectionId, ... }
+  switch (event.type) {
+    case 'connect':
+      // Handle new connection
+      break;
+    case 'message':
+      // Handle incoming message
+      break;
+    case 'disconnect':
+      // Handle disconnection
+      break;
+  }
+};
+```
+
+## Function Structure
+
+```
+my-project/
+├── index.js              # Entry point
+├── package.json          # Dependencies
+├── template.yml          # FC deployment config
+└── .funignore            # Files to exclude
+```
+
+### template.yml Example
+
+```yaml
+ROSTemplateFormatVersion: '2015-09-01'
+Transform: Alibaba Cloud Resource Orchestration Service (ROS)
+Resources:
+  my-service:
+    Type: Alibaba Cloud::Function Compute::Function
+    Properties:
+      ServiceName: my-service
+      FunctionName: hello
+      Runtime: nodejs16
+      Handler: index.handler
+      MemorySize: 256
+      Timeout: 60
+      CodeUri: ./
+      EnvironmentVariables:
+        NODE_ENV: production
+```
+
+## Deployment
+
+### Using fun CLI
+
+```bash
+# Deploy with template
+fun deploy --template template.yml
+
+# Deploy specific function
+fun deploy --function hello --service my-service
+
+# Deploy all functions in template
+fun deploy
+```
+
+### Using serverless devs (s.yaml)
+
+```yaml
+edition: 1.0.0
+services:
+  my-app:
+    component: fc
+    props:
+      region: cn-shanghai
+      service:
+        name: my-service
+        description: My service
+      function:
+        name: hello
+        runtime: nodejs16
+        handler: index.handler
+        memorySize: 256
+        timeout: 60
+```
+
+```bash
+s deploy
+```
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `fun init --template http-trigger` | Initialize new function project |
+| `fun deploy --template template.yml` | Deploy from template |
+| `fun invoke --function hello --service my-service` | Invoke function |
+| `fun logs --function hello --service my-service` | View logs |
+| `fun list functions --service my-service` | List functions |
+| `fun remove --function hello --service my-service` | Delete function |
+
+## Limits and Quotas
+
+| Limit | Value | Notes |
+|-------|-------|-------|
+| Timeout | 600s (default), up to 600s | Use SAE for longer |
+| Memory | 128-3072MB | Adjust in template |
+| Concurrent executions | 1000 (default) | Can request increase |
+| Package size | 50MB (compressed) | Include dependencies |
+| Environment variables | 4KB total | Per function |
+| VPC | Supported | Requires config |
+
+## Cold Start Optimization
+
+### Problem
+Cold start adds 500ms-2s latency when function is idle.
+
+### Solutions
+
+1. **Use provisioned concurrency** (paid feature)
+```yaml
+function:
+  name: hello
+  provisionedConcurrency: 2  # Keep 2 instances warm
+```
+
+2. **Reduce package size**
+- Minimize dependencies
+- Use ES modules
+- Tree-shake unused code
+
+3. **Use larger memory allocation**
+- More memory → faster CPU
+- 512MB+ recommended for latency-sensitive functions
+
+4. **Avoid VPC if possible**
+- VPC adds 10-30s cold start
+
+## Error Handling
+
+### Function Errors
+
+```javascript
+module.exports.handler = async (req, resp, context) => {
+  try {
+    // Business logic
+    const result = await processData(req.body);
+    return { success: true, data: result };
+
+  } catch (error) {
+    // Log error for debugging
+    console.error('Error:', error.message);
+    // Return error response
+    resp.statusCode = 500;
+    return { error: error.message };
+  }
+};
+```
+
+### Retry Behavior
+
+- HTTP functions: No automatic retry (client should retry)
+- Event functions: Depends on trigger (OSS triggers have built-in retry)
+- For critical operations, implement idempotency
+
+## Accessing Aliyun Services from Functions
+
+```javascript
+const OSS = require('ali-oss');
+const FC = require('@alicloud/fc-builders');
+
+module.exports.handler = async (event, context) => {
+  const accessKeyId = process.env.ALICLOUD_ACCESS_KEY;
+  const accessKeySecret = process.env.ALICLOUD_SECRET_KEY;
+
+  // Access OSS
+  const ossClient = new OSS({
+    region: process.env.ALICLOUD_REGION,
+    accessKeyId,
+    accessKeySecret,
+    bucket: 'my-bucket'
+  });
+
+  // Access TableStore
+  const TableStore = require('tablestore');
+  const client = new TableStore.Client({
+    accessKeyId,
+    accessKeySecret,
+    instanceName: 'my-instance',
+    region: process.env.ALICLOUD_REGION
+  });
+};
+```
+
+## Best Practices
+
+1. **Stateless design** - Don't rely on in-memory state between invocations
+2. **Idempotent operations** - Handle duplicate invocations gracefully
+3. **Structured logging** - Use `console.log` with JSON format
+4. **Environment-specific config** - Use env vars, not hardcoded values
+5. **Minimize dependencies** - Faster cold start, smaller package
+6. **Set appropriate timeout** - Not too short (failures), not too long (cost)
+7. **Use VPC wisely** - VPC adds cold start time
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Function timeout | Long execution | Optimize code or use SAE |
+| 403 Forbidden | Permission error | Check RAM roles |
+| Cold start too slow | Large package, VPC | Minimize deps, avoid VPC |
+| Memory exceeded | Memory limit exceeded | Increase memory in template |
+| Concurrent limit reached | Too many requests | Request increase or implement throttling |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`