iloom-flatten/outputs/文档鉴别材料-设计说明书.md

# 纺织行业采购计划管理系统 - 设计说明书

## 文档鉴别材料 - 设计说明书

**软件名称**：纺织行业采购计划管理系统  
**软件简称**：昱森  
**版本号**：V1.0.0  
**编制日期**：2025年05月

---

## 目录

1. 系统架构设计
2. 数据库设计
3. 接口设计
4. 安全设计
5. 部署架构
6. 技术选型说明

---

## 第一章 系统架构设计

### 1.1 整体架构

本系统采用前后端分离架构，基于云原生技术栈构建：

```
┌─────────────────────────────────────────────────────────────┐
│                        客户端层                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Web浏览器  │  │   移动端    │  │   平板      │         │
│  │  (React)    │  │  (H5)       │  │  (响应式)   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      云服务层 (Meoo Cloud)                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Supabase  │  │   认证服务   │  │   实时订阅   │         │
│  │  (PostgreSQL)│  │  (Auth)     │  │ (Realtime)  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
```

### 1.2 前端架构

**技术栈**：
- **框架**：React 18 + TypeScript
- **路由**：React Router v6 (HashRouter)
- **状态管理**：React Context + Zustand
- **样式方案**：TailwindCSS
- **动画库**：Framer Motion
- **构建工具**：Webpack 5

**目录结构**：
```
src/
├── components/     # 公共组件
├── pages/          # 页面组件
│   ├── purchaser/  # 采购商页面
│   ├── textile/    # 纺织厂页面
│   └── washing/    # 水洗厂页面
├── hooks/          # 自定义Hooks
├── contexts/       # React上下文
├── stores/         # 状态管理
├── utils/          # 工具函数
├── types/          # 类型定义
└── supabase/       # Supabase客户端
```

### 1.3 后端架构

**云服务**：Meoo Cloud (基于Supabase)
- **数据库**：PostgreSQL 15
- **认证**：Supabase Auth
- **实时**：Supabase Realtime
- **存储**：Supabase Storage

---

## 第二章 数据库设计

### 2.1 ER关系图

```
auth.users (Supabase内置)
    │
    ├── 1:1 ── profiles (用户配置)
    │              │
    │              ├── N:1 ── companies (公司)
    │              │              │
    │              │              ├── 1:N ── company_members (公司成员)
    │              │              │
    │              │              ├── 1:N ── factories (工厂)
    │              │              │              │
    │              │              │              ├── N:M ── production_plans
    │              │              │
    │              │              ├── 1:N ── warehouses (仓库)
    │              │              │              │
    │              │              │              ├── 1:N ── inventory_records
    │              │              │
    │              │              ├── 1:N ── yarn_stock (纱线库存)
    │              │
    │              ├── 1:N ── production_plans (采购商创建的计划)
    │              │              │
    │              │              ├── 1:N ── yarn_ratios (纱线配比)
    │              │              │
    │              │              ├── 1:N ── plan_process_steps (流程节点)
    │              │              │
    │              │              ├── N:M ── factories (通过plan_factories关联)
    │              │
    │              ├── 1:N ── payments (结款记录)
```

### 2.2 核心表结构

#### 2.2.1 companies - 公司表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID (PK) | 公司ID |
| name | TEXT | 公司名称 |
| role | app_role | 公司类型：purchaser/textile/washing |
| address | TEXT | 公司地址 |
| contact_phone | TEXT | 联系电话 |
| created_at | TIMESTAMPTZ | 创建时间 |

#### 2.2.2 profiles - 用户配置表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID (PK) | 关联auth.users.id |
| username | TEXT (UNIQUE) | 用户名 |
| display_name | TEXT | 显示名称 |
| phone | TEXT | 手机号（加密存储） |
| company_id | UUID (FK) | 所属公司 |
| is_master | BOOLEAN | 是否主账号 |
| master_id | UUID (FK) | 主账号ID（子账号使用） |
| created_at | TIMESTAMPTZ | 创建时间 |

