chore: add contributing guidelines and enhance project overview in README

Author: pengyue-polaron

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to EaseCation Open User Center
+
+感谢你愿意为 `EaseCation Open User Center` 贡献代码、文档或反馈。
+
+开始贡献前，建议先阅读 [README.md](README.md) 了解项目背景、启动方式和仓库结构；这份文档主要说明协作方式和提交要求。
+
+## 贡献方式
+
+你可以通过以下方式参与：
+
+- 提交 Bug 反馈
+- 提出功能建议或交互改进建议
+- 完善文档
+- 修复问题或提交新功能代码
+
+如果改动会影响现有流程、接口约定或页面行为，建议先开 Issue 讨论。
+
+## 提交前检查
+
+仓库 CI 会执行质量检查、类型检查、测试、构建和基础安全检查。提交 Pull Request 前，建议至少本地运行以下命令：
+
+```bash
+yarn quality:frontend
+yarn type-check
+yarn test
+yarn build
+```
+
+如果改动只涉及部分模块，至少也要确保：
+
+- 改动相关页面可以正常启动和访问
+- 多个模块共用的类型或工具函数优先放在 `shared/` 或 `frontend-common/`
+- 没有引入新的硬编码中文或破坏现有国际化约定
+- 没有引入暗色模式相关 API 的错误用法
+- 没有提交密钥、令牌、生产配置或其他敏感信息
+
+## 提交内容建议
+
+请尽量保持每个 Pull Request 聚焦单一目标。
+
+推荐做法：
+
+- 一个 PR 只解决一个明确问题，或只引入一组紧密相关的改动
+- 避免把重构、样式调整和功能修改混在同一个 PR 里
+- 不要顺手提交无关格式化结果或大面积无意义改名
+- 如果改动了接口、状态流转或共享类型，请在描述中明确说明影响范围
+
+## Pull Request 说明
+
+提交 PR 时，建议在描述中写清楚：
+
+- 改动背景
+- 解决了什么问题
+- 主要改了哪些模块
+- 是否影响用户端、管理端或 Mock 后端
+- 本地如何验证
+
+如果是 UI 改动，建议附上截图或录屏。
+
+## 文档与代码风格
+
+请尽量保持与现有仓库一致的风格：
+
+- 文档优先写清楚“做什么、为什么、怎么验证”
+- 尽量复用已有类型、组件、Hook 和工具函数
+- 公共逻辑优先抽到共享层，而不是在页面内重复实现
+- 不要提交 `.env`、构建产物、日志文件或其他本地临时文件
+
+## 当前不开源部分
+
+以下内容当前不在开源范围内：
+
+- 生产后端
+- 数据库迁移
+- 部署密钥
+- 私有基础设施配置
+
+涉及这些部分的功能，通常需要通过 `mock-backend/` 或共享契约适配。提交相关改动时，请避免假设生产内部实现细节。
+
+## License
+
+向本仓库提交代码即表示你同意这些贡献将继续以仓库当前使用的 `GNU AGPL-3.0` 许可证进行分发。

README.md

@@ -1,92 +1,146 @@
 # EaseCation Open User Center
 
-欢迎来到 `EaseCation Open User Center`，这是 EaseCation 用户中心的开源仓库，也是我们第一个正式公开的 Web 平台项目。过去我们陆续开源过一些服务器内部项目，而这一次，我们想把更贴近社区日常使用体验的一部分真正交到大家手里。
+欢迎来到 `EaseCation Open User Center`。这是 EaseCation 用户中心的开源仓库，也是我们第一个正式公开的 Web 平台项目。
 
-一直以来，我们都希望能为 MC 社区提供一个稳定、易用、高鲁棒性的现代化工单平台，也希望给热心玩家和开发者一个可以一起参与共建的入口。所以现在，这个前端项目正式向社区开放。无论你是来提建议、报 Bug，还是直接提交代码，我们都欢迎。
+过去我们陆续开源过一些服务器内部项目，而这一次，我们想把更贴近社区日常使用体验的一部分真正交到大家手里。
 
