docs(architecture): consolidate domain protocols

src/data/repositories/payment_repository.ts

@@ -1,7 +1,7 @@
 /**
  * PaymentRepository
  *
- * 支付 / 付费墙相关远程调用。
+ * 统一封装默认套餐、Tip 套餐、订单创建和订单状态查询。
  */
 import type { IPaymentRepository } from "@/data/repositories/interfaces";
 import {

src/data/services/api/payment_api.ts

@@ -1,7 +1,7 @@
 /**
  * Payment API
  *
- * 付费墙 / 充值相关接口
+ * 套餐目录、订单创建与订单状态接口。
  */
 import {
   CreatePaymentOrderRequest,
@@ -20,9 +20,7 @@ import { httpClient } from "./http_client";
 import { ApiEnvelope, unwrap } from "./response_helper";
 
 export class PaymentApi {
-  /**
-   * 获取套餐列表
-   */
+  /** 获取 VIP 与 Top-up 套餐列表。 */
   async getPlans(): Promise<PaymentPlansResponse> {
     const env = await httpClient<ApiEnvelope<unknown>>(ApiPath.paymentPlans);
     return PaymentPlansResponseSchema.parse(
@@ -38,9 +36,7 @@ export class PaymentApi {
     );
   }
 
-  /**
-   * 创建支付订单
-   */
+  /** 创建 VIP、Top-up 或 Tip 订单。 */
   async createOrder(
     body: CreatePaymentOrderRequest,
   ): Promise<CreatePaymentOrderResponse> {
@@ -56,9 +52,7 @@ export class PaymentApi {
     );
   }
 
-  /**
-   * 查询支付订单状态
-   */
+  /** 查询订单最终支付状态。 */
   async getOrderStatus(orderId: string): Promise<PaymentOrderStatusResponse> {
     const env = await httpClient<ApiEnvelope<unknown>>(
       ApiPath.paymentOrderStatus,

src/stores/payment/payment-context.tsx

@@ -1,8 +1,6 @@
 "use client";
 
-/**
- * PaymentContext：基于 XState v5 的 React Context Provider
- */
+/** Route UI reads this projection instead of the Payment machine snapshot. */
 import type { Dispatch, ReactNode } from "react";
 import { createActorContext, shallowEqual } from "@xstate/react";
 import type { SnapshotFrom } from "xstate";

src/stores/payment/payment-events.ts

@@ -1,6 +1,4 @@
-/**
- * Payment 状态机：事件联合
- */
+/** Public events for one route-scoped Payment actor. */
 import type { PayChannel } from "@/data/schemas/payment";
 import type { PaymentPlanCatalog } from "./payment-state";
 

src/stores/payment/payment-state.ts

@@ -1,6 +1,4 @@
-/**
- * Payment 状态机：State 形状 + 初始值
- */
+/** Context shared by the default and Tip payment catalogs. */
 import type {
   PayChannel,
   PaymentOrderStatus,

src/stores/private-room/private-room-context.tsx

@@ -10,6 +10,7 @@ import type {
   PrivateRoomState as MachineContext,
 } from "./private-room-machine";
 
+/** Route UI reads this projection instead of the Private Room snapshot. */
 export interface PrivateRoomContextState {
   characterId: string;
   status: string;

src/stores/private-room/private-room-events.ts

@@ -1,3 +1,4 @@
+/** Public events for one character-scoped Private Room actor. */
 export type PrivateRoomEvent =
   | { type: "PrivateRoomInit" }
   | { type: "PrivateRoomRefresh" }