LLHS/01_设计/初步设计文档.md

# 废品回收小程序 - 初步设计文档 V1.0

> **文档状态**: 评审中
> **版本**: 1.0
> **日期**: 2025-08-08
> **联合编制**:
> - **产品经理**: Sean
> - **项目经理**: Alex (PM)
> - **研发经理**: (待定)

---

## 0. 文档追踪

| **评审状态** | **评审人** | **评审日期** | **备注** |
| :--- | :--- | :--- | :--- |
| 初稿 | Sean | 2025-08-08 | - |
| 技术评审 | (待定) | (待定) | - |

---

## 1. 项目概述

### 1.1 项目背景与核心矛盾
本项目旨在通过O2O平台，连接社区居民、回收小站、物流及处理中心，解决传统废品回收流程中信息不对称、效率低下、体验差的痛点。

**核心矛盾**: 居民侧“便捷、透明地处理废品”的需求 与 传统回收行业“效率低下、信息不透明”的现状 之间的矛盾。本平台即为解决此矛盾的关键载体。

### 1.2 项目目标 (MVP V1.0)
- **业务目标**: 跑通“居民到小站”的核心商业模式闭环。
- **数据目标**: 在1-2个试点社区，实现每周100+笔交易，C端用户次月留存率达到30%。

---

## 2. MVP范围定义

为实现快速验证，MVP版本将聚焦于最核心的功能闭环。

- **C端 (居民端)**: 核心是“卖钱”。
  - **功能**: 微信一键登录、我的卖品码、我的余额、交易记录。
- **B端 (小站端)**: 核心是“收钱”。
  - **功能**: 账号登录、核心回收流程（扫码、录入、确认）、语音播报。
- **管理后台**: 核心是“能管”。
  - **功能**: 品类与价格管理、小站管理（用于创建账号）、基础订单流水查询。

### 2.1 MVP范围之外 (Out of Scope)
为确保核心价值的快速验证，以下在PRD中提及的功能将**不包含**在V1.0版本中：
- **C端提现功能**: V1.0用户余额仅作记录，V1.1实现提现。
- **物流端功能**: V1.0不包含物流角色和相关功能。
- **积分商城等增值服务**: 待核心模式验证后规划。

---

## 3. 技术架构设计

### 3.1 架构图

```mermaid
graph TD
    subgraph 用户端 (User Layer)
        C_MP[C端用户小程序<br>(uni-app / Vue.js)]
        Admin[管理后台Web<br>(Vue 3 + Element Plus)]
        Maintenance[运维端APP<br>(Flutter / React Native)]
    end

    subgraph 智能终端层 (Terminal Layer)
        Terminal1[智能终端设备#1<br>(嵌入式Linux + Qt)]
        Terminal2[智能终端设备#2<br>(嵌入式Linux + Qt)]
        TerminalN[智能终端设备#N<br>(嵌入式Linux + Qt)]
    end

    subgraph 网关层 (API Gateway)
        Gateway[API Gateway<br>(Nginx + Load Balancer)]
    end

    subgraph 后端服务 (Backend Service)
        Backend[后端应用服务器<br>(Node.js + NestJS)]
        AIService[AI识别服务<br>(Python + TensorFlow)]
        DeviceManager[设备管理服务<br>(MQTT Broker)]
    end

    subgraph 数据层 (Data Layer)
        DB[(PostgreSQL<br>核心业务数据)]
        Cache[(Redis<br>缓存/会话)]
        TimeSeries[(InfluxDB<br>设备时序数据)]
    end

    C_MP --> Gateway
    Admin --> Gateway
    Maintenance --> Gateway
    Terminal1 --> DeviceManager
    Terminal2 --> DeviceManager
    TerminalN --> DeviceManager
    Gateway --> Backend
    Backend --> AIService
    Backend --> DeviceManager
    Backend --> DB
    Backend --> Cache
    DeviceManager --> TimeSeries
    AIService --> Cache
```

### 3.2 技术选型理由
- **前端 (uni-app + Vue)**: 一次开发，多端发布，极大提升MVP开发效率，C端小程序和运维端APP统一技术栈。
- **智能终端 (嵌入式Linux + Qt)**: 稳定可靠的嵌入式系统，Qt提供良好的触屏界面开发体验，支持多媒体和网络通信。
- **后端 (Node.js + NestJS)**: 全栈语言统一（TypeScript），微服务架构清晰，适合处理高并发的设备连接。
- **AI服务 (Python + TensorFlow)**: 成熟的机器学习框架，支持物品识别模型的训练和推理。
- **设备通信 (MQTT)**: 轻量级物联网协议，适合终端设备与云端的实时通信。
- **数据库 (PostgreSQL + Redis + InfluxDB)**: PostgreSQL处理业务数据，Redis提供缓存和会话，InfluxDB专门存储设备时序数据。

