whale-town-end/docs/ai-reading/README.md

# AI Code Inspection Guide - Whale Town Game Server

## ⚠️ 🚨 CRITICAL: MANDATORY PRE-EXECUTION REQUIREMENTS 🚨 ⚠️

**<EFBFBD> AI MUST READ THIS SECTION FIRST - EXECUTION WITHOUT COMPLETING THESE STEPS IS STRICTLY FORBIDDEN 🔴**

**⛔ STOP! Before executing ANY step (including Step 1), you MUST complete ALL items in this section! ⛔**

---

## 🎯 Pre-execution Setup (MANDATORY - CANNOT BE SKIPPED)

### 🚀 User Information Setup (STEP 0 - MUST EXECUTE FIRST)
**⚠️ CRITICAL: Before starting any inspection steps (including Step 1), MUST run the user information script:**

```bash
# Enter AI-reading directory
cd docs/ai-reading

# Run user information setup script
node tools/setup-user-info.js
```

**🚨 VERIFICATION CHECKPOINT:**
- [ ] Have you executed `node tools/setup-user-info.js`?
- [ ] Does `docs/ai-reading/me.config.json` file exist?
- [ ] Have you read and confirmed the user's date and name from the config file?

**⛔ IF ANY CHECKBOX ABOVE IS UNCHECKED, YOU CANNOT PROCEED TO STEP 1! ⛔**

#### Script Functions
- Automatically get current date (YYYY-MM-DD format)
- Check if config file exists or date matches
- Prompt for username/nickname input if needed
- Save to `me.config.json` file for AI inspection steps

#### Config File Format
```json
{
  "date": "2026-01-13",
  "name": "Developer Name"
}
```

### 📋 Using Config in AI Inspection Steps
When AI executes inspection steps, get user info from config file:

```javascript
// Read config file
const fs = require('fs');
const config = JSON.parse(fs.readFileSync('docs/ai-reading/me.config.json', 'utf-8'));

// Get user information
const userDate = config.date;  // e.g.: "2026-01-13"
const userName = config.name;  // e.g.: "John"

// Use for modification records and @author fields
const modifyRecord = `- ${userDate}: Code standard optimization - Clean unused imports (Modified by: ${userName})`;
```

### 🏗️ Project Characteristics (MUST UNDERSTAND BEFORE STEP 1)
**⚠️ AI MUST read and understand these characteristics BEFORE executing Step 1:**

This project is a **NestJS Game Server** with the following features:
- **Dual-mode Architecture**: Supports both database and memory modes
- **Real-time Communication**: WebSocket-based real-time bidirectional communication
- **Property Testing**: Admin modules use fast-check for randomized testing
- **Layered Architecture**: Core layer (technical implementation) + Business layer (business logic)

**🚨 VERIFICATION CHECKPOINT:**
- [ ] Have you read and understood the project is a NestJS Game Server?
- [ ] Have you understood the dual-mode architecture?
- [ ] Have you understood the WebSocket real-time communication feature?
- [ ] Have you understood the property testing requirements?
- [ ] Have you understood the layered architecture?

**⛔ IF ANY CHECKBOX ABOVE IS UNCHECKED, YOU CANNOT PROCEED TO STEP 1! ⛔**

---

## 🚨 FINAL PRE-EXECUTION CHECKLIST (MUST COMPLETE BEFORE STEP 1) 🚨

**Before proceeding to Step 1, AI MUST confirm ALL of the following:**

### ✅ Mandatory Completion Checklist:
- [ ] ✅ Executed `node tools/setup-user-info.js` script
- [ ] ✅ Confirmed `me.config.json` file exists and contains valid date and name
- [ ] ✅ Read and stored user's date from config file
- [ ] ✅ Read and stored user's name from config file
- [ ] ✅ Understood this is a NestJS Game Server project
- [ ] ✅ Understood the dual-mode architecture (database + memory)
- [ ] ✅ Understood the WebSocket real-time communication feature
- [ ] ✅ Understood the property testing requirements
- [ ] ✅ Understood the layered architecture (Core + Business)
- [ ] ✅ Read and understood the execution principles below

### 🔴 CRITICAL RULE:
**IF ANY ITEM IN THE CHECKLIST ABOVE IS NOT COMPLETED, AI IS ABSOLUTELY FORBIDDEN FROM EXECUTING STEP 1 OR ANY OTHER STEPS!**