-## 当前开源范围
+我们希望能为 MC 社区提供一个稳定、易用的现代化工单平台，也给热心玩家和开发者一个可以一起参与共建的入口。这个仓库聚焦的，就是登录、账号绑定、工单处理、后台运营和本地联调支持这些用户中心核心能力。
 
-目前仓库开放的内容包括：
+## 项目概览
+
+EaseCation 用户中心目前由以下几个部分组成：
+
+| 模块 | 说明 |
+| --- | --- |
+| `frontend-user` | 面向玩家和普通用户的前台，负责登录、绑定账号、提交工单、查看处理进度等流程。 |
+| `frontend-admin` | 面向客服、审核和管理人员的后台，负责工单分配、处理、回复、追踪和基础运营操作。 |
+| `frontend-common` | 前后台共享的环境配置、公共样式、上下文、Hook 和通用组件。 |
+| `shared` | 前端共用的类型、接口契约和共享逻辑。 |
+| `mock-backend` | 本地联调用的模拟后端，提供稳定、可预测的接口响应。 |
+
+系统覆盖的核心场景包括：
+
+- 玩家申诉、举报、建议反馈
+- 账号绑定、WIKI 绑定、媒体相关申请
+- 物品补发及其他人工服务流程
+- 后台工单分配、状态流转、回复记录与基础运营操作
+
+## 开源范围
+
+当前仓库已开放：
 
 - `frontend-user`
 - `frontend-admin`
 - `frontend-common`
 - `shared`
 - `mock-backend`
 
-暂不包含：
+当前暂未开放：
 
 - 生产后端
 - 数据库迁移
 - 部署密钥
 - 私有基础设施配置
 
-现有后端逻辑还和 EC 的其他 Web 服务存在较强耦合。为了让未来公开出去的代码更清晰、更稳定、也更便于大家理解和参与，我们会先完成内部重构，再择机开放后端部分。
-
-## 这是一个什么项目
+现阶段后端逻辑仍与 EaseCation 的其他 Web 服务存在较强耦合。后续会在内部完成进一步重构，再择机开放更完整的后端实现。
 
-EaseCation用户中心大致可以分成三部分：
+## 环境要求
 
-- `frontend-user`：给玩家和普通用户使用的前台，用来登录、绑定账号、发起工单、查看处理进度。
-- `frontend-admin`：给客服、审核人员和管理人员使用的后台，用来分配、处理、回复和追踪工单。
-- `mock-backend`：给开源仓本地联调用的模拟后端，用来提供稳定的演示数据和接口响应。
+- Node.js `>= 18`
+- Corepack
+- Yarn `4.5.1`
 
-这套系统覆盖的核心场景包括：
+建议先在本机启用 Corepack 并固定 Yarn 版本：
 
-- 玩家申诉、举报、建议反馈
-- 账号绑定、WIKI 绑定、媒体相关申请
-- 物品补发、其他服务类人工处理流程
-- 后台工单分配、状态流转、回复记录与基础运营操作
+```bash
+corepack enable
+corepack prepare yarn@4.5.1 --activate
+```
 
 ## 快速开始
 
+### 1. 安装依赖
+
 ```bash
-corepack enable
-corepack prepare yarn@4.5.1 --activate
 yarn install
+```
+
+### 2. 初始化环境变量
+
+```bash
 cp frontend-common/.env.template frontend-common/.env
+cp frontend-admin/.env.template frontend-admin/.env
 cp mock-backend/.env.template mock-backend/.env
+```
+
+默认本地联调场景下，通常保持模板默认值即可。
+
+### 3. 一键启动本地联调
+
+```bash
 yarn mock
 ```
 
-启动后默认地址：
+默认访问地址：
 
