# 项目字段结构分析文档

## 1. 确认需求阶段字段

### 1.1 确认需求按钮时间字段
**位置**: `Project.data.requirementsConfirmed*` 字段组
```typescript
// 确认需求阶段完成时保存的字段
data.requirementsConfirmed = true;                          // 是否已确认需求
data.requirementsConfirmedBy = this.currentUser.id;        // 确认人ID
data.requirementsConfirmedByName = this.currentUser.get('name'); // 确认人姓名
data.requirementsConfirmedAt = new Date().toISOString();   // 确认时间 (ISO字符串)
```

**文件位置**: `src/modules/project/pages/project-detail/stages/stage-requirements.component.ts:1363-1366`

## 2. 交付执行阶段字段

### 2.1 交付执行四个子阶段
**阶段标识符**:
- `white_model` - 白模阶段
- `soft_decor` - 软装阶段  
- `rendering` - 渲染阶段
- `post_process` - 后期阶段

### 2.2 阶段状态字段
**位置**: `Project.data.deliveryStageStatus` 对象
```typescript
// 每个子阶段的状态结构
deliveryStageStatus: {
  [stageId: string]: {
    status: 'not_started' | 'in_progress' | 'completed' | 'approved' | 'rejected';
    startedAt?: string;      // 开始时间
    completedAt?: string;    // 完成时间
    approvedAt?: string;     // 审批通过时间
    rejectedAt?: string;     // 审批驳回时间
    approvedBy?: string;     // 审批人ID
    rejectionReason?: string; // 驳回原因
  }
}
```

**示例**:
```typescript
data.deliveryStageStatus = {
  white_model: {
    status: 'approved',
    startedAt: '2024-01-01T09:00:00.000Z',
    completedAt: '2024-01-05T17:00:00.000Z',
    approvedAt: '2024-01-06T10:00:00.000Z',
    approvedBy: 'userId123'
  },
  soft_decor: {
    status: 'in_progress',
    startedAt: '2024-01-06T09:00:00.000Z'
  },
  rendering: {
    status: 'not_started'
  },
  post_process: {
    status: 'not_started'
  }
}
```

**文件位置**: `src/modules/project/pages/project-detail/stages/stage-delivery.component.ts:391-400`

## 3. 产品空间场景字段分析

### 3.1 Product表结构 (产品空间)
**主要字段**:
```typescript
interface Product {
  id: string;
  project: Pointer<Project>;           // 关联项目
  productName: string;                 // 产品/空间名称
  productType: string;                 // 产品类型
  status: string;                      // 状态 ('not_started' | 'in_progress' | 'completed')
  
  // 空间信息
  space: {
    spaceName: string;                 // 空间名称
    area: number;                      // 面积
    dimensions: {                      // 尺寸
      length: number;
      width: number; 
      height: number;
    };
    features: string[];                // 空间特征
    constraints: string[];             // 限制条件
    priority: number;                  // 优先级 (1-10)
    complexity: string;                // 复杂度 ('simple' | 'medium' | 'complex')
  };
  
  // 报价信息
  quotation: {
    price: number;                     // 价格
    currency: string;                  // 货币
    breakdown: object;                 // 价格明细
    status: string;                    // 报价状态
    validUntil: Date;                  // 有效期
  };
  
  // 需求信息
  requirements: {
    colorRequirement: object;          // 色彩需求
    spaceStructureRequirement: object; // 空间结构需求
    materialRequirement: object;       // 材质需求
    lightingRequirement: object;       // 照明需求
    specificRequirements: object;      // 特殊需求
  };
  
  profile: Pointer<Profile>;           // 设计师
  images: string[];                    // 空间图片URLs
}
```

### 3.2 Project表中的空间场景字段
**位置**: `Project.data.quotation.spaces` 数组
```typescript
// 报价明细中的空间信息
data.quotation = {
  spaces: [
    {
      name: string;          // 空间名称 (如: "客厅", "主卧", "厨房")
      type: string;          // 空间类型 (如: "living", "bedroom", "kitchen") 
      area: number;          // 面积 (平方米)
      price: number;         // 单价
      totalPrice: number;    // 总价
      description?: string;  // 描述
      productId?: string;    // 关联的Product ID (如果已创建)
    }
  ],
  totalPrice: number;        // 总价
  currency: string;          // 货币
  validUntil: Date;         // 有效期
}
```

### 3.3 空间场景提取逻辑
**从Product表提取**:
```typescript
// 获取项目所有产品空间
const products = await productSpaceService.getProjectProductSpaces(projectId);

products.forEach(product => {
  const spaceName = product.name || product.space?.spaceName;
  const spaceType = product.type || product.space?.spaceType;
  const area = product.space?.area;
  const complexity = product.space?.complexity;
  const priority = product.space?.priority;
  const status = product.status;
});
```

**从Project.data提取**:
```typescript
// 从报价明细提取空间信息
const data = project.get('data') || {};
const quotationSpaces = data.quotation?.spaces || [];

quotationSpaces.forEach(space => {
  const spaceName = space.name;
  const spaceType = space.type;
  const area = space.area;
  const price = space.price;
  const productId = space.productId; // 关联的Product记录
});
```

## 4. 已补充的字段结构

### 4.1 Project.data 中已添加的字段

```typescript
// ✅ 已在确认需求阶段添加：阶段时间轴字段
data.phaseDeadlines = {
  modeling: {
    startDate: Date;
    deadline: Date;
    estimatedDays: number;
    status: 'not_started' | 'in_progress' | 'completed';
    priority: 'high' | 'medium' | 'low';
  };
  softDecor: { /* 同上结构 */ };
  rendering: { /* 同上结构 */ };
  postProcessing: { /* 同上结构 */ };
};

// ✅ 已在确认需求阶段初始化，交付执行阶段动态更新：空间交付物汇总
data.spaceDeliverableSummary = {
  [productId: string]: {
    spaceName: string;
    totalDeliverables: number;
    completedDeliverables: number;
    completionRate: number;
    lastUpdateTime: string;
    phaseProgress: {
      white_model: number;    // 0-100 (审批通过=100, 待审批=80, 驳回=50)
      soft_decor: number;
      rendering: number; 
      post_process: number;
    };
  };
  overallCompletionRate: number; // 整体完成率
};

// ✅ 已在确认需求阶段添加：需求确认详细信息
data.requirementsDetail = {
  globalRequirements: object;     // 全局需求
  spaceRequirements: object[];    // 空间需求
  crossSpaceRequirements: object[]; // 跨空间需求
  referenceImages: object[];      // 参考图片信息
  cadFiles: object[];            // CAD文件信息
  aiAnalysisResults: object;     // AI分析结果
  confirmedAt: string;           // 确认时间
};
```

### 4.2 ProjectFile.data 中已添加的字段

```typescript
// ✅ 已在需求阶段和交付阶段文件上传时添加：文件关联信息
data.spaceId = string;           // 关联的空间/产品ID
data.deliveryType = string;      // 交付类型标识
data.uploadedFor = string;       // 上传用途
data.uploadStage = string;       // 上传阶段 ('requirements' | 'delivery')

// ✅ 已添加：AI分析结果结构
data.analysis = {
  ai: {
    // 图片分析结果
    styleElements?: string[];
    colorPalette?: string[];
    materialAnalysis?: string[];
    layoutFeatures?: string[];
    mood?: string;
    confidence?: number;
    // CAD分析结果  
    spaceStructure?: object;
    dimensions?: object;
    constraints?: string[];
    opportunities?: string[];
    // 通用字段
    analyzedAt: string;
    version: string;
    source: string;
  };
  manual: object | null;         // 手动分析结果
  lastAnalyzedAt: string | null; // 最后分析时间
  // 交付文件专用字段
  qualityScore?: number | null;   // 质量评分
  designCompliance?: object | null; // 设计合规性
};

// ✅ 需求阶段CAD文件额外字段
data.cadFormat = string;         // CAD格式 (dwg/dxf/pdf)

// ✅ 交付阶段文件额外字段  
data.approvalStatus = string;    // 审批状态 ('unverified' | 'pending' | 'approved' | 'rejected')
```

### 4.3 字段补充实现位置

**确认需求阶段** (`stage-requirements.component.ts`):
- ✅ `requirementsDetail` - 需求确认详细信息 (行1368-1390)
- ✅ `phaseDeadlines` - 阶段截止时间初始化 (行1392-1436) 
- ✅ `spaceDeliverableSummary` - 空间交付物汇总初始化 (行1438-1467)
- ✅ 参考图片 `ProjectFile.data` 补充 (行445-459)
- ✅ CAD文件 `ProjectFile.data` 补充 (行607-626)
- ✅ AI分析结果保存到 `ProjectFile.data.analysis.ai` (行802-833)

**交付执行阶段** (`stage-delivery.component.ts`):
- ✅ 交付文件 `ProjectFile.data` 补充 (行685-703)
- ✅ `spaceDeliverableSummary` 动态更新 (行1569, 1863-1929)
- ✅ 审批状态变更时更新交付物进度

## 5. 字段使用示例

### 5.1 获取确认需求时间
```typescript
const project = await projectQuery.get(projectId);
const data = project.get('data') || {};
const requirementsConfirmedAt = data.requirementsConfirmedAt; // ISO字符串
const confirmedTime = new Date(requirementsConfirmedAt);
```

### 5.2 获取交付阶段状态
```typescript
const data = project.get('data') || {};
const deliveryStatus = data.deliveryStageStatus || {};

// 获取白模阶段状态
const whiteModelStatus = deliveryStatus.white_model?.status || 'not_started';
const whiteModelApprovedAt = deliveryStatus.white_model?.approvedAt;

// 检查所有阶段完成情况
const allStages = ['white_model', 'soft_decor', 'rendering', 'post_process'];
const completedStages = allStages.filter(stage => 
  deliveryStatus[stage]?.status === 'approved'
);
```

### 5.3 获取空间场景信息
```typescript
// 方法1: 从Product表获取
const products = await productSpaceService.getProjectProductSpaces(projectId);
const spaceScenes = products.map(p => ({
  id: p.id,
  name: p.name,
  type: p.type,
  area: p.space?.area,
  status: p.status,
  complexity: p.space?.complexity
}));

// 方法2: 从Project.data获取
const data = project.get('data') || {};
const quotationSpaces = data.quotation?.spaces || [];
const spaceScenes = quotationSpaces.map(s => ({
  name: s.name,
  type: s.type, 
  area: s.area,
  price: s.price,
  productId: s.productId
}));
```

## 6. 数据同步建议

### 6.1 确保数据一致性
- Product表中的空间信息应与Project.data.quotation.spaces保持同步
- 交付阶段状态变更时，同时更新Project.currentStage字段
- 空间名称修改时，同步更新所有关联的ProjectFile记录

### 6.2 性能优化
- 使用include查询减少网络请求: `query.include('contact', 'assignee', 'department')`
- 批量操作时使用Parse.Object.saveAll()
- 大数据量时使用分页查询: `query.limit(100).skip(offset)`

---

**文档生成时间**: 2025-11-13  
**基于代码版本**: yss-project latest  
**分析覆盖文件**: 
- stage-requirements.component.ts
- stage-delivery.component.ts  
- product-space.service.ts
- 相关数据模型定义