opencode/yao
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #1149 from trheyi/main

Browse source 
Refactor user management API documentation and routing structure
This commit is contained in:
Max 2025-09-17 09:56:06 +08:00 • committed by GitHub
commit c4a1f7040b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 108 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
openapi/user/README.md
View file

@ -78,16 +78,16 @@ This module provides comprehensive user management APIs including authentication
| DELETE | `/user/api-keys/:key_id` | Required | Delete API key | | DELETE | `/user/api-keys/:key_id` | Required | Delete API key |
| POST | `/user/api-keys/:key_id/regenerate` | Required | Regenerate API key | | POST | `/user/api-keys/:key_id/regenerate` | Required | Regenerate API key |
### Balance & Credits ### Credits & Top-up
| Method | Endpoint | Auth | Description | | Method | Endpoint | Auth | Description |
| ------ | ------------------------------- | -------- | -------------------------- | | ------ | ------------------------------- | -------- | -------------------------- |
| GET | `/user/balance` | Required | Get user balance info | | GET | `/user/credits` | Required | Get user credits info |
| GET | `/user/balance/history` | Required | Get balance change history | | GET | `/user/credits/history` | Required | Get credits change history |
| GET | `/user/balance/topup` | Required | Get topup records | | GET | `/user/credits/topup` | Required | Get topup records |
| POST | `/user/balance/topup` | Required | Create topup order | | POST | `/user/credits/topup` | Required | Create topup order |
| GET | `/user/balance/topup/:order_id` | Required | Get topup order status | | GET | `/user/credits/topup/:order_id` | Required | Get topup order status |
| POST | `/user/balance/topup/card-code` | Required | Redeem card code | | POST | `/user/credits/topup/card-code` | Required | Redeem card code |
### Subscription Management ### Subscription Management
@ -106,33 +106,61 @@ This module provides comprehensive user management APIs including authentication
### Billing & Invoices ### Billing & Invoices
| Method | Endpoint | Auth | Description | | Method | Endpoint | Auth | Description |
| ------ | ----------------------- | -------- | --------------------------- | | ------ | ------------------------ | -------- | ------------------------ |
| PUT | `/user/billing/history` | Required | Update user billing history | | GET | `/user/billing/history` | Required | Get user billing history |
| GET | `/user/billing/invoices` | Required | Get user invoices list |
### Referral & Invitations ### Referral & Invitations
| Method | Endpoint | Auth | Description | | Method | Endpoint | Auth | Description |
| ------ | -------------------------- | -------- | --------------------------- | | ------ | ---------------------------- | -------- | ----------------------------- |
| GET | `/user/invite/code` | Required | Get user invite code | | GET | `/user/referral/code` | Required | Get user referral code |
| GET | `/user/invite/statistics` | Required | Get user invite statistics | | GET | `/user/referral/statistics` | Required | Get user referral statistics |
| GET | `/user/invite/history` | Required | Get user invite history | | GET | `/user/referral/history` | Required | Get user referral history |
| GET | `/user/invite/commissions` | Required | Get user invite commissions | | GET | `/user/referral/commissions` | Required | Get user referral commissions |
### Team Management ### Team Management
#### Team CRUD
| Method | Endpoint | Auth | Description | | Method | Endpoint | Auth | Description |
| ------ | ----------------------------------------- | -------- | ---------------------------- | | ------ | ---------------------- | -------- | --------------------- |
| GET | `/user/teams` | Required | Get user teams | | GET | `/user/teams` | Required | Get user teams |
| POST | `/user/teams` | Required | Create user team | | POST | `/user/teams` | Required | Create user team |
| GET | `/user/teams/:team_id` | Required | Get user team details | | GET | `/user/teams/:team_id` | Required | Get user team details |
| PUT | `/user/teams/:team_id` | Required | Update user team | | PUT | `/user/teams/:team_id` | Required | Update user team |
| DELETE | `/user/teams/:team_id` | Required | Delete user team | | DELETE | `/user/teams/:team_id` | Required | Delete user team |
#### Member Management
| Method | Endpoint | Auth | Description |
| ------ | ----------------------------------------- | -------- | --------------------------------- |
| GET | `/user/teams/:team_id/members` | Required | Get user team members | | GET | `/user/teams/:team_id/members` | Required | Get user team members |
| GET | `/user/teams/:team_id/members/:member_id` | Required | Get user team member details | | GET | `/user/teams/:team_id/members/:member_id` | Required | Get user team member details |
| POST | `/user/teams/:team_id/members/:type` | Required | Create user team member | | POST | `/user/teams/:team_id/members/direct` | Required | Add member directly (bots/system) |
| PUT | `/user/teams/:team_id/members/:member_id` | Required | Update user team member | | PUT | `/user/teams/:team_id/members/:member_id` | Required | Update user team member |
| DELETE | `/user/teams/:team_id/members/:member_id` | Required | Remove user team member | | DELETE | `/user/teams/:team_id/members/:member_id` | Required | Remove user team member |
#### Team Invitations
| Method | Endpoint | Auth | Description |
| ------ | -------------------------------------------------------- | -------- | ---------------------- |
| POST | `/user/teams/:team_id/invitations` | Required | Send team invitation |
| GET | `/user/teams/:team_id/invitations` | Required | Get team invitations |
| GET | `/user/teams/:team_id/invitations/:invitation_id` | Required | Get invitation details |
| PUT | `/user/teams/:team_id/invitations/:invitation_id/resend` | Required | Resend invitation |
| DELETE | `/user/teams/:team_id/invitations/:invitation_id` | Required | Cancel invitation |
### Invitation Response (Cross-module)
_Universal invitation response endpoints that handle invitations from any module (teams, organizations, etc.)_
| Method | Endpoint | Auth | Description |
| ------ | ---------------------------------- | -------- | ---------------------------- |
| GET | `/user/invitations/:token` | Public | Get invitation info by token |
| POST | `/user/invitations/:token/accept` | Required | Accept invitation |
| POST | `/user/invitations/:token/decline` | Public | Decline invitation |
### User Preferences ### User Preferences
| Method | Endpoint | Auth | Description | | Method | Endpoint | Auth | Description |
@ -170,3 +198,17 @@ This module provides comprehensive user management APIs including authentication
- Rate limiting may apply to sensitive operations (password reset, verification codes) - Rate limiting may apply to sensitive operations (password reset, verification codes)
- This module is designed to eventually replace the `signin` module - This module is designed to eventually replace the `signin` module
- OAuth callbacks support both GET (Google, GitHub) and POST (Apple, WeChat) methods - OAuth callbacks support both GET (Google, GitHub) and POST (Apple, WeChat) methods
## Architecture
### Modular Design
- **Team Management**: Handles team CRUD, member management, and invitation sending
- **Invitation Response**: Universal cross-module invitation handling (accept/decline)
- **Dual Member Addition**: Supports both direct addition (bots/system) and invitation flow (users)
### Invitation Flow
1. **Send Invitation**: `POST /user/teams/:team_id/invitations`
2. **Manage Invitations**: View, resend, or cancel via team-specific endpoints
3. **Respond to Invitation**: Universal endpoints handle acceptance/decline regardless of source module