**AI MUST explicitly confirm completion of ALL checklist items before proceeding to Step 1!**

---

## 🔄 Execution Principles

### 🚨 Mid-step Start Requirements (Important)
**If AI starts execution from any intermediate step (not starting from step 1), must first complete the following preparation:**

#### 📋 Mandatory Information Collection
Before executing any intermediate step, AI must:
1. **Collect user current date**: For modification records and timestamp updates
2. **Collect user name**: For @author field handling and modification records
3. **Confirm project characteristics**: Identify NestJS game server project features

#### 🔍 Global Context Acquisition
AI must first understand:
- **Project Architecture**: Dual-mode architecture (database+memory), layered structure (Core+Business)
- **Tech Stack**: NestJS, WebSocket, Jest testing, fast-check property testing
- **File Structure**: Overall file organization of current project
- **Existing Standards**: Established naming, commenting, testing standards in project

#### 🎯 Execution Flow Constraints
```
Mid-step Start Request
    ↓
🚨 Mandatory User Info Collection (date, name)
    ↓
🚨 Mandatory Project Characteristics & Context Identification
    ↓
🚨 Mandatory Understanding of Target Step Requirements
    ↓
Start Executing Specified Step
```

**⚠️ Violation Handling: If AI skips information collection and directly executes intermediate steps, user should require AI to restart and complete preparation work.**

### ⚠️ Mandatory Requirements
- **Step-by-step Execution**: Execute one step at a time, strictly no step skipping or merging
- **Wait for Confirmation**: Must wait for user confirmation after each step before proceeding
- **Modification Verification**: Must re-execute current step after any file modification
- **🔥 Must Re-execute Current Step After Modification**: If any modification behavior occurs during current step (file modification, renaming, moving, etc.), AI must immediately re-execute the complete check of that step, cannot directly proceed to next step
- **Re-check After Problem Fix**: If current step has problems requiring modification, AI must re-execute the step after solving problems to ensure no other issues are missed
- **User Info Usage**: All date fields use user-provided real dates, @author fields handled correctly

### 🎯 Execution Flow
```
User Requests Code Inspection
    ↓
🚨 MANDATORY: Execute node tools/setup-user-info.js
    ↓
🚨 MANDATORY: Verify me.config.json exists
    ↓
🚨 MANDATORY: Read and Store User Info (date, name)
    ↓
🚨 MANDATORY: Understand Project Characteristics
    ↓
🚨 MANDATORY: Complete Pre-execution Checklist
    ↓
🚨 MANDATORY: Explicitly Confirm ALL Checklist Items Completed
    ↓
⛔ CHECKPOINT: Cannot proceed without completing above steps ⛔
    ↓
Execute Step 1 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 1 → Verification Report → Wait for Confirmation
    ↓
Execute Step 2 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 2 → Verification Report → Wait for Confirmation
    ↓
Execute Step 3 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 3 → Verification Report → Wait for Confirmation
    ↓
Execute Step 4 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 4 → Verification Report → Wait for Confirmation
    ↓
Execute Step 5 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 5 → Verification Report → Wait for Confirmation
    ↓
Execute Step 6 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 6 → Verification Report → Wait for Confirmation
    ↓
Execute Step 7 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 7 → Verification Report → Wait for Confirmation

⚠️ Key Rule: After any modification behavior in any step, must immediately re-execute that step!
```

## 📚 Step Execution Guide

**🚨 REMINDER: Before executing Step 1, ensure you have completed ALL items in the "FINAL PRE-EXECUTION CHECKLIST" above! 🚨**

### Step 1: Naming Convention Check
**⚠️ BEFORE STARTING STEP 1, AI MUST:**
1. ✅ Confirm `node tools/setup-user-info.js` has been executed
2. ✅ Confirm user date and name have been read from `me.config.json`
3. ✅ Confirm project characteristics have been understood
4. ✅ Explicitly state: "Pre-execution checklist completed, now starting Step 1"

**ONLY AFTER EXPLICIT CONFIRMATION CAN STEP 1 BEGIN!**

---
**Read when executing:** `step1-naming-convention.md`
**Focus on:** Folder structure flattening, game server special file types
**After completion:** Provide inspection report, wait for user confirmation

