9.18王德鹏/1

doc/database_documentation.md

@@ -192,7 +192,6 @@
 | user_id | BIGINT UNSIGNED | NOT NULL |  |  |
 | purchase_price | DECIMAL(18,2) | NOT NULL | 0.00 |  |
 | retail_price | DECIMAL(18,2) | NOT NULL | 0.00 |  |
-| distribution_price | DECIMAL(18,2) | NOT NULL | 0.00 |  |
 | wholesale_price | DECIMAL(18,2) | NOT NULL | 0.00 |  |
 | big_client_price | DECIMAL(18,2) | NOT NULL | 0.00 |  |
 | updated_at | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP |  |
@@ -308,7 +307,7 @@
 | supplier_id | BIGINT UNSIGNED | YES |  |  |
 | order_no | VARCHAR(32) | NOT NULL |  |  |
 | order_time | DATETIME | NOT NULL |  |  |
-| status | ENUM('draft','approved','void') | NOT NULL | draft |  |
+| status | ENUM('draft','approved','void','returned') | NOT NULL | draft |  |
 | amount | DECIMAL(18,2) | NOT NULL | 0.00 | 应付合计 |
 | paid_amount | DECIMAL(18,2) | NOT NULL | 0.00 | 已付合计 |
 | remark | VARCHAR(255) | YES |  |  |
@@ -399,6 +398,25 @@
 **Indexes**: - PRIMARY KEY: `id` - KEY: `idx_notices_shop` (`shop_id`,`status`,`is_pinned`,`created_at`) - KEY: `idx_notices_time` (`starts_at`,`ends_at`)
 **Foreign Keys**: - `fk_notices_shop`: `shop_id` → `shops(id)` ON UPDATE NO ACTION ON DELETE NO ACTION - `fk_notices_user`: `user_id` → `users(id)` ON UPDATE NO ACTION ON DELETE NO ACTION
 
+### inventory_movements
+| Column Name | Data Type | Nullable | Default | Comment |
+| ----------- | --------- | -------- | ------- | ------- |
+| id | BIGINT UNSIGNED | NOT NULL | AUTO_INCREMENT |  |
+| shop_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| user_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| product_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| source_type | VARCHAR(32) | NOT NULL |  | sale/purchase/sale_return/purchase_return/adjust |
+| source_id | BIGINT UNSIGNED | YES |  | 关联单据ID |
+| qty_delta | DECIMAL(18,3) | NOT NULL |  | 数量增减（正加负减） |
+| amount_delta | DECIMAL(18,2) | YES |  | 金额变动（可空） |
+| reason | VARCHAR(64) | YES |  |  |
+| tx_time | DATETIME | NOT NULL |  |  |
+| remark | VARCHAR(255) | YES |  |  |
+| created_at | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP |  |
+
+**Indexes**: - PRIMARY KEY: `id` - KEY: `idx_im_shop_time` (`shop_id`,`tx_time`) - KEY: `idx_im_product` (`product_id`)
+**Foreign Keys**: - `fk_im_shop`: `shop_id` → `shops(id)` - `fk_im_user`: `user_id` → `users(id)` - `fk_im_product`: `product_id` → `products(id)`
+
 ### 附：演示种子数据（非完整，仅用于联调验证）
 - 演示店铺：演示店A（用户 3，全部店长 owner）
 - 商品域：基础单位3条、类别2条、全局SKU2条、商品2条（含别名/价格/库存/图片）
@@ -406,3 +424,70 @@
 - 单据：销售单1（含明细2）与进货单1（含明细2）、收付款各1、其他收支2
 - 审核与公告：part_submissions 1、attachments 1、notices 2、新增 wechat 身份与会话各1
 