57
openapi/user/user.go
View file

@ -22,13 +22,14 @@ func Attach(group *gin.RouterGroup, oauth types.OAuth) {
attachAccount(group, oauth) // Account settings attachAccount(group, oauth) // Account settings
attachThirdParty(group, oauth) // Third party login attachThirdParty(group, oauth) // Third party login
attachMFA(group, oauth) // MFA settings attachMFA(group, oauth) // MFA settings
attachBalance(group, oauth) // User balance management attachCredits(group, oauth) // User credits management
attachSubscription(group, oauth) // User subscription management attachSubscription(group, oauth) // User subscription management
attachAPIKeys(group, oauth) // User API keys management attachAPIKeys(group, oauth) // User API keys management
attachUsage(group, oauth) // User usage management attachUsage(group, oauth) // User usage management
attachBilling(group, oauth) // User billing management attachBilling(group, oauth) // User billing management
attachInvite(group, oauth) // User invite management attachReferral(group, oauth) // User referral management
attachTeam(group, oauth) // User team management attachTeam(group, oauth) // User team management
attachInvitations(group, oauth) // Invitation response management
attachPrivacy(group, oauth) // User privacy management attachPrivacy(group, oauth) // User privacy management
// User Management // User Management
@ -39,6 +40,8 @@ func Attach(group *gin.RouterGroup, oauth types.OAuth) {
func attachTeam(group *gin.RouterGroup, oauth types.OAuth) { func attachTeam(group *gin.RouterGroup, oauth types.OAuth) {
team := group.Group("/teams") team := group.Group("/teams")
team.Use(oauth.Guard) team.Use(oauth.Guard)
// Team CRUD
team.GET("/", placeholder) // Get user teams team.GET("/", placeholder) // Get user teams
team.GET("/:team_id", placeholder) // Get user team details team.GET("/:team_id", placeholder) // Get user team details
team.POST("/", placeholder) // Create user team team.POST("/", placeholder) // Create user team
@ -48,9 +51,24 @@ func attachTeam(group *gin.RouterGroup, oauth types.OAuth) {
// Member Management // Member Management
team.GET("/:team_id/members", placeholder) // Get user team members team.GET("/:team_id/members", placeholder) // Get user team members
team.GET("/:team_id/members/:member_id", placeholder) // Get user team member details team.GET("/:team_id/members/:member_id", placeholder) // Get user team member details
team.POST("/:team_id/members/:type", placeholder) // Create user team member team.POST("/:team_id/members/direct", placeholder) // Add member directly (for bots/system)
team.PUT("/:team_id/members/:member_id", placeholder) // Update user team member team.PUT("/:team_id/members/:member_id", placeholder) // Update user team member
team.DELETE("/:team_id/members/:member_id", placeholder) // Remove user team member team.DELETE("/:team_id/members/:member_id", placeholder) // Remove user team member
// Member Invitation Management
team.POST("/:team_id/invitations", placeholder) // Send team invitation
team.GET("/:team_id/invitations", placeholder) // Get team invitations
team.GET("/:team_id/invitations/:invitation_id", placeholder) // Get invitation details
team.PUT("/:team_id/invitations/:invitation_id/resend", placeholder) // Resend invitation
team.DELETE("/:team_id/invitations/:invitation_id", placeholder) // Cancel invitation
}
// Invitation Response Management (Cross-module invitation handling)
func attachInvitations(group *gin.RouterGroup, oauth types.OAuth) {
// Public endpoints for invitation recipients
group.GET("/invitations/:token", placeholder) // Get invitation info by token (public)
group.POST("/invitations/:token/accept", oauth.Guard, placeholder) // Accept invitation (requires login)
group.POST("/invitations/:token/decline", placeholder) // Decline invitation (public)
} }
// User Privacy // User Privacy
@ -76,30 +94,31 @@ func attachPreferences(group *gin.RouterGroup, oauth types.OAuth) {
func attachBilling(group *gin.RouterGroup, oauth types.OAuth) { func attachBilling(group *gin.RouterGroup, oauth types.OAuth) {
billing := group.Group("/billing") billing := group.Group("/billing")
billing.Use(oauth.Guard) billing.Use(oauth.Guard)
billing.PUT("/history", placeholder) // Update user billing history billing.GET("/history", placeholder) // Get user billing history
billing.GET("/invoices", placeholder) // Get user invoices list
} }
// Invite Management // Referral Management
func attachInvite(group *gin.RouterGroup, oauth types.OAuth) { func attachReferral(group *gin.RouterGroup, oauth types.OAuth) {
invite := group.Group("/invite") referral := group.Group("/referral")
invite.Use(oauth.Guard) referral.Use(oauth.Guard)
invite.GET("/code", placeholder) // Get user invite code referral.GET("/code", placeholder) // Get user referral code
invite.GET("/statistics", placeholder) // Get user invite statistics referral.GET("/statistics", placeholder) // Get user referral statistics
invite.GET("/history", placeholder) // Get user invite history referral.GET("/history", placeholder) // Get user referral history
invite.GET("/commissions", placeholder) // Get user invite commissions referral.GET("/commissions", placeholder) // Get user referral commissions
} }
// User Balance Management // User Credits Management
func attachBalance(group *gin.RouterGroup, oauth types.OAuth) { func attachCredits(group *gin.RouterGroup, oauth types.OAuth) {
balance := group.Group("/balance") credits := group.Group("/credits")
balance.Use(oauth.Guard) credits.Use(oauth.Guard)
balance.GET("/", placeholder) // Get user balance info credits.GET("/", placeholder) // Get user credits info
balance.GET("/history", placeholder) // Get balance change history credits.GET("/history", placeholder) // Get credits change history
// Top-up Management // Top-up Management
topup := balance.Group("/topup") topup := credits.Group("/topup")
topup.GET("/", placeholder) // Get topup records topup.GET("/", placeholder) // Get topup records
topup.POST("/", placeholder) // Create topup order topup.POST("/", placeholder) // Create topup order
topup.GET("/:order_id", placeholder) // Get topup order status topup.GET("/:order_id", placeholder) // Get topup order status