9.18/2

doc/database_documentation.md

@@ -218,16 +218,20 @@
 | shop_id | BIGINT UNSIGNED | NOT NULL |  |  |
 | user_id | BIGINT UNSIGNED | NOT NULL |  |  |
 | name | VARCHAR(120) | NOT NULL |  |  |
-| phone | VARCHAR(32) | YES |  |  |
+| phone | VARCHAR(32) | YES |  | 座机 |
+| address | VARCHAR(255) | YES |  | 送货地址 |
+| mobile | VARCHAR(32) | YES |  | 手机 |
 | level | VARCHAR(32) | YES |  | 客户等级标签 |
+| contact_name | VARCHAR(64) | YES |  | 联系人 |
 | price_level | ENUM('retail','distribution','wholesale','big_client') | NOT NULL | retail | 默认售价列 |
 | status | TINYINT UNSIGNED | NOT NULL | 1 |  |
+| ar_opening | 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` - KEY: `idx_customers_shop` (`shop_id`) - KEY: `idx_customers_phone` (`phone`)
+**Indexes**: - PRIMARY KEY: `id` - KEY: `idx_customers_shop` (`shop_id`) - KEY: `idx_customers_phone` (`phone`) - KEY: `idx_customers_mobile` (`mobile`)
 **Foreign Keys**: - `fk_customers_shop`: `shop_id` → `shops(id)` - `fk_customers_user`: `user_id` → `users(id)`
 
 ### suppliers

doc/openapi.yaml

@@ -335,13 +335,17 @@ paths:
                           $ref: '#/components/schemas/Product'
   /api/customers:
     get:
-      summary: 客户搜索（❌ Partially Implemented）
-      description: 前端已接入查询参数 kw/page/size，后端待实现或对齐。
+      summary: 客户搜索（✅ Fully Implemented）
+      description: 支持 kw/page/size/debtOnly；返回 {list:[]}，含动态计算的 receivable 字段。
       parameters:
         - in: query
           name: kw
           schema:
             type: string
+        - in: query
+          name: debtOnly
+          schema:
+            type: boolean
         - in: query
           name: page
           schema:
@@ -368,6 +372,17 @@ paths:
                         type: array
                         items:
                           $ref: '#/components/schemas/Customer'
+    post:
+      summary: 新建客户（✅ Fully Implemented）
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateCustomerRequest'
+      responses:
+        '200':
+          description: 成功
   /api/orders:
     post:
       summary: 新建单据（✅ Fully Implemented）
@@ -839,13 +854,27 @@ components:
     Customer:
       type: object
       properties:
-        id:
-          type: integer
-          format: int64
-        name:
-          type: string
-        mobile:
-          type: string
+        id: { type: integer, format: int64 }
+        name: { type: string }
+        contactName: { type: string }
+        mobile: { type: string }
+        phone: { type: string }
+        level: { type: string }
+        priceLevel: { type: string, enum: [retail, distribution, wholesale, big_client] }
+        remark: { type: string }
+        receivable: { type: number }
+    CreateCustomerRequest:
+      type: object
+      properties:
+        name: { type: string }
+        level: { type: string, nullable: true }
+        priceLevel: { type: string, enum: [retail, distribution, wholesale, big_client] }
+        contactName: { type: string, nullable: true }
+        mobile: { type: string, nullable: true }
+        phone: { type: string, nullable: true }
+        address: { type: string, nullable: true }
+        arOpening: { type: number, nullable: true }
+        remark: { type: string, nullable: true }
     CreateOrderRequest:
       type: object
       properties: