@umacloud/knowledge 1.0.1

package/experts/architect/methodology.md

@@ -0,0 +1,124 @@
+---
+id: methodology
+title: Architect — System Architecture Methodology
+domain: experts
+category: architect
+difficulty: intermediate
+tags: [architecture, data, decision, design, experts, framework, infrastructure, methodology]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Architect — System Architecture Methodology
+
+## Architecture Decision Framework
+
+### Technology Selection
+- Evaluate based on: team expertise, community size, long-term viability, license
+- Document decision rationale in ADR (Architecture Decision Record) format
+- Prefer boring technology for core infrastructure; innovate at edges
+- Prototype risky integrations before committing
+
+### Scalability Planning
+- Design for 10x current load; plan for 100x
+- Identify bottlenecks early: database reads, API fanout, file I/O
+- Separate read/write paths when read:write ratio exceeds 10:1
+- Use connection pooling for all database and HTTP client connections
+
+## System Design Patterns
+
+### Layered Architecture
+```
+┌─────────────────────────┐
+│  Presentation (UI/API)  │
+├─────────────────────────┤
+│  Application (Use Cases)│
+├─────────────────────────┤
+│  Domain (Business Logic)│
+├─────────────────────────┤
+│  Infrastructure (DB/IO) │
+└─────────────────────────┘
+```
+- Each layer only depends on the layer below
+- Domain layer has zero external dependencies
+- Infrastructure implements interfaces defined by domain
+
+### API Gateway Pattern
+- Single entry point for all client requests
+- Rate limiting, auth, logging at gateway level
+- Request routing to appropriate microservice/handler
+- Response aggregation for composite endpoints
+
+### Event-Driven Architecture
+- Use events for cross-domain communication
+- Event store for audit trail and replay capability
+- Idempotent event handlers (at-least-once delivery)
+- Dead letter queue for failed event processing
+
+## Data Architecture
+
+### Database Selection Matrix
+| Requirement | Relational (PostgreSQL) | Document (MongoDB) | KV (Redis) |
+|---|---|---|---|
+| Complex queries | Best | Poor | N/A |
+| Schema flexibility | Moderate | Best | N/A |
+| Transactions | Best | Limited | Limited |
+| Caching | Moderate | Moderate | Best |
+| Full-text search | Good (w/ extensions) | Good | N/A |
+
+### Schema Design Principles
+- Normalize to 3NF by default; denormalize with measurement justification
+- Every table needs: `id` (UUID/ULID), `created_at`, `updated_at`
+- Soft-delete with `deleted_at` for recoverable entities
+- Index foreign keys and frequently queried columns
+- Use enums/check constraints at DB level, not just application
+
+### Migration Strategy
+- One migration per logical change (not per table)
+- Migrations must be reversible (up + down)
+- Zero-downtime migrations: add column → backfill → add constraint → remove old
+- Never rename columns in production; add new, migrate, drop old
+
+## Infrastructure Patterns
+
+### Deployment Architecture
+- Container-first: Dockerfile for every deployable service
+- Environment parity: dev ≈ staging ≈ production
+- Configuration via environment variables (12-factor)
+- Health check endpoints: `/health` (liveness), `/ready` (readiness)
+
+### Caching Strategy
+- Cache hierarchy: browser → CDN → application → database
+- Cache invalidation: TTL for reads, explicit invalidation on writes
+- Cache key design: `{entity}:{id}:{version}` for granular invalidation
+- Never cache authenticated/personalized responses at CDN level
+
+### Observability
+- Structured logging (JSON) with correlation IDs
+- Metrics: RED method (Rate, Errors, Duration) for services
+- Distributed tracing for cross-service request flows
+- Alert on symptoms (error rate, latency), not causes
+
+## Security Architecture
+
+### Defense in Depth
+1. Network: firewall rules, VPC isolation, TLS everywhere
+2. Application: input validation, output encoding, CSRF tokens
+3. Data: encryption at rest, field-level encryption for PII
+4. Access: RBAC/ABAC, principle of least privilege
+5. Audit: immutable log of all access and mutations
+
+### Auth Architecture
+- Prefer JWT for stateless API auth; sessions for server-rendered
+- Access token: short-lived (15m), refresh token: longer (7d), rotate on use
+- Store refresh tokens in httpOnly secure cookies, not localStorage
+- Permission model: User → Role → Permission (many-to-many)
+
+## Architecture Review Checklist
+- [ ] Single responsibility: each service/module does one thing
+- [ ] Failure isolation: one component failure doesn't cascade
+- [ ] Data ownership: each domain owns its data store
+- [ ] API contract: OpenAPI/GraphQL schema defined before implementation
+- [ ] Security: auth, authz, input validation, secrets management
+- [ ] Observability: logging, metrics, tracing, alerting
+- [ ] Scalability: identified bottlenecks and horizontal scaling path
+- [ ] Recovery: backup strategy, disaster recovery, rollback plan

package/experts/architect/security.md

@@ -0,0 +1,75 @@
+---
+id: security
+title: Architect — Security Checklist (OWASP-based)
+domain: experts
+category: architect
+difficulty: intermediate
+tags: [authentication, authorization, encoding, experts, input, management, output, security]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Architect — Security Checklist (OWASP-based)
+
+## Authentication & Session Management
+
+- [ ] Passwords hashed with bcrypt (cost ≥ 12) or Argon2id
+- [ ] JWT access tokens expire in ≤ 15 minutes
+- [ ] Refresh tokens are single-use and stored server-side
+- [ ] Session invalidation on password change
+- [ ] Account lockout after 5 failed attempts (15 min cooldown)
+- [ ] MFA option available for sensitive operations
+- [ ] Logout invalidates all tokens server-side
+
+## Input Validation
+
+- [ ] ALL user input validated server-side (never trust client)
+- [ ] Parameterized queries / ORM for database operations (no string concatenation)
+- [ ] File uploads: validate type (magic bytes, not extension), limit size, store outside webroot
+- [ ] Reject unexpected fields in request body (allowlist, not blocklist)
+- [ ] Content-Type header checked on all endpoints accepting body
+
+## Output Encoding
+
+- [ ] HTML output encoded to prevent XSS (`<script>` → `&lt;script&gt;`)
+- [ ] JSON responses use `Content-Type: application/json` (never `text/html`)
+- [ ] User-generated content sanitized before rendering
+- [ ] CSP headers set: `Content-Security-Policy: default-src 'self'`
+
+## Authorization
+
+- [ ] Every endpoint checks authorization (not just authentication)
+- [ ] IDOR prevention: verify user owns the resource, not just that resource exists
+- [ ] Admin endpoints on separate route group with role check middleware
+- [ ] API keys scoped to minimum necessary permissions
+
+## Data Protection
+
+- [ ] HTTPS only (HSTS header with max-age ≥ 1 year)
+- [ ] Sensitive data encrypted at rest (AES-256)
+- [ ] PII not logged (mask email, phone in logs)
+- [ ] Database credentials in environment variables, never in code
+- [ ] `.env` in `.gitignore`
+
+## Headers
+
+```
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+Content-Security-Policy: default-src 'self'; script-src 'self'
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+## Dependency Security
+
+- [ ] No known vulnerabilities (`npm audit` / `cargo audit` clean)
+- [ ] Dependencies pinned to exact versions in lock file
+- [ ] Automated dependency update checks (Dependabot / Renovate)
+
+## Error Handling
+
+- [ ] Internal errors return generic message to client (no stack traces)
+- [ ] Errors logged with context on server (request ID, user ID, timestamp)
+- [ ] 404 for missing resources (don't leak existence via different error codes)
+- [ ] Rate limiting on all public endpoints

package/experts/backend-lead/methodology.md

@@ -0,0 +1,216 @@
+---
+id: methodology
+title: Backend Lead — Development Methodology
+domain: experts
+category: backend-lead
+difficulty: intermediate
+tags: [authentication, best, database, experts, implementation, logging, methodology, pattern]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Backend Lead — Development Methodology
+
+## 工程标准库速查（按需查阅对应标准，`backend/01-standards/<id>`）
+
+本项目附带商业级工程标准库。**先识别项目用到的方面，再查对应标准照着做**（不确定就检索 knowledge/）：
+
+- 结构：application-layering-and-packaging（分层/服务层/分包）· backend-framework-idioms（所选框架地道写法）· api-and-error-conventions · data-modeling-and-persistence · config-and-observability
+- 横切：secure-coding-baseline（安全/OWASP）· test-strategy-and-layering · performance-and-scalability · microservices-and-distributed
+- 功能（项目用到才做）：auth-implementation · payment-integration · file-upload-and-storage · background-jobs-and-async · email-and-notifications · search-and-filtering · realtime-and-websocket · analytics-and-growth · llm-application-standard（AI/RAG/Agent）
+- 交付：deployment-and-delivery-standard · release-and-store-submission
+- 前端/多端见 frontend/mobile/desktop/miniprogram/harmony/cross-platform 下对应标准（含各端官方设计规范）。
+
+## 结构第一：分层 + 分包（动手写代码前先定骨架）
+
+商业级后端的第一要务不是功能，而是**结构**。写任何实现前，先按下面定下分层与分包骨架，再填代码。详见标准《应用分层与分包标准》(`backend/01-standards/application-layering-and-packaging`)，这里给硬性底线：
+
+- **四层 + 依赖向内**：接口层(controller，仅传输) → 应用层(service，编排+事务) → 领域层(entity/VO，业务规则与不变量) → 基础设施层(repository/adapter，持久化与外部)。依赖只能向内，业务核心不依赖框架/DB/HTTP。
+- **服务层规则**：无状态；一个方法=一个用例=一个事务边界；收发 DTO，**绝不返回/接收 ORM entity**；只依赖 repository/gateway 接口（注入），不依赖具体实现。
+- **领域不要贫血**：把"这个对象在什么状态下能做什么"的规则封进 entity 方法（`order.cancel()`），不要散在 service 的 if 里。
+- **校验分层**：边界格式校验放接口层(DTO+schema，失败 422)；业务不变量放领域/服务层。
+- **分包优先 package-by-feature**：`modules/<feature>/{interface,application,domain,infrastructure}`，跨 feature 通过服务接口/领域事件通信，不互相调对方 repository/entity。先模块化单体，复杂了再抽服务。
+- **红线**：fat controller、controller 直连 repository/SQL、service 泄露 entity、事务写在 controller/repository、一个类贯穿所有层——出现即不合格。
+
+## API Implementation Pattern
+
+### Controller/Handler Structure
+Every API endpoint follows:
+1. **Parse** — validate request body/params
+2. **Authorize** — check user has permission
+3. **Execute** — call business logic
+4. **Respond** — format and return result
+
+```
+Request → Middleware(auth, rate-limit) → Handler(parse, authorize, execute, respond) → Response
+```
+
+### Input Validation Rules
+- Validate at the API boundary, not in business logic
+- Use schema validation library (Zod, Joi, Pydantic, serde)
+- Return 422 with field-level errors:
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "details": [
+      { "field": "email", "message": "Must be a valid email address" },
+      { "field": "name", "message": "Must be between 2 and 100 characters" }
+    ]
+  }
+}
+```
+- Never trust frontend validation alone
+
+### Error Handling Pattern
+```
+try {
+  // business logic
+} catch (NotFoundError) {
+  return 404 with generic message
+} catch (ForbiddenError) {
+  return 403
+} catch (ConflictError) {
+  return 409 with "resource already exists"
+} catch (ValidationError) {
+  return 422 with field details
+} catch (unknown) {
+  log error with full context (requestId, userId, stack trace)
+  return 500 with "Internal server error" (NO details to client)
+}
+```
+
+## Database Best Practices
+
+### Migration Standards
+- Every schema change is a migration file with up + down
+- Never modify a deployed migration — create a new one
+- Migrations run automatically on deploy
+- Test migrations against production-like data volume
+
+### Query Patterns
+- Use parameterized queries (NEVER string concatenation)
+- Add indexes for: foreign keys, frequently queried fields, sort columns
+- Pagination: cursor-based for infinite scroll, offset for page numbers
+- N+1 prevention: eager load relationships or use DataLoader pattern
+
+### Seed Data
+- `seeds/development.ts` — realistic test data for local dev
+- `seeds/test.ts` — minimal data for automated tests
+- Never seed production directly
+
+## Authentication Implementation
+
+### JWT Flow
+```
+1. POST /auth/login { email, password }
+   → Verify credentials
+   → Generate access token (15 min, signed)
+   → Generate refresh token (7 days, stored in DB + httpOnly cookie)
+   → Return { accessToken, user }
+
+2. Authenticated request:
+   → Client sends: Authorization: Bearer <accessToken>
+   → Middleware verifies signature + expiration
+   → Extracts user from claims
+
+3. Token refresh:
+   → POST /auth/refresh (cookie has refresh token)
+   → Verify refresh token exists in DB + not expired
+   → Invalidate old refresh token (single-use)
+   → Issue new access + refresh tokens
+
+4. Logout:
+   → POST /auth/logout
+   → Delete refresh token from DB
+   → Clear httpOnly cookie
+```
+
+### Password Rules
+- Hash with bcrypt (cost 12) or Argon2id
+- Minimum 8 characters
+- Check against breached password list (haveibeenpwned API)
+- Never log plaintext passwords
+- Never return password hash in API responses
+
+## Logging Standards
+
+### What to Log
+| Level | When | Example |
+|---|---|---|
+| ERROR | Operation failed, needs attention | Database connection lost, payment failed |
+| WARN | Degraded but functioning | Cache miss, retry succeeded, rate limit approaching |
+| INFO | Significant events | User signed up, order placed, deploy completed |
+| DEBUG | Development troubleshooting | Query executed, cache hit, request parsed |
+
+### Log Format
+```json
+{
+  "level": "error",
+  "timestamp": "2026-01-15T10:30:00Z",
+  "requestId": "req_abc123",
+  "userId": "usr_456",
+  "message": "Payment processing failed",
+  "error": { "code": "STRIPE_DECLINED", "message": "Card declined" },
+  "context": { "orderId": "ord_789", "amount": 9900, "currency": "usd" }
+}
+```
+
+### What NOT to Log
+- Passwords, tokens, API keys
+- Full credit card numbers (last 4 only)
+- Personal health information
+- Full request/response bodies (summarize instead)
+
+## Testing Standards
+
+### Unit Tests
+- Test business logic functions in isolation
+- Mock external dependencies (database, APIs, email)
+- Naming: `describe('createUser')` → `it('should hash password before saving')`
+- Assert both success path and error paths
+
+### Integration Tests
+- Test API endpoints with real database (test instance)
+- Reset database between tests (transaction rollback or truncate)
+- Test auth: verify 401 without token, 403 with wrong role
+- Test validation: verify 422 for each invalid field
+
+### Test Coverage Targets
+| Layer | Target |
+|---|---|
+| Business logic | ≥ 90% |
+| API handlers | ≥ 80% |
+| Middleware | ≥ 80% |
+| Utilities | ≥ 95% |
+| Overall | ≥ 80% |
+
+## Environment Variables
+
+### Naming Convention
+```
+# Database
+DATABASE_URL=postgres://user:pass@host:5432/dbname
+DATABASE_POOL_SIZE=10
+
+# Auth
+JWT_SECRET=<random 256-bit key>
+JWT_ACCESS_TTL=900     # 15 minutes in seconds
+JWT_REFRESH_TTL=604800 # 7 days in seconds
+
+# External services
+STRIPE_SECRET_KEY=sk_live_...
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+
+# App
+NODE_ENV=production
+PORT=3001
+CORS_ORIGIN=https://your-frontend.com
+LOG_LEVEL=info
+```
+
+### Rules
+- NEVER commit `.env` files (add to `.gitignore`)
+- Provide `.env.example` with placeholder values
+- Validate all required env vars on startup (fail fast if missing)
+- Different values per environment (dev/staging/prod)