#### 2.2.3 production_plans - 生产计划表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID (PK) | 计划ID |
| plan_code | TEXT (UNIQUE) | 系统自动生成计划唯一识别码 |
| product_name | TEXT | 成品名称 |
| color | TEXT | 颜色 |
| fabric_code | TEXT | 坯布唯一识别码（纯字母） |
| color_code | TEXT | 色号（数字排序） |
| remark | TEXT | 备注 |
| purchaser_id | UUID (FK) | 采购商公司ID |
| target_quantity | INTEGER | 计划产量（米） |
| completed_quantity | INTEGER | 已完成产量（米） |
| yarn_usage_per_meter | DECIMAL | 每米布纱用量(g/m) |
| production_price | DECIMAL | 生产采购价（元/米） |
| status | plan_status | 状态：pending/producing/completed |
| start_time | TIMESTAMPTZ | 计划开始时间 |
| created_by | UUID (FK) | 创建人 |
| created_at | TIMESTAMPTZ | 创建时间 |
| updated_at | TIMESTAMPTZ | 更新时间 |

#### 2.2.4 plan_process_steps - 计划流程节点表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID (PK) | 节点ID |
| plan_id | UUID (FK) | 计划ID |
| step_type | step_type | 节点类型：confirm/yarn_purchase/dyeing/machine_start/fabric_warehouse |
| status | step_status | 状态：pending/active/completed |
| timestamp | TIMESTAMPTZ | 确认时间戳 |
| operator_id | UUID (FK) | 操作人 |
| notes | TEXT | 备注 |
| created_at | TIMESTAMPTZ | 创建时间 |

### 2.3 自定义枚举类型

```sql
-- 应用角色（公司类型）
CREATE TYPE app_role AS ENUM ('purchaser', 'textile', 'washing');

-- 工厂类型
CREATE TYPE factory_type AS ENUM ('textile', 'washing');

-- 计划状态
CREATE TYPE plan_status AS ENUM ('pending', 'producing', 'completed');

-- 流程节点类型
CREATE TYPE step_type AS ENUM ('confirm', 'yarn_purchase', 'dyeing', 'machine_start', 'fabric_warehouse');

-- 流程节点状态
CREATE TYPE step_status AS ENUM ('pending', 'active', 'completed');

-- 仓库类型
CREATE TYPE warehouse_type AS ENUM ('raw_fabric', 'fabric', 'finished', 'yarn');

-- 结款状态
CREATE TYPE payment_status AS ENUM ('pending', 'completed');
```

### 2.4 RLS安全策略

所有表启用Row Level Security (RLS)，基于公司ID进行数据隔离：

```sql
-- 示例：production_plans表RLS策略
CREATE POLICY company_select_plans ON production_plans
  FOR SELECT USING (purchaser_id = get_user_master_company_id());

CREATE POLICY company_insert_plans ON production_plans
  FOR INSERT WITH CHECK (purchaser_id = get_user_master_company_id());

CREATE POLICY company_update_plans ON production_plans
  FOR UPDATE USING (purchaser_id = get_user_master_company_id());

CREATE POLICY company_delete_plans ON production_plans
  FOR DELETE USING (purchaser_id = get_user_master_company_id());
```

---

## 第三章 接口设计

### 3.1 认证接口

| 接口 | 方法 | 说明 |
|------|------|------|
| /auth/v1/token | POST | 用户登录 |
| /auth/v1/signup | POST | 用户注册 |
| /auth/v1/logout | POST | 用户退出 |
| /auth/v1/refresh | POST | 刷新Token |

### 3.2 数据接口

基于Supabase自动生成的RESTful API：

| 资源 | 操作 | 接口示例 |
|------|------|----------|
| production_plans | CRUD | /rest/v1/production_plans |
| companies | CRUD | /rest/v1/companies |
| profiles | CRUD | /rest/v1/profiles |
| inventory_records | CRUD | /rest/v1/inventory_records |
| plan_process_steps | CRUD | /rest/v1/plan_process_steps |

### 3.3 实时订阅

使用Supabase Realtime进行数据实时同步：

