257 lines
9.5 KiB
Markdown
257 lines
9.5 KiB
Markdown
# 废品回收小程序 - 初步设计文档 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)]
|
||
B_MP[B端小站小程序<br>(uni-app / Vue.js)]
|
||
Admin[管理后台Web<br>(Vue 3 + Element Plus)]
|
||
end
|
||
|
||
subgraph 网关层 (API Gateway)
|
||
Gateway[API Gateway<br>(Nginx)]
|
||
end
|
||
|
||
subgraph 后端服务 (Backend Service)
|
||
Backend[后端应用服务器<br>(Node.js + NestJS)]
|
||
end
|
||
|
||
subgraph 数据层 (Data Layer)
|
||
DB[(PostgreSQL<br>核心业务数据)]
|
||
Cache[(Redis<br>缓存/会话)]
|
||
end
|
||
|
||
C_MP --> Gateway
|
||
B_MP --> Gateway
|
||
Admin --> Gateway
|
||
Gateway --> Backend
|
||
Backend --> DB
|
||
Backend --> Cache
|
||
```
|
||
|
||
### 3.2 技术选型理由
|
||
- **前端 (uni-app + Vue)**: 一次开发，多端发布，极大提升MVP开发效率，统一技术栈。
|
||
- **后端 (Node.js + NestJS)**: 全栈语言统一（TypeScript），架构清晰，适合企业级应用，保证代码质量和可维护性。
|
||
- **数据库 (PostgreSQL + Redis)**: PostgreSQL功能强大，满足地理位置查询等复杂需求；Redis作为缓存，保证系统响应速度。
|
||
|
||
### 3.3 风险评估与应对策略
|
||
- **技术风险**:
|
||
- **风险点**: `uni-app` 在部分低端安卓机型上可能存在性能瓶颈。
|
||
- **应对策略**: 在开发中期，选取核心页面（如扫码、列表）进行专项性能测试，预留优化时间。
|
||
- **团队风险**:
|
||
- **风险点**: 团队成员对 `NestJS` 或 `uni-app` 的熟练度可能不一。
|
||
- **应对策略**: 在项目启动前安排1-2天的技术预研（Spike），统一代码规范和最佳实践。
|
||
- **需求风险**:
|
||
- **风险点**: MVP开发期间出现重大需求变更，影响核心交付范围。
|
||
- **应对策略**: 建立需求变更控制流程。所有需求变更需经由产品、项目、研发三方共同评估影响后，再决定是否纳入当前版本。
|
||
|
||
---
|
||
|
||
## 4. 数据库设计
|
||
|
||
以下为MVP版本所需的核心数据表结构。
|
||
|
||
```sql
|
||
-- 1. C端居民用户表
|
||
CREATE TABLE users (
|
||
id SERIAL PRIMARY KEY,
|
||
wx_openid VARCHAR(255) UNIQUE NOT NULL,
|
||
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. B端回收小站表
|
||
CREATE TABLE stations (
|
||
id SERIAL PRIMARY KEY,
|
||
name VARCHAR(255) NOT NULL,
|
||
address TEXT NOT NULL,
|
||
location GEOGRAPHY(POINT, 4326),
|
||
manager_name VARCHAR(100),
|
||
phone_number VARCHAR(20),
|
||
status VARCHAR(20) NOT NULL DEFAULT 'active',
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 3. 小站员工表
|
||
CREATE TABLE staff (
|
||
id SERIAL PRIMARY KEY,
|
||
station_id INT NOT NULL REFERENCES stations(id),
|
||
phone_number VARCHAR(20) UNIQUE NOT NULL,
|
||
password_hash VARCHAR(255) NOT NULL,
|
||
role VARCHAR(50) NOT NULL DEFAULT 'staff',
|
||
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,
|
||
unit VARCHAR(20) NOT NULL DEFAULT 'kg',
|
||
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),
|
||
station_id INT NOT NULL REFERENCES stations(id),
|
||
price DECIMAL(10, 2) NOT NULL,
|
||
effective_date TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
UNIQUE(category_id, station_id)
|
||
);
|
||
|
||
-- 6. 交易记录总表
|
||
CREATE TABLE transactions (
|
||
id SERIAL PRIMARY KEY,
|
||
user_id INT NOT NULL REFERENCES users(id),
|
||
station_id INT NOT NULL REFERENCES stations(id),
|
||
staff_id INT NOT NULL REFERENCES staff(id),
|
||
total_amount DECIMAL(10, 2) NOT NULL,
|
||
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),
|
||
weight DECIMAL(10, 2) NOT NULL,
|
||
price_per_unit DECIMAL(10, 2) NOT NULL,
|
||
amount DECIMAL(10, 2) NOT NULL,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 核心API接口设计
|
||
|
||
### 5.1 管理后台API (`/api/admin`)
|
||
- **品类管理**: `GET, POST, PUT /categories/:id`
|
||
- **小站管理**: `GET, POST, PUT /stations/:id`
|
||
- **价格管理**: `GET, POST /prices`
|
||
- **员工管理**: `GET, POST /staff`
|
||
|
||
### 5.2 C端小程序API (`/api/c`)
|
||
- **认证**: `POST /auth/login` (微信Code换JWT)
|
||
- **用户信息**: `GET /profile`
|
||
- **核心功能**:
|
||
- `GET /features/prices` (今日回收价)
|
||
- `GET /features/nearby-stations` (附近小站)
|
||
- `GET /features/transactions` (交易记录)
|
||
|
||
### 5.3 B端小程序API (`/api/b`)
|
||
- **认证**: `POST /auth/login` (手机号密码登录)
|
||
- **回收流程**:
|
||
- `GET /recycle/user-info` (扫码识客)
|
||
- `POST /recycle/transactions` (创建交易)
|
||
- **数据查询**:
|
||
- `GET /data/summary` (今日汇总)
|
||
- `GET /data/inventory` (库存盘点)
|
||
- `GET /data/categories` (可用回收品类)
|
||
|
||
---
|
||
|
||
## 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
|