"}
{"path":"apps/admin/src/pages/Students/index.tsx","start_line":541,"end_line":541,"category":"bug","severity":"medium","content":"Pagination is not reset when the search keyword, filters (status/class/teacher/org), or the archived toggle change. The list query refetches with a new queryKey but `pageInfo.current` keeps its old value, so if the current page is beyond the page count of the new result set, the table renders empty/out-of-range data. Reset `pageInfo.current` to 1 in every filter/search/toggle handler (or in an effect watching the filter values).","suggestion_code":" onSearchName={(name) => {\n setSearchName(name);\n setPageInfo((prev) => ({ ...prev, current: 1 }));\n }}","existing_code":" onSearchName={setSearchName}"}
{"path":"apps/admin/src/pages/Students/index.tsx","start_line":468,"end_line":470,"category":"bug","severity":"medium","content":"The `else` branch treats every non-'partial' status as success. If the backend reports status `'error'`/`'failed'`, the error message would be shown in a `message.success` toast, misleading users into believing the sync succeeded. Explicitly handle an error status with `message.error`.","suggestion_code":" } else if (log?.status === 'error') {\n message.error(log?.errorMessage || '钉钉同步失败');\n } else {\n message.success(\n log?.errorMessage || `钉钉同步完成，共处理 ${log?.recordsCount ?? res.synced} 条`,\n );\n }","existing_code":" message.success(\n log?.errorMessage || `钉钉同步完成，共处理 ${log?.recordsCount ?? res.synced} 条`,\n );"}
{"path":"apps/admin/src/pages/Students/index.tsx","start_line":85,"end_line":85,"category":"maintainability","severity":"low","content":"`any` is used for the `editing` state (and similarly for `saveCell`'s `record: any` and the import handlers' `{ file, onSuccess, onError }: any`), which bypasses type checking on the record fields accessed later (e.g., `editing.id`, `record.id`). Define a concrete Student record type (or reuse the schema-derived row type) for these; if `any` is unavoidable, add a comment explaining why.","suggestion_code":null,"existing_code":" const [editing, setEditing] = useState
(null);"}
{"path":"apps/admin/src/pages/Students/index.tsx","start_line":301,"end_line":301,"category":"bug","severity":"low","content":"`form.validateFields()` rejects when validation fails, and this call sits outside the try/catch, producing an unhandled promise rejection (and possible uncaught error log) when the user submits an invalid form. Wrap the validation in its own try/catch and return early on failure.","suggestion_code":" let values: Record;\n try {\n values = await form.validateFields();\n } catch {\n return;\n }\n setSaving(true);","existing_code":" const values = await form.validateFields();"}
{"path":"apps/admin/src/pages/Students/index.tsx","start_line":571,"end_line":577,"category":"maintainability","severity":"low","content":"The \"add student\" logic (reset form, prefill host organization, open modal) is duplicated verbatim in both `StudentsToolbar`'s `onAddStudent` and `StudentsTable`'s `onAddStudent`. Extract a single `openCreateModal` callback and reuse it in both places so the prefill behavior cannot diverge.","suggestion_code":null,"existing_code":" onAddStudent={() => {\n setEditing(null);\n form.resetFields();\n const host = organizations.find((organization) => organization.isHost);\n if (host) form.setFieldValue('organizationId', host.id);\n setModalOpen(true);\n }}"}
{"path":"apps/admin/src/pages/Students/index.tsx","start_line":472,"end_line":472,"category":"maintainability","severity":"low","content":"Hardcoded `['students']` query key is used here (and again in `JinshujuModal`'s `onApplied`), while the rest of the page uses the centralized `queryKeys.students.all`. Use `queryKeys.students.all` (or the same `invalidateStudents` array used by the mutations) so cache invalidation stays consistent if the key structure changes.","suggestion_code":" void queryClient.invalidateQueries({ queryKey: queryKeys.students.all });","existing_code":" void queryClient.invalidateQueries({ queryKey: ['students'] });"}
{"path":"apps/admin/src/pages/Users/index.tsx","start_line":38,"end_line":38,"category":"maintainability","severity":"medium","content":"This file uses `any` extensively (`editing`, `resetTarget`, `profileUser`, `record` parameters, the query generic, etc.) without any justification comment. Per the review rules `any` should be avoided. Define shared types (e.g. `UserRecord`/`Role`) and reuse `UserProfileResponse` (already imported from `user-profile-form`) so the table rows, handlers and mutations are type-safe.","suggestion_code":" const [editing, setEditing] = useState(null);","existing_code":" const [editing, setEditing] = useState(null);"}
{"path":"apps/admin/src/pages/Users/index.tsx","start_line":98,"end_line":101,"category":"bug","severity":"medium","content":"Errors are caught inside the `queryFn` and converted into empty results plus a toast. This swallows the query's error state (`isError` is never set), and because TanStack Query retries failed queries by default (3 retries) and mutations invalidate `['rbac', 'users']` to trigger background refetches, a transient failure can produce multiple `加载失败，请稍后重试` toasts in a row (one per retry/refetch). Prefer throwing from `queryFn` and handling the error once at the query level (error state/`onError`), or set `retry: false` and toast once here.","suggestion_code":" } catch (e: unknown) {\n // 由 useQuery 的 error 状态统一处理，避免重试/后台刷新时重复弹 toast\n throw e;\n }","existing_code":" } catch (e: unknown) {\n message.error(getErrorMessage(e, '加载失败，请稍后重试'));\n return { users: [], roles: [] };\n }"}
{"path":"apps/admin/src/pages/Users/index.tsx","start_line":24,"end_line":30,"category":"maintainability","severity":"low","content":"`USER_FIELDS.phone`, `USER_FIELDS.email` and `USER_FIELDS.status` are declared but never referenced anywhere in this file (only `username` and `name` are used as column `dataIndex`). Remove the unused entries or actually use them, otherwise they are dead constants that mislead readers into thinking these fields are editable here.","suggestion_code":"const USER_FIELDS = {\n username: 'username',\n name: 'name',\n} as const;","existing_code":"const USER_FIELDS = {\n username: 'username',\n name: 'name',\n phone: 'phone',\n email: 'email',\n status: 'status',\n} as const;"}
{"path":"apps/admin/src/pages/Users/index.tsx","start_line":161,"end_line":162,"category":"bug","severity":"low","content":"`form.validateFields()` is awaited outside the try/catch in `handleSubmit` (same pattern in `handleProfileSubmit` and `handlePwdSubmit`). When validation fails it rejects, producing an unhandled promise rejection from the Modal's `onOk`. antd already shows the field errors, so wrap the validation (or the whole flow) in try/catch so the rejection is handled explicitly.","suggestion_code":" const handleSubmit = async () => {\n let values: any;\n try {\n values = await form.validateFields();\n } catch {\n // 校验失败，antd 已展示错误提示\n return;\n }","existing_code":" const handleSubmit = async () => {\n const values = await form.validateFields();"}
{"path":"apps/admin/src/pages/Users/index.tsx","start_line":91,"end_line":91,"category":"maintainability","severity":"low","content":"API endpoint paths are hardcoded inline in many places (`/rbac/users`, `/rbac/roles`, `/rbac/users/${id}/profile`, `.../password`, `.../permanent`, `.../archive`/`restore`). Per the review rules business URL paths should not be hardcoded; centralize them in the `api` module so endpoint names stay consistent and are easier to adjust/version.","suggestion_code":null,"existing_code":" api.get(`/rbac/users?isArchived=${showArchived}`) as Promise,"}
{"path":"apps/admin/src/pages/Users/index.tsx","start_line":264,"end_line":266,"category":"style","severity":"low","content":"Several inline `style` attributes are used (page-header wrapper, the Switch wrapper span, the username cell span, etc.). Per the review rules inline styles should be reserved for dynamic values only; extract static layout styles into classNames/CSS instead.","suggestion_code":null,"existing_code":" undefined }`. This is a type mismatch (TS2554: expected 1 argument, got 2) whenever type-checking is enabled, and the comment itself admits the argument only exists to satisfy an external signature. If the underlying implementation truly has a two-parameter signature, define an explicit prop type (e.g. `(options: UploadRequestOption, info?: { defaultRequest: () => void }) => void`) and keep the interfaces in sync; otherwise drop the second argument entirely.","suggestion_code":null,"existing_code":" // 实现方只使用 { file, onSuccess, onError }；info 参数仅用于满足类型签名\n onUpdateImport?.(options, { defaultRequest: () => undefined });"}
{"path":"apps/admin/src/pages/Students/StudentsToolbar.tsx","start_line":254,"end_line":256,"category":"bug","severity":"low","content":"If the user cancels `modal.confirm`, neither `options.onSuccess` nor `options.onError` is ever invoked, so the `Upload` component keeps this file permanently stuck in the 'uploading' state. It is invisible only because `showUploadList={false}`, but the internal state leaks and any success/error feedback is lost. Handle the cancel path (e.g. call `options.onError?.()` when the dialog is dismissed, or intercept selection with `beforeUpload` returning `Upload.LIST_IGNORE`), and wrap the async `onUpdateImport` call in try/catch so failures surface to the user instead of leaving the modal/upload in an unresolved state.","suggestion_code":null,"existing_code":" customRequest={(options) => {\n const file = options.file as File;\n modal.confirm({"}
{"path":"apps/admin/src/pages/Students/StudentsToolbar.tsx","start_line":180,"end_line":182,"category":"maintainability","severity":"low","content":"This renders batch actions with a nested ternary (`showArchived && canEditStudent ? ... : !showArchived && canDeleteStudent ? ... : null`), which the review rules prohibit. Extract the batch-action block into a small helper (e.g. `renderBatchActions()`) using early returns for readability.","suggestion_code":null,"existing_code":" {showArchived && canEditStudent ? (\n <>\n "}
{"path":"apps/admin/src/pages/Teachers/index.tsx","start_line":120,"end_line":120,"category":"bug","severity":"medium","content":"Clearing the date field cannot be persisted: when the user clears `joinedAt`, `values.joinedAt` is `null` and this expression yields `undefined`. JSON serialization drops `undefined` keys, so the PUT payload will not contain `joinedAt` at all and the server keeps the old value. Send `null` explicitly so the backend can clear it.","suggestion_code":" joinedAt: values.joinedAt ? values.joinedAt.format('YYYY-MM-DD') : null,","existing_code":" joinedAt: values.joinedAt?.format('YYYY-MM-DD'),"}
{"path":"apps/admin/src/pages/Teachers/index.tsx","start_line":107,"end_line":107,"category":"bug","severity":"medium","content":"Same clearing bug on the inline-edit path: `EditableCell`'s date editor serializes a cleared date to `undefined` (see `serializeEditableValue` for 'date' in EditableCell/index.tsx), so `{ [field]: undefined }` drops the `joinedAt` key from the JSON payload and the server retains the previous date. Normalize to `null` before sending.","suggestion_code":" api.put(`/rbac/teachers/${record.id}/profile`, { [field]: value ?? null }),","existing_code":" api.put(`/rbac/teachers/${record.id}/profile`, { [field]: value }),"}
{"path":"apps/admin/src/pages/Teachers/index.tsx","start_line":83,"end_line":83,"category":"maintainability","severity":"low","content":"Business API paths `/rbac/teachers` and `/rbac/teachers/${id}/profile` are hardcoded and duplicated in three places (queryFn and both mutations), making the endpoint contract drift-prone. Centralize them in the api layer (e.g., `api.rbac.teachers.list` / `api.rbac.teachers.updateProfile`) instead of scattering path strings across the page.","suggestion_code":null,"existing_code":" await api.get('/rbac/teachers', {"}
{"path":"apps/admin/src/pages/Teachers/index.tsx","start_line":165,"end_line":166,"category":"maintainability","severity":"low","content":"Using the array index as the React `key` for classAssignment tags (here and in `expandedRowRender`) can cause incorrect reconciliation when the assignment list changes/reorders after a refetch. Prefer a stable composite key such as `${a.roleType}-${a.className}-${a.subject}`.","suggestion_code":null,"existing_code":" \n {a.className || '-'}"}
{"path":"apps/admin/src/pages/Teachers/index.tsx","start_line":91,"end_line":91,"category":"performance","severity":"low","content":"Binding the Table's `loading` to `isFetching` shows a full-page spinner overlay on every background refetch — including the refetch triggered by `invalidate` after each inline cell save and by `useVisibleRefetch` — which blocks/interrupts an in-progress cell edit and causes table flicker. Use `isLoading` for the Table overlay and keep `isFetching` only for the subtle `RefreshButton` indicator.","suggestion_code":" const loading = isLoading;","existing_code":" const loading = isLoading || isFetching;"}
{"path":"apps/admin/src/pages/Wallets/index.tsx","start_line":336,"end_line":336,"category":"bug","severity":"medium","content":"Batch selection is silently lost when changing pages: antd's `rowSelection` by default prunes `selectedRowKeys` to the rows of the current page, so students selected on page 1 are dropped after the user flips to page 2. The batch operation then applies to fewer students than the user intended, and the success message count (`selectedRowKeys.length`) reflects only the current page. Enable `preserveSelectedRowKeys: true` so selections survive pagination (selection is already correctly cleared on filter changes).","suggestion_code":" rowSelection={{ selectedRowKeys, onChange: setSelectedRowKeys, preserveSelectedRowKeys: true }}","existing_code":" rowSelection={{ selectedRowKeys, onChange: setSelectedRowKeys }}"}
{"path":"apps/admin/src/pages/Wallets/index.tsx","start_line":162,"end_line":162,"category":"bug","severity":"low","content":"`mutateAsync` result is typed as `any`; if the request resolves to an empty/undefined body (e.g., 204 or a gateway transform), `result.payments` throws a TypeError that is silently swallowed by the catch block, so a successful operation is reported as a generic failure. Use `result?.payments || []` and define a proper response type (e.g., `{ wallet: ...; payments: { paidAmount: number }[] }`) instead of `any`. The same pattern is repeated in `submitBatchChange`.","suggestion_code":" const result = await changeMutation.mutateAsync<{ payments?: { paidAmount?: number }[] }>({","existing_code":" const result: any = await changeMutation.mutateAsync({"}
{"path":"apps/admin/src/pages/Wallets/index.tsx","start_line":184,"end_line":184,"category":"bug","severity":"low","content":"Same untyped/`any` response handling as in `submitChange`: `result.results` will throw if the body is undefined, and `item.payments`/`bill.paidAmount` are untyped. Use `result?.results || []` and define a typed response shape instead of `any`.","suggestion_code":" const result = await batchChangeMutation.mutateAsync<{ results?: { payments?: { paidAmount?: number }[] }[] }>({","existing_code":" const result: any = await batchChangeMutation.mutateAsync({"}
{"path":"apps/admin/src/pages/Wallets/index.tsx","start_line":39,"end_line":45,"category":"maintainability","severity":"low","content":"`WalletTransaction` is incomplete and unvalidated: the table columns read `billId` and `description` but the interface doesn't declare them, and — unlike the two list queries which go through `validateResponse` — the `/wallets/transactions` response has no schema validation. Malformed data (e.g., missing `amount` or `createdAt`) would crash `value.toFixed(2)` / `dayjs(value)` in the drawer. Add the missing optional fields and validate this response too.","suggestion_code":"interface WalletTransaction {\n id: number;\n createdAt: string;\n type: string;\n amount: number;\n balanceAfter: number;\n billId?: number;\n description?: string;\n}","existing_code":"interface WalletTransaction {\n id: number;\n createdAt: string;\n type: string;\n amount: number;\n balanceAfter: number;\n}"}
{"path":"apps/admin/src/pages/Wallets/index.tsx","start_line":399,"end_line":401,"category":"maintainability","severity":"low","content":"The `type`/`amount`/`description` Form fields (including the same validation rules and helper text) are duplicated between the single and batch modals. Extract them into a shared field set/component or a shared field config so validation rules and copy stay in sync when changed in one place.","suggestion_code":null,"existing_code":" "}
{"path":"apps/admin/src/pages/Wallets/index.tsx","start_line":367,"end_line":367,"category":"bug","severity":"low","content":"No validation links the amount sign to the operation type: a negative value is accepted for 充值 (recharge) and a positive one for 调账 (adjustment), even though the helper text says recharge must be positive and deductions must be negative. Add conditional rules (e.g., `min: 0.01` when type is `recharge`) so invalid values are rejected before reaching the API.","suggestion_code":null,"existing_code":" rules={[{ required: true, message: '请输入金额' }]}"}
{"path":"apps/server/src/agent-context/business-context.types.ts","start_line":16,"end_line":16,"category":"maintainability","severity":"low","content":"All other collection fields in this file are declared `readonly` to enforce immutability of the shared config, but `options` is a mutable `Array`. This inconsistency allows accidental mutation of the config (e.g., push/sort in callers). Declare it `readonly` for consistency.","suggestion_code":" options?: ReadonlyArray<{ label: string; value: string }>;","existing_code":" options?: Array<{ label: string; value: string }>;"}
{"path":"apps/server/src/agent-tools/agent-skill.catalog.ts","start_line":3,"end_line":5,"category":"maintainability","severity":"low","content":"The `key` values here (e.g. 'overview', 'student') are plain string literals with no compile-time linkage to the `skillKey` used by actual tool definitions (see `ToolDef.skillKey` in agent-tool.types.ts). Since `AgentSkillDescriptor.key` is typed as `string`, a typo or a key that no tool implements will silently produce an empty skill at runtime. Consider using a shared union type / const assertion (e.g. `as const` + `satisfies`) so keys are validated against the set of defined tools.","suggestion_code":null,"existing_code":"export const AGENT_SKILLS: readonly Omit[] = [\n {\n key: 'overview',"}
{"path":"apps/server/src/agent-context/get-pending-tasks.tool.ts","start_line":20,"end_line":21,"category":"maintainability","severity":"low","content":"The description hardcodes the three workflow keys (`student_teaching / dormitory_billing / classroom_rental`), duplicating `BUSINESS_WORKFLOW_KEYS` which is already imported and used to build the schema enum dynamically. When a new workflow is added to the registry, the enum updates automatically but this LLM-facing description silently drifts out of sync. Consider composing the description from `BUSINESS_WORKFLOW_KEYS` to keep them in lockstep.","suggestion_code":" readonly description =\n `获取当前账号可见范围内的业务待办计数（未分班学生、已建档未入住学生、在住未生成账单、租赁缺合同/临期到期等），可按闭环（${BUSINESS_WORKFLOW_KEYS.join(' / ')}）聚焦。写入或导入前用它核实前置数据是否齐备，完成后用它判断后续待办。`;","existing_code":" readonly description =\n '获取当前账号可见范围内的业务待办计数（未分班学生、已建档未入住学生、在住未生成账单、租赁缺合同/临期到期等）。写入或导入前用它核实前置数据是否齐备，完成后用它判断后续待办。';"}
{"path":"apps/server/src/agent-context/get-pending-tasks.tool.ts","start_line":40,"end_line":46,"category":"maintainability","severity":"low","content":"`workflowKey` is matched with exact equality against the enum, but LLM-supplied input can easily carry accidental whitespace (e.g. `\"student_teaching \"`). Such input is rejected with the confusing \"必须是 X 之一\" error even though the value is semantically valid. Other tools normalize string input via `optionalString` (which trims); consider trimming here before the `includes` check.","suggestion_code":" if (\n typeof input.workflowKey !== 'string' ||\n !BUSINESS_WORKFLOW_KEYS.includes(input.workflowKey.trim())\n ) {\n return { ok: false, error: `workflowKey 必须是 ${BUSINESS_WORKFLOW_KEYS.join(' / ')} 之一` };\n }\n return { ok: true, value: { workflowKey: input.workflowKey.trim() } };","existing_code":" if (\n typeof input.workflowKey !== 'string' ||\n !(BUSINESS_WORKFLOW_KEYS).includes(input.workflowKey)\n ) {\n return { ok: false, error: `workflowKey 必须是 ${BUSINESS_WORKFLOW_KEYS.join(' / ')} 之一` };\n }\n return { ok: true, value: { workflowKey: input.workflowKey } };"}
{"path":"apps/server/src/agent-context/business-context.service.ts","start_line":155,"end_line":158,"category":"bug","severity":"medium","content":"Inconsistent returned context: entities are collected from the visible workflows' stage.entities, but then additionally filtered by the entity's own requiredPermissions. If a visible workflow references an entity the principal lacks permission for (e.g. a user with `student:view` but not `attendance:view`), the workflow is still returned while the entity definition is dropped. The caller then receives workflows whose `stages[].entities` reference keys absent from the returned `entities` array — and the entity key is already leaked via the workflow anyway. Either return all referenced entities for visible workflows, or drop workflows that reference entities the principal cannot view, so the result is internally consistent.","suggestion_code":null,"existing_code":" const entities = BUSINESS_ENTITIES.filter(\n (entity) => entityKeys.has(entity.key) && hasPermission(principal, entity.requiredPermissions),\n );\n return { workflows, entities };"}
{"path":"apps/server/src/agent-context/business-context.service.ts","start_line":58,"end_line":60,"category":"maintainability","severity":"medium","content":"validateRegistry is incomplete as an integrity check: it detects duplicate entity keys, duplicate field keys, and duplicate stage keys within a workflow, but not duplicate workflow keys across BUSINESS_WORKFLOWS (a duplicate key would make getBusinessContext(principal, workflowKey) silently return multiple workflows) nor duplicate nextSteps step keys (which would make suggestNextSteps return duplicate suggestions). Add checks for both so the registry validator catches these.","suggestion_code":null,"existing_code":" const duplicateEntities = BUSINESS_ENTITIES\n .map((entity) => entity.key)\n .filter((key, index, all) => all.indexOf(key) !== index);"}
{"path":"apps/server/src/agent-context/business-context.service.ts","start_line":86,"end_line":90,"category":"maintainability","severity":"low","content":"`stageKeys` here is a union of stage keys across ALL workflows, so a relation's `requiredFor` reference passes validation as long as the key exists in any workflow — e.g. 'schedule' is a stage in both student_teaching and classroom_rental, and 'profile'/'room' also appear in multiple workflows. This lets cross-workflow stage-key collisions mask a wrong reference (a relation pointing at a stage that doesn't exist in the workflow context where the entity is actually used). Consider validating `requiredFor` against the per-workflow stage keys of the workflow(s) that use this entity.","suggestion_code":null,"existing_code":" for (const stageKey of relation.requiredFor) {\n if (!stageKeys.has(stageKey)) {\n problems.push(`实体 ${entity.key} 关系 ${relation.via} 引用未知阶段: ${stageKey}`);\n }\n }"}
{"path":"apps/server/src/agent-context/get-business-context.tool.ts","start_line":19,"end_line":19,"category":"maintainability","severity":"medium","content":"Description hardcodes business keys (student_teaching / dormitory_billing / classroom_rental) and the entity list that already live in business-context.registry.ts. If a workflow or entity key is renamed/removed in the registry, this LLM-facing prompt silently drifts and the model will keep generating stale keys. Consider composing the description (or the inputSchema description) from BUSINESS_WORKFLOWS/BUSINESS_ENTITIES so keys stay in sync automatically.","suggestion_code":"'获取当前账号可见的业务流程、实体字典、阶段依赖与下一步建议。写入或导入前先调用本工具确认前置数据要求。';","existing_code":"'获取当前账号可见的业务流程（学生教学/住宿计费/教室租赁）、实体字典、阶段依赖与下一步建议。写入或导入前先调用本工具确认前置数据要求。';"}
{"path":"apps/server/src/agent-context/get-business-context.tool.ts","start_line":42,"end_line":43,"category":"maintainability","severity":"low","content":"The synchronous service call is wrapped in Promise.resolve instead of using async/await. Since both service methods are synchronous, making these handlers `async execute(...)` and returning the value directly is simpler, clearer, and matches the project's preference for async/await.","suggestion_code":" async execute(input: GetBusinessContextInput, context: AgentToolContext): Promise {\n return this.service.getBusinessContext(","existing_code":" execute(input: GetBusinessContextInput, context: AgentToolContext): Promise {\n return Promise.resolve("}
{"path":"apps/server/src/agent-context/get-business-context.tool.ts","start_line":76,"end_line":78,"category":"bug","severity":"low","content":"The error message 'entityKey 必须是字符串' is misleading: this branch also catches empty/whitespace-only strings and strings longer than 50 chars (before trim). A caller passing an empty string gets a message claiming the type is wrong. Split the checks so each failure returns an accurate message (e.g. 'entityKey 不能为空' for empty/whitespace-only, 'entityKey 长度不能超过 50' for length).","suggestion_code":" if (typeof input.entityKey !== 'string') {\n return { ok: false, error: 'entityKey 必须是字符串' };\n }\n if (!input.entityKey.trim()) {\n return { ok: false, error: 'entityKey 不能为空' };\n }","existing_code":" if (typeof input.entityKey !== 'string' || !input.entityKey.trim()) {\n return { ok: false, error: 'entityKey 必须是字符串' };\n }"}
{"path":"apps/server/src/agent-context/get-business-context.tool.ts","start_line":37,"end_line":37,"category":"other","severity":"low","content":"Unknown keys are silently accepted: a typo'd workflowKey yields an empty workflow list and a typo'd entityKey yields null, both as 'success'. For an LLM agent this is a silent failure that wastes a turn and may make the model conclude the data does not exist. Consider validating the key against the registry and returning an explicit error for unknown keys (while still returning empty/null for known-but-forbidden keys to avoid leaking existence).","suggestion_code":null,"existing_code":" const workflowKey = optionalString(input.workflowKey, 'workflowKey', 50);"}
{"path":"apps/server/src/agent-tools/agent-tool.registry.ts","start_line":30,"end_line":30,"category":"maintainability","severity":"medium","content":"The permission subject string `PermissionCode:${tool.requiredPermission}` is hand-built here, duplicating the exported helper `permissionCodeSubject()` from `../authorization/casl.constants` (which the executor's execute-time check goes through via `AuthorizationService.canPermission`). If the subject format ever changes, this listing filter and the execute-time authorization check will silently diverge — a tool could disappear from listings or, worse, be listed without matching the execute-time gate. Use the shared helper instead to keep a single source of truth. (The explicit super-admin branch is also redundant: a `manage all` ability already satisfies `ability.can(Access, ...)` in CASL, but keeping it is harmless.)","suggestion_code":" return ability.can(CaslAction.Access, permissionCodeSubject(tool.requiredPermission));","existing_code":" return ability.can(CaslAction.Access, `PermissionCode:${tool.requiredPermission}`);"}
{"path":"apps/server/src/agent-tools/agent-tool.registry.ts","start_line":12,"end_line":17,"category":"maintainability","severity":"medium","content":"`register()` silently replaces an existing tool that shares the same `name`. Since the doc comment states it is \"called once at module init\", a duplicate name almost certainly indicates a configuration error (two tools defined with the same name), and silently overwriting the earlier registration makes that error invisible — the first tool is dropped with no warning and only the last one ever runs. Consider throwing (or at least logging a warning) on duplicate names so misconfiguration is caught at startup rather than at runtime.","suggestion_code":" if (this.tools.some((t) => t.name === tool.name)) {\n throw new Error(`Agent tool already registered: ${tool.name}`);\n }\n this.tools.push(tool);","existing_code":" const idx = this.tools.findIndex((t) => t.name === tool.name);\n if (idx >= 0) {\n this.tools[idx] = tool;\n } else {\n this.tools.push(tool);\n }"}
{"path":"apps/server/src/agent-tools/agent-business-scope.factory.ts","start_line":22,"end_line":29,"category":"bug","severity":"medium","content":"Dead branch for non-super-admins: `mapPermissionCode`/`permissionToAction` in casl.constants.ts only ever produces create/read/update/delete domain rules — `manage` is granted solely by `createForUser` when `isSuperAdmin` is true. So for any regular user this method is effectively `isSuperAdmin || can(Update, Class)`. A user holding `attendance:edit` (mapped to `update Attendance`) or any `attendance:manage`-style exact code will be denied here, and `get-attendance-summary.tool.ts` will silently fall back to class-scoped data instead of all-attendance scope. If full attendance management should be honored, check `ability.can(CaslAction.Update, SubjectName.Attendance)` (or use `CaslAction.Access` + `permissionCodeSubject('attendance:edit')`); otherwise drop the misleading `Manage` branch.","suggestion_code":null,"existing_code":" canManageAllAttendance(context: AgentToolContext): boolean {\n const ability = this.ability(context);\n return (\n context.isSuperAdmin ||\n ability.can(CaslAction.Manage, SubjectName.Attendance) ||\n ability.can(CaslAction.Update, SubjectName.Class)\n );\n }"}
{"path":"apps/server/src/agent-tools/agent-business-scope.factory.ts","start_line":31,"end_line":38,"category":"bug","severity":"medium","content":"Same dead `Manage` branch: `dashboard:view` maps to `read Dashboard` (never `manage Dashboard`), so for non-super-admins `canManageAllDashboard` reduces to `isSuperAdmin || can(Update, Class)`. A user holding only `dashboard:view` (no `class:edit`) is treated as not managing all and `get-dashboard-stats.tool.ts` returns class-scoped data instead of school-wide stats. If `dashboard:view` should grant full scope, check `ability.can(CaslAction.Read, SubjectName.Dashboard)` or the exact permission code; otherwise remove the `Manage` branch.","suggestion_code":null,"existing_code":" canManageAllDashboard(context: AgentToolContext): boolean {\n const ability = this.ability(context);\n return (\n context.isSuperAdmin ||\n ability.can(CaslAction.Manage, SubjectName.Dashboard) ||\n ability.can(CaslAction.Update, SubjectName.Class)\n );\n }"}
{"path":"apps/server/src/agent-tools/agent-business-scope.factory.ts","start_line":17,"end_line":20,"category":"maintainability","severity":"low","content":"Duplicated logic: `context.isSuperAdmin || ability.can(CaslAction.Update, SubjectName.Class)` is repeated verbatim in all three methods, and each call rebuilds a fresh CASL ability via `createForUser`. Extract a shared private helper (e.g. `private canManageClasses(context: AgentToolContext): boolean`) and reuse it in the attendance/dashboard checks; this also makes the intended semantics (class-scope granting) explicit and avoids rebuilding the ability if several scope checks run in one tool invocation.","suggestion_code":null,"existing_code":" canManageAllClasses(context: AgentToolContext): boolean {\n const ability = this.ability(context);\n return context.isSuperAdmin || ability.can(CaslAction.Update, SubjectName.Class);\n }"}
{"path":"apps/server/src/agent-context/business-context.registry.ts","start_line":105,"end_line":107,"category":"bug","severity":"medium","content":"Attendance metadata is internally inconsistent: the description says records are by 班级与日期 (class + date), and the relations claim attendance links to class/schedule via 'class_schedule', but the entity has no classId field — only studentId/date/status. Since fields drive render_form, the agent cannot generate a class selector for attendance, and the class_schedule 'via' is the class↔schedule join table, not an attendance link. Suggest adding a classId field (and/or a dedicated via) so the form can capture the class the record belongs to.","suggestion_code":null,"existing_code":" field('studentId', '学生', 'number', { required: true }),\n field('date', '日期', 'date', { required: true }),\n field('status', '状态', 'enum', { enumFrom: 'attendance.status' }),"}
{"path":"apps/server/src/agent-context/business-context.registry.ts","start_line":220,"end_line":220,"category":"bug","severity":"medium","content":"This relation's requiredFor references stage 'profile', but the 'profile' stage only exists in the student_teaching and dormitory_billing workflows. The 'organization' entity is only used by the classroom_rental workflow, whose stages are classroom/organization/rental/contract/schedule — so 'profile' can never be satisfied in the workflow where this relation is actually relevant. Additionally, the counterpart relation is missing on the 'student' entity (student has relations to class/occupancy/bill/exam but not organization). Since validateRegistry checks requiredFor against the union of ALL workflow stage keys, this cross-workflow reference silently passes validation. This is likely a misplaced relation: it should either live on the student entity (e.g., relation('organization', 'organization', ['profile'])) or reference a stage within classroom_rental.","suggestion_code":null,"existing_code":" relation('student', 'organization', ['profile']),"}
{"path":"apps/server/src/agent-context/business-context.registry.ts","start_line":303,"end_line":303,"category":"maintainability","severity":"low","content":"Stage keys are not unique across workflows: 'profile' (student_teaching + dormitory_billing) and 'schedule' (student_teaching + classroom_rental) are duplicated. Because BusinessContextService.validateRegistry builds one global set from all workflows' stage keys, relation.requiredFor / nextSteps.after references are validated only against the union, so a relation in one workflow can silently reference a stage belonging to another workflow (see the organization entity's requiredFor ['profile']). Consider namespacing stage keys (e.g., 'teaching:profile', 'rental:schedule') or validating requiredFor against the workflow that actually uses the entity.","suggestion_code":null,"existing_code":" { key: 'schedule', label: '教室日程', entities: ['schedule', 'classroom', 'rental'] },"}
{"path":"apps/server/src/agent-context/pending-tasks.service.ts","start_line":110,"end_line":111,"category":"bug","severity":"medium","content":"The `LEFT JOIN bills b ON b.student_id = o.student_id` matches any bill the student has *ever* had, with no status or period filter. Since `bills` is generated per student per period (`period_start`/`period_end`) and includes historical statuses (`paid`, `cancelled`), a student whose current active occupancy simply has no bill *yet* for the current period will be excluded from this count as long as they have any older (even cancelled) bill. The '在住但未生成账单' count therefore only detects students with zero bills ever, which under-reports the intended pending task. Consider restricting to non-cancelled bills overlapping the occupancy's billing window, e.g. `AND b.status <> 'cancelled' AND b.period_end >= o.billing_start_date`.","suggestion_code":" LEFT JOIN bills b ON b.student_id = o.student_id\n AND b.status <> 'cancelled'\n AND b.period_end >= o.billing_start_date\n WHERE o.status = 'active'","existing_code":" LEFT JOIN bills b ON b.student_id = o.student_id\n WHERE o.status = 'active'"}
{"path":"apps/server/src/agent-context/pending-tasks.service.ts","start_line":161,"end_line":163,"category":"performance","severity":"low","content":"The five count queries are independent (each is a separate `dataSource.query`), but they run sequentially inside `await` in a `for...of` loop, so total latency is the sum of all queries. For an agent-facing service that may be called with several workflows, prefer filtering eligible definitions first and executing the queries in parallel with `Promise.all`, then mapping back in the original order.","suggestion_code":" const eligible = TASKS.filter(\n (d) => can(context, d.permission) && (!workflowKey || d.workflowKeys.includes(workflowKey)),\n );\n const tasks = await Promise.all(\n eligible.map(async (definition) => {\n if (definition.teacherRestricted && scope.type === 'teacher') {\n return {\n key: definition.key, label: definition.label, entity: definition.entity,\n permission: definition.permission, workflowKeys: definition.workflowKeys,\n count: null, restricted: true,\n detail: '当前角色数据范围不适合统计该待办，建议由教务/运营角色处理',\n } as PendingTask;\n }\n const { sql, params } = definition.sql(scope);\n const rows = await this.dataSource.query>>(sql, params);\n return {\n key: definition.key, label: definition.label, entity: definition.entity,\n permission: definition.permission, workflowKeys: definition.workflowKeys,\n count: Number(rows[0]?.cnt ?? 0),\n };\n }),\n );\n return tasks;","existing_code":" for (const definition of TASKS) {\n if (!can(context, definition.permission)) continue;\n if (workflowKey && !definition.workflowKeys.includes(workflowKey)) continue;"}
{"path":"apps/server/src/agent-context/pending-tasks.service.ts","start_line":177,"end_line":179,"category":"bug","severity":"medium","content":"`getPendingTasks` has no error handling around the DB queries: if any single count query fails (missing table/column, timeout, transient connection error), the whole method rejects and the agent receives a raw DB error with no partial results or user-friendly message. Since this service aggregates independent pending-task counts for an agent, wrap each query in a per-task try/catch and either skip the entry or return `count: null` with a `detail` explaining the failure, so one failing task does not abort the entire list.","suggestion_code":" let count = 0;\n try {\n const { sql, params } = definition.sql(scope);\n const rows = await this.dataSource.query>>(sql, params);\n count = Number(rows[0]?.cnt ?? 0);\n } catch (error) {\n // Log and return count:null with a friendly detail instead of failing the whole list\n }","existing_code":" const { sql, params } = definition.sql(scope);\n const rows = await this.dataSource.query>>(sql, params);\n const count = Number(rows[0]?.cnt ?? 0);"}
{"path":"apps/server/src/agent-context/pending-tasks.service.ts","start_line":58,"end_line":60,"category":"maintainability","severity":"low","content":"`utcOffset(8)` is hardcoded in both `today()` and `inDays()`, which means the '七天内到期租赁' date window silently depends on a fixed China-time assumption. If the server is deployed in another region or the business timezone ever changes, the date boundaries shift. Consider injecting the timezone offset from configuration instead of hardcoding it.","suggestion_code":null,"existing_code":"function today(): string {\n return dayjs().utcOffset(8).format('YYYY-MM-DD');\n}"}
{"path":"apps/server/src/agent-tools/tools/get-dashboard-stats.tool.ts","start_line":9,"end_line":9,"category":"maintainability","severity":"low","content":"Multiple class property definitions are collapsed onto a single line, unlike sibling tools (e.g., get-attendance-summary.tool.ts) where each `readonly` property is on its own line. This hurts readability and makes diffs noisier. Consider splitting them one-per-line for consistency and maintainability.","suggestion_code":" readonly name = 'get_dashboard_stats';\n readonly skillKey = 'overview';\n readonly requiredPermission = 'dashboard:view';","existing_code":" readonly name = 'get_dashboard_stats'; readonly skillKey = 'overview'; readonly requiredPermission = 'dashboard:view';"}
{"path":"apps/server/src/agent-tools/tools/create-student.tool.ts","start_line":123,"end_line":129,"category":"bug","severity":"medium","content":"Type-confusion in organizationId validation: `Number(input.organizationId)` coerces values of other types, so booleans and single-element arrays slip through — e.g. `organizationId: true` becomes `1`, and `[5]` becomes `5`. Since the schema declares `type: 'integer'`, validation should require the raw value to actually be a number instead of coercing. Otherwise a malformed model payload can silently target a wrong organization.","suggestion_code":" if (input.organizationId !== undefined) {\n if (\n typeof input.organizationId !== 'number' ||\n !Number.isInteger(input.organizationId) ||\n input.organizationId <= 0\n ) {\n return { ok: false, error: 'organizationId 必须是正整数' };\n }\n result.organizationId = input.organizationId;\n }","existing_code":" if (input.organizationId !== undefined) {\n const id = Number(input.organizationId);\n if (!Number.isInteger(id) || id <= 0) {\n return { ok: false, error: 'organizationId 必须是正整数' };\n }\n result.organizationId = id;\n }"}
{"path":"apps/server/src/agent-tools/tools/create-student.tool.ts","start_line":134,"end_line":135,"category":"security","severity":"medium","content":"`execute` ignores the trusted `AgentToolContext` entirely and blindly trusts the model-supplied `organizationId` (falling back to the global host organization). `StudentsService.create` only asserts the target organization is active — it does not verify the current user has any access to it. Any user holding `student:create` can therefore create students in arbitrary active organizations (cross-tenant write), and there is no audit trail since `_context.userId` is unused. Consider restricting organizationId to the user's own accessible organizations (using the context) and/or recording the acting user for audit.","suggestion_code":null,"existing_code":" async execute(input: CreateStudentInput, _context: AgentToolContext): Promise {\n const organizationId = input.organizationId ?? (await this.resolveDefaultOrganizationId());"}
{"path":"apps/server/src/agent-tools/tools/create-student.tool.ts","start_line":110,"end_line":113,"category":"bug","severity":"low","content":"Inconsistency: `name` is trimmed before validation, but `studentNo` and `idNumber` are not trimmed and whitespace-only strings are accepted. This allows storing blank/whitespace values (e.g. `' '`) that can later break lookups or duplicate checks. Trim them and reject empty results for consistency.","suggestion_code":" if (typeof input.studentNo !== 'string' || input.studentNo.trim().length > 30) {\n return { ok: false, error: 'studentNo 必须是长度不超过 30 的字符串' };\n }\n result.studentNo = input.studentNo.trim();","existing_code":" if (typeof input.studentNo !== 'string' || input.studentNo.length > 30) {\n return { ok: false, error: 'studentNo 必须是长度不超过 30 的字符串' };\n }\n result.studentNo = input.studentNo;"}
{"path":"apps/server/src/agent-tools/agent-tool.types.ts","start_line":31,"end_line":31,"category":"maintainability","severity":"medium","content":"The `_brand` field / `CONTEXT_BRAND` symbol is effectively dead and misleading code: nothing anywhere reads `_brand` — `assertTrusted` verifies trust solely via `trustedContexts` (WeakSet), so the brand adds no real forgery resistance despite the docs claiming the context is \"branded to prevent forgery\". Additionally, the class-field initializer `= CONTEXT_BRAND` can never run because instances are only created via `Object.create(AgentToolContext.prototype)` (the private constructor is never invoked), so the declaration implies a default that is never applied and contradicts the factory's `defineProperty`. Recommend removing `_brand`/`CONTEXT_BRAND` and relying on the WeakSet (which cannot be spoofed), or — if keeping the brand — actually verifying it inside `assertTrusted` instead of just setting it.","suggestion_code":null,"existing_code":" private readonly _brand = CONTEXT_BRAND;"}
{"path":"apps/server/src/agent-tools/agent-tool.types.ts","start_line":59,"end_line":59,"category":"bug","severity":"low","content":"`[...user.permissions]` will throw a raw `TypeError: user.permissions is not iterable` if the runtime user record lacks `permissions` (undefined). The `AuthenticatedUser` type guarantees the field, but this factory is the trust boundary between the JWT layer and the executor, so a defensive guard that fails fast with a clear message (and never produces a broken context) would be more robust and diagnosable.","suggestion_code":null,"existing_code":" value: Object.freeze([...user.permissions]),"}
{"path":"apps/server/src/agent-tools/agent-tools.module.ts","start_line":124,"end_line":127,"category":"maintainability","severity":"medium","content":"Tool registration is maintained in three separate places that must be kept in sync manually: the `imports`/`providers` array, the constructor parameter list, and these 20 `this.registry.register(...)` calls in `onModuleInit`. If a tool is added to `providers` but forgotten here (or vice versa), there is no compile-time error — the executor's registry lookup silently returns `undefined` and the tool is reported as \"unknown tool\" at runtime. Consider driving registration from a single source of truth, e.g. a module-level array of tool tokens used both in `providers` and iterated over in `onModuleInit` (or a custom provider factory that registers on instantiation), so adding a tool cannot be missed.","suggestion_code":null,"existing_code":" onModuleInit(): void {\n this.registry.register(this.businessContextTool);\n this.registry.register(this.entitySchemaTool);\n this.registry.register(this.pendingTasksTool);"}
{"path":"apps/server/src/agent-tools/tools/get-room-occupancy-summary.tool.ts","start_line":17,"end_line":17,"category":"bug","severity":"low","content":"Limit upper bound mismatch: this tool advertises `limit` up to 100 in both the schema and validator, but `RoomsService.agentGetRoomOccupancySummary` silently clamps results to max 50 (default 20). The LLM may request e.g. `limit=100` and receive only 50 rows without knowing results were truncated, which can skew its summarization. Align the maximum to 50 (as `search-rooms.tool.ts` does) so the advertised capability matches actual behavior.","suggestion_code":"const limit = optionalPositiveInt(raw.limit, 'limit', 50); if (!limit.ok) return limit;","existing_code":"const limit = optionalPositiveInt(raw.limit, 'limit', 100); if (!limit.ok) return limit;"}
{"path":"apps/server/src/agent-tools/agent-tool.executor.ts","start_line":123,"end_line":123,"category":"security","severity":"medium","content":"The tool lookup uses the raw, unsanitized `name` (model-controlled input), while `sanitizeName(name)` is only applied for audit logging. Today the registry only holds names matching the regex, so behavior is equivalent, but this creates a latent divergence: if a registered tool ever contains characters outside `[a-zA-Z0-9_]` (e.g. a hyphenated name), the audit log name and the actually-executed tool name will differ, and the sanitization step provides no defense-in-depth for the lookup itself. For consistency and hardening, perform the lookup with `safeName` so the sanitized name is the single source of truth for both the lookup and the audit/log output.","suggestion_code":"const tool = this.registry.getForExecution(safeName);","existing_code":"const tool = this.registry.getForExecution(name);"}
{"path":"apps/server/src/agent-tools/agent-tool.executor.ts","start_line":244,"end_line":246,"category":"maintainability","severity":"low","content":"`sanitizeName` can return an empty string when the input is empty (e.g. `name === ''`), producing malformed audit entries such as ` [denied]` in `action`. Add an empty-result fallback so the audit trail always contains a meaningful, sanitized tool name.","suggestion_code":" if (TOOL_NAME_RE.test(trimmed)) return trimmed;\n // Replace unsafe chars with underscore\n const replaced = trimmed.replace(/[^a-zA-Z0-9_]/g, '_').slice(0, TOOL_NAME_MAX_LEN);\n return replaced || '_invalid';","existing_code":" if (TOOL_NAME_RE.test(trimmed)) return trimmed;\n // Replace unsafe chars with underscore\n return trimmed.replace(/[^a-zA-Z0-9_]/g, '_').slice(0, TOOL_NAME_MAX_LEN);"}
{"path":"apps/server/src/agent-tools/agent-tool.executor.ts","start_line":128,"end_line":130,"category":"security","severity":"low","content":"The response for an unknown tool (`'未知工具'`) is distinct from the response for an existing-but-unauthorized tool (`'权限不足'`). Even though both use the `denied` status, the differing `error` text lets a probing caller (e.g. an LLM or an authenticated user without the permission) enumerate which tool names are registered vs. merely forbidden. If tool-name enumeration is a concern, use the same generic message for both branches (or remove the distinct `unknownTool` message).","suggestion_code":null,"existing_code":" undefined,\n SAFE_MESSAGES.unknownTool,\n context,"}
{"path":"apps/server/src/agent-tools/tools/get-student-basic.tool.ts","start_line":47,"end_line":51,"category":"maintainability","severity":"low","content":"The FORBIDDEN_INPUT_KEYS check is fully redundant: the second `allowedKeys` loop below already rejects any key not in `{'studentId'}` — which includes every entry in FORBIDDEN_INPUT_KEYS (and more). The first loop can never reject a payload the second one would accept, so this is duplicate/dead validation logic. Keep only one validation path (the `allowedKeys` whitelist) and remove FORBIDDEN_INPUT_KEYS to avoid confusion about which check is authoritative.","suggestion_code":" // Unexpected keys (including sensitive ones) are rejected by the allowedKeys whitelist below.","existing_code":" for (const key of Object.keys(input)) {\n if (FORBIDDEN_INPUT_KEYS.has(key)) {\n return { ok: false, error: `不允许的输入字段: ${key}` };\n }\n }"}
{"path":"apps/server/src/agent-tools/tools/get-student-basic.tool.ts","start_line":57,"end_line":60,"category":"bug","severity":"medium","content":"`Number(input.studentId)` silently coerces non-number types: e.g. `{\"studentId\": true}` becomes 1, `{\"studentId\": [\"1\"]}` or `{\"studentId\": \"1\"}` become 1. Booleans/arrays should be rejected outright rather than coerced, otherwise a malformed LLM payload can unexpectedly read a different student. Since the schema declares `type: 'integer'`, validate the raw type before conversion.","suggestion_code":" if (typeof input.studentId !== 'number' || !Number.isInteger(input.studentId) || input.studentId <= 0) {\n return { ok: false, error: 'studentId 必须是正整数' };\n }\n const studentId = input.studentId;","existing_code":" const studentId = Number(input.studentId);\n if (!Number.isInteger(studentId) || studentId <= 0) {\n return { ok: false, error: 'studentId 必须是正整数' };\n }"}
{"path":"apps/server/src/agent-tools/tools/get-attendance-summary.tool.ts","start_line":25,"end_line":25,"category":"bug","severity":"low","content":"The `limit` contract is inconsistent: the JSON schema advertises `maximum: 50` (hardcoded again here as the second source of `50`), but when the field is omitted `optionalPositiveInt` returns `undefined` and the service silently applies its own default of 30 (`query.limit ?? 30` in attendance.service.ts). Callers who omit `limit` therefore receive fewer rows than the tool's advertised maximum, and the two hardcoded `50`s can drift apart. Suggest declaring `default: 30` (or 50) in `inputSchema` and applying the default here in `validate` (e.g. `limit: limit.value ?? 50`) so the tool's contract is explicit and matches downstream behavior.","suggestion_code":null,"existing_code":"const limit = optionalPositiveInt(raw.limit, 'limit', 50); if (!limit.ok) return limit;"}
{"path":"apps/server/src/agent-tools/tools/search-bills.tool.ts","start_line":20,"end_line":20,"category":"maintainability","severity":"medium","content":"limit 的 schema 上限和校验上限都是 50，但底层 agentSearchBills 在未传 limit 时默认只返回 20 条且没有分页/游标。LLM 不传 limit 时会把截断后的 20 条结果误认为全部匹配账单，导致后续判断/操作基于不完整数据。建议在 inputSchema 的 limit 属性中补充 description 说明默认值，或让未传时的默认行为与上限一致（例如默认也取 50）。","suggestion_code":null,"existing_code":"const limit = optionalPositiveInt(raw.limit, 'limit', 50); if (!limit.ok) return limit;"}
{"path":"apps/server/src/agent-tools/tools/search-bills.tool.ts","start_line":19,"end_line":19,"category":"maintainability","severity":"low","content":"schema 中各属性（keyword/status/periodStart/periodEnd）都没有 description，LLM 只能根据字段名和一行 tool description 猜测参数含义；status 仅按长度(20)校验，是自由字符串，模型猜错取值时会静默返回空结果。建议在 schema 中为 status 提供可选值说明（或确认 status 为自由字符串后接受此行为），并给其他属性补充简短描述以提升工具调用的准确率。","suggestion_code":null,"existing_code":"const status = optionalString(raw.status, 'status', 20); if (!status.ok) return status;"}
{"path":"apps/server/src/agent-tools/tools/search-classes.tool.ts","start_line":23,"end_line":23,"category":"bug","severity":"medium","content":"The `status` input is only checked for string length, but it is used to filter `class.status`, whose only valid values are the `ClassStatus` enum values (`enrolling` | `active` | `ended` | `suspended`, see `entities/class.entity.ts`). The inputSchema also gives the LLM no hint about allowed values (no enum/description), so the model can easily pass invalid values (e.g. `graduated`, `ENROLLING`) and silently get empty results instead of a clear validation error. Add an `enum` to the schema and validate the value against `ClassStatus` in `validate` (import it from `../../entities/class.entity`).","suggestion_code":"const status = optionalString(raw.status, 'status', 20); if (!status.ok) return status;\n if (status.value && !Object.values(ClassStatus).includes(status.value as ClassStatus)) {\n return { ok: false, error: 'status 必须是 enrolling/active/ended/suspended 之一' };\n }","existing_code":"const status = optionalString(raw.status, 'status', 20); if (!status.ok) return status;"}
{"path":"apps/server/src/agent-tools/tools/search-classroom-rentals.tool.ts","start_line":53,"end_line":53,"category":"maintainability","severity":"low","content":"The Boolean() coercion here is redundant: the type check above (`typeof raw.includeEnded !== 'boolean'` with early return) already guarantees that when `includeEnded` is present it is a boolean, so `Boolean(raw.includeEnded)` is an identity conversion. This can be simplified to just `raw.includeEnded` (TypeScript narrows it to `boolean | undefined` after the guard).","suggestion_code":" includeEnded: raw.includeEnded,","existing_code":" includeEnded: raw.includeEnded === undefined ? undefined : Boolean(raw.includeEnded),"}
{"path":"apps/server/src/agent-tools/tools/search-classroom-rentals.tool.ts","start_line":30,"end_line":30,"category":"maintainability","severity":"low","content":"The inputSchema declares `month` as a plain string with only a description, while `validate()` enforces the YYYY-MM format and a valid month range. Since the schema is likely consumed by agent/tooling to generate or pre-validate calls, it should declare the same constraint (e.g., `pattern: '^\\\\d{4}-\\\\d{2}$'`) so schema-level validation is consistent with the runtime validator.","suggestion_code":" month: { type: 'string', pattern: '^\\\\d{4}-\\\\d{2}$', description: 'YYYY-MM' },","existing_code":" month: { type: 'string', description: 'YYYY-MM' },"}
{"path":"apps/server/src/agent-tools/tools/search-rooms.tool.ts","start_line":10,"end_line":10,"category":"documentation","severity":"medium","content":"Description mismatch: this tool advertises '查询宿舍及床位占用数量' (returns room and bed occupancy counts), but the underlying agentSearchRooms (room-query.service.ts) only returns room metadata (id, roomNumber, building, floor, capacity, roomType, status) — no occupancy count fields at all. Occupancy numbers are provided by the separate GetRoomOccupancySummaryTool. Since the LLM agent relies on this description to decide which tool to call and what to expect, the misleading text will produce incorrect agent behavior. Suggest correcting it, e.g. '查询宿舍基本信息及状态，不返回住户资料和占用数。'.","suggestion_code":null,"existing_code":"readonly description = '查询宿舍及床位占用数量，不返回住户资料。';"}
{"path":"apps/server/src/agent-tools/tools/search-rooms.tool.ts","start_line":17,"end_line":17,"category":"maintainability","severity":"low","content":"The `status` parameter is accepted as an arbitrary string (maxLength 20) with no whitelist, yet the underlying rooms.status column is a free-form varchar (default 'available'). Any value outside the known set (e.g. 'occupied', 'archived') silently yields an empty result, and because valid statuses are not enumerated in the schema, the LLM agent has no way to know which values are usable. Consider constraining `status` to the known status values in inputSchema (and/or validating against them) so invalid input is rejected with a clear error instead of returning empty results.","suggestion_code":null,"existing_code":"const status = optionalString(raw.status, 'status', 20); if (!status.ok) return status;"}
{"path":"apps/server/src/ai-chat/ai-a2ui-submissions.service.ts","start_line":27,"end_line":29,"category":"bug","severity":"high","content":"TOCTOU race breaks the idempotency guarantee: `findSubmission` followed by `save` is not atomic. Under concurrent duplicate submissions (double-click / parallel retries with the same artifactId+clientRequestId), both requests can pass the existence check, and the second `save` will hit the unique index `uk_ai_a2ui_submissions_artifact_client`, throwing an unhandled duplicate-key error (QueryFailedError) and returning a 500 to the caller instead of the existing submission. Recommend an atomic upsert (e.g. `insert` with `ON DUPLICATE KEY`/`ON CONFLICT DO NOTHING` depending on DB) or catching the unique-violation error and re-reading the existing row in the conflict path.","suggestion_code":null,"existing_code":" const existing = await this.findSubmission(input.artifactId, input.clientRequestId);\n if (existing) return { created: false, submission: existing };\n const submission = await this.submissions.save("}
{"path":"apps/server/src/agent-tools/tools/search-expenses.tool.ts","start_line":37,"end_line":46,"category":"maintainability","severity":"low","content":"Minor contract inconsistency: the 3rd argument of `optionalPositiveInt` is the *maximum* (30), not a default. When the LLM omits `limit`, `limit.value` is `undefined` and is passed through unchanged, so the service silently falls back to its own default of 10 results — while the tool's `inputSchema` advertises a maximum of 30 with no mention of the effective default. The agent/model has no way to know results will be capped at 10 when `limit` is omitted. Suggest setting an explicit default in `validate` (e.g., `limit: limit.value ?? 10`) or documenting the default in the schema description so the tool's contract matches actual behavior.","suggestion_code":" const limit = optionalPositiveInt(raw.limit, 'limit', 30); if (!limit.ok) return limit;\n return {\n ok: true,\n value: {\n keyword: keyword.value,\n periodStart: periodStart.value,\n periodEnd: periodEnd.value,\n limit: limit.value ?? 10,\n },\n };","existing_code":" const limit = optionalPositiveInt(raw.limit, 'limit', 30); if (!limit.ok) return limit;\n return {\n ok: true,\n value: {\n keyword: keyword.value,\n periodStart: periodStart.value,\n periodEnd: periodEnd.value,\n limit: limit.value,\n },\n };"}
{"path":"apps/server/src/agent-tools/tools/search-exams.tool.ts","start_line":21,"end_line":24,"category":"maintainability","severity":"low","content":"The numeric constraints are hardcoded in two places that must stay in sync: the JSON schema exposed to the LLM (maxLength: 100/50, minimum: 1, maximum: 50) and the literal limits passed to optionalString/optionalPositiveInt in validate(). If one side is updated without the other (e.g. raising the schema maximum for `limit` without updating `optionalPositiveInt(raw.limit, 'limit', 50)`), input that is valid per the schema will be silently rejected at runtime. Suggest extracting module-level constants (e.g. `const LIMIT_MAX = 50`) and referencing them in both the schema and the validation calls.","suggestion_code":null,"existing_code":" limit: { type: 'integer', minimum: 1, maximum: 50 },\n },\n additionalProperties: false,\n };"}
{"path":"apps/server/src/agent-tools/tools/search-schedules.tool.ts","start_line":36,"end_line":40,"category":"maintainability","severity":"low","content":"The manual `weekDay` range check (`> 7`) duplicates functionality already provided by `optionalPositiveInt`'s `maximum` parameter (used for `limit`). It also makes the `!== undefined` guard unnecessary, since `undefined > 7` is `false` anyway. Simplify to `optionalPositiveInt(raw.weekDay, 'weekDay', 7)`, which produces the same behavior (rejects 0/negatives/8+) with a clearer error message and less code.","suggestion_code":" const weekDay = optionalPositiveInt(raw.weekDay, 'weekDay', 7);\n if (!weekDay.ok) return weekDay;","existing_code":" const weekDay = optionalPositiveInt(raw.weekDay, 'weekDay');\n if (!weekDay.ok) return weekDay;\n if (weekDay.value !== undefined && weekDay.value > 7) {\n return { ok: false, error: 'weekDay 必须在 1-7 之间' };\n }"}
{"path":"apps/server/src/agent-tools/tools/tool-input.ts","start_line":39,"end_line":40,"category":"bug","severity":"medium","content":"`Number(value)` performs very loose coercion on untrusted tool input: `true` → 1, `[5]` → 5, `\"1e2\"` → 100, `\"0x10\"` → 16 all pass as valid positive integers. Since these validators gate server-side tool execution, non-numeric types (booleans, arrays, objects, null) and non-canonical numeric strings should be rejected explicitly. Recommend a strict check, e.g. accept only `typeof value === 'number'` or a string matching `/^[1-9]\\d*$/` before converting.","suggestion_code":" const parsed =\n typeof value === 'number'\n ? value\n : typeof value === 'string' && /^[1-9]\\d*$/.test(value.trim())\n ? Number(value.trim())\n : NaN;\n if (!Number.isInteger(parsed) || parsed <= 0 || (maximum !== undefined && parsed > maximum)) {","existing_code":" const parsed = Number(value);\n if (!Number.isInteger(parsed) || parsed <= 0 || (maximum !== undefined && parsed > maximum)) {"}
{"path":"apps/server/src/agent-tools/tools/tool-input.ts","start_line":41,"end_line":41,"category":"bug","severity":"low","content":"The error message uses truthiness `maximum ? ...` while the validation above uses `maximum !== undefined`. If `maximum` is `0`, the constraint is applied in validation but silently omitted from the error message. Use `maximum !== undefined` for consistency.","suggestion_code":" return { ok: false, error: `${field} 必须是正整数${maximum !== undefined ? `且不超过${maximum}` : ''}` };","existing_code":" return { ok: false, error: `${field} 必须是正整数${maximum ? `且不超过${maximum}` : ''}` };"}
{"path":"apps/server/src/agent-tools/tools/tool-input.ts","start_line":27,"end_line":30,"category":"bug","severity":"low","content":"Length is checked on the raw value but the returned value is trimmed afterwards. This causes two inconsistencies: (1) a value like `\" ab \"` with maxLength 3 is rejected even though its trimmed form fits; (2) a whitespace-only string silently becomes `undefined` (treated as absent), which can mask a caller mistake. Trim first, then validate the trimmed length.","suggestion_code":" if (typeof value !== 'string') {\n return { ok: false, error: `${field} 必须是字符串` };\n }\n const trimmed = value.trim();\n if (trimmed.length > maxLength) {\n return { ok: false, error: `${field} 必须是长度不超过${maxLength}的字符串` };\n }\n return { ok: true, value: trimmed || undefined };","existing_code":" if (typeof value !== 'string' || value.length > maxLength) {\n return { ok: false, error: `${field} 必须是长度不超过${maxLength}的字符串` };\n }\n return { ok: true, value: value.trim() || undefined };"}
{"path":"apps/server/src/ai-chat/ai-a2ui.artifact.ts","start_line":21,"end_line":26,"category":"maintainability","severity":"medium","content":"The artifact type list is defined twice: once in the union type `A2uiArtifactType` and once in the `A2UI_ARTIFACT_TYPES` Set. This duplicates the source of truth and creates a drift risk — adding a type to the union but forgetting the Set makes `buildA2uiArtifact` throw at runtime, while adding to the Set only surfaces as call-site TS errors. Better to use a single const array and derive the union type from it, e.g.:\n\n```ts\nexport const A2UI_ARTIFACT_TYPES = ['form', 'review', 'chart', 'import_wizard'] as const;\nexport type A2uiArtifactType = (typeof A2UI_ARTIFACT_TYPES)[number];\n```\n\nand then `new Set(A2UI_ARTIFACT_TYPES)` if the Set is still needed.","suggestion_code":null,"existing_code":"const A2UI_ARTIFACT_TYPES = new Set([\n 'form',\n 'review',\n 'chart',\n 'import_wizard',\n]);"}
{"path":"apps/server/src/ai-chat/ai-a2ui.artifact.ts","start_line":42,"end_line":44,"category":"maintainability","severity":"low","content":"The runtime validation only covers `type`, not `status` (or `id`/`messageId`/`conversationId`). If this function can receive runtime data (e.g., from untyped sources), an invalid `status` would silently pass through and potentially break frontend normalization. For consistency, either validate `status` with its own allow-list (e.g., `new Set(['rendering', 'pending', 'submitted', 'expired', 'cancelled'])`) or drop the `type` check if all callers are guaranteed type-safe at compile time.","suggestion_code":null,"existing_code":" if (!A2UI_ARTIFACT_TYPES.has(input.type)) {\n throw new Error(`未知 A2UI artifact 类型: ${String(input.type)}`);\n }"}
{"path":"apps/server/src/agent-tools/tools/update-students.tool.ts","start_line":226,"end_line":238,"category":"performance","severity":"medium","content":"Student updates are executed strictly sequentially with `await` inside a `for` loop. These operations are independent of each other, so they can run in parallel. Given the batch supports up to 12 items, consider mapping each item to a promise (with per-item try/catch to preserve the partial-failure behavior) and awaiting them with `Promise.all` to cut the total latency to roughly the slowest single update instead of the sum.","suggestion_code":" const results = await Promise.all(\n input.updates.map(async (item) => {\n const { id: _id, ...rest } = item;\n const dto = rest as UpdateStudentDto;\n try {\n const student = await this.studentsService.update(item.id, dto);\n return { id: item.id, name: student?.name ?? null };\n } catch (error) {\n return {\n id: item.id,\n error: error instanceof NotFoundException ? '学生不存在' : '更新失败',\n };\n }\n }),\n );\n for (const r of results) {\n if ('error' in r) failed.push(r);\n else updated.push(r);\n }","existing_code":" for (const item of input.updates) {\n const { id: _id, ...rest } = item;\n const dto = rest as UpdateStudentDto;\n try {\n const student = await this.studentsService.update(item.id, dto);\n updated.push({ id: item.id, name: student?.name ?? null });\n } catch (error) {\n failed.push({\n id: item.id,\n error: error instanceof NotFoundException ? '学生不存在' : '更新失败',\n });\n }\n }"}
{"path":"apps/server/src/agent-tools/tools/update-students.tool.ts","start_line":169,"end_line":170,"category":"bug","severity":"medium","content":"`Number(raw.id)`/`Number(raw.organizationId)` coerces non-number values: `Number(true)` is `1` and `Number(['5'])` is `5`, so a boolean `true` or a single-element array would pass the “must be a positive integer” check and update student #1. Since `validate()` is the defense-in-depth gate (the schema may not always run first), require the raw value to be a real number instead of coercing it.","suggestion_code":" if (typeof raw.id !== 'number' || !Number.isInteger(raw.id) || raw.id <= 0) {\n return { ok: false, error: `第 ${index + 1} 条的学生 id 必须是正整数` };\n }\n const id = raw.id;","existing_code":" const id = Number(raw.id);\n if (!Number.isInteger(id) || id <= 0) {"}
{"path":"apps/server/src/agent-tools/tools/update-students.tool.ts","start_line":199,"end_line":200,"category":"bug","severity":"low","content":"The same coercion issue applies to `organizationId`: `Number(true)` → `1`, `Number(['5'])` → `5`, so invalid payloads (booleans, arrays) pass the check. Require a real number type here as well.","suggestion_code":" if (typeof raw.organizationId !== 'number' || !Number.isInteger(raw.organizationId) || raw.organizationId <= 0) {\n return { ok: false, error: `第 ${index + 1} 条的 organizationId 必须是正整数` };\n }\n const organizationId = raw.organizationId;","existing_code":" const organizationId = Number(raw.organizationId);\n if (!Number.isInteger(organizationId) || organizationId <= 0) {"}
{"path":"apps/server/src/agent-tools/tools/update-students.tool.ts","start_line":227,"end_line":227,"category":"other","severity":"low","content":"`_id` is destructured but never used — dead variable. Also note that `dto` built from `rest` is passed directly to `repo.update` in `StudentsService.update` without going through the DTO's class-validator pipeline, so any flaw in this whitelist would hit the DB directly; at minimum remove the unused binding to avoid confusion about intent.","suggestion_code":" const rest = { ...item };\n delete rest.id;","existing_code":" const { id: _id, ...rest } = item;"}
{"path":"apps/server/src/agent-tools/tools/update-students.tool.ts","start_line":77,"end_line":78,"category":"bug","severity":"low","content":"`optionalString` accepts a trimmed empty string (`''`), and `validate()` requires only “at least one editable field”, so a payload like `{ id: 1, name: '' }` passes validation and will write an empty `name` into the database (bypassing DTO validation as noted). If empty values are meant to clear optional fields (e.g. `emergencyPhone`) that is fine, but for required fields like `name`/`studentNo`/`idNumber` empty strings should be rejected to avoid corrupting required data.","suggestion_code":" const trimmed = value.trim();\n if (trimmed.length === 0) return { ok: false, error: '字段不能为空字符串' };\n if (trimmed.length > max) return { ok: false, error: `字段长度不能超过 ${max}` };","existing_code":" const trimmed = value.trim();\n if (trimmed.length > max) return { ok: false, error: `字段长度不能超过 ${max}` };"}
{"path":"apps/server/src/agent-tools/tools/search-students.tool.ts","start_line":92,"end_line":98,"category":"bug","severity":"medium","content":"Loose type coercion in numeric validation: `Number(input.classId)` silently accepts values that are clearly not valid per the declared schema (`type: 'integer'`), e.g. `classId: true` → 1, `classId: [5]` → 5, `classId: \"5\"` / `\"0x10\"` → 16. The same pattern applies to `organizationId` and `limit`. This makes the runtime validation inconsistent with `inputSchema` and lets malformed model output through instead of failing validation. If numeric strings are intentionally tolerated, reject booleans/arrays explicitly; otherwise require a real number to match the schema.","suggestion_code":" if (input.classId !== undefined) {\n if (typeof input.classId !== 'number' || !Number.isInteger(input.classId) || input.classId <= 0) {\n return { ok: false, error: 'classId 必须是正整数' };\n }\n result.classId = input.classId;\n }","existing_code":" if (input.classId !== undefined) {\n const id = Number(input.classId);\n if (!Number.isInteger(id) || id <= 0) {\n return { ok: false, error: 'classId 必须是正整数' };\n }\n result.classId = id;\n }"}
{"path":"apps/server/src/agent-tools/tools/search-students.tool.ts","start_line":66,"end_line":74,"category":"maintainability","severity":"low","content":"This FORBIDDEN_INPUT_KEYS loop is fully redundant: the `allowedKeys` whitelist loop right below already rejects every key not in the whitelist (including all of these forbidden keys) with the exact same error message. Maintaining two sources of truth for input key validation risks drift (e.g., a key added to `allowedKeys` but forgotten here). Either remove this block and the constant, or give it a distinct error message so it adds value as an explicit denial.","suggestion_code":null,"existing_code":" // Reject forbidden keys\n for (const key of Object.keys(input)) {\n if (FORBIDDEN_INPUT_KEYS.has(key)) {\n return {\n ok: false,\n error: `不允许的输入字段: ${key}`,\n };\n }\n }"}
{"path":"apps/server/src/ai-chat/ai-chat.constants.ts","start_line":92,"end_line":94,"category":"maintainability","severity":"medium","content":"The description states fields are limited to 1-12, but the JSON schema has no minItems/maxItems, so providers validating against this schema will accept any number of fields. An LLM can emit dozens/hundreds of fields, inflating request payloads and downstream storage. Add minItems: 1 and maxItems: 12 to enforce the documented bound.","suggestion_code":" fields: {\n type: 'array',\n description: '表单字段（1-12个）',\n minItems: 1,\n maxItems: 12,","existing_code":" fields: {\n type: 'array',\n description: '表单字段（1-12个）',"}
{"path":"apps/server/src/ai-chat/ai-chat.constants.ts","start_line":104,"end_line":106,"category":"maintainability","severity":"low","content":"The description says options are limited to 1-20, but no minItems/maxItems is declared. Add minItems: 1 and maxItems: 20 so the schema matches the documented contract and bounds the payload.","suggestion_code":" options: {\n type: 'array',\n description: 'select 类型的选项（1-20个）',\n minItems: 1,\n maxItems: 20,","existing_code":" options: {\n type: 'array',\n description: 'select 类型的选项（1-20个）',"}
{"path":"apps/server/src/ai-chat/ai-chat.constants.ts","start_line":143,"end_line":145,"category":"maintainability","severity":"low","content":"The description says columns are 2-10, but the schema has no minItems/maxItems. Add minItems: 2 and maxItems: 10 to enforce the documented bound.","suggestion_code":" columns: {\n type: 'array',\n description: '列定义（2-10个）：第一列为类别/名称，其余列为数值序列；饼图只用前两列（名称+数值）',\n minItems: 2,\n maxItems: 10,","existing_code":" columns: {\n type: 'array',\n description: '列定义（2-10个）：第一列为类别/名称，其余列为数值序列；饼图只用前两列（名称+数值）',"}
{"path":"apps/server/src/ai-chat/ai-chat.constants.ts","start_line":156,"end_line":158,"category":"maintainability","severity":"medium","content":"The description limits rows to ≤500, but no maxItems is declared. render_chart rows are the largest possible payload of the A2UI tools (and are persisted/rendered per round); without maxItems: 500 the schema accepts arbitrarily large row arrays, creating a resource/cost risk. Add maxItems: 500 to enforce the documented cap.","suggestion_code":" rows: {\n type: 'array',\n description: '行数据（≤500行，键名须与 columns.key 对应）',\n maxItems: 500,","existing_code":" rows: {\n type: 'array',\n description: '行数据（≤500行，键名须与 columns.key 对应）',"}
{"path":"apps/server/src/ai-chat/ai-chat.helpers.ts","start_line":3,"end_line":4,"category":"security","severity":"medium","content":"Redaction ordering bug: the phone-number rule runs before the ID-card rule, and the phone pattern `1[3-9]\\d{9}` has no word boundaries. An 18-digit Chinese ID card containing an 11-digit mobile-like substring (e.g. `110101199003078510` contains `19900307851`) will have those 11 digits replaced first, so the subsequent `\\b\\d{17}[\\dXx]\\b` pattern can no longer match the full card and the remaining digits leak into logs — defeating the purpose of this redaction function for the most sensitive PII. Fix by redacting ID cards first and/or anchoring the phone pattern with `\\b` (which also avoids mangling longer numeric fields such as account numbers).","suggestion_code":" .replace(/\\b\\d{17}[\\dXx]\\b/g, '[ID_CARD]')\n .replace(/\\b1[3-9]\\d{9}\\b/g, '[PHONE]')","existing_code":" .replace(/1[3-9]\\d{9}/g, '[PHONE]')\n .replace(/\\b\\d{17}[\\dXx]\\b/g, '[ID_CARD]')"}
{"path":"apps/server/src/ai-chat/ai-chat.helpers.ts","start_line":11,"end_line":13,"category":"maintainability","severity":"low","content":"The sensitive-key regex in this replacer is unanchored substring matching, so any key merely containing one of these words gets its whole value replaced. For example `tokenCount`, `phoneVerified`, or `mobileVersion` — which are typically benign counters/booleans, not secrets — will be rendered as `\"[REDACTED]\"`, corrupting log output and metrics. Consider matching exact key names (case-insensitive) or a small allowlist of known sensitive keys instead.","suggestion_code":null,"existing_code":" if (/password|token|secret|api.?key|authorization|phone|mobile|id.?card|身份证/i.test(key)) {\n return '[REDACTED]';\n }"}
{"path":"apps/server/src/ai-chat/ai-chat.import-confirm.ts","start_line":45,"end_line":46,"category":"bug","severity":"medium","content":"Header 值在判空时用了 trim()，但实际写入 mapping 并参与 `allowedHeaders.has(headerName)` 严格比较时使用的是未 trim 的 `header.slice(0, 200)`。如果确认方返回的表头带首尾空格（如 `\" 姓名 \"`），即使它对应的正是工作表表头也会被误判为“不在工作表表头中”而抛错。建议先 trim 再截断比较，同时落库的 headerName 也更干净。","suggestion_code":" if (typeof header !== 'string' || !header.trim()) continue;\n const headerName = header.trim().slice(0, 200);","existing_code":" if (typeof header !== 'string' || !header.trim()) continue;\n const headerName = header.slice(0, 200);"}
{"path":"apps/server/src/ai-chat/ai-chat.import-confirm.ts","start_line":40,"end_line":41,"category":"maintainability","severity":"low","content":"`Object.entries` 返回的 key 永远是 string，因此 `typeof field !== 'string'` 是恒为 false 的死分支。另外，`field.length > 50` 时直接静默 continue，与“未知字段直接抛错”的校验风格不一致——用户误传一个超长字段名会被静默丢弃（可能最终导致该阶段 mapping 为空），建议改为抛错或至少给出提示。","suggestion_code":" for (const [field, header] of Object.entries(fields as Record)) {\n if (!field.trim() || field.length > 50) continue;","existing_code":" for (const [field, header] of Object.entries(fields as Record)) {\n if (typeof field !== 'string' || !field.trim() || field.length > 50) continue;"}
{"path":"apps/server/src/ai-chat/ai-chat.import-confirm.ts","start_line":54,"end_line":54,"category":"bug","severity":"low","content":"当某个 step 的所有字段都被跳过（空 header / 超长字段等）时，仍会把空对象 `columnMapping = {}` 写入 `mapping[typedStepKey]`。下游若以“mapping 中是否包含该 stepKey”来判断该阶段是否已确认映射，空对象会被误认为已确认。建议仅在 columnMapping 非空时才写入。","suggestion_code":" if (Object.keys(columnMapping).length > 0) mapping[typedStepKey] = columnMapping;","existing_code":" mapping[typedStepKey] = columnMapping;"}
{"path":"apps/server/src/ai-chat/ai-chat.import-confirm.ts","start_line":95,"end_line":97,"category":"bug","severity":"low","content":"`attachment.mimeType.includes(...)` 直接调用，若调用方传入的 attachment.mimeType 为 undefined/null（例如来自部分解析的数据或 DB 可空列），会抛 TypeError 而不是返回 false。建议对 mimeType 做空值保护。","suggestion_code":" attachment.mimeType?.includes('spreadsheetml') ||\n attachment.mimeType?.includes('excel') ||\n attachment.mimeType?.includes('csv') ||","existing_code":" attachment.mimeType.includes('spreadsheetml') ||\n attachment.mimeType.includes('excel') ||\n attachment.mimeType.includes('csv') ||"}
{"path":"apps/server/src/ai-chat/ai-chat.controller.ts","start_line":320,"end_line":323,"category":"bug","severity":"medium","content":"If `execute` resolves successfully without ever calling `onReady` (headers never sent), the `finally` block only finalizes the response when `res.headersSent` is true. In the success-without-stream path nothing is written and the response is left dangling — the client hangs indefinitely with no data and no error, and the socket is only reclaimed by server timeouts. The rethrow path in `catch` only covers errors, not this case. Add a `started` flag set in `onReady` and after `await execute(...)` throw if the stream never started so the error propagates to the global exception filter (which will write a proper response since headers aren't sent yet).","suggestion_code":" try {\n await execute(abortController.signal, emit, onReady);\n if (!res.headersSent) {\n throw new Error('AI stream finished without starting the response');\n }\n } catch (error) {\n if (!res.headersSent) throw error;","existing_code":" try {\n await execute(abortController.signal, emit, onReady);\n } catch (error) {\n if (!res.headersSent) throw error;"}
{"path":"apps/server/src/ai-chat/ai-chat.controller.ts","start_line":130,"end_line":130,"category":"bug","severity":"medium","content":"`stream.pipe(res)` has no error handler on the read stream. If the underlying file is missing/corrupt (e.g. the file on disk was removed while the DB row still exists, or a storage failure occurs), `createReadStream` emits an async 'error' event which is not handled — the pipe stalls and the client hangs until a server-level timeout, with no error response. Attach a `stream.on('error', ...)` handler that logs and destroys/ends the response appropriately.","suggestion_code":" stream.on('error', () => {\n if (!res.headersSent) {\n res.status(500).end();\n } else {\n res.destroy();\n }\n });\n stream.pipe(res);","existing_code":" stream.pipe(res);"}
{"path":"apps/server/src/ai-chat/ai-chat.controller.ts","start_line":346,"end_line":346,"category":"security","severity":"low","content":"For HTTP 4xx/5xx upstream errors, `error.message` is forwarded verbatim to the SSE client. Upstream/AI service messages may contain internal implementation details (host paths, model names, stack traces, database errors) that should not be exposed to end users. Return a generic user-facing message and log the real error server-side instead.","suggestion_code":" if (status >= 500) return { code: 'UPSTREAM_ERROR', message: 'AI 服务暂时不可用' };","existing_code":" if (status >= 500) return { code: 'UPSTREAM_ERROR', message: error.message };"}
{"path":"apps/server/src/ai-chat/ai-chat.conversations.ts","start_line":58,"end_line":59,"category":"bug","severity":"medium","content":"TOCTOU race between the in-memory `activeConversations` check and the actual deletion. After the check there are several `await`s (attachment query, `conversations.remove`), during which a concurrently starting generation can call `acquireConversation` (which adds the id to the set synchronously) and begin writing messages to the conversation that is about to be deleted. This can result in FK errors or silently losing in-flight generation data. The same unsafe check-then-delete pattern exists in `deleteAllConversations` and `deleteMessage`. Consider re-verifying the set right before removal (and/or after the awaits) or guarding deletion with a DB-level lock/transaction.","suggestion_code":null,"existing_code":" if (context.activeConversations.has(id)) throw new ConflictException('该会话正在生成回答');\n const attachmentIds = await context.messages"}
{"path":"apps/server/src/ai-chat/ai-chat.conversations.ts","start_line":82,"end_line":89,"category":"maintainability","severity":"low","content":"The attachment-id collection query is duplicated three times (`deleteConversation`, `deleteAllConversations`, `deleteMessage`). Extract a shared helper such as `collectAttachmentIds(context, messageIds)` so that table names, the raw-to-number mapping and join logic stay in sync if they ever change.","suggestion_code":null,"existing_code":" const attachmentIds = await context.messages\n .createQueryBuilder('message')\n .innerJoin('message.attachments', 'attachment')\n .where('message.conversation_id IN (:...ids)', {\n ids: conversations.map((item) => item.id),\n })\n .select('attachment.id', 'id')\n .getRawMany<{ id: number }>();"}
{"path":"apps/server/src/ai-chat/ai-chat.conversations.ts","start_line":111,"end_line":112,"category":"bug","severity":"low","content":"`page` and `limit` are taken from user input without validation. `page = 0` (or negative) produces a negative `skip`, which TypeORM rejects or handles unpredictably (500 error), and a very large `limit` can cause an unbounded/heavy query. Clamp the values, e.g. `page = Math.max(1, page)` and `limit = Math.min(100, Math.max(1, limit))`.","suggestion_code":" skip: (Math.max(1, page) - 1) * Math.min(100, Math.max(1, limit)),\n take: Math.min(100, Math.max(1, limit)),","existing_code":" skip: (page - 1) * limit,\n take: limit,"}
{"path":"apps/server/src/ai-chat/ai-chart.service.ts","start_line":66,"end_line":68,"category":"bug","severity":"low","content":"When `rows` is missing or not an array (e.g. the model omits it or sends an object/string), this branch throws with the misleading message \"图表行数不能超过 500\", and an empty array `[]` is silently accepted (chart with no data). Suggest splitting the two cases: reject non-array/missing `rows` with a \"必须是数组\" message and reject only length overflow with the current message (same applies to the `columns` check above).","suggestion_code":null,"existing_code":" if (!Array.isArray(rawArgs.rows) || rawArgs.rows.length > MAX_ROWS) {\n throw new BadRequestException(`图表行数不能超过 ${MAX_ROWS}`);\n }"}
{"path":"apps/server/src/ai-chat/ai-chart.service.ts","start_line":78,"end_line":78,"category":"security","severity":"low","content":"The guard `isPlainRecord` only checks `typeof === 'object' && !Array.isArray`, so class instances, `Date`, `Map`, and objects created with a custom/null prototype also pass as \"plain records\". Since this input is untrusted AI-generated tool-arguments, the row/column validation here can be bypassed by non-plain objects (they are then silently treated as empty via `Object.entries`). Recommend a stricter check at the usage site, e.g. `Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null`.","suggestion_code":null,"existing_code":" if (!isPlainRecord(raw)) throw new BadRequestException(`图表第 ${index + 1} 行格式无效`);"}
{"path":"apps/server/src/ai-chat/ai-chart.service.ts","start_line":44,"end_line":46,"category":"bug","severity":"medium","content":"Only the scatter column count is special-cased. Other chart types pass through with arbitrary column counts and arbitrary cell values: e.g. a `pie`/`gauge` with 3+ columns, or a `line`/`bar`/`scatter` whose value columns contain strings/booleans/null, will pass validation and can break the frontend ECharts conversion this service is meant to protect. Consider per-chart-type shape checks (e.g. pie/gauge exactly 2 columns) and enforcing that value columns are numeric for numeric chart types.","suggestion_code":null,"existing_code":" if (rawArgs.chartType === 'scatter' && rawArgs.columns.length < 3) {\n throw new BadRequestException('散点图需要 3 列：名称、X 数值、Y 数值');\n }"}
{"path":"apps/server/src/ai-chat/ai-attachment.service.ts","start_line":133,"end_line":133,"category":"maintainability","severity":"low","content":"`Repository.findByIds()` is deprecated in TypeORM 0.3.x and will be removed. Use the explicit query form with `In(uniqueIds)` instead so the query also filters by userId in one round trip.","suggestion_code":" const attachments = await this.attachments.find({ where: { id: In(uniqueIds) } });","existing_code":" const attachments = await this.attachments.findByIds(uniqueIds);"}
{"path":"apps/server/src/ai-chat/ai-attachment.service.ts","start_line":111,"end_line":115,"category":"performance","severity":"low","content":"The per-attachment DB removal and file unlink are independent operations; running them sequentially in a loop serializes I/O. Since the operations don't depend on each other's results, use Promise.all to process them in parallel (still skipping attachments bound to messages).","suggestion_code":" await Promise.all(\n attachments\n .filter((attachment) => !attachment.messages?.length)\n .map(async (attachment) => {\n await this.attachments.remove(attachment);\n await unlink(this.resolveStoragePath(attachment.storageKey)).catch(() => undefined);\n }),\n );","existing_code":" for (const attachment of attachments) {\n if (attachment.messages?.length) continue;\n await this.attachments.remove(attachment);\n await unlink(this.resolveStoragePath(attachment.storageKey)).catch(() => undefined);\n }"}
{"path":"apps/server/src/ai-chat/ai-attachment.service.ts","start_line":49,"end_line":49,"category":"maintainability","severity":"low","content":"The 10MB limit is defined here as MAX_FILE_BYTES but the enforcement at the transport layer (the controller's `FileInterceptor` `limits.fileSize`) is a separate hardcoded `10 * 1024 * 1024`. These two values can drift over time, causing the in-memory buffer check to disagree with what multer actually accepts. Export a shared constant (e.g. from a common module) and reference it in both places.","suggestion_code":null,"existing_code":" if (file.size > MAX_FILE_BYTES) throw new BadRequestException('单个附件不能超过 10MB');"}
{"path":"apps/server/src/ai-chat/ai-attachment.service.ts","start_line":181,"end_line":181,"category":"maintainability","severity":"low","content":"The attachment URL is hardcoded here. If the route in the controller ever changes (prefix, version, module path), this serialized payload silently points clients at a 404. Derive the path from the controller route or a shared route constant instead of duplicating the string.","suggestion_code":null,"existing_code":" url: `/api/ai/chat/attachments/${attachment.id}`,"}
{"path":"apps/server/src/ai-chat/ai-attachment.service.ts","start_line":89,"end_line":94,"category":"maintainability","severity":"low","content":"If this final `save` throws (e.g. transient DB failure), the file already written to disk is never cleaned up (the try/catch + unlink only guards the first save) and the DB record stays in 'processing' status, producing a permanent orphan until something explicitly removes it. Consider wrapping the post-extraction save so a failure unlinks the file (and ideally deletes the stale record), matching the cleanup done for the first save.","suggestion_code":null,"existing_code":" } catch {\n entity.processingStatus = 'failed';\n entity.processingError = '文件内容解析失败';\n }\n entity = await this.attachments.save(entity);\n return entity;"}
{"path":"apps/server/src/ai-chat/ai-chat.service-base.ts","start_line":85,"end_line":89,"category":"maintainability","severity":"medium","content":"`attachments: any[]` uses `any` without justification, which violates the project rule to avoid `any` and also diverges from the typed contract: `AiChatServiceContext` in `ai-chat.types.ts` and the concrete override in `ai-chat.service.ts` both declare `attachments: AiAttachment[]`. Using `any` here silently disables type checking for all callers/subclasses of this abstract method. Suggest typing it as `AiAttachment[]` (imported from `./entities`).","suggestion_code":" abstract buildUserContent(\n text: string,\n attachments: AiAttachment[],\n supportsVision: boolean,\n ): Promise;","existing_code":" abstract buildUserContent(\n text: string,\n attachments: any[],\n supportsVision: boolean,\n ): Promise;"}
{"path":"apps/server/src/ai-chat/ai-chat.generation.ts","start_line":85,"end_line":89,"category":"maintainability","severity":"low","content":"Nested ternary expression is used to pick `modelFocusContent`. The review rules prohibit nested ternaries as they hurt readability. Consider extracting this into a small helper function with early returns, e.g. `if (formSubmit) return buildFormSubmitModelContent(formSubmit); if (reviewSubmit) return buildReviewSubmitModelContent(reviewSubmit); return focusContent;`.","suggestion_code":null,"existing_code":" const modelFocusContent = formSubmit\n ? buildFormSubmitModelContent(formSubmit)\n : reviewSubmit\n ? buildReviewSubmitModelContent(reviewSubmit)\n : focusContent;"}
{"path":"apps/server/src/ai-chat/ai-chat.generation.ts","start_line":64,"end_line":78,"category":"maintainability","severity":"low","content":"The tool-name allowlist/denylist is duplicated across two `filter` blocks and relies on hardcoded string literals (`create_student`, `update_students`, `render_form`, `start_import_wizard`). These tool names are business-critical; if a tool is renamed the filter silently stops working. Extract the excluded tool names into a shared constant and consolidate the two filters into one (e.g. a single helper that computes the excluded set based on `formSubmit`/`reviewSubmit`).","suggestion_code":null,"existing_code":" if (!formSubmit && !reviewSubmit) {\n tools = tools.filter(\n (tool) =>\n tool.function.name !== 'create_student' && tool.function.name !== 'update_students',\n );\n }\n if (reviewSubmit) {\n tools = tools.filter(\n (tool) =>\n tool.function.name !== 'create_student' &&\n tool.function.name !== 'update_students' &&\n tool.function.name !== 'render_form' &&\n tool.function.name !== 'start_import_wizard',\n );\n }"}
{"path":"apps/server/src/ai-chat/ai-chat.generation.ts","start_line":151,"end_line":152,"category":"performance","severity":"low","content":"Tool calls within a round are awaited sequentially even though they are independent (each call is executed based on its own parsed arguments). In a loop that can run up to `MAX_TOOL_ROUNDS` times, this serializes potentially slow tool executions and adds latency per round. Consider `Promise.all` for parallel execution (tool run records are later re-sorted by `id`, so persistence order stays deterministic); only keep sequential execution if the ordering of the per-tool SSE events (`tool.completed`/`tool.failed`) must be guaranteed.","suggestion_code":null,"existing_code":" for (const call of toolCalls) {\n const toolResult = await executeTool("}
{"path":"apps/server/src/ai-chat/ai-chat.service.ts","start_line":110,"end_line":116,"category":"maintainability","severity":"low","content":"`summarize` and `safeStructured` duplicate the same `JSON.stringify(value, this.redactingReplacer)` + try/catch pattern. Both also swallow the serialization error silently (returning a sentinel value without any log), which makes failures such as circular references or BigInt values (`TypeError: Do not know how to serialize a BigInt`) impossible to diagnose in production. Consider extracting a shared private helper (e.g. `stringifySafely`) and logging the caught error before returning the fallback.","suggestion_code":null,"existing_code":" let json: string;\n try {\n json = JSON.stringify(value, this.redactingReplacer);\n } catch {\n return '[无法序列化]';\n }\n return this.redactText(json).slice(0, 2000);"}
{"path":"apps/server/src/ai-chat/ai-chat.service.ts","start_line":116,"end_line":116,"category":"bug","severity":"low","content":"`slice(0, 2000)` truncates the serialized string by UTF-16 code units, which can split a surrogate pair in the middle and leave an unpaired/invalid character in the summary. Since the same pattern (`safeStructured`) round-trips through `JSON.parse`, a truncated `summarize` output is also not guaranteed to be valid JSON if ever re-parsed. For a code-point-safe truncation, consider slicing with `Array.from(json)` (or `Intl.Segmenter`) instead.","suggestion_code":null,"existing_code":" return this.redactText(json).slice(0, 2000);"}
{"path":"apps/server/src/ai-chat/ai-chat.submissions.runtime.ts","start_line":19,"end_line":19,"category":"maintainability","severity":"medium","content":"`attachments` is typed as `any[]`, violating the project rule against the `any` type without justification. The entity relation is typed `AiAttachment[]` (ManyToMany), so passing `any[]` here bypasses type safety and hides invalid attachment shapes at the call sites. Import `AiAttachment` from `./entities` and use `AiAttachment[]`.","suggestion_code":" attachments?: AiAttachment[],","existing_code":" attachments?: any[],"}
{"path":"apps/server/src/ai-chat/ai-chat.submissions.runtime.ts","start_line":32,"end_line":32,"category":"bug","severity":"low","content":"The spread `{ clientRequestId, skillKey, ...metadata }` puts `metadata` last, so any caller-supplied metadata containing `clientRequestId` or `skillKey` silently overrides the explicitly passed parameters. This can make the persisted user-message metadata diverge from the assistant message's metadata (which is stored as `{ clientRequestId, skillKey }`), causing mismatched/duplicated request identifiers. Spread `metadata` first so the explicit arguments take precedence.","suggestion_code":" metadata: { ...metadata, clientRequestId, skillKey },","existing_code":" metadata: { clientRequestId, skillKey, ...metadata },"}
{"path":"apps/server/src/ai-chat/ai-chat.submissions.ts","start_line":3,"end_line":10,"category":"maintainability","severity":"low","content":"Duplicate logic: `resolveFormConversationId` and `resolveReviewConversationId` are structurally identical (`await service.findOwnedPending(id, userId)` then return `.conversationId`). The same `findOwnedPending` + `.conversationId` lookup is also repeated inline in `submitForm`/`submitReview` in `ai-chat.submissions.flow.ts`. Consider extracting a small shared helper (e.g. `resolveOwnedConversationId(find: () => Promise<{ conversationId: number }>)`) so the lookup/ownership semantics stay consistent in one place.","suggestion_code":"async function resolveOwnedConversationId(\n find: () => Promise<{ conversationId: number }>,\n): Promise {\n const owned = await find();\n return owned.conversationId;\n}\n\nexport async function resolveFormConversationId(\n context: AiChatServiceContext,\n userId: number,\n formId: string,\n): Promise {\n return resolveOwnedConversationId(() =>\n context.formService.findOwnedPending(formId, userId),\n );\n}","existing_code":"export async function resolveFormConversationId(\n context: AiChatServiceContext,\n userId: number,\n formId: string,\n): Promise {\n const form = await context.formService.findOwnedPending(formId, userId);\n return form.conversationId;\n}"}
{"path":"apps/server/src/ai-chat/ai-chat.review-confirm.ts","start_line":115,"end_line":115,"category":"bug","severity":"medium","content":"`confirmReviewGroup` reports success and writes a hardcoded `status: 'success'` op-log entry even when no section was actually imported. The underlying `submitGroup` deliberately swallows per-section errors (persistent failures) and returns the review unchanged when every section in the group is already submitted or all submissions failed. The handler never verifies that at least one section transitioned to `submitted`, so the API returns 200 and logs \"成功\" for a failed/no-op confirm. Verify the resulting group sections before returning success (e.g., throw a ConflictException when none were newly confirmed), and derive the log status from the actual outcome.","suggestion_code":" const { review: updated } = await context.reviewService.submitGroup(review.id, user.id, type);\n const groupSections = context.reviewService\n .parseSections(updated.sectionsJson)\n .filter((section) => section.type === type);\n if (groupSections.length > 0 && groupSections.every((section) => section.status !== 'submitted')) {\n throw new ConflictException(`分组「${type}」没有可确认的分表，请查看分表失败原因`);\n }","existing_code":" const { review: updated } = await context.reviewService.submitGroup(review.id, user.id, type);"}
{"path":"apps/server/src/ai-chat/ai-chat.review-confirm.ts","start_line":23,"end_line":32,"category":"bug","severity":"medium","content":"`finalizeReview` runs after the import transaction has already committed, but it performs best-effort side effects (`markReviewSubmittedOnMessage` — a message findOne+save — plus `serialize`) that can still throw. If any of these fail, the request returns an error for an import that actually succeeded, and the client's retry then hits `分表已确认导入` (409) — a confusing and inconsistent user experience. The same applies to `logImportOp` failures in both handlers. Wrap the post-commit message-metadata sync and op-log write in try/catch so a best-effort sync failure cannot misreport a committed import as failed.","suggestion_code":"async function finalizeReview(\n context: AiChatServiceContext,\n updated: AiReview,\n): Promise> {\n try {\n await context.markReviewSubmittedOnMessage(\n updated.assistantMessageId,\n updated.conversationId,\n updated,\n );\n } catch {\n // 消息元数据同步为尽力而为，导入已提交，不影响返回结果\n }\n return context.reviewService.serialize(updated);","existing_code":"async function finalizeReview(\n context: AiChatServiceContext,\n updated: AiReview,\n): Promise> {\n await context.markReviewSubmittedOnMessage(\n updated.assistantMessageId,\n updated.conversationId,\n updated,\n );\n return context.reviewService.serialize(updated);"}
{"path":"apps/server/src/ai-chat/ai-chat.review-confirm.ts","start_line":59,"end_line":64,"category":"maintainability","severity":"low","content":"The `sectionPermission` map is rebuilt on every invocation of `assertReviewImportPermissions`, even though it is constant. Hoist it to module scope so it is allocated once.","suggestion_code":"const SECTION_PERMISSIONS: Record = {\n students: 'student:create',\n rooms: 'room:create',\n transfers: 'occupancy:transfer',\n checkins: 'occupancy:checkin',\n};","existing_code":" const sectionPermission: Record = {\n students: 'student:create',\n rooms: 'room:create',\n transfers: 'occupancy:transfer',\n checkins: 'occupancy:checkin',\n };"}
{"path":"apps/server/src/ai-chat/ai-chat.review-confirm.ts","start_line":14,"end_line":19,"category":"maintainability","severity":"low","content":"The `submitted`/`expired` status checks here are duplicated inside `submitSection`/`submitGroup` (where they are re-evaluated inside a transaction). Because this pre-check is not atomic with the subsequent confirm, it can go stale under concurrent requests (e.g., a second request may pass the check and then receive the 409 from the transaction-level check). It only serves as early feedback, so keep it in sync with the service-layer checks to avoid error-message drift if statuses change.","suggestion_code":null,"existing_code":" if (review.status === 'submitted') {\n throw new ConflictException('导入已全部确认，无需重复确认');\n }\n if (review.status === 'expired') {\n throw new ConflictException('导入预览已失效，请重新生成预览');\n }"}
{"path":"apps/server/src/ai-chat/ai-chat.submissions.flow.ts","start_line":144,"end_line":150,"category":"maintainability","severity":"low","content":"Nested ternary expression (`type === 'students' ? 'profile' : type === 'rooms' ? 'room' : 'checkin'`) violates the project rule that nested ternaries are not allowed. Extract to a small mapping function or if/else chain for readability.","suggestion_code":" sectionTypes.map((type) => {\n if (type === 'students') return 'profile';\n if (type === 'rooms') return 'room';\n return 'checkin';\n }),","existing_code":" sectionTypes.map((type) =>\n type === 'students'\n ? 'profile'\n : type === 'rooms'\n ? 'room'\n : 'checkin',\n ),"}
{"path":"apps/server/src/ai-chat/ai-chat.submissions.flow.ts","start_line":191,"end_line":193,"category":"maintainability","severity":"low","content":"`onReady` is invoked explicitly here and then passed to `runGenerationAndRelease`, which calls `executeGeneration` — and `executeGeneration` calls `onReady()` again at its start. The controller's `onReady` is guarded by `res.headersSent`, so the second call is a no-op today, but this double-invocation is fragile (any future change that removes the guard will fire it twice) and inconsistent with `submitForm`, which only passes `onReady` through. Keep only one path for invoking `onReady`.","suggestion_code":null,"existing_code":" const serialized = context.reviewService.serialize(updatedReview);\n onReady();\n emit('ui.artifact', {"}
{"path":"apps/server/src/ai-chat/ai-chat.submissions.flow.ts","start_line":134,"end_line":137,"category":"bug","severity":"medium","content":"Non-atomic confirmation flow: `submitAll` (the actual data import) runs outside the `persistExchange` transaction, and `recordSubmission` persists a `created` record up front that is never updated to a failed/completed state on any later failure. If `submitAll` succeeds but `persistExchange` (or `markReviewSubmittedOnMessage`) throws, the review data is already imported while the conversation message is missing, and any retry with the same `clientRequestId` is rejected as a duplicate (\"该导入预览已确认过\"), wedging the artifact. `submitForm` has the same pattern (`markSubmitted`/`markFormSubmittedOnMessage` run after the transaction commits). Consider wrapping the artifact state change + exchange persistence in one transaction and updating the submission record's status (or deleting it) on failure so a partial failure can be retried consistently.","suggestion_code":null,"existing_code":" const { review: updatedReview, result } = await context.reviewService.submitAll(\n review.id,\n user.id,\n );"}
{"path":"apps/server/src/ai-chat/ai-chat.submissions.flow.ts","start_line":105,"end_line":105,"category":"maintainability","severity":"medium","content":"`submitForm` and `submitReview` share a large amount of duplicated logic: fetching the owned pending artifact, `requireOwnedConversation`, computing `effectiveSkillKey`, `assertSkillAvailable`, `recordSubmission` + duplicate-check, `acquireConversation` + try/finally cleanup, `persistExchange` with the `DEFAULT_TITLE` title update, `emit('ui.artifact')`, and the final `runGenerationAndRelease`. This duplication makes it easy for fixes to one flow to miss the other (e.g., the inconsistent `onReady` handling). Consider extracting a shared helper (e.g., a generic `runSubmission` that takes the artifact-specific steps as callbacks).","suggestion_code":null,"existing_code":"export async function submitReview("}
{"path":"apps/server/src/ai-chat/ai-chat.submit-content.ts","start_line":49,"end_line":56,"category":"bug","severity":"medium","content":"This function performs DB I/O (findOne + save) without any error handling, yet it is awaited by callers after the submission transaction has already been committed (e.g., ai-chat.submissions.flow.ts:74). If the save throws (transient DB error, constraint conflict) the whole request fails for the user even though the form submission already succeeded. Also, when the assistant message is not found the function silently no-ops and the stored message metadata is never marked 'submitted', leaving it inconsistent with the emitted ui.artifact. Since this is best-effort bookkeeping, wrap the read/write in try/catch with logging (or return a boolean indicating whether the mark was applied) so failures here cannot break the completed submission flow.","suggestion_code":null,"existing_code":"export async function markFormSubmittedOnMessage(\n context: AiChatServiceContext,\n assistantMessageId: number,\n conversationId: number,\n): Promise {\n const assistant = await context.messages.findOne({\n where: { id: assistantMessageId, conversationId },\n });"}
{"path":"apps/server/src/ai-chat/ai-chat.submit-content.ts","start_line":108,"end_line":116,"category":"bug","severity":"medium","content":"Same robustness issue as markFormSubmittedOnMessage: this function is awaited (ai-chat.submissions.flow.ts:204, ai-chat.review-confirm.ts:27) after the review/import side effects have already been persisted, and an unhandled save error here will surface a failure response to the user despite the operation having succeeded. Additionally, in the review-provided branch the whole a2uiReview object is replaced by serialize(review), which will also drop any previously stored metadata keys on that object that are not part of the serialized shape. Consider guarding the read-modify-write with try/catch + logging.","suggestion_code":null,"existing_code":"export async function markReviewSubmittedOnMessage(\n context: AiChatServiceContext,\n assistantMessageId: number,\n conversationId: number,\n review?: AiReview,\n): Promise {\n const assistant = await context.messages.findOne({\n where: { id: assistantMessageId, conversationId },\n });"}
{"path":"apps/server/src/ai-chat/ai-chat.submit-content.ts","start_line":46,"end_line":46,"category":"maintainability","severity":"low","content":"The truncation limit '32 * 1024' is a hard-coded magic number and String.prototype.slice operates on UTF-16 code units, so truncation can split a surrogate pair (e.g., emoji in submitted values) and can cut JSON mid-structure, producing a malformed snippet in the model prompt. Meanwhile fieldErrors is serialized with no length cap at all, so an oversized fieldErrors array can push the prompt over the context limit. Suggest extracting a named constant (e.g., MAX_JSON_SNIPPET) and applying the same truncation/length guard to fieldErrors; wrapping its JSON.stringify in try/catch would also make it consistent with the guarded submit.values serialization.","suggestion_code":null,"existing_code":" return `【表单提交：${submit.title}】${submissionId}\\n提交值（JSON）：${json.slice(0, 32 * 1024)}${fieldErrors}\\n用户已在表单中确认，你可以执行允许的写操作工具。`;"}
{"path":"apps/server/src/ai-chat/ai-chat.streaming.ts","start_line":256,"end_line":263,"category":"bug","severity":"medium","content":"The transaction commits destructive changes (editing the target user message and deleting ALL later messages) before generation runs. The subsequent `context.conversations.update` and `removeOrphans` calls run outside the transaction: if either throws, or the process crashes after commit, the conversation is left with its history irrecoverably truncated plus a dangling 'pending' assistant message, and the client receives an error with no generation ever started. Consider moving the conversation title/lastMessageAt update into the same transaction (using `manager.update`), and making the orphan cleanup best-effort (catch/log) so a file-cleanup failure cannot block generation.","suggestion_code":null,"existing_code":" await context.conversations.update(\n { id: conversationId, userId: user.id },\n {\n lastMessageAt: now,\n ...(conversation.title === oldTitleHint ? { title: context.titleFromMessage(content) } : {}),\n },\n );\n await context.attachmentService.removeOrphans(user.id, orphanAttachmentIds);"}
{"path":"apps/server/src/ai-chat/ai-chat.streaming.ts","start_line":295,"end_line":295,"category":"bug","severity":"medium","content":"Messages whose `status !== 'completed'` (e.g., pending/cancelled assistant rows left behind by interrupted generations) are skipped in the loop, yet they still occupy one slot of the `take: MAX_HISTORY_MESSAGES + 1` fetch window. In a long conversation with several interrupted regenerations, older completed messages beyond the window are never fetched, so the effective model context silently shrinks well below MAX_HISTORY_MESSAGES. Filter completed messages in the query itself (or fetch a larger window) so skipped rows don't displace real history.","suggestion_code":" where: { conversationId, id: LessThanOrEqual(focusUserMessageId), status: 'completed' },\n relations: { attachments: true },\n order: { createdAt: 'DESC', id: 'DESC' },\n take: MAX_HISTORY_MESSAGES + 1,","existing_code":" take: MAX_HISTORY_MESSAGES + 1,"}
{"path":"apps/server/src/ai-chat/ai-chat.streaming.ts","start_line":337,"end_line":337,"category":"bug","severity":"low","content":"All attachment text (including the `[图片附件：…]`/`[附件：…]` markers) is merged into a single leading text part while every image is appended afterwards, destroying the original interleaving order of text and images in multi-part attachments (e.g., a scanned multi-page document where each page's OCR text should sit next to its image). The model receives all page texts before any image, which can degrade multimodal reasoning. Consider emitting text/image parts in their original sequence (one content part per attachment item) instead of collecting all text first.","suggestion_code":null,"existing_code":" return [{ type: 'text', text: combinedText }, ...contentParts];"}
{"path":"apps/server/src/ai-chat/ai-chat.streaming.ts","start_line":63,"end_line":63,"category":"maintainability","severity":"low","content":"Minor inconsistency: the persisted user content uses `dto.message.trim()`, but the auto-generated title uses the untrimmed `dto.message`. If the input has leading/trailing whitespace, the title may retain it while the stored content does not. Use the trimmed value consistently.","suggestion_code":" conversation.title === DEFAULT_TITLE ? context.titleFromMessage(dto.message.trim()) : undefined,","existing_code":" conversation.title === DEFAULT_TITLE ? context.titleFromMessage(dto.message) : undefined,"}
{"path":"apps/server/src/ai-chat/ai-review.enrich.ts","start_line":7,"end_line":9,"category":"bug","severity":"medium","content":"Organization IDs are only resolved when `raw` is an actual JS number, but the caller passes `row.organization` from AI-extracted rows (`ai-review.import-basic.ts` line 37), where values are typically strings. A numeric string such as \"3\" will never be matched against `org.id` and silently falls through to the name/code lookup, then to `null`/host fallback. This inconsistency makes the id resolution unreliable for the primary use case. Consider also matching numeric strings against `org.id`.","suggestion_code":" if (typeof raw === 'number') {\n return organizations.some((org) => org.id === raw) ? raw : null;\n }\n const text = typeof raw === 'string' ? raw.trim() : '';\n if (/^\\d+$/.test(text)) {\n const id = Number(text);\n return organizations.some((org) => org.id === id) ? id : null;\n }","existing_code":" if (typeof raw === 'number') {\n return organizations.some((org) => org.id === raw) ? raw : null;\n }"}
{"path":"apps/server/src/ai-chat/ai-review.enrich.ts","start_line":11,"end_line":13,"category":"bug","severity":"low","content":"Any empty/missing value (empty string, `undefined`, `null`, or even unexpected types like booleans/objects, since they all fall into `!text`) is silently resolved to the host organization without any warning. In the caller (`ai-review.import-basic.ts`), the warning \"机构无法识别，已按本机构导入\" is only emitted when `null` is returned, so data rows with a missing/garbage organization value are imported under the host org with no signal to the user. If silent defaulting is not intended for empty values, return `null` for empty input and let the caller decide (including emitting a warning).","suggestion_code":" if (!text) {\n return null;\n }","existing_code":" if (!text) {\n return organizations.find((org) => org.isHost)?.id ?? null;\n }"}
{"path":"apps/server/src/ai-chat/ai-chat.types.ts","start_line":63,"end_line":70,"category":"maintainability","severity":"medium","content":"`AiReviewSection.type` is declared as the non-nullable union `AiReviewSectionType = 'students' | 'rooms' | 'transfers' | 'checkins'` (see ai-review.entity.ts), so the first `if` here always evaluates to true and `reviewSectionType` always returns `section.type`. The entire fallback below (the `section.key` cast, the `startsWith` loop and the `BadRequestException`) is dead code given the current types. Either this function is meant to tolerate legacy/malformed data — in which case the parameter type should be widened (e.g. `type?: AiReviewSectionType | null`) — or the unreachable fallback should be removed. Also note the literal `['students', 'rooms', 'transfers', 'checkins']` (and its four-way comparisons) is duplicated three times; extract a shared `const` (e.g. `REVIEW_SECTION_TYPES`) to keep the accepted values in sync.","suggestion_code":null,"existing_code":" if (\n section.type === 'students' ||\n section.type === 'rooms' ||\n section.type === 'transfers' ||\n section.type === 'checkins'\n ) {\n return section.type;\n }"}
{"path":"apps/server/src/ai-chat/ai-chat.types.ts","start_line":2,"end_line":5,"category":"maintainability","severity":"low","content":"This is a `.types.ts` file, but most imports are runtime (value) imports even though they are only used in type positions (`DataSource`, `Repository`, `AiConfigService`, `AgentToolExecutor`, `AgentToolContextFactory`, `AiAttachmentService`, `ImportsService`, `AiChartService`, `AiExcelReaderService`, `AiFormService`, `AiReviewService`, `AiModelStreamService`, `OperationLogsService`, and the entity classes/types). Anyone importing from this types file will therefore eagerly load all those service modules, which risks circular-dependency issues and unnecessary module initialization. Only `BadRequestException` (thrown by `reviewSectionType`) needs a value import; convert the rest to `import type` (note `AgentToolContextFactory` is only used in `typeof ...` position, so `import type` is sufficient there too).","suggestion_code":null,"existing_code":"import { DataSource, Repository } from 'typeorm';\nimport { AiConfigService } from '../ai-config/ai-config.service';\nimport { AgentToolExecutor } from '../agent-tools/agent-tool.executor';\nimport { AgentToolContextFactory } from '../agent-tools/agent-tool.types';"}
{"path":"apps/server/src/ai-chat/ai-chat.tool-actions.ts","start_line":84,"end_line":87,"category":"bug","severity":"medium","content":"This catch block swallows the original error and reports \"表单参数无效\" (invalid form parameters) for ANY failure — DB errors, missing assistant message, metadata serialization failures, etc. — with no logging of the real cause. This misleads the model/user about the actual failure and makes server-side debugging nearly impossible. Capture the error (e.g., `catch (error)`) and log it; only use the \"参数无效\" message when the failure is genuinely an argument/validation error.","suggestion_code":null,"existing_code":" } catch {\n await finishToolRun(context, run, call, startedAt, { status: 'failed', summary: '表单参数无效', error: '表单参数无效' }, emit);\n return JSON.stringify({ status: 'failed', error: '表单参数无效' });\n }"}
{"path":"apps/server/src/ai-chat/ai-chat.tool-actions.ts","start_line":136,"end_line":139,"category":"bug","severity":"medium","content":"Same issue as executeRenderForm: the catch reports \"图表参数无效\" for every failure (DB error, missing assistant message, chart serialization error, etc.) and discards the actual error without logging it. Swallow-and-remap hides real bugs and misleads the model. Log the underlying error and only classify it as an argument error when appropriate.","suggestion_code":null,"existing_code":" } catch {\n await finishToolRun(context, run, call, startedAt, { status: 'failed', summary: '图表参数无效', error: '图表参数无效' }, emit);\n return JSON.stringify({ status: 'failed', error: '图表参数无效' });\n }"}
{"path":"apps/server/src/ai-chat/ai-chat.tool-actions.ts","start_line":107,"end_line":111,"category":"maintainability","severity":"low","content":"Nested ternary expression — prohibited by the project's review rules. The inner `existingCharts ? [existingCharts] : []` branch is hard to read and error-prone. Rewrite with if/else branches (or extract a small helper) for clarity.","suggestion_code":" let charts: unknown[];\n if (isUnknownArray(existingCharts)) {\n charts = [...existingCharts];\n } else if (existingCharts) {\n charts = [existingCharts];\n } else {\n charts = [];\n }","existing_code":" const charts = isUnknownArray(existingCharts)\n ? [...existingCharts]\n : existingCharts\n ? [existingCharts]\n : [];"}
{"path":"apps/server/src/ai-chat/ai-chat.tool-actions.ts","start_line":90,"end_line":95,"category":"maintainability","severity":"low","content":"executeRenderForm and executeRenderChart share nearly the same skeleton: look up assistant message → merge/save metadata → finishToolRun(success) → emit('ui.artifact') → return success JSON, plus two identical catch blocks that remap errors to a fixed '参数无效' message. Consider extracting a shared helper (e.g., a generic save-and-emit-artifact routine) to avoid drift between the two implementations.","suggestion_code":null,"existing_code":"export async function executeRenderChart(\n context: AiChatServiceContext,\n messageId: number,\n call: ModelToolCall,\n emit: AiSseEmitter,\n): Promise {"}
{"path":"apps/server/src/ai-chat/ai-form.service.ts","start_line":147,"end_line":147,"category":"security","severity":"medium","content":"The size guard is labeled `MAX_VALUES_BYTES` (64 KB) but `serialized.length` counts UTF-16 code units, not bytes. With CJK input (common in this app, cf. the Chinese messages) a value up to ~192 KB UTF-8 can be stored, and `Buffer.byteLength` is what actually matches the stated byte limit. Either use `Buffer.byteLength(serialized, 'utf8')` or rename the constant to reflect that it's a character limit.","suggestion_code":" if (Buffer.byteLength(serialized, 'utf8') > MAX_VALUES_BYTES) throw new BadRequestException('提交内容过长');","existing_code":" if (serialized.length > MAX_VALUES_BYTES) throw new BadRequestException('提交内容过长');"}
{"path":"apps/server/src/ai-chat/ai-form.service.ts","start_line":110,"end_line":115,"category":"bug","severity":"medium","content":"`markSubmitted` performs an unconditional save without re-checking `status`. `findOwnedPending` checks `status: 'pending'` earlier, but between that read and this save another request can also pass the check (double submit) or the form can be expired via `expirePreviousForms`, and this save will still overwrite the row. Use a conditional update on `{ id, status: 'pending' }` and reject the request when the affected row count is 0 to make the state transition atomic.","suggestion_code":" async markSubmitted(form: AiForm, values: Record): Promise {\n const result = await this.forms.update(\n { id: form.id, status: 'pending' },\n {\n status: 'submitted',\n submittedValuesJson: JSON.stringify(values),\n submittedAt: new Date(),\n },\n );\n if (!result.affected) throw new BadRequestException('表单不存在、已提交或已失效');\n form.status = 'submitted';\n form.submittedValuesJson = JSON.stringify(values);\n form.submittedAt = new Date();\n return form;\n }","existing_code":" async markSubmitted(form: AiForm, values: Record): Promise {\n form.status = 'submitted';\n form.submittedValuesJson = JSON.stringify(values);\n form.submittedAt = new Date();\n return this.forms.save(form);\n }"}
{"path":"apps/server/src/ai-chat/ai-form.service.ts","start_line":103,"end_line":106,"category":"bug","severity":"low","content":"This find-then-update sequence is not atomic: a form that is submitted (or otherwise transitioned) concurrently between the `find` and the `update` will be force-marked `expired`, losing a legitimate submission. Narrow the update condition to only pending rows (e.g. add `status: 'pending'` to the where clause) so already-submitted forms cannot be overwritten, or use a single conditional UPDATE instead of read-then-write.","suggestion_code":" await this.forms.update({ id: In(ids), status: 'pending' }, { status: 'expired' });","existing_code":" const expired = pending.filter((form) => form.id !== exceptFormId);\n if (expired.length === 0) return [];\n const ids = expired.map((form) => form.id);\n await this.forms.update({ id: In(ids) }, { status: 'expired' });"}
{"path":"apps/server/src/ai-chat/ai-form.service.ts","start_line":276,"end_line":278,"category":"bug","severity":"low","content":"`DATE_RE` only checks the shape `YYYY-MM-DD`, so impossible dates such as `2023-13-40` or `2023-02-30` are accepted. Construct a `Date` and verify the round-trip (e.g. `d.toISOString().slice(0, 10) === value`) to reject non-existent calendar dates.","suggestion_code":null,"existing_code":" if (field.type === 'date' && !DATE_RE.test(value)) {\n throw new BadRequestException(`「${field.label}」必须是 YYYY-MM-DD 格式`);\n }"}
{"path":"apps/server/src/ai-chat/ai-form.service.ts","start_line":131,"end_line":131,"category":"security","severity":"low","content":"`FIELD_NAME_RE` (`/^[a-zA-Z0-9_]{1,50}$/`) permits names like `__proto__`, and `result[field.name] = ...` writes into a plain object. Assigning `result['__proto__'] = value` does not create an own property (setting the prototype to a primitive is silently ignored), so that field's submitted value is silently dropped and the serialized payload is inconsistent with the schema. Use a null-prototype object (`Object.create(null)`) for `result`, or reject reserved prototype property names during schema validation.","suggestion_code":" const result: Record = Object.create(null);","existing_code":" const result: Record = {};"}
{"path":"apps/server/src/ai-chat/ai-excel-reader.service.ts","start_line":84,"end_line":84,"category":"bug","severity":"high","content":"The `truncated` flag semantics are inverted. `slice.length < limit` means the end of the sheet was reached (i.e., nothing was cut off), while the truly truncated case is when exactly `limit` rows were returned but the sheet still has more rows (`from + limit < sheet.rows.length`). As written, the last page reports `truncated: false` and an earlier partial page can misreport, which can mislead the AI into stopping early or reading past the end.","suggestion_code":" truncated: from + limit < sheet.rows.length,","existing_code":" truncated: slice.length < limit,"}
{"path":"apps/server/src/ai-chat/ai-excel-reader.service.ts","start_line":41,"end_line":42,"category":"performance","severity":"medium","content":"The doc comment promises a \"short sample, small enough for prompts\", but this implementation serializes every row of every sheet into `text`. For large workbooks this can produce enormous prompts (token/memory blow-up) and defeats the stated design of reading sheets on demand. Consider limiting the overview to a sample (e.g., the first N rows per sheet) and leaving the full dump to `extractText`.","suggestion_code":null,"existing_code":" /** Sheet list + row counts + a short sample, small enough for prompts. */\n async overview(buffer: Buffer): Promise<{ sheets: ExcelSheetInfo[]; text: string }> {"}
{"path":"apps/server/src/ai-chat/ai-excel-reader.service.ts","start_line":29,"end_line":31,"category":"maintainability","severity":"medium","content":"This empty catch block silently swallows every ExcelJS failure (corrupt file, invalid zip, unexpected library bug, etc.) and hides it behind the fallback. If the fallback also throws, the original root cause is lost, making production debugging very difficult. Log the original error before falling back, or narrow the catch to the expected WPS-style namespace failure.","suggestion_code":null,"existing_code":" } catch {\n return this.loadWithFallback(buffer);\n }"}
{"path":"apps/server/src/ai-chat/ai-excel-reader.service.ts","start_line":70,"end_line":71,"category":"performance","severity":"medium","content":"Every `readRows` (and `overview`/`extractText`) call re-parses the entire workbook and stringifies every cell via `loadSheets`, even though only a small slice is requested. For large Excel files this is O(file size) work per page request and materializes all rows in memory, contradicting the \"reads sheets on demand\" design. Consider caching the parsed result per buffer (e.g., `WeakMap>`) or parsing only the requested sheet/range.","suggestion_code":null,"existing_code":" const sheets = await this.loadSheets(buffer);\n const sheet = sheets.find((item) => item.name === sheetName) ?? sheets[0];"}
{"path":"apps/server/src/ai-chat/ai-chat.tool-actions.import.ts","start_line":164,"end_line":171,"category":"bug","severity":"medium","content":"Possible double-finish of the tool run: `finishToolRun` is called with `status: 'success'` first (persisting success + emitting `tool.completed`), and then `emit('ui.import_wizard')` / `emit('ui.artifact')` are called still inside the `try` block of `runImportTool`. If either SSE emit throws (e.g. connection closed), the catch block calls `finishToolRun` a second time with `status: 'failed'`, overwriting the already-saved success record and emitting a contradictory `tool.failed` after `tool.completed`; the caller also receives a `failed` JSON even though the wizard was created and persisted. Recommend emitting the UI events before the success `finishToolRun`, or moving them outside the error-handling path / marking the run as finished so the catch cannot re-finish it.","suggestion_code":null,"existing_code":" await finishToolRun(context, run, call, startedAt, {\n status: 'success',\n summary: `已生成导入向导：${detail.steps\n .filter((step) => step.status !== 'skipped')\n .map((step) => step.label)\n .join('、')}`,\n }, emit);\n emit('ui.import_wizard', { messageId, wizard });"}
{"path":"apps/server/src/ai-chat/ai-chat.tool-actions.import.ts","start_line":121,"end_line":122,"category":"bug","severity":"low","content":"`parsedRecord.stages` is cast directly to `ImportStageRequest[]` without verifying each element is a non-null object. If the model returns stages containing e.g. `null`, a number or a string, `stage.stepKey` (and `expandStageSheets(stage)`) will throw a generic `TypeError` that is only caught by the outer catch in `runImportTool`, so the user gets an opaque failure instead of the intended validation message. Add an element-level guard before accessing `stage.stepKey`/`expandStageSheets` (e.g. `typeof stage === 'object' && stage !== null`).","suggestion_code":null,"existing_code":" for (const stage of stages) {\n if (!IMPORT_STEP_KEYS.includes(stage.stepKey)) {"}
{"path":"apps/server/src/ai-chat/ai-chat.tool-actions.import.ts","start_line":82,"end_line":89,"category":"maintainability","severity":"low","content":"The catch block swallows the original error without logging it anywhere, which makes server-side debugging of failed import-wizard runs difficult. Additionally, `finishToolRun` inside this catch can itself throw (e.g. DB save failure or SSE emit failure); in that case the error propagates unhandled and the intended failed JSON response is never returned. Consider logging the original error and wrapping the failure finalization so a response is still produced.","suggestion_code":null,"existing_code":" } catch (error) {\n const summary = error instanceof Error ? error.message.slice(0, 100) : `${toolName} 失败`;\n await finishToolRun(context, run, call, startedAt, {\n status: 'failed',\n summary,\n error: summary,\n }, emit);\n return JSON.stringify({ status: 'failed', error: run.resultSummary });"}
{"path":"apps/server/src/ai-chat/ai-review.shared.ts","start_line":0,"end_line":0,"category":"bug","severity":"high","content":"The `AiReviewSectionResult` union declares the same member twice (`{ created: ... }` in both branches) — the second branch is a copy-paste typo and should be `{ completed: ... }`. As written, the union collapses to a single shape, so the `completed` variant is no longer part of the type: `importTransfers`/`importCheckins`/`parseStoredSectionResult` return `{ completed, ... }` objects that are not assignable to this type, and callers in `mergeStepResult`/`sectionResultMessage` are forced to use unsafe `as` casts. Fix the second member.","suggestion_code":"export type AiReviewSectionResult =\n | { created: number; skipped: number; issues: string[] }\n | { completed: number; skipped: number; issues: string[] };","existing_code":"export type AiReviewSectionResult =\n | { created: number; skipped: number; issues: string[] }\n | { created: number; skipped: number; issues: string[] };"}
{"path":"apps/server/src/ai-chat/ai-review.shared.ts","start_line":47,"end_line":50,"category":"bug","severity":"medium","content":"`DATE_RE` only checks the YYYY-MM-DD *format*, not calendar validity — strings like \"2026-02-31\" or \"2026-13-45\" pass and are returned as valid dates. Downstream this value is stored directly into date columns (`checkOutDate`/`checkInDate`) and compared as a string, so an impossible date can be persisted or silently rolled over (e.g. by dayjs) into a different day, corrupting the data. Consider validating the parsed date components (e.g. reconstruct a UTC Date and check year/month/day round-trip) before returning.","suggestion_code":null,"existing_code":"export function toDateString(value: unknown): string | null {\n if (typeof value === 'string' && DATE_RE.test(value.trim())) return value.trim();\n return null;\n}"}
{"path":"apps/server/src/ai-chat/ai-review.shared.ts","start_line":103,"end_line":106,"category":"maintainability","severity":"low","content":"The final fallback branch of `sectionResultMessage` silently assumes any key that is not students/rooms/transfers is `checkins` (the default `return` is the check-in message). If a new section type is added to `SECTION_TYPES`/`SECTION_ORDER`, it will be mislabeled with the check-in message instead of failing loudly. Make the `checkins` branch explicit and throw (or otherwise handle) unknown keys for clarity and future safety.","suggestion_code":null,"existing_code":" if (key === 'transfers') {\n return `成功换宿 ${(result as { completed: number }).completed} 条，跳过 ${result.skipped} 条`;\n }\n return `成功入住 ${(result as { completed: number }).completed} 条，跳过 ${result.skipped} 条`;"}
{"path":"apps/server/src/ai-chat/ai-review.service.ts","start_line":9,"end_line":12,"category":"maintainability","severity":"low","content":"`AiReviewStepSubmitResult` and `AiReviewSubmitResult` are pure interfaces (defined as `interface`/`type` in ai-review.shared.ts) and are used only in type positions. They are imported as value imports here, which is inconsistent with the `import type` style used everywhere else in this file. Under TS configs with `verbatimModuleSyntax`/`isolatedModules` this fails to compile, and a bundler would try to resolve a non-existent runtime export. Use a type-only import.","suggestion_code":"import type {\n AiReviewStepSubmitResult,\n AiReviewSubmitResult,\n} from './ai-review.shared';","existing_code":"import {\n AiReviewStepSubmitResult,\n AiReviewSubmitResult,\n} from './ai-review.shared';"}
{"path":"apps/server/src/ai-chat/ai-review.service.ts","start_line":40,"end_line":46,"category":"maintainability","severity":"low","content":"`findOwnedPending` and the `findOwned` method below are nearly identical (same lookup, different `status` filter and error message), and `findOwned` also duplicates the exported `findOwned` helper in ai-review.submit.ts. Consider extracting a single private helper, e.g. `findOwned(reviewId, userId, status?)`, so the lookup/not-found logic is defined once and the two public methods only add their specific filter/message.","suggestion_code":null,"existing_code":" async findOwnedPending(reviewId: string, userId: number): Promise {\n const review = await this.reviews.findOne({\n where: { id: reviewId, userId, status: 'pending' },\n });\n if (!review) throw new NotFoundException('导入预览不存在、已确认或已失效');\n return review;\n }"}
{"path":"apps/server/src/ai-chat/ai-chat.tools.ts","start_line":84,"end_line":84,"category":"maintainability","severity":"medium","content":"The `reviewSubmitted` parameter is accepted and forwarded all the way from the generation flow (`ai-chat.generation.ts` passes `Boolean(reviewSubmit)`) but is never referenced inside `executeTool`. The write-tool gate only checks `allowWriteTools`, so the review-submission state has no effect on tool execution. Either remove the dead parameter or use it in the guard (e.g., deny write tools unless the review has been submitted), otherwise the intended \"review must be submitted first\" policy is silently not enforced.","suggestion_code":null,"existing_code":" reviewSubmitted: boolean,"}
{"path":"apps/server/src/ai-chat/ai-chat.tools.ts","start_line":97,"end_line":97,"category":"maintainability","severity":"medium","content":"Write-tool names are hardcoded here and again in `denyWriteTool` ('create_student'). This is an authorization-relevant guard: any write tool registered later (e.g. delete_student, create_room) would bypass this deny-before-form-confirmation check because it is not in this literal list, and the two copies can drift. Derive the write-tool set from the tool registry/metadata (e.g., a `write` capability flag or `requiredPermission` prefix) instead of hardcoding tool names.","suggestion_code":null,"existing_code":" if ((call.name === 'create_student' || call.name === 'update_students') && !allowWriteTools) {"}
{"path":"apps/server/src/ai-chat/ai-chat.tools.ts","start_line":108,"end_line":108,"category":"bug","severity":"medium","content":"There is no try/catch around `context.toolExecutor.execute` or the subsequent `summarize`/`safeStructured`/`toolRuns.save` calls. `tool.started` has already been emitted and the DB row is saved with status 'running'; if any of these steps throws, the run is left permanently in 'running' state, no `tool.failed` event is emitted, and the error propagates without a tool result payload — breaking the SSE/message flow contract. Wrap the execution + persistence in try/catch and, on failure, mark the run 'failed', save it, emit `tool.failed`, and return a safe error JSON.","suggestion_code":null,"existing_code":" const result = await context.toolExecutor.execute(call.name, parsedArgs, agentContext, allowedSkillKey);"}
{"path":"apps/server/src/ai-chat/ai-chat.tools.ts","start_line":111,"end_line":111,"category":"maintainability","severity":"low","content":"This finishing block (status/resultSummary/durationMs update, `toolRuns.save`, and the `tool.completed`/`tool.failed` emit) duplicates the logic already provided by `finishToolRun`, which is used by the tool-action modules. Reuse `finishToolRun` (extending it to also persist `resultData`/`skillKey` if needed) to avoid the two implementations drifting apart (e.g., one day only one of them is updated to include new fields/events).","suggestion_code":null,"existing_code":" run.resultSummary = context.summarize(result.result ?? result.error ?? null);"}
{"path":"apps/server/src/ai-chat/ai-chat.tools.ts","start_line":36,"end_line":36,"category":"maintainability","severity":"low","content":"`context.safeStructured(parsedArgs)` returns `unknown`; the cast to `Record | null` is unsound when the model supplies array-shaped tool arguments (the entity's `resultData` column explicitly allows `unknown[]`, so arrays are expected elsewhere). Casting only hides the type mismatch. Preserve the real shape (e.g., widen `AiToolRun.argumentsData` to `Record | unknown[] | null` and let the value flow without a cast) so type errors surface instead of being suppressed.","suggestion_code":null,"existing_code":" (context.safeStructured(parsedArgs) as Record | null),"}
{"path":"apps/server/src/ai-chat/ai-chat.tools.ts","start_line":134,"end_line":134,"category":"performance","severity":"low","content":"The 32KB truncation check measures `modelPayload.length` (UTF-16 code units), not byte size. With Chinese/other multibyte content a payload can be up to ~3x the byte budget (96KB) while still passing this check, which may exceed the model context limit it is meant to protect. Use `Buffer.byteLength(modelPayload, 'utf8') <= 32 * 1024` (or an explicit byte-based limit) for the comparison.","suggestion_code":null,"existing_code":" if (modelPayload.length <= 32 * 1024) return modelPayload;"}
{"path":"apps/server/src/ai-chat/ai-review.workbook.ts","start_line":9,"end_line":12,"category":"bug","severity":"medium","content":"Inconsistent error handling: malformed JSON is silently treated as \"no sections\" (`return []`), while structurally invalid items throw BadRequestException. If `sectionsJson` in the DB is corrupted/truncated, callers such as `submitAll` (ai-review.submit.ts) will get an empty array and proceed as if the review is fully submitted, silently masking data loss. Recommend throwing a BadRequestException here as well (or applying a single consistent error policy) so corrupt data is surfaced instead of swallowed.","suggestion_code":" } catch {\n throw new BadRequestException('导入预览数据解析失败');\n }\n if (!Array.isArray(parsed)) {\n throw new BadRequestException('导入预览数据格式无效');\n }","existing_code":" } catch {\n return [];\n }\n if (!Array.isArray(parsed)) return [];"}
{"path":"apps/server/src/ai-chat/ai-review.workbook.ts","start_line":14,"end_line":16,"category":"bug","severity":"low","content":"Only `typeof item.key === 'string'` is validated here, but the shared module defines `SECTION_KEY_RE = /^[a-zA-Z0-9_]{1,50}$/` and `submitSection` (ai-review.submit.ts) rejects keys that fail this regex. A key that starts with a valid type prefix (e.g., `students_`) but is longer than 50 chars or contains invalid characters passes `parseSections` and is persisted, yet can never be submitted via the API afterwards. Validate the key against `SECTION_KEY_RE` at parse time for consistency.","suggestion_code":" if (\n !isPlainRecord(item) ||\n typeof item.key !== 'string' ||\n !SECTION_KEY_RE.test(item.key)\n ) {\n throw new BadRequestException('导入预览分表格式无效');\n }","existing_code":" if (!isPlainRecord(item) || typeof item.key !== 'string') {\n throw new BadRequestException('导入预览分表格式无效');\n }"}
{"path":"apps/server/src/ai-chat/ai-review.workbook.ts","start_line":25,"end_line":27,"category":"bug","severity":"low","content":"`columns`/`rows`/`issues` are only checked with `Array.isArray`; their element shapes are not validated. The persisted JSON is AI-generated/user-supplied, so e.g. rows may contain nested objects/arrays that violate `AiReviewRow` (scalar values only), columns may lack `key`/`title` strings, and issues may contain non-strings. This unvalidated data flows directly into section import and frontend rendering, risking runtime errors. Consider validating element types (or at least normalizing them) here.","suggestion_code":null,"existing_code":" columns: Array.isArray(section.columns) ? section.columns : [],\n rows: Array.isArray(section.rows) ? section.rows : [],\n issues: Array.isArray(section.issues) ? section.issues : [],"}
{"path":"apps/server/src/ai-chat/ai-review.workbook.ts","start_line":13,"end_line":13,"category":"maintainability","severity":"low","content":"After `Array.isArray(parsed)`, `parsed` is narrowed to `any[]`, so `item` here is implicitly `any`. Per the project's type rules (`any` should be avoided or annotated with a reason), type the array explicitly, e.g. cast to `unknown[]` before `map` and narrow inside the callback.","suggestion_code":" return (parsed as unknown[]).map((item) => {","existing_code":" return parsed.map((item) => {"}
{"path":"apps/server/src/ai-chat/ai-review.import-relations.ts","start_line":192,"end_line":202,"category":"bug","severity":"high","content":"同一学生在同一批次中，如果一行只填手机号、另一行只填学号（或一行同时填了学号+手机号），去重 key 和数据库查询都只按单一标识（phone 优先）进行，第二条记录无法命中第一条已创建的学生，会重复创建 Student（重复学号/手机号），破坏数据唯一性。建议去重 key 同时覆盖两个标识，且查询时 phone 查不到再按 studentNo 查。","suggestion_code":" const dedupeKey = `${phone ? `phone:${phone}` : ''}|${studentNo ? `no:${studentNo}` : ''}`;\n if (seen.has(dedupeKey)) {\n skipped += 1;\n issues.push(`学生「${name}」与同一批次中的其他行手机号/学号重复`);\n continue;\n }\n seen.add(dedupeKey);\n\n let student = phone\n ? await studentRepo.findOne({ where: { phone } })\n : null;\n if (!student && studentNo) {\n student = await studentRepo.findOne({ where: { studentNo } });\n }","existing_code":" const dedupeKey = phone ? `phone:${phone}` : `no:${studentNo}`;\n if (seen.has(dedupeKey)) {\n skipped += 1;\n issues.push(`学生「${name}」与同一批次中的其他行手机号/学号重复`);\n continue;\n }\n seen.add(dedupeKey);\n\n let student = phone\n ? await studentRepo.findOne({ where: { phone } })\n : await studentRepo.findOne({ where: { studentNo } });"}
{"path":"apps/server/src/ai-chat/ai-review.import-relations.ts","start_line":255,"end_line":256,"category":"bug","severity":"medium","content":"历史入住记录（含 checkOutDate）缺少基本校验：checkOutDate 可能早于 checkInDate，也可能与学生在住（checkOutDate 为空）的现有记录时间段重叠，直接写入会生成自相矛盾/重叠的入住记录。建议在写入前校验 checkOutDate > checkInDate，并对与学生现有在住/历史记录的重叠做检查后跳过并记录问题。","suggestion_code":null,"existing_code":" const checkOutDate = toDateString(row.checkOutDate);\n const isHistoricalRecord = Boolean(checkOutDate);"}
{"path":"apps/server/src/ai-chat/ai-review.import-relations.ts","start_line":253,"end_line":253,"category":"bug","severity":"medium","content":"checkInDate 无效时（如格式错误）会被 ?? 静默降级为当天日期，而不是像 importTransfers 那样将无效日期作为问题行跳过并提示。这会让日期写错的记录被静默导入成“今天”，与换宿逻辑的校验行为不一致，容易掩盖脏数据。建议对无效 checkInDate 跳过并输出提示。","suggestion_code":" const checkInDate = toDateString(row.checkInDate) ?? dayjs().utcOffset(8).format('YYYY-MM-DD');\n if (!toDateString(row.checkInDate)) {\n skipped += 1;\n issues.push(`学生「${name}」的入住日期格式无效（应为 YYYY-MM-DD）`);\n continue;\n }","existing_code":" const checkInDate = toDateString(row.checkInDate) ?? dayjs().utcOffset(8).format('YYYY-MM-DD');"}
{"path":"apps/server/src/ai-chat/ai-review.import-relations.ts","start_line":106,"end_line":106,"category":"bug","severity":"low","content":"用 `String(active.checkInDate)` 与 YYYY-MM-DD 字符串直接做字典序比较是脆弱的：一旦数据库驱动把 date 列水合为 Date 对象，String(Date) 会变成 \"Wed Aug 05 2026 ...\" 这类格式，比较结果会静默出错。建议统一用 toDateString 归一化后再比较。","suggestion_code":" if (transferDate < (toDateString(active.checkInDate) ?? '')) {","existing_code":" if (transferDate < String(active.checkInDate)) {"}
{"path":"apps/server/src/ai-chat/ai-validation.ts","start_line":17,"end_line":20,"category":"bug","severity":"medium","content":"When `optional` is true, an explicitly-provided empty string (`''`) still throws `必须是字符串`, so callers such as `requireString(rawArgs.description, ..., true) || null` can never receive `''` — the `|| null` fallback for a missing/empty value is unreachable, and optional fields sent as `\"\"` (common with LLM-generated payloads) cause spurious 400 errors. The `optional` branch is also only reached for `undefined`/`null`, which is inconsistent with the caller's expectation. Suggest treating an empty/whitespace string as absent when `optional` is true, and using a distinct `不能为空` message for empty strings (the current `必须是字符串` message is misleading for `''`):","suggestion_code":" if (typeof value !== 'string') {\n throw new BadRequestException(`${label}必须是字符串`);\n }\n const trimmed = value.trim();\n if (!trimmed) {\n if (optional) return '';\n throw new BadRequestException(`${label}不能为空`);\n }","existing_code":" if (typeof value !== 'string' || !value.trim()) {\n throw new BadRequestException(`${label}必须是字符串`);\n }\n const trimmed = value.trim();"}
{"path":"apps/server/src/ai-chat/ai-validation.ts","start_line":3,"end_line":5,"category":"bug","severity":"low","content":"`isPlainRecord` only excludes `null`/arrays, so it also returns true for `Date`, `RegExp`, `Map`, class instances, or any object with a custom prototype. Given the name and its use as a gate before `assertKeys`/key access, it is safer to require an ordinary object (or null-prototype object). This also rejects objects whose inherited properties could otherwise influence downstream `in` checks or spreads. For JSON-parsed input the current check is harmless, but hardening the guard is cheap:","suggestion_code":"export function isPlainRecord(value: unknown): value is Record {\n if (!value || typeof value !== 'object' || Array.isArray(value)) return false;\n const proto = Object.getPrototypeOf(value);\n return proto === Object.prototype || proto === null;\n}","existing_code":"export function isPlainRecord(value: unknown): value is Record {\n return Boolean(value) && typeof value === 'object' && !Array.isArray(value);\n}"}
{"path":"apps/server/src/ai-chat/dto/ai-chat.dto.ts","start_line":16,"end_line":16,"category":"maintainability","severity":"medium","content":"Cross-module coupling: the ai-chat DTO imports a domain constant from another module's DTO file (`ai-config/dto/ai-config.dto.ts`). This ties the two modules together at the type level and risks circular imports as modules evolve. A DTO file should not be the shared source of a business constant — move `REASONING_EFFORT_LEVELS` to a shared constants location (e.g., `common/constants` or an `ai-config/constants` file) and import it from there in both modules.","suggestion_code":null,"existing_code":"import { REASONING_EFFORT_LEVELS } from '../../ai-config/dto/ai-config.dto';"}
{"path":"apps/server/src/ai-chat/dto/ai-chat.dto.ts","start_line":61,"end_line":62,"category":"maintainability","severity":"medium","content":"The `@IsUUID() clientRequestId` and `@IsOptional() @IsIn(REASONING_EFFORT_LEVELS) reasoningEffort` fields are duplicated verbatim across 5 DTOs in this file (SendMessageDto, RegenerateMessageDto, EditMessageDto, SubmitFormDto, SubmitReviewDto). Extract a shared base DTO (e.g., `MessageRequestBaseDto`) containing these common fields and have the message DTOs extend it, so validation rules stay consistent and changes are made in one place.","suggestion_code":null,"existing_code":" @IsUUID()\n clientRequestId: string;"}
{"path":"apps/server/src/ai-chat/dto/ai-chat.dto.ts","start_line":96,"end_line":97,"category":"security","severity":"low","content":"`values` is an unbounded object while every other request field in this file is length/size-capped. A client can submit an arbitrarily large `values` object, causing excess memory usage during validation and downstream processing. Consider adding a size limit (e.g., a custom validator capping the number of keys or the serialized size) to be consistent with the other bounded fields.","suggestion_code":null,"existing_code":" @IsObject()\n values: Record;"}
{"path":"apps/server/src/ai-chat/dto/ai-chat.dto.ts","start_line":20,"end_line":22,"category":"bug","severity":"low","content":"Inconsistent validation: `CreateConversationDto.title` has no `@IsNotEmpty()`, so an empty-string title is accepted on creation, while `UpdateConversationDto.title` rejects empty strings. If empty titles are invalid, add `@IsNotEmpty()` here too; otherwise align both DTOs to the same rule.","suggestion_code":null,"existing_code":" @IsString()\n @MaxLength(100)\n title?: string;"}
{"path":"apps/server/src/ai-chat/ai-review.submit.ts","start_line":52,"end_line":55,"category":"bug","severity":"medium","content":"Concurrency hazard: the transaction performs a read-modify-write of `review.sectionsJson` without any row lock or optimistic versioning. Two concurrent confirmations of the same review (e.g. `submitAll` running while the user confirms another section, or double-submit of the same section) both read the same `sectionsJson`, update disjoint sections, and then the last `manager.save(review)` overwrites the other's change — silently losing a section's `submitted` status. The affected section then appears pending and a re-submit re-runs `importOneSection`, risking duplicate imports. Use a pessimistic write lock or an optimistic version column on `AiReview`; the same pattern also exists in `markSectionFailed`.","suggestion_code":" return await context.dataSource.transaction(async (manager) => {\n const review = await manager.findOne(AiReview, {\n where: { id: reviewId, userId },\n lock: { mode: 'pessimistic_write' },\n });","existing_code":" return await context.dataSource.transaction(async (manager) => {\n const review = await manager.findOne(AiReview, {\n where: { id: reviewId, userId },\n });"}
{"path":"apps/server/src/ai-chat/ai-review.submit.ts","start_line":82,"end_line":84,"category":"bug","severity":"medium","content":"Data-consistency issue: `resultSummary` is stored from `result.issues` before `section.issues` is merged, so issues accumulated from a previous failed attempt (`markSectionFailed` appends `导入失败：…` to `section.issues`) are never persisted into the stored summary. Downstream `parseStoredSectionResult`/`buildAggregateResult` read issues only from `resultSummary`, so the earlier failure message silently disappears from the final aggregate, while `section.issues` in `sectionsJson` still contains it. Merge issues first, then persist the merged list.","suggestion_code":" section.issues = mergeIssues(section.issues, result.issues);\n section.resultSummary = JSON.stringify({ ...result, issues: section.issues, message });\n section.submittedAt = new Date().toISOString();","existing_code":" section.resultSummary = JSON.stringify({ ...result, message });\n section.submittedAt = new Date().toISOString();\n section.issues = mergeIssues(section.issues, result.issues);"}
{"path":"apps/server/src/ai-chat/ai-review.submit.ts","start_line":235,"end_line":236,"category":"bug","severity":"low","content":"Fragile arithmetic / unsafe cast: `(value as { created: number }).created` is a compile-time-only assertion. If a caller ever passes a section result without a numeric `created`/`completed` field, `target[key].created += undefined` produces `NaN`, which then propagates into `buildAggregateMessage` (e.g. `成功导入学生 NaN 人`). Guard with `Number(...) || 0` (same for the `completed` branch) to make it robust.","suggestion_code":" const created = Number((value as { created?: number }).created) || 0;\n target[key].created += created;","existing_code":" const created = (value as { created: number }).created;\n target[key].created += created;"}
{"path":"apps/server/src/ai-chat/ai-review.submit.ts","start_line":314,"end_line":316,"category":"maintainability","severity":"low","content":"When a dependency type has no matching section at all, the user-facing message falls back to the raw type key (`「students」尚未导入，请先确认对应分表`), which is an internal identifier rather than a human-readable title. Consider mapping `dependencyType` to a display label (or deriving one) so the error message is understandable to end users.","suggestion_code":null,"existing_code":" if (matches.length === 0) {\n return { step: -1, title: dependencyType };\n }"}
{"path":"apps/server/src/ai-chat/ai-review.import-basic.ts","start_line":120,"end_line":125,"category":"bug","severity":"medium","content":"TOCTOU race + unhandled DB error: `roomNumber` has a unique constraint in the `rooms` table, but the existence check (`findOne`) and the insert (`save`) are not atomic. Two concurrent imports (e.g., double submit or parallel requests) can both pass the check, and the second `save` will throw an uncaught unique-violation error that aborts the entire batch (and rolls back rows already saved if the caller uses a transaction). Wrap the loop/save in try/catch and convert unique-violation into a skip + issue, or serialize imports for the same room numbers.","suggestion_code":null,"existing_code":" const existing = await roomRepo.findOne({ where: { roomNumber } });\n if (existing) {\n skipped += 1;\n issues.push(`宿舍「${roomNumber}」已存在，未重复创建`);\n continue;\n }"}
{"path":"apps/server/src/ai-chat/ai-review.import-basic.ts","start_line":57,"end_line":63,"category":"bug","severity":"medium","content":"TOCTOU race: `Student.phone` and `studentNo` have no unique constraint in the entity, so the `findOne`-then-`save` pattern is not atomic — concurrent import batches can both pass the existence check and silently create duplicate students. Additionally, there is no try/catch around the per-row operations, so any DB error (e.g., connection loss) aborts the whole batch with no user-friendly message. Consider adding a unique index / upsert and graceful per-row error handling.","suggestion_code":null,"existing_code":" const existing =\n (phone\n ? await studentRepo.findOne({ where: { phone } })\n : null) ||\n (studentNo\n ? await studentRepo.findOne({ where: { studentNo } })\n : null);"}
{"path":"apps/server/src/ai-chat/ai-review.import-basic.ts","start_line":174,"end_line":176,"category":"bug","severity":"high","content":"Timezone-dependent off-by-one bug: the date is parsed as midnight `+08:00`, but `setDate`/`getFullYear`/`getMonth`/`getDate` use the server's *local* timezone. On a UTC server (or any zone west of +08:00), `nextDay('2026-08-09')` parses to 2026-08-08T16:00Z, so the local date is the 8th; adding one day then formatting yields `2026-08-09` — the same day, not the next day. Since this feeds `billingStartDate` for transfers, billing dates can be off by one day. Also, an invalid `date` string silently produces `NaN-NaN-NaN`. Use UTC-based getters (or a date library) and validate the input.","suggestion_code":"export function nextDay(date: string): string {\n const parsed = new Date(`${date}T00:00:00Z`);\n if (Number.isNaN(parsed.getTime())) return date;\n parsed.setUTCDate(parsed.getUTCDate() + 1);\n const year = parsed.getUTCFullYear();\n const month = String(parsed.getUTCMonth() + 1).padStart(2, '0');\n const day = String(parsed.getUTCDate()).padStart(2, '0');\n return `${year}-${month}-${day}`;\n}","existing_code":"export function nextDay(date: string): string {\n const parsed = new Date(`${date}T00:00:00+08:00`);\n parsed.setDate(parsed.getDate() + 1);"}
{"path":"apps/server/src/ai-chat/ai-review.import-basic.ts","start_line":25,"end_line":26,"category":"performance","severity":"medium","content":"Sequential per-row DB round trips: each row issues 1–2 `findOne` queries plus a `save` (and `importRooms` additionally saves beds), all awaited inside the loop. For AI-extracted batches that can contain hundreds of rows this becomes O(n) round trips. The in-batch `seen` dedupe can be computed purely in memory upfront, after which existing records can be checked with a single `In()` query and the remaining saves can be parallelized with `Promise.all` (same applies to `importRooms`).","suggestion_code":null,"existing_code":" for (const row of section.rows) {\n const name = row.name === undefined || row.name === null ? '' : String(row.name).trim();"}
{"path":"apps/server/src/ai-chat/entities/ai-attachment.entity.ts","start_line":45,"end_line":46,"category":"bug","severity":"medium","content":"`text` maps to MySQL TEXT (max 65,535 bytes). Extracted text from documents (PDFs, Word files, OCR results) can easily exceed this limit, which will cause a `Data too long for column 'extracted_text'` error on insert/update. Consider `longtext` (or at least `mediumtext`) for this column.","suggestion_code":"@Column({ name: 'extracted_text', type: 'longtext', nullable: true })\n extractedText: string | null;","existing_code":"@Column({ name: 'extracted_text', type: 'text', nullable: true })\n extractedText: string | null;"}
{"path":"apps/server/src/ai-chat/entities/ai-attachment.entity.ts","start_line":48,"end_line":49,"category":"maintainability","severity":"low","content":"`varchar(200)` will silently truncate long processing errors (e.g., stack traces or upstream API error messages), losing information needed for debugging. Use a `text` column or a larger length for `processing_error`.","suggestion_code":"@Column({ name: 'processing_error', type: 'text', nullable: true })\n processingError: string | null;","existing_code":"@Column({ name: 'processing_error', type: 'varchar', length: 200, nullable: true })\n processingError: string | null;"}
{"path":"apps/server/src/ai-chat/entities/ai-attachment.entity.ts","start_line":36,"end_line":37,"category":"bug","severity":"low","content":"`integer` is a signed 32-bit INT (max ~2.1 GB). If an uploaded file ever exceeds 2 GB, `size` will overflow/corrupt the stored value. Use `bigint` for safety (note: MySQL `bigint` is returned as a string by the driver, so a `transformer` may be needed to keep `size` as a number).","suggestion_code":"@Column({ type: 'bigint', transformer: { to: (v: number) => v, from: (v: string) => Number(v) } })\n size: number;","existing_code":"@Column({ type: 'integer' })\n size: number;"}
{"path":"apps/server/src/ai-chat/ai-model-stream.service.ts","start_line":253,"end_line":253,"category":"bug","severity":"medium","content":"The timeout/abort guarantee does not cover DNS resolution: `dns.lookup` is not abortable and is not wrapped in a timer, so if the system resolver hangs (misconfigured DNS, unreachable resolver), `pinnedPost` never settles and the `RequestTimeoutException` branch never triggers — the whole `stream()` can hang well beyond `config.timeoutMs`. The consumer's `signal` also cannot cancel the lookup. Consider racing the lookup against a timer (or checking `signal.aborted` and rejecting inside the callback and after it returns).","suggestion_code":" lookup(parsed.hostname, { all: true, family: 0 }, (dnsError, addresses) => {\n if (signal.aborted) return reject(signal.reason ?? new Error('aborted'));","existing_code":" lookup(parsed.hostname, { all: true, family: 0 }, (dnsError, addresses) => {"}
{"path":"apps/server/src/ai-chat/ai-model-stream.service.ts","start_line":254,"end_line":254,"category":"bug","severity":"low","content":"DNS failures are rejected as a plain `Error` with no `code`/`errno`, so the `ENOTFOUND`/`EAI_AGAIN` entries in `RETRYABLE_TRANSPORT_CODES` never match — transient DNS failures are therefore never retried (the check in `isRetryableTransportError` can only match the code set, and connection errors can't produce those codes since the request targets a resolved IP). Propagate the original `dnsError.code` (e.g. `EAI_AGAIN`) so the retry logic actually applies to flaky DNS.","suggestion_code":" if (dnsError || !addresses?.length) {\n const err = new Error('DNS 解析失败') as NodeJS.ErrnoException;\n err.code = (dnsError as NodeJS.ErrnoException | null)?.code ?? 'ENOTFOUND';\n return reject(err);\n }","existing_code":" if (dnsError || !addresses?.length) return reject(new Error('DNS 解析失败'));"}
{"path":"apps/server/src/ai-chat/ai-model-stream.service.ts","start_line":122,"end_line":122,"category":"bug","severity":"medium","content":"In this retryable-status branch the body is resumed without any `'error'` listener. If the upstream socket errors (e.g. ECONNRESET) while this stale error body is being drained, `IncomingMessage` emits `'error'` with no listener, which becomes an uncaught exception and can crash the process. Attach a no-op `error` handler, or `destroy()` the response instead of only resuming it.","suggestion_code":" response.body.resume();\n response.body.on('error', () => undefined);","existing_code":" response.body.resume?.();"}
{"path":"apps/server/src/ai-chat/ai-model-stream.service.ts","start_line":140,"end_line":140,"category":"maintainability","severity":"low","content":"Dead code: the loop can only exit via `break` on a 2xx response — every non-2xx branch either throws (after retries are exhausted) or `continue`s, and `pinnedPost` either resolves or throws. So `if (!response)` is always false and `response.status` here is always 2xx; both blocks are unreachable. Remove them or restructure the loop so error/retry handling isn't duplicated after it.","suggestion_code":null,"existing_code":" if (response.status < 200 || response.status >= 300) {"}
{"path":"apps/server/src/ai-chat/ai-model-stream.service.ts","start_line":255,"end_line":257,"category":"security","severity":"low","content":"SSRF hardening gaps: `allowPrivate` also skips the private-IP check entirely for `DNS_TRUSTED_HOSTS` — if DNS for these hosts is poisoned/compromised, requests (including the bearer API key) can be sent to internal addresses with no IP validation. Additionally the IPv4 range list misses `198.18.0.0/15`, multicast `224.0.0.0/4`, reserved `240.0.0.0/4` and TEST-NET (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`), and hex-encoded IPv4-mapped IPv6 (e.g. `::ffff:7f00:1`) bypasses the `::ffff:` check because `isIP` on the hex tail returns 0. Consider adding these ranges and validating the mapped tail as a numeric IPv4 address.","suggestion_code":null,"existing_code":" const allowPrivate =\n process.env.AI_ALLOW_PRIVATE_BASE_URL === 'true' ||\n DNS_TRUSTED_HOSTS.has(parsed.hostname);"}
{"path":"apps/server/src/ai-chat/entities/ai-form.entity.ts","start_line":65,"end_line":69,"category":"bug","severity":"medium","content":"The status transition (pending -> submitted) is not protected against concurrent submissions. Without a version column (@Version optimistic locking) or an atomic conditional update (e.g. `UPDATE ai_forms SET status='submitted', ... WHERE id=? AND status='pending'`), two simultaneous submit requests can both pass validation and overwrite `submittedValuesJson`/`submitted_at`, or double-count the submission. Consider adding a `@Version` column to this entity and having the submit service rely on it.","suggestion_code":null,"existing_code":" @Column({ type: 'varchar', length: 20, default: 'pending' })\n status: AiFormStatus;\n\n @Column({ name: 'submitted_values_json', type: 'text', nullable: true })\n submittedValuesJson: string | null;"}
{"path":"apps/server/src/ai-chat/entities/ai-form.entity.ts","start_line":59,"end_line":60,"category":"bug","severity":"low","content":"`submit_label` is limited to varchar(20), but this is a user-facing custom label (default '提交'). Longer labels will be silently truncated (or rejected in strict SQL modes), losing data the user explicitly entered. Consider widening the column (e.g. varchar(50)) or validating/clamping the length in the service before persistence.","suggestion_code":null,"existing_code":" @Column({ name: 'submit_label', type: 'varchar', length: 20, default: '提交' })\n submitLabel: string;"}
{"path":"apps/server/src/ai-chat/entities/ai-form.entity.ts","start_line":49,"end_line":51,"category":"maintainability","severity":"low","content":"The FK column `assistantMessageId` is non-nullable, but the relation property is declared as `AiMessage | null` and `@ManyToOne` does not state `nullable: false`. This makes the relation metadata inconsistent with the column definition and forces callers to handle a null that can never occur. Set `nullable: false` on the relation and type the property as `AiMessage`.","suggestion_code":null,"existing_code":" @ManyToOne(() => AiMessage, { onDelete: 'CASCADE' })\n @JoinColumn({ name: 'assistant_message_id' })\n assistantMessage: AiMessage | null;"}
{"path":"apps/server/src/ai-chat/entities/ai-review.entity.ts","start_line":73,"end_line":74,"category":"maintainability","severity":"medium","content":"`sectionsJson` is stored as raw `text` and typed as plain `string`, even though this file defines the typed `AiReviewSection` contract. Every read/write of this field requires callers to manually `JSON.parse`/`JSON.stringify` with ad-hoc error handling, which is error-prone (malformed JSON will throw at runtime). Consider using a `ColumnTransformer` (or the `json` column type) so the entity field can be typed as `AiReviewSection[]` and serialization is centralized and validated in one place.","suggestion_code":null,"existing_code":"@Column({ name: 'sections_json', type: 'text' })\n sectionsJson: string;"}
{"path":"apps/server/src/ai-chat/entities/ai-review.entity.ts","start_line":63,"end_line":64,"category":"maintainability","severity":"low","content":"The `@ManyToOne` relation defaults to `nullable: true`, which is inconsistent with the explicitly declared non-nullable `assistant_message_id` column (`@Column` without `nullable: true`). This can produce a schema where the FK relationship allows `NULL` while the column does not, and it weakens the domain invariant (a review must always reference an assistant message). Add `nullable: false` to the relation to keep the DDL and the model consistent.","suggestion_code":"@ManyToOne(() => AiMessage, { nullable: false, onDelete: 'CASCADE' })\n @JoinColumn({ name: 'assistant_message_id' })","existing_code":"@ManyToOne(() => AiMessage, { onDelete: 'CASCADE' })\n @JoinColumn({ name: 'assistant_message_id' })"}
{"path":"apps/server/src/ai-chat/entities/ai-review.entity.ts","start_line":54,"end_line":55,"category":"performance","severity":"low","content":"`conversation_id` is a core query key for chat flows (fetching all reviews of a conversation), yet no index exists on it, while the composite index is on `(userId, status)` and another on `assistantMessageId`. If the typical access pattern is `WHERE conversation_id = ? (AND status = ?)`, these indexes won't serve it and scans will occur as review rows accumulate. Consider adding an index on `conversationId` (or a `(conversationId, status)` composite) if query patterns confirm it.","suggestion_code":null,"existing_code":"@Column({ name: 'conversation_id', type: 'integer' })\n conversationId: number;"}
{"path":"apps/server/src/ai-chat/entities/ai-tool-run.entity.ts","start_line":15,"end_line":15,"category":"maintainability","severity":"low","content":"This explicit index on `messageId` is redundant: InnoDB automatically creates an index on a foreign-key column when the `@ManyToOne`/`@JoinColumn` FK constraint (with `onDelete: 'CASCADE'`) is created. Keeping a second, separately named index on the same column wastes storage and adds write overhead for no query benefit. Consider removing `@Index('idx_ai_tool_runs_message', ['messageId'])` and relying on the FK's auto-created index.","suggestion_code":"@Entity('ai_tool_runs')","existing_code":"@Index('idx_ai_tool_runs_message', ['messageId'])"}
{"path":"apps/server/src/ai-config/ai-config.entity.ts","start_line":33,"end_line":34,"category":"security","severity":"medium","content":"Sensitive credential fields (`encryptedApiKey`, `apiKeyIv`, `apiKeyAuthTag`) are selected by default on every query. If this entity is ever returned directly in an API response, logged, or serialized, the ciphertext, IV, and auth tag will leak. Mark these columns with `select: false` so they are only loaded when explicitly requested, and never included in default queries/serialization.","suggestion_code":" @Column({ name: 'encrypted_api_key', type: 'text', nullable: true, select: false })\n encryptedApiKey: string | null;","existing_code":" @Column({ name: 'encrypted_api_key', type: 'text', nullable: true })\n encryptedApiKey: string | null;"}
{"path":"apps/server/src/ai-config/ai-config.entity.ts","start_line":27,"end_line":28,"category":"maintainability","severity":"low","content":"The `provider` column is declared as a TS enum (`AiProvider`) but persisted as plain `varchar`, so the DB accepts arbitrary strings and TypeORM will silently return any invalid value as the enum type at runtime. Use `type: 'enum'` with the `enum` option to enforce valid values at the database level, or explicitly document why varchar was chosen.","suggestion_code":" @Column({ type: 'enum', enum: AiProvider, default: AiProvider.DEEPSEEK })\n provider: AiProvider;","existing_code":" @Column({ type: 'varchar', length: 50, default: AiProvider.DEEPSEEK })\n provider: AiProvider;"}
{"path":"apps/server/src/ai-config/ai-config.controller.ts","start_line":41,"end_line":44,"category":"bug","severity":"medium","content":"Audit logging runs *after* the config has already been persisted, and the hostname is extracted with an unguarded `new URL(config.baseUrl).hostname`. If URL parsing throws or the operation-logs insert fails, this handler returns 500 even though the save already succeeded — the client believes the save failed and may retry, causing duplicate writes/audits. Extract the hostname defensively and make the audit write best-effort so it cannot invalidate an already-successful operation.","suggestion_code":" const config = await this.service.saveConfig(body);\n try {\n let hostname = '-';\n try { hostname = new URL(config.baseUrl).hostname; } catch { /* keep '-' */ }\n await logAudit(this.opLog, req, {\n module: 'ai-config', action: 'save', targetId: config.id, targetType: 'AiConfig', detail: `provider=${body.provider} host=${hostname} model=${body.defaultModel ? 'configured' : 'not-set'}`,\n });\n } catch {\n // audit-log failure must not turn a successful save into an error response\n }","existing_code":" const config = await this.service.saveConfig(body);\n await logAudit(this.opLog, req, {\n module: 'ai-config', action: 'save', targetId: config.id, targetType: 'AiConfig', detail: `provider=${body.provider} host=${new URL(config.baseUrl).hostname} model=${body.defaultModel ? 'configured' : 'not-set'}`,\n });"}
{"path":"apps/server/src/ai-config/ai-config.controller.ts","start_line":68,"end_line":71,"category":"bug","severity":"medium","content":"Same audit-after-mutation hazard: the API key has already been cleared from the DB when `logAudit` runs. If the audit insert fails (e.g. operation-logs table unavailable), the client receives a 500 although the key was successfully cleared — misleading and may cause confusing retries. Wrap the audit write in try/catch or log-and-continue.","suggestion_code":" const data = await this.service.clearKey();\n try {\n await logAudit(this.opLog, req, {\n module: 'ai-config', action: 'clear-key', targetType: 'AiConfig', detail: `keySource=${data.keySource}`,\n });\n } catch {\n // audit-log failure must not turn a successful clear into an error response\n }","existing_code":" const data = await this.service.clearKey();\n await logAudit(this.opLog, req, {\n module: 'ai-config', action: 'clear-key', targetType: 'AiConfig', detail: `keySource=${data.keySource}`,\n });"}
{"path":"apps/server/src/ai-config/ai-config.controller.ts","start_line":51,"end_line":54,"category":"bug","severity":"low","content":"Same audit-after-mutation pattern as the other handlers: a successful connection test is followed by `logAudit`; if that audit write fails, the endpoint returns an error even though the test succeeded. Consider making the audit write best-effort so logging failures cannot override the real operation result.","suggestion_code":null,"existing_code":" const result = await this.service.testConnection(body);\n await logAudit(this.opLog, req, {\n module: 'ai-config', action: 'test', targetType: 'AiConfig', detail: `provider=${body.provider ?? '-'} success=${result.success} latency=${result.latencyMs ?? '-'}`, status: result.success ? 'success' : 'failure',\n });"}
{"path":"apps/server/src/ai-config/ai-config.probe.ts","start_line":146,"end_line":152,"category":"maintainability","severity":"medium","content":"Nested ternary expressions are used to build the connection message, which violates the review rule that nested ternaries are not allowed and reduces readability. Refactor into explicit if/else branches.","suggestion_code":" let message: string;\n if (modelAvailable) {\n message = `连接成功，目标模型 \"${effectiveDefaultModel}\" 可用`;\n } else if (effectiveDefaultModel) {\n message = '连接成功，但未找到目标模型';\n } else if (models.length > 0) {\n message = `连接成功，可用模型 ${models.length} 个`;\n } else {\n message = '连接成功，但未返回可用模型';\n }","existing_code":" const message = modelAvailable\n ? `连接成功，目标模型 \"${effectiveDefaultModel}\" 可用`\n : effectiveDefaultModel\n ? '连接成功，但未找到目标模型'\n : models.length > 0\n ? `连接成功，可用模型 ${models.length} 个`\n : '连接成功，但未返回可用模型';"}
{"path":"apps/server/src/ai-config/ai-config.probe.ts","start_line":164,"end_line":173,"category":"maintainability","severity":"medium","content":"This error-message mapping uses nested ternaries (not allowed by the review rules) and, worse, the '禁止重定向' branch maps to the exact same string as the fallback branch, making the extra branch dead logic. Simplify with if/else and drop the redundant branch.","suggestion_code":" let message = '连接失败，请检查 Base URL';\n if (err instanceof Error && err.message === '连接超时') {\n message = '连接超时';\n } else if (err instanceof Error && err.message === '响应过大') {\n message = '响应过大';\n }","existing_code":" const message =\n err instanceof Error\n ? err.message === '连接超时'\n ? '连接超时'\n : err.message === '响应过大'\n ? '响应过大'\n : err.message === '禁止重定向'\n ? '连接失败，请检查 Base URL'\n : '连接失败，请检查 Base URL'\n : '连接失败，请检查 Base URL';"}
{"path":"apps/server/src/ai-config/ai-config.probe.ts","start_line":203,"end_line":207,"category":"maintainability","severity":"medium","content":"testConnection and fetchModels duplicate nearly the same flow: baseUrl validation, DNS SSRF check, API-key resolution, the /models HTTP call, and HTTP-status classification (401/403, >=500, >=400, non-JSON). Extract this into a shared helper so the two entry points cannot diverge in behavior (e.g., different error messages for the same failure).","suggestion_code":null,"existing_code":" const message = err instanceof BadRequestException ? err.message : '请求参数无效';\n return { success: false, models: [], message };\n }\n\n // DNS SSRF check"}
{"path":"apps/server/src/ai-config/ai-config.probe.ts","start_line":126,"end_line":131,"category":"maintainability","severity":"low","content":"The JSON-parse failure path saves the config manually and returns early, duplicating the shared save block at the end of testConnection. Any future change to the final save logic (e.g., adding a field) will silently diverge on this path. Build the failure `result` here and fall through to the single save at the end instead of saving and returning early.","suggestion_code":null,"existing_code":" } catch {\n config.lastTestedAt = new Date();\n config.lastTestLatencyMs = latencyMs;\n config.verified = false;\n await context.save(config);\n return {"}
{"path":"apps/server/src/ai-config/ai-config.probe.ts","start_line":18,"end_line":21,"category":"maintainability","severity":"low","content":"resolveApiKey is declared to accept `AiConfig | null`, but every call site in this file passes a non-null config returned by getOrCreateConfig(). Either drop `null` from the parameter type or add a null guard at call sites so the type accurately reflects the contract.","suggestion_code":null,"existing_code":" resolveApiKey(config: AiConfig | null): {\n plaintext: string | null;\n source: 'database' | 'environment' | 'none';\n };"}
{"path":"apps/server/src/app.module.ts","start_line":168,"end_line":168,"category":"bug","severity":"high","content":"synchronize defaults to `true` whenever DB_SYNCHRONIZE is not set, including production, and the loose `!== 'false'` comparison treats any value other than the literal string 'false' (e.g. '0', 'no', '', 'TRUE') as enabling auto-sync. Combined with the large entity list and the migrations array defined just above, TypeORM auto-sync can silently alter/drop columns and conflict with the migration history, risking real data loss. Recommend defaulting to `false` in production and parsing strictly, e.g.: synchronize: config.get('DB_SYNCHRONIZE', process.env.NODE_ENV === 'production' ? 'false' : 'true') === 'true'","suggestion_code":"synchronize: config.get('DB_SYNCHRONIZE', process.env.NODE_ENV === 'production' ? 'false' : 'true') === 'true',","existing_code":"synchronize: config.get('DB_SYNCHRONIZE', 'true') !== 'false',"}
{"path":"apps/server/src/app.module.ts","start_line":162,"end_line":162,"category":"bug","severity":"low","content":"ConfigService.get returns environment variables as strings, so when DB_PORT is set (e.g. DB_PORT=3306) the value passed to the mysql driver is a string despite the `number` type parameter. Coerce it explicitly to avoid connection/type inconsistencies.","suggestion_code":"port: Number(config.get('DB_PORT', 3306)),","existing_code":"port: config.get('DB_PORT', 3306),"}
{"path":"apps/server/src/app.module.ts","start_line":23,"end_line":23,"category":"maintainability","severity":"low","content":"The allMigrations array is declared in the middle of the import block; the subsequent import statements for feature modules come after executable code. Although ESM import hoisting makes this work, it hurts readability and import-order linting. Move all import statements to the top of the file and place the migration array after them.","suggestion_code":null,"existing_code":"const allMigrations = ["}
{"path":"apps/server/src/app.module.ts","start_line":89,"end_line":89,"category":"maintainability","severity":"low","content":"The throttling window/limit (ttl: 60000, limit: 100) are hardcoded business values. Per the project rules, business numbers should not be hardcoded - read them from configuration/env so each deployment can tune rate limits without a code change.","suggestion_code":null,"existing_code":"limit: 100, // 普通接口每分钟100次"}
{"path":"apps/server/src/ai-chat/entities/ai-message.entity.ts","start_line":73,"end_line":74,"category":"bug","severity":"low","content":"`datetime` in MySQL has second precision only (no fractional seconds). The composite index `idx_ai_messages_conversation_created` on (conversationId, createdAt) is presumably used for conversation history pagination, but multiple messages created within the same second will share an identical `createdAt`, making `ORDER BY createdAt` / cursor-based pagination (`createdAt < x`) non-deterministic — rows can be skipped or duplicated. Since this app persists multiple messages in quick succession (e.g., streaming/tool-run splits), consider `datetime(6)` (or `datetime(3)`) for both timestamp columns, and/or add `id` as a secondary sort key in pagination queries.","suggestion_code":" @CreateDateColumn({ name: 'created_at', type: 'datetime(6)' })\n createdAt: Date;","existing_code":" @CreateDateColumn({ name: 'created_at', type: 'datetime' })\n createdAt: Date;"}
{"path":"apps/server/src/ai-chat/entities/ai-message.entity.ts","start_line":46,"end_line":47,"category":"bug","severity":"low","content":"The DB-level default for `status` is `'completed'`, but the actual initial lifecycle state of a message is `'pending'` (the streaming flow inserts messages with `status: 'pending'`, and `pending` is the first member of `AiMessageStatus`). Any insert that omits an explicit `status` (e.g., raw SQL, bulk insert, partial entity save) will silently record an unfinished message as `'completed'`, corrupting the conversation state. Align the default with the initial state (`'pending'`) or drop the default so `status` is always set explicitly.","suggestion_code":" @Column({ type: 'varchar', length: 20, default: 'pending' })\n status: AiMessageStatus;","existing_code":" @Column({ type: 'varchar', length: 20, default: 'completed' })\n status: AiMessageStatus;"}
{"path":"apps/server/src/archive/archive-report.attendance.ts","start_line":118,"end_line":118,"category":"bug","severity":"high","content":"Session label mismatch causes the entire detail matrix to render empty. The stored `session` values are English keys — `morning_reading`/`morning`/`afternoon`/`evening_study`/`night_check` (see `@IsIn` in attendance.dto.ts and `mapLessonScheduleTimeToSession` in attendance-time.ts) — but here the table columns are hardcoded Chinese labels `['上午','下午','晚自习']`. `cellMap` is keyed by `r.session`, so `cellMap.get(session)` never matches and every cell always shows `-`, silently dropping all detail data from the report. Additionally the system defines 5 session slots while only 3 columns are rendered. Suggest mapping the real session keys to display labels (covering all 5), e.g. build the columns from `{ morning_reading: '早读', morning: '上午', afternoon: '下午', evening_study: '晚自习', night_check: '晚查' }` or from the actual keys present in the records.","suggestion_code":null,"existing_code":" const sessions = ['上午', '下午', '晚自习'];"}
{"path":"apps/server/src/archive/archive-report.attendance.ts","start_line":138,"end_line":138,"category":"bug","severity":"low","content":"The heading says \"最近30条\" (last 30 records), but `dates.slice(-30)` limits the number of distinct *dates*; each date can contain up to 3 sessions (or more, once the session mapping is fixed), so the table can show far more than 30 records. Make the label/behavior consistent, e.g. rename to \"最近30天\" or slice the records themselves.","suggestion_code":null,"existing_code":" 考勤明细（最近30条）
"}
{"path":"apps/server/src/archive/archive-report.attendance.ts","start_line":58,"end_line":59,"category":"maintainability","severity":"low","content":"The per-status counting logic is duplicated: `buildAttendance` filters records 4 times (`r.status === 'present'/'absent'/'late'/'leave'`) and `renderAttendanceBar` recomputes the same counts via `statuses.map(...)`. If a new status is added, the two places can drift. Consider extracting a shared helper (e.g. `countByStatus(records)` returning a partial counts object) used by both.","suggestion_code":null,"existing_code":" const statuses = ['present', 'absent', 'late', 'leave'] as const;\n const counts = statuses.map((s) => records.filter((r) => r.status === s).length);"}
{"path":"apps/server/src/ai-config/dto/ai-config.dto.ts","start_line":64,"end_line":90,"category":"maintainability","severity":"medium","content":"The validation field definitions (`provider`, `baseUrl`, `apiKey`, `timeoutMs`, `reasoningEffort`) are duplicated almost verbatim across `SaveAiConfigDto`, `TestAiConfigDto`, and `FetchModelsDto`. This makes it easy for the DTOs to drift out of sync (e.g., adding a new field to one but forgetting the others). Consider extracting a shared base DTO (e.g., `AiConfigConnectionFieldsDto`) holding the common optional-validated fields and extending it in all three DTOs.","suggestion_code":null,"existing_code":"export class TestAiConfigDto {\n @IsOptional()\n @IsIn(PROVIDERS)\n provider?: AiProvider;\n\n @IsOptional()\n @IsString()\n baseUrl?: string;\n\n @IsOptional()\n @IsString()\n apiKey?: string;\n\n @IsOptional()\n @IsString()\n defaultModel?: string;\n\n @IsOptional()\n @IsInt()\n @Min(1000)\n @Max(120000)\n timeoutMs?: number;\n\n @IsOptional()\n @IsIn(REASONING_EFFORT_LEVELS)\n reasoningEffort?: string | null;\n}"}
{"path":"apps/server/src/ai-config/dto/ai-config.dto.ts","start_line":58,"end_line":61,"category":"maintainability","severity":"low","content":"`reasoningEffort` is declared as `string | null` even though the `@IsIn(REASONING_EFFORT_LEVELS)` decorator restricts runtime values to the exported union. This type gap lets callers compile invalid values (e.g., `'extreme'`) that will then fail at runtime with a validation error. Type it as `(typeof REASONING_EFFORT_LEVELS)[number] | null` to get compile-time enforcement matching the validator. The same applies to `AiConfigResponseDto.reasoningEffort` and `AiRuntimeConfig.reasoningEffort` below.","suggestion_code":null,"existing_code":" @IsOptional()\n @IsIn(REASONING_EFFORT_LEVELS)\n reasoningEffort?: string | null;\n}"}
{"path":"apps/server/src/ai-config/ai-config.service.ts","start_line":190,"end_line":196,"category":"bug","severity":"medium","content":"Validation gap / logic inconsistency: when the client omits `enabled` (it is optional in `SaveAiConfigDto`), the `else` branch force-sets `config.enabled = true`, but the required-key/model check only runs when `dto.enabled === true`. As a result, a PUT that only updates e.g. the API key (or `defaultModel: ''`, which is coerced to null) will silently enable AI with no key/model, producing a state that later throws '未配置 API Key' / '未配置默认模型' in `getRuntimeConfig`. Validate against the final `config.enabled` instead.","suggestion_code":" if (config.enabled) {\n const { plaintext } = this.resolveApiKey(config);\n if (!plaintext) throw new BadRequestException('启用 AI 服务前必须配置 API Key');\n if (!config.defaultModel?.trim()) {\n throw new BadRequestException('启用 AI 服务前必须配置默认模型');\n }\n }","existing_code":" if (dto.enabled === true) {\n const { plaintext } = this.resolveApiKey(config);\n if (!plaintext) throw new BadRequestException('启用 AI 服务前必须配置 API Key');\n if (!config.defaultModel?.trim()) {\n throw new BadRequestException('启用 AI 服务前必须配置默认模型');\n }\n }"}
{"path":"apps/server/src/ai-config/ai-config.service.ts","start_line":127,"end_line":131,"category":"maintainability","severity":"low","content":"Nested ternary is prohibited by the project review rules. Extract this masking logic into a small helper or a plain if/else so the display logic stays readable, e.g. compute `maskedApiKey` before building the response object.","suggestion_code":null,"existing_code":" maskedApiKey: config.keyLast4\n ? this.buildMaskedKey(config.keyLast4)\n : source !== 'none'\n ? '••••'\n : null,"}
{"path":"apps/server/src/ai-config/ai-config.service.ts","start_line":116,"end_line":117,"category":"bug","severity":"low","content":"`getConfig()` calls `resolveApiKey(config)`, which throws `InternalServerErrorException` whenever the stored ciphertext/IV/authTag cannot be decrypted. A single corrupted DB key then makes the entire GET config endpoint (and hence the settings UI) return 500 with no way to inspect or fix the rest of the config through that endpoint (only `clearKey` recovers, and it is not reachable from a UI that depends on GET). Consider catching the decryption failure here and reporting `hasApiKey`/`hasDatabaseKey` as false (or an explicit 'decrypt-failed' state) instead of failing the whole request.","suggestion_code":null,"existing_code":" const config = await this.getOrCreateConfig();\n const { source } = this.resolveApiKey(config);"}
{"path":"apps/server/src/archive/archive-report.cover.ts","start_line":33,"end_line":33,"category":"security","severity":"medium","content":"The full national ID (身份证号) is rendered unmasked on the report cover. This is highly sensitive PII; even though the report footer labels it confidential, such reports can be printed, emailed, or leaked. Recommend masking it (e.g., keep first 6 + last 4 digits: `123456********1234`) unless the full number is strictly required for archival use, and if so, gate the full value behind access control rather than including it in the default cover layout.","suggestion_code":null,"existing_code":"学号: ${esc(student.studentNo || '-')}
身份证号: ${esc(student.idNumber || '-')}
"}
{"path":"apps/server/src/archive/archive-report.learning.ts","start_line":52,"end_line":53,"category":"bug","severity":"medium","content":"The loose inequality `!= null` is prohibited by the review rules; use strict equality or the nullish coalescing operator. Note also that these are `decimal` DB columns (TypeORM/MySQL may return them as strings at runtime), and they are interpolated into HTML without `esc()`, which is inconsistent with the other fields — escape them for safety (e.g., `esc(String(result.cultureFinalScore ?? '')) || '-'`).","suggestion_code":" 文化课成绩${esc(String(result.cultureFinalScore ?? '')) || '-'}
\n 专业课成绩${esc(String(result.professionalFinalScore ?? '')) || '-'}
","existing_code":" 文化课成绩${result.cultureFinalScore != null ? result.cultureFinalScore : '-'}
\n 专业课成绩${result.professionalFinalScore != null ? result.professionalFinalScore : '-'}
"}
{"path":"apps/server/src/archive/archive-report.learning.ts","start_line":19,"end_line":26,"category":"maintainability","severity":"low","content":"Both `buildLearning` and `buildResult` duplicate the same `sectionFrame(sectionHeader(...) + title-row)` wrapper boilerplate. Consider extracting a shared helper (e.g., `archiveSection(title, body, source?)`) to avoid duplication and keep the two builders consistent.","suggestion_code":null,"existing_code":" return sectionFrame(`\n ${sectionHeader('学情记录')}\n \n
\n
${esc(now)} · 系统生成
\n
学情记录
\n
\n
${e.score !== null ? e.score : '-'} | \n ${e.classAvg !== null ? e.classAvg : '-'} | \n ${e.rank !== null ? e.rank : '-'} | ","existing_code":" ${e.score != null ? e.score : '-'} | \n ${e.classAvg != null ? e.classAvg : '-'} | \n ${e.rank != null ? e.rank : '-'} | "}
{"path":"apps/server/src/archive/dto/archive.dto.ts","start_line":4,"end_line":4,"category":"bug","severity":"medium","content":"All fields are optional, so an empty body `{}` passes validation. In `archive.service.ts#upsertProfile`, when no profile exists the code runs `profileRepo.create({ ...dto, studentId })`, which would insert an empty record; and because `@IsOptional()` also allows `null` through, a payload like `{ targetCollege: null }` will overwrite existing data via `Object.assign(profile, dto)`. Recommend requiring at least one field (custom validator) for upsert, or splitting into a CreateDto with required fields plus a PartialType-based UpdateDto.","suggestion_code":null,"existing_code":"export class UpsertProfileDto {"}
{"path":"apps/server/src/archive/dto/archive.dto.ts","start_line":51,"end_line":51,"category":"bug","severity":"medium","content":"Same all-optional issue as `UpsertProfileDto`: an empty body passes validation and `archive.service.ts#upsertResult` will create an empty result record for a new student, while explicit `null` values (allowed by `@IsOptional()`) can erase existing result fields via `Object.assign(result, dto)`. Consider requiring at least one field or using a dedicated CreateDto/UpdateDto split.","suggestion_code":null,"existing_code":"export class UpsertResultDto {"}
{"path":"apps/server/src/archive/dto/archive.dto.ts","start_line":26,"end_line":26,"category":"maintainability","severity":"low","content":"`PartialType` makes every field optional, so an empty body `{}` passes validation and `updateEnrollment` becomes a silent no-op (`Object.assign(entity, dto)` with no keys). If this endpoint is meant to be a full update (PUT semantics), empty payloads should be rejected; if PATCH semantics are intended, consider validating that the body is non-empty to avoid silent no-ops. The same applies to `UpdateExamScoreDto` and `UpdateLearningRecordDto`.","suggestion_code":null,"existing_code":"export class UpdateEnrollmentDto extends PartialType(CreateEnrollmentDto) {}"}
{"path":"apps/server/src/archive/archive.controller.ts","start_line":211,"end_line":211,"category":"bug","severity":"medium","content":"`file` will be `undefined` when the multipart request does not include a `file` field (or the field name differs). In that case, before the service's friendly `addAttachment` validation (which throws `BadRequestException('请选择附件文件')`) is ever reached, the audit-detail callback dereferences `file.originalname` and raises an unhandled TypeError -> HTTP 500. Guard the file first (e.g., `if (!file) throw new BadRequestException(...)`) or use `ParseFilePipe` with `FileTypeValidator`/`MaxFileSizeValidator` so a missing/invalid file is rejected before the handler runs.","suggestion_code":" module: '学生档案', action: '上传附件', targetId: result.id, targetType: 'archive_attachment', detail: `${file?.originalname || ''} (${category || 'other'})`,","existing_code":" module: '学生档案', action: '上传附件', targetId: result.id, targetType: 'archive_attachment', detail: `${file.originalname} (${category || 'other'})`,"}
{"path":"apps/server/src/archive/archive.controller.ts","start_line":203,"end_line":204,"category":"security","severity":"high","content":"`FileInterceptor` is used without any `limits` and defaults to multer memory storage, so the entire uploaded file is buffered in RAM with no size cap (multer's default file size limit is unlimited). A malicious/large upload can exhaust server memory (DoS), and arbitrary file types are accepted. Configure `limits: { fileSize: ... }` and validate the content type / file signature before persisting.","suggestion_code":" @UseInterceptors(FileInterceptor('file', { limits: { fileSize: 10 * 1024 * 1024 } }))\n async uploadAttachment(","existing_code":" @UseInterceptors(FileInterceptor('file'))\n async uploadAttachment("}
{"path":"apps/server/src/archive/archive.controller.ts","start_line":226,"end_line":227,"category":"security","severity":"high","content":"Stored XSS risk: `mimeType` is stored verbatim from the client-supplied upload header (see `addAttachment` in the service) and later served with `Content-Disposition: inline` from the same origin. An attacker can upload a `.html`/`.svg` file claiming `text/html` and it will render/execute in the app origin when downloaded. Use `attachment` disposition (forces download instead of inline rendering) and/or whitelist safe content types when serving.","suggestion_code":" res.setHeader('Content-Disposition', `attachment; filename=\"${encodeURIComponent(fileName)}\"`);","existing_code":" res.setHeader('Content-Type', mimeType);\n res.setHeader('Content-Disposition', `inline; filename=\"${encodeURIComponent(fileName)}\"`);"}
{"path":"apps/server/src/archive/archive.controller.ts","start_line":228,"end_line":229,"category":"bug","severity":"medium","content":"`fs.createReadStream(fullPath)` has no `error` listener. Although the service checks `fs.existsSync` beforehand, that is a TOCTOU race (file can be deleted/rotated between the check and the open) and read errors can still occur. An unhandled 'error' event on the stream will throw and can crash the process, or leave the client connection hanging. Attach `stream.on('error', ...)` that ends the response with an error status.","suggestion_code":" const stream = fs.createReadStream(fullPath);\n stream.on('error', (err) => {\n if (!res.headersSent) res.status(500);\n res.end();\n });\n stream.pipe(res);","existing_code":" const stream = fs.createReadStream(fullPath);\n stream.pipe(res);"}
{"path":"apps/server/src/archive/archive.controller.ts","start_line":65,"end_line":65,"category":"security","severity":"low","content":"Audit logs write the full request DTO via `JSON.stringify(dto)` for profile, enrollment, exam-score, learning-record, and result mutations. These DTOs contain student personal data / scores (PII), and `detail` is persisted to the operation-logs table and may end up in other log sinks. Consider logging only a summary (field names changed or non-sensitive attributes) to comply with data minimization.","suggestion_code":null,"existing_code":" module: '学生档案', action: '更新档案信息', targetId: studentId, targetType: 'student_profile', detail: JSON.stringify(dto),"}
{"path":"apps/server/src/attendance-devices/attendance-devices.controller.ts","start_line":41,"end_line":43,"category":"bug","severity":"medium","content":"The audit log write runs after the DB mutation has already succeeded in create/update/remove. If `logService.log` throws (e.g., operation-log table failure), the request returns a 500 even though the device was created/updated/deleted — the client may retry and hit duplicate-SN conflicts or otherwise see inconsistent state. Wrap the logging in a try/catch (or make it non-blocking) so audit failures don't break the main operation; consider extracting this duplicated log block into a private helper since it's repeated identically in all three mutation methods.","suggestion_code":" const result = await this.service.create(dto);\n try {\n await this.logService.log({\n userId: req.user?.id,","existing_code":" const result = await this.service.create(dto);\n await this.logService.log({\n userId: req.user?.id,"}
{"path":"apps/server/src/attendance-devices/attendance-devices.controller.ts","start_line":31,"end_line":34,"category":"bug","severity":"medium","content":"The `status` query param is unvalidated user input that flows directly into the TypeORM where clause (`where.status = query.status`). Any arbitrary string (e.g. `?status=foo`) is accepted and just yields an empty result, while a repeated param can arrive as a `string[]` and cause a DB error. Similarly, `Number(classroomId)` silently produces `NaN` for non-numeric input. Validate/whitelist these query params (e.g. ParseEnumPipe / ParseIntPipe or explicit checks) before querying, so the API contract is enforced instead of relying on downstream falsy filtering.","suggestion_code":" const parsedStatus =\n status === AttendanceDeviceStatus.ACTIVE || status === AttendanceDeviceStatus.DISABLED\n ? status\n : undefined;\n const parsedClassroomId = classroomId && Number.isFinite(Number(classroomId)) ? Number(classroomId) : undefined;\n return this.service.findAll({\n classroomId: parsedClassroomId,\n status: parsedStatus,\n });","existing_code":" return this.service.findAll({\n classroomId: classroomId ? Number(classroomId) : undefined,\n status,\n });"}
{"path":"apps/server/src/attendance-devices/dto/attendance-device.dto.ts","start_line":15,"end_line":16,"category":"bug","severity":"medium","content":"classroomId has no lower-bound validation: @IsInt() accepts 0 and negative values, so an invalid classroom ID (e.g., 0 or -1) passes DTO validation and only fails later at the DB foreign-key layer (producing a 500 instead of a 400). Add @IsPositive() (or @Min(1)) to both CreateAttendanceDeviceDto and UpdateAttendanceDeviceDto.","suggestion_code":" @IsInt()\n @IsPositive()\n classroomId: number;","existing_code":" @IsInt()\n classroomId: number;"}
{"path":"apps/server/src/attendance-devices/dto/attendance-device.dto.ts","start_line":27,"end_line":29,"category":"security","severity":"low","content":"notes has no length limit, while the analogous location field is capped at @MaxLength(200). Since this value comes from user input and is persisted to the DB, unbounded notes allows oversized payloads to be accepted. Add @MaxLength (e.g., 1000 or a value aligned with the intended content) for consistency and input-size control.","suggestion_code":" @IsOptional()\n @IsString()\n @MaxLength(1000)\n notes?: string;","existing_code":" @IsOptional()\n @IsString()\n notes?: string;"}
{"path":"apps/server/src/attendance-devices/dto/attendance-device.dto.ts","start_line":32,"end_line":35,"category":"maintainability","severity":"low","content":"UpdateAttendanceDeviceDto duplicates all field declarations and validation decorators of CreateAttendanceDeviceDto (only swapping required vs optional). This duplication is error-prone when the schema evolves (fields/decorators can drift between the two classes). Consider deriving it from the create DTO using PartialType(CreateAttendanceDeviceDto) from @nestjs/mapped-types.","suggestion_code":"import { PartialType } from '@nestjs/mapped-types';\n\nexport class UpdateAttendanceDeviceDto extends PartialType(CreateAttendanceDeviceDto) {}","existing_code":"export class UpdateAttendanceDeviceDto {\n @IsOptional()\n @IsString()\n @IsNotEmpty()"}
{"path":"apps/server/src/archive/archive.service.ts","start_line":300,"end_line":301,"category":"security","severity":"high","content":"IDOR risk: this method (like deleteEnrollment/updateEnrollment/updateExamScore/deleteExamScore/purge* etc.) operates only by `id` without verifying the record belongs to the current student. Note getAttachmentFile does scope by `studentId`, so the API surface is inconsistent. If access is only role-based, any authenticated student can archive/delete other students' records by enumerating ids. Scope the query with the caller's student id (e.g., `{ id, studentId }`) or enforce an explicit ownership check.","suggestion_code":null,"existing_code":" async deleteAttachment(id: number) {\n const entity = await this.attachmentRepo.findOne({ where: { id } });"}
{"path":"apps/server/src/archive/archive.service.ts","start_line":273,"end_line":273,"category":"performance","severity":"medium","content":"`fs.writeFileSync` (and `fs.mkdirSync`/`fs.unlinkSync` elsewhere) runs synchronously inside an async request handler and blocks the Node.js event loop, hurting concurrency under load. Use `await fs.promises.writeFile` / `fs.promises.mkdir` instead.","suggestion_code":null,"existing_code":" fs.writeFileSync(filePath, file.buffer);"}
{"path":"apps/server/src/archive/archive.service.ts","start_line":273,"end_line":275,"category":"bug","severity":"medium","content":"If `attachmentRepo.save()` throws after the file has been written to disk, the file becomes an orphan that is never cleaned up. Wrap the file write + DB save in a try/catch and unlink the file when persistence fails.","suggestion_code":null,"existing_code":" fs.writeFileSync(filePath, file.buffer);\n\n const entity = this.attachmentRepo.create({"}
{"path":"apps/server/src/archive/archive.service.ts","start_line":271,"end_line":271,"category":"bug","severity":"low","content":"`Date.now()` only has millisecond resolution; two concurrent uploads for the same student in the same millisecond produce the same filename and silently overwrite each other's file (both DB rows then point to the same file). Use `crypto.randomUUID()` or `crypto.randomBytes()` to generate a collision-resistant filename.","suggestion_code":null,"existing_code":" const filename = `${studentId}_${Date.now()}${ext}`;"}
{"path":"apps/server/src/archive/archive.service.ts","start_line":281,"end_line":281,"category":"security","severity":"medium","content":"`mimeType` is taken from client-controlled upload metadata (`file.mimetype`) and later used to serve the file. An attacker can upload a file labeled `text/html` containing script, which can lead to stored XSS if served inline from the same origin. Validate actual file content (magic bytes/extension whitelist) and ensure the file is served with `X-Content-Type-Options: nosniff` and `Content-Disposition: attachment`.","suggestion_code":null,"existing_code":" mimeType: file.mimetype,"}
{"path":"apps/server/src/archive/archive.service.ts","start_line":290,"end_line":290,"category":"bug","severity":"low","content":"`entity.filePath` can be null/empty for legacy or partial records; `resolveAttachmentPath` calls `filePath.replace(...)` which would throw a TypeError (500) instead of a clean 404. Guard for a missing filePath before resolving.","suggestion_code":null,"existing_code":" const fullPath = this.resolveAttachmentPath(entity.filePath);"}
{"path":"apps/server/src/archive/archive.service.ts","start_line":149,"end_line":149,"category":"maintainability","severity":"low","content":"The business status literal `'archived'` is repeated across many methods (enrollment/examScore/learningRecord/attachment). Extract it to a shared constant or enum to avoid typos and drift between soft-delete checks.","suggestion_code":null,"existing_code":" if (entity.status === 'archived') throw new BadRequestException('报名记录已归档');"}
{"path":"apps/server/src/ai-config/ai-config.helpers.ts","start_line":108,"end_line":108,"category":"security","severity":"medium","content":"SSRF hardening gap: this private/reserved IP list is missing several ranges commonly used on internal networks, e.g. 198.18.0.0/15 (benchmarking), 192.0.0.0/24, 224.0.0.0/4 (multicast), 240.0.0.0/4 (reserved) and 255.255.255.255/32. The IPv6 branch also does not cover the deprecated site-local fec0::/10 (only fe8-feb link-local is matched) nor IPv4-compatible ::/96. An attacker able to point an OPENAI_COMPATIBLE baseUrl at a host in these ranges would bypass the SSRF check. Consider adding the missing ranges and the fec0::/10 prefix.","suggestion_code":null,"existing_code":"export function isPrivateHost(hostname: string): boolean {"}
{"path":"apps/server/src/ai-config/ai-config.helpers.ts","start_line":280,"end_line":284,"category":"bug","severity":"medium","content":"The DNS lookup phase is not covered by timeoutMs. dns.lookup runs in the libuv threadpool and can block for the OS resolver timeout (typically several seconds with retries), so pinnedGet can hang far beyond the configured timeout; the socket (and its timeout) is only created after resolution completes. Wrap the lookup in a race with a timer (or pass a lookup timeout) so the promise always settles within the caller-visible budget.","suggestion_code":null,"existing_code":" lookup(hostname, { all: true, family: 0 }, (dnsErr, addresses) => {\n if (dnsErr || !addresses || addresses.length === 0) {\n reject(new Error('DNS 解析失败'));\n return;\n }"}
{"path":"apps/server/src/ai-config/ai-config.helpers.ts","start_line":304,"end_line":304,"category":"bug","severity":"low","content":"The Host header omits the port. validateAndNormalizeBaseUrl does not restrict the port, so an admin may configure a base URL with a non-default port (e.g. https://api.openai.com:8443/v1); in that case HTTP/1.1 virtual hosting requires Host: hostname:port, otherwise the server may route the request incorrectly or reject it. Build the Host header conditionally on the effective port, e.g. Host: (port === (isHttps ? 443 : 80)) ? hostname : `${hostname}:${port}` (parsed.hostname already includes IPv6 brackets, so the concatenation is correct).","suggestion_code":null,"existing_code":" headers: { ...headers, Host: hostname },"}
{"path":"apps/server/src/ai-config/ai-config.helpers.ts","start_line":34,"end_line":35,"category":"security","severity":"low","content":"The development fallback encryption key is a hardcoded, publicly known constant (32 bytes of 0xFF). Any ciphertext produced in dev environments can be decrypted by anyone who knows this file, and the same known key is shared across all developers. If dev/test data (which may contain real API keys) is ever leaked or mixed into production backups, the keys are exposed. Prefer generating a random per-boot key in dev (randomBytes(32)) with a clear warning that previously persisted dev ciphertext becomes undecryptable, or fail closed in dev too.","suggestion_code":null,"existing_code":" // 32 hex pairs → 32 bytes\n return Buffer.from('ff'.repeat(32), 'hex');"}
{"path":"apps/server/src/ai-config/ai-config.helpers.ts","start_line":56,"end_line":58,"category":"maintainability","severity":"low","content":"This error message is misleading: a canonical base64 encoding of a 32-byte key always ends with two '=' padding chars, so an unpadded/under-padded key fails the raw !== canonical comparison and is reported as having 'extra padding', which is the opposite of the actual problem. Rephrase to indicate the key must be the canonical padded base64 form, e.g. 'base64 编码须为标准格式（含正确 padding）'.","suggestion_code":null,"existing_code":" throw new InternalServerErrorException(\n 'AI_CONFIG_ENCRYPTION_KEY 格式无效：base64 编码须为标准格式（无多余 padding）',\n );"}
{"path":"apps/server/src/ai-config/ai-config.helpers.ts","start_line":247,"end_line":258,"category":"maintainability","severity":"low","content":"Duplicate DNS/private-IP logic: validateDnsNotPrivate resolves the hostname and checks isPrivateHost, and pinnedGet re-implements the same resolution + private-IP filtering with a second lookup. Besides the duplication and divergent error messages, this leaves a TOCTOU window in which validation resolves the name to a public IP while the actual request resolves it again (the pin does re-check, but the two lookups may disagree on split-horizon DNS). Consider a single shared helper that resolves and returns the first non-private address, used by both validation and the pinned request, so the checks stay consistent.","suggestion_code":null,"existing_code":" let addresses: { address: string; family: number }[];\n try {\n addresses = await resolveHostnames(hostname);\n } catch {\n throw new BadRequestException('无法解析域名');\n }\n\n for (const { address } of addresses) {\n if (isPrivateHost(address)) {\n throw new BadRequestException('域名解析到内网地址');\n }\n }"}
{"path":"apps/server/src/ai-config/ai-config.helpers.ts","start_line":313,"end_line":317,"category":"bug","severity":"low","content":"A 3xx response without a Location header (e.g. certain 304 responses) is not treated as a redirect here and will be read and returned as a successful body, even though the documented intent is 'Redirects are forbidden'. Since a redirect is rejected regardless of target, reject on status alone (drop the res.headers.location condition) to keep the policy consistent.","suggestion_code":null,"existing_code":" if (status >= 300 && status < 400 && res.headers.location) {\n res.resume();\n res.destroy();\n return reject(new Error('禁止重定向'));\n }"}
{"path":"apps/server/src/attendance-devices/attendance-devices.service.ts","start_line":43,"end_line":44,"category":"bug","severity":"medium","content":"Validation gap: `normalizeSn`/`deviceName.trim()` run after DTO validation, so a whitespace-only `deviceSn`/`deviceName` (e.g. \" \") passes `@IsNotEmpty` and gets saved as an empty string (also possible in `update` via `patch.deviceSn`/`patch.deviceName`). An empty SN then collides with the unique index on later inserts, and an empty device name is persisted. Trim and re-validate (reject empty) before saving.","suggestion_code":" const deviceSn = this.normalizeSn(dto.deviceSn);\n if (!deviceSn) throw new BadRequestException('SN 不能为空');\n await this.assertClassroomExists(dto.classroomId);","existing_code":" const deviceSn = this.normalizeSn(dto.deviceSn);\n await this.assertClassroomExists(dto.classroomId);"}
{"path":"apps/server/src/attendance-devices/attendance-devices.service.ts","start_line":45,"end_line":46,"category":"bug","severity":"medium","content":"TOCTOU race on SN uniqueness: the existence check and the subsequent insert/update are not atomic. The entity has a unique index on `deviceSn`, so two concurrent requests with the same SN can both pass `findOne` and one will fail with an unhandled DB unique-constraint error (500) instead of the intended 400. Same applies to the SN check in `update`. Consider wrapping `repo.save`/`repo.update` and translating `QueryFailedError` (duplicate key) into `BadRequestException`, or rely on the unique index as the source of truth.","suggestion_code":null,"existing_code":" const exists = await this.repo.findOne({ where: { deviceSn } });\n if (exists) throw new BadRequestException(`SN ${deviceSn} 已绑定教室`);"}
{"path":"apps/server/src/attendance-devices/attendance-devices.service.ts","start_line":62,"end_line":63,"category":"style","severity":"low","content":"Loose inequality (`!= null`) is used for the null checks; per project rules strict equality (`===`/`!==`) is required. Use `dto.classroomId !== undefined && dto.classroomId !== null` (or an explicit `isNil` helper).","suggestion_code":" if (dto.classroomId !== undefined && dto.classroomId !== null) await this.assertClassroomExists(dto.classroomId);\n if (dto.deviceSn !== undefined && dto.deviceSn !== null) {","existing_code":" if (dto.classroomId != null) await this.assertClassroomExists(dto.classroomId);\n if (dto.deviceSn != null) {"}
{"path":"apps/server/src/attendance-devices/attendance-devices.service.ts","start_line":63,"end_line":68,"category":"maintainability","severity":"low","content":"Duplicate logic: the SN normalization + uniqueness check is implemented twice (create and update) with only the self-exclusion differing. Extract a shared helper such as `private async assertSnAvailable(sn: string, excludeId?: number)` and reuse it in both places to avoid divergence.","suggestion_code":null,"existing_code":" if (dto.deviceSn != null) {\n const deviceSn = this.normalizeSn(dto.deviceSn);\n const exists = await this.repo.findOne({ where: { deviceSn } });\n if (exists && exists.id !== id) throw new BadRequestException(`SN ${deviceSn} 已绑定教室`);\n patch.deviceSn = deviceSn;\n }"}
{"path":"apps/server/src/attendance/attendance-calendar.service.ts","start_line":33,"end_line":36,"category":"bug","severity":"high","content":"Off-by-one weekday bug: `new Date(`${date}T00:00:00+08:00`)` converts China-midnight to an instant whose UTC time is 8 hours earlier (the previous calendar day), and `.getUTCDay()` then returns the weekday of that previous day. E.g. `2026-08-10` (Monday in China) becomes `2026-08-09T16:00Z` (Sunday) and this method returns `7` instead of `1`. As a result `getScheduleOptionsForAttendance` always queries the wrong `cs.weekDay` and returns schedules for the incorrect weekday. Use dayjs (with the same +08 offset used elsewhere in this file) so `.day()` is evaluated in the China timezone.","suggestion_code":" private getWeekDayForDate(date: string): number {\n const day = dayjs(`${date}T00:00:00+08:00`).day();\n return day === 0 ? 7 : day;\n }","existing_code":" private getWeekDayForDate(date: string): number {\n const day = new Date(`${date}T00:00:00+08:00`).getUTCDay();\n return day === 0 ? 7 : day;\n }"}
{"path":"apps/server/src/attendance/attendance-calendar.service.ts","start_line":22,"end_line":22,"category":"maintainability","severity":"low","content":"China timezone offset (+8) is hardcoded in three places with two different mechanisms (`dayjs().utcOffset(8)` here/in `buildCalendar` and the `+08:00` literal in `getWeekDayForDate`). This is business-specific magic that is easy to get out of sync (and is exactly what caused the off-by-one in `getWeekDayForDate`). Extract a named constant (e.g. `CHINA_TZ_OFFSET = 8` / `CHINA_TZ_SUFFIX = '+08:00'`) and centralize weekday/date helpers.","suggestion_code":null,"existing_code":" const now = dayjs().utcOffset(8);"}
{"path":"apps/server/src/attendance/attendance-calendar.service.ts","start_line":76,"end_line":79,"category":"bug","severity":"low","content":"`weekStart` is validated with `@IsDateString()`, which also accepts ISO timestamps with a time/offset component (e.g. `2026-08-09T00:00:00.000Z`), not just `YYYY-MM-DD`. Passing such a value here produces a `Between(weekStart, endStr)` where the lower bound mixes a timestamp with a date-only upper bound and the `end` computed via `new Date(weekStart)` + `setDate` relies on server-local `getDate()`, so `endStr` can drift. Normalize `weekStart` to a date-only string (and construct `start` explicitly in the +08 zone) before computing the range to keep the query deterministic.","suggestion_code":" const weekStartDate = weekStart.slice(0, 10);\n const start = new Date(`${weekStartDate}T00:00:00+08:00`);\n const end = new Date(start);\n end.setDate(start.getDate() + 6);\n const endStr = dayjs(end).utcOffset(8).format('YYYY-MM-DD');","existing_code":" const start = new Date(weekStart);\n const end = new Date(start);\n end.setDate(start.getDate() + 6);\n const endStr = dayjs(end).utcOffset(8).format('YYYY-MM-DD');"}
{"path":"apps/server/src/attendance/attendance-leave-sync.service.ts","start_line":45,"end_line":47,"category":"performance","severity":"medium","content":"Nested sequential await loop: for every date × every user the code issues an API call and DB writes one after another, so a lesson spanning many days with many students results in N×M sequential network round-trips (plus resolveStudentName does 2 extra DB queries per new record). These per-user/per-date operations are independent and should run in parallel — e.g. collect per-date Promise.all batches with a concurrency limit — to avoid multi-minute syncs.","suggestion_code":null,"existing_code":" for (const userId of userIds) {\n try {\n const leaves = await this.dingTalkService.fetchDailyLeaveStatus(userId, date);"}
{"path":"apps/server/src/attendance/attendance-leave-sync.service.ts","start_line":48,"end_line":51,"category":"bug","severity":"medium","content":"The doc comment promises \"单条失败只记录错误、不中断整批\" (a single failed record only logs an error without interrupting the batch), but the try/catch wraps the whole user×date iteration: if one leave's upsert throws, all remaining leaves for that user/date are silently skipped and only one generic error is recorded. To honor the documented intent, wrap each `upsertLeave` call in its own try/catch so a single bad record doesn't cause other leave data to be lost from settlement.","suggestion_code":null,"existing_code":" for (const leave of leaves) {\n await this.upsertLeave(leave);\n synced++;\n }"}
{"path":"apps/server/src/attendance/attendance-leave-sync.service.ts","start_line":68,"end_line":70,"category":"bug","severity":"low","content":"`findOne` then `create`/`save` is a check-then-act pattern: `dingId` has a unique constraint, so if this service runs concurrently (e.g. two lesson syncs overlapping the same date range) both requests can pass the `findOne` miss and one insert will throw a duplicate-key error, failing the whole user×date batch. Prefer an atomic upsert (e.g. `insert` with `orUpdate`/`orIgnore` keyed on `dingId`, or catch the unique-violation and re-query).","suggestion_code":null,"existing_code":" const existing = await this.dingLeaveRawRepo.findOne({\n where: { dingId: result.procInstId },\n });"}
{"path":"apps/server/src/attendance/attendance-leave-sync.service.ts","start_line":72,"end_line":74,"category":"bug","severity":"low","content":"On the update path `userName` is never refreshed: if a record was synced before a StudentDingMapping existed (leaving userName as ''), subsequent re-syncs of the same approval never backfill the name even though the mapping now exists. Consider resolving/updating `userName` here as well (or backfilling in autoMatchLeaveRecords).","suggestion_code":null,"existing_code":" Object.assign(existing, {\n dingUserId: result.userId,\n workDate: result.workDate,"}
{"path":"apps/server/src/attendance/attendance-leave-sync.service.ts","start_line":100,"end_line":100,"category":"maintainability","severity":"low","content":"The literal status strings 'unmatched' / 'matched' are hardcoded in multiple places (create default, autoMatch filter/assignment). Extract them into a shared enum/const (e.g. MatchStatus) so typos or future status values can't silently diverge between the write path and the query path.","suggestion_code":null,"existing_code":" matchStatus: 'unmatched',"}
{"path":"apps/server/src/attendance/attendance-generation.service.ts","start_line":107,"end_line":110,"category":"performance","severity":"medium","content":"N+1 query / redundant computation inside the nested loop: `mapScheduleTimeToSession` calls `ensureAttendancePeriodConfigs()` which performs DB queries (count + find) on every call, and it is awaited once per schedule per day (e.g. 4 schedules × 7 days = 28+ DB round trips). Also `classStudents.filter(isClassStudentActiveOnDate)` is recomputed for every schedule even though it only depends on `dateStr`. Pre-resolve the session for each schedule once (e.g. `Map` built with `Promise.all`) before the date loop, and compute `classStudentsForDate` once per date outside the schedule loop.","suggestion_code":" const session = scheduleSessions.get(sched.id)!;","existing_code":" const session = await this.mapScheduleTimeToSession(sched.startTime);\n const classStudentsForDate = classStudents.filter((cs) =>\n isClassStudentActiveOnDate(cs, dateStr),\n );"}
{"path":"apps/server/src/attendance/attendance-generation.service.ts","start_line":214,"end_line":214,"category":"performance","severity":"medium","content":"Sequential awaited DB calls in a loop: `mapScheduleTimeToSession` hits the DB (via `ensureAttendancePeriodConfigs`) for every schedule, and each iteration awaits the previous one. Resolve the session for all schedules in parallel (single call to fetch the enabled periods, then match in memory), e.g. `await Promise.all(schedules.map(...))` or fetch periods once before the loop.","suggestion_code":null,"existing_code":" if ((await this.mapScheduleTimeToSession(schedule.startTime)) === session) {"}
{"path":"apps/server/src/attendance/attendance-generation.service.ts","start_line":100,"end_line":101,"category":"bug","severity":"medium","content":"Day-of-week/timezone inconsistency: `new Date(dateFrom)` with a date-only string is parsed as UTC midnight, and `d.getDay()` is evaluated in the server's local timezone, while `dateStr` is formatted with a fixed UTC+8 offset. On servers running in a timezone west of UTC (or any TZ where the UTC date differs from the +8 date), `weekDay` will not correspond to `dateStr`, so records can be generated for the wrong weekday. Derive both from the same UTC+8 `dayjs` instance.","suggestion_code":" const d8 = dayjs(d).utcOffset(8);\n const dateStr = d8.format('YYYY-MM-DD');\n const weekDay = d8.day() === 0 ? 7 : d8.day();","existing_code":" const dateStr = dayjs(d).utcOffset(8).format('YYYY-MM-DD');\n const weekDay = d.getDay() === 0 ? 7 : d.getDay();"}
{"path":"apps/server/src/attendance/attendance-generation.service.ts","start_line":254,"end_line":257,"category":"maintainability","severity":"medium","content":"`clear()` followed by `save()` is not transactional (also in `resetAttendancePeriodConfigs`). If `save` fails or a concurrent request reads/configures periods in between, the existing period configs are lost and the table is left empty or inconsistent. Wrap both operations in `this.dataSource.transaction(...)` using the transaction's repository.","suggestion_code":" await this.dataSource.transaction(async (manager) => {\n const repo = manager.getRepository(AttendancePeriodConfig);\n await repo.clear();\n await repo.save(normalized.map((period) => repo.create(period)));\n });","existing_code":" await this.attendancePeriodConfigRepo.clear();\n await this.attendancePeriodConfigRepo.save(\n normalized.map((period) => this.attendancePeriodConfigRepo.create(period)),\n );"}
{"path":"apps/server/src/attendance/attendance-generation.service.ts","start_line":266,"end_line":267,"category":"maintainability","severity":"low","content":"Dead code: `mapLessonScheduleTimeToSession` is a private method that is never called anywhere in this file, and it references a `night_check` period key that does not exist in `defaultAttendancePeriods` or in `saveAttendancePeriodConfigs` handling. Remove it to avoid confusion with the actually-used `mapScheduleTimeToSession`.","suggestion_code":null,"existing_code":" private mapLessonScheduleTimeToSession(startTime: string): string {\n const hour = parseInt(startTime.slice(0, 2), 10);"}
{"path":"apps/server/src/attendance/attendance-generation.service.ts","start_line":155,"end_line":158,"category":"maintainability","severity":"low","content":"Duplicate logic / shadowed import: the private `toMinutes` method duplicates the `toMinutes` imported from './attendance-time'. Because class methods shadow module-level imports, every unqualified `toMinutes(...)` call in this file resolves to the private copy, leaving the imported one unused (dead import). Keep only one implementation to avoid two definitions drifting apart.","suggestion_code":null,"existing_code":" private toMinutes(time: string): number {\n const [hour, minute] = time.split(':').map(Number);\n return hour * 60 + minute;\n }"}
{"path":"apps/server/src/attendance/attendance-generation.service.ts","start_line":22,"end_line":22,"category":"other","severity":"low","content":"Likely copy-paste typo in the default config: the `afternoon` (14:00–17:00) period is labeled '晚课' (evening class), which overlaps semantically with `evening_study` labeled '晚自习'. It is probably meant to be '午课'/'下午课'.","suggestion_code":null,"existing_code":" { periodKey: 'afternoon', label: '晚课', startTime: '14:00', endTime: '17:00', sortOrder: 3 },"}
{"path":"apps/server/src/attendance/attendance-generation.service.ts","start_line":229,"end_line":231,"category":"bug","severity":"low","content":"Missing time-format validation: if `startTime`/`endTime` are not `HH:mm`, `toMinutes` returns NaN and all comparisons (`NaN <= NaN`, `NaN < NaN`) evaluate to false, so invalid times silently pass validation and get persisted. Validate the `HH:mm` format before comparing.","suggestion_code":" if (!/^\\d{2}:\\d{2}$/.test(period.startTime) || !/^\\d{2}:\\d{2}$/.test(period.endTime)) {\n throw new BadRequestException(`${label} 的时间格式必须为 HH:mm`);\n }\n if (toMinutes(period.endTime) <= toMinutes(period.startTime)) {\n throw new BadRequestException(`${label} 的结束时间必须晚于开始时间`);\n }","existing_code":" if (toMinutes(period.endTime) <= toMinutes(period.startTime)) {\n throw new BadRequestException(`${label} 的结束时间必须晚于开始时间`);\n }"}
{"path":"apps/server/src/attendance/attendance-import.service.ts","start_line":87,"end_line":92,"category":"bug","severity":"high","content":"The safety timeout can corrupt the single-import guarantee. If the timer fires while the original import is still genuinely running (which is the only case where it can fire, since `finally` always clears it on the normal path), it sets `isRunning = false` but does nothing to stop the hung import. A second import can then start concurrently, and both share the same `progressSubject` / `importingUserId`, so: (1) the old import's later `emit` calls get tagged with the new user's ID, breaking SSE scoping; (2) when the old import finally exits, its `finally` block resets `isRunning = false` and `importingUserId = undefined` while the new import is still running, allowing a third import to start. Consider using a per-run token/generation counter so only the matching run resets the flags, and refuse starting a new import until the previous run has truly finished.","suggestion_code":null,"existing_code":" const safetyTimer = setTimeout(() => {\n if (this.isRunning) {\n this.logger.error('Import safety timeout triggered — force-resetting isRunning');\n this.isRunning = false;\n }\n }, SAFETY_TIMEOUT_MS);"}
{"path":"apps/server/src/attendance/attendance-import.service.ts","start_line":144,"end_line":144,"category":"bug","severity":"medium","content":"Batch save failures are collected into `errors` and the loop continues, but the method still returns `success: true`. If every batch fails (e.g., unique-constraint violation or a transient DB error), callers that rely on the `success` flag will treat a fully failed import as successful. Return `success: false` (or a partial-success indicator) when `errors.length > 0`, and reflect the errors in the 'complete' progress event as well.","suggestion_code":null,"existing_code":" return { success: true, imported, skipped, matched, errors, duration };"}
{"path":"apps/server/src/attendance/attendance-import.service.ts","start_line":295,"end_line":295,"category":"performance","severity":"medium","content":"For every record that lacks `userName`, `resolveStudentName` runs two sequential DB queries (mapping lookup + student lookup). With thousands of imported records this is an N+1 pattern (up to 2×N queries, executed in `Promise.all` batches of 100). Batch-load the `StudentDingMapping`/`Student` rows for the whole page with `In(...)` and resolve names in memory instead.","suggestion_code":null,"existing_code":" entity.userName = r.userName || await this.resolveStudentName(r.userId);"}
{"path":"apps/server/src/attendance/attendance-import.service.ts","start_line":254,"end_line":256,"category":"bug","severity":"medium","content":"`In(dingIds)` builds a single `WHERE dingId IN (...)` with one bind variable per record. For large imports the clause can exceed the database's max bind-variable/expression limit (e.g., ~999 for SQLite, 65535 for MySQL/PostgreSQL), causing the whole import to fail with a generic error. Chunk the id list (e.g., 500–1000 ids per query) and merge the results.","suggestion_code":null,"existing_code":" const existing = await this.dingRawRepo.find({\n where: { dingId: In(dingIds) },\n });"}
{"path":"apps/server/src/attendance/attendance-import.service.ts","start_line":107,"end_line":107,"category":"bug","severity":"low","content":"Deduplication only compares against existing DB records, not against other records in the same fetched result. If the same `checkId` appears twice in `rawResults` (or is returned by overlapping API responses), both entries are treated as new; the second insert then violates the unique constraint and is reported as a batch error while the import still claims `success: true`. Deduplicate `rawResults` in memory by `checkId` before the DB lookup/filter.","suggestion_code":null,"existing_code":" const newRecords = rawResults.filter((r) => !existingByDingId.has(r.checkId));"}
{"path":"apps/server/src/attendance/attendance-import.service.ts","start_line":30,"end_line":30,"category":"maintainability","severity":"low","content":"`progressSubject` is never completed or replaced, and there is no subscription cleanup after an import finishes. Long-lived SSE subscriptions that don't unsubscribe will accumulate over repeated imports. Consider completing the Subject (or replacing it per import run) once the pipeline finishes/errors.","suggestion_code":null,"existing_code":" private progressSubject = new Subject();"}
{"path":"apps/server/src/attendance/attendance-device.ts","start_line":34,"end_line":35,"category":"style","severity":"low","content":"Uses non-strict equality `!=` (twice here), which violates the project's strict-equality rule. Note that `record.classId` is typed `number` (non-nullable) in the entity, so this filter is only a runtime-null guard; if the null/undefined check is intended, express it strictly as `!== null && !== undefined` (or use a nullable field type) instead of `!=`.","suggestion_code":" ...records.map((record) => record.classId).filter((id): id is number => id !== null && id !== undefined),\n ...(classroomId !== null && classroomId !== undefined ? [classroomId] : []),","existing_code":" ...records.map((record) => record.classId).filter((id): id is number => id != null),\n ...(classroomId != null ? [classroomId] : []),"}
{"path":"apps/server/src/attendance/attendance-device.ts","start_line":41,"end_line":41,"category":"maintainability","severity":"low","content":"Hardcoded business status literal `'active'`. The entity already exports the `AttendanceDeviceStatus` enum (`ACTIVE = 'active'`), so use the enum constant to avoid string-literal drift and keep status values centralized.","suggestion_code":" where: { classroomId: In(classroomIds), status: AttendanceDeviceStatus.ACTIVE },","existing_code":" where: { classroomId: In(classroomIds), status: 'active' },"}
{"path":"apps/server/src/attendance/attendance-device.ts","start_line":25,"end_line":26,"category":"performance","severity":"low","content":"These two repository queries are independent (SN lookup vs. classroom lookup) but are awaited sequentially, adding two round-trip latencies. They can be executed concurrently with `Promise.all`, which is preferable for independent async operations.","suggestion_code":null,"existing_code":" const devices = await attendanceDeviceRepo.find({\n where: { deviceSn: In(sns) },"}
{"path":"apps/server/src/attendance/attendance-import.controller.ts","start_line":35,"end_line":40,"category":"security","severity":"high","content":"Missing class-scope authorization for match/auto-match. Unlike `getDingRaw` (assertClassAccess) and `importFromDingTalk` (getTeacherClassDingUserIds), neither `matchDingRecord` nor `autoMatch` verifies that the raw record/student belongs to the requester's accessible classes. The underlying `AttendanceRecordMutationService.matchDingRecord` simply loads the record by id and saves the match, and `autoMatchDingRecords` iterates ALL unmatched records globally. A user holding only `attendance:edit` (e.g., a teacher) can match records belonging to other classes by guessing IDs and trigger a global auto-match. Suggest resolving the raw record's class and calling `assertClassAccess` before matching, and scoping `autoMatch` to the user's accessible classes (or requiring `canManageAllAttendance`).","suggestion_code":null,"existing_code":" async matchDingRecord(\n @Param('id', ParseIntPipe) id: number,\n @Body() dto: MatchDingRecordDto,\n @Request() req: { user: RequestUser },\n ) {\n const result = await this.service.matchDingRecord(id, dto);"}
{"path":"apps/server/src/attendance/attendance-import.controller.ts","start_line":135,"end_line":138,"category":"bug","severity":"medium","content":"SSE stream can hang indefinitely. `importService.progress$` is backed by a plain RxJS `Subject` (see attendance-import.service.ts), so any event emitted before the subscriber connects is lost. If the client connects when no import is running — or after the import already finished — the observable never emits and never reaches the `complete`/`error` phase, so `subscriber.complete()` is never called and the connection stays open until the client disconnects. There is also no heartbeat/keep-alive event, which can cause idle connection drops behind proxies. Consider exposing a replay of the last event (e.g., BehaviorSubject/ReplaySubject(1)), emitting an immediate \"no active import\" snapshot, and adding a keep-alive heartbeat plus a timeout that terminates stale connections.","suggestion_code":null,"existing_code":" return new Observable((subscriber) => {\n const subscription = this.importService.progress$\n .pipe(filter((event) => event.userId === userId))\n .subscribe({"}
{"path":"apps/server/src/attendance/attendance-import.controller.ts","start_line":102,"end_line":108,"category":"bug","severity":"low","content":"Inconsistent error handling in the import endpoint. When another import is already running, `AttendanceImportService.importFromDingTalk` throws a plain `Error('An import is already in progress')` which surfaces to the client as an HTTP 500; and when the pipeline itself fails, the service returns `{ success: false, errors }` but this controller still replies HTTP 200 and writes a normal audit entry that omits the error details. Consider catching the concurrency exception and mapping it to a 409 Conflict, and when `result.success === false` include `result.errors` in the audit log detail / response so failures are observable.","suggestion_code":null,"existing_code":" const result = await this.importService.importFromDingTalk({\n startDate,\n endDate,\n userIds,\n autoMatch: true,\n userId: req.user.id,\n });"}
{"path":"apps/server/src/attendance/attendance-lesson-status.ts","start_line":124,"end_line":126,"category":"performance","severity":"medium","content":"Performance: this query loads the student's ENTIRE leave history (every leave row ever synced) and then filters/sorts in memory. It runs once per student during finalize (from buildLessonRecord inside Promise.all over classStudents, inside a transaction), so a class of N students triggers N full-history queries while the transaction is held open. Push the time-window filter down to SQL — e.g. filter on workDate between window.dateFrom/window.dateTo (uses the existing workDate index) or startTime <= window.end && endTime >= window.start — and select only the needed columns instead of materializing all rows.","suggestion_code":" const leaves = await dingLeaveRawRepo.find({\n where: {\n matchedStudentId: studentId,\n startTime: LessThanOrEqual(new Date(window.end)),\n endTime: MoreThanOrEqual(new Date(window.start)),\n },\n });","existing_code":" const leaves = await dingLeaveRawRepo.find({\n where: { matchedStudentId: studentId },\n });"}
{"path":"apps/server/src/attendance/attendance-lesson-status.ts","start_line":128,"end_line":134,"category":"bug","severity":"low","content":"The function is named findApprovedLeaveForStudent and its doc comment promises only approved leave ('钉钉已审批通过的请假'), but the filter never checks that approvedAt is non-null; it only sorts by it. The DingTalk sync currently stores only finished approvals, but the entity column is nullable and this contract is not enforced at read time — any pending/rejected record present in the table would be treated as a valid leave and incorrectly change the student's status from absent to leave. Add a defensive approvedAt check.","suggestion_code":" const overlapping = leaves.filter(\n (leave) =>\n leave.approvedAt &&\n leave.startTime &&\n leave.endTime &&\n leave.startTime.getTime() <= window.end &&\n leave.endTime.getTime() >= window.start,\n );","existing_code":" const overlapping = leaves.filter(\n (leave) =>\n leave.startTime &&\n leave.endTime &&\n leave.startTime.getTime() <= window.end &&\n leave.endTime.getTime() >= window.start,\n );"}
{"path":"apps/server/src/attendance/attendance-dingtalk.ts","start_line":89,"end_line":93,"category":"maintainability","severity":"medium","content":"Nested ternary buried inside a `||` expression violates the project rule that nested ternary expressions are not allowed, and the fallback chain (metadataRecord?.punchSource -> attendanceType for non-standard types -> primary.punchSource) is hard to follow. Extract this into a small helper with if/else statements and add a comment explaining the fallback intent.","suggestion_code":null,"existing_code":" const source =\n metadataRecord?.punchSource ||\n (metadataRecord && !['OnDuty', 'OffDuty'].includes(metadataRecord.attendanceType)\n ? metadataRecord.attendanceType\n : primary.record.punchSource);"}
{"path":"apps/server/src/attendance/attendance-dingtalk.ts","start_line":81,"end_line":82,"category":"maintainability","severity":"low","content":"Business values such as DingTalk's attendance types 'OnDuty'/'OffDuty' (and the default advance of 30 minutes in getLessonAttendanceWindow) are hardcoded and duplicated in getLessonPunchMetadata. Extract them into named constants so the semantics and any API-driven changes are centralized.","suggestion_code":null,"existing_code":" !!(record.punchSource || record.punchDeviceName || record.punchDeviceId) ||\n !['OnDuty', 'OffDuty'].includes(record.attendanceType),"}
{"path":"apps/server/src/attendance/attendance-dingtalk.ts","start_line":16,"end_line":16,"category":"maintainability","severity":"low","content":"The fixed timezone '+08:00' is hardcoded in multiple date constructions (here and in getLessonPunchMetadata), and the same `new Date(`${lessonDate}T${time}:00+08:00`)` pattern is duplicated across functions. If the business timezone ever changes or the server runs outside Asia/Shanghai, these silently diverge from `shiftDate`/`dayjs.utc` usage. Centralize into a single timezone constant/helper to keep them consistent.","suggestion_code":null,"existing_code":" const lessonStart = new Date(`${lessonDate}T${schedule.startTime}:00+08:00`).getTime();"}
{"path":"apps/server/src/attendance/attendance-record-mutation.service.ts","start_line":66,"end_line":69,"category":"performance","severity":"medium","content":"Performance: this loop issues one `save()` per unmatched record sequentially (N+1). These updates are independent, so they should be batched — either collect all matches and run them with `Promise.all`, or use a single bulk `UPDATE ... WHERE id IN (...)` via `createQueryBuilder().update()`. Sequential awaits will be slow when the unmatched set is large.","suggestion_code":" await Promise.all(\n unmatched.map((record) => {\n const studentId = dingToStudentId.get(record.dingUserId);\n if (studentId == null) return Promise.resolve();\n return this.dingRawRepo.update(record.id, {\n matchedStudentId: studentId,\n matchStatus: 'matched',\n });\n }),\n );","existing_code":" record.matchedStudentId = studentId;\n record.matchStatus = 'matched';\n await this.dingRawRepo.save(record);\n matched++;"}
{"path":"apps/server/src/attendance/attendance-record-mutation.service.ts","start_line":61,"end_line":64,"category":"bug","severity":"medium","content":"Atomicity: `autoMatchDingRecords` mutates records one by one without a transaction. If any `save` fails mid-loop, the exception propagates and leaves a partial state (some records 'matched', the rest still 'unmatched') with no rollback. Wrap the whole matching loop in `this.dataSource.transaction(...)` so the operation is all-or-nothing.","suggestion_code":null,"existing_code":" let matched = 0;\n for (const record of unmatched) {\n const studentId = dingToStudentId.get(record.dingUserId);\n if (studentId == null) continue;"}
{"path":"apps/server/src/attendance/attendance-record-mutation.service.ts","start_line":96,"end_line":108,"category":"maintainability","severity":"low","content":"Maintainability: the mutex + transaction + session/completed re-check + fresh-record re-fetch logic in `update()` and `remove()` is duplicated almost verbatim. Extract a private helper (e.g. `withSessionLock(id, fn)`) that performs the mutex acquisition, transaction, session validation and fresh-record lookup, and have both `update()` and `remove()` delegate to it so the two paths cannot drift apart.","suggestion_code":null,"existing_code":" return this.sessionMutex.runExclusive(record.attendanceSessionId, () =>\n this.dataSource.transaction(async (manager) => {\n const recordRepo = manager.getRepository(AttendanceRecord);\n const sessionRepo = manager.getRepository(AttendanceSession);\n\n // Re-check session status inside the transaction while holding the lock\n const session = await sessionRepo.findOne({ where: { id: record.attendanceSessionId! } });\n if (!session || session.status === 'completed') {\n throw new BadRequestException('已完成考勤的记录不允许修改或删除');\n }\n\n const freshRecord = await recordRepo.findOne({ where: { id } });\n if (!freshRecord) throw new NotFoundException(`AttendanceRecord ${id} not found`);"}
{"path":"apps/server/src/attendance/attendance-record-mutation.service.ts","start_line":42,"end_line":44,"category":"bug","severity":"medium","content":"Data integrity: `matchDingRecord` accepts any `studentId` without verifying the student exists. An invalid id will fail at the DB with a FK constraint error (surfacing as a 500) rather than a clean 4xx, and a valid-but-different id silently overwrites an already-matched record. Validate the student's existence (throw NotFoundException/BadRequestException) before assigning, and consider rejecting overwrites of records already in 'matched' state unless explicitly intended.","suggestion_code":null,"existing_code":" record.matchedStudentId = dto.studentId;\n record.matchStatus = 'matched';\n return this.dingRawRepo.save(record);"}
{"path":"apps/server/src/attendance/attendance-mutex.ts","start_line":12,"end_line":13,"category":"bug","severity":"medium","content":"The queue has no timeout or abort mechanism. If the wrapped `fn` (e.g. the DB transaction in attendance-record-mutation.service.ts) never settles — DB stall, deadlock in the connection pool — every subsequent `runExclusive` call for that sessionId will wait forever on `await tail`, and each call appends a new tail promise to `queueTails` that is never removed (the `finally` cleanup only runs when the last queued op completes). Over time this permanently blocks the session and grows the map without bound. Consider adding a per-call timeout (settle with an error after a configurable duration) and/or an `abort(sessionId)`/queue-clear API so a hung operation can be evicted instead of wedging the session forever.","suggestion_code":null,"existing_code":" this.queueTails.set(sessionId, newTail);\n await tail;"}
{"path":"apps/server/src/attendance/attendance-mutex.ts","start_line":8,"end_line":8,"category":"maintainability","severity":"low","content":"This mutex is non-reentrant: if `fn` itself calls `runExclusive` with the same `sessionId` (directly or transitively through a nested service call), the inner call awaits the outer call's `newTail`, which only resolves after the outer `fn` completes — a guaranteed deadlock with no detection. The current call sites don't nest, but this is a latent hazard worth guarding against (e.g. detect same-session re-entry and throw) or at least documenting on the class.","suggestion_code":null,"existing_code":" async runExclusive(sessionId: number, fn: () => Promise): Promise {"}
{"path":"apps/server/src/attendance/attendance-query.service.ts","start_line":80,"end_line":80,"category":"security","severity":"medium","content":"Accessibility filter is only applied when `query.classId` is NOT provided. If a caller passes both `classId` and `accessibleClassIds` where the classId is outside the user's accessible set, the classId filter wins and the accessibility check is silently skipped — a potential authorization bypass. Either have the controller validate classId against accessibleClassIds, or intersect here, e.g.: if `accessibleClassIds && !accessibleClassIds.includes(query.classId)` return zeroed summary.","suggestion_code":" if (accessibleClassIds && query.classId && !accessibleClassIds.includes(query.classId)) {\n return { total: 0, present: 0, late: 0, absent: 0, leave: 0, pending: 0, presentRate: 0 };\n }\n if (!query.classId && accessibleClassIds) {","existing_code":" if (!query.classId && accessibleClassIds) {"}
{"path":"apps/server/src/attendance/attendance-query.service.ts","start_line":145,"end_line":145,"category":"security","severity":"medium","content":"Same authorization concern as in `getSummary`: when `query.classId` is supplied, `accessibleClassIds` is ignored, so a caller can query attendance records of any class by passing an arbitrary classId. Ensure the controller verifies `classId` membership in `accessibleClassIds`, or enforce it here.","suggestion_code":" if (query.classId) {\n if (accessibleClassIds && !accessibleClassIds.includes(query.classId)) {\n return { list: [], total: 0, page, pageSize };\n }\n qb.andWhere('ar.classId = :classId', { classId: query.classId });\n } else if (accessibleClassIds) {","existing_code":" } else if (accessibleClassIds) {"}
{"path":"apps/server/src/attendance/attendance-query.service.ts","start_line":250,"end_line":250,"category":"security","severity":"medium","content":"When `query.classId` is provided, `accessibleClassIds` is completely ignored, so a user could query DingTalk raw records for a class they have no access to by simply passing the classId. Apply an intersection check so classId is only honored when it falls within the user's accessible set.","suggestion_code":" const scopedClassIds = query.classId\n ? (accessibleClassIds && !accessibleClassIds.includes(query.classId) ? [] : [query.classId])\n : accessibleClassIds;","existing_code":" const scopedClassIds = query.classId ? [query.classId] : accessibleClassIds;"}
{"path":"apps/server/src/attendance/attendance-query.service.ts","start_line":95,"end_line":95,"category":"performance","severity":"medium","content":"`getMany()` materializes every matching row and the aggregate counts are computed in JS. For large date ranges / many classes this loads all records into memory. Prefer SQL-side aggregation, e.g. COUNT + SUM(CASE WHEN status='present' THEN 1 ELSE 0 END) via `getRawOne()`/`getCount()`, so only one aggregate row is returned.","suggestion_code":null,"existing_code":" const rows = await qb.getMany();"}
{"path":"apps/server/src/attendance/attendance-query.service.ts","start_line":179,"end_line":181,"category":"maintainability","severity":"low","content":"When `accessibleClassIds` is provided, the returned classes are derived purely from the accessible id list, regardless of whether any attendance records exist — this contradicts the method's stated purpose (\"Get distinct classes with attendance records\"). If only classes that actually have attendance data should be listed, intersect accessibleClassIds with the distinct classIds present in the attendance table.","suggestion_code":null,"existing_code":" const rows: Array<{ classId: string | number }> = accessibleClassIds\n ? accessibleClassIds.map((classId) => ({ classId }))\n : await qb.orderBy('ar.classId', 'ASC').getRawMany();"}
{"path":"apps/server/src/attendance/attendance-query.service.ts","start_line":134,"end_line":135,"category":"maintainability","severity":"low","content":"Pagination and date/status filter-building logic is duplicated between `findAll` and `getDingRaw` (identical page/pageSize clamping and dateFrom/dateTo conditions). Consider extracting a shared helper to keep filter semantics consistent and avoid drift.","suggestion_code":null,"existing_code":" const page = Math.max(1, Math.floor(Number(query.page) || 1));\n const pageSize = Math.min(200, Math.max(1, Math.floor(Number(query.pageSize) || 20)));"}
{"path":"apps/server/src/attendance/attendance-time.ts","start_line":3,"end_line":6,"category":"bug","severity":"medium","content":"`toMinutes` does not validate its input: if `time` is not exactly `HH:MM` (e.g. missing colon, non-numeric segment, or just \"8\"), `hour * 60 + minute` evaluates to `NaN` and silently propagates to callers (e.g. overnight/overlap comparisons in attendance-dingtalk and attendance-generation), potentially breaking attendance logic without any error signal. Suggest validating and throwing a descriptive error for malformed input.","suggestion_code":"export function toMinutes(time: string): number {\n const parts = time.split(':').map(Number);\n if (parts.length !== 2 || parts.some(Number.isNaN)) {\n throw new Error(`Invalid time format: ${time}`);\n }\n const [hour, minute] = parts;\n return hour * 60 + minute;\n}","existing_code":"export function toMinutes(time: string): number {\n const [hour, minute] = time.split(':').map(Number);\n return hour * 60 + minute;\n}"}
{"path":"apps/server/src/attendance/attendance-time.ts","start_line":25,"end_line":27,"category":"bug","severity":"medium","content":"When `startTime` is empty or malformed, `parseInt('', 10)` returns `NaN`, all range checks are false, and the function silently returns `'night_check'` — an incorrect session classification that masks data errors. Validate the input (throw on `Number.isNaN(hour)`) instead of falling through to a misleading default, or make the default an explicit 'unknown' session.","suggestion_code":" if (Number.isNaN(hour)) {\n throw new Error(`Invalid startTime: ${startTime}`);\n }\n if (hour < 20) return 'evening_study';\n return 'night_check';\n}","existing_code":" if (hour < 20) return 'evening_study';\n return 'night_check';\n}"}
{"path":"apps/server/src/attendance/attendance-time.ts","start_line":8,"end_line":9,"category":"maintainability","severity":"low","content":"Timezone handling is inconsistent within this module: `getCourseClock` derives date/minutes from the process's local timezone (`dayjs(date)`), while `shiftDate` forces UTC. These only agree because the deployment assumes Asia/Shanghai (per the comment in common/dayjs.ts); if the server ever runs with a different `TZ`, `getCourseClock` will return a different calendar date than `shiftDate`/`lessonDate`, causing off-by-one-day attendance errors. Consider making both UTC-based or passing an explicit timezone to keep date-only arithmetic consistent.","suggestion_code":"export function getCourseClock(date: Date): { date: string; minutes: number } {\n const d = dayjs.utc(date);","existing_code":"export function getCourseClock(date: Date): { date: string; minutes: number } {\n const d = dayjs(date);"}
{"path":"apps/server/src/attendance/attendance-time.ts","start_line":20,"end_line":22,"category":"maintainability","severity":"low","content":"The session names (`'morning_reading'`, `'morning'`, `'afternoon'`, `'evening_study'`, `'night_check'`) are business keys hardcoded in a stringly-typed way. They are used for lookups elsewhere and would benefit from being shared constants (or a union type) to avoid typos and to keep the hour boundaries documented.","suggestion_code":null,"existing_code":"export function mapLessonScheduleTimeToSession(startTime: string): string {\n const hour = parseInt(startTime.slice(0, 2), 10);\n if (hour < 8) return 'morning_reading';"}
{"path":"apps/server/src/attendance/attendance-report.service.ts","start_line":179,"end_line":181,"category":"bug","severity":"high","content":"The \"consecutive\" absence/late detection does not actually check that dates are consecutive calendar days. The query only returns records with status IN ('absent','late'), so any intervening present/leave/pending record is invisible — a student absent Mon, present Tue, absent Wed will be counted as count=2 \"consecutive\" absences. Additionally, multiple sessions on the same day (morning/afternoon) are counted as separate days, and the lastDate update (`r.attendanceDate > current.lastDate`) never fires because the list is already sorted by date DESC. To correctly detect consecutive absences, group records per student per day (dedupe by date) and verify date difference === 1 day between consecutive entries.","suggestion_code":null,"existing_code":" if (current && current.studentId === r.studentId && current.type === status) {\n current.count++;\n if (r.attendanceDate > current.lastDate) current.lastDate = r.attendanceDate;"}
{"path":"apps/server/src/attendance/attendance-report.service.ts","start_line":122,"end_line":125,"category":"bug","severity":"medium","content":"Statuses other than the four handled here (e.g., 'pending', which is a valid status elsewhere in this module — see attendance-query.service.ts getSummary which counts it) are silently dropped: they contribute to neither `total` nor the rates, so the report statistics are skewed whenever pending/unhandled records exist. Add a `pending` field (or otherwise include unknown statuses) in the aggregation and in `total`.","suggestion_code":null,"existing_code":" if (row.status === 'present') entry.present += count;\n else if (row.status === 'absent') entry.absent += count;\n else if (row.status === 'late') entry.late += count;\n else if (row.status === 'leave') entry.leave += count;"}
{"path":"apps/server/src/attendance/attendance-report.service.ts","start_line":143,"end_line":145,"category":"bug","severity":"low","content":"Timezone handling mixes server-local time arithmetic with a fixed UTC+8 formatting offset: `new Date()`/`setDate` operate in the server's local timezone while `dayjs(cutoff).utcOffset(8)` displays the result in UTC+8. If the server's local timezone is not UTC+8 (and its calendar date differs from Beijing's at the moment of execution), the cutoff date can be off by one day. Since the project standardizes on UTC+8 (see common/dayjs.ts), compute the cutoff directly from a UTC+8 now, e.g. `dayjs().utcOffset(8).subtract(days, 'day').format('YYYY-MM-DD')`.","suggestion_code":null,"existing_code":" const cutoff = new Date();\n cutoff.setDate(cutoff.getDate() - days);\n const cutoffStr = dayjs(cutoff).utcOffset(8).format('YYYY-MM-DD');"}
{"path":"apps/server/src/attendance/attendance-report.service.ts","start_line":37,"end_line":42,"category":"maintainability","severity":"low","content":"The classId/accessibleClassIds access-control filter and the dateFrom/dateTo filter blocks are duplicated (with minor variations) across findAllForExport, getReport, and getAlerts. Consider extracting a private helper that builds a base QueryBuilder with these filters applied, to avoid divergence between the three methods.","suggestion_code":null,"existing_code":" if (query.classId) {\n qb.andWhere('ar.classId = :classId', { classId: query.classId });\n } else if (accessibleClassIds) {\n if (accessibleClassIds.length === 0) return [];\n qb.andWhere('ar.classId IN (:...accessibleClassIds)', { accessibleClassIds });\n }"}
{"path":"apps/server/src/attendance/attendance-records.controller.ts","start_line":124,"end_line":126,"category":"maintainability","severity":"low","content":"Uses loose equality `== null` / `!= null`. Per project rules, strict equality is required. Since `record.classId` is an optional `number`, check explicitly for null/undefined (e.g. `record.classId == null` should be `record.classId === null || record.classId === undefined`, or use `record.classId != null` → strict equivalent). The same pattern also appears later in `update`/`remove` (`existing.classId == null`).","suggestion_code":" if (!canManageAll && dto.records.some((record) => record.classId === null || record.classId === undefined)) {\n throw new ForbiddenException('教师录入考勤时必须关联自己任教的班级');\n }","existing_code":" if (!canManageAll && dto.records.some((record) => record.classId == null)) {\n throw new ForbiddenException('教师录入考勤时必须关联自己任教的班级');\n }"}
{"path":"apps/server/src/attendance/attendance-records.controller.ts","start_line":86,"end_line":89,"category":"bug","severity":"medium","content":"When `importFromDingTalk` returns `success: false` with an empty `errors` array, this branch pushes nothing and `continue`s, so the failure is silently swallowed: the audit log reports status `success` and the response `errors` is empty even though nothing was refreshed. Make the failure branch always surface an error message.","suggestion_code":" if (!importResult.success) {\n errors.push(\n importResult.errors.length > 0\n ? importResult.errors.join('；')\n : `排课 ${schedule.id} 刷新失败（无详细错误）`,\n );\n continue;\n }\n if (importResult.errors.length > 0) {\n errors.push(...importResult.errors);\n continue;\n }","existing_code":" if (!importResult.success || importResult.errors.length > 0) {\n errors.push(...importResult.errors);\n continue;\n }"}
{"path":"apps/server/src/attendance/attendance-records.controller.ts","start_line":214,"end_line":217,"category":"bug","severity":"low","content":"`encodeURIComponent()` output is placed in the plain `filename` parameter, which is NOT percent-decoded by most browsers — exported files will be saved with a garbled/percent-encoded name (e.g. `%E8%80%83%E5%8B%A4...xlsx`). Use an ASCII fallback filename plus the RFC 5987 `filename*=UTF-8''...` parameter for the Chinese name.","suggestion_code":" res.setHeader(\n 'Content-Disposition',\n `attachment; filename=attendance-report.xlsx; filename*=UTF-8''${encodeURIComponent(`考勤统计报表-${dateRange}`)}.xlsx`,\n );","existing_code":" res.setHeader(\n 'Content-Disposition',\n `attachment; filename=${encodeURIComponent(`考勤统计报表-${dateRange}`)}.xlsx`,\n );"}
{"path":"apps/server/src/attendance/attendance-records.controller.ts","start_line":251,"end_line":272,"category":"performance","severity":"low","content":"Each id in `dto.ids` (up to 200) triggers 2–3 sequential DB awaits, so this endpoint performs up to ~600 sequential round trips (N+1). The per-item work is independent and each item already isolates its own errors, so it can be parallelized with `Promise.all` while keeping the same per-item counting semantics.","suggestion_code":" await Promise.all(\n dto.ids.map(async (id) => {\n try {\n const existing = await this.service.findAttendanceRecord(id);\n if (existing.classId == null && !this.canManageAllAttendance(req)) {\n throw new ForbiddenException('无权修改未关联班级的考勤记录');\n }\n if (existing.classId != null) await this.assertClassAccess(req, existing.classId);\n await this.service.update(id, { status: dto.status, remark: dto.remark });\n updated += 1;\n } catch (error) {\n failedIds.push(id);\n if (\n error instanceof BadRequestException ||\n error instanceof NotFoundException ||\n error instanceof ForbiddenException\n ) {\n return;\n }\n systemFailed += 1;\n }\n }),\n );","existing_code":" for (const id of dto.ids) {\n try {\n const existing = await this.service.findAttendanceRecord(id);\n if (existing.classId == null && !this.canManageAllAttendance(req)) {\n throw new ForbiddenException('无权修改未关联班级的考勤记录');\n }\n if (existing.classId != null) await this.assertClassAccess(req, existing.classId);\n await this.service.update(id, { status: dto.status, remark: dto.remark });\n updated += 1;\n } catch (error) {\n failedIds.push(id);\n // 业务失败（已结算/无权限等）与系统错误区分开，便于前端给出准确提示\n if (\n error instanceof BadRequestException ||\n error instanceof NotFoundException ||\n error instanceof ForbiddenException\n ) {\n continue;\n }\n systemFailed += 1;\n }\n }"}
{"path":"apps/server/src/attendance/attendance-records.controller.ts","start_line":253,"end_line":257,"category":"maintainability","severity":"low","content":"Same loose equality pattern (`== null`) as in `batchCreate`; the project rules require strict equality. The same pattern also appears in the `remove` handler below.","suggestion_code":" const existing = await this.service.findAttendanceRecord(id);\n if (existing.classId === null && !this.canManageAllAttendance(req)) {\n throw new ForbiddenException('无权修改未关联班级的考勤记录');\n }\n if (existing.classId !== null) await this.assertClassAccess(req, existing.classId);","existing_code":" const existing = await this.service.findAttendanceRecord(id);\n if (existing.classId == null && !this.canManageAllAttendance(req)) {\n throw new ForbiddenException('无权修改未关联班级的考勤记录');\n }\n if (existing.classId != null) await this.assertClassAccess(req, existing.classId);"}
{"path":"apps/server/src/attendance/dto/dingtalk-import.dto.ts","start_line":16,"end_line":17,"category":"bug","severity":"medium","content":"No validation ensures `end` is not earlier than `start`. An inverted date range (e.g. start=2026-08-10, end=2026-08-01) would pass validation and could cause the import to query an empty/incorrect range or behave unexpectedly downstream. Add a custom cross-field validator (e.g. @ValidateIf + @IsDateString on a check, or a class-level @ValidatorConstraint) or at minimum guard this in the service.","suggestion_code":null,"existing_code":" @IsDateString()\n end?: string;"}
{"path":"apps/server/src/attendance/dto/dingtalk-import.dto.ts","start_line":10,"end_line":12,"category":"bug","severity":"low","content":"`IsDateString()` accepts full ISO 8601 timestamps (e.g. '2026-08-09T12:00:00.000Z'), not just the documented YYYY-MM-DD format. If downstream code treats these as date-only, timezone shifts can silently move the date across days. Consider a stricter regex/format check or explicit normalization if the range boundaries must be day-granular.","suggestion_code":null,"existing_code":" @IsOptional()\n @IsDateString()\n start?: string;"}
{"path":"apps/server/src/attendance/attendance.controller-base.ts","start_line":41,"end_line":43,"category":"security","severity":"medium","content":"Security concern: `CaslAction.Update` on `SubjectName.Class` (legacy class:edit) is treated as 'manage all attendance'. Combined with AttendanceService.getAccessibleClassIds/assertClassAccess (canManageAll=true returns undefined = ALL classes and bypasses class-teacher scoping), any user who can merely edit a class gets unrestricted access to every class's attendance records, bypassing the classTeacher scoping used elsewhere. Since this is a legacy fallback, recommend removing it or narrowing it to a dedicated permission (e.g., a Manage-on-Attendance check or explicit attendance:manage-all permission code) so class:edit no longer grants cross-scope attendance access.","suggestion_code":null,"existing_code":" this.authz.can(req, CaslAction.Manage, SubjectName.Attendance) ||\n // Legacy: class:edit grants broad attendance access for teacher scoping\n this.authz.can(req, CaslAction.Update, SubjectName.Class)"}
{"path":"apps/server/src/attendance/attendance.controller-base.ts","start_line":36,"end_line":36,"category":"maintainability","severity":"low","content":"Hardcoded business value: the UTC+8 offset is a magic number. While common/dayjs.ts documents the fixed Asia/Shanghai convention, the literal `8` here is opaque to readers and can drift out of sync if the convention ever changes. Suggest extracting it to a named constant (e.g., CHINA_UTC_OFFSET = 8) or using a timezone-aware helper so the intent is explicit.","suggestion_code":" const CHINA_UTC_OFFSET = 8;\n return dayjs().utcOffset(CHINA_UTC_OFFSET).format('YYYY-MM-DD');","existing_code":" return dayjs().utcOffset(8).format('YYYY-MM-DD');"}
{"path":"apps/server/src/attendance/dto/attendance.dto.ts","start_line":35,"end_line":37,"category":"bug","severity":"medium","content":"startTime/endTime are only format-validated (HH:mm); there is no cross-field check that endTime is after startTime. A period such as \"22:00\" -> \"08:00\" or a reversed pair passes validation and can be persisted, leading to incorrect schedule-generation logic downstream. Consider a custom validator (e.g., @Validate(EndTimeAfterStartTimeConstraint)) or a service-level check.","suggestion_code":null,"existing_code":" @IsString()\n @Matches(/^([01]\\d|2[0-3]):[0-5]\\d$/)\n endTime: string;"}
{"path":"apps/server/src/attendance/dto/attendance.dto.ts","start_line":107,"end_line":113,"category":"bug","severity":"medium","content":"dateFrom/dateTo have no ordering validation. The same pattern is repeated in QueryAttendanceRecordsDto, AttendanceReportQueryDto, QueryDingRawDto and GenerateAttendanceFromSchedulesDto; a reversed range (dateFrom > dateTo) passes validation and silently yields empty or incorrect query results. Add a cross-field validator or check the ordering in the service layer.","suggestion_code":null,"existing_code":" @IsOptional()\n @IsDateString()\n dateFrom?: string;\n\n @IsOptional()\n @IsDateString()\n dateTo?: string;"}
{"path":"apps/server/src/attendance/dto/attendance.dto.ts","start_line":74,"end_line":77,"category":"maintainability","severity":"low","content":"Business enum values are duplicated as inline string arrays across multiple DTOs: session values appear in AttendanceRecordItem, and status values appear in AttendanceRecordItem, UpdateAttendanceRecordDto, BatchUpdateAttendanceStatusDto and QueryAttendanceRecordsDto. Extract them into shared constants or TS enums (e.g., export const ATTENDANCE_STATUSES = ['present','late','absent','leave'] as const) so there is a single source of truth and no risk of drift when a status/session is added.","suggestion_code":null,"existing_code":" @IsString()\n @IsIn(['present', 'late', 'absent', 'leave'])\n @IsNotEmpty()\n status: string;"}
{"path":"apps/server/src/attendance/dto/attendance.dto.ts","start_line":89,"end_line":93,"category":"performance","severity":"low","content":"The records array has no upper bound, unlike BatchUpdateAttendanceStatusDto which caps ids at 200. A client can submit an arbitrarily large payload, causing high CPU/memory usage during transformation and per-item nested validation (same applies to SaveAttendancePeriodConfigsDto.periods). Consider adding @ArrayMaxSize(...) to bound the batch size.","suggestion_code":null,"existing_code":" @IsArray()\n @ArrayNotEmpty()\n @ValidateNested({ each: true })\n @Type(() => AttendanceRecordItem)\n records: AttendanceRecordItem[];"}
{"path":"apps/server/src/attendance/attendance-lesson.service.ts","start_line":157,"end_line":157,"category":"bug","severity":"medium","content":"Unsound non-null assertion: `studentsById` is built from `getClassStudentsForLesson(...)` which filters students active on the lesson date, but `existingRecords` may contain records for students who have since left the class / are no longer active on that date (roster changed after the session was created). In that case `studentsById.get(...)` returns `undefined` and `record.student` is set to `undefined`, losing the `student` relation in the saved entity and in the returned payload (controllers serializing `record.student.name` will break), and possibly nulling the FK on save. Fall back to the existing value instead of asserting non-null.","suggestion_code":" const student = studentsById.get(record.studentId);\n if (student) record.student = student;","existing_code":" record.student = studentsById.get(record.studentId)!;"}
{"path":"apps/server/src/attendance/attendance-lesson.service.ts","start_line":246,"end_line":254,"category":"bug","severity":"medium","content":"Concurrency gap in the first-pull fallback: this method mutates `AttendanceSession`/`AttendanceRecord` without the `sessionMutex` that `completeLessonAttendance` uses, and when two requests race to create the session, the loser catches `ER_DUP_ENTRY`, finds the winner's session and returns its records *without honoring the current request's `finalize` flag*. A concurrent finalize request can therefore silently succeed while returning an `in_progress` session with `pending` records — the finalize is effectively dropped. Consider serializing this method (e.g., reuse `sessionMutex` keyed by `scheduleId:lessonDate`) and re-applying the resolve/finalize logic on the fallback path instead of returning early.","suggestion_code":null,"existing_code":" if (existing) {\n session = existing;\n const existingRecords = await recordRepo.find({\n where: { attendanceSessionId: session.id },\n relations: ['student'],\n order: { studentId: 'ASC' },\n });\n return { schedule, session, records: await attachAttendanceDeviceMappings(existingRecords, this.attendanceDeviceRepo, schedule.classId) };\n }"}
{"path":"apps/server/src/attendance/attendance-lesson.service.ts","start_line":37,"end_line":42,"category":"maintainability","severity":"low","content":"Dead code: `classRepo`, `studentRepo`, `studentDingMappingRepo`, and `classTeacherRepo` are injected into the constructor but never referenced anywhere in this service. Remove them to avoid unused dependencies (and unnecessary injection overhead).","suggestion_code":null,"existing_code":" @InjectRepository(Class) private classRepo: Repository,\n @InjectRepository(Student) private studentRepo: Repository,\n @InjectRepository(ClassSchedule) private scheduleRepo: Repository,\n @InjectRepository(ClassStudent) private classStudentRepo: Repository