```typescript
supabase
  .channel('inventory_changes')
  .on('postgres_changes', {
    event: '*',
    schema: 'public',
    table: 'inventory_records'
  }, callback)
  .subscribe();
```

---

## 第四章 安全设计

### 4.1 数据安全

**加密存储**：
- 手机号使用XOR加密存储
- 敏感数据加密传输（HTTPS）

**访问控制**：
- 基于角色的访问控制（RBAC）
- 行级安全策略（RLS）
- 公司数据隔离

### 4.2 认证安全

- JWT Token认证
- Token自动刷新
- Session持久化
- 虚拟邮箱格式保护隐私

### 4.3 分享安全

- 分享链接使用Base64 + 盐值混淆加密
- 链接不包含敏感信息
- 导入页面隐藏成品名称、颜色等敏感字段

---

## 第五章 部署架构

### 5.1 部署环境

**云服务**：Meoo Cloud (Supabase)
- 托管数据库
- 托管认证服务
- 托管实时服务

**前端部署**：
- 静态资源托管
- CDN加速
- HTTPS安全传输

### 5.2 构建配置

**开发环境**：
```bash
pnpm run dev      # 启动开发服务器
pnpm run build    # 构建生产版本
```

**生产构建**：
- Webpack 5优化打包
- 代码分割
- Tree Shaking
- 资源压缩

---

## 第六章 技术选型说明

### 6.1 前端技术选型

| 技术 | 版本 | 选型理由 |
|------|------|----------|
| React | 18.2.0 | 组件化开发，生态丰富 |
| TypeScript | 5.3.3 | 类型安全，提升开发效率 |
| TailwindCSS | 3.3.5 | 原子化CSS，快速开发 |
| Framer Motion | 11.16.1 | 流畅动画，用户体验好 |
| React Router | 6.8.0 | 声明式路由，易于管理 |
| Zustand | 4.4.7 | 轻量状态管理，简单易用 |

### 6.2 后端技术选型

| 技术 | 版本 | 选型理由 |
|------|------|----------|
| PostgreSQL | 15+ | 关系型数据库，支持复杂查询 |
| Supabase | 2.98.0 | 开源Firebase替代，功能完整 |
| Row Level Security | - | 行级安全，数据隔离 |

### 6.3 开发工具选型

| 工具 | 版本 | 用途 |
|------|------|------|
| Webpack | 5.89.0 | 模块打包 |
| Babel | 7.23.5 | JavaScript编译 |
| Jest | 29.7.0 | 单元测试 |
| Playwright | 1.40.0 | E2E测试 |
| pnpm | 8+ | 包管理 |

---

## 附录

### A. 数据库迁移脚本

```sql
-- 创建公司表
CREATE TABLE companies (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  role app_role NOT NULL,
  address TEXT,
  contact_phone TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 创建用户配置表
CREATE TABLE profiles (
  id UUID PRIMARY KEY REFERENCES auth.users(id),
  username TEXT UNIQUE NOT NULL,
  display_name TEXT,
  phone TEXT,
  company_id UUID REFERENCES companies(id),
  is_master BOOLEAN DEFAULT false,
  master_id UUID REFERENCES auth.users(id),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 启用RLS
ALTER TABLE companies ENABLE ROW LEVEL SECURITY;
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
```

### B. 技术架构图

```
┌────────────────────────────────────────────────────────────┐
│                         前端层                              │
│  React 18 + TypeScript + TailwindCSS + Framer Motion      │
└────────────────────────────────────────────────────────────┘
                              │
                              ▼ HTTP/HTTPS
┌────────────────────────────────────────────────────────────┐
│                      API网关层                             │
│              Supabase REST API / Realtime                 │
└────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────┐
│                      数据层                                │
│  PostgreSQL + Row Level Security + Realtime Subscription  │
└────────────────────────────────────────────────────────────┘
```

---

**文档版本**：V1.0.0  
**最后更新**：2025年05月  
**编制单位**：[您的单位名称]

---

*本说明书版权归软件著作权人所有，未经许可不得复制、传播。*