technical-spec（技术规格）

Technical Design Rules

Basic Technology Stack Policy

TypeScript-based application implementation. Architecture patterns should be selected according to project requirements and scale.

Environment Variable Management and Security

Environment Variable Management

• Centrally manage environment variables and build mechanisms to ensure type safety
• Avoid direct references to process.env, obtain through configuration management layer
• Properly implement default value settings and mandatory checks

Security

• Do not include .env files in Git
• Always manage API keys and secrets as environment variables
• Prohibit logging of sensitive information
• Do not include sensitive information in error messages

Architecture Design

Architecture Design Principles

Select appropriate architecture for each project and define clearly:

• Separation of Responsibilities: Clearly define responsibilities for each layer and module, and maintain boundaries

Unified Data Flow Principles

Basic Principles

1. Single Data Source: Store the same information in only one place
2. Structured Data Priority: Use parsed objects rather than JSON strings
3. Clear Responsibility Separation: Clearly define responsibilities for each layer

Data Flow Best Practices

• Validation at Input: Validate data at input layer and pass internally in type-safe form
• Centralized Transformation: Consolidate data transformation logic in dedicated utilities
• Structured Logging: Output structured logs at each stage of data flow

Build and Testing

Use the appropriate run command based on the packageManager field in package.json.

Build Commands

• build - TypeScript build
• type-check - Type check (no emit)

Testing Commands

• test - Run tests
• test:coverage - Run tests with coverage
• test:coverage:fresh - Run tests with coverage (fresh cache)
• test:safe - Safe test execution (with auto cleanup)
• cleanup:processes - Cleanup Vitest processes

Quality Check Requirements

Quality checks are mandatory upon implementation completion:

Phase 1-3: Code Quality Checks

• Auto-detect and execute the following from package.json scripts:

- lint + format check - Detect unused exports - Detect circular dependencies - TypeScript build

Phase 4: Tests

• test - Test execution

Phase 5: Code Quality Re-verification

• check:code - Re-verify code quality (clean up side effects from test fixes in Phase 4)

Auxiliary Commands

• check:all - Overall integrated check (check:code + test) *for manual batch verification
• open coverage/index.html - Check coverage report
• format - Format fixes
• lint:fix - Lint fixes

Troubleshooting

• Port in use error: Run the cleanup:processes script
• Cache issues: Run the test:coverage:fresh script
• Dependency errors: Clean reinstall dependencies

Coverage Requirements

• MANDATORY: Unit test coverage MUST be 70% or higher
• Metrics: Statements, Branches, Functions, Lines