docs: 完善项目说明和协作规则

src/views/roles/index.vue

@@ -25,10 +25,12 @@ defineOptions({
   name: "RoleManagement"
 });
 
+/** 表单状态与角色 payload 对齐，id 只在编辑已有角色时存在。 */
 type RoleFormState = RolePayload & {
   id?: number;
 };
 
+/** 角色编码用于权限判断，限制为稳定的小写标识，避免展示名变更影响授权逻辑。 */
 const codePattern = /^[a-z][a-z0-9_]*$/;
 const tableLoading = ref(false);
 const submitLoading = ref(false);
@@ -65,6 +67,7 @@ const rules: FormRules<RoleFormState> = {
   ]
 };
 
+/** 角色列表当前不分页，搜索在前端完成，降低简单维护场景的交互成本。 */
 const filteredRoles = computed(() => {
   const keyword = query.keyword.trim().toLowerCase();
 
@@ -119,6 +122,7 @@ function resetFormState() {
   formRef.value?.clearValidate();
 }
 
+/** 空说明统一转为 null，和后端可选字段语义保持一致。 */
 function buildPayload(): RolePayload {
   const description = form.description?.trim();
 
@@ -129,6 +133,7 @@ function buildPayload(): RolePayload {
   };
 }
 
+/** 角色是员工绑定的基础字典，页面加载和保存后都需要刷新。 */
 async function fetchRoles() {
   tableLoading.value = true;
   try {