feat: add team member role for team-level permission control (#1023)

## Summary

Cherry-pick from #1021 (`feat/user-team-api` branch).

- Add `role` field (`owner` / `member`) to `TeamMember`, enabling
team-level permission control
- Team creator is auto-added as team owner; team write operations now
require **team owner**, org owner, or admin
- Add private API `GET /-/team/:org/:team/member` returning `[{user,
role}]`
- Add private API `PATCH /-/team/:org/:team/member/:username` for
updating member role
- Keep npm compatible endpoints unchanged
- Update docs (Chinese + English)
- SQL migration: `4.32.0.sql` adds `role` column to `team_members`

## Test plan

- [x] Run `npm run test:local
test/port/controller/TeamController/index.test.ts`
- [x] Run full test suite
- [x] Verify npm CLI commands still work unchanged

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Team members can now have assignable roles (owner or member)
controlling team permissions
* New API endpoints to view team member roles and update member
permissions
* Team creators automatically receive team owner status upon team
creation

* **Documentation**
* Added comprehensive guide to organization, team, and package
permission models with API endpoint reference

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

Author: elrrrrrrr

app/core/entity/TeamMember.ts

@@ -5,6 +5,7 @@ interface TeamMemberData extends EntityData {
   teamMemberId: string;
   teamId: string;
   userId: string;
+  role: string;
 }
 
 export type CreateTeamMemberData = Omit<EasyData<TeamMemberData, 'teamMemberId'>, 'id'>;
@@ -13,12 +14,14 @@ export class TeamMember extends Entity {
   teamMemberId: string;
   teamId: string;
   userId: string;
+  role: string;
 
   constructor(data: TeamMemberData) {
     super(data);
     this.teamMemberId = data.teamMemberId;
     this.teamId = data.teamId;
     this.userId = data.userId;
+    this.role = data.role || 'member';
   }
 
   static create(data: CreateTeamMemberData): TeamMember {

app/core/service/OrgService.ts

@@ -50,6 +50,7 @@ export class OrgService extends AbstractService {
     const teamMember = TeamMember.create({
       teamId: developersTeam.teamId,
       userId: cmd.creatorUserId,
+      role: 'owner',
     });
     await this.orgRepository.createOrgCascade(org, developersTeam, ownerMember, teamMember);
 
@@ -110,6 +111,7 @@ export class OrgService extends AbstractService {
         const teamMember = TeamMember.create({
           teamId: developersTeam.teamId,
           userId,
+          role: 'member',
         });
         await this.teamRepository.addMember(teamMember);
       }

app/core/service/TeamService.ts

@@ -19,7 +19,7 @@ export class TeamService extends AbstractService {
   @Inject()
   private readonly teamRepository: TeamRepository;
 
-  async createTeam(orgId: string, name: string, description?: string): Promise<Team> {
+  async createTeam(orgId: string, name: string, description?: string, creatorUserId?: string): Promise<Team> {
     const existing = await this.teamRepository.findTeam(orgId, name);
     if (existing) {
       throw new ForbiddenError(`Team "${name}" already exists`);
@@ -31,7 +31,20 @@ export class TeamService extends AbstractService {
       description,
     });
     await this.teamRepository.saveTeam(team);
-    this.logger.info('[TeamService:createTeam] teamId: %s, orgId: %s, name: %s', team.teamId, orgId, name);
+
+    // Auto-add creator as team owner
+    if (creatorUserId) {
+      const member = TeamMember.create({ teamId: team.teamId, userId: creatorUserId, role: 'owner' });
+      await this.teamRepository.addMember(member);
+    }
+
+    this.logger.info(
+      '[TeamService:createTeam] teamId: %s, orgId: %s, name: %s, creator: %s',
+      team.teamId,
+      orgId,
+      name,
+      creatorUserId,
+    );
     return team;
   }
 
@@ -48,7 +61,7 @@ export class TeamService extends AbstractService {
     this.logger.info('[TeamService:removeTeam] teamId: %s', teamId);
   }
 
-  async addMember(teamId: string, userId: string): Promise<TeamMember> {
+  async addMember(teamId: string, userId: string, role: 'owner' | 'member' = 'member'): Promise<TeamMember> {
     const team = await this.teamRepository.findTeamByTeamId(teamId);
     if (!team) {
       throw new NotFoundError('Team not found');
@@ -66,12 +79,17 @@ export class TeamService extends AbstractService {
 
     const existing = await this.teamRepository.findMember(teamId, userId);
     if (existing) {
+      // Update role if changed
+      if (existing.role !== role) {
+        existing.role = role;
+        await this.teamRepository.addMember(existing);
+      }
       return existing;
     }
 
-    const member = TeamMember.create({ teamId, userId });
+    const member = TeamMember.create({ teamId, userId, role });
     await this.teamRepository.addMember(member);
-    this.logger.info('[TeamService:addMember] teamId: %s, userId: %s', teamId, userId);
+    this.logger.info('[TeamService:addMember] teamId: %s, userId: %s, role: %s', teamId, userId, role);
     return member;
   }
 

app/port/controller/OrgController.ts

@@ -167,7 +167,7 @@ export class OrgController extends AbstractController {
     if (!targetUser) {
       throw new NotFoundError(`User "${username}" not found`);
     }
-    const teams = await this.teamRepository.listTeamsByUserIdAndOrgId(targetUser.userId, org.orgId);
-    return teams.map((t) => ({ name: t.name, description: t.description }));
+    const teamResults = await this.teamRepository.listTeamsByUserIdAndOrgId(targetUser.userId, org.orgId);
+    return teamResults.map((t) => ({ name: t.team.name, description: t.team.description, role: t.role }));
   }
 }

app/port/controller/TeamController.ts

@@ -1,9 +1,10 @@
 import { Context, HTTPBody, HTTPContext, HTTPController, HTTPMethod, HTTPMethodEnum, HTTPParam, Inject } from 'egg';
-import { NotFoundError, UnprocessableEntityError } from 'egg/errors';
+import { ForbiddenError, NotFoundError, UnprocessableEntityError } from 'egg/errors';
 
 import { getScopeAndName } from '../../common/PackageUtil.ts';
 import type { OrgService } from '../../core/service/OrgService.ts';
 import type { TeamService } from '../../core/service/TeamService.ts';
+import type { OrgRepository } from '../../repository/OrgRepository.ts';
 import type { TeamRepository } from '../../repository/TeamRepository.ts';
 import { AbstractController } from './AbstractController.ts';
 
@@ -15,6 +16,9 @@ export class TeamController extends AbstractController {
   @Inject()
   private readonly teamService: TeamService;
 
+  @Inject()
+  private readonly orgRepository: OrgRepository;
+
   @Inject()
   private readonly teamRepository: TeamRepository;
 
@@ -50,12 +54,44 @@ export class TeamController extends AbstractController {
   }
 
   private async requireTeamWriteAccess(ctx: Context, orgName: string, teamName: string) {
-    const { org, authorizedUser } = await this.requireOrgWriteAccess(ctx, orgName);
+    const authorizedUser = await this.userRoleManager.requiredAuthorizedUser(ctx, 'setting');
+    const isAdmin = await this.userRoleManager.isAdmin(ctx);
+
+    let org;
+    if (this.isAllowScopeOrg(orgName)) {
+      org = await this.orgService.ensureOrgForScope(`@${orgName}`);
+    } else {
+      org = await this.orgService.findOrgByName(orgName);
+      if (!org) {
+        throw new NotFoundError(`Org "${orgName}" not found`);
+      }
+    }
+
     const team = await this.teamRepository.findTeam(org.orgId, teamName);
     if (!team) {
       throw new NotFoundError(`Team "${teamName}" not found`);
     }
-    return { org, team, authorizedUser };
+
+    // Admin always has access
+    if (isAdmin) {
+      return { org, team, authorizedUser };
+    }
+
+    // Org owner has access
+    if (!this.isAllowScopeOrg(orgName)) {
+      const orgMember = await this.orgRepository.findMember(org.orgId, authorizedUser.userId);
+      if (orgMember && orgMember.role === 'owner') {
+        return { org, team, authorizedUser };
+      }
+    }
+
+    // Team owner has access
+    const teamMember = await this.teamRepository.findMember(team.teamId, authorizedUser.userId);
+    if (teamMember && teamMember.role === 'owner') {
+      return { org, team, authorizedUser };
+    }
+
+    throw new ForbiddenError('Only team owner or admin can perform this action');
   }
 
   // --- Team CRUD ---
@@ -70,12 +106,12 @@ export class TeamController extends AbstractController {
     @HTTPParam() orgName: string,
     @HTTPBody() body: { name: string; description?: string },
   ) {
-    const { org } = await this.requireOrgWriteAccess(ctx, orgName);
+    const { org, authorizedUser } = await this.requireOrgWriteAccess(ctx, orgName);
 
     if (!body.name) {
       throw new UnprocessableEntityError('name is required');
     }
-    await this.teamService.createTeam(org.orgId, body.name, body.description);
+    await this.teamService.createTeam(org.orgId, body.name, body.description, authorizedUser.userId);
     return { ok: true };
   }
 
@@ -131,6 +167,7 @@ export class TeamController extends AbstractController {
   // --- Team Members (npm uses "user") ---
 
   // npm team ls @scope:team → GET /-/team/:orgName/:teamName/user
+  // npm compatible: returns string array ["user1", "user2"]
   @HTTPMethod({
     path: '/-/team/:orgName/:teamName/user',
     method: HTTPMethodEnum.GET,
@@ -150,6 +187,64 @@ export class TeamController extends AbstractController {
     return users.map((u) => u.displayName);
   }
 
+  // Private API: GET /-/team/:orgName/:teamName/member
+  // Returns [{user, role}] with team member role info
+  @HTTPMethod({
+    path: '/-/team/:orgName/:teamName/member',
+    method: HTTPMethodEnum.GET,
+  })
+  async listTeamMembersWithRole(
+    @HTTPContext() ctx: Context,
+    @HTTPParam() orgName: string,
+    @HTTPParam() teamName: string,
+  ) {
+    await this.userRoleManager.requiredAuthorizedUser(ctx, 'read');
+    const org = await this.findOrg(orgName);
+    if (!org) {
+      throw new NotFoundError(`Org "${orgName}" not found`);
+    }
+    const team = await this.teamRepository.findTeam(org.orgId, teamName);
+    if (!team) {
+      throw new NotFoundError(`Team "${teamName}" not found`);
+    }
+    const members = await this.teamService.listMembers(team.teamId);
+    const users = await this.userRepository.findUsersByUserIds(members.map((m) => m.userId));
+    const userMap = new Map(users.map((u) => [u.userId, u]));
+    return members.map((m) => ({
+      user: userMap.get(m.userId)?.displayName ?? '',
+      role: m.role,
+    }));
+  }
+
+  // Private API: PATCH /-/team/:orgName/:teamName/member/:username
+  // Update team member role
+  @HTTPMethod({
+    path: '/-/team/:orgName/:teamName/member/:username',
+    method: HTTPMethodEnum.PATCH,
+  })
+  async updateTeamMemberRole(
+    @HTTPContext() ctx: Context,
+    @HTTPParam() orgName: string,
+    @HTTPParam() teamName: string,
+    @HTTPParam() username: string,
+    @HTTPBody() body: { role: string },
+  ) {
+    const { team } = await this.requireTeamWriteAccess(ctx, orgName, teamName);
+    if (!body.role || (body.role !== 'owner' && body.role !== 'member')) {
+      throw new UnprocessableEntityError('role is required and must be "owner" or "member"');
+    }
+    const targetUser = await this.userRepository.findUserByName(username);
+    if (!targetUser) {
+      throw new NotFoundError(`User "${username}" not found`);
+    }
+    const member = await this.teamRepository.findMember(team.teamId, targetUser.userId);
+    if (!member) {
+      throw new NotFoundError(`User "${username}" is not a member of this team`);
+    }
+    await this.teamService.addMember(team.teamId, targetUser.userId, body.role as 'owner' | 'member');
+    return { ok: true };
+  }
+
   // npm team add <user> @scope:team → PUT /-/team/:orgName/:teamName/user
   @HTTPMethod({
     path: '/-/team/:orgName/:teamName/user',

app/repository/TeamRepository.ts

@@ -68,16 +68,19 @@ export class TeamRepository extends AbstractRepository {
     return models.map((model) => ModelConvertor.convertModelToEntity(model, Team));
   }
 
-  async listTeamsByUserIdAndOrgId(userId: string, orgId: string): Promise<Team[]> {
+  async listTeamsByUserIdAndOrgId(userId: string, orgId: string): Promise<{ team: Team; role: string }[]> {
     const orgTeams = await this.Team.find({ orgId });
     if (orgTeams.length === 0) return [];
     const orgTeamIds = orgTeams.map((t) => t.teamId);
     const memberModels = await this.TeamMember.find({ userId, teamId: { $in: orgTeamIds } });
     if (memberModels.length === 0) return [];
-    const memberTeamIds = new Set(memberModels.map((m) => m.teamId));
+    const memberRoleMap = new Map(memberModels.map((m) => [m.teamId, m.role || 'member']));
     return orgTeams
-      .filter((t) => memberTeamIds.has(t.teamId))
-      .map((model) => ModelConvertor.convertModelToEntity(model, Team));
+      .filter((t) => memberRoleMap.has(t.teamId))
+      .map((model) => ({
+        team: ModelConvertor.convertModelToEntity(model, Team),
+        role: memberRoleMap.get(model.teamId) || 'member',
+      }));
   }
 
   // --- TeamMember ---
@@ -90,6 +93,10 @@ export class TeamRepository extends AbstractRepository {
 
   async addMember(member: TeamMember): Promise<void> {
     if (member.id) {
+      const model = await this.TeamMember.findOne({ id: member.id });
+      if (model) {
+        await ModelConvertor.saveEntityToModel(member, model);
+      }
       return;
     }
     await ModelConvertor.convertEntityToModel(member, this.TeamMember);

app/repository/model/TeamMember.ts

@@ -24,4 +24,7 @@ export class TeamMember extends Bone {
 
   @Attribute(DataTypes.STRING(24))
   userId: string;
+
+  @Attribute(DataTypes.STRING(20))
+  role: string;
 }