-- 用户端：`http://localhost:9001`
-- 管理端：`http://localhost:9002`
-- Mock 后端：`http://localhost:9000`
+| 服务 | 地址 |
+| --- | --- |
+| 用户端 | `http://localhost:9001` |
+| 管理端 | `http://localhost:9002` |
+| Mock 后端 | `http://localhost:9000` |
 
 ## 常用命令
 
-- `yarn dev:user`：只启动用户前台，适合改玩家端页面时使用。
-- `yarn dev:admin`：只启动管理后台，适合改客服端或管理端页面时使用。
-- `yarn mock:backend`：只启动本地 mock 后端，提供前端联调所需接口。
-- `yarn mock`：一键启动共享包构建、mock 后端、用户前台和管理后台，适合第一次跑项目或完整联调。
-- `yarn check:i18n`：检查多语言文案和硬编码中文，避免新代码破坏现有国际化约定。
-- `yarn check:dark-mode-api`：检查暗色模式相关 API 使用是否符合当前约束。
-- `yarn quality:frontend`：运行前端质量检查，当前会串行执行 i18n 和 dark mode 两类校验。
-- `yarn check:secrets`：检查仓库里是否误提交敏感信息。
-- `yarn type-check`：对 `shared`、前台、后台和 mock 后端执行 TypeScript 类型检查。
-- `yarn test`：运行各工作区测试。
-- `yarn build`：构建共享包、用户前台和管理后台，用于验证生产构建是否通过。
+### 开发相关
 
-## 协作说明
+| 命令 | 说明 |
+| --- | --- |
+| `yarn mock` | 一键启动共享包构建、Mock 后端、用户前台和管理后台，适合首次运行或完整联调。 |
+| `yarn dev:user` | 仅启动用户前台。 |
+| `yarn dev:admin` | 仅启动管理后台。 |
+| `yarn mock:backend` | 仅启动本地 Mock 后端。 |
 
-公开协作请优先在以下目录中提交修改：
+### 质量检查
+
+| 命令 | 说明 |
+| --- | --- |
+| `yarn check:i18n` | 检查多语言文案与硬编码中文，避免破坏现有国际化约定。 |
+| `yarn check:dark-mode-api` | 检查暗色模式相关 API 的使用方式。 |
+| `yarn quality:frontend` | 串行执行前端质量检查。 |
+| `yarn check:secrets` | 检查仓库中是否误提交敏感信息。 |
+
+### 构建与验证
+
+| 命令 | 说明 |
+| --- | --- |
+| `yarn type-check` | 对 `shared`、前台、后台和 Mock 后端执行 TypeScript 类型检查。 |
+| `yarn test` | 运行各工作区测试。 |
+| `yarn build` | 构建共享包、用户前台和管理后台，用于验证生产构建是否通过。 |
+
+## 协作约定
+
+如果你希望参与公开协作，可以优先关注以下目录：
 
-- 前端 API 合约定义在 `shared/`
-- 本地联调默认依赖 `mock-backend/`
 - `frontend-user/`
 - `frontend-admin/`
 - `frontend-common/`
 - `shared/`
 - `mock-backend/`
 
+补充说明：
+
+- 前端 API 契约和共享类型定义位于 `shared/`
+- 本地联调默认依赖 `mock-backend/`
+- 涉及公共逻辑时，优先复用 `frontend-common/` 中已有能力
+
+欢迎通过 Issue、Discussion 或 Pull Request 参与改进。
+
 ## License
 
 本仓库采用 `GNU AGPL-3.0` 许可证开源。
 
 如果你分发修改版本，或将修改后的版本作为网络服务对外提供使用，需要按照 `AGPL-3.0` 的要求继续公开对应源码。完整条款见根目录 [LICENSE](LICENSE)。
 
-## 贡献者
+## Contributors
 
-感谢以下贡献者参与了这个项目的开发：
+感谢所有参与项目建设、提出反馈和贡献代码的开发者与社区成员。