### Step 2: Comment Standard Check
**Read when executing:** `step2-comment-standard.md`
**Focus on:** @author field handling, modification record updates, timestamp rules
**After completion:** Provide inspection report, wait for user confirmation

### Step 3: Code Quality Check
**Read when executing:** `step3-code-quality.md`
**Focus on:** TODO item handling, unused code cleanup
**After completion:** Provide inspection report, wait for user confirmation

### Step 4: Architecture Layer Check
**Read when executing:** `step4-architecture-layer.md`
**Focus on:** Core layer naming standards, dependency relationship checks
**After completion:** Provide inspection report, wait for user confirmation

### Step 5: Test Coverage Check
**Read when executing:** `step5-test-coverage.md`
**Focus on:** Strict one-to-one test mapping, test file locations, test execution verification
**After completion:** Provide inspection report, wait for user confirmation

#### 🧪 Test File Debugging Standards
**When debugging test files, must follow this workflow:**

1. **Read jest.config.js Configuration**
   - Check jest.config.js to understand test environment configuration
   - Confirm testRegex patterns and file matching rules
   - Understand moduleNameMapper and other configuration items

2. **Use Existing Test Commands in package.json**
   - **Forbidden to customize jest commands**: Must use test commands defined in package.json scripts
   - **Common Test Commands**:
     - `npm run test` - Run all tests
     - `npm run test:unit` - Run unit tests (.spec.ts files)
     - `npm run test:integration` - Run integration tests (.integration.spec.ts files)
     - `npm run test:e2e` - Run end-to-end tests (.e2e.spec.ts files)
     - `npm run test:watch` - Run tests in watch mode
     - `npm run test:cov` - Run tests and generate coverage report
     - `npm run test:debug` - Run tests in debug mode
     - `npm run test:isolated` - Run tests in isolation
   
3. **Specific Module Test Commands**
   - **Zulip Module Tests**:
     - `npm run test:zulip` - Run all Zulip-related tests
     - `npm run test:zulip:unit` - Run Zulip unit tests
     - `npm run test:zulip:integration` - Run Zulip integration tests
     - `npm run test:zulip:e2e` - Run Zulip end-to-end tests
     - `npm run test:zulip:performance` - Run Zulip performance tests

4. **Test Execution Verification Workflow**
   ```
   Discover Test Issue → Read jest.config.js → Choose Appropriate npm run test:xxx Command → Execute Test → Analyze Results → Fix Issues → Re-execute Test
   ```

5. **Test Command Selection Principles**
   - **Single File Test**: Use `npm run test -- file_path`
   - **Specific Type Test**: Use corresponding test:xxx command
   - **Debug Test**: Prioritize `npm run test:debug`
   - **CI/CD Environment**: Use `npm run test:isolated`

### Step 6: Function Documentation Generation
**Read when executing:** `step6-documentation.md`
**Focus on:** API interface documentation, WebSocket event documentation
**After completion:** Provide inspection report, wait for user confirmation

### Step 7: Code Commit
**Read when executing:** `step7-code-commit.md`
**Focus on:** Git change detection, branch management, commit message standards, merge document generation
**🚨 Important Principle:** Regardless of when or what type of changes were made, if Git detects changes, provide commit service
**After completion:** Provide commit report, generate merge document

## 📋 Unified Report Template

Use this template for reporting after each step completion:

```
## Step X: [Step Name] Inspection Report

### 🔍 Inspection Results
[List of discovered issues]

### 🛠️ Correction Plan  
[Specific correction suggestions]

### ✅ Completion Status
- Check Item 1 ✓/✗
- Check Item 2 ✓/✗

**Please confirm correction plan, proceed to next step after confirmation**
```

## 🚨 Global Constraints

### 📝 File Modification Record Standards (Important)
**After each modification execution, file headers need to update modification records and related information**

#### Modification Type Definitions
- `Code Standard Optimization` - Naming standards, comment standards, code cleanup, etc.
- `Feature Addition` - Adding new features or methods
- `Feature Modification` - Modifying existing feature implementations
- `Bug Fix` - Fixing code defects
- `Performance Optimization` - Improving code performance
- `Refactoring` - Code structure adjustment but functionality unchanged