package/experts/devops/methodology.md

@@ -0,0 +1,160 @@
+---
+id: methodology
+title: DevOps — Methodology
+domain: experts
+category: devops
+difficulty: intermediate
+tags: [alerting, design, docker, environment, experts, methodology, monitoring, pipeline]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# DevOps — Methodology
+
+## 交付底线（能跑通 ≠ 能交付）
+
+详见标准《部署与交付规范》(`cicd/01-standards/deployment-and-delivery-standard`)。硬性底线：
+
+- **Dockerfile**：多阶段、固定版本小基础镜像、**非 root**、.dockerignore、HEALTHCHECK；不把密钥/.env 打进镜像。
+- **CI**：lint+类型+单元+集成+安全扫描(依赖审计/镜像扫描)+质量门，任一失败**阻断合并**；制品打不可变版本(git sha)，不用 latest 部署。
+- **CD 零停机**：滚动/蓝绿/金丝雀之一；新旧并存期间接口与 DB **向后兼容**；**禁止手改生产**。
+- **迁移**：自动化、幂等、expand-contract、不锁表停服。
+- **环境/密钥**：dev/staging/prod 隔离，同代码不同配置；密钥按环境注入，绝不进仓库/镜像/日志。
+- **回滚 + 观测**：保留上一可用版本可一键回滚；发布后盯错误率/p99；健康探针 + 优雅停机。
+- **随附交付物**：Dockerfile/compose、CI 配置、迁移脚本、.env.example、部署 README。
+
+## CI/CD Pipeline Design
+
+### Pipeline Stages
+```
+commit → lint → test → build → deploy:staging → smoke-test → deploy:production → monitor
+```
+
+### Stage Details
+
+**Lint** (< 1 min)
+- TypeScript: `tsc --noEmit`
+- ESLint: `eslint --max-warnings 0`
+- Prettier: `prettier --check`
+- Fail fast: any lint failure blocks the pipeline
+
+**Test** (< 5 min)
+- Unit tests: `jest` / `vitest` / `cargo test`
+- Coverage gate: fail if below threshold (80% for business logic)
+- Parallel execution when possible
+
+**Build** (< 3 min)
+- Production build with minification
+- Generate source maps (for error tracking, not served to users)
+- Output bundle size check (fail if > budget)
+
+**Deploy: Staging**
+- Automatic on every merged PR to main
+- Same infrastructure as production (just scaled down)
+- Seeded with realistic test data
+
+**Smoke Test**
+- Automated: hit key endpoints, verify 200 responses
+- Verify database migration ran successfully
+- Check external service connections (payment, email, etc)
+
+**Deploy: Production**
+- Manual approval gate (or auto after staging smoke passes)
+- Rolling deploy (no downtime)
+- Database migrations run before new code deploys
+
+**Monitor**
+- Watch error rate for 15 minutes after deploy
+- Auto-rollback if error rate > 1%
+
+## Environment Strategy
+
+| Environment | Purpose | Data | Access |
+|---|---|---|---|
+| local | Development | Seed data | Developer |
+| staging | Pre-production testing | Anonymized prod copy | Team |
+| production | Live users | Real data | Restricted |
+
+### Environment Variables
+- Same variable names across all environments
+- Different VALUES per environment (never different variable names)
+- `.env.example` committed with placeholder values
+- Actual `.env` files NEVER committed
+
+## Docker Standards
+
+### Dockerfile Best Practices
+```dockerfile
+# Multi-stage build
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production=false
+COPY . .
+RUN npm run build
+
+FROM node:20-slim
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+EXPOSE 3000
+CMD ["node", "dist/server.js"]
+```
+
+Rules:
+- Multi-stage builds (separate build/runtime)
+- Pin base image versions (`node:20-slim`, not `node:latest`)
+- `npm ci` not `npm install` (deterministic)
+- Non-root user in production image
+- `.dockerignore` excludes node_modules, .git, .env
+
+## Monitoring & Alerting
+
+### Four Golden Signals
+| Signal | What to measure | Alert threshold |
+|---|---|---|
+| **Latency** | p95 response time | > 500ms for 5 min |
+| **Traffic** | Requests per second | Drop > 50% from baseline |
+| **Errors** | 5xx error rate | > 1% for 5 min |
+| **Saturation** | CPU/memory usage | > 80% for 10 min |
+
+### Health Check Endpoint
+```
+GET /api/health
+→ 200 { "status": "healthy", "version": "1.2.3", "uptime": 86400 }
+→ 503 { "status": "unhealthy", "checks": { "database": "timeout" } }
+```
+
+Check: database connection, cache connection, external API reachability
+
+### Logging in Production
+- Structured JSON logs (not plain text)
+- Include: timestamp, level, requestId, userId, message
+- Never log: passwords, tokens, PII, credit card numbers
+- Log to stdout (let the platform handle aggregation)
+
+## Rollback Strategy
+
+### Criteria for rollback
+- Error rate > 1% sustained for 5 minutes
+- Any 500 on critical path (checkout, login)
+- Performance regression > 2x baseline latency
+
+### Rollback steps
+1. Route traffic to previous version (< 1 min)
+2. Verify previous version is healthy
+3. Investigate root cause on the failed version
+4. Fix → test on staging → re-deploy
+
+### Database rollback
+- Every migration has a DOWN migration
+- Test DOWN migration BEFORE deploying UP
+- Never drop columns immediately — deprecate, deploy, then drop in next release
+
+## Security in Deployment
+
+- [ ] All secrets in environment variables / secret manager (never in code)
+- [ ] HTTPS everywhere (HSTS with 1-year max-age)
+- [ ] Database not publicly accessible (VPC/private network only)
+- [ ] SSH access via bastion/jump server only
+- [ ] Automated dependency vulnerability scanning
+- [ ] Container images scanned for CVEs before deploy