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 架构图

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版本所需的核心数据表结构。

-- 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