### 3.3 风险评估与应对策略
- **硬件风险**:
  - **风险点**: 智能终端设备的硬件稳定性和恶劣环境适应性。
  - **应对策略**: 选择工业级硬件组件，进行充分的环境测试（高温、低温、湿度、振动）。
- **AI识别风险**:
  - **风险点**: 物品识别准确率可能达不到预期，影响用户体验。
  - **应对策略**: 建立持续学习机制，收集错误样本不断优化模型；设置人工审核机制作为兜底。
- **网络风险**:
  - **风险点**: 终端设备网络不稳定导致数据传输中断。
  - **应对策略**: 实现本地数据缓存机制，支持断网重连和数据补传。
- **成本风险**:
  - **风险点**: 单台设备成本超出3000元预算，影响盈利模式。
  - **应对策略**: 严格控制硬件BOM成本，探索批量采购降本，优化设计减少不必要功能。

---

## 4. 数据库设计

以下为MVP版本所需的核心数据表结构。

```sql
-- 1. C端居民用户表
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    wx_openid VARCHAR(255) UNIQUE NOT NULL,
    phone_number VARCHAR(20) UNIQUE,
    nickname VARCHAR(255),
    avatar_url TEXT,
    balance DECIMAL(10, 2) NOT NULL DEFAULT 0.00,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 2. 智能终端设备表
CREATE TABLE terminals (
    id SERIAL PRIMARY KEY,
    device_code VARCHAR(100) UNIQUE NOT NULL,
    name VARCHAR(255) NOT NULL,
    address TEXT NOT NULL,
    location GEOGRAPHY(POINT, 4326),
    venue_type VARCHAR(50) NOT NULL, -- supermarket, express_station, etc.
    venue_contact_name VARCHAR(100),
    venue_contact_phone VARCHAR(20),
    status VARCHAR(20) NOT NULL DEFAULT 'online', -- online, offline, maintenance, error
    hardware_version VARCHAR(50),
    software_version VARCHAR(50),
    deployment_cost DECIMAL(10, 2) DEFAULT 3000.00,
    deployment_date DATE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 3. 终端配置表
CREATE TABLE terminal_configs (
    id SERIAL PRIMARY KEY,
    terminal_id INT NOT NULL REFERENCES terminals(id),
    bag_count INT NOT NULL DEFAULT 3,
    max_weight_per_bag DECIMAL(10, 2) DEFAULT 50.00,
    ai_confidence_threshold DECIMAL(3, 2) DEFAULT 0.85,
    network_config JSONB,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 4. 回收物料品类表
CREATE TABLE categories (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) UNIQUE NOT NULL,
    code VARCHAR(20) UNIQUE NOT NULL, -- bottle, paper, textile
    unit VARCHAR(20) NOT NULL DEFAULT 'kg',
    ai_model_labels TEXT[], -- AI识别标签数组
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 5. 价格表
CREATE TABLE prices (
    id SERIAL PRIMARY KEY,
    category_id INT NOT NULL REFERENCES categories(id),
    terminal_id INT NOT NULL REFERENCES terminals(id),
    price DECIMAL(10, 2) NOT NULL,
    effective_date TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE(category_id, terminal_id)
);

-- 6. 交易记录总表
CREATE TABLE transactions (
    id SERIAL PRIMARY KEY,
    user_id INT NOT NULL REFERENCES users(id),
    terminal_id INT NOT NULL REFERENCES terminals(id),
    total_amount DECIMAL(10, 2) NOT NULL,
    payment_method VARCHAR(20) DEFAULT 'balance', -- balance, wechat_pay
    ai_confidence_score DECIMAL(3, 2),
    transaction_images TEXT[], -- 交易过程图片
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 7. 交易详情表
CREATE TABLE transaction_items (
    id SERIAL PRIMARY KEY,
    transaction_id INT NOT NULL REFERENCES transactions(id) ON DELETE CASCADE,
    category_id INT NOT NULL REFERENCES categories(id),
    bag_number INT NOT NULL, -- 投入的袋子编号
    weight DECIMAL(10, 2) NOT NULL,
    price_per_unit DECIMAL(10, 2) NOT NULL,
    amount DECIMAL(10, 2) NOT NULL,
    ai_identified_category VARCHAR(100), -- AI识别的品类
    ai_confidence DECIMAL(3, 2), -- AI置信度
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 8. 终端状态监控表
CREATE TABLE terminal_status (
    id SERIAL PRIMARY KEY,
    terminal_id INT NOT NULL REFERENCES terminals(id),
    cpu_usage DECIMAL(5, 2),
    memory_usage DECIMAL(5, 2),
    disk_usage DECIMAL(5, 2),
    network_status VARCHAR(20),
    temperature DECIMAL(5, 2),
    bag_weights JSONB, -- 各袋子当前重量 {"bag1": 25.5, "bag2": 30.2}
    error_codes VARCHAR(255)[],
    last_heartbeat TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 9. 设备维护记录表
CREATE TABLE maintenance_records (
    id SERIAL PRIMARY KEY,
    terminal_id INT NOT NULL REFERENCES terminals(id),
    maintenance_type VARCHAR(50) NOT NULL, -- routine, repair, emergency
    operator_name VARCHAR(100),
    operator_phone VARCHAR(20),
    description TEXT,
    before_images TEXT[],
    after_images TEXT[],
    cost DECIMAL(10, 2),
    status VARCHAR(20) DEFAULT 'completed', -- pending, in_progress, completed
    scheduled_at TIMESTAMPTZ,
    completed_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

---

## 5. 核心API接口设计

### 5.1 管理后台API (`/api/admin`)
- **终端管理**: `GET, POST, PUT /terminals/:id`
- **品类管理**: `GET, POST, PUT /categories/:id`
- **价格管理**: `GET, POST /prices`
- **维护管理**: `GET, POST /maintenance`
- **数据监控**: `GET /monitoring/dashboard`

### 5.2 C端小程序API (`/api/c`)
- **认证**: `POST /auth/login` (微信Code换JWT)
- **用户信息**: `GET /profile`
- **核心功能**:
  - `GET /features/prices` (今日回收价)
  - `GET /features/nearby-terminals` (附近终端)
  - `GET /features/transactions` (交易记录)
  - `GET /features/qrcode` (生成登录二维码)

### 5.3 智能终端设备API (`/api/terminal`)
- **设备认证**: `POST /auth/device` (设备注册登录)
- **用户识别**: `POST /user/identify` (二维码/手机号识别)
- **交易流程**:
  - `POST /transaction/start` (开始交易)
  - `POST /transaction/weigh` (称重数据上传)
  - `POST /transaction/ai-verify` (AI识别验证)
  - `POST /transaction/complete` (完成交易)
- **设备状态**:
  - `POST /status/heartbeat` (设备心跳)
  - `POST /status/error` (错误报告)
  - `GET /config` (获取设备配置)

### 5.4 运维端API (`/api/maintenance`)
- **认证**: `POST /auth/login` (运维人员登录)
- **任务管理**:
  - `GET /tasks` (获取维护任务)
  - `POST /tasks/:id/start` (开始任务)
  - `POST /tasks/:id/complete` (完成任务)
- **设备检测**:
  - `POST /device/:id/diagnose` (设备诊断)
  - `POST /device/:id/repair` (维修记录)

---

## 6. 项目排期与资源规划

### 6.1 总体排期 (估算)
项目采用敏捷开发模式，以**2个为期两周的Sprint**完成MVP版本的开发和测试，总计**4周**。

- **Sprint 1 (第一、二周)**:
  - **目标**: 完成后端核心API开发与前端基础架构。
  - **后端**: 完成所有后台、C端、B端的API开发与单元测试。
  - **前端**: 完成项目脚手架搭建，各端登录、核心页面UI布局。
  - **产出**: **所有后端API通过单元测试并提供Swagger文档**，前端完成核心页面UI框架搭建。

- **Sprint 2 (第三、四周)**:
  - **目标**: 完成前后端对接、联调测试与上线准备。
  - **前端**: 完成所有业务逻辑开发，与后端API全面对接。
  - **测试**: 执行端到端的核心流程测试用例，进行多轮Bug修复。
  - **产出**: 功能完备、**通过核心流程E2E测试**的MVP版本，可随时部署。

### 6.2 资源分配 (建议)
- **后端开发**: 1-2人
- **前端开发**: 1-2人 (uni-app, Vue)
- **测试(QA)**: 1人 (在Sprint 2后半段集中投入)
- **产品/项目**: 1人 (负责需求澄清、进度跟踪)

### 6.3 关键里程碑 (Milestones)

| **里程碑** | **预计完成日期** | **负责人** | **交付物** |
| :--- | :--- | :--- | :--- |
| M1: 项目启动与技术预研 | W1周三 | Alex | 项目计划、技术选型确认 |
| M2: 后端API开发完成 | W2周五 | 后端Leader | 可供调用的API文档 |
| M3: 前后端联调完成 | W4周三 | 前/后端Leader | 完成核心功能对接 |
| M4: MVP版本测试完成 | W4周五 | QA Leader | 测试报告 |
| M5: MVP正式上线 | W5周一 | Alex | 上线公告 |

### 6.4 沟通与协作
- **每日站会**: 每天上午10点，15分钟，同步进度、风险和阻塞点。
- **每周复盘与演示**: 每周五下午，复盘本周进展，并**进行功能演示**，规划下周计划。
- **协作工具**:
  - **任务管理**: Jira (或类似工具)
  - **即时沟通**: Slack / 钉钉
  - **文档中心**: Confluence / Git仓库Wiki