Initial commit

2025-11-18 03:36:49 +08:00
commit d17c7efb3c
7078 changed files with 831480 additions and 0 deletions
--- a/文档/UserBillService.md
+++ b/文档/UserBillService.md
@@ -0,0 +1,227 @@
+# UserBillService
+> 账单相关服务
+
+---
+
+## countAllUserBills
+> 计算所有账单数量
+
+- 角色：`admin`, `user`
+- HTTP：`POST https://backend.dooki.cloud/UserBillService/countAllUserBills`
+- RPC：`rpc countAllUserBills (CountAllUserBillsRequest) returns (RPCCountResponse);`
+
+**请求对象 (`CountAllUserBillsRequest`)**
+
+```json
+{
+  "paidFlag": "int32 // 可选，0|1|-1",
+  "userId": "int64 // 可选，用户ID",
+  "month": "string // 可选，月份",
+  "trafficRelated": "bool // 可选，是否为流量带宽相关",
+  "minDailyBillDays": "int32 // 可选，按日计费账单生成最小天数",
+  "minMonthlyBillDays": "int32 // 可选，按月计费账单生成最小天数"
+}
+```
+
+**响应对象 (`RPCCountResponse`)**
+
+```json
+{
+  "count": "int64 // 数量"
+}
+```
+
+**调用示例**
+
+```bash
+curl -X POST "https://backend.dooki.cloud/UserBillService/countAllUserBills" \
+  -H "Content-Type: application/json" \
+  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
+  -d '{
+    ...
+  }'
+```
+
+---
+
+## findUserBill
+> 查找账单信息
+
+- 角色：`admin`, `user`
+- HTTP：`POST https://backend.dooki.cloud/UserBillService/findUserBill`
+- RPC：`rpc findUserBill(FindUserBillRequest) returns (FindUserBillResponse);`
+
+**请求对象 (`FindUserBillRequest`)**
+
+```json
+{
+  "userBillId": "int64 // ID，和单号二选一",
+  "code": "string // 单号"
+}
+```
+
+**响应对象 (`FindUserBillResponse`)**
+
+```json
+{
+  "userBill": "UserBill"
+}
+```
+
+**调用示例**
+
+```bash
+curl -X POST "https://backend.dooki.cloud/UserBillService/findUserBill" \
+  -H "Content-Type: application/json" \
+  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
+  -d '{
+    ...
+  }'
+```
+
+---
+
+## generateAllUserBills
+> 手工生成账单
+
+- 角色：`admin`
+- HTTP：`POST https://backend.dooki.cloud/UserBillService/generateAllUserBills`
+- RPC：`rpc generateAllUserBills (GenerateAllUserBillsRequest) returns (RPCSuccess);`
+
+**请求对象 (`GenerateAllUserBillsRequest`)**
+
+```json
+{
+  "month": "string",
+  "day": "string"
+}
+```
+
+**响应对象 (`RPCSuccess`)**
+
+```json
+{}
+```
+
+**调用示例**
+
+```bash
+curl -X POST "https://backend.dooki.cloud/UserBillService/generateAllUserBills" \
+  -H "Content-Type: application/json" \
+  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
+  -d '{
+    ...
+  }'
+```
+
+---
+
+## listUserBills
+> 列出单页账单
+
+- 角色：`admin`, `user`
+- HTTP：`POST https://backend.dooki.cloud/UserBillService/listUserBills`
+- RPC：`rpc listUserBills (ListUserBillsRequest) returns (ListUserBillsResponse);`
+
+**请求对象 (`ListUserBillsRequest`)**
+
+```json
+{
+  "paidFlag": "int32",
+  "userId": "int64 // 用户ID",
+  "month": "string",
+  "offset": "int64 // 读取位置",
+  "size": "int64 // 数量，通常不能小于0"
+}
+```
+
+**响应对象 (`ListUserBillsResponse`)**
+
+```json
+{
+  "userBills": "[]UserBill"
+}
+```
+
+**调用示例**
+
+```bash
+curl -X POST "https://backend.dooki.cloud/UserBillService/listUserBills" \
+  -H "Content-Type: application/json" \
+  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
+  -d '{
+    ...
+  }'
+```
+
+---
+
+## payUserBill
+> 支付账单
+
+- 角色：`admin`, `user`
+- HTTP：`POST https://backend.dooki.cloud/UserBillService/payUserBill`
+- RPC：`rpc payUserBill(PayUserBillRequest) returns (RPCSuccess);`
+
+**请求对象 (`PayUserBillRequest`)**
+
+```json
+{
+  "userBillId": "int64"
+}
+```
+
+**响应对象 (`RPCSuccess`)**
+
+```json
+{}
+```
+
+**调用示例**
+
+```bash
+curl -X POST "https://backend.dooki.cloud/UserBillService/payUserBill" \
+  -H "Content-Type: application/json" \
+  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
+  -d '{
+    ...
+  }'
+```
+
+---
+
+## sumUserUnpaidBills
+> 计算用户所有未支付账单总额
+
+- 角色：`admin`, `user`
+- HTTP：`POST https://backend.dooki.cloud/UserBillService/sumUserUnpaidBills`
+- RPC：`rpc sumUserUnpaidBills(SumUserUnpaidBillsRequest) returns (SumUserUnpaidBillsResponse);`
+
+**请求对象 (`SumUserUnpaidBillsRequest`)**
+
+```json
+{
+  "userId": "int64 // 用户ID"
+}
+```
+
+**响应对象 (`SumUserUnpaidBillsResponse`)**
+
+```json
+{
+  "amount": "double"
+}
+```
+
+**调用示例**
+
+```bash
+curl -X POST "https://backend.dooki.cloud/UserBillService/sumUserUnpaidBills" \
+  -H "Content-Type: application/json" \
+  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
+  -d '{
+    ...
+  }'
+```
+
+---