+### sales_return_orders
+| Column Name | Data Type | Nullable | Default | Comment |
+| ----------- | --------- | -------- | ------- | ------- |
+| id | BIGINT UNSIGNED | NOT NULL | AUTO_INCREMENT |  |
+| shop_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| user_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| customer_id | BIGINT UNSIGNED | YES |  |  |
+| order_no | VARCHAR(32) | NOT NULL |  |  |
+| order_time | DATETIME | NOT NULL |  |  |
+| status | ENUM('approved','void') | NOT NULL | approved |  |
+| amount | DECIMAL(18,2) | NOT NULL | 0.00 |  |
+| paid_amount | DECIMAL(18,2) | NOT NULL | 0.00 |  |
+| remark | VARCHAR(255) | YES |  |  |
+| created_at | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP |  |
+| updated_at | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP |  |
+| deleted_at | DATETIME | YES |  |  |
+
+**Indexes**: - PRIMARY KEY: `id` - UNIQUE: `ux_sr_order_no` (`shop_id`,`order_no`) - KEY: `idx_sr_shop_time` (`shop_id`,`order_time`)
+**Foreign Keys**: - `fk_sr_shop`: `shop_id` → `shops(id)` - `fk_sr_user`: `user_id` → `users(id)` - `fk_sr_customer`: `customer_id` → `customers(id)`
+
+### sales_return_order_items
+| Column Name | Data Type | Nullable | Default | Comment |
+| ----------- | --------- | -------- | ------- | ------- |
+| id | BIGINT UNSIGNED | NOT NULL | AUTO_INCREMENT |  |
+| order_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| product_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| quantity | DECIMAL(18,3) | NOT NULL |  |  |
+| unit_price | DECIMAL(18,2) | NOT NULL |  |  |
+| discount_rate | DECIMAL(5,2) | NOT NULL | 0.00 |  |
+| amount | DECIMAL(18,2) | NOT NULL |  |  |
+
+**Indexes**: - PRIMARY KEY: `id` - KEY: `idx_sroi_order` (`order_id`) - KEY: `idx_sroi_product` (`product_id`)
+**Foreign Keys**: - `fk_sroi_order`: `order_id` → `sales_return_orders(id)` ON DELETE CASCADE - `fk_sroi_product`: `product_id` → `products(id)`
+
+### purchase_return_orders
+| Column Name | Data Type | Nullable | Default | Comment |
+| ----------- | --------- | -------- | ------- | ------- |
+| id | BIGINT UNSIGNED | NOT NULL | AUTO_INCREMENT |  |
+| shop_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| user_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| supplier_id | BIGINT UNSIGNED | YES |  |  |
+| order_no | VARCHAR(32) | NOT NULL |  |  |
+| order_time | DATETIME | NOT NULL |  |  |
+| status | ENUM('approved','void') | NOT NULL | approved |  |
+| amount | DECIMAL(18,2) | NOT NULL | 0.00 |  |
+| paid_amount | DECIMAL(18,2) | NOT NULL | 0.00 |  |
+| remark | VARCHAR(255) | YES |  |  |
+| created_at | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP |  |
+| updated_at | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP |  |
+| deleted_at | DATETIME | YES |  |  |
+
+**Indexes**: - PRIMARY KEY: `id` - UNIQUE: `ux_pr_order_no` (`shop_id`,`order_no`) - KEY: `idx_pr_shop_time` (`shop_id`,`order_time`)
+**Foreign Keys**: - `fk_pr_shop`: `shop_id` → `shops(id)` - `fk_pr_user`: `user_id` → `users(id)` - `fk_pr_supplier`: `supplier_id` → `suppliers(id)`
+
+### purchase_return_order_items
+| Column Name | Data Type | Nullable | Default | Comment |
+| ----------- | --------- | -------- | ------- | ------- |
+| id | BIGINT UNSIGNED | NOT NULL | AUTO_INCREMENT |  |
+| order_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| product_id | BIGINT UNSIGNED | NOT NULL |  |  |
+| quantity | DECIMAL(18,3) | NOT NULL |  |  |
+| unit_price | DECIMAL(18,2) | NOT NULL |  |  |
+| amount | DECIMAL(18,2) | NOT NULL |  |  |
+
+**Indexes**: - PRIMARY KEY: `id` - KEY: `idx_proi_order` (`order_id`) - KEY: `idx_proi_product` (`product_id`)
+**Foreign Keys**: - `fk_proi_order`: `order_id` → `purchase_return_orders(id)` ON DELETE CASCADE - `fk_proi_product`: `product_id` → `products(id)`
+

doc/openapi.yaml

@@ -370,8 +370,8 @@ paths:
                           $ref: '#/components/schemas/Customer'
   /api/orders:
     post:
-      summary: 新建单据（❌ Partially Implemented）
-      description: 前端开单页已提交 payload，后端待实现。
+      summary: 新建单据（✅ Fully Implemented）
+      description: 销售/进货出入库与退货：保存即 approved；后端重算金额并联动库存。
       requestBody:
         required: true
         content:
@@ -391,6 +391,224 @@ paths:
                     format: int64
                   orderNo:
                     type: string
+  /api/orders:
+    get:
+      summary: 单据列表查询（❌ Partially Implemented）
+      description: 支持按时间范围与关键字筛选；参数 biz=sale|purchase，type=out|in|return；返回 {list:[]}。
+      parameters:
+        - in: query
+          name: biz
+          schema: { type: string }
+        - in: query
+          name: type
+          schema: { type: string }
+        - in: query
+          name: kw
+          schema: { type: string }
+        - in: query
+          name: page
+          schema: { type: integer, default: 1 }
+        - in: query
+          name: size
+          schema: { type: integer, default: 20 }
+        - in: query
+          name: startDate
+          schema: { type: string, format: date }
+        - in: query
+          name: endDate
+          schema: { type: string, format: date }
+  /api/payments/{biz}:
+    post:
+      summary: 创建收款/付款（✅ Fully Implemented）
+      description: biz=sale|purchase；根据 payments 写入多条记录，可选挂单并累加订单已付金额。
+      parameters:
+        - in: path
+          name: biz
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: '#/components/schemas/PaymentItem'
+      responses:
+        '200':
+          description: 成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  paymentIds:
+                    type: array
+                    items: { type: integer, format: int64 }
+      description: 支持按时间范围与关键字筛选；返回 {list:[]}。前端已接入，后端待实现。
+      parameters:
+        - in: query
+          name: kw
+          schema: { type: string }
+        - in: query
+          name: page
+          schema: { type: integer, default: 1 }
+        - in: query
+          name: size
+          schema: { type: integer, default: 20 }
+        - in: query
+          name: startDate
+          schema: { type: string, format: date }
+        - in: query
+          name: endDate
+          schema: { type: string, format: date }
+      responses:
+        '200':
+          description: 成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  list:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id: { type: integer, format: int64 }
+                        orderNo: { type: string }
+                        orderTime: { type: string, format: date-time }
+                        amount: { type: number }
+                        customerName: { type: string }
+
+  /api/purchase-orders:
+    get:
+      summary: 进货单列表查询（❌ Partially Implemented）
+      parameters:
+        - in: query
+          name: kw
+          schema: { type: string }
+        - in: query
+          name: page
+          schema: { type: integer, default: 1 }
+        - in: query
+          name: size
+          schema: { type: integer, default: 20 }
+        - in: query
+          name: startDate
+          schema: { type: string, format: date }
+        - in: query
+          name: endDate
+          schema: { type: string, format: date }
+        - in: query
+          name: status
+          schema:
+            type: string
+            enum: [draft, approved, void, returned]
+      responses:
+        '200':
+          description: 成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  list:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id: { type: integer, format: int64 }
+                        orderNo: { type: string }
+                        orderTime: { type: string, format: date-time }
+                        amount: { type: number }
+                        supplierName: { type: string }
+
+  /api/payments:
+    get:
+      summary: 收付款流水列表（❌ Partially Implemented）
+      parameters:
+        - in: query
+          name: kw
+          schema: { type: string }
+        - in: query
+          name: page
+          schema: { type: integer, default: 1 }
+        - in: query
+          name: size
+          schema: { type: integer, default: 20 }
+        - in: query
+          name: startDate
+          schema: { type: string, format: date }
+        - in: query
+          name: endDate
+          schema: { type: string, format: date }
+      responses:
+        '200':
+          description: 成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  list:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id: { type: integer, format: int64 }
+                        bizType: { type: string }
+                        direction: { type: string }
+                        payTime: { type: string, format: date-time }
+                        amount: { type: number }
+                        accountName: { type: string }
+
+  /api/inventories/logs:
+    get:
+      summary: 库存/盘点流水列表（❌ Partially Implemented）
+      parameters:
+        - in: query
+          name: kw
+          schema: { type: string }
+        - in: query
+          name: page
+          schema: { type: integer, default: 1 }
+        - in: query
+          name: size
+          schema: { type: integer, default: 20 }
+        - in: query
+          name: startDate
+          schema: { type: string, format: date }
+        - in: query
+          name: endDate
+          schema: { type: string, format: date }
+        - in: query
+          name: productId
+          schema: { type: integer, format: int64 }
+        - in: query
+          name: reason
+          schema: { type: string }
+      responses:
+        '200':
+          description: 成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  list:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id: { type: integer, format: int64 }
+                        bizType: { type: string }
+                        txTime: { type: string, format: date-time }
+                        amount: { type: number }
+                        remark: { type: string }
+                        productId: { type: integer, format: int64 }
+                        qtyDelta: { type: number }
+                        amountDelta: { type: number, nullable: true }
   /api/attachments:
     post:
       summary: 上传附件（✅ Fully Implemented，占位图方案）
@@ -633,14 +851,18 @@ components:
       properties:
         type:
           type: string
-          description: 'sale.out/sale.return/sale.collect/purchase/income/expense 等'
+          description: 'sale.out/sale.return/sale.collect/purchase.in/purchase.return/purchase.pay'
         orderTime:
           type: string
-          format: date
+          format: date-time
         customerId:
           type: integer
           format: int64
           nullable: true
+        supplierId:
+          type: integer
+          format: int64
+          nullable: true
         items:
           type: array
           items:
@@ -653,6 +875,18 @@ components:
                 type: number
               unitPrice:
                 type: number
+              discountRate:
+                type: number
         amount:
           type: number
+        payments:
+          type: array
+          items:
+            $ref: '#/components/schemas/PaymentItem'
+    PaymentItem:
+      type: object
+      properties:
+        method: { type: string, enum: [cash, bank, wechat] }
+        amount: { type: number }
+        orderId: { type: integer, format: int64, nullable: true }