#### Modification Record Format Requirements
```typescript
/**
 * Recent Modifications:
 * - [User Date]: Code Standard Optimization - Clean unused imports (Modified by: [User Name])
 * - 2024-01-06: Bug Fix - Fix email validation logic error (Modified by: Li Si)
 * - 2024-01-05: Feature Addition - Add user verification code login feature (Modified by: Wang Wu)
 * 
 * @author [Processed Author Name]
 * @version x.x.x
 * @since [Creation Date]
 * @lastModified [User Date]
 */
```

#### 🔢 Recent Modification Record Quantity Limit
- **Maximum 5 Records**: Recent modification records keep maximum of 5 latest records
- **Auto-delete When Exceeded**: When adding new modification records, if exceeding 5, automatically delete oldest records
- **Maintain Time Order**: Records arranged in reverse chronological order, newest at top
- **Complete Record Retention**: Each record must include complete date, modification type, description and modifier information

#### Version Number Increment Rules
- **Patch Version +1**: Code standard optimization, bug fixes (1.0.0 → 1.0.1)
- **Minor Version +1**: Feature addition, feature modification (1.0.1 → 1.1.0)
- **Major Version +1**: Refactoring, architecture changes (1.1.0 → 2.0.0)

#### Time Update Rules
- **Check Only No Modification**: If only checking without actually modifying file content, **do not update** @lastModified field
- **Update Only on Actual Modification**: Only update @lastModified field and add modification records when actually modifying file content
- **Git Change Detection**: Check if files have actual changes through `git status` and `git diff`, only add modification records and update timestamps when git shows files are modified

#### 🚨 Important Emphasis: Pure Check Steps Do Not Update Modification Records
**When AI executes code inspection steps, if code already meets standards and needs no modification, then:**
- **Forbidden to Add Modification Records**: Do not add records like "AI code inspection step X: XXX check and optimization"
- **Forbidden to Update Timestamps**: Do not update @lastModified field
- **Forbidden to Increment Version Numbers**: Do not modify @version field
- **Only add modification records when actually modifying code content, comment content, structure, etc.**

**Wrong Example**:
```typescript
// ❌ Wrong: Only checked without modification but added modification record
/**
 * Recent Modifications:
 * - 2026-01-12: Code Standard Optimization - AI code inspection step 2: Comment standard check and optimization (Modified by: moyin)  // This is wrong!
 * - 2026-01-07: Feature Addition - Add user verification feature (Modified by: Zhang San)
 */
```

**Correct Example**:
```typescript
// ✅ Correct: Check found compliance with standards, do not add modification records
/**
 * Recent Modifications:
 * - 2026-01-07: Feature Addition - Add user verification feature (Modified by: Zhang San)  // Keep original records unchanged
 */
```

### @author Field Handling Standards
- **Retention Principle**: Human names must be retained, cannot be arbitrarily modified
- **AI Identifier Replacement**: Only AI identifiers (kiro, ChatGPT, Claude, AI, etc.) can be replaced with user names
- **Judgment Example**: `@author kiro` → Can replace, `@author Zhang San` → Must retain

### Game Server Special Requirements
- **WebSocket Files**: Gateway files must have complete connection and message processing tests
- **Dual-mode Services**: Both memory services and database services need complete test coverage
- **Property Testing**: Admin modules use fast-check for property testing
- **Test Separation**: Strictly distinguish unit tests, integration tests, E2E tests, performance tests

## 🔧 Modification Verification Process

### 🔥 Immediately Re-execute Rule After Modification (Important)
**After any modification behavior occurs in any step, AI must immediately re-execute that step, cannot directly proceed to next step!**

#### Modification Behaviors Include But Not Limited To:
- File content modification (code, comments, configuration, etc.)
- File renaming
- File moving
- File deletion
- New file creation
- Folder structure adjustment

#### Mandatory Execution Process:
```
Step Execution → Discover Issues → Execute Modifications → 🔥 Immediately Re-execute That Step → Verify No Omissions → User Confirmation → Next Step
```

### Re-check Process After Problem Fix
When issues are discovered and modifications made in any step, must follow this process:

1. **Execute Modification Operations**
   - Make specific modifications based on discovered issues
   - Ensure modification content is accurate
   - **Update file header modification records, version numbers and @lastModified fields**

2. **🔥 Immediately Re-execute Current Step**
   - **Cannot skip this step!**
   - Complete re-execution of all check items for that step
   - Cannot only check modified parts, must comprehensively re-check

