docs: add enterprise repository files (LICENSE/CHANGELOG/CONTRIBUTING/SECURITY)
This commit is contained in:
SpecialX
43
CHANGELOG.md
Normal file
43
CHANGELOG.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- arch:scan @public JSDoc 标记豁免机制，支持登录前/公开/内部工具 Server Action 豁免权限校验
|
||||
- arch:scan 递归 CTE 违规检测，识别通过辅助函数间接调用 requirePermission 的调用链
|
||||
- 大仓工程基建：LICENSE、CONTRIBUTING、SECURITY、.env.example 文档
|
||||
- husky + lint-staged + commitlint 本地提交规范工具链
|
||||
- /api/health 健康检查端点 + Dockerfile HEALTHCHECK
|
||||
- @next/bundle-analyzer 构建体积分析工具
|
||||
- CI 流水线新增 Unit test + coverage 阶段
|
||||
- tsconfig 开启 noUncheckedIndexedAccess 严格模式
|
||||
|
||||
### Changed
|
||||
- 重构 004 架构文档为完整架构设计文档（912 行，14 章节，13 个 mermaid 图）
|
||||
- 重写 35 个模块 README，统一 8 章节模板（架构图/流程图/技术栈）
|
||||
- 拆分 5 个超长文件：schema.ts (2245→29+27子文件)、invalidation-map.ts (1195→50+6子文件)、messaging/actions.ts (973→47+5子文件)、textbooks/data-access.ts (907→15+6子文件)、questions/data-access.ts (828→48+4子文件)
|
||||
- 精简 known-issues.md 为索引式速查手册（场景→技术/规则映射）
|
||||
|
||||
### Fixed
|
||||
- 修复 20 个 Server Action 权限违规（12 个 @public 豁免 + 8 个真违规修复）
|
||||
- 修复 ai 模块 6 个 Action 权限误报（requireAiPermission 间接调用链识别）
|
||||
- 修复 parent 模块 6 个 Action 权限缺失（requireAuth → requirePermission）
|
||||
- 修复 settings 模块 updateProfileAction 权限校验（显式 requirePermission）
|
||||
|
||||
## [0.1.0] - 2026-06-01
|
||||
|
||||
### Added
|
||||
- 初始版本发布
|
||||
- K12 智慧教学平台核心功能：备课、作业、考试、成绩、考勤、消息、家校互动
|
||||
- 严格三层架构：app → modules → shared
|
||||
- 5 层状态管理模型：URL(nuqs) · Server(TanStack Query) · Client(Zustand) · Global UI · Form
|
||||
- 权限 3 道防线：proxy.ts → requirePermission → usePermission
|
||||
- 设计令牌双层架构：Primitive + Semantic
|
||||
- arch.db 架构元数据库（12 张表 + 7 个索引）
|
||||
- cacheFn 请求级缓存层
|
||||
- Gitea Actions CI/CD 流水线
|
||||
129
CONTRIBUTING.md
Normal file
129
CONTRIBUTING.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# 贡献指南
|
||||
|
||||
感谢参与本项目！请遵循以下规范提交贡献。
|
||||
|
||||
## 开发环境准备
|
||||
|
||||
```bash
|
||||
# 1. 安装依赖
|
||||
npm install
|
||||
|
||||
# 2. 准备环境变量
|
||||
cp .env.example .env
|
||||
# 编辑 .env 填入实际配置
|
||||
|
||||
# 3. 初始化数据库
|
||||
npm run db:push
|
||||
|
||||
# 4. 启动开发服务器
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## 强制工作流程
|
||||
|
||||
**所有代码改动前必须先查阅架构文档：**
|
||||
|
||||
1. 阅读 `docs/architecture/004_architecture_impact_map.md` 了解架构设计意图
|
||||
2. 运行 `npm run arch:scan` 更新 arch.db
|
||||
3. 运行 `npm run arch:query -- module-deps` 查目标模块依赖
|
||||
4. 阅读 `src/modules/[模块]/README.md` 了解模块工作流程
|
||||
5. 查 `docs/troubleshooting/known-issues.md` 读相关经验
|
||||
|
||||
**代码改动后必须：**
|
||||
|
||||
1. 运行 `npx tsc --noEmit` 确保零错误
|
||||
2. 运行 `npm run lint` 确保零错误
|
||||
3. 运行 `npm run arch:scan` 更新 arch.db
|
||||
4. 若架构设计意图变化，同步更新 004 文档
|
||||
5. 若发现新场景→技术映射，更新 known-issues.md
|
||||
|
||||
## 提交规范
|
||||
|
||||
### Conventional Commits 格式
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer]
|
||||
```
|
||||
|
||||
**类型（type）：**
|
||||
- `feat`: 新功能
|
||||
- `fix`: Bug 修复
|
||||
- `docs`: 文档变更
|
||||
- `style`: 代码格式（不影响功能）
|
||||
- `refactor`: 重构（既不是新功能也不是修复）
|
||||
- `test`: 测试相关
|
||||
- `chore`: 构建/工具/依赖变更
|
||||
- `perf`: 性能优化
|
||||
- `ci`: CI/CD 变更
|
||||
|
||||
**示例：**
|
||||
```
|
||||
feat(arch-scan): add @public JSDoc tag exemption mechanism
|
||||
fix(permissions): fix parent module 6 Action permission violations
|
||||
refactor: split 5 oversized files into domain-specific subfiles
|
||||
docs(architecture): rewrite 004 as architecture design document
|
||||
```
|
||||
|
||||
### 提交前检查
|
||||
|
||||
husky + lint-staged 会在 `git commit` 时自动执行：
|
||||
- ESLint 检查暂存文件
|
||||
- Prettier 格式化暂存文件
|
||||
- commitlint 校验 commit message 格式
|
||||
|
||||
如果检查失败，请修复后重新提交。
|
||||
|
||||
## 架构约束
|
||||
|
||||
### 严格三层架构
|
||||
|
||||
```
|
||||
app → modules → shared
|
||||
```
|
||||
|
||||
- `app/` 只能调用 `modules/` 的 Server Actions 和 data-access
|
||||
- `modules/` 之间通过对方 data-access 通信，不直接查询对方 DB 表
|
||||
- `shared/` 不得反向依赖 `modules/*` 或 `app/*`
|
||||
|
||||
### 代码质量规则
|
||||
|
||||
- 禁止 `any`，未知类型用 `unknown` + 类型守卫
|
||||
- 禁止 `as` 断言（除非从 `unknown` 转换，需注释原因）
|
||||
- 函数返回值必须显式标注，特别是 `Promise<T>`
|
||||
- 仅用于类型的导入使用 `import type`
|
||||
- Server Action 必须调用 `requirePermission()`（或加 `@public` 标记豁免）
|
||||
- 前端权限检查使用 `usePermission().hasPermission()`，禁止 `role === "xxx"` 硬编码
|
||||
- 单文件行数：组件 ≤500，actions/data-access ≤800，硬限 1000
|
||||
|
||||
### 设计令牌规范
|
||||
|
||||
- 禁止硬编码颜色（`#hex`），使用 `hsl(var(--*))` 或 Tailwind 类
|
||||
- 禁止硬编码字体（`'Inter'`），使用 `var(--font-family-*)`
|
||||
- 禁止 Tailwind 任意值（`w-[137px]`），映射到 `--space-*` 或默认阶梯
|
||||
|
||||
## 文档同步
|
||||
|
||||
### 需要同步架构图的场景
|
||||
|
||||
- 新增/删除/重命名导出函数、组件、Hook、类型
|
||||
- 修改函数签名（参数、返回类型）
|
||||
- 修改权限点或角色-权限映射
|
||||
- 新增/删除数据库表、路由页面、API 路由
|
||||
- 修改模块间依赖关系
|
||||
- 新增模块
|
||||
|
||||
### 同步方式
|
||||
|
||||
- 修改源码后运行 `npm run arch:scan` 更新 arch.db（强制）
|
||||
- 若架构设计意图变化，同步更新 `docs/architecture/004_architecture_impact_map.md`
|
||||
- 若发现新"场景→技术"映射，更新 `docs/troubleshooting/known-issues.md`
|
||||
|
||||
## 问题报告
|
||||
|
||||
- 构建/lint/tsc 报错 → 记录到 `docs/troubleshooting/known-issues.md` "全局经验"分区
|
||||
- 运行时异常 → 记录到"模块经验"分区
|
||||
- 框架/库版本兼容问题 → 记录到"全局经验: Next.js 配置与运行时"
|
||||
14
LICENSE
Normal file
14
LICENSE
Normal file
@@ -0,0 +1,14 @@
|
||||
PROPRIETARY AND CONFIDENTIAL
|
||||
|
||||
Copyright (c) 2026 EazyGame. All rights reserved.
|
||||
|
||||
This source code and accompanying documentation (the "Software") is the
|
||||
proprietary and confidential property of EazyGame. No part of the Software
|
||||
may be reproduced, distributed, or transmitted in any form or by any means,
|
||||
including photocopying, recording, or other electronic or mechanical methods,
|
||||
without the prior written permission of EazyGame.
|
||||
|
||||
For licensing inquiries, contact: legal@eazygame.cn
|
||||
|
||||
Unauthorized use, reproduction, or distribution of this Software, via any
|
||||
medium, is strictly prohibited and may result in civil and criminal penalties.
|
||||
90
SECURITY.md
Normal file
90
SECURITY.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# 安全策略
|
||||
|
||||
## 报告安全漏洞
|
||||
|
||||
**请不要通过 GitHub Issue 公开报告安全漏洞。**
|
||||
|
||||
发现安全漏洞请通过以下渠道私密报告：
|
||||
|
||||
- 邮件：security@eazygame.cn
|
||||
- 内部工单系统：Security 项目 → New Issue
|
||||
|
||||
报告时请包含：
|
||||
1. 漏洞描述和影响范围
|
||||
2. 复现步骤（最小化示例）
|
||||
3. 影响的版本号
|
||||
4. 建议的修复方案（可选）
|
||||
|
||||
**响应时间：** 24 小时内确认收到，5 个工作日内给出评估结果。
|
||||
|
||||
## 安全架构
|
||||
|
||||
### 权限三道防线
|
||||
|
||||
```
|
||||
proxy.ts (路由级 bitmap) → requirePermission (Server Action 级) → usePermission (客户端级)
|
||||
```
|
||||
|
||||
- **路由级**：`src/proxy.ts` 使用 bitmap 快速拦截未授权路由
|
||||
- **Server Action 级**：每个 Action 必须调用 `requirePermission()`，或用 `@public` JSDoc 标记豁免
|
||||
- **客户端级**：组件使用 `usePermission().hasPermission()` 控制元素显隐
|
||||
|
||||
### 认证与会话
|
||||
|
||||
- JWT/session ID 存储在 httpOnly + Secure + SameSite=Strict 的 Cookie 中
|
||||
- 服务端环境变量不加 `NEXT_PUBLIC_` 前缀
|
||||
- 环境变量使用 `@t3-oss/env-nextjs` + Zod 校验（`src/env.mjs`）
|
||||
|
||||
### 数据访问
|
||||
|
||||
- 前端禁止直接访问数据库，所有数据访问必须通过 `data-access.ts` 模块
|
||||
- Server Action 必须使用 `requirePermission()` 进行权限校验
|
||||
- 家长路由必须包含 `parentId` 和 `studentId` 双重权限校验，防止信息泄露
|
||||
|
||||
### 输入安全
|
||||
|
||||
- **禁止 `dangerouslySetInnerHTML`**（如必须使用，先用 DOMPurify 清洗）
|
||||
- Server Action 输入使用 Zod 验证，验证失败返回结构化错误
|
||||
- 注册/登录流程实施速率限制，防止暴力破解和邮箱枚举攻击
|
||||
|
||||
## 安全审计
|
||||
|
||||
### arch:scan 自动检测
|
||||
|
||||
`npm run arch:query -- violations` 会自动检测：
|
||||
|
||||
- **长文件**（>800 行）：提示拆分，降低维护风险
|
||||
- **Server Action 权限缺失**：识别未调用 `requirePermission` 的 Server Action（支持递归调用链识别）
|
||||
|
||||
### @public 豁免标记
|
||||
|
||||
登录前/公开/内部工具 Server Action 可用 `@public` JSDoc 标记豁免权限校验：
|
||||
|
||||
```ts
|
||||
/**
|
||||
* 注册 Action，登录前公开调用。
|
||||
*
|
||||
* @public 登录前公开 Action，豁免 requirePermission 校验。
|
||||
*/
|
||||
export async function registerAction(formData: FormData) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**豁免场景：**
|
||||
- 登录前 Action（注册、邮箱可用性检查、2FA 预检）
|
||||
- 内部日志工具（audit-logger、change-logger、login-logger）
|
||||
- 权限查询工具（isAdminRole、canConfigurePublicAiProvider）
|
||||
- 登录后必经流程（onboarding 状态查询/完成）
|
||||
|
||||
## 依赖安全
|
||||
|
||||
- 定期运行 `npm audit` 检查已知漏洞
|
||||
- CI 流水线包含 Trivy 安全扫描（`.trivyignore` 配置豁免项）
|
||||
- 依赖升级通过 PR 审核，不允许直接推送 main 分支
|
||||
|
||||
## 数据保护
|
||||
|
||||
- 数据库备份：每日自动备份，每周 DR 演练
|
||||
- 敏感数据（密码、2FA 密钥）使用 bcrypt/Argon2 哈希存储
|
||||
- 日志不记录敏感信息（密码、token、个人身份信息）
|
||||
Reference in New Issue
Block a user