3. **Provide Verification Report**
   - Confirm previously discovered issues are resolved
   - Confirm no new issues introduced
   - Confirm no other issues omitted

4. **Wait for User Confirmation**
   - Provide complete verification report
   - Wait for user confirmation before proceeding to next step

### Verification Report Template
```
## Step X: Modification Verification Report

### 🔧 Executed Modification Operations
- Modification Type: [File modification/renaming/moving/deletion, etc.]
- Modification Content: [Specific modification description]
- Affected Files: [List of affected files]

### 📝 Updated Modification Records
- Added Modification Record: [User Date]: [Modification Type] - [Modification Content] (Modified by: [User Name])
- Updated Version Number: [Old Version] → [New Version]
- Updated Timestamp: @lastModified [User Date]

### 🔍 Re-executed Step X Complete Check Results
[Complete re-execution results of all check items for that step]

### ✅ Verification Status
- Original Issues Resolved ✓
- Modification Records Updated ✓
- No New Issues Introduced ✓
- No Other Issues Omitted ✓
- Step X Check Completely Passed ✓

**🔥 Important: This step has completed modification and re-verification, please confirm before proceeding to next step**
```

### Importance of Re-checking
- **Ensure Completeness**: Avoid omitting other issues during modification process
- **Prevent New Issues**: Ensure modifications do not introduce new problems
- **Maintain Quality**: Each step reaches complete inspection standards
- **Maintain Consistency**: Ensure rigor throughout entire inspection process
- **🔥 Mandatory Execution**: Cannot skip this step after modifications

## ⚡ Key Success Factors

- **Strict Step-by-step Execution**: No step skipping, no merged execution
- **🔥 Immediately Re-execute After Modification**: Must immediately re-execute current step after any modification behavior, cannot directly proceed to next step
- **Must Re-check After Problem Fix**: Must re-execute entire step after file modification to ensure no omissions
- **Must Update Modification Records**: Must update file header modification records, version numbers and timestamps after each file modification
- **Real Modification Verification**: Verify modification effects through tools
- **Accurate User Info Usage**: Correctly apply date and name information
- **Project Characteristic Adaptation**: Optimize inspections for game server characteristics
- **Complete Report Provision**: Provide detailed inspection reports for each step

---

## 🔴 FINAL WARNING 🔴

**⚠️ AI EXECUTION REQUIREMENTS SUMMARY:**

1. **STEP 0 (MANDATORY)**: Execute `node tools/setup-user-info.js`
2. **STEP 0.1 (MANDATORY)**: Verify `me.config.json` exists and read user info
3. **STEP 0.2 (MANDATORY)**: Understand project characteristics
4. **STEP 0.3 (MANDATORY)**: Complete and explicitly confirm pre-execution checklist
5. **ONLY THEN**: Begin Step 1

**🚨 VIOLATION CONSEQUENCES:**
- If AI skips Step 0 and directly executes Step 1, user MUST stop AI and require restart
- If AI does not explicitly confirm checklist completion, user MUST stop AI and require confirmation
- If AI does not read user info from config file, all subsequent steps are INVALID

**✅ CORRECT EXECUTION START:**
```
AI: "I will now begin the code inspection process.

Step 0 - Pre-execution Setup:
1. ✅ Executing user information setup script...
   Command: cd docs/ai-reading && node tools/setup-user-info.js
   
2. ✅ Verifying me.config.json exists...
   File found: docs/ai-reading/me.config.json
   
3. ✅ Reading user information...
   User Date: 2026-01-19
   User Name: [Name from config]
   
4. ✅ Understanding project characteristics...
   - NestJS Game Server ✓
   - Dual-mode Architecture ✓
   - WebSocket Communication ✓
   - Property Testing ✓
   - Layered Architecture ✓
   
5. ✅ Pre-execution checklist completed!

All mandatory pre-execution requirements have been satisfied.
Now proceeding to Step 1: Naming Convention Check..."
```

**⛔ INCORRECT EXECUTION START (FORBIDDEN):**
```
AI: "I will start with Step 1: Naming Convention Check..." ❌ WRONG!
AI: "Let me check the naming conventions..." ❌ WRONG!
AI: "Starting code inspection..." ❌ WRONG!
```

---

**🎯 Remember: Step 0 is NOT optional - it is MANDATORY before